@springbrand/model-client 0.0.0-stage → 0.1.0-alpha.1

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @springbrand/model-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native OpenRouter HTTP and payload helpers for Node and Workers. Runtime dependencies: none.
+The package does not depend on Pi, an Agent runtime, environment variables or platform bindings.
+Callers provide credentials, protocol-specific base URLs, model IDs and business schemas.
+
+```ts
+import {
+  requestOpenRouter,
+  withOpenRouterRouting,
+  withOpenRouterStructuredOutput,
+} from "@springbrand/model-client";
+
+const protocol = "openrouter-chat";
+const body = withOpenRouterRouting(withOpenRouterStructuredOutput({
+  model: modelId,
+  messages: [{ role: "user", content: prompt }],
+  stream: false,
+}, protocol, schema));
+const response = await requestOpenRouter({
+  protocol, apiKey, baseURL, headers: gatewayHeaders,
+}, body, { signal });
+```
+
+`requestOpenRouter` preserves the native body and returns the original `Response`,
+including non-2xx status, request IDs, usage and SSE. Callers check status and
+validate generated content against their schema. No retries or response parsing
+are added. Payload helpers are opt-in; raw requests remain lossless.
+
+Base URLs follow the native protocol. Supply resolved Gateway URLs and headers
+in the same way; the client never rewrites one version prefix into another.
+
+| Protocol | Direct base URL | Appended path |
+| --- | --- | --- |
+| `openrouter-messages` | `https://openrouter.ai/api` | `/v1/messages` |
+| `openrouter-chat` | `https://openrouter.ai/api/v1` | `/chat/completions` |
+| `openrouter-responses` | `https://openrouter.ai/api/v1` | `/responses` |
+| `openrouter-decisions` | `https://openrouter.ai/api/alpha` | `/decisions` |
+
+Jev uses OpenRouter's native [Decisions API](https://openrouter.ai/docs/api/api-reference/alphadecisions/submit-a-decisions-request)
+with the same OpenRouter key and transport:
+
+```ts
+const response = await requestOpenRouter({
+  protocol: "openrouter-decisions",
+  baseURL: "https://openrouter.ai/api/alpha",
+  apiKey,
+}, {
+  model: decisionModelId,
+  state: { task: "Find a source-control connector" },
+  questions: {
+    source: {
+      type: "choice",
+      instructions: "Which source fits the task?",
+      criteria: { git: "Source control", calendar: "Scheduling" },
+    },
+  },
+}, { signal });
+```
+
+The body and response stay native: `state`, `questions`, `answers`, probabilities,
+usage and future fields are untouched. Choice, Score, Noul and Box questions
+follow the [Jev model's capabilities](https://openrouter.ai/docs/guides/community/jev).
+Callers choose the model and validate answers, then apply their own ranking,
+thresholds and follow-up policy. `withOpenRouterStructuredOutput` accepts only
+`OpenRouterGenerationProtocol`; Decisions supplies its own typed questions.
+
+Pi consumers inject `createOpenRouterFetch({ apiKey, fetch })` into Pi's `fetch`
+option. Pi retains model registration, message conversion, Tool execution and
+stream parsing. `openRouterHeaders` also prepares Bearer headers for SDKs that
+validate credentials before invoking fetch. A configured key overrides incoming
+Authorization; `x-api-key` is removed. Fetch without a configured key preserves
+an SDK-supplied Authorization header.
+
+Source, declarations and runtime JavaScript are built with `pnpm build`;
+`pnpm pack` runs the same build. The published package exports only compiled ESM
+and declarations. Source tests run in Node and Workers through the repository's
+Vitest configuration.

package/dist/contracts.d.ts

@@ -0,0 +1,21 @@
+/** Native APIs that generate assistant responses. */
+export type OpenRouterGenerationProtocol = "openrouter-messages" | "openrouter-chat" | "openrouter-responses";
+export type OpenRouterProtocol = OpenRouterGenerationProtocol | "openrouter-decisions";
+/** A caller-owned endpoint with resolved credentials. */
+export interface OpenRouterEndpoint {
+    readonly protocol: OpenRouterProtocol;
+    readonly baseURL: string;
+    readonly apiKey: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export interface OpenRouterRequestOptions {
+    readonly headers?: HeadersInit;
+    readonly signal?: AbortSignal;
+    readonly fetch?: typeof globalThis.fetch;
+}
+/** Credentials may also be supplied by an SDK in the outgoing Request. */
+export interface OpenRouterFetchOptions {
+    readonly apiKey?: string;
+    readonly headers?: HeadersInit;
+    readonly fetch?: typeof globalThis.fetch;
+}

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/endpoint.d.ts

@@ -0,0 +1,3 @@
+import type { OpenRouterEndpoint } from "./contracts.js";
+/** Caller supplies the native protocol base (/api, /api/v1, or /api/alpha). */
+export declare function openRouterRequestUrl(endpoint: Pick<OpenRouterEndpoint, "protocol" | "baseURL">): string;

package/dist/endpoint.js

@@ -0,0 +1,11 @@
+/** Caller supplies the native protocol base (/api, /api/v1, or /api/alpha). */
+export function openRouterRequestUrl(endpoint) {
+    const baseURL = endpoint.baseURL.replace(/\/+$/, "");
+    switch (endpoint.protocol) {
+        case "openrouter-messages": return `${baseURL}/v1/messages`;
+        case "openrouter-chat": return `${baseURL}/chat/completions`;
+        case "openrouter-responses": return `${baseURL}/responses`;
+        case "openrouter-decisions": return `${baseURL}/decisions`;
+        default: throw new Error(`Not an OpenRouter protocol: ${endpoint.protocol}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { OpenRouterEndpoint, OpenRouterFetchOptions, OpenRouterGenerationProtocol, OpenRouterProtocol, OpenRouterRequestOptions, } from "./contracts.js";
+export { openRouterRequestUrl } from "./endpoint.js";
+export { createOpenRouterFetch, openRouterHeaders, requestOpenRouter } from "./transport.js";
+export { withOpenRouterRouting } from "./routing.js";
+export { withOpenRouterStructuredOutput } from "./structured-output.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { openRouterRequestUrl } from "./endpoint.js";
+export { createOpenRouterFetch, openRouterHeaders, requestOpenRouter } from "./transport.js";
+export { withOpenRouterRouting } from "./routing.js";
+export { withOpenRouterStructuredOutput } from "./structured-output.js";

package/dist/routing.d.ts

@@ -0,0 +1,2 @@
+/** Apply native OpenRouter routing without owning model or provider policy. */
+export declare function withOpenRouterRouting(body: Readonly<Record<string, unknown>>, routing?: Readonly<Record<string, unknown>>, sessionId?: string): Record<string, unknown>;

package/dist/routing.js

@@ -0,0 +1,13 @@
+/** Apply native OpenRouter routing without owning model or provider policy. */
+export function withOpenRouterRouting(body, routing, sessionId) {
+    const provider = body.provider;
+    return {
+        ...body,
+        ...(sessionId ? { session_id: sessionId } : {}),
+        provider: {
+            ...(provider && typeof provider === "object" && !Array.isArray(provider) ? provider : {}),
+            ...routing,
+            require_parameters: true,
+        },
+    };
+}

package/dist/structured-output.d.ts

@@ -0,0 +1,3 @@
+import type { OpenRouterGenerationProtocol } from "./contracts.js";
+/** Map a caller-owned JSON Schema into the selected native protocol. */
+export declare function withOpenRouterStructuredOutput(body: Readonly<Record<string, unknown>>, protocol: OpenRouterGenerationProtocol, schema: Readonly<Record<string, unknown>>, name?: string): Record<string, unknown>;

package/dist/structured-output.js

@@ -0,0 +1,30 @@
+/** Map a caller-owned JSON Schema into the selected native protocol. */
+export function withOpenRouterStructuredOutput(body, protocol, schema, name = "output") {
+    switch (protocol) {
+        case "openrouter-messages": {
+            const current = body.output_config;
+            return {
+                ...body,
+                output_config: {
+                    ...(current && typeof current === "object" && !Array.isArray(current) ? current : {}),
+                    format: { type: "json_schema", schema },
+                },
+            };
+        }
+        case "openrouter-chat": return {
+            ...body,
+            response_format: { type: "json_schema", json_schema: { name, strict: true, schema } },
+        };
+        case "openrouter-responses": {
+            const current = body.text;
+            return {
+                ...body,
+                text: {
+                    ...(current && typeof current === "object" && !Array.isArray(current) ? current : {}),
+                    format: { type: "json_schema", name, strict: true, schema },
+                },
+            };
+        }
+        default: throw new Error(`Not an OpenRouter generation protocol: ${protocol}`);
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,6 @@
+import type { OpenRouterEndpoint, OpenRouterFetchOptions, OpenRouterRequestOptions } from "./contracts.js";
+/** OpenRouter uses Bearer authentication for all three native protocols. */
+export declare function openRouterHeaders(apiKey: string | undefined, ...sources: (HeadersInit | undefined)[]): Headers;
+/** Shared native/SDK transport. Response status, headers and streaming body stay untouched. */
+export declare function createOpenRouterFetch(options?: OpenRouterFetchOptions): typeof globalThis.fetch;
+export declare function requestOpenRouter(endpoint: OpenRouterEndpoint, body: Readonly<Record<string, unknown>>, options?: OpenRouterRequestOptions): Promise<Response>;

package/dist/transport.js

@@ -0,0 +1,37 @@
+import { openRouterRequestUrl } from "./endpoint.js";
+/** OpenRouter uses Bearer authentication for all three native protocols. */
+export function openRouterHeaders(apiKey, ...sources) {
+    const headers = new Headers();
+    for (const source of sources) {
+        new Headers(source).forEach((value, name) => headers.set(name, value));
+    }
+    headers.delete("x-api-key");
+    if (apiKey !== undefined)
+        headers.set("authorization", `Bearer ${apiKey}`);
+    return headers;
+}
+/** Shared native/SDK transport. Response status, headers and streaming body stay untouched. */
+export function createOpenRouterFetch(options = {}) {
+    const fetcher = options.fetch ?? globalThis.fetch;
+    return (input, init) => {
+        const request = new Request(input, init);
+        return fetcher(new Request(request, {
+            headers: openRouterHeaders(options.apiKey, options.headers, request.headers),
+        }));
+    };
+}
+export function requestOpenRouter(endpoint, body, options = {}) {
+    const url = openRouterRequestUrl(endpoint);
+    const headers = new Headers(options.headers);
+    headers.set("content-type", "application/json");
+    return createOpenRouterFetch({
+        apiKey: endpoint.apiKey,
+        headers: endpoint.headers,
+        fetch: options.fetch,
+    })(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: options.signal,
+    });
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@springbrand/model-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
 }