@dataforge/sdk-types

Pure runtime types for the DataForge SDK. Zero dependencies.

This package provides all TypeScript interfaces and error classes used by @dataforge/sdk-client and @dataforge/sdk-generator.

Installation

npm install @dataforge/sdk-types

Exports

Core Types

• OntologyObject<TProps> — Base interface for all ontology objects ($objectType, $primaryKey, $version, $properties, timestamps)
• ObjectSetBuilder<T, TProps> — Lazy query builder interface (filter, order, paginate, aggregate)
• ObjectTypeOperations<T, TCreate, TUpdate> — CRUD + OCC + upsert + batch operations interface
• PageResult<T> — Paginated response (data, total, cursor, hasMore)

Filters

• FilterClause — Serializable filter ({ property, operator, value })
• FilterBuilders<TProps> — Type-safe proxy for building filters (eq, gt, contains, in, isNull, between, before, after)
• StringFilter, NumberFilter, DateFilter, BooleanFilter

Ordering & Aggregation

• OrderByClause — { property, direction: 'asc' | 'desc' }
• AggregationClause — { field, operation: 'count' | 'sum' | 'avg' | 'min' | 'max' }

Links

• SingleLinkAccessor<T> — Navigate 1:1 / N:1 relationships
• MultiLinkAccessor<T> — Navigate 1:N / N:N relationships (paginated)

Client Config

• ClientConfig — baseUrl, apiKey, workspaceId, espaceId, timeout, retry, fetch
• RetryConfig — maxAttempts, baseDelayMs, maxDelayMs
• RequestOptions — Per-request options (method, path, body, signal, timeoutMs, idempotencyKey)

Manifest (Codegen)

• OntologyManifest, ObjectTypeDescriptor, PropertyDescriptor, LinkTypeDescriptor, ActionDescriptor, InterfaceDescriptor

Errors (Runtime Values)

All extend DataForgeError (with .toJSON() safe redaction of sensitive fields):

| Class | HTTP Status | Extra Fields | |-------|------------|--------------| | AuthenticationError | 401 | | | AuthorizationError | 403 | | | NotFoundError | 404 | | | ValidationError | 400 | fieldErrors | | ConflictError | 409 | currentVersion | | RateLimitError | 429 | retryAfterMs | | ServerError | 5xx | |

Write Operations (v0.5.0)

• WriteOptions — Extends OperationOptions with expectedVersion? for OCC
• UpsertResult<T> — { created: boolean, object: T }
• BatchResult<T> — { results: BatchItemResult<T>[], succeeded, failed }
• BatchItemResult<T> — { ok: true, data: T, index } | { ok: false, error, index }
• BatchOptions — mode?: 'allOrNothing' | 'partial', throwOnFirstError?

Streaming

• StreamEvent<TType, TData> — Typed streaming event
• StreamAbortError, StreamParseError, StreamProtocolError

Zod Schemas (v3.0.0)

Optional runtime validation schemas for API responses. Requires zod peer dependency (opt-in).

import { PageResultSchema, AgentResponseSchema } from '@dataforge/sdk-types/schemas';

Available schemas: PageResultSchema, AgentResponseSchema, KnowledgeSearchResultSchema, WorkflowRunSchema, CalendarEventSchema, PipelineRunSchema, DataSourceSchema, AuditEventSchema, ApprovalRequestSchema, McpToolResultSchema.

License

MIT