OpenAiClient.ts

OpenAiClient.ts overview

The OpenAiClient module provides an Effect service for OpenAI-compatible chat completions and embeddings APIs. It builds on the Effect HTTP client, adds authentication and OpenAI organization or project headers, and exposes typed helpers for non-streaming chat completions, streaming chat completions, and embedding requests.

Since v4.0.0

---

Exports Grouped by Category

• configuration
  • ChatCompletionResponseFormat (type alias)
  • ChatCompletionToolChoice (type alias)
  • TextResponseFormatConfiguration (type alias)
• constructors
  • make
• layers
  • layer
  • layerConfig
• models
  • MessageStatus (type alias)
  • Service (interface)
• options
  • Options (type alias)
• request
  • ChatCompletionContentPart (type alias)
  • ChatCompletionRequest (type alias)
  • ChatCompletionRequestMessage (type alias)
  • ChatCompletionRequestToolCall (type alias)
  • ChatCompletionTool (type alias)
  • CreateEmbeddingRequest (type alias)
  • CreateEmbeddingRequestJson (type alias)
  • CreateResponse (type alias)
  • CreateResponseRequestJson (type alias)
  • InputContent (type alias)
  • InputItem (type alias)
  • Tool (type alias)
• response
  • Annotation (type alias)
  • ChatCompletionChoice (type alias)
  • ChatCompletionMessage (type alias)
  • ChatCompletionResponse (type alias)
  • ChatCompletionToolCall (type alias)
  • ChatCompletionUsage (type alias)
  • CreateEmbedding200 (type alias)
  • CreateEmbeddingResponse (type alias)
  • CreateResponse200 (type alias)
  • Embedding (type alias)
  • IncludeEnum (type alias)
  • ReasoningItem (type alias)
  • Response (type alias)
  • ResponseUsage (type alias)
  • SummaryTextContent (type alias)
• services
  • OpenAiClient (class)
• streaming
  • ChatCompletionChunk (type alias)
  • ChatCompletionStreamEvent (type alias)
  • CreateResponse200Sse (type alias)
  • ResponseStreamEvent (type alias)

---

configuration

ChatCompletionResponseFormat (type alias)

JSON response format configuration for chat completion requests.

Signature

type ChatCompletionResponseFormat =
  | {
      readonly type: "json_object"
    }
  | {
      readonly type: "json_schema"
      readonly json_schema: {
        readonly name: string
        readonly schema: JsonObject
        readonly description?: string | undefined
        readonly strict?: boolean | undefined
      }
    }

Source

Since v4.0.0

ChatCompletionToolChoice (type alias)

Controls whether the model may call tools and can force a specific function.

Signature

type ChatCompletionToolChoice =
  | "none"
  | "auto"
  | "required"
  | {
      readonly type: "function"
      readonly function: {
        readonly name: string
      }
    }

Source

Since v4.0.0

TextResponseFormatConfiguration (type alias)

Text output format configuration for plain text, JSON object, or JSON Schema responses.

Signature

type TextResponseFormatConfiguration =
  | {
      readonly type: "text"
    }
  | {
      readonly type: "json_schema"
      readonly description?: string | undefined
      readonly name: string
      readonly schema: JsonObject
      readonly strict?: boolean | null | undefined
    }
  | {
      readonly type: "json_object"
    }

Source

Since v4.0.0

constructors

make

Constructs an OpenAI-compatible client service from explicit options.

When to use

Use when you need the OpenAI-compatible client service value inside an effect.

Details

The returned service uses the current HttpClient, prepends apiUrl or https://api.openai.com/v1, adds authentication and OpenAI organization/project headers, accepts JSON responses, and applies transformClient when provided.

Gotchas

A scoped OpenAiConfig.withClientTransform is applied when request helpers run, after the transformClient option supplied to make.

See

• layer for providing this client from explicit options
• layerConfig for loading client settings from Config

Signature

declare const make: (options: Options) => Effect.Effect<Service, never, HttpClient.HttpClient>

Source

Since v4.0.0

layers

layer

Creates a layer that provides an OpenAI-compatible client from explicit options.

When to use

Use to install OpenAiClient in an application layer when the client options are already available as values rather than loaded from Config.

See

• make for constructing the client service effectfully
• layerConfig for loading client settings from Config

Signature

declare const layer: (options: Options) => Layer.Layer<OpenAiClient, never, HttpClient.HttpClient>

Source

Since v4.0.0

layerConfig

Creates a layer that loads OpenAI-compatible client settings from Config values before constructing the service.

When to use

Use when you need client settings for OpenAI-compatible APIs to be read from Effect Config values while providing OpenAiClient 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

• make for constructing the client service effectfully
• layer for providing the client from already-resolved options

Signature

declare const layerConfig: (options?: {
  readonly apiKey?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
  readonly apiUrl?: Config.Config<string> | undefined
  readonly organizationId?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
  readonly projectId?: Config.Config<Redacted.Redacted<string> | undefined> | undefined
  readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
}) => Layer.Layer<OpenAiClient, Config.ConfigError, HttpClient.HttpClient>

Source

Since v4.0.0

models

MessageStatus (type alias)

Lifecycle status shared by message, reasoning, and tool-call items.

Signature

type MessageStatus = "in_progress" | "completed" | "incomplete"

Source

Since v4.0.0

Service (interface)

Effect service interface for OpenAI-compatible chat completions and embeddings.

Details

Exposes the configured HTTP client plus helpers for non-streaming chat completions, streaming chat completions, and embeddings. Transport and schema decoding failures are mapped to AiError.

Signature

export interface Service {
  readonly client: HttpClient.HttpClient
  readonly createResponse: (
    options: CreateResponseRequestJson
  ) => Effect.Effect<[body: CreateResponse200, response: HttpClientResponse.HttpClientResponse], AiError.AiError>
  readonly createResponseStream: (
    options: Omit<CreateResponseRequestJson, "stream" | "stream_options">
  ) => Effect.Effect<
    [response: HttpClientResponse.HttpClientResponse, stream: Stream.Stream<CreateResponse200Sse, AiError.AiError>],
    AiError.AiError
  >
  readonly createEmbedding: (options: CreateEmbeddingRequestJson) => Effect.Effect<CreateEmbedding200, AiError.AiError>
}

Source

Since v4.0.0

options

Options (type alias)

Configuration options used to construct an OpenAI-compatible client.

Signature

type Options = {
  readonly apiKey?: Redacted.Redacted<string> | undefined
  readonly apiUrl?: string | undefined
  readonly organizationId?: Redacted.Redacted<string> | undefined
  readonly projectId?: Redacted.Redacted<string> | undefined
  readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
}

Source

Since v4.0.0

request

ChatCompletionContentPart (type alias)

Structured content parts accepted in chat completion messages.

Signature

type ChatCompletionContentPart =
  | {
      readonly type: "text"
      readonly text: string
    }
  | {
      readonly type: "image_url"
      readonly image_url: {
        readonly url: string
        readonly detail?: "low" | "high" | "auto" | undefined
      }
    }

Source

Since v4.0.0

ChatCompletionRequest (type alias)

Request payload for the OpenAI-compatible chat completions endpoint.

Signature

type ChatCompletionRequest = {
  readonly model: string
  readonly messages: ReadonlyArray<ChatCompletionRequestMessage>
  readonly temperature?: number | null | undefined
  readonly top_p?: number | null | undefined
  readonly max_tokens?: number | null | undefined
  readonly user?: string | null | undefined
  readonly seed?: number | undefined
  readonly parallel_tool_calls?: boolean | null | undefined
  readonly response_format?: ChatCompletionResponseFormat | undefined
  readonly tools?: ReadonlyArray<ChatCompletionTool> | undefined
  readonly tool_choice?: ChatCompletionToolChoice | undefined
  readonly service_tier?: string | undefined
  readonly reasoning?: unknown
  readonly stream?: boolean | undefined
  readonly stream_options?:
    | {
        readonly include_usage?: boolean | undefined
      }
    | undefined
  readonly [x: string]: unknown
}

Source

Since v4.0.0

ChatCompletionRequestMessage (type alias)

Message shapes accepted by the chat completions endpoint.

Signature

type ChatCompletionRequestMessage =
  | {
      readonly role: "system" | "developer" | "user" | "assistant"
      readonly content: string | ReadonlyArray<ChatCompletionContentPart> | null
      readonly tool_calls?: ReadonlyArray<ChatCompletionRequestToolCall> | undefined
    }
  | {
      readonly role: "tool"
      readonly tool_call_id: string
      readonly content: string
    }

Source

Since v4.0.0

ChatCompletionRequestToolCall (type alias)

Tool call data attached to an assistant chat completion message.

Signature

type ChatCompletionRequestToolCall = {
  readonly id: string
  readonly type: "function"
  readonly function: {
    readonly name: string
    readonly arguments: string
  }
}

Source

Since v4.0.0

ChatCompletionTool (type alias)

Function tool definition accepted by the chat completions endpoint.

Signature

type ChatCompletionTool = {
  readonly type: "function"
  readonly function: {
    readonly name: string
    readonly description?: string | null | undefined
    readonly parameters?: JsonObject | undefined
    readonly strict?: boolean | undefined
  }
}

Source

Since v4.0.0

CreateEmbeddingRequest (type alias)

Request payload for the embeddings endpoint.

Signature

type CreateEmbeddingRequest = {
  readonly input: string | ReadonlyArray<string> | ReadonlyArray<number> | ReadonlyArray<ReadonlyArray<number>>
  readonly model: string
  readonly encoding_format?: "float" | "base64" | undefined
  readonly dimensions?: number | undefined
  readonly user?: string | undefined
}

Source

Since v4.0.0

CreateEmbeddingRequestJson (type alias)

JSON request body accepted by the embeddings endpoint.

Signature

type CreateEmbeddingRequestJson = CreateEmbeddingRequest

Source

Since v4.0.0

CreateResponse (type alias)

Request options for creating a Responses-style response with an OpenAI-compatible provider.

Signature

type CreateResponse = {
  readonly metadata?: Readonly<Record<string, string>> | null | undefined
  readonly top_logprobs?: number | undefined
  readonly temperature?: number | null | undefined
  readonly top_p?: number | null | undefined
  readonly user?: string | null | undefined
  readonly safety_identifier?: string | null | undefined
  readonly prompt_cache_key?: string | null | undefined
  readonly service_tier?: string | undefined
  readonly prompt_cache_retention?: "in-memory" | "24h" | null | undefined
  readonly previous_response_id?: string | null | undefined
  readonly model?: string | undefined
  readonly reasoning?: unknown
  readonly background?: boolean | null | undefined
  readonly max_output_tokens?: number | null | undefined
  readonly max_tool_calls?: number | null | undefined
  readonly text?:
    | {
        readonly format?: TextResponseFormatConfiguration | undefined
        readonly verbosity?: "low" | "medium" | "high" | null | undefined
      }
    | undefined
  readonly tools?: ReadonlyArray<Tool> | undefined
  readonly tool_choice?: ToolChoice | undefined
  readonly truncation?: "auto" | "disabled" | null | undefined
  readonly input?: string | ReadonlyArray<InputItem> | undefined
  readonly include?: ReadonlyArray<IncludeEnum> | null | undefined
  readonly parallel_tool_calls?: boolean | null | undefined
  readonly store?: boolean | null | undefined
  readonly instructions?: string | null | undefined
  readonly stream?: boolean | null | undefined
  readonly conversation?: string | null | undefined
  readonly modalities?: ReadonlyArray<"text" | "audio"> | undefined
  readonly seed?: number | undefined
}

Source

Since v4.0.0

CreateResponseRequestJson (type alias)

JSON request body used by this client when creating a chat completion response.

Signature

type CreateResponseRequestJson = ChatCompletionRequest

Source

Since v4.0.0

InputContent (type alias)

Content blocks accepted in input messages.

Signature

type InputContent = InputTextContent | InputImageContent | InputFileContent

Source

Since v4.0.0

InputItem (type alias)

Item shapes accepted by a Responses-style input field.

Details

Supports input messages, output messages, tool calls, tool outputs, reasoning items, custom tool interactions, and item references.

Signature

type InputItem =
  | {
      readonly role: "user" | "assistant" | "system" | "developer"
      readonly content: string | ReadonlyArray<InputContent>
      readonly type?: "message" | undefined
    }
  | {
      readonly type?: "message" | undefined
      readonly role: "user" | "system" | "developer"
      readonly status?: MessageStatus | undefined
      readonly content: ReadonlyArray<InputContent>
    }
  | OutputMessage
  | FunctionCall
  | FunctionCallOutput
  | ReasoningItem
  | CustomToolCallOutput
  | CustomToolCall
  | ItemReference

Source

Since v4.0.0

Tool (type alias)

Tool definitions that can be supplied to a Responses-style request.

Signature

type Tool = FunctionTool | CustomToolParam

Source

Since v4.0.0

response

Annotation (type alias)

Citation and file-path annotations attached to output text content.

Signature

type Annotation = FileCitationAnnotation | UrlCitationAnnotation | ContainerFileCitationAnnotation | FilePathAnnotation

Source

Since v4.0.0

ChatCompletionChoice (type alias)

Decoded choice object returned by chat completion responses and chunks.

Signature

type ChatCompletionChoice = typeof ChatCompletionChoice.Type

Source

Since v4.0.0

ChatCompletionMessage (type alias)

Decoded message object from a non-streaming chat completion choice.

Signature

type ChatCompletionMessage = typeof ChatCompletionMessage.Type

Source

Since v4.0.0

ChatCompletionResponse (type alias)

Decoded successful response from the chat completions endpoint.

Signature

type ChatCompletionResponse = typeof ChatCompletionResponse.Type

Source

Since v4.0.0

ChatCompletionToolCall (type alias)

Decoded tool-call object from a chat completion response or streaming chunk.

Signature

type ChatCompletionToolCall = typeof ChatCompletionToolCall.Type

Source

Since v4.0.0

ChatCompletionUsage (type alias)

Decoded token usage summary returned by chat completions.

Signature

type ChatCompletionUsage = typeof ChatCompletionUsage.Type

Source

Since v4.0.0

CreateEmbedding200 (type alias)

Decoded successful embeddings response body.

Signature

type CreateEmbedding200 = CreateEmbeddingResponse

Source

Since v4.0.0

CreateEmbeddingResponse (type alias)

Successful response payload returned by the embeddings endpoint.

Signature

type CreateEmbeddingResponse = {
  readonly data: ReadonlyArray<Embedding>
  readonly model: string
  readonly object?: "list" | undefined
  readonly usage?:
    | {
        readonly prompt_tokens: number
        readonly total_tokens: number
      }
    | undefined
}

Source

Since v4.0.0

CreateResponse200 (type alias)

Decoded successful chat completion response body returned by createResponse.

Signature

type CreateResponse200 = ChatCompletionResponse

Source

Since v4.0.0

Embedding (type alias)

Represents one embedding item returned by an OpenAI-compatible embeddings API.

Details

The embedding can be returned either as a numeric vector or as a base64-encoded string. The index field identifies the input item that produced this embedding.

Signature

type Embedding = {
  readonly embedding: ReadonlyArray<number> | string
  readonly index: number
  readonly object?: string | undefined
}

Source

Since v4.0.0

IncludeEnum (type alias)

Optional response fields that can be requested with the include parameter.

Signature

type IncludeEnum = "message.input_image.image_url" | "reasoning.encrypted_content" | "message.output_text.logprobs"

Source

Since v4.0.0

ReasoningItem (type alias)

Reasoning output item containing encrypted reasoning content, summaries, and optional reasoning text.

Signature

type ReasoningItem = {
  readonly type: "reasoning"
  readonly id: string
  readonly encrypted_content?: string | null | undefined
  readonly summary: ReadonlyArray<SummaryTextContent>
  readonly content?: ReadonlyArray<ReasoningTextContent> | undefined
  readonly status?: MessageStatus | undefined
}

Source

Since v4.0.0

Response (type alias)

Responses-style response object returned by compatible providers or embedded in response stream lifecycle events.

Signature

type Response = {
  readonly id: string
  readonly object?: "response" | undefined
  readonly model: string
  readonly status?: "completed" | "failed" | "in_progress" | "cancelled" | "queued" | "incomplete" | undefined
  readonly created_at: number
  readonly output: ReadonlyArray<OutputItem>
  readonly usage?: ResponseUsage | null | undefined
  readonly incomplete_details?:
    | {
        readonly reason?: "max_output_tokens" | "content_filter" | undefined
      }
    | null
    | undefined
  readonly service_tier?: string | undefined
}

Source

Since v4.0.0

ResponseUsage (type alias)

Token accounting reported on Responses-style response objects.

Signature

type ResponseUsage = {
  readonly input_tokens: number
  readonly output_tokens: number
  readonly total_tokens: number
  readonly input_tokens_details?: unknown
  readonly output_tokens_details?: unknown
}

Source

Since v4.0.0

SummaryTextContent (type alias)

Text content block used for model-provided reasoning summaries.

Signature

type SummaryTextContent = {
  readonly type: "summary_text"
  readonly text: string
}

Source

Since v4.0.0

services

OpenAiClient (class)

Service tag for the OpenAI-compatible chat completions and embeddings client.

When to use

Use when building effects that depend on the low-level OpenAI-compatible client through context rather than receiving the client as a value.

Details

The tagged service is the Service interface produced by make and provided by layer or layerConfig.

See

• Service for the operations provided by the service
• make for constructing the service from explicit options
• layer for providing the service from explicit options
• layerConfig for loading client settings from Config

Signature

declare class OpenAiClient

Source

Since v4.0.0

streaming

ChatCompletionChunk (type alias)

Decoded streaming chunk emitted by the chat completions endpoint.

Signature

type ChatCompletionChunk = typeof ChatCompletionChunk.Type

Source

Since v4.0.0

ChatCompletionStreamEvent (type alias)

Streaming chat completion event, including decoded chunks and the [DONE] sentinel.

Signature

type ChatCompletionStreamEvent = ChatCompletionChunk | "[DONE]"

Source

Since v4.0.0

CreateResponse200Sse (type alias)

Decoded server-sent event payload emitted by createResponseStream.

Signature

type CreateResponse200Sse = ChatCompletionStreamEvent

Source

Since v4.0.0

ResponseStreamEvent (type alias)

Server-sent event shapes emitted by Responses-style response streams.

Signature

type ResponseStreamEvent =
  | ResponseCreatedEvent
  | ResponseCompletedEvent
  | ResponseIncompleteEvent
  | ResponseFailedEvent
  | ResponseOutputItemAddedEvent
  | ResponseOutputItemDoneEvent
  | ResponseTextDeltaEvent
  | ResponseOutputTextAnnotationAddedEvent
  | ResponseFunctionCallArgumentsDeltaEvent
  | ResponseReasoningSummaryPartAddedEvent
  | ResponseReasoningSummaryPartDoneEvent
  | ResponseReasoningSummaryTextDeltaEvent
  | ResponseErrorEvent
  | UnknownResponseStreamEvent

Source

Since v4.0.0