@hypercerts-org/sdk-core 0.2.0-beta.0

package/dist/lexicons.cjs

@@ -0,0 +1,420 @@
+'use strict';
+
+var lexicon$1 = require('@atproto/lexicon');
+var lexicon = require('@hypercerts-org/lexicon');
+
+/**
+ * Base error class for all SDK errors.
+ *
+ * All errors thrown by the Hypercerts SDK extend this class, making it easy
+ * to catch and handle SDK-specific errors.
+ *
+ * @example Catching all SDK errors
+ * ```typescript
+ * try {
+ *   await sdk.authorize("user.bsky.social");
+ * } catch (error) {
+ *   if (error instanceof ATProtoSDKError) {
+ *     console.error(`SDK Error [${error.code}]: ${error.message}`);
+ *     console.error(`HTTP Status: ${error.status}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example Checking error codes
+ * ```typescript
+ * try {
+ *   await repo.records.get(collection, rkey);
+ * } catch (error) {
+ *   if (error instanceof ATProtoSDKError) {
+ *     switch (error.code) {
+ *       case "AUTHENTICATION_ERROR":
+ *         // Redirect to login
+ *         break;
+ *       case "VALIDATION_ERROR":
+ *         // Show form errors
+ *         break;
+ *       case "NETWORK_ERROR":
+ *         // Retry or show offline message
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+class ATProtoSDKError extends Error {
+    /**
+     * Creates a new SDK error.
+     *
+     * @param message - Human-readable error description
+     * @param code - Machine-readable error code for programmatic handling
+     * @param status - HTTP status code associated with this error type
+     * @param cause - The underlying error that caused this error, if any
+     */
+    constructor(message, code, status, cause) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.cause = cause;
+        this.name = "ATProtoSDKError";
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+/**
+ * Error thrown when input validation fails.
+ *
+ * This error indicates that provided data doesn't meet the required format
+ * or constraints. Common causes:
+ * - Missing required fields
+ * - Invalid URL formats
+ * - Invalid DID format
+ * - Schema validation failures for records
+ * - Invalid configuration values
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sdk.authorize("");  // Empty identifier
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error("Invalid input:", error.message);
+ *     // Show validation error to user
+ *   }
+ * }
+ * ```
+ *
+ * @example With Zod validation cause
+ * ```typescript
+ * try {
+ *   await repo.records.create(collection, record);
+ * } catch (error) {
+ *   if (error instanceof ValidationError && error.cause) {
+ *     // error.cause may be a ZodError with detailed field errors
+ *     const zodError = error.cause as ZodError;
+ *     zodError.errors.forEach(e => {
+ *       console.error(`Field ${e.path.join(".")}: ${e.message}`);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+class ValidationError extends ATProtoSDKError {
+    /**
+     * Creates a validation error.
+     *
+     * @param message - Description of what validation failed
+     * @param cause - The underlying validation error (e.g., ZodError)
+     */
+    constructor(message, cause) {
+        super(message, "VALIDATION_ERROR", 400, cause);
+        this.name = "ValidationError";
+    }
+}
+
+/**
+ * Registry for managing and validating AT Protocol lexicon schemas.
+ *
+ * Lexicons are schema definitions that describe the structure of records
+ * in the AT Protocol. This registry allows you to:
+ *
+ * - Register custom lexicons for your application's record types
+ * - Validate records against their lexicon schemas
+ * - Extend the AT Protocol Agent with custom lexicon support
+ *
+ * @remarks
+ * The SDK automatically registers hypercert lexicons when creating a Repository.
+ * You only need to use this class directly if you're working with custom
+ * record types.
+ *
+ * **Lexicon IDs** follow the NSID (Namespaced Identifier) format:
+ * `{authority}.{name}` (e.g., `org.hypercerts.hypercert`)
+ *
+ * @example Registering custom lexicons
+ * ```typescript
+ * const registry = sdk.getLexiconRegistry();
+ *
+ * // Register a single lexicon
+ * registry.register({
+ *   lexicon: 1,
+ *   id: "org.example.myRecord",
+ *   defs: {
+ *     main: {
+ *       type: "record",
+ *       key: "tid",
+ *       record: {
+ *         type: "object",
+ *         required: ["title", "createdAt"],
+ *         properties: {
+ *           title: { type: "string" },
+ *           description: { type: "string" },
+ *           createdAt: { type: "string", format: "datetime" },
+ *         },
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * // Register multiple lexicons at once
+ * registry.registerMany([lexicon1, lexicon2, lexicon3]);
+ * ```
+ *
+ * @example Validating records
+ * ```typescript
+ * const result = registry.validate("org.example.myRecord", {
+ *   title: "Test",
+ *   createdAt: new Date().toISOString(),
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error(`Validation failed: ${result.error}`);
+ * }
+ * ```
+ *
+ * @see https://atproto.com/specs/lexicon for the Lexicon specification
+ */
+class LexiconRegistry {
+    /**
+     * Creates a new LexiconRegistry.
+     *
+     * The registry starts empty. Use {@link register} or {@link registerMany}
+     * to add lexicons.
+     */
+    constructor() {
+        /** Map of lexicon ID to lexicon document */
+        this.lexicons = new Map();
+        this.lexiconsCollection = new lexicon$1.Lexicons();
+    }
+    /**
+     * Registers a single lexicon schema.
+     *
+     * @param lexicon - The lexicon document to register
+     * @throws {@link ValidationError} if the lexicon doesn't have an `id` field
+     *
+     * @remarks
+     * If a lexicon with the same ID is already registered, it will be
+     * replaced with the new definition. This is useful for testing but
+     * should generally be avoided in production.
+     *
+     * @example
+     * ```typescript
+     * registry.register({
+     *   lexicon: 1,
+     *   id: "org.example.post",
+     *   defs: {
+     *     main: {
+     *       type: "record",
+     *       key: "tid",
+     *       record: {
+     *         type: "object",
+     *         required: ["text", "createdAt"],
+     *         properties: {
+     *           text: { type: "string", maxLength: 300 },
+     *           createdAt: { type: "string", format: "datetime" },
+     *         },
+     *       },
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    register(lexicon) {
+        if (!lexicon.id) {
+            throw new ValidationError("Lexicon must have an 'id' field");
+        }
+        // Remove existing lexicon if present (to allow overwriting)
+        if (this.lexicons.has(lexicon.id)) {
+            // Lexicons collection doesn't support removal, so we create a new one
+            // This is a limitation - in practice, lexicons shouldn't be overwritten
+            // But we allow it for testing and flexibility
+            const existingLexicon = this.lexicons.get(lexicon.id);
+            if (existingLexicon) {
+                // Try to remove from collection (may fail if not supported)
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    this.lexiconsCollection.remove?.(lexicon.id);
+                }
+                catch {
+                    // If removal fails, create a new collection
+                    this.lexiconsCollection = new lexicon$1.Lexicons();
+                    // Re-register all other lexicons
+                    for (const [id, lex] of this.lexicons.entries()) {
+                        if (id !== lexicon.id) {
+                            this.lexiconsCollection.add(lex);
+                        }
+                    }
+                }
+            }
+        }
+        this.lexicons.set(lexicon.id, lexicon);
+        this.lexiconsCollection.add(lexicon);
+    }
+    /**
+     * Registers multiple lexicons at once.
+     *
+     * @param lexicons - Array of lexicon documents to register
+     *
+     * @example
+     * ```typescript
+     * import { HYPERCERT_LEXICONS } from "@hypercerts-org/sdk/lexicons";
+     *
+     * registry.registerMany(HYPERCERT_LEXICONS);
+     * ```
+     */
+    registerMany(lexicons) {
+        for (const lexicon of lexicons) {
+            this.register(lexicon);
+        }
+    }
+    /**
+     * Gets a lexicon document by ID.
+     *
+     * @param id - The lexicon NSID (e.g., "org.hypercerts.hypercert")
+     * @returns The lexicon document, or `undefined` if not registered
+     *
+     * @example
+     * ```typescript
+     * const lexicon = registry.get("org.hypercerts.hypercert");
+     * if (lexicon) {
+     *   console.log(`Found lexicon: ${lexicon.id}`);
+     * }
+     * ```
+     */
+    get(id) {
+        return this.lexicons.get(id);
+    }
+    /**
+     * Validates a record against a collection's lexicon schema.
+     *
+     * @param collection - The collection NSID (same as lexicon ID)
+     * @param record - The record data to validate
+     * @returns Validation result with `valid` boolean and optional `error` message
+     *
+     * @remarks
+     * - If no lexicon is registered for the collection, validation passes
+     *   (we can't validate against unknown schemas)
+     * - Validation checks required fields and type constraints defined
+     *   in the lexicon schema
+     *
+     * @example
+     * ```typescript
+     * const result = registry.validate("org.hypercerts.hypercert", {
+     *   title: "My Hypercert",
+     *   description: "Description...",
+     *   // ... other fields
+     * });
+     *
+     * if (!result.valid) {
+     *   throw new Error(`Invalid record: ${result.error}`);
+     * }
+     * ```
+     */
+    validate(collection, record) {
+        // Check if we have a lexicon registered for this collection
+        // Collection format is typically "namespace.collection" (e.g., "app.bsky.feed.post")
+        // Lexicon ID format is the same
+        const lexiconId = collection;
+        const lexicon = this.lexicons.get(lexiconId);
+        if (!lexicon) {
+            // No lexicon registered - validation passes (can't validate unknown schemas)
+            return { valid: true };
+        }
+        // Check required fields if the lexicon defines them
+        const recordDef = lexicon.defs?.record;
+        if (recordDef && typeof recordDef === "object" && "record" in recordDef) {
+            const recordSchema = recordDef.record;
+            if (typeof recordSchema === "object" && "required" in recordSchema && Array.isArray(recordSchema.required)) {
+                const recordObj = record;
+                for (const requiredField of recordSchema.required) {
+                    if (typeof requiredField === "string" && !(requiredField in recordObj)) {
+                        return {
+                            valid: false,
+                            error: `Missing required field: ${requiredField}`,
+                        };
+                    }
+                }
+            }
+        }
+        try {
+            this.lexiconsCollection.assertValidRecord(collection, record);
+            return { valid: true };
+        }
+        catch (error) {
+            // If error indicates lexicon not found, treat as validation pass
+            // (the lexicon might exist in Agent's collection but not ours)
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage.includes("not found") || errorMessage.includes("Lexicon not found")) {
+                return { valid: true };
+            }
+            return {
+                valid: false,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Adds all registered lexicons to an AT Protocol Agent instance.
+     *
+     * This allows the Agent to understand custom lexicon types when making
+     * API requests.
+     *
+     * @param agent - The Agent instance to extend
+     *
+     * @remarks
+     * This is called automatically when creating a Repository. You typically
+     * don't need to call this directly unless you're using the Agent
+     * independently.
+     *
+     * @internal
+     */
+    addToAgent(agent) {
+        // Access the internal lexicons collection and merge our lexicons
+        // The Agent's lex property is a Lexicons instance
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const agentLex = agent.lex;
+        // Add each registered lexicon to the agent
+        for (const lexicon of this.lexicons.values()) {
+            agentLex.add(lexicon);
+        }
+    }
+    /**
+     * Gets all registered lexicon IDs.
+     *
+     * @returns Array of lexicon NSIDs
+     *
+     * @example
+     * ```typescript
+     * const ids = registry.getRegisteredIds();
+     * console.log(`Registered lexicons: ${ids.join(", ")}`);
+     * ```
+     */
+    getRegisteredIds() {
+        return Array.from(this.lexicons.keys());
+    }
+    /**
+     * Checks if a lexicon is registered.
+     *
+     * @param id - The lexicon NSID to check
+     * @returns `true` if the lexicon is registered
+     *
+     * @example
+     * ```typescript
+     * if (registry.has("org.hypercerts.hypercert")) {
+     *   // Hypercert lexicon is available
+     * }
+     * ```
+     */
+    has(id) {
+        return this.lexicons.has(id);
+    }
+}
+
+Object.defineProperty(exports, "HYPERCERT_COLLECTIONS", {
+    enumerable: true,
+    get: function () { return lexicon.HYPERCERT_COLLECTIONS; }
+});
+Object.defineProperty(exports, "HYPERCERT_LEXICONS", {
+    enumerable: true,
+    get: function () { return lexicon.HYPERCERT_LEXICONS; }
+});
+exports.LexiconRegistry = LexiconRegistry;
+//# sourceMappingURL=lexicons.cjs.map

package/dist/lexicons.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexicons.cjs","sources":["../src/core/errors.ts","../src/repository/LexiconRegistry.ts"],"sourcesContent":["/**\n * Base error class for all SDK errors.\n *\n * All errors thrown by the Hypercerts SDK extend this class, making it easy\n * to catch and handle SDK-specific errors.\n *\n * @example Catching all SDK errors\n * ```typescript\n * try {\n *   await sdk.authorize(\"user.bsky.social\");\n * } catch (error) {\n *   if (error instanceof ATProtoSDKError) {\n *     console.error(`SDK Error [${error.code}]: ${error.message}`);\n *     console.error(`HTTP Status: ${error.status}`);\n *   }\n * }\n * ```\n *\n * @example Checking error codes\n * ```typescript\n * try {\n *   await repo.records.get(collection, rkey);\n * } catch (error) {\n *   if (error instanceof ATProtoSDKError) {\n *     switch (error.code) {\n *       case \"AUTHENTICATION_ERROR\":\n *         // Redirect to login\n *         break;\n *       case \"VALIDATION_ERROR\":\n *         // Show form errors\n *         break;\n *       case \"NETWORK_ERROR\":\n *         // Retry or show offline message\n *         break;\n *     }\n *   }\n * }\n * ```\n */\nexport class ATProtoSDKError extends Error {\n  /**\n   * Creates a new SDK error.\n   *\n   * @param message - Human-readable error description\n   * @param code - Machine-readable error code for programmatic handling\n   * @param status - HTTP status code associated with this error type\n   * @param cause - The underlying error that caused this error, if any\n   */\n  constructor(\n    message: string,\n    public code: string,\n    public status?: number,\n    public cause?: unknown,\n  ) {\n    super(message);\n    this.name = \"ATProtoSDKError\";\n    Error.captureStackTrace?.(this, this.constructor);\n  }\n}\n\n/**\n * Error thrown when authentication fails.\n *\n * This error indicates problems with the OAuth flow, invalid credentials,\n * or failed token exchanges. Common causes:\n * - Invalid authorization code\n * - Expired or invalid state parameter\n * - Revoked or invalid tokens\n * - User denied authorization\n *\n * @example\n * ```typescript\n * try {\n *   const session = await sdk.callback(params);\n * } catch (error) {\n *   if (error instanceof AuthenticationError) {\n *     // Clear any stored state and redirect to login\n *     console.error(\"Authentication failed:\", error.message);\n *   }\n * }\n * ```\n */\nexport class AuthenticationError extends ATProtoSDKError {\n  /**\n   * Creates an authentication error.\n   *\n   * @param message - Description of what went wrong during authentication\n   * @param cause - The underlying error (e.g., from the OAuth client)\n   */\n  constructor(message: string, cause?: unknown) {\n    super(message, \"AUTHENTICATION_ERROR\", 401, cause);\n    this.name = \"AuthenticationError\";\n  }\n}\n\n/**\n * Error thrown when a session has expired and cannot be refreshed.\n *\n * This typically occurs when:\n * - The refresh token has expired (usually after extended inactivity)\n * - The user has revoked access to your application\n * - The PDS has invalidated all sessions for the user\n *\n * When this error occurs, the user must re-authenticate.\n *\n * @example\n * ```typescript\n * try {\n *   const session = await sdk.restoreSession(did);\n * } catch (error) {\n *   if (error instanceof SessionExpiredError) {\n *     // Clear stored session and prompt user to log in again\n *     localStorage.removeItem(\"userDid\");\n *     window.location.href = \"/login\";\n *   }\n * }\n * ```\n */\nexport class SessionExpiredError extends ATProtoSDKError {\n  /**\n   * Creates a session expired error.\n   *\n   * @param message - Description of why the session expired\n   * @param cause - The underlying error from the token refresh attempt\n   */\n  constructor(message: string = \"Session expired\", cause?: unknown) {\n    super(message, \"SESSION_EXPIRED\", 401, cause);\n    this.name = \"SessionExpiredError\";\n  }\n}\n\n/**\n * Error thrown when input validation fails.\n *\n * This error indicates that provided data doesn't meet the required format\n * or constraints. Common causes:\n * - Missing required fields\n * - Invalid URL formats\n * - Invalid DID format\n * - Schema validation failures for records\n * - Invalid configuration values\n *\n * @example\n * ```typescript\n * try {\n *   await sdk.authorize(\"\");  // Empty identifier\n * } catch (error) {\n *   if (error instanceof ValidationError) {\n *     console.error(\"Invalid input:\", error.message);\n *     // Show validation error to user\n *   }\n * }\n * ```\n *\n * @example With Zod validation cause\n * ```typescript\n * try {\n *   await repo.records.create(collection, record);\n * } catch (error) {\n *   if (error instanceof ValidationError && error.cause) {\n *     // error.cause may be a ZodError with detailed field errors\n *     const zodError = error.cause as ZodError;\n *     zodError.errors.forEach(e => {\n *       console.error(`Field ${e.path.join(\".\")}: ${e.message}`);\n *     });\n *   }\n * }\n * ```\n */\nexport class ValidationError extends ATProtoSDKError {\n  /**\n   * Creates a validation error.\n   *\n   * @param message - Description of what validation failed\n   * @param cause - The underlying validation error (e.g., ZodError)\n   */\n  constructor(message: string, cause?: unknown) {\n    super(message, \"VALIDATION_ERROR\", 400, cause);\n    this.name = \"ValidationError\";\n  }\n}\n\n/**\n * Error thrown when a network request fails.\n *\n * This error indicates connectivity issues or server unavailability.\n * Common causes:\n * - No internet connection\n * - DNS resolution failure\n * - Server timeout\n * - Server returned 5xx error\n * - TLS/SSL errors\n *\n * These errors are typically transient and may succeed on retry.\n *\n * @example\n * ```typescript\n * try {\n *   await repo.records.list(collection);\n * } catch (error) {\n *   if (error instanceof NetworkError) {\n *     // Implement retry logic or show offline indicator\n *     console.error(\"Network error:\", error.message);\n *     await retryWithBackoff(() => repo.records.list(collection));\n *   }\n * }\n * ```\n */\nexport class NetworkError extends ATProtoSDKError {\n  /**\n   * Creates a network error.\n   *\n   * @param message - Description of the network failure\n   * @param cause - The underlying error (e.g., fetch error, timeout)\n   */\n  constructor(message: string, cause?: unknown) {\n    super(message, \"NETWORK_ERROR\", 503, cause);\n    this.name = \"NetworkError\";\n  }\n}\n\n/**\n * Error thrown when an SDS-only operation is attempted on a PDS.\n *\n * Certain operations are only available on Shared Data Servers (SDS),\n * such as collaborator management and organization operations.\n * This error is thrown when these operations are attempted on a\n * Personal Data Server (PDS).\n *\n * @example\n * ```typescript\n * const pdsRepo = sdk.repository(session);  // Default is PDS\n *\n * try {\n *   // This will throw SDSRequiredError\n *   await pdsRepo.collaborators.list();\n * } catch (error) {\n *   if (error instanceof SDSRequiredError) {\n *     // Switch to SDS for this operation\n *     const sdsRepo = sdk.repository(session, { server: \"sds\" });\n *     const collaborators = await sdsRepo.collaborators.list();\n *   }\n * }\n * ```\n */\nexport class SDSRequiredError extends ATProtoSDKError {\n  /**\n   * Creates an SDS required error.\n   *\n   * @param message - Description of which operation requires SDS\n   * @param cause - Any underlying error\n   */\n  constructor(message: string = \"This operation requires a Shared Data Server (SDS)\", cause?: unknown) {\n    super(message, \"SDS_REQUIRED\", 400, cause);\n    this.name = \"SDSRequiredError\";\n  }\n}\n","import type { Agent } from \"@atproto/api\";\nimport type { LexiconDoc } from \"@atproto/lexicon\";\nimport { Lexicons } from \"@atproto/lexicon\";\nimport { ValidationError } from \"../core/errors.js\";\n\n/**\n * Result of validating a record against a lexicon schema.\n */\nexport interface ValidationResult {\n  /**\n   * Whether the record is valid according to the lexicon schema.\n   */\n  valid: boolean;\n\n  /**\n   * Error message if validation failed.\n   *\n   * Only present when `valid` is `false`.\n   */\n  error?: string;\n}\n\n/**\n * Registry for managing and validating AT Protocol lexicon schemas.\n *\n * Lexicons are schema definitions that describe the structure of records\n * in the AT Protocol. This registry allows you to:\n *\n * - Register custom lexicons for your application's record types\n * - Validate records against their lexicon schemas\n * - Extend the AT Protocol Agent with custom lexicon support\n *\n * @remarks\n * The SDK automatically registers hypercert lexicons when creating a Repository.\n * You only need to use this class directly if you're working with custom\n * record types.\n *\n * **Lexicon IDs** follow the NSID (Namespaced Identifier) format:\n * `{authority}.{name}` (e.g., `org.hypercerts.hypercert`)\n *\n * @example Registering custom lexicons\n * ```typescript\n * const registry = sdk.getLexiconRegistry();\n *\n * // Register a single lexicon\n * registry.register({\n *   lexicon: 1,\n *   id: \"org.example.myRecord\",\n *   defs: {\n *     main: {\n *       type: \"record\",\n *       key: \"tid\",\n *       record: {\n *         type: \"object\",\n *         required: [\"title\", \"createdAt\"],\n *         properties: {\n *           title: { type: \"string\" },\n *           description: { type: \"string\" },\n *           createdAt: { type: \"string\", format: \"datetime\" },\n *         },\n *       },\n *     },\n *   },\n * });\n *\n * // Register multiple lexicons at once\n * registry.registerMany([lexicon1, lexicon2, lexicon3]);\n * ```\n *\n * @example Validating records\n * ```typescript\n * const result = registry.validate(\"org.example.myRecord\", {\n *   title: \"Test\",\n *   createdAt: new Date().toISOString(),\n * });\n *\n * if (!result.valid) {\n *   console.error(`Validation failed: ${result.error}`);\n * }\n * ```\n *\n * @see https://atproto.com/specs/lexicon for the Lexicon specification\n */\nexport class LexiconRegistry {\n  /** Map of lexicon ID to lexicon document */\n  private lexicons = new Map<string, LexiconDoc>();\n\n  /** Lexicons collection for validation */\n  private lexiconsCollection: Lexicons;\n\n  /**\n   * Creates a new LexiconRegistry.\n   *\n   * The registry starts empty. Use {@link register} or {@link registerMany}\n   * to add lexicons.\n   */\n  constructor() {\n    this.lexiconsCollection = new Lexicons();\n  }\n\n  /**\n   * Registers a single lexicon schema.\n   *\n   * @param lexicon - The lexicon document to register\n   * @throws {@link ValidationError} if the lexicon doesn't have an `id` field\n   *\n   * @remarks\n   * If a lexicon with the same ID is already registered, it will be\n   * replaced with the new definition. This is useful for testing but\n   * should generally be avoided in production.\n   *\n   * @example\n   * ```typescript\n   * registry.register({\n   *   lexicon: 1,\n   *   id: \"org.example.post\",\n   *   defs: {\n   *     main: {\n   *       type: \"record\",\n   *       key: \"tid\",\n   *       record: {\n   *         type: \"object\",\n   *         required: [\"text\", \"createdAt\"],\n   *         properties: {\n   *           text: { type: \"string\", maxLength: 300 },\n   *           createdAt: { type: \"string\", format: \"datetime\" },\n   *         },\n   *       },\n   *     },\n   *   },\n   * });\n   * ```\n   */\n  register(lexicon: LexiconDoc): void {\n    if (!lexicon.id) {\n      throw new ValidationError(\"Lexicon must have an 'id' field\");\n    }\n\n    // Remove existing lexicon if present (to allow overwriting)\n    if (this.lexicons.has(lexicon.id)) {\n      // Lexicons collection doesn't support removal, so we create a new one\n      // This is a limitation - in practice, lexicons shouldn't be overwritten\n      // But we allow it for testing and flexibility\n      const existingLexicon = this.lexicons.get(lexicon.id);\n      if (existingLexicon) {\n        // Try to remove from collection (may fail if not supported)\n        try {\n          // eslint-disable-next-line @typescript-eslint/no-explicit-any\n          (this.lexiconsCollection as any).remove?.(lexicon.id);\n        } catch {\n          // If removal fails, create a new collection\n          this.lexiconsCollection = new Lexicons();\n          // Re-register all other lexicons\n          for (const [id, lex] of this.lexicons.entries()) {\n            if (id !== lexicon.id) {\n              this.lexiconsCollection.add(lex);\n            }\n          }\n        }\n      }\n    }\n\n    this.lexicons.set(lexicon.id, lexicon);\n    this.lexiconsCollection.add(lexicon);\n  }\n\n  /**\n   * Registers multiple lexicons at once.\n   *\n   * @param lexicons - Array of lexicon documents to register\n   *\n   * @example\n   * ```typescript\n   * import { HYPERCERT_LEXICONS } from \"@hypercerts-org/sdk/lexicons\";\n   *\n   * registry.registerMany(HYPERCERT_LEXICONS);\n   * ```\n   */\n  registerMany(lexicons: LexiconDoc[]): void {\n    for (const lexicon of lexicons) {\n      this.register(lexicon);\n    }\n  }\n\n  /**\n   * Gets a lexicon document by ID.\n   *\n   * @param id - The lexicon NSID (e.g., \"org.hypercerts.hypercert\")\n   * @returns The lexicon document, or `undefined` if not registered\n   *\n   * @example\n   * ```typescript\n   * const lexicon = registry.get(\"org.hypercerts.hypercert\");\n   * if (lexicon) {\n   *   console.log(`Found lexicon: ${lexicon.id}`);\n   * }\n   * ```\n   */\n  get(id: string): LexiconDoc | undefined {\n    return this.lexicons.get(id);\n  }\n\n  /**\n   * Validates a record against a collection's lexicon schema.\n   *\n   * @param collection - The collection NSID (same as lexicon ID)\n   * @param record - The record data to validate\n   * @returns Validation result with `valid` boolean and optional `error` message\n   *\n   * @remarks\n   * - If no lexicon is registered for the collection, validation passes\n   *   (we can't validate against unknown schemas)\n   * - Validation checks required fields and type constraints defined\n   *   in the lexicon schema\n   *\n   * @example\n   * ```typescript\n   * const result = registry.validate(\"org.hypercerts.hypercert\", {\n   *   title: \"My Hypercert\",\n   *   description: \"Description...\",\n   *   // ... other fields\n   * });\n   *\n   * if (!result.valid) {\n   *   throw new Error(`Invalid record: ${result.error}`);\n   * }\n   * ```\n   */\n  validate(collection: string, record: unknown): ValidationResult {\n    // Check if we have a lexicon registered for this collection\n    // Collection format is typically \"namespace.collection\" (e.g., \"app.bsky.feed.post\")\n    // Lexicon ID format is the same\n    const lexiconId = collection;\n    const lexicon = this.lexicons.get(lexiconId);\n    if (!lexicon) {\n      // No lexicon registered - validation passes (can't validate unknown schemas)\n      return { valid: true };\n    }\n\n    // Check required fields if the lexicon defines them\n    const recordDef = lexicon.defs?.record;\n    if (recordDef && typeof recordDef === \"object\" && \"record\" in recordDef) {\n      const recordSchema = recordDef.record;\n      if (typeof recordSchema === \"object\" && \"required\" in recordSchema && Array.isArray(recordSchema.required)) {\n        const recordObj = record as Record<string, unknown>;\n        for (const requiredField of recordSchema.required) {\n          if (typeof requiredField === \"string\" && !(requiredField in recordObj)) {\n            return {\n              valid: false,\n              error: `Missing required field: ${requiredField}`,\n            };\n          }\n        }\n      }\n    }\n\n    try {\n      this.lexiconsCollection.assertValidRecord(collection, record);\n      return { valid: true };\n    } catch (error) {\n      // If error indicates lexicon not found, treat as validation pass\n      // (the lexicon might exist in Agent's collection but not ours)\n      const errorMessage = error instanceof Error ? error.message : String(error);\n      if (errorMessage.includes(\"not found\") || errorMessage.includes(\"Lexicon not found\")) {\n        return { valid: true };\n      }\n      return {\n        valid: false,\n        error: errorMessage,\n      };\n    }\n  }\n\n  /**\n   * Adds all registered lexicons to an AT Protocol Agent instance.\n   *\n   * This allows the Agent to understand custom lexicon types when making\n   * API requests.\n   *\n   * @param agent - The Agent instance to extend\n   *\n   * @remarks\n   * This is called automatically when creating a Repository. You typically\n   * don't need to call this directly unless you're using the Agent\n   * independently.\n   *\n   * @internal\n   */\n  addToAgent(agent: Agent): void {\n    // Access the internal lexicons collection and merge our lexicons\n    // The Agent's lex property is a Lexicons instance\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const agentLex = (agent as any).lex as Lexicons;\n\n    // Add each registered lexicon to the agent\n    for (const lexicon of this.lexicons.values()) {\n      agentLex.add(lexicon);\n    }\n  }\n\n  /**\n   * Gets all registered lexicon IDs.\n   *\n   * @returns Array of lexicon NSIDs\n   *\n   * @example\n   * ```typescript\n   * const ids = registry.getRegisteredIds();\n   * console.log(`Registered lexicons: ${ids.join(\", \")}`);\n   * ```\n   */\n  getRegisteredIds(): string[] {\n    return Array.from(this.lexicons.keys());\n  }\n\n  /**\n   * Checks if a lexicon is registered.\n   *\n   * @param id - The lexicon NSID to check\n   * @returns `true` if the lexicon is registered\n   *\n   * @example\n   * ```typescript\n   * if (registry.has(\"org.hypercerts.hypercert\")) {\n   *   // Hypercert lexicon is available\n   * }\n   * ```\n   */\n  has(id: string): boolean {\n    return this.lexicons.has(id);\n  }\n}\n"],"names":["Lexicons"],"mappings":"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"}

package/dist/lexicons.d.ts

@@ -0,0 +1,227 @@
+import { Agent } from '@atproto/api';
+import { LexiconDoc } from '@atproto/lexicon';
+export { HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS } from '@hypercerts-org/lexicon';
+
+/**
+ * Result of validating a record against a lexicon schema.
+ */
+interface ValidationResult {
+    /**
+     * Whether the record is valid according to the lexicon schema.
+     */
+    valid: boolean;
+    /**
+     * Error message if validation failed.
+     *
+     * Only present when `valid` is `false`.
+     */
+    error?: string;
+}
+/**
+ * Registry for managing and validating AT Protocol lexicon schemas.
+ *
+ * Lexicons are schema definitions that describe the structure of records
+ * in the AT Protocol. This registry allows you to:
+ *
+ * - Register custom lexicons for your application's record types
+ * - Validate records against their lexicon schemas
+ * - Extend the AT Protocol Agent with custom lexicon support
+ *
+ * @remarks
+ * The SDK automatically registers hypercert lexicons when creating a Repository.
+ * You only need to use this class directly if you're working with custom
+ * record types.
+ *
+ * **Lexicon IDs** follow the NSID (Namespaced Identifier) format:
+ * `{authority}.{name}` (e.g., `org.hypercerts.hypercert`)
+ *
+ * @example Registering custom lexicons
+ * ```typescript
+ * const registry = sdk.getLexiconRegistry();
+ *
+ * // Register a single lexicon
+ * registry.register({
+ *   lexicon: 1,
+ *   id: "org.example.myRecord",
+ *   defs: {
+ *     main: {
+ *       type: "record",
+ *       key: "tid",
+ *       record: {
+ *         type: "object",
+ *         required: ["title", "createdAt"],
+ *         properties: {
+ *           title: { type: "string" },
+ *           description: { type: "string" },
+ *           createdAt: { type: "string", format: "datetime" },
+ *         },
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * // Register multiple lexicons at once
+ * registry.registerMany([lexicon1, lexicon2, lexicon3]);
+ * ```
+ *
+ * @example Validating records
+ * ```typescript
+ * const result = registry.validate("org.example.myRecord", {
+ *   title: "Test",
+ *   createdAt: new Date().toISOString(),
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error(`Validation failed: ${result.error}`);
+ * }
+ * ```
+ *
+ * @see https://atproto.com/specs/lexicon for the Lexicon specification
+ */
+declare class LexiconRegistry {
+    /** Map of lexicon ID to lexicon document */
+    private lexicons;
+    /** Lexicons collection for validation */
+    private lexiconsCollection;
+    /**
+     * Creates a new LexiconRegistry.
+     *
+     * The registry starts empty. Use {@link register} or {@link registerMany}
+     * to add lexicons.
+     */
+    constructor();
+    /**
+     * Registers a single lexicon schema.
+     *
+     * @param lexicon - The lexicon document to register
+     * @throws {@link ValidationError} if the lexicon doesn't have an `id` field
+     *
+     * @remarks
+     * If a lexicon with the same ID is already registered, it will be
+     * replaced with the new definition. This is useful for testing but
+     * should generally be avoided in production.
+     *
+     * @example
+     * ```typescript
+     * registry.register({
+     *   lexicon: 1,
+     *   id: "org.example.post",
+     *   defs: {
+     *     main: {
+     *       type: "record",
+     *       key: "tid",
+     *       record: {
+     *         type: "object",
+     *         required: ["text", "createdAt"],
+     *         properties: {
+     *           text: { type: "string", maxLength: 300 },
+     *           createdAt: { type: "string", format: "datetime" },
+     *         },
+     *       },
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    register(lexicon: LexiconDoc): void;
+    /**
+     * Registers multiple lexicons at once.
+     *
+     * @param lexicons - Array of lexicon documents to register
+     *
+     * @example
+     * ```typescript
+     * import { HYPERCERT_LEXICONS } from "@hypercerts-org/sdk/lexicons";
+     *
+     * registry.registerMany(HYPERCERT_LEXICONS);
+     * ```
+     */
+    registerMany(lexicons: LexiconDoc[]): void;
+    /**
+     * Gets a lexicon document by ID.
+     *
+     * @param id - The lexicon NSID (e.g., "org.hypercerts.hypercert")
+     * @returns The lexicon document, or `undefined` if not registered
+     *
+     * @example
+     * ```typescript
+     * const lexicon = registry.get("org.hypercerts.hypercert");
+     * if (lexicon) {
+     *   console.log(`Found lexicon: ${lexicon.id}`);
+     * }
+     * ```
+     */
+    get(id: string): LexiconDoc | undefined;
+    /**
+     * Validates a record against a collection's lexicon schema.
+     *
+     * @param collection - The collection NSID (same as lexicon ID)
+     * @param record - The record data to validate
+     * @returns Validation result with `valid` boolean and optional `error` message
+     *
+     * @remarks
+     * - If no lexicon is registered for the collection, validation passes
+     *   (we can't validate against unknown schemas)
+     * - Validation checks required fields and type constraints defined
+     *   in the lexicon schema
+     *
+     * @example
+     * ```typescript
+     * const result = registry.validate("org.hypercerts.hypercert", {
+     *   title: "My Hypercert",
+     *   description: "Description...",
+     *   // ... other fields
+     * });
+     *
+     * if (!result.valid) {
+     *   throw new Error(`Invalid record: ${result.error}`);
+     * }
+     * ```
+     */
+    validate(collection: string, record: unknown): ValidationResult;
+    /**
+     * Adds all registered lexicons to an AT Protocol Agent instance.
+     *
+     * This allows the Agent to understand custom lexicon types when making
+     * API requests.
+     *
+     * @param agent - The Agent instance to extend
+     *
+     * @remarks
+     * This is called automatically when creating a Repository. You typically
+     * don't need to call this directly unless you're using the Agent
+     * independently.
+     *
+     * @internal
+     */
+    addToAgent(agent: Agent): void;
+    /**
+     * Gets all registered lexicon IDs.
+     *
+     * @returns Array of lexicon NSIDs
+     *
+     * @example
+     * ```typescript
+     * const ids = registry.getRegisteredIds();
+     * console.log(`Registered lexicons: ${ids.join(", ")}`);
+     * ```
+     */
+    getRegisteredIds(): string[];
+    /**
+     * Checks if a lexicon is registered.
+     *
+     * @param id - The lexicon NSID to check
+     * @returns `true` if the lexicon is registered
+     *
+     * @example
+     * ```typescript
+     * if (registry.has("org.hypercerts.hypercert")) {
+     *   // Hypercert lexicon is available
+     * }
+     * ```
+     */
+    has(id: string): boolean;
+}
+
+export { LexiconRegistry };
+export type { ValidationResult };