@effect/ai-openrouter 4.0.0-beta.9 → 4.0.0-beta.91

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect/ai-openrouter",
-  "version": "4.0.0-beta.9",
+  "version": "4.0.0-beta.91",
   "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.9"
+    "effect": "^4.0.0-beta.91"
   },
   "peerDependencies": {
-    "effect": "^4.0.0-beta.9"
+    "effect": "^4.0.0-beta.91"
   },
   "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"
@@ -8923,7 +8923,7 @@ export const make = (
     Type,
     DecodingServices
   >(
-    schema: Schema.Decoder<Type, DecodingServices>
+    schema: Schema.ConstraintDecoder<Type, DecodingServices>
   ) =>
   (
     request: HttpClientRequest.HttpClientRequest
@@ -8939,10 +8939,10 @@ export const make = (
       Stream.pipeThroughChannel(Sse.decodeDataSchema(schema))
     )
   const decodeSuccess =
-    <Schema extends Schema.Top>(schema: Schema) => (response: HttpClientResponse.HttpClientResponse) =>
+    <Schema extends Schema.Constraint>(schema: Schema) => (response: HttpClientResponse.HttpClientResponse) =>
       HttpClientResponse.schemaBodyJson(schema)(response)
   const decodeError =
-    <const Tag extends string, Schema extends Schema.Top>(tag: Tag, schema: Schema) =>
+    <const Tag extends string, Schema extends Schema.Constraint>(tag: Tag, schema: Schema) =>
     (response: HttpClientResponse.HttpClientResponse) =>
       Effect.flatMap(
         HttpClientResponse.schemaBodyJson(schema)(response),

package/src/OpenRouterClient.ts

@@ -1,14 +1,19 @@
 /**
- * @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, authentication and optional
+ * site ranking headers, typed errors, and streaming support.
+ *
+ * @since 4.0.0
  */
 import type * as Config from "effect/Config"
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import { identity } from "effect/Function"
 import * as Layer from "effect/Layer"
 import * as Predicate from "effect/Predicate"
 import type * as Redacted from "effect/Redacted"
 import * as Schema from "effect/Schema"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import type * as AiError from "effect/unstable/ai/AiError"
 import * as Sse from "effect/unstable/encoding/Sse"
@@ -27,11 +32,13 @@ import { OpenRouterConfig } from "./OpenRouterConfig.ts"
 /**
  * The OpenRouter client service interface.
  *
+ * **Details**
+ *
  * 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 +62,15 @@ export interface Service {
 }
 
 /**
- * @since 1.0.0
- * @category Models
+ * 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
 
@@ -65,12 +79,21 @@ export type ChatStreamingResponseChunkData = typeof Generated.ChatStreamingRespo
 // =============================================================================
 
 /**
- * Service identifier for the OpenRouter client.
+ * Service tag for the OpenRouter client.
+ *
+ * **When to use**
  *
- * @since 1.0.0
- * @category service
+ * Use when accessing or providing the OpenRouter client service through
+ * Effect's context.
+ *
+ * @see {@link make} for constructing an OpenRouter client effectfully
+ * @see {@link layer} for providing a client from explicit options
+ * @see {@link layerConfig} for providing a client from `Config`
+ *
+ * @category services
+ * @since 4.0.0
  */
-export class OpenRouterClient extends ServiceMap.Service<
+export class OpenRouterClient extends Context.Service<
   OpenRouterClient,
   Service
 >()("@effect/ai-openrouter/OpenRouterClient") {}
@@ -80,10 +103,10 @@ export class OpenRouterClient extends ServiceMap.Service<
 // =============================================================================
 
 /**
- * Configuration options for creating an OpenRouter client.
+ * Configuration for creating an OpenRouter client.
  *
- * @since 1.0.0
- * @category models
+ * @category options
+ * @since 4.0.0
  */
 export type Options = {
   readonly apiKey?: Redacted.Redacted<string> | undefined
@@ -103,7 +126,9 @@ export type Options = {
   /**
    * Optional transformer for the underlying HTTP client.
    *
-   * Use this to add middleware, logging, or custom request/response handling.
+   * **When to use**
+   *
+   * Use to add middleware, logging, or custom request/response handling.
    */
   readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
 }
@@ -113,10 +138,30 @@ export type Options = {
 // =============================================================================
 
 /**
- * Creates an OpenRouter client service with the given options.
+ * Creates an OpenRouter client service from explicit options.
+ *
+ * **When to use**
+ *
+ * Use when you need the OpenRouter client service value inside an effect.
+ *
+ * **Details**
+ *
+ * The returned service uses the current `HttpClient`, prepends `apiUrl` or
+ * `https://openrouter.ai/api/v1`, adds the bearer token and optional
+ * `HTTP-Referer` and `X-Title` headers, accepts JSON responses, and applies
+ * `transformClient` when provided.
+ *
+ * **Gotchas**
+ *
+ * Scoped `OpenRouterConfig.withClientTransform` applies to generated client
+ * request methods. Streaming chat completion requests are sent directly by this
+ * module and do not read that scoped transform.
+ *
+ * @see {@link layer} for providing this client from explicit options
+ * @see {@link layerConfig} for loading client settings from `Config`
  *
- * @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> {
@@ -127,7 +172,7 @@ export const make = Effect.fnUntraced(
         request.pipe(
           HttpClientRequest.prependUrl(options.apiUrl ?? "https://openrouter.ai/api/v1"),
           options.apiKey ? HttpClientRequest.bearerToken(options.apiKey) : identity,
-          options.siteReferrer ? HttpClientRequest.setHeader("HTTP-Referrer", options.siteReferrer) : identity,
+          options.siteReferrer ? HttpClientRequest.setHeader("HTTP-Referer", options.siteReferrer) : identity,
           options.siteTitle ? HttpClientRequest.setHeader("X-Title", options.siteTitle) : identity,
           HttpClientRequest.acceptJson
         )
@@ -212,24 +257,45 @@ export const make = Effect.fnUntraced(
 /**
  * Creates a layer for the OpenRouter client with the given options.
  *
- * @since 1.0.0
+ * **When to use**
+ *
+ * Use when you already have the OpenRouter client options in code and want to
+ * provide `OpenRouterClient` as a layer.
+ *
+ * @see {@link make} for constructing the client service effectfully
+ * @see {@link layerConfig} for loading client settings from `Config`
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: Options): Layer.Layer<OpenRouterClient, never, HttpClient.HttpClient> =>
   Layer.effect(OpenRouterClient, make(options))
 
 /**
- * Creates a layer for the OpenRouter client, loading the requisite
- * configuration via Effect's `Config` module.
+ * Creates a layer for the OpenRouter client from provided `Config` values.
+ *
+ * **When to use**
+ *
+ * Use when you need client settings for OpenRouter to be read from Effect
+ * `Config` values while providing `OpenRouterClient` as a layer.
+ *
+ * **Details**
+ *
+ * Only config values supplied in `options` are loaded. Omitted fields are
+ * passed to `make` as `undefined`, and `transformClient` is forwarded as a
+ * plain option.
+ *
+ * @see {@link make} for constructing the client service effectfully
+ * @see {@link layer} for providing the client from already-resolved options
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layerConfig = (options?: {
   /**
    * The config value to load for the API key.
    */
-  readonly apiKey?: Config.Config<Redacted.Redacted<string>> | undefined
+  readonly apiKey?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
 
   /**
    * The config value to load for the API URL.

package/src/OpenRouterConfig.ts

@@ -1,35 +1,57 @@
 /**
- * @since 1.0.0
+ * The `OpenRouterConfig` module lets a workflow temporarily customize the HTTP
+ * client used by generated OpenRouter request methods. `OpenRouterClient` reads
+ * this scoped transform when generated client operations execute, so callers can
+ * add middleware or instrumentation without rebuilding the client layer.
+ *
+ * @since 4.0.0
  */
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import { dual } from "effect/Function"
-import * as ServiceMap from "effect/ServiceMap"
 import type { HttpClient } from "effect/unstable/http/HttpClient"
 
 /**
- * @since 1.0.0
+ * Context service for scoped OpenRouter provider configuration used by client
+ * operations.
+ *
+ * **When to use**
+ *
+ * Use as the context service tag when manually providing or reading scoped
+ * OpenRouter provider configuration in an Effect context.
+ *
+ * @see {@link withClientTransform} for scoping an HTTP client transformation
+ *
  * @category services
+ * @since 4.0.0
  */
-export class OpenRouterConfig extends ServiceMap.Service<
+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.services<never>(),
+    Effect.context<never>(),
     (services) => services.mapUnsafe.get(OpenRouterConfig.key)
   )
 }
 
 /**
- * @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 +59,81 @@ export declare namespace OpenRouterConfig {
 }
 
 /**
- * @since 1.0.0
+ * Provides a scoped transform for the OpenRouter HTTP client used by provider
+ * operations.
+ *
+ * **When to use**
+ *
+ * Use when you need temporary OpenRouter HTTP client customization for a
+ * single effect or workflow without rebuilding the client layer.
+ *
+ * **Details**
+ *
+ * Supports both data-first and data-last forms. The transform is stored in the
+ * scoped `OpenRouterConfig` service and read by generated OpenRouter request
+ * operations while running the supplied effect.
+ *
+ * **Gotchas**
+ *
+ * If a transform is already present in the scoped config, this helper replaces
+ * it. Compose transforms manually when both should apply. Streaming chat
+ * completion requests are sent directly by `OpenRouterClient.make` and do not
+ * read this scoped transform.
+ *
  * @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.
+   *
+   * **When to use**
+   *
+   * Use when you need temporary OpenRouter HTTP client customization for a
+   * single effect or workflow without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenRouterConfig` service and read by generated OpenRouter request
+   * operations while running the supplied effect.
+   *
+   * **Gotchas**
+   *
+   * If a transform is already present in the scoped config, this helper replaces
+   * it. Compose transforms manually when both should apply. Streaming chat
+   * completion requests are sent directly by `OpenRouterClient.make` and do not
+   * read this scoped transform.
+   *
    * @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.
+   *
+   * **When to use**
+   *
+   * Use when you need temporary OpenRouter HTTP client customization for a
+   * single effect or workflow without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenRouterConfig` service and read by generated OpenRouter request
+   * operations while running the supplied effect.
+   *
+   * **Gotchas**
+   *
+   * If a transform is already present in the scoped config, this helper replaces
+   * it. Compose transforms manually when both should apply. Streaming chat
+   * completion requests are sent directly by `OpenRouterClient.make` and do not
+   * read this scoped transform.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(
     self: Effect.Effect<A, E, R>,
@@ -56,13 +141,55 @@ 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.
+   *
+   * **When to use**
+   *
+   * Use when you need temporary OpenRouter HTTP client customization for a
+   * single effect or workflow without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenRouterConfig` service and read by generated OpenRouter request
+   * operations while running the supplied effect.
+   *
+   * **Gotchas**
+   *
+   * If a transform is already present in the scoped config, this helper replaces
+   * it. Compose transforms manually when both should apply. Streaming chat
+   * completion requests are sent directly by `OpenRouterClient.make` and do not
+   * read this scoped transform.
+   *
    * @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.
+   *
+   * **When to use**
+   *
+   * Use when you need temporary OpenRouter HTTP client customization for a
+   * single effect or workflow without rebuilding the client layer.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms. The transform is stored in the
+   * scoped `OpenRouterConfig` service and read by generated OpenRouter request
+   * operations while running the supplied effect.
+   *
+   * **Gotchas**
+   *
+   * If a transform is already present in the scoped config, this helper replaces
+   * it. Compose transforms manually when both should apply. Streaming chat
+   * completion requests are sent directly by `OpenRouterClient.make` and do not
+   * read this scoped transform.
+   *
    * @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,51 +42,184 @@ export type OpenRouterRateLimitMetadata = OpenRouterErrorMetadata & {
 }
 
 declare module "effect/unstable/ai/AiError" {
-  export interface RateLimitError {
-    readonly metadata: {
-      readonly openrouter?: OpenRouterRateLimitMetadata | null
-    }
+  /**
+   * OpenRouter metadata attached to `RateLimitError` values.
+   *
+   * **Details**
+   *
+   * Captures OpenRouter error details together with rate limit header
+   * information from responses where the provider rejected the request because
+   * a limit was reached.
+   *
+   * @category configuration
+   * @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.
+   *
+   * **Details**
+   *
+   * Preserves provider error details for failures caused by exhausted account,
+   * billing, or usage quota.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface QuotaExhaustedErrorMetadata {
+    /**
+     * OpenRouter-specific details for the quota exhaustion response.
+     */
+    readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
-  export interface QuotaExhaustedError {
-    readonly metadata: {
-      readonly openrouter?: OpenRouterErrorMetadata | null
-    }
+  /**
+   * OpenRouter metadata attached to `AuthenticationError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details for failed API key, authorization, or
+   * permission checks.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface AuthenticationErrorMetadata {
+    /**
+     * OpenRouter-specific details for the authentication failure.
+     */
+    readonly openrouter?: OpenRouterErrorMetadata | null
+  }
+
+  /**
+   * OpenRouter metadata attached to `ContentPolicyError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details when OpenRouter rejects input or output
+   * because it violates a content policy.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface ContentPolicyErrorMetadata {
+    /**
+     * OpenRouter-specific details for the content policy response.
+     */
+    readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
-  export interface AuthenticationError {
-    readonly metadata: {
-      readonly openrouter?: OpenRouterErrorMetadata | null
-    }
+  /**
+   * OpenRouter metadata attached to `InvalidRequestError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details for malformed requests, unsupported
+   * parameters, or other request validation failures reported by OpenRouter.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface InvalidRequestErrorMetadata {
+    /**
+     * OpenRouter-specific details for the invalid request response.
+     */
+    readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
-  export interface ContentPolicyError {
-    readonly metadata: {
-      readonly openrouter?: OpenRouterErrorMetadata | null
-    }
+  /**
+   * OpenRouter metadata attached to `InternalProviderError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details for OpenRouter-side failures such as
+   * transient server errors or overload responses.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface InternalProviderErrorMetadata {
+    /**
+     * OpenRouter-specific details for the internal provider response.
+     */
+    readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
-  export interface InvalidRequestError {
-    readonly metadata: {
-      readonly openrouter?: OpenRouterErrorMetadata | null
-    }
+  /**
+   * OpenRouter metadata attached to `InvalidOutputError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details when an OpenRouter response cannot be
+   * parsed or validated as the expected output.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface InvalidOutputErrorMetadata {
+    /**
+     * OpenRouter-specific details for the invalid output response.
+     */
+    readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
-  export interface InternalProviderError {
-    readonly metadata: {
-      readonly openrouter?: OpenRouterErrorMetadata | null
-    }
+  /**
+   * OpenRouter metadata attached to `StructuredOutputError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details when OpenRouter returns content that does
+   * not satisfy the requested structured output schema.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface StructuredOutputErrorMetadata {
+    /**
+     * OpenRouter-specific details for the structured output failure.
+     */
+    readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
-  export interface InvalidOutputError {
-    readonly metadata: {
-      readonly openrouter?: OpenRouterErrorMetadata | null
-    }
+  /**
+   * OpenRouter metadata attached to `UnsupportedSchemaError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details when an unsupported schema failure is
+   * associated with an OpenRouter response.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface UnsupportedSchemaErrorMetadata {
+    /**
+     * OpenRouter-specific details for the unsupported schema failure.
+     */
+    readonly openrouter?: OpenRouterErrorMetadata | null
   }
 
-  export interface UnknownError {
-    readonly metadata: {
-      readonly openrouter?: OpenRouterErrorMetadata | null
-    }
+  /**
+   * OpenRouter metadata attached to `UnknownError` values.
+   *
+   * **Details**
+   *
+   * Preserves provider error details for OpenRouter failures that do not map
+   * cleanly to a more specific AI error category.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface UnknownErrorMetadata {
+    /**
+     * OpenRouter-specific details for the unclassified provider failure.
+     */
+    readonly openrouter?: OpenRouterErrorMetadata | null
   }
 }