@babav/knowledge-core-client 0.30.0 → 0.32.0

package/dist/index.d.ts

@@ -95,7 +95,13 @@ export interface QueryRequest {
  * 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`. */
+ * system as citations).
+ *
+ * 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: {
@@ -107,10 +113,8 @@ export interface Visual {
     payload: Record<string, unknown>;
     /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
     layout: VisualLayout;
-    rendered_svg?: string;
+    /** Pixel dimensions of the PNG (for layout). Fetch the bytes with getVisualImage(id). */
     image?: {
-        url: string;
-        expires_at: number;
         width: number;
         height: number;
     };
@@ -531,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.30.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

@@ -129,17 +129,23 @@ export type VisualLayout =
   | "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`. */
+ * system as citations).
+ *
+ * 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;
-  rendered_svg?: string;
-  image?: { url: string; expires_at: number; width: number; height: number };
+  /** 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
@@ -645,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).