@inferencesh/sdk 0.7.1 → 0.8.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-24
+
+### Removed
+
+- The integration-named aliases: `IntegrationsAPI`, `client.integrations`, the `Integration*` type aliases, and `httpTool().auth({ integration, integrationId })`. Use `CredentialsAPI`, `client.credentials`, the `Credential*` types and `auth({ credential, credentialId })`.
+
 ## [0.7.0] - 2026-09-23
 
 ### Changed

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

@@ -21,14 +21,12 @@ export { TeamsAPI, type MeResponse } from './api/teams';
 export { SecretsAPI } from './api/secrets';
 export { ApiKeysAPI } from './api/api-keys';
 export { CredentialsAPI } from './api/credentials';
-/** @deprecated renamed CredentialsAPI */
-export { CredentialsAPI as IntegrationsAPI } from './api/credentials';
 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';
@@ -39,7 +37,6 @@ export { parseStatus, isTerminalStatus, isChatBusy, pendingApprovals } from './u
 export type { PendingApproval } from './utils';
 export * from './types';
 export type { TaskDTO as Task } from './types';
-export type { CredentialDTO as IntegrationDTO, CredentialConfigDTO as IntegrationConfigDTO, CredentialConnectRequest as IntegrationConnectRequest, CredentialConnectResponse as IntegrationConnectResponse, CredentialCompleteOAuthRequest as IntegrationCompleteOAuthRequest, CredentialRequirement as IntegrationRequirement, CredentialStatus as IntegrationStatus, CredentialScope as IntegrationScope, CredentialGrant as IntegrationGrant, CredentialType as IntegrationAuthType, CredentialProvider as IntegrationProvider, } from './types';
 import { HttpClient, type HttpClientConfig } from './http/client';
 import { TasksAPI, RunOptions } from './api/tasks';
 import { SocketsAPI } from './api/sockets';
@@ -119,8 +116,6 @@ export declare class Inference {
     readonly projects: ProjectsAPI;
     readonly mcpServers: MCPServersAPI;
     readonly sockets: SocketsAPI;
-    /** @deprecated renamed `credentials` */
-    get integrations(): CredentialsAPI;
     constructor(config: InferenceConfig | HttpClientConfig);
     /** @internal */
     _request<T>(method: 'get' | 'post' | 'put' | 'delete', endpoint: string, options?: {

package/dist/index.js

@@ -23,14 +23,12 @@ export { TeamsAPI } from './api/teams';
 export { SecretsAPI } from './api/secrets';
 export { ApiKeysAPI } from './api/api-keys';
 export { CredentialsAPI } from './api/credentials';
-/** @deprecated renamed CredentialsAPI */
-export { CredentialsAPI as IntegrationsAPI } from './api/credentials';
 export { SearchAPI } from './api/search';
 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)
@@ -74,10 +72,6 @@ import { MCPServersAPI } from './api/mcp-servers';
  * ```
  */
 export class Inference {
-    /** @deprecated renamed `credentials` */
-    get integrations() {
-        return this.credentials;
-    }
     constructor(config) {
         // Handle both simple config and full HttpClientConfig
         this.http = new HttpClient({

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/dist/tool-builder.d.ts

@@ -94,8 +94,6 @@ declare class HTTPToolBuilder extends ToolBuilder {
     auth(config: {
         credential?: string;
         credentialId?: string;
-        /** @deprecated renamed `credential` */ integration?: string;
-        /** @deprecated renamed `credentialId` */ integrationId?: string;
         apiKey?: string;
         bearer?: string;
         header?: string;

package/dist/tool-builder.js

@@ -189,9 +189,8 @@ class HTTPToolBuilder extends ToolBuilder {
      * send a vault secret.
      */
     auth(config) {
-        const provider = config.credential ?? config.integration;
-        if (provider) {
-            this.authConfig = { type: ToolAuthTypeCredential, provider, credential_id: config.credentialId ?? config.integrationId };
+        if (config.credential) {
+            this.authConfig = { type: ToolAuthTypeCredential, provider: config.credential, credential_id: config.credentialId };
         }
         else if (config.apiKey) {
             this.authConfig = { type: ToolAuthTypeAPIKey, secret: config.apiKey, header: config.header || 'X-API-Key' };

package/dist/types.d.ts

@@ -127,11 +127,6 @@ export interface ToolAuthConfig {
     type: ToolAuthType;
     provider?: string;
     credential_id?: string;
-    /**
-     * Deprecated: the credential id used to be called integration_id. Read
-     * through CredentialRef(); never written.
-     */
-    integration_id?: string;
     secret?: string;
     header?: string;
 }
@@ -147,11 +142,6 @@ export interface HTTPToolConfig {
 }
 export interface MCPToolConfig {
     credential_id?: string;
-    /**
-     * Deprecated: the credential id used to be called integration_id. Read
-     * through CredentialRef(); never written.
-     */
-    integration_id?: string;
     tool_name: string;
 }
 export interface AppToolConfigDTO {
@@ -855,7 +845,7 @@ export declare const ScopeSecretsRead: Scope;
 export declare const ScopeSecretsWrite: Scope;
 /**
  * Action-level scopes for credentials (connected accounts, vaults,
- * custom providers, MCP servers). Formerly integrations:read|write.
+ * custom providers, MCP servers).
  */
 export declare const ScopeCredentialsRead: Scope;
 /**
@@ -4443,7 +4433,7 @@ export type SecretScope = string;
  */
 export declare const SecretScopeTeam: SecretScope;
 /**
- * SecretScopeInternal is an integration-managed secret, hidden from user lists
+ * SecretScopeInternal is a credential-managed secret, hidden from user lists
  */
 export declare const SecretScopeInternal: SecretScope;
 /**

package/dist/types.js

@@ -199,7 +199,7 @@ export const ScopeSecretsRead = "secrets:read";
 export const ScopeSecretsWrite = "secrets:write";
 /**
  * Action-level scopes for credentials (connected accounts, vaults,
- * custom providers, MCP servers). Formerly integrations:read|write.
+ * custom providers, MCP servers).
  */
 export const ScopeCredentialsRead = "credentials:read";
 /**
@@ -608,7 +608,7 @@ export const ResponseFormatTypeJSONSchema = "json_schema";
  */
 export const SecretScopeTeam = "team";
 /**
- * SecretScopeInternal is an integration-managed secret, hidden from user lists
+ * SecretScopeInternal is a credential-managed secret, hidden from user lists
  */
 export const SecretScopeInternal = "internal";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/sdk",
-  "version": "0.7.1",
+  "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",