@babav/knowledge-core-client 0.25.1 → 0.26.0

package/dist/index.d.ts

@@ -181,6 +181,16 @@ export interface Folder {
     corpus_id: UUID;
     name: string;
 }
+export interface Reach {
+    exposure_queries: number;
+    citation_reach: number | null;
+    retrieved_reach: number | null;
+    conversion: number | null;
+    citation_count: number;
+    chunks_reranked: number;
+    best_rerank_score: number | null;
+    band: AnalyticsBand;
+}
 export interface Document {
     id: UUID;
     corpus_id: UUID;
@@ -192,6 +202,7 @@ export interface Document {
     chunk_count: number;
     custom_metadata: Record<string, unknown>;
     error: string | null;
+    reach?: Reach;
 }
 export interface ContentUrl {
     content_url: string;
@@ -312,6 +323,25 @@ export interface RetrievalEventRow {
     message_id: UUID | null;
     documents: Array<Record<string, unknown>>;
 }
+export type Quadrant = "workhorse" | "hidden_gem" | "padding" | "cold" | "insufficient_data";
+export interface ScatterDoc {
+    document_id: UUID;
+    filename: string | null;
+    x_retrieved_reach: number;
+    y_conversion: number;
+    chunk_count: number;
+    citation_count: number;
+    exposure_queries: number;
+    band: AnalyticsBand;
+    quadrant: Quadrant;
+}
+export interface ScatterResponse {
+    corpus_id: UUID;
+    corpus_total_queries: number;
+    generated_at: string;
+    truncated: boolean;
+    documents: ScatterDoc[];
+}
 export interface Conversation {
     id: UUID;
     title: string | null;
@@ -638,6 +668,7 @@ export declare class KnowledgeCoreClient extends HttpBase {
         listDocuments: (folderId: UUID, q?: {
             limit?: number;
             cursor?: string;
+            include?: "reach";
         }) => Promise<Page<Document>>;
         /** Count documents in the folder: { total, indexed, in_flight, failed }. */
         countDocuments: (folderId: UUID) => Promise<DocumentCount>;
@@ -651,7 +682,9 @@ export declare class KnowledgeCoreClient extends HttpBase {
         events: (folderId: UUID, handlers: DocumentEventHandlers, signal?: AbortSignal) => Promise<void>;
     };
     documents: {
-        get: (id: UUID) => Promise<Document>;
+        get: (id: UUID, opts?: {
+            include?: "reach";
+        }) => Promise<Document>;
         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>>;
@@ -777,6 +810,9 @@ export declare class KnowledgeCoreClient extends HttpBase {
         document: (documentId: UUID) => Promise<DocumentAnalytics>;
         /** Parent-section grain for a document (never exposes chunk ids). */
         documentSections: (documentId: UUID) => Promise<SectionsResponse>;
+        /** Whole-corpus scatter payload: every document with x=retrieved_reach, y=conversion,
+         *  bubble=chunk_count, and a server-computed quadrant. No pagination (`truncated` if capped). */
+        corpusScatter: (corpusId: UUID) => Promise<ScatterResponse>;
         /** A corpus's monthly metrics + revenue_share (YYYY-MM). */
         corpusMonthly: (corpusId: UUID, yyyyMm: string) => Promise<MonthlyCorpus>;
         /** Cross-corpus monthly totals + per-corpus breakdown + unattributed share (YYYY-MM). */

package/dist/index.js

@@ -336,7 +336,7 @@ export class KnowledgeCoreClient extends HttpBase {
     };
     // --- documents ---
     documents = {
-        get: (id) => this.request("GET", `/v1/documents/${id}`),
+        get: (id, opts) => this.request("GET", `/v1/documents/${id}`, { query: opts }),
         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 }),
@@ -420,6 +420,9 @@ export class KnowledgeCoreClient extends HttpBase {
         document: (documentId) => this.request("GET", `/v1/analytics/documents/${documentId}`),
         /** Parent-section grain for a document (never exposes chunk ids). */
         documentSections: (documentId) => this.request("GET", `/v1/analytics/documents/${documentId}/sections`),
+        /** Whole-corpus scatter payload: every document with x=retrieved_reach, y=conversion,
+         *  bubble=chunk_count, and a server-computed quadrant. No pagination (`truncated` if capped). */
+        corpusScatter: (corpusId) => this.request("GET", `/v1/analytics/corpora/${corpusId}/scatter`),
         /** A corpus's monthly metrics + revenue_share (YYYY-MM). */
         corpusMonthly: (corpusId, yyyyMm) => this.request("GET", `/v1/analytics/corpora/${corpusId}/monthly/${yyyyMm}`),
         /** Cross-corpus monthly totals + per-corpus breakdown + unattributed share (YYYY-MM). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.25.1",
+  "version": "0.26.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

@@ -202,6 +202,16 @@ export interface Folder {
   corpus_id: UUID;
   name: string;
 }
+export interface Reach {
+  exposure_queries: number;
+  citation_reach: number | null;   // DOCUMENT headline metric
+  retrieved_reach: number | null;
+  conversion: number | null;
+  citation_count: number;
+  chunks_reranked: number;
+  best_rerank_score: number | null;
+  band: AnalyticsBand;
+}
 export interface Document {
   id: UUID;
   corpus_id: UUID;
@@ -213,6 +223,7 @@ export interface Document {
   chunk_count: number;
   custom_metadata: Record<string, unknown>;
   error: string | null;
+  reach?: Reach;   // present only when requested with include=reach
 }
 export interface ContentUrl {
   content_url: string;
@@ -293,6 +304,17 @@ export interface RetrievalEventRow {
   id: UUID; created_at: string; corpus_ids: UUID[]; pool_size: number;
   message_id: UUID | null; documents: Array<Record<string, unknown>>;
 }
+export type Quadrant = "workhorse" | "hidden_gem" | "padding" | "cold" | "insufficient_data";
+export interface ScatterDoc {
+  document_id: UUID; filename: string | null;
+  x_retrieved_reach: number; y_conversion: number;
+  chunk_count: number; citation_count: number; exposure_queries: number;
+  band: AnalyticsBand; quadrant: Quadrant;
+}
+export interface ScatterResponse {
+  corpus_id: UUID; corpus_total_queries: number; generated_at: string;
+  truncated: boolean; documents: ScatterDoc[];
+}
 export interface Conversation {
   id: UUID;
   title: string | null;
@@ -792,7 +814,7 @@ export class KnowledgeCoreClient extends HttpBase {
     // folder cannot be deleted either way.
     delete: (folderId: UUID, confirmName?: string) =>
       this.request<void>("DELETE", `/v1/folders/${folderId}`, confirmName ? { query: { confirm: confirmName } } : undefined),
-    listDocuments: (folderId: UUID, q?: { limit?: number; cursor?: string }) =>
+    listDocuments: (folderId: UUID, q?: { limit?: number; cursor?: string; include?: "reach" }) =>
       this.request<Page<Document>>("GET", `/v1/folders/${folderId}/documents`, { query: q }),
     /** Count documents in the folder: { total, indexed, in_flight, failed }. */
     countDocuments: (folderId: UUID) =>
@@ -808,7 +830,8 @@ export class KnowledgeCoreClient extends HttpBase {
 
   // --- documents ---
   documents = {
-    get: (id: UUID) => this.request<Document>("GET", `/v1/documents/${id}`),
+    get: (id: UUID, opts?: { include?: "reach" }) =>
+      this.request<Document>("GET", `/v1/documents/${id}`, { query: opts }),
     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>) =>
@@ -911,6 +934,9 @@ export class KnowledgeCoreClient extends HttpBase {
     document: (documentId: UUID) => this.request<DocumentAnalytics>("GET", `/v1/analytics/documents/${documentId}`),
     /** Parent-section grain for a document (never exposes chunk ids). */
     documentSections: (documentId: UUID) => this.request<SectionsResponse>("GET", `/v1/analytics/documents/${documentId}/sections`),
+    /** Whole-corpus scatter payload: every document with x=retrieved_reach, y=conversion,
+     *  bubble=chunk_count, and a server-computed quadrant. No pagination (`truncated` if capped). */
+    corpusScatter: (corpusId: UUID) => this.request<ScatterResponse>("GET", `/v1/analytics/corpora/${corpusId}/scatter`),
     /** A corpus's monthly metrics + revenue_share (YYYY-MM). */
     corpusMonthly: (corpusId: UUID, yyyyMm: string) => this.request<MonthlyCorpus>("GET", `/v1/analytics/corpora/${corpusId}/monthly/${yyyyMm}`),
     /** Cross-corpus monthly totals + per-corpus breakdown + unattributed share (YYYY-MM). */