@babav/knowledge-core-client 0.27.0 → 0.29.0

package/dist/index.d.ts

@@ -181,6 +181,7 @@ export interface Corpus {
     id: UUID;
     name: string;
     description: string | null;
+    custom_metadata: Record<string, unknown>;
 }
 export interface Folder {
     id: UUID;
@@ -468,8 +469,12 @@ declare class HttpBase {
     protected pageAll<T>(path: string, query?: RequestOpts["query"]): Promise<T[]>;
 }
 export interface StreamHandlers {
+    /** Retrieval milestone. `retrieval_contents` is the reranked top_k (unchanged).
+     *  `retrieved_count` is the total distinct candidate chunks fetched across ALL corpora
+     *  (and sub-queries) BEFORE reranking/truncation — i.e. the recall-net size. */
     onSources?: (d: {
         retrieval_contents: RetrievalContent[];
+        retrieved_count: number;
     }) => void;
     onToken?: (text: string) => void;
     /** A citation, emitted inline as the answer streams (Claude/native path). Also
@@ -545,16 +550,25 @@ export declare class KnowledgeCoreClient extends HttpBase {
         create: (b: {
             name: string;
             description?: string;
+            custom_metadata?: Record<string, unknown>;
         }) => Promise<Corpus>;
         list: (q?: {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<Corpus>>;
         listAll: () => Promise<Corpus[]>;
+        /** Filter corpora by custom_metadata using the same metadata filter as documents. */
+        search: (b: {
+            filter?: MetadataFilter;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Corpus>>;
         get: (id: UUID) => Promise<Corpus>;
+        /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). */
         update: (id: UUID, b: {
             name?: string;
             description?: string;
+            custom_metadata?: Record<string, unknown>;
         }) => Promise<Corpus>;
         delete: (id: UUID, confirmName: string) => Promise<void>;
         listFolders: (id: UUID) => Promise<Folder[]>;

package/dist/index.js

@@ -219,7 +219,10 @@ export class KnowledgeCoreClient extends HttpBase {
         create: (b) => this.request("POST", "/v1/corpora", { json: b }),
         list: (q) => this.request("GET", "/v1/corpora", { query: q }),
         listAll: () => this.pageAll("/v1/corpora"),
+        /** Filter corpora by custom_metadata using the same metadata filter as documents. */
+        search: (b) => this.request("POST", "/v1/corpora/search", { json: b }),
         get: (id) => this.request("GET", `/v1/corpora/${id}`),
+        /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). */
         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`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps). Includes the babav.visual grammar TYPES at the ./visual subpath (types only; all visual rendering is server-side).",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -211,6 +211,7 @@ export interface Corpus {
   id: UUID;
   name: string;
   description: string | null;
+  custom_metadata: Record<string, unknown>;
 }
 export interface Folder {
   id: UUID;
@@ -551,7 +552,10 @@ const MULTIPART_MAX_BYTES = 30 * 1024 * 1024;
 // SSE handlers
 // ---------------------------------------------------------------------------
 export interface StreamHandlers {
-  onSources?: (d: { retrieval_contents: RetrievalContent[] }) => void;
+  /** Retrieval milestone. `retrieval_contents` is the reranked top_k (unchanged).
+   *  `retrieved_count` is the total distinct candidate chunks fetched across ALL corpora
+   *  (and sub-queries) BEFORE reranking/truncation — i.e. the recall-net size. */
+  onSources?: (d: { retrieval_contents: RetrievalContent[]; retrieved_count: number }) => void;
   onToken?: (text: string) => void;
   /** A citation, emitted inline as the answer streams (Claude/native path). Also
    *  present aggregated in the `final` event. */
@@ -676,12 +680,16 @@ export class KnowledgeCoreClient extends HttpBase {
 
   // --- corpora ---
   corpora = {
-    create: (b: { name: string; description?: string }) =>
+    create: (b: { name: string; description?: string; custom_metadata?: Record<string, unknown> }) =>
       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"),
+    /** Filter corpora by custom_metadata using the same metadata filter as documents. */
+    search: (b: { filter?: MetadataFilter; limit?: number; cursor?: string }) =>
+      this.request<Page<Corpus>>("POST", "/v1/corpora/search", { json: b }),
     get: (id: UUID) => this.request<Corpus>("GET", `/v1/corpora/${id}`),
-    update: (id: UUID, b: { name?: string; description?: string }) =>
+    /** `custom_metadata` merges (provided keys upsert, a null value deletes a key). */
+    update: (id: UUID, b: { name?: string; description?: string; custom_metadata?: Record<string, unknown> }) =>
       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`),