@broberg/ai-sdk 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -74,12 +74,21 @@ interface Usage {
 interface CostSink {
     record(usage: Usage): void | Promise<void>;
 }
+/** Backing store for a BudgetGuard's rolling total. Default is in-memory
+ *  (per createAI instance). A persistent store (e.g. sqliteBudgetStore) makes
+ *  the rolling budget survive restarts + shared across processes (F7.1). */
+interface BudgetStore {
+    getSpent(): number | Promise<number>;
+    addSpent(usd: number): void | Promise<void>;
+}
 /** Pre-flight budget ceilings, enforced before a call fires (F3.2). */
 interface BudgetConfig {
     /** Reject a single call whose estimated cost exceeds this many USD. */
     perCallUsd?: number;
-    /** Reject once cumulative spend on this client instance exceeds this many USD. */
+    /** Reject once cumulative spend exceeds this many USD. */
     rollingUsd?: number;
+    /** Where the rolling total lives. Omit for in-memory (per instance). */
+    store?: BudgetStore;
 }
 /** Per-call options shared by every capability: which tier, optional routing
  *  override, optional fallback chain, and a free-text purpose for cost reports. */
@@ -98,12 +107,39 @@ interface ChatRequest {
     tools?: Tool[];
     maxTokens?: number;
     temperature?: number;
+    /** "json" → request JSON-object output where the provider supports it (F009). */
+    responseFormat?: "json" | "text";
 }
 interface ChatResult {
     text: string;
     toolCalls?: ToolCall[];
     usage: Usage;
 }
+/** A single event from `ai.chatStream` / `adapter.chatStream` (F8). A streamed
+ *  turn yields `text`/`tool_call` events as they arrive, one `usage` event when
+ *  the provider reports totals, and a terminal `finish` (or `error`). Tool calls
+ *  are emitted COMPLETE — accumulated across wire fragments, never partial. */
+type ChatStreamEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: "usage";
+    costUsd: number;
+    model: string;
+    usage: Usage;
+} | {
+    type: "finish";
+    reason: "end_turn" | "tool_calls" | "length" | "stop";
+} | {
+    type: "error";
+    message: string;
+    status?: number;
+};
 interface ImageRequest {
     prompt: string;
     spec: TierSpec;
@@ -126,6 +162,8 @@ interface TranscribeRequest {
     /** Raw audio bytes (the client resolves a URL to bytes before calling). */
     audio: Uint8Array;
     language?: string;
+    /** Audio length in seconds — enables per-minute cost (Whisper). Omit → cost 0. */
+    durationSec?: number;
     spec: TierSpec;
 }
 interface TranscribeResult {
@@ -141,6 +179,9 @@ interface ProviderAdapter {
      *  (e.g. fal does image only). The client guards each call and throws a clear
      *  "provider X does not support Y" when a capability is absent. */
     chat?(req: ChatRequest): Promise<ChatResult>;
+    /** Streaming chat (F8). Optional — absence is a typed "no streaming support".
+     *  Same request shape as chat; yields ChatStreamEvents as the turn unfolds. */
+    chatStream?(req: ChatRequest): AsyncIterable<ChatStreamEvent>;
     vision?(req: ChatRequest): Promise<ChatResult>;
     image?(req: ImageRequest): Promise<ImageResult>;
     embedding?(req: EmbeddingRequest): Promise<EmbeddingResult>;
@@ -430,6 +471,8 @@ declare const chatInputSchema: z.ZodObject<{
     }>, "many">>;
     maxTokens: z.ZodOptional<z.ZodNumber>;
     temperature: z.ZodOptional<z.ZodNumber>;
+    /** "json" requests JSON-object output (OpenAI-compatible response_format). */
+    responseFormat: z.ZodOptional<z.ZodEnum<["json", "text"]>>;
 }, "strip", z.ZodTypeAny, {
     system?: string | undefined;
     prompt?: string | undefined;
@@ -457,6 +500,7 @@ declare const chatInputSchema: z.ZodObject<{
     }[] | undefined;
     temperature?: number | undefined;
     maxTokens?: number | undefined;
+    responseFormat?: "text" | "json" | undefined;
     tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
     override?: {
         provider?: string | undefined;
@@ -496,6 +540,7 @@ declare const chatInputSchema: z.ZodObject<{
     }[] | undefined;
     temperature?: number | undefined;
     maxTokens?: number | undefined;
+    responseFormat?: "text" | "json" | undefined;
     tier?: "fast" | "smart" | "powerful" | "cheap" | "vision" | "embedding" | undefined;
     override?: {
         provider?: string | undefined;
@@ -795,6 +840,8 @@ declare const transcribeInputSchema: z.ZodObject<{
     /** Audio URL or raw bytes. */
     audio: z.ZodUnion<[z.ZodString, z.ZodType<Uint8Array<ArrayBuffer>, z.ZodTypeDef, Uint8Array<ArrayBuffer>>]>;
     language: z.ZodOptional<z.ZodString>;
+    /** Audio length in seconds — enables Whisper per-minute cost. */
+    durationSec: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     audio: string | Uint8Array<ArrayBuffer>;
     language?: string | undefined;
@@ -810,6 +857,7 @@ declare const transcribeInputSchema: z.ZodObject<{
         transport: "http" | "subprocess";
     })[] | undefined;
     purpose?: string | undefined;
+    durationSec?: number | undefined;
 }, {
     audio: string | Uint8Array<ArrayBuffer>;
     language?: string | undefined;
@@ -825,6 +873,7 @@ declare const transcribeInputSchema: z.ZodObject<{
         transport: "http" | "subprocess";
     })[] | undefined;
     purpose?: string | undefined;
+    durationSec?: number | undefined;
 }>;
 declare const aiConfigSchema: z.ZodObject<{
     defaults: z.ZodOptional<z.ZodRecord<z.ZodEnum<["fast", "smart", "powerful", "cheap", "vision", "embedding"]>, z.ZodObject<{
@@ -887,6 +936,9 @@ type AiConfig = z.infer<typeof aiConfigSchema>;
 /** The public facade. Defined here because it depends on the derived inputs. */
 interface AiClient {
     chat(input: ChatInput): Promise<ChatResult>;
+    /** Streaming chat (F8) — same input as chat; yields ChatStreamEvents. The
+     *  caller owns the tool-loop (per-turn engine, not an agent runtime). */
+    chatStream(input: ChatInput): AsyncIterable<ChatStreamEvent>;
     vision(input: VisionInput): Promise<ChatResult>;
     translate(input: TranslateInput): Promise<TranslateResult>;
     image(input: ImageInput): Promise<ImageResult>;
@@ -912,6 +964,7 @@ declare function anthropicAdapter(config?: {
     apiKey?: string;
     baseUrl?: string;
     anthropicVersion?: string;
+    fetch?: typeof fetch;
 }): ProviderAdapter;
 
 declare function openaiAdapter(config?: {
@@ -923,6 +976,7 @@ declare function openaiAdapter(config?: {
 declare function geminiAdapter(config?: {
     apiKey?: string;
     baseUrl?: string;
+    fetch?: typeof fetch;
 }): ProviderAdapter;
 
 declare function deepinfraAdapter(config?: {
@@ -960,6 +1014,12 @@ interface OpenAICompatibleConfig {
     apiKey?: string;
     /** Extra headers (e.g. OpenRouter's HTTP-Referer / X-Title). */
     extraHeaders?: Record<string, string>;
+    /** Injectable fetch for the streaming path (tests). */
+    fetch?: typeof fetch;
+    /** OpenRouter ground-truth cost (F010): send `usage:{include:true}` and use the
+     *  response's `usage.cost` (USD) as costUsd, falling back to the pricing table.
+     *  Only OpenRouter returns this field — openai/deepinfra leave it false. */
+    costFromResponseField?: boolean;
 }
 declare function makeOpenAICompatibleAdapter(config: OpenAICompatibleConfig): ProviderAdapter;
 
@@ -978,8 +1038,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.1.2";
-declare const SDK_TAG: "@broberg/ai-sdk@0.1.2";
+declare const VERSION: "0.3.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.3.0";
 
 /** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
  *  per-call override. Model IDs are current at scaffold time; callers pin their
@@ -1025,15 +1085,24 @@ declare class BudgetExceededError extends Error {
 }
 declare class BudgetGuard {
     private readonly config;
-    private spentUsd;
+    private readonly store;
     constructor(config: BudgetConfig);
     /** Throws BudgetExceededError if `requested` would breach the per-call ceiling
-     *  or push the rolling total past its ceiling. Call before firing the request. */
-    check(requested: number): void;
+     *  or push the rolling total past its ceiling. Call before firing the request.
+     *  Async because a persistent store may be I/O-backed. */
+    check(requested: number): Promise<void>;
     /** Add an actual cost to the running total (after a successful call). */
-    record(actual: number): void;
-    get totalSpent(): number;
+    record(actual: number): Promise<void>;
+    totalSpent(): Promise<number>;
+}
+
+interface SqliteBudgetStoreConfig {
+    /** SQLite file path, e.g. "./ai-budget.db". */
+    dbPath: string;
+    /** Window/bucket key — use e.g. a day-stamp for a daily budget. Default "default". */
+    key?: string;
 }
+declare function sqliteBudgetStore(config: SqliteBudgetStoreConfig): BudgetStore;
 
 /** A sink that does nothing. The default when no costSink is configured. */
 declare const noopSink: CostSink;
@@ -1146,4 +1215,21 @@ declare function httpTransport(req: TransportRequest): Promise<HttpResponse>;
 declare function parseClaudeCliJson(raw: string): SubprocessResponse;
 declare function subprocessTransport(req: TransportRequest): Promise<SubprocessResponse>;
 
-export { type AiClient, type AiConfig, type BudgetConfig, BudgetExceededError, BudgetGuard, type CallOptions, type Capability, type ChatInput, type ChatRequest, type ChatResult, type ClassifyInput, type ClassifyResult, type ContentPart, type Contracts, type CostSink, type CostSummary, DEFAULT_TIER_MAP, type DesignInput, type DesignResult, type DiscordSinkConfig, type EmbeddingInput, type EmbeddingRequest, type EmbeddingResult, type ExtractInput, type ExtractResult, type FalAdapterConfig, type HttpResponse, type ImageInput, type ImageRequest, type ImageResult, type Message, type MockupInput, type MockupResult, type OpenAICompatibleConfig, type PricingEntry, type ProviderAdapter, type RerankInput, type RerankResult, type Role, SDK_TAG, type SqliteSinkConfig, type SubprocessResponse, type Tier, type TierSpec, type Tool, type ToolCall, type TranscribeInput, type TranscribeRequest, type TranscribeResult, type TranslateInput, type TranslateResult, type Transport, type TransportRequest, type TransportResponse, type UpmetricsSinkConfig, type Usage, VERSION, type VisionInput, aiConfigSchema, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, chatInputSchema, computeCost, createAI, deepinfraAdapter, defaultProviders, discordSink, embeddingInputSchema, falAdapter, falStubAdapter, freshUsage, fromProviderToolCall, geminiAdapter, getCostSummary, getPrice, httpTransport, imageInputSchema, makeContracts, makeOpenAICompatibleAdapter, messageSchema, multiSink, noopSink, openaiAdapter, openaiStubAdapter, openrouterAdapter, parseClaudeCliJson, parseJsonLoose, resolveTier, sqliteSink, stubProviders, subprocessTransport, tierSpecSchema, toProviderTools, toolSchema, translateInputSchema, upmetricsSink, visionInputSchema };
+/** HTTP error from a streaming connect — carries `status` so the client's
+ *  pre-stream fallback can tell an eligible 429/5xx from a hard 4xx. */
+declare class StreamHttpError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface StreamTransportRequest extends TransportRequest {
+    /** Injectable fetch for tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * Open an SSE stream and yield each event's `data:` payload as a raw string
+ * (the JSON after `data: `), skipping the `[DONE]` terminator and non-data
+ * lines. Throws StreamHttpError before the first yield on a non-2xx connect.
+ */
+declare function streamTransport(req: StreamTransportRequest): AsyncIterable<string>;
+
+export { type AiClient, type AiConfig, type BudgetConfig, BudgetExceededError, BudgetGuard, type BudgetStore, type CallOptions, type Capability, type ChatInput, type ChatRequest, type ChatResult, type ChatStreamEvent, type ClassifyInput, type ClassifyResult, type ContentPart, type Contracts, type CostSink, type CostSummary, DEFAULT_TIER_MAP, type DesignInput, type DesignResult, type DiscordSinkConfig, type EmbeddingInput, type EmbeddingRequest, type EmbeddingResult, type ExtractInput, type ExtractResult, type FalAdapterConfig, type HttpResponse, type ImageInput, type ImageRequest, type ImageResult, type Message, type MockupInput, type MockupResult, type OpenAICompatibleConfig, type PricingEntry, type ProviderAdapter, type RerankInput, type RerankResult, type Role, SDK_TAG, type SqliteBudgetStoreConfig, type SqliteSinkConfig, StreamHttpError, type SubprocessResponse, type Tier, type TierSpec, type Tool, type ToolCall, type TranscribeInput, type TranscribeRequest, type TranscribeResult, type TranslateInput, type TranslateResult, type Transport, type TransportRequest, type TransportResponse, type UpmetricsSinkConfig, type Usage, VERSION, type VisionInput, aiConfigSchema, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, chatInputSchema, computeCost, createAI, deepinfraAdapter, defaultProviders, discordSink, embeddingInputSchema, falAdapter, falStubAdapter, freshUsage, fromProviderToolCall, geminiAdapter, getCostSummary, getPrice, httpTransport, imageInputSchema, makeContracts, makeOpenAICompatibleAdapter, messageSchema, multiSink, noopSink, openaiAdapter, openaiStubAdapter, openrouterAdapter, parseClaudeCliJson, parseJsonLoose, resolveTier, sqliteBudgetStore, sqliteSink, streamTransport, stubProviders, subprocessTransport, tierSpecSchema, toProviderTools, toolSchema, translateInputSchema, upmetricsSink, visionInputSchema };