@effect/ai-openai 4.0.0-beta.65 → 4.0.0-beta.67

package/src/OpenAiClient.ts

@@ -4,7 +4,7 @@
  * Provides a type-safe, Effect-based client for OpenAI operations including
  * completions, embeddings, and streaming responses.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Array from "effect/Array"
 import type * as Config from "effect/Config"
@@ -39,10 +39,13 @@ import * as OpenAiSchema from "./OpenAiSchema.ts"
 // =============================================================================
 
 /**
- * The OpenAI client interface.
+ * Effect service interface for the handwritten OpenAI client.
+ *
+ * **Details**
+ * Provides the configured HTTP client plus helpers for Responses API calls, streaming Responses events, and embeddings. Transport and schema decoding failures are mapped to `AiError`.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Service {
   /**
@@ -88,8 +91,8 @@ export interface Service {
 /**
  * Service identifier for the OpenAI client.
  *
- * @since 1.0.0
  * @category service
+ * @since 4.0.0
  */
 export class OpenAiClient extends Context.Service<OpenAiClient, Service>()(
   "@effect/ai-openai/OpenAiClient"
@@ -102,8 +105,8 @@ export class OpenAiClient extends Context.Service<OpenAiClient, Service>()(
 /**
  * Options for configuring the OpenAI client.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Options = {
   /**
@@ -146,8 +149,8 @@ const RedactedOpenAiHeaders = {
 /**
  * Creates an OpenAI client service with the given options.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(
   function*(
@@ -298,8 +301,8 @@ export const make = Effect.fnUntraced(
 /**
  * Creates a layer for the OpenAI client with the given options.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: Options): Layer.Layer<OpenAiClient, never, HttpClient.HttpClient> =>
   Layer.effect(OpenAiClient, make(options))
@@ -308,8 +311,8 @@ export const layer = (options: Options): Layer.Layer<OpenAiClient, never, HttpCl
  * Creates a layer for the OpenAI client, loading the requisite configuration
  * via Effect's `Config` module.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layerConfig = (options?: {
   /**
@@ -367,14 +370,18 @@ export const layerConfig = (options?: {
 // =============================================================================
 
 /**
- * @since 1.0.0
+ * Response stream event emitted by the OpenAI Responses API.
+ *
  * @category Events
+ * @since 4.0.0
  */
 export type ResponseStreamEvent = typeof OpenAiSchema.ResponseStreamEvent.Type
 
 /**
- * @since 1.0.0
+ * Service for creating OpenAI response streams over a WebSocket connection.
+ *
  * @category Websocket mode
+ * @since 4.0.0
  */
 export class OpenAiSocket extends Context.Service<OpenAiSocket, {
   /**
@@ -504,7 +511,7 @@ const makeSocket = Effect.gen(function*() {
               },
               description: error.message
             })
-          }).asEffect()),
+          })),
         Effect.catchCause((cause) => Queue.failCause(incoming, cause)),
         Effect.ensuring(Effect.forkIn(RcRef.invalidate(queueRef), socketScope, {
           startImmediately: true
@@ -587,8 +594,8 @@ const decodeEvent = Schema.decodeUnknownSync(Schema.fromJsonString(AllEvents))
  * This is because it needs to use non-standard options for setting the
  * Authorization header.
  *
- * @since 1.0.0
  * @category Websocket mode
+ * @since 4.0.0
  */
 export const withWebSocketMode = <A, E, R>(
   effect: Effect.Effect<A, E, R>
@@ -615,8 +622,8 @@ export const withWebSocketMode = <A, E, R>(
  * This is because it needs to use non-standard options for setting the
  * Authorization header.
  *
- * @since 1.0.0
  * @category Websocket mode
+ * @since 4.0.0
  */
 export const layerWebSocketMode: Layer.Layer<
   OpenAiSocket | ResponseIdTracker.ResponseIdTracker,

package/src/OpenAiClientGenerated.ts

@@ -1,5 +1,5 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Array from "effect/Array"
 import type * as Config from "effect/Config"
@@ -23,7 +23,7 @@ import { OpenAiConfig } from "./OpenAiConfig.ts"
 /**
  * Service identifier for the generated OpenAI client.
  *
- * @since 1.0.0
+ * @since 4.0.0
  * @category service
  */
 export class OpenAiClientGenerated extends Context.Service<OpenAiClientGenerated, Generated.OpenAiClient>()(
@@ -37,7 +37,7 @@ export class OpenAiClientGenerated extends Context.Service<OpenAiClientGenerated
 /**
  * Options for configuring the generated OpenAI client.
  *
- * @since 1.0.0
+ * @since 4.0.0
  * @category models
  */
 export type Options = {
@@ -81,7 +81,7 @@ const RedactedOpenAiHeaders = {
 /**
  * Creates a generated OpenAI client service with the given options.
  *
- * @since 1.0.0
+ * @since 4.0.0
  * @category constructors
  */
 export const make = Effect.fnUntraced(
@@ -137,7 +137,7 @@ export const make = Effect.fnUntraced(
 /**
  * Creates a layer for the generated OpenAI client with the given options.
  *
- * @since 1.0.0
+ * @since 4.0.0
  * @category layers
  */
 export const layer = (options: Options): Layer.Layer<OpenAiClientGenerated, never, HttpClient.HttpClient> =>
@@ -147,7 +147,7 @@ export const layer = (options: Options): Layer.Layer<OpenAiClientGenerated, neve
  * Creates a layer for the generated OpenAI client, loading the requisite
  * configuration via Effect's `Config` module.
  *
- * @since 1.0.0
+ * @since 4.0.0
  * @category layers
  */
 export const layerConfig = (options?: {

package/src/OpenAiConfig.ts

@@ -1,5 +1,21 @@
 /**
- * @since 1.0.0
+ * The `OpenAiConfig` module provides contextual configuration for the
+ * `@effect/ai-openai` integration. It is used to customize how OpenAI clients
+ * are built and interpreted without threading configuration through every API
+ * call manually.
+ *
+ * The primary use case is installing an HTTP client transform with
+ * {@link withClientTransform}. This lets applications adapt the underlying
+ * OpenAI HTTP client for cross-cutting concerns such as custom middleware,
+ * instrumentation, proxying, or request policy changes while keeping the
+ * OpenAI service APIs unchanged.
+ *
+ * Configuration is scoped through Effect's context, so transforms only apply to
+ * the effect they are provided to and anything evaluated inside that scope.
+ * When multiple transforms are needed, compose them into a single
+ * `HttpClient => HttpClient` function before providing the configuration.
+ *
+ * @since 4.0.0
  */
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
@@ -7,15 +23,20 @@ import { dual } from "effect/Function"
 import type { HttpClient } from "effect/unstable/http/HttpClient"
 
 /**
- * @since 1.0.0
+ * Context service carrying scoped OpenAI configuration for provider
+ * operations.
+ *
  * @category services
+ * @since 4.0.0
  */
 export class OpenAiConfig extends Context.Service<
   OpenAiConfig,
   OpenAiConfig.Service
 >()("@effect/ai-openai/OpenAiConfig") {
   /**
-   * @since 1.0.0
+   * Gets the configured OpenAI service from the current context when present.
+   *
+   * @since 4.0.0
    */
   static readonly getOrUndefined: Effect.Effect<typeof OpenAiConfig.Service | undefined> = Effect.map(
     Effect.context<never>(),
@@ -24,12 +45,17 @@ export class OpenAiConfig extends Context.Service<
 }
 
 /**
- * @since 1.0.0
+ * Types used by the `OpenAiConfig` context service.
+ *
+ * @since 4.0.0
  */
 export declare namespace OpenAiConfig {
   /**
-   * @since 1.0.
+   * Configuration values read by OpenAI provider operations when executing
+   * requests.
+   *
    * @category models
+   * @since 1.0.
    */
   export interface Service {
     readonly transformClient?: ((client: HttpClient) => HttpClient) | undefined
@@ -37,18 +63,27 @@ export declare namespace OpenAiConfig {
 }
 
 /**
- * @since 1.0.0
+ * Provides a scoped transform for the OpenAI 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 OpenAI 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 OpenAI HTTP client used by provider
+   * operations.
+   *
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(
     self: Effect.Effect<A, E, R>,

package/src/OpenAiEmbeddingModel.ts

@@ -3,7 +3,7 @@
  *
  * Provides an EmbeddingModel implementation for OpenAI's embeddings API.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
@@ -17,16 +17,18 @@ import { OpenAiClient } from "./OpenAiClient.ts"
 import type * as OpenAiSchema from "./OpenAiSchema.ts"
 
 /**
- * @since 1.0.0
+ * Model identifiers supported by OpenAI's embeddings API.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Model = "text-embedding-ada-002" | "text-embedding-3-small" | "text-embedding-3-large"
 
 /**
  * Service definition for OpenAI embedding model configuration.
  *
- * @since 1.0.0
  * @category services
+ * @since 4.0.0
  */
 export class Config extends Context.Service<
   Config,
@@ -44,8 +46,10 @@ export class Config extends Context.Service<
 >()("@effect/ai-openai/OpenAiEmbeddingModel/Config") {}
 
 /**
- * @since 1.0.0
+ * Creates an `AiModel` for an OpenAI embedding model with its configured vector dimensions.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const model = (
   model: (string & {}) | Model,
@@ -72,8 +76,8 @@ export const model = (
 /**
  * Creates an OpenAI embedding model service.
  *
- * @since 1.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = Effect.fnUntraced(function*({ model, config: providerConfig }: {
   readonly model: (string & {}) | Model
@@ -98,8 +102,8 @@ export const make = Effect.fnUntraced(function*({ model, config: providerConfig
 /**
  * Creates a layer for the OpenAI embedding model.
  *
- * @since 1.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = (options: {
   readonly model: (string & {}) | Model
@@ -110,37 +114,37 @@ export const layer = (options: {
 /**
  * Provides config overrides for OpenAI embedding model operations.
  *
- * @since 1.0.0
  * @category configuration
+ * @since 4.0.0
  */
 export const withConfigOverride: {
   /**
    * Provides config overrides for OpenAI embedding model operations.
    *
-   * @since 1.0.0
    * @category configuration
+   * @since 4.0.0
    */
   (overrides: typeof Config.Service): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>
   /**
    * Provides config overrides for OpenAI embedding model operations.
    *
-   * @since 1.0.0
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service): Effect.Effect<A, E, Exclude<R, Config>>
 } = dual<
   /**
    * Provides config overrides for OpenAI embedding model operations.
    *
-   * @since 1.0.0
    * @category configuration
+   * @since 4.0.0
    */
   (overrides: typeof Config.Service) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Config>>,
   /**
    * Provides config overrides for OpenAI embedding model operations.
    *
-   * @since 1.0.0
    * @category configuration
+   * @since 4.0.0
    */
   <A, E, R>(self: Effect.Effect<A, E, R>, overrides: typeof Config.Service) => Effect.Effect<A, E, Exclude<R, Config>>
 >(2, (self, overrides) =>

package/src/OpenAiError.ts

@@ -4,14 +4,14 @@
  * Provides OpenAI-specific metadata fields for AI error types through module
  * augmentation, enabling typed access to OpenAI error details.
  *
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
  * OpenAI-specific error metadata fields.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiErrorMetadata = {
   /**
@@ -34,8 +34,8 @@ export type OpenAiErrorMetadata = {
  * Extends base error metadata with rate limit specific information from
  * OpenAI's rate limit headers.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
   /**
@@ -57,43 +57,164 @@ export type OpenAiRateLimitMetadata = OpenAiErrorMetadata & {
 }
 
 declare module "effect/unstable/ai/AiError" {
+  /**
+   * OpenAI metadata attached to `RateLimitError` values.
+   *
+   * Captures OpenAI 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 {
+    /**
+     * OpenAI-specific details for the rate limit response.
+     */
     readonly openai?: OpenAiRateLimitMetadata | null
   }
 
+  /**
+   * OpenAI 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 {
+    /**
+     * OpenAI-specific details for the quota exhaustion response.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI 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 {
+    /**
+     * OpenAI-specific details for the authentication failure.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `ContentPolicyError` values.
+   *
+   * Preserves provider error details when OpenAI rejects input or output because
+   * it violates a content policy.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface ContentPolicyErrorMetadata {
+    /**
+     * OpenAI-specific details for the content policy response.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `InvalidRequestError` values.
+   *
+   * Preserves provider error details for malformed requests, unsupported
+   * parameters, or other request validation failures reported by OpenAI.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface InvalidRequestErrorMetadata {
+    /**
+     * OpenAI-specific details for the invalid request response.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `InternalProviderError` values.
+   *
+   * Preserves provider error details for OpenAI-side failures such as transient
+   * server errors.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface InternalProviderErrorMetadata {
+    /**
+     * OpenAI-specific details for the internal provider response.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `InvalidOutputError` values.
+   *
+   * Preserves provider error details when an OpenAI response cannot be parsed or
+   * validated as the expected output.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface InvalidOutputErrorMetadata {
+    /**
+     * OpenAI-specific details for the invalid output response.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `StructuredOutputError` values.
+   *
+   * Preserves provider error details when OpenAI returns content that does not
+   * satisfy the requested structured output schema.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface StructuredOutputErrorMetadata {
+    /**
+     * OpenAI-specific details for the structured output failure.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `UnsupportedSchemaError` values.
+   *
+   * Preserves provider error details when an unsupported schema failure is
+   * associated with an OpenAI response.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface UnsupportedSchemaErrorMetadata {
+    /**
+     * OpenAI-specific details for the unsupported schema failure.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 
+  /**
+   * OpenAI metadata attached to `UnknownError` values.
+   *
+   * Preserves provider error details for OpenAI failures that do not map cleanly
+   * to a more specific AI error category.
+   *
+   * @category provider options
+   * @since 4.0.0
+   */
   export interface UnknownErrorMetadata {
+    /**
+     * OpenAI-specific details for the unclassified provider failure.
+     */
     readonly openai?: OpenAiErrorMetadata | null
   }
 }