@babav/knowledge-core-client 0.23.3 → 0.25.0

package/dist/index.d.ts

@@ -224,6 +224,94 @@ export interface BatchUploadUrls {
     }>;
     expires_in: number;
 }
+/** One RESUMABLE GCS upload session (corpora.createUploadSessions). Hand `upload_url` to the
+ *  browser: it PUTs bytes straight to GCS there, needing NO KC/tenant credential (the URI is the
+ *  per-object write capability). Resumable → a dropped connection resumes, not restarts. */
+export interface UploadSession {
+    filename: string;
+    document_id: UUID;
+    upload_url: string;
+    gcs_uri: string;
+    method: "PUT";
+    headers: Record<string, string>;
+    expires_at: string;
+}
+/** Per-item result of corpora.finalizeUploads (idempotent registration). */
+export interface FinalizeResult {
+    document_id: UUID;
+    status: "ingesting" | "failed";
+    error?: string;
+}
+export type AnalyticsBand = "frequent" | "occasional" | "rare" | "never" | "insufficient_data";
+export interface UsageSeries {
+    corpus_id: UUID;
+    granularity: string;
+    points: Array<{
+        bucket: string;
+        queries: number;
+    }>;
+}
+export interface DocumentAnalytics {
+    document_id: UUID;
+    filename: string | null;
+    chunks_retrieved: number;
+    chunks_reranked: number;
+    citation_count: number;
+    best_rerank_rank: number | null;
+    best_rerank_score: number | null;
+    exposure_queries: number;
+    retrieved_reach: number;
+    citation_reach: number;
+    conversion: number;
+    band: AnalyticsBand;
+}
+export interface SectionAnalytics {
+    parent_id: UUID;
+    ordinal: number;
+    chunks_retrieved: number;
+    chunks_reranked: number;
+    citation_count: number;
+    best_rerank_score: number | null;
+    band: AnalyticsBand;
+}
+export interface SectionsResponse {
+    document_id: UUID;
+    sections: SectionAnalytics[];
+}
+export interface MonthlyCorpus {
+    corpus_id: UUID;
+    yyyy_mm: string;
+    queries: number;
+    documents_retrieved: number;
+    chunks_retrieved: number;
+    citations: number;
+    revenue_share: number;
+}
+export interface CorpusMonthSlice {
+    corpus_id: UUID;
+    queries: number;
+    documents_retrieved: number;
+    chunks_retrieved: number;
+    citations: number;
+    revenue_share: number;
+}
+export interface MonthTotals {
+    yyyy_mm: string;
+    queries: number;
+    documents_retrieved: number;
+    chunks_retrieved: number;
+    citations: number;
+    unattributed_share: number;
+    corpora: CorpusMonthSlice[];
+}
+export interface RetrievalEventRow {
+    id: UUID;
+    created_at: string;
+    corpus_ids: UUID[];
+    pool_size: number;
+    message_id: UUID | null;
+    documents: Array<Record<string, unknown>>;
+}
 export interface Conversation {
     id: UUID;
     title: string | null;
@@ -498,6 +586,43 @@ export declare class KnowledgeCoreClient extends HttpBase {
             custom_metadata?: Record<string, unknown>;
             concurrency?: number;
         }) => Promise<Document[]>;
+        /** (server-side) Mint one RESUMABLE GCS upload session per file. Return only the sessions to the
+         *  browser; the browser PUTs bytes to each `upload_url` and needs NO KC/tenant credential (the
+         *  session URI IS the per-object write capability). `origin` = the browser app origin (scopes the
+         *  session; the bucket CORS must allow PUT/POST from it). */
+        createUploadSessions: (id: UUID, files: Array<{
+            filename: string;
+            content_type?: string;
+            size?: number;
+        }>, opts?: {
+            origin?: string;
+        }) => Promise<{
+            items: UploadSession[];
+        }>;
+        /** (server-side) Register documents whose bytes the browser already PUT to GCS. IDEMPOTENT +
+         *  PER-ITEM — safe to retry; each result is { document_id, status: 'ingesting' | 'failed' }. Call
+         *  after the browser reports its PUTs done. folder_id/visibility/custom_metadata apply to all
+         *  items. `document_id` is stable from createUploadSessions, so documents.events (SSE) tracks it. */
+        finalizeUploads: (id: UUID, items: Array<{
+            document_id: UUID;
+            filename: string;
+            content_type?: string;
+        }>, opts?: {
+            folder_id?: UUID;
+            visibility?: Visibility;
+            custom_metadata?: Record<string, unknown>;
+        }) => Promise<{
+            results: FinalizeResult[];
+        }>;
+        /** (server-side) Cancel upload sessions the browser gave up on (idempotent cleanup). Pass the
+         *  `upload_url` from createUploadSessions so the resumable session is dropped; any pending row is
+         *  removed too. Safe to call repeatedly. */
+        abortUploadSessions: (id: UUID, items: Array<{
+            document_id: UUID;
+            upload_url?: string;
+        }>) => Promise<{
+            aborted: UUID[];
+        }>;
     };
     parse(a: {
         file: FileData;
@@ -630,6 +755,48 @@ export declare class KnowledgeCoreClient extends HttpBase {
         listAll: () => Promise<Agent[]>;
         get: (id: UUID) => Promise<Agent>;
     };
+    analytics: {
+        /** Query-volume time series for a corpus (the denominator for everything). */
+        corpusUsage: (corpusId: UUID, q?: {
+            from?: string;
+            to?: string;
+            granularity?: "day" | "week" | "month";
+        }) => Promise<UsageSeries>;
+        /** Per-document analytics for a corpus (feeds the document list + the quadrant scatter). */
+        corpusDocuments: (corpusId: UUID, q?: {
+            sort?: "citations" | "reranked" | "retrieved" | "best_score";
+            limit?: number;
+            cursor?: string;
+            from?: string;
+            to?: string;
+        }) => Promise<{
+            items: DocumentAnalytics[];
+            next_cursor: string | null;
+        }>;
+        /** One document's lifetime rollup (headline reach is CITATION reach). */
+        document: (documentId: UUID) => Promise<DocumentAnalytics>;
+        /** Parent-section grain for a document (never exposes chunk ids). */
+        documentSections: (documentId: UUID) => Promise<SectionsResponse>;
+        /** 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). */
+        month: (yyyyMm: string) => Promise<MonthTotals>;
+        /** Raw immutable events + document rollups (escape hatch for custom formulas). */
+        events: (q?: {
+            from?: string;
+            to?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<{
+            items: RetrievalEventRow[];
+            next_cursor: string | null;
+        }>;
+        /** Flush pending events into the read tables NOW (idempotent; read-your-writes). The Cloud
+         *  Scheduler drain is the authoritative periodic driver — this is a convenience trigger. */
+        drain: () => Promise<{
+            processed: number;
+        }>;
+    };
 }
 export declare class AdminClient extends HttpBase {
     /** @param opts.apiKey the ADMIN key, supplied by the caller. */

package/dist/index.js

@@ -283,6 +283,33 @@ export class KnowledgeCoreClient extends HttpBase {
                 } });
             return res.documents;
         },
+        // --- browser direct-to-GCS uploads (ANY size; the browser NEVER needs an API key) ---
+        // Split flow so the browser uploads bytes ITSELF while the tenant key stays server-side:
+        //   1. (server) createUploadSessions -> returns a resumable GCS session URI per file
+        //   2. (browser) PUT the bytes straight to each session URI (resumable; no credential)
+        //   3. (server) finalizeUploads -> register + enqueue; or abortUploadSessions to cancel
+        // Use this instead of uploadMany when bytes must not pass through your worker (browser -> GCS
+        // direct), e.g. multi-GB files or a browser that can't hold the tenant key.
+        /** (server-side) Mint one RESUMABLE GCS upload session per file. Return only the sessions to the
+         *  browser; the browser PUTs bytes to each `upload_url` and needs NO KC/tenant credential (the
+         *  session URI IS the per-object write capability). `origin` = the browser app origin (scopes the
+         *  session; the bucket CORS must allow PUT/POST from it). */
+        createUploadSessions: (id, files, opts) => this.request("POST", `/v1/corpora/${id}/documents/upload-sessions`, { json: {
+                items: files.map((f) => ({ filename: f.filename, content_type: f.content_type })),
+                origin: opts?.origin,
+            } }),
+        /** (server-side) Register documents whose bytes the browser already PUT to GCS. IDEMPOTENT +
+         *  PER-ITEM — safe to retry; each result is { document_id, status: 'ingesting' | 'failed' }. Call
+         *  after the browser reports its PUTs done. folder_id/visibility/custom_metadata apply to all
+         *  items. `document_id` is stable from createUploadSessions, so documents.events (SSE) tracks it. */
+        finalizeUploads: (id, items, opts) => this.request("POST", `/v1/corpora/${id}/documents/finalize`, { json: {
+                items, folder_id: opts?.folder_id, visibility: opts?.visibility,
+                custom_metadata: opts?.custom_metadata,
+            } }),
+        /** (server-side) Cancel upload sessions the browser gave up on (idempotent cleanup). Pass the
+         *  `upload_url` from createUploadSessions so the resumable session is dropped; any pending row is
+         *  removed too. Safe to call repeatedly. */
+        abortUploadSessions: (id, items) => this.request("POST", `/v1/corpora/${id}/documents/abort-uploads`, { json: { items } }),
     };
     // --- parsing (utility: file -> text, stores nothing) ---
     parse(a) {
@@ -383,6 +410,26 @@ export class KnowledgeCoreClient extends HttpBase {
         listAll: () => this.pageAll("/v1/agents"),
         get: (id) => this.request("GET", `/v1/agents/${id}`),
     };
+    // --- retrieval analytics (read-only, tenant-scoped, aggregate-on-read) ---
+    analytics = {
+        /** Query-volume time series for a corpus (the denominator for everything). */
+        corpusUsage: (corpusId, q) => this.request("GET", `/v1/analytics/corpora/${corpusId}/usage`, { query: q }),
+        /** Per-document analytics for a corpus (feeds the document list + the quadrant scatter). */
+        corpusDocuments: (corpusId, q) => this.request("GET", `/v1/analytics/corpora/${corpusId}/documents`, { query: q }),
+        /** One document's lifetime rollup (headline reach is CITATION reach). */
+        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`),
+        /** 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). */
+        month: (yyyyMm) => this.request("GET", `/v1/analytics/months/${yyyyMm}`),
+        /** Raw immutable events + document rollups (escape hatch for custom formulas). */
+        events: (q) => this.request("GET", "/v1/analytics/events", { query: q }),
+        /** Flush pending events into the read tables NOW (idempotent; read-your-writes). The Cloud
+         *  Scheduler drain is the authoritative periodic driver — this is a convenience trigger. */
+        drain: () => this.request("POST", "/v1/analytics/drain"),
+    };
 }
 // ---------------------------------------------------------------------------
 // Admin client (tenant + key + agent management) — use the ADMIN key

package/package.json

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

@@ -240,6 +240,59 @@ export interface BatchUploadUrls {
   items: Array<{ filename: string; document_id: UUID; upload_url: string; gcs_uri: string }>;
   expires_in: number;
 }
+/** One RESUMABLE GCS upload session (corpora.createUploadSessions). Hand `upload_url` to the
+ *  browser: it PUTs bytes straight to GCS there, needing NO KC/tenant credential (the URI is the
+ *  per-object write capability). Resumable → a dropped connection resumes, not restarts. */
+export interface UploadSession {
+  filename: string;
+  document_id: UUID;
+  upload_url: string;
+  gcs_uri: string;
+  method: "PUT";
+  headers: Record<string, string>;
+  expires_at: string;
+}
+/** Per-item result of corpora.finalizeUploads (idempotent registration). */
+export interface FinalizeResult {
+  document_id: UUID;
+  status: "ingesting" | "failed";
+  error?: string;
+}
+// --- retrieval analytics ---
+export type AnalyticsBand = "frequent" | "occasional" | "rare" | "never" | "insufficient_data";
+export interface UsageSeries {
+  corpus_id: UUID;
+  granularity: string;
+  points: Array<{ bucket: string; queries: number }>;
+}
+export interface DocumentAnalytics {
+  document_id: UUID; filename: string | null;
+  chunks_retrieved: number; chunks_reranked: number; citation_count: number;
+  best_rerank_rank: number | null; best_rerank_score: number | null;
+  exposure_queries: number; retrieved_reach: number; citation_reach: number;
+  conversion: number; band: AnalyticsBand;
+}
+export interface SectionAnalytics {
+  parent_id: UUID; ordinal: number; chunks_retrieved: number; chunks_reranked: number;
+  citation_count: number; best_rerank_score: number | null; band: AnalyticsBand;
+}
+export interface SectionsResponse { document_id: UUID; sections: SectionAnalytics[] }
+export interface MonthlyCorpus {
+  corpus_id: UUID; yyyy_mm: string; queries: number; documents_retrieved: number;
+  chunks_retrieved: number; citations: number; revenue_share: number;
+}
+export interface CorpusMonthSlice {
+  corpus_id: UUID; queries: number; documents_retrieved: number;
+  chunks_retrieved: number; citations: number; revenue_share: number;
+}
+export interface MonthTotals {
+  yyyy_mm: string; queries: number; documents_retrieved: number; chunks_retrieved: number;
+  citations: number; unattributed_share: number; corpora: CorpusMonthSlice[];
+}
+export interface RetrievalEventRow {
+  id: UUID; created_at: string; corpus_ids: UUID[]; pool_size: number;
+  message_id: UUID | null; documents: Array<Record<string, unknown>>;
+}
 export interface Conversation {
   id: UUID;
   title: string | null;
@@ -669,6 +722,58 @@ export class KnowledgeCoreClient extends HttpBase {
       );
       return res.documents;
     },
+
+    // --- browser direct-to-GCS uploads (ANY size; the browser NEVER needs an API key) ---
+    // Split flow so the browser uploads bytes ITSELF while the tenant key stays server-side:
+    //   1. (server) createUploadSessions -> returns a resumable GCS session URI per file
+    //   2. (browser) PUT the bytes straight to each session URI (resumable; no credential)
+    //   3. (server) finalizeUploads -> register + enqueue; or abortUploadSessions to cancel
+    // Use this instead of uploadMany when bytes must not pass through your worker (browser -> GCS
+    // direct), e.g. multi-GB files or a browser that can't hold the tenant key.
+
+    /** (server-side) Mint one RESUMABLE GCS upload session per file. Return only the sessions to the
+     *  browser; the browser PUTs bytes to each `upload_url` and needs NO KC/tenant credential (the
+     *  session URI IS the per-object write capability). `origin` = the browser app origin (scopes the
+     *  session; the bucket CORS must allow PUT/POST from it). */
+    createUploadSessions: (
+      id: UUID,
+      files: Array<{ filename: string; content_type?: string; size?: number }>,
+      opts?: { origin?: string },
+    ): Promise<{ items: UploadSession[] }> =>
+      this.request<{ items: UploadSession[] }>(
+        "POST", `/v1/corpora/${id}/documents/upload-sessions`,
+        { json: {
+            items: files.map((f) => ({ filename: f.filename, content_type: f.content_type })),
+            origin: opts?.origin,
+        } },
+      ),
+
+    /** (server-side) Register documents whose bytes the browser already PUT to GCS. IDEMPOTENT +
+     *  PER-ITEM — safe to retry; each result is { document_id, status: 'ingesting' | 'failed' }. Call
+     *  after the browser reports its PUTs done. folder_id/visibility/custom_metadata apply to all
+     *  items. `document_id` is stable from createUploadSessions, so documents.events (SSE) tracks it. */
+    finalizeUploads: (
+      id: UUID,
+      items: Array<{ document_id: UUID; filename: string; content_type?: string }>,
+      opts?: { folder_id?: UUID; visibility?: Visibility; custom_metadata?: Record<string, unknown> },
+    ): Promise<{ results: FinalizeResult[] }> =>
+      this.request<{ results: FinalizeResult[] }>(
+        "POST", `/v1/corpora/${id}/documents/finalize`,
+        { json: {
+            items, folder_id: opts?.folder_id, visibility: opts?.visibility,
+            custom_metadata: opts?.custom_metadata,
+        } },
+      ),
+
+    /** (server-side) Cancel upload sessions the browser gave up on (idempotent cleanup). Pass the
+     *  `upload_url` from createUploadSessions so the resumable session is dropped; any pending row is
+     *  removed too. Safe to call repeatedly. */
+    abortUploadSessions: (
+      id: UUID,
+      items: Array<{ document_id: UUID; upload_url?: string }>,
+    ): Promise<{ aborted: UUID[] }> =>
+      this.request<{ aborted: UUID[] }>(
+        "POST", `/v1/corpora/${id}/documents/abort-uploads`, { json: { items } }),
   };
 
   // --- parsing (utility: file -> text, stores nothing) ---
@@ -793,6 +898,30 @@ export class KnowledgeCoreClient extends HttpBase {
     listAll: () => this.pageAll<Agent>("/v1/agents"),
     get: (id: UUID) => this.request<Agent>("GET", `/v1/agents/${id}`),
   };
+
+  // --- retrieval analytics (read-only, tenant-scoped, aggregate-on-read) ---
+  analytics = {
+    /** Query-volume time series for a corpus (the denominator for everything). */
+    corpusUsage: (corpusId: UUID, q?: { from?: string; to?: string; granularity?: "day" | "week" | "month" }) =>
+      this.request<UsageSeries>("GET", `/v1/analytics/corpora/${corpusId}/usage`, { query: q }),
+    /** Per-document analytics for a corpus (feeds the document list + the quadrant scatter). */
+    corpusDocuments: (corpusId: UUID, q?: { sort?: "citations" | "reranked" | "retrieved" | "best_score"; limit?: number; cursor?: string; from?: string; to?: string }) =>
+      this.request<{ items: DocumentAnalytics[]; next_cursor: string | null }>("GET", `/v1/analytics/corpora/${corpusId}/documents`, { query: q }),
+    /** One document's lifetime rollup (headline reach is CITATION reach). */
+    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`),
+    /** 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). */
+    month: (yyyyMm: string) => this.request<MonthTotals>("GET", `/v1/analytics/months/${yyyyMm}`),
+    /** Raw immutable events + document rollups (escape hatch for custom formulas). */
+    events: (q?: { from?: string; to?: string; limit?: number; cursor?: string }) =>
+      this.request<{ items: RetrievalEventRow[]; next_cursor: string | null }>("GET", "/v1/analytics/events", { query: q }),
+    /** Flush pending events into the read tables NOW (idempotent; read-your-writes). The Cloud
+     *  Scheduler drain is the authoritative periodic driver — this is a convenience trigger. */
+    drain: () => this.request<{ processed: number }>("POST", "/v1/analytics/drain"),
+  };
 }
 
 // ---------------------------------------------------------------------------