@alumbwe/anvil 1.0.20 → 1.0.21

package/vendor/@anvil/common/src/util/error.ts

@@ -0,0 +1,562 @@
+export type ErrorOr<T, E extends ErrorObject = ErrorObject> =
+  | Success<T>
+  | Failure<E>
+
+export type Success<T> = {
+  success: true
+  value: T
+}
+
+export type Failure<E extends ErrorObject = ErrorObject> = {
+  success: false
+  error: E
+}
+
+/**
+ * Result type for prompt functions that can be aborted.
+ * Provides rich semantics to distinguish between successful completion and user abort.
+ *
+ * ## When to use `PromptResult<T>` vs `ErrorOr<T>`
+ *
+ * Use `PromptResult<T>` when:
+ * - The operation can be cancelled by the user (via AbortSignal)
+ * - An abort is an expected outcome, not an error
+ * - You need to distinguish between errors (which might trigger fallbacks) and
+ *   user-initiated aborts (which should propagate immediately)
+ *
+ * Use `ErrorOr<T>` when:
+ * - The operation can fail with an error that should be handled
+ * - There's no concept of user-initiated abort
+ * - You want to return error details rather than throw
+ *
+ * ## Abort handling patterns
+ *
+ * 1. **Check and return early** - For graceful handling where abort means "stop, no error":
+ *    ```ts
+ *    const result = await promptAiSdk({ ... })
+ *    if (result.aborted) return // or return null, false, etc.
+ *    doSomething(result.value)
+ *    ```
+ *
+ * 2. **Unwrap and throw** - For propagating aborts as exceptions:
+ *    ```ts
+ *    const value = unwrapPromptResult(await promptAiSdk({ ... }))
+ *    // Throws if aborted, callers should use isAbortError() in catch blocks
+ *    ```
+ *
+ * 3. **Rethrow in catch blocks** - Prevent swallowing abort errors:
+ *    ```ts
+ *    try {
+ *      await someOperation()
+ *    } catch (error) {
+ *      if (isAbortError(error)) throw error // Don't swallow aborts
+ *      // Handle other errors
+ *    }
+ *    ```
+ */
+export type PromptResult<T> = PromptSuccess<T> | PromptAborted
+
+export type PromptSuccess<T> = {
+  aborted: false
+  value: T
+}
+
+export type PromptAborted = {
+  aborted: true
+  reason?: string
+}
+
+export type ErrorObject = {
+  name: string
+  message: string
+  stack?: string
+  /** HTTP status code from error.status (used by some libraries) */
+  status?: number
+  /** HTTP status code from error.statusCode (used by AI SDK and Anvil errors) */
+  statusCode?: number
+  /** Optional machine-friendly error code, if available */
+  code?: string
+  /** Optional raw error object */
+  rawError?: string
+  /** Response body from API errors (AI SDK APICallError) */
+  responseBody?: string
+  /** URL that was called (API errors) */
+  url?: string
+  /** Whether the error is retryable (API errors) */
+  isRetryable?: boolean
+  /** Request body values that were sent (API errors) - stringified for safety */
+  requestBodyValues?: string
+  /** Cause of the error, if nested */
+  cause?: ErrorObject
+}
+
+export function success<T>(value: T): Success<T> {
+  return {
+    success: true,
+    value,
+  }
+}
+
+export function failure(error: unknown): Failure<ErrorObject> {
+  return {
+    success: false,
+    error: getErrorObject(error),
+  }
+}
+
+/**
+ * Create a successful prompt result.
+ */
+export function promptSuccess<T>(value: T): PromptSuccess<T> {
+  return {
+    aborted: false,
+    value,
+  }
+}
+
+/**
+ * Create an aborted prompt result.
+ */
+export function promptAborted(reason?: string): PromptAborted {
+  return {
+    aborted: true,
+    ...(reason !== undefined && { reason }),
+  }
+}
+
+/**
+ * Standard error message for aborted requests.
+ * Use this constant when throwing abort errors to ensure consistency.
+ */
+export const ABORT_ERROR_MESSAGE = 'Request aborted'
+
+/**
+ * Custom error class for abort errors.
+ * Use this class instead of generic Error for abort errors to ensure
+ * robust detection via isAbortError() (checks error.name === 'AbortError').
+ */
+export class AbortError extends Error {
+  constructor(reason?: string) {
+    super(reason ? `${ABORT_ERROR_MESSAGE}: ${reason}` : ABORT_ERROR_MESSAGE)
+    this.name = 'AbortError'
+  }
+}
+
+/**
+ * Check if an error is an abort error.
+ * Use this helper to detect abort errors in catch blocks.
+ *
+ * Detects both:
+ * - Errors with message starting with 'Request aborted' (thrown by our code via AbortError)
+ * - Native AbortError (thrown by fetch/AI SDK when AbortSignal is triggered)
+ */
+export function isAbortError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false
+  }
+  // Check for our custom abort error message:
+  // - Exact match: 'Request aborted'
+  // - With reason: 'Request aborted: <reason>' (from AbortError class)
+  if (
+    error.message === ABORT_ERROR_MESSAGE ||
+    error.message.startsWith(`${ABORT_ERROR_MESSAGE}: `)
+  ) {
+    return true
+  }
+  // Check for native AbortError (DOMException or Error with name 'AbortError')
+  // This is thrown by fetch, AI SDK, and other web APIs when AbortSignal is triggered
+  if (error.name === 'AbortError') {
+    return true
+  }
+  return false
+}
+
+/**
+ * Unwrap a PromptResult, returning the value if successful or throwing if aborted.
+ *
+ * Use this helper for consistent abort handling when you want aborts to propagate
+ * as exceptions. Callers should use `isAbortError()` in catch blocks to detect
+ * and handle abort errors appropriately (e.g., rethrow instead of logging as errors).
+ *
+ * @throws {AbortError} When result.aborted is true.
+ */
+export function unwrapPromptResult<T>(result: PromptResult<T>): T {
+  if (result.aborted) {
+    throw new AbortError(result.reason)
+  }
+  return result.value
+}
+
+/**
+ * Parses a JSON response body string from an API error to extract structured error details.
+ * Used to extract machine-readable error codes and human-readable messages from API responses
+ * (e.g., AI SDK's APICallError includes a responseBody with the server's JSON response).
+ *
+ * Returns extracted fields, or an empty object if the responseBody is not a valid JSON string
+ * with the expected shape.
+ */
+export function parseApiErrorResponseBody(responseBody: unknown): {
+  errorCode?: string
+  message?: string
+  countryCode?: string
+  countryBlockReason?: string
+  ipPrivacySignals?: string[]
+} {
+  if (typeof responseBody !== 'string') return {}
+  try {
+    const parsed: unknown = JSON.parse(responseBody)
+    if (!parsed || typeof parsed !== 'object') return {}
+    const result: {
+      errorCode?: string
+      message?: string
+      countryCode?: string
+      countryBlockReason?: string
+      ipPrivacySignals?: string[]
+    } = {}
+    if (
+      'error' in parsed &&
+      typeof (parsed as { error: unknown }).error === 'string'
+    ) {
+      result.errorCode = (parsed as { error: string }).error
+    }
+    if (
+      'message' in parsed &&
+      typeof (parsed as { message: unknown }).message === 'string'
+    ) {
+      result.message = (parsed as { message: string }).message
+    }
+    // OpenAI-style nested error object: { error: { message, code, type } }.
+    // Upstream provider errors (Fireworks, OpenRouter, etc.) are relayed to
+    // the client in this shape.
+    if (
+      'error' in parsed &&
+      typeof (parsed as { error: unknown }).error === 'object' &&
+      (parsed as { error: unknown }).error !== null
+    ) {
+      const nested = (parsed as { error: Record<string, unknown> }).error
+      if (result.errorCode === undefined) {
+        if (typeof nested.code === 'string') {
+          result.errorCode = nested.code
+        } else if (typeof nested.type === 'string') {
+          result.errorCode = nested.type
+        }
+      }
+      if (result.message === undefined && typeof nested.message === 'string') {
+        result.message = nested.message
+      }
+    }
+    if (
+      'countryCode' in parsed &&
+      typeof (parsed as { countryCode: unknown }).countryCode === 'string'
+    ) {
+      result.countryCode = (parsed as { countryCode: string }).countryCode
+    }
+    if (
+      'countryBlockReason' in parsed &&
+      typeof (parsed as { countryBlockReason: unknown }).countryBlockReason ===
+        'string'
+    ) {
+      result.countryBlockReason = (
+        parsed as { countryBlockReason: string }
+      ).countryBlockReason
+    }
+    if ('ipPrivacySignals' in parsed) {
+      const signals = (parsed as { ipPrivacySignals: unknown }).ipPrivacySignals
+      if (Array.isArray(signals)) {
+        result.ipPrivacySignals = signals.filter(
+          (signal): signal is string => typeof signal === 'string',
+        )
+      }
+    }
+    return result
+  } catch {
+    return {}
+  }
+}
+
+export type ApiErrorDetails = ReturnType<typeof parseApiErrorResponseBody> & {
+  statusCode?: number
+}
+
+function getApiErrorCandidates(
+  error: unknown,
+  seen = new Set<object>(),
+): unknown[] {
+  if (!error || typeof error !== 'object') return [error]
+  if (seen.has(error)) return []
+  seen.add(error)
+
+  const candidates: unknown[] = [error]
+  const errorWithNested = error as {
+    lastError?: unknown
+    errors?: unknown[]
+    cause?: unknown
+  }
+
+  candidates.push(...getApiErrorCandidates(errorWithNested.lastError, seen))
+
+  if (Array.isArray(errorWithNested.errors)) {
+    for (const nestedError of [...errorWithNested.errors].reverse()) {
+      candidates.push(...getApiErrorCandidates(nestedError, seen))
+    }
+  }
+
+  candidates.push(...getApiErrorCandidates(errorWithNested.cause, seen))
+
+  return candidates
+}
+
+function getApiErrorStatusCode(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') return undefined
+
+  if ('statusCode' in error) {
+    const statusCode = (error as { statusCode: unknown }).statusCode
+    if (typeof statusCode === 'number') return statusCode
+  }
+
+  if ('status' in error) {
+    const status = (error as { status: unknown }).status
+    if (typeof status === 'number') return status
+  }
+
+  return undefined
+}
+
+function getApiErrorResponseBody(error: unknown): unknown {
+  if (!error || typeof error !== 'object') return undefined
+  if (!('responseBody' in error)) return undefined
+  return (error as { responseBody: unknown }).responseBody
+}
+
+function hasParsedApiErrorDetails(
+  details: ReturnType<typeof parseApiErrorResponseBody>,
+): boolean {
+  return (
+    details.errorCode !== undefined ||
+    details.message !== undefined ||
+    details.countryCode !== undefined ||
+    details.countryBlockReason !== undefined ||
+    details.ipPrivacySignals !== undefined
+  )
+}
+
+/**
+ * Extracts HTTP status and structured server error fields from API errors,
+ * including AI SDK RetryError wrappers whose useful APICallError is nested in
+ * `lastError` / `errors`.
+ */
+export function extractApiErrorDetails(error: unknown): ApiErrorDetails {
+  for (const candidate of getApiErrorCandidates(error)) {
+    const statusCode = getApiErrorStatusCode(candidate)
+    const parsed = parseApiErrorResponseBody(getApiErrorResponseBody(candidate))
+
+    if (statusCode !== undefined || hasParsedApiErrorDetails(parsed)) {
+      return {
+        ...parsed,
+        ...(statusCode !== undefined && { statusCode }),
+      }
+    }
+  }
+
+  return {}
+}
+
+/**
+ * Detects the runtime's fetch inactivity timeout (a DOMException named
+ * "TimeoutError"). Bun hardcodes this to fire after 5 minutes without
+ * receiving any bytes on a fetch response — including while still waiting on
+ * the response headers, verified 2026-08-02 against a server that delayed only
+ * its headers. Walks AI SDK RetryError wrappers and cause chains.
+ */
+export function isFetchIdleTimeoutError(error: unknown): boolean {
+  for (const candidate of getApiErrorCandidates(error)) {
+    if (!candidate || typeof candidate !== 'object') continue
+    const { name, message } = candidate as { name?: unknown; message?: unknown }
+    if (
+      name === 'TimeoutError' ||
+      (typeof message === 'string' &&
+        message.toLowerCase().includes('the operation timed out'))
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * User-facing explanation for the fetch idle timeout. The raw runtime message
+ * ("The operation timed out.") reads like a server failure, so this states the
+ * symptom instead.
+ *
+ * It deliberately does NOT blame the user's network. That copy shipped in June
+ * 2026 on the assumption that a heartbeat covered every silent window, but the
+ * heartbeat only started once the upstream model had answered — a slow model
+ * start produced exactly this error with nothing wrong on the user's end, and
+ * sent them chasing their own VPN. See grace-flush.ts on the server.
+ */
+export const FETCH_IDLE_TIMEOUT_USER_MESSAGE =
+  'Connection timed out: no data was received from the server for 5 minutes, so the request was aborted.\n\n' +
+  'This can be a slow model start on our side, or a connection dropped in transit (VPN, proxy, firewall, or flaky network).\n\n' +
+  'Retrying your message usually works. If it keeps happening, try a different model, or check your network/VPN/proxy.'
+
+/**
+ * Substrings of error messages that indicate the TCP connection died in
+ * transit (as opposed to the server returning an error response). Bun's fetch
+ * throws a plain Error with "The socket connection was closed unexpectedly..."
+ * and code ECONNRESET/ConnectionClosed; undici throws TypeError "fetch failed".
+ */
+const TRANSIENT_NETWORK_ERROR_MESSAGE_PATTERNS = [
+  'socket connection was closed unexpectedly',
+  'fetch failed',
+  'failed to fetch',
+  'network connection was lost',
+]
+
+const TRANSIENT_NETWORK_ERROR_CODES = new Set([
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'EPIPE',
+  'ETIMEDOUT',
+  // Bun-specific fetch error codes
+  'ConnectionClosed',
+  'ConnectionRefused',
+  'FailedToOpenSocket',
+])
+
+/**
+ * Detects transient connection-level failures (socket closed/reset, connection
+ * refused, etc.) where no HTTP response was received. These are safe to retry
+ * and should be shown to the user as a connectivity problem instead of a raw
+ * runtime error with a stack trace. Walks AI SDK RetryError wrappers and
+ * cause chains.
+ */
+export function isTransientNetworkError(error: unknown): boolean {
+  for (const candidate of getApiErrorCandidates(error)) {
+    if (!candidate || typeof candidate !== 'object') continue
+    const { message, code } = candidate as {
+      message?: unknown
+      code?: unknown
+    }
+    if (typeof code === 'string' && TRANSIENT_NETWORK_ERROR_CODES.has(code)) {
+      return true
+    }
+    if (typeof message === 'string') {
+      const lower = message.toLowerCase()
+      if (
+        TRANSIENT_NETWORK_ERROR_MESSAGE_PATTERNS.some((pattern) =>
+          lower.includes(pattern),
+        )
+      ) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+/**
+ * User-facing explanation for a dropped connection. The raw runtime message
+ * ("The socket connection was closed unexpectedly. For more information, pass
+ * `verbose: true`...") plus a stack trace reads like a crash; in practice the
+ * connection to the server was cut mid-request, which is transient and safe
+ * to retry.
+ */
+export const TRANSIENT_NETWORK_ERROR_USER_MESSAGE =
+  'Connection interrupted: the connection to the server was closed unexpectedly, even after retrying.\n\n' +
+  'This is usually a transient issue — a flaky network, VPN/proxy, or the server briefly under heavy load.\n\n' +
+  'Your progress is saved. Please try sending your message again.'
+
+// Extended error properties that various libraries add to Error objects
+interface ExtendedErrorProperties {
+  status?: number
+  statusCode?: number
+  code?: string
+  // API error properties (AI SDK APICallError, etc.)
+  responseBody?: string
+  url?: string
+  isRetryable?: boolean
+  requestBodyValues?: Record<string, unknown>
+  cause?: unknown
+}
+
+/**
+ * Safely stringify an object, handling circular references and large objects.
+ */
+function safeStringify(value: unknown, maxLength = 10000): string | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value === 'string') return value.slice(0, maxLength)
+  try {
+    const seen = new WeakSet()
+    const str = JSON.stringify(
+      value,
+      (_, val) => {
+        if (typeof val === 'object' && val !== null) {
+          if (seen.has(val)) return '[Circular]'
+          seen.add(val)
+        }
+        return val
+      },
+      2,
+    )
+    return str?.slice(0, maxLength)
+  } catch {
+    return '[Unable to stringify]'
+  }
+}
+
+export function getErrorObject(
+  error: unknown,
+  options: { includeRawError?: boolean } = {},
+): ErrorObject {
+  if (error instanceof Error) {
+    const extError = error as Error & Partial<ExtendedErrorProperties>
+
+    // Extract responseBody - could be string or object
+    let responseBody: string | undefined
+    if (extError.responseBody !== undefined) {
+      responseBody = safeStringify(extError.responseBody)
+    }
+
+    // Extract requestBodyValues - typically an object, stringify for logging
+    let requestBodyValues: string | undefined
+    if (
+      extError.requestBodyValues !== undefined &&
+      typeof extError.requestBodyValues === 'object'
+    ) {
+      requestBodyValues = safeStringify(extError.requestBodyValues)
+    }
+
+    // Extract cause - recursively convert to ErrorObject if present
+    let cause: ErrorObject | undefined
+    if (extError.cause !== undefined) {
+      cause = getErrorObject(extError.cause, options)
+    }
+
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+      status: typeof extError.status === 'number' ? extError.status : undefined,
+      statusCode:
+        typeof extError.statusCode === 'number'
+          ? extError.statusCode
+          : undefined,
+      code: typeof extError.code === 'string' ? extError.code : undefined,
+      rawError: options.includeRawError ? safeStringify(error) : undefined,
+      // API error fields
+      responseBody,
+      url: typeof extError.url === 'string' ? extError.url : undefined,
+      isRetryable:
+        typeof extError.isRetryable === 'boolean'
+          ? extError.isRetryable
+          : undefined,
+      requestBodyValues,
+      cause,
+    }
+  }
+
+  return {
+    name: 'Error',
+    message: `${error}`,
+  }
+}