@babav/knowledge-core-client 0.37.0 → 0.38.0

package/dist/index.d.ts

@@ -325,6 +325,36 @@ export interface SectionsResponse {
     document_id: UUID;
     sections: SectionAnalytics[];
 }
+/** One chunk's retrieval heat + where it sits in the document's view-PDF. `regions` are
+ * view-PDF points (origin bottom-left), possibly spanning pages; `method`/`regions` null (or
+ * method "unaligned") => no box to draw (heat still shown). retrieved=0 => never-retrieved. */
+export interface ChunkHeat {
+    chunk_id: string;
+    seq: number;
+    parent_id: UUID | null;
+    retrieved: number;
+    reranked: number;
+    citation_count: number;
+    best_rerank_rank: number | null;
+    best_rerank_score: number | null;
+    method: string | null;
+    regions: {
+        page: number;
+        bbox: [number, number, number, number];
+    }[] | null;
+}
+/** Everything to overlay retrieval heat on the original document: a signed view-PDF URL
+ * (render with pdf.js), its per-page geometry, and every chunk's heat + boxes. */
+export interface ChunkHeatmapResponse {
+    document_id: UUID;
+    view_pdf_url: string | null;
+    page_dims: {
+        w: number;
+        h: number;
+        rotation: number;
+    }[] | null;
+    chunks: ChunkHeat[];
+}
 export interface MonthlyCorpus {
     corpus_id: UUID;
     yyyy_mm: string;
@@ -933,6 +963,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>;
+        /** Per-chunk retrieval heat + position in the document's view-PDF, plus a signed
+         * view-PDF URL — everything to overlay heat on the ORIGINAL document with pdf.js. */
+        documentChunks: (documentId: UUID) => Promise<ChunkHeatmapResponse>;
         /** 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>;

package/dist/index.js

@@ -468,6 +468,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`),
+        /** Per-chunk retrieval heat + position in the document's view-PDF, plus a signed
+         * view-PDF URL — everything to overlay heat on the ORIGINAL document with pdf.js. */
+        documentChunks: (documentId) => this.request("GET", `/v1/analytics/documents/${documentId}/chunks`),
         /** 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`),

package/package.json

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

@@ -336,6 +336,24 @@ export interface SectionAnalytics {
   citation_count: number; best_rerank_score: number | null; band: AnalyticsBand;
 }
 export interface SectionsResponse { document_id: UUID; sections: SectionAnalytics[] }
+/** One chunk's retrieval heat + where it sits in the document's view-PDF. `regions` are
+ * view-PDF points (origin bottom-left), possibly spanning pages; `method`/`regions` null (or
+ * method "unaligned") => no box to draw (heat still shown). retrieved=0 => never-retrieved. */
+export interface ChunkHeat {
+  chunk_id: string; seq: number; parent_id: UUID | null;
+  retrieved: number; reranked: number; citation_count: number;
+  best_rerank_rank: number | null; best_rerank_score: number | null;
+  method: string | null;
+  regions: { page: number; bbox: [number, number, number, number] }[] | null;
+}
+/** Everything to overlay retrieval heat on the original document: a signed view-PDF URL
+ * (render with pdf.js), its per-page geometry, and every chunk's heat + boxes. */
+export interface ChunkHeatmapResponse {
+  document_id: UUID;
+  view_pdf_url: string | null;
+  page_dims: { w: number; h: number; rotation: number }[] | null;
+  chunks: ChunkHeat[];
+}
 export interface MonthlyCorpus {
   corpus_id: UUID; yyyy_mm: string; queries: number; documents_retrieved: number;
   chunks_retrieved: number; citations: number; revenue_share: number;
@@ -1070,6 +1088,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`),
+    /** Per-chunk retrieval heat + position in the document's view-PDF, plus a signed
+     * view-PDF URL — everything to overlay heat on the ORIGINAL document with pdf.js. */
+    documentChunks: (documentId: UUID) => this.request<ChunkHeatmapResponse>("GET", `/v1/analytics/documents/${documentId}/chunks`),
     /** 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`),