@atproto/lex-client 0.0.10 → 0.0.12

package/dist/errors.d.ts

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

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