@atproto/lex-client 0.0.11 → 0.0.13

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/lexicons/com/atproto/repo/createRecord.defs.ts

@@ -22,7 +22,7 @@ const main =
         /*#__PURE__*/ l.string({ format: 'record-key', maxLength: 512 }),
       ),
       validate: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
-      record: /*#__PURE__*/ l.unknownObject(),
+      record: /*#__PURE__*/ l.lexMap(),
       swapCommit: /*#__PURE__*/ l.optional(
         /*#__PURE__*/ l.string({ format: 'cid' }),
       ),
@@ -35,17 +35,25 @@ const main =
           (() => RepoDefs.commitMeta) as any,
         ),
       ),
-      validationStatus: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
+      validationStatus: /*#__PURE__*/ l.optional(
+        /*#__PURE__*/ l.string<{ knownValues: ['valid', 'unknown'] }>(),
+      ),
     }),
     ['InvalidSwap'],
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Input = l.InferMethodInput<typeof main>
-export type InputBody = l.InferMethodInputBody<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Input<B = l.BinaryData> = l.InferMethodInput<typeof main, B>
+export type $InputBody<B = l.BinaryData> = l.InferMethodInputBody<
+  typeof main,
+  B
+>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = /*#__PURE__*/ main.parameters,

package/src/lexicons/com/atproto/repo/deleteRecord.defs.ts

@@ -37,11 +37,17 @@ const main =
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Input = l.InferMethodInput<typeof main>
-export type InputBody = l.InferMethodInputBody<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Input<B = l.BinaryData> = l.InferMethodInput<typeof main, B>
+export type $InputBody<B = l.BinaryData> = l.InferMethodInputBody<
+  typeof main,
+  B
+>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = /*#__PURE__*/ main.parameters,

package/src/lexicons/com/atproto/repo/getRecord.defs.ts

@@ -22,15 +22,18 @@ const main =
     /*#__PURE__*/ l.jsonPayload({
       uri: /*#__PURE__*/ l.string({ format: 'at-uri' }),
       cid: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string({ format: 'cid' })),
-      value: /*#__PURE__*/ l.unknownObject(),
+      value: /*#__PURE__*/ l.lexMap(),
     }),
     ['RecordNotFound'],
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = main.parameters,

package/src/lexicons/com/atproto/repo/listRecords.defs.ts

@@ -34,9 +34,12 @@ const main =
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = main.parameters,
@@ -46,7 +49,7 @@ type Record$0 = {
   $type?: 'com.atproto.repo.listRecords#record'
   uri: l.AtUriString
   cid: l.CidString
-  value: l.UnknownObject
+  value: l.LexMap
 }
 
 export type { Record$0 as Record }
@@ -57,7 +60,7 @@ const record$0 = /*#__PURE__*/ l.typedObject<Record$0>(
   /*#__PURE__*/ l.object({
     uri: /*#__PURE__*/ l.string({ format: 'at-uri' }),
     cid: /*#__PURE__*/ l.string({ format: 'cid' }),
-    value: /*#__PURE__*/ l.unknownObject(),
+    value: /*#__PURE__*/ l.lexMap(),
   }),
 )
 

package/src/lexicons/com/atproto/repo/putRecord.defs.ts

@@ -20,7 +20,7 @@ const main =
       collection: /*#__PURE__*/ l.string({ format: 'nsid' }),
       rkey: /*#__PURE__*/ l.string({ format: 'record-key', maxLength: 512 }),
       validate: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
-      record: /*#__PURE__*/ l.unknownObject(),
+      record: /*#__PURE__*/ l.lexMap(),
       swapRecord: /*#__PURE__*/ l.optional(
         /*#__PURE__*/ l.nullable(/*#__PURE__*/ l.string({ format: 'cid' })),
       ),
@@ -36,17 +36,25 @@ const main =
           (() => RepoDefs.commitMeta) as any,
         ),
       ),
-      validationStatus: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
+      validationStatus: /*#__PURE__*/ l.optional(
+        /*#__PURE__*/ l.string<{ knownValues: ['valid', 'unknown'] }>(),
+      ),
     }),
     ['InvalidSwap'],
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Input = l.InferMethodInput<typeof main>
-export type InputBody = l.InferMethodInputBody<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Input<B = l.BinaryData> = l.InferMethodInput<typeof main, B>
+export type $InputBody<B = l.BinaryData> = l.InferMethodInputBody<
+  typeof main,
+  B
+>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = /*#__PURE__*/ main.parameters,

package/src/lexicons/com/atproto/repo/uploadBlob.defs.ts

@@ -21,11 +21,17 @@ const main =
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Input = l.InferMethodInput<typeof main>
-export type InputBody = l.InferMethodInputBody<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Input<B = l.BinaryData> = l.InferMethodInput<typeof main, B>
+export type $InputBody<B = l.BinaryData> = l.InferMethodInputBody<
+  typeof main,
+  B
+>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = /*#__PURE__*/ main.parameters,

package/src/lexicons/com/atproto/sync/getBlob.defs.ts

@@ -28,9 +28,12 @@ const main =
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = main.parameters,

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