@atproto/lex-client 0.0.14 → 0.0.15

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["import { LexError, LexErrorCode, LexErrorData } from '@atproto/lex-data'\nimport {\n  InferMethodError,\n  Procedure,\n  Query,\n  ResultFailure,\n  lexErrorDataSchema,\n} from '@atproto/lex-schema'\nimport { XrpcResponsePayload } from './util.js'\nimport {\n  WWWAuthenticate,\n  parseWWWAuthenticateHeader,\n} from './www-authenticate.js'\n\n/**\n * HTTP status codes that indicate a transient error that may succeed on retry.\n *\n * Includes:\n * - 408 Request Timeout\n * - 425 Too Early\n * - 429 Too Many Requests (rate limited)\n * - 500 Internal Server Error\n * - 502 Bad Gateway\n * - 503 Service Unavailable\n * - 504 Gateway Timeout\n * - 522 Connection Timed Out (Cloudflare)\n * - 524 A Timeout Occurred (Cloudflare)\n */\nexport const RETRYABLE_HTTP_STATUS_CODES: ReadonlySet<number> = new Set([\n  408, 425, 429, 500, 502, 503, 504, 522, 524,\n])\n\nexport { LexError }\nexport type { LexErrorCode, LexErrorData }\n\n/**\n * The payload structure for XRPC error responses.\n *\n * All XRPC errors return JSON with an `error` code and optional `message`.\n *\n * @typeParam N - The specific error code type\n */\nexport type XrpcErrorPayload<N extends LexErrorCode = LexErrorCode> = {\n  body: LexErrorData<N>\n  encoding: 'application/json'\n}\n\n/**\n * All unsuccessful responses should follow a standard error response\n * schema. The Content-Type should be application/json, and the payload\n * should be a JSON object with the following fields:\n *\n * - `error` (string, required): type name of the error (generic ASCII\n *   constant, no whitespace)\n * - `message` (string, optional): description of the error, appropriate for\n *   display to humans\n *\n * This function checks whether a given payload matches this schema.\n */\nexport function isXrpcErrorPayload(\n  payload: XrpcResponsePayload | null | undefined,\n): payload is XrpcErrorPayload {\n  return (\n    payload != null &&\n    payload.encoding === 'application/json' &&\n    lexErrorDataSchema.matches(payload.body)\n  )\n}\n\n/**\n * Abstract base class for all XRPC errors.\n *\n * Extends {@link LexError} and implements {@link ResultFailure} for use with\n * safe/result-based error handling patterns.\n *\n * @typeParam M - The XRPC method type (Procedure or Query)\n * @typeParam N - The error code type\n * @typeParam TReason - The reason type for ResultFailure\n *\n * @see {@link XrpcResponseError} - For valid XRPC error responses\n * @see {@link XrpcUpstreamError} - For invalid/unexpected responses\n * @see {@link XrpcInternalError} - For network/internal errors\n */\nexport abstract class XrpcError<\n    M extends Procedure | Query = Procedure | Query,\n    N extends LexErrorCode = LexErrorCode,\n    TReason = unknown,\n  >\n  extends LexError<N>\n  implements ResultFailure<TReason>\n{\n  name = 'XrpcError'\n\n  constructor(\n    readonly method: M,\n    error: N,\n    message: string = `${error} Lexicon RPC error`,\n    options?: ErrorOptions,\n  ) {\n    super(error, message, options)\n  }\n\n  /**\n   * @see {@link ResultFailure.success}\n   */\n  readonly success = false as const\n\n  /**\n   * @see {@link ResultFailure.reason}\n   */\n  abstract readonly reason: TReason\n\n  /**\n   * Indicates whether the error is transient and can be retried.\n   */\n  abstract shouldRetry(): boolean\n\n  matchesSchema(): this is XrpcError<M, InferMethodError<M>> {\n    return this.method.errors?.includes(this.error) ?? false\n  }\n}\n\n/**\n * Error class for valid XRPC error responses from the server.\n *\n * This represents a properly formatted XRPC error where the server returned\n * a non-2xx status with a valid JSON error payload containing `error` and\n * optional `message` fields.\n *\n * Use {@link matchesSchema} to check if the error matches the method's declared\n * error types for type-safe error handling.\n *\n * @typeParam M - The XRPC method type\n * @typeParam N - The error code type (inferred from method or generic)\n *\n * @example Handling specific errors\n * ```typescript\n * try {\n *   await client.xrpc(someMethod, options)\n * } catch (err) {\n *   if (err instanceof XrpcResponseError && err.error === 'RecordNotFound') {\n *     // Handle not found case\n *   }\n * }\n * ```\n */\nexport class XrpcResponseError<\n  M extends Procedure | Query = Procedure | Query,\n  N extends LexErrorCode = InferMethodError<M> | LexErrorCode,\n> extends XrpcError<M, N, XrpcResponseError<M, N>> {\n  name = 'XrpcResponseError'\n\n  constructor(\n    method: M,\n    readonly response: Response,\n    readonly payload: XrpcErrorPayload<N>,\n    options?: ErrorOptions,\n  ) {\n    const { error, message } = payload.body\n    super(method, error, message, options)\n  }\n\n  override get reason(): this {\n    return this\n  }\n\n  override shouldRetry(): boolean {\n    return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)\n  }\n\n  override toJSON() {\n    return this.payload.body\n  }\n\n  override toResponse(): Response {\n    // Re-expose schema-valid errors as-is to downstream clients\n    if (this.matchesSchema()) {\n      const status = this.response.status >= 500 ? 502 : this.response.status\n      return Response.json(this.toJSON(), { status })\n    }\n\n    return this.response.status >= 500\n      ? // The upstream server had an error, return a generic upstream failure\n        Response.json({ error: 'UpstreamFailure' }, { status: 502 })\n      : // If the error is on our side, return a generic internal server error\n        Response.json({ error: 'InternalServerError' }, { status: 500 })\n  }\n\n  get body(): LexErrorData {\n    return this.payload.body\n  }\n}\n\nexport type { WWWAuthenticate }\n\n/**\n * Error class for 401 Unauthorized XRPC responses.\n *\n * Extends {@link XrpcResponseError} with access to parsed WWW-Authenticate header\n * information, useful for implementing authentication flows.\n *\n * Authentication errors are never retryable as they require user intervention\n * (e.g., re-authentication, token refresh).\n *\n * @typeParam M - The XRPC method type\n * @typeParam N - The error code type\n *\n * @example Handling authentication errors\n * ```typescript\n * try {\n *   await client.xrpc(someMethod, options)\n * } catch (err) {\n *   if (err instanceof XrpcAuthenticationError) {\n *     const { DPoP } = err.wwwAuthenticate\n *     if (DPoP?.error === 'use_dpop_nonce') {\n *       // Handle DPoP nonce requirement\n *     }\n *   }\n * }\n * ```\n */\nexport class XrpcAuthenticationError<\n  M extends Procedure | Query = Procedure | Query,\n  N extends LexErrorCode = LexErrorCode,\n> extends XrpcResponseError<M, N> {\n  name = 'XrpcAuthenticationError'\n\n  override shouldRetry(): boolean {\n    return false\n  }\n\n  #wwwAuthenticateCached?: WWWAuthenticate\n  /**\n   * Parsed WWW-Authenticate header from the response.\n   * Contains authentication scheme parameters (e.g., Bearer realm, DPoP nonce).\n   */\n  get wwwAuthenticate(): WWWAuthenticate {\n    return (this.#wwwAuthenticateCached ??=\n      parseWWWAuthenticateHeader(\n        this.response.headers.get('www-authenticate'),\n      ) ?? {})\n  }\n}\n\n/**\n * Error class for invalid or unprocessable XRPC responses from upstream servers.\n *\n * This occurs when the server returns a response that doesn't conform to the\n * XRPC protocol, such as:\n * - Missing or invalid Content-Type header\n * - Response body that doesn't match the method's output schema\n * - Non-JSON error responses\n * - Responses from non-XRPC endpoints\n *\n * The error code is always 'UpstreamFailure' and maps to HTTP 502 Bad Gateway\n * when converted to a response.\n *\n * @typeParam M - The XRPC method type\n */\nexport class XrpcUpstreamError<\n  M extends Procedure | Query = Procedure | Query,\n> extends XrpcError<M, 'UpstreamFailure', XrpcUpstreamError<M>> {\n  name = 'XrpcUpstreamError'\n\n  constructor(\n    method: M,\n    readonly response: Response,\n    readonly payload: XrpcResponsePayload | null = null,\n    message: string = `Unexpected upstream XRPC response`,\n    options?: ErrorOptions,\n  ) {\n    super(method, 'UpstreamFailure', message, options)\n  }\n\n  override get reason(): this {\n    return this\n  }\n\n  override shouldRetry(): boolean {\n    return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)\n  }\n\n  override toResponse(): Response {\n    return Response.json(this.toJSON(), { status: 502 })\n  }\n}\n\n/**\n * Error class for internal/client-side errors during XRPC requests.\n *\n * This represents errors that occur before or during the request that are not\n * server responses, such as:\n * - Network errors (connection refused, DNS failure)\n * - Request timeouts\n * - Request aborted via AbortSignal\n * - Invalid request construction\n *\n * The error code is always 'InternalServerError' and these errors are\n * optimistically considered retryable.\n *\n * @typeParam M - The XRPC method type\n */\nexport class XrpcInternalError<\n  M extends Procedure | Query = Procedure | Query,\n> extends XrpcError<M, 'InternalServerError', XrpcInternalError<M>> {\n  name = 'XrpcInternalError'\n\n  constructor(method: M, message?: string, options?: ErrorOptions) {\n    super(\n      method,\n      'InternalServerError',\n      message ?? 'Unable to fulfill XRPC request',\n      options,\n    )\n  }\n\n  override get reason(): this {\n    return this\n  }\n\n  override shouldRetry(): true {\n    // Ideally, we would inspect the reason to determine if it's retryable\n    // (by detecting network errors, timeouts, etc.). Since these cases are\n    // highly platform-dependent, we optimistically assume all internal\n    // errors are retryable.\n    return true\n  }\n\n  override toResponse(): Response {\n    // Do not expose internal error details to downstream clients\n    return Response.json({ error: this.error }, { status: 500 })\n  }\n}\n\n/**\n * Union type of all possible XRPC failure types.\n *\n * Used as the return type for safe/non-throwing XRPC methods. Check the\n * `success` property to distinguish between success and failure:\n *\n * @typeParam M - The XRPC method type\n *\n * @example\n * ```typescript\n * const result = await client.xrpcSafe(someMethod, options)\n * if (result.success) {\n *   console.log(result.body) // XrpcResponse\n * } else {\n *   // result is XrpcFailure (XrpcResponseError | XrpcUpstreamError | XrpcInternalError)\n *   console.error(result.error, result.message)\n * }\n * ```\n */\nexport type XrpcFailure<M extends Procedure | Query = Procedure | Query> =\n  // The server returned a valid XRPC error response\n  | XrpcResponseError<M>\n  // The response was not a valid XRPC response, or it does not match the schema\n  | XrpcUpstreamError<M>\n  // Something went wrong (network error, etc.)\n  | XrpcInternalError<M>\n\n/**\n * Converts an unknown error into an appropriate {@link XrpcFailure} type.\n *\n * If the error is already an XrpcFailure for the given method, returns it as-is.\n * Otherwise, wraps it in an {@link XrpcInternalError}.\n *\n * @param method - The XRPC method that was called\n * @param cause - The error to convert\n * @returns An XrpcFailure instance\n *\n * @example\n * ```typescript\n * try {\n *   const response = await fetch(...)\n *   // ... process response\n * } catch (err) {\n *   return asXrpcFailure(method, err)\n * }\n * ```\n */\nexport function asXrpcFailure<M extends Procedure | Query>(\n  method: M,\n  cause: unknown,\n): XrpcFailure<M> {\n  if (\n    cause instanceof XrpcResponseError ||\n    cause instanceof XrpcUpstreamError ||\n    cause instanceof XrpcInternalError\n  ) {\n    if (cause.method === method) return cause\n  }\n\n  return new XrpcInternalError(method, undefined, { cause })\n}\n"]}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["import { LexError, LexErrorCode, LexErrorData } from '@atproto/lex-data'\nimport {\n  InferMethodError,\n  LexValidationError,\n  Procedure,\n  Query,\n  ResultFailure,\n  lexErrorDataSchema,\n} from '@atproto/lex-schema'\nimport { XrpcResponsePayload } from './util.js'\nimport {\n  WWWAuthenticate,\n  parseWWWAuthenticateHeader,\n} from './www-authenticate.js'\n\nexport type DownstreamError<N extends LexErrorCode = LexErrorCode> = {\n  status: number\n  headers?: Headers\n  encoding?: 'application/json'\n  body: LexErrorData<N>\n}\n\n/**\n * HTTP status codes that indicate a transient error that may succeed on retry.\n *\n * Includes:\n * - 408 Request Timeout\n * - 425 Too Early\n * - 429 Too Many Requests (rate limited)\n * - 500 Internal Server Error\n * - 502 Bad Gateway\n * - 503 Service Unavailable\n * - 504 Gateway Timeout\n * - 522 Connection Timed Out (Cloudflare)\n * - 524 A Timeout Occurred (Cloudflare)\n */\nexport const RETRYABLE_HTTP_STATUS_CODES: ReadonlySet<number> = new Set([\n  408, 425, 429, 500, 502, 503, 504, 522, 524,\n])\n\nexport { LexError }\nexport type { LexErrorCode, LexErrorData }\n\n/**\n * The payload structure for XRPC error responses.\n *\n * All XRPC errors return JSON with an `error` code and optional `message`.\n *\n * @typeParam N - The specific error code type\n */\nexport type XrpcErrorPayload<N extends LexErrorCode = LexErrorCode> = {\n  body: LexErrorData<N>\n  encoding: 'application/json'\n}\n\n/**\n * All unsuccessful responses should follow a standard error response\n * schema. The Content-Type should be application/json, and the payload\n * should be a JSON object with the following fields:\n *\n * - `error` (string, required): type name of the error (generic ASCII\n *   constant, no whitespace)\n * - `message` (string, optional): description of the error, appropriate for\n *   display to humans\n *\n * This function checks whether a given payload matches this schema.\n */\nexport function isXrpcErrorPayload(\n  payload: XrpcResponsePayload | null | undefined,\n): payload is XrpcErrorPayload {\n  return (\n    payload != null &&\n    payload.encoding === 'application/json' &&\n    lexErrorDataSchema.matches(payload.body)\n  )\n}\n\n/**\n * Abstract base class for all XRPC errors.\n *\n * Extends {@link LexError} and implements {@link ResultFailure} for use with\n * safe/result-based error handling patterns.\n *\n * @typeParam M - The XRPC method type (Procedure or Query)\n * @typeParam N - The error code type\n * @typeParam TReason - The reason type for ResultFailure\n *\n * @see {@link XrpcResponseError} - For valid XRPC error responses\n * @see {@link XrpcUpstreamError} - For invalid/unexpected responses\n * @see {@link XrpcInternalError} - For network/internal errors\n */\nexport abstract class XrpcError<\n    M extends Procedure | Query = Procedure | Query,\n    N extends LexErrorCode = LexErrorCode,\n    TReason = unknown,\n  >\n  extends LexError<N>\n  implements ResultFailure<TReason>\n{\n  name = 'XrpcError'\n\n  constructor(\n    readonly method: M,\n    error: N,\n    message: string = `${error} Lexicon RPC error`,\n    options?: ErrorOptions,\n  ) {\n    super(error, message, options)\n  }\n\n  /**\n   * @see {@link ResultFailure.success}\n   */\n  readonly success = false as const\n\n  /**\n   * @see {@link ResultFailure.reason}\n   */\n  abstract readonly reason: TReason\n\n  /**\n   * Indicates whether the error is transient and can be retried.\n   */\n  abstract shouldRetry(): boolean\n\n  abstract toDownstreamError(): DownstreamError\n\n  matchesSchemaErrors(): this is XrpcError<M, InferMethodError<M>> {\n    return this.method.errors?.includes(this.error) ?? false\n  }\n}\n\n/**\n * Error class for valid XRPC error responses from the server.\n *\n * This represents a properly formatted XRPC error where the server returned\n * a non-2xx status with a valid JSON error payload containing `error` and\n * optional `message` fields.\n *\n * Use {@link matchesSchemaErrors} to check if the error matches the method's declared\n * error types for type-safe error handling.\n *\n * @typeParam M - The XRPC method type\n * @typeParam N - The error code type (inferred from method or generic)\n *\n * @example Handling specific errors\n * ```typescript\n * try {\n *   await client.xrpc(someMethod, options)\n * } catch (err) {\n *   if (err instanceof XrpcResponseError && err.error === 'RecordNotFound') {\n *     // Handle not found case\n *   }\n * }\n * ```\n */\nexport class XrpcResponseError<\n  M extends Procedure | Query = Procedure | Query,\n  N extends LexErrorCode = InferMethodError<M> | LexErrorCode,\n> extends XrpcError<M, N, XrpcResponseError<M, N>> {\n  name = 'XrpcResponseError'\n\n  constructor(\n    method: M,\n    readonly response: Response,\n    readonly payload: XrpcErrorPayload<N>,\n    options?: ErrorOptions,\n  ) {\n    const { error, message } = payload.body\n    super(method, error, message, options)\n  }\n\n  override get reason(): this {\n    return this\n  }\n\n  override shouldRetry(): boolean {\n    return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)\n  }\n\n  override toJSON(): LexErrorData<N> {\n    return this.payload.body\n  }\n\n  override toDownstreamError(): DownstreamError {\n    // If the upstream server returned a 5xx error, we want to return a 502 Bad\n    // Gateway to downstream clients, as the issue is with the upstream server,\n    // not us. We still return the original error code and message in the body\n    // for transparency, but we do not want to expose internal server errors\n    // from the upstream server as-is to downstream clients.\n    return {\n      status: this.response.status === 500 ? 502 : this.status,\n      headers: stripHopByHopHeaders(this.headers),\n      body: this.toJSON(),\n    }\n  }\n\n  get status(): number {\n    return this.response.status\n  }\n\n  get headers(): Headers {\n    return this.response.headers\n  }\n\n  get body(): LexErrorData<N> {\n    return this.payload.body\n  }\n}\n\nexport type { WWWAuthenticate }\n\n/**\n * Error class for 401 Unauthorized XRPC responses.\n *\n * Extends {@link XrpcResponseError} with access to parsed WWW-Authenticate header\n * information, useful for implementing authentication flows.\n *\n * Authentication errors are never retryable as they require user intervention\n * (e.g., re-authentication, token refresh).\n *\n * @typeParam M - The XRPC method type\n * @typeParam N - The error code type\n *\n * @example Handling authentication errors\n * ```typescript\n * try {\n *   await client.xrpc(someMethod, options)\n * } catch (err) {\n *   if (err instanceof XrpcAuthenticationError) {\n *     const { DPoP } = err.wwwAuthenticate\n *     if (DPoP?.error === 'use_dpop_nonce') {\n *       // Handle DPoP nonce requirement\n *     }\n *   }\n * }\n * ```\n */\nexport class XrpcAuthenticationError<\n  M extends Procedure | Query = Procedure | Query,\n  N extends LexErrorCode = LexErrorCode,\n> extends XrpcResponseError<M, N> {\n  name = 'XrpcAuthenticationError'\n\n  override shouldRetry(): boolean {\n    return false\n  }\n\n  #wwwAuthenticateCached?: WWWAuthenticate\n  /**\n   * Parsed WWW-Authenticate header from the response.\n   * Contains authentication scheme parameters (e.g., Bearer realm, DPoP nonce).\n   */\n  get wwwAuthenticate(): WWWAuthenticate {\n    return (this.#wwwAuthenticateCached ??=\n      parseWWWAuthenticateHeader(\n        this.response.headers.get('www-authenticate'),\n      ) ?? {})\n  }\n\n  override toDownstreamError(): DownstreamError {\n    return {\n      status: 401,\n      headers: stripHopByHopHeaders(this.headers),\n      body: this.toJSON(),\n    }\n  }\n}\n\n/**\n * Error class for invalid or unprocessable XRPC responses from upstream servers.\n *\n * This occurs when the server returns a response that doesn't conform to the\n * XRPC protocol, such as:\n * - Missing or invalid Content-Type header\n * - Response body that doesn't match the method's output schema\n * - Non-JSON error responses\n * - Responses from non-XRPC endpoints\n *\n * The error code is always 'UpstreamFailure' and maps to HTTP 502 Bad Gateway\n * when converted to a response.\n *\n * @typeParam M - The XRPC method type\n */\nexport class XrpcUpstreamError<\n  M extends Procedure | Query = Procedure | Query,\n> extends XrpcError<M, 'UpstreamFailure', XrpcUpstreamError<M>> {\n  name = 'XrpcUpstreamError'\n\n  constructor(\n    method: M,\n    readonly response: Response,\n    readonly payload: XrpcResponsePayload | null = null,\n    message: string = `Unexpected upstream XRPC response`,\n    options?: ErrorOptions,\n  ) {\n    super(method, 'UpstreamFailure', message, options)\n  }\n\n  override get reason(): this {\n    return this\n  }\n\n  override shouldRetry(): boolean {\n    return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)\n  }\n\n  override toDownstreamError(): DownstreamError {\n    return { status: 502, body: this.toJSON() }\n  }\n}\n\n/**\n * Error class for invalid XRPC responses that fail schema validation.\n *\n * This is a specific type of {@link XrpcUpstreamError} that indicates the\n * upstream server returned a response that was structurally valid but did not\n * conform to the expected schema for the method. This likely indicates a\n * mismatch between client and server versions or an issue with the server's\n * XRPC implementation.\n *\n * @typeParam M - The XRPC method type\n */\nexport class XrpcInvalidResponseError<\n  M extends Procedure | Query = Procedure | Query,\n> extends XrpcUpstreamError<M> {\n  name = 'XrpcInvalidResponseError'\n\n  constructor(\n    method: M,\n    response: Response,\n    payload: XrpcResponsePayload,\n    readonly cause: LexValidationError,\n  ) {\n    super(method, response, payload, `Invalid response: ${cause.message}`, {\n      cause,\n    })\n  }\n\n  override toDownstreamError(): DownstreamError {\n    // @NOTE This could be reflected as both a 500 (\"we\" are at fault) and 502\n    // (\"they\" are at fault). We are using 502 here to allow downstream clients\n    // to determine that the issue lies at the interface between us and the\n    // upstream server, rather than an issue with our internal processing.\n    return { status: 502, body: this.toJSON() }\n  }\n}\n\n/**\n * Error class for internal/client-side errors during XRPC requests.\n *\n * This represents errors that occur before or during the request that are not\n * server responses, such as:\n * - Network errors (connection refused, DNS failure)\n * - Request timeouts\n * - Request aborted via AbortSignal\n * - Invalid request construction\n *\n * The error code is always 'InternalServerError' and these errors are\n * optimistically considered retryable.\n *\n * @typeParam M - The XRPC method type\n */\nexport class XrpcInternalError<\n  M extends Procedure | Query = Procedure | Query,\n> extends XrpcError<M, 'InternalServerError', XrpcInternalError<M>> {\n  name = 'XrpcInternalError'\n\n  constructor(method: M, message?: string, options?: ErrorOptions) {\n    super(\n      method,\n      'InternalServerError',\n      message ?? 'Unable to fulfill XRPC request',\n      options,\n    )\n  }\n\n  override get reason(): this {\n    return this\n  }\n\n  override shouldRetry(): true {\n    // Ideally, we would inspect the reason to determine if it's retryable\n    // (by detecting network errors, timeouts, etc.). Since these cases are\n    // highly platform-dependent, we optimistically assume all internal\n    // errors are retryable.\n    return true\n  }\n\n  override toJSON(): LexErrorData<'InternalServerError'> {\n    // @NOTE Do not expose internal error details to downstream clients\n    return { error: this.error, message: 'Internal Server Error' }\n  }\n\n  override toDownstreamError(): DownstreamError {\n    return { status: 500, body: this.toJSON() }\n  }\n}\n\n/**\n * Union type of all possible XRPC failure types.\n *\n * Used as the return type for safe/non-throwing XRPC methods. Check the\n * `success` property to distinguish between success and failure:\n *\n * @typeParam M - The XRPC method type\n *\n * @example\n * ```typescript\n * const result = await client.xrpcSafe(someMethod, options)\n * if (result.success) {\n *   console.log(result.body) // XrpcResponse\n * } else {\n *   // result is XrpcFailure (XrpcResponseError | XrpcUpstreamError | XrpcInternalError)\n *   console.error(result.error, result.message)\n * }\n * ```\n */\nexport type XrpcFailure<M extends Procedure | Query = Procedure | Query> =\n  // The server returned a valid XRPC error response\n  | XrpcResponseError<M>\n  // The response was not a valid XRPC response, or it does not match the schema\n  | XrpcUpstreamError<M>\n  // Something went wrong (network error, etc.)\n  | XrpcInternalError<M>\n\n/**\n * Converts an unknown error into an appropriate {@link XrpcFailure} type.\n *\n * If the error is already an XrpcFailure for the given method, returns it as-is.\n * Otherwise, wraps it in an {@link XrpcInternalError}.\n *\n * @param method - The XRPC method that was called\n * @param cause - The error to convert\n * @returns An XrpcFailure instance\n *\n * @example\n * ```typescript\n * try {\n *   const response = await fetch(...)\n *   // ... process response\n * } catch (err) {\n *   return asXrpcFailure(method, err)\n * }\n * ```\n */\nexport function asXrpcFailure<M extends Procedure | Query>(\n  method: M,\n  cause: unknown,\n): XrpcFailure<M> {\n  if (\n    cause instanceof XrpcResponseError ||\n    cause instanceof XrpcUpstreamError ||\n    cause instanceof XrpcInternalError\n  ) {\n    if (cause.method === method) return cause\n  }\n\n  return new XrpcInternalError(method, undefined, { cause })\n}\n\nconst HOP_BY_HOP_HEADERS = new Set([\n  'connection',\n  'keep-alive',\n  'proxy-authenticate',\n  'proxy-authorization',\n  'te',\n  'trailer',\n  'transfer-encoding',\n  'upgrade',\n])\n\nfunction stripHopByHopHeaders(headers: Headers): Headers {\n  const result = new Headers(headers)\n\n  // Remove statically known hop-by-hop headers\n  for (const name of HOP_BY_HOP_HEADERS) {\n    result.delete(name)\n  }\n\n  // Remove headers listed in the \"Connection\" header\n  const connection = headers.get('connection')\n  if (connection) {\n    for (const name of connection.split(',')) {\n      result.delete(name.trim())\n    }\n  }\n\n  // These are not actually hop-by-hop headers, but we remove them because the\n  // upstream payload gets parsed and re-serialized, so content length and\n  // encoding may no longer be accurate.\n  result.delete('content-length')\n  result.delete('content-encoding')\n\n  return result\n}\n"]}

package/dist/response.d.ts

@@ -36,7 +36,7 @@ export declare class XrpcResponse<M extends Procedure | Query> implements Result
     get body(): XrpcResponseBody<M>;
     /**
      * @throws {XrpcResponseError} in case of (valid) XRPC error responses. Use
-     * {@link XrpcResponseError.matchesSchema} to narrow the error type based on
+     * {@link XrpcResponseError.matchesSchemaErrors} to narrow the error type based on
      * the method's declared error schema. This can be narrowed further as a
      * {@link XrpcAuthenticationError} if the error is an authentication error.
      * @throws {XrpcUpstreamError} when the response is not a valid XRPC

package/dist/response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AACA,OAAO,EACL,yBAAyB,EACzB,SAAS,EACT,KAAK,EACL,aAAa,EACd,MAAM,qBAAqB,CAAA;AAO5B,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAKjE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAA;AAErD;;;;GAIG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,SAAS,GAAG,KAAK,CACnD,YAAW,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAWvC,QAAQ,CAAC,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO;IACzB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAZ1C,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAG,IAAI,CAAS;IAEhC,uCAAuC;IACvC,IAAI,KAAK,IAAI,IAAI,CAEhB;gBAGU,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAG1C;;;OAGG;IACH,IAAI,QAAQ,YAEX;IAED;;;OAGG;IACH,IAAI,QAAQ,IACuB,yBAAyB,CAAC,CAAC,CAAC,CAC9D;IAED;;;;;;OAMG;IACH,IAAI,IAAI,IACuB,gBAAgB,CAAC,CAAC,CAAC,CACjD;IAED;;;;;;;OAOG;WACU,iBAAiB,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,GAAG,KAAK,EAC9D,MAAM,EAAE,CAAC,EACT,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAE,GACvC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CAoG5B"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AACA,OAAO,EACL,yBAAyB,EACzB,SAAS,EACT,KAAK,EACL,aAAa,EACd,MAAM,qBAAqB,CAAA;AAQ5B,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAKjE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAA;AAErD;;;;GAIG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,SAAS,GAAG,KAAK,CACnD,YAAW,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAWvC,QAAQ,CAAC,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO;IACzB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAZ1C,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAG,IAAI,CAAS;IAEhC,uCAAuC;IACvC,IAAI,KAAK,IAAI,IAAI,CAEhB;gBAGU,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAG1C;;;OAGG;IACH,IAAI,QAAQ,YAEX;IAED;;;OAGG;IACH,IAAI,QAAQ,IACuB,yBAAyB,CAAC,CAAC,CAAC,CAC9D;IAED;;;;;;OAMG;IACH,IAAI,IAAI,IACuB,gBAAgB,CAAC,CAAC,CAAC,CACjD;IAED;;;;;;;OAOG;WACU,iBAAiB,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,GAAG,KAAK,EAC9D,MAAM,EAAE,CAAC,EACT,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAE,GACvC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CAmG5B"}

package/dist/response.js

@@ -53,7 +53,7 @@ class XrpcResponse {
     }
     /**
      * @throws {XrpcResponseError} in case of (valid) XRPC error responses. Use
-     * {@link XrpcResponseError.matchesSchema} to narrow the error type based on
+     * {@link XrpcResponseError.matchesSchemaErrors} to narrow the error type based on
      * the method's declared error schema. This can be narrowed further as a
      * {@link XrpcAuthenticationError} if the error is an authentication error.
      * @throws {XrpcUpstreamError} when the response is not a valid XRPC
@@ -106,7 +106,7 @@ class XrpcResponse {
             if (method.output.schema && options?.validateResponse !== false) {
                 const result = method.output.schema.safeParse(payload.body);
                 if (!result.success) {
-                    throw new errors_js_1.XrpcUpstreamError(method, response, payload, `Response validation failed: ${result.reason.message}`, { cause: result.reason });
+                    throw new errors_js_1.XrpcInvalidResponseError(method, response, payload, result.reason);
                 }
             }
         }

package/dist/response.js.map

@@ -1 +1 @@
-{"version":3,"file":"response.js","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"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","sourcesContent":["import { lexParse } from '@atproto/lex-json'\nimport {\n  InferMethodOutputEncoding,\n  Procedure,\n  Query,\n  ResultSuccess,\n} from '@atproto/lex-schema'\nimport {\n  XrpcAuthenticationError,\n  XrpcResponseError,\n  XrpcUpstreamError,\n  isXrpcErrorPayload,\n} from './errors.js'\nimport { XrpcResponseBody, XrpcResponsePayload } from './util.js'\n\nconst CONTENT_TYPE_BINARY = 'application/octet-stream'\nconst CONTENT_TYPE_JSON = 'application/json'\n\nexport type { XrpcResponseBody, XrpcResponsePayload }\n\n/**\n * Small container for XRPC response data.\n *\n * @implements {ResultSuccess<XrpcResponse<M>>} for convenience in result handling contexts.\n */\nexport class XrpcResponse<M extends Procedure | Query>\n  implements ResultSuccess<XrpcResponse<M>>\n{\n  /** @see {@link ResultSuccess.success} */\n  readonly success = true as const\n\n  /** @see {@link ResultSuccess.value} */\n  get value(): this {\n    return this\n  }\n\n  constructor(\n    readonly method: M,\n    readonly status: number,\n    readonly headers: Headers,\n    readonly payload: XrpcResponsePayload<M>,\n  ) {}\n\n  /**\n   * Whether the response payload was parsed as {@link LexValue} (`true`) or is\n   * in binary form {@link Uint8Array} (`false`).\n   */\n  get isParsed() {\n    return this.method.output.encoding === CONTENT_TYPE_JSON\n  }\n\n  /**\n   * The Content-Type encoding of the response (e.g., 'application/json').\n   * Returns `undefined` if the response has no body.\n   */\n  get encoding() {\n    return this.payload?.encoding as InferMethodOutputEncoding<M>\n  }\n\n  /**\n   * The parsed response body.\n   *\n   * For 'application/json' responses, this is the parsed and validated LexValue.\n   * For binary responses, this is a Uint8Array.\n   * Returns `undefined` if the response has no body.\n   */\n  get body() {\n    return this.payload?.body as XrpcResponseBody<M>\n  }\n\n  /**\n   * @throws {XrpcResponseError} in case of (valid) XRPC error responses. Use\n   * {@link XrpcResponseError.matchesSchema} to narrow the error type based on\n   * the method's declared error schema. This can be narrowed further as a\n   * {@link XrpcAuthenticationError} if the error is an authentication error.\n   * @throws {XrpcUpstreamError} when the response is not a valid XRPC\n   * response, or if the response does not conform to the method's schema.\n   */\n  static async fromFetchResponse<const M extends Procedure | Query>(\n    method: M,\n    response: Response,\n    options?: { validateResponse?: boolean },\n  ): Promise<XrpcResponse<M>> {\n    // @NOTE The body MUST either be read or canceled to avoid resource leaks.\n    // Since nothing should cause an exception before \"readPayload\" is\n    // called, we can safely not use a try/finally here.\n\n    // @NOTE redirect is set to 'follow', so we shouldn't get 3xx responses here\n    if (response.status < 200 || response.status >= 300) {\n      // Always parse json for error responses\n      const payload = await readPayload(response, { parse: true }).catch(\n        (cause) => {\n          throw new XrpcUpstreamError(\n            method,\n            response,\n            null,\n            'Unable to parse response payload',\n            { cause },\n          )\n        },\n      )\n\n      // Properly formatted XRPC error response ?\n      if (response.status >= 400 && isXrpcErrorPayload(payload)) {\n        throw response.status === 401\n          ? new XrpcAuthenticationError<M>(method, response, payload)\n          : new XrpcResponseError<M>(method, response, payload)\n      }\n\n      // Invalid XRPC response (we probably did not hit an XRPC implementation)\n      throw new XrpcUpstreamError(\n        method,\n        response,\n        payload,\n        response.status >= 500\n          ? 'Upstream server encountered an error'\n          : response.status >= 400\n            ? 'Invalid response payload'\n            : 'Invalid response status code',\n      )\n    }\n\n    // Only parse json if the schema expects it\n    const payload = await readPayload(response, {\n      parse: method.output.encoding === CONTENT_TYPE_JSON,\n    }).catch((cause) => {\n      throw new XrpcUpstreamError(\n        method,\n        response,\n        null,\n        'Unable to parse response payload',\n        { cause },\n      )\n    })\n\n    // Response is successful (2xx). Validate payload (data and encoding) against schema.\n    if (method.output.encoding == null) {\n      // Schema expects no payload\n      if (payload) {\n        throw new XrpcUpstreamError(\n          method,\n          response,\n          payload,\n          `Expected response with no body, got ${payload.encoding}`,\n        )\n      }\n    } else {\n      // Schema expects a payload\n      if (!payload || !method.output.matchesEncoding(payload.encoding)) {\n        throw new XrpcUpstreamError(\n          method,\n          response,\n          payload,\n          payload\n            ? `Expected ${method.output.encoding} response, got ${payload.encoding}`\n            : `Expected non-empty response with content-type ${method.output.encoding}`,\n        )\n      }\n\n      // Assert valid response body.\n      if (method.output.schema && options?.validateResponse !== false) {\n        const result = method.output.schema.safeParse(payload.body)\n\n        if (!result.success) {\n          throw new XrpcUpstreamError(\n            method,\n            response,\n            payload,\n            `Response validation failed: ${result.reason.message}`,\n            { cause: result.reason },\n          )\n        }\n      }\n    }\n\n    return new XrpcResponse<M>(\n      method,\n      response.status,\n      response.headers,\n      payload as XrpcResponsePayload<M>,\n    )\n  }\n}\n\n/**\n * @note this function always consumes the response body\n */\nasync function readPayload(\n  response: Response,\n  options?: { parse?: boolean },\n): Promise<XrpcResponsePayload> {\n  // @TODO Should we limit the maximum response size here (this could also be\n  // done by the FetchHandler)?\n\n  const encoding = response.headers\n    .get('content-type')\n    ?.split(';')[0]\n    .trim()\n    .toLowerCase()\n\n  // Response content-type is undefined\n  if (!encoding) {\n    // If the body is empty, return undefined (= no payload)\n    const body = await response.arrayBuffer()\n    if (body.byteLength === 0) return undefined\n\n    // If we got data despite no content-type, treat it as binary\n    return {\n      encoding: CONTENT_TYPE_BINARY,\n      body: new Uint8Array(body),\n    }\n  }\n\n  if (options?.parse && encoding === CONTENT_TYPE_JSON) {\n    // @NOTE It might be worth returning the raw bytes here (Uint8Array) and\n    // perform the lex parsing using cborg/json, allowing to do\n    // bytes->LexValue in one step instead of bytes->text->JSON->LexValue.\n    // This would require adding encode/decode utilities to lex-json (similar\n    // to @ipld/dag-json)\n    const text = await response.text()\n\n    // @NOTE Using `lexParse(text)` (instead of `jsonToLex(json)`) here as\n    // using a reviver function during JSON.parse should be faster than\n    // parsing to JSON then converting to Lex (?)\n\n    // @TODO verify statement above\n    return { encoding, body: lexParse(text) }\n  }\n\n  return { encoding, body: new Uint8Array(await response.arrayBuffer()) }\n}\n"]}
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"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","sourcesContent":["import { lexParse } from '@atproto/lex-json'\nimport {\n  InferMethodOutputEncoding,\n  Procedure,\n  Query,\n  ResultSuccess,\n} from '@atproto/lex-schema'\nimport {\n  XrpcAuthenticationError,\n  XrpcInvalidResponseError,\n  XrpcResponseError,\n  XrpcUpstreamError,\n  isXrpcErrorPayload,\n} from './errors.js'\nimport { XrpcResponseBody, XrpcResponsePayload } from './util.js'\n\nconst CONTENT_TYPE_BINARY = 'application/octet-stream'\nconst CONTENT_TYPE_JSON = 'application/json'\n\nexport type { XrpcResponseBody, XrpcResponsePayload }\n\n/**\n * Small container for XRPC response data.\n *\n * @implements {ResultSuccess<XrpcResponse<M>>} for convenience in result handling contexts.\n */\nexport class XrpcResponse<M extends Procedure | Query>\n  implements ResultSuccess<XrpcResponse<M>>\n{\n  /** @see {@link ResultSuccess.success} */\n  readonly success = true as const\n\n  /** @see {@link ResultSuccess.value} */\n  get value(): this {\n    return this\n  }\n\n  constructor(\n    readonly method: M,\n    readonly status: number,\n    readonly headers: Headers,\n    readonly payload: XrpcResponsePayload<M>,\n  ) {}\n\n  /**\n   * Whether the response payload was parsed as {@link LexValue} (`true`) or is\n   * in binary form {@link Uint8Array} (`false`).\n   */\n  get isParsed() {\n    return this.method.output.encoding === CONTENT_TYPE_JSON\n  }\n\n  /**\n   * The Content-Type encoding of the response (e.g., 'application/json').\n   * Returns `undefined` if the response has no body.\n   */\n  get encoding() {\n    return this.payload?.encoding as InferMethodOutputEncoding<M>\n  }\n\n  /**\n   * The parsed response body.\n   *\n   * For 'application/json' responses, this is the parsed and validated LexValue.\n   * For binary responses, this is a Uint8Array.\n   * Returns `undefined` if the response has no body.\n   */\n  get body() {\n    return this.payload?.body as XrpcResponseBody<M>\n  }\n\n  /**\n   * @throws {XrpcResponseError} in case of (valid) XRPC error responses. Use\n   * {@link XrpcResponseError.matchesSchemaErrors} to narrow the error type based on\n   * the method's declared error schema. This can be narrowed further as a\n   * {@link XrpcAuthenticationError} if the error is an authentication error.\n   * @throws {XrpcUpstreamError} when the response is not a valid XRPC\n   * response, or if the response does not conform to the method's schema.\n   */\n  static async fromFetchResponse<const M extends Procedure | Query>(\n    method: M,\n    response: Response,\n    options?: { validateResponse?: boolean },\n  ): Promise<XrpcResponse<M>> {\n    // @NOTE The body MUST either be read or canceled to avoid resource leaks.\n    // Since nothing should cause an exception before \"readPayload\" is\n    // called, we can safely not use a try/finally here.\n\n    // @NOTE redirect is set to 'follow', so we shouldn't get 3xx responses here\n    if (response.status < 200 || response.status >= 300) {\n      // Always parse json for error responses\n      const payload = await readPayload(response, { parse: true }).catch(\n        (cause) => {\n          throw new XrpcUpstreamError(\n            method,\n            response,\n            null,\n            'Unable to parse response payload',\n            { cause },\n          )\n        },\n      )\n\n      // Properly formatted XRPC error response ?\n      if (response.status >= 400 && isXrpcErrorPayload(payload)) {\n        throw response.status === 401\n          ? new XrpcAuthenticationError<M>(method, response, payload)\n          : new XrpcResponseError<M>(method, response, payload)\n      }\n\n      // Invalid XRPC response (we probably did not hit an XRPC implementation)\n      throw new XrpcUpstreamError(\n        method,\n        response,\n        payload,\n        response.status >= 500\n          ? 'Upstream server encountered an error'\n          : response.status >= 400\n            ? 'Invalid response payload'\n            : 'Invalid response status code',\n      )\n    }\n\n    // Only parse json if the schema expects it\n    const payload = await readPayload(response, {\n      parse: method.output.encoding === CONTENT_TYPE_JSON,\n    }).catch((cause) => {\n      throw new XrpcUpstreamError(\n        method,\n        response,\n        null,\n        'Unable to parse response payload',\n        { cause },\n      )\n    })\n\n    // Response is successful (2xx). Validate payload (data and encoding) against schema.\n    if (method.output.encoding == null) {\n      // Schema expects no payload\n      if (payload) {\n        throw new XrpcUpstreamError(\n          method,\n          response,\n          payload,\n          `Expected response with no body, got ${payload.encoding}`,\n        )\n      }\n    } else {\n      // Schema expects a payload\n      if (!payload || !method.output.matchesEncoding(payload.encoding)) {\n        throw new XrpcUpstreamError(\n          method,\n          response,\n          payload,\n          payload\n            ? `Expected ${method.output.encoding} response, got ${payload.encoding}`\n            : `Expected non-empty response with content-type ${method.output.encoding}`,\n        )\n      }\n\n      // Assert valid response body.\n      if (method.output.schema && options?.validateResponse !== false) {\n        const result = method.output.schema.safeParse(payload.body)\n\n        if (!result.success) {\n          throw new XrpcInvalidResponseError(\n            method,\n            response,\n            payload,\n            result.reason,\n          )\n        }\n      }\n    }\n\n    return new XrpcResponse<M>(\n      method,\n      response.status,\n      response.headers,\n      payload as XrpcResponsePayload<M>,\n    )\n  }\n}\n\n/**\n * @note this function always consumes the response body\n */\nasync function readPayload(\n  response: Response,\n  options?: { parse?: boolean },\n): Promise<XrpcResponsePayload> {\n  // @TODO Should we limit the maximum response size here (this could also be\n  // done by the FetchHandler)?\n\n  const encoding = response.headers\n    .get('content-type')\n    ?.split(';')[0]\n    .trim()\n    .toLowerCase()\n\n  // Response content-type is undefined\n  if (!encoding) {\n    // If the body is empty, return undefined (= no payload)\n    const body = await response.arrayBuffer()\n    if (body.byteLength === 0) return undefined\n\n    // If we got data despite no content-type, treat it as binary\n    return {\n      encoding: CONTENT_TYPE_BINARY,\n      body: new Uint8Array(body),\n    }\n  }\n\n  if (options?.parse && encoding === CONTENT_TYPE_JSON) {\n    // @NOTE It might be worth returning the raw bytes here (Uint8Array) and\n    // perform the lex parsing using cborg/json, allowing to do\n    // bytes->LexValue in one step instead of bytes->text->JSON->LexValue.\n    // This would require adding encode/decode utilities to lex-json (similar\n    // to @ipld/dag-json)\n    const text = await response.text()\n\n    // @NOTE Using `lexParse(text)` (instead of `jsonToLex(json)`) here as\n    // using a reviver function during JSON.parse should be faster than\n    // parsing to JSON then converting to Lex (?)\n\n    // @TODO verify statement above\n    return { encoding, body: lexParse(text) }\n  }\n\n  return { encoding, body: new Uint8Array(await response.arrayBuffer()) }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-client",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "license": "MIT",
   "description": "HTTP client for interacting with Lexicon based APIs",
   "keywords": [
@@ -37,14 +37,14 @@
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@atproto/lex-data": "^0.0.12",
-    "@atproto/lex-json": "^0.0.12",
-    "@atproto/lex-schema": "^0.0.13"
+    "@atproto/lex-data": "^0.0.13",
+    "@atproto/lex-json": "^0.0.13",
+    "@atproto/lex-schema": "^0.0.14"
   },
   "devDependencies": {
     "vitest": "^4.0.16",
-    "@atproto/lex-cbor": "^0.0.13",
-    "@atproto/lex-builder": "^0.0.16"
+    "@atproto/lex-cbor": "^0.0.14",
+    "@atproto/lex-builder": "^0.0.17"
   },
   "scripts": {
     "prebuild": "node ./scripts/lex-build.mjs",

package/src/client.ts

@@ -1,4 +1,4 @@
-import { LexError, LexMap, LexValue, TypedLexMap } from '@atproto/lex-data'
+import { LexMap, LexValue, TypedLexMap } from '@atproto/lex-data'
 import {
   AtIdentifierString,
   CidString,
@@ -331,7 +331,7 @@ export class Client implements Agent {
 
   /**
    * The DID of the authenticated user.
-   * @throws {LexError} with code 'AuthenticationRequired' if not authenticated
+   * @throws {Error} if not authenticated
    */
   get assertDid(): DidString {
     this.assertAuthenticated()
@@ -342,7 +342,7 @@ export class Client implements Agent {
    * Asserts that the client is authenticated.
    * Use as a type guard when you need to ensure authentication.
    *
-   * @throws {LexError} with code 'AuthenticationRequired' if not authenticated
+   * @throws {Error} if not authenticated
    *
    * @example
    * ```typescript
@@ -352,7 +352,7 @@ export class Client implements Agent {
    * ```
    */
   public assertAuthenticated(): asserts this is { did: DidString } {
-    if (!this.did) throw new LexError('AuthenticationRequired')
+    if (!this.did) throw new Error('Client is not authenticated')
   }
 
   /**

package/src/errors.test.ts

@@ -0,0 +1,346 @@
+import { describe, expect, it } from 'vitest'
+import { IssueInvalidType, LexValidationError, l } from '@atproto/lex-schema'
+import {
+  XrpcAuthenticationError,
+  XrpcInternalError,
+  XrpcInvalidResponseError,
+  XrpcResponseError,
+  XrpcUpstreamError,
+  asXrpcFailure,
+} from './errors.js'
+
+// Minimal method fixture
+const testQuery = l.query(
+  'io.example.test',
+  l.params(),
+  l.payload('application/json', l.object({ value: l.string() })),
+  ['TestError', 'AnotherError'],
+)
+
+const testQueryNoErrors = l.query(
+  'io.example.noErrors',
+  l.params(),
+  l.payload('application/json', l.object({ value: l.string() })),
+)
+
+// ============================================================================
+// XrpcResponseError
+// ============================================================================
+
+describe(XrpcResponseError, () => {
+  function createResponseError(
+    status: number,
+    errorCode: string,
+    message?: string,
+  ) {
+    const response = new Response(null, { status })
+    return new XrpcResponseError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: errorCode, message },
+    })
+  }
+
+  it('exposes status from the response', () => {
+    const err = createResponseError(404, 'NotFound')
+    expect(err.status).toBe(404)
+  })
+
+  it('exposes headers from the response', () => {
+    const response = new Response(null, {
+      status: 400,
+      headers: { 'X-Test': 'value' },
+    })
+    const err = new XrpcResponseError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'TestError' },
+    })
+    expect(err.headers.get('X-Test')).toBe('value')
+  })
+
+  it('exposes body from the payload', () => {
+    const err = createResponseError(400, 'TestError', 'details')
+    expect(err.body).toEqual({ error: 'TestError', message: 'details' })
+  })
+
+  describe('toDownstreamError', () => {
+    it('returns 502 for 5xx upstream errors', () => {
+      const err = createResponseError(
+        500,
+        'InternalServerError',
+        'Upstream crashed',
+      )
+      const downstream = err.toDownstreamError()
+
+      expect(downstream.status).toBe(502)
+      expect(downstream.body).toEqual({
+        error: 'InternalServerError',
+        message: 'Upstream crashed',
+      })
+    })
+
+    it('preserves original status for 4xx errors', () => {
+      const err = createResponseError(404, 'NotFound', 'Record not found')
+      const downstream = err.toDownstreamError()
+
+      expect(downstream.status).toBe(404)
+      expect(downstream.body).toEqual({
+        error: 'NotFound',
+        message: 'Record not found',
+      })
+    })
+  })
+
+  describe('toJSON', () => {
+    it('returns the payload body', () => {
+      const err = createResponseError(400, 'TestError', 'message')
+      expect(err.toJSON()).toEqual({ error: 'TestError', message: 'message' })
+    })
+  })
+
+  describe('matchesSchemaErrors', () => {
+    it('returns true when error matches method declared errors', () => {
+      const err = createResponseError(400, 'TestError')
+      expect(err.matchesSchemaErrors()).toBe(true)
+    })
+
+    it('returns false for undeclared error codes', () => {
+      const err = createResponseError(400, 'UnknownError')
+      expect(err.matchesSchemaErrors()).toBe(false)
+    })
+
+    it('returns false when method has no declared errors', () => {
+      const response = new Response(null, { status: 400 })
+      const err = new XrpcResponseError(testQueryNoErrors, response, {
+        encoding: 'application/json',
+        body: { error: 'SomeError' },
+      })
+      expect(err.matchesSchemaErrors()).toBe(false)
+    })
+  })
+
+  describe('shouldRetry', () => {
+    it('returns true for retryable status codes', () => {
+      expect(createResponseError(429, 'RateLimit').shouldRetry()).toBe(true)
+      expect(createResponseError(500, 'Internal').shouldRetry()).toBe(true)
+      expect(createResponseError(502, 'BadGateway').shouldRetry()).toBe(true)
+      expect(createResponseError(503, 'Unavailable').shouldRetry()).toBe(true)
+    })
+
+    it('returns false for non-retryable status codes', () => {
+      expect(createResponseError(400, 'BadRequest').shouldRetry()).toBe(false)
+      expect(createResponseError(401, 'Unauthorized').shouldRetry()).toBe(false)
+      expect(createResponseError(404, 'NotFound').shouldRetry()).toBe(false)
+    })
+  })
+})
+
+// ============================================================================
+// XrpcAuthenticationError
+// ============================================================================
+
+describe(XrpcAuthenticationError, () => {
+  it('is never retryable', () => {
+    const response = new Response(null, { status: 401 })
+    const err = new XrpcAuthenticationError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'AuthenticationRequired' },
+    })
+    expect(err.shouldRetry()).toBe(false)
+  })
+
+  it('parses WWW-Authenticate header', () => {
+    const response = new Response(null, {
+      status: 401,
+      headers: {
+        'WWW-Authenticate': 'Bearer realm="api", error="InvalidToken"',
+      },
+    })
+    const err = new XrpcAuthenticationError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'AuthenticationRequired' },
+    })
+    expect(err.wwwAuthenticate).toHaveProperty('Bearer')
+  })
+
+  it('returns empty object when no WWW-Authenticate header', () => {
+    const response = new Response(null, { status: 401 })
+    const err = new XrpcAuthenticationError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'AuthenticationRequired' },
+    })
+    expect(err.wwwAuthenticate).toEqual({})
+  })
+
+  it('toDownstreamError always returns 401', () => {
+    const response = new Response(null, { status: 401 })
+    const err = new XrpcAuthenticationError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'AuthenticationRequired', message: 'No token' },
+    })
+    const downstream = err.toDownstreamError()
+
+    expect(downstream.status).toBe(401)
+    expect(downstream.body).toEqual({
+      error: 'AuthenticationRequired',
+      message: 'No token',
+    })
+  })
+})
+
+// ============================================================================
+// XrpcUpstreamError
+// ============================================================================
+
+describe(XrpcUpstreamError, () => {
+  it('has error code UpstreamFailure', () => {
+    const response = new Response(null, { status: 200 })
+    const err = new XrpcUpstreamError(testQuery, response)
+    expect(err.error).toBe('UpstreamFailure')
+  })
+
+  it('toDownstreamError returns 502', () => {
+    const response = new Response(null, { status: 200 })
+    const err = new XrpcUpstreamError(testQuery, response)
+    const downstream = err.toDownstreamError()
+    expect(downstream.status).toBe(502)
+  })
+
+  it('shouldRetry is true for retryable status codes', () => {
+    const response = new Response(null, { status: 502 })
+    const err = new XrpcUpstreamError(testQuery, response)
+    expect(err.shouldRetry()).toBe(true)
+  })
+
+  it('shouldRetry is false for non-retryable status codes', () => {
+    const response = new Response(null, { status: 200 })
+    const err = new XrpcUpstreamError(testQuery, response)
+    expect(err.shouldRetry()).toBe(false)
+  })
+})
+
+// ============================================================================
+// XrpcInvalidResponseError
+// ============================================================================
+
+describe(XrpcInvalidResponseError, () => {
+  it('extends XrpcUpstreamError', () => {
+    const response = new Response(null, { status: 200 })
+    const validationError = new LexValidationError([
+      new IssueInvalidType([], 42, ['string']),
+    ])
+    const err = new XrpcInvalidResponseError(
+      testQuery,
+      response,
+      { encoding: 'application/json', body: { value: 42 } },
+      validationError,
+    )
+
+    expect(err).toBeInstanceOf(XrpcUpstreamError)
+    expect(err.error).toBe('UpstreamFailure')
+    expect(err.cause).toBe(validationError)
+  })
+
+  it('includes validation error message', () => {
+    const validationError = new LexValidationError([
+      new IssueInvalidType([], 42, ['string']),
+    ])
+    const err = new XrpcInvalidResponseError(
+      testQuery,
+      new Response(null, { status: 200 }),
+      { encoding: 'application/json', body: { value: 42 } },
+      validationError,
+    )
+
+    expect(err.message).toContain('Invalid response:')
+    expect(err.message).toContain(validationError.message)
+  })
+
+  it('toDownstreamError returns 502', () => {
+    const validationError = new LexValidationError([
+      new IssueInvalidType([], 42, ['string']),
+    ])
+    const err = new XrpcInvalidResponseError(
+      testQuery,
+      new Response(null, { status: 200 }),
+      { encoding: 'application/json', body: { value: 42 } },
+      validationError,
+    )
+    const downstream = err.toDownstreamError()
+    expect(downstream.status).toBe(502)
+  })
+})
+
+// ============================================================================
+// XrpcInternalError
+// ============================================================================
+
+describe(XrpcInternalError, () => {
+  it('has error code InternalServerError', () => {
+    const err = new XrpcInternalError(testQuery)
+    expect(err.error).toBe('InternalServerError')
+  })
+
+  it('is always retryable', () => {
+    const err = new XrpcInternalError(testQuery)
+    expect(err.shouldRetry()).toBe(true)
+  })
+
+  it('toJSON does not expose internal details', () => {
+    const err = new XrpcInternalError(
+      testQuery,
+      'Secret database connection string leaked',
+    )
+    const json = err.toJSON()
+
+    expect(json.error).toBe('InternalServerError')
+    expect(json.message).toBe('Internal Server Error')
+    expect(json.message).not.toContain('Secret')
+  })
+
+  it('toDownstreamError returns 500', () => {
+    const err = new XrpcInternalError(testQuery, 'internal details')
+    const downstream = err.toDownstreamError()
+
+    expect(downstream.status).toBe(500)
+    expect(downstream.body.error).toBe('InternalServerError')
+    expect(downstream.body.message).toBe('Internal Server Error')
+  })
+})
+
+// ============================================================================
+// asXrpcFailure
+// ============================================================================
+
+describe('asXrpcFailure', () => {
+  it('returns existing XrpcResponseError for the same method', () => {
+    const response = new Response(null, { status: 400 })
+    const err = new XrpcResponseError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'TestError' },
+    })
+    expect(asXrpcFailure(testQuery, err)).toBe(err)
+  })
+
+  it('wraps unknown errors in XrpcInternalError', () => {
+    const err = new TypeError('fetch failed')
+    const failure = asXrpcFailure(testQuery, err)
+
+    expect(failure).toBeInstanceOf(XrpcInternalError)
+    expect(failure.cause).toBe(err)
+  })
+
+  it('wraps XrpcError for a different method in XrpcInternalError', () => {
+    const otherQuery = l.query(
+      'io.example.other',
+      l.params(),
+      l.payload('application/json', l.object({ value: l.string() })),
+    )
+    const response = new Response(null, { status: 400 })
+    const err = new XrpcResponseError(otherQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'TestError' },
+    })
+    const failure = asXrpcFailure(testQuery, err)
+    expect(failure).toBeInstanceOf(XrpcInternalError)
+  })
+})