@atproto/lex-client 0.0.11 → 0.0.12

package/src/errors.ts

@@ -6,12 +6,26 @@ import {
   ResultFailure,
   lexErrorDataSchema,
 } from '@atproto/lex-schema'
-import { XrpcPayload } from './util.js'
+import { XrpcResponsePayload } from './util.js'
 import {
   WWWAuthenticate,
   parseWWWAuthenticateHeader,
 } from './www-authenticate.js'
 
+/**
+ * HTTP status codes that indicate a transient error that may succeed on retry.
+ *
+ * Includes:
+ * - 408 Request Timeout
+ * - 425 Too Early
+ * - 429 Too Many Requests (rate limited)
+ * - 500 Internal Server Error
+ * - 502 Bad Gateway
+ * - 503 Service Unavailable
+ * - 504 Gateway Timeout
+ * - 522 Connection Timed Out (Cloudflare)
+ * - 524 A Timeout Occurred (Cloudflare)
+ */
 export const RETRYABLE_HTTP_STATUS_CODES: ReadonlySet<number> = new Set([
   408, 425, 429, 500, 502, 503, 504, 522, 524,
 ])
@@ -19,8 +33,17 @@ export const RETRYABLE_HTTP_STATUS_CODES: ReadonlySet<number> = new Set([
 export { LexError }
 export type { LexErrorCode, LexErrorData }
 
-export type XrpcErrorPayload<N extends LexErrorCode = LexErrorCode> =
-  XrpcPayload<LexErrorData<N>, 'application/json'>
+/**
+ * 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
@@ -35,15 +58,29 @@ export type XrpcErrorPayload<N extends LexErrorCode = LexErrorCode> =
  * This function checks whether a given payload matches this schema.
  */
 export function isXrpcErrorPayload(
-  payload: XrpcPayload | null,
+  payload: XrpcResponsePayload | null | undefined,
 ): payload is XrpcErrorPayload {
   return (
-    payload !== null &&
+    payload != null &&
     payload.encoding === 'application/json' &&
     lexErrorDataSchema.matches(payload.body)
   )
 }
 
+/**
+ * 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
+ */
 export abstract class XrpcError<
     M extends Procedure | Query = Procedure | Query,
     N extends LexErrorCode = LexErrorCode,
@@ -84,8 +121,28 @@ export abstract class XrpcError<
 }
 
 /**
- * Class used to represent an HTTP request that resulted in an XRPC method
- * error. That is, a non-2xx response with a valid XRPC error payload.
+ * Error class for valid XRPC error responses from the server.
+ *
+ * This represents a properly formatted XRPC error where the server returned
+ * a non-2xx status with a valid JSON error payload containing `error` and
+ * optional `message` fields.
+ *
+ * Use {@link matchesSchema} to check if the error matches the method's declared
+ * error types for type-safe error handling.
+ *
+ * @typeParam M - The XRPC method type
+ * @typeParam N - The error code type (inferred from method or generic)
+ *
+ * @example Handling specific errors
+ * ```typescript
+ * try {
+ *   await client.xrpc(someMethod, options)
+ * } catch (err) {
+ *   if (err instanceof XrpcResponseError && err.error === 'RecordNotFound') {
+ *     // Handle not found case
+ *   }
+ * }
+ * ```
  */
 export class XrpcResponseError<
   M extends Procedure | Query = Procedure | Query,
@@ -135,6 +192,33 @@ export class XrpcResponseError<
 }
 
 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 class XrpcAuthenticationError<
   M extends Procedure | Query = Procedure | Query,
   N extends LexErrorCode = LexErrorCode,
@@ -145,9 +229,13 @@ export class XrpcAuthenticationError<
     return false
   }
 
-  #wwwAuthenticate?: WWWAuthenticate
+  #wwwAuthenticateCached?: WWWAuthenticate
+  /**
+   * Parsed WWW-Authenticate header from the response.
+   * Contains authentication scheme parameters (e.g., Bearer realm, DPoP nonce).
+   */
   get wwwAuthenticate(): WWWAuthenticate {
-    return (this.#wwwAuthenticate ??=
+    return (this.#wwwAuthenticateCached ??=
       parseWWWAuthenticateHeader(
         this.response.headers.get('www-authenticate'),
       ) ?? {})
@@ -155,8 +243,19 @@ export class XrpcAuthenticationError<
 }
 
 /**
- * This class represents invalid or unprocessable XRPC response from the
- * upstream server.
+ * Error class for invalid or unprocessable XRPC responses from upstream servers.
+ *
+ * This occurs when the server returns a response that doesn't conform to the
+ * XRPC protocol, such as:
+ * - Missing or invalid Content-Type header
+ * - Response body that doesn't match the method's output schema
+ * - Non-JSON error responses
+ * - Responses from non-XRPC endpoints
+ *
+ * The error code is always 'UpstreamFailure' and maps to HTTP 502 Bad Gateway
+ * when converted to a response.
+ *
+ * @typeParam M - The XRPC method type
  */
 export class XrpcUpstreamError<
   M extends Procedure | Query = Procedure | Query,
@@ -166,7 +265,7 @@ export class XrpcUpstreamError<
   constructor(
     method: M,
     readonly response: Response,
-    readonly payload: XrpcPayload | null,
+    readonly payload: XrpcResponsePayload | null = null,
     message: string = `Unexpected upstream XRPC response`,
     options?: ErrorOptions,
   ) {
@@ -186,6 +285,21 @@ export class XrpcUpstreamError<
   }
 }
 
+/**
+ * Error class for internal/client-side errors during XRPC requests.
+ *
+ * This represents errors that occur before or during the request that are not
+ * server responses, such as:
+ * - Network errors (connection refused, DNS failure)
+ * - Request timeouts
+ * - Request aborted via AbortSignal
+ * - Invalid request construction
+ *
+ * The error code is always 'InternalServerError' and these errors are
+ * optimistically considered retryable.
+ *
+ * @typeParam M - The XRPC method type
+ */
 export class XrpcInternalError<
   M extends Procedure | Query = Procedure | Query,
 > extends XrpcError<M, 'InternalServerError', XrpcInternalError<M>> {
@@ -218,6 +332,25 @@ export class XrpcInternalError<
   }
 }
 
+/**
+ * Union type of all possible XRPC failure types.
+ *
+ * Used as the return type for safe/non-throwing XRPC methods. Check the
+ * `success` property to distinguish between success and failure:
+ *
+ * @typeParam M - The XRPC method type
+ *
+ * @example
+ * ```typescript
+ * const result = await client.xrpcSafe(someMethod, options)
+ * if (result.success) {
+ *   console.log(result.body) // XrpcResponse
+ * } else {
+ *   // result is XrpcFailure (XrpcResponseError | XrpcUpstreamError | XrpcInternalError)
+ *   console.error(result.error, result.message)
+ * }
+ * ```
+ */
 export type XrpcFailure<M extends Procedure | Query = Procedure | Query> =
   // The server returned a valid XRPC error response
   | XrpcResponseError<M>
@@ -226,6 +359,26 @@ export type XrpcFailure<M extends Procedure | Query = Procedure | Query> =
   // Something went wrong (network error, etc.)
   | 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 function asXrpcFailure<M extends Procedure | Query>(
   method: M,
   cause: unknown,

package/src/response.ts

@@ -1,6 +1,5 @@
 import { lexParse } from '@atproto/lex-json'
 import {
-  InferMethodOutputBody,
   InferMethodOutputEncoding,
   Procedure,
   Query,
@@ -12,15 +11,12 @@ import {
   XrpcUpstreamError,
   isXrpcErrorPayload,
 } from './errors.js'
-import { XrpcPayload } from './util.js'
+import { XrpcResponseBody, XrpcResponsePayload } from './util.js'
 
-export type XrpcResponseBody<M extends Procedure | Query> =
-  InferMethodOutputBody<M, Uint8Array>
+const CONTENT_TYPE_BINARY = 'application/octet-stream'
+const CONTENT_TYPE_JSON = 'application/json'
 
-export type XrpcResponsePayload<M extends Procedure | Query> =
-  InferMethodOutputEncoding<M> extends infer E extends string
-    ? XrpcPayload<XrpcResponseBody<M>, E>
-    : null
+export type { XrpcResponseBody, XrpcResponsePayload }
 
 /**
  * Small container for XRPC response data.
@@ -50,13 +46,24 @@ export class XrpcResponse<M extends Procedure | Query>
    * in binary form {@link Uint8Array} (`false`).
    */
   get isParsed() {
-    return this.encoding === 'application/json' && shouldParse(this.method)
+    return this.method.output.encoding === CONTENT_TYPE_JSON
   }
 
+  /**
+   * The Content-Type encoding of the response (e.g., 'application/json').
+   * Returns `undefined` if the response has no body.
+   */
   get encoding() {
     return this.payload?.encoding as InferMethodOutputEncoding<M>
   }
 
+  /**
+   * The parsed response body.
+   *
+   * For 'application/json' responses, this is the parsed and validated LexValue.
+   * For binary responses, this is a Uint8Array.
+   * Returns `undefined` if the response has no body.
+   */
   get body() {
     return this.payload?.body as XrpcResponseBody<M>
   }
@@ -115,7 +122,7 @@ export class XrpcResponse<M extends Procedure | Query>
 
     // Only parse json if the schema expects it
     const payload = await readPayload(response, {
-      parse: shouldParse(method),
+      parse: method.output.encoding === CONTENT_TYPE_JSON,
     }).catch((cause) => {
       throw new XrpcUpstreamError(
         method,
@@ -175,17 +182,13 @@ export class XrpcResponse<M extends Procedure | Query>
   }
 }
 
-function shouldParse(method: Procedure | Query) {
-  return method.output.encoding === 'application/json'
-}
-
 /**
  * @note this function always consumes the response body
  */
 async function readPayload(
   response: Response,
   options?: { parse?: boolean },
-): Promise<XrpcPayload | null> {
+): Promise<XrpcResponsePayload> {
   // @TODO Should we limit the maximum response size here (this could also be
   // done by the FetchHandler)?
 
@@ -197,18 +200,18 @@ async function readPayload(
 
   // Response content-type is undefined
   if (!encoding) {
-    // If the body is empty, return null (= no payload)
+    // If the body is empty, return undefined (= no payload)
     const body = await response.arrayBuffer()
-    if (body.byteLength === 0) return null
+    if (body.byteLength === 0) return undefined
 
     // If we got data despite no content-type, treat it as binary
     return {
-      encoding: 'application/octet-stream',
+      encoding: CONTENT_TYPE_BINARY,
       body: new Uint8Array(body),
     }
   }
 
-  if (options?.parse && encoding === 'application/json') {
+  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.

package/src/types.ts

@@ -2,13 +2,40 @@ import { DidString, UnknownString } from '@atproto/lex-schema'
 
 export type { DidString, UnknownString }
 
+/**
+ * Service identifier fragment for DID service endpoints.
+ *
+ * Common values include 'atproto_labeler' for labeling services,
+ * or custom service identifiers.
+ */
 export type DidServiceIdentifier = 'atproto_labeler' | UnknownString
+
+/**
+ * A full service proxy identifier combining a DID with a service fragment.
+ *
+ * Used to route requests through a specific service endpoint.
+ *
+ * @example
+ * ```typescript
+ * const service: Service = 'did:web:api.bsky.app#bsky_appview'
+ * ```
+ */
 export type Service = `${DidString}#${DidServiceIdentifier}`
 
+/**
+ * Common options available for all XRPC calls.
+ *
+ * These options can be passed to any method that makes XRPC requests,
+ * including `xrpc()`, `call()`, and record operations.
+ */
 export type CallOptions = {
+  /** Labeler DIDs to request labels from for content moderation. */
   labelers?: Iterable<DidString>
+  /** AbortSignal to cancel the request. */
   signal?: AbortSignal
+  /** Additional HTTP headers to include in the request. */
   headers?: HeadersInit
+  /** Service proxy identifier for routing requests through a specific service. */
   service?: Service
 
   /**
@@ -33,6 +60,31 @@ export type CallOptions = {
   validateResponse?: boolean
 }
 
+/**
+ * Valid input types for binary request bodies.
+ *
+ * These types can be used as the body for procedures that expect
+ * non-JSON content (e.g., blob uploads, binary data).
+ *
+ * @example Uploading a blob
+ * ```typescript
+ * const imageData: BinaryBodyInit = new Uint8Array(buffer)
+ * await client.uploadBlob(imageData, { encoding: 'image/png' })
+ * ```
+ *
+ * @example Streaming upload
+ * ```typescript
+ * const stream: BinaryBodyInit = someReadableStream
+ * await client.xrpc(uploadMethod, { body: stream })
+ * ```
+ *
+ * @example File upload in browser
+ * ```typescript
+ * const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement
+ * const file: BinaryBodyInit = fileInput.files[0]
+ * await client.xrpc(uploadMethod, { body: file })
+ * ```
+ */
 export type BinaryBodyInit =
   | Uint8Array
   | ArrayBuffer

package/src/util.ts

@@ -1,10 +1,42 @@
-import { DidString } from '@atproto/lex-schema'
+import {
+  DidString,
+  InferMethodOutput,
+  InferMethodOutputBody,
+  Procedure,
+  Query,
+} from '@atproto/lex-schema'
 
-export type XrpcPayload<B = unknown, E extends string = string> = {
-  body: B
-  encoding: E
-}
+/**
+ * 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 = Procedure | Query> =
+  InferMethodOutputBody<M, Uint8Array>
+
+/**
+ * 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 = Procedure | Query,
+> = InferMethodOutput<M, Uint8Array>
 
+/**
+ * Type guard to check if a value is {@link Blob}-like.
+ *
+ * Handles both native Blobs and polyfilled Blob implementations
+ * (e.g., fetch-blob from node-fetch).
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a Blob or Blob-like object
+ */
 export function isBlobLike(value: unknown): value is Blob {
   if (value == null) return false
   if (typeof value !== 'object') return false
@@ -32,6 +64,19 @@ export function isAsyncIterable<T>(
   )
 }
 
+/**
+ * Builds HTTP headers for AT Protocol requests.
+ *
+ * Adds the following headers when applicable:
+ * - `atproto-proxy`: Service routing header (if service is specified)
+ * - `atproto-accept-labelers`: Comma-separated list of labeler DIDs
+ *
+ * @param options - Header building options
+ * @param options.headers - Base headers to include
+ * @param options.service - Service proxy identifier
+ * @param options.labelers - Labeler DIDs to request labels from
+ * @returns A new Headers object with AT Protocol headers added
+ */
 export function buildAtprotoHeaders(options: {
   headers?: HeadersInit
   service?: `${DidString}#${string}`

package/src/www-authenticate.ts

@@ -1,4 +1,28 @@
 type WWWAuthenticateParams = { [authParam in string]: string }
+
+/**
+ * Parsed representation of a WWW-Authenticate HTTP header.
+ *
+ * Maps authentication scheme names to either:
+ * - A token68 string (compact authentication data)
+ * - A params object with key-value pairs
+ *
+ * @example Bearer with realm
+ * ```typescript
+ * // WWW-Authenticate: Bearer realm="example"
+ * const parsed: WWWAuthenticate = {
+ *   Bearer: { realm: 'example' }
+ * }
+ * ```
+ *
+ * @example DPoP with error
+ * ```typescript
+ * // WWW-Authenticate: DPoP error="use_dpop_nonce", error_description="..."
+ * const parsed: WWWAuthenticate = {
+ *   DPoP: { error: 'use_dpop_nonce', error_description: '...' }
+ * }
+ * ```
+ */
 export type WWWAuthenticate = {
   [authScheme in string]:
     | string // token68

package/src/xrpc.ts

@@ -17,7 +17,6 @@ import { XrpcFailure, asXrpcFailure } from './errors.js'
 import { XrpcResponse } from './response.js'
 import { BinaryBodyInit, CallOptions } from './types.js'
 import {
-  XrpcPayload,
   buildAtprotoHeaders,
   isAsyncIterable,
   isBlobLike,
@@ -28,6 +27,11 @@ import {
 type XrpcParamsOptions<P extends Params> =
   NonNullable<unknown> extends P ? { params?: P } : { params: P }
 
+/**
+ * The query/path parameters type for an XRPC method, inferred from its schema.
+ *
+ * @typeParam M - The XRPC method type (Procedure, Query, or Subscription)
+ */
 export type XrpcRequestParams<M extends Procedure | Query | Subscription> =
   InferInput<M['parameters']>
 
@@ -40,13 +44,54 @@ type XrpcInputOptions<In> = In extends { body: infer B; encoding: infer E }
     { body: B; encoding?: E }
   : { body?: undefined; encoding?: undefined }
 
+/**
+ * Options for making an XRPC request.
+ *
+ * Combines {@link CallOptions} with method-specific params and body requirements.
+ * The type system ensures required params/body are provided based on the method schema.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ * @see {@link CallOptions} for general request options like signal and validateRequest
+ * @see {@link XrpcParamsOptions} for method-specific query parameters
+ * @see {@link XrpcInputOptions} for method-specific body and encoding requirements
+ *
+ * @example Query with params
+ * ```typescript
+ * const options: XrpcOptions<typeof app.bsky.feed.getTimeline.main> = {
+ *   params: { limit: 50 }
+ * }
+ * ```
+ *
+ * @example Procedure with body
+ * ```typescript
+ * const options: XrpcOptions<typeof com.atproto.repo.createRecord.main> = {
+ *   body: { repo: did, collection: 'app.bsky.feed.post', record: { ... } }
+ * }
+ * ```
+ */
 export type XrpcOptions<M extends Procedure | Query = Procedure | Query> =
   CallOptions &
     XrpcInputOptions<XrpcRequestPayload<M>> &
     XrpcParamsOptions<XrpcRequestParams<M>>
 
 /**
- * @throws XrpcFailure<M>
+ * Makes an XRPC request and throws on failure.
+ *
+ * This is the low-level function for making XRPC calls. For most use cases,
+ * prefer using {@link Client.xrpc} which provides a more ergonomic API.
+ *
+ * @param agent - The {@link Agent} to use for making the request
+ * @param ns - The lexicon method definition
+ * @param options - Request {@link XrpcOptions options} (params, body, headers, etc.)
+ * @returns The successful {@link XrpcResponse}
+ * @throws {XrpcFailure} When the request fails
+ *
+ * @example
+ * ```typescript
+ * const response = await xrpc(agent, app.bsky.feed.getTimeline.main, {
+ *   params: { limit: 50 }
+ * })
+ * ```
  */
 export async function xrpc<const M extends Query | Procedure>(
   agent: Agent,
@@ -69,10 +114,44 @@ export async function xrpc<const M extends Query | Procedure>(
   else throw response
 }
 
+/**
+ * Union type representing either a successful response or a failure.
+ *
+ * Both {@link XrpcResponse} and {@link XrpcFailure} have a `success` property
+ * that can be used to discriminate between them.
+ *
+ * @typeParam M - The XRPC method type
+ */
 export type XrpcResult<M extends Procedure | Query> =
   | XrpcResponse<M>
   | XrpcFailure<M>
 
+/**
+ * Makes an XRPC request without throwing on failure.
+ *
+ * Returns a discriminated union that can be checked via the `success` property.
+ * This is useful for handling errors without try/catch blocks. This also allow
+ * failure results to be typed with the method schema, which can provide better
+ * type safety when handling errors (e.g. checking for specific error codes).
+ *
+ * @param agent - The {@link Agent} to use for making the request
+ * @param ns - The lexicon method definition
+ * @param options - Request {@link XrpcOptions options} (params, body, headers, etc.)
+ * @returns Either a successful {@link XrpcResponse} or an {@link XrpcFailure}
+ *
+ * @example
+ * ```typescript
+ * const result = await xrpcSafe(agent, app.bsky.actor.getProfile.main, {
+ *   params: { actor: 'alice.bsky.social' }
+ * })
+ *
+ * if (result.success) {
+ *   console.log(result.body.displayName)
+ * } else {
+ *   console.error('Request failed:', result.error)
+ * }
+ * ```
+ */
 export async function xrpcSafe<const M extends Query | Procedure>(
   agent: Agent,
   ns: NonNullable<unknown> extends XrpcOptions<M>
@@ -173,7 +252,7 @@ function xrpcProcedureInput(
   method: Procedure,
   options: CallOptions & { body?: LexValue | BinaryBodyInit },
   encodingHint?: string,
-): null | XrpcPayload<BodyInit> {
+): null | { body: BodyInit; encoding: string } {
   const { input } = method
   const { body } = options
 
@@ -222,7 +301,7 @@ function buildPayload(
   schema: Payload,
   body: undefined | BodyInit,
   encodingHint?: string,
-): null | XrpcPayload<BodyInit> {
+): null | { body: BodyInit; encoding: string } {
   if (schema.encoding === undefined) {
     if (body !== undefined) {
       throw new TypeError(