@babav/knowledge-core-client 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# @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:**
+```bash
+npm install @babav/knowledge-core-client
+```
+```ts
+import { KnowledgeCoreClient, KnowledgeCoreError } from "@babav/knowledge-core-client";
+```
+
+**Deno / Supabase Edge:**
+```ts
+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
+
+```ts
+const kc = new KnowledgeCoreClient({
+  baseUrl: "https://babav-kc-api-gmtvlr3vta-uc.a.run.app",
+  apiKey: Deno.env.get("BABAV_KC_TENANT_KEY")!, // or process.env on Node
+});
+
+// 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)
+```ts
+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)
+```ts
+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)

package/dist/index.d.ts

@@ -0,0 +1,477 @@
+/**
+ * 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.
+ */
+export type UUID = string;
+export interface Page<T> {
+    items: T[];
+    next_cursor: string | null;
+}
+export type Visibility = "downloadable" | "viewable" | "attributable" | "hidden";
+export type FilterOp = "eq" | "ne" | "in" | "nin" | "gt" | "gte" | "lt" | "lte" | "exists";
+export interface FilterClause {
+    field: string;
+    op: FilterOp;
+    value?: unknown;
+}
+export interface MetadataFilter {
+    op?: "and" | "or";
+    clauses: FilterClause[];
+}
+export interface RetrievalContent {
+    text: string;
+    score: number;
+    parent_id: string;
+    document_id: string;
+    corpus_id: string;
+    source_type: "corpus" | "conversation_attachment";
+    visibility: Visibility | string;
+    metadata: Record<string, unknown>;
+    source_url: string | null;
+}
+export interface QueryOverrides {
+    generation_model?: string;
+    top_k?: number;
+    rerank_instruction?: string;
+    max_hops?: number;
+    groundedness_threshold?: number;
+    grounding_enabled?: boolean;
+}
+export interface QueryRequest {
+    corpus_ids: UUID[];
+    query: string;
+    conversation_id?: UUID | null;
+    overrides?: QueryOverrides;
+    filter?: MetadataFilter;
+}
+export interface QueryResponse {
+    conversation_id: UUID | null;
+    message_id: UUID | null;
+    answer: string;
+    retrieval_contents: RetrievalContent[];
+    citations: Citation[];
+    groundedness: Groundedness | null;
+    usage: Record<string, number | null>;
+    standalone_query: string | null;
+    hops: string[];
+}
+export interface Citation {
+    quote: string;
+    text_span: [number, number] | null;
+    context_index: number;
+    document_id: string;
+    source_url: string | null;
+    supported: boolean;
+}
+export interface Groundedness {
+    score: number;
+    model: string;
+    threshold: number | null;
+    passed: boolean | null;
+}
+export interface Corpus {
+    id: UUID;
+    tenant_id: UUID | null;
+    name: string;
+    description: string | null;
+    embedding_model: string;
+    external_ref: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Folder {
+    id: UUID;
+    corpus_id: UUID;
+    name: string;
+    is_default: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface Document {
+    id: UUID;
+    corpus_id: UUID;
+    folder_id: UUID;
+    source_uri: string;
+    status: string;
+    visibility: Visibility;
+    content_type: string | null;
+    filename: string | null;
+    parse_job_id: UUID | null;
+    chunk_count: number;
+    datapoint_ids: string[];
+    custom_metadata: Record<string, unknown>;
+    error: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ContentUrl {
+    content_url: string;
+    content_type: string;
+    filename: string;
+}
+export interface Conversation {
+    id: UUID;
+    tenant_id: UUID | null;
+    title: string | null;
+    custom_metadata: Record<string, unknown>;
+    ephemeral: boolean;
+    last_activity: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface Message {
+    id: UUID;
+    conversation_id: UUID;
+    agent_id: UUID | null;
+    corpus_ids: UUID[] | null;
+    query: string;
+    answer: string | null;
+    citations: Record<string, unknown> | null;
+    groundedness: Record<string, unknown> | null;
+    retrieval_contents: unknown[] | null;
+    retrieval_debug: Record<string, unknown> | null;
+    usage: Record<string, unknown> | null;
+    created_at: string;
+}
+export interface ConversationDocument {
+    id: UUID;
+    conversation_id: UUID;
+    tenant_id: UUID;
+    filename: string | null;
+    content_type: string | null;
+    byte_size: number | null;
+    status: "parsing" | "ready" | "failed";
+    custom_metadata: Record<string, unknown> | null;
+    error: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ParseJob {
+    id: UUID;
+    tenant_id: UUID | null;
+    status: string;
+    document_count: number;
+    completed_count: number;
+    failed_count: number;
+    documents: unknown[];
+    created_at: string;
+    updated_at: string;
+}
+export interface Feedback {
+    id: UUID;
+    message_id: UUID;
+    rating: number | null;
+    comment: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Agent {
+    id: UUID;
+    name: string;
+    kind: "query" | "ingestion";
+    tenant_id: UUID | null;
+    generation_model: string | null;
+    top_k: number | null;
+    rerank_instruction: string | null;
+    max_hops: number | null;
+    groundedness_threshold: number | null;
+    grounding_enabled: boolean | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Tenant {
+    id: UUID;
+    name: string;
+    external_ref: string | null;
+    vector_index: string | null;
+    source_bucket: string | null;
+    artifacts_bucket: string | null;
+    query_endpoint: string | null;
+    query_public_domain: string | null;
+    query_deployed_index_id: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ApiKeyCreated {
+    id: UUID;
+    api_key: string;
+    prefix: string;
+    label: string | null;
+    created_at: string;
+}
+export interface ApiKeyInfo {
+    id: UUID;
+    tenant_id: UUID;
+    prefix: string;
+    label: string | null;
+    last_used_at: string | null;
+    revoked_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** 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 declare class KnowledgeCoreError extends Error {
+    readonly status: number;
+    readonly detail: unknown;
+    readonly path: string;
+    constructor(status: number, detail: unknown, path: string);
+    /** Convenience: the `error` code for structured guard responses. */
+    get code(): string | undefined;
+}
+export interface ClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    /** Optional default fetch timeout (ms). Streaming ignores this. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+interface RequestOpts {
+    query?: Record<string, string | number | boolean | undefined>;
+    json?: unknown;
+    body?: BodyInit;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+declare class HttpBase {
+    protected readonly baseUrl: string;
+    protected readonly apiKey: string;
+    protected readonly timeoutMs?: number;
+    protected readonly _fetch: typeof fetch;
+    constructor(opts: ClientOptions);
+    protected url(path: string, query?: RequestOpts["query"]): string;
+    protected raw(method: string, path: string, opts?: RequestOpts): Promise<Response>;
+    protected request<T>(method: string, path: string, opts?: RequestOpts): Promise<T>;
+    /** Auto-paginate a list endpoint into a single array. */
+    protected pageAll<T>(path: string, query?: RequestOpts["query"]): Promise<T[]>;
+}
+export interface StreamHandlers {
+    onHop?: (d: {
+        n: number;
+        subquery: string;
+        status: string;
+        retrieval_contents?: number;
+    }) => void;
+    onSources?: (d: {
+        retrieval_contents: RetrievalContent[];
+    }) => void;
+    onToken?: (text: string) => void;
+    onFinal?: (d: QueryResponse) => void;
+    onError?: (d: unknown) => void;
+    onDone?: () => void;
+    /** Catch-all for any event (incl. unknown ones). */
+    onEvent?: (event: string, data: unknown) => void;
+}
+export declare class KnowledgeCoreClient extends HttpBase {
+    query(agentId: UUID, body: QueryRequest): Promise<QueryResponse>;
+    /** Streaming query (SSE). Resolves when the stream ends. */
+    queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void>;
+    retrieve(body: {
+        query: string;
+        corpus_ids: UUID[];
+        top_k?: number;
+        rerank?: boolean;
+        instruction?: string;
+        filter?: MetadataFilter;
+    }): Promise<{
+        retrieval_contents: RetrievalContent[];
+    }>;
+    corpora: {
+        create: (b: {
+            name: string;
+            embedding_model: string;
+            description?: string;
+            external_ref?: string;
+        }) => Promise<Corpus>;
+        list: (q?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Corpus>>;
+        listAll: () => Promise<Corpus[]>;
+        get: (id: UUID) => Promise<Corpus>;
+        update: (id: UUID, b: {
+            name?: string;
+            description?: string;
+            external_ref?: string;
+        }) => Promise<Corpus>;
+        delete: (id: UUID, confirmName: string) => Promise<void>;
+        listFolders: (id: UUID) => Promise<Folder[]>;
+        listDocuments: (id: UUID, q?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Document>>;
+        createDocument: (id: UUID, b: {
+            source_uri: string;
+            folder_id?: UUID;
+            visibility?: Visibility;
+            status?: string;
+            parse_job_id?: UUID;
+            custom_metadata?: Record<string, unknown>;
+        }) => Promise<Document>;
+        ingest: (id: UUID, b: {
+            ingestion_agent_id: UUID;
+            folder_id?: UUID;
+            documents: {
+                gcs_uri: string;
+                custom_metadata?: Record<string, unknown>;
+                visibility?: Visibility;
+            }[];
+        }) => Promise<{
+            parse_job_id: UUID;
+        }>;
+    };
+    folders: {
+        create: (corpusId: UUID, name: string) => Promise<Folder>;
+        rename: (folderId: UUID, name: string) => Promise<Folder>;
+        delete: (folderId: UUID) => Promise<void>;
+        listDocuments: (folderId: UUID, q?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Document>>;
+    };
+    documents: {
+        get: (id: UUID) => Promise<Document>;
+        getMetadata: (id: UUID) => Promise<{
+            document_id: UUID;
+            custom_metadata: Record<string, unknown>;
+        }>;
+        patchMetadata: (id: UUID, custom_metadata: Record<string, unknown>) => Promise<{
+            document_id: UUID;
+            custom_metadata: Record<string, unknown>;
+        }>;
+        update: (id: UUID, b: {
+            visibility?: Visibility;
+            folder_id?: UUID;
+        }) => Promise<Document>;
+        contentUrl: (id: UUID, disposition?: "inline" | "attachment") => Promise<ContentUrl>;
+        delete: (id: UUID) => Promise<void>;
+    };
+    conversations: {
+        create: (b?: {
+            title?: string;
+            custom_metadata?: Record<string, unknown>;
+            ephemeral?: boolean;
+        }) => Promise<Conversation>;
+        list: (q?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Conversation>>;
+        get: (id: UUID) => Promise<Conversation>;
+        update: (id: UUID, b: {
+            title?: string;
+            custom_metadata?: Record<string, unknown>;
+        }) => Promise<Conversation>;
+        delete: (id: UUID) => Promise<void>;
+        /** Filter by custom_metadata using the same metadata filter as documents. */
+        search: (b: {
+            filter?: MetadataFilter;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Conversation>>;
+        listMessages: (id: UUID, q?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Message>>;
+    };
+    attachments: {
+        /** Upload + attach a document. `data` is the raw file bytes. Returns status=parsing. */
+        upload: (conversationId: UUID, a: {
+            filename: string;
+            content_type: string;
+            data: BodyInit;
+            custom_metadata?: Record<string, unknown>;
+        }) => Promise<ConversationDocument>;
+        list: (conversationId: UUID, q?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<ConversationDocument>>;
+        get: (conversationId: UUID, docId: UUID) => Promise<ConversationDocument>;
+        contentUrl: (conversationId: UUID, docId: UUID, disposition?: "inline" | "attachment") => Promise<ContentUrl>;
+        delete: (conversationId: UUID, docId: UUID) => Promise<void>;
+        /** Poll until the attachment is ready or failed (or timeout). */
+        waitReady: (conversationId: UUID, docId: UUID, opts?: {
+            intervalMs?: number;
+            timeoutMs?: number;
+        }) => Promise<ConversationDocument>;
+    };
+    messages: {
+        get: (id: UUID) => Promise<Message>;
+        createFeedback: (messageId: UUID, b: {
+            rating?: number;
+            comment?: string;
+        }) => Promise<Feedback>;
+        listFeedback: (messageId: UUID, q?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Feedback>>;
+    };
+    feedback: {
+        get: (id: UUID) => Promise<Feedback>;
+        delete: (id: UUID) => Promise<void>;
+    };
+    parseJobs: {
+        list: (q?: {
+            status_filter?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<ParseJob>>;
+        get: (id: UUID) => Promise<ParseJob>;
+    };
+    agents: {
+        list: (q?: {
+            kind?: "query" | "ingestion";
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Agent>>;
+        listAll: () => Promise<Agent[]>;
+        get: (id: UUID) => Promise<Agent>;
+    };
+}
+export declare class AdminClient extends HttpBase {
+    tenants: {
+        create: (b: Partial<Tenant> & {
+            name: string;
+        }) => Promise<Tenant>;
+        list: (q?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Tenant>>;
+        get: (id: UUID) => Promise<Tenant>;
+        update: (id: UUID, b: Partial<Tenant>) => Promise<Tenant>;
+        delete: (id: UUID, confirmName: string) => Promise<void>;
+        /** Mint a tenant API key — the raw key is in the response ONCE; store it now. */
+        createApiKey: (tenantId: UUID, label?: string) => Promise<ApiKeyCreated>;
+        listApiKeys: (tenantId: UUID, q?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<ApiKeyInfo>>;
+        revokeApiKey: (tenantId: UUID, keyId: UUID) => Promise<void>;
+    };
+    agents: {
+        /** tenant_id explicit, or null for a global/shared agent. */
+        create: (b: {
+            name: string;
+            kind: "query" | "ingestion";
+            tenant_id?: UUID | null;
+            generation_model?: string;
+            top_k?: number;
+            rerank_instruction?: string;
+            max_hops?: number;
+            groundedness_threshold?: number;
+            grounding_enabled?: boolean;
+        }) => Promise<Agent>;
+        update: (id: UUID, b: Partial<Omit<Agent, "id" | "kind" | "tenant_id" | "created_at" | "updated_at">>) => Promise<Agent>;
+        delete: (id: UUID) => Promise<void>;
+    };
+}
+export {};