@effect/ai-anthropic 4.0.0-beta.7 → 4.0.0-beta.71

package/src/AnthropicConfig.ts

@@ -1,35 +1,72 @@
 /**
- * @since 1.0.0
+ * The `AnthropicConfig` module provides contextual configuration for the
+ * Anthropic AI provider integration. It is used to customize the generated
+ * Anthropic HTTP client without changing individual request code.
+ *
+ * **Common tasks**
+ *
+ * - Provide a shared `HttpClient` transformation for Anthropic requests
+ * - Add provider-specific concerns such as request instrumentation, proxying,
+ *   retries, or header manipulation
+ * - Scope a client transformation to a single effect with {@link withClientTransform}
+ *
+ * **Gotchas**
+ *
+ * - Configuration is read from the Effect context, so overrides only apply to
+ *   effects run inside the configured scope
+ * - `withClientTransform` replaces the current `transformClient` value while
+ *   preserving any other Anthropic configuration fields
+ *
+ * @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 a layer or integration needs to provide or read Anthropic client
+ * configuration through Effect's context.
+ *
+ * @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 +74,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
   }
 }