@atproto/lex-client 0.0.10 → 0.0.12

package/src/errors.ts

@@ -1,25 +1,48 @@
 import { LexError, LexErrorCode, LexErrorData } from '@atproto/lex-data'
-import { l } from '@atproto/lex-schema'
-import { XrpcPayload } from './util.js'
+import {
+  InferMethodError,
+  Procedure,
+  Query,
+  ResultFailure,
+  lexErrorDataSchema,
+} from '@atproto/lex-schema'
+import { XrpcResponsePayload } from './util.js'
+import {
+  WWWAuthenticate,
+  parseWWWAuthenticateHeader,
+} from './www-authenticate.js'
+
+/**
+ * HTTP status codes that indicate a transient error that may succeed on retry.
+ *
+ * Includes:
+ * - 408 Request Timeout
+ * - 425 Too Early
+ * - 429 Too Many Requests (rate limited)
+ * - 500 Internal Server Error
+ * - 502 Bad Gateway
+ * - 503 Service Unavailable
+ * - 504 Gateway Timeout
+ * - 522 Connection Timed Out (Cloudflare)
+ * - 524 A Timeout Occurred (Cloudflare)
+ */
+export const RETRYABLE_HTTP_STATUS_CODES: ReadonlySet<number> = new Set([
+  408, 425, 429, 500, 502, 503, 504, 522, 524,
+])
 
 export { LexError }
 export type { LexErrorCode, LexErrorData }
 
-export type XrpcErrorPayload<N extends LexErrorCode = LexErrorCode> =
-  XrpcPayload<LexErrorData<N>, 'application/json'>
-
-export class XrpcError<
-  N extends LexErrorCode = LexErrorCode,
-> extends LexError<N> {
-  name = 'XrpcError'
-
-  constructor(
-    error: N,
-    message: string = `${error} Lexicon RPC error`,
-    options?: ErrorOptions,
-  ) {
-    super(error, message, options)
-  }
+/**
+ * The payload structure for XRPC error responses.
+ *
+ * All XRPC errors return JSON with an `error` code and optional `message`.
+ *
+ * @typeParam N - The specific error code type
+ */
+export type XrpcErrorPayload<N extends LexErrorCode = LexErrorCode> = {
+  body: LexErrorData<N>
+  encoding: 'application/json'
 }
 
 /**
@@ -35,173 +58,338 @@ export class XrpcError<
  * This function checks whether a given payload matches this schema.
  */
 export function isXrpcErrorPayload(
-  payload: XrpcPayload | null,
+  payload: XrpcResponsePayload | null | undefined,
 ): payload is XrpcErrorPayload {
   return (
-    payload !== null &&
+    payload != null &&
     payload.encoding === 'application/json' &&
-    l.lexErrorData.matches(payload.body)
+    lexErrorDataSchema.matches(payload.body)
   )
 }
 
 /**
- * Interface representing a failed XRPC request result.
+ * Abstract base class for all XRPC errors.
+ *
+ * Extends {@link LexError} and implements {@link ResultFailure} for use with
+ * safe/result-based error handling patterns.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ * @typeParam N - The error code type
+ * @typeParam TReason - The reason type for ResultFailure
+ *
+ * @see {@link XrpcResponseError} - For valid XRPC error responses
+ * @see {@link XrpcUpstreamError} - For invalid/unexpected responses
+ * @see {@link XrpcInternalError} - For network/internal errors
  */
-type LexRpcFailureResult<N extends LexErrorCode, E> = l.ResultFailure<E> & {
-  readonly error: N
-  shouldRetry(): boolean
-  matchesSchema(): boolean
+export abstract class XrpcError<
+    M extends Procedure | Query = Procedure | Query,
+    N extends LexErrorCode = LexErrorCode,
+    TReason = unknown,
+  >
+  extends LexError<N>
+  implements ResultFailure<TReason>
+{
+  name = 'XrpcError'
+
+  constructor(
+    readonly method: M,
+    error: N,
+    message: string = `${error} Lexicon RPC error`,
+    options?: ErrorOptions,
+  ) {
+    super(error, message, options)
+  }
+
+  /**
+   * @see {@link ResultFailure.success}
+   */
+  readonly success = false as const
+
+  /**
+   * @see {@link ResultFailure.reason}
+   */
+  abstract readonly reason: TReason
+
+  /**
+   * Indicates whether the error is transient and can be retried.
+   */
+  abstract shouldRetry(): boolean
+
+  matchesSchema(): this is XrpcError<M, InferMethodError<M>> {
+    return this.method.errors?.includes(this.error) ?? false
+  }
 }
 
 /**
- * Class used to represent an HTTP request that resulted in an XRPC method error
- * That is, a non-2xx response with a valid XRPC error payload.
+ * Error class for valid XRPC error responses from the server.
+ *
+ * This represents a properly formatted XRPC error where the server returned
+ * a non-2xx status with a valid JSON error payload containing `error` and
+ * optional `message` fields.
+ *
+ * Use {@link matchesSchema} to check if the error matches the method's declared
+ * error types for type-safe error handling.
+ *
+ * @typeParam M - The XRPC method type
+ * @typeParam N - The error code type (inferred from method or generic)
+ *
+ * @example Handling specific errors
+ * ```typescript
+ * try {
+ *   await client.xrpc(someMethod, options)
+ * } catch (err) {
+ *   if (err instanceof XrpcResponseError && err.error === 'RecordNotFound') {
+ *     // Handle not found case
+ *   }
+ * }
+ * ```
  */
 export class XrpcResponseError<
-    M extends l.Procedure | l.Query = l.Procedure | l.Query,
-    N extends LexErrorCode = LexErrorCode,
-  >
-  extends XrpcError<N>
-  implements LexRpcFailureResult<N, XrpcResponseError<M, N>>
-{
+  M extends Procedure | Query = Procedure | Query,
+  N extends LexErrorCode = InferMethodError<M> | LexErrorCode,
+> extends XrpcError<M, N, XrpcResponseError<M, N>> {
   name = 'XrpcResponseError'
 
   constructor(
-    readonly method: M,
-    readonly status: number,
-    readonly headers: Headers,
+    method: M,
+    readonly response: Response,
     readonly payload: XrpcErrorPayload<N>,
     options?: ErrorOptions,
   ) {
     const { error, message } = payload.body
-    super(error, message, options)
+    super(method, error, message, options)
   }
 
-  readonly success = false
+  override get reason(): this {
+    return this
+  }
 
-  get reason(): this {
-    return this as this
+  override shouldRetry(): boolean {
+    return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)
   }
 
-  get body(): LexErrorData {
+  override toJSON() {
     return this.payload.body
   }
 
-  matchesSchema(): this is M extends {
-    errors: readonly (infer E extends string)[]
+  override toResponse(): Response {
+    // Re-expose schema-valid errors as-is to downstream clients
+    if (this.matchesSchema()) {
+      const status = this.response.status >= 500 ? 502 : this.response.status
+      return Response.json(this.toJSON(), { status })
+    }
+
+    return this.response.status >= 500
+      ? // The upstream server had an error, return a generic upstream failure
+        Response.json({ error: 'UpstreamFailure' }, { status: 502 })
+      : // If the error is on our side, return a generic internal server error
+        Response.json({ error: 'InternalServerError' }, { status: 500 })
   }
-    ? XrpcResponseError<M, E>
-    : never {
-    return this.method.errors?.includes(this.error) ?? false
+
+  get body(): LexErrorData {
+    return this.payload.body
   }
+}
 
-  shouldRetry(): boolean {
-    // Do not retry client errors
-    if (this.status < 500) return false
+export type { WWWAuthenticate }
 
-    return true
-  }
+/**
+ * Error class for 401 Unauthorized XRPC responses.
+ *
+ * Extends {@link XrpcResponseError} with access to parsed WWW-Authenticate header
+ * information, useful for implementing authentication flows.
+ *
+ * Authentication errors are never retryable as they require user intervention
+ * (e.g., re-authentication, token refresh).
+ *
+ * @typeParam M - The XRPC method type
+ * @typeParam N - The error code type
+ *
+ * @example Handling authentication errors
+ * ```typescript
+ * try {
+ *   await client.xrpc(someMethod, options)
+ * } catch (err) {
+ *   if (err instanceof XrpcAuthenticationError) {
+ *     const { DPoP } = err.wwwAuthenticate
+ *     if (DPoP?.error === 'use_dpop_nonce') {
+ *       // Handle DPoP nonce requirement
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class XrpcAuthenticationError<
+  M extends Procedure | Query = Procedure | Query,
+  N extends LexErrorCode = LexErrorCode,
+> extends XrpcResponseError<M, N> {
+  name = 'XrpcAuthenticationError'
 
-  toJSON() {
-    return this.payload.body
+  override shouldRetry(): boolean {
+    return false
   }
 
-  toResponse(): Response {
-    const { status, headers } = this
-    return Response.json(this.toJSON(), { status, headers })
+  #wwwAuthenticateCached?: WWWAuthenticate
+  /**
+   * Parsed WWW-Authenticate header from the response.
+   * Contains authentication scheme parameters (e.g., Bearer realm, DPoP nonce).
+   */
+  get wwwAuthenticate(): WWWAuthenticate {
+    return (this.#wwwAuthenticateCached ??=
+      parseWWWAuthenticateHeader(
+        this.response.headers.get('www-authenticate'),
+      ) ?? {})
   }
 }
 
 /**
- * This class represents an invalid XRPC response from the server.
+ * Error class for invalid or unprocessable XRPC responses from upstream servers.
+ *
+ * This occurs when the server returns a response that doesn't conform to the
+ * XRPC protocol, such as:
+ * - Missing or invalid Content-Type header
+ * - Response body that doesn't match the method's output schema
+ * - Non-JSON error responses
+ * - Responses from non-XRPC endpoints
+ *
+ * The error code is always 'UpstreamFailure' and maps to HTTP 502 Bad Gateway
+ * when converted to a response.
+ *
+ * @typeParam M - The XRPC method type
  */
 export class XrpcUpstreamError<
-    N extends 'InvalidResponse' | 'UpstreamFailure' =
-      | 'InvalidResponse'
-      | 'UpstreamFailure',
-  >
-  extends XrpcError<N>
-  implements LexRpcFailureResult<N, XrpcUpstreamError<N>>
-{
-  name = 'XrpcUpstreamError' as const
-
-  // For debugging purposes, we keep the response details here
-  readonly response: {
-    status: number
-    headers: Headers
-    payload: XrpcPayload | null
-  }
+  M extends Procedure | Query = Procedure | Query,
+> extends XrpcError<M, 'UpstreamFailure', XrpcUpstreamError<M>> {
+  name = 'XrpcUpstreamError'
 
   constructor(
-    error: N,
-    message: string,
-    response: { status: number; headers: Headers },
-    payload: XrpcPayload | null,
+    method: M,
+    readonly response: Response,
+    readonly payload: XrpcResponsePayload | null = null,
+    message: string = `Unexpected upstream XRPC response`,
     options?: ErrorOptions,
   ) {
-    super(error, message, { cause: options?.cause })
-    this.response = {
-      status: response.status,
-      headers: response.headers,
-      payload,
-    }
+    super(method, 'UpstreamFailure', message, options)
   }
 
-  readonly success = false as const
-
-  get reason(): this {
+  override get reason(): this {
     return this
   }
 
-  matchesSchema(): false {
-    return false
+  override shouldRetry(): boolean {
+    return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)
   }
 
-  shouldRetry(): boolean {
-    // Do not retry client errors
-    return this.response.status >= 500
-  }
-
-  toResponse(): Response {
+  override toResponse(): Response {
     return Response.json(this.toJSON(), { status: 502 })
   }
 }
 
-export class XrpcUnexpectedError
-  extends XrpcError<'InternalServerError'>
-  implements LexRpcFailureResult<'InternalServerError', unknown>
-{
-  name = 'XrpcUnexpectedError' as const
-
-  protected constructor(message: string, options: Required<ErrorOptions>) {
-    super('InternalServerError', message, options)
-  }
-
-  readonly success = false
-
-  get reason() {
-    return this.cause
+/**
+ * Error class for internal/client-side errors during XRPC requests.
+ *
+ * This represents errors that occur before or during the request that are not
+ * server responses, such as:
+ * - Network errors (connection refused, DNS failure)
+ * - Request timeouts
+ * - Request aborted via AbortSignal
+ * - Invalid request construction
+ *
+ * The error code is always 'InternalServerError' and these errors are
+ * optimistically considered retryable.
+ *
+ * @typeParam M - The XRPC method type
+ */
+export class XrpcInternalError<
+  M extends Procedure | Query = Procedure | Query,
+> extends XrpcError<M, 'InternalServerError', XrpcInternalError<M>> {
+  name = 'XrpcInternalError'
+
+  constructor(method: M, message?: string, options?: ErrorOptions) {
+    super(
+      method,
+      'InternalServerError',
+      message ?? 'Unable to fulfill XRPC request',
+      options,
+    )
   }
 
-  matchesSchema(): false {
-    return false
+  override get reason(): this {
+    return this
   }
 
-  shouldRetry(): boolean {
+  override shouldRetry(): true {
+    // Ideally, we would inspect the reason to determine if it's retryable
+    // (by detecting network errors, timeouts, etc.). Since these cases are
+    // highly platform-dependent, we optimistically assume all internal
+    // errors are retryable.
     return true
   }
 
-  toResponse(): Response {
-    return Response.json(this.toJSON(), { status: 500 })
+  override toResponse(): Response {
+    // Do not expose internal error details to downstream clients
+    return Response.json({ error: this.error }, { status: 500 })
   }
+}
+
+/**
+ * Union type of all possible XRPC failure types.
+ *
+ * Used as the return type for safe/non-throwing XRPC methods. Check the
+ * `success` property to distinguish between success and failure:
+ *
+ * @typeParam M - The XRPC method type
+ *
+ * @example
+ * ```typescript
+ * const result = await client.xrpcSafe(someMethod, options)
+ * if (result.success) {
+ *   console.log(result.body) // XrpcResponse
+ * } else {
+ *   // result is XrpcFailure (XrpcResponseError | XrpcUpstreamError | XrpcInternalError)
+ *   console.error(result.error, result.message)
+ * }
+ * ```
+ */
+export type XrpcFailure<M extends Procedure | Query = Procedure | Query> =
+  // The server returned a valid XRPC error response
+  | XrpcResponseError<M>
+  // The response was not a valid XRPC response, or it does not match the schema
+  | XrpcUpstreamError<M>
+  // Something went wrong (network error, etc.)
+  | XrpcInternalError<M>
 
-  static from(
-    cause: unknown,
-    message: string = cause instanceof LexError
-      ? cause.message
-      : 'XRPC request failed',
-  ): XrpcUnexpectedError {
-    if (cause instanceof XrpcUnexpectedError) return cause
-    return new XrpcUnexpectedError(message, { cause })
+/**
+ * Converts an unknown error into an appropriate {@link XrpcFailure} type.
+ *
+ * If the error is already an XrpcFailure for the given method, returns it as-is.
+ * Otherwise, wraps it in an {@link XrpcInternalError}.
+ *
+ * @param method - The XRPC method that was called
+ * @param cause - The error to convert
+ * @returns An XrpcFailure instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const response = await fetch(...)
+ *   // ... process response
+ * } catch (err) {
+ *   return asXrpcFailure(method, err)
+ * }
+ * ```
+ */
+export function asXrpcFailure<M extends Procedure | Query>(
+  method: M,
+  cause: unknown,
+): XrpcFailure<M> {
+  if (
+    cause instanceof XrpcResponseError ||
+    cause instanceof XrpcUpstreamError ||
+    cause instanceof XrpcInternalError
+  ) {
+    if (cause.method === method) return cause
   }
+
+  return new XrpcInternalError(method, undefined, { cause })
 }