@canarycoders/ai 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,1070 @@
+import { CompatTarget } from './compat.cjs';
+export { anthropicTarget, openaiTarget } from './compat.cjs';
+import { C as CreateRealtimeSessionParams, R as RealtimeSession, a as RealtimeSessionRecord, F as FinalizeRealtimeParams, B as BrokeredCredential } from './realtime-BWDkXcj9.cjs';
+export { b as RealtimeKind, c as RealtimeTool } from './realtime-BWDkXcj9.cjs';
+
+type FetchLike = typeof globalThis.fetch;
+
+/** Every provider the gateway can route to. */
+type ProviderType = "gemini" | "vertex" | "openai" | "anthropic" | "xai" | "lmstudio" | "ollama" | "perplexity" | "elevenlabs" | "mlxaudio" | "vision" | "gcvision";
+/** Providers that serve text chat / completion. */
+type ChatProvider = "gemini" | "vertex" | "openai" | "anthropic" | "xai" | "lmstudio" | "ollama" | "perplexity";
+type ModelCapability = "chat" | "vision" | "image-generation" | "video-generation" | "text-to-speech" | "speech-to-text" | "image-recognition" | "face-detection" | "web-detection" | "conversation" | "sound-effect" | "music-generation" | "dialogue" | "realtime-voice" | "realtime-translate" | "realtime-transcribe" | "embeddings" | "reasoning";
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cachedTokens?: number;
+    reasoningTokens?: number;
+}
+interface ModelInfo {
+    id: string;
+    name: string;
+    contextWindow: number;
+    maxOutputTokens: number;
+    provider: string;
+    capabilities: ModelCapability[];
+    inputCostPer1k?: number;
+    outputCostPer1k?: number;
+    costPerImage?: number;
+    costPerSecond?: number;
+    costPerCharacter?: number;
+    costPerHour?: number;
+    costPerAnalysis?: number;
+    costPerMinute?: number;
+    higherContextThreshold?: number;
+    higherContextInputCostPer1k?: number;
+    higherContextOutputCostPer1k?: number;
+    deprecated?: boolean;
+    shutdownDate?: string;
+    replacedBy?: string;
+}
+interface VoiceInfo {
+    id: string;
+    name: string;
+    gender?: string;
+    accent?: string;
+    age?: string;
+    language?: string;
+    description?: string;
+    preview_url?: string;
+    labels?: Record<string, string>;
+}
+interface Citation {
+    url?: string;
+    title?: string;
+    text?: string;
+    startIndex?: number;
+    endIndex?: number;
+}
+/** The standard CanaryLLM success envelope: `{ success: true, data: T }`. */
+interface ApiEnvelope<T> {
+    success: boolean;
+    data: T;
+    message?: string;
+}
+
+type ConversationTemplateType = "interview" | "conversation";
+interface ConversationQuestion {
+    question: string;
+    context?: string;
+    isRequired?: boolean;
+}
+interface ConversationVoiceSettings {
+    stability?: number;
+    speed?: number;
+    similarityBoost?: number;
+}
+interface ConversationTool {
+    name: string;
+    description?: string;
+}
+interface ConversationTemplateParams {
+    name: string;
+    type: ConversationTemplateType;
+    systemPrompt: string;
+    description?: string;
+    firstMessage?: string;
+    voiceId?: string;
+    voiceModel?: string;
+    voiceSettings?: ConversationVoiceSettings;
+    language?: string;
+    languagePresets?: Record<string, {
+        firstMessage?: string;
+    }>;
+    llmProvider?: ChatProvider;
+    llmModel?: string;
+    clientWebhookUrl?: string;
+    webhookSecret?: string;
+    maxDurationSeconds?: number;
+    tag?: string;
+    questions?: ConversationQuestion[];
+    tools?: ConversationTool[];
+}
+type ConversationTemplateUpdate = Partial<ConversationTemplateParams>;
+interface ConversationTemplate extends ConversationTemplateParams {
+    id: number;
+    agentId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface ConversationSessionRecord {
+    id: number;
+    templateId: number;
+    status: string;
+    metadata?: Record<string, unknown>;
+    createdAt?: string;
+    completedAt?: string;
+}
+interface CreateConversationSessionParams {
+    templateId: number;
+    metadata?: Record<string, unknown>;
+    textOnly?: boolean;
+}
+interface ConversationSession {
+    session: ConversationSessionRecord;
+    signedUrl: string;
+    /** seconds until the signed URL expires (≈900) */
+    expiresIn: number;
+    textOnly: boolean;
+}
+interface SignedUrlParams {
+    agentId: string;
+    sessionId?: number;
+}
+interface SignedUrlResult {
+    signedUrl: string;
+    expiresIn: number;
+    sessionId?: number;
+}
+
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+type RetryMode = "idempotent" | "submit" | "none";
+interface TransportConfig {
+    apiKey?: string;
+    baseURL: string;
+    authStyle: "bearer" | "x-api-key";
+    timeoutMs: number;
+    maxRetries: number;
+    fetch?: FetchLike;
+    defaultHeaders?: Record<string, string>;
+    defaultTag?: string;
+    userAgent?: string;
+}
+interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /** total timeout for this call; 0 disables (used for streams) */
+    timeoutMs?: number;
+    /** unwrap `{ success, data }` envelopes and return `data` (default true) */
+    unwrap?: boolean;
+    retry?: RetryMode;
+}
+declare class Transport {
+    readonly baseURL: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    private readonly apiKey?;
+    private readonly authStyle;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    private readonly defaultTag?;
+    private readonly userAgent;
+    private readonly retryPolicy;
+    constructor(config: TransportConfig);
+    json<T>(method: HttpMethod, path: string, opts?: RequestOptions): Promise<T>;
+    /** Perform the request and return the Response without throwing on non-2xx. */
+    raw(method: HttpMethod, path: string, opts?: RequestOptions): Promise<Response>;
+    /** Perform the request and return the raw text body (CSV, YAML, …). */
+    text(method: HttpMethod, path: string, opts?: RequestOptions): Promise<string>;
+    /** Open a streaming response. Throws if the initial response is an error. */
+    stream(method: HttpMethod, path: string, opts?: RequestOptions): Promise<Response>;
+    private maybeUnwrap;
+    private send;
+    private withDefaultTag;
+    private withRetry;
+    private execute;
+    private buildHeaders;
+    private buildUrl;
+}
+
+type MessageRole = "system" | "user" | "assistant" | "tool";
+interface TextContent {
+    type: "text";
+    text: string;
+}
+interface ImageContent {
+    type: "image";
+    /** base64-encoded image bytes */
+    data: string;
+    mimeType?: string;
+}
+interface DocumentContent {
+    type: "document";
+    /** base64-encoded PDF bytes */
+    data: string;
+    mimeType: "application/pdf";
+}
+interface VideoContent {
+    type: "video";
+    /** base64-encoded video bytes */
+    data?: string;
+    /** id returned by `video.upload()` */
+    fileId?: string;
+    mimeType?: string;
+}
+type ContentPart = TextContent | ImageContent | DocumentContent | VideoContent;
+type MessageContent = string | ContentPart[];
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ToolCallDelta {
+    index: number;
+    id?: string;
+    type?: "function";
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+}
+interface Message {
+    role: MessageRole;
+    content: MessageContent;
+    name?: string;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+}
+interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+type ToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
+interface ThinkingMode {
+    enabled: boolean;
+    budget?: number;
+}
+interface WebSearchOptions {
+    enabled: boolean;
+    maxUses?: number;
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    recencyFilter?: "day" | "week" | "month" | "year";
+    userLocation?: {
+        country?: string;
+        region?: string;
+        city?: string;
+        timezone?: string;
+    };
+    xSearch?: boolean;
+}
+type ResponseFormat = "text" | "json" | "json_schema";
+interface CompleteParams {
+    provider: ChatProvider;
+    messages: Message[];
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    stop?: string[];
+    responseFormat?: ResponseFormat;
+    jsonSchema?: Record<string, unknown>;
+    tools?: ToolDefinition[];
+    toolChoice?: ToolChoice;
+    thinkingMode?: ThinkingMode;
+    webSearch?: WebSearchOptions;
+    cache?: {
+        enabled?: boolean;
+        ttl?: number;
+    };
+    tag?: string;
+    service?: string;
+    /** server-side per-request timeout in ms (1000–300000) */
+    timeout?: number;
+}
+interface CompletionResult {
+    content: string;
+    usage: TokenUsage;
+    model: string;
+    provider: string;
+    requestId?: string;
+    cached?: boolean;
+    finishReason?: string;
+    toolCalls?: ToolCall[];
+    citations?: Citation[];
+    metadata?: Record<string, unknown>;
+}
+/** Raw chunk shape emitted by the native `/queue/stream` endpoint. */
+interface StreamChunk {
+    delta: string;
+    usage?: TokenUsage;
+    finishReason?: string;
+    toolCallDeltas?: ToolCallDelta[];
+    metadata?: Record<string, unknown>;
+}
+/** Normalized streaming event, identical across every wire protocol. */
+type ChatStreamEvent = {
+    type: "start";
+    raw?: unknown;
+} | {
+    type: "text";
+    delta: string;
+    raw?: unknown;
+} | {
+    type: "thinking";
+    delta: string;
+    raw?: unknown;
+} | {
+    type: "tool_call";
+    index: number;
+    id?: string;
+    name?: string;
+    argsDelta?: string;
+    raw?: unknown;
+} | {
+    type: "usage";
+    usage: TokenUsage;
+    raw?: unknown;
+} | {
+    type: "done";
+    finishReason?: string;
+    usage?: TokenUsage;
+    raw?: unknown;
+} | {
+    type: "raw";
+    event?: string;
+    data: unknown;
+};
+
+type JobStatus = "queued" | "processing" | "thinking" | "streaming" | "completed" | "failed" | "cancelled" | "not_found" | "error";
+interface JobSnapshot {
+    id: string;
+    status: JobStatus;
+    /** queue position, present only while `queued` */
+    position?: number;
+    createdAt?: string;
+    startedAt?: string;
+    completedAt?: string;
+    provider?: string;
+    model?: string;
+    error?: {
+        message: string;
+        code?: string;
+        statusCode?: number;
+    };
+}
+/** Drives per-domain default poll timeouts. */
+type TaskKind = "completion" | "image" | "video" | "tts" | "stt" | "sound-effect" | "music" | "dialogue" | "vision" | "embedding";
+interface PollOptions {
+    /** first poll delay after submit (default 500ms) */
+    initialIntervalMs?: number;
+    /** interval growth factor (default 1.5) */
+    backoffFactor?: number;
+    /** cap on the per-poll interval (default 5000ms) */
+    maxIntervalMs?: number;
+    /** jitter fraction applied to each interval, 0–1 (default 0.2) */
+    jitter?: number;
+    /** total wall-clock budget; defaults per task kind */
+    maxWaitMs?: number;
+    /** fired on every poll while the job is still running */
+    onPoll?: (info: {
+        status: JobStatus;
+        position?: number;
+        elapsedMs: number;
+    }) => void;
+    signal?: AbortSignal;
+    /** also fire `POST /queue/cancel` when the signal aborts (default true) */
+    cancelServerOnAbort?: boolean;
+}
+
+interface JobStreamOptions {
+    signal?: AbortSignal;
+    includeRaw?: boolean;
+    /** abort the stream if no bytes arrive within this window (default 60s) */
+    idleMs?: number;
+}
+/**
+ * A handle to a queued task. Returned by the `*Job` / `.submit()` methods so
+ * callers can hold the `id`, poll, stream, or cancel out of band.
+ */
+declare class Job<T> {
+    readonly id: string;
+    private readonly transport;
+    private readonly taskKind;
+    private readonly defaultPoll?;
+    private cachedValue?;
+    constructor(id: string, transport: Transport, taskKind: TaskKind, defaultPoll?: PollOptions);
+    /** One-shot status probe. Throws `NotFoundError` unless `allowMissing`. */
+    status(opts?: {
+        signal?: AbortSignal;
+        allowMissing?: boolean;
+    }): Promise<JobSnapshot>;
+    /** Poll to completion and resolve the typed result (cached after success). */
+    result(opts?: PollOptions): Promise<T>;
+    /** Stream the task's chunks via `/queue/stream` (for `stream: true` tasks). */
+    stream(opts?: JobStreamOptions): AsyncGenerator<ChatStreamEvent>;
+    /** Best-effort server cancel. Safe to call more than once. */
+    cancel(opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+declare class BaseResource {
+    protected readonly transport: Transport;
+    protected readonly defaultPoll?: PollOptions;
+    constructor(transport: Transport, defaultPoll?: PollOptions);
+    protected submitQueued<T>(path: string, body: unknown, kind: TaskKind, signal?: AbortSignal): Promise<Job<T>>;
+    protected runQueued<T>(path: string, body: unknown, kind: TaskKind, poll?: PollOptions): Promise<T>;
+}
+
+declare class AgentsResource extends BaseResource {
+    /** Mint a short-lived signed URL for an ElevenLabs agent. */
+    signedUrl(params: SignedUrlParams, signal?: AbortSignal): Promise<SignedUrlResult>;
+}
+
+interface ImageGenerateParams {
+    provider: "openai" | "gemini" | "vertex" | "xai" | "ollama";
+    prompt: string;
+    model?: string;
+    n?: number;
+    size?: string;
+    aspectRatio?: string;
+    quality?: "standard" | "hd" | "ultra";
+    tag?: string;
+    service?: string;
+}
+interface GeneratedImage {
+    /** base64-encoded image bytes (when returned inline) */
+    data?: string;
+    url?: string;
+    mimeType?: string;
+    revisedPrompt?: string;
+}
+interface ImageGenerationResult {
+    images: GeneratedImage[];
+    model: string;
+    provider: string;
+}
+interface VideoGenerateParams {
+    provider: "gemini" | "vertex" | "xai";
+    prompt: string;
+    model?: string;
+    aspectRatio?: string;
+    resolution?: string;
+    durationSeconds?: number;
+    numberOfVideos?: number;
+    /** public URL of a seed image */
+    imageUrl?: string;
+    /** id from `video.upload()` for image-to-video */
+    fileId?: string;
+    tag?: string;
+    service?: string;
+}
+interface GeneratedVideo {
+    data?: string;
+    url?: string;
+    mimeType?: string;
+}
+interface VideoGenerationResult {
+    videos: GeneratedVideo[];
+    model: string;
+    provider: string;
+}
+interface VideoUploadResult {
+    fileId: string;
+    mimeType: string;
+}
+type AudioOutputFormat = "mp3_44100_128" | "mp3_44100_192" | "pcm_16000" | "pcm_22050" | "pcm_24000" | "pcm_44100";
+interface VoiceSettings {
+    stability?: number;
+    similarityBoost?: number;
+    style?: number;
+    useSpeakerBoost?: boolean;
+    speed?: number;
+}
+interface SpeechParams {
+    provider: "elevenlabs" | "mlxaudio";
+    text: string;
+    model?: string;
+    voiceId?: string;
+    outputFormat?: AudioOutputFormat;
+    voiceSettings?: VoiceSettings;
+    languageCode?: string;
+    previousText?: string;
+    nextText?: string;
+    applyTextNormalization?: "auto" | "on" | "off";
+    previousRequestIds?: string[];
+    tag?: string;
+    service?: string;
+}
+interface TTSResult {
+    /** base64-encoded audio bytes */
+    audio: string;
+    mimeType: string;
+    model: string;
+    provider: string;
+    characterCount?: number;
+}
+interface TranscribeParams {
+    provider: "elevenlabs" | "mlxaudio";
+    /** base64-encoded audio bytes or a public URL */
+    audio: string;
+    mimeType: string;
+    model?: string;
+    language?: string;
+    diarize?: boolean;
+    numSpeakers?: number;
+    timestampsGranularity?: "word" | "character";
+    tagAudioEvents?: boolean;
+    tag?: string;
+    service?: string;
+}
+interface TranscriptWord {
+    text: string;
+    start?: number;
+    end?: number;
+    speaker?: string;
+    type?: string;
+}
+interface STTResult {
+    text: string;
+    language?: string;
+    words?: TranscriptWord[];
+    model: string;
+    provider: string;
+}
+interface SoundEffectParams {
+    text: string;
+    model?: string;
+    durationSeconds?: number;
+    promptInfluence?: number;
+    loop?: boolean;
+    tag?: string;
+    service?: string;
+}
+interface SoundEffectResult {
+    audio: string;
+    mimeType: string;
+    model: string;
+    provider: string;
+}
+interface MusicParams {
+    prompt: string;
+    model?: string;
+    durationMs?: number;
+    forceInstrumental?: boolean;
+    tag?: string;
+    service?: string;
+}
+interface MusicResult {
+    audio: string;
+    mimeType: string;
+    model: string;
+    provider: string;
+}
+interface DialogueInput {
+    text: string;
+    voiceId: string;
+}
+interface DialogueParams {
+    inputs: DialogueInput[];
+    model?: string;
+    outputFormat?: AudioOutputFormat;
+    voiceSettings?: VoiceSettings;
+    languageCode?: string;
+    seed?: number;
+    applyTextNormalization?: "auto" | "on" | "off";
+    tag?: string;
+    service?: string;
+}
+interface DialogueResult {
+    audio: string;
+    mimeType: string;
+    model: string;
+    provider: string;
+}
+interface EmbeddingParams {
+    provider: "lmstudio";
+    /** A single string or an array of strings (max 2048) to embed. */
+    input: string | string[];
+    /** Embedding model id, e.g. `nomic-embed-text-v1.5`. */
+    model?: string;
+    /** Output dimensionality for models that support truncation (Matryoshka). */
+    dimensions?: number;
+    encodingFormat?: "float" | "base64";
+    tag?: string;
+    service?: string;
+}
+interface EmbeddingResult {
+    /** One vector per input, in input order. */
+    embeddings: number[][];
+    model: string;
+    provider: string;
+    dimensions: number;
+    usage: {
+        inputTokens: number;
+        totalTokens: number;
+    };
+}
+
+declare class AudioResource extends BaseResource {
+    /** Text-to-speech. */
+    speech(params: SpeechParams, poll?: PollOptions): Promise<TTSResult>;
+    speechJob(params: SpeechParams, signal?: AbortSignal): Promise<Job<TTSResult>>;
+    /** Speech-to-text. */
+    transcribe(params: TranscribeParams, poll?: PollOptions): Promise<STTResult>;
+    transcribeJob(params: TranscribeParams, signal?: AbortSignal): Promise<Job<STTResult>>;
+    soundEffect(params: SoundEffectParams, poll?: PollOptions): Promise<SoundEffectResult>;
+    soundEffectJob(params: SoundEffectParams, signal?: AbortSignal): Promise<Job<SoundEffectResult>>;
+    music(params: MusicParams, poll?: PollOptions): Promise<MusicResult>;
+    musicJob(params: MusicParams, signal?: AbortSignal): Promise<Job<MusicResult>>;
+    dialogue(params: DialogueParams, poll?: PollOptions): Promise<DialogueResult>;
+    dialogueJob(params: DialogueParams, signal?: AbortSignal): Promise<Job<DialogueResult>>;
+}
+
+interface ChatStreamOptions {
+    signal?: AbortSignal;
+    includeRaw?: boolean;
+}
+declare class ChatResource extends BaseResource {
+    /** Submit a completion and poll until the final result is ready. */
+    complete(params: CompleteParams, poll?: PollOptions): Promise<CompletionResult>;
+    /** Submit a completion and return the `Job` handle without waiting. */
+    submit(params: CompleteParams, signal?: AbortSignal): Promise<Job<CompletionResult>>;
+    /** Stream a completion as normalized chat events. */
+    stream(params: CompleteParams, opts?: ChatStreamOptions): AsyncGenerator<ChatStreamEvent>;
+}
+
+declare class TemplatesAPI extends BaseResource {
+    create(params: ConversationTemplateParams, signal?: AbortSignal): Promise<ConversationTemplate>;
+    list(signal?: AbortSignal): Promise<ConversationTemplate[]>;
+    get(id: number, signal?: AbortSignal): Promise<ConversationTemplate>;
+    update(id: number, params: ConversationTemplateUpdate, signal?: AbortSignal): Promise<ConversationTemplate>;
+    delete(id: number, signal?: AbortSignal): Promise<void>;
+}
+declare class SessionsAPI extends BaseResource {
+    create(params: CreateConversationSessionParams, signal?: AbortSignal): Promise<ConversationSession>;
+    list(opts?: {
+        templateId?: number;
+    }, signal?: AbortSignal): Promise<ConversationSessionRecord[]>;
+    get(id: number, signal?: AbortSignal): Promise<ConversationSessionRecord>;
+}
+declare class ConversationsResource extends BaseResource {
+    readonly templates: TemplatesAPI;
+    readonly sessions: SessionsAPI;
+}
+
+declare class DiscoveryResource extends BaseResource {
+    providers(signal?: AbortSignal): Promise<string[]>;
+    models(provider: string, signal?: AbortSignal): Promise<ModelInfo[]>;
+    voices(provider: string, signal?: AbortSignal): Promise<VoiceInfo[]>;
+    capabilities(signal?: AbortSignal): Promise<Record<string, any>>;
+    concurrency(signal?: AbortSignal): Promise<Record<string, any>>;
+    concurrencyFor(provider: string, signal?: AbortSignal): Promise<Record<string, any>>;
+}
+
+declare class EmbeddingsResource extends BaseResource {
+    /**
+     * Embed one or more text inputs into vectors via a local embedding model
+     * (LM Studio). Submits to the queue and resolves with the vectors. Content is
+     * processed transiently by the gateway and never stored — intended for
+     * customer-side RAG ingestion and retrieval.
+     */
+    create(params: EmbeddingParams, poll?: PollOptions): Promise<EmbeddingResult>;
+    /** Handle form: returns a {@link Job} you can poll or cancel yourself. */
+    createJob(params: EmbeddingParams, signal?: AbortSignal): Promise<Job<EmbeddingResult>>;
+}
+
+declare class ImagesResource extends BaseResource {
+    /** Generate one or more images and wait for the result. */
+    generate(params: ImageGenerateParams, poll?: PollOptions): Promise<ImageGenerationResult>;
+    /** Submit an image generation and return the `Job` handle. */
+    generateJob(params: ImageGenerateParams, signal?: AbortSignal): Promise<Job<ImageGenerationResult>>;
+}
+
+interface KeyInfo {
+    keyPrefix: string;
+    name?: string;
+    permissions: {
+        read: boolean;
+        write: boolean;
+        admin?: boolean;
+    };
+    rateLimits: {
+        perMinute: number;
+        perDay: number;
+    };
+    expiresAt?: string;
+    lastUsedAt?: string;
+    createdAt?: string;
+}
+interface KeyValidation {
+    success: boolean;
+    valid: boolean;
+    message?: string;
+    data?: unknown;
+}
+declare class KeysResource extends BaseResource {
+    /** Info about the key the client is authenticated with. */
+    info(signal?: AbortSignal): Promise<KeyInfo>;
+    /** Validate an API key. Returns `{ valid: false }` rather than throwing. */
+    validate(apiKey: string, signal?: AbortSignal): Promise<KeyValidation>;
+}
+
+interface PortalPeriod {
+    year?: number;
+    month?: number;
+}
+declare class PortalResource extends BaseResource {
+    info(signal?: AbortSignal): Promise<Record<string, unknown>>;
+    overview(period?: PortalPeriod, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    usageDaily(period?: PortalPeriod, signal?: AbortSignal): Promise<unknown[]>;
+    usageByModel(period?: PortalPeriod, signal?: AbortSignal): Promise<unknown[]>;
+    /** Export a month of usage as CSV text. */
+    exportUsage(params: {
+        month: number;
+        year: number;
+    }, signal?: AbortSignal): Promise<string>;
+}
+
+/** Unauthenticated endpoints. These work even without an API key. */
+declare class PublicResource extends BaseResource {
+    /** All providers with their models and public pricing. */
+    models(signal?: AbortSignal): Promise<Record<string, any>>;
+    /** Available voices per provider. */
+    voices(signal?: AbortSignal): Promise<Record<string, any>>;
+    /** A short spoken preview of a voice (base64 audio). */
+    voicePreview(params: {
+        provider: string;
+        voiceId: string;
+    }, signal?: AbortSignal): Promise<{
+        audio: string;
+        mimeType: string;
+        voiceId: string;
+    }>;
+    /** The raw OpenAPI specification (YAML). */
+    openapi(signal?: AbortSignal): Promise<string>;
+}
+
+/** Low-level access to the queue by `queueId`, for tasks tracked out of band. */
+declare class QueueResource extends BaseResource {
+    /** Reconstruct a `Job` handle from a known queue id. */
+    job<T = unknown>(queueId: string, taskKind?: TaskKind): Job<T>;
+    status(queueId: string, opts?: {
+        signal?: AbortSignal;
+        allowMissing?: boolean;
+    }): Promise<JobSnapshot>;
+    result<T = unknown>(queueId: string, opts?: PollOptions): Promise<T>;
+    stream(queueId: string, opts?: {
+        signal?: AbortSignal;
+        includeRaw?: boolean;
+        idleMs?: number;
+    }): AsyncGenerator<ChatStreamEvent>;
+    cancel(queueId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+declare class RealtimeSessionsAPI extends BaseResource {
+    /** Mint an ephemeral realtime credential. The response is NOT enveloped. */
+    create(params: CreateRealtimeSessionParams, signal?: AbortSignal): Promise<RealtimeSession>;
+    get(id: number, signal?: AbortSignal): Promise<RealtimeSessionRecord>;
+    end(id: number, params?: FinalizeRealtimeParams, signal?: AbortSignal): Promise<RealtimeSessionRecord>;
+}
+declare class RealtimeResource extends BaseResource {
+    readonly sessions: RealtimeSessionsAPI;
+}
+/**
+ * Normalize a realtime or conversational session into a single credential
+ * shape safe to hand to a frontend (only the short-lived secret, never the
+ * API key).
+ */
+declare function toBrokeredCredential(session: RealtimeSession | ConversationSession): BrokeredCredential;
+
+interface UsageSummary {
+    totalRequests: number;
+    totalTokens: number;
+    totalPrice?: number;
+    [k: string]: unknown;
+}
+declare class UsageResource extends BaseResource {
+    /** Current-month usage summary. */
+    current(signal?: AbortSignal): Promise<UsageSummary>;
+    /** Monthly usage broken down by model/provider. */
+    monthly(signal?: AbortSignal): Promise<unknown>;
+    /** Daily usage breakdown. */
+    daily(signal?: AbortSignal): Promise<unknown>;
+}
+
+interface VideoUploadOptions {
+    filename?: string;
+    mimeType?: string;
+    signal?: AbortSignal;
+}
+declare class VideoResource extends BaseResource {
+    generate(params: VideoGenerateParams, poll?: PollOptions): Promise<VideoGenerationResult>;
+    generateJob(params: VideoGenerateParams, signal?: AbortSignal): Promise<Job<VideoGenerationResult>>;
+    /** Upload a seed video for image/video-to-video; returns a `fileId`. */
+    upload(file: Blob | Uint8Array | ArrayBuffer, opts?: VideoUploadOptions): Promise<VideoUploadResult>;
+}
+
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface Detection {
+    label: string;
+    confidence: number;
+    box: BoundingBox;
+    classId?: number;
+}
+interface DetectParams {
+    /** base64-encoded image bytes (max ~50MB) */
+    image: string;
+    model?: string;
+    confidence?: number;
+    /** restrict to these YOLO class ids */
+    classes?: number[];
+    tag?: string;
+    service?: string;
+}
+interface ZeroShotDetectParams {
+    image: string;
+    prompt: string;
+    confidence?: number;
+    tag?: string;
+    service?: string;
+}
+interface FaceDetectParams {
+    image: string;
+    model?: "haarcascade" | "mediapipe" | "yolo-face";
+    blur?: boolean;
+    blurStrength?: number;
+    confidence?: number;
+    minSize?: number;
+    scaleFactor?: number;
+    minNeighbors?: number;
+    tag?: string;
+    service?: string;
+}
+interface WebDetectParams {
+    image: string;
+    maxResults?: number;
+    tag?: string;
+}
+interface ImageRecognitionResult {
+    detections: Detection[];
+    model: string;
+    width?: number;
+    height?: number;
+}
+interface FaceDetectionResult {
+    faces: Detection[];
+    /** base64-encoded image with faces blurred (when `blur: true`) */
+    blurredImage?: string;
+    model: string;
+}
+interface WebEntity {
+    description?: string;
+    score?: number;
+}
+interface WebDetectionResult {
+    entities: WebEntity[];
+    pages?: unknown[];
+    matchingImages?: unknown[];
+}
+interface AutoLabelParams {
+    images: string[];
+    classes: string[];
+    confidence?: number;
+    outputFormat?: string;
+    valSplit?: number;
+    tag?: string;
+}
+interface AutoLabelResult {
+    labeled: number;
+    datasetId?: string;
+    [k: string]: unknown;
+}
+interface AutoTrainParams {
+    images: string[];
+    classes: string[];
+    baseModel?: string;
+    confidence?: number;
+    imageSize?: number;
+    epochs?: number;
+    tag?: string;
+}
+/** Dataset-based fine-tuning. Field shape depends on the server build. */
+type TrainParams = Record<string, unknown>;
+interface TrainingJob {
+    jobId: string;
+    status: string;
+    progress?: number;
+    modelId?: string;
+    createdAt?: string;
+    completedAt?: string;
+    error?: string;
+}
+interface VisionModel {
+    modelId: string;
+    name?: string;
+    classes?: string[];
+    createdAt?: string;
+}
+
+declare class VisionResource extends BaseResource {
+    detect(params: DetectParams, poll?: PollOptions): Promise<ImageRecognitionResult>;
+    detectJob(params: DetectParams, signal?: AbortSignal): Promise<Job<ImageRecognitionResult>>;
+    zeroShot(params: ZeroShotDetectParams, poll?: PollOptions): Promise<ImageRecognitionResult>;
+    zeroShotJob(params: ZeroShotDetectParams, signal?: AbortSignal): Promise<Job<ImageRecognitionResult>>;
+    faces(params: FaceDetectParams, poll?: PollOptions): Promise<FaceDetectionResult>;
+    facesJob(params: FaceDetectParams, signal?: AbortSignal): Promise<Job<FaceDetectionResult>>;
+    web(params: WebDetectParams, poll?: PollOptions): Promise<WebDetectionResult>;
+    webJob(params: WebDetectParams, signal?: AbortSignal): Promise<Job<WebDetectionResult>>;
+    autoLabel(params: AutoLabelParams, poll?: PollOptions): Promise<AutoLabelResult>;
+    autoLabelJob(params: AutoLabelParams, signal?: AbortSignal): Promise<Job<AutoLabelResult>>;
+    autoTrain(params: AutoTrainParams, poll?: PollOptions): Promise<TrainingJob>;
+    autoTrainJob(params: AutoTrainParams, signal?: AbortSignal): Promise<Job<TrainingJob>>;
+    /** Start a dataset training run (synchronous; returns a job record). */
+    train(params: TrainParams, signal?: AbortSignal): Promise<TrainingJob>;
+    getTraining(jobId: string, signal?: AbortSignal): Promise<TrainingJob>;
+    listTraining(signal?: AbortSignal): Promise<TrainingJob[]>;
+    models(signal?: AbortSignal): Promise<VisionModel[]>;
+    deleteModel(modelId: string, signal?: AbortSignal): Promise<{
+        deleted: boolean;
+        modelId: string;
+    }>;
+}
+
+interface CanaryLLMOptions {
+    /** API key. Defaults to `process.env.CANARY_AI_API_KEY` (legacy `CANARYLLM_API_KEY` still read). */
+    apiKey?: string;
+    /** Base URL. Defaults to `https://api.ai.canarycoders.es`. */
+    baseURL?: string;
+    /** Send the key as `Authorization: Bearer` (default) or `X-API-Key`. */
+    authStyle?: "bearer" | "x-api-key";
+    /** Per-request total timeout in ms (default 60000). */
+    timeoutMs?: number;
+    /** Automatic retries for transient failures (default 2). */
+    maxRetries?: number;
+    /** Override the fetch implementation (tests, proxies, custom agents). */
+    fetch?: FetchLike;
+    defaultHeaders?: Record<string, string>;
+    /** Default `tag` attached to requests for usage attribution. */
+    defaultTag?: string;
+    /** Default polling behavior for queued operations. */
+    poll?: PollOptions;
+}
+declare class CanaryLLM {
+    readonly chat: ChatResource;
+    readonly queue: QueueResource;
+    readonly images: ImagesResource;
+    readonly video: VideoResource;
+    readonly audio: AudioResource;
+    readonly embeddings: EmbeddingsResource;
+    readonly vision: VisionResource;
+    readonly conversations: ConversationsResource;
+    readonly agents: AgentsResource;
+    readonly realtime: RealtimeResource;
+    readonly discovery: DiscoveryResource;
+    readonly usage: UsageResource;
+    readonly portal: PortalResource;
+    readonly keys: KeysResource;
+    readonly public: PublicResource;
+    private readonly transport;
+    private readonly baseURL;
+    private readonly apiKey?;
+    constructor(options?: CanaryLLMOptions);
+    /** Targets to plug into the official `openai` / `@anthropic-ai/sdk` clients. */
+    get compat(): {
+        openai: () => CompatTarget;
+        anthropic: () => CompatTarget;
+    };
+}
+
+interface APIErrorInit {
+    status?: number;
+    code?: string | number;
+    requestId?: string;
+    headers?: Headers;
+    details?: unknown;
+    raw?: unknown;
+}
+/** Base class for every error the SDK throws from an API interaction. */
+declare class APIError extends Error {
+    readonly status?: number;
+    readonly code?: string | number;
+    readonly requestId?: string;
+    readonly headers?: Headers;
+    readonly details?: unknown;
+    readonly raw?: unknown;
+    constructor(message: string, init?: APIErrorInit);
+}
+declare class BadRequestError extends APIError {
+    /** parsed Zod issues from the server, when present */
+    readonly validationIssues?: unknown;
+    constructor(message: string, init?: APIErrorInit);
+}
+declare class AuthenticationError extends APIError {
+}
+declare class PermissionError extends APIError {
+}
+declare class NotFoundError extends APIError {
+}
+declare class ConflictError extends APIError {
+}
+declare class UnprocessableEntityError extends APIError {
+}
+declare class RateLimitError extends APIError {
+    /** remaining request budget; only sent by the server in development */
+    readonly remaining?: {
+        minute: number;
+        day: number;
+    };
+    readonly retryAfterMs?: number;
+    constructor(message: string, init?: APIErrorInit);
+}
+declare class InternalServerError extends APIError {
+}
+/** Network-level failure (DNS, connection refused, TLS, reset). No HTTP status. */
+declare class APIConnectionError extends APIError {
+}
+declare class APIConnectionTimeoutError extends APIConnectionError {
+    phase?: "connect" | "read" | "total";
+}
+
+interface SSEOptions {
+    signal?: AbortSignal;
+    /** abort the stream if no bytes arrive within this window */
+    idleMs?: number;
+}
+
+type StreamProtocol = "native" | "openai" | "anthropic" | "responses";
+interface StreamAdapterOptions extends SSEOptions {
+    /** attach the source payload as `raw` on each event (off by default) */
+    includeRaw?: boolean;
+}
+
+// @ts-ignore
+export = CanaryLLM;
+export { APIConnectionError, APIConnectionTimeoutError, APIError, type ApiEnvelope, type AudioOutputFormat, AuthenticationError, type AutoLabelParams, type AutoLabelResult, type AutoTrainParams, BadRequestError, type BoundingBox, BrokeredCredential, CanaryLLM, type CanaryLLMOptions, type ChatProvider, type ChatStreamEvent, type ChatStreamOptions, type Citation, CompatTarget, type CompleteParams, type CompletionResult, ConflictError, type ContentPart, type ConversationQuestion, type ConversationSession, type ConversationSessionRecord, type ConversationTemplate, type ConversationTemplateParams, type ConversationTemplateType, type ConversationTemplateUpdate, type ConversationTool, type ConversationVoiceSettings, type CreateConversationSessionParams, CreateRealtimeSessionParams, type DetectParams, type Detection, type DialogueInput, type DialogueParams, type DialogueResult, type DocumentContent, type EmbeddingParams, type EmbeddingResult, type FaceDetectParams, type FaceDetectionResult, FinalizeRealtimeParams, type GeneratedImage, type GeneratedVideo, type ImageContent, type ImageGenerateParams, type ImageGenerationResult, type ImageRecognitionResult, InternalServerError, Job, type JobSnapshot, type JobStatus, type JobStreamOptions, type KeyInfo, type KeyValidation, type Message, type MessageContent, type MessageRole, type ModelCapability, type ModelInfo, type MusicParams, type MusicResult, NotFoundError, PermissionError, type PollOptions, type PortalPeriod, type ProviderType, RateLimitError, RealtimeSession, RealtimeSessionRecord, type ResponseFormat, type STTResult, type SignedUrlParams, type SignedUrlResult, type SoundEffectParams, type SoundEffectResult, type SpeechParams, type StreamAdapterOptions, type StreamChunk, type StreamProtocol, type TTSResult, type TaskKind, type TextContent, type ThinkingMode, type TokenUsage, type ToolCall, type ToolCallDelta, type ToolChoice, type ToolDefinition, type TrainParams, type TrainingJob, type TranscribeParams, type TranscriptWord, UnprocessableEntityError, type UsageSummary, type VideoContent, type VideoGenerateParams, type VideoGenerationResult, type VideoUploadOptions, type VideoUploadResult, type VisionModel, type VoiceInfo, type VoiceSettings, type WebDetectParams, type WebDetectionResult, type WebEntity, type WebSearchOptions, type ZeroShotDetectParams, toBrokeredCredential };