@inferencesh/sdk 0.8.0 → 0.8.1

package/dist/api/sockets.d.ts

@@ -1,6 +1,7 @@
 import { HttpClient } from '../http/client';
 import type { Response } from '../http/response';
 import { LiveSession, type LiveHandlers, type WebSocketConstructor } from '../live/session';
+import type { JsonSchema } from '../live/schema';
 import { CursorListRequest, CursorListResponse, SocketAccess, SocketDTO, TaskDTO as Task } from '../types';
 import type { TasksAPI } from './tasks';
 /** What identifies the socket to open: the run response (which carries the access), a task, or a task id. */
@@ -16,6 +17,10 @@ export interface OpenSocketOptions {
     watchTask?: boolean;
     /** The WebSocket to dial with; defaults to the runtime's global one. */
     webSocket?: WebSocketConstructor;
+    /** The function's input schema: `session.sendField` routes by it. */
+    inputSchema?: JsonSchema | null;
+    /** The function's output schema: frames arrive at `onUpdate` as fields. */
+    outputSchema?: JsonSchema | null;
 }
 /**
  * Sockets API: the duplex connection of a stream task.

package/dist/api/sockets.js

@@ -54,6 +54,8 @@ export class SocketsAPI {
             renew: async () => (await this.access(access.id)).data,
             task: options.watchTask === false ? undefined : this.tasks.watch(task),
             webSocket: options.webSocket,
+            inputSchema: options.inputSchema,
+            outputSchema: options.outputSchema,
         });
         session.connect();
         return session;

package/dist/index.d.ts

@@ -25,8 +25,8 @@ export { SearchAPI } from './api/search';
 export { ProjectsAPI } from './api/projects';
 export { MCPServersAPI } from './api/mcp-servers';
 export { LiveSession, accessUrl } from './live/session';
-export type { LiveState, LiveEnd, LiveHandlers, LiveSessionOptions, WebSocketLike, WebSocketConstructor } from './live/session';
-export { STREAM_FORMAT, CLEAR_KEY, isLiveField, parseMediaType, pcmFormat, splitLiveSchema, binaryLiveField, alternativeLabel, } from './live/schema';
+export type { LiveState, LiveEnd, LiveHandlers, LiveSessionOptions, LiveUpdate, WebSocketLike, WebSocketConstructor } from './live/session';
+export { STREAM_FORMAT, CLEAR_KEY, ERROR_KEY, isLiveField, parseMediaType, pcmFormat, splitLiveSchema, binaryLiveField, alternativeLabel, alternativeTag, } from './live/schema';
 export type { JsonSchema, MediaType, PCMFormat, LiveField } from './live/schema';
 export { tool, appTool, agentTool, webhookTool, httpTool, callTool, mcpTool, internalTools, string, number, integer, boolean, enumOf, object, array, optional, } from './tool-builder';
 export type { ClientTool, ClientToolHandler } from './tool-builder';

package/dist/index.js

@@ -28,7 +28,7 @@ export { ProjectsAPI } from './api/projects';
 export { MCPServersAPI } from './api/mcp-servers';
 // Live: the socket of a stream task and the live fields of its schemas
 export { LiveSession, accessUrl } from './live/session';
-export { STREAM_FORMAT, CLEAR_KEY, isLiveField, parseMediaType, pcmFormat, splitLiveSchema, binaryLiveField, alternativeLabel, } from './live/schema';
+export { STREAM_FORMAT, CLEAR_KEY, ERROR_KEY, isLiveField, parseMediaType, pcmFormat, splitLiveSchema, binaryLiveField, alternativeLabel, alternativeTag, } from './live/schema';
 // Tool Builder (fluent API)
 export { tool, appTool, agentTool, webhookTool, httpTool, callTool, mcpTool, internalTools, string, number, integer, boolean, enumOf, object, array, optional, } from './tool-builder';
 // Hook Builder (fluent API)

package/dist/live/schema.d.ts

@@ -17,11 +17,13 @@
  * JSON Schema type keeps it.
  */
 export declare const STREAM_FORMAT = "stream";
+/** `{"$clear": "audio"}`: drop what has been buffered of a live output field. */
+export declare const CLEAR_KEY = "$clear";
 /**
- * A control frame, `{"$clear": "audio"}`: drop what has been buffered of a
- * live output field. Reserved keys start with `$`, which no field name can.
+ * `{"$error": {"field": ..., "message": ...}}`: a refused frame, or anything
+ * else the caller should be told went wrong. The stream goes on.
  */
-export declare const CLEAR_KEY = "$clear";
+export declare const ERROR_KEY = "$error";
 /** The part of JSON Schema these helpers read. */
 export interface JsonSchema {
     $ref?: string;
@@ -37,6 +39,9 @@ export interface JsonSchema {
     required?: string[];
     anyOf?: JsonSchema[];
     oneOf?: JsonSchema[];
+    discriminator?: {
+        propertyName?: string;
+    };
 }
 export declare function isLiveField(schema: JsonSchema | undefined | null): boolean;
 export interface MediaType {
@@ -65,6 +70,8 @@ export interface LiveField<S extends JsonSchema = JsonSchema> {
      * or the single item schema. Empty for a binary field.
      */
     alternatives: S[];
+    /** The property that tells the alternatives apart, when the schema names one. */
+    discriminator?: string;
 }
 /**
  * Splits a function schema into what a form renders (the ordinary
@@ -76,5 +83,10 @@ export declare function splitLiveSchema<S extends JsonSchema>(schema: S | undefi
 };
 /** The schema's one binary live field. A binary frame carries no field name. */
 export declare function binaryLiveField<S extends JsonSchema>(live: LiveField<S>[]): LiveField<S> | null;
-/** A label for one alternative of a JSON live field: its `type` const, else its title. */
-export declare function alternativeLabel(schema: JsonSchema, index: number): string;
+/**
+ * The property whose constant names this alternative: the schema's
+ * discriminator, else `type`, else the first property with a constant.
+ */
+export declare function alternativeTag(schema: JsonSchema, discriminator?: string): string | undefined;
+/** A label for one alternative of a JSON live field: the constant that tags it, else its title. */
+export declare function alternativeLabel(schema: JsonSchema, index: number, discriminator?: string): string;

package/dist/live/schema.js

@@ -17,11 +17,15 @@
  * JSON Schema type keeps it.
  */
 export const STREAM_FORMAT = 'stream';
+// Control frames. Reserved keys start with `$`, which no field name can, so a
+// control frame is never mistaken for an output field.
+/** `{"$clear": "audio"}`: drop what has been buffered of a live output field. */
+export const CLEAR_KEY = '$clear';
 /**
- * A control frame, `{"$clear": "audio"}`: drop what has been buffered of a
- * live output field. Reserved keys start with `$`, which no field name can.
+ * `{"$error": {"field": ..., "message": ...}}`: a refused frame, or anything
+ * else the caller should be told went wrong. The stream goes on.
  */
-export const CLEAR_KEY = '$clear';
+export const ERROR_KEY = '$error';
 export function isLiveField(schema) {
     return !!schema && schema.format === STREAM_FORMAT;
 }
@@ -99,6 +103,7 @@ export function splitLiveSchema(schema) {
             binary,
             media: binary ? parseMediaType(resolvedItems.contentMediaType) : null,
             alternatives: binary ? [] : itemAlternatives(items, schema),
+            discriminator: binary ? undefined : resolvedItems.discriminator?.propertyName,
         });
     }
     return {
@@ -110,10 +115,21 @@ export function splitLiveSchema(schema) {
 export function binaryLiveField(live) {
     return live.find((field) => field.binary) ?? null;
 }
-/** A label for one alternative of a JSON live field: its `type` const, else its title. */
-export function alternativeLabel(schema, index) {
-    const tag = schema.properties?.type?.const;
-    if (typeof tag === 'string')
-        return tag;
+/**
+ * The property whose constant names this alternative: the schema's
+ * discriminator, else `type`, else the first property with a constant.
+ */
+export function alternativeTag(schema, discriminator) {
+    const constants = Object.entries(schema.properties ?? {})
+        .filter(([, property]) => property && 'const' in property)
+        .map(([key]) => key);
+    return [discriminator, 'type', ...constants].find((key) => !!key && constants.includes(key));
+}
+/** A label for one alternative of a JSON live field: the constant that tags it, else its title. */
+export function alternativeLabel(schema, index, discriminator) {
+    const tag = alternativeTag(schema, discriminator);
+    const value = tag ? schema.properties?.[tag]?.const : undefined;
+    if (typeof value === 'string')
+        return value;
     return schema.title ?? `option ${index + 1}`;
 }

package/dist/live/session.d.ts

@@ -11,6 +11,8 @@
  * name.
  */
 import type { SocketAccess } from '../types';
+import type { TaskWatch as TasksWatch } from '../api/tasks';
+import { type JsonSchema } from './schema';
 export type LiveState = 'connecting' | 'waiting' | 'live' | 'ended';
 export interface LiveEnd {
     /** The WebSocket close code, or 1006 when the session ended without one. */
@@ -33,16 +35,37 @@ export interface LiveHandlers {
      * handler the control frame reaches onPatch as `{"$clear": field}`.
      */
     onClear?: (field: string) => void;
+    /**
+     * The app refused a frame, or has something to report, and goes on:
+     * `{"$error": {field, message}}`. Apps on SDKs before 0.7.2 / 0.9.2 send it
+     * as `{"error": ...}`, which counts too unless the output has an `error`
+     * field. Without this handler it stays in the patch.
+     */
+    onError?: (field: string | null, message: string) => void;
+    /** A text frame that is not a JSON object: text the app sent as text. */
+    onText?: (text: string) => void;
+    /**
+     * With `outputSchema`, each frame mapped to its output field: an item of a
+     * live field (an ArrayBuffer for the binary one) or a new value of an
+     * ordinary field. Takes the place of onBinary and onPatch where those are
+     * not set.
+     */
+    onUpdate?: (update: LiveUpdate) => void;
+}
+/** One thing the app sent, mapped to its output field. */
+export interface LiveUpdate {
+    field: string;
+    value: unknown;
 }
 /**
- * Follows the task the socket belongs to. `done` settles when the task ends
- * (rejected when it failed or was cancelled); `stop` ends the watch early and
- * leaves `done` pending.
+ * Follows the task the socket belongs to (what `client.tasks.watch` returns):
+ * `done` settles when the task ends, rejected when it failed or was
+ * cancelled; `stop` ends the watch early and leaves `done` pending. Only
+ * settling matters here, so any promise will do.
  */
-export interface TaskWatch {
+export type TaskWatch = Pick<TasksWatch, 'stop'> & {
     done: Promise<unknown>;
-    stop(): void;
-}
+};
 /** The part of the WebSocket API the session uses; browsers, Node 22+ and `ws` all provide it. */
 export interface WebSocketLike {
     binaryType: string;
@@ -72,6 +95,10 @@ export interface LiveSessionOptions {
     task?: TaskWatch;
     /** The WebSocket to dial with; defaults to the runtime's global one. */
     webSocket?: WebSocketConstructor;
+    /** The function's input schema: `sendField` routes by it. */
+    inputSchema?: JsonSchema | null;
+    /** The function's output schema: frames arrive at onUpdate as fields. */
+    outputSchema?: JsonSchema | null;
 }
 /**
  * Where to dial. A browser cannot set headers on a WebSocket, so the
@@ -88,6 +115,11 @@ export declare class LiveSession {
     private readonly renew;
     private readonly task;
     private readonly WebSocket;
+    private readonly mapped;
+    private readonly outputBinary;
+    private readonly outputFields;
+    private readonly inputKnown;
+    private readonly inputBinary;
     private resolveEnded;
     /** Settles when the session has ended, however it ended. */
     readonly ended: Promise<LiveEnd>;
@@ -96,6 +128,10 @@ export declare class LiveSession {
     get isOpen(): boolean;
     /** Dials the relay. The session reports its progress through onState. */
     connect(): void;
+    private deliverText;
+    /** `{"error": {"message": ...}}` from an app on an older SDK, unless the output has an `error` field. */
+    private legacyError;
+    private deliverBinary;
     private watched;
     private watchTask;
     private redial;
@@ -104,6 +140,12 @@ export declare class LiveSession {
     private closeSocket;
     /** One item of the input's binary live field. */
     sendBinary(data: ArrayBuffer | ArrayBufferView): void;
+    /**
+     * One item of an input live field, or a new value of an ordinary one: a
+     * binary frame for the binary live field, a JSON frame otherwise. Needs
+     * `inputSchema`.
+     */
+    sendField(field: string, value: unknown): void;
     /** A partial input object keyed by field name. */
     sendPatch(patch: Record<string, unknown>): void;
     /** Ends the stream; the function returns and the task completes. */

package/dist/live/session.js

@@ -1,4 +1,4 @@
-import { CLEAR_KEY } from './schema';
+import { binaryLiveField, CLEAR_KEY, ERROR_KEY, splitLiveSchema } from './schema';
 const WS_OPEN = 1;
 // 1012: the relay is restarting and closed an end that still waited for its
 // peer. 1013: the peer did not come in time. Both mean "dial again" while the
@@ -32,6 +32,11 @@ export class LiveSession {
         this.renew = options.renew;
         this.task = options.task;
         this.WebSocket = options.webSocket ?? globalWebSocket();
+        this.mapped = !!options.outputSchema;
+        this.outputBinary = binaryLiveField(splitLiveSchema(options.outputSchema).live)?.key;
+        this.outputFields = new Set(Object.keys(options.outputSchema?.properties ?? {}));
+        this.inputKnown = !!options.inputSchema;
+        this.inputBinary = binaryLiveField(splitLiveSchema(options.inputSchema).live)?.key;
         this.ended = new Promise((resolve) => {
             this.resolveEnded = resolve;
         });
@@ -55,29 +60,10 @@ export class LiveSession {
                 this.setState('live');
                 this.task?.stop(); // the app is there; the task's fate now shows on the socket
             }
-            if (typeof event.data === 'string') {
-                let patch;
-                try {
-                    patch = JSON.parse(event.data);
-                }
-                catch {
-                    patch = { text: event.data };
-                }
-                if (patch && typeof patch === 'object' && !Array.isArray(patch)) {
-                    const record = patch;
-                    const clear = record[CLEAR_KEY];
-                    if (this.handlers.onClear && typeof clear === 'string') {
-                        this.handlers.onClear(clear);
-                        delete record[CLEAR_KEY];
-                        if (Object.keys(record).length === 0)
-                            return;
-                    }
-                    this.handlers.onPatch?.(record);
-                }
-            }
-            else {
-                this.handlers.onBinary?.(event.data);
-            }
+            if (typeof event.data === 'string')
+                this.deliverText(event.data);
+            else
+                this.deliverBinary(event.data);
         };
         ws.onclose = (event) => {
             if (this.ws !== ws)
@@ -92,6 +78,53 @@ export class LiveSession {
             this.end({ code: event.code, reason: event.reason, byCaller: this.closedByCaller, taskEnded: false });
         };
     }
+    deliverText(text) {
+        let patch;
+        try {
+            patch = JSON.parse(text);
+        }
+        catch {
+            patch = undefined;
+        }
+        if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+            this.handlers.onText?.(text); // text the app sent as text
+            return;
+        }
+        const record = patch;
+        const arrivedEmpty = Object.keys(record).length === 0;
+        const { onClear, onError } = this.handlers;
+        if (onClear && typeof record[CLEAR_KEY] === 'string') {
+            onClear(record[CLEAR_KEY]);
+            delete record[CLEAR_KEY];
+        }
+        if (onError) {
+            const key = ERROR_KEY in record ? ERROR_KEY : this.legacyError(record) ? 'error' : undefined;
+            if (key) {
+                const err = record[key];
+                delete record[key];
+                const { field = null, message } = (err && typeof err === 'object' ? err : { message: String(err) });
+                onError(field, typeof message === 'string' ? message : JSON.stringify(err));
+            }
+        }
+        if (!arrivedEmpty && Object.keys(record).length === 0)
+            return; // it was only control frames
+        if (this.handlers.onPatch)
+            this.handlers.onPatch(record);
+        else if (this.mapped)
+            for (const [field, value] of Object.entries(record))
+                this.handlers.onUpdate?.({ field, value });
+    }
+    /** `{"error": {"message": ...}}` from an app on an older SDK, unless the output has an `error` field. */
+    legacyError(record) {
+        const err = record.error;
+        return !!err && typeof err === 'object' && 'message' in err && !this.outputFields.has('error');
+    }
+    deliverBinary(data) {
+        if (this.handlers.onBinary)
+            this.handlers.onBinary(data);
+        else if (this.mapped && this.outputBinary)
+            this.handlers.onUpdate?.({ field: this.outputBinary, value: data });
+    }
     watchTask() {
         if (!this.task || this.watched)
             return;
@@ -136,6 +169,19 @@ export class LiveSession {
         if (this.isOpen)
             this.ws.send(data);
     }
+    /**
+     * One item of an input live field, or a new value of an ordinary one: a
+     * binary frame for the binary live field, a JSON frame otherwise. Needs
+     * `inputSchema`.
+     */
+    sendField(field, value) {
+        if (!this.inputKnown)
+            throw new Error("sendField needs the function's inputSchema");
+        if (field === this.inputBinary)
+            this.sendBinary(value);
+        else
+            this.sendPatch({ [field]: value });
+    }
     /** A partial input object keyed by field name. */
     sendPatch(patch) {
         if (this.isOpen)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/sdk",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Official JavaScript/TypeScript SDK for inference.sh - Run AI models with a simple API",
   "type": "module",
   "main": "dist/index.js",