Oversai SDK

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

Installation

npm install @oversai/sdk

Or using yarn:

yarn add @oversai/sdk

Quick Start

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: '[email protected]',
  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:

// 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:

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

Create Object

Create a new object:

const newCustomer = {
  name: 'Acme Corporation',
  email: '[email protected]',
  industry: 'Technology',
  status: 'active'
};

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

Update Object

Update an existing object:

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:

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

Working with Relationships

// 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

// Create multiple objects
const customers = await client.ontology.bulkCreateObjects('customer', [
  { name: 'Company A', email: '[email protected]' },
  { name: 'Company B', email: '[email protected]' }
]);

// 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:

// 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:

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:

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: '[email protected]',
  // ...other properties
};

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

License

MIT