@clidey/whodb-sdk 0.0.0

package/dist/transport-http.js

@@ -0,0 +1,60 @@
+import { mapGraphQLErrors, AuthError, PlatformError } from './errors.js';
+import { SDK_VERSION } from './version.js';
+const RETRYABLE_STATUS = new Set([502, 503, 504]);
+/**
+ * HttpTransport posts operations to `<host>/api/query` with bearer
+ * credentials and workspace headers. It retries once on a transient 5xx and
+ * once after refreshing credentials on a 401.
+ */
+export class HttpTransport {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Sets the workspace scope headers used on subsequent requests. */
+    setWorkspace(orgId, projectId) {
+        this.options.orgId = orgId;
+        this.options.projectId = projectId;
+    }
+    async execute(operationName, document, variables) {
+        let response = await this.post(document, variables);
+        if (response.status === 401 && this.options.credentials.refresh) {
+            await this.options.credentials.refresh();
+            response = await this.post(document, variables);
+        }
+        else if (RETRYABLE_STATUS.has(response.status)) {
+            response = await this.post(document, variables);
+        }
+        if (response.status === 401) {
+            throw new AuthError('authentication failed — check your API key or run: whodb login');
+        }
+        if (!response.ok) {
+            throw new PlatformError(`platform request failed with HTTP ${response.status}`, `HTTP_${response.status}`);
+        }
+        const payload = (await response.json());
+        if (payload.errors && payload.errors.length > 0) {
+            throw mapGraphQLErrors(payload.errors);
+        }
+        if (!payload.data) {
+            throw new PlatformError(`empty response for ${operationName}`, 'EMPTY_RESPONSE');
+        }
+        return payload.data;
+    }
+    async post(document, variables) {
+        const token = await this.options.credentials.token();
+        const headers = {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+            'User-Agent': `clidey-whodb-ts/${SDK_VERSION}`,
+        };
+        if (this.options.orgId)
+            headers['X-Whodb-Org-Id'] = this.options.orgId;
+        if (this.options.projectId)
+            headers['X-Whodb-Project-Id'] = this.options.projectId;
+        return fetch(`${this.options.host.replace(/\/$/, '')}/api/query`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ query: document, variables }),
+        });
+    }
+}

package/dist/transport-ipc.d.ts

@@ -0,0 +1,31 @@
+import type { Transport } from './transport.js';
+/**
+ * IpcTransport runs the same facades inside the WhoDB Functions runtime,
+ * over the in-container IPC server (unix socket in Docker, TCP in K8s).
+ *
+ * Two impedance differences are absorbed here:
+ * - GraphQL operations address entities by ID; IPC endpoints address them by
+ *   apiName. IDs resolve via a cached /entities call.
+ * - GraphQL write mutations carry RecordInput pairs; IPC takes plain objects.
+ *
+ * Operations outside the ontology surface (datasets, sources, files,
+ * workspace) throw TransportCapabilityError in v1.
+ */
+export declare class IpcTransport implements Transport {
+    private readonly address;
+    private readonly jobId;
+    private readonly token;
+    private entitiesCache;
+    constructor(options?: {
+        address?: string;
+        jobId?: string;
+        token?: string;
+    });
+    execute(operationName: string, _document: string, variables: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private post;
+    private entities;
+    private entityName;
+    private entityPk;
+    private recordInputsToData;
+    private readonly handlers;
+}

package/dist/transport-ipc.js

@@ -0,0 +1,183 @@
+import { request as httpRequest } from 'node:http';
+import { NotFoundError, PlatformError, TransportCapabilityError } from './errors.js';
+/**
+ * IpcTransport runs the same facades inside the WhoDB Functions runtime,
+ * over the in-container IPC server (unix socket in Docker, TCP in K8s).
+ *
+ * Two impedance differences are absorbed here:
+ * - GraphQL operations address entities by ID; IPC endpoints address them by
+ *   apiName. IDs resolve via a cached /entities call.
+ * - GraphQL write mutations carry RecordInput pairs; IPC takes plain objects.
+ *
+ * Operations outside the ontology surface (datasets, sources, files,
+ * workspace) throw TransportCapabilityError in v1.
+ */
+export class IpcTransport {
+    address;
+    jobId;
+    token;
+    entitiesCache = null;
+    constructor(options = {}) {
+        this.address = options.address ?? process.env.WHODB_IPC_ADDRESS ?? '';
+        this.jobId = options.jobId ?? process.env.WHODB_JOB_ID ?? '';
+        this.token = options.token ?? process.env.WHODB_IPC_TOKEN ?? '';
+    }
+    async execute(operationName, _document, variables) {
+        const handler = this.handlers[operationName];
+        if (!handler) {
+            throw new TransportCapabilityError(`${operationName} is not available inside the function runtime in v1`);
+        }
+        return { [operationName]: await handler(variables) };
+    }
+    post(path, body) {
+        return new Promise((resolve, reject) => {
+            const payload = JSON.stringify(body ?? {});
+            const isSocket = this.address.startsWith('/');
+            const options = {
+                method: 'POST',
+                path,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Content-Length': Buffer.byteLength(payload),
+                    'X-Job-ID': this.jobId,
+                    Authorization: this.token,
+                },
+                ...(isSocket
+                    ? { socketPath: this.address }
+                    : {
+                        host: this.address.split(':')[0],
+                        port: Number(this.address.split(':')[1] ?? 80),
+                    }),
+            };
+            const req = httpRequest(options, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    const text = Buffer.concat(chunks).toString('utf8');
+                    if ((res.statusCode ?? 500) >= 400) {
+                        reject(new PlatformError(`IPC request ${path} failed with HTTP ${res.statusCode}`, `IPC_${res.statusCode}`));
+                        return;
+                    }
+                    try {
+                        resolve(text ? JSON.parse(text) : null);
+                    }
+                    catch {
+                        reject(new PlatformError(`IPC request ${path} returned invalid JSON`, 'IPC_INVALID_JSON'));
+                    }
+                });
+            });
+            req.on('error', reject);
+            req.end(payload);
+        });
+    }
+    async entities() {
+        this.entitiesCache ??= (await this.post('/entities', {})) ?? [];
+        return this.entitiesCache;
+    }
+    async entityName(entityId) {
+        const entity = (await this.entities()).find(e => e.id === entityId);
+        if (!entity)
+            throw new NotFoundError(`ontology entity ${entityId} not found in this function's scope`);
+        return String(entity.apiName ?? '');
+    }
+    async entityPk(entityId) {
+        const entity = (await this.entities()).find(e => e.id === entityId);
+        return String(entity?.primaryKey ?? '');
+    }
+    recordInputsToData(values) {
+        const data = {};
+        for (const record of values ?? []) {
+            data[record.Key] = record.Value;
+        }
+        return data;
+    }
+    handlers = {
+        OntologyEntities: async () => this.entities(),
+        OntologyQuery: async (variables) => {
+            const input = { ...(variables.input ?? {}) };
+            const body = {};
+            for (const [key, value] of Object.entries(input)) {
+                if (value !== null && value !== undefined)
+                    body[key] = value;
+            }
+            const whereJson = body.whereJson;
+            delete body.whereJson;
+            if (whereJson)
+                body.where = JSON.parse(whereJson);
+            return this.post('/query', body);
+        },
+        OntologyDescribe: async (variables) => this.post('/describe', variables.input ?? {}),
+        OntologyStats: async (variables) => this.post('/stats', {
+            entity: await this.entityName(String(variables.id)),
+            property: variables.property,
+            where: variables.where,
+        }),
+        OntologySimilar: async (variables) => {
+            const input = variables.input ?? {};
+            return this.post('/similar', {
+                entity: await this.entityName(String(input.entityId)),
+                rowId: input.rowId,
+                topK: input.topK,
+                properties: input.properties,
+                where: input.where,
+            });
+        },
+        OntologyAggregate: async (variables) => this.post('/query', {
+            entity: await this.entityName(String(variables.id)),
+            where: variables.where,
+            groupBy: variables.groupBy,
+            metrics: variables.metrics,
+            sort: variables.sort,
+            pageSize: variables.pageSize,
+            offset: variables.pageOffset,
+        }),
+        OntologyAddRow: async (variables) => {
+            await this.post('/create', {
+                entity: await this.entityName(String(variables.entityId)),
+                data: this.recordInputsToData(variables.values),
+            });
+            return { Status: true };
+        },
+        OntologyAddRows: async (variables) => {
+            const ids = (await this.post('/create_many', {
+                entity: await this.entityName(String(variables.entityId)),
+                rows: (variables.rows ?? []).map(row => this.recordInputsToData(row.values)),
+                idempotencyKey: variables.idempotencyKey,
+            })) ?? [];
+            return { inserted: ids.length, ids };
+        },
+        OntologyUpdateRow: async (variables) => {
+            const entityId = String(variables.entityId);
+            const data = this.recordInputsToData(variables.values);
+            const pkKey = await this.entityPk(entityId);
+            const pk = pkKey ? String(data[pkKey] ?? '') : '';
+            if (pkKey)
+                delete data[pkKey];
+            await this.post('/update', { entity: await this.entityName(entityId), pk, data });
+            return { Status: true };
+        },
+        OntologyDeleteRow: async (variables) => {
+            const entityId = String(variables.entityId);
+            const data = this.recordInputsToData(variables.values);
+            const pkKey = await this.entityPk(entityId);
+            const pk = pkKey ? String(data[pkKey] ?? '') : String(Object.values(data)[0] ?? '');
+            await this.post('/delete', { entity: await this.entityName(entityId), pk });
+            return { Status: true };
+        },
+        OntologyFollowLink: async (variables) => this.post('/follow_link', {
+            entity: await this.entityName(String(variables.entityId)),
+            pk: variables.pk,
+            link: variables.linkApiName,
+            pageSize: variables.pageSize,
+            offset: variables.pageOffset,
+        }),
+        OntologyFollowIncomingLink: async (variables) => this.post('/follow_incoming_link', {
+            entity: await this.entityName(String(variables.entityId)),
+            pk: variables.pk,
+            sourceEntity: await this.entityName(String(variables.sourceEntityId)),
+            link: variables.linkApiName,
+            pageSize: variables.pageSize,
+            offset: variables.pageOffset,
+        }),
+    };
+}

package/dist/transport.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Transport executes one platform operation and returns the GraphQL `data`
+ * object. Implementations: HttpTransport (default, GraphQL over HTTP) and
+ * IpcTransport (inside the WhoDB Functions runtime). The generated core and
+ * the facade never speak HTTP directly — everything routes through this seam.
+ */
+export interface Transport {
+    execute(operationName: string, document: string, variables: Record<string, unknown>): Promise<Record<string, unknown>>;
+}

package/dist/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SDK_VERSION is stamped by the release workflow (sync-versions.mjs) and used
+ * only for the User-Agent header — the SDK's sole telemetry.
+ */
+export declare const SDK_VERSION = "0.0.0";

package/dist/version.js

@@ -0,0 +1,5 @@
+/**
+ * SDK_VERSION is stamped by the release workflow (sync-versions.mjs) and used
+ * only for the User-Agent header — the SDK's sole telemetry.
+ */
+export const SDK_VERSION = '0.0.0';

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@clidey/whodb-sdk",
+  "version": "0.0.0",
+  "description": "Official WhoDB platform SDK — ontology, datasets, and sources as in-code function APIs",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test 'test/*.test.mjs'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clidey/whodb.git",
+    "directory": "sdk/packages/typescript"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.2",
+    "typescript": "6.0.3"
+  }
+}