@babav/knowledge-core-client 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,15 +1,16 @@
 /**
  * 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.
+ * Portable: uses the global `fetch`, `FormData`, `Blob` + `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.
+ * Auth: every call carries an X-API-Key. Use KnowledgeCoreClient 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> {
@@ -18,6 +19,8 @@ export interface Page<T> {
 }
 export type Visibility = "downloadable" | "viewable" | "attributable" | "hidden";
 export type FilterOp = "eq" | "ne" | "in" | "nin" | "gt" | "gte" | "lt" | "lte" | "exists";
+/** Raw file input accepted by upload/parse helpers. */
+export type FileData = Blob | Uint8Array | ArrayBuffer;
 export interface FilterClause {
     field: string;
     op: FilterOp;
@@ -80,53 +83,45 @@ export interface Groundedness {
 }
 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;
 }
+/** Document tally for a corpus or folder. `indexed` = searchable; `in_flight` =
+ *  pending + ingesting (still processing); `failed` = terminal; `total` = all. */
+export interface DocumentCount {
+    total: number;
+    indexed: number;
+    in_flight: number;
+    failed: number;
+}
 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;
@@ -138,55 +133,33 @@ export interface Message {
     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 {
+export interface Attachment {
     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;
@@ -198,25 +171,18 @@ export interface Tenant {
     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 {
+export interface ApiKey {
     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;
+    revoked: boolean;
 }
 /** Thrown on any non-2xx response. `detail` is the structured body when present
  *  (e.g. {error:"attachments_pending", attachments:[...]} or
@@ -232,7 +198,8 @@ export declare class KnowledgeCoreError extends Error {
 export interface ClientOptions {
     baseUrl: string;
     apiKey: string;
-    /** Optional default fetch timeout (ms). Streaming ignores this. */
+    /** Optional default fetch timeout (ms). Streaming ignores this. Note:
+     *  synchronous ingest can take a while — set this generously or omit. */
     timeoutMs?: number;
     fetch?: typeof fetch;
 }
@@ -289,9 +256,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
     corpora: {
         create: (b: {
             name: string;
-            embedding_model: string;
             description?: string;
-            external_ref?: string;
         }) => Promise<Corpus>;
         list: (q?: {
             limit?: number;
@@ -302,7 +267,6 @@ export declare class KnowledgeCoreClient extends HttpBase {
         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[]>;
@@ -310,26 +274,27 @@ export declare class KnowledgeCoreClient extends HttpBase {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<Document>>;
-        createDocument: (id: UUID, b: {
-            source_uri: string;
-            folder_id?: UUID;
+        /** Count documents in the corpus: { total, indexed, in_flight, failed }. */
+        countDocuments: (id: UUID) => Promise<DocumentCount>;
+        /** Upload a file and ingest it ASYNCHRONOUSLY — resolves with the created
+         *  document at status `pending` (HTTP 202); track via documents.get() polling
+         *  the status to `indexed`/`failed`, or the tenant result webhook. */
+        ingestDocument: (id: UUID, a: {
+            file: FileData;
+            filename: string;
+            content_type?: string;
             visibility?: Visibility;
-            status?: string;
-            parse_job_id?: UUID;
+            folder_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;
-        }>;
     };
+    parse(a: {
+        file: FileData;
+        filename?: string;
+        content_type?: string;
+    }): Promise<{
+        text: string;
+    }>;
     folders: {
         create: (corpusId: UUID, name: string) => Promise<Folder>;
         rename: (folderId: UUID, name: string) => Promise<Folder>;
@@ -338,17 +303,14 @@ export declare class KnowledgeCoreClient extends HttpBase {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<Document>>;
+        /** Count documents in the folder: { total, indexed, in_flight, failed }. */
+        countDocuments: (folderId: UUID) => Promise<DocumentCount>;
     };
     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>;
-        }>;
+        getCustomMetadata: (id: UUID) => Promise<Record<string, unknown>>;
+        /** Merge custom_metadata (a null value deletes a key). Returns the merged object. */
+        patchCustomMetadata: (id: UUID, custom_metadata: Record<string, unknown>) => Promise<Record<string, unknown>>;
         update: (id: UUID, b: {
             visibility?: Visibility;
             folder_id?: UUID;
@@ -384,25 +346,20 @@ export declare class KnowledgeCoreClient extends HttpBase {
         }) => Promise<Page<Message>>;
     };
     attachments: {
-        /** Upload + attach a document. `data` is the raw file bytes. Returns status=parsing. */
+        /** Upload + attach a file and parse it SYNCHRONOUSLY — resolves with status=ready. */
         upload: (conversationId: UUID, a: {
+            file: FileData;
             filename: string;
-            content_type: string;
-            data: BodyInit;
+            content_type?: string;
             custom_metadata?: Record<string, unknown>;
-        }) => Promise<ConversationDocument>;
+        }) => Promise<Attachment>;
         list: (conversationId: UUID, q?: {
             limit?: number;
             cursor?: string;
-        }) => Promise<Page<ConversationDocument>>;
-        get: (conversationId: UUID, docId: UUID) => Promise<ConversationDocument>;
+        }) => Promise<Page<Attachment>>;
+        get: (conversationId: UUID, docId: UUID) => Promise<Attachment>;
         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>;
@@ -419,17 +376,8 @@ export declare class KnowledgeCoreClient extends HttpBase {
         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>>;
@@ -454,15 +402,12 @@ export declare class AdminClient extends HttpBase {
         listApiKeys: (tenantId: UUID, q?: {
             limit?: number;
             cursor?: string;
-        }) => Promise<Page<ApiKeyInfo>>;
+        }) => Promise<Page<ApiKey>>;
         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;
@@ -470,7 +415,7 @@ export declare class AdminClient extends HttpBase {
             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>;
+        update: (id: UUID, b: Partial<Omit<Agent, "id">>) => Promise<Agent>;
         delete: (id: UUID) => Promise<void>;
     };
 }

package/dist/index.js

@@ -1,15 +1,16 @@
 /**
  * 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.
+ * Portable: uses the global `fetch`, `FormData`, `Blob` + `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.
+ * Auth: every call carries an X-API-Key. Use KnowledgeCoreClient 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
@@ -63,6 +64,7 @@ class HttpBase {
             body = JSON.stringify(opts.json);
         }
         else if (opts.body !== undefined) {
+            // FormData sets its own multipart content-type (with boundary) on fetch.
             body = opts.body;
         }
         let signal = opts.signal;
@@ -110,6 +112,11 @@ function safeJson(t) {
         return t;
     }
 }
+function toBlob(data, contentType) {
+    if (data instanceof Blob)
+        return data;
+    return new Blob([data], { type: contentType ?? "application/octet-stream" });
+}
 // ---------------------------------------------------------------------------
 // Tenant client (data ops) — use a TENANT key
 // ---------------------------------------------------------------------------
@@ -157,21 +164,44 @@ export class KnowledgeCoreClient extends HttpBase {
         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 }),
+        /** Count documents in the corpus: { total, indexed, in_flight, failed }. */
+        countDocuments: (id) => this.request("GET", `/v1/corpora/${id}/documents/count`),
+        /** Upload a file and ingest it ASYNCHRONOUSLY — resolves with the created
+         *  document at status `pending` (HTTP 202); track via documents.get() polling
+         *  the status to `indexed`/`failed`, or the tenant result webhook. */
+        ingestDocument: (id, a) => {
+            const fd = new FormData();
+            fd.append("file", toBlob(a.file, a.content_type), a.filename);
+            if (a.custom_metadata)
+                fd.append("custom_metadata", JSON.stringify(a.custom_metadata));
+            if (a.visibility)
+                fd.append("visibility", a.visibility);
+            if (a.folder_id)
+                fd.append("folder_id", a.folder_id);
+            return this.request("POST", `/v1/corpora/${id}/documents`, { body: fd });
+        },
     };
+    // --- parsing (utility: file -> text, stores nothing) ---
+    parse(a) {
+        const fd = new FormData();
+        fd.append("file", toBlob(a.file, a.content_type), a.filename ?? "document");
+        return this.request("POST", "/v1/documents/parse", { body: fd });
+    }
     // --- 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 }),
+        /** Count documents in the folder: { total, indexed, in_flight, failed }. */
+        countDocuments: (folderId) => this.request("GET", `/v1/folders/${folderId}/documents/count`),
     };
     // --- 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 } }),
+        getCustomMetadata: (id) => this.request("GET", `/v1/documents/${id}/custom_metadata`),
+        /** Merge custom_metadata (a null value deletes a key). Returns the merged object. */
+        patchCustomMetadata: (id, custom_metadata) => this.request("PATCH", `/v1/documents/${id}/custom_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}`),
@@ -189,27 +219,18 @@ export class KnowledgeCoreClient extends HttpBase {
     };
     // --- 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 },
-        }),
+        /** Upload + attach a file and parse it SYNCHRONOUSLY — resolves with status=ready. */
+        upload: (conversationId, a) => {
+            const fd = new FormData();
+            fd.append("file", toBlob(a.file, a.content_type), a.filename);
+            if (a.custom_metadata)
+                fd.append("custom_metadata", JSON.stringify(a.custom_metadata));
+            return this.request("POST", `/v1/conversations/${conversationId}/documents`, { body: fd });
+        },
         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 = {
@@ -221,11 +242,6 @@ export class KnowledgeCoreClient extends HttpBase {
         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 }),
@@ -248,8 +264,8 @@ export class AdminClient extends HttpBase {
         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 are query agents, global for now.
     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}`),
@@ -292,6 +308,3 @@ function dispatchSse(frame, h) {
             break;
     }
 }
-function sleep(ms) {
-    return new Promise((r) => setTimeout(r, ms));
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps).",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -1,19 +1,20 @@
 /**
  * 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.
+ * Portable: uses the global `fetch`, `FormData`, `Blob` + `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.
+ * Auth: every call carries an X-API-Key. Use KnowledgeCoreClient 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)
+// Shared types (mirror the API objects)
 // ---------------------------------------------------------------------------
 export type UUID = string;
 
@@ -25,6 +26,9 @@ export interface Page<T> {
 export type Visibility = "downloadable" | "viewable" | "attributable" | "hidden";
 export type FilterOp = "eq" | "ne" | "in" | "nin" | "gt" | "gte" | "lt" | "lte" | "exists";
 
+/** Raw file input accepted by upload/parse helpers. */
+export type FileData = Blob | Uint8Array | ArrayBuffer;
+
 export interface FilterClause {
   field: string;
   op: FilterOp;
@@ -93,53 +97,45 @@ export interface Groundedness {
 
 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;
 }
+/** Document tally for a corpus or folder. `indexed` = searchable; `in_flight` =
+ *  pending + ingesting (still processing); `failed` = terminal; `total` = all. */
+export interface DocumentCount {
+  total: number;
+  indexed: number;
+  in_flight: number;
+  failed: number;
+}
 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;
@@ -151,55 +147,33 @@ export interface Message {
   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 {
+export interface Attachment {
   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;
@@ -211,25 +185,18 @@ export interface Tenant {
   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 {
+export interface ApiKey {
   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;
+  revoked: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -260,7 +227,8 @@ export class KnowledgeCoreError extends Error {
 export interface ClientOptions {
   baseUrl: string;
   apiKey: string;
-  /** Optional default fetch timeout (ms). Streaming ignores this. */
+  /** Optional default fetch timeout (ms). Streaming ignores this. Note:
+   *  synchronous ingest can take a while — set this generously or omit. */
   timeoutMs?: number;
   fetch?: typeof fetch; // override for tests
 }
@@ -268,7 +236,7 @@ export interface ClientOptions {
 interface RequestOpts {
   query?: Record<string, string | number | boolean | undefined>;
   json?: unknown;
-  body?: BodyInit; // raw body (attachment upload)
+  body?: BodyInit; // raw body / multipart FormData (file uploads)
   headers?: Record<string, string>;
   signal?: AbortSignal;
 }
@@ -303,6 +271,7 @@ class HttpBase {
       headers["content-type"] = "application/json";
       body = JSON.stringify(opts.json);
     } else if (opts.body !== undefined) {
+      // FormData sets its own multipart content-type (with boundary) on fetch.
       body = opts.body;
     }
     let signal = opts.signal;
@@ -350,6 +319,11 @@ function safeJson(t: string): unknown {
   }
 }
 
+function toBlob(data: FileData, contentType?: string): Blob {
+  if (data instanceof Blob) return data;
+  return new Blob([data as BlobPart], { type: contentType ?? "application/octet-stream" });
+}
+
 // ---------------------------------------------------------------------------
 // SSE handlers
 // ---------------------------------------------------------------------------
@@ -404,23 +378,40 @@ export class KnowledgeCoreClient extends HttpBase {
 
   // --- corpora ---
   corpora = {
-    create: (b: { name: string; embedding_model: string; description?: string; external_ref?: string }) =>
+    create: (b: { name: string; description?: 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 }) =>
+    update: (id: UUID, b: { name?: string; description?: 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 }),
+    /** Count documents in the corpus: { total, indexed, in_flight, failed }. */
+    countDocuments: (id: UUID) =>
+      this.request<DocumentCount>("GET", `/v1/corpora/${id}/documents/count`),
+    /** Upload a file and ingest it ASYNCHRONOUSLY — resolves with the created
+     *  document at status `pending` (HTTP 202); track via documents.get() polling
+     *  the status to `indexed`/`failed`, or the tenant result webhook. */
+    ingestDocument: (id: UUID, a: { file: FileData; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown> }) => {
+      const fd = new FormData();
+      fd.append("file", toBlob(a.file, a.content_type), a.filename);
+      if (a.custom_metadata) fd.append("custom_metadata", JSON.stringify(a.custom_metadata));
+      if (a.visibility) fd.append("visibility", a.visibility);
+      if (a.folder_id) fd.append("folder_id", a.folder_id);
+      return this.request<Document>("POST", `/v1/corpora/${id}/documents`, { body: fd });
+    },
   };
 
+  // --- parsing (utility: file -> text, stores nothing) ---
+  parse(a: { file: FileData; filename?: string; content_type?: string }): Promise<{ text: string }> {
+    const fd = new FormData();
+    fd.append("file", toBlob(a.file, a.content_type), a.filename ?? "document");
+    return this.request<{ text: string }>("POST", "/v1/documents/parse", { body: fd });
+  }
+
   // --- folders ---
   folders = {
     create: (corpusId: UUID, name: string) => this.request<Folder>("POST", `/v1/corpora/${corpusId}/folders`, { json: { name } }),
@@ -428,14 +419,18 @@ export class KnowledgeCoreClient extends HttpBase {
     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 }),
+    /** Count documents in the folder: { total, indexed, in_flight, failed }. */
+    countDocuments: (folderId: UUID) =>
+      this.request<DocumentCount>("GET", `/v1/folders/${folderId}/documents/count`),
   };
 
   // --- 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 } }),
+    getCustomMetadata: (id: UUID) => this.request<Record<string, unknown>>("GET", `/v1/documents/${id}/custom_metadata`),
+    /** Merge custom_metadata (a null value deletes a key). Returns the merged object. */
+    patchCustomMetadata: (id: UUID, custom_metadata: Record<string, unknown>) =>
+      this.request<Record<string, unknown>>("PATCH", `/v1/documents/${id}/custom_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 } }),
@@ -460,29 +455,19 @@ export class KnowledgeCoreClient extends HttpBase {
 
   // --- 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 },
-      }),
+    /** Upload + attach a file and parse it SYNCHRONOUSLY — resolves with status=ready. */
+    upload: (conversationId: UUID, a: { file: FileData; filename: string; content_type?: string; custom_metadata?: Record<string, unknown> }) => {
+      const fd = new FormData();
+      fd.append("file", toBlob(a.file, a.content_type), a.filename);
+      if (a.custom_metadata) fd.append("custom_metadata", JSON.stringify(a.custom_metadata));
+      return this.request<Attachment>("POST", `/v1/conversations/${conversationId}/documents`, { body: fd });
+    },
     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}`),
+      this.request<Page<Attachment>>("GET", `/v1/conversations/${conversationId}/documents`, { query: q }),
+    get: (conversationId: UUID, docId: UUID) => this.request<Attachment>("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 ---
@@ -498,15 +483,9 @@ export class KnowledgeCoreClient extends HttpBase {
     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 }),
+    list: (q?: { 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}`),
   };
@@ -524,15 +503,15 @@ export class AdminClient extends HttpBase {
     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 }),
+    listApiKeys: (tenantId: UUID, q?: { limit?: number; cursor?: string }) => this.request<Page<ApiKey>>("GET", `/v1/tenants/${tenantId}/api-keys`, { query: q }),
     revokeApiKey: (tenantId: UUID, keyId: UUID) => this.request<void>("DELETE", `/v1/tenants/${tenantId}/api-keys/${keyId}`),
   };
 
+  // Agents are query agents, global for now.
   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 }) =>
+    create: (b: { name: string; 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">>) =>
+    update: (id: UUID, b: Partial<Omit<Agent, "id">>) =>
       this.request<Agent>("PATCH", `/v1/agents/${id}`, { json: b }),
     delete: (id: UUID) => this.request<void>("DELETE", `/v1/agents/${id}`),
   };
@@ -560,7 +539,3 @@ function dispatchSse(frame: string, h: StreamHandlers): void {
     case "done": h.onDone?.(); break;
   }
 }
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((r) => setTimeout(r, ms));
-}