@dvina/sdk 3.3.124

package/dist/client-CLhQragb.d.ts

@@ -0,0 +1,446 @@
+/**
+ * A single part of a multi-modal message content array.
+ */
+interface ContentPart {
+    type: 'text' | 'image_url';
+    text?: string;
+    image_url?: {
+        url: string;
+    };
+}
+/**
+ * A tool call requested by the assistant.
+ */
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * A tool definition that can be passed to the model.
+ */
+interface Tool {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+/**
+ * Tool choice configuration.
+ * - `'auto'`: model decides whether to call a tool
+ * - `'none'`: model never calls a tool
+ * - `'required'`: model must call a tool
+ * - `{ type: 'function'; function: { name } }`: model must call the specified tool
+ */
+type ToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+/**
+ * A single message in a chat conversation.
+ */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | ContentPart[];
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+/**
+ * Request body for POST /chat/completions (non-streaming).
+ */
+interface ChatCompletionRequest {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    max_completion_tokens?: number;
+    stream?: false;
+    tools?: Tool[];
+    tool_choice?: ToolChoice;
+}
+/**
+ * Request body for POST /chat/completions (streaming).
+ */
+interface ChatCompletionStreamRequest {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    max_completion_tokens?: number;
+    stream: true;
+    tools?: Tool[];
+    tool_choice?: ToolChoice;
+}
+/**
+ * Request body for POST /responses (non-streaming).
+ */
+interface ResponsesRequest {
+    model: string;
+    input: string | unknown[];
+    stream?: false;
+    instructions?: string;
+    temperature?: number;
+    max_output_tokens?: number;
+    tools?: unknown[];
+    tool_choice?: unknown;
+    reasoning?: {
+        effort?: string;
+        summary?: string;
+    };
+    text?: {
+        format?: unknown;
+    };
+    include?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Request body for POST /responses (streaming).
+ */
+interface ResponsesStreamRequest {
+    model: string;
+    input: string | unknown[];
+    stream: true;
+    instructions?: string;
+    temperature?: number;
+    max_output_tokens?: number;
+    tools?: unknown[];
+    tool_choice?: unknown;
+    reasoning?: {
+        effort?: string;
+        summary?: string;
+    };
+    text?: {
+        format?: unknown;
+    };
+    include?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Token usage statistics returned by the API.
+ */
+interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+/**
+ * A single choice in a non-streaming chat completion response.
+ */
+interface ChatCompletionChoice {
+    index: number;
+    message: {
+        role: string;
+        content: string | null;
+        tool_calls?: ToolCall[];
+    };
+    finish_reason: string;
+}
+/**
+ * Non-streaming chat completion response (OpenAI-compatible).
+ */
+interface ChatCompletionResponse {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage: Usage;
+}
+/**
+ * A delta object within a streaming chunk.
+ */
+interface StreamDelta {
+    role?: string;
+    content?: string;
+    tool_calls?: unknown[];
+}
+/**
+ * A single choice in a streaming chat completion chunk.
+ */
+interface StreamChunkChoice {
+    index: number;
+    delta: StreamDelta;
+    finish_reason: string | null;
+}
+/**
+ * A single SSE chunk during streaming chat completion.
+ */
+interface ChatCompletionChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: StreamChunkChoice[];
+    usage?: Usage;
+}
+/**
+ * A model object returned by the models endpoint.
+ */
+interface Model {
+    id: string;
+    object: 'model';
+    created: number;
+    owned_by: string;
+}
+/**
+ * Response from GET /models.
+ */
+interface ModelListResponse {
+    object: 'list';
+    data: Model[];
+}
+/**
+ * OpenAI-compatible error response body from the inference API.
+ */
+interface InferenceErrorResponse {
+    error: {
+        message: string;
+        type: string;
+        code: string;
+    };
+}
+/**
+ * Response from GET /health.
+ */
+interface HealthResponse {
+    status: 'ok';
+    models: number;
+    openaiHost: string;
+    anthropicHost: string;
+    apiVersion: string;
+    timestamp: number;
+}
+/**
+ * Options for creating an inference client.
+ */
+interface InferenceClientOptions {
+    /** Base URL for the inference API (e.g. 'https://api.dvina.ai/inference/v1'). */
+    baseUrl: string;
+    /**
+     * Static auth token. Use for scripts, CLI tools, and tests.
+     * Mutually exclusive with `getToken`.
+     */
+    token?: string;
+    /**
+     * Async callback that returns an auth token.
+     * When called with `{ forceRefresh: true }`, the callback must bypass any
+     * cache and obtain a brand-new token.
+     * Mutually exclusive with `token`.
+     */
+    getToken?: (options?: {
+        forceRefresh?: boolean;
+    }) => Promise<string>;
+    /** Custom headers to include in every request. */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds. Default: 120000 (2 minutes).
+     */
+    timeout?: number;
+}
+
+/**
+ * Parse a Server-Sent Events response body into an async iterable of typed chunks.
+ *
+ * Handles:
+ * - Chunked network reads (buffer splitting across `data:` boundaries)
+ * - `\r\n` and `\n` line endings
+ * - `data: [DONE]` termination signal
+ * - Mid-stream errors (yields what it can, then throws)
+ *
+ * @param body - A ReadableStream<Uint8Array> from a fetch response
+ * @returns An async iterable of parsed SSE data objects
+ */
+declare function parseSSEStream<T = ChatCompletionChunk>(body: ReadableStream<Uint8Array>): AsyncGenerator<T, void, undefined>;
+/**
+ * A chat completion stream that also aggregates the full response for convenience.
+ *
+ * Implements `AsyncIterable<ChatCompletionChunk>` for chunk-by-chunk processing,
+ * and provides helper methods to extract the final assembled text and usage.
+ *
+ * @example
+ * ```typescript
+ * const stream = await client.chat.completions.stream({ ... });
+ *
+ * // Option 1: Iterate chunk by chunk
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ * }
+ *
+ * // Option 2: Get aggregated result after iteration
+ * const text = stream.getText();
+ * const usage = stream.getUsage();
+ * ```
+ */
+declare class ChatCompletionStream implements AsyncIterable<ChatCompletionChunk> {
+    private readonly _chunks;
+    private readonly _source;
+    private _consumed;
+    constructor(source: AsyncGenerator<ChatCompletionChunk, void, undefined>);
+    [Symbol.asyncIterator](): AsyncIterator<ChatCompletionChunk>;
+    /**
+     * Concatenate all content deltas into a single string.
+     * Must be called after the stream has been fully consumed.
+     */
+    getText(): string;
+    /**
+     * Get the token usage from the final chunk (if the server included it).
+     * Must be called after the stream has been fully consumed.
+     */
+    getUsage(): {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    } | undefined;
+    /**
+     * Get the collected chunks array.
+     * Must be called after the stream has been fully consumed.
+     */
+    getChunks(): readonly ChatCompletionChunk[];
+}
+
+/**
+ * Namespaced chat completions API.
+ *
+ * @example
+ * ```typescript
+ * // Non-streaming
+ * const response = await sdk.inference.chat.completions.create({
+ *   model: 'claude-sonnet-4-6',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ *
+ * // Streaming
+ * const stream = await sdk.inference.chat.completions.stream({
+ *   model: 'claude-sonnet-4-6',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ * }
+ * ```
+ */
+interface ChatCompletions {
+    /** Create a non-streaming chat completion. */
+    create(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
+    /** Create a streaming chat completion. Returns an async iterable of chunks. */
+    stream(request: Omit<ChatCompletionStreamRequest, 'stream'>): Promise<ChatCompletionStream>;
+}
+interface Chat {
+    completions: ChatCompletions;
+}
+/**
+ * Namespaced responses API.
+ *
+ * @example
+ * ```typescript
+ * // Non-streaming
+ * const response = await sdk.inference.responses.create({
+ *   model: 'gpt-5.2',
+ *   input: 'Hello!',
+ * });
+ *
+ * // Streaming
+ * const stream = await sdk.inference.responses.stream({
+ *   model: 'gpt-5.2',
+ *   input: 'Hello!',
+ * });
+ * for await (const event of stream) {
+ *   console.log(event);
+ * }
+ * ```
+ */
+interface Responses {
+    /** Create a non-streaming response. */
+    create(request: ResponsesRequest): Promise<unknown>;
+    /** Create a streaming response. Returns a raw async iterable of SSE events. */
+    stream(request: Omit<ResponsesStreamRequest, 'stream'>): Promise<AsyncIterable<unknown>>;
+}
+/**
+ * Namespaced models API.
+ */
+interface Models {
+    /** List all available models. */
+    list(): Promise<ModelListResponse>;
+    /** Get a single model by ID. */
+    get(modelId: string): Promise<Model>;
+}
+/**
+ * The Dvina Inference client.
+ *
+ * Provides a typed interface to the `/inference/v1` REST API with full
+ * SSE streaming support. Follows the OpenAI client naming conventions
+ * (`sdk.inference.chat.completions`, `sdk.inference.responses`, `sdk.inference.models`).
+ *
+ * @example
+ * ```typescript
+ * const sdk = new DvinaSdk({ token: 'your-jwt-token' });
+ *
+ * // Chat completion
+ * const response = await sdk.inference.chat.completions.create({
+ *   model: 'claude-sonnet-4-6',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ *
+ * // Streaming
+ * const stream = await sdk.inference.chat.completions.stream({
+ *   model: 'claude-sonnet-4-6',
+ *   messages: [{ role: 'user', content: 'Tell me a story' }],
+ * });
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ * }
+ * ```
+ */
+interface InferenceClient {
+    chat: Chat;
+    responses: Responses;
+    models: Models;
+    /** Check the health of the inference API. */
+    health(): Promise<HealthResponse>;
+}
+/**
+ * Create an inference client using pre-resolved baseUrl and getToken from the SDK.
+ * This is the internal factory called by `createDvinaClient` — it does NOT resolve
+ * token/options itself, it receives them from the parent SDK client.
+ *
+ * @internal
+ */
+declare function createInferenceClientInternal(baseUrl: string, getToken: (options?: {
+    forceRefresh?: boolean;
+}) => Promise<string>, options?: {
+    headers?: Record<string, string>;
+    timeout?: number;
+}): InferenceClient;
+/**
+ * Create a standalone Dvina Inference client.
+ *
+ * Use this when you need inference without the full GraphQL SDK.
+ * For most cases, prefer `sdk.inference` which shares auth with the SDK.
+ *
+ * @param options - Client configuration (base URL, auth, headers, timeout)
+ * @returns A fully configured inference client
+ *
+ * @example
+ * ```typescript
+ * import { createInferenceClient } from '@dvina/sdk/inference';
+ *
+ * const client = createInferenceClient({
+ *   baseUrl: 'https://api.dvina.ai/inference/v1',
+ *   token: 'your-jwt-token',
+ * });
+ *
+ * const response = await client.chat.completions.create({
+ *   model: 'claude-sonnet-4-6',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ * ```
+ */
+declare function createInferenceClient(options: InferenceClientOptions): InferenceClient;
+
+export { type Chat as C, type HealthResponse as H, type InferenceClient as I, type Model as M, type Responses as R, type StreamChunkChoice as S, type Tool as T, type Usage as U, type ChatCompletionChoice as a, type ChatCompletionChunk as b, type ChatCompletionRequest as c, type ChatCompletionResponse as d, ChatCompletionStream as e, type ChatCompletionStreamRequest as f, type ChatCompletions as g, type ChatMessage as h, type ContentPart as i, type InferenceClientOptions as j, type InferenceErrorResponse as k, type ModelListResponse as l, type Models as m, type ResponsesRequest as n, type ResponsesStreamRequest as o, type StreamDelta as p, type ToolCall as q, type ToolChoice as r, createInferenceClient as s, createInferenceClientInternal as t, parseSSEStream as u };

package/dist/error-CsVoUTY8.d.cts

@@ -0,0 +1,95 @@
+/**
+ * Base error class for all Dvina SDK errors.
+ */
+declare class DvinaError extends Error {
+    /** The original error, if any */
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when the GraphQL response contains errors.
+ */
+declare class DvinaGraphQLError extends DvinaError {
+    /** The raw GraphQL errors array */
+    readonly errors: readonly GraphQLErrorEntry[];
+    /** The query that caused the error (for debugging) */
+    readonly query?: string;
+    /** The variables that were passed */
+    readonly variables?: Record<string, unknown>;
+    constructor(errors: readonly GraphQLErrorEntry[], query?: string, variables?: Record<string, unknown>);
+}
+/**
+ * Error thrown on network failures (connection refused, timeout, etc.)
+ */
+declare class DvinaNetworkError extends DvinaError {
+    /** HTTP status code, if available */
+    readonly status?: number;
+    constructor(message: string, status?: number, cause?: Error);
+}
+/**
+ * Error thrown when authentication fails (401/403).
+ */
+declare class DvinaAuthenticationError extends DvinaError {
+    /** The token that was used when the auth error occurred (for stale-token detection). */
+    readonly failedToken?: string;
+    constructor(message?: string, failedTokenOrCause?: string | Error, cause?: Error);
+}
+/**
+ * Known GraphQL error codes returned by the Dvina API in `extensions.code`.
+ * Used for programmatic matching in SDK error detection.
+ */
+declare const GRAPHQL_ERROR_CODES: {
+    readonly SESSION_TOKEN_LIMIT_REACHED: "SESSION_TOKEN_LIMIT_REACHED";
+    readonly STORAGE_LIMIT_REACHED: "STORAGE_LIMIT_REACHED";
+    readonly DEEP_ANALYSIS_LIMIT_EXCEEDED: "DEEP_ANALYSIS_LIMIT_EXCEEDED";
+    readonly PLAN_DETAIL_RESTRICTION: "PLAN_DETAIL_RESTRICTION";
+    readonly RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
+};
+/**
+ * Base class for plan/billing restriction errors.
+ * Thrown when the workspace exceeds a plan limit (storage, capabilities, deep analysis).
+ *
+ * Consumers can `catch (e) { if (e instanceof DvinaPlanRestrictionError) showUpgradeDialog(); }`
+ */
+declare class DvinaPlanRestrictionError extends DvinaGraphQLError {
+    /** The specific restriction code (e.g. 'PLAN_DETAIL_RESTRICTION') */
+    readonly restrictionCode: string;
+    constructor(errors: readonly GraphQLErrorEntry[], restrictionCode: string, query?: string, variables?: Record<string, unknown>);
+}
+/**
+ * Error thrown when the chat session token limit is reached (SESSION_TOKEN_LIMIT_REACHED).
+ * Distinct from inference quota — this is a per-session GraphQL limit.
+ */
+declare class DvinaTokenLimitError extends DvinaGraphQLError {
+    constructor(errors: readonly GraphQLErrorEntry[], query?: string, variables?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a requested resource is not found (RESOURCE_NOT_FOUND).
+ */
+declare class DvinaNotFoundError extends DvinaGraphQLError {
+    constructor(errors: readonly GraphQLErrorEntry[], query?: string, variables?: Record<string, unknown>);
+}
+/**
+ * Extract the first extension code from a list of GraphQL errors (normalized to uppercase).
+ * Returns `undefined` if no code is present.
+ */
+declare function extractErrorCode(errors: readonly GraphQLErrorEntry[]): string | undefined;
+/**
+ * Create the appropriate `DvinaGraphQLError` subclass for the given errors,
+ * or return a generic `DvinaGraphQLError` if no specific match is found.
+ */
+declare function createGraphQLError(errors: readonly GraphQLErrorEntry[], query?: string, variables?: Record<string, unknown>): DvinaGraphQLError;
+/**
+ * Shape of a single GraphQL error in the response.
+ */
+interface GraphQLErrorEntry {
+    message: string;
+    locations?: readonly {
+        line: number;
+        column: number;
+    }[];
+    path?: readonly (string | number)[];
+    extensions?: Record<string, unknown>;
+}
+
+export { DvinaError as D, GRAPHQL_ERROR_CODES as G, DvinaAuthenticationError as a, DvinaGraphQLError as b, DvinaNetworkError as c, DvinaNotFoundError as d, DvinaPlanRestrictionError as e, DvinaTokenLimitError as f, type GraphQLErrorEntry as g, createGraphQLError as h, extractErrorCode as i };

package/dist/error-CsVoUTY8.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Base error class for all Dvina SDK errors.
+ */
+declare class DvinaError extends Error {
+    /** The original error, if any */
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when the GraphQL response contains errors.
+ */
+declare class DvinaGraphQLError extends DvinaError {
+    /** The raw GraphQL errors array */
+    readonly errors: readonly GraphQLErrorEntry[];
+    /** The query that caused the error (for debugging) */
+    readonly query?: string;
+    /** The variables that were passed */
+    readonly variables?: Record<string, unknown>;
+    constructor(errors: readonly GraphQLErrorEntry[], query?: string, variables?: Record<string, unknown>);
+}
+/**
+ * Error thrown on network failures (connection refused, timeout, etc.)
+ */
+declare class DvinaNetworkError extends DvinaError {
+    /** HTTP status code, if available */
+    readonly status?: number;
+    constructor(message: string, status?: number, cause?: Error);
+}
+/**
+ * Error thrown when authentication fails (401/403).
+ */
+declare class DvinaAuthenticationError extends DvinaError {
+    /** The token that was used when the auth error occurred (for stale-token detection). */
+    readonly failedToken?: string;
+    constructor(message?: string, failedTokenOrCause?: string | Error, cause?: Error);
+}
+/**
+ * Known GraphQL error codes returned by the Dvina API in `extensions.code`.
+ * Used for programmatic matching in SDK error detection.
+ */
+declare const GRAPHQL_ERROR_CODES: {
+    readonly SESSION_TOKEN_LIMIT_REACHED: "SESSION_TOKEN_LIMIT_REACHED";
+    readonly STORAGE_LIMIT_REACHED: "STORAGE_LIMIT_REACHED";
+    readonly DEEP_ANALYSIS_LIMIT_EXCEEDED: "DEEP_ANALYSIS_LIMIT_EXCEEDED";
+    readonly PLAN_DETAIL_RESTRICTION: "PLAN_DETAIL_RESTRICTION";
+    readonly RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
+};
+/**
+ * Base class for plan/billing restriction errors.
+ * Thrown when the workspace exceeds a plan limit (storage, capabilities, deep analysis).
+ *
+ * Consumers can `catch (e) { if (e instanceof DvinaPlanRestrictionError) showUpgradeDialog(); }`
+ */
+declare class DvinaPlanRestrictionError extends DvinaGraphQLError {
+    /** The specific restriction code (e.g. 'PLAN_DETAIL_RESTRICTION') */
+    readonly restrictionCode: string;
+    constructor(errors: readonly GraphQLErrorEntry[], restrictionCode: string, query?: string, variables?: Record<string, unknown>);
+}
+/**
+ * Error thrown when the chat session token limit is reached (SESSION_TOKEN_LIMIT_REACHED).
+ * Distinct from inference quota — this is a per-session GraphQL limit.
+ */
+declare class DvinaTokenLimitError extends DvinaGraphQLError {
+    constructor(errors: readonly GraphQLErrorEntry[], query?: string, variables?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a requested resource is not found (RESOURCE_NOT_FOUND).
+ */
+declare class DvinaNotFoundError extends DvinaGraphQLError {
+    constructor(errors: readonly GraphQLErrorEntry[], query?: string, variables?: Record<string, unknown>);
+}
+/**
+ * Extract the first extension code from a list of GraphQL errors (normalized to uppercase).
+ * Returns `undefined` if no code is present.
+ */
+declare function extractErrorCode(errors: readonly GraphQLErrorEntry[]): string | undefined;
+/**
+ * Create the appropriate `DvinaGraphQLError` subclass for the given errors,
+ * or return a generic `DvinaGraphQLError` if no specific match is found.
+ */
+declare function createGraphQLError(errors: readonly GraphQLErrorEntry[], query?: string, variables?: Record<string, unknown>): DvinaGraphQLError;
+/**
+ * Shape of a single GraphQL error in the response.
+ */
+interface GraphQLErrorEntry {
+    message: string;
+    locations?: readonly {
+        line: number;
+        column: number;
+    }[];
+    path?: readonly (string | number)[];
+    extensions?: Record<string, unknown>;
+}
+
+export { DvinaError as D, GRAPHQL_ERROR_CODES as G, DvinaAuthenticationError as a, DvinaGraphQLError as b, DvinaNetworkError as c, DvinaNotFoundError as d, DvinaPlanRestrictionError as e, DvinaTokenLimitError as f, type GraphQLErrorEntry as g, createGraphQLError as h, extractErrorCode as i };