@wrongstack/providers 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 ECOSTACK TECHNOLOGY OÜ
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,311 @@
+import { Provider, Capabilities, Request, Response, StreamEvent, ProviderError, TextBlock, Message, Tool, ModelsRegistry, StopReason, ContentBlock, Logger, ProviderFactory, ProviderConfig } from '@wrongstack/core';
+
+/**
+ * Minimal Server-Sent Events parser for HTTP streaming responses.
+ *
+ * Yields parsed events as `{ event, data }` pairs. Per spec:
+ *   - Each event is separated by a blank line
+ *   - `event: foo` sets the event name (defaults to "message")
+ *   - `data: ...` lines accumulate into the data buffer
+ *   - `:` lines are comments and ignored
+ *   - `id` / `retry` fields are accepted and ignored
+ *
+ * For Anthropic the wire format is canonical SSE with explicit `event:` lines.
+ * For OpenAI / OpenAI-compatible the format omits `event:` and just emits
+ * `data: <json>` chunks, with a final `data: [DONE]`. Both work with this
+ * parser; consumers branch on event name or just on `data`.
+ */
+interface SSEMessage {
+    event: string;
+    data: string;
+}
+declare function parseSSE(body: ReadableStream<Uint8Array> | NodeJS.ReadableStream | null): AsyncIterable<SSEMessage>;
+
+/**
+ * Shared HTTP mechanics for streaming providers.
+ * Providers extend this to get:
+ *   - canonical error handling (ProviderError with retryable flag)
+ *   - SSE body parsing via parseSSE()
+ *   - abort signal wiring
+ *
+ * Subclasses implement the abstract members to provide their specific wire format.
+ */
+declare abstract class WireAdapter implements Provider {
+    protected readonly apiKey: string;
+    protected readonly baseUrl: string;
+    readonly fetchImpl: typeof fetch;
+    abstract readonly id: string;
+    abstract readonly capabilities: Capabilities;
+    constructor(apiKey: string, baseUrl: string, fetchImpl?: typeof fetch);
+    complete(req: Request, opts: {
+        signal: AbortSignal;
+    }): Promise<Response>;
+    stream(req: Request, opts: {
+        signal: AbortSignal;
+    }): AsyncIterable<StreamEvent>;
+    /** HTTP endpoint for this provider's chat completions / messages API. */
+    protected abstract buildUrl(req: Request): string;
+    /** Per-request headers. `apiKey` is already in scope — call `super.buildHeaders` first. */
+    protected buildHeaders(_req: Request): Record<string, string>;
+    /** Map Request fields to the wire request body. */
+    protected abstract buildBody(req: Request): Record<string, unknown>;
+    /** Translate wire SSE events into canonical StreamEvent[]. */
+    protected abstract parseStream(body: ReadableStream<Uint8Array> | NodeJS.ReadableStream | null, fallbackModel: string): AsyncIterable<StreamEvent>;
+    /** Build a ProviderError from an HTTP failure response. */
+    protected translateError(status: number, body: string): ProviderError;
+}
+
+interface AnthropicProviderOptions {
+    apiKey: string;
+    baseUrl?: string;
+    apiVersion?: string;
+    beta?: string[];
+    fetchImpl?: typeof fetch;
+}
+declare class AnthropicProvider extends WireAdapter {
+    readonly id = "anthropic";
+    readonly capabilities: Capabilities;
+    private readonly opts;
+    constructor(opts: AnthropicProviderOptions);
+    protected buildUrl(_req: Request): string;
+    protected buildHeaders(req: Request): Record<string, string>;
+    protected buildBody(req: Request): Record<string, unknown>;
+    protected parseStream(body: Parameters<typeof parseSSE>[0], fallbackModel: string): AsyncIterable<StreamEvent>;
+    protected translateError(status: number, text: string): ProviderError;
+    private normalizeMessage;
+}
+
+interface OpenAIToolSchema {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+declare function toolsToOpenAI(tools: Tool[]): OpenAIToolSchema[];
+interface OpenAIMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string | OpenAIContent[];
+    tool_calls?: OpenAIToolCall[];
+    tool_call_id?: string;
+    name?: string;
+}
+interface OpenAIContent {
+    type: 'text' | 'image_url';
+    text?: string;
+    image_url?: {
+        url: string;
+    };
+}
+interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ConvertOptions {
+    flattenContentToString?: boolean;
+    stripCacheControl?: boolean;
+    systemAsMessage?: boolean;
+    emptyToolCallContent?: 'null' | 'empty_string';
+}
+declare function messagesToOpenAI(system: TextBlock[] | undefined, messages: Message[], opts?: ConvertOptions): OpenAIMessage[];
+
+interface OpenAIProviderOptions {
+    apiKey: string;
+    baseUrl?: string;
+    organization?: string;
+    fetchImpl?: typeof fetch;
+    quirks?: ConvertOptions & {
+        parallelToolsDisabled?: boolean;
+        jsonArgumentsBuggy?: boolean;
+    };
+    id?: string;
+    capabilities?: Partial<Capabilities>;
+}
+declare class OpenAIProvider extends WireAdapter {
+    readonly id: string;
+    readonly capabilities: Capabilities;
+    protected readonly opts: OpenAIProviderOptions;
+    constructor(opts: OpenAIProviderOptions);
+    protected buildUrl(_req: Request): string;
+    protected buildHeaders(req: Request): Record<string, string>;
+    protected buildBody(req: Request): Record<string, unknown>;
+    protected parseStream(body: Parameters<typeof parseSSE>[0], fallbackModel: string): AsyncIterable<StreamEvent>;
+    protected translateError(status: number, text: string): ProviderError;
+    private stripCacheControl;
+}
+
+interface CompatibilityQuirks {
+    stripCacheControl?: boolean;
+    systemAsMessage?: boolean;
+    flattenContentToString?: boolean;
+    preserveToolCallIds?: boolean;
+    parallelToolsDisabled?: boolean;
+    jsonArgumentsBuggy?: boolean;
+    emptyToolCallContent?: 'null' | 'empty_string';
+}
+interface OpenAICompatibleOptions {
+    id: string;
+    apiKey: string;
+    baseUrl: string;
+    headers?: Record<string, string>;
+    quirks?: CompatibilityQuirks;
+    capabilities?: Partial<Capabilities>;
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional override for URL construction. Receives the base URL and request,
+     * returns the full URL to use. Allows custom providers with non-standard
+     * URL structures (e.g. Google with model-in-path, Anthropic with /v1/messages).
+     */
+    urlOverride?: (baseUrl: string, req: Request) => string;
+}
+declare class OpenAICompatibleProvider extends OpenAIProvider {
+    private readonly extraHeaders?;
+    private readonly urlOverride?;
+    constructor(opts: OpenAICompatibleOptions);
+    protected buildUrl(req: Request): string;
+    protected buildHeaders(req: Request): Record<string, string>;
+}
+
+/**
+ * Google Gemini wire format (generativelanguage.googleapis.com).
+ *
+ * Differences vs OpenAI:
+ *   - Endpoint includes the model in the path: /v1beta/models/{model}:generateContent
+ *   - Messages → `contents: [{ role: 'user'|'model', parts: [...] }]`
+ *   - System prompt → `systemInstruction: { parts: [{ text }] }`
+ *   - Tools → `tools: [{ functionDeclarations: [...] }]`
+ *   - Tool call → `parts: [{ functionCall: { name, args } }]`
+ *   - Tool result → `parts: [{ functionResponse: { name, response } }]`
+ *   - Auth via `?key=` query param or `x-goog-api-key` header
+ */
+interface GoogleProviderOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    id?: string;
+    capabilities?: Partial<Capabilities>;
+}
+declare class GoogleProvider extends WireAdapter {
+    readonly id: string;
+    readonly capabilities: Capabilities;
+    private readonly opts;
+    constructor(opts: GoogleProviderOptions);
+    protected buildUrl(req: Request): string;
+    protected buildHeaders(req: Request): Record<string, string>;
+    protected buildBody(req: Request): Record<string, unknown>;
+    protected parseStream(body: Parameters<typeof parseSSE>[0], fallbackModel: string): AsyncIterable<StreamEvent>;
+    protected translateError(status: number, text: string): ProviderError;
+    private buildGenConfig;
+}
+
+/**
+ * Resolve capabilities for a (provider, model) pair using the family default
+ * as a baseline and overlaying per-model facts from the ModelsRegistry.
+ */
+declare function capabilitiesFor(registry: ModelsRegistry, providerId: string, modelId: string): Promise<Capabilities>;
+
+/**
+ * Provider HTTP error bodies come in three or four shapes depending on
+ * vendor. Rather than dump the raw JSON into the error message (which is
+ * what was shipped to the user log before this module existed), we parse
+ * out the fields we care about — `type`, `message`, `requestId` — and put
+ * them on `ProviderError.body` for `describe()` and downstream rendering.
+ *
+ * The function is intentionally tolerant: anything we can't parse falls
+ * back to a truncated raw string, never throws.
+ */
+declare function parseProviderHttpError(providerId: string, status: number, rawText: string): ProviderError;
+
+declare function normalizeAnthropic(stop: string | null | undefined): StopReason;
+declare function normalizeOpenAI(stop: string | null | undefined): StopReason;
+
+interface AnthropicToolSchema {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+declare function toolsToAnthropic(tools: Tool[]): AnthropicToolSchema[];
+
+interface AnthropicBlock {
+    type: string;
+    text?: string;
+    id?: string;
+    name?: string;
+    input?: unknown;
+    content?: unknown;
+    tool_use_id?: string;
+    is_error?: boolean;
+    source?: {
+        type?: 'base64' | 'url';
+        media_type?: string;
+        data?: string;
+        url?: string;
+    };
+}
+interface FromAnthropicOptions {
+    /**
+     * Called once for each block whose `type` the converter doesn't recognize.
+     * The block is still dropped — this hook only exists so callers can wire
+     * it into observability (event bus, logger) instead of silently losing
+     * data. Anthropic ships new block types over time (`thinking`,
+     * `server_tool_use`, etc.) and we want a way to find out without
+     * inflating the conversion logic itself.
+     */
+    onUnsupported?: (type: string, block: AnthropicBlock) => void;
+}
+declare function contentFromAnthropic(blocks: AnthropicBlock[], opts?: FromAnthropicOptions): ContentBlock[];
+
+interface OpenAIChoice {
+    message: {
+        role: string;
+        content: string | null;
+        tool_calls?: OpenAIToolCall[];
+    };
+    finish_reason: string | null;
+}
+interface FromOpenAIOptions {
+    /**
+     * Deprecated: the sanitizer fallback is now always attempted. Kept for
+     * backward compatibility; the value is ignored.
+     */
+    jsonArgumentsBuggy?: boolean;
+    /**
+     * Called when a tool call's `arguments` field can't be parsed even after
+     * the sanitizer pass. Callers can use this to emit a structured event,
+     * log it, or surface it in a UI. The block is still appended with
+     * `{ __raw_arguments }` so the tool gets *something* to fail on, but
+     * silently producing garbage input is the kind of bug that wastes
+     * debugging hours — this is the hook to find out.
+     */
+    onParseFailure?: (info: {
+        toolName: string;
+        toolCallId: string;
+        raw: string;
+    }) => void;
+}
+declare function contentFromOpenAI(choice: OpenAIChoice, opts?: FromOpenAIOptions): ContentBlock[];
+
+interface BuildFactoriesOptions {
+    registry: ModelsRegistry;
+    /** Used to log unsupported families during boot. */
+    log?: Logger;
+}
+/**
+ * Build one ProviderFactory per provider known to models.dev. The factory's
+ * `create(cfg)` resolves the wire-family at construction time and returns the
+ * matching transport. Unsupported families return a stub that throws when
+ * complete() is called, so the system can still boot.
+ */
+declare function buildProviderFactoriesFromRegistry(opts: BuildFactoriesOptions): Promise<ProviderFactory[]>;
+/**
+ * Build a Provider purely from config — no models.dev lookup at all.
+ * Used for user-defined providers and offline operation.
+ */
+declare function makeProviderFromConfig(id: string, cfg: ProviderConfig): Provider;
+
+export { AnthropicProvider, type AnthropicProviderOptions, type BuildFactoriesOptions, type CompatibilityQuirks, type ConvertOptions, GoogleProvider, type GoogleProviderOptions, type OpenAIChoice, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OpenAIMessage, OpenAIProvider, type OpenAIProviderOptions, type OpenAIToolCall, WireAdapter, buildProviderFactoriesFromRegistry, capabilitiesFor, contentFromAnthropic, contentFromOpenAI, makeProviderFromConfig, messagesToOpenAI, normalizeAnthropic, normalizeOpenAI, parseProviderHttpError, toolsToAnthropic, toolsToOpenAI };