@effect/ai-openrouter 0.8.3 → 4.0.0-beta.0

package/src/index.ts

@@ -1,19 +1,35 @@
 /**
  * @since 1.0.0
  */
-export * as Generated from "./Generated.js"
+
+// @barrel: Auto-generated exports. Do not edit manually.
+
+/**
+ * @since 1.0.0
+ */
+export * as Generated from "./Generated.ts"
+
+/**
+ * @since 1.0.0
+ */
+export * as OpenRouterClient from "./OpenRouterClient.ts"
 
 /**
  * @since 1.0.0
  */
-export * as OpenRouterClient from "./OpenRouterClient.js"
+export * as OpenRouterConfig from "./OpenRouterConfig.ts"
 
 /**
+ * OpenRouter error metadata augmentation.
+ *
+ * Provides OpenRouter-specific metadata fields for AI error types through
+ * module augmentation, enabling typed access to OpenRouter error details.
+ *
  * @since 1.0.0
  */
-export * as OpenRouterConfig from "./OpenRouterConfig.js"
+export * as OpenRouterError from "./OpenRouterError.ts"
 
 /**
  * @since 1.0.0
  */
-export * as OpenRouterLanguageModel from "./OpenRouterLanguageModel.js"
+export * as OpenRouterLanguageModel from "./OpenRouterLanguageModel.ts"

package/src/internal/errors.ts

@@ -0,0 +1,373 @@
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import { dual } from "effect/Function"
+import * as Number from "effect/Number"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Redactable from "effect/Redactable"
+import * as Schema from "effect/Schema"
+import * as AiError from "effect/unstable/ai/AiError"
+import type * as Response from "effect/unstable/ai/Response"
+import type * as HttpClientError from "effect/unstable/http/HttpClientError"
+import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import type * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
+import type * as Generated from "../Generated.ts"
+import type { OpenRouterErrorMetadata } from "../OpenRouterError.ts"
+
+// =============================================================================
+// OpenRouter Error Body Schema
+// =============================================================================
+
+/** @internal */
+export const OpenRouterErrorBody = Schema.Struct({
+  error: Schema.Struct({
+    message: Schema.String,
+    type: Schema.optional(Schema.NullOr(Schema.String)),
+    code: Schema.optional(Schema.NullOr(Schema.Union([Schema.String, Schema.Number.check(Schema.isFinite())])))
+  })
+})
+
+/** @internal */
+export type OpenRouterClientErrorBody = {
+  readonly error: {
+    readonly code: string | number | null
+    readonly message: string
+    readonly param?: string | null
+    readonly type?: string | null
+  }
+}
+
+// =============================================================================
+// Error Mappers
+// =============================================================================
+
+/** @internal */
+export const mapSchemaError = dual<
+  (method: string) => (error: Schema.SchemaError) => AiError.AiError,
+  (error: Schema.SchemaError, method: string) => AiError.AiError
+>(2, (error, method) =>
+  AiError.make({
+    module: "OpenRouterClient",
+    method,
+    reason: AiError.InvalidOutputError.fromSchemaError(error)
+  }))
+
+/** @internal */
+export const mapClientError = dual<
+  (method: string) => (error: Generated.OpenRouterClientError<string, OpenRouterClientErrorBody>) => AiError.AiError,
+  (error: Generated.OpenRouterClientError<string, OpenRouterClientErrorBody>, method: string) => AiError.AiError
+>(2, (error, method) => {
+  const { request, response, cause } = error
+  const status = response.status
+  const headers = response.headers as Record<string, string>
+  const metadata: OpenRouterErrorMetadata = {
+    errorCode: cause.error.code ?? null,
+    errorType: cause.error.type ?? null,
+    requestId: headers["x-request-id"] ?? null
+  }
+  const http = buildHttpContext({ request, response, body: JSON.stringify(cause) })
+  const reason = mapStatusCodeToReason({
+    status,
+    headers,
+    message: cause.error.message,
+    metadata,
+    http
+  })
+  return AiError.make({ module: "OpenRouterClient", method, reason })
+})
+
+/** @internal */
+export const mapHttpClientError = dual<
+  (method: string) => (error: HttpClientError.HttpClientError) => Effect.Effect<never, AiError.AiError>,
+  (error: HttpClientError.HttpClientError, method: string) => Effect.Effect<never, AiError.AiError>
+>(2, (error, method) => {
+  const reason = error.reason
+  switch (reason._tag) {
+    case "TransportError": {
+      return Effect.fail(AiError.make({
+        module: "OpenRouterClient",
+        method,
+        reason: new AiError.NetworkError({
+          reason: "TransportError",
+          description: reason.description,
+          request: buildHttpRequestDetails(reason.request)
+        })
+      }))
+    }
+    case "EncodeError": {
+      return Effect.fail(AiError.make({
+        module: "OpenRouterClient",
+        method,
+        reason: new AiError.NetworkError({
+          reason: "EncodeError",
+          description: reason.description,
+          request: buildHttpRequestDetails(reason.request)
+        })
+      }))
+    }
+    case "InvalidUrlError": {
+      return Effect.fail(AiError.make({
+        module: "OpenRouterClient",
+        method,
+        reason: new AiError.NetworkError({
+          reason: "InvalidUrlError",
+          description: reason.description,
+          request: buildHttpRequestDetails(reason.request)
+        })
+      }))
+    }
+    case "StatusCodeError": {
+      return mapStatusCodeError(reason, method)
+    }
+    case "DecodeError": {
+      return Effect.fail(AiError.make({
+        module: "OpenRouterClient",
+        method,
+        reason: new AiError.InvalidOutputError({
+          description: reason.description ?? "Failed to decode response"
+        })
+      }))
+    }
+    case "EmptyBodyError": {
+      return Effect.fail(AiError.make({
+        module: "OpenRouterClient",
+        method,
+        reason: new AiError.InvalidOutputError({
+          description: reason.description ?? "Response body was empty"
+        })
+      }))
+    }
+  }
+})
+
+/** @internal */
+const mapStatusCodeError = Effect.fnUntraced(function*(
+  error: HttpClientError.StatusCodeError,
+  method: string
+) {
+  const { request, response, description } = error
+  const status = response.status
+  const headers = response.headers as Record<string, string>
+  const requestId = headers["x-request-id"]
+
+  let body: string | undefined = description
+  if (!description || !description.startsWith("{")) {
+    const responseBody = yield* Effect.option(response.text)
+    if (Option.isSome(responseBody) && responseBody.value) {
+      body = responseBody.value
+    }
+  }
+
+  let json: unknown = undefined
+  // @effect-diagnostics effect/tryCatchInEffectGen:off
+  try {
+    json = Predicate.isNotUndefined(body) ? JSON.parse(body) : undefined
+  } catch {
+    json = undefined
+  }
+  const decoded = Schema.decodeUnknownOption(OpenRouterErrorBody)(json)
+
+  const reason = mapStatusCodeToReason({
+    status,
+    headers,
+    message: Option.isSome(decoded) ? decoded.value.error.message : undefined,
+    http: buildHttpContext({ request, response, body }),
+    metadata: {
+      errorCode: Option.isSome(decoded) ? decoded.value.error.code ?? null : null,
+      errorType: Option.isSome(decoded) ? decoded.value.error.type ?? null : null,
+      requestId: requestId ?? null
+    }
+  })
+
+  return yield* AiError.make({ module: "OpenRouterClient", method, reason })
+})
+
+// =============================================================================
+// Rate Limits
+// =============================================================================
+
+/** @internal */
+export const parseRateLimitHeaders = (headers: Record<string, string>) => {
+  const retryAfterRaw = headers["retry-after"]
+  let retryAfter: Duration.Duration | undefined
+  if (Predicate.isNotUndefined(retryAfterRaw)) {
+    const parsed = Number.parse(retryAfterRaw)
+    if (Predicate.isNotUndefined(parsed)) {
+      retryAfter = Duration.seconds(parsed)
+    }
+  }
+  const remainingRaw = headers["x-ratelimit-remaining-requests"]
+  const remaining = Predicate.isNotUndefined(remainingRaw) ? Number.parse(remainingRaw) ?? null : null
+  return {
+    retryAfter,
+    limit: headers["x-ratelimit-limit-requests"] ?? null,
+    remaining,
+    resetRequests: headers["x-ratelimit-reset-requests"] ?? null,
+    resetTokens: headers["x-ratelimit-reset-tokens"] ?? null
+  }
+}
+
+// =============================================================================
+// HTTP Context
+// =============================================================================
+
+/** @internal */
+export const buildHttpRequestDetails = (
+  request: HttpClientRequest.HttpClientRequest
+): typeof Response.HttpRequestDetails.Type => ({
+  method: request.method,
+  url: request.url,
+  urlParams: Array.from(request.urlParams),
+  hash: request.hash,
+  headers: Redactable.redact(request.headers) as Record<string, string>
+})
+
+/** @internal */
+export const buildHttpContext = (params: {
+  readonly request: HttpClientRequest.HttpClientRequest
+  readonly response?: HttpClientResponse.HttpClientResponse
+  readonly body?: string | undefined
+}): typeof AiError.HttpContext.Type => ({
+  request: buildHttpRequestDetails(params.request),
+  response: Predicate.isNotUndefined(params.response)
+    ? {
+      status: params.response.status,
+      headers: Redactable.redact(params.response.headers) as Record<string, string>
+    }
+    : undefined,
+  body: params.body
+})
+
+// =============================================================================
+// HTTP Status Code
+// =============================================================================
+
+const buildInvalidRequestDescription = (params: {
+  readonly status: number
+  readonly message: string | undefined
+  readonly method: string
+  readonly url: string
+  readonly errorCode: string | number | null
+  readonly errorType: string | null
+  readonly requestId: string | null
+  readonly body: string | undefined
+}): string => {
+  const parts: Array<string> = []
+
+  if (params.message) {
+    parts.push(params.message)
+  } else {
+    parts.push(`HTTP ${params.status}`)
+  }
+
+  parts.push(`(${params.method} ${params.url})`)
+
+  if (params.errorCode) {
+    parts.push(`[code: ${params.errorCode}]`)
+  } else if (params.errorType) {
+    parts.push(`[type: ${params.errorType}]`)
+  }
+
+  if (params.requestId) {
+    parts.push(`[requestId: ${params.requestId}]`)
+  }
+
+  if (!params.message && params.body) {
+    const truncated = params.body.length > 200
+      ? params.body.slice(0, 200) + "..."
+      : params.body
+    parts.push(`Response: ${truncated}`)
+  }
+
+  return parts.join(" ")
+}
+
+/** @internal */
+export const mapStatusCodeToReason = ({ status, headers, message, metadata, http }: {
+  readonly status: number
+  readonly headers: Record<string, string>
+  readonly message: string | undefined
+  readonly metadata: OpenRouterErrorMetadata
+  readonly http: typeof AiError.HttpContext.Type
+}): AiError.AiErrorReason => {
+  const invalidRequestDescription = buildInvalidRequestDescription({
+    status,
+    message,
+    method: http.request.method,
+    url: http.request.url,
+    errorCode: metadata.errorCode,
+    errorType: metadata.errorType,
+    requestId: metadata.requestId,
+    body: http.body
+  })
+
+  switch (status) {
+    case 400:
+      return new AiError.InvalidRequestError({
+        description: invalidRequestDescription,
+        metadata: { openrouter: metadata },
+        http
+      })
+    case 401:
+      return new AiError.AuthenticationError({
+        kind: "InvalidKey",
+        metadata: { openrouter: metadata },
+        http
+      })
+    case 403:
+      return new AiError.AuthenticationError({
+        kind: "InsufficientPermissions",
+        metadata: { openrouter: metadata },
+        http
+      })
+    case 404:
+    case 409:
+    case 422:
+      return new AiError.InvalidRequestError({
+        description: invalidRequestDescription,
+        metadata: { openrouter: metadata },
+        http
+      })
+    case 429: {
+      if (
+        metadata.errorCode === "insufficient_quota" ||
+        metadata.errorType === "insufficient_quota"
+      ) {
+        return new AiError.QuotaExhaustedError({
+          metadata: { openrouter: metadata },
+          http
+        })
+      }
+      const { retryAfter, ...rateLimitMetadata } = parseRateLimitHeaders(headers)
+      return new AiError.RateLimitError({
+        retryAfter,
+        metadata: {
+          openrouter: {
+            ...metadata,
+            ...rateLimitMetadata
+          }
+        },
+        http
+      })
+    }
+    case 529:
+      return new AiError.InternalProviderError({
+        description: message ?? "OpenRouter API is overloaded",
+        metadata: { openrouter: metadata },
+        http
+      })
+    default:
+      if (status >= 500) {
+        return new AiError.InternalProviderError({
+          description: message ?? "Server error",
+          metadata: { openrouter: metadata },
+          http
+        })
+      }
+      return new AiError.UnknownError({
+        description: message,
+        metadata: { openrouter: metadata },
+        http
+      })
+  }
+}

package/src/internal/utilities.ts

@@ -1,26 +1,93 @@
-import type * as Response from "@effect/ai/Response"
 import * as Predicate from "effect/Predicate"
-import type * as Generated from "../Generated.js"
+import type * as Response from "effect/unstable/ai/Response"
+import type { ReasoningDetails } from "../OpenRouterLanguageModel.ts"
 
 const finishReasonMap: Record<string, Response.FinishReason> = {
   content_filter: "content-filter",
   error: "error",
   function_call: "tool-calls",
-  tool_calls: "tool-calls",
   length: "length",
+  tool_calls: "tool-calls",
   stop: "stop"
 }
 
 /** @internal */
 export const resolveFinishReason = (
-  finishReason: typeof Generated.ChatCompletionFinishReason.Type | null
-): Response.FinishReason => {
-  if (Predicate.isNull(finishReason)) {
-    return "unknown"
+  finishReason: string | null | undefined
+): Response.FinishReason =>
+  Predicate.isNotNullish(finishReason)
+    ? finishReasonMap[finishReason]
+    : "other"
+
+/**
+ * Tracks ReasoningDetailUnion entries and deduplicates them based
+ * on a derived canonical key.
+ *
+ * This is used when converting messages to ensure the API request only
+ * contains unique reasoning details, preventing "Duplicate item found with id"
+ * errors in multi-turn conversations.
+ *
+ * The canonical key logic matches the OpenRouter API's deduplication exactly
+ * (see openrouter-web/packages/llm-interfaces/reasonings/duplicate-tracker.ts):
+ * - Summary: key = summary field
+ * - Encrypted: key = id field (if truthy) or data field
+ * - Text: key = text field (if truthy) or signature field (if truthy)
+ *
+ * @internal
+ */
+export class ReasoningDetailsDuplicateTracker {
+  readonly #seenKeys = new Set<string>()
+
+  /**
+   * Attempts to track a detail.
+   *
+   * @returns `true` if this is a NEW detail (not seen before and has valid key),
+   * or `false` if it was skipped (no valid key) or already seen (duplicate).
+   */
+  upsert(detail: ReasoningDetails[number]): boolean {
+    const key = this.getCanonicalKey(detail)
+
+    if (Predicate.isNull(key)) {
+      return false
+    }
+
+    if (this.#seenKeys.has(key)) {
+      return false
+    }
+
+    this.#seenKeys.add(key)
+
+    return true
   }
-  const reason = finishReasonMap[finishReason]
-  if (Predicate.isUndefined(reason)) {
-    return "unknown"
+
+  private getCanonicalKey(detail: ReasoningDetails[number]): string | null {
+    // This logic matches the OpenRouter API's deduplication exactly.
+    // See: openrouter-web/packages/llm-interfaces/reasonings/duplicate-tracker.ts
+    switch (detail.type) {
+      case "reasoning.summary": {
+        return detail.summary
+      }
+
+      case "reasoning.encrypted": {
+        return Predicate.isNotNullish(detail.id) ? detail.id : detail.data
+      }
+
+      case "reasoning.text": {
+        if (Predicate.isNotNullish(detail.text)) {
+          return detail.text
+        }
+
+        if (Predicate.isNotNullish(detail.signature)) {
+          return detail.signature
+        }
+
+        return null
+      }
+
+      default: {
+        // Handle unknown types gracefully
+        return null
+      }
+    }
   }
-  return reason
 }

package/Generated/package.json

@@ -1,6 +0,0 @@
-{
-  "sideEffects": [],
-  "main": "../dist/cjs/Generated.js",
-  "module": "../dist/esm/Generated.js",
-  "types": "../dist/dts/Generated.d.ts"
-}

package/OpenRouterClient/package.json

@@ -1,6 +0,0 @@
-{
-  "sideEffects": [],
-  "main": "../dist/cjs/OpenRouterClient.js",
-  "module": "../dist/esm/OpenRouterClient.js",
-  "types": "../dist/dts/OpenRouterClient.d.ts"
-}

package/OpenRouterConfig/package.json

@@ -1,6 +0,0 @@
-{
-  "sideEffects": [],
-  "main": "../dist/cjs/OpenRouterConfig.js",
-  "module": "../dist/esm/OpenRouterConfig.js",
-  "types": "../dist/dts/OpenRouterConfig.d.ts"
-}

package/OpenRouterLanguageModel/package.json

@@ -1,6 +0,0 @@
-{
-  "sideEffects": [],
-  "main": "../dist/cjs/OpenRouterLanguageModel.js",
-  "module": "../dist/esm/OpenRouterLanguageModel.js",
-  "types": "../dist/dts/OpenRouterLanguageModel.d.ts"
-}

package/README.md

@@ -1,5 +0,0 @@
-# `@effect/ai-openrouter`
-
-## Documentation
-
-- **API Reference**: [View the full documentation](https://effect-ts.github.io/effect/docs/ai/openrouter).