@ontologie/sdk-client

HTTP client for the Ontologie SDK. Provides createClient() with type-safe ontology access, ObjectSet query builder, CRUD with OCC, upsert, batch per-item results, idempotency helpers, actions, NDJSON streaming, 28 platform namespaces, and 3 middleware utilities (logging, telemetry, validation).

Installation

npm install @ontologie/sdk-client

Usage

import { createClient } from '@ontologie/sdk-client';
import type { Ontology } from './generated';

const client = createClient<Ontology>({
  // baseUrl defaults to https://api.dataforge.io
  apiKey: 'df_your_key',
  workspaceId: 'ws-uuid',
});

// Query with lazy ObjectSet builder
const results = await client.ontology.Employee
  .where(e => e.salary.gt(50000))
  .orderBy(e => e.name.asc())
  .limit(20)
  .fetchAll();

// CRUD
await client.ontology.Employee.create({ name: 'Alice', salary: 60000 });
await client.ontology.Employee.update('id', { salary: 70000 });
await client.ontology.Employee.delete('id');

// OCC (Optimistic Concurrency Control)
await client.ontology.Employee.update('id', { salary: 90000 }, { expectedVersion: 3 });

// Upsert (create-or-update)
const { created, object } = await client.ontology.Employee.upsert('id', { name: 'Jane', salary: 75000 });

// Batch operations (returns BatchResult with per-item status)
const result = await client.ontology.Employee.batchCreate([{ name: 'A' }, { name: 'B' }]);
console.log(`${result.succeeded} created, ${result.failed} failed`);

// Idempotency
const safeClient = client.withIdempotency(); // auto-injects keys on writes

// Actions
await client.ontology.Employee.actions.promote('id', { level: 3 });

API

createClient<TOntology>(config: ClientConfig): DataForgeClient<TOntology>

Creates a typed client instance. Config fields:

| Field | Type | Required | Description | |-------|------|----------|-------------| | baseUrl | string | Yes | API base URL | | apiKey | string | Yes | API key (df_...) | | workspaceId | string | Yes | Workspace UUID | | espaceId | string | No | Espace (canvas) UUID | | timeout | number | No | Request timeout in ms (default: 30000) | | retry | RetryConfig | No | Retry configuration for transient errors | | fetch | typeof fetch | No | Custom fetch implementation |

DataForgeClient<TOntology>

| Property | Type | Description | |----------|------|-------------| | ontology | TOntology | Type-safe ontology namespace proxy | | transport | HttpTransport | Raw HTTP transport for custom requests | | config | Readonly<ClientConfig> | Frozen client configuration | | withIdempotency(gen?) | DataForgeClient | Returns new client with auto-injected idempotency keys on writes | | agents | AgentOperations | Agent invoke, stream, tools, conversations | | knowledge | KnowledgeOperations | Hybrid search, documents, RAG ask | | workflows | WorkflowOperations | Trigger, stream, schedules | | forms | FormsOperations | Form builder, public submissions (v3.1.0) | | webhooks | WebhookOperations | Webhook subscriptions, delivery logs (v3.1.0) | | agentStudio | AgentStudioOperations | Agent definitions CRUD, publish (v3.1.0) | | instanceGraph | InstanceGraphOperations | Edge traversal (v3.1.0) | | instances(id) | InstanceOperations | Scoped instance CRUD (v3.1.0) | | ... | | 28 namespaces total — see README.md for full list |

ObjectSet Builder

All builder methods are lazy (return a new instance without API call). Terminal operations trigger the request.

Builder methods: where(), orderBy(), limit(), offset(), select() (type-narrowing), include(), distinct(), groupBy()

Terminal operations: fetchPage(), fetchAll(), count(), aggregate(), get(), first(), firstOrThrow(), exists(), [Symbol.asyncIterator]()

HttpTransport

For advanced use cases, access client.transport directly:

const data = await client.transport.request<MyType>({
  method: 'GET',
  path: '/api/custom/endpoint',
});

Exports

// Main
export { createClient, DataForgeClient };
export { HttpTransport };
export { ObjectSetImpl };
export { SingleLinkAccessorImpl, MultiLinkAccessorImpl };
export { ActionExecutor, createActionsProxy };

// Utilities
export { createFilterProxy, createOrderByProxy, createAggregationProxy };
export { parseNDJSONStream };
export { createIdempotencyKey };
export { mapHttpError };
export { withRetry, isRetryable, isSafeToRetry };

// Re-exported types
export type { WriteOptions, BatchOptions, BatchResult, BatchItemResult, UpsertResult };

// Re-exported errors
export { DataForgeError, AuthenticationError, ... };

License

MIT