@babav/knowledge-core-client 0.31.0 → 0.32.0

package/dist/index.d.ts

@@ -97,13 +97,11 @@ export type VisualLayout = "linear-flow" | "ring-cycle" | "nesting" | "radial-hu
 /** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
  * system as citations).
  *
- * UNIFORM DELIVERY: every register (chart / structural / conceptual / scenic) carries `image` — a
- * PNG served BY KC. To display it, GET `image.url` (resolve a relative path against your KC base
- * URL) with your normal API key; the response body is the PNG bytes. The URL is a stable, non-
- * expiring KC endpoint for persisted/conversational visuals (`expires_at` absent), so it works on
- * reload/copy/export and on later conversation retrieval — the client never fetches GCS and never
- * parses inline SVG. `rendered_svg` appears ONLY as a rare fail-soft fallback (server rasterization
- * failed); prefer `image` and treat `rendered_svg` as a last resort. */
+ * IDs-ONLY: the API never returns a URL. Every visual (chart / structural / conceptual / scenic) is
+ * a PNG served by KC and identified by its `id`. To display it, fetch the bytes by id:
+ * `getVisualImage(visual.id)` (or GET /v1/visuals/{id}/image with your API key). `image` carries only
+ * the pixel DIMENSIONS, for layout. The image is authenticated + tenant-scoped exactly like every
+ * other KC call; there is no URL, no signed GCS link, and nothing to expire. */
 export interface Visual {
     id: string;
     anchor: {
@@ -115,15 +113,11 @@ export interface Visual {
     payload: Record<string, unknown>;
     /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
     layout: VisualLayout;
-    /** PRIMARY: GET this (relative to your KC base, with your API key) -> PNG bytes. */
+    /** Pixel dimensions of the PNG (for layout). Fetch the bytes with getVisualImage(id). */
     image?: {
-        url: string;
         width: number;
         height: number;
-        expires_at?: number;
     };
-    /** Fail-soft fallback only (rasterize/store failed); normally absent. */
-    rendered_svg?: string;
 }
 /** Visual stage (streaming): generation has started. MAY be emitted twice — first with
  *  `pending: null` (started, count unknown), then again with the ACCURATE post-vet count before
@@ -541,6 +535,11 @@ export declare class KnowledgeCoreClient extends HttpBase {
      *  error). Pass `signal` and abort() on unmount / when the user cancels or navigates away so the
      *  connection doesn't linger. Transient (ends on `done`) — no reopen logic needed. */
     queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void>;
+    /** Fetch a visual's PNG bytes BY ID. This is the ONLY way to get a visual image — the API never
+     *  returns a URL. Authenticated + tenant-scoped like every call. Use `visual.id` from a query
+     *  response / streamed `visual` event / persisted message. Returns a Blob (browser: `URL.
+     *  createObjectURL(blob)` for an <img>; Node: `Buffer.from(await blob.arrayBuffer())`). */
+    getVisualImage(visualId: UUID | string, signal?: AbortSignal): Promise<Blob>;
     /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
      *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
      *  `query`/`queryStream` ONLY for programmatic one-shots (tools).

package/dist/index.js

@@ -178,6 +178,18 @@ export class KnowledgeCoreClient extends HttpBase {
         if (buf.trim())
             dispatchSse(buf, handlers);
     }
+    /** Fetch a visual's PNG bytes BY ID. This is the ONLY way to get a visual image — the API never
+     *  returns a URL. Authenticated + tenant-scoped like every call. Use `visual.id` from a query
+     *  response / streamed `visual` event / persisted message. Returns a Blob (browser: `URL.
+     *  createObjectURL(blob)` for an <img>; Node: `Buffer.from(await blob.arrayBuffer())`). */
+    async getVisualImage(visualId, signal) {
+        const res = await this.raw("GET", `/v1/visuals/${visualId}/image`, { signal });
+        if (!res.ok) {
+            const t = await res.text();
+            throw new KnowledgeCoreError(res.status, safeJson(t), `/v1/visuals/${visualId}/image`);
+        }
+        return await res.blob();
+    }
     /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
      *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
      *  `query`/`queryStream` ONLY for programmatic one-shots (tools).

package/package.json

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

@@ -131,25 +131,21 @@ export type VisualLayout =
 /** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
  * system as citations).
  *
- * UNIFORM DELIVERY: every register (chart / structural / conceptual / scenic) carries `image` — a
- * PNG served BY KC. To display it, GET `image.url` (resolve a relative path against your KC base
- * URL) with your normal API key; the response body is the PNG bytes. The URL is a stable, non-
- * expiring KC endpoint for persisted/conversational visuals (`expires_at` absent), so it works on
- * reload/copy/export and on later conversation retrieval — the client never fetches GCS and never
- * parses inline SVG. `rendered_svg` appears ONLY as a rare fail-soft fallback (server rasterization
- * failed); prefer `image` and treat `rendered_svg` as a last resort. */
+ * IDs-ONLY: the API never returns a URL. Every visual (chart / structural / conceptual / scenic) is
+ * a PNG served by KC and identified by its `id`. To display it, fetch the bytes by id:
+ * `getVisualImage(visual.id)` (or GET /v1/visuals/{id}/image with your API key). `image` carries only
+ * the pixel DIMENSIONS, for layout. The image is authenticated + tenant-scoped exactly like every
+ * other KC call; there is no URL, no signed GCS link, and nothing to expire. */
 export interface Visual {
   id: string;
   anchor: { start: number; end: number };
   register: "chart" | "structural" | "conceptual" | "scenic";
   priority: number;
-  payload: Record<string, unknown>; // {kind: "grammar"|"vega_lite"|"svg"|"image", ...}
+  payload: Record<string, unknown>; // {kind: "grammar"|"vega_lite"|"image", ...}
   /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
   layout: VisualLayout;
-  /** PRIMARY: GET this (relative to your KC base, with your API key) -> PNG bytes. */
-  image?: { url: string; width: number; height: number; expires_at?: number };
-  /** Fail-soft fallback only (rasterize/store failed); normally absent. */
-  rendered_svg?: string;
+  /** Pixel dimensions of the PNG (for layout). Fetch the bytes with getVisualImage(id). */
+  image?: { width: number; height: number };
 }
 
 /** Visual stage (streaming): generation has started. MAY be emitted twice — first with
@@ -655,6 +651,19 @@ export class KnowledgeCoreClient extends HttpBase {
     if (buf.trim()) dispatchSse(buf, handlers);
   }
 
+  /** Fetch a visual's PNG bytes BY ID. This is the ONLY way to get a visual image — the API never
+   *  returns a URL. Authenticated + tenant-scoped like every call. Use `visual.id` from a query
+   *  response / streamed `visual` event / persisted message. Returns a Blob (browser: `URL.
+   *  createObjectURL(blob)` for an <img>; Node: `Buffer.from(await blob.arrayBuffer())`). */
+  async getVisualImage(visualId: UUID | string, signal?: AbortSignal): Promise<Blob> {
+    const res = await this.raw("GET", `/v1/visuals/${visualId}/image`, { signal });
+    if (!res.ok) {
+      const t = await res.text();
+      throw new KnowledgeCoreError(res.status, safeJson(t), `/v1/visuals/${visualId}/image`);
+    }
+    return await res.blob();
+  }
+
   /** DUMMY-PROOF CHAT. Every message goes through a conversation — it is structurally impossible
    *  to send a chat turn as a non-persisted one-shot. Use this for ANY chat UI. Use the low-level
    *  `query`/`queryStream` ONLY for programmatic one-shots (tools).