@atproto/lex-client 0.0.0-spaces-alpha-20260818021221

package/dist/agent.d.ts

@@ -0,0 +1,127 @@
+import type { 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 declare function isAgent(value: unknown): value is Agent;
+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;
+    fetchHandler?: never;
+};
+/**
+ * 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 ...' }
+ * })
+ * ```
+ *
+ * @example // From existing Agent
+ * ```typescript
+ * const existingAgent: Agent = { ... }
+ * const agent = buildAgent(existingAgent)
+ * ```
+ *
+ * @example // From agent like object with fetchHandler
+ * ```typescript
+ * const agent = buildAgent({
+ *   did: 'did:plc:example',
+ *   fetchHandler: async (path, init) => { ... }
+ *   // @NOTE "headers" and "service" are not allowed when providing a fetchHandler, because the input will returned "as is" if it matched the "Agent" interface.
+ * })
+ * ```
+ */
+export declare function buildAgent<O extends Agent | AgentOptions>(options: O): O extends Agent ? O : Agent;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAGpD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG;AACzB;;;;GAIG;AACH,IAAI,EAAE,IAAI,MAAM,EAAE,EAClB,IAAI,EAAE,WAAW,KACd,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,KAAK;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAA;IACxB,oDAAoD;IACpD,YAAY,EAAE,YAAY,CAAA;CAC3B;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAUtD;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;IAK/B,YAAY,CAAC,EAAE,KAAK,CAAA;CACrB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,YAAY,GAAG,MAAM,GAAG,GAAG,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,KAAK,GAAG,YAAY,EACvD,OAAO,EAAE,CAAC,GACT,CAAC,SAAS,KAAK,GAAG,CAAC,GAAG,KAAK,CAAA"}

package/dist/agent.js

@@ -0,0 +1,41 @@
+import { mergeHeaders } from './util.js';
+export function isAgent(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'fetchHandler' in value &&
+        typeof value.fetchHandler === 'function' &&
+        (!('did' in value) ||
+            value.did === undefined ||
+            typeof value.did === 'string'));
+}
+export function buildAgent(options) {
+    if (typeof options === 'function') {
+        return { did: undefined, fetchHandler: options };
+    }
+    const config = typeof options === 'string' || options instanceof URL
+        ? { did: undefined, service: options }
+        : options;
+    // Prevent mismatch between `fetchHandler` and `headers` in the config, since
+    // `headers` would be ignored if `fetchHandler` is provided.
+    if ('fetchHandler' in config) {
+        if (isAgent(config))
+            return config;
+        throw new TypeError('fetchHandler must not be provided when using AgentConfig');
+    }
+    const { did, service, fetch = globalThis.fetch, headers: defaultHeaders, } = config;
+    if (typeof fetch !== 'function') {
+        throw new TypeError('fetch() is not available in this environment');
+    }
+    return {
+        get did() {
+            return did;
+        },
+        async fetchHandler(path, init) {
+            const headers = defaultHeaders != null && init.headers != null
+                ? mergeHeaders(defaultHeaders, init.headers)
+                : defaultHeaders || init.headers;
+            return fetch(new URL(path, service), headers !== init.headers ? { ...init, headers } : init);
+        },
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AA0DxC,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,cAAc,IAAI,KAAK;QACvB,OAAO,KAAK,CAAC,YAAY,KAAK,UAAU;QACxC,CAAC,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC;YAChB,KAAK,CAAC,GAAG,KAAK,SAAS;YACvB,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,CACjC,CAAA;AACH,CAAC;AAqFD,MAAM,UAAU,UAAU,CAAC,OAA6B;IACtD,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,CAAA;IAClD,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,6EAA6E;IAC7E,4DAA4D;IAC5D,IAAI,cAAc,IAAI,MAAM,EAAE,CAAC;QAC7B,IAAI,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAA;QAElC,MAAM,IAAI,SAAS,CACjB,0DAA0D,CAC3D,CAAA;IACH,CAAC;IAED,MAAM,EACJ,GAAG,EACH,OAAO,EACP,KAAK,GAAG,UAAU,CAAC,KAAK,EACxB,OAAO,EAAE,cAAc,GACxB,GAAG,MAAM,CAAA;IAEV,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAA;IACrE,CAAC;IAED,OAAO;QACL,IAAI,GAAG;YACL,OAAO,GAAG,CAAA;QACZ,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI;YAC3B,MAAM,OAAO,GACX,cAAc,IAAI,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI;gBAC5C,CAAC,CAAC,YAAY,CAAC,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC;gBAC5C,CAAC,CAAC,cAAc,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","sourcesContent":["import type { DidString } from '@atproto/lex-schema'\nimport { mergeHeaders } from './util.js'\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 can also be 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 towards a specific service.\n *\n * An {@link Agent} encapsulates an identity and request handling for AT\n * Protocol operations. Agents will typically handle authentication, service URL\n * resolution, and other request configuration, allowing client code to make\n * requests without needing to manage these details directly. The key component\n * of an Agent is the {@link FetchHandler}, which is responsible for\n * constructing the full request URL and adding any necessary headers or\n * authentication tokens. The Agent's `did` property represents the\n * authenticated user's DID, if available, and can be used for operations that\n * require knowledge of the user's identity (such as creating AT Protocol\n * records).\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: async (path, init) => {\n *     const url = new URL(path, 'https://bsky.social')\n *     return fetch(url, init)\n *   }\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 function isAgent(value: unknown): value is Agent {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'fetchHandler' in value &&\n    typeof value.fetchHandler === 'function' &&\n    (!('did' in value) ||\n      value.did === undefined ||\n      typeof value.did === 'string')\n  )\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  // Because this type get unioned with `Agent`, we need to prevent TypeScript\n  // from accepting `headers` when `fetchHandler` is provided, since `headers`\n  // would not be used (while the user might expect it to be).\n  fetchHandler?: never\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 | FetchHandler | 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\n * URL, or a full configuration object. It handles the common case of creating\n * an 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 // From existing Agent\n * ```typescript\n * const existingAgent: Agent = { ... }\n * const agent = buildAgent(existingAgent)\n * ```\n *\n * @example // From agent like object with fetchHandler\n * ```typescript\n * const agent = buildAgent({\n *   did: 'did:plc:example',\n *   fetchHandler: async (path, init) => { ... }\n *   // @NOTE \"headers\" and \"service\" are not allowed when providing a fetchHandler, because the input will returned \"as is\" if it matched the \"Agent\" interface.\n * })\n * ```\n */\nexport function buildAgent<O extends Agent | AgentOptions>(\n  options: O,\n): O extends Agent ? O : Agent\nexport function buildAgent(options: Agent | AgentOptions): Agent {\n  if (typeof options === 'function') {\n    return { did: undefined, fetchHandler: options }\n  }\n\n  const config: Agent | AgentConfig =\n    typeof options === 'string' || options instanceof URL\n      ? { did: undefined, service: options }\n      : options\n\n  // Prevent mismatch between `fetchHandler` and `headers` in the config, since\n  // `headers` would be ignored if `fetchHandler` is provided.\n  if ('fetchHandler' in config) {\n    if (isAgent(config)) return config\n\n    throw new TypeError(\n      'fetchHandler must not be provided when using AgentConfig',\n    )\n  }\n\n  const {\n    did,\n    service,\n    fetch = globalThis.fetch,\n    headers: defaultHeaders,\n  } = 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 did\n    },\n\n    async fetchHandler(path, init) {\n      const headers =\n        defaultHeaders != null && init.headers != null\n          ? mergeHeaders(defaultHeaders, init.headers)\n          : defaultHeaders || init.headers\n\n      return fetch(\n        new URL(path, service),\n        headers !== init.headers ? { ...init, headers } : init,\n      )\n    },\n  }\n}\n"]}