@babav/knowledge-core-client 0.1.0

package/dist/index.js

@@ -0,0 +1,297 @@
+/**
+ * Babav Knowledge Core — TypeScript client.
+ *
+ * Portable: uses the global `fetch` + `ReadableStream`, so it runs unchanged in
+ * Supabase Edge Functions (Deno) and Railway (Node 18+). Zero dependencies.
+ *
+ * Wire shapes are snake_case to mirror the Knowledge Core API 1:1 — so an API
+ * change is reflected here with a one-to-one type edit and never drifts.
+ *
+ * Auth: every call carries an X-API-Key. Use TenantClient with a TENANT key for
+ * all data ops; use AdminClient with the ADMIN key for tenant / API-key / agent
+ * management. The key is server-side only — never ship it to a browser.
+ */
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+/** Thrown on any non-2xx response. `detail` is the structured body when present
+ *  (e.g. {error:"attachments_pending", attachments:[...]} or
+ *  {error:"attachment_exceeds_context_window", ...}). */
+export class KnowledgeCoreError extends Error {
+    status;
+    detail;
+    path;
+    constructor(status, detail, path) {
+        super(`KnowledgeCore ${status} on ${path}: ${JSON.stringify(detail)}`);
+        this.status = status;
+        this.detail = detail;
+        this.path = path;
+        this.name = "KnowledgeCoreError";
+    }
+    /** Convenience: the `error` code for structured guard responses. */
+    get code() {
+        const d = this.detail;
+        return d?.detail?.error ?? d?.error;
+    }
+}
+class HttpBase {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    _fetch;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+        this.timeoutMs = opts.timeoutMs;
+        this._fetch = opts.fetch ?? fetch;
+    }
+    url(path, query) {
+        const u = new URL(this.baseUrl + path);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== undefined)
+                    u.searchParams.set(k, String(v));
+            }
+        }
+        return u.toString();
+    }
+    async raw(method, path, opts = {}) {
+        const headers = { "x-api-key": this.apiKey, ...(opts.headers ?? {}) };
+        let body;
+        if (opts.json !== undefined) {
+            headers["content-type"] = "application/json";
+            body = JSON.stringify(opts.json);
+        }
+        else if (opts.body !== undefined) {
+            body = opts.body;
+        }
+        let signal = opts.signal;
+        let timer;
+        if (!signal && this.timeoutMs) {
+            const ac = new AbortController();
+            timer = setTimeout(() => ac.abort(), this.timeoutMs);
+            signal = ac.signal;
+        }
+        try {
+            return await this._fetch(this.url(path, opts.query), { method, headers, body, signal });
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async request(method, path, opts = {}) {
+        const res = await this.raw(method, path, opts);
+        const text = await res.text();
+        const parsed = text ? safeJson(text) : null;
+        if (!res.ok)
+            throw new KnowledgeCoreError(res.status, parsed ?? text, path);
+        return parsed;
+    }
+    /** Auto-paginate a list endpoint into a single array. */
+    async pageAll(path, query = {}) {
+        const out = [];
+        let cursor = undefined;
+        do {
+            const page = await this.request("GET", path, {
+                query: { ...query, cursor: cursor ?? undefined },
+            });
+            out.push(...page.items);
+            cursor = page.next_cursor;
+        } while (cursor);
+        return out;
+    }
+}
+function safeJson(t) {
+    try {
+        return JSON.parse(t);
+    }
+    catch {
+        return t;
+    }
+}
+// ---------------------------------------------------------------------------
+// Tenant client (data ops) — use a TENANT key
+// ---------------------------------------------------------------------------
+export class KnowledgeCoreClient extends HttpBase {
+    // --- query (agent-anchored) ---
+    query(agentId, body) {
+        return this.request("POST", `/v1/agents/${agentId}/query`, { json: body });
+    }
+    /** Streaming query (SSE). Resolves when the stream ends. */
+    async queryStream(agentId, body, handlers, signal) {
+        const res = await this.raw("POST", `/v1/agents/${agentId}/query/stream`, { json: body, signal });
+        if (!res.ok || !res.body) {
+            const t = await res.text();
+            throw new KnowledgeCoreError(res.status, safeJson(t), `/v1/agents/${agentId}/query/stream`);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buf.indexOf("\n\n")) !== -1) {
+                const frame = buf.slice(0, idx);
+                buf = buf.slice(idx + 2);
+                dispatchSse(frame, handlers);
+            }
+        }
+        if (buf.trim())
+            dispatchSse(buf, handlers);
+    }
+    // --- retrieve (cross-corpus primitive, no generation) ---
+    retrieve(body) {
+        return this.request("POST", "/v1/retrieve", { json: body });
+    }
+    // --- corpora ---
+    corpora = {
+        create: (b) => this.request("POST", "/v1/corpora", { json: b }),
+        list: (q) => this.request("GET", "/v1/corpora", { query: q }),
+        listAll: () => this.pageAll("/v1/corpora"),
+        get: (id) => this.request("GET", `/v1/corpora/${id}`),
+        update: (id, b) => this.request("PATCH", `/v1/corpora/${id}`, { json: b }),
+        delete: (id, confirmName) => this.request("DELETE", `/v1/corpora/${id}`, { query: { confirm: confirmName } }),
+        listFolders: (id) => this.pageAll(`/v1/corpora/${id}/folders`),
+        listDocuments: (id, q) => this.request("GET", `/v1/corpora/${id}/documents`, { query: q }),
+        createDocument: (id, b) => this.request("POST", `/v1/corpora/${id}/documents`, { json: b }),
+        ingest: (id, b) => this.request("POST", `/v1/corpora/${id}/ingest`, { json: b }),
+    };
+    // --- folders ---
+    folders = {
+        create: (corpusId, name) => this.request("POST", `/v1/corpora/${corpusId}/folders`, { json: { name } }),
+        rename: (folderId, name) => this.request("PATCH", `/v1/folders/${folderId}`, { json: { name } }),
+        delete: (folderId) => this.request("DELETE", `/v1/folders/${folderId}`),
+        listDocuments: (folderId, q) => this.request("GET", `/v1/folders/${folderId}/documents`, { query: q }),
+    };
+    // --- documents ---
+    documents = {
+        get: (id) => this.request("GET", `/v1/documents/${id}`),
+        getMetadata: (id) => this.request("GET", `/v1/documents/${id}/metadata`),
+        patchMetadata: (id, custom_metadata) => this.request("PATCH", `/v1/documents/${id}/metadata`, { json: { custom_metadata } }),
+        update: (id, b) => this.request("PATCH", `/v1/documents/${id}`, { json: b }),
+        contentUrl: (id, disposition = "inline") => this.request("GET", `/v1/documents/${id}/content-url`, { query: { disposition } }),
+        delete: (id) => this.request("DELETE", `/v1/documents/${id}`),
+    };
+    // --- conversations ---
+    conversations = {
+        create: (b) => this.request("POST", "/v1/conversations", { json: b ?? {} }),
+        list: (q) => this.request("GET", "/v1/conversations", { query: q }),
+        get: (id) => this.request("GET", `/v1/conversations/${id}`),
+        update: (id, b) => this.request("PATCH", `/v1/conversations/${id}`, { json: b }),
+        delete: (id) => this.request("DELETE", `/v1/conversations/${id}`),
+        /** Filter by custom_metadata using the same metadata filter as documents. */
+        search: (b) => this.request("POST", "/v1/conversations/search", { json: b }),
+        listMessages: (id, q) => this.request("GET", `/v1/conversations/${id}/messages`, { query: q }),
+    };
+    // --- conversation attachments (pinned full-document review) ---
+    attachments = {
+        /** Upload + attach a document. `data` is the raw file bytes. Returns status=parsing. */
+        upload: (conversationId, a) => this.request("POST", `/v1/conversations/${conversationId}/documents`, {
+            body: a.data,
+            headers: { "content-type": a.content_type },
+            query: { filename: a.filename, content_type: a.content_type, custom_metadata: a.custom_metadata ? JSON.stringify(a.custom_metadata) : undefined },
+        }),
+        list: (conversationId, q) => this.request("GET", `/v1/conversations/${conversationId}/documents`, { query: q }),
+        get: (conversationId, docId) => this.request("GET", `/v1/conversations/${conversationId}/documents/${docId}`),
+        contentUrl: (conversationId, docId, disposition = "inline") => this.request("GET", `/v1/conversations/${conversationId}/documents/${docId}/content-url`, { query: { disposition } }),
+        delete: (conversationId, docId) => this.request("DELETE", `/v1/conversations/${conversationId}/documents/${docId}`),
+        /** Poll until the attachment is ready or failed (or timeout). */
+        waitReady: async (conversationId, docId, opts = {}) => {
+            const interval = opts.intervalMs ?? 3000;
+            const deadline = Date.now() + (opts.timeoutMs ?? 180_000);
+            for (;;) {
+                const d = await this.attachments.get(conversationId, docId);
+                if (d.status === "ready" || d.status === "failed" || Date.now() > deadline)
+                    return d;
+                await sleep(interval);
+            }
+        },
+    };
+    // --- messages + feedback ---
+    messages = {
+        get: (id) => this.request("GET", `/v1/messages/${id}`),
+        createFeedback: (messageId, b) => this.request("POST", `/v1/messages/${messageId}/feedback`, { json: b }),
+        listFeedback: (messageId, q) => this.request("GET", `/v1/messages/${messageId}/feedback`, { query: q }),
+    };
+    feedback = {
+        get: (id) => this.request("GET", `/v1/feedback/${id}`),
+        delete: (id) => this.request("DELETE", `/v1/feedback/${id}`),
+    };
+    // --- parse jobs ---
+    parseJobs = {
+        list: (q) => this.request("GET", "/v1/parse_jobs", { query: q }),
+        get: (id) => this.request("GET", `/v1/parse_jobs/${id}`),
+    };
+    // --- agents (tenant read-only: choose an agent to query) ---
+    agents = {
+        list: (q) => this.request("GET", "/v1/agents", { query: q }),
+        listAll: () => this.pageAll("/v1/agents"),
+        get: (id) => this.request("GET", `/v1/agents/${id}`),
+    };
+}
+// ---------------------------------------------------------------------------
+// Admin client (tenant + key + agent management) — use the ADMIN key
+// ---------------------------------------------------------------------------
+export class AdminClient extends HttpBase {
+    tenants = {
+        create: (b) => this.request("POST", "/v1/tenants", { json: b }),
+        list: (q) => this.request("GET", "/v1/tenants", { query: q }),
+        get: (id) => this.request("GET", `/v1/tenants/${id}`),
+        update: (id, b) => this.request("PATCH", `/v1/tenants/${id}`, { json: b }),
+        delete: (id, confirmName) => this.request("DELETE", `/v1/tenants/${id}`, { query: { confirm: confirmName } }),
+        /** Mint a tenant API key — the raw key is in the response ONCE; store it now. */
+        createApiKey: (tenantId, label) => this.request("POST", `/v1/tenants/${tenantId}/api-keys`, { json: { label } }),
+        listApiKeys: (tenantId, q) => this.request("GET", `/v1/tenants/${tenantId}/api-keys`, { query: q }),
+        revokeApiKey: (tenantId, keyId) => this.request("DELETE", `/v1/tenants/${tenantId}/api-keys/${keyId}`),
+    };
+    agents = {
+        /** tenant_id explicit, or null for a global/shared agent. */
+        create: (b) => this.request("POST", "/v1/agents", { json: b }),
+        update: (id, b) => this.request("PATCH", `/v1/agents/${id}`, { json: b }),
+        delete: (id) => this.request("DELETE", `/v1/agents/${id}`),
+    };
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function dispatchSse(frame, h) {
+    let event = "message";
+    const dataLines = [];
+    for (const line of frame.split("\n")) {
+        if (line.startsWith("event:"))
+            event = line.slice(6).trim();
+        else if (line.startsWith("data:"))
+            dataLines.push(line.slice(5).trim());
+    }
+    if (dataLines.length === 0)
+        return;
+    const data = safeJson(dataLines.join("\n"));
+    h.onEvent?.(event, data);
+    switch (event) {
+        case "hop":
+            h.onHop?.(data);
+            break;
+        case "retrieval_contents":
+            h.onSources?.(data);
+            break;
+        case "token":
+            h.onToken?.(data.text);
+            break;
+        case "final":
+            h.onFinal?.(data);
+            break;
+        case "error":
+            h.onError?.(data);
+            break;
+        case "done":
+            h.onDone?.();
+            break;
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@babav/knowledge-core-client",
+  "version": "0.1.0",
+  "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bkaponig/babav-knowledge-core.git",
+    "directory": "clients/typescript"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "engines": { "node": ">=18" },
+  "sideEffects": false,
+  "private": false,
+  "license": "UNLICENSED"
+}