aura-llm 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,371 @@
+/**
+ * Aura SDK error hierarchy.
+ *
+ * Mirrors the Python SDK's `exceptions.py`:
+ *   AuraError
+ *   ├── APIError                (errors returned by the gateway)
+ *   │   ├── AuthenticationError (401)
+ *   │   ├── BadRequestError     (400)
+ *   │   ├── NotFoundError       (404)
+ *   │   └── RateLimitError      (429, carries retryAfter)
+ *   ├── APIConnectionError      (network failure)
+ *   └── APITimeoutError         (exceeded the configured timeout)
+ *
+ * Use `instanceof` to branch on error class.
+ */
+interface AuraErrorOptions {
+    code?: string;
+    param?: string;
+    status?: number;
+    requestId?: string;
+    responseBody?: unknown;
+}
+/** Base class for every error thrown by the SDK. */
+declare class AuraError extends Error {
+    /** Gateway error code (e.g. `invalid_model`), when present. */
+    readonly code?: string;
+    /** Offending request parameter, when the gateway reports one. */
+    readonly param?: string;
+    /** HTTP status code, when the error originated from a response. */
+    readonly status?: number;
+    /** Gateway request id for support/correlation, when present. */
+    readonly requestId?: string;
+    /** Raw parsed response body, for debugging. */
+    readonly responseBody?: unknown;
+    constructor(message: string, options?: AuraErrorOptions);
+}
+/** An error returned by the Aura API (any non-2xx with a parseable body). */
+declare class APIError extends AuraError {
+}
+/** 401 — invalid or missing API key. */
+declare class AuthenticationError extends APIError {
+    constructor(message?: string, options?: AuraErrorOptions);
+}
+/** 400 — the request was malformed or invalid. */
+declare class BadRequestError extends APIError {
+    constructor(message: string, options?: AuraErrorOptions);
+}
+/** 404 — resource not found (e.g. an unknown model). */
+declare class NotFoundError extends APIError {
+    constructor(message: string, options?: AuraErrorOptions);
+}
+/** 429 — rate limit exceeded. */
+declare class RateLimitError extends APIError {
+    /** Seconds to wait before retrying, from the `Retry-After` header. */
+    readonly retryAfter?: number;
+    constructor(message?: string, options?: AuraErrorOptions & {
+        retryAfter?: number;
+    });
+}
+/** Failed to connect to the gateway (DNS, refused, reset, …). */
+declare class APIConnectionError extends AuraError {
+    constructor(message?: string, options?: AuraErrorOptions);
+}
+/** The request exceeded the configured `timeout`. */
+declare class APITimeoutError extends AuraError {
+    constructor(message?: string, options?: AuraErrorOptions);
+}
+
+/**
+ * Open Responses API types, ported from the Python SDK's `types.py`.
+ *
+ * These are plain TypeScript interfaces/unions (the gateway returns JSON; we
+ * don't validate at runtime beyond shape-narrowing on `type`). Helper
+ * functions (`outputText`, `toolCalls`) replace the Python `@property`
+ * accessors, since interfaces can't carry methods.
+ */
+type ResponseStatus = 'in_progress' | 'completed' | 'failed' | 'incomplete' | 'cancelled';
+type ItemType = 'message' | 'function_call' | 'function_call_output' | 'reasoning';
+type Role = 'user' | 'assistant' | 'system';
+interface TextContent {
+    type: 'text';
+    text: string;
+}
+interface ImageContent {
+    type: 'image';
+    url?: string;
+    base64?: string;
+    media_type?: string;
+}
+type Content = TextContent | ImageContent;
+interface MessageItem {
+    type: 'message';
+    id?: string;
+    role: Role;
+    content: Content[];
+    status?: string;
+}
+interface FunctionCallItem {
+    type: 'function_call';
+    id?: string;
+    call_id: string;
+    name: string;
+    arguments: string;
+    status?: string;
+}
+interface FunctionCallOutputItem {
+    type: 'function_call_output';
+    id?: string;
+    call_id: string;
+    output: string;
+}
+interface ReasoningItem {
+    type: 'reasoning';
+    id?: string;
+    content: TextContent[];
+    status?: string;
+}
+type Item = MessageItem | FunctionCallItem | FunctionCallOutputItem | ReasoningItem;
+interface FunctionDefinition {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+interface Tool {
+    type: 'function';
+    function: FunctionDefinition;
+}
+/** Convenience builder for a function tool (mirrors Tool.function_tool). */
+declare function functionTool(name: string, description?: string, parameters?: Record<string, unknown>): Tool;
+interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    input_tokens_details?: Record<string, number>;
+    output_tokens_details?: Record<string, number>;
+    cost_usd?: number;
+}
+interface ResponseError {
+    code: string;
+    message: string;
+    param?: string;
+}
+interface AuraMetadata {
+    request_id?: string;
+    model?: string;
+    provider?: string;
+    gateway_version?: string;
+    latency_ms?: number;
+    agentic?: Record<string, unknown>;
+}
+interface ResponseMetadata {
+    aura?: AuraMetadata;
+}
+interface Response {
+    id: string;
+    object: 'response';
+    created_at: number;
+    status: ResponseStatus;
+    model: string;
+    output: Item[];
+    usage?: Usage;
+    error?: ResponseError;
+    metadata?: ResponseMetadata;
+    previous_response_id?: string;
+    conversation_id?: string;
+}
+/** Text from the first assistant message output item ('' if none). */
+declare function outputText(response: Response): string;
+/** All function-call items in the output. */
+declare function toolCalls(response: Response): FunctionCallItem[];
+declare const hasToolCalls: (r: Response) => boolean;
+declare const isComplete: (r: Response) => boolean;
+declare const isFailed: (r: Response) => boolean;
+interface StreamEventBase {
+    type: string;
+    sequence?: number;
+}
+interface ResponseCreatedEvent extends StreamEventBase {
+    type: 'response.created';
+    response: Response;
+}
+interface ResponseInProgressEvent extends StreamEventBase {
+    type: 'response.in_progress';
+    response: Response;
+}
+interface ResponseCompletedEvent extends StreamEventBase {
+    type: 'response.completed';
+    response: Response;
+}
+interface ResponseFailedEvent extends StreamEventBase {
+    type: 'response.failed';
+    response: Response;
+}
+interface OutputItemAddedEvent extends StreamEventBase {
+    type: 'response.output_item.added';
+    item: Item;
+    output_index: number;
+}
+interface OutputItemDoneEvent extends StreamEventBase {
+    type: 'response.output_item.done';
+    item: Item;
+    output_index: number;
+}
+interface TextDeltaEvent extends StreamEventBase {
+    type: 'response.output_text.delta';
+    delta: string;
+    output_index: number;
+    content_index: number;
+}
+interface TextDoneEvent extends StreamEventBase {
+    type: 'response.output_text.done';
+    text: string;
+    output_index: number;
+    content_index: number;
+}
+interface FunctionCallDeltaEvent extends StreamEventBase {
+    type: 'response.function_call.delta';
+    delta: string;
+    output_index: number;
+    call_id: string;
+}
+interface FunctionCallDoneEvent extends StreamEventBase {
+    type: 'response.function_call.done';
+    item: FunctionCallItem;
+    output_index: number;
+}
+interface ErrorEvent extends StreamEventBase {
+    type: 'error';
+    error: ResponseError;
+}
+type StreamEvent = ResponseCreatedEvent | ResponseInProgressEvent | ResponseCompletedEvent | ResponseFailedEvent | OutputItemAddedEvent | OutputItemDoneEvent | TextDeltaEvent | TextDoneEvent | FunctionCallDeltaEvent | FunctionCallDoneEvent | ErrorEvent;
+/** All recognized stream event type strings. */
+declare const STREAM_EVENT_TYPES: Set<string>;
+interface InputMessage {
+    role: Role;
+    content: string | Content[];
+}
+declare const userMessage: (content: string) => InputMessage;
+declare const assistantMessage: (content: string) => InputMessage;
+declare const systemMessage: (content: string) => InputMessage;
+interface CompressionConfig {
+    strategy?: string;
+    auto_select?: boolean;
+    [key: string]: unknown;
+}
+interface ValidationConfig {
+    strategy?: string;
+    n?: number;
+    min_confidence?: number;
+    [key: string]: unknown;
+}
+interface ConsistencyConfig {
+    style_profile?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * AuraClient — the TypeScript client for the Aura LLM Gateway.
+ *
+ * Single client (no sync/async split — JS is async by default). Everything
+ * returns a Promise; `create({ stream: true })` returns an AsyncIterable of
+ * `StreamEvent`. Universal: uses global `fetch` + Web Streams, so it runs on
+ * Node 20+, browsers, Deno, Bun, and edge runtimes with no Node-only deps.
+ */
+
+declare const DEFAULT_BASE_URL = "http://localhost:8080";
+declare const DEFAULT_TIMEOUT = 60000;
+declare const DEFAULT_MAX_RETRIES = 2;
+type FetchFn = typeof fetch;
+interface AuraClientOptions {
+    /** API key. Falls back to `AURA_API_KEY` env var (Node/Deno/Bun). */
+    apiKey?: string;
+    /** Gateway base URL. Falls back to `AURA_BASE_URL`, then localhost:8080. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds (default 60000). */
+    timeout?: number;
+    /** Max retries for retryable failures (default 2; 0 disables). */
+    maxRetries?: number;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Custom fetch implementation (injection for edge runtimes / tests). */
+    fetch?: FetchFn;
+    /** Lifecycle hooks. */
+    onRequest?: (req: {
+        method: string;
+        url: string;
+        headers: Headers;
+    }) => void;
+    onResponse?: (res: {
+        status: number;
+        url: string;
+    }, durationMs: number) => void;
+    onError?: (err: AuraError) => void;
+}
+interface ResponseCreateParams {
+    model: string;
+    input: string | InputMessage[] | Array<Record<string, unknown>>;
+    instructions?: string;
+    tools?: Tool[];
+    tool_choice?: string;
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    previous_response_id?: string;
+    /** End-user identifier for multi-tenant cost tracking. */
+    user?: string;
+    compression?: CompressionConfig;
+    validation?: ValidationConfig;
+    consistency?: ConsistencyConfig;
+    /** Escape hatch for params not yet typed. */
+    [key: string]: unknown;
+}
+/** Responses API resource. */
+declare class Responses {
+    private readonly client;
+    constructor(client: AuraClient);
+    /** Create a non-streaming response. */
+    create(params: ResponseCreateParams & {
+        stream?: false;
+    }): Promise<Response>;
+    /** Create a streaming response (AsyncIterable of events). */
+    create(params: ResponseCreateParams & {
+        stream: true;
+    }): Promise<AsyncIterable<StreamEvent>>;
+    private buildPayload;
+}
+declare class AuraClient {
+    readonly baseUrl: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    readonly responses: Responses;
+    private readonly apiKey;
+    private readonly headers;
+    private readonly fetchFn;
+    private readonly opts;
+    constructor(options?: AuraClientOptions);
+    /** Build an absolute URL + Headers for a request. */
+    private prepare;
+    /** Exponential backoff with jitter, capped at 30s; honors Retry-After. */
+    private backoffMs;
+    /** Non-streaming JSON request with retry + typed error mapping. */
+    _request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /**
+     * Streaming request → AsyncIterable<StreamEvent>. Streams are NOT retried
+     * (re-issuing a partial stream would replay events); errors before the
+     * first byte still surface as typed errors.
+     */
+    _stream(path: string, body: unknown): Promise<AsyncIterable<StreamEvent>>;
+    /** Map a thrown fetch error to a typed AuraError, or null if not ours. */
+    private mapNetworkError;
+}
+
+/**
+ * Server-Sent Events parsing for the streaming Responses API.
+ *
+ * Consumes a `ReadableStream<Uint8Array>` (from `fetch` `response.body`) and
+ * yields typed `StreamEvent`s as an AsyncIterable — the idiomatic TS shape for
+ * `for await (const event of stream)`. Mirrors the Python SDK's
+ * `_parse_sse_stream` / `_parse_sse_event` / `_parse_event_data`.
+ */
+
+/** Parse one SSE block ("event:" / "data:" lines) into a StreamEvent. */
+declare function parseSSEChunk(chunk: string): StreamEvent | null;
+/**
+ * Turn a byte stream of SSE into an AsyncIterable of events.
+ * Splits on the SSE record separator ("\n\n") and decodes incrementally,
+ * giving the caller full back-pressure (we only read as fast as consumed).
+ */
+declare function parseSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<StreamEvent, void, unknown>;
+
+export { APIConnectionError, APIError, APITimeoutError, AuraClient, type AuraClientOptions, AuraError, type AuraErrorOptions, type AuraMetadata, AuthenticationError, BadRequestError, type CompressionConfig, type ConsistencyConfig, type Content, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, type ErrorEvent, type FunctionCallDeltaEvent, type FunctionCallDoneEvent, type FunctionCallItem, type FunctionCallOutputItem, type FunctionDefinition, type ImageContent, type InputMessage, type Item, type ItemType, type MessageItem, NotFoundError, type OutputItemAddedEvent, type OutputItemDoneEvent, RateLimitError, type ReasoningItem, type Response, type ResponseCompletedEvent, type ResponseCreateParams, type ResponseCreatedEvent, type ResponseError, type ResponseFailedEvent, type ResponseInProgressEvent, type ResponseMetadata, type ResponseStatus, Responses, type Role, STREAM_EVENT_TYPES, type StreamEvent, type TextContent, type TextDeltaEvent, type TextDoneEvent, type Tool, type Usage, type ValidationConfig, assistantMessage, functionTool, hasToolCalls, isComplete, isFailed, outputText, parseSSE, parseSSEChunk, systemMessage, toolCalls, userMessage };