@atproto/lex-client 0.2.0 → 0.2.2

package/dist/xrpc.js

@@ -1,10 +1,10 @@
 import { isLexScalar, isPlainObject } from '@atproto/lex-data';
 import { lexStringify } from '@atproto/lex-json';
-import { getMain, } from '@atproto/lex-schema';
+import { Payload, Procedure, Query, Subscription, getMain, } from '@atproto/lex-schema';
 import { buildAgent } from './agent.js';
-import { XrpcFetchError, asXrpcFailure } from './errors.js';
+import { XrpcFetchError, XrpcResponseError, asXrpcFailure } from './errors.js';
 import { XrpcResponse } from './response.js';
-import { asUint8ArrayArrayBuffer, buildXrpcRequestHeaders, isAsyncIterable, isBlobLike, toReadableStream, } from './util.js';
+import { asUint8ArrayArrayBuffer, buildXrpcRequestHeaders, isAsyncIterable, isBlobLike, toReadableStream, wait, } from './util.js';
 export async function xrpc(agentOpts, ns, options = {}) {
     const response = await xrpcSafe(agentOpts, ns, options);
     if (response.success)
@@ -13,20 +13,32 @@ export async function xrpc(agentOpts, ns, options = {}) {
         throw response;
 }
 export async function xrpcSafe(agentOpts, ns, options = {}) {
-    options.signal?.throwIfAborted();
     const method = getMain(ns);
-    try {
-        const agent = buildAgent(agentOpts);
-        const url = xrpcRequestUrl(method, options);
-        const request = xrpcRequestInit(method, options);
-        const response = await agent.fetchHandler(url, request).catch((err) => {
-            const cause = extractFetchErrorCause(err);
-            throw new XrpcFetchError(method, cause);
-        });
-        return await XrpcResponse.fromFetchResponse(method, response, options);
-    }
-    catch (cause) {
-        return asXrpcFailure(method, cause);
+    for (let counter = 1;; counter++) {
+        options.signal?.throwIfAborted();
+        try {
+            const agent = buildAgent(agentOpts);
+            const url = xrpcRequestUrl(method, options);
+            const request = xrpcRequestInit(method, options);
+            const response = await agent.fetchHandler(url, request).catch((err) => {
+                const cause = extractFetchErrorCause(err);
+                throw new XrpcFetchError(method, cause);
+            });
+            return await XrpcResponse.fromFetchResponse(method, response, options);
+        }
+        catch (cause) {
+            const failure = asXrpcFailure(method, cause);
+            // Cannot retry a request with a consumable body
+            if (options.body instanceof ReadableStream ||
+                isAsyncIterable(options.body)) {
+                return failure;
+            }
+            const waitTime = getRetryWaitTime(failure, options, counter);
+            if (waitTime == null) {
+                return failure;
+            }
+            await wait(waitTime, options);
+        }
     }
 }
 function xrpcRequestUrl(method, options) {
@@ -186,4 +198,38 @@ export function extractFetchErrorCause(err) {
     // environments like React Native, Deno, Bun, Browser, etc.)
     return err;
 }
+function getRetryWaitTime(failure, options, counter) {
+    const { retry, maxRetries = 0, minRetryTimeout = 500, maxRetryTimeout = 30_000, retryTimeoutFactor = 2, retryHeaders = true, } = options;
+    if (counter > maxRetries) {
+        return undefined;
+    }
+    const shouldRetry = retry
+        ? retry(failure, { counter })
+        : failure.shouldRetry();
+    if (!shouldRetry) {
+        return undefined;
+    }
+    const waitTime = retryHeaders && failure instanceof XrpcResponseError
+        ? getWaitTimeFromHeaders(failure.headers)
+        : undefined;
+    return Math.min(maxRetryTimeout, waitTime ?? minRetryTimeout * retryTimeoutFactor ** (counter - 1));
+}
+function getWaitTimeFromHeaders(headers) {
+    const retryAfterHeader = headers.get('retry-after');
+    if (retryAfterHeader) {
+        const waitTime = /^\s*\d+\s*$/.test(retryAfterHeader)
+            ? // Retry-After is in seconds
+                Number(retryAfterHeader) * 1000
+            : // Retry-After is an http-date
+                new Date(retryAfterHeader).getTime() - Date.now();
+        if (waitTime > 0)
+            return waitTime;
+    }
+    const resetsAt = headers.get('RateLimit-Reset'); // epoch
+    if (resetsAt) {
+        const waitTime = Number(resetsAt) * 1000 - Date.now();
+        if (waitTime > 0)
+            return waitTime;
+    }
+}
 //# sourceMappingURL=xrpc.js.map

package/dist/xrpc.js.map

@@ -1 +1 @@
-{"version":3,"file":"xrpc.js","sourceRoot":"","sources":["../src/xrpc.ts"],"names":[],"mappings":"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","sourcesContent":["import { LexValue, isLexScalar, isPlainObject } from '@atproto/lex-data'\nimport { lexStringify } from '@atproto/lex-json'\nimport {\n  InferInput,\n  InferPayload,\n  Main,\n  NsidString,\n  Params,\n  Payload,\n  Procedure,\n  Query,\n  Restricted,\n  Subscription,\n  getMain,\n} from '@atproto/lex-schema'\nimport { Agent, AgentOptions, buildAgent } from './agent.js'\nimport { XrpcFailure, XrpcFetchError, asXrpcFailure } from './errors.js'\nimport { XrpcResponse, XrpcResponseOptions } from './response.js'\nimport { BinaryBodyInit } from './types.js'\nimport {\n  XrpcRequestHeadersOptions,\n  asUint8ArrayArrayBuffer,\n  buildXrpcRequestHeaders,\n  isAsyncIterable,\n  isBlobLike,\n  toReadableStream,\n} from './util.js'\n\n/**\n * The query/path parameters type for an XRPC method, inferred from its schema.\n *\n * @typeParam M - The XRPC method type (Procedure, Query, or Subscription)\n */\nexport type XrpcRequestParams<M extends Procedure | Query | Subscription> =\n  InferInput<M['parameters']>\n\n// If all params are optional, allow omitting the params object\ntype XrpcRequestParamsOptions<P extends Params> =\n  NonNullable<unknown> extends P ? { params?: P } : { params: P }\n\ntype XrpcRequestPayload<M extends Procedure | Query> = M extends Procedure\n  ? InferPayload<M['input'], BinaryBodyInit>\n  : undefined\n\ntype XrpcRequestPayloadOptions<TPayload> = TPayload extends {\n  body: infer B\n  encoding: infer E\n}\n  ? {\n      body: B\n\n      /**\n       * mime type hint for binary bodies\n       *\n       * Only needed for endpoints that accept binary input (e.g. file uploads)\n       * when the body is a Blob-like object without a type (e.g. fetch-blob's\n       * Blob). If the body is a Blob-like object with a type, that type will be\n       * used as the content-type header instead of this option.\n       *\n       * @default \"application/octet-stream\"\n       */\n      encoding?: E\n    }\n  : { body?: undefined; encoding?: undefined }\n\n/**\n * Options for making an XRPC request, based on the method schema.\n *\n * Combines {@link XrpcRequestOptions} and {@link XrpcResponseOptions} with\n * method-specific params and body requirements. The type system ensures\n * required params/body are provided based on the method schema.\n *\n * @typeParam M - The XRPC method type (Procedure or Query)\n *\n * @example Query with params\n * ```typescript\n * const options: XrpcOptions<typeof app.bsky.feed.getTimeline.main> = {\n *   params: { limit: 50 }\n * }\n * ```\n *\n * @example Procedure with body\n * ```typescript\n * const options: XrpcOptions<typeof com.atproto.repo.createRecord.main> = {\n *   body: { repo: did, collection: 'app.bsky.feed.post', record: { ... } }\n * }\n * ```\n */\nexport type XrpcOptions<M extends Procedure | Query = Procedure | Query> =\n  XrpcRequestOptions<M> & XrpcResponseOptions\n\nexport type XrpcRequestOptions<\n  M extends Procedure | Query = Procedure | Query,\n> = XrpcRequestProcessingOptions &\n  XrpcRequestHeadersOptions &\n  XrpcRequestPayloadOptions<XrpcRequestPayload<M>> &\n  XrpcRequestParamsOptions<XrpcRequestParams<M>>\n\nexport type XrpcRequestProcessingOptions = {\n  /**\n   * AbortSignal to cancel the request.\n   */\n  signal?: AbortSignal\n\n  /**\n   * Whether to validate the request against the method's input schema. Enabling\n   * this can help catch errors early but may have a performance cost. This\n   * would typically only be set to `true` in development or debugging\n   * scenarios.\n   *\n   * @default false\n   */\n  validateRequest?: boolean\n}\n\n/**\n * Makes an XRPC request and throws on failure.\n *\n * This is the low-level function for making XRPC calls.\n *\n * @param agent - The {@link Agent} to use for making the request\n * @param ns - The lexicon method definition\n * @param options - Request {@link XrpcOptions options} (params, body, headers, etc.)\n * @returns The successful {@link XrpcResponse}\n * @throws {XrpcFailure} When the request fails\n *\n * @example\n * ```typescript\n * const response = await xrpc('https://bsky.network', com.atproto.identity.resolveHandle, {\n *   params: { handle: \"atproto.com\" }\n * })\n * ```\n *\n * @example\n * ```typescript\n * const response = await xrpc(agent, app.bsky.feed.getTimeline.main, {\n *   params: { limit: 50 }\n * })\n * ```\n */\nexport async function xrpc<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: NonNullable<unknown> extends XrpcOptions<M>\n    ? Main<M>\n    : Restricted<'This XRPC method requires an \"options\" argument'>,\n): Promise<XrpcResponse<M>>\nexport async function xrpc<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: Main<M>,\n  options: XrpcOptions<M>,\n): Promise<XrpcResponse<M>>\nexport async function xrpc<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: Main<M>,\n  options: XrpcOptions<M> = {} as XrpcOptions<M>,\n): Promise<XrpcResponse<M>> {\n  const response = await xrpcSafe<M>(agentOpts, ns, options)\n  if (response.success) return response\n  else throw response\n}\n\n/**\n * Union type representing either a successful response or a failure.\n *\n * Both {@link XrpcResponse} and {@link XrpcFailure} have a `success` property\n * that can be used to discriminate between them.\n *\n * @typeParam M - The XRPC method type\n */\nexport type XrpcResult<M extends Procedure | Query> =\n  | XrpcResponse<M>\n  | XrpcFailure<M>\n\n/**\n * Makes an XRPC request without throwing on failure.\n *\n * Returns a discriminated union that can be checked via the `success` property.\n * This is useful for handling errors without try/catch blocks. This also allow\n * failure results to be typed with the method schema, which can provide better\n * type safety when handling errors (e.g. checking for specific error codes).\n *\n * @param agent - The {@link Agent} to use for making the request\n * @param ns - The lexicon method definition\n * @param options - Request {@link XrpcOptions options} (params, body, headers, etc.)\n * @returns Either a successful {@link XrpcResponse} or an {@link XrpcFailure}\n *\n * @example\n * ```typescript\n * const result = await xrpcSafe('https://example.com', app.bsky.actor.getProfile, {\n *   params: { actor: 'alice.bsky.social' }\n * })\n *\n * if (result.success) {\n *   console.log(result.body.displayName)\n * } else {\n *   console.error('Request failed:', result.error)\n * }\n * ```\n */\nexport async function xrpcSafe<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: NonNullable<unknown> extends XrpcOptions<M>\n    ? Main<M>\n    : Restricted<'This XRPC method requires an \"options\" argument'>,\n): Promise<XrpcResult<M>>\nexport async function xrpcSafe<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: Main<M>,\n  options: XrpcOptions<M>,\n): Promise<XrpcResult<M>>\nexport async function xrpcSafe<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: Main<M>,\n  options: XrpcOptions<M> = {} as XrpcOptions<M>,\n): Promise<XrpcResult<M>> {\n  options.signal?.throwIfAborted()\n  const method: M = getMain(ns)\n  try {\n    const agent = buildAgent(agentOpts)\n    const url = xrpcRequestUrl(method, options)\n    const request = xrpcRequestInit(method, options)\n    const response = await agent.fetchHandler(url, request).catch((err) => {\n      const cause = extractFetchErrorCause(err)\n      throw new XrpcFetchError(method, cause)\n    })\n    return await XrpcResponse.fromFetchResponse<M>(method, response, options)\n  } catch (cause) {\n    return asXrpcFailure(method, cause)\n  }\n}\n\nfunction xrpcRequestUrl<M extends Procedure | Query | Subscription>(\n  method: M,\n  options: { params?: Params },\n): `/xrpc/${NsidString}${'' | `?${string}`}` {\n  const path = `/xrpc/${method.nsid}` as const\n\n  // @NOTE param.toURLSearchParams() will always validate the params in order to\n  // apply default values, so we can't disable it with options.validateRequest\n\n  const queryString = method.parameters\n    ?.toURLSearchParams(options.params ?? {})\n    .toString()\n\n  return queryString ? (`${path}?${queryString}` as const) : path\n}\n\nfunction xrpcRequestInit<T extends Procedure | Query>(\n  schema: T,\n  options: XrpcRequestProcessingOptions &\n    XrpcRequestHeadersOptions &\n    XrpcProcedureInputOptions & {\n      encoding?: string\n    },\n): RequestInit & { duplex?: 'half' } {\n  const headers = buildXrpcRequestHeaders(options)\n\n  // Tell the server what type of response we're expecting\n  if (schema.output.encoding) {\n    headers.set('accept', schema.output.encoding)\n  }\n\n  // Caller should not set content-type header\n  if (headers.has('content-type')) {\n    const contentType = headers.get('content-type')\n    throw new TypeError(`Unexpected content-type header (${contentType})`)\n  }\n\n  // Requests with body\n  if ('input' in schema) {\n    const encodingHint = options.encoding\n    const input = xrpcProcedureInput(schema, options, encodingHint)\n\n    if (input) {\n      headers.set('content-type', input.encoding)\n    } else if (encodingHint != null) {\n      throw new TypeError(`Unexpected encoding hint (${encodingHint})`)\n    }\n\n    return {\n      duplex: 'half',\n      redirect: 'follow',\n      referrerPolicy: 'strict-origin-when-cross-origin', // (default)\n      mode: 'cors', // (default)\n      signal: options.signal,\n      method: 'POST',\n      headers,\n      body: input?.body,\n    }\n  }\n\n  // Requests without body\n  return {\n    duplex: 'half',\n    redirect: 'follow',\n    referrerPolicy: 'strict-origin-when-cross-origin', // (default)\n    mode: 'cors', // (default)\n    signal: options.signal,\n    method: 'GET',\n    headers,\n  }\n}\n\ntype XrpcProcedureInputOptions = {\n  body?: LexValue | BinaryBodyInit\n  validateRequest?: boolean\n}\n\nfunction xrpcProcedureInput(\n  method: Procedure,\n  options: XrpcProcedureInputOptions,\n  encodingHint?: string,\n): null | { body: BodyInit; encoding: string } {\n  const { input } = method\n  const { body } = options\n\n  if (options.validateRequest) {\n    input.schema?.check(body)\n  }\n\n  // Special handling for endpoints expecting application/json input\n  if (input.encoding === 'application/json') {\n    // @NOTE **NOT** using isLexValue here to avoid deep checks in order to\n    // distinguish between LexValue and BinaryBodyInit.\n    if (!isLexScalar(body) && !isPlainObject(body) && !Array.isArray(body)) {\n      throw new TypeError(`Expected LexValue body, got ${typeof body}`)\n    }\n\n    return buildPayload(input, lexStringify(body), encodingHint)\n  }\n\n  // Other encodings will be sent unaltered (ie. as binary data)\n  switch (typeof body) {\n    case 'undefined':\n    case 'string':\n      return buildPayload(input, body, encodingHint)\n    case 'object': {\n      if (body === null) break\n      if (ArrayBuffer.isView(body)) {\n        return buildPayload(input, asUint8ArrayArrayBuffer(body), encodingHint)\n      } else if (\n        body instanceof ArrayBuffer ||\n        body instanceof ReadableStream\n      ) {\n        return buildPayload(input, body, encodingHint)\n      } else if (isAsyncIterable(body)) {\n        // @NOTE While fetch() does not allow SharedArrayBuffer-backed\n        // Uint8Arrays as \"body\", it **does** allow using ReadableStreams made\n        // of Uint8Arrays<SharedArrayBuffer> (tested on NodeJS 22) as \"body\".\n        return buildPayload(input, toReadableStream(body), encodingHint)\n      } else if (isBlobLike(body)) {\n        return buildPayload(input, body, encodingHint || body.type)\n      }\n    }\n  }\n\n  throw new TypeError(\n    `Invalid ${typeof body} body for ${input.encoding} encoding`,\n  )\n}\n\nfunction buildPayload(\n  schema: Payload,\n  body: undefined | BodyInit,\n  encodingHint?: string,\n): null | { body: BodyInit; encoding: string } {\n  if (schema.encoding === undefined) {\n    if (body !== undefined) {\n      throw new TypeError(`Endpoint expects no payload`)\n    }\n\n    return null\n  }\n\n  if (body === undefined) {\n    // This error would be returned by the server, but we can catch it earlier\n    // to avoid un-necessary requests. Note that a content-length of 0 does not\n    // necessary mean that the body is \"empty\" (e.g. an empty txt file).\n    throw new TypeError(`A request body is expected but none was provided`)\n  }\n\n  const encoding = buildEncoding(schema, encodingHint)\n  return { encoding, body }\n}\n\nfunction buildEncoding(schema: Payload, encodingHint?: string): string {\n  // Should never happen (required for type safety)\n  if (!schema.encoding) {\n    throw new TypeError('Unexpected payload')\n  }\n\n  if (encodingHint?.length) {\n    if (!schema.matchesEncoding(encodingHint)) {\n      throw new TypeError(\n        `Cannot send a body with content-type \"${encodingHint}\" for \"${schema.encoding}\" encoding`,\n      )\n    }\n    return encodingHint\n  }\n\n  // Fallback\n\n  if (schema.encoding === '*/*') {\n    return 'application/octet-stream'\n  }\n\n  if (schema.encoding.startsWith('text/')) {\n    return schema.encoding.includes('*')\n      ? 'text/plain; charset=utf-8'\n      : `${schema.encoding}; charset=utf-8`\n  }\n\n  if (!schema.encoding.includes('*')) {\n    return schema.encoding\n  }\n\n  throw new TypeError(\n    `Unable to determine payload encoding. Please provide a 'content-type' header matching ${schema.encoding}.`,\n  )\n}\n\n/**\n * Extracts the root cause from an error, unwrapping common fetch-related errors\n * such as those from undici (Node's internal fetch implementation).\n *\n * @param err - The error to extract the root cause from\n * @returns The root cause error, or the original error if no specific pattern is matched\n * @remarks This is useful for getting more specific error information from fetch-related failures, especially in Node environments using undici.\n */\nexport function extractFetchErrorCause(err: unknown): unknown {\n  // Unwrap the Network error from undici (i.e. Node's internal fetch() implementation)\n  // https://github.com/nodejs/undici/blob/04cb77327f7ada95c2e5b67424cddcb22d7bf882/lib/web/fetch/index.js#L234-L239\n  if (\n    err instanceof TypeError &&\n    err.message === 'fetch failed' &&\n    err.cause !== undefined\n  ) {\n    return err.cause\n  }\n\n  // @TODO Add other unwrap patterns here as needed (e.g. for other fetch\n  // implementations or common network libraries, like \"node:http\", or in other\n  // environments like React Native, Deno, Bun, Browser, etc.)\n\n  return err\n}\n"]}
+{"version":3,"file":"xrpc.js","sourceRoot":"","sources":["../src/xrpc.ts"],"names":[],"mappings":"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","sourcesContent":["import type { LexValue } from '@atproto/lex-data'\nimport { isLexScalar, isPlainObject } from '@atproto/lex-data'\nimport { lexStringify } from '@atproto/lex-json'\nimport type {\n  InferInput,\n  InferPayload,\n  Main,\n  NsidString,\n  Params,\n  Restricted,\n} from '@atproto/lex-schema'\nimport {\n  Payload,\n  Procedure,\n  Query,\n  Subscription,\n  getMain,\n} from '@atproto/lex-schema'\nimport type { Agent, AgentOptions } from './agent.js'\nimport { buildAgent } from './agent.js'\nimport type { XrpcFailure } from './errors.js'\nimport { XrpcFetchError, XrpcResponseError, asXrpcFailure } from './errors.js'\nimport type { XrpcResponseOptions } from './response.js'\nimport { XrpcResponse } from './response.js'\nimport type { BinaryBodyInit } from './types.js'\nimport type { XrpcRequestHeadersOptions } from './util.js'\nimport {\n  asUint8ArrayArrayBuffer,\n  buildXrpcRequestHeaders,\n  isAsyncIterable,\n  isBlobLike,\n  toReadableStream,\n  wait,\n} from './util.js'\n\n/**\n * The query/path parameters type for an XRPC method, inferred from its schema.\n *\n * @typeParam M - The XRPC method type (Procedure, Query, or Subscription)\n */\nexport type XrpcRequestParams<M extends Procedure | Query | Subscription> =\n  InferInput<M['parameters']>\n\n// If all params are optional, allow omitting the params object\ntype XrpcRequestParamsOptions<P extends Params> =\n  NonNullable<unknown> extends P ? { params?: P } : { params: P }\n\ntype XrpcRequestPayload<M extends Procedure | Query> = M extends Procedure\n  ? InferPayload<M['input'], BinaryBodyInit>\n  : undefined\n\ntype XrpcRequestPayloadOptions<TPayload> = TPayload extends {\n  body: infer B\n  encoding: infer E\n}\n  ? {\n      body: B\n\n      /**\n       * mime type hint for binary bodies\n       *\n       * Only needed for endpoints that accept binary input (e.g. file uploads)\n       * when the body is a Blob-like object without a type (e.g. fetch-blob's\n       * Blob). If the body is a Blob-like object with a type, that type will be\n       * used as the content-type header instead of this option.\n       *\n       * @default \"application/octet-stream\"\n       */\n      encoding?: E\n    }\n  : { body?: undefined; encoding?: undefined }\n\n/**\n * Options for making an XRPC request, based on the method schema.\n *\n * Combines {@link XrpcRequestOptions} and {@link XrpcResponseOptions} with\n * method-specific params and body requirements. The type system ensures\n * required params/body are provided based on the method schema.\n *\n * @typeParam M - The XRPC method type (Procedure or Query)\n *\n * @example Query with params\n * ```typescript\n * const options: XrpcOptions<typeof app.bsky.feed.getTimeline.main> = {\n *   params: { limit: 50 }\n * }\n * ```\n *\n * @example Procedure with body\n * ```typescript\n * const options: XrpcOptions<typeof com.atproto.repo.createRecord.main> = {\n *   body: { repo: did, collection: 'app.bsky.feed.post', record: { ... } }\n * }\n * ```\n */\nexport type XrpcOptions<M extends Procedure | Query = Procedure | Query> =\n  XrpcRequestOptions<M> & XrpcResponseOptions & RetryOptions\n\nexport type XrpcRequestOptions<\n  M extends Procedure | Query = Procedure | Query,\n> = XrpcRequestProcessingOptions &\n  XrpcRequestHeadersOptions &\n  XrpcRequestPayloadOptions<XrpcRequestPayload<M>> &\n  XrpcRequestParamsOptions<XrpcRequestParams<M>>\n\nexport type XrpcRequestProcessingOptions = {\n  /**\n   * AbortSignal to cancel the request.\n   */\n  signal?: AbortSignal\n\n  /**\n   * Whether to validate the request against the method's input schema. Enabling\n   * this can help catch errors early but may have a performance cost. This\n   * would typically only be set to `true` in development or debugging\n   * scenarios.\n   *\n   * @default false\n   */\n  validateRequest?: boolean\n}\n\n/**\n * Makes an XRPC request and throws on failure.\n *\n * This is the low-level function for making XRPC calls.\n *\n * @param agent - The {@link Agent} to use for making the request\n * @param ns - The lexicon method definition\n * @param options - Request {@link XrpcOptions options} (params, body, headers, etc.)\n * @returns The successful {@link XrpcResponse}\n * @throws {XrpcFailure} When the request fails\n *\n * @example\n * ```typescript\n * const response = await xrpc('https://bsky.network', com.atproto.identity.resolveHandle, {\n *   params: { handle: \"atproto.com\" }\n * })\n * ```\n *\n * @example\n * ```typescript\n * const response = await xrpc(agent, app.bsky.feed.getTimeline.main, {\n *   params: { limit: 50 }\n * })\n * ```\n */\nexport async function xrpc<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: NonNullable<unknown> extends XrpcOptions<M>\n    ? Main<M>\n    : Restricted<'This XRPC method requires an \"options\" argument'>,\n): Promise<XrpcResponse<M>>\nexport async function xrpc<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: Main<M>,\n  options: XrpcOptions<M>,\n): Promise<XrpcResponse<M>>\nexport async function xrpc<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: Main<M>,\n  options: XrpcOptions<M> = {} as XrpcOptions<M>,\n): Promise<XrpcResponse<M>> {\n  const response = await xrpcSafe<M>(agentOpts, ns, options)\n  if (response.success) return response\n  else throw response\n}\n\n/**\n * Union type representing either a successful response or a failure.\n *\n * Both {@link XrpcResponse} and {@link XrpcFailure} have a `success` property\n * that can be used to discriminate between them.\n *\n * @typeParam M - The XRPC method type\n */\nexport type XrpcResult<M extends Procedure | Query> =\n  | XrpcResponse<M>\n  | XrpcFailure<M>\n\n/**\n * Makes an XRPC request without throwing on failure.\n *\n * Returns a discriminated union that can be checked via the `success` property.\n * This is useful for handling errors without try/catch blocks. This also allows\n * failure results to be typed with the method schema, which can provide better\n * type safety when handling errors (e.g. checking for specific error codes).\n *\n * @param agent - The {@link Agent} to use for making the request\n * @param ns - The lexicon method definition\n * @param options - Request {@link XrpcOptions options} (params, body, headers, etc.)\n * @returns Either a successful {@link XrpcResponse} or an {@link XrpcFailure}\n *\n * @example\n * ```typescript\n * const result = await xrpcSafe('https://example.com', app.bsky.actor.getProfile, {\n *   params: { actor: 'alice.bsky.social' }\n * })\n *\n * if (result.success) {\n *   console.log(result.body.displayName)\n * } else {\n *   console.error('Request failed:', result.error)\n * }\n * ```\n */\nexport async function xrpcSafe<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: NonNullable<unknown> extends XrpcOptions<M>\n    ? Main<M>\n    : Restricted<'This XRPC method requires an \"options\" argument'>,\n): Promise<XrpcResult<M>>\nexport async function xrpcSafe<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: Main<M>,\n  options: XrpcOptions<M>,\n): Promise<XrpcResult<M>>\nexport async function xrpcSafe<const M extends Query | Procedure>(\n  agentOpts: Agent | AgentOptions,\n  ns: Main<M>,\n  options: XrpcOptions<M> = {} as XrpcOptions<M>,\n): Promise<XrpcResult<M>> {\n  const method: M = getMain(ns)\n\n  for (let counter = 1; ; counter++) {\n    options.signal?.throwIfAborted()\n    try {\n      const agent = buildAgent(agentOpts)\n      const url = xrpcRequestUrl(method, options)\n      const request = xrpcRequestInit(method, options)\n      const response = await agent.fetchHandler(url, request).catch((err) => {\n        const cause = extractFetchErrorCause(err)\n        throw new XrpcFetchError(method, cause)\n      })\n      return await XrpcResponse.fromFetchResponse<M>(method, response, options)\n    } catch (cause) {\n      const failure = asXrpcFailure(method, cause)\n\n      // Cannot retry a request with a consumable body\n      if (\n        options.body instanceof ReadableStream ||\n        isAsyncIterable(options.body)\n      ) {\n        return failure\n      }\n\n      const waitTime = getRetryWaitTime(failure, options, counter)\n      if (waitTime == null) {\n        return failure\n      }\n\n      await wait(waitTime, options)\n    }\n  }\n}\n\nfunction xrpcRequestUrl<M extends Procedure | Query | Subscription>(\n  method: M,\n  options: { params?: Params },\n): `/xrpc/${NsidString}${'' | `?${string}`}` {\n  const path = `/xrpc/${method.nsid}` as const\n\n  // @NOTE param.toURLSearchParams() will always validate the params in order to\n  // apply default values, so we can't disable it with options.validateRequest\n\n  const queryString = method.parameters\n    ?.toURLSearchParams(options.params ?? {})\n    .toString()\n\n  return queryString ? (`${path}?${queryString}` as const) : path\n}\n\nfunction xrpcRequestInit<T extends Procedure | Query>(\n  schema: T,\n  options: XrpcRequestProcessingOptions &\n    XrpcRequestHeadersOptions &\n    XrpcProcedureInputOptions & {\n      encoding?: string\n    },\n): RequestInit & { duplex?: 'half' } {\n  const headers = buildXrpcRequestHeaders(options)\n\n  // Tell the server what type of response we're expecting\n  if (schema.output.encoding) {\n    headers.set('accept', schema.output.encoding)\n  }\n\n  // Caller should not set content-type header\n  if (headers.has('content-type')) {\n    const contentType = headers.get('content-type')\n    throw new TypeError(`Unexpected content-type header (${contentType})`)\n  }\n\n  // Requests with body\n  if ('input' in schema) {\n    const encodingHint = options.encoding\n    const input = xrpcProcedureInput(schema, options, encodingHint)\n\n    if (input) {\n      headers.set('content-type', input.encoding)\n    } else if (encodingHint != null) {\n      throw new TypeError(`Unexpected encoding hint (${encodingHint})`)\n    }\n\n    return {\n      duplex: 'half',\n      redirect: 'follow',\n      referrerPolicy: 'strict-origin-when-cross-origin', // (default)\n      mode: 'cors', // (default)\n      signal: options.signal,\n      method: 'POST',\n      headers,\n      body: input?.body,\n    }\n  }\n\n  // Requests without body\n  return {\n    duplex: 'half',\n    redirect: 'follow',\n    referrerPolicy: 'strict-origin-when-cross-origin', // (default)\n    mode: 'cors', // (default)\n    signal: options.signal,\n    method: 'GET',\n    headers,\n  }\n}\n\ntype XrpcProcedureInputOptions = {\n  body?: LexValue | BinaryBodyInit\n  validateRequest?: boolean\n}\n\nfunction xrpcProcedureInput(\n  method: Procedure,\n  options: XrpcProcedureInputOptions,\n  encodingHint?: string,\n): null | { body: BodyInit; encoding: string } {\n  const { input } = method\n  const { body } = options\n\n  if (options.validateRequest) {\n    input.schema?.check(body)\n  }\n\n  // Special handling for endpoints expecting application/json input\n  if (input.encoding === 'application/json') {\n    // @NOTE **NOT** using isLexValue here to avoid deep checks in order to\n    // distinguish between LexValue and BinaryBodyInit.\n    if (!isLexScalar(body) && !isPlainObject(body) && !Array.isArray(body)) {\n      throw new TypeError(`Expected LexValue body, got ${typeof body}`)\n    }\n\n    return buildPayload(input, lexStringify(body), encodingHint)\n  }\n\n  // Other encodings will be sent unaltered (ie. as binary data)\n  switch (typeof body) {\n    case 'undefined':\n    case 'string':\n      return buildPayload(input, body, encodingHint)\n    case 'object': {\n      if (body === null) break\n      if (ArrayBuffer.isView(body)) {\n        return buildPayload(input, asUint8ArrayArrayBuffer(body), encodingHint)\n      } else if (\n        body instanceof ArrayBuffer ||\n        body instanceof ReadableStream\n      ) {\n        return buildPayload(input, body, encodingHint)\n      } else if (isAsyncIterable(body)) {\n        // @NOTE While fetch() does not allow SharedArrayBuffer-backed\n        // Uint8Arrays as \"body\", it **does** allow using ReadableStreams made\n        // of Uint8Arrays<SharedArrayBuffer> (tested on NodeJS 22) as \"body\".\n        return buildPayload(input, toReadableStream(body), encodingHint)\n      } else if (isBlobLike(body)) {\n        return buildPayload(input, body, encodingHint || body.type)\n      }\n    }\n  }\n\n  throw new TypeError(\n    `Invalid ${typeof body} body for ${input.encoding} encoding`,\n  )\n}\n\nfunction buildPayload(\n  schema: Payload,\n  body: undefined | BodyInit,\n  encodingHint?: string,\n): null | { body: BodyInit; encoding: string } {\n  if (schema.encoding === undefined) {\n    if (body !== undefined) {\n      throw new TypeError(`Endpoint expects no payload`)\n    }\n\n    return null\n  }\n\n  if (body === undefined) {\n    // This error would be returned by the server, but we can catch it earlier\n    // to avoid un-necessary requests. Note that a content-length of 0 does not\n    // necessary mean that the body is \"empty\" (e.g. an empty txt file).\n    throw new TypeError(`A request body is expected but none was provided`)\n  }\n\n  const encoding = buildEncoding(schema, encodingHint)\n  return { encoding, body }\n}\n\nfunction buildEncoding(schema: Payload, encodingHint?: string): string {\n  // Should never happen (required for type safety)\n  if (!schema.encoding) {\n    throw new TypeError('Unexpected payload')\n  }\n\n  if (encodingHint?.length) {\n    if (!schema.matchesEncoding(encodingHint)) {\n      throw new TypeError(\n        `Cannot send a body with content-type \"${encodingHint}\" for \"${schema.encoding}\" encoding`,\n      )\n    }\n    return encodingHint\n  }\n\n  // Fallback\n\n  if (schema.encoding === '*/*') {\n    return 'application/octet-stream'\n  }\n\n  if (schema.encoding.startsWith('text/')) {\n    return schema.encoding.includes('*')\n      ? 'text/plain; charset=utf-8'\n      : `${schema.encoding}; charset=utf-8`\n  }\n\n  if (!schema.encoding.includes('*')) {\n    return schema.encoding\n  }\n\n  throw new TypeError(\n    `Unable to determine payload encoding. Please provide a 'content-type' header matching ${schema.encoding}.`,\n  )\n}\n\n/**\n * Extracts the root cause from an error, unwrapping common fetch-related errors\n * such as those from undici (Node's internal fetch implementation).\n *\n * @param err - The error to extract the root cause from\n * @returns The root cause error, or the original error if no specific pattern is matched\n * @remarks This is useful for getting more specific error information from fetch-related failures, especially in Node environments using undici.\n */\nexport function extractFetchErrorCause(err: unknown): unknown {\n  // Unwrap the Network error from undici (i.e. Node's internal fetch() implementation)\n  // https://github.com/nodejs/undici/blob/04cb77327f7ada95c2e5b67424cddcb22d7bf882/lib/web/fetch/index.js#L234-L239\n  if (\n    err instanceof TypeError &&\n    err.message === 'fetch failed' &&\n    err.cause !== undefined\n  ) {\n    return err.cause\n  }\n\n  // @TODO Add other unwrap patterns here as needed (e.g. for other fetch\n  // implementations or common network libraries, like \"node:http\", or in other\n  // environments like React Native, Deno, Bun, Browser, etc.)\n\n  return err\n}\n\nexport type RetryOptions = {\n  /**\n   * Function to determine whether a request should be retried after a failure.\n   *\n   * @default `(failure) => failure.shouldRetry()`\n   */\n  retry?: (failure: XrpcFailure, context: { counter: number }) => boolean\n  /**\n   * Maximum number of retries to allow.\n   *\n   * @default 0 (no retries)\n   */\n  maxRetries?: number\n  /**\n   * Max number of milliseconds allow between retries\n   *\n   * @default 30000\n   */\n  maxRetryTimeout?: number\n  /**\n   * Initial number of milliseconds to wait before retrying for the first time.\n   *\n   * @default 500\n   */\n  minRetryTimeout?: number\n  /**\n   * Factor to multiply the timeout factor between retries.\n   *\n   * @default 2\n   */\n  retryTimeoutFactor?: number\n  /**\n   * Automatically infer timeout between retries based on header values (`Retry-After`, `RateLimit-Reset`).\n   *\n   * @default true\n   */\n  retryHeaders?: boolean\n}\n\nfunction getRetryWaitTime(\n  failure: XrpcFailure,\n  options: RetryOptions,\n  counter: number,\n): number | undefined {\n  const {\n    retry,\n    maxRetries = 0,\n    minRetryTimeout = 500,\n    maxRetryTimeout = 30_000,\n    retryTimeoutFactor = 2,\n    retryHeaders = true,\n  } = options\n\n  if (counter > maxRetries) {\n    return undefined\n  }\n\n  const shouldRetry = retry\n    ? retry(failure, { counter })\n    : failure.shouldRetry()\n\n  if (!shouldRetry) {\n    return undefined\n  }\n\n  const waitTime =\n    retryHeaders && failure instanceof XrpcResponseError\n      ? getWaitTimeFromHeaders(failure.headers)\n      : undefined\n\n  return Math.min(\n    maxRetryTimeout,\n    waitTime ?? minRetryTimeout * retryTimeoutFactor ** (counter - 1),\n  )\n}\n\nfunction getWaitTimeFromHeaders(headers: Headers): number | undefined {\n  const retryAfterHeader = headers.get('retry-after')\n  if (retryAfterHeader) {\n    const waitTime = /^\\s*\\d+\\s*$/.test(retryAfterHeader)\n      ? // Retry-After is in seconds\n        Number(retryAfterHeader) * 1000\n      : // Retry-After is an http-date\n        new Date(retryAfterHeader).getTime() - Date.now()\n    if (waitTime > 0) return waitTime\n  }\n\n  const resetsAt = headers.get('RateLimit-Reset') // epoch\n  if (resetsAt) {\n    const waitTime = Number(resetsAt) * 1000 - Date.now()\n    if (waitTime > 0) return waitTime\n  }\n}\n"]}

package/package.json

@@ -1,9 +1,6 @@
 {
   "name": "@atproto/lex-client",
-  "version": "0.2.0",
-  "engines": {
-    "node": ">=22"
-  },
+  "version": "0.2.2",
   "license": "MIT",
   "description": "HTTP client for interacting with Lexicon based APIs",
   "keywords": [
@@ -19,10 +16,6 @@
     "directory": "packages/lex/lex-client"
   },
   "files": [
-    "./src",
-    "./tsconfig.build.json",
-    "./tsconfig.tests.json",
-    "./tsconfig.json",
     "./dist",
     "./CHANGELOG.md"
   ],
@@ -34,19 +27,23 @@
       "default": "./dist/index.js"
     }
   },
+  "engines": {
+    "node": ">=22"
+  },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@atproto/lex-data": "^0.1.3",
-    "@atproto/lex-json": "^0.1.2",
-    "@atproto/lex-schema": "^0.1.5"
+    "@atproto/lex-data": "^0.1.4",
+    "@atproto/lex-json": "^0.1.3",
+    "@atproto/lex-schema": "^0.2.0"
   },
   "devDependencies": {
     "vitest": "^4.0.16",
-    "@atproto/lex-cbor": "^0.1.2",
-    "@atproto/lex-builder": "^0.1.4"
+    "@atproto/lex-builder": "^0.1.6",
+    "@atproto/lex-cbor": "^0.1.3"
   },
   "scripts": {
-    "prebuild": "node ./scripts/lex-build.mjs",
+    "codegen:lex": "node ./scripts/lex-build.mjs",
+    "prebuild": "pnpm run '/^(codegen:.+)$/'",
     "build": "tsgo --build tsconfig.build.json",
     "test": "vitest run"
   }

package/src/agent.test.ts

@@ -1,216 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import {
-  type Agent,
-  type AgentConfig,
-  type FetchHandler,
-  buildAgent,
-  isAgent,
-} from './agent.js'
-
-// ============================================================================
-// isAgent
-// ============================================================================
-
-describe(isAgent, () => {
-  it('returns true for a valid agent with did', () => {
-    const agent: Agent = {
-      did: 'did:plc:example',
-      fetchHandler: async () => new Response(),
-    }
-    expect(isAgent(agent)).toBe(true)
-  })
-
-  it('returns true for an agent without did', () => {
-    const agent = { fetchHandler: async () => new Response() }
-    expect(isAgent(agent)).toBe(true)
-  })
-
-  it('returns true when did is undefined', () => {
-    const agent = { did: undefined, fetchHandler: async () => new Response() }
-    expect(isAgent(agent)).toBe(true)
-  })
-
-  it('returns false for null', () => {
-    expect(isAgent(null)).toBe(false)
-  })
-
-  it('returns false for non-objects', () => {
-    expect(isAgent('string')).toBe(false)
-    expect(isAgent(42)).toBe(false)
-    expect(isAgent(undefined)).toBe(false)
-  })
-
-  it('returns false when fetchHandler is not a function', () => {
-    expect(isAgent({ fetchHandler: 'not-a-function' })).toBe(false)
-  })
-
-  it('returns false when did is not a string', () => {
-    expect(isAgent({ did: 42, fetchHandler: async () => new Response() })).toBe(
-      false,
-    )
-  })
-})
-
-// ============================================================================
-// buildAgent
-// ============================================================================
-
-describe(buildAgent, () => {
-  describe('from Agent', () => {
-    it('returns the same agent instance', () => {
-      const agent: Agent = {
-        did: 'did:plc:example',
-        fetchHandler: async () => new Response(),
-      }
-      expect(buildAgent(agent)).toBe(agent)
-    })
-  })
-
-  describe('from FetchHandler', () => {
-    it('wraps a function as an agent', () => {
-      const handler: FetchHandler = async () => new Response()
-      const agent = buildAgent(handler)
-
-      expect(agent.did).toBeUndefined()
-      expect(typeof agent.fetchHandler).toBe('function')
-    })
-  })
-
-  describe('from string URL', () => {
-    it('creates an agent that prepends the service URL', async () => {
-      const fetchFn = vi.fn<typeof globalThis.fetch>(async () =>
-        Response.json({ ok: true }),
-      )
-      const agent = buildAgent({
-        service: 'https://example.com',
-        fetch: fetchFn,
-      })
-
-      await agent.fetchHandler('/xrpc/io.example.test', { method: 'GET' })
-
-      expect(fetchFn).toHaveBeenCalledOnce()
-      const [url, init] = fetchFn.mock.calls[0]
-      expect(url).toEqual(
-        new URL('/xrpc/io.example.test', 'https://example.com'),
-      )
-      expect(init?.method).toBe('GET')
-    })
-
-    it('has undefined did', () => {
-      const agent = buildAgent('https://example.com')
-      expect(agent.did).toBeUndefined()
-    })
-  })
-
-  describe('from URL instance', () => {
-    it('creates an agent with the URL as service', async () => {
-      const fetchFn = vi.fn<typeof globalThis.fetch>(async () =>
-        Response.json({ ok: true }),
-      )
-      const agent = buildAgent({
-        service: new URL('https://example.com'),
-        fetch: fetchFn,
-      })
-
-      await agent.fetchHandler('/xrpc/io.example.test', { method: 'GET' })
-
-      expect(fetchFn).toHaveBeenCalledOnce()
-      const [url] = fetchFn.mock.calls[0]
-      expect(url).toEqual(
-        new URL('/xrpc/io.example.test', 'https://example.com'),
-      )
-    })
-  })
-
-  describe('from AgentConfig', () => {
-    it('exposes did from config', () => {
-      const agent = buildAgent({
-        did: 'did:plc:test123',
-        service: 'https://example.com',
-      })
-      expect(agent.did).toBe('did:plc:test123')
-    })
-
-    it('reflects did changes on the config object', () => {
-      const config: AgentConfig = {
-        did: 'did:plc:original',
-        service: 'https://example.com',
-      }
-      const agent = buildAgent(config)
-      expect(agent.did).toBe('did:plc:original')
-
-      config.did = 'did:plc:updated'
-      expect(agent.did).toBe('did:plc:updated')
-    })
-
-    it('throws TypeError when fetch is not available', () => {
-      const originalFetch = globalThis.fetch
-      try {
-        // @ts-expect-error removing fetch to simulate missing environment
-        globalThis.fetch = undefined
-        expect(() => buildAgent({ service: 'https://example.com' })).toThrow(
-          TypeError,
-        )
-      } finally {
-        globalThis.fetch = originalFetch
-      }
-    })
-  })
-
-  describe('headers', () => {
-    it('sends config headers when no request headers', async () => {
-      const fetchFn = vi.fn<typeof globalThis.fetch>(async () =>
-        Response.json({}),
-      )
-      const agent = buildAgent({
-        service: 'https://example.com',
-        headers: { Authorization: 'Bearer token123' },
-        fetch: fetchFn,
-      })
-
-      await agent.fetchHandler('/xrpc/test', { method: 'GET' })
-
-      const [, init] = fetchFn.mock.calls[0]
-      expect(init?.headers).toEqual({ Authorization: 'Bearer token123' })
-    })
-
-    it('sends request headers when no config headers', async () => {
-      const fetchFn = vi.fn<typeof globalThis.fetch>(async () =>
-        Response.json({}),
-      )
-      const agent = buildAgent({
-        service: 'https://example.com',
-        fetch: fetchFn,
-      })
-
-      await agent.fetchHandler('/xrpc/test', {
-        method: 'GET',
-        headers: { 'X-Custom': 'value' },
-      })
-
-      const [, init] = fetchFn.mock.calls[0]
-      expect(init?.headers).toEqual({ 'X-Custom': 'value' })
-    })
-
-    it('merges config and request headers, with request taking priority', async () => {
-      const fetchFn = vi.fn<typeof globalThis.fetch>(async () =>
-        Response.json({}),
-      )
-      const agent = buildAgent({
-        service: 'https://example.com',
-        headers: { Authorization: 'Bearer default', 'X-Default': 'yes' },
-        fetch: fetchFn,
-      })
-
-      await agent.fetchHandler('/xrpc/test', {
-        method: 'GET',
-        headers: { Authorization: 'Bearer override' },
-      })
-
-      const [, init] = fetchFn.mock.calls[0]
-      const headers = new Headers(init?.headers)
-      expect(headers.get('Authorization')).toBe('Bearer override')
-      expect(headers.get('X-Default')).toBe('yes')
-    })
-  })
-})

package/src/agent.ts

@@ -1,186 +0,0 @@
-import { DidString } from '@atproto/lex-schema'
-
-/**
- * A function that performs HTTP requests towards a service endpoint.
- *
- * The handler is responsible for adding the origin (protocol, hostname, and
- * port) to the provided path, typically based on authentication or service
- * configuration. The handler can also be responsible for adding any necessary
- * headers, such as authorization tokens.
- *
- * @param path - The URL path (pathname + query parameters) without the origin
- * @param init - Standard fetch RequestInit options
- * @returns A Promise resolving to the HTTP Response
- */
-export type FetchHandler = (
-  /**
-   * The URL (pathname + query parameters) to make the request to, without the
-   * origin. The origin (protocol, hostname, and port) must be added by this
-   * {@link FetchHandler}, typically based on authentication or other factors.
-   */
-  path: `/${string}`,
-  init: RequestInit,
-) => Promise<Response>
-
-/**
- * Core interface for making XRPC requests towards a specific service.
- *
- * An {@link Agent} encapsulates an identity and request handling for AT
- * Protocol operations. Agents will typically handle authentication, service URL
- * resolution, and other request configuration, allowing client code to make
- * requests without needing to manage these details directly. The key component
- * of an Agent is the {@link FetchHandler}, which is responsible for
- * constructing the full request URL and adding any necessary headers or
- * authentication tokens. The Agent's `did` property represents the
- * authenticated user's DID, if available, and can be used for operations that
- * require knowledge of the user's identity (such as creating AT Protocol
- * records).
- *
- * @see {@link buildAgent} for creating (simple) Agent instances.
- *
- * @example
- * ```typescript
- * const agent: Agent = {
- *   did: 'did:plc:example123',
- *   fetchHandler: async (path, init) => {
- *     const url = new URL(path, 'https://bsky.social')
- *     return fetch(url, init)
- *   }
- * }
- * ```
- */
-export interface Agent {
-  /** The DID of the authenticated user, or `undefined` if unauthenticated. */
-  readonly did?: DidString
-  /** The fetch handler used to make HTTP requests. */
-  fetchHandler: FetchHandler
-}
-
-export function isAgent(value: unknown): value is Agent {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'fetchHandler' in value &&
-    typeof value.fetchHandler === 'function' &&
-    (!('did' in value) ||
-      value.did === undefined ||
-      typeof value.did === 'string')
-  )
-}
-
-export type AgentConfig = {
-  /**
-   * The identifier (DID) of the user represented by this agent.
-   */
-  did?: DidString
-
-  /**
-   * The service URL to make requests to. This can be a string, URL, or a
-   * function that returns a string or URL. This is useful for dynamic URLs,
-   * such as a service URL that changes based on authentication.
-   */
-  service: string | URL
-
-  /**
-   * Optional headers to include with every request made by this agent, unless
-   * overridden by the request-specific headers provided to the fetch handler.
-   */
-  headers?: HeadersInit
-
-  /**
-   * Bring your own fetch implementation. Typically useful for testing, logging,
-   * mocking, or adding retries, session management, signatures, proof of
-   * possession (DPoP), SSRF protection, etc. Defaults to the global `fetch`
-   * function.
-   */
-  fetch?: typeof globalThis.fetch
-}
-
-/**
- * Options for creating an Agent.
- *
- * Can be a full {@link AgentConfig} object, or a simple service URL string/{@link URL}.
- */
-export type AgentOptions = AgentConfig | FetchHandler | string | URL
-
-/**
- * Creates an {@link Agent} from various input types.
- *
- * This factory function accepts an existing Agent (returned as-is), a service
- * URL, or a full configuration object. It handles the common case of creating
- * an unauthenticated agent from just a service URL.
- *
- * @param options - Agent instance, configuration object, or service URL
- * @returns A configured Agent ready for making requests
- * @throws {TypeError} If fetch() is not available in the environment
- *
- * @example // From URL string
- * ```typescript
- * const agent = buildAgent('https://public.api.bsky.app')
- * ```
- *
- * @example // From configuration
- * ```typescript
- * const agent = buildAgent({
- *   did: 'did:plc:example',
- *   service: 'https://bsky.social',
- *   headers: { 'Authorization': 'Bearer ...' }
- * })
- * ```
- */
-export function buildAgent<O extends Agent | AgentOptions>(
-  options: O,
-): O extends Agent ? O : Agent
-export function buildAgent(options: Agent | AgentOptions): Agent {
-  const config: Agent | AgentConfig =
-    typeof options === 'function'
-      ? { did: undefined, fetchHandler: options }
-      : typeof options === 'string' || options instanceof URL
-        ? { did: undefined, service: options }
-        : options
-
-  if (isAgent(config)) return config
-
-  const { service, fetch = globalThis.fetch } = config
-
-  if (typeof fetch !== 'function') {
-    throw new TypeError('fetch() is not available in this environment')
-  }
-
-  return {
-    get did() {
-      return config.did
-    },
-
-    async fetchHandler(path, init) {
-      const headers =
-        config.headers != null && init.headers != null
-          ? mergeHeaders(config.headers, init.headers)
-          : config.headers || init.headers
-
-      return fetch(
-        new URL(path, service),
-        headers !== init.headers ? { ...init, headers } : init,
-      )
-    },
-  }
-}
-
-function mergeHeaders(
-  defaultHeaders: HeadersInit,
-  requestHeaders: HeadersInit,
-): Headers {
-  // We don't want to alter the original Headers objects, so we create a new one
-  const result = new Headers(defaultHeaders)
-
-  const overrides =
-    requestHeaders instanceof Headers
-      ? requestHeaders
-      : new Headers(requestHeaders)
-
-  for (const [key, value] of overrides.entries()) {
-    result.set(key, value)
-  }
-
-  return result
-}