@atproto/lex-client 0.0.16 → 0.0.18

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -1,12 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XrpcFetchError = exports.XrpcInternalError = exports.XrpcInvalidResponseError = exports.XrpcUpstreamError = exports.XrpcAuthenticationError = exports.XrpcResponseError = exports.XrpcError = exports.LexError = exports.RETRYABLE_HTTP_STATUS_CODES = void 0;
+exports.XrpcFetchError = exports.XrpcInternalError = exports.XrpcResponseValidationError = exports.XrpcInvalidResponseError = exports.XrpcAuthenticationError = exports.XrpcResponseError = exports.XrpcError = exports.LexError = exports.RETRYABLE_HTTP_STATUS_CODES = void 0;
 exports.isXrpcErrorPayload = isXrpcErrorPayload;
 exports.asXrpcFailure = asXrpcFailure;
 const lex_data_1 = require("@atproto/lex-data");
 Object.defineProperty(exports, "LexError", { enumerable: true, get: function () { return lex_data_1.LexError; } });
 const lex_schema_1 = require("@atproto/lex-schema");
 const www_authenticate_js_1 = require("./www-authenticate.js");
+/**
+ * Mapping that allows generating an XRPC error code from an HTTP status code
+ * when the response does not contain a valid XRPC error payload. This is used
+ * to convert non-XRPC error responses from upstream servers into a standardized
+ * XRPC error for downstream clients.
+ */
+const StatusErrorCodes = new Map([
+    [400, 'InvalidRequest'],
+    [401, 'AuthenticationRequired'],
+    [403, 'Forbidden'],
+    [404, 'XRPCNotSupported'],
+    [406, 'NotAcceptable'],
+    [413, 'PayloadTooLarge'],
+    [415, 'UnsupportedMediaType'],
+    [429, 'RateLimitExceeded'],
+    [500, 'InternalServerError'],
+    [501, 'MethodNotImplemented'],
+    [502, 'UpstreamFailure'],
+    [503, 'NotEnoughResources'],
+    [504, 'UpstreamTimeout'],
+]);
 /**
  * HTTP status codes that indicate a transient error that may succeed on retry.
  *
@@ -52,7 +73,7 @@ function isXrpcErrorPayload(payload) {
  * @typeParam TReason - The reason type for ResultFailure
  *
  * @see {@link XrpcResponseError} - For valid XRPC error responses
- * @see {@link XrpcUpstreamError} - For invalid/unexpected responses
+ * @see {@link XrpcInvalidResponseError} - For invalid/unexpected responses
  * @see {@link XrpcInternalError} - For network/internal errors
  */
 class XrpcError extends lex_data_1.LexError {
@@ -100,7 +121,13 @@ class XrpcResponseError extends XrpcError {
     payload;
     name = 'XrpcResponseError';
     constructor(method, response, payload, options) {
-        const { error, message } = payload.body;
+        const { error, message } = isXrpcErrorPayload(payload)
+            ? payload.body
+            : {
+                error: StatusErrorCodes.get(response.status) ??
+                    (response.status >= 500 ? 'UpstreamFailure' : 'InvalidRequest'),
+                message: buildResponseOverviewMessage(response),
+            };
         super(method, error, message, options);
         this.response = response;
         this.payload = payload;
@@ -112,17 +139,24 @@ class XrpcResponseError extends XrpcError {
         return exports.RETRYABLE_HTTP_STATUS_CODES.has(this.response.status);
     }
     toJSON() {
-        return this.payload.body;
+        // Return the original error payload if it's a valid XRPC error, otherwise
+        // convert to an XRPC error format.
+        const { payload } = this;
+        if (isXrpcErrorPayload(payload)) {
+            return payload.body;
+        }
+        return super.toJSON();
     }
     toDownstreamError() {
-        // If the upstream server returned a 5xx error, we want to return a 502 Bad
+        const { status, headers } = this.response;
+        // If the upstream server returned a 500 error, we want to return a 502 Bad
         // Gateway to downstream clients, as the issue is with the upstream server,
         // not us. We still return the original error code and message in the body
         // for transparency, but we do not want to expose internal server errors
         // from the upstream server as-is to downstream clients.
         return {
-            status: this.response.status === 500 ? 502 : this.status,
-            headers: stripHopByHopHeaders(this.headers),
+            status: status === 500 ? 502 : status,
+            headers: stripHopByHopHeaders(headers),
             body: this.toJSON(),
         };
     }
@@ -133,7 +167,7 @@ class XrpcResponseError extends XrpcError {
         return this.response.headers;
     }
     get body() {
-        return this.payload.body;
+        return this.payload?.body;
     }
 }
 exports.XrpcResponseError = XrpcResponseError;
@@ -177,13 +211,6 @@ class XrpcAuthenticationError extends XrpcResponseError {
         return (this.#wwwAuthenticateCached ??=
             (0, www_authenticate_js_1.parseWWWAuthenticateHeader)(this.response.headers.get('www-authenticate')) ?? {});
     }
-    toDownstreamError() {
-        return {
-            status: 401,
-            headers: stripHopByHopHeaders(this.headers),
-            body: this.toJSON(),
-        };
-    }
 }
 exports.XrpcAuthenticationError = XrpcAuthenticationError;
 /**
@@ -196,17 +223,18 @@ exports.XrpcAuthenticationError = XrpcAuthenticationError;
  * - 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.
+ * The error code is always 'InvalidResponse' and maps to HTTP 502 Bad Gateway
+ * when converted to a response. This should allow downstream clients to
+ * determine at which boundary the error occurred.
  *
  * @typeParam M - The XRPC method type
  */
-class XrpcUpstreamError extends XrpcError {
+class XrpcInvalidResponseError extends XrpcError {
     response;
     payload;
-    name = 'XrpcUpstreamError';
-    constructor(method, response, payload = null, message = `Unexpected upstream XRPC response`, options) {
-        super(method, 'UpstreamFailure', message, options);
+    name = 'XrpcInvalidResponseError';
+    constructor(method, response, payload, message = buildResponseOverviewMessage(response), options) {
+        super(method, 'InvalidResponse', message, options);
         this.response = response;
         this.payload = payload;
     }
@@ -220,11 +248,11 @@ class XrpcUpstreamError extends XrpcError {
         return { status: 502, body: this.toJSON() };
     }
 }
-exports.XrpcUpstreamError = XrpcUpstreamError;
+exports.XrpcInvalidResponseError = XrpcInvalidResponseError;
 /**
  * Error class for invalid XRPC responses that fail schema validation.
  *
- * This is a specific type of {@link XrpcUpstreamError} that indicates the
+ * This is a specific type of {@link XrpcInvalidResponseError} that indicates the
  * upstream server returned a response that was structurally valid but did not
  * conform to the expected schema for the method. This likely indicates a
  * mismatch between client and server versions or an issue with the server's
@@ -232,24 +260,15 @@ exports.XrpcUpstreamError = XrpcUpstreamError;
  *
  * @typeParam M - The XRPC method type
  */
-class XrpcInvalidResponseError extends XrpcUpstreamError {
+class XrpcResponseValidationError extends XrpcInvalidResponseError {
     cause;
-    name = 'XrpcInvalidResponseError';
+    name = 'XrpcResponseValidationError';
     constructor(method, response, payload, cause) {
-        super(method, response, payload, `Invalid response: ${cause.message}`, {
-            cause,
-        });
+        super(method, response, payload, `Invalid response payload: ${cause.message}`, { cause });
         this.cause = cause;
     }
-    toDownstreamError() {
-        // @NOTE This could be reflected as both a 500 ("we" are at fault) and 502
-        // ("they" are at fault). We are using 502 here to allow downstream clients
-        // to determine that the issue lies at the interface between us and the
-        // upstream server, rather than an issue with our internal processing.
-        return { status: 502, body: this.toJSON() };
-    }
 }
-exports.XrpcInvalidResponseError = XrpcInvalidResponseError;
+exports.XrpcResponseValidationError = XrpcResponseValidationError;
 /**
  * Error class for unexpected internal/client-side errors during XRPC requests.
  *
@@ -338,7 +357,7 @@ exports.XrpcFetchError = XrpcFetchError;
  */
 function asXrpcFailure(method, cause) {
     if (cause instanceof XrpcResponseError ||
-        cause instanceof XrpcUpstreamError ||
+        cause instanceof XrpcInvalidResponseError ||
         cause instanceof XrpcInternalError) {
         if (cause.method === method)
             return cause;
@@ -375,4 +394,10 @@ function stripHopByHopHeaders(headers) {
     result.delete('content-encoding');
     return result;
 }
+function buildResponseOverviewMessage(response) {
+    if (response.status < 400) {
+        return `Upstream server responded with an invalid status code (${response.status})`;
+    }
+    return `Upstream server responded with a ${response.status} error`;
+}
 //# sourceMappingURL=errors.js.map

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  LexValidationError,\n  Procedure,\n  Query,\n  ResultFailure,\n  lexErrorDataSchema,\n} from '@atproto/lex-schema'\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport { Agent } from './agent.js'\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 unexpected internal/client-side errors during XRPC requests.\n *\n * The error code is always 'InternalServerError' and these errors not\n * considered retryable as they stem from unforeseen issues in the\n * implementation.\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(): boolean {\n    return false\n  }\n\n  override toJSON(): LexErrorData {\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 * Special case of XrpcInternalError that specifically represents errors thrown\n * by {@link Agent.fetchHandler} during the XRPC request. This includes:\n * - Network errors (connection refused, DNS failure)\n * - Request timeouts\n * - Request aborted via AbortSignal\n *\n * These errors are optimistically considered retryable, as many fetch errors\n * are transient and may succeed on retry.\n */\nexport class XrpcFetchError<\n  M extends Procedure | Query = Procedure | Query,\n> extends XrpcInternalError<M> {\n  name = 'XrpcFetchError'\n\n  constructor(method: M, cause: unknown) {\n    const message = cause instanceof Error ? cause.message : String(cause)\n    super(method, `Unexpected fetchHandler() error: ${message}`, { cause })\n  }\n\n  override shouldRetry(): boolean {\n    // Ideally, we would inspect the reason to determine if it's retryable (by\n    // detecting network errors, timeouts, etc.). Since these cases are highly\n    // platform-dependent, we optimistically assume all fetch errors are\n    // transient and retryable.\n    return true\n  }\n\n  override toJSON(): LexErrorData {\n    // @NOTE Do not expose internal error details to downstream clients\n    return { error: this.error, message: 'Failed to perform upstream request' }\n  }\n\n  override toDownstreamError(): DownstreamError {\n    // While it might technically be a 500 error, we use 502 Bad Gateway here to\n    // indicate that the error occurred while communicating with the upstream\n    // server, allowing downstream clients to distinguish between errors in our\n    // internal processing (500) and errors in the upstream server or network\n    // (502).\n    return { status: 502, 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"]}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  LexError,\n  LexErrorCode,\n  LexErrorData,\n  LexValue,\n} from '@atproto/lex-data'\nimport {\n  InferMethodError,\n  LexValidationError,\n  Procedure,\n  Query,\n  ResultFailure,\n  lexErrorDataSchema,\n} from '@atproto/lex-schema'\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport { Agent } from './agent.js'\nimport { XrpcUnknownResponsePayload } from './types.js'\nimport {\n  WWWAuthenticate,\n  parseWWWAuthenticateHeader,\n} from './www-authenticate.js'\n\n/**\n * Mapping that allows generating an XRPC error code from an HTTP status code\n * when the response does not contain a valid XRPC error payload. This is used\n * to convert non-XRPC error responses from upstream servers into a standardized\n * XRPC error for downstream clients.\n */\nconst StatusErrorCodes = new Map<number, LexErrorCode>([\n  [400, 'InvalidRequest'],\n  [401, 'AuthenticationRequired'],\n  [403, 'Forbidden'],\n  [404, 'XRPCNotSupported'],\n  [406, 'NotAcceptable'],\n  [413, 'PayloadTooLarge'],\n  [415, 'UnsupportedMediaType'],\n  [429, 'RateLimitExceeded'],\n  [500, 'InternalServerError'],\n  [501, 'MethodNotImplemented'],\n  [502, 'UpstreamFailure'],\n  [503, 'NotEnoughResources'],\n  [504, 'UpstreamTimeout'],\n])\n\nexport type { XrpcUnknownResponsePayload }\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: XrpcUnknownResponsePayload | 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 XrpcInvalidResponseError} - 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> extends XrpcError<M, LexErrorCode, XrpcResponseError<M>> {\n  name = 'XrpcResponseError'\n\n  constructor(\n    method: M,\n    readonly response: Response,\n    readonly payload?: XrpcUnknownResponsePayload,\n    options?: ErrorOptions,\n  ) {\n    const { error, message } = isXrpcErrorPayload(payload)\n      ? payload.body\n      : {\n          error:\n            StatusErrorCodes.get(response.status) ??\n            (response.status >= 500 ? 'UpstreamFailure' : 'InvalidRequest'),\n          message: buildResponseOverviewMessage(response),\n        }\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    // Return the original error payload if it's a valid XRPC error, otherwise\n    // convert to an XRPC error format.\n    const { payload } = this\n    if (isXrpcErrorPayload(payload)) {\n      return payload.body\n    }\n\n    return super.toJSON()\n  }\n\n  override toDownstreamError(): DownstreamError {\n    const { status, headers } = this.response\n    // If the upstream server returned a 500 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: status === 500 ? 502 : status,\n      headers: stripHopByHopHeaders(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(): undefined | Uint8Array | LexValue {\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> extends XrpcResponseError<M> {\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 'InvalidResponse' and maps to HTTP 502 Bad Gateway\n * when converted to a response. This should allow downstream clients to\n * determine at which boundary the error occurred.\n *\n * @typeParam M - The XRPC method type\n */\nexport class XrpcInvalidResponseError<\n  M extends Procedure | Query = Procedure | Query,\n> extends XrpcError<M, 'InvalidResponse', XrpcInvalidResponseError<M>> {\n  name = 'XrpcInvalidResponseError'\n\n  constructor(\n    method: M,\n    readonly response: Response,\n    readonly payload?: XrpcUnknownResponsePayload,\n    message: string = buildResponseOverviewMessage(response),\n    options?: ErrorOptions,\n  ) {\n    super(method, 'InvalidResponse', 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 XrpcInvalidResponseError} 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 XrpcResponseValidationError<\n  M extends Procedure | Query = Procedure | Query,\n> extends XrpcInvalidResponseError<M> {\n  name = 'XrpcResponseValidationError'\n\n  constructor(\n    method: M,\n    response: Response,\n    payload: XrpcUnknownResponsePayload,\n    readonly cause: LexValidationError,\n  ) {\n    super(\n      method,\n      response,\n      payload,\n      `Invalid response payload: ${cause.message}`,\n      { cause },\n    )\n  }\n}\n\n/**\n * Error class for unexpected internal/client-side errors during XRPC requests.\n *\n * The error code is always 'InternalServerError' and these errors not\n * considered retryable as they stem from unforeseen issues in the\n * implementation.\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(): boolean {\n    return false\n  }\n\n  override toJSON(): LexErrorData {\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 * Special case of XrpcInternalError that specifically represents errors thrown\n * by {@link Agent.fetchHandler} during the XRPC request. This includes:\n * - Network errors (connection refused, DNS failure)\n * - Request timeouts\n * - Request aborted via AbortSignal\n *\n * These errors are optimistically considered retryable, as many fetch errors\n * are transient and may succeed on retry.\n */\nexport class XrpcFetchError<\n  M extends Procedure | Query = Procedure | Query,\n> extends XrpcInternalError<M> {\n  name = 'XrpcFetchError'\n\n  constructor(method: M, cause: unknown) {\n    const message = cause instanceof Error ? cause.message : String(cause)\n    super(method, `Unexpected fetchHandler() error: ${message}`, { cause })\n  }\n\n  override shouldRetry(): boolean {\n    // Ideally, we would inspect the reason to determine if it's retryable (by\n    // detecting network errors, timeouts, etc.). Since these cases are highly\n    // platform-dependent, we optimistically assume all fetch errors are\n    // transient and retryable.\n    return true\n  }\n\n  override toJSON(): LexErrorData {\n    // @NOTE Do not expose internal error details to downstream clients\n    return { error: this.error, message: 'Failed to perform upstream request' }\n  }\n\n  override toDownstreamError(): DownstreamError {\n    // While it might technically be a 500 error, we use 502 Bad Gateway here to\n    // indicate that the error occurred while communicating with the upstream\n    // server, allowing downstream clients to distinguish between errors in our\n    // internal processing (500) and errors in the upstream server or network\n    // (502).\n    return { status: 502, 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 | XrpcInvalidResponseError | 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  | XrpcInvalidResponseError<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 XrpcInvalidResponseError ||\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\nfunction buildResponseOverviewMessage(response: Response): string {\n  if (response.status < 400) {\n    return `Upstream server responded with an invalid status code (${response.status})`\n  }\n\n  return `Upstream server responded with a ${response.status} error`\n}\n"]}

package/dist/response.d.ts

@@ -1,6 +1,66 @@
-import { InferMethodOutputEncoding, Procedure, Query, ResultSuccess } from '@atproto/lex-schema';
-import { XrpcResponseBody, XrpcResponsePayload } from './util.js';
-export type { XrpcResponseBody, XrpcResponsePayload };
+import { InferMethodOutputEncoding, InferOutput, LexValue, Payload, Procedure, Query, ResultSuccess, Validator } from '@atproto/lex-schema';
+import { EncodingString } from './types.js';
+type InferEncodingType<TEncoding extends string> = TEncoding extends '*/*' ? EncodingString : TEncoding extends `${infer T extends string}/*` ? `${T}/${string}` : TEncoding;
+type InferBodyType<TEncoding extends string, TSchema> = TSchema extends Validator ? InferOutput<TSchema> : TEncoding extends `application/json` ? LexValue : Uint8Array;
+/**
+ * The body type of an XRPC response, inferred from the method's output schema.
+ *
+ * For JSON responses, this is the parsed LexValue. For binary responses,
+ * this is a Uint8Array.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ */
+export type XrpcResponseBody<M extends Procedure | Query> = M['output'] extends Payload<infer TEncoding, infer TSchema> ? TEncoding extends string ? InferBodyType<TEncoding, TSchema> : undefined | LexValue | Uint8Array : never;
+/**
+ * The full payload type of an XRPC response, including body and encoding.
+ *
+ * Returns `null` for methods that have no output.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ */
+export type XrpcResponsePayload<M extends Procedure | Query> = M['output'] extends Payload<infer TEncoding, infer TSchema> ? TEncoding extends string ? {
+    encoding: InferEncodingType<TEncoding>;
+    body: InferBodyType<TEncoding, TSchema>;
+} : // If the schema does not specify an output encoding, anything could be
+undefined | {
+    body: LexValue | Uint8Array;
+    encoding: string;
+} : never;
+export type XrpcResponseOptions = {
+    /**
+     * Whether to validate the response against the method's output schema.
+     * Disabling this can improve performance but may lead to runtime errors if
+     * the response does not conform to the expected schema. Only set this to
+     * `false` if you are certain that the upstream service will always return
+     * valid responses.
+     *
+     * @default true
+     */
+    validateResponse?: boolean;
+    /**
+     * Whether to strictly process response payloads according to Lex encoding
+     * rules. By default, the client will reject responses with invalid Lex data
+     * (floats and invalid $bytes / $link objects).
+     *
+     * Setting this option to `false` will allow the client to accept such
+     * responses in a non-strict mode, where invalid Lex data will be returned
+     * as-is (e.g., floats will not be rejected, and invalid $bytes / $link
+     * objects will not be converted to Uint8Array / Cid). When in non-strict
+     * mode, the validation will also be relaxed when validating the response
+     * against the method's output schema, allowing values that do not strictly
+     * conform to the schema (e.g. datetime strings that are not valid RFC3339
+     * format, blobs that are not of the right size/mime-type, etc.) to be
+     * accepted as long as their basic structure is correct.
+     *
+     * When validation is enabled (the default), the values defined through the
+     * method schema will be enforced, ensuring that the client can still process
+     * the response even if the server returns invalid Lex data.
+     *
+     * @default true
+     * @see {@link LexParseOptions.strict}
+     */
+    strictResponseProcessing?: boolean;
+};
 /**
  * Small container for XRPC response data.
  *
@@ -39,11 +99,10 @@ export declare class XrpcResponse<M extends Procedure | Query> implements Result
      * {@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
+     * @throws {XrpcInvalidResponseError} when the response is not a valid XRPC
      * response, or if the response does not conform to the method's schema.
      */
-    static fromFetchResponse<const M extends Procedure | Query>(method: M, response: Response, options?: {
-        validateResponse?: boolean;
-    }): Promise<XrpcResponse<M>>;
+    static fromFetchResponse<const M extends Procedure | Query>(method: M, response: Response, options?: XrpcResponseOptions): Promise<XrpcResponse<M>>;
 }
+export {};
 //# sourceMappingURL=response.d.ts.map

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;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"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"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"}

package/dist/response.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.XrpcResponse = void 0;
 const lex_json_1 = require("@atproto/lex-json");
 const errors_js_1 = require("./errors.js");
+const types_js_1 = require("./types.js");
 const CONTENT_TYPE_BINARY = 'application/octet-stream';
 const CONTENT_TYPE_JSON = 'application/json';
 /**
@@ -56,58 +57,64 @@ class XrpcResponse {
      * {@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
+     * @throws {XrpcInvalidResponseError} when the response is not a valid XRPC
      * response, or if the response does not conform to the method's schema.
      */
     static async fromFetchResponse(method, response, options) {
         // @NOTE The body MUST either be read or canceled to avoid resource leaks.
         // Since nothing should cause an exception before "readPayload" is
         // called, we can safely not use a try/finally here.
-        // @NOTE redirect is set to 'follow', so we shouldn't get 3xx responses here
-        if (response.status < 200 || response.status >= 300) {
-            // Always parse json for error responses
-            const payload = await readPayload(response, { parse: true }).catch((cause) => {
-                throw new errors_js_1.XrpcUpstreamError(method, response, null, 'Unable to parse response payload', { cause });
+        // Always turn 4xx/5xx responses into XrpcResponseError
+        if (response.status >= 400) {
+            const payload = await readPayload(method, response, {
+                // Always parse errors in non-strict mode
+                parse: { strict: false },
             });
-            // Properly formatted XRPC error response ?
-            if (response.status >= 400 && (0, errors_js_1.isXrpcErrorPayload)(payload)) {
-                throw response.status === 401
-                    ? new errors_js_1.XrpcAuthenticationError(method, response, payload)
-                    : new errors_js_1.XrpcResponseError(method, response, payload);
+            if (response.status === 401) {
+                throw new errors_js_1.XrpcAuthenticationError(method, response, payload);
             }
-            // Invalid XRPC response (we probably did not hit an XRPC implementation)
-            throw new errors_js_1.XrpcUpstreamError(method, response, payload, response.status >= 500
-                ? 'Upstream server encountered an error'
-                : response.status >= 400
-                    ? 'Invalid response payload'
-                    : 'Invalid response status code');
+            throw new errors_js_1.XrpcResponseError(method, response, payload);
         }
-        // Only parse json if the schema expects it
-        const payload = await readPayload(response, {
-            parse: method.output.encoding === CONTENT_TYPE_JSON,
-        }).catch((cause) => {
-            throw new errors_js_1.XrpcUpstreamError(method, response, null, 'Unable to parse response payload', { cause });
+        // @NOTE redirect is set to 'follow', so we shouldn't get 3xx responses here
+        if (response.status < 200 || response.status >= 300) {
+            await response.body?.cancel();
+            throw new errors_js_1.XrpcInvalidResponseError(method, response, undefined, `Unexpected status code ${response.status}`);
+        }
+        const payload = await readPayload(method, response, {
+            // Parse response if there is a schema, or if the encoding is
+            // "application/json"
+            parse: method.output.schema || method.output.encoding === CONTENT_TYPE_JSON
+                ? { strict: options?.strictResponseProcessing ?? true }
+                : // If there is no declared output encoding, we'll parse the output (in loose mode)
+                    method.output.encoding == null
+                        ? { strict: false }
+                        : false,
         });
-        // Response is successful (2xx). Validate payload (data and encoding) against schema.
-        if (method.output.encoding == null) {
-            // Schema expects no payload
-            if (payload) {
-                throw new errors_js_1.XrpcUpstreamError(method, response, payload, `Expected response with no body, got ${payload.encoding}`);
-            }
+        if (!method.output.matchesEncoding(payload?.encoding)) {
+            throw new errors_js_1.XrpcInvalidResponseError(method, response, payload, `Expected ${stringifyEncoding(method.output.encoding)} response (got ${stringifyEncoding(payload?.encoding)})`);
         }
-        else {
-            // Schema expects a payload
-            if (!payload || !method.output.matchesEncoding(payload.encoding)) {
-                throw new errors_js_1.XrpcUpstreamError(method, response, payload, payload
-                    ? `Expected ${method.output.encoding} response, got ${payload.encoding}`
-                    : `Expected non-empty response with content-type ${method.output.encoding}`);
-            }
+        // Response is successful (2xx). Validate payload (data and encoding) against schema.
+        if (method.output.encoding != null) {
+            // If the schema specifies an output, verify that the response properly
+            // matches the expected format (encoding and schema, if present). If no
+            // output is specified, any payload could be returned.
+            // Needed for type safety. Should never happen since matchesEncoding()
+            // should return not succeed if there is a schema encoding but no payload.
+            if (!payload)
+                throw new Error('Expected payload');
             // Assert valid response body.
             if (method.output.schema && options?.validateResponse !== false) {
-                const result = method.output.schema.safeParse(payload.body);
+                const result = method.output.schema.safeParse(payload.body, {
+                    strict: options?.strictResponseProcessing ?? true,
+                });
                 if (!result.success) {
-                    throw new errors_js_1.XrpcInvalidResponseError(method, response, payload, result.reason);
+                    throw new errors_js_1.XrpcResponseValidationError(method, response, payload, result.reason);
                 }
+                const parsedPayload = {
+                    body: result.value,
+                    encoding: payload.encoding,
+                };
+                return new XrpcResponse(method, response.status, response.headers, parsedPayload);
             }
         }
         return new XrpcResponse(method, response.status, response.headers, payload);
@@ -117,39 +124,53 @@ exports.XrpcResponse = XrpcResponse;
 /**
  * @note this function always consumes the response body
  */
-async function readPayload(response, options) {
-    // @TODO Should we limit the maximum response size here (this could also be
-    // done by the FetchHandler)?
-    const encoding = response.headers
-        .get('content-type')
-        ?.split(';')[0]
-        .trim()
-        .toLowerCase();
-    // Response content-type is undefined
-    if (!encoding) {
-        // If the body is empty, return undefined (= no payload)
-        const body = await response.arrayBuffer();
-        if (body.byteLength === 0)
-            return undefined;
-        // If we got data despite no content-type, treat it as binary
-        return {
-            encoding: CONTENT_TYPE_BINARY,
-            body: new Uint8Array(body),
-        };
+async function readPayload(method, response, options) {
+    try {
+        // @TODO Should we limit the maximum response size here (this could also be
+        // done by the FetchHandler)?
+        const encoding = response.headers
+            .get('content-type')
+            ?.split(';')[0]
+            .trim()
+            .toLowerCase();
+        // Response content-type is undefined
+        if (!encoding) {
+            // If the body is empty, return undefined (= no payload)
+            const arrayBuffer = await response.arrayBuffer();
+            if (arrayBuffer.byteLength === 0)
+                return undefined;
+            // If we got data despite no content-type, treat it as binary
+            return {
+                encoding: CONTENT_TYPE_BINARY,
+                body: new Uint8Array(arrayBuffer),
+            };
+        }
+        if (!(0, types_js_1.isEncodingString)(encoding)) {
+            throw new TypeError(`Invalid content-type "${encoding}" in response`);
+        }
+        if (options?.parse && encoding === CONTENT_TYPE_JSON) {
+            // @NOTE It might be worth returning the raw bytes here (Uint8Array) and
+            // perform the lex parsing using cborg/json, allowing to do
+            // bytes->LexValue in one step instead of bytes->text->JSON->LexValue.
+            // This would require adding encode/decode utilities to lex-json (similar
+            // to @ipld/dag-json)
+            const text = await response.text();
+            // @NOTE Using `lexParse(text)` (instead of `jsonToLex(json)`) here as
+            // using a reviver function during JSON.parse should be faster than
+            // parsing to JSON then converting to Lex (?)
+            // @TODO verify statement above
+            return { encoding, body: (0, lex_json_1.lexParse)(text, options.parse) };
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return { encoding, body: new Uint8Array(arrayBuffer) };
     }
-    if (options?.parse && encoding === CONTENT_TYPE_JSON) {
-        // @NOTE It might be worth returning the raw bytes here (Uint8Array) and
-        // perform the lex parsing using cborg/json, allowing to do
-        // bytes->LexValue in one step instead of bytes->text->JSON->LexValue.
-        // This would require adding encode/decode utilities to lex-json (similar
-        // to @ipld/dag-json)
-        const text = await response.text();
-        // @NOTE Using `lexParse(text)` (instead of `jsonToLex(json)`) here as
-        // using a reviver function during JSON.parse should be faster than
-        // parsing to JSON then converting to Lex (?)
-        // @TODO verify statement above
-        return { encoding, body: (0, lex_json_1.lexParse)(text) };
+    catch (cause) {
+        const message = 'Unable to parse response payload';
+        const messageDetail = cause instanceof TypeError ? cause.message : undefined;
+        throw new errors_js_1.XrpcInvalidResponseError(method, response, undefined, messageDetail ? `${message}: ${messageDetail}` : message, { cause });
     }
-    return { encoding, body: new Uint8Array(await response.arrayBuffer()) };
+}
+function stringifyEncoding(encoding) {
+    return encoding ? `"${encoding}"` : 'no payload';
 }
 //# sourceMappingURL=response.js.map