@wrongstack/providers 0.1.2 → 0.1.4

package/LICENSE

@@ -1,17 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+MIT License
 
-   Copyright 2026 ECOSTACK TECHNOLOGY OÜ
+Copyright (c) 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
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-       http://www.apache.org/licenses/LICENSE-2.0
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-   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.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Provider, Capabilities, Request, Response, StreamEvent, ProviderError, TextBlock, Message, Tool, ModelsRegistry, StopReason, ContentBlock, Logger, ProviderFactory, ProviderConfig } from '@wrongstack/core';
+import { Provider, Capabilities, Request, Response, StreamEvent, ProviderError, TextBlock, Message, Tool, WireFamily, ProviderFactory, Usage, StopReason, ModelsRegistry, ContentBlock, Logger, ProviderConfig } from '@wrongstack/core';
 
 /**
  * Minimal Server-Sent Events parser for HTTP streaming responses.
@@ -203,6 +203,157 @@ declare class GoogleProvider extends WireAdapter {
     private buildGenConfig;
 }
 
+/**
+ * Declarative wire-format definition. Sufficient to add a new HTTP+SSE
+ * provider without subclassing `WireAdapter` — the boilerplate (HTTP errors,
+ * abort wiring, SSE body parsing) is shared.
+ *
+ * The shape covers the variation that actually matters between providers:
+ *   - URL template (path, query)
+ *   - Auth headers (x-api-key, Authorization, etc.)
+ *   - Request body (field names, system-prompt placement, tool format)
+ *   - SSE event translation (one wire event → 0+ canonical events)
+ *
+ * Anything more exotic (non-SSE streams, multipart bodies, OAuth flows) still
+ * needs a hand-written subclass — those cases are too varied to template.
+ *
+ * `S` is provider-internal state threaded across SSE events for one stream:
+ * accumulating partial tool-call JSON, tracking block kinds, carrying the
+ * model id forward from `message_start`, etc. Each `stream()` call gets a
+ * fresh `S` via `createStreamState`.
+ */
+interface WireFormatConfig<S = Record<string, unknown>> {
+    /** Provider id (matches catalog id when the provider is in models.dev). */
+    id: string;
+    /** Wire family — used by the registry's factory list. */
+    family: WireFamily;
+    capabilities: Capabilities;
+    /** Used when the user doesn't override via config.baseUrl. */
+    defaultBaseUrl: string;
+    /** Build the HTTPS endpoint. Receives the (possibly user-overridden) base URL. */
+    buildUrl(baseUrl: string, req: Request): string;
+    /** Per-request headers. Default `content-type`/`accept` are provided already. */
+    buildHeaders(apiKey: string, req: Request): Record<string, string>;
+    /** Map a canonical Request onto the provider's body shape. */
+    buildBody(req: Request): Record<string, unknown>;
+    /** Construct fresh per-stream state. Called once per `stream()` call. */
+    createStreamState(fallbackModel: string): S;
+    /**
+     * Translate one SSE event into 0+ canonical events. Mutating `state` is
+     * expected — providers carry per-stream accumulators (partial tool JSON,
+     * current model id, usage) here.
+     */
+    parseStreamEvent(msg: SSEMessage, state: S): StreamEvent[];
+    /**
+     * Optional: yield any final events after the upstream stream closes
+     * (e.g. emit a synthetic `message_stop` when the wire format ends with
+     * `[DONE]` instead of an explicit terminator).
+     */
+    finalizeStream?(state: S): StreamEvent[];
+    /** Optional override; defaults to the shared HTTP error parser. */
+    normalizeError?(status: number, body: string): ProviderError;
+}
+/**
+ * Concrete Provider built from a declarative config. Extends WireAdapter to
+ * inherit the canonical HTTP + abort + error machinery.
+ */
+declare class WireFormatProvider<S = Record<string, unknown>> extends WireAdapter {
+    readonly id: string;
+    readonly capabilities: Capabilities;
+    private readonly cfg;
+    constructor(cfg: WireFormatConfig<S>, opts: {
+        apiKey: string;
+        baseUrl?: string;
+        fetchImpl?: typeof fetch;
+    });
+    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, body: string): ProviderError;
+    private runStream;
+}
+/**
+ * Identity helper that gives authors type checking on the config literal.
+ * Use at module level:
+ *
+ *   export const myProvider = defineWireFormat({
+ *     id: 'mistral',
+ *     family: 'openai-compatible',
+ *     capabilities: { ... },
+ *     ...
+ *   });
+ */
+declare function defineWireFormat<S = Record<string, unknown>>(cfg: WireFormatConfig<S>): WireFormatConfig<S>;
+interface WireFactoryOptions {
+    /**
+     * Optional config-time override of the API key. When omitted, the factory
+     * reads `cfg.apiKey` (passed in at create time by the registry / config
+     * loader). Setting this here is useful in tests.
+     */
+    apiKey?: string;
+    /** Override the base URL at factory build time. */
+    baseUrl?: string;
+}
+/**
+ * Build a `ProviderFactory` from a declarative wire-format. Plug into
+ * `ProviderRegistry.register(...)` or use in `buildProviderFactoriesFromRegistry`
+ * for catalog-driven discovery.
+ */
+declare function createWireFormatFactory(cfg: WireFormatConfig, opts?: WireFactoryOptions): ProviderFactory;
+
+interface MistralStreamState {
+    model: string;
+    started: boolean;
+    toolCalls: Map<number, {
+        id?: string;
+        name?: string;
+        partial: string;
+        emittedStart: boolean;
+    }>;
+}
+declare const mistralWireFormat: WireFormatConfig<MistralStreamState>;
+
+type BlockKind = 'text' | 'tool_use' | 'unknown';
+interface AnthropicStreamState {
+    model: string;
+    usage: Usage;
+    stopReason: StopReason;
+    started: boolean;
+    blocks: Map<number, {
+        kind: BlockKind;
+        id?: string;
+        name?: string;
+        partial: string;
+    }>;
+}
+declare const anthropicWireFormat: WireFormatConfig<AnthropicStreamState>;
+
+interface OpenAIStreamState {
+    model: string;
+    usage: Usage;
+    stopReason: StopReason;
+    started: boolean;
+    textOpen: boolean;
+    toolByIndex: Map<number, {
+        id: string;
+        name: string;
+        argBuf: string;
+    }>;
+    finalEmitted: boolean;
+}
+declare const openaiWireFormat: WireFormatConfig<OpenAIStreamState>;
+
+interface GoogleStreamState {
+    model: string;
+    usage: Usage;
+    stopReason: StopReason;
+    started: boolean;
+    sawFunctionCall: boolean;
+    finalEmitted: boolean;
+}
+declare const googleWireFormat: WireFormatConfig<GoogleStreamState>;
+
 /**
  * Resolve capabilities for a (provider, model) pair using the family default
  * as a baseline and overlaying per-model facts from the ModelsRegistry.
@@ -308,4 +459,4 @@ declare function buildProviderFactoriesFromRegistry(opts: BuildFactoriesOptions)
  */
 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 };
+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, type WireFactoryOptions, type WireFormatConfig, WireFormatProvider, anthropicWireFormat, buildProviderFactoriesFromRegistry, capabilitiesFor, contentFromAnthropic, contentFromOpenAI, createWireFormatFactory, defineWireFormat, googleWireFormat, makeProviderFromConfig, messagesToOpenAI, mistralWireFormat, normalizeAnthropic, normalizeOpenAI, openaiWireFormat, parseProviderHttpError, toolsToAnthropic, toolsToOpenAI };