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

package/dist/lexicons.d.ts

@@ -1,4 +1,235 @@
-import { LexiconDoc } from '@atproto/lexicon';
+import { LexiconDoc, Lexicons } from '@atproto/lexicon';
+import { Agent } from '@atproto/api';
+
+/**
+ * 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
+ */
+
+/**
+ * Validation result from lexicon validation.
+ */
+interface ValidationResult {
+    /**
+     * Whether the record is valid according to the lexicon.
+     */
+    valid: boolean;
+    /**
+     * Error message if validation failed.
+     */
+    error?: string;
+}
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare class LexiconRegistry {
+    private lexicons;
+    private registeredIds;
+    /**
+     * Creates a new LexiconRegistry instance.
+     *
+     * @param initialLexicons - Optional array of lexicons to register on initialization
+     */
+    constructor(initialLexicons?: LexiconDoc[]);
+    /**
+     * 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: LexiconDoc): void;
+    /**
+     * 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: LexiconDoc[]): void;
+    /**
+     * 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: unknown): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string): LexiconDoc | undefined;
+    /**
+     * Gets all registered lexicon NSIDs.
+     *
+     * @returns Array of registered NSIDs
+     *
+     * @example
+     * ```typescript
+     * const registered = registry.getAll();
+     * console.log(`Registered lexicons: ${registered.join(", ")}`);
+     * ```
+     */
+    getAll(): string[];
+    /**
+     * 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: string, record: unknown): ValidationResult;
+    /**
+     * 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: Agent): void;
+    /**
+     * 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(): Lexicons;
+}
 
 /**
  * Lexicons entrypoint - Lexicon definitions and registry.
@@ -85,9 +316,15 @@ declare const HYPERCERT_COLLECTIONS: {
      */
     readonly LOCATION: "app.certified.location";
     /**
-     * Contribution record collection.
+     * Contribution details record collection.
+     * For storing details about a specific contribution (role, description, timeframe).
+     */
+    readonly CONTRIBUTION_DETAILS: "org.hypercerts.claim.contributionDetails";
+    /**
+     * Contributor information record collection.
+     * For storing contributor profile information (identifier, displayName, image).
      */
-    readonly CONTRIBUTION: "org.hypercerts.claim.contribution";
+    readonly CONTRIBUTOR_INFORMATION: "org.hypercerts.claim.contributorInformation";
     /**
      * Measurement record collection.
      */
@@ -102,12 +339,9 @@ declare const HYPERCERT_COLLECTIONS: {
     readonly EVIDENCE: "org.hypercerts.claim.evidence";
     /**
      * Collection record collection (groups of hypercerts).
+     * Projects are now collections with type='project'.
      */
     readonly COLLECTION: "org.hypercerts.claim.collection";
-    /**
-     * Project record collection.
-     */
-    readonly PROJECT: "org.hypercerts.claim.project";
     /**
      * Badge award record collection.
      */
@@ -124,6 +358,12 @@ declare const HYPERCERT_COLLECTIONS: {
      * Funding receipt record collection.
      */
     readonly FUNDING_RECEIPT: "org.hypercerts.funding.receipt";
+    /**
+     * Work scope tag record collection.
+     * For defining reusable work scope atoms.
+     */
+    readonly WORK_SCOPE_TAG: "org.hypercerts.helper.workScopeTag";
 };
 
-export { HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS };
+export { HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS, LexiconRegistry };
+export type { ValidationResult };