@atproto/lex-client 0.0.11 → 0.0.13

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @atproto/lex-client
 
+## 0.0.13
+
+### Patch Changes
+
+- Updated dependencies [[`39dea03`](https://github.com/bluesky-social/atproto/commit/39dea03c417a1da069962560505427a7aa25ad7a), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df), [`39dea03`](https://github.com/bluesky-social/atproto/commit/39dea03c417a1da069962560505427a7aa25ad7a), [`39dea03`](https://github.com/bluesky-social/atproto/commit/39dea03c417a1da069962560505427a7aa25ad7a), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df), [`39dea03`](https://github.com/bluesky-social/atproto/commit/39dea03c417a1da069962560505427a7aa25ad7a), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df), [`ea5df64`](https://github.com/bluesky-social/atproto/commit/ea5df64db9e408d2b320f5f75eb2878aef6bc6df)]:
+  - @atproto/lex-schema@0.0.13
+  - @atproto/lex-data@0.0.12
+  - @atproto/lex-json@0.0.12
+
+## 0.0.12
+
+### Patch Changes
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add missing exports
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Fix `exports` field in package.json
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add JSDoc
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add JSDoc to `Client` class properties and methods
+
+- Updated dependencies [[`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157), [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015), [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157), [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015)]:
+  - @atproto/lex-schema@0.0.12
+  - @atproto/lex-json@0.0.11
+  - @atproto/lex-data@0.0.11
+
 ## 0.0.11
 
 ### Patch Changes

package/dist/agent.d.ts

@@ -1,4 +1,16 @@
 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 are also 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
@@ -6,8 +18,27 @@ export type FetchHandler = (
  * {@link FetchHandler}, typically based on authentication or other factors.
  */
 path: string, init: RequestInit) => Promise<Response>;
+/**
+ * Core interface for making XRPC requests.
+ *
+ * An Agent encapsulates an identity and request handling for AT Protocol
+ * operations. It can represent an authenticated user session or an
+ * unauthenticated service client.
+ *
+ * @see {@link buildAgent} for creating (simple) Agent instances.
+ *
+ * @example
+ * ```typescript
+ * const agent: Agent = {
+ *   did: 'did:plc:example123',
+ *   fetchHandler: (path, init) => fetch(new URL(path, 'https://bsky.social'), 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 type AgentConfig = {
@@ -34,6 +65,42 @@ export type AgentConfig = {
      */
     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 | 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 ...' }
+ * })
+ * ```
+ *
+ * @example Pass-through existing agent
+ * ```typescript
+ * const existing: Agent = { ... }
+ * const agent = buildAgent(existing) // Returns existing unchanged
+ * ```
+ */
 export declare function buildAgent(options: Agent | AgentOptions): Agent;
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAE/C,MAAM,MAAM,YAAY,GAAG;AACzB;;;;GAIG;AACH,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,KACd,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEtB,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAA;IACxB,YAAY,EAAE,YAAY,CAAA;CAC3B;AAED,MAAM,MAAM,WAAW,GAAG;IACxB;;OAEG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;IAEf;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,GAAG,CAAA;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAA;IAErB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAChC,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,MAAM,GAAG,GAAG,CAAA;AAErD,wBAAgB,UAAU,CAAC,OAAO,EAAE,KAAK,GAAG,YAAY,GAAG,KAAK,CAiC/D"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG;AACzB;;;;GAIG;AACH,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,KACd,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEtB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,KAAK;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAA;IACxB,oDAAoD;IACpD,YAAY,EAAE,YAAY,CAAA;CAC3B;AAED,MAAM,MAAM,WAAW,GAAG;IACxB;;OAEG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;IAEf;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,GAAG,CAAA;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAA;IAErB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAChC,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,MAAM,GAAG,GAAG,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,KAAK,GAAG,YAAY,GAAG,KAAK,CAiC/D"}

package/dist/agent.js

@@ -1,6 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAgent = buildAgent;
+/**
+ * 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 ...' }
+ * })
+ * ```
+ *
+ * @example Pass-through existing agent
+ * ```typescript
+ * const existing: Agent = { ... }
+ * const agent = buildAgent(existing) // Returns existing unchanged
+ * ```
+ */
 function buildAgent(options) {
     if (typeof options === 'object' && 'fetchHandler' in options) {
         return options;

package/dist/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":";;AA+CA,gCAiCC;AAjCD,SAAgB,UAAU,CAAC,OAA6B;IACtD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,cAAc,IAAI,OAAO,EAAE,CAAC;QAC7D,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,MAAM,MAAM,GACV,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,YAAY,GAAG;QACnD,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE;QACtC,CAAC,CAAC,OAAO,CAAA;IAEb,MAAM,EAAE,OAAO,EAAE,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,GAAG,MAAM,CAAA;IAEpD,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAA;IACrE,CAAC;IAED,OAAO;QACL,IAAI,GAAG;YACL,OAAO,MAAM,CAAC,GAAG,CAAA;QACnB,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI;YAC3B,MAAM,OAAO,GACX,MAAM,CAAC,OAAO,IAAI,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI;gBAC5C,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC;gBAC5C,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAA;YAEpC,OAAO,KAAK,CACV,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,EACtB,OAAO,KAAK,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CACvD,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,YAAY,CACnB,cAA2B,EAC3B,cAA2B;IAE3B,8EAA8E;IAC9E,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,cAAc,CAAC,CAAA;IAE1C,MAAM,SAAS,GACb,cAAc,YAAY,OAAO;QAC/B,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,IAAI,OAAO,CAAC,cAAc,CAAC,CAAA;IAEjC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,SAAS,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/C,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IACxB,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC","sourcesContent":["import { DidString } from '@atproto/lex-schema'\n\nexport type FetchHandler = (\n  /**\n   * The URL (pathname + query parameters) to make the request to, without the\n   * origin. The origin (protocol, hostname, and port) must be added by this\n   * {@link FetchHandler}, typically based on authentication or other factors.\n   */\n  path: string,\n  init: RequestInit,\n) => Promise<Response>\n\nexport interface Agent {\n  readonly did?: DidString\n  fetchHandler: FetchHandler\n}\n\nexport type AgentConfig = {\n  /**\n   * The identifier (DID) of the user represented by this agent.\n   */\n  did?: DidString\n\n  /**\n   * The service URL to make requests to. This can be a string, URL, or a\n   * function that returns a string or URL. This is useful for dynamic URLs,\n   * such as a service URL that changes based on authentication.\n   */\n  service: string | URL\n\n  /**\n   * Optional headers to include with every request made by this agent, unless\n   * overridden by the request-specific headers provided to the fetch handler.\n   */\n  headers?: HeadersInit\n\n  /**\n   * Bring your own fetch implementation. Typically useful for testing, logging,\n   * mocking, or adding retries, session management, signatures, proof of\n   * possession (DPoP), SSRF protection, etc. Defaults to the global `fetch`\n   * function.\n   */\n  fetch?: typeof globalThis.fetch\n}\n\nexport type AgentOptions = AgentConfig | string | URL\n\nexport function buildAgent(options: Agent | AgentOptions): Agent {\n  if (typeof options === 'object' && 'fetchHandler' in options) {\n    return options\n  }\n\n  const config: Agent | AgentConfig =\n    typeof options === 'string' || options instanceof URL\n      ? { did: undefined, service: options }\n      : options\n\n  const { service, fetch = globalThis.fetch } = config\n\n  if (typeof fetch !== 'function') {\n    throw new TypeError('fetch() is not available in this environment')\n  }\n\n  return {\n    get did() {\n      return config.did\n    },\n\n    async fetchHandler(path, init) {\n      const headers =\n        config.headers != null && init.headers != null\n          ? mergeHeaders(config.headers, init.headers)\n          : config.headers || init.headers\n\n      return fetch(\n        new URL(path, service),\n        headers !== init.headers ? { ...init, headers } : init,\n      )\n    },\n  }\n}\n\nfunction mergeHeaders(\n  defaultHeaders: HeadersInit,\n  requestHeaders: HeadersInit,\n): Headers {\n  // We don't want to alter the original Headers objects, so we create a new one\n  const result = new Headers(defaultHeaders)\n\n  const overrides =\n    requestHeaders instanceof Headers\n      ? requestHeaders\n      : new Headers(requestHeaders)\n\n  for (const [key, value] of overrides.entries()) {\n    result.set(key, value)\n  }\n\n  return result\n}\n"]}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":";;AAkHA,gCAiCC;AAhED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,SAAgB,UAAU,CAAC,OAA6B;IACtD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,cAAc,IAAI,OAAO,EAAE,CAAC;QAC7D,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,MAAM,MAAM,GACV,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,YAAY,GAAG;QACnD,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE;QACtC,CAAC,CAAC,OAAO,CAAA;IAEb,MAAM,EAAE,OAAO,EAAE,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,GAAG,MAAM,CAAA;IAEpD,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAA;IACrE,CAAC;IAED,OAAO;QACL,IAAI,GAAG;YACL,OAAO,MAAM,CAAC,GAAG,CAAA;QACnB,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI;YAC3B,MAAM,OAAO,GACX,MAAM,CAAC,OAAO,IAAI,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI;gBAC5C,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC;gBAC5C,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAA;YAEpC,OAAO,KAAK,CACV,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,EACtB,OAAO,KAAK,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CACvD,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,YAAY,CACnB,cAA2B,EAC3B,cAA2B;IAE3B,8EAA8E;IAC9E,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,cAAc,CAAC,CAAA;IAE1C,MAAM,SAAS,GACb,cAAc,YAAY,OAAO;QAC/B,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,IAAI,OAAO,CAAC,cAAc,CAAC,CAAA;IAEjC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,SAAS,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/C,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IACxB,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC","sourcesContent":["import { DidString } from '@atproto/lex-schema'\n\n/**\n * A function that performs HTTP requests towards a service endpoint.\n *\n * The handler is responsible for adding the origin (protocol, hostname, and\n * port) to the provided path, typically based on authentication or service\n * configuration. The handler are also responsible for adding any necessary\n * headers, such as authorization tokens.\n *\n * @param path - The URL path (pathname + query parameters) without the origin\n * @param init - Standard fetch RequestInit options\n * @returns A Promise resolving to the HTTP Response\n */\nexport type FetchHandler = (\n  /**\n   * The URL (pathname + query parameters) to make the request to, without the\n   * origin. The origin (protocol, hostname, and port) must be added by this\n   * {@link FetchHandler}, typically based on authentication or other factors.\n   */\n  path: string,\n  init: RequestInit,\n) => Promise<Response>\n\n/**\n * Core interface for making XRPC requests.\n *\n * An Agent encapsulates an identity and request handling for AT Protocol\n * operations. It can represent an authenticated user session or an\n * unauthenticated service client.\n *\n * @see {@link buildAgent} for creating (simple) Agent instances.\n *\n * @example\n * ```typescript\n * const agent: Agent = {\n *   did: 'did:plc:example123',\n *   fetchHandler: (path, init) => fetch(new URL(path, 'https://bsky.social'), init)\n * }\n * ```\n */\nexport interface Agent {\n  /** The DID of the authenticated user, or `undefined` if unauthenticated. */\n  readonly did?: DidString\n  /** The fetch handler used to make HTTP requests. */\n  fetchHandler: FetchHandler\n}\n\nexport type AgentConfig = {\n  /**\n   * The identifier (DID) of the user represented by this agent.\n   */\n  did?: DidString\n\n  /**\n   * The service URL to make requests to. This can be a string, URL, or a\n   * function that returns a string or URL. This is useful for dynamic URLs,\n   * such as a service URL that changes based on authentication.\n   */\n  service: string | URL\n\n  /**\n   * Optional headers to include with every request made by this agent, unless\n   * overridden by the request-specific headers provided to the fetch handler.\n   */\n  headers?: HeadersInit\n\n  /**\n   * Bring your own fetch implementation. Typically useful for testing, logging,\n   * mocking, or adding retries, session management, signatures, proof of\n   * possession (DPoP), SSRF protection, etc. Defaults to the global `fetch`\n   * function.\n   */\n  fetch?: typeof globalThis.fetch\n}\n\n/**\n * Options for creating an Agent.\n *\n * Can be a full {@link AgentConfig} object, or a simple service URL string/{@link URL}.\n */\nexport type AgentOptions = AgentConfig | string | URL\n\n/**\n * Creates an {@link Agent} from various input types.\n *\n * This factory function accepts an existing Agent (returned as-is), a service URL,\n * or a full configuration object. It handles the common case of creating an\n * unauthenticated agent from just a service URL.\n *\n * @param options - Agent instance, configuration object, or service URL\n * @returns A configured Agent ready for making requests\n * @throws {TypeError} If fetch() is not available in the environment\n *\n * @example From URL string\n * ```typescript\n * const agent = buildAgent('https://public.api.bsky.app')\n * ```\n *\n * @example From configuration\n * ```typescript\n * const agent = buildAgent({\n *   did: 'did:plc:example',\n *   service: 'https://bsky.social',\n *   headers: { 'Authorization': 'Bearer ...' }\n * })\n * ```\n *\n * @example Pass-through existing agent\n * ```typescript\n * const existing: Agent = { ... }\n * const agent = buildAgent(existing) // Returns existing unchanged\n * ```\n */\nexport function buildAgent(options: Agent | AgentOptions): Agent {\n  if (typeof options === 'object' && 'fetchHandler' in options) {\n    return options\n  }\n\n  const config: Agent | AgentConfig =\n    typeof options === 'string' || options instanceof URL\n      ? { did: undefined, service: options }\n      : options\n\n  const { service, fetch = globalThis.fetch } = config\n\n  if (typeof fetch !== 'function') {\n    throw new TypeError('fetch() is not available in this environment')\n  }\n\n  return {\n    get did() {\n      return config.did\n    },\n\n    async fetchHandler(path, init) {\n      const headers =\n        config.headers != null && init.headers != null\n          ? mergeHeaders(config.headers, init.headers)\n          : config.headers || init.headers\n\n      return fetch(\n        new URL(path, service),\n        headers !== init.headers ? { ...init, headers } : init,\n      )\n    },\n  }\n}\n\nfunction mergeHeaders(\n  defaultHeaders: HeadersInit,\n  requestHeaders: HeadersInit,\n): Headers {\n  // We don't want to alter the original Headers objects, so we create a new one\n  const result = new Headers(defaultHeaders)\n\n  const overrides =\n    requestHeaders instanceof Headers\n      ? requestHeaders\n      : new Headers(requestHeaders)\n\n  for (const [key, value] of overrides.entries()) {\n    result.set(key, value)\n  }\n\n  return result\n}\n"]}