@babav/knowledge-core-client

TypeScript client for the Babav Knowledge Core API. Zero dependencies; runs in Supabase Edge Functions (Deno) and Railway (Node 18+) unchanged (uses the global fetch + ReadableStream). It lives in the babav-knowledge-core repo so every API change is reflected here 1:1 — wire shapes are snake_case to match the API.

The API key is server-side only. Use a TENANT key for data ops; never ship it to a browser. The frontend mediates end-user permissions + visibility.

Install / import

Published as a public npm package (free; no secrets in it — the API key is held server-side by you, never embedded). Use it like any other dependency.

Node / Railway:

npm install @babav/knowledge-core-client

import { KnowledgeCoreClient, KnowledgeCoreError } from "@babav/knowledge-core-client";

Deno / Supabase Edge:

import { KnowledgeCoreClient } from "npm:@babav/knowledge-core-client";

(or, to avoid the registry entirely, import the single self-contained source file <repo>/clients/typescript/mod.ts — zero deps.)

Usage

// You supply baseUrl + your tenant key at construction (from wherever your app keeps
// its config/secrets). The SDK never reads the environment or defaults a key itself.
const kc = new KnowledgeCoreClient({
  baseUrl: "https://knowledgecore.babav.ai",
  apiKey: myTenantKey, // your tenant key, provided by your app
});

// One-shot grounded query
const r = await kc.query(agentId, { corpus_ids: [corpusId], query: "..." });
console.log(r.answer, r.retrieval_contents, r.citations, r.groundedness);

// Conversational (persisted, history-aware)
const convo = await kc.conversations.create({ title: "Contract review", custom_metadata: { account_id } });
const turn = await kc.query(agentId, { corpus_ids: [corpusId], query: "...", conversation_id: convo.id });

// Streaming (SSE)
await kc.queryStream(agentId, { corpus_ids: [corpusId], query: "..." }, {
  onSources: (s) => render(s.retrieval_contents),
  onToken: (t) => append(t),
  onFinal: (f) => done(f),
  onError: (e) => fail(e),
});

// Attachment-backed review
const att = await kc.attachments.upload(convo.id, { filename: "c.pdf", content_type: "application/pdf", data: bytes });
await kc.attachments.waitReady(convo.id, att.id);
const review = await kc.query(agentId, { corpus_ids: [corpusId], conversation_id: convo.id, query: "Review the attached contract." });

// View/download a stored doc (signed URL)
const { content_url, content_type } = await kc.documents.contentUrl(documentId, "inline");

Error handling (structured guards)

try { await kc.query(agentId, body); }
catch (e) {
  if (e instanceof KnowledgeCoreError) {
    if (e.code === "attachments_pending") { /* a document is still parsing */ }
    else if (e.code === "attachment_exceeds_context_window") { /* too large; e.detail has sizes */ }
    else if (e.status === 404) { /* not found / not your tenant */ }
  }
}

Admin client (tenant + key + agent management — ADMIN key)

import { AdminClient } from "@babav/knowledge-core-client";
const admin = new AdminClient({ baseUrl, apiKey: ADMIN_KEY });
const created = await admin.tenants.createApiKey(tenantId, "label"); // created.api_key shown ONCE

Surface

• query, queryStream, retrieve
• corpora (CRUD, listFolders, listDocuments, createDocument, ingest)
• folders (create, rename, delete, listDocuments)
• documents (get, getMetadata, patchMetadata, update, contentUrl, delete)
• conversations (CRUD, search, listMessages)
• attachments (upload, list, get, contentUrl, delete, waitReady)
• messages (get, createFeedback, listFeedback), feedback (get, delete)
• parseJobs (list, get), agents (list, get)
• AdminClient: tenants (CRUD + api-keys), agents (create/update/delete)