addisai 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,718 @@
+type FetchLike = typeof fetch;
+interface TransportConfig {
+    apiKey: string;
+    baseURL: string;
+    timeout: number;
+    maxRetries: number;
+    defaultHeaders: Record<string, string>;
+    defaultQuery: Record<string, string>;
+    fetch: FetchLike;
+    logLevel: LogLevel;
+}
+type LogLevel = "off" | "error" | "warn" | "info" | "debug";
+/** Per-request options accepted by every resource method. */
+interface RequestOptions {
+    timeout?: number;
+    maxRetries?: number;
+    signal?: AbortSignal;
+    idempotencyKey?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+}
+interface InternalRequest {
+    method: "GET" | "POST" | "DELETE" | "PUT" | "PATCH" | "HEAD";
+    path: string;
+    query?: Record<string, unknown>;
+    /** JSON body (mutually exclusive with `form`). */
+    body?: unknown;
+    /** multipart/form-data body (mutually exclusive with `body`). */
+    form?: FormData;
+    /** Return the raw Response (for streaming or binary) instead of parsed JSON. */
+    raw?: boolean;
+    /** Minimum effective timeout in ms (e.g. paid synthesis budget). */
+    timeoutFloor?: number;
+}
+declare class Transport {
+    private readonly config;
+    constructor(config: TransportConfig);
+    /** The configured fetch implementation, for direct asset downloads. */
+    get fetch(): FetchLike;
+    private log;
+    private buildURL;
+    private buildHeaders;
+    private isRetryable;
+    private retryDelayMs;
+    request<T>(req: InternalRequest, opts?: RequestOptions): Promise<T>;
+    /**
+     * Open a streaming request: a single fetch (streams are not retried once
+     * started), with the timeout guarding only the initial response. The returned
+     * controller stays live so the caller can cancel the body mid-stream.
+     */
+    openStream(req: InternalRequest, opts?: RequestOptions): Promise<{
+        response: Response;
+        controller: AbortController;
+    }>;
+    private parseJSON;
+    private toError;
+}
+
+/**
+ * An OpenAI-style streaming chat response. It is async-iterable (`for await`),
+ * and provides convenience accumulators and cancellation.
+ */
+declare class ChatStream implements AsyncIterable<ChatCompletionChunk> {
+    private readonly response;
+    private readonly controller?;
+    /** Transcription, if the request included audio input. */
+    transcription?: {
+        raw?: string;
+        clean?: string;
+    };
+    private readonly id;
+    private readonly created;
+    private consumed;
+    private finalUsage;
+    constructor(response: Response, controller?: AbortController | undefined);
+    /** Cancel the stream and underlying request. */
+    abort(): void;
+    [Symbol.asyncIterator](): AsyncIterator<ChatCompletionChunk>;
+    /** Consume the stream and return the concatenated assistant text. */
+    finalText(): Promise<string>;
+    /** Consume the stream and return an assembled non-streaming completion. */
+    finalCompletion(): Promise<ChatCompletion>;
+    /** Re-encode the stream as a byte ReadableStream of SSE chunks (for piping). */
+    toReadableStream(): ReadableStream<Uint8Array>;
+}
+
+type Uploadable = Blob | ArrayBuffer | ArrayBufferView | FileInput;
+interface FileInput {
+    /** Raw bytes or a Blob. */
+    data: Blob | ArrayBuffer | ArrayBufferView;
+    /** Filename sent to the API; helps the server infer format. */
+    filename?: string;
+    /** MIME type, e.g. "audio/wav". Strongly recommended. */
+    contentType?: string;
+}
+/**
+ * Read a file from disk into a FileInput (Node/Bun/Deno only). Convenience for
+ * `audio: await fileFromPath("./call.wav")`.
+ */
+declare function fileFromPath(path: string, contentType?: string): Promise<FileInput>;
+
+/** Languages supported for generation/chat. */
+type Language = "am" | "om";
+/** Languages supported for speech-to-text. */
+type SttLanguage = "am" | "om" | "en" | "ha" | "sw";
+/** Languages supported for translation. */
+type TranslateLanguage = "am" | "om" | "en";
+/** TTS output formats. `pcm_16000` is delivered as a WAV container. */
+type OutputFormat = "mp3_44100" | "wav_44100" | "pcm_16000";
+
+/** Public model identifier surfaced to developers. Never the underlying model. */
+declare const ADDIS_CHAT_MODEL = "addis-1-alef";
+type ChatRole = "system" | "developer" | "user" | "assistant" | "tool";
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+    /** Opaque provider state. Managed by the SDK; echo it back unchanged. */
+    addis_tool_state?: string;
+}
+interface ChatCompletionMessage {
+    role: ChatRole;
+    content?: string | null;
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+interface FunctionTool {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+/** A tool whose implementation the SDK will execute during `chat.runTools`. */
+interface RunnableTool {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+        /** Local implementation invoked with the parsed arguments. */
+        function: (args: any) => unknown | Promise<unknown>;
+    };
+}
+type ToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
+interface ChatAttachment {
+    /** A field name used for the multipart upload (defaults to "attachment_N"). */
+    name?: string;
+    file: Uploadable;
+}
+interface ChatCompletionCreateParams {
+    /** Accepted for OpenAI compatibility. Addis selects the model internally. */
+    model?: string;
+    messages: ChatCompletionMessage[];
+    /** Target language. "am" (Amharic) or "om" (Afan Oromo). Default "am". */
+    language?: Language;
+    /** Extra behaviour instructions (tone/format). Does not change identity. */
+    system?: string;
+    /** Replaces the assistant identity for branded apps. */
+    persona?: string;
+    temperature?: number;
+    max_tokens?: number;
+    tools?: FunctionTool[];
+    tool_choice?: ToolChoice;
+    /** Beta: stream tokens. Not available with tools. */
+    stream?: boolean;
+    /** Files/images/documents to attach to the final user message. */
+    attachments?: ChatAttachment[];
+    /** Audio voice-command input; transcribed server-side. */
+    audio?: Uploadable;
+}
+interface ChatUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface ChatCompletionChoice {
+    index: number;
+    message: ChatCompletionMessage;
+    finish_reason: string | null;
+}
+interface ChatCompletion {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage?: ChatUsage;
+    /** Present when audio input was transcribed. */
+    transcription?: {
+        raw?: string;
+        clean?: string;
+    };
+    /** Uploaded attachment URIs to reuse in later turns. */
+    uploaded_attachments?: {
+        fileUri: string;
+        mimeType: string;
+    }[];
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: "assistant";
+            content?: string;
+        };
+        finish_reason: string | null;
+    }>;
+}
+declare class Chat {
+    private readonly transport;
+    readonly completions: Completions;
+    constructor(transport: Transport);
+    /**
+     * Run an automatic tool-calling loop: the model requests tools, the SDK
+     * executes your local implementations, feeds results back, and repeats until
+     * the model produces a final answer.
+     */
+    runTools(params: Omit<ChatCompletionCreateParams, "tools" | "stream"> & {
+        tools: RunnableTool[];
+        maxToolRoundtrips?: number;
+    }, opts?: RequestOptions): Promise<ChatCompletion>;
+}
+declare class Completions {
+    private readonly transport;
+    constructor(transport: Transport);
+    create(params: ChatCompletionCreateParams & {
+        stream: true;
+    }, opts?: RequestOptions): Promise<ChatStream>;
+    create(params: ChatCompletionCreateParams & {
+        stream?: false;
+    }, opts?: RequestOptions): Promise<ChatCompletion>;
+    private createStream;
+    private createMultipart;
+}
+
+interface Page<T> {
+    data: T[];
+    nextCursor: string | null;
+    limit: number | null;
+}
+declare class CursorPage<T> implements AsyncIterable<T> {
+    private readonly firstPage;
+    private readonly fetchPage;
+    constructor(firstPage: Page<T>, fetchPage: (cursor: string) => Promise<Page<T>>);
+    /** Items on the first page only. */
+    get data(): T[];
+    get nextCursor(): string | null;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+/**
+ * A pending page that is BOTH awaitable (`await list()` → CursorPage) and
+ * async-iterable (`for await (const item of list())` → items across all pages).
+ * Lets `list()` be used either way without the caller needing to await first.
+ */
+declare class CursorPagePromise<T> implements PromiseLike<CursorPage<T>>, AsyncIterable<T> {
+    private readonly load;
+    private promise?;
+    constructor(load: () => Promise<CursorPage<T>>);
+    private get inner();
+    then<TResult1 = CursorPage<T>, TResult2 = never>(onfulfilled?: ((value: CursorPage<T>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<CursorPage<T> | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<CursorPage<T>>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+
+interface ClipUsage {
+    pricingUnit: "character";
+    pricePer1000Characters: number;
+    creditsUsed: number | null;
+    creditsRemaining: number | null;
+    currency: string;
+}
+interface ClipMeta {
+    /** Voice settings the request sent that the engine did not apply. */
+    ignoredVoiceSettings: string[];
+    /** True when this result was replayed from a prior identical request (no new billing). */
+    idempotentReplay: boolean;
+}
+interface ClipData {
+    id: string;
+    text: string;
+    textPreview: string;
+    voiceId: string;
+    voiceName: string;
+    voiceDescriptor: string;
+    language: Language;
+    outputFormat: OutputFormat;
+    audioUrl: string;
+    mimeType: string;
+    durationSeconds: number | null;
+    characterCount: number;
+    billableCharacters: number;
+    downloadName: string;
+    createdAt: string;
+    usage?: ClipUsage;
+    meta?: ClipMeta;
+    /** The idempotency key used for this generation. */
+    clientRequestId?: string;
+}
+/**
+ * A generated audio clip. Exposes the signed playback URL plus convenience
+ * helpers to fetch the bytes or write them to disk.
+ */
+declare class AddisClip implements ClipData {
+    private readonly fetchImpl;
+    readonly id: string;
+    readonly text: string;
+    readonly textPreview: string;
+    readonly voiceId: string;
+    readonly voiceName: string;
+    readonly voiceDescriptor: string;
+    readonly language: Language;
+    readonly outputFormat: OutputFormat;
+    readonly audioUrl: string;
+    readonly mimeType: string;
+    readonly durationSeconds: number | null;
+    readonly characterCount: number;
+    readonly billableCharacters: number;
+    readonly downloadName: string;
+    readonly createdAt: string;
+    readonly usage?: ClipUsage;
+    readonly meta?: ClipMeta;
+    readonly clientRequestId?: string;
+    constructor(data: ClipData, fetchImpl: FetchLike);
+    /** Fetch the audio bytes from the signed playback URL. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Write the audio to a file on disk (Node/Bun/Deno). */
+    toFile(path: string): Promise<void>;
+}
+
+/**
+ * A stream of audio byte chunks. Async-iterable (`for await` yields
+ * `Uint8Array`), with helpers to collect or save the audio. Normalizes the two
+ * legacy stream encodings (newline-delimited base64 JSON chunks, or a raw audio
+ * byte stream) into a single byte stream.
+ */
+declare class AudioStream implements AsyncIterable<Uint8Array> {
+    private readonly response;
+    private readonly mode;
+    private readonly controller?;
+    private consumed;
+    constructor(response: Response, mode: "ndjson" | "raw", controller?: AbortController | undefined);
+    static fromResponse(response: Response, controller?: AbortController): AudioStream;
+    /** Cancel the stream and underlying request. */
+    abort(): void;
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+    /** Collect every chunk into a single ArrayBuffer. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Stream the audio to a file on disk (Node/Bun/Deno). */
+    toFile(path: string): Promise<void>;
+}
+
+/** ElevenLabs-style voice controls, expressed on a 0–100 scale. */
+interface VoiceSettings {
+    speed?: number;
+    stability?: number;
+    similarity?: number;
+    style?: number;
+}
+interface VoiceGenerateParams {
+    voiceId: string;
+    text: string;
+    language: Language;
+    /** Default "mp3_44100". */
+    outputFormat?: OutputFormat;
+    voiceSettings?: VoiceSettings;
+    /**
+     * Idempotency key. Auto-generated if omitted and reused across retries so a
+     * retried request is never billed twice. Reusing a key with changed inputs
+     * raises IdempotencyConflictError.
+     */
+    clientRequestId?: string;
+}
+interface VoiceEstimateParams {
+    voiceId: string;
+    text: string;
+    language: Language;
+    outputFormat?: OutputFormat;
+}
+interface VoiceEstimate {
+    characterCount: number;
+    billableCharacters: number;
+    pricingUnit: "character";
+    pricePer1000Characters: number;
+    estimatedCost: number;
+    currency: string;
+    currentBalance: number;
+    estimatedBalanceAfter: number;
+    canGenerate: boolean;
+}
+interface VoiceUsage {
+    walletId: string;
+    balance: number;
+    formattedBalance: string;
+    currency: string;
+    lastDeductionAt: string | null;
+    totalSpend: number;
+    formattedTotalSpend: string;
+    maxTtsCharacters: number;
+    pricing: {
+        unit: string;
+        pricePer1000Characters: number;
+        minimumCharge: number;
+        currency: string;
+    };
+    budget: unknown | null;
+}
+interface ClipListParams {
+    limit?: number;
+    cursor?: string;
+    language?: Language;
+    voiceId?: string;
+}
+declare class Voice {
+    private readonly transport;
+    readonly clips: Clips;
+    constructor(transport: Transport);
+    /** Synthesize speech and return the generated clip. */
+    generate(params: VoiceGenerateParams, opts?: RequestOptions): Promise<AddisClip>;
+    /**
+     * Streaming synthesis. The surface is stable for when the API enables it;
+     * until then it raises NotSupportedError. Use {@link Voice.generate} today.
+     */
+    stream(_params: VoiceGenerateParams, _opts?: RequestOptions): Promise<AudioStream>;
+    /** Pre-flight cost estimate (and whether the wallet can cover it). */
+    estimate(params: VoiceEstimateParams, opts?: RequestOptions): Promise<VoiceEstimate>;
+    /** Wallet balance and pricing for voice generation. */
+    usage(opts?: RequestOptions): Promise<VoiceUsage>;
+}
+declare class Clips {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * List generated clips. The returned value is both awaitable
+     * (`const page = await clips.list()`) and async-iterable
+     * (`for await (const clip of clips.list())` walks every page).
+     */
+    list(params?: ClipListParams, opts?: RequestOptions): CursorPagePromise<AddisClip>;
+    /** Fetch one clip by ID. */
+    get(clipId: string, opts?: RequestOptions): Promise<AddisClip>;
+    /** Download the audio bytes for a clip. */
+    download(clipId: string, opts?: RequestOptions): Promise<ArrayBuffer>;
+    /** Delete a clip. */
+    delete(clipId: string, opts?: RequestOptions): Promise<void>;
+}
+
+interface VoiceCatalogEntry {
+    id: string;
+    name: string;
+    descriptor: string;
+    language: Language;
+    gender: string;
+    style: string;
+    scriptChip: string;
+    tags: string[];
+    previewAudioUrl: string | null;
+    previewMimeType: string | null;
+    previewDurationSeconds: number | null;
+    isDefault: boolean;
+    isAvailable: boolean;
+    sortOrder: number;
+}
+interface VoiceListParams {
+    language?: Language;
+    gender?: "female" | "male";
+    search?: string;
+    includeUnavailable?: boolean;
+}
+interface VoicePreview {
+    voiceId: string;
+    audioUrl: string | null;
+    audio: string | null;
+    mimeType: string | null;
+    durationSeconds: number | null;
+    downloadName: string;
+}
+declare class Voices {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List the voice catalog. */
+    list(params?: VoiceListParams, opts?: RequestOptions): Promise<VoiceCatalogEntry[]>;
+    /** Fetch a single voice's preview clip metadata. */
+    preview(voiceId: string, opts?: RequestOptions): Promise<VoicePreview>;
+}
+
+interface TranscribeParams {
+    /** Audio input. Buffer/Blob/Uint8Array, or a FileInput descriptor. Max 25 MB / 120 s. */
+    audio: Uploadable;
+    /** Language of the audio: "am" | "om" | "en" | "ha" | "sw". */
+    language: SttLanguage;
+}
+interface Transcription {
+    text: string;
+    confidence: number | null;
+    usage: unknown;
+}
+declare class Speech {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Transcribe speech to text. */
+    transcribe(params: TranscribeParams, opts?: RequestOptions): Promise<Transcription>;
+}
+
+interface TranslateParams {
+    text: string;
+    /** Target language: "am" | "om" | "en". */
+    to: TranslateLanguage;
+    /** Source language. Must differ from `to`. */
+    from: TranslateLanguage;
+}
+interface Translation {
+    text: string;
+    sourceLanguage: TranslateLanguage;
+    targetLanguage: TranslateLanguage;
+    quality: "high" | "medium" | "low" | null;
+    usage: unknown;
+}
+declare class Translate {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Translate text between Amharic, Afan Oromo, and English. */
+    create(params: TranslateParams, opts?: RequestOptions): Promise<Translation>;
+}
+
+/**
+ * ElevenLabs-style alias over `voice.*`, for developers migrating from
+ * ElevenLabs. `client.textToSpeech.convert(voiceId, { text, language })`.
+ */
+interface ConvertParams {
+    text: string;
+    language: Language;
+    outputFormat?: OutputFormat;
+    voiceSettings?: VoiceSettings;
+    clientRequestId?: string;
+}
+declare class TextToSpeech {
+    private readonly voice;
+    constructor(voice: Voice);
+    /** Synthesize speech for a voice. Mirrors ElevenLabs `textToSpeech.convert`. */
+    convert(voiceId: string, params: ConvertParams, opts?: RequestOptions): Promise<AddisClip>;
+}
+
+interface LegacyAudioParams {
+    text: string;
+    /** "am" | "om". */
+    language: Language;
+}
+/** Result of a legacy non-streaming synthesis. */
+declare class LegacyAudio {
+    /** Base64-encoded audio (WAV or MP3, provider-dependent). */
+    readonly audio: string;
+    constructor(
+    /** Base64-encoded audio (WAV or MP3, provider-dependent). */
+    audio: string);
+    /** Decode the base64 audio into bytes. */
+    arrayBuffer(): ArrayBuffer;
+    /** Write the decoded audio to disk (Node/Bun/Deno). */
+    toFile(path: string): Promise<void>;
+}
+/**
+ * @deprecated The legacy `/audio` text-to-speech endpoint. Use
+ * {@link Voice.generate} (`addis.voice.generate`) instead — it uses the current
+ * voice model and returns durable, signed clips with idempotent billing.
+ *
+ * Provided only as a migration bridge for existing integrations. Limited to
+ * 1500 characters for non-streaming synthesis.
+ */
+declare class LegacyAudioResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * @deprecated Use `addis.voice.generate(...)`.
+     * Synthesize speech via the legacy endpoint (non-streaming).
+     */
+    generate(params: LegacyAudioParams, opts?: RequestOptions): Promise<LegacyAudio>;
+    /**
+     * @deprecated Use `addis.voice.generate(...)`.
+     * Stream synthesis via the legacy endpoint. Returns an {@link AudioStream} of
+     * audio byte chunks. The SDK normalizes the two legacy encodings (Amharic
+     * newline-delimited base64 JSON, Afan Oromo raw `audio/wav`) into one byte
+     * stream. New code should not depend on this.
+     */
+    stream(params: LegacyAudioParams, opts?: RequestOptions): Promise<AudioStream>;
+}
+/** @deprecated Namespace for legacy endpoints retained for backward compatibility. */
+declare class Legacy {
+    /** @deprecated Use `addis.voice` instead. */
+    readonly audio: LegacyAudioResource;
+    constructor(transport: Transport);
+}
+
+interface ClientOptions {
+    /** Addis AI API key. Defaults to `process.env.ADDIS_API_KEY`. */
+    apiKey?: string;
+    /** Override the API base URL. Defaults to the Addis AI Cloudflare endpoint. */
+    baseURL?: string;
+    /** Request timeout in milliseconds. Default 60000. */
+    timeout?: number;
+    /** Maximum automatic retries for transient failures. Default 2. */
+    maxRetries?: number;
+    /** Headers merged into every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Query params merged into every request. */
+    defaultQuery?: Record<string, string>;
+    /** Inject a custom fetch implementation. Defaults to the global fetch. */
+    fetch?: FetchLike;
+    /** Allow running in a browser. API keys are secrets — keep this false. */
+    dangerouslyAllowBrowser?: boolean;
+    /** Logging verbosity. Secrets are never logged at any level. Default "warn". */
+    logLevel?: LogLevel;
+}
+declare class AddisAI {
+    readonly chat: Chat;
+    readonly voice: Voice;
+    readonly voices: Voices;
+    readonly speech: Speech;
+    readonly translate: Translate;
+    /** ElevenLabs-style alias over `voice.*` for developers migrating. */
+    readonly textToSpeech: TextToSpeech;
+    /** @deprecated Legacy endpoints retained for backward compatibility. Use `voice`. */
+    readonly legacy: Legacy;
+    /** @internal */
+    readonly _transport: Transport;
+    private readonly _apiKey;
+    constructor(options?: ClientOptions);
+    /** Redacted representation; never exposes the API key. */
+    toString(): string;
+}
+
+interface ErrorDetail {
+    field?: string;
+    code?: string;
+    message?: string;
+}
+declare class AddisAIError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a capability exists in the SDK surface but is not yet enabled. */
+declare class NotSupportedError extends AddisAIError {
+}
+/** Network-level failure (DNS, TLS, socket, fetch rejection). */
+declare class APIConnectionError extends AddisAIError {
+    readonly cause?: unknown;
+    constructor(message?: string, cause?: unknown);
+}
+/** Request exceeded the configured timeout / was aborted by timeout. */
+declare class APIConnectionTimeoutError extends APIConnectionError {
+    constructor(message?: string);
+}
+/** Any non-2xx HTTP response. */
+declare class APIError extends AddisAIError {
+    readonly status: number;
+    readonly code: string | null;
+    readonly details: ErrorDetail[];
+    readonly requestId: string | null;
+    readonly headers: Record<string, string>;
+    constructor(status: number, message: string, opts?: {
+        code?: string | null;
+        details?: ErrorDetail[];
+        requestId?: string | null;
+        headers?: Record<string, string>;
+    });
+}
+declare class BadRequestError extends APIError {
+}
+declare class AuthenticationError extends APIError {
+}
+declare class InsufficientCreditsError extends APIError {
+    get availableBalance(): number | null;
+}
+declare class PermissionDeniedError extends APIError {
+}
+declare class NotFoundError extends APIError {
+}
+declare class ConflictError extends APIError {
+}
+declare class IdempotencyConflictError extends ConflictError {
+}
+declare class GenerationInProgressError extends ConflictError {
+    get retryAfter(): number | null;
+}
+declare class UnprocessableEntityError extends APIError {
+}
+declare class RateLimitError extends APIError {
+    get retryAfter(): number | null;
+    get limit(): number | null;
+    get remaining(): number | null;
+    get reset(): number | null;
+}
+declare class InternalServerError extends APIError {
+}
+
+/**
+ * Play audio through the system audio device (Node only). Lazily spawns
+ * `ffplay` (from ffmpeg); falls back to `mpv`. Intended for local scripts and
+ * demos, not production servers.
+ */
+declare function play(audio: AddisClip | ArrayBuffer | Uint8Array): Promise<void>;
+
+/** Generate a new ULID, e.g. "01JZ900QK3GZTY2VJ9ZQ5A96M5". */
+declare function ulid(): string;
+
+export { ADDIS_CHAT_MODEL, APIConnectionError, APIConnectionTimeoutError, APIError, AddisAI, AddisAIError, AddisClip, AudioStream, AuthenticationError, BadRequestError, type ChatAttachment, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionCreateParams, type ChatCompletionMessage, type ChatRole, ChatStream, type ChatUsage, type ClientOptions, type ClipData, type ClipListParams, type ClipMeta, type ClipUsage, ConflictError, type ConvertParams, CursorPage, CursorPagePromise, type ErrorDetail, type FileInput, type FunctionTool, GenerationInProgressError, IdempotencyConflictError, InsufficientCreditsError, InternalServerError, type Language, LegacyAudio, type LegacyAudioParams, type LogLevel, NotFoundError, NotSupportedError, type OutputFormat, PermissionDeniedError, RateLimitError, type RequestOptions, type SttLanguage, type ToolCall, type ToolChoice, type TranscribeParams, type Transcription, type TranslateLanguage, type TranslateParams, type Translation, UnprocessableEntityError, type Uploadable, type VoiceCatalogEntry, type VoiceEstimate, type VoiceEstimateParams, type VoiceGenerateParams, type VoiceListParams, type VoicePreview, type VoiceSettings, type VoiceUsage, AddisAI as default, fileFromPath, play, ulid };