@effect/ai-anthropic 4.0.0-beta.8 → 4.0.0-beta.81

package/src/AnthropicClient.ts

@@ -1,20 +1,20 @@
 /**
- * Anthropic Client module for interacting with Anthropic's API.
+ * The `AnthropicClient` module defines the low-level Effect service for
+ * Anthropic's Messages API. It builds a generated Anthropic HTTP client with
+ * authentication headers, API version headers, response decoding, and error
+ * mapping, then exposes helpers for regular and streaming message requests.
  *
- * Provides a type-safe, Effect-based client for Anthropic operations including
- * messages and streaming responses.
- *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Array from "effect/Array"
 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 * 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"
@@ -33,47 +33,31 @@ import * as Errors from "./internal/errors.ts"
 // =============================================================================
 
 /**
- * The Anthropic client service interface.
- *
- * Provides methods for interacting with Anthropic's Messages API, including
- * both synchronous and streaming message creation.
+ * Represents the Anthropic client service with methods for the Messages API, including regular and streaming message
+ * creation.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Service {
   /**
-   * The underlying generated Anthropic client providing access to all API
-   * endpoints.
+   * The underlying generated Anthropic client that exposes all API endpoints.
    */
   readonly client: Generated.AnthropicClient
 
   /**
-   * Low-level streaming request helper for custom SSE endpoints.
-   *
-   * Executes an HTTP request and decodes the Server-Sent Events response
-   * using the provided schema.
+   * Executes a low-level streaming HTTP request and decodes the Server-Sent Events response using the provided schema.
    */
-  readonly streamRequest: <
-    Type extends {
-      readonly id?: string | undefined
-      readonly event: string
-      readonly data: string
-    },
-    DecodingServices
-  >(
-    schema: Schema.Decoder<Type, DecodingServices>
+  readonly streamRequest: <S extends Sse.EventCodec>(
+    schema: S
   ) => (request: HttpClientRequest.HttpClientRequest) => Stream.Stream<
-    Type,
+    S["Type"],
     HttpClientError.HttpClientError | Schema.SchemaError | Sse.Retry,
-    DecodingServices
+    S["DecodingServices"]
   >
 
   /**
-   * Creates a message using the Anthropic Messages API.
-   *
-   * Sends a structured list of input messages and returns the model's
-   * generated response. All errors are mapped to the unified `AiError` type.
+   * Creates a message using the Anthropic Messages API and maps all errors to the unified `AiError` type.
    */
   readonly createMessage: (options: {
     readonly payload: typeof Generated.BetaCreateMessageParams.Encoded
@@ -84,12 +68,12 @@ export interface Service {
   >
 
   /**
-   * Creates a streaming message using the Anthropic Messages API.
+   * Creates a streaming message using the Anthropic Messages API and maps all errors to the unified `AiError` type.
+   *
+   * **Details**
    *
-   * Returns an Effect that yields the HTTP response and a stream of events
-   * as the model generates its response. The stream automatically terminates
-   * when a `message_stop` event is received. All errors are mapped to the
-   * unified `AiError` type.
+   * The returned Effect yields the HTTP response and a stream of events as the model generates its response. The stream
+   * automatically terminates when a `message_stop` event is received.
    */
   readonly createMessageStream: (options: {
     readonly payload: Omit<typeof Generated.BetaCreateMessageParams.Encoded, "stream">
@@ -101,8 +85,9 @@ export interface Service {
 }
 
 /**
- * Represents an event received from the Anthropic Messages API during a
- * streaming request.
+ * Represents an event received from the Anthropic Messages API during a streaming request.
+ *
+ * **Details**
  *
  * Events include:
  * - `message_start`: Initial event containing message metadata
@@ -113,8 +98,8 @@ export interface Service {
  * - `content_block_stop`: End of a content block
  * - `error`: Error events with type and message
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type MessageStreamEvent =
   | typeof Generated.BetaMessageStartEvent.Type
@@ -130,12 +115,21 @@ export type MessageStreamEvent =
 // =============================================================================
 
 /**
- * Service identifier for the Anthropic client.
+ * Service tag for the Anthropic client.
+ *
+ * **When to use**
+ *
+ * Use when accessing or providing the Anthropic client service through Effect's
+ * context.
+ *
+ * @see {@link make} for constructing an Anthropic client effectfully
+ * @see {@link layer} for providing a client from explicit options
+ * @see {@link layerConfig} for providing a client from `Config`
  *
- * @since 1.0.0
- * @category service
+ * @category services
+ * @since 4.0.0
  */
-export class AnthropicClient extends ServiceMap.Service<AnthropicClient, Service>()(
+export class AnthropicClient extends Context.Service<AnthropicClient, Service>()(
   "@effect/ai-anthropic/AnthropicClient"
 ) {}
 
@@ -144,43 +138,50 @@ export class AnthropicClient extends ServiceMap.Service<AnthropicClient, Service
 // =============================================================================
 
 /**
- * Configuration options for creating an Anthropic client.
+ * Configuration for creating an Anthropic client.
  *
- * @since 1.0.0
- * @category models
+ * **When to use**
+ *
+ * Use when the Anthropic client settings are already available as values and
+ * should be passed directly to `make` or `layer`.
+ *
+ * **Details**
+ *
+ * These options configure the base Anthropic URL, the `x-api-key`
+ * authentication header, the `anthropic-version` header, and an optional
+ * transformation of the underlying `HttpClient`.
+ *
+ * @see {@link make} for constructing an Anthropic client from explicit options
+ * @see {@link layer} for providing an Anthropic client from explicit options
+ * @see {@link layerConfig} for loading Anthropic client settings from `Config`
+ *
+ * @category options
+ * @since 4.0.0
  */
 export type Options = {
   /**
-   * The Anthropic API key for authentication.
-   *
-   * If not provided, requests will be made without authentication (useful for
-   * proxied setups or testing).
+   * The Anthropic API key for authentication. Requests are made without authentication when this is omitted, which is
+   * useful for proxied setups or testing.
    */
   readonly apiKey?: Redacted.Redacted<string> | undefined
 
   /**
-   * The base URL for the Anthropic API.
-   *
-   * Override this to use a proxy or a different API-compatible endpoint.
+   * The base URL for the Anthropic API. Override this to use a proxy or a different API-compatible endpoint.
    *
    * @default "https://api.anthropic.com"
    */
   readonly apiUrl?: string | undefined
 
   /**
-   * The Anthropic API version header value.
-   *
-   * Controls which version of the API to use. See Anthropic's versioning
-   * documentation for available versions and their features.
+   * The Anthropic API version header value. This controls which version of the API to use.
    *
    * @default "2023-06-01"
    */
   readonly apiVersion?: string | undefined
 
   /**
-   * Optional transformer for the underlying HTTP client.
-   *
-   * Use this to add middleware, logging, or custom request/response handling.
+   * Optional transformer for the underlying HTTP client, such as middleware, logging, or custom request/response
+   * handling.
    */
   readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
 }
@@ -196,16 +197,22 @@ const RedactedAnthropicHeaders = {
 /**
  * Creates an Anthropic client service with the given options.
  *
- * The client automatically handles:
- * - API key authentication via the `x-api-key` header
- * - API versioning via the `anthropic-version` header
- * - Error mapping to the unified `AiError` type
- * - Request/response transformations via `AnthropicConfig`
+ * **When to use**
+ *
+ * Use when you have explicit configuration values and need an `Effect` that
+ * constructs the Anthropic client service, rather than providing it as a `Layer`.
+ *
+ * **Details**
  *
- * Requires an `HttpClient` in the context.
+ * The client handles API key authentication via the `x-api-key` header, API versioning via the `anthropic-version`
+ * header, error mapping to the unified `AiError` type, and request/response transformations via `AnthropicConfig`. It
+ * requires an `HttpClient` in the context.
+ *
+ * @see {@link layer} for providing the client as a `Layer` from explicit options
+ * @see {@link layerConfig} for providing the client as a `Layer` with `Config`-based settings
  *
- * @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> {
@@ -243,25 +250,19 @@ export const make = Effect.fnUntraced(
 
     const httpClientOk = HttpClient.filterStatusOk(httpClient)
 
-    const streamRequest = <
-      Type extends {
-        readonly id?: string | undefined
-        readonly event: string
-        readonly data: string
-      },
-      DecodingServices
-    >(schema: Schema.Decoder<Type, DecodingServices>) =>
-    (request: HttpClientRequest.HttpClientRequest): Stream.Stream<
-      Type,
-      HttpClientError.HttpClientError | Schema.SchemaError | Sse.Retry,
-      DecodingServices
-    > =>
-      httpClientOk.execute(request).pipe(
-        Effect.map((response) => response.stream),
-        Stream.unwrap,
-        Stream.decodeText,
-        Stream.pipeThroughChannel(Sse.decodeSchema(schema))
-      )
+    const streamRequest =
+      <S extends Sse.EventCodec>(schema: S) =>
+      (request: HttpClientRequest.HttpClientRequest): Stream.Stream<
+        S["Type"],
+        HttpClientError.HttpClientError | Schema.SchemaError | Sse.Retry,
+        S["DecodingServices"]
+      > =>
+        httpClientOk.execute(request).pipe(
+          Effect.map((response) => response.stream),
+          Stream.unwrap,
+          Stream.decodeText,
+          Stream.pipeThroughChannel(Sse.decodeSchema(schema))
+        )
 
     const createMessage = (options: {
       readonly payload: typeof Generated.BetaCreateMessageParams.Encoded
@@ -352,8 +353,16 @@ export const make = Effect.fnUntraced(
 /**
  * Creates a layer for the Anthropic client with the given options.
  *
- * @since 1.0.0
+ * **When to use**
+ *
+ * Use when you already have explicit `Options` values, such as an API key or
+ * custom API URL, and want to provide `AnthropicClient` 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<AnthropicClient, never, HttpClient.HttpClient> =>
   Layer.effect(AnthropicClient, make(options))
@@ -362,41 +371,42 @@ export const layer = (options: Options): Layer.Layer<AnthropicClient, never, Htt
  * Creates a layer for the Anthropic client, loading the requisite configuration
  * via Effect's `Config` module.
  *
- * @since 1.0.0
+ * **When to use**
+ *
+ * Use when you want to provide the Anthropic client as a `Layer` with
+ * configuration loaded from Effect's `Config` module, such as from environment
+ * variables or a secrets provider.
+ *
+ * @see {@link layer} for providing the client from explicit options instead of `Config`
+ * @see {@link make} for constructing the client service effectfully
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerConfig = (options?: {
   /**
-   * The Anthropic API key for authentication.
-   *
-   * If not provided, requests will be made without authentication (useful for
-   * proxied setups or testing).
+   * The Anthropic API key for authentication. Requests are made without authentication when this is omitted, which is
+   * useful for proxied setups or testing.
    */
-  readonly apiKey?: Config.Config<Redacted.Redacted<string>> | undefined
+  readonly apiKey?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
 
   /**
-   * The base URL for the Anthropic API.
-   *
-   * Override this to use a proxy or a different API-compatible endpoint.
+   * The base URL for the Anthropic API. Override this to use a proxy or a different API-compatible endpoint.
    *
    * @default "https://api.anthropic.com"
    */
   readonly apiUrl?: Config.Config<string> | undefined
 
   /**
-   * The Anthropic API version header value.
-   *
-   * Controls which version of the API to use. See Anthropic's versioning
-   * documentation for available versions and their features.
+   * The Anthropic API version header value. This controls which version of the API to use.
    *
    * @default "2023-06-01"
    */
   readonly apiVersion?: Config.Config<string> | undefined
 
   /**
-   * Optional transformer for the underlying HTTP client.
-   *
-   * Use this to add middleware, logging, or custom request/response handling.
+   * Optional transformer for the underlying HTTP client, such as middleware, logging, or custom request/response
+   * handling.
    */
   readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
 }): Layer.Layer<AnthropicClient, Config.ConfigError, HttpClient.HttpClient> =>

package/src/AnthropicConfig.ts

@@ -1,35 +1,59 @@
 /**
- * @since 1.0.0
+ * The `AnthropicConfig` module lets a workflow temporarily customize the HTTP
+ * client used by generated Anthropic requests. It is used by
+ * `AnthropicClient` when request helpers run, so code can add middleware,
+ * logging, or other client changes 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
+ * Service tag for Anthropic client configuration overrides, such as transformations applied to the generated HTTP client.
+ *
+ * **When to use**
+ *
+ * Use when you need to provide or read Anthropic client configuration through
+ * Effect's context from a layer or integration.
+ *
+ * @see {@link withClientTransform} for scoping an HTTP client transformation
+ *
  * @category services
+ * @since 4.0.0
  */
-export class AnthropicConfig extends ServiceMap.Service<
+export class AnthropicConfig extends Context.Service<
   AnthropicConfig,
   AnthropicConfig.Service
 >()("@effect/ai-anthropic/AnthropicConfig") {
   /**
-   * @since 1.0.0
+   * Gets the configured Anthropic service from the current context when present.
+   *
+   * @since 4.0.0
    */
   static readonly getOrUndefined: Effect.Effect<typeof AnthropicConfig.Service | undefined> = Effect.map(
-    Effect.services<never>(),
+    Effect.context<never>(),
     (services) => services.mapUnsafe.get(AnthropicConfig.key)
   )
 }
 
 /**
- * @since 1.0.0
+ * Namespace containing types associated with the `AnthropicConfig` service.
+ *
+ * @since 4.0.0
  */
 export declare namespace AnthropicConfig {
   /**
-   * @since 1.0.0
+   * Configuration provided through `AnthropicConfig`.
+   *
+   * **Details**
+   *
+   * Use `transformClient` to wrap or replace the `HttpClient` used by generated Anthropic API requests.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Service {
     readonly transformClient?: ((client: HttpClient) => HttpClient) | undefined
@@ -37,18 +61,39 @@ export declare namespace AnthropicConfig {
 }
 
 /**
- * @since 1.0.0
+ * Runs an effect with an `AnthropicConfig` override that transforms the underlying `HttpClient` used by generated Anthropic requests.
+ *
+ * **When to use**
+ *
+ * Use when you need to apply a temporary `HttpClient` transformation, such as adding middleware or logging, to a
+ * specific scope of an effectful program.
+ *
  * @category configuration
+ * @since 4.0.0
  */
 export const withClientTransform: {
   /**
-   * @since 1.0.0
+   * Runs an effect with an `AnthropicConfig` override that transforms the underlying `HttpClient` used by generated Anthropic requests.
+   *
+   * **When to use**
+   *
+   * Use when you need to apply a temporary `HttpClient` transformation, such as adding middleware or logging, to a
+   * specific scope of an effectful program.
+   *
    * @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
+   * Runs an effect with an `AnthropicConfig` override that transforms the underlying `HttpClient` used by generated Anthropic requests.
+   *
+   * **When to use**
+   *
+   * Use when you need to apply a temporary `HttpClient` transformation, such as adding middleware or logging, to a
+   * specific scope of an effectful program.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(
     self: Effect.Effect<A, E, R>,

package/src/AnthropicError.ts

@@ -4,14 +4,22 @@
  * Provides Anthropic-specific metadata fields for AI error types through module
  * augmentation, enabling typed access to Anthropic error details.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
  * Anthropic-specific error metadata fields.
  *
- * @since 1.0.0
+ * **Details**
+ *
+ * Contains the Anthropic error type and request identifier copied from provider
+ * error responses when available. Either field may be `null` when Anthropic
+ * does not include it or the response cannot be decoded.
+ *
+ * @see {@link AnthropicRateLimitMetadata} for rate-limit responses that also include parsed Anthropic rate-limit headers
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AnthropicErrorMetadata = {
   /**
@@ -27,11 +35,12 @@ export type AnthropicErrorMetadata = {
 /**
  * Anthropic-specific rate limit metadata fields.
  *
- * Extends base error metadata with rate limit specific information from
- * Anthropic's rate limit headers.
+ * **Details**
+ *
+ * Extends base error metadata with rate limit-specific information from Anthropic's rate limit headers.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type AnthropicRateLimitMetadata = AnthropicErrorMetadata & {
   /**
@@ -61,51 +70,143 @@ export type AnthropicRateLimitMetadata = AnthropicErrorMetadata & {
 }
 
 declare module "effect/unstable/ai/AiError" {
-  export interface RateLimitError {
-    readonly metadata: {
-      readonly anthropic?: AnthropicRateLimitMetadata | null
-    }
+  /**
+   * Anthropic metadata attached to `RateLimitError` values.
+   *
+   * **Details**
+   *
+   * Includes request identifiers, Anthropic error types, and parsed request or token limit headers when the provider rejects a request due to rate limits.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface RateLimitErrorMetadata {
+    readonly anthropic?: AnthropicRateLimitMetadata | null
+  }
+
+  /**
+   * Anthropic metadata attached to `QuotaExhaustedError` values.
+   *
+   * **Details**
+   *
+   * Captures the Anthropic error type and request identifier for failures where the account or workspace has exhausted its available quota.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface QuotaExhaustedErrorMetadata {
+    readonly anthropic?: AnthropicErrorMetadata | null
+  }
+
+  /**
+   * Anthropic metadata attached to `AuthenticationError` values.
+   *
+   * **Details**
+   *
+   * Preserves Anthropic error details for missing, invalid, or unauthorized API credentials while keeping the error in the shared AI error model.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface AuthenticationErrorMetadata {
+    readonly anthropic?: AnthropicErrorMetadata | null
   }
 
-  export interface QuotaExhaustedError {
-    readonly metadata: {
-      readonly anthropic?: AnthropicErrorMetadata | null
-    }
+  /**
+   * Anthropic metadata attached to `ContentPolicyError` values.
+   *
+   * **Details**
+   *
+   * Records Anthropic error details returned when a request or response is rejected by Anthropic safety or content policy enforcement.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface ContentPolicyErrorMetadata {
+    readonly anthropic?: AnthropicErrorMetadata | null
   }
 
-  export interface AuthenticationError {
-    readonly metadata: {
-      readonly anthropic?: AnthropicErrorMetadata | null
-    }
+  /**
+   * Anthropic metadata attached to `InvalidRequestError` values.
+   *
+   * **Details**
+   *
+   * Provides the Anthropic error type and request identifier for malformed or unsupported requests rejected before model execution.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface InvalidRequestErrorMetadata {
+    readonly anthropic?: AnthropicErrorMetadata | null
   }
 
-  export interface ContentPolicyError {
-    readonly metadata: {
-      readonly anthropic?: AnthropicErrorMetadata | null
-    }
+  /**
+   * Anthropic metadata attached to `InternalProviderError` values.
+   *
+   * **Details**
+   *
+   * Preserves Anthropic request correlation data for provider-side failures that should be reported or investigated with Anthropic support.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface InternalProviderErrorMetadata {
+    readonly anthropic?: AnthropicErrorMetadata | null
   }
 
-  export interface InvalidRequestError {
-    readonly metadata: {
-      readonly anthropic?: AnthropicErrorMetadata | null
-    }
+  /**
+   * Anthropic metadata attached to `InvalidOutputError` values.
+   *
+   * **Details**
+   *
+   * Describes Anthropic-specific context for responses that could not be decoded or interpreted as valid AI output.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface InvalidOutputErrorMetadata {
+    readonly anthropic?: AnthropicErrorMetadata | null
   }
 
-  export interface InternalProviderError {
-    readonly metadata: {
-      readonly anthropic?: AnthropicErrorMetadata | null
-    }
+  /**
+   * Anthropic metadata attached to `StructuredOutputError` values.
+   *
+   * **Details**
+   *
+   * Captures Anthropic error details for structured-output failures, including request correlation data useful when diagnosing schema-related responses.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface StructuredOutputErrorMetadata {
+    readonly anthropic?: AnthropicErrorMetadata | null
   }
 
-  export interface InvalidOutputError {
-    readonly metadata: {
-      readonly anthropic?: AnthropicErrorMetadata | null
-    }
+  /**
+   * Anthropic metadata attached to `UnsupportedSchemaError` values.
+   *
+   * **Details**
+   *
+   * Provides Anthropic error details for schemas that cannot be represented by or submitted to the Anthropic API.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface UnsupportedSchemaErrorMetadata {
+    readonly anthropic?: AnthropicErrorMetadata | null
   }
 
-  export interface UnknownError {
-    readonly metadata: {
-      readonly anthropic?: AnthropicErrorMetadata | null
-    }
+  /**
+   * Anthropic metadata attached to `UnknownError` values.
+   *
+   * **Details**
+   *
+   * Retains the Anthropic error type and request identifier when a provider response cannot be classified as a more specific AI error.
+   *
+   * @category configuration
+   * @since 4.0.0
+   */
+  export interface UnknownErrorMetadata {
+    readonly anthropic?: AnthropicErrorMetadata | null
   }
 }