10xgraph-client 0.6.0 → 1.0.0-rc.2

package/dist/cjs/index.d.ts

@@ -0,0 +1,41 @@
+export * from './tools.js';
+export * from './client.js';
+export * from './errors.js';
+export * from './request.js';
+export * from './endpoints/ping.js';
+export * from './endpoints/graph.js';
+export * from './endpoints/graphTools.js';
+export * from './endpoints/observability.js';
+export * from './endpoints/stopGraph.js';
+export * from './endpoints/fixGraph.js';
+export * from './endpoints/stateSchema.js';
+export * from './endpoints/threadState.js';
+export * from './endpoints/updateThreadState.js';
+export * from './endpoints/clearThreadState.js';
+export * from './endpoints/threadMessages.js';
+export * from './endpoints/addThreadMessages.js';
+export * from './endpoints/threadMessage.js';
+export * from './endpoints/deleteThreadMessage.js';
+export * from './endpoints/updateThreadMessageFeedback.js';
+export * from './endpoints/deleteThread.js';
+export * from './endpoints/threads.js';
+export * from './endpoints/threadDetails.js';
+export * from './endpoints/invoke.js';
+export * from './endpoints/stream.js';
+export * from './interrupt.js';
+export * from './endpoints/wsStream.js';
+export * from './ws.js';
+export * from './endpoints/realtime.js';
+export * from './endpoints/storeMemory.js';
+export * from './endpoints/searchMemory.js';
+export * from './endpoints/getMemory.js';
+export * from './endpoints/updateMemory.js';
+export * from './endpoints/deleteMemory.js';
+export * from './endpoints/listMemories.js';
+export * from './endpoints/forgetMemories.js';
+export * from './endpoints/files.js';
+export * from './endpoints/deleteFile.js';
+export * from './endpoints/metadata.js';
+export * from './agent.js';
+export * from './message.js';
+export * from './compat.js';

package/dist/cjs/interrupt.d.ts

@@ -0,0 +1,45 @@
+import type { StreamChunk } from './endpoints/stream.js';
+/**
+ * A pause raised by `interrupt()` in a graph node or tool, waiting for a resume value.
+ * Mirrors the server payload at `chunk.data.interrupt` of an `updates` chunk whose
+ * `status` is `"interrupted"`.
+ */
+export interface Interrupt {
+    /** Unique id of this pause; echo it as `interrupt_id` when resuming. */
+    id: string;
+    /** Stable position of the call within its node or tool call. */
+    key: string;
+    /** Node that was running when the graph paused. */
+    node: string;
+    /** Payload passed to `interrupt()`: what to approve or choose from. */
+    value?: unknown;
+    /** Human-readable prompt. */
+    message?: string | null;
+    /** Machine-readable reason, for example `"tool_approval"`. */
+    reason: string;
+    /** JSON Schema the resume value must follow. */
+    response_schema?: Record<string, unknown> | null;
+    /** Tool call that paused, when `interrupt()` ran inside a tool. */
+    tool_call_id?: string | null;
+}
+/** Spread into the `options` of `invoke`, `stream` or `wsStream` to answer an interrupt. */
+export interface InterruptResume {
+    resume: unknown;
+    interrupt_id: string;
+}
+/** The pending interrupt carried by a stream chunk, or null when the chunk has none. */
+export declare function getInterrupt(chunk: Pick<StreamChunk, 'event' | 'data'>): Interrupt | null;
+/**
+ * Answer an interrupt with approval. `value` is what the interrupted code receives; it
+ * defaults to `true`. When the interrupt sets `response_schema`, pass a value that matches it.
+ *
+ * ```ts
+ * await client.invoke([], { config: { thread_id }, ...approveInterrupt(interrupt) });
+ * ```
+ */
+export declare function approveInterrupt(interrupt: Interrupt, value?: unknown): InterruptResume;
+/**
+ * Answer an interrupt with a cancel. The server resumes the interrupted code with `null`
+ * and does not check it against `response_schema`.
+ */
+export declare function rejectInterrupt(interrupt: Interrupt): InterruptResume;

package/dist/cjs/message.d.ts

@@ -0,0 +1,173 @@
+export declare class MediaRef {
+    kind: 'url' | 'file_id' | 'data';
+    url?: string;
+    file_id?: string;
+    data_base64?: string;
+    mime_type?: string;
+    size_bytes?: number;
+    sha256?: string;
+    filename?: string;
+    width?: number;
+    height?: number;
+    duration_ms?: number;
+    page?: number;
+    constructor(kind?: 'url' | 'file_id' | 'data', url?: string, file_id?: string, data_base64?: string, mime_type?: string, size_bytes?: number, sha256?: string, filename?: string, width?: number, height?: number, duration_ms?: number, page?: number);
+}
+export declare class AnnotationRef {
+    url?: string;
+    file_id?: string;
+    page?: number;
+    index?: number;
+    title?: string;
+    constructor(url?: string, file_id?: string, page?: number, index?: number, title?: string);
+}
+export declare class TextBlock {
+    type: 'text';
+    text: string;
+    annotations: AnnotationRef[];
+    constructor(text?: string, annotations?: AnnotationRef[]);
+}
+export declare class ImageBlock {
+    type: 'image';
+    media: MediaRef;
+    alt_text?: string;
+    bbox?: number[];
+    constructor(media?: MediaRef, alt_text?: string, bbox?: number[]);
+}
+export declare class AudioBlock {
+    type: 'audio';
+    media: MediaRef;
+    transcript?: string;
+    sample_rate?: number;
+    channels?: number;
+    constructor(media?: MediaRef, transcript?: string, sample_rate?: number, channels?: number);
+}
+export declare class VideoBlock {
+    type: 'video';
+    media: MediaRef;
+    thumbnail?: MediaRef;
+    constructor(media?: MediaRef, thumbnail?: MediaRef);
+}
+export declare class DocumentBlock {
+    type: 'document';
+    media: MediaRef;
+    pages?: number[];
+    excerpt?: string;
+    constructor(media?: MediaRef, pages?: number[], excerpt?: string);
+}
+export declare class DataBlock {
+    type: 'data';
+    mime_type: string;
+    data_base64?: string;
+    media?: MediaRef;
+    constructor(mime_type?: string, data_base64?: string, media?: MediaRef);
+}
+export declare class ToolCallBlock {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    args: Record<string, any>;
+    tool_type?: string;
+    constructor(id?: string, name?: string, args?: Record<string, any>, tool_type?: string);
+}
+export declare class RemoteToolCallBlock {
+    type: 'remote_tool_call';
+    id: string;
+    name: string;
+    args: Record<string, any>;
+    tool_type: string;
+    constructor(id?: string, name?: string, args?: Record<string, any>, tool_type?: string);
+}
+export declare class ToolResultBlock {
+    type: 'tool_result';
+    call_id: string;
+    output: any;
+    is_error: boolean;
+    status?: 'completed' | 'failed';
+    constructor(props: {
+        call_id: string;
+        output: any;
+        status: 'completed' | 'failed';
+        is_error: boolean;
+    });
+}
+export declare class ReasoningBlock {
+    type: 'reasoning';
+    summary: string;
+    details?: string[];
+    constructor(summary?: string, details?: string[]);
+}
+export declare class AnnotationBlock {
+    type: 'annotation';
+    kind: 'citation' | 'note';
+    refs: AnnotationRef[];
+    spans?: [number, number][];
+    constructor(kind?: 'citation' | 'note', refs?: AnnotationRef[], spans?: [number, number][]);
+}
+export declare class ErrorBlock {
+    type: 'error';
+    message: string;
+    code?: string;
+    data?: Record<string, any>;
+    constructor(message?: string, code?: string, data?: Record<string, any>);
+}
+export type ContentBlock = TextBlock | ImageBlock | AudioBlock | VideoBlock | DocumentBlock | DataBlock | ToolCallBlock | RemoteToolCallBlock | ToolResultBlock | ReasoningBlock | AnnotationBlock | ErrorBlock;
+export declare class TokenUsages {
+    completion_tokens: number;
+    prompt_tokens: number;
+    total_tokens: number;
+    reasoning_tokens: number;
+    cache_creation_input_tokens: number;
+    cache_read_input_tokens: number;
+    image_tokens?: number;
+    audio_tokens?: number;
+}
+export declare class Message {
+    message_id: string | null;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: ContentBlock[];
+    delta: boolean;
+    tools_calls?: Record<string, any>[];
+    timestamp: number;
+    metadata: Record<string, any>;
+    usages?: TokenUsages;
+    raw?: Record<string, any>;
+    constructor(role: 'user' | 'assistant' | 'system' | 'tool', content: ContentBlock[], message_id?: string | null);
+    static text_message(content: string, role?: 'user' | 'assistant' | 'system' | 'tool', message_id?: string | null): Message;
+    static tool_message(content: ContentBlock[], message_id?: string | null, meta?: Record<string, any>): Message;
+    text(): string;
+    attach_media(media: MediaRef, as_type: 'image' | 'audio' | 'video' | 'document'): void;
+    /**
+     * Create a message with an image (via URL or base64).
+     *
+     * @example
+     * ```ts
+     * const msg = Message.withImage('Describe this', 'https://example.com/photo.jpg');
+     * const msg2 = Message.withImage('Describe this', 'data:image/png;base64,...');
+     * ```
+     */
+    static withImage(text: string, imageUrl: string, role?: 'user' | 'assistant' | 'system'): Message;
+    /**
+     * Create a message with a file reference (e.g. from uploadFile result).
+     *
+     * @example
+     * ```ts
+     * const upload = await client.uploadFile(pdfFile);
+     * const msg = Message.withFile('Summarize this PDF', upload.data.file_id, 'application/pdf');
+     * ```
+     */
+    static withFile(text: string, fileId: string, mimeType?: string, role?: 'user' | 'assistant' | 'system'): Message;
+    /**
+     * Create a multimodal message with arbitrary content blocks.
+     *
+     * @example
+     * ```ts
+     * const msg = Message.multimodal([
+     *   new TextBlock('Look at these'),
+     *   new ImageBlock(new MediaRef('url', 'https://...')),
+     *   new ImageBlock(new MediaRef('url', 'https://...')),
+     * ]);
+     * ```
+     */
+    static multimodal(blocks: ContentBlock[], role?: 'user' | 'assistant' | 'system'): Message;
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}

package/dist/cjs/request.d.ts

@@ -0,0 +1,60 @@
+import type { WebSocketImpl } from './ws.js';
+export interface TenxGraphBearerAuth {
+    type: 'bearer';
+    token: string;
+}
+export interface TenxGraphBasicAuth {
+    type: 'basic';
+    username: string;
+    password: string;
+}
+export interface TenxGraphHeaderAuth {
+    type: 'header';
+    name: string;
+    value: string;
+    prefix?: string | null;
+}
+export type TenxGraphAuth = TenxGraphBearerAuth | TenxGraphBasicAuth | TenxGraphHeaderAuth;
+/**
+ * Abort `controller` when the caller's `signal` aborts. Returns a cleanup function.
+ * A signal that is already aborted aborts the controller immediately.
+ */
+export declare function linkAbortSignal(controller: AbortController, signal?: AbortSignal | null): () => void;
+/** Per-call options accepted by every client method that makes a request. */
+export interface RequestOptions {
+    /** Abort to cancel the request. Rejects with the signal's AbortError, never as a timeout. */
+    signal?: AbortSignal;
+}
+export interface RequestContext {
+    baseUrl: string;
+    authToken?: string | null;
+    auth?: TenxGraphAuth | null;
+    headers?: HeadersInit;
+    credentials?: RequestCredentials;
+    timeout: number;
+    debug: boolean;
+    webSocketImpl?: WebSocketImpl;
+    /** Caller's cancellation signal for this call. Set per call by the client, not stored. */
+    signal?: AbortSignal;
+}
+export declare function buildHeaders(context: Pick<RequestContext, 'authToken' | 'auth' | 'headers'>, defaults?: HeadersInit): Record<string, string>;
+export declare function getRequestCredentials(context: Pick<RequestContext, 'credentials'>): Pick<RequestInit, 'credentials'> | Record<string, never>;
+export declare function bearerAuth(token: string): TenxGraphBearerAuth;
+export declare function basicAuth(username: string, password: string): TenxGraphBasicAuth;
+export declare function headerAuth(name: string, value: string, prefix?: string | null): TenxGraphHeaderAuth;
+/** Percent-encode one URL path segment (thread, message or memory id). */
+export declare function encodePathSegment(value: string | number): string;
+/** Strip trailing slashes so `${baseUrl}/path` never produces `//path`. */
+export declare function normalizeBaseUrl(baseUrl: string): string;
+/**
+ * fetch with the shared client policy:
+ * - the timeout timer is always cleared (also when fetch rejects) and does not keep a Node
+ *   process alive;
+ * - `context.signal` cancels the call (rejects with the AbortError, never as a timeout);
+ * - a timeout throws RequestTimeoutError, any other fetch rejection throws NetworkError
+ *   with the original error as `cause`;
+ * - with header-type credentials other than Authorization (e.g. X-API-Key, which fetch does not
+ *   strip on a redirect)
+ *   redirects are followed only within the same origin; a cross-origin redirect is refused.
+ */
+export declare function fetchWithTimeout(context: Pick<RequestContext, 'timeout' | 'signal' | 'auth'>, url: string, init?: RequestInit): Promise<Response>;

package/dist/cjs/tools.d.ts

@@ -0,0 +1,80 @@
+import { Message } from './message.js';
+export interface ToolHandler {
+    (args: any): Promise<any>;
+}
+/**
+ * JSON Schema describing a tool's arguments.
+ *
+ * `properties` and `required` are optional, matching JSON Schema itself: a tool
+ * whose arguments are all optional needs neither, and a tool that takes no
+ * arguments can be declared as `{ type: 'object' }`. Additional JSON Schema
+ * keywords (`additionalProperties`, `$defs`, ...) are passed through untouched.
+ */
+export interface ToolParameter {
+    type: string;
+    properties?: Record<string, any>;
+    required?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Fill in the JSON Schema defaults a tool declaration may leave out, so the
+ * wire format sent to the server is always a complete object schema.
+ */
+export declare function normalizeToolParameters(parameters?: ToolParameter): ToolParameter;
+export interface Tool {
+    type: string;
+    function: {
+        name: string;
+        description: string;
+        parameters: ToolParameter;
+    };
+}
+export interface ToolRegistration {
+    node?: string;
+    name: string;
+    description?: string;
+    parameters?: ToolParameter;
+    handler: ToolHandler;
+    /**
+     * Runs on the server-sent arguments before the handler (after the declared `parameters`
+     * check). Throw, or return `false`, to reject the call: the model receives a failed tool
+     * result and the handler is not run.
+     */
+    validate?: (args: any) => boolean | void | Promise<boolean | void>;
+    /** Reject calls whose JSON-serialised arguments exceed this many bytes. Default 1 MiB. */
+    maxArgsBytes?: number;
+}
+/** Default cap on serialised tool-call arguments. */
+export declare const DEFAULT_MAX_TOOL_ARGS_BYTES: number;
+/** Check `args` against the top level of a declared JSON Schema; returns an error message or null. */
+export declare function checkToolArguments(args: unknown, parameters?: ToolParameter): string | null;
+export interface ToolDefinition extends ToolHandler {
+    name: string;
+    description?: string;
+    parameters?: ToolParameter;
+    node?: string;
+    validate?: ToolRegistration['validate'];
+    maxArgsBytes?: number;
+}
+export declare class ToolExecutor {
+    private tools;
+    private toolsByNode;
+    constructor(tools?: ToolDefinition[]);
+    /**
+     * Register a new tool
+     */
+    registerTool(registration: ToolRegistration): void;
+    /**
+     * Get tools for a specific node
+     */
+    getToolsForNode(node: string): ToolDefinition[];
+    /**
+     * Get all tools in OpenAI-compatible format
+     */
+    all_tools(): Tool[];
+    /**
+     * Extract and execute all tool calls from the response
+     * Returns an array of tool result messages
+     */
+    executeToolCalls(messages: Message[]): Promise<Message[]>;
+}

package/dist/cjs/ws.d.ts

@@ -0,0 +1,47 @@
+import { TenxGraphAuth } from './request.js';
+/**
+ * Sec-WebSocket-Protocol token the server recognizes for browser-safe bearer auth.
+ * The client opens the socket with `[WS_BEARER_SUBPROTOCOL, "<jwt>"]`; the server
+ * extracts the second protocol entry as the token. This works in browsers (which
+ * cannot set request headers on a WebSocket) and avoids leaking the token in the URL.
+ */
+export declare const WS_BEARER_SUBPROTOCOL = "10xgraph-bearer";
+/** Minimal constructor shape shared by the browser `WebSocket` and the Node `ws` package. */
+export type WebSocketImpl = new (url: string, protocols?: string | string[], options?: unknown) => WebSocket;
+/** The auth/transport fields the WS helpers read from a request context. */
+export interface WsAuthContext {
+    baseUrl: string;
+    authToken?: string | null;
+    auth?: TenxGraphAuth | null;
+    headers?: HeadersInit;
+    credentials?: RequestCredentials;
+    debug?: boolean;
+    /** Optional WebSocket implementation for runtimes without a global (Node < 21). */
+    webSocketImpl?: WebSocketImpl;
+}
+/**
+ * Resolve the bearer token with the same priority as `buildHeaders`.
+ *
+ * `auth` takes precedence over `authToken`, matching the HTTP path. When `auth`
+ * is set to a non-bearer scheme (basic/header) there is no bearer token to send,
+ * so this returns `null` rather than silently falling back to `authToken` — the
+ * HTTP path would not send a bearer in that case either.
+ */
+export declare function resolveBearerToken(context: Pick<WsAuthContext, 'authToken' | 'auth'>): string | null;
+/**
+ * Convert the HTTP base URL to a WebSocket URL and append `path`.
+ * The token is never placed in the URL — it travels via the `10xgraph-bearer`
+ * subprotocol (browser-safe) and, in Node, the Authorization header.
+ */
+export declare function buildWsUrl(context: Pick<WsAuthContext, 'baseUrl'>, path: string): string;
+/**
+ * Open a WebSocket with bearer auth.
+ *
+ * - If a token is present it is sent as the `10xgraph-bearer` subprotocol (works
+ *   in browsers and Node `ws`).
+ * - In Node-style implementations that accept a third `options` argument, the
+ *   Authorization header is also passed (ignored by browsers).
+ * - The implementation is taken from `context.webSocketImpl`, falling back to the
+ *   global `WebSocket`. If neither exists a descriptive error is thrown.
+ */
+export declare function openWebSocket(url: string, context: WsAuthContext): WebSocket;