sailfork / t3code-github / .repos/ effect/ packages/ ai/ openrouter/ src/ OpenRouterClient.ts

/**
 * HTTP client for OpenRouter's chat completions and alpha Decisions APIs,
 * with authentication, site ranking headers, typed errors, and chat streaming.
 *
 * @stability unstable
 * @since 4.0.0
 */
import * as AiError from "effect/ai/AiError"
import type * as Config from "effect/Config"
import * as Context from "effect/Context"
import * as Effect from "effect/Effect"
import * as Sse from "effect/encoding/Sse"
import { identity } from "effect/Function"
import * as HttpBody from "effect/http/HttpBody"
import * as HttpClient from "effect/http/HttpClient"
import * as HttpClientRequest from "effect/http/HttpClientRequest"
import * as HttpClientResponse from "effect/http/HttpClientResponse"
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 Stream from "effect/Stream"
import * as Generated from "./Generated.ts"
import * as Errors from "./internal/errors.ts"
import { OpenRouterConfig } from "./OpenRouterConfig.ts"
import * as OpenRouterSchema from "./OpenRouterSchema.ts"

// =============================================================================
// Service Interface
// =============================================================================

/**
 * The OpenRouter client service interface.
 *
 * **Details**
 *
 * Provides methods for interacting with OpenRouter's Chat Completions API,
 * including both synchronous and streaming message creation.
 *
 * @stability unstable
 * @category services
 * @since 4.0.0
 */
export interface Service {
  readonly client: Generated.OpenRouterClient

  readonly createDecisions: (
    options: typeof OpenRouterSchema.DecisionsRequest.Encoded
  ) => Effect.Effect<
    [body: typeof OpenRouterSchema.DecisionsResponse.Type, response: HttpClientResponse.HttpClientResponse],
    AiError.AiError
  >

  readonly createChatCompletion: (
    options: typeof Generated.ChatRequest.Encoded
  ) => Effect.Effect<
    [body: typeof Generated.SendChatCompletionRequest200.Type, response: HttpClientResponse.HttpClientResponse],
    AiError.AiError
  >

  readonly createChatCompletionStream: (
    options: Omit<typeof Generated.ChatRequest.Encoded, "stream" | "stream_options">
  ) => Effect.Effect<
    [
      response: HttpClientResponse.HttpClientResponse,
      stream: Stream.Stream<ChatStreamingResponseChunkData, AiError.AiError>
    ],
    AiError.AiError
  >
}

/**
 * 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.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export type ChatStreamingResponseChunkData = typeof Generated.ChatStreamingResponse.fields.data.Type

// =============================================================================
// Service Identifier
// =============================================================================

/**
 * Service tag for the OpenRouter client.
 *
 * **When to use**
 *
 * 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`
 *
 * @stability unstable
 * @category services
 * @since 4.0.0
 */
export class OpenRouterClient extends Context.Service<
  OpenRouterClient,
  Service
>()("@effect/ai-openrouter/OpenRouterClient") {}

// =============================================================================
// Options
// =============================================================================

/**
 * Configuration for creating an OpenRouter client.
 *
 * @stability unstable
 * @category options
 * @since 4.0.0
 */
export type Options = {
  readonly apiKey?: Redacted.Redacted<string> | undefined

  /**
   * Base URL for the versioned API. Decisions replace a trailing "/v1" with
   * "/alpha/decisions"; otherwise they append "/alpha/decisions" to this URL.
   */
  readonly apiUrl?: string | undefined

  /**
   * Optional URL of your site for rankings on `openrouter.ai`.
   */
  readonly siteReferrer?: string | undefined

  /**
   * Optional title of your site for rankings on `openrouter.ai`.
   */
  readonly siteTitle?: string | undefined

  /**
   * Optional transformer for the underlying HTTP client.
   *
   * **When to use**
   *
   * Use to add middleware, logging, or custom request/response handling.
   */
  readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
}

// =============================================================================
// Constructor
// =============================================================================

/**
 * Creates an OpenRouter client service from explicit options.
 *
 * **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.
 *
 * Scoped `OpenRouterConfig.withClientTransform` applies to generated client
 * methods and alpha Decisions requests, but not streaming chat completions.
 *
 * @see {@link layer} for providing this client from explicit options
 * @see {@link layerConfig} for loading client settings from `Config`
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const make = Effect.fnUntraced(
  function*(options: Options): Effect.fn.Return<Service, never, HttpClient.HttpClient> {
    const baseClient = yield* HttpClient.HttpClient

    const makeHttpClient = (baseUrl: string) =>
      baseClient.pipe(
        HttpClient.mapRequest((request) =>
          request.pipe(
            HttpClientRequest.prependUrl(baseUrl),
            options.apiKey ? HttpClientRequest.bearerToken(options.apiKey) : identity,
            options.siteReferrer ? HttpClientRequest.setHeader("HTTP-Referer", options.siteReferrer) : identity,
            options.siteTitle ? HttpClientRequest.setHeader("X-Title", options.siteTitle) : identity,
            HttpClientRequest.acceptJson
          )
        ),
        options.transformClient ?? identity
      )

    const httpClient = makeHttpClient(options.apiUrl ?? "https://openrouter.ai/api/v1")
    const httpClientOk = HttpClient.filterStatusOk(httpClient)

    // Remove the version suffix for alpha requests, preserving proxy prefixes.
    const decisionsClient = makeHttpClient(
      (options.apiUrl ?? "https://openrouter.ai/api/v1").replace(/\/v1\/?$/, "")
    )
    const createDecisions: Service["createDecisions"] = Effect.fnUntraced(
      function*(payload) {
        const config = yield* OpenRouterConfig.getOrUndefined
        const client = HttpClient.filterStatusOk(
          config?.transformClient ? config.transformClient(decisionsClient) : decisionsClient
        )
        const request = yield* HttpClientRequest.bodyJson(HttpClientRequest.post("/alpha/decisions"), payload).pipe(
          Effect.mapError((error) =>
            AiError.make({
              module: "OpenRouterClient",
              method: "createDecisions",
              reason: new AiError.InvalidRequestError({ description: String(error) })
            })
          )
        )
        const response = yield* client.execute(request)
        const body = yield* HttpClientResponse.schemaBodyJson(OpenRouterSchema.DecisionsResponse)(response)
        return [body, response] as [
          typeof OpenRouterSchema.DecisionsResponse.Type,
          HttpClientResponse.HttpClientResponse
        ]
      },
      Effect.catchTags({
        HttpClientError: (error) => Errors.mapHttpClientError(error, "createDecisions"),
        SchemaError: (error) => Effect.fail(Errors.mapSchemaError(error, "createDecisions"))
      })
    )

    const client = Generated.make(httpClient, {
      transformClient: Effect.fnUntraced(function*(client) {
        const config = yield* OpenRouterConfig.getOrUndefined
        if (Predicate.isNotUndefined(config?.transformClient)) {
          return config.transformClient(client)
        }
        return client
      })
    })

    const createChatCompletion: Service["createChatCompletion"] = (payload) =>
      client.sendChatCompletionRequest({ payload, config: { includeResponse: true } }).pipe(
        Effect.catchTags({
          SendChatCompletionRequest400: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest401: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest402: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest403: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest404: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest408: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest413: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest422: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest429: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest500: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest502: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest503: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest524: (error) => Errors.mapClientError(error, "createChatCompletion"),
          SendChatCompletionRequest529: (error) => Errors.mapClientError(error, "createChatCompletion"),
          HttpClientError: (error) => Errors.mapHttpClientError(error, "createChatCompletion"),
          SchemaError: (error) => Effect.fail(Errors.mapSchemaError(error, "createChatCompletion"))
        })
      )

    const buildChatCompletionStream = (
      response: HttpClientResponse.HttpClientResponse
    ): [
      HttpClientResponse.HttpClientResponse,
      Stream.Stream<ChatStreamingResponseChunkData, AiError.AiError>
    ] => {
      const stream = response.stream.pipe(
        Stream.decodeText(),
        Stream.pipeThroughChannel(Sse.decode()),
        Stream.mapEffect((event) => decodeChatCompletionSseData(event.data)),
        Stream.takeWhile((data) => data !== "[DONE]"),
        Stream.catchTags({
          // TODO: handle SSE retries
          Retry: (error) => Stream.die(error),
          SseError: (error) => Stream.fail(Errors.mapSseError(error, "createChatCompletionStream")),
          HttpClientError: (error) => Stream.fromEffect(Errors.mapHttpClientError(error, "createChatCompletionStream")),
          SchemaError: (error) => Stream.fail(Errors.mapSchemaError(error, "createChatCompletionStream"))
        })
      ) as any
      return [response, stream]
    }

    const createChatCompletionStream: Service["createChatCompletionStream"] = (payload) =>
      httpClientOk.execute(
        HttpClientRequest.post("/chat/completions", {
          body: HttpBody.jsonUnsafe({
            ...payload,
            stream: true,
            stream_options: { include_usage: true }
          })
        })
      ).pipe(
        Effect.map(buildChatCompletionStream),
        Effect.catchTag(
          "HttpClientError",
          (error) => Errors.mapHttpClientError(error, "createChatCompletionStream")
        )
      )

    return OpenRouterClient.of({
      client,
      createDecisions,
      createChatCompletion,
      createChatCompletionStream
    })
  }
)

// =============================================================================
// Layers
// =============================================================================

/**
 * Creates a layer for the OpenRouter client with the given options.
 *
 * **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`
 *
 * @stability unstable
 * @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 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
 *
 * @stability unstable
 * @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> | undefined

  /**
   * The config value to load for the API URL.
   */
  readonly apiUrl?: Config.Config<string> | undefined

  /**
   * The config value to load for the site referrer URL.
   */
  readonly siteReferrer?: Config.Config<string> | undefined

  /**
   * The config value to load for the site title.
   */
  readonly siteTitle?: Config.Config<string> | undefined

  /**
   * Optional transformer for the HTTP client.
   */
  readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
}): Layer.Layer<OpenRouterClient, Config.ConfigError, HttpClient.HttpClient> =>
  Layer.effect(
    OpenRouterClient,
    Effect.gen(function*() {
      const apiKey = Predicate.isNotUndefined(options?.apiKey)
        ? yield* options.apiKey
        : undefined
      const apiUrl = Predicate.isNotUndefined(options?.apiUrl)
        ? yield* options.apiUrl
        : undefined
      const siteReferrer = Predicate.isNotUndefined(options?.siteReferrer)
        ? yield* options.siteReferrer
        : undefined
      const siteTitle = Predicate.isNotUndefined(options?.siteTitle)
        ? yield* options.siteTitle
        : undefined
      return yield* make({
        apiKey,
        apiUrl,
        siteReferrer,
        siteTitle,
        transformClient: options?.transformClient
      })
    })
  )

// =============================================================================
// Internal Utilities
// =============================================================================

const ChatStreamingResponseChunkDataFromString = Schema.fromJsonString(Generated.ChatStreamingResponse.fields.data)
const decodeChatStreamingResponseChunkData = Schema.decodeUnknownEffect(ChatStreamingResponseChunkDataFromString)

const decodeChatCompletionSseData = (
  data: string
): Effect.Effect<ChatStreamingResponseChunkData | "[DONE]", Schema.SchemaError> =>
  data === "[DONE]"
    ? Effect.succeed(data)
    : decodeChatStreamingResponseChunkData(data)