@babav/knowledge-core-client 0.25.1 → 0.27.0

package/dist/index.d.ts

@@ -90,6 +90,10 @@ export interface QueryRequest {
     filter?: MetadataFilter;
     visual?: VisualRequest;
 }
+/** The spatial arrangement a conceptual visual encodes (the geometry that carries the meaning).
+ * "free" = renderer's judgment / not a declared arrangement (also the value for non-conceptual
+ * registers). */
+export type VisualLayout = "linear-flow" | "ring-cycle" | "nesting" | "radial-hub" | "side-by-side" | "stacked-layers" | "two-state" | "free";
 /** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
  * system as citations). For delivery="svg", `rendered_svg` is set; scenic sets `image`. */
 export interface Visual {
@@ -101,6 +105,8 @@ export interface Visual {
     register: "chart" | "structural" | "conceptual" | "scenic";
     priority: number;
     payload: Record<string, unknown>;
+    /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
+    layout: VisualLayout;
     rendered_svg?: string;
     image?: {
         url: string;
@@ -181,6 +187,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 +208,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 +329,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 +674,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 +688,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 +816,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.27.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

@@ -115,6 +115,19 @@ export interface QueryRequest {
   visual?: VisualRequest;
 }
 
+/** The spatial arrangement a conceptual visual encodes (the geometry that carries the meaning).
+ * "free" = renderer's judgment / not a declared arrangement (also the value for non-conceptual
+ * registers). */
+export type VisualLayout =
+  | "linear-flow"
+  | "ring-cycle"
+  | "nesting"
+  | "radial-hub"
+  | "side-by-side"
+  | "stacked-layers"
+  | "two-state"
+  | "free";
+
 /** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
  * system as citations). For delivery="svg", `rendered_svg` is set; scenic sets `image`. */
 export interface Visual {
@@ -123,6 +136,8 @@ export interface Visual {
   register: "chart" | "structural" | "conceptual" | "scenic";
   priority: number;
   payload: Record<string, unknown>; // {kind: "grammar"|"vega_lite"|"svg"|"image", ...}
+  /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
+  layout: VisualLayout;
   rendered_svg?: string;
   image?: { url: string; expires_at: number; width: number; height: number };
 }
@@ -202,6 +217,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 +238,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 +319,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 +829,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 +845,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 +949,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). */