@hypercerts-org/sdk-core 0.10.0-beta.0 → 0.10.0-beta.2

package/dist/index.d.ts

@@ -1,231 +1,11 @@
-import { Agent } from '@atproto/api';
-import { LexiconDoc } from '@atproto/lexicon';
 import { NodeSavedSession, NodeSavedState, OAuthSession } from '@atproto/oauth-client-node';
 import { z } from 'zod';
 import { EventEmitter } from 'eventemitter3';
-import { OrgHypercertsClaim, OrgHypercertsCollection, ComAtprotoRepoStrongRef, OrgHypercertsClaimRights, OrgHypercertsClaimContribution, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation, AppCertifiedLocation } from '@hypercerts-org/lexicon';
-export { AppCertifiedDefs, AppCertifiedLocation, ComAtprotoRepoStrongRef, HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS, OrgHypercertsClaim, OrgHypercertsClaimContribution, OrgHypercertsClaimEvaluation, OrgHypercertsClaimEvidence, OrgHypercertsClaimMeasurement, OrgHypercertsClaimRights, OrgHypercertsCollection, ids, lexicons, schemaDict, schemas, validate } 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;
-}
+import { OrgHypercertsClaimEvidence, OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, ComAtprotoRepoStrongRef, OrgHypercertsClaimRights, OrgHypercertsClaimContribution, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation, OrgHypercertsClaimProject, AppCertifiedLocation, AppCertifiedBadgeAward, AppCertifiedBadgeDefinition, AppCertifiedBadgeResponse, OrgHypercertsFundingReceipt, OrgHypercertsDefs } from '@hypercerts-org/lexicon';
+export { AppCertifiedBadgeAward, AppCertifiedBadgeDefinition, AppCertifiedBadgeResponse, AppCertifiedDefs, AppCertifiedLocation, ComAtprotoRepoStrongRef, HYPERCERTS_LEXICON_DOC, HYPERCERTS_LEXICON_JSON, HYPERCERTS_NSIDS, HYPERCERTS_NSIDS_BY_TYPE, HYPERCERTS_SCHEMAS, HYPERCERTS_SCHEMA_DICT, OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, OrgHypercertsClaimContribution, OrgHypercertsClaimEvaluation, OrgHypercertsClaimEvidence, OrgHypercertsClaimMeasurement, OrgHypercertsClaimProject, OrgHypercertsClaimRights, OrgHypercertsDefs, OrgHypercertsFundingReceipt, lexicons, validate } from '@hypercerts-org/lexicon';
+import { Agent } from '@atproto/api';
+import { LexiconDoc } from '@atproto/lexicon';
+export { BlobRef, JsonBlobRef } from '@atproto/lexicon';
 
 /**
  * Storage interface for persisting OAuth sessions.
@@ -1043,6 +823,132 @@ interface ProgressStep {
     error?: Error;
 }
 
+/**
+ * Lexicons entrypoint - Lexicon definitions and registry.
+ *
+ * This sub-entrypoint exports the lexicon registry and hypercert
+ * lexicon constants for working with AT Protocol record schemas.
+ *
+ * @remarks
+ * Import from `@hypercerts-org/sdk/lexicons`:
+ *
+ * ```typescript
+ * import {
+ *   LexiconRegistry,
+ *   HYPERCERT_LEXICONS,
+ *   HYPERCERT_COLLECTIONS,
+ * } from "@hypercerts-org/sdk/lexicons";
+ * ```
+ *
+ * **Exports**:
+ * - {@link LexiconRegistry} - Registry for managing and validating lexicons
+ * - {@link HYPERCERT_LEXICONS} - Array of all hypercert lexicon documents
+ * - {@link HYPERCERT_COLLECTIONS} - Constants for collection NSIDs
+ *
+ * @example Using collection constants
+ * ```typescript
+ * import { HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk/lexicons";
+ *
+ * // List hypercerts using the correct collection name
+ * const records = await repo.records.list({
+ *   collection: HYPERCERT_COLLECTIONS.RECORD,
+ * });
+ *
+ * // List contributions
+ * const contributions = await repo.records.list({
+ *   collection: HYPERCERT_COLLECTIONS.CONTRIBUTION,
+ * });
+ * ```
+ *
+ * @example Custom lexicon registration
+ * ```typescript
+ * import { LexiconRegistry } from "@hypercerts-org/sdk/lexicons";
+ *
+ * const registry = sdk.getLexiconRegistry();
+ *
+ * // Register custom lexicon
+ * registry.register({
+ *   lexicon: 1,
+ *   id: "org.myapp.customRecord",
+ *   defs: { ... },
+ * });
+ *
+ * // Validate a record
+ * const result = registry.validate("org.myapp.customRecord", record);
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * All hypercert-related lexicons for registration with AT Protocol Agent.
+ * This array contains all lexicon documents from the published package.
+ */
+declare const HYPERCERT_LEXICONS: LexiconDoc[];
+/**
+ * Collection NSIDs (Namespaced Identifiers) for hypercert records.
+ *
+ * Use these constants when performing record operations to ensure
+ * correct collection names.
+ */
+declare const HYPERCERT_COLLECTIONS: {
+    /**
+     * Main hypercert claim record collection.
+     */
+    readonly CLAIM: "org.hypercerts.claim.activity";
+    /**
+     * Rights record collection.
+     */
+    readonly RIGHTS: "org.hypercerts.claim.rights";
+    /**
+     * Location record collection (shared certified lexicon).
+     */
+    readonly LOCATION: "app.certified.location";
+    /**
+     * Contribution record collection.
+     */
+    readonly CONTRIBUTION: "org.hypercerts.claim.contribution";
+    /**
+     * Measurement record collection.
+     */
+    readonly MEASUREMENT: "org.hypercerts.claim.measurement";
+    /**
+     * Evaluation record collection.
+     */
+    readonly EVALUATION: "org.hypercerts.claim.evaluation";
+    /**
+     * Evidence record collection.
+     */
+    readonly EVIDENCE: "org.hypercerts.claim.evidence";
+    /**
+     * Collection record collection (groups of hypercerts).
+     */
+    readonly COLLECTION: "org.hypercerts.claim.collection";
+    /**
+     * Project record collection.
+     */
+    readonly PROJECT: "org.hypercerts.claim.project";
+    /**
+     * Badge award record collection.
+     */
+    readonly BADGE_AWARD: "app.certified.badge.award";
+    /**
+     * Badge definition record collection.
+     */
+    readonly BADGE_DEFINITION: "app.certified.badge.definition";
+    /**
+     * Badge response record collection.
+     */
+    readonly BADGE_RESPONSE: "app.certified.badge.response";
+    /**
+     * Funding receipt record collection.
+     */
+    readonly FUNDING_RECEIPT: "org.hypercerts.funding.receipt";
+};
+
 /**
  * TypeScript types for hypercert lexicon schemas.
  *
@@ -1052,30 +958,32 @@ interface ProgressStep {
  */
 
 type StrongRef = ComAtprotoRepoStrongRef.Main;
-type HypercertClaim = OrgHypercertsClaim.Main;
+type HypercertClaim = OrgHypercertsClaimActivity.Main;
 type HypercertRights = OrgHypercertsClaimRights.Main;
 type HypercertContribution = OrgHypercertsClaimContribution.Main;
 type HypercertMeasurement = OrgHypercertsClaimMeasurement.Main;
 type HypercertEvaluation = OrgHypercertsClaimEvaluation.Main;
-type HypercertCollection = OrgHypercertsCollection.Main;
-type HypercertCollectionClaimItem = OrgHypercertsCollection.ClaimItem;
+type HypercertEvidence = OrgHypercertsClaimEvidence.Main;
+type HypercertCollection = OrgHypercertsClaimCollection.Main;
+type HypercertCollectionClaimItem = OrgHypercertsClaimActivity.ActivityWeight;
+type HypercertProject = OrgHypercertsClaimProject.Main;
 type HypercertLocation = AppCertifiedLocation.Main;
-/** Blob reference for uploaded files (images, GeoJSON, etc.) */
-interface BlobRef {
-    $type: "blob";
-    ref: {
-        $link: string;
-    };
-    mimeType: string;
-    size: number;
-}
-/** Evidence item for operations */
-interface HypercertEvidence {
-    uri: string;
-    title?: string;
-    description?: string;
-}
-/** Image input for operations */
+type BadgeAward = AppCertifiedBadgeAward.Main;
+type BadgeDefinition = AppCertifiedBadgeDefinition.Main;
+type BadgeResponse = AppCertifiedBadgeResponse.Main;
+type FundingReceipt = OrgHypercertsFundingReceipt.Main;
+/**
+ * Image input for SDK operations.
+ *
+ * Can be either:
+ * - A URI reference (for external images)
+ * - A Blob to be uploaded
+ *
+ * The SDK will convert these to the appropriate lexicon types:
+ * - OrgHypercertsDefs.Uri
+ * - OrgHypercertsDefs.SmallImage
+ * - OrgHypercertsDefs.LargeImage
+ */
 type HypercertImage = {
     type: "uri";
     uri: string;
@@ -1083,6 +991,11 @@ type HypercertImage = {
     type: "blob";
     blob: Blob;
 };
+/**
+ * Lexicon-defined image types (union of Uri and image blob types).
+ * Use this when working with stored records.
+ */
+type HypercertImageRecord = OrgHypercertsDefs.Uri | OrgHypercertsDefs.SmallImage | OrgHypercertsDefs.LargeImage;
 /** Hypercert with AT Protocol metadata */
 interface HypercertWithMetadata {
     uri: string;
@@ -2071,7 +1984,6 @@ declare class Repository {
     private session;
     private serverUrl;
     private repoDid;
-    private lexiconRegistry;
     private logger?;
     private agent;
     private _isSDS;
@@ -2087,7 +1999,6 @@ declare class Repository {
      * @param session - Authenticated OAuth session
      * @param serverUrl - Base URL of the AT Protocol server
      * @param repoDid - DID of the repository to operate on
-     * @param lexiconRegistry - Registry for lexicon validation
      * @param isSDS - Whether this is a Shared Data Server
      * @param logger - Optional logger for debugging
      *
@@ -2097,7 +2008,7 @@ declare class Repository {
      *
      * @internal
      */
-    constructor(session: Session, serverUrl: string, repoDid: string, lexiconRegistry: LexiconRegistry, isSDS: boolean, logger?: LoggerInterface);
+    constructor(session: Session, serverUrl: string, repoDid: string, isSDS: boolean, logger?: LoggerInterface);
     /**
      * The DID (Decentralized Identifier) of this repository.
      *
@@ -2852,7 +2763,6 @@ declare class ATProtoSDK {
     private oauthClient;
     private config;
     private logger?;
-    private lexiconRegistry;
     /**
      * Creates a new ATProto SDK instance.
      *
@@ -3072,27 +2982,6 @@ declare class ATProtoSDK {
      * ```
      */
     repository(session: Session, options?: RepositoryOptions): Repository;
-    /**
-     * Gets the lexicon registry for schema validation.
-     *
-     * The lexicon registry manages AT Protocol lexicon schemas used for
-     * validating record data. You can register custom lexicons to extend
-     * the SDK's capabilities.
-     *
-     * @returns The {@link LexiconRegistry} instance
-     *
-     * @example
-     * ```typescript
-     * const registry = sdk.getLexiconRegistry();
-     *
-     * // Register custom lexicons
-     * registry.register(myCustomLexicons);
-     *
-     * // Check if a lexicon is registered
-     * const hasLexicon = registry.has("org.example.myRecord");
-     * ```
-     */
-    getLexiconRegistry(): LexiconRegistry;
     /**
      * The configured PDS (Personal Data Server) URL.
      *
@@ -4708,5 +4597,5 @@ declare function validateScope(scope: string): {
     invalidPermissions: string[];
 };
 
-export { ATPROTO_SCOPE, ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AccountActionSchema, AccountAttrSchema, AccountPermissionSchema, AuthenticationError, BlobPermissionSchema, CollaboratorPermissionsSchema, CollaboratorSchema, ConfigurableAgent, IdentityAttrSchema, IdentityPermissionSchema, InMemorySessionStore, InMemoryStateStore, IncludePermissionSchema, LexiconRegistry, MimeTypeSchema, NetworkError, NsidSchema, OAuthConfigSchema, OrganizationSchema, PermissionBuilder, PermissionSchema, RepoActionSchema, RepoPermissionSchema, Repository, RpcPermissionSchema, SDSRequiredError, ScopePresets, ServerConfigSchema, SessionExpiredError, TRANSITION_SCOPES, TimeoutConfigSchema, TransitionScopeSchema, ValidationError, buildScope, createATProtoSDK, hasAllPermissions, hasAnyPermission, hasPermission, mergeScopes, parseScope, removePermissions, validateScope };
-export type { ATProtoSDKConfig, AccountAction, AccountAttr, AccountPermissionInput, AuthorizeOptions, BlobOperations, BlobPermissionInput, BlobRef, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertParams, CreateHypercertResult, CreateResult, DID, HypercertClaim, HypercertCollection, HypercertCollectionClaimItem, HypercertContribution, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertRights, HypercertWithMetadata, IdentityAttr, IdentityPermissionInput, IncludePermissionInput, ListParams, LoggerInterface, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, Permission, PermissionInput, ProfileOperations, ProgressStep, RecordOperations, RepoAction, RepoPermissionInput, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, RpcPermissionInput, Session, SessionStore, StateStore, StrongRef, TransitionScope, UpdateResult, ValidationResult };
+export { ATPROTO_SCOPE, ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AccountActionSchema, AccountAttrSchema, AccountPermissionSchema, AuthenticationError, BlobPermissionSchema, CollaboratorPermissionsSchema, CollaboratorSchema, ConfigurableAgent, HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS, IdentityAttrSchema, IdentityPermissionSchema, InMemorySessionStore, InMemoryStateStore, IncludePermissionSchema, MimeTypeSchema, NetworkError, NsidSchema, OAuthConfigSchema, OrganizationSchema, PermissionBuilder, PermissionSchema, RepoActionSchema, RepoPermissionSchema, Repository, RpcPermissionSchema, SDSRequiredError, ScopePresets, ServerConfigSchema, SessionExpiredError, TRANSITION_SCOPES, TimeoutConfigSchema, TransitionScopeSchema, ValidationError, buildScope, createATProtoSDK, hasAllPermissions, hasAnyPermission, hasPermission, mergeScopes, parseScope, removePermissions, validateScope };
+export type { ATProtoSDKConfig, AccountAction, AccountAttr, AccountPermissionInput, AuthorizeOptions, BadgeAward, BadgeDefinition, BadgeResponse, BlobOperations, BlobPermissionInput, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertParams, CreateHypercertResult, CreateResult, DID, FundingReceipt, HypercertClaim, HypercertCollection, HypercertCollectionClaimItem, HypercertContribution, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertImageRecord, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertProject, HypercertRights, HypercertWithMetadata, IdentityAttr, IdentityPermissionInput, IncludePermissionInput, ListParams, LoggerInterface, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, Permission, PermissionInput, ProfileOperations, ProgressStep, RecordOperations, RepoAction, RepoPermissionInput, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, RpcPermissionInput, Session, SessionStore, StateStore, StrongRef, TransitionScope, UpdateResult };