@atproto/lex-client 0.0.11 → 0.0.13

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(