@effect/ai-openrouter 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/index.d.ts

@@ -1,16 +1,16 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as Generated from "./Generated.ts";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenRouterClient from "./OpenRouterClient.ts";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenRouterConfig from "./OpenRouterConfig.ts";
 /**
@@ -19,11 +19,11 @@ export * as OpenRouterConfig from "./OpenRouterConfig.ts";
  * Provides OpenRouter-specific metadata fields for AI error types through
  * module augmentation, enabling typed access to OpenRouter error details.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenRouterError from "./OpenRouterError.ts";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenRouterLanguageModel from "./OpenRouterLanguageModel.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,17 +1,17 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 // @barrel: Auto-generated exports. Do not edit manually.
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as Generated from "./Generated.js";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenRouterClient from "./OpenRouterClient.js";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenRouterConfig from "./OpenRouterConfig.js";
 /**
@@ -20,11 +20,11 @@ export * as OpenRouterConfig from "./OpenRouterConfig.js";
  * Provides OpenRouter-specific metadata fields for AI error types through
  * module augmentation, enabling typed access to OpenRouter error details.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenRouterError from "./OpenRouterError.js";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as OpenRouterLanguageModel from "./OpenRouterLanguageModel.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect/ai-openrouter",
-  "version": "4.0.0-beta.66",
+  "version": "4.0.0-beta.67",
   "type": "module",
   "license": "MIT",
   "description": "An OpenRouter provider integration for Effect AI SDK",
@@ -43,10 +43,10 @@
     "provenance": true
   },
   "devDependencies": {
-    "effect": "^4.0.0-beta.66"
+    "effect": "^4.0.0-beta.67"
   },
   "peerDependencies": {
-    "effect": "^4.0.0-beta.66"
+    "effect": "^4.0.0-beta.67"
   },
   "scripts": {
     "codegen": "effect-utils codegen",

package/src/Generated.ts

@@ -1,5 +1,5 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 import * as Data from "effect/Data"

package/src/OpenRouterClient.ts

@@ -1,5 +1,27 @@
 /**
- * @since 1.0.0
+ * The `OpenRouterClient` module provides an Effect service for calling
+ * OpenRouter's chat completions API. It wraps the generated OpenRouter HTTP
+ * client with Effect-native constructors, layers, typed errors, and streaming
+ * support.
+ *
+ * **Common tasks**
+ *
+ * - Build a client from explicit options with {@link make}
+ * - Provide the client to an application with {@link layer} or {@link layerConfig}
+ * - Create non-streaming chat completions with {@link Service.createChatCompletion}
+ * - Create server-sent event chat completion streams with
+ *   {@link Service.createChatCompletionStream}
+ * - Customize authentication, base URL, OpenRouter ranking headers, or the
+ *   underlying HTTP client through {@link Options}
+ *
+ * **Gotchas**
+ *
+ * - Streaming requests are sent directly to `/chat/completions` with `stream`
+ *   and `stream_options.include_usage` enabled by this module.
+ * - OpenRouter API failures, HTTP client failures, and schema decoding failures
+ *   are mapped into `AiError` values for the exported service methods.
+ *
+ * @since 4.0.0
  */
 import type * as Config from "effect/Config"
 import * as Context from "effect/Context"
@@ -30,8 +52,8 @@ import { OpenRouterConfig } from "./OpenRouterConfig.ts"
  * Provides methods for interacting with OpenRouter's Chat Completions API,
  * including both synchronous and streaming message creation.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Service {
   readonly client: Generated.OpenRouterClient
@@ -55,8 +77,15 @@ export interface Service {
 }
 
 /**
- * @since 1.0.0
+ * Decoded `data` payload from an OpenRouter chat completion streaming chunk.
+ *
+ * **Details**
+ *
+ * The payload contains streamed choices, model metadata, optional usage, and may
+ * include an OpenRouter error object for a streamed response.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export type ChatStreamingResponseChunkData = typeof Generated.ChatStreamingResponseChunk.fields.data.Type
 
@@ -67,8 +96,8 @@ export type ChatStreamingResponseChunkData = typeof Generated.ChatStreamingRespo
 /**
  * Service identifier for the OpenRouter client.
  *
- * @since 1.0.0
  * @category service
+ * @since 4.0.0
  */
 export class OpenRouterClient extends Context.Service<
   OpenRouterClient,
@@ -82,8 +111,8 @@ export class OpenRouterClient extends Context.Service<
 /**
  * Configuration options for creating an OpenRouter client.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Options = {
   readonly apiKey?: Redacted.Redacted<string> | undefined
@@ -115,8 +144,8 @@ export type Options = {
 /**
  * Creates an OpenRouter client service with the given options.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(
   function*(options: Options): Effect.fn.Return<Service, never, HttpClient.HttpClient> {
@@ -212,8 +241,8 @@ export const make = Effect.fnUntraced(
 /**
  * Creates a layer for the OpenRouter client with the given options.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: Options): Layer.Layer<OpenRouterClient, never, HttpClient.HttpClient> =>
   Layer.effect(OpenRouterClient, make(options))
@@ -222,8 +251,8 @@ export const layer = (options: Options): Layer.Layer<OpenRouterClient, never, Ht
  * Creates a layer for the OpenRouter client, loading the requisite
  * configuration via Effect's `Config` module.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layerConfig = (options?: {
   /**

package/src/OpenRouterConfig.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * The `OpenRouterConfig` module provides contextual configuration for the
+ * OpenRouter provider integration. It is used to customize the HTTP client that
+ * backs OpenRouter requests without rebuilding the provider layer itself.
+ *
+ * Use {@link withClientTransform} when a single effect, workflow, or scoped
+ * portion of an application needs to add cross-cutting HTTP client behavior
+ * such as request logging, retries, proxy routing, additional headers, or test
+ * doubles. The configuration is read from the current Effect context, so the
+ * transform only applies where the returned effect is run with that context.
+ *
+ * **Gotchas**
+ *
+ * - Each call to {@link withClientTransform} replaces the current client
+ *   transform for the provided effect; compose transforms manually when both
+ *   behaviors should apply.
+ * - The transform receives and returns an `HttpClient`, so it should preserve
+ *   the OpenRouter client contract while adding behavior around it.
+ *
+ * @since 4.0.0
  */
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
@@ -7,15 +25,20 @@ import { dual } from "effect/Function"
 import type { HttpClient } from "effect/unstable/http/HttpClient"
 
 /**
- * @since 1.0.0
+ * Context service carrying scoped OpenRouter provider configuration for client
+ * operations.
+ *
  * @category services
+ * @since 4.0.0
  */
 export class OpenRouterConfig extends Context.Service<
   OpenRouterConfig,
   OpenRouterConfig.Service
 >()("@effect/ai-openrouter/OpenRouterConfig") {
   /**
-   * @since 1.0.0
+   * Gets the configured OpenRouter service from the current context when present.
+   *
+   * @since 4.0.0
    */
   static readonly getOrUndefined: Effect.Effect<typeof OpenRouterConfig.Service | undefined> = Effect.map(
     Effect.context<never>(),
@@ -24,12 +47,17 @@ export class OpenRouterConfig extends Context.Service<
 }
 
 /**
- * @since 1.0.0
+ * Types associated with the `OpenRouterConfig` context service.
+ *
+ * @since 4.0.0
  */
 export declare namespace OpenRouterConfig {
   /**
-   * @since 1.0.0
+   * Configuration values read by OpenRouter provider operations when resolving
+   * the generated HTTP client.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Service {
     readonly transformClient?: ((client: HttpClient) => HttpClient) | undefined
@@ -37,18 +65,27 @@ export declare namespace OpenRouterConfig {
 }
 
 /**
- * @since 1.0.0
+ * Provides a scoped transform for the OpenRouter HTTP client used by provider
+ * operations.
+ *
  * @category configuration
+ * @since 4.0.0
  */
 export const withClientTransform: {
   /**
-   * @since 1.0.0
+   * Provides a scoped transform for the OpenRouter HTTP client used by provider
+   * operations.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   (transform: (client: HttpClient) => HttpClient): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * @since 1.0.0
+   * Provides a scoped transform for the OpenRouter HTTP client used by provider
+   * operations.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(
     self: Effect.Effect<A, E, R>,
@@ -56,13 +93,19 @@ export const withClientTransform: {
   ): Effect.Effect<A, E, R>
 } = dual<
   /**
-   * @since 1.0.0
+   * Provides a scoped transform for the OpenRouter HTTP client used by provider
+   * operations.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   (transform: (client: HttpClient) => HttpClient) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>,
   /**
-   * @since 1.0.0
+   * Provides a scoped transform for the OpenRouter HTTP client used by provider
+   * operations.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(
     self: Effect.Effect<A, E, R>,

package/src/OpenRouterError.ts

@@ -4,14 +4,14 @@
  * Provides OpenRouter-specific metadata fields for AI error types through
  * module augmentation, enabling typed access to OpenRouter error details.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
  * OpenRouter-specific error metadata fields.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenRouterErrorMetadata = {
   /**
@@ -31,8 +31,8 @@ export type OpenRouterErrorMetadata = {
 /**
  * OpenRouter-specific rate limit metadata fields.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenRouterRateLimitMetadata = OpenRouterErrorMetadata & {
   readonly limit: string | null
@@ -42,43 +42,164 @@ export type OpenRouterRateLimitMetadata = OpenRouterErrorMetadata & {
 }
 
 declare module "effect/unstable/ai/AiError" {
+  /**
+   * OpenRouter metadata attached to `RateLimitError` values.
+   *
+   * Captures OpenRouter error details together with rate limit header
+   * information from responses where the provider rejected the request because
+   * a limit was reached.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface RateLimitErrorMetadata {
+    /**
+     * OpenRouter-specific details for the rate limit response.
+     */
     readonly openrouter?: OpenRouterRateLimitMetadata | null
   }
 
+  /**
+   * OpenRouter metadata attached to `QuotaExhaustedError` values.
+   *
+   * Preserves provider error details for failures caused by exhausted account,
+   * billing, or usage quota.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface QuotaExhaustedErrorMetadata {
+    /**
+     * OpenRouter-specific details for the quota exhaustion response.
+     */
     readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
+  /**
+   * OpenRouter metadata attached to `AuthenticationError` values.
+   *
+   * Preserves provider error details for failed API key, authorization, or
+   * permission checks.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface AuthenticationErrorMetadata {
+    /**
+     * OpenRouter-specific details for the authentication failure.
+     */
     readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
+  /**
+   * OpenRouter metadata attached to `ContentPolicyError` values.
+   *
+   * Preserves provider error details when OpenRouter rejects input or output
+   * because it violates a content policy.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface ContentPolicyErrorMetadata {
+    /**
+     * OpenRouter-specific details for the content policy response.
+     */
     readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
+  /**
+   * OpenRouter metadata attached to `InvalidRequestError` values.
+   *
+   * Preserves provider error details for malformed requests, unsupported
+   * parameters, or other request validation failures reported by OpenRouter.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface InvalidRequestErrorMetadata {
+    /**
+     * OpenRouter-specific details for the invalid request response.
+     */
     readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
+  /**
+   * OpenRouter metadata attached to `InternalProviderError` values.
+   *
+   * Preserves provider error details for OpenRouter-side failures such as
+   * transient server errors or overload responses.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface InternalProviderErrorMetadata {
+    /**
+     * OpenRouter-specific details for the internal provider response.
+     */
     readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
+  /**
+   * OpenRouter metadata attached to `InvalidOutputError` values.
+   *
+   * Preserves provider error details when an OpenRouter response cannot be
+   * parsed or validated as the expected output.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface InvalidOutputErrorMetadata {
+    /**
+     * OpenRouter-specific details for the invalid output response.
+     */
     readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
+  /**
+   * OpenRouter metadata attached to `StructuredOutputError` values.
+   *
+   * Preserves provider error details when OpenRouter returns content that does
+   * not satisfy the requested structured output schema.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface StructuredOutputErrorMetadata {
+    /**
+     * OpenRouter-specific details for the structured output failure.
+     */
     readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
+  /**
+   * OpenRouter metadata attached to `UnsupportedSchemaError` values.
+   *
+   * Preserves provider error details when an unsupported schema failure is
+   * associated with an OpenRouter response.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface UnsupportedSchemaErrorMetadata {
+    /**
+     * OpenRouter-specific details for the unsupported schema failure.
+     */
     readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
+  /**
+   * OpenRouter metadata attached to `UnknownError` values.
+   *
+   * Preserves provider error details for OpenRouter failures that do not map
+   * cleanly to a more specific AI error category.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface UnknownErrorMetadata {
+    /**
+     * OpenRouter-specific details for the unclassified provider failure.
+     */
     readonly openrouter?: OpenRouterErrorMetadata | null
   }
 }