@hypercerts-org/sdk-core 0.10.0-beta.4 → 0.10.0-beta.5

package/dist/lexicons.mjs

@@ -1,4 +1,406 @@
-import { CERTIFIED_DEFS_LEXICON_JSON, LOCATION_LEXICON_JSON, STRONGREF_LEXICON_JSON, HYPERCERTS_DEFS_LEXICON_JSON, ACTIVITY_LEXICON_JSON, COLLECTION_LEXICON_JSON, CONTRIBUTION_LEXICON_JSON, EVALUATION_LEXICON_JSON, EVIDENCE_LEXICON_JSON, MEASUREMENT_LEXICON_JSON, RIGHTS_LEXICON_JSON, PROJECT_LEXICON_JSON, BADGE_AWARD_LEXICON_JSON, BADGE_DEFINITION_LEXICON_JSON, BADGE_RESPONSE_LEXICON_JSON, FUNDING_RECEIPT_LEXICON_JSON, FUNDING_RECEIPT_NSID, BADGE_RESPONSE_NSID, BADGE_DEFINITION_NSID, BADGE_AWARD_NSID, PROJECT_NSID, COLLECTION_NSID, EVIDENCE_NSID, EVALUATION_NSID, MEASUREMENT_NSID, CONTRIBUTION_NSID, LOCATION_NSID, RIGHTS_NSID, ACTIVITY_NSID } from '@hypercerts-org/lexicon';
+import { CERTIFIED_DEFS_LEXICON_JSON, LOCATION_LEXICON_JSON, STRONG_REF_LEXICON_JSON, HYPERCERTS_DEFS_LEXICON_JSON, ACTIVITY_LEXICON_JSON, COLLECTION_LEXICON_JSON, CONTRIBUTION_DETAILS_LEXICON_JSON, CONTRIBUTOR_INFORMATION_LEXICON_JSON, EVALUATION_LEXICON_JSON, EVIDENCE_LEXICON_JSON, MEASUREMENT_LEXICON_JSON, RIGHTS_LEXICON_JSON, BADGE_AWARD_LEXICON_JSON, BADGE_DEFINITION_LEXICON_JSON, BADGE_RESPONSE_LEXICON_JSON, FUNDING_RECEIPT_LEXICON_JSON, WORK_SCOPE_TAG_LEXICON_JSON, WORK_SCOPE_TAG_NSID, FUNDING_RECEIPT_NSID, BADGE_RESPONSE_NSID, BADGE_DEFINITION_NSID, BADGE_AWARD_NSID, COLLECTION_NSID, EVIDENCE_NSID, EVALUATION_NSID, MEASUREMENT_NSID, CONTRIBUTOR_INFORMATION_NSID, CONTRIBUTION_DETAILS_NSID, LOCATION_NSID, RIGHTS_NSID, ACTIVITY_NSID } from '@hypercerts-org/lexicon';
+import { Lexicons } from '@atproto/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";
+    }
+}
+
+/**
+ * LexiconRegistry - Manages custom lexicon registration and validation.
+ *
+ * This module provides a registry for AT Protocol lexicon schemas,
+ * allowing developers to register custom lexicons and validate records
+ * against registered schemas.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Registry for managing AT Protocol lexicon schemas.
+ *
+ * The LexiconRegistry allows developers to:
+ * - Register custom lexicon definitions
+ * - Validate records against registered schemas
+ * - Query registered lexicons
+ * - Add lexicons to AT Protocol agents
+ *
+ * @example Basic usage
+ * ```typescript
+ * const registry = new LexiconRegistry();
+ *
+ * // Register a custom lexicon
+ * registry.register({
+ *   lexicon: 1,
+ *   id: "org.myapp.customRecord",
+ *   defs: {
+ *     main: {
+ *       type: "record",
+ *       key: "tid",
+ *       record: {
+ *         type: "object",
+ *         required: ["$type", "title"],
+ *         properties: {
+ *           "$type": { type: "string", const: "org.myapp.customRecord" },
+ *           title: { type: "string" }
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // Validate a record
+ * const result = registry.validate("org.myapp.customRecord", {
+ *   $type: "org.myapp.customRecord",
+ *   title: "My Record"
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+class LexiconRegistry {
+    /**
+     * Creates a new LexiconRegistry instance.
+     *
+     * @param initialLexicons - Optional array of lexicons to register on initialization
+     */
+    constructor(initialLexicons) {
+        this.lexicons = new Lexicons();
+        this.registeredIds = new Set();
+        if (initialLexicons && initialLexicons.length > 0) {
+            this.registerMany(initialLexicons);
+        }
+    }
+    /**
+     * Registers a single lexicon definition.
+     *
+     * @param lexicon - The lexicon document to register
+     * @throws {Error} If the lexicon is invalid or already registered
+     *
+     * @example
+     * ```typescript
+     * registry.register({
+     *   lexicon: 1,
+     *   id: "org.myapp.customRecord",
+     *   defs: { ... }
+     * });
+     * ```
+     */
+    register(lexicon) {
+        if (!lexicon.id) {
+            throw new Error("Lexicon must have an id");
+        }
+        if (this.registeredIds.has(lexicon.id)) {
+            throw new Error(`Lexicon ${lexicon.id} is already registered`);
+        }
+        try {
+            // Check if the lexicon already exists in the internal store
+            // (e.g., after unregister which only removes from registeredIds)
+            const existingLexicon = this.lexicons.get(lexicon.id);
+            if (!existingLexicon) {
+                // Lexicon is truly new, add it to the store
+                this.lexicons.add(lexicon);
+            }
+            // Always add to registeredIds (re-enable if previously unregistered)
+            this.registeredIds.add(lexicon.id);
+        }
+        catch (error) {
+            throw new Error(`Failed to register lexicon ${lexicon.id}: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    }
+    /**
+     * Registers multiple lexicon definitions at once.
+     *
+     * @param lexicons - Array of lexicon documents to register
+     * @throws {Error} If any lexicon is invalid or already registered
+     *
+     * @example
+     * ```typescript
+     * registry.registerMany([lexicon1, lexicon2, lexicon3]);
+     * ```
+     */
+    registerMany(lexicons) {
+        for (const lexicon of lexicons) {
+            this.register(lexicon);
+        }
+    }
+    /**
+     * Registers a lexicon from a JSON object.
+     *
+     * This is a convenience method for registering lexicons loaded from JSON files.
+     *
+     * @param lexiconJson - The lexicon as a plain JavaScript object
+     * @throws {ValidationError} If the lexicon is not a valid object
+     * @throws {Error} If the lexicon is invalid or already registered
+     *
+     * @example
+     * ```typescript
+     * import customLexicon from "./custom-lexicon.json";
+     * registry.registerFromJSON(customLexicon);
+     * ```
+     */
+    registerFromJSON(lexiconJson) {
+        // Validate that input is an object and not null
+        if (typeof lexiconJson !== "object" || lexiconJson === null) {
+            throw new ValidationError("Lexicon JSON must be a valid object");
+        }
+        // Now we can safely cast to LexiconDoc and register
+        this.register(lexiconJson);
+    }
+    /**
+     * Unregisters a lexicon by its NSID.
+     *
+     * @param nsid - The NSID of the lexicon to unregister
+     * @returns True if the lexicon was unregistered, false if it wasn't registered
+     *
+     * @example
+     * ```typescript
+     * registry.unregister("org.myapp.customRecord");
+     * ```
+     */
+    unregister(nsid) {
+        if (!this.registeredIds.has(nsid)) {
+            return false;
+        }
+        this.registeredIds.delete(nsid);
+        // Note: Lexicons class doesn't have a remove method,
+        // so we can't actually remove from the internal store.
+        // We track removal in our Set for isRegistered checks.
+        return true;
+    }
+    /**
+     * Checks if a lexicon is registered.
+     *
+     * @param nsid - The NSID to check
+     * @returns True if the lexicon is registered
+     *
+     * @example
+     * ```typescript
+     * if (registry.isRegistered("org.myapp.customRecord")) {
+     *   // Lexicon is available
+     * }
+     * ```
+     */
+    isRegistered(nsid) {
+        return this.registeredIds.has(nsid);
+    }
+    /**
+     * Gets a lexicon definition by its NSID.
+     *
+     * @param nsid - The NSID of the lexicon to retrieve
+     * @returns The lexicon document, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const lexicon = registry.get("org.myapp.customRecord");
+     * if (lexicon) {
+     *   console.log(lexicon.defs);
+     * }
+     * ```
+     */
+    get(nsid) {
+        if (!this.isRegistered(nsid)) {
+            return undefined;
+        }
+        return this.lexicons.get(nsid);
+    }
+    /**
+     * Gets all registered lexicon NSIDs.
+     *
+     * @returns Array of registered NSIDs
+     *
+     * @example
+     * ```typescript
+     * const registered = registry.getAll();
+     * console.log(`Registered lexicons: ${registered.join(", ")}`);
+     * ```
+     */
+    getAll() {
+        return Array.from(this.registeredIds);
+    }
+    /**
+     * Validates a record against a registered lexicon.
+     *
+     * @param nsid - The collection NSID to validate against
+     * @param record - The record data to validate
+     * @returns Validation result with success status and optional error message
+     *
+     * @example
+     * ```typescript
+     * const result = registry.validate("org.myapp.customRecord", {
+     *   $type: "org.myapp.customRecord",
+     *   title: "My Record"
+     * });
+     *
+     * if (!result.valid) {
+     *   console.error(`Validation failed: ${result.error}`);
+     * }
+     * ```
+     */
+    validate(nsid, record) {
+        if (!this.isRegistered(nsid)) {
+            return {
+                valid: false,
+                error: `Lexicon ${nsid} is not registered`,
+            };
+        }
+        try {
+            this.lexicons.assertValidRecord(nsid, record);
+            return { valid: true };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: error instanceof Error ? error.message : "Validation failed",
+            };
+        }
+    }
+    /**
+     * Adds all registered lexicons to an AT Protocol Agent.
+     *
+     * This method is currently a no-op as the AT Protocol Agent
+     * doesn't provide a public API for adding lexicons at runtime.
+     * Lexicons must be registered with the server.
+     *
+     * This method is kept for future compatibility if the API
+     * adds support for client-side lexicon registration.
+     *
+     * @param _agent - The AT Protocol Agent (currently unused)
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent(session);
+     * registry.addToAgent(agent);
+     * // Reserved for future use
+     * ```
+     */
+    addToAgent(_agent) {
+        // No-op: AT Protocol Agent doesn't support client-side lexicon addition
+        // Lexicons are validated client-side via this registry,
+        // but server-side validation is performed by the PDS/SDS
+    }
+    /**
+     * Gets the underlying Lexicons instance.
+     *
+     * This provides direct access to the AT Protocol Lexicons object
+     * for advanced use cases.
+     *
+     * @returns The internal Lexicons instance
+     *
+     * @example
+     * ```typescript
+     * const lexicons = registry.getLexicons();
+     * // Use lexicons directly for advanced operations
+     * ```
+     */
+    getLexicons() {
+        return this.lexicons;
+    }
+}
 
 /**
  * Lexicons entrypoint - Lexicon definitions and registry.
@@ -66,20 +468,21 @@ import { CERTIFIED_DEFS_LEXICON_JSON, LOCATION_LEXICON_JSON, STRONGREF_LEXICON_J
 const HYPERCERT_LEXICONS = [
     CERTIFIED_DEFS_LEXICON_JSON,
     LOCATION_LEXICON_JSON,
-    STRONGREF_LEXICON_JSON,
+    STRONG_REF_LEXICON_JSON,
     HYPERCERTS_DEFS_LEXICON_JSON,
     ACTIVITY_LEXICON_JSON,
     COLLECTION_LEXICON_JSON,
-    CONTRIBUTION_LEXICON_JSON,
+    CONTRIBUTION_DETAILS_LEXICON_JSON,
+    CONTRIBUTOR_INFORMATION_LEXICON_JSON,
     EVALUATION_LEXICON_JSON,
     EVIDENCE_LEXICON_JSON,
     MEASUREMENT_LEXICON_JSON,
     RIGHTS_LEXICON_JSON,
-    PROJECT_LEXICON_JSON,
     BADGE_AWARD_LEXICON_JSON,
     BADGE_DEFINITION_LEXICON_JSON,
     BADGE_RESPONSE_LEXICON_JSON,
     FUNDING_RECEIPT_LEXICON_JSON,
+    WORK_SCOPE_TAG_LEXICON_JSON,
 ];
 /**
  * Collection NSIDs (Namespaced Identifiers) for hypercert records.
@@ -101,9 +504,15 @@ const HYPERCERT_COLLECTIONS = {
      */
     LOCATION: LOCATION_NSID,
     /**
-     * Contribution record collection.
+     * Contribution details record collection.
+     * For storing details about a specific contribution (role, description, timeframe).
+     */
+    CONTRIBUTION_DETAILS: CONTRIBUTION_DETAILS_NSID,
+    /**
+     * Contributor information record collection.
+     * For storing contributor profile information (identifier, displayName, image).
      */
-    CONTRIBUTION: CONTRIBUTION_NSID,
+    CONTRIBUTOR_INFORMATION: CONTRIBUTOR_INFORMATION_NSID,
     /**
      * Measurement record collection.
      */
@@ -118,12 +527,9 @@ const HYPERCERT_COLLECTIONS = {
     EVIDENCE: EVIDENCE_NSID,
     /**
      * Collection record collection (groups of hypercerts).
+     * Projects are now collections with type='project'.
      */
     COLLECTION: COLLECTION_NSID,
-    /**
-     * Project record collection.
-     */
-    PROJECT: PROJECT_NSID,
     /**
      * Badge award record collection.
      */
@@ -140,7 +546,12 @@ const HYPERCERT_COLLECTIONS = {
      * Funding receipt record collection.
      */
     FUNDING_RECEIPT: FUNDING_RECEIPT_NSID,
+    /**
+     * Work scope tag record collection.
+     * For defining reusable work scope atoms.
+     */
+    WORK_SCOPE_TAG: WORK_SCOPE_TAG_NSID,
 };
 
-export { HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS };
+export { HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS, LexiconRegistry };
 //# sourceMappingURL=lexicons.mjs.map

package/dist/lexicons.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"lexicons.mjs","sources":["../src/lexicons.ts"],"sourcesContent":["/**\n * Lexicons entrypoint - Lexicon definitions and registry.\n *\n * This sub-entrypoint exports the lexicon registry and hypercert\n * lexicon constants for working with AT Protocol record schemas.\n *\n * @remarks\n * Import from `@hypercerts-org/sdk/lexicons`:\n *\n * ```typescript\n * import {\n *   LexiconRegistry,\n *   HYPERCERT_LEXICONS,\n *   HYPERCERT_COLLECTIONS,\n * } from \"@hypercerts-org/sdk/lexicons\";\n * ```\n *\n * **Exports**:\n * - {@link LexiconRegistry} - Registry for managing and validating lexicons\n * - {@link HYPERCERT_LEXICONS} - Array of all hypercert lexicon documents\n * - {@link HYPERCERT_COLLECTIONS} - Constants for collection NSIDs\n *\n * @example Using collection constants\n * ```typescript\n * import { HYPERCERT_COLLECTIONS } from \"@hypercerts-org/sdk/lexicons\";\n *\n * // List hypercerts using the correct collection name\n * const records = await repo.records.list({\n *   collection: HYPERCERT_COLLECTIONS.RECORD,\n * });\n *\n * // List contributions\n * const contributions = await repo.records.list({\n *   collection: HYPERCERT_COLLECTIONS.CONTRIBUTION,\n * });\n * ```\n *\n * @example Custom lexicon registration\n * ```typescript\n * import { LexiconRegistry } from \"@hypercerts-org/sdk/lexicons\";\n *\n * const registry = sdk.getLexiconRegistry();\n *\n * // Register custom lexicon\n * registry.register({\n *   lexicon: 1,\n *   id: \"org.myapp.customRecord\",\n *   defs: { ... },\n * });\n *\n * // Validate a record\n * const result = registry.validate(\"org.myapp.customRecord\", record);\n * if (!result.valid) {\n *   console.error(result.error);\n * }\n * ```\n *\n * @packageDocumentation\n */\n\n// Import lexicon JSON files and constants from the published package\nimport type { LexiconDoc } from \"@atproto/lexicon\";\nimport {\n  CERTIFIED_DEFS_LEXICON_JSON,\n  LOCATION_LEXICON_JSON,\n  STRONGREF_LEXICON_JSON,\n  HYPERCERTS_DEFS_LEXICON_JSON,\n  ACTIVITY_LEXICON_JSON,\n  COLLECTION_LEXICON_JSON,\n  CONTRIBUTION_LEXICON_JSON,\n  EVALUATION_LEXICON_JSON,\n  EVIDENCE_LEXICON_JSON,\n  MEASUREMENT_LEXICON_JSON,\n  RIGHTS_LEXICON_JSON,\n  PROJECT_LEXICON_JSON,\n  BADGE_AWARD_LEXICON_JSON,\n  BADGE_DEFINITION_LEXICON_JSON,\n  BADGE_RESPONSE_LEXICON_JSON,\n  FUNDING_RECEIPT_LEXICON_JSON,\n  // NSID constants\n  ACTIVITY_NSID,\n  RIGHTS_NSID,\n  LOCATION_NSID,\n  CONTRIBUTION_NSID,\n  MEASUREMENT_NSID,\n  EVALUATION_NSID,\n  EVIDENCE_NSID,\n  COLLECTION_NSID,\n  PROJECT_NSID,\n  BADGE_AWARD_NSID,\n  BADGE_DEFINITION_NSID,\n  BADGE_RESPONSE_NSID,\n  FUNDING_RECEIPT_NSID,\n} from \"@hypercerts-org/lexicon\";\n\n/**\n * All hypercert-related lexicons for registration with AT Protocol Agent.\n * This array contains all lexicon documents from the published package.\n */\nexport const HYPERCERT_LEXICONS: LexiconDoc[] = [\n  CERTIFIED_DEFS_LEXICON_JSON as LexiconDoc,\n  LOCATION_LEXICON_JSON as LexiconDoc,\n  STRONGREF_LEXICON_JSON as LexiconDoc,\n  HYPERCERTS_DEFS_LEXICON_JSON as LexiconDoc,\n  ACTIVITY_LEXICON_JSON as LexiconDoc,\n  COLLECTION_LEXICON_JSON as LexiconDoc,\n  CONTRIBUTION_LEXICON_JSON as LexiconDoc,\n  EVALUATION_LEXICON_JSON as LexiconDoc,\n  EVIDENCE_LEXICON_JSON as LexiconDoc,\n  MEASUREMENT_LEXICON_JSON as LexiconDoc,\n  RIGHTS_LEXICON_JSON as LexiconDoc,\n  PROJECT_LEXICON_JSON as LexiconDoc,\n  BADGE_AWARD_LEXICON_JSON as LexiconDoc,\n  BADGE_DEFINITION_LEXICON_JSON as LexiconDoc,\n  BADGE_RESPONSE_LEXICON_JSON as LexiconDoc,\n  FUNDING_RECEIPT_LEXICON_JSON as LexiconDoc,\n];\n\n/**\n * Collection NSIDs (Namespaced Identifiers) for hypercert records.\n *\n * Use these constants when performing record operations to ensure\n * correct collection names.\n */\nexport const HYPERCERT_COLLECTIONS = {\n  /**\n   * Main hypercert claim record collection.\n   */\n  CLAIM: ACTIVITY_NSID,\n\n  /**\n   * Rights record collection.\n   */\n  RIGHTS: RIGHTS_NSID,\n\n  /**\n   * Location record collection (shared certified lexicon).\n   */\n  LOCATION: LOCATION_NSID,\n\n  /**\n   * Contribution record collection.\n   */\n  CONTRIBUTION: CONTRIBUTION_NSID,\n\n  /**\n   * Measurement record collection.\n   */\n  MEASUREMENT: MEASUREMENT_NSID,\n\n  /**\n   * Evaluation record collection.\n   */\n  EVALUATION: EVALUATION_NSID,\n\n  /**\n   * Evidence record collection.\n   */\n  EVIDENCE: EVIDENCE_NSID,\n\n  /**\n   * Collection record collection (groups of hypercerts).\n   */\n  COLLECTION: COLLECTION_NSID,\n\n  /**\n   * Project record collection.\n   */\n  PROJECT: PROJECT_NSID,\n\n  /**\n   * Badge award record collection.\n   */\n  BADGE_AWARD: BADGE_AWARD_NSID,\n\n  /**\n   * Badge definition record collection.\n   */\n  BADGE_DEFINITION: BADGE_DEFINITION_NSID,\n\n  /**\n   * Badge response record collection.\n   */\n  BADGE_RESPONSE: BADGE_RESPONSE_NSID,\n\n  /**\n   * Funding receipt record collection.\n   */\n  FUNDING_RECEIPT: FUNDING_RECEIPT_NSID,\n} as const;\n"],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;AAqCH;;;AAGG;AACI,MAAM,kBAAkB,GAAiB;IAC9C,2BAAyC;IACzC,qBAAmC;IACnC,sBAAoC;IACpC,4BAA0C;IAC1C,qBAAmC;IACnC,uBAAqC;IACrC,yBAAuC;IACvC,uBAAqC;IACrC,qBAAmC;IACnC,wBAAsC;IACtC,mBAAiC;IACjC,oBAAkC;IAClC,wBAAsC;IACtC,6BAA2C;IAC3C,2BAAyC;IACzC,4BAA0C;;AAG5C;;;;;AAKG;AACI,MAAM,qBAAqB,GAAG;AACnC;;AAEG;AACH,IAAA,KAAK,EAAE,aAAa;AAEpB;;AAEG;AACH,IAAA,MAAM,EAAE,WAAW;AAEnB;;AAEG;AACH,IAAA,QAAQ,EAAE,aAAa;AAEvB;;AAEG;AACH,IAAA,YAAY,EAAE,iBAAiB;AAE/B;;AAEG;AACH,IAAA,WAAW,EAAE,gBAAgB;AAE7B;;AAEG;AACH,IAAA,UAAU,EAAE,eAAe;AAE3B;;AAEG;AACH,IAAA,QAAQ,EAAE,aAAa;AAEvB;;AAEG;AACH,IAAA,UAAU,EAAE,eAAe;AAE3B;;AAEG;AACH,IAAA,OAAO,EAAE,YAAY;AAErB;;AAEG;AACH,IAAA,WAAW,EAAE,gBAAgB;AAE7B;;AAEG;AACH,IAAA,gBAAgB,EAAE,qBAAqB;AAEvC;;AAEG;AACH,IAAA,cAAc,EAAE,mBAAmB;AAEnC;;AAEG;AACH,IAAA,eAAe,EAAE,oBAAoB;;;;;"}
+{"version":3,"file":"lexicons.mjs","sources":["../src/core/errors.ts","../src/repository/LexiconRegistry.ts","../src/lexicons.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","/**\n * LexiconRegistry - Manages custom lexicon registration and validation.\n *\n * This module provides a registry for AT Protocol lexicon schemas,\n * allowing developers to register custom lexicons and validate records\n * against registered schemas.\n *\n * @packageDocumentation\n */\n\nimport type { LexiconDoc } from \"@atproto/lexicon\";\nimport { Lexicons } from \"@atproto/lexicon\";\nimport type { Agent } from \"@atproto/api\";\nimport { ValidationError } from \"../errors.js\";\n\n/**\n * Validation result from lexicon validation.\n */\nexport interface ValidationResult {\n  /**\n   * Whether the record is valid according to the lexicon.\n   */\n  valid: boolean;\n\n  /**\n   * Error message if validation failed.\n   */\n  error?: string;\n}\n\n/**\n * Registry for managing AT Protocol lexicon schemas.\n *\n * The LexiconRegistry allows developers to:\n * - Register custom lexicon definitions\n * - Validate records against registered schemas\n * - Query registered lexicons\n * - Add lexicons to AT Protocol agents\n *\n * @example Basic usage\n * ```typescript\n * const registry = new LexiconRegistry();\n *\n * // Register a custom lexicon\n * registry.register({\n *   lexicon: 1,\n *   id: \"org.myapp.customRecord\",\n *   defs: {\n *     main: {\n *       type: \"record\",\n *       key: \"tid\",\n *       record: {\n *         type: \"object\",\n *         required: [\"$type\", \"title\"],\n *         properties: {\n *           \"$type\": { type: \"string\", const: \"org.myapp.customRecord\" },\n *           title: { type: \"string\" }\n *         }\n *       }\n *     }\n *   }\n * });\n *\n * // Validate a record\n * const result = registry.validate(\"org.myapp.customRecord\", {\n *   $type: \"org.myapp.customRecord\",\n *   title: \"My Record\"\n * });\n *\n * if (!result.valid) {\n *   console.error(result.error);\n * }\n * ```\n */\nexport class LexiconRegistry {\n  private lexicons: Lexicons;\n  private registeredIds: Set<string>;\n\n  /**\n   * Creates a new LexiconRegistry instance.\n   *\n   * @param initialLexicons - Optional array of lexicons to register on initialization\n   */\n  constructor(initialLexicons?: LexiconDoc[]) {\n    this.lexicons = new Lexicons();\n    this.registeredIds = new Set();\n\n    if (initialLexicons && initialLexicons.length > 0) {\n      this.registerMany(initialLexicons);\n    }\n  }\n\n  /**\n   * Registers a single lexicon definition.\n   *\n   * @param lexicon - The lexicon document to register\n   * @throws {Error} If the lexicon is invalid or already registered\n   *\n   * @example\n   * ```typescript\n   * registry.register({\n   *   lexicon: 1,\n   *   id: \"org.myapp.customRecord\",\n   *   defs: { ... }\n   * });\n   * ```\n   */\n  register(lexicon: LexiconDoc): void {\n    if (!lexicon.id) {\n      throw new Error(\"Lexicon must have an id\");\n    }\n\n    if (this.registeredIds.has(lexicon.id)) {\n      throw new Error(`Lexicon ${lexicon.id} is already registered`);\n    }\n\n    try {\n      // Check if the lexicon already exists in the internal store\n      // (e.g., after unregister which only removes from registeredIds)\n      const existingLexicon = this.lexicons.get(lexicon.id);\n\n      if (!existingLexicon) {\n        // Lexicon is truly new, add it to the store\n        this.lexicons.add(lexicon);\n      }\n\n      // Always add to registeredIds (re-enable if previously unregistered)\n      this.registeredIds.add(lexicon.id);\n    } catch (error) {\n      throw new Error(\n        `Failed to register lexicon ${lexicon.id}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      );\n    }\n  }\n\n  /**\n   * Registers multiple lexicon definitions at once.\n   *\n   * @param lexicons - Array of lexicon documents to register\n   * @throws {Error} If any lexicon is invalid or already registered\n   *\n   * @example\n   * ```typescript\n   * registry.registerMany([lexicon1, lexicon2, lexicon3]);\n   * ```\n   */\n  registerMany(lexicons: LexiconDoc[]): void {\n    for (const lexicon of lexicons) {\n      this.register(lexicon);\n    }\n  }\n\n  /**\n   * Registers a lexicon from a JSON object.\n   *\n   * This is a convenience method for registering lexicons loaded from JSON files.\n   *\n   * @param lexiconJson - The lexicon as a plain JavaScript object\n   * @throws {ValidationError} If the lexicon is not a valid object\n   * @throws {Error} If the lexicon is invalid or already registered\n   *\n   * @example\n   * ```typescript\n   * import customLexicon from \"./custom-lexicon.json\";\n   * registry.registerFromJSON(customLexicon);\n   * ```\n   */\n  registerFromJSON(lexiconJson: unknown): void {\n    // Validate that input is an object and not null\n    if (typeof lexiconJson !== \"object\" || lexiconJson === null) {\n      throw new ValidationError(\"Lexicon JSON must be a valid object\");\n    }\n\n    // Now we can safely cast to LexiconDoc and register\n    this.register(lexiconJson as LexiconDoc);\n  }\n\n  /**\n   * Unregisters a lexicon by its NSID.\n   *\n   * @param nsid - The NSID of the lexicon to unregister\n   * @returns True if the lexicon was unregistered, false if it wasn't registered\n   *\n   * @example\n   * ```typescript\n   * registry.unregister(\"org.myapp.customRecord\");\n   * ```\n   */\n  unregister(nsid: string): boolean {\n    if (!this.registeredIds.has(nsid)) {\n      return false;\n    }\n\n    this.registeredIds.delete(nsid);\n    // Note: Lexicons class doesn't have a remove method,\n    // so we can't actually remove from the internal store.\n    // We track removal in our Set for isRegistered checks.\n    return true;\n  }\n\n  /**\n   * Checks if a lexicon is registered.\n   *\n   * @param nsid - The NSID to check\n   * @returns True if the lexicon is registered\n   *\n   * @example\n   * ```typescript\n   * if (registry.isRegistered(\"org.myapp.customRecord\")) {\n   *   // Lexicon is available\n   * }\n   * ```\n   */\n  isRegistered(nsid: string): boolean {\n    return this.registeredIds.has(nsid);\n  }\n\n  /**\n   * Gets a lexicon definition by its NSID.\n   *\n   * @param nsid - The NSID of the lexicon to retrieve\n   * @returns The lexicon document, or undefined if not found\n   *\n   * @example\n   * ```typescript\n   * const lexicon = registry.get(\"org.myapp.customRecord\");\n   * if (lexicon) {\n   *   console.log(lexicon.defs);\n   * }\n   * ```\n   */\n  get(nsid: string): LexiconDoc | undefined {\n    if (!this.isRegistered(nsid)) {\n      return undefined;\n    }\n\n    return this.lexicons.get(nsid);\n  }\n\n  /**\n   * Gets all registered lexicon NSIDs.\n   *\n   * @returns Array of registered NSIDs\n   *\n   * @example\n   * ```typescript\n   * const registered = registry.getAll();\n   * console.log(`Registered lexicons: ${registered.join(\", \")}`);\n   * ```\n   */\n  getAll(): string[] {\n    return Array.from(this.registeredIds);\n  }\n\n  /**\n   * Validates a record against a registered lexicon.\n   *\n   * @param nsid - The collection NSID to validate against\n   * @param record - The record data to validate\n   * @returns Validation result with success status and optional error message\n   *\n   * @example\n   * ```typescript\n   * const result = registry.validate(\"org.myapp.customRecord\", {\n   *   $type: \"org.myapp.customRecord\",\n   *   title: \"My Record\"\n   * });\n   *\n   * if (!result.valid) {\n   *   console.error(`Validation failed: ${result.error}`);\n   * }\n   * ```\n   */\n  validate(nsid: string, record: unknown): ValidationResult {\n    if (!this.isRegistered(nsid)) {\n      return {\n        valid: false,\n        error: `Lexicon ${nsid} is not registered`,\n      };\n    }\n\n    try {\n      this.lexicons.assertValidRecord(nsid, record);\n      return { valid: true };\n    } catch (error) {\n      return {\n        valid: false,\n        error: error instanceof Error ? error.message : \"Validation failed\",\n      };\n    }\n  }\n\n  /**\n   * Adds all registered lexicons to an AT Protocol Agent.\n   *\n   * This method is currently a no-op as the AT Protocol Agent\n   * doesn't provide a public API for adding lexicons at runtime.\n   * Lexicons must be registered with the server.\n   *\n   * This method is kept for future compatibility if the API\n   * adds support for client-side lexicon registration.\n   *\n   * @param _agent - The AT Protocol Agent (currently unused)\n   *\n   * @example\n   * ```typescript\n   * const agent = new Agent(session);\n   * registry.addToAgent(agent);\n   * // Reserved for future use\n   * ```\n   */\n  addToAgent(_agent: Agent): void {\n    // No-op: AT Protocol Agent doesn't support client-side lexicon addition\n    // Lexicons are validated client-side via this registry,\n    // but server-side validation is performed by the PDS/SDS\n  }\n\n  /**\n   * Gets the underlying Lexicons instance.\n   *\n   * This provides direct access to the AT Protocol Lexicons object\n   * for advanced use cases.\n   *\n   * @returns The internal Lexicons instance\n   *\n   * @example\n   * ```typescript\n   * const lexicons = registry.getLexicons();\n   * // Use lexicons directly for advanced operations\n   * ```\n   */\n  getLexicons(): Lexicons {\n    return this.lexicons;\n  }\n}\n","/**\n * Lexicons entrypoint - Lexicon definitions and registry.\n *\n * This sub-entrypoint exports the lexicon registry and hypercert\n * lexicon constants for working with AT Protocol record schemas.\n *\n * @remarks\n * Import from `@hypercerts-org/sdk/lexicons`:\n *\n * ```typescript\n * import {\n *   LexiconRegistry,\n *   HYPERCERT_LEXICONS,\n *   HYPERCERT_COLLECTIONS,\n * } from \"@hypercerts-org/sdk/lexicons\";\n * ```\n *\n * **Exports**:\n * - {@link LexiconRegistry} - Registry for managing and validating lexicons\n * - {@link HYPERCERT_LEXICONS} - Array of all hypercert lexicon documents\n * - {@link HYPERCERT_COLLECTIONS} - Constants for collection NSIDs\n *\n * @example Using collection constants\n * ```typescript\n * import { HYPERCERT_COLLECTIONS } from \"@hypercerts-org/sdk/lexicons\";\n *\n * // List hypercerts using the correct collection name\n * const records = await repo.records.list({\n *   collection: HYPERCERT_COLLECTIONS.RECORD,\n * });\n *\n * // List contributions\n * const contributions = await repo.records.list({\n *   collection: HYPERCERT_COLLECTIONS.CONTRIBUTION,\n * });\n * ```\n *\n * @example Custom lexicon registration\n * ```typescript\n * import { LexiconRegistry } from \"@hypercerts-org/sdk/lexicons\";\n *\n * const registry = sdk.getLexiconRegistry();\n *\n * // Register custom lexicon\n * registry.register({\n *   lexicon: 1,\n *   id: \"org.myapp.customRecord\",\n *   defs: { ... },\n * });\n *\n * // Validate a record\n * const result = registry.validate(\"org.myapp.customRecord\", record);\n * if (!result.valid) {\n *   console.error(result.error);\n * }\n * ```\n *\n * @packageDocumentation\n */\n\n// Import lexicon JSON files and constants from the published package\nimport type { LexiconDoc } from \"@atproto/lexicon\";\nimport {\n  CERTIFIED_DEFS_LEXICON_JSON,\n  LOCATION_LEXICON_JSON,\n  STRONG_REF_LEXICON_JSON,\n  HYPERCERTS_DEFS_LEXICON_JSON,\n  ACTIVITY_LEXICON_JSON,\n  COLLECTION_LEXICON_JSON,\n  CONTRIBUTION_DETAILS_LEXICON_JSON,\n  CONTRIBUTOR_INFORMATION_LEXICON_JSON,\n  EVALUATION_LEXICON_JSON,\n  EVIDENCE_LEXICON_JSON,\n  MEASUREMENT_LEXICON_JSON,\n  RIGHTS_LEXICON_JSON,\n  BADGE_AWARD_LEXICON_JSON,\n  BADGE_DEFINITION_LEXICON_JSON,\n  BADGE_RESPONSE_LEXICON_JSON,\n  FUNDING_RECEIPT_LEXICON_JSON,\n  WORK_SCOPE_TAG_LEXICON_JSON,\n  // NSID constants\n  ACTIVITY_NSID,\n  RIGHTS_NSID,\n  LOCATION_NSID,\n  CONTRIBUTION_DETAILS_NSID,\n  CONTRIBUTOR_INFORMATION_NSID,\n  MEASUREMENT_NSID,\n  EVALUATION_NSID,\n  EVIDENCE_NSID,\n  COLLECTION_NSID,\n  BADGE_AWARD_NSID,\n  BADGE_DEFINITION_NSID,\n  BADGE_RESPONSE_NSID,\n  FUNDING_RECEIPT_NSID,\n  WORK_SCOPE_TAG_NSID,\n} from \"@hypercerts-org/lexicon\";\n\n// Export LexiconRegistry for custom lexicon management\nexport { LexiconRegistry } from \"./repository/LexiconRegistry.js\";\nexport type { ValidationResult } from \"./repository/LexiconRegistry.js\";\n\n/**\n * All hypercert-related lexicons for registration with AT Protocol Agent.\n * This array contains all lexicon documents from the published package.\n */\nexport const HYPERCERT_LEXICONS: LexiconDoc[] = [\n  CERTIFIED_DEFS_LEXICON_JSON as LexiconDoc,\n  LOCATION_LEXICON_JSON as LexiconDoc,\n  STRONG_REF_LEXICON_JSON as LexiconDoc,\n  HYPERCERTS_DEFS_LEXICON_JSON as LexiconDoc,\n  ACTIVITY_LEXICON_JSON as LexiconDoc,\n  COLLECTION_LEXICON_JSON as LexiconDoc,\n  CONTRIBUTION_DETAILS_LEXICON_JSON as LexiconDoc,\n  CONTRIBUTOR_INFORMATION_LEXICON_JSON as LexiconDoc,\n  EVALUATION_LEXICON_JSON as LexiconDoc,\n  EVIDENCE_LEXICON_JSON as LexiconDoc,\n  MEASUREMENT_LEXICON_JSON as LexiconDoc,\n  RIGHTS_LEXICON_JSON as LexiconDoc,\n  BADGE_AWARD_LEXICON_JSON as LexiconDoc,\n  BADGE_DEFINITION_LEXICON_JSON as LexiconDoc,\n  BADGE_RESPONSE_LEXICON_JSON as LexiconDoc,\n  FUNDING_RECEIPT_LEXICON_JSON as LexiconDoc,\n  WORK_SCOPE_TAG_LEXICON_JSON as LexiconDoc,\n];\n\n/**\n * Collection NSIDs (Namespaced Identifiers) for hypercert records.\n *\n * Use these constants when performing record operations to ensure\n * correct collection names.\n */\nexport const HYPERCERT_COLLECTIONS = {\n  /**\n   * Main hypercert claim record collection.\n   */\n  CLAIM: ACTIVITY_NSID,\n\n  /**\n   * Rights record collection.\n   */\n  RIGHTS: RIGHTS_NSID,\n\n  /**\n   * Location record collection (shared certified lexicon).\n   */\n  LOCATION: LOCATION_NSID,\n\n  /**\n   * Contribution details record collection.\n   * For storing details about a specific contribution (role, description, timeframe).\n   */\n  CONTRIBUTION_DETAILS: CONTRIBUTION_DETAILS_NSID,\n\n  /**\n   * Contributor information record collection.\n   * For storing contributor profile information (identifier, displayName, image).\n   */\n  CONTRIBUTOR_INFORMATION: CONTRIBUTOR_INFORMATION_NSID,\n\n  /**\n   * Measurement record collection.\n   */\n  MEASUREMENT: MEASUREMENT_NSID,\n\n  /**\n   * Evaluation record collection.\n   */\n  EVALUATION: EVALUATION_NSID,\n\n  /**\n   * Evidence record collection.\n   */\n  EVIDENCE: EVIDENCE_NSID,\n\n  /**\n   * Collection record collection (groups of hypercerts).\n   * Projects are now collections with type='project'.\n   */\n  COLLECTION: COLLECTION_NSID,\n\n  /**\n   * Badge award record collection.\n   */\n  BADGE_AWARD: BADGE_AWARD_NSID,\n\n  /**\n   * Badge definition record collection.\n   */\n  BADGE_DEFINITION: BADGE_DEFINITION_NSID,\n\n  /**\n   * Badge response record collection.\n   */\n  BADGE_RESPONSE: BADGE_RESPONSE_NSID,\n\n  /**\n   * Funding receipt record collection.\n   */\n  FUNDING_RECEIPT: FUNDING_RECEIPT_NSID,\n\n  /**\n   * Work scope tag record collection.\n   * For defining reusable work scope atoms.\n   */\n  WORK_SCOPE_TAG: WORK_SCOPE_TAG_NSID,\n} as const;\n"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -348,22 +348,28 @@ interface LoggerInterface {
  * Zod schema for OAuth configuration validation.
  *
  * @remarks
- * All URLs must be valid and use HTTPS in production. The `jwkPrivate` field
- * should contain the private key in JWK (JSON Web Key) format as a string.
+ * All URLs must be valid and use HTTPS in production. For local development,
+ * HTTP loopback URLs (localhost, 127.0.0.1, [::1]) are allowed.
+ * The `jwkPrivate` field should contain the private key in JWK (JSON Web Key) format as a string.
  */
 declare const OAuthConfigSchema: z.ZodObject<{
     /**
      * URL to the OAuth client metadata JSON document.
      * This document describes your application to the authorization server.
      *
+     * For local development, you can use `http://localhost/` as a loopback client.
+     *
      * @see https://atproto.com/specs/oauth#client-metadata
      */
-    clientId: z.ZodString;
+    clientId: z.ZodEffects<z.ZodString, string, string>;
     /**
      * URL where users are redirected after authentication.
      * Must match one of the redirect URIs in your client metadata.
+     *
+     * For local development, you can use HTTP loopback URLs like
+     * `http://127.0.0.1:3000/callback` or `http://localhost:3000/callback`.
      */
-    redirectUri: z.ZodString;
+    redirectUri: z.ZodEffects<z.ZodString, string, string>;
     /**
      * OAuth scopes to request, space-separated.
      *
@@ -397,8 +403,11 @@ declare const OAuthConfigSchema: z.ZodObject<{
     /**
      * URL to your public JWKS (JSON Web Key Set) endpoint.
      * Used by the authorization server to verify your client's signatures.
+     *
+     * For local development, you can serve JWKS from a loopback URL like
+     * `http://127.0.0.1:3000/.well-known/jwks.json`.
      */
-    jwksUri: z.ZodString;
+    jwksUri: z.ZodEffects<z.ZodString, string, string>;
     /**
      * Private JWK (JSON Web Key) as a JSON string.
      * Used for signing DPoP proofs and client assertions.
@@ -408,40 +417,78 @@ declare const OAuthConfigSchema: z.ZodObject<{
      * Typically loaded from environment variables or a secrets manager.
      */
     jwkPrivate: z.ZodString;
+    /**
+     * Enable development mode features (optional).
+     *
+     * When true, suppresses warnings about using HTTP loopback URLs.
+     * Should be set to true for local development to reduce console noise.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * oauth: {
+     *   clientId: "http://localhost/",
+     *   redirectUri: "http://127.0.0.1:3000/callback",
+     *   // ... other config
+     *   developmentMode: true, // Suppress loopback warnings
+     * }
+     * ```
+     */
+    developmentMode: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     clientId: string;
     redirectUri: string;
     scope: string;
     jwksUri: string;
     jwkPrivate: string;
+    developmentMode?: boolean | undefined;
 }, {
     clientId: string;
     redirectUri: string;
     scope: string;
     jwksUri: string;
     jwkPrivate: string;
+    developmentMode?: boolean | undefined;
 }>;
 /**
  * Zod schema for server URL configuration.
  *
  * @remarks
  * At least one server (PDS or SDS) should be configured for the SDK to be useful.
+ * For local development, HTTP loopback URLs are allowed.
  */
 declare const ServerConfigSchema: z.ZodObject<{
     /**
      * Personal Data Server URL - the user's own AT Protocol server.
      * This is the primary server for user data operations.
      *
-     * @example "https://bsky.social"
+     * @example Production
+     * ```typescript
+     * pds: "https://bsky.social"
+     * ```
+     *
+     * @example Local development
+     * ```typescript
+     * pds: "http://localhost:2583"
+     * ```
      */
-    pds: z.ZodOptional<z.ZodString>;
+    pds: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     /**
      * Shared Data Server URL - for collaborative data storage.
      * Required for collaborator and organization operations.
      *
-     * @example "https://sds.hypercerts.org"
+     * @example Production
+     * ```typescript
+     * sds: "https://sds.hypercerts.org"
+     * ```
+     *
+     * @example Local development
+     * ```typescript
+     * sds: "http://127.0.0.1:2584"
+     * ```
      */
-    sds: z.ZodOptional<z.ZodString>;
+    sds: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
     pds?: string | undefined;
     sds?: string | undefined;