@atproto/lex-resolver 0.0.13 → 0.0.14

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @atproto/lex-resolver
 
+## 0.0.14
+
+### 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)! - 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
+
+- Updated dependencies [[`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157), [`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), [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157), [`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), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015)]:
+  - @atproto/lex-schema@0.0.12
+  - @atproto/lex-document@0.0.13
+  - @atproto/lex-client@0.0.12
+  - @atproto/lex-data@0.0.11
+
 ## 0.0.13
 
 ### Patch Changes

package/dist/lex-resolver-error.d.ts

@@ -1,9 +1,106 @@
+import { LexError } from '@atproto/lex-data';
 import { NSID } from '@atproto/syntax';
-export declare class LexResolverError extends Error {
+/**
+ * Error class for lexicon resolution failures.
+ *
+ * This error is thrown when the {@link LexResolver} encounters issues during
+ * the resolution process, such as DNS lookup failures, DID resolution errors,
+ * invalid lexicon documents, or network failures.
+ *
+ * @example Catching resolution errors
+ * ```typescript
+ * import { LexResolver, LexResolverError } from '@atproto/lex-resolver'
+ *
+ * const resolver = new LexResolver({})
+ *
+ * try {
+ *   const result = await resolver.get('com.example.myLexicon')
+ * } catch (error) {
+ *   if (error instanceof LexResolverError) {
+ *     console.error(`Failed to resolve ${error.nsid}: ${error.description}`)
+ *     // Access the original cause if available
+ *     if (error.cause) {
+ *       console.error('Caused by:', error.cause)
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Creating errors with the factory method
+ * ```typescript
+ * import { LexResolverError } from '@atproto/lex-resolver'
+ *
+ * // Create from string NSID
+ * const error = LexResolverError.from(
+ *   'com.example.myLexicon',
+ *   'Custom error description'
+ * )
+ * ```
+ */
+export declare class LexResolverError extends LexError {
+    /**
+     * The NSID that failed to resolve.
+     */
     readonly nsid: NSID;
+    /**
+     * Human-readable description of what went wrong during resolution.
+     */
     readonly description: string;
     name: string;
-    constructor(nsid: NSID, description?: string, options?: ErrorOptions);
+    /**
+     * Creates a new LexResolverError instance.
+     *
+     * @param nsid - The NSID that failed to resolve
+     * @param description - Human-readable description of the error. Defaults to
+     *   a generic message if not provided.
+     * @param options - Standard error options including `cause` for error chaining
+     *
+     * @example
+     * ```typescript
+     * import { NSID } from '@atproto/syntax'
+     * import { LexResolverError } from '@atproto/lex-resolver'
+     *
+     * const nsid = NSID.from('com.example.myLexicon')
+     * const error = new LexResolverError(
+     *   nsid,
+     *   'DNS lookup failed',
+     *   { cause: originalError }
+     * )
+     * ```
+     */
+    constructor(
+    /**
+     * The NSID that failed to resolve.
+     */
+    nsid: NSID, 
+    /**
+     * Human-readable description of what went wrong during resolution.
+     */
+    description?: string, options?: ErrorOptions);
+    /**
+     * Factory method to create a LexResolverError from a string or NSID.
+     *
+     * This is a convenience method that handles the conversion of string NSIDs
+     * to NSID objects automatically.
+     *
+     * @param nsid - The NSID as a string or NSID object
+     * @param description - Optional human-readable description of the error
+     * @returns A new LexResolverError instance
+     *
+     * @example
+     * ```typescript
+     * import { LexResolverError } from '@atproto/lex-resolver'
+     *
+     * // Create from string
+     * const error1 = LexResolverError.from('com.example.myLexicon')
+     *
+     * // Create with description
+     * const error2 = LexResolverError.from(
+     *   'com.example.myLexicon',
+     *   'Authority not found in DNS'
+     * )
+     * ```
+     */
     static from(nsid: NSID | string, description?: string): LexResolverError;
 }
 //# sourceMappingURL=lex-resolver-error.d.ts.map

package/dist/lex-resolver-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lex-resolver-error.d.ts","sourceRoot":"","sources":["../src/lex-resolver-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEtC,qBAAa,gBAAiB,SAAQ,KAAK;aAIvB,IAAI,EAAE,IAAI;aACV,WAAW;IAJ7B,IAAI,SAAqB;gBAGP,IAAI,EAAE,IAAI,EACV,WAAW,SAAuC,EAClE,OAAO,CAAC,EAAE,YAAY;IAKxB,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAMtD"}
+{"version":3,"file":"lex-resolver-error.d.ts","sourceRoot":"","sources":["../src/lex-resolver-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;IAyB1C;;OAEG;aACa,IAAI,EAAE,IAAI;IAC1B;;OAEG;aACa,WAAW;IA/B7B,IAAI,SAAqB;IAEzB;;;;;;;;;;;;;;;;;;;;OAoBG;;IAED;;OAEG;IACa,IAAI,EAAE,IAAI;IAC1B;;OAEG;IACa,WAAW,SAAuC,EAClE,OAAO,CAAC,EAAE,YAAY;IAKxB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAMtD"}

package/dist/lex-resolver-error.js

@@ -1,16 +1,107 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LexResolverError = void 0;
+const lex_data_1 = require("@atproto/lex-data");
 const syntax_1 = require("@atproto/syntax");
-class LexResolverError extends Error {
+/**
+ * Error class for lexicon resolution failures.
+ *
+ * This error is thrown when the {@link LexResolver} encounters issues during
+ * the resolution process, such as DNS lookup failures, DID resolution errors,
+ * invalid lexicon documents, or network failures.
+ *
+ * @example Catching resolution errors
+ * ```typescript
+ * import { LexResolver, LexResolverError } from '@atproto/lex-resolver'
+ *
+ * const resolver = new LexResolver({})
+ *
+ * try {
+ *   const result = await resolver.get('com.example.myLexicon')
+ * } catch (error) {
+ *   if (error instanceof LexResolverError) {
+ *     console.error(`Failed to resolve ${error.nsid}: ${error.description}`)
+ *     // Access the original cause if available
+ *     if (error.cause) {
+ *       console.error('Caused by:', error.cause)
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Creating errors with the factory method
+ * ```typescript
+ * import { LexResolverError } from '@atproto/lex-resolver'
+ *
+ * // Create from string NSID
+ * const error = LexResolverError.from(
+ *   'com.example.myLexicon',
+ *   'Custom error description'
+ * )
+ * ```
+ */
+class LexResolverError extends lex_data_1.LexError {
     nsid;
     description;
     name = 'LexResolverError';
-    constructor(nsid, description = `Could not resolve Lexicon for NSID`, options) {
-        super(`${description} (${nsid})`, options);
+    /**
+     * Creates a new LexResolverError instance.
+     *
+     * @param nsid - The NSID that failed to resolve
+     * @param description - Human-readable description of the error. Defaults to
+     *   a generic message if not provided.
+     * @param options - Standard error options including `cause` for error chaining
+     *
+     * @example
+     * ```typescript
+     * import { NSID } from '@atproto/syntax'
+     * import { LexResolverError } from '@atproto/lex-resolver'
+     *
+     * const nsid = NSID.from('com.example.myLexicon')
+     * const error = new LexResolverError(
+     *   nsid,
+     *   'DNS lookup failed',
+     *   { cause: originalError }
+     * )
+     * ```
+     */
+    constructor(
+    /**
+     * The NSID that failed to resolve.
+     */
+    nsid, 
+    /**
+     * Human-readable description of what went wrong during resolution.
+     */
+    description = `Could not resolve Lexicon for NSID`, options) {
+        super('LexiconResolutionFailure', `${description} (${nsid})`, options);
         this.nsid = nsid;
         this.description = description;
     }
+    /**
+     * Factory method to create a LexResolverError from a string or NSID.
+     *
+     * This is a convenience method that handles the conversion of string NSIDs
+     * to NSID objects automatically.
+     *
+     * @param nsid - The NSID as a string or NSID object
+     * @param description - Optional human-readable description of the error
+     * @returns A new LexResolverError instance
+     *
+     * @example
+     * ```typescript
+     * import { LexResolverError } from '@atproto/lex-resolver'
+     *
+     * // Create from string
+     * const error1 = LexResolverError.from('com.example.myLexicon')
+     *
+     * // Create with description
+     * const error2 = LexResolverError.from(
+     *   'com.example.myLexicon',
+     *   'Authority not found in DNS'
+     * )
+     * ```
+     */
     static from(nsid, description) {
         return new LexResolverError(typeof nsid === 'string' ? syntax_1.NSID.from(nsid) : nsid, description);
     }

package/dist/lex-resolver-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"lex-resolver-error.js","sourceRoot":"","sources":["../src/lex-resolver-error.ts"],"names":[],"mappings":";;;AAAA,4CAAsC;AAEtC,MAAa,gBAAiB,SAAQ,KAAK;IAIvB;IACA;IAJlB,IAAI,GAAG,kBAAkB,CAAA;IAEzB,YACkB,IAAU,EACV,cAAc,oCAAoC,EAClE,OAAsB;QAEtB,KAAK,CAAC,GAAG,WAAW,KAAK,IAAI,GAAG,EAAE,OAAO,CAAC,CAAA;QAJ1B,SAAI,GAAJ,IAAI,CAAM;QACV,gBAAW,GAAX,WAAW,CAAuC;IAIpE,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,IAAmB,EAAE,WAAoB;QACnD,OAAO,IAAI,gBAAgB,CACzB,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EACjD,WAAW,CACZ,CAAA;IACH,CAAC;CACF;AAjBD,4CAiBC","sourcesContent":["import { NSID } from '@atproto/syntax'\n\nexport class LexResolverError extends Error {\n  name = 'LexResolverError'\n\n  constructor(\n    public readonly nsid: NSID,\n    public readonly description = `Could not resolve Lexicon for NSID`,\n    options?: ErrorOptions,\n  ) {\n    super(`${description} (${nsid})`, options)\n  }\n\n  static from(nsid: NSID | string, description?: string) {\n    return new LexResolverError(\n      typeof nsid === 'string' ? NSID.from(nsid) : nsid,\n      description,\n    )\n  }\n}\n"]}
+{"version":3,"file":"lex-resolver-error.js","sourceRoot":"","sources":["../src/lex-resolver-error.ts"],"names":[],"mappings":";;;AAAA,gDAA4C;AAC5C,4CAAsC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAa,gBAAiB,SAAQ,mBAAQ;IA4B1B;IAIA;IA/BlB,IAAI,GAAG,kBAAkB,CAAA;IAEzB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH;IACE;;OAEG;IACa,IAAU;IAC1B;;OAEG;IACa,cAAc,oCAAoC,EAClE,OAAsB;QAEtB,KAAK,CAAC,0BAA0B,EAAE,GAAG,WAAW,KAAK,IAAI,GAAG,EAAE,OAAO,CAAC,CAAA;QAPtD,SAAI,GAAJ,IAAI,CAAM;QAIV,gBAAW,GAAX,WAAW,CAAuC;IAIpE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,IAAI,CAAC,IAAmB,EAAE,WAAoB;QACnD,OAAO,IAAI,gBAAgB,CACzB,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EACjD,WAAW,CACZ,CAAA;IACH,CAAC;CACF;AApED,4CAoEC","sourcesContent":["import { LexError } from '@atproto/lex-data'\nimport { NSID } from '@atproto/syntax'\n\n/**\n * Error class for lexicon resolution failures.\n *\n * This error is thrown when the {@link LexResolver} encounters issues during\n * the resolution process, such as DNS lookup failures, DID resolution errors,\n * invalid lexicon documents, or network failures.\n *\n * @example Catching resolution errors\n * ```typescript\n * import { LexResolver, LexResolverError } from '@atproto/lex-resolver'\n *\n * const resolver = new LexResolver({})\n *\n * try {\n *   const result = await resolver.get('com.example.myLexicon')\n * } catch (error) {\n *   if (error instanceof LexResolverError) {\n *     console.error(`Failed to resolve ${error.nsid}: ${error.description}`)\n *     // Access the original cause if available\n *     if (error.cause) {\n *       console.error('Caused by:', error.cause)\n *     }\n *   }\n * }\n * ```\n *\n * @example Creating errors with the factory method\n * ```typescript\n * import { LexResolverError } from '@atproto/lex-resolver'\n *\n * // Create from string NSID\n * const error = LexResolverError.from(\n *   'com.example.myLexicon',\n *   'Custom error description'\n * )\n * ```\n */\nexport class LexResolverError extends LexError {\n  name = 'LexResolverError'\n\n  /**\n   * Creates a new LexResolverError instance.\n   *\n   * @param nsid - The NSID that failed to resolve\n   * @param description - Human-readable description of the error. Defaults to\n   *   a generic message if not provided.\n   * @param options - Standard error options including `cause` for error chaining\n   *\n   * @example\n   * ```typescript\n   * import { NSID } from '@atproto/syntax'\n   * import { LexResolverError } from '@atproto/lex-resolver'\n   *\n   * const nsid = NSID.from('com.example.myLexicon')\n   * const error = new LexResolverError(\n   *   nsid,\n   *   'DNS lookup failed',\n   *   { cause: originalError }\n   * )\n   * ```\n   */\n  constructor(\n    /**\n     * The NSID that failed to resolve.\n     */\n    public readonly nsid: NSID,\n    /**\n     * Human-readable description of what went wrong during resolution.\n     */\n    public readonly description = `Could not resolve Lexicon for NSID`,\n    options?: ErrorOptions,\n  ) {\n    super('LexiconResolutionFailure', `${description} (${nsid})`, options)\n  }\n\n  /**\n   * Factory method to create a LexResolverError from a string or NSID.\n   *\n   * This is a convenience method that handles the conversion of string NSIDs\n   * to NSID objects automatically.\n   *\n   * @param nsid - The NSID as a string or NSID object\n   * @param description - Optional human-readable description of the error\n   * @returns A new LexResolverError instance\n   *\n   * @example\n   * ```typescript\n   * import { LexResolverError } from '@atproto/lex-resolver'\n   *\n   * // Create from string\n   * const error1 = LexResolverError.from('com.example.myLexicon')\n   *\n   * // Create with description\n   * const error2 = LexResolverError.from(\n   *   'com.example.myLexicon',\n   *   'Authority not found in DNS'\n   * )\n   * ```\n   */\n  static from(nsid: NSID | string, description?: string) {\n    return new LexResolverError(\n      typeof nsid === 'string' ? NSID.from(nsid) : nsid,\n      description,\n    )\n  }\n}\n"]}

package/dist/lex-resolver.d.ts

@@ -2,30 +2,105 @@ import { Cid } from '@atproto/lex-data';
 import { LexiconDocument } from '@atproto/lex-document';
 import { AtUri, NSID } from '@atproto/syntax';
 import { CreateDidResolverOptions, Did, DidResolver, ResolveDidOptions } from '@atproto-labs/did-resolver';
+/**
+ * Result returned when successfully resolving a lexicon document.
+ *
+ * Contains the full AT URI where the lexicon was found, the content-addressed
+ * identifier (CID) for integrity verification, and the parsed lexicon document.
+ */
 export type LexResolverResult = {
+    /** The AT URI where the lexicon document was found */
     uri: AtUri;
+    /** Content identifier (CID) of the lexicon record for integrity verification */
     cid: Cid;
+    /** The parsed and validated lexicon document */
     lexicon: LexiconDocument;
 };
+/**
+ * Result returned when fetching a lexicon document from a specific URI.
+ *
+ * This is a subset of {@link LexResolverResult} used internally and by hooks,
+ * containing only the CID and lexicon document (without the URI, which is
+ * already known from the fetch request).
+ */
 export type LexResolverFetchResult = {
+    /** Content identifier (CID) of the lexicon record */
     cid: Cid;
+    /** The parsed and validated lexicon document */
     lexicon: LexiconDocument;
 };
-type Awaitable<T> = T | Promise<T>;
+export type Awaitable<T> = T | Promise<T>;
+/**
+ * Callback hooks for customizing the lexicon resolution process.
+ *
+ * Hooks allow you to intercept, cache, or override the default resolution
+ * behavior at various stages. Each hook can be synchronous or asynchronous.
+ *
+ * @example Implementing a cache with hooks
+ * ```typescript
+ * import { LexResolver, LexResolverHooks, LexResolverFetchResult } from '@atproto/lex-resolver'
+ * import { AtUri } from '@atproto/syntax'
+ *
+ * const cache = new Map<string, LexResolverFetchResult>()
+ *
+ * const hooks: LexResolverHooks = {
+ *   // Return cached result if available, bypassing network fetch
+ *   onFetch({ uri }) {
+ *     return cache.get(uri.toString())
+ *   },
+ *   // Cache successful fetches
+ *   onFetchResult({ uri, cid, lexicon }) {
+ *     cache.set(uri.toString(), { cid, lexicon })
+ *   },
+ *   // Log errors for monitoring
+ *   onFetchError({ uri, err }) {
+ *     console.error(`Failed to fetch ${uri}:`, err)
+ *   }
+ * }
+ *
+ * const resolver = new LexResolver({ hooks })
+ * ```
+ *
+ * @example Overriding authority resolution for testing
+ * ```typescript
+ * const hooks: LexResolverHooks = {
+ *   // Always resolve to a test DID
+ *   onResolveAuthority({ nsid }) {
+ *     if (nsid.authority === 'test.example') {
+ *       return 'did:plc:test123'
+ *     }
+ *     // Return undefined to use default resolution
+ *   }
+ * }
+ * ```
+ */
 export type LexResolverHooks = {
     /**
      * Hook called before resolving a lexicon authority DID. If a DID is returned,
      * it will be used instead of performing the default resolution. In that case,
      * the `onResolveAuthorityResult` and `onResolveAuthorityError` hooks will
      * not be called.
+     *
+     * @param data - Object containing the NSID being resolved
+     * @returns A DID to use instead of default resolution, or void/undefined to proceed normally
      */
     onResolveAuthority?(data: {
         nsid: NSID;
     }): Awaitable<void | Did>;
+    /**
+     * Hook called after successfully resolving a lexicon authority DID.
+     *
+     * @param data - Object containing the NSID and resolved DID
+     */
     onResolveAuthorityResult?(data: {
         nsid: NSID;
         did: Did;
     }): Awaitable<void>;
+    /**
+     * Hook called when authority resolution fails.
+     *
+     * @param data - Object containing the NSID and error that occurred
+     */
     onResolveAuthorityError?(data: {
         nsid: NSID;
         err: unknown;
@@ -34,32 +109,220 @@ export type LexResolverHooks = {
      * Hook called before fetching a lexicon URI. If a result is returned, it will
      * be used instead of performing the default fetch. In that case, the
      * `onFetchResult` and `onFetchError` hooks will not be called.
+     *
+     * @param data - Object containing the URI being fetched
+     * @returns A fetch result to use instead of default fetch, or void/undefined to proceed normally
      */
     onFetch?(data: {
         uri: AtUri;
     }): Awaitable<void | LexResolverFetchResult>;
+    /**
+     * Hook called after successfully fetching a lexicon document.
+     *
+     * @param data - Object containing the URI, CID, and parsed lexicon document
+     */
     onFetchResult?(data: {
         uri: AtUri;
         cid: Cid;
         lexicon: LexiconDocument;
     }): Awaitable<void>;
+    /**
+     * Hook called when fetching fails.
+     *
+     * @param data - Object containing the URI and error that occurred
+     */
     onFetchError?(data: {
         uri: AtUri;
         err: unknown;
     }): Awaitable<void>;
 };
+/**
+ * Configuration options for the {@link LexResolver}.
+ *
+ * Extends DID resolver options with lexicon-specific hooks for customizing
+ * the resolution process.
+ *
+ * @see {@link CreateDidResolverOptions} for DID resolver configuration
+ */
 export type LexResolverOptions = CreateDidResolverOptions & {
+    /**
+     * Optional hooks for customizing the resolution process.
+     * See {@link LexResolverHooks} for available callbacks.
+     */
     hooks?: LexResolverHooks;
 };
 export { AtUri, type Cid, NSID };
 export type { LexiconDocument, ResolveDidOptions };
+/**
+ * Resolves Lexicon documents from the AT Protocol network.
+ *
+ * The {@link LexResolver} handles the complete process of resolving a lexicon
+ * by NSID:
+ * 1. **Authority Resolution**: Looks up the `_lexicon.<authority>` DNS TXT record
+ *    to find the DID that controls lexicons for that namespace
+ * 2. **DID Resolution**: Resolves the DID document to find the PDS endpoint and
+ *    signing key
+ * 3. **Record Fetch**: Fetches the lexicon record from the PDS with cryptographic
+ *    proof verification
+ * 4. **Validation**: Validates the lexicon document structure
+ *
+ * @example Basic usage - resolve a lexicon by NSID
+ * ```typescript
+ * import { LexResolver } from '@atproto/lex-resolver'
+ *
+ * const resolver = new LexResolver({})
+ *
+ * // Get a lexicon document by its NSID
+ * const result = await resolver.get('app.bsky.feed.post')
+ * console.log(result.lexicon) // The parsed lexicon document
+ * console.log(result.uri)     // AT URI where it was found
+ * console.log(result.cid)     // Content identifier for verification
+ * ```
+ *
+ * @example Two-step resolution for more control
+ * ```typescript
+ * import { LexResolver } from '@atproto/lex-resolver'
+ *
+ * const resolver = new LexResolver({})
+ *
+ * // Step 1: Resolve the authority to get the AT URI
+ * const uri = await resolver.resolve('app.bsky.feed.post')
+ * console.log(uri.toString()) // 'at://did:plc:xxx/com.atproto.lexicon.schema/app.bsky.feed.post'
+ *
+ * // Step 2: Fetch the lexicon from the URI
+ * const result = await resolver.fetch(uri)
+ * console.log(result.lexicon)
+ * ```
+ *
+ * @example Using hooks for caching
+ * ```typescript
+ * import { LexResolver, LexResolverFetchResult } from '@atproto/lex-resolver'
+ *
+ * const cache = new Map<string, LexResolverFetchResult>()
+ *
+ * const resolver = new LexResolver({
+ *   hooks: {
+ *     onFetch({ uri }) {
+ *       return cache.get(uri.toString())
+ *     },
+ *     onFetchResult({ uri, cid, lexicon }) {
+ *       cache.set(uri.toString(), { cid, lexicon })
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * import { LexResolver, LexResolverError } from '@atproto/lex-resolver'
+ *
+ * const resolver = new LexResolver({})
+ *
+ * try {
+ *   const result = await resolver.get('com.example.unknown')
+ * } catch (error) {
+ *   if (error instanceof LexResolverError) {
+ *     console.error(`Failed to resolve ${error.nsid}: ${error.description}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class LexResolver {
     protected readonly options: LexResolverOptions;
     protected readonly didResolver: DidResolver<'plc' | 'web'>;
     constructor(options: LexResolverOptions);
+    /**
+     * Gets a lexicon document by its NSID.
+     *
+     * This is the primary method for resolving lexicons. It combines
+     * {@link resolve} and {@link fetch} into a single operation, handling
+     * authority resolution, DID lookup, and record fetching.
+     *
+     * @param nsidStr - The NSID to resolve, either as a string or NSID object
+     * @param options - Optional DID resolution options (e.g., signal for cancellation)
+     * @returns The resolved lexicon result containing URI, CID, and lexicon document
+     * @throws {LexResolverError} If resolution fails at any stage
+     *
+     * @example
+     * ```typescript
+     * // Resolve using string NSID
+     * const result = await resolver.get('app.bsky.feed.post')
+     *
+     * // Resolve using NSID object
+     * import { NSID } from '@atproto/syntax'
+     * const nsid = NSID.from('app.bsky.feed.post')
+     * const result = await resolver.get(nsid)
+     *
+     * // With abort signal for cancellation
+     * const controller = new AbortController()
+     * const result = await resolver.get('app.bsky.feed.post', {
+     *   signal: controller.signal
+     * })
+     * ```
+     */
     get(nsidStr: NSID | string, options?: ResolveDidOptions): Promise<LexResolverResult>;
+    /**
+     * Resolves the authority for an NSID and returns the AT URI for the lexicon.
+     *
+     * This method performs the first stage of lexicon resolution:
+     * 1. Parses the NSID to extract the authority domain
+     * 2. Looks up the `_lexicon.<authority>` DNS TXT record
+     * 3. Extracts the DID from the TXT record (format: `did=<did>`)
+     * 4. Constructs the AT URI for the lexicon record
+     *
+     * Use this when you need the URI without fetching the actual document,
+     * or when you want to implement custom fetching logic.
+     *
+     * @param nsidStr - The NSID to resolve, either as a string or NSID object
+     * @returns The AT URI pointing to the lexicon record
+     * @throws {LexResolverError} If authority resolution fails (e.g., DNS lookup fails)
+     *
+     * @example
+     * ```typescript
+     * // Resolve to get the AT URI
+     * const uri = await resolver.resolve('app.bsky.feed.post')
+     * console.log(uri.toString())
+     * // Output: 'at://did:plc:z72i7hdynmk6r22z27h6tvur/com.atproto.lexicon.schema/app.bsky.feed.post'
+     *
+     * // The URI can then be used with fetch() or stored for later use
+     * const result = await resolver.fetch(uri)
+     * ```
+     */
     resolve(nsidStr: NSID | string): Promise<AtUri>;
     protected resolveLexiconAuthority(nsid: NSID): Promise<Did>;
+    /**
+     * Fetches a lexicon document from a specific AT URI.
+     *
+     * This method performs the second stage of lexicon resolution:
+     * 1. Resolves the DID from the URI to find the PDS endpoint
+     * 2. Fetches the record from the PDS using `com.atproto.sync.getRecord`
+     * 3. Verifies the cryptographic proof (commit signature)
+     * 4. Validates the lexicon document structure
+     * 5. Ensures the document ID matches the URI rkey
+     *
+     * Use this when you already have an AT URI (e.g., from {@link resolve})
+     * and want to fetch the lexicon document.
+     *
+     * @param uriStr - The AT URI to fetch, either as a string or AtUri object
+     * @param options - Optional DID resolution options (e.g., signal for cancellation, noCache)
+     * @returns The resolved lexicon result containing URI, CID, and lexicon document
+     * @throws {LexResolverError} If fetching or validation fails
+     *
+     * @example
+     * ```typescript
+     * // Fetch from a known URI
+     * const result = await resolver.fetch(
+     *   'at://did:plc:xyz/com.atproto.lexicon.schema/app.bsky.feed.post'
+     * )
+     *
+     * // Fetch with no-cache to bypass any upstream caching
+     * const result = await resolver.fetch(uri, { noCache: true })
+     *
+     * // Fetch with abort signal
+     * const controller = new AbortController()
+     * const result = await resolver.fetch(uri, { signal: controller.signal })
+     * ```
+     */
     fetch(uriStr: AtUri | string, options?: ResolveDidOptions): Promise<LexResolverResult>;
     protected fetchLexiconUri(uri: AtUri, options?: ResolveDidOptions): Promise<LexResolverFetchResult>;
 }

package/dist/lex-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lex-resolver.d.ts","sourceRoot":"","sources":["../src/lex-resolver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lex-resolver.d.ts","sourceRoot":"","sources":["../src/lex-resolver.ts"],"names":[],"mappings":"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"}