@babav/knowledge-core-client 0.1.0

package/src/index.ts

@@ -0,0 +1,566 @@
+/**
+ * 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.
+ */
+
+// ---------------------------------------------------------------------------
+// Shared types (mirror the API Read models)
+// ---------------------------------------------------------------------------
+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; // present => conversational; absent => one-shot
+  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; // shown ONCE — store it now
+  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;
+}
+
+// ---------------------------------------------------------------------------
+// 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 {
+  constructor(
+    readonly status: number,
+    readonly detail: unknown,
+    readonly path: string,
+  ) {
+    super(`KnowledgeCore ${status} on ${path}: ${JSON.stringify(detail)}`);
+    this.name = "KnowledgeCoreError";
+  }
+  /** Convenience: the `error` code for structured guard responses. */
+  get code(): string | undefined {
+    const d = this.detail as { detail?: { error?: string }; error?: string };
+    return d?.detail?.error ?? d?.error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Base HTTP
+// ---------------------------------------------------------------------------
+export interface ClientOptions {
+  baseUrl: string;
+  apiKey: string;
+  /** Optional default fetch timeout (ms). Streaming ignores this. */
+  timeoutMs?: number;
+  fetch?: typeof fetch; // override for tests
+}
+
+interface RequestOpts {
+  query?: Record<string, string | number | boolean | undefined>;
+  json?: unknown;
+  body?: BodyInit; // raw body (attachment upload)
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+class HttpBase {
+  protected readonly baseUrl: string;
+  protected readonly apiKey: string;
+  protected readonly timeoutMs?: number;
+  protected readonly _fetch: typeof fetch;
+
+  constructor(opts: ClientOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    this.timeoutMs = opts.timeoutMs;
+    this._fetch = opts.fetch ?? fetch;
+  }
+
+  protected url(path: string, query?: RequestOpts["query"]): string {
+    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();
+  }
+
+  protected async raw(method: string, path: string, opts: RequestOpts = {}): Promise<Response> {
+    const headers: Record<string, string> = { "x-api-key": this.apiKey, ...(opts.headers ?? {}) };
+    let body: BodyInit | undefined;
+    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: ReturnType<typeof setTimeout> | undefined;
+    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);
+    }
+  }
+
+  protected async request<T>(method: string, path: string, opts: RequestOpts = {}): Promise<T> {
+    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 as T;
+  }
+
+  /** Auto-paginate a list endpoint into a single array. */
+  protected async pageAll<T>(path: string, query: RequestOpts["query"] = {}): Promise<T[]> {
+    const out: T[] = [];
+    let cursor: string | null | undefined = undefined;
+    do {
+      const page: Page<T> = await this.request<Page<T>>("GET", path, {
+        query: { ...query, cursor: cursor ?? undefined },
+      });
+      out.push(...page.items);
+      cursor = page.next_cursor;
+    } while (cursor);
+    return out;
+  }
+}
+
+function safeJson(t: string): unknown {
+  try {
+    return JSON.parse(t);
+  } catch {
+    return t;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SSE handlers
+// ---------------------------------------------------------------------------
+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;
+}
+
+// ---------------------------------------------------------------------------
+// Tenant client (data ops) — use a TENANT key
+// ---------------------------------------------------------------------------
+export class KnowledgeCoreClient extends HttpBase {
+  // --- query (agent-anchored) ---
+  query(agentId: UUID, body: QueryRequest): Promise<QueryResponse> {
+    return this.request("POST", `/v1/agents/${agentId}/query`, { json: body });
+  }
+
+  /** Streaming query (SSE). Resolves when the stream ends. */
+  async queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void> {
+    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: number;
+      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: { query: string; corpus_ids: UUID[]; top_k?: number; rerank?: boolean; instruction?: string; filter?: MetadataFilter; }): Promise<{ retrieval_contents: RetrievalContent[] }> {
+    return this.request("POST", "/v1/retrieve", { json: body });
+  }
+
+  // --- corpora ---
+  corpora = {
+    create: (b: { name: string; embedding_model: string; description?: string; external_ref?: string }) =>
+      this.request<Corpus>("POST", "/v1/corpora", { json: b }),
+    list: (q?: { limit?: number; cursor?: string }) => this.request<Page<Corpus>>("GET", "/v1/corpora", { query: q }),
+    listAll: () => this.pageAll<Corpus>("/v1/corpora"),
+    get: (id: UUID) => this.request<Corpus>("GET", `/v1/corpora/${id}`),
+    update: (id: UUID, b: { name?: string; description?: string; external_ref?: string }) =>
+      this.request<Corpus>("PATCH", `/v1/corpora/${id}`, { json: b }),
+    delete: (id: UUID, confirmName: string) => this.request<void>("DELETE", `/v1/corpora/${id}`, { query: { confirm: confirmName } }),
+    listFolders: (id: UUID) => this.pageAll<Folder>(`/v1/corpora/${id}/folders`),
+    listDocuments: (id: UUID, q?: { limit?: number; cursor?: string }) =>
+      this.request<Page<Document>>("GET", `/v1/corpora/${id}/documents`, { query: q }),
+    createDocument: (id: UUID, b: { source_uri: string; folder_id?: UUID; visibility?: Visibility; status?: string; parse_job_id?: UUID; custom_metadata?: Record<string, unknown> }) =>
+      this.request<Document>("POST", `/v1/corpora/${id}/documents`, { json: b }),
+    ingest: (id: UUID, b: { ingestion_agent_id: UUID; folder_id?: UUID; documents: { gcs_uri: string; custom_metadata?: Record<string, unknown>; visibility?: Visibility }[] }) =>
+      this.request<{ parse_job_id: UUID }>("POST", `/v1/corpora/${id}/ingest`, { json: b }),
+  };
+
+  // --- folders ---
+  folders = {
+    create: (corpusId: UUID, name: string) => this.request<Folder>("POST", `/v1/corpora/${corpusId}/folders`, { json: { name } }),
+    rename: (folderId: UUID, name: string) => this.request<Folder>("PATCH", `/v1/folders/${folderId}`, { json: { name } }),
+    delete: (folderId: UUID) => this.request<void>("DELETE", `/v1/folders/${folderId}`),
+    listDocuments: (folderId: UUID, q?: { limit?: number; cursor?: string }) =>
+      this.request<Page<Document>>("GET", `/v1/folders/${folderId}/documents`, { query: q }),
+  };
+
+  // --- documents ---
+  documents = {
+    get: (id: UUID) => this.request<Document>("GET", `/v1/documents/${id}`),
+    getMetadata: (id: UUID) => this.request<{ document_id: UUID; custom_metadata: Record<string, unknown> }>("GET", `/v1/documents/${id}/metadata`),
+    patchMetadata: (id: UUID, custom_metadata: Record<string, unknown>) =>
+      this.request<{ document_id: UUID; custom_metadata: Record<string, unknown> }>("PATCH", `/v1/documents/${id}/metadata`, { json: { custom_metadata } }),
+    update: (id: UUID, b: { visibility?: Visibility; folder_id?: UUID }) => this.request<Document>("PATCH", `/v1/documents/${id}`, { json: b }),
+    contentUrl: (id: UUID, disposition: "inline" | "attachment" = "inline") =>
+      this.request<ContentUrl>("GET", `/v1/documents/${id}/content-url`, { query: { disposition } }),
+    delete: (id: UUID) => this.request<void>("DELETE", `/v1/documents/${id}`),
+  };
+
+  // --- conversations ---
+  conversations = {
+    create: (b?: { title?: string; custom_metadata?: Record<string, unknown>; ephemeral?: boolean }) =>
+      this.request<Conversation>("POST", "/v1/conversations", { json: b ?? {} }),
+    list: (q?: { limit?: number; cursor?: string }) => this.request<Page<Conversation>>("GET", "/v1/conversations", { query: q }),
+    get: (id: UUID) => this.request<Conversation>("GET", `/v1/conversations/${id}`),
+    update: (id: UUID, b: { title?: string; custom_metadata?: Record<string, unknown> }) =>
+      this.request<Conversation>("PATCH", `/v1/conversations/${id}`, { json: b }),
+    delete: (id: UUID) => this.request<void>("DELETE", `/v1/conversations/${id}`),
+    /** Filter by custom_metadata using the same metadata filter as documents. */
+    search: (b: { filter?: MetadataFilter; limit?: number; cursor?: string }) =>
+      this.request<Page<Conversation>>("POST", "/v1/conversations/search", { json: b }),
+    listMessages: (id: UUID, q?: { limit?: number; cursor?: string }) =>
+      this.request<Page<Message>>("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: UUID, a: { filename: string; content_type: string; data: BodyInit; custom_metadata?: Record<string, unknown> }) =>
+      this.request<ConversationDocument>("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: UUID, q?: { limit?: number; cursor?: string }) =>
+      this.request<Page<ConversationDocument>>("GET", `/v1/conversations/${conversationId}/documents`, { query: q }),
+    get: (conversationId: UUID, docId: UUID) => this.request<ConversationDocument>("GET", `/v1/conversations/${conversationId}/documents/${docId}`),
+    contentUrl: (conversationId: UUID, docId: UUID, disposition: "inline" | "attachment" = "inline") =>
+      this.request<ContentUrl>("GET", `/v1/conversations/${conversationId}/documents/${docId}/content-url`, { query: { disposition } }),
+    delete: (conversationId: UUID, docId: UUID) => this.request<void>("DELETE", `/v1/conversations/${conversationId}/documents/${docId}`),
+    /** Poll until the attachment is ready or failed (or timeout). */
+    waitReady: async (conversationId: UUID, docId: UUID, opts: { intervalMs?: number; timeoutMs?: number } = {}): Promise<ConversationDocument> => {
+      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: UUID) => this.request<Message>("GET", `/v1/messages/${id}`),
+    createFeedback: (messageId: UUID, b: { rating?: number; comment?: string }) =>
+      this.request<Feedback>("POST", `/v1/messages/${messageId}/feedback`, { json: b }),
+    listFeedback: (messageId: UUID, q?: { limit?: number; cursor?: string }) =>
+      this.request<Page<Feedback>>("GET", `/v1/messages/${messageId}/feedback`, { query: q }),
+  };
+  feedback = {
+    get: (id: UUID) => this.request<Feedback>("GET", `/v1/feedback/${id}`),
+    delete: (id: UUID) => this.request<void>("DELETE", `/v1/feedback/${id}`),
+  };
+
+  // --- parse jobs ---
+  parseJobs = {
+    list: (q?: { status_filter?: string; limit?: number; cursor?: string }) => this.request<Page<ParseJob>>("GET", "/v1/parse_jobs", { query: q }),
+    get: (id: UUID) => this.request<ParseJob>("GET", `/v1/parse_jobs/${id}`),
+  };
+
+  // --- agents (tenant read-only: choose an agent to query) ---
+  agents = {
+    list: (q?: { kind?: "query" | "ingestion"; limit?: number; cursor?: string }) => this.request<Page<Agent>>("GET", "/v1/agents", { query: q }),
+    listAll: () => this.pageAll<Agent>("/v1/agents"),
+    get: (id: UUID) => this.request<Agent>("GET", `/v1/agents/${id}`),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Admin client (tenant + key + agent management) — use the ADMIN key
+// ---------------------------------------------------------------------------
+export class AdminClient extends HttpBase {
+  tenants = {
+    create: (b: Partial<Tenant> & { name: string }) => this.request<Tenant>("POST", "/v1/tenants", { json: b }),
+    list: (q?: { limit?: number; cursor?: string }) => this.request<Page<Tenant>>("GET", "/v1/tenants", { query: q }),
+    get: (id: UUID) => this.request<Tenant>("GET", `/v1/tenants/${id}`),
+    update: (id: UUID, b: Partial<Tenant>) => this.request<Tenant>("PATCH", `/v1/tenants/${id}`, { json: b }),
+    delete: (id: UUID, confirmName: string) => this.request<void>("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: UUID, label?: string) => this.request<ApiKeyCreated>("POST", `/v1/tenants/${tenantId}/api-keys`, { json: { label } }),
+    listApiKeys: (tenantId: UUID, q?: { limit?: number; cursor?: string }) => this.request<Page<ApiKeyInfo>>("GET", `/v1/tenants/${tenantId}/api-keys`, { query: q }),
+    revokeApiKey: (tenantId: UUID, keyId: UUID) => this.request<void>("DELETE", `/v1/tenants/${tenantId}/api-keys/${keyId}`),
+  };
+
+  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 }) =>
+      this.request<Agent>("POST", "/v1/agents", { json: b }),
+    update: (id: UUID, b: Partial<Omit<Agent, "id" | "kind" | "tenant_id" | "created_at" | "updated_at">>) =>
+      this.request<Agent>("PATCH", `/v1/agents/${id}`, { json: b }),
+    delete: (id: UUID) => this.request<void>("DELETE", `/v1/agents/${id}`),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function dispatchSse(frame: string, h: StreamHandlers): void {
+  let event = "message";
+  const dataLines: string[] = [];
+  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 as never); break;
+    case "retrieval_contents": h.onSources?.(data as never); break;
+    case "token": h.onToken?.((data as { text: string }).text); break;
+    case "final": h.onFinal?.(data as QueryResponse); break;
+    case "error": h.onError?.(data); break;
+    case "done": h.onDone?.(); break;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}