npm package: @oversai/sdk
Description: JavaScript/TypeScript client library for integrating with Oversai APIs
Author: Oversai
Latest version: 0.1.1

# Oversai SDK

A JavaScript/TypeScript client library for integrating with Oversai APIs.

## Installation

```bash
npm install @oversai/sdk
```

Or using yarn:

```bash
yarn add @oversai/sdk
```

## Quick Start

```typescript
import { OversaiClient } from '@oversai/sdk';

// Initialize with API key
const client = new OversaiClient({ 
  apiKey: 'your_api_key'
});

// Or with JWT auth
const client = new OversaiClient({ 
  jwt: 'your_jwt_token'
});

// Use the Ontology API
const customers = await client.ontology.getObjects('customer', {
  limit: 10,
  filter: {
    field: 'status',
    operator: 'eq',
    value: 'active'
  }
});

// Create a new object
const newCustomer = await client.ontology.createObject('customer', {
  name: 'Acme Corporation',
  email: 'contact@acme.com',
  status: 'active'
});

// Work with relationships
await client.ontology.createRelationship({
  sourceType: 'customer',
  sourceId: 'cust_123',
  relationshipType: 'placed',
  targetType: 'order',
  targetId: 'order_456'
});
```

## Documentation

### Ontology API

The Ontology API allows you to manage data objects and their relationships in your Oversai application.

#### Get Objects

Retrieve objects of a specific type:

```typescript
// Get all customers
const response = await client.ontology.getObjects('customer');
const customers = response.data;

// With filtering
const response = await client.ontology.getObjects('customer', {
  filter: {
    field: 'status',
    operator: 'eq',
    value: 'active'
  }
});

// With pagination
const response = await client.ontology.getObjects('customer', {
  limit: 10,
  offset: 0
});
```

#### Get Object by ID

Retrieve a specific object by its ID:

```typescript
const customerId = '12345';
const customer = await client.ontology.getObject('customer', customerId);
```

#### Create Object

Create a new object:

```typescript
const newCustomer = {
  name: 'Acme Corporation',
  email: 'contact@acme.com',
  industry: 'Technology',
  status: 'active'
};

const createdCustomer = await client.ontology.createObject('customer', newCustomer);
```

#### Update Object

Update an existing object:

```typescript
const customerId = '12345';
const updates = {
  status: 'inactive',
  notes: 'Customer account paused on request'
};

const updatedCustomer = await client.ontology.updateObject('customer', customerId, updates);
```

#### Delete Object

Delete an object:

```typescript
const customerId = '12345';
await client.ontology.deleteObject('customer', customerId);
```

#### Working with Relationships

```typescript
// Get all orders for a customer
const customerId = '12345';
const orders = await client.ontology.getRelatedObjects('customer', customerId, 'orders');

// Create a relationship
await client.ontology.createRelationship({
  sourceType: 'customer',
  sourceId: '12345',
  relationshipType: 'placed',
  targetType: 'order',
  targetId: '67890'
});

// Delete a relationship
await client.ontology.deleteRelationship({
  sourceType: 'customer',
  sourceId: '12345',
  relationshipType: 'placed',
  targetType: 'order',
  targetId: '67890'
});
```

#### Bulk Operations

```typescript
// Create multiple objects
const customers = await client.ontology.bulkCreateObjects('customer', [
  { name: 'Company A', email: 'contact@companya.com' },
  { name: 'Company B', email: 'contact@companyb.com' }
]);

// Update multiple objects
const updatedCustomers = await client.ontology.bulkUpdateObjects('customer', [
  { id: 'cust_123', status: 'inactive' },
  { id: 'cust_456', status: 'inactive' }
]);

// Delete multiple objects
await client.ontology.bulkDeleteObjects('customer', ['cust_123', 'cust_456']);
```

#### Pagination with Async Iterators

The SDK provides helpers for paginating through large result sets:

```typescript
// Iterate through all customers, 100 at a time
const iterator = client.ontology.getObjectsIterator('customer', {
  limit: 100,
  filter: { field: 'status', operator: 'eq', value: 'active' }
});

for await (const page of iterator) {
  for (const customer of page) {
    console.log(customer.id, customer.name);
  }
}
```

## Error Handling

The SDK throws standardized errors that you can catch and handle in your application:

```typescript
import { OversaiClient, ApiError } from '@oversai/sdk';

const client = new OversaiClient({ apiKey: 'your_api_key' });

try {
  const result = await client.ontology.getObject('customer', 'invalid-id');
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status code: ${error.statusCode}`);
    console.error(`Error code: ${error.code}`);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## TypeScript Support

The SDK includes TypeScript definitions to improve your development experience:

```typescript
import { OversaiClient } from '@oversai/sdk';
import type { Customer, Order } from '@oversai/sdk/types';

const client = new OversaiClient({ apiKey: 'your_api_key' });

// TypeScript will enforce the correct object structure
const newCustomer: Customer = {
  name: 'Acme Corp',
  email: 'contact@acme.com',
  // ...other properties
};

const createdCustomer = await client.ontology.createObject<Customer>('customer', newCustomer);
```

## License

MIT