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

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import { NodeSavedSession, NodeSavedState, OAuthSession } from '@atproto/oauth-client-node';
 import { z } from 'zod';
-import { EventEmitter } from 'eventemitter3';
-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';
+import { LexiconDoc as LexiconDoc$1, Lexicons } from '@atproto/lexicon';
 export { BlobRef, JsonBlobRef } from '@atproto/lexicon';
+import { Agent } from '@atproto/api';
+import { EventEmitter } from 'eventemitter3';
+import { OverrideProperties, SetOptional } from 'type-fest';
+import { ComAtprotoRepoStrongRef, AppCertifiedLocation, OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, OrgHypercertsClaimRights, OrgHypercertsClaimContributionDetails, OrgHypercertsClaimContributorInformation, OrgHypercertsClaimMeasurement, OrgHypercertsClaimEvaluation, OrgHypercertsHelperWorkScopeTag, AppCertifiedBadgeAward, AppCertifiedBadgeDefinition, AppCertifiedBadgeResponse, OrgHypercertsFundingReceipt, OrgHypercertsClaimEvidence, 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, OrgHypercertsClaimContributionDetails, OrgHypercertsClaimContributorInformation, OrgHypercertsClaimEvaluation, OrgHypercertsClaimEvidence, OrgHypercertsClaimMeasurement, OrgHypercertsClaimRights, OrgHypercertsDefs, OrgHypercertsFundingReceipt, OrgHypercertsHelperWorkScopeTag, lexicons, validate } from '@hypercerts-org/lexicon';
 
 /**
  * Storage interface for persisting OAuth sessions.
@@ -737,6 +738,236 @@ declare const CollaboratorSchema: z.ZodObject<{
  */
 type Collaborator = z.infer<typeof CollaboratorSchema>;
 
+/**
+ * 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$1[]);
+    /**
+     * 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$1): 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$1[]): 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$1 | 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;
+}
+
 /**
  * Repository types - Shared types for repository operations
  * @packageDocumentation
@@ -887,7 +1118,7 @@ interface ProgressStep {
  * 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[];
+declare const HYPERCERT_LEXICONS: LexiconDoc$1[];
 /**
  * Collection NSIDs (Namespaced Identifiers) for hypercert records.
  *
@@ -908,9 +1139,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.
      */
@@ -925,12 +1162,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.
      */
@@ -947,6 +1181,11 @@ 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";
 };
 
 /**
@@ -960,13 +1199,18 @@ declare const HYPERCERT_COLLECTIONS: {
 type StrongRef = ComAtprotoRepoStrongRef.Main;
 type HypercertClaim = OrgHypercertsClaimActivity.Main;
 type HypercertRights = OrgHypercertsClaimRights.Main;
-type HypercertContribution = OrgHypercertsClaimContribution.Main;
+type HypercertContributionDetails = OrgHypercertsClaimContributionDetails.Main;
+type HypercertContributorInformation = OrgHypercertsClaimContributorInformation.Main;
+/** Contributor entry in an activity - can be inline or reference external records */
+type HypercertContributor = OrgHypercertsClaimActivity.Contributor;
 type HypercertMeasurement = OrgHypercertsClaimMeasurement.Main;
 type HypercertEvaluation = OrgHypercertsClaimEvaluation.Main;
 type HypercertEvidence = OrgHypercertsClaimEvidence.Main;
 type HypercertCollection = OrgHypercertsClaimCollection.Main;
-type HypercertCollectionClaimItem = OrgHypercertsClaimActivity.ActivityWeight;
-type HypercertProject = OrgHypercertsClaimProject.Main;
+/** Collection item with optional weight */
+type HypercertCollectionItem = OrgHypercertsClaimCollection.Item;
+/** Work scope tag for creating reusable scope atoms */
+type HypercertWorkScopeTag = OrgHypercertsHelperWorkScopeTag.Main;
 type HypercertLocation = AppCertifiedLocation.Main;
 type BadgeAward = AppCertifiedBadgeAward.Main;
 type BadgeDefinition = AppCertifiedBadgeDefinition.Main;
@@ -975,33 +1219,118 @@ type FundingReceipt = OrgHypercertsFundingReceipt.Main;
 /**
  * Image input for SDK operations.
  *
- * Can be either:
- * - A URI reference (for external images)
- * - A Blob to be uploaded
+ * Accepts either:
+ * - A string URI reference (for external images)
+ * - A Blob to be uploaded (will be converted to SmallImage or LargeImage)
  *
- * The SDK will convert these to the appropriate lexicon types:
- * - OrgHypercertsDefs.Uri
- * - OrgHypercertsDefs.SmallImage
- * - OrgHypercertsDefs.LargeImage
+ * The SDK will convert these inputs to the appropriate lexicon types.
  */
-type HypercertImage = {
-    type: "uri";
-    uri: string;
-} | {
-    type: "blob";
-    blob: Blob;
-};
+type HypercertImage = string | Blob;
 /**
  * Lexicon-defined image types (union of Uri and image blob types).
- * Use this when working with stored records.
+ *
+ * Used when working with stored records. Can be:
+ * - OrgHypercertsDefs.Uri - External image reference
+ * - OrgHypercertsDefs.SmallImage - Uploaded blob for avatars/thumbnails
+ * - OrgHypercertsDefs.LargeImage - Uploaded blob for banners/covers
  */
 type HypercertImageRecord = OrgHypercertsDefs.Uri | OrgHypercertsDefs.SmallImage | OrgHypercertsDefs.LargeImage;
-/** Hypercert with AT Protocol metadata */
-interface HypercertWithMetadata {
+/** Hypercert with resolved metadata */
+type HypercertWithMetadata = HypercertClaim & {
+    resolvedRights?: HypercertRights;
+    resolvedLocation?: HypercertLocation;
+};
+/** Project type alias (collection with type="project") */
+type HypercertProject = HypercertCollection & {
+    type: "project";
+};
+/** Project with resolved metadata */
+type HypercertProjectWithMetadata = HypercertCollection & {
+    resolvedLocation?: HypercertLocation;
+    resolvedActivities?: HypercertClaim[];
+};
+
+type CollectionItemInput = SetOptional<OrgHypercertsClaimCollection.Item, "$type">;
+/**
+ * Parameters for specifying a location in collection/project operations.
+ * Supports three ways to specify location:
+ *
+ * 1. **StrongRef** - Direct reference with uri and cid (no record creation)
+ * 2. **AT-URI string** - Reference to existing location record
+ * 3. **Location object** - Full location data (lpVersion, srs, locationType, location, etc.)
+ *    with optional `$type` and `createdAt` fields
+ *    where-as location field can be a Blob (e.g., GeoJSON) that will be uploaded
+ *
+ * @example Using a StrongRef (no record creation)
+ * ```typescript
+ * const location: AttachLocationParams = { uri: "at://did:plc:test/app.certified.location/abc", cid: "bafyrei..." };
+ * ```
+ *
+ * @example Using an AT-URI (fetches existing record)
+ * ```typescript
+ * const location: AttachLocationParams = "at://did:plc:test/app.certified.location/xyz";
+ * ```
+ *
+ * @example Using a location object
+ * ```typescript
+ * const location: AttachLocationParams = {
+ *   lpVersion: "1.0.0",
+ *   srs: "EPSG:4326",
+ *   locationType: "coordinate-decimal",
+ *   location: "https://locationuri.com",
+ *   name: "San Francisco",
+ * };
+ * ```
+ */
+type CreateLocationParams = OverrideProperties<SetOptional<HypercertLocation, "$type" | "createdAt">, {
+    location: string | Blob | HypercertLocation["location"];
+}>;
+type LocationParams = StrongRef | string | CreateLocationParams;
+/**
+ * SDK input parameters for creating a collection.
+ * Derived from lexicon type with $type and createdAt removed.
+ * avatar/banner accept HypercertImage (string URI or Blob) for user convenience.
+ * Location can be provided inline or via attachLocationToCollection().
+ */
+type CreateCollectionParams = OverrideProperties<SetOptional<OrgHypercertsClaimCollection.Main, "$type" | "createdAt">, {
+    avatar?: HypercertImage;
+    banner?: HypercertImage;
+    items: CollectionItemInput[];
+    /**
+     * Optional location to attach to the collection.
+     * Can be:
+     * - StrongRef to reference existing location (uri + cid)
+     * - string (AT-URI) to reference existing location (CID will be fetched)
+     * - Location object to create a new location record
+     */
+    location?: LocationParams;
+}>;
+/**
+ * SDK input parameters for updating a collection.
+ * All fields are optional.
+ * avatar/banner accept HypercertImage (string URI or Blob), or null to remove.
+ * Location can be updated inline or removed with null.
+ */
+type UpdateCollectionParams = Omit<Partial<CreateCollectionParams>, "avatar" | "banner" | "location"> & {
+    avatar?: HypercertImage | null;
+    banner?: HypercertImage | null;
+    location?: LocationParams | null;
+};
+type CreateCollectionResult = {
     uri: string;
     cid: string;
-    record: HypercertClaim;
-}
+    record: HypercertCollection;
+};
+/**
+ * SDK input parameters for creating a project.
+ * Projects are collections with type="project" (set automatically).
+ */
+type CreateProjectParams = CreateCollectionParams;
+/**
+ * SDK input parameters for updating a project.
+ */
+type UpdateProjectParams = UpdateCollectionParams;
+type CreateProjectResult = CreateCollectionResult;
 
 /**
  * Parameters for creating a new hypercert.
@@ -1083,14 +1412,12 @@ interface CreateHypercertParams {
     description: string;
     /**
      * Scope of work or impact area.
-     * Logical scope of the work using label-based conditions. All labels in `withinAllOf` must apply; at least one label in `withinAnyOf` must apply if provided; no label in `withinNoneOf` may apply.
+     * Logical scope of the work using label-based conditions.
      *
-     * @example "Climate Action", "Education", "Healthcare"
+     * @example WorkScopeAll with atom references
      */
-    workScope?: {
-        withinAllOf?: string[];
-        withinAnyOf?: string[];
-        withinNoneOf?: string[];
+    workScope?: OrgHypercertsDefs.WorkScopeAll | OrgHypercertsDefs.WorkScopeAny | OrgHypercertsDefs.WorkScopeNot | OrgHypercertsDefs.WorkScopeAtom | {
+        $type: string;
     };
     /**
      * Start date of the work period.
@@ -1142,34 +1469,7 @@ interface CreateHypercertParams {
     /**
      * Optional geographic location of the impact.
      */
-    location?: {
-        /**
-         * Location value/address.
-         *
-         * @example "San Francisco, CA, USA"
-         */
-        value: string;
-        /**
-         * Human-readable location name.
-         *
-         * @example "SF Bay Area"
-         */
-        name?: string;
-        /**
-         * Description of the location scope.
-         */
-        description?: string;
-        /**
-         * Spatial Reference System identifier (required if location is provided).
-         *
-         * @example "EPSG:4326" for WGS84
-         */
-        srs: string;
-        /**
-         * GeoJSON file as a Blob for precise boundaries.
-         */
-        geojson?: Blob;
-    };
+    location?: LocationParams;
     /**
      * Optional list of contributions to the impact.
      *
@@ -1194,7 +1494,7 @@ interface CreateHypercertParams {
     /**
      * Optional evidence supporting the impact claim.
      */
-    evidence?: HypercertEvidence[];
+    evidence?: Array<Omit<CreateHypercertEvidenceParams, "subjectUri">>;
     /**
      * Optional callback for progress updates during creation.
      *
@@ -1219,6 +1519,45 @@ interface CreateOrganizationParams {
      */
     description?: string;
 }
+/**
+ * Input params for creating Hypercert evidence.
+ *
+ * Based on `org.hypercerts.claim.evidence` but:
+ * - removes: $type, createdAt, subject, content
+ * - adds: subjectUri, content (string | Blob)
+ */
+interface CreateHypercertEvidenceParams {
+    /**
+     * URI for the subject this evidence is attached to.
+     */
+    subjectUri: string;
+    /**
+     * Evidence content.
+     * - string: should be a URI.
+     * - Blob: binary payload (e.g. image/pdf)
+     */
+    content: string | Blob;
+    /**
+     * Title to describe the nature of the evidence.
+     */
+    title: string;
+    /**
+     * Short description explaining what this evidence shows.
+     */
+    shortDescription?: string;
+    /**
+     * Longer description describing the evidence in more detail.
+     */
+    description?: string;
+    /**
+     * How this evidence relates to the subject.
+     */
+    relationType?: "supports" | "challenges" | "clarifies" | (string & {});
+    /**
+     * Any additional custom fields supported by the record.
+     */
+    [k: string]: unknown;
+}
 /**
  * Result of creating a hypercert.
  *
@@ -1249,6 +1588,10 @@ interface CreateHypercertResult {
      * AT-URIs of contribution records, if contributions were provided.
      */
     contributionUris?: string[];
+    /**
+     * AT-URIs of evidence records, if evidence was provided.
+     */
+    evidenceUris?: string[];
 }
 /**
  * Low-level record operations for AT Protocol CRUD.
@@ -1563,6 +1906,67 @@ interface HypercertEvents {
         uri: string;
         cid: string;
     };
+    /**
+     * Emitted when a collection is updated.
+     */
+    collectionUpdated: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when a collection is deleted.
+     */
+    collectionDeleted: {
+        uri: string;
+    };
+    /**
+     * Emitted when a location is attached to a collection.
+     */
+    locationAttachedToCollection: {
+        uri: string;
+        cid: string;
+        collectionUri: string;
+    };
+    /**
+     * Emitted when a location is removed from a collection.
+     */
+    locationRemovedFromCollection: {
+        collectionUri: string;
+    };
+    /**
+     * Emitted when a project is created.
+     */
+    projectCreated: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when a project is updated.
+     */
+    projectUpdated: {
+        uri: string;
+        cid: string;
+    };
+    /**
+     * Emitted when a project is deleted.
+     */
+    projectDeleted: {
+        uri: string;
+    };
+    /**
+     * Emitted when a location is attached to a project.
+     */
+    locationAttachedToProject: {
+        uri: string;
+        cid: string;
+        projectUri: string;
+    };
+    /**
+     * Emitted when a location is removed from a project.
+     */
+    locationRemovedFromProject: {
+        projectUri: string;
+    };
 }
 /**
  * High-level hypercert operations.
@@ -1618,7 +2022,7 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
      */
     update(params: {
         uri: string;
-        updates: Partial<Omit<HypercertClaim, "$type" | "createdAt" | "rights">>;
+        updates: Partial<CreateHypercertParams>;
         image?: Blob | null;
     }): Promise<UpdateResult>;
     /**
@@ -1664,21 +2068,14 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
      * @param location.geojson - Optional GeoJSON blob for precise boundaries
      * @returns Promise resolving to location record result
      */
-    attachLocation(uri: string, location: {
-        value: string;
-        name?: string;
-        description?: string;
-        srs: string;
-        geojson?: Blob;
-    }): Promise<CreateResult>;
+    attachLocation(uri: string, location: LocationParams): Promise<CreateResult>;
     /**
      * Adds evidence to an existing hypercert.
      *
-     * @param uri - AT-URI of the hypercert
-     * @param evidence - Array of evidence items to add
+     * @param evidence - Evidence item to add
      * @returns Promise resolving to update result
      */
-    addEvidence(uri: string, evidence: HypercertEvidence[]): Promise<UpdateResult>;
+    addEvidence(evidence: CreateHypercertEvidenceParams): Promise<UpdateResult>;
     /**
      * Creates a contribution record.
      *
@@ -1720,18 +2117,9 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
      * Creates a collection of hypercerts.
      *
      * @param params - Collection parameters
-     * @returns Promise resolving to collection record result
-     */
-    createCollection(params: {
-        title: string;
-        claims: Array<{
-            uri: string;
-            cid: string;
-            weight: string;
-        }>;
-        shortDescription?: string;
-        coverPhoto?: Blob;
-    }): Promise<CreateResult>;
+     * @returns Promise resolving to collection record result with optional location URI
+     */
+    createCollection(params: CreateCollectionParams): Promise<CreateCollectionResult>;
     /**
      * Gets a collection by URI.
      *
@@ -1754,16 +2142,111 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
         cid: string;
         record: HypercertCollection;
     }>>;
-}
-/**
- * Collaborator operations for SDS access control.
- *
- * **SDS Only**: These operations are only available on Shared Data Servers.
- *
- * @example
- * ```typescript
- * // Grant access
- * await repo.collaborators.grant({
+    /**
+     * Updates a collection.
+     *
+     * @param uri - AT-URI of the collection
+     * @param updates - Fields to update
+     * @returns Promise resolving to update result
+     */
+    updateCollection(uri: string, updates: UpdateCollectionParams): Promise<UpdateResult>;
+    /**
+     * Deletes a collection.
+     *
+     * @param uri - AT-URI of the collection
+     * @returns Promise resolving when deleted
+     */
+    deleteCollection(uri: string): Promise<void>;
+    /**
+     * Attaches a location to a collection.
+     *
+     * @param uri - AT-URI of the collection
+     * @param location - Location data
+     * @returns Promise resolving to location record result
+     */
+    attachLocationToCollection(uri: string, location: LocationParams): Promise<CreateResult>;
+    /**
+     * Removes a location from a collection.
+     *
+     * @param uri - AT-URI of the collection
+     * @returns Promise resolving when location is removed
+     */
+    removeLocationFromCollection(uri: string): Promise<void>;
+    /**
+     * Creates a project.
+     *
+     * A project is a collection with type='project' and optional location sidecar.
+     *
+     * @param params - Project parameters
+     * @returns Promise resolving to project record result with optional location URI
+     */
+    createProject(params: CreateProjectParams): Promise<CreateProjectResult>;
+    /**
+     * Gets a project by URI.
+     *
+     * Projects are collections with type='project'.
+     *
+     * @param uri - AT-URI of the project
+     * @returns Promise resolving to project data (as collection)
+     */
+    getProject(uri: string): Promise<{
+        uri: string;
+        cid: string;
+        record: HypercertCollection;
+    }>;
+    /**
+     * Lists projects with pagination.
+     *
+     * Projects are collections with type='project'.
+     *
+     * @param params - Optional pagination parameters
+     * @returns Promise resolving to paginated list
+     */
+    listProjects(params?: ListParams): Promise<PaginatedList<{
+        uri: string;
+        cid: string;
+        record: HypercertCollection;
+    }>>;
+    /**
+     * Updates a project.
+     *
+     * @param uri - AT-URI of the project
+     * @param updates - Fields to update
+     * @returns Promise resolving to update result
+     */
+    updateProject(uri: string, updates: UpdateProjectParams): Promise<UpdateResult>;
+    /**
+     * Deletes a project.
+     *
+     * @param uri - AT-URI of the project
+     * @returns Promise resolving when deleted
+     */
+    deleteProject(uri: string): Promise<void>;
+    /**
+     * Attaches a location to a project.
+     *
+     * @param uri - AT-URI of the project
+     * @param location - Location data
+     * @returns Promise resolving to location record result
+     */
+    attachLocationToProject(uri: string, location: LocationParams): Promise<CreateResult>;
+    /**
+     * Removes a location from a project.
+     *
+     * @param uri - AT-URI of the project
+     * @returns Promise resolving when location is removed
+     */
+    removeLocationFromProject(uri: string): Promise<void>;
+}
+/**
+ * Collaborator operations for SDS access control.
+ *
+ * **SDS Only**: These operations are only available on Shared Data Servers.
+ *
+ * @example
+ * ```typescript
+ * // Grant access
+ * await repo.collaborators.grant({
  *   userDid: "did:plc:new-user",
  *   role: "editor",
  * });
@@ -2008,6 +2491,7 @@ declare class Repository {
     private logger?;
     private agent;
     private _isSDS;
+    private lexiconRegistry;
     private _records?;
     private _blobs?;
     private _profile?;
@@ -2022,6 +2506,7 @@ declare class Repository {
      * @param repoDid - DID of the repository to operate on
      * @param isSDS - Whether this is a Shared Data Server
      * @param logger - Optional logger for debugging
+     * @param lexiconRegistry - Registry for custom lexicon management
      *
      * @remarks
      * This constructor is typically not called directly. Use
@@ -2029,7 +2514,7 @@ declare class Repository {
      *
      * @internal
      */
-    constructor(session: Session, serverUrl: string, repoDid: string, isSDS: boolean, logger?: LoggerInterface);
+    constructor(session: Session, serverUrl: string, repoDid: string, isSDS: boolean, logger?: LoggerInterface, lexiconRegistry?: LexiconRegistry);
     /**
      * The DID (Decentralized Identifier) of this repository.
      *
@@ -2093,6 +2578,50 @@ declare class Repository {
      * ```
      */
     repo(did: string): Repository;
+    /**
+     * Gets the LexiconRegistry instance for managing custom lexicons.
+     *
+     * The registry is shared across all operations in this repository and
+     * enables validation of custom record types.
+     *
+     * @returns The {@link LexiconRegistry} instance
+     *
+     * @example
+     * ```typescript
+     * // Access the registry
+     * const registry = repo.getLexiconRegistry();
+     *
+     * // Register a custom lexicon
+     * registry.register({
+     *   lexicon: 1,
+     *   id: "org.myapp.evaluation",
+     *   defs: {
+     *     main: {
+     *       type: "record",
+     *       key: "tid",
+     *       record: {
+     *         type: "object",
+     *         required: ["$type", "score"],
+     *         properties: {
+     *           "$type": { type: "string", const: "org.myapp.evaluation" },
+     *           score: { type: "integer", minimum: 0, maximum: 100 }
+     *         }
+     *       }
+     *     }
+     *   }
+     * });
+     *
+     * // Now create records using the custom lexicon
+     * await repo.records.create({
+     *   collection: "org.myapp.evaluation",
+     *   record: {
+     *     $type: "org.myapp.evaluation",
+     *     score: 85
+     *   }
+     * });
+     * ```
+     */
+    getLexiconRegistry(): LexiconRegistry;
     /**
      * Low-level record operations for CRUD on any AT Protocol record type.
      *
@@ -2269,22 +2798,28 @@ declare class Repository {
  * 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.
      *
@@ -2318,8 +2853,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.
@@ -2329,40 +2867,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;
@@ -2408,14 +2984,19 @@ declare const ATProtoSDKConfigSchema: 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.
          *
@@ -2449,8 +3030,11 @@ declare const ATProtoSDKConfigSchema: 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.
@@ -2460,34 +3044,71 @@ declare const ATProtoSDKConfigSchema: 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;
     }>;
     servers: z.ZodOptional<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;
@@ -2520,6 +3141,7 @@ declare const ATProtoSDKConfigSchema: z.ZodObject<{
         scope: string;
         jwksUri: string;
         jwkPrivate: string;
+        developmentMode?: boolean | undefined;
     };
     servers?: {
         pds?: string | undefined;
@@ -2536,6 +3158,7 @@ declare const ATProtoSDKConfigSchema: z.ZodObject<{
         scope: string;
         jwksUri: string;
         jwkPrivate: string;
+        developmentMode?: boolean | undefined;
     };
     servers?: {
         pds?: string | undefined;
@@ -2784,6 +3407,7 @@ declare class ATProtoSDK {
     private oauthClient;
     private config;
     private logger?;
+    private lexiconRegistry;
     /**
      * Creates a new ATProto SDK instance.
      *
@@ -3003,6 +3627,32 @@ declare class ATProtoSDK {
      * ```
      */
     repository(session: Session, options?: RepositoryOptions): Repository;
+    /**
+     * Gets the LexiconRegistry instance for managing custom lexicons.
+     *
+     * The registry allows you to register custom lexicon schemas and validate
+     * records against them. All registered lexicons will be automatically
+     * validated during record creation operations.
+     *
+     * @returns The {@link LexiconRegistry} instance
+     *
+     * @example
+     * ```typescript
+     * // Register a custom lexicon
+     * const registry = sdk.getLexiconRegistry();
+     * registry.register({
+     *   lexicon: 1,
+     *   id: "org.myapp.customRecord",
+     *   defs: { ... }
+     * });
+     *
+     * // Check if lexicon is registered
+     * if (registry.isRegistered("org.myapp.customRecord")) {
+     *   console.log("Custom lexicon is available");
+     * }
+     * ```
+     */
+    getLexiconRegistry(): LexiconRegistry;
     /**
      * The configured PDS (Personal Data Server) URL.
      *
@@ -3017,87 +3667,1169 @@ declare class ATProtoSDK {
     get sdsUrl(): string | undefined;
 }
 /**
- * Factory function to create an ATProto SDK instance.
+ * Factory function to create an ATProto SDK instance.
+ *
+ * This is a convenience function equivalent to `new ATProtoSDK(config)`.
+ *
+ * @param config - SDK configuration
+ * @returns A new {@link ATProtoSDK} instance
+ *
+ * @example
+ * ```typescript
+ * import { createATProtoSDK } from "@hypercerts-org/sdk";
+ *
+ * const sdk = createATProtoSDK({
+ *   oauth: { ... },
+ *   servers: { pds: "https://bsky.social" },
+ * });
+ * ```
+ */
+declare function createATProtoSDK(config: ATProtoSDKConfig): ATProtoSDK;
+
+/**
+ * ConfigurableAgent - Agent with configurable service URL routing.
+ *
+ * This module provides an Agent extension that allows routing requests to
+ * a specific server URL, overriding the default URL from the OAuth session.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Agent subclass that routes requests to a configurable service URL.
+ *
+ * The standard Agent uses the service URL embedded in the OAuth session's
+ * fetch handler. This class allows overriding that URL to route requests
+ * to different servers (e.g., PDS vs SDS, or multiple SDS instances).
+ *
+ * @remarks
+ * This is particularly useful for:
+ * - Routing to a Shared Data Server (SDS) while authenticated via PDS
+ * - Supporting multiple SDS instances for different organizations
+ * - Testing against different server environments
+ *
+ * @example Basic usage
+ * ```typescript
+ * const session = await sdk.authorize("user.bsky.social");
+ *
+ * // Create agent routing to SDS instead of session's default PDS
+ * const sdsAgent = new ConfigurableAgent(session, "https://sds.hypercerts.org");
+ *
+ * // All requests will now go to the SDS
+ * await sdsAgent.com.atproto.repo.createRecord({...});
+ * ```
+ *
+ * @example Multiple SDS instances
+ * ```typescript
+ * // Route to organization A's SDS
+ * const orgAAgent = new ConfigurableAgent(session, "https://sds-org-a.example.com");
+ *
+ * // Route to organization B's SDS
+ * const orgBAgent = new ConfigurableAgent(session, "https://sds-org-b.example.com");
+ * ```
+ */
+declare class ConfigurableAgent extends Agent {
+    private customServiceUrl;
+    /**
+     * Creates a ConfigurableAgent that routes to a specific service URL.
+     *
+     * @param session - OAuth session for authentication
+     * @param serviceUrl - Base URL of the server to route requests to
+     *
+     * @remarks
+     * The agent wraps the session's fetch handler to intercept requests and
+     * prepend the custom service URL instead of using the session's default.
+     */
+    constructor(session: Session, serviceUrl: string);
+    /**
+     * Gets the service URL this agent routes to.
+     *
+     * @returns The base URL of the configured service
+     */
+    getServiceUrl(): string;
+}
+
+/**
+ * BaseOperations - Abstract base class for custom lexicon operations.
+ *
+ * This module provides a foundation for building domain-specific operation
+ * classes that work with custom lexicons. It handles validation, record
+ * creation, and provides utilities for working with AT Protocol records.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Abstract base class for creating custom lexicon operation classes.
+ *
+ * Extend this class to build domain-specific operations for your custom
+ * lexicons. The base class provides:
+ *
+ * - Automatic validation against registered lexicon schemas
+ * - Helper methods for creating and updating records
+ * - Utilities for building strongRefs and AT-URIs
+ * - Error handling and logging support
+ *
+ * @typeParam TParams - Type of parameters accepted by the create() method
+ * @typeParam TResult - Type of result returned by the create() method
+ *
+ * @remarks
+ * This class is designed to be extended by developers creating custom
+ * operation classes for their own lexicons. It follows the same patterns
+ * as the built-in hypercert operations.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { BaseOperations } from "@hypercerts-org/sdk-core";
+ *
+ * interface EvaluationParams {
+ *   subjectUri: string;
+ *   subjectCid: string;
+ *   score: number;
+ *   methodology?: string;
+ * }
+ *
+ * interface EvaluationResult {
+ *   uri: string;
+ *   cid: string;
+ *   record: MyEvaluation;
+ * }
+ *
+ * class EvaluationOperations extends BaseOperations<EvaluationParams, EvaluationResult> {
+ *   async create(params: EvaluationParams): Promise<EvaluationResult> {
+ *     const record = {
+ *       $type: "org.myapp.evaluation",
+ *       subject: this.createStrongRef(params.subjectUri, params.subjectCid),
+ *       score: params.score,
+ *       methodology: params.methodology,
+ *       createdAt: new Date().toISOString(),
+ *     };
+ *
+ *     const { uri, cid } = await this.validateAndCreate("org.myapp.evaluation", record);
+ *     return { uri, cid, record };
+ *   }
+ * }
+ * ```
+ *
+ * @example With validation and error handling
+ * ```typescript
+ * class ProjectOperations extends BaseOperations<CreateProjectParams, ProjectResult> {
+ *   async create(params: CreateProjectParams): Promise<ProjectResult> {
+ *     // Validate input parameters
+ *     if (!params.title || params.title.trim().length === 0) {
+ *       throw new ValidationError("Project title cannot be empty");
+ *     }
+ *
+ *     const record = {
+ *       $type: "org.myapp.project",
+ *       title: params.title,
+ *       description: params.description,
+ *       createdAt: new Date().toISOString(),
+ *     };
+ *
+ *     try {
+ *       const { uri, cid } = await this.validateAndCreate("org.myapp.project", record);
+ *       this.logger?.info(`Created project: ${uri}`);
+ *       return { uri, cid, record };
+ *     } catch (error) {
+ *       this.logger?.error(`Failed to create project: ${error}`);
+ *       throw error;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseOperations<TParams = unknown, TResult = unknown> {
+    protected agent: Agent;
+    protected repoDid: string;
+    protected lexiconRegistry: LexiconRegistry;
+    protected logger?: LoggerInterface | undefined;
+    /**
+     * Creates a new BaseOperations instance.
+     *
+     * @param agent - AT Protocol Agent for making API calls
+     * @param repoDid - DID of the repository to operate on
+     * @param lexiconRegistry - Registry for validating records against lexicon schemas
+     * @param logger - Optional logger for debugging and monitoring
+     *
+     * @internal
+     */
+    constructor(agent: Agent, repoDid: string, lexiconRegistry: LexiconRegistry, logger?: LoggerInterface | undefined);
+    /**
+     * Validates a record against its lexicon schema and creates it in the repository.
+     *
+     * This method performs the following steps:
+     * 1. Validates the record against the registered lexicon schema
+     * 2. Throws ValidationError if validation fails
+     * 3. Creates the record using the AT Protocol Agent
+     * 4. Returns the created record's URI and CID
+     *
+     * @param collection - NSID of the collection (e.g., "org.myapp.customRecord")
+     * @param record - Record data conforming to the collection's lexicon schema
+     * @param rkey - Optional record key. If not provided, a TID is auto-generated
+     * @returns Promise resolving to the created record's URI and CID
+     * @throws {@link ValidationError} if the record doesn't conform to the lexicon schema
+     * @throws {@link NetworkError} if the API request fails
+     *
+     * @example
+     * ```typescript
+     * const record = {
+     *   $type: "org.myapp.evaluation",
+     *   subject: { uri: "at://...", cid: "bafyrei..." },
+     *   score: 85,
+     *   createdAt: new Date().toISOString(),
+     * };
+     *
+     * const { uri, cid } = await this.validateAndCreate("org.myapp.evaluation", record);
+     * ```
+     */
+    protected validateAndCreate(collection: string, record: unknown, rkey?: string): Promise<CreateResult>;
+    /**
+     * Validates a record against its lexicon schema and updates it in the repository.
+     *
+     * This method performs the following steps:
+     * 1. Validates the record against the registered lexicon schema
+     * 2. Throws ValidationError if validation fails
+     * 3. Updates the record using the AT Protocol Agent
+     * 4. Returns the updated record's URI and new CID
+     *
+     * @param collection - NSID of the collection
+     * @param rkey - Record key (the last segment of the AT-URI)
+     * @param record - New record data (completely replaces existing record)
+     * @returns Promise resolving to the updated record's URI and new CID
+     * @throws {@link ValidationError} if the record doesn't conform to the lexicon schema
+     * @throws {@link NetworkError} if the API request fails
+     *
+     * @remarks
+     * This is a full replacement operation, not a partial update.
+     *
+     * @example
+     * ```typescript
+     * const updatedRecord = {
+     *   $type: "org.myapp.evaluation",
+     *   subject: { uri: "at://...", cid: "bafyrei..." },
+     *   score: 90, // Updated score
+     *   createdAt: existingRecord.createdAt,
+     * };
+     *
+     * const { uri, cid } = await this.validateAndUpdate(
+     *   "org.myapp.evaluation",
+     *   "abc123",
+     *   updatedRecord
+     * );
+     * ```
+     */
+    protected validateAndUpdate(collection: string, rkey: string, record: unknown): Promise<UpdateResult>;
+    /**
+     * Creates a strongRef object from a URI and CID.
+     *
+     * StrongRefs are used in AT Protocol to reference specific versions
+     * of records. They ensure that references point to an exact record
+     * version, not just the latest version.
+     *
+     * @param uri - AT-URI of the record (e.g., "at://did:plc:abc/collection/rkey")
+     * @param cid - Content Identifier (CID) of the record
+     * @returns StrongRef object with uri and cid properties
+     *
+     * @example
+     * ```typescript
+     * const hypercertRef = this.createStrongRef(
+     *   "at://did:plc:abc123/org.hypercerts.claim.activity/xyz789",
+     *   "bafyreiabc123..."
+     * );
+     *
+     * const evaluation = {
+     *   $type: "org.myapp.evaluation",
+     *   subject: hypercertRef, // Reference to specific hypercert version
+     *   score: 85,
+     *   createdAt: new Date().toISOString(),
+     * };
+     * ```
+     */
+    protected createStrongRef(uri: string, cid: string): StrongRef;
+    /**
+     * Creates a strongRef from a CreateResult or UpdateResult.
+     *
+     * This is a convenience method for creating strongRefs from the
+     * results of create or update operations.
+     *
+     * @param result - Result from a create or update operation
+     * @returns StrongRef object with uri and cid properties
+     *
+     * @example
+     * ```typescript
+     * // Create a project
+     * const projectResult = await this.validateAndCreate("org.myapp.project", projectRecord);
+     *
+     * // Create a task that references the project
+     * const taskRecord = {
+     *   $type: "org.myapp.task",
+     *   project: this.createStrongRefFromResult(projectResult),
+     *   title: "Implement feature",
+     *   createdAt: new Date().toISOString(),
+     * };
+     * ```
+     */
+    protected createStrongRefFromResult(result: CreateResult | UpdateResult): StrongRef;
+    /**
+     * Parses an AT-URI to extract its components.
+     *
+     * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
+     *
+     * @param uri - AT-URI to parse
+     * @returns Object containing did, collection, and rkey
+     * @throws Error if the URI format is invalid
+     *
+     * @example
+     * ```typescript
+     * const { did, collection, rkey } = this.parseAtUri(
+     *   "at://did:plc:abc123/org.hypercerts.claim.activity/xyz789"
+     * );
+     * // did: "did:plc:abc123"
+     * // collection: "org.hypercerts.claim.activity"
+     * // rkey: "xyz789"
+     * ```
+     */
+    protected parseAtUri(uri: string): {
+        did: string;
+        collection: string;
+        rkey: string;
+    };
+    /**
+     * Builds an AT-URI from its components.
+     *
+     * @param did - DID of the repository
+     * @param collection - NSID of the collection
+     * @param rkey - Record key (typically a TID)
+     * @returns Complete AT-URI string
+     *
+     * @example
+     * ```typescript
+     * const uri = this.buildAtUri(
+     *   "did:plc:abc123",
+     *   "org.myapp.evaluation",
+     *   "xyz789"
+     * );
+     * // Returns: "at://did:plc:abc123/org.myapp.evaluation/xyz789"
+     * ```
+     */
+    protected buildAtUri(did: string, collection: string, rkey: string): string;
+    /**
+     * Abstract create method that must be implemented by subclasses.
+     *
+     * Implement this method to define how your custom records are created.
+     * Use the helper methods like `validateAndCreate()`, `createStrongRef()`,
+     * etc. to build your implementation.
+     *
+     * @param params - Parameters for creating the record
+     * @returns Promise resolving to the creation result
+     *
+     * @example
+     * ```typescript
+     * async create(params: EvaluationParams): Promise<EvaluationResult> {
+     *   const record = {
+     *     $type: "org.myapp.evaluation",
+     *     subject: this.createStrongRef(params.subjectUri, params.subjectCid),
+     *     score: params.score,
+     *     methodology: params.methodology,
+     *     createdAt: new Date().toISOString(),
+     *   };
+     *
+     *   const { uri, cid } = await this.validateAndCreate("org.myapp.evaluation", record);
+     *   return { uri, cid, record };
+     * }
+     * ```
+     */
+    abstract create(params: TParams): Promise<TResult>;
+}
+
+/**
+ * Lexicon Development Utilities - AT-URI and StrongRef Helpers
+ *
+ * This module provides utilities for working with AT Protocol URIs and strongRefs
+ * when building custom lexicons. These tools help developers create type-safe
+ * references between records.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Components of an AT-URI (AT Protocol Uniform Resource Identifier).
+ *
+ * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
+ * where:
+ * - `did`: The DID of the repository owner (e.g., "did:plc:abc123")
+ * - `collection`: The NSID of the record type (e.g., "org.hypercerts.claim.activity")
+ * - `rkey`: The record key, either a TID or custom key (e.g., "3km2vj4kfqp2a")
+ */
+interface AtUriComponents {
+    /** Repository owner's DID */
+    did: string;
+    /** Collection NSID (lexicon identifier) */
+    collection: string;
+    /** Record key (TID or custom string) */
+    rkey: string;
+}
+/**
+ * Parse an AT-URI into its component parts.
+ *
+ * Extracts the DID, collection NSID, and record key from an AT-URI string.
+ * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
+ *
+ * @param uri - The AT-URI to parse
+ * @returns The components of the URI
+ * @throws {Error} If the URI format is invalid
+ *
+ * @example
+ * ```typescript
+ * const components = parseAtUri("at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a");
+ * console.log(components);
+ * // {
+ * //   did: "did:plc:abc123",
+ * //   collection: "org.hypercerts.claim.activity",
+ * //   rkey: "3km2vj4kfqp2a"
+ * // }
+ * ```
+ */
+declare function parseAtUri(uri: string): AtUriComponents;
+/**
+ * Build an AT-URI from its component parts.
+ *
+ * Constructs a valid AT-URI string from a DID, collection NSID, and record key.
+ * The resulting URI follows the format: `at://{did}/{collection}/{rkey}`
+ *
+ * @param did - The repository owner's DID
+ * @param collection - The collection NSID (lexicon identifier)
+ * @param rkey - The record key (TID or custom string)
+ * @returns The complete AT-URI
+ *
+ * @example
+ * ```typescript
+ * const uri = buildAtUri(
+ *   "did:plc:abc123",
+ *   "org.hypercerts.claim.activity",
+ *   "3km2vj4kfqp2a"
+ * );
+ * console.log(uri); // "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a"
+ * ```
+ */
+declare function buildAtUri(did: string, collection: string, rkey: string): string;
+/**
+ * Extract the record key (TID or custom key) from an AT-URI.
+ *
+ * Returns the last component of the AT-URI, which is the record key.
+ * This is equivalent to `parseAtUri(uri).rkey` but more efficient.
+ *
+ * @param uri - The AT-URI to extract from
+ * @returns The record key (TID or custom string)
+ * @throws {Error} If the URI format is invalid
+ *
+ * @example
+ * ```typescript
+ * const rkey = extractRkeyFromUri("at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a");
+ * console.log(rkey); // "3km2vj4kfqp2a"
+ * ```
+ */
+declare function extractRkeyFromUri(uri: string): string;
+/**
+ * Check if a string is a valid AT-URI format.
+ *
+ * Validates that the string follows the AT-URI format without throwing errors.
+ * This is useful for input validation before parsing.
+ *
+ * @param uri - The string to validate
+ * @returns True if the string is a valid AT-URI, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isValidAtUri(userInput)) {
+ *   const components = parseAtUri(userInput);
+ *   // ... use components
+ * } else {
+ *   console.error("Invalid AT-URI");
+ * }
+ * ```
+ */
+declare function isValidAtUri(uri: string): boolean;
+/**
+ * Create a strongRef from a URI and CID.
+ *
+ * StrongRefs are the canonical way to reference specific versions of records
+ * in AT Protocol. They combine an AT-URI (which identifies the record) with
+ * a CID (which identifies the specific version).
+ *
+ * @param uri - The AT-URI of the record
+ * @param cid - The CID (Content Identifier) of the record version
+ * @returns A strongRef object
+ *
+ * @example
+ * ```typescript
+ * const ref = createStrongRef(
+ *   "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a",
+ *   "bafyreiabc123..."
+ * );
+ * console.log(ref);
+ * // {
+ * //   uri: "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a",
+ * //   cid: "bafyreiabc123..."
+ * // }
+ * ```
+ */
+declare function createStrongRef(uri: string, cid: string): StrongRef;
+/**
+ * Create a strongRef from a CreateResult or UpdateResult.
+ *
+ * This is a convenience function that extracts the URI and CID from
+ * the result of a record creation or update operation.
+ *
+ * @param result - The result from creating or updating a record
+ * @returns A strongRef object
+ *
+ * @example
+ * ```typescript
+ * const hypercert = await repo.hypercerts.create({
+ *   title: "Climate Research",
+ *   // ... other params
+ * });
+ *
+ * const ref = createStrongRefFromResult(hypercert);
+ * // Now use ref in another record to reference this hypercert
+ * ```
+ */
+declare function createStrongRefFromResult(result: CreateResult | UpdateResult): StrongRef;
+/**
+ * Validate that an object is a valid strongRef.
+ *
+ * Checks that the object has the required `uri` and `cid` properties
+ * and that they are non-empty strings.
+ *
+ * @param ref - The object to validate
+ * @returns True if the object is a valid strongRef, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const maybeRef = { uri: "at://...", cid: "bafyrei..." };
+ * if (validateStrongRef(maybeRef)) {
+ *   // Safe to use as strongRef
+ *   record.subject = maybeRef;
+ * }
+ * ```
+ */
+declare function validateStrongRef(ref: unknown): ref is StrongRef;
+/**
+ * Type guard to check if a value is a strongRef.
+ *
+ * This is an alias for `validateStrongRef` that provides better semantics
+ * for type narrowing in TypeScript.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a strongRef, false otherwise
+ *
+ * @example
+ * ```typescript
+ * function processReference(ref: unknown) {
+ *   if (isStrongRef(ref)) {
+ *     // TypeScript knows ref is StrongRef here
+ *     console.log(ref.uri);
+ *   }
+ * }
+ * ```
+ */
+declare function isStrongRef(value: unknown): value is StrongRef;
+
+/**
+ * Lexicon Builder Utilities
+ *
+ * This module provides utilities for constructing lexicon JSON schemas programmatically.
+ * These builders help developers create valid AT Protocol lexicons with proper structure
+ * and type-safe field definitions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Lexicon field type definitions.
+ */
+type LexiconFieldType = "string" | "integer" | "boolean" | "number" | "datetime" | "blob" | "ref" | "array" | "object" | "unknown";
+/**
+ * Base lexicon field definition.
+ */
+interface LexiconFieldBase {
+    type: LexiconFieldType;
+    description?: string;
+}
+/**
+ * String field definition.
+ */
+interface LexiconStringField extends LexiconFieldBase {
+    type: "string";
+    format?: "datetime" | "uri" | "at-uri" | "did" | "handle" | "at-identifier" | "nsid" | "cid";
+    minLength?: number;
+    maxLength?: number;
+    minGraphemes?: number;
+    maxGraphemes?: number;
+    enum?: string[];
+    const?: string;
+    default?: string;
+}
+/**
+ * Integer field definition.
+ */
+interface LexiconIntegerField extends LexiconFieldBase {
+    type: "integer";
+    minimum?: number;
+    maximum?: number;
+    enum?: number[];
+    const?: number;
+    default?: number;
+}
+/**
+ * Number field definition.
+ */
+interface LexiconNumberField extends LexiconFieldBase {
+    type: "number";
+    minimum?: number;
+    maximum?: number;
+    enum?: number[];
+    const?: number;
+    default?: number;
+}
+/**
+ * Boolean field definition.
+ */
+interface LexiconBooleanField extends LexiconFieldBase {
+    type: "boolean";
+    const?: boolean;
+    default?: boolean;
+}
+/**
+ * Reference field definition (for strongRefs).
+ */
+interface LexiconRefField extends LexiconFieldBase {
+    type: "ref";
+    ref: string;
+}
+/**
+ * Array field definition.
+ */
+interface LexiconArrayField extends LexiconFieldBase {
+    type: "array";
+    items: LexiconField;
+    minLength?: number;
+    maxLength?: number;
+}
+/**
+ * Object field definition.
+ */
+interface LexiconObjectField extends LexiconFieldBase {
+    type: "object";
+    properties?: Record<string, LexiconField>;
+    required?: string[];
+}
+/**
+ * Blob field definition.
+ */
+interface LexiconBlobField extends LexiconFieldBase {
+    type: "blob";
+    accept?: string[];
+    maxSize?: number;
+}
+/**
+ * Unknown field definition (accepts any type).
+ */
+interface LexiconUnknownField extends LexiconFieldBase {
+    type: "unknown";
+}
+/**
+ * Union of all lexicon field types.
+ */
+type LexiconField = LexiconStringField | LexiconIntegerField | LexiconNumberField | LexiconBooleanField | LexiconRefField | LexiconArrayField | LexiconObjectField | LexiconBlobField | LexiconUnknownField;
+/**
+ * Record definition for a lexicon.
  *
- * This is a convenience function equivalent to `new ATProtoSDK(config)`.
+ * Key types:
+ * - "tid" (default): Server-generated timestamp-based ID
+ * - "any": Client can specify any valid rkey
+ */
+interface LexiconRecordDef {
+    type: "record";
+    key?: "tid" | "any";
+    record: {
+        type: "object";
+        required: string[];
+        properties: Record<string, LexiconField>;
+    };
+}
+/**
+ * Main lexicon document structure.
+ */
+interface LexiconDoc {
+    lexicon: 1;
+    id: string;
+    defs: {
+        main: LexiconRecordDef;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Create a string field definition.
  *
- * @param config - SDK configuration
- * @returns A new {@link ATProtoSDK} instance
+ * @param options - String field options
+ * @returns A lexicon string field definition
  *
  * @example
  * ```typescript
- * import { createATProtoSDK } from "@hypercerts-org/sdk";
+ * const titleField = createStringField({
+ *   description: "Title of the item",
+ *   minLength: 1,
+ *   maxLength: 200,
+ * });
+ * ```
+ */
+declare function createStringField(options?: Omit<LexiconStringField, "type">): LexiconStringField;
+/**
+ * Create an integer field definition.
  *
- * const sdk = createATProtoSDK({
- *   oauth: { ... },
- *   servers: { pds: "https://bsky.social" },
+ * @param options - Integer field options
+ * @returns A lexicon integer field definition
+ *
+ * @example
+ * ```typescript
+ * const scoreField = createIntegerField({
+ *   description: "Score from 0 to 100",
+ *   minimum: 0,
+ *   maximum: 100,
  * });
  * ```
  */
-declare function createATProtoSDK(config: ATProtoSDKConfig): ATProtoSDK;
+declare function createIntegerField(options?: Omit<LexiconIntegerField, "type">): LexiconIntegerField;
+/**
+ * Create a number field definition.
+ *
+ * @param options - Number field options
+ * @returns A lexicon number field definition
+ *
+ * @example
+ * ```typescript
+ * const weightField = createNumberField({
+ *   description: "Weight as decimal",
+ *   minimum: 0,
+ *   maximum: 1,
+ * });
+ * ```
+ */
+declare function createNumberField(options?: Omit<LexiconNumberField, "type">): LexiconNumberField;
+/**
+ * Create a boolean field definition.
+ *
+ * @param options - Boolean field options
+ * @returns A lexicon boolean field definition
+ *
+ * @example
+ * ```typescript
+ * const verifiedField = createBooleanField({
+ *   description: "Whether the item is verified",
+ *   default: false,
+ * });
+ * ```
+ */
+declare function createBooleanField(options?: Omit<LexiconBooleanField, "type">): LexiconBooleanField;
+/**
+ * Create a strongRef field definition.
+ *
+ * StrongRefs are the standard way to reference other records in AT Protocol.
+ * They contain both the AT-URI and CID of the referenced record.
+ *
+ * @param options - Reference field options
+ * @returns A lexicon reference field definition
+ *
+ * @example
+ * ```typescript
+ * const subjectField = createStrongRefField({
+ *   description: "The hypercert being evaluated",
+ * });
+ * ```
+ */
+declare function createStrongRefField(options?: Omit<LexiconRefField, "type" | "ref"> & {
+    ref?: string;
+}): LexiconRefField;
+/**
+ * Create an array field definition.
+ *
+ * @param itemType - The type of items in the array
+ * @param options - Array field options
+ * @returns A lexicon array field definition
+ *
+ * @example
+ * ```typescript
+ * const tagsField = createArrayField(
+ *   createStringField({ maxLength: 50 }),
+ *   {
+ *     description: "List of tags",
+ *     minLength: 1,
+ *     maxLength: 10,
+ *   }
+ * );
+ * ```
+ */
+declare function createArrayField(itemType: LexiconField, options?: Omit<LexiconArrayField, "type" | "items">): LexiconArrayField;
+/**
+ * Create an object field definition.
+ *
+ * @param options - Object field options
+ * @returns A lexicon object field definition
+ *
+ * @example
+ * ```typescript
+ * const metadataField = createObjectField({
+ *   description: "Additional metadata",
+ *   properties: {
+ *     author: createStringField(),
+ *     version: createIntegerField(),
+ *   },
+ *   required: ["author"],
+ * });
+ * ```
+ */
+declare function createObjectField(options?: Omit<LexiconObjectField, "type">): LexiconObjectField;
+/**
+ * Create a blob field definition.
+ *
+ * @param options - Blob field options
+ * @returns A lexicon blob field definition
+ *
+ * @example
+ * ```typescript
+ * const imageField = createBlobField({
+ *   description: "Profile image",
+ *   accept: ["image/png", "image/jpeg"],
+ *   maxSize: 1000000, // 1MB
+ * });
+ * ```
+ */
+declare function createBlobField(options?: Omit<LexiconBlobField, "type">): LexiconBlobField;
+/**
+ * Create a datetime string field.
+ *
+ * This is a convenience function for creating string fields with datetime format.
+ *
+ * @param options - String field options
+ * @returns A lexicon string field with datetime format
+ *
+ * @example
+ * ```typescript
+ * const createdAtField = createDatetimeField({
+ *   description: "When the record was created",
+ * });
+ * ```
+ */
+declare function createDatetimeField(options?: Omit<LexiconStringField, "type" | "format">): LexiconStringField;
+/**
+ * Create a record definition.
+ *
+ * This defines the structure of records in your lexicon.
+ *
+ * @param properties - The record's properties (fields)
+ * @param required - Array of required field names
+ * @param keyType - The type of record key ("tid" for server-generated, "any" for custom)
+ * @returns A lexicon record definition
+ *
+ * @example
+ * ```typescript
+ * const recordDef = createRecordDef(
+ *   {
+ *     $type: createStringField({ const: "org.myapp.evaluation" }),
+ *     subject: createStrongRefField({ description: "The evaluated item" }),
+ *     score: createIntegerField({ minimum: 0, maximum: 100 }),
+ *     createdAt: createDatetimeField(),
+ *   },
+ *   ["$type", "subject", "score", "createdAt"],
+ *   "tid"
+ * );
+ * ```
+ */
+declare function createRecordDef(properties: Record<string, LexiconField>, required: string[], keyType?: "tid" | "any"): LexiconRecordDef;
+/**
+ * Create a complete lexicon document.
+ *
+ * This creates a full lexicon JSON structure that can be registered with the SDK.
+ *
+ * @param nsid - The NSID (Namespaced Identifier) for this lexicon
+ * @param properties - The record's properties (fields)
+ * @param required - Array of required field names
+ * @param keyType - The type of record key ("tid" for server-generated, "any" for custom)
+ * @returns A complete lexicon document
+ *
+ * @example
+ * ```typescript
+ * const lexicon = createLexiconDoc(
+ *   "org.myapp.evaluation",
+ *   {
+ *     $type: createStringField({ const: "org.myapp.evaluation" }),
+ *     subject: createStrongRefField({ description: "The evaluated item" }),
+ *     score: createIntegerField({ minimum: 0, maximum: 100 }),
+ *     methodology: createStringField({ maxLength: 500 }),
+ *     createdAt: createDatetimeField(),
+ *   },
+ *   ["$type", "subject", "score", "createdAt"],
+ *   "tid"
+ * );
+ *
+ * // Register with SDK
+ * sdk.getLexiconRegistry().registerFromJSON(lexicon);
+ * ```
+ */
+declare function createLexiconDoc(nsid: string, properties: Record<string, LexiconField>, required: string[], keyType?: "tid" | "any"): LexiconDoc;
+/**
+ * Validate a lexicon document structure.
+ *
+ * Performs basic validation to ensure the lexicon follows AT Protocol conventions.
+ * This does NOT perform full JSON schema validation.
+ *
+ * @param lexicon - The lexicon document to validate
+ * @returns True if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const lexicon = createLexiconDoc(...);
+ * if (validateLexiconStructure(lexicon)) {
+ *   sdk.getLexiconRegistry().registerFromJSON(lexicon);
+ * } else {
+ *   console.error("Invalid lexicon structure");
+ * }
+ * ```
+ */
+declare function validateLexiconStructure(lexicon: unknown): lexicon is LexiconDoc;
 
 /**
- * ConfigurableAgent - Agent with configurable service URL routing.
+ * Sidecar Pattern Utilities
  *
- * This module provides an Agent extension that allows routing requests to
- * a specific server URL, overriding the default URL from the OAuth session.
+ * This module provides utilities for implementing the AT Protocol "sidecar pattern"
+ * where additional records are created that reference a main record via StrongRef.
+ *
+ * ## The Sidecar Pattern
+ *
+ * In AT Protocol, the sidecar pattern uses **unidirectional references**:
+ * - Sidecar records contain a StrongRef (uri + cid) pointing to the main record
+ * - Main records do NOT maintain back-references to sidecars
+ * - Sidecars are discovered by querying records that reference the main record
+ * - Optionally, sidecars can use the same rkey as the main record (in different collections)
+ *
+ * ## Example Use Cases
+ *
+ * - Evaluations that reference hypercerts
+ * - Comments that reference posts
+ * - Metadata records that reference primary entities
+ *
+ * @see https://atproto.com/specs/record-key
+ * @see https://atproto.com/specs/data-model
  *
  * @packageDocumentation
  */
 
 /**
- * Agent subclass that routes requests to a configurable service URL.
+ * Parameters for creating a sidecar record.
+ */
+interface SidecarRecordParams {
+    /** The collection NSID for the sidecar record */
+    collection: string;
+    /** The record data */
+    record: Record<string, unknown>;
+    /** Optional custom rkey */
+    rkey?: string;
+}
+/**
+ * Result from creating a sidecar record.
+ */
+interface SidecarResult {
+    /** The main record that was referenced */
+    mainRecord: CreateResult;
+    /** The sidecar record that was created */
+    sidecarRecord: CreateResult;
+}
+/**
+ * Parameters for attaching a sidecar to an existing record.
+ */
+interface AttachSidecarParams {
+    /** The main record to reference */
+    mainRecord: {
+        uri: string;
+        cid: string;
+    };
+    /** The sidecar record to create */
+    sidecar: SidecarRecordParams;
+}
+/**
+ * Result from creating multiple sidecars.
+ */
+interface MultiSidecarResult {
+    /** The main record that was created */
+    main: CreateResult;
+    /** The sidecar records that were created */
+    sidecars: CreateResult[];
+}
+/**
+ * Parameters for creating a main record with multiple sidecars.
+ */
+interface CreateWithSidecarsParams {
+    /** The main record to create */
+    main: SidecarRecordParams;
+    /** The sidecar records to create (can reference the main record via placeholder) */
+    sidecars: SidecarRecordParams[];
+}
+/**
+ * Create a sidecar record that references an existing record.
  *
- * The standard Agent uses the service URL embedded in the OAuth session's
- * fetch handler. This class allows overriding that URL to route requests
- * to different servers (e.g., PDS vs SDS, or multiple SDS instances).
+ * This is a low-level utility that creates a single sidecar record. The sidecar
+ * record should include a strongRef field that points to the main record.
  *
- * @remarks
- * This is particularly useful for:
- * - Routing to a Shared Data Server (SDS) while authenticated via PDS
- * - Supporting multiple SDS instances for different organizations
- * - Testing against different server environments
+ * @param repo - The repository instance
+ * @param collection - The collection NSID for the sidecar
+ * @param record - The sidecar record data (should include a strongRef to the main record)
+ * @param options - Optional creation options
+ * @returns The created sidecar record
  *
- * @example Basic usage
+ * @example
  * ```typescript
- * const session = await sdk.authorize("user.bsky.social");
+ * const hypercert = await repo.hypercerts.create({...});
+ *
+ * const evaluation = await createSidecarRecord(
+ *   repo,
+ *   "org.myapp.evaluation",
+ *   {
+ *     $type: "org.myapp.evaluation",
+ *     subject: { uri: hypercert.hypercertUri, cid: hypercert.hypercertCid },
+ *     score: 85,
+ *     createdAt: new Date().toISOString(),
+ *   }
+ * );
+ * ```
+ */
+declare function createSidecarRecord(repo: Repository, collection: string, record: Record<string, unknown>, options?: {
+    rkey?: string;
+}): Promise<CreateResult>;
+/**
+ * Attach a sidecar record to an existing main record.
  *
- * // Create agent routing to SDS instead of session's default PDS
- * const sdsAgent = new ConfigurableAgent(session, "https://sds.hypercerts.org");
+ * This creates a new record that references an existing record via strongRef.
+ * It's a higher-level convenience function that wraps `createSidecarRecord`.
  *
- * // All requests will now go to the SDS
- * await sdsAgent.com.atproto.repo.createRecord({...});
+ * @param repo - The repository instance
+ * @param params - Parameters including the main record reference and sidecar definition
+ * @returns Both the main record reference and the created sidecar
+ *
+ * @example
+ * ```typescript
+ * const hypercert = await repo.hypercerts.create({...});
+ *
+ * const result = await attachSidecar(repo, {
+ *   mainRecord: {
+ *     uri: hypercert.hypercertUri,
+ *     cid: hypercert.hypercertCid,
+ *   },
+ *   sidecar: {
+ *     collection: "org.myapp.evaluation",
+ *     record: {
+ *       $type: "org.myapp.evaluation",
+ *       subject: { uri: hypercert.hypercertUri, cid: hypercert.hypercertCid },
+ *       score: 85,
+ *       createdAt: new Date().toISOString(),
+ *     },
+ *   },
+ * });
  * ```
+ */
+declare function attachSidecar(repo: Repository, params: AttachSidecarParams): Promise<SidecarResult>;
+/**
+ * Create a main record and multiple sidecar records in sequence.
  *
- * @example Multiple SDS instances
+ * This orchestrates the creation of a main record followed by one or more
+ * sidecar records that reference it. This is useful for workflows like:
+ * - Creating a project with multiple hypercert claims
+ * - Creating a hypercert with evidence and evaluation records
+ *
+ * @param repo - The repository instance
+ * @param params - Parameters including the main record and sidecar definitions
+ * @returns The main record and all created sidecar records
+ *
+ * @example
  * ```typescript
- * // Route to organization A's SDS
- * const orgAAgent = new ConfigurableAgent(session, "https://sds-org-a.example.com");
+ * const result = await createWithSidecars(repo, {
+ *   main: {
+ *     collection: "org.hypercerts.project",
+ *     record: {
+ *       $type: "org.hypercerts.project",
+ *       title: "Climate Initiative 2024",
+ *       description: "Our climate work",
+ *       createdAt: new Date().toISOString(),
+ *     },
+ *   },
+ *   sidecars: [
+ *     {
+ *       collection: "org.hypercerts.claim.activity",
+ *       record: {
+ *         $type: "org.hypercerts.claim.activity",
+ *         title: "Tree Planting",
+ *         // ... other hypercert fields
+ *         // Note: If you need to reference the main record, you must wait
+ *         // for result.main and then call batchCreateSidecars separately
+ *       },
+ *     },
+ *     {
+ *       collection: "org.hypercerts.claim.activity",
+ *       record: {
+ *         $type: "org.hypercerts.claim.activity",
+ *         title: "Carbon Measurement",
+ *         // ... other hypercert fields
+ *       },
+ *     },
+ *   ],
+ * });
  *
- * // Route to organization B's SDS
- * const orgBAgent = new ConfigurableAgent(session, "https://sds-org-b.example.com");
+ * console.log(result.main.uri); // Main project record
+ * console.log(result.sidecars.length); // 2 hypercert sidecars
  * ```
  */
-declare class ConfigurableAgent extends Agent {
-    private customServiceUrl;
-    /**
-     * Creates a ConfigurableAgent that routes to a specific service URL.
-     *
-     * @param session - OAuth session for authentication
-     * @param serviceUrl - Base URL of the server to route requests to
-     *
-     * @remarks
-     * The agent wraps the session's fetch handler to intercept requests and
-     * prepend the custom service URL instead of using the session's default.
-     */
-    constructor(session: Session, serviceUrl: string);
-    /**
-     * Gets the service URL this agent routes to.
-     *
-     * @returns The base URL of the configured service
-     */
-    getServiceUrl(): string;
-}
+declare function createWithSidecars(repo: Repository, params: CreateWithSidecarsParams): Promise<MultiSidecarResult>;
+/**
+ * Batch create multiple sidecar records.
+ *
+ * This is useful when you want to add multiple related records
+ * efficiently. The sidecar records should already contain any necessary
+ * references to the main record in their data.
+ *
+ * @param repo - The repository instance
+ * @param sidecars - Array of sidecar definitions (records should include references)
+ * @returns Array of created sidecar records
+ *
+ * @example
+ * ```typescript
+ * const hypercert = await repo.hypercerts.create({...});
+ * const mainRef = { uri: hypercert.hypercertUri, cid: hypercert.hypercertCid };
+ *
+ * const evaluations = await batchCreateSidecars(repo, [
+ *   {
+ *     collection: "org.myapp.evaluation",
+ *     record: {
+ *       $type: "org.myapp.evaluation",
+ *       subject: mainRef,  // Reference already included
+ *       score: 85,
+ *       methodology: "Peer review",
+ *       createdAt: new Date().toISOString(),
+ *     },
+ *   },
+ *   {
+ *     collection: "org.myapp.comment",
+ *     record: {
+ *       $type: "org.myapp.comment",
+ *       subject: mainRef,  // Reference already included
+ *       text: "Great work!",
+ *       createdAt: new Date().toISOString(),
+ *     },
+ *   },
+ * ]);
+ * ```
+ */
+declare function batchCreateSidecars(repo: Repository, sidecars: SidecarRecordParams[]): Promise<CreateResult[]>;
 
 /**
  * Base error class for all SDK errors.
@@ -3671,12 +5403,29 @@ type IdentityAttr = z.infer<typeof IdentityAttrSchema>;
 /**
  * Zod schema for MIME type patterns.
  *
- * Validates MIME type strings like "image/*" or "video/mp4".
+ * Validates MIME type strings used in blob permissions.
+ * Supports standard MIME types and wildcard patterns per ATProto spec.
+ *
+ * **References:**
+ * - ATProto Permission Spec: https://atproto.com/specs/permission (blob resource)
+ * - RFC 2045 (MIME): https://www.rfc-editor.org/rfc/rfc2045 (token definition)
+ * - IANA Media Types: https://www.iana.org/assignments/media-types/
+ *
+ * **Implementation:**
+ * This is a "good enough" validation that allows common real-world MIME types:
+ * - Type: letters, digits (e.g., "3gpp")
+ * - Subtype: letters, digits, hyphens, plus signs, dots, underscores, wildcards
+ * - Examples: "image/png", "application/vnd.api+json", "video/*", "clue_info+xml"
+ *
+ * Note: We use a simplified regex rather than full RFC 2045 token validation
+ * for practicality. Zod v4 has native MIME support (z.file().mime()) but would
+ * require a larger migration effort.
  *
  * @example
  * ```typescript
- * MimeTypeSchema.parse('image/*'); // Valid
- * MimeTypeSchema.parse('video/mp4'); // Valid
+ * MimeTypeSchema.parse('image/*'); // Valid - wildcard
+ * MimeTypeSchema.parse('video/mp4'); // Valid - standard
+ * MimeTypeSchema.parse('application/vnd.api+json'); // Valid - with dots/plus
  * MimeTypeSchema.parse('invalid'); // Throws ZodError
  * ```
  */
@@ -3687,6 +5436,12 @@ declare const MimeTypeSchema: z.ZodString;
  * NSIDs are reverse-DNS style identifiers used throughout ATProto
  * (e.g., "app.bsky.feed.post" or "com.example.myrecord").
  *
+ * Official ATProto NSID spec requires:
+ * - Each segment must be 1-63 characters
+ * - Authority segments (all but last) can contain hyphens, but not at boundaries
+ * - Name segment (last) must start with a letter and contain only alphanumerics
+ * - Hyphens only allowed in authority segments, not in the name segment
+ *
  * @see https://atproto.com/specs/nsid
  *
  * @example
@@ -4521,20 +6276,44 @@ declare function parseScope(scope: string): string[];
 /**
  * Check if a scope string contains a specific permission.
  *
- * This function performs exact string matching. For more advanced
- * permission checking (e.g., wildcard matching), you'll need to
- * implement custom logic.
+ * Implements permission matching per ATProto OAuth spec with support for
+ * exact matching and limited wildcard patterns.
+ *
+ * **References:**
+ * - ATProto Permission Spec: https://atproto.com/specs/permission
+ * - ATProto OAuth Spec: https://atproto.com/specs/oauth
+ *
+ * **Supported wildcards (per spec):**
+ * - `repo:*` - Matches any repository collection (e.g., `repo:app.bsky.feed.post`)
+ * - `rpc:*` - Matches any RPC lexicon (but aud cannot also be wildcard)
+ * - `blob:image/*` - MIME type wildcards (e.g., matches `blob:image/png`, `blob:image/jpeg`)
+ * - `blob:` + wildcard MIME - Matches any MIME type (using `*` + `/` + `*` pattern)
+ * - `identity:*` - Full control of DID document and handle (spec allows `*` as attr value)
+ *
+ * **NOT supported (per spec):**
+ * - `account:*` - Account attr does not support wildcards (only `email` and `repo` allowed)
+ * - `include:*` - Include NSID does not support wildcards
+ * - Partial wildcards like `com.example.*` are not supported
  *
  * @param scope - Space-separated scope string
  * @param permission - The permission to check for
  * @returns True if the scope contains the permission
  *
- * @example
+ * @example Exact matching
  * ```typescript
- * const scope = "account:email?action=read repo:app.bsky.feed.post";
- * hasPermission(scope, "account:email?action=read"); // true
+ * const scope = "account:email repo:app.bsky.feed.post";
+ * hasPermission(scope, "account:email"); // true
  * hasPermission(scope, "account:repo"); // false
  * ```
+ *
+ * @example Wildcard matching
+ * ```typescript
+ * const scope = "repo:* blob:image/* identity:*";
+ * hasPermission(scope, "repo:app.bsky.feed.post"); // true
+ * hasPermission(scope, "blob:image/png"); // true
+ * hasPermission(scope, "blob:video/mp4"); // false
+ * hasPermission(scope, "identity:handle"); // true
+ * ```
  */
 declare function hasPermission(scope: string, permission: string): boolean;
 /**
@@ -4618,5 +6397,5 @@ declare function validateScope(scope: string): {
     invalidPermissions: string[];
 };
 
-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 };
+export { ATPROTO_SCOPE, ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AccountActionSchema, AccountAttrSchema, AccountPermissionSchema, AuthenticationError, BaseOperations, BlobPermissionSchema, CollaboratorPermissionsSchema, CollaboratorSchema, ConfigurableAgent, HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS, 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, attachSidecar, batchCreateSidecars, buildAtUri, buildScope, createATProtoSDK, createArrayField, createBlobField, createBooleanField, createDatetimeField, createIntegerField, createLexiconDoc, createNumberField, createObjectField, createRecordDef, createSidecarRecord, createStringField, createStrongRef, createStrongRefField, createStrongRefFromResult, createWithSidecars, extractRkeyFromUri, hasAllPermissions, hasAnyPermission, hasPermission, isStrongRef, isValidAtUri, mergeScopes, parseAtUri, parseScope, removePermissions, validateLexiconStructure, validateScope, validateStrongRef };
+export type { ATProtoSDKConfig, AccountAction, AccountAttr, AccountPermissionInput, AtUriComponents, AttachSidecarParams, AuthorizeOptions, BadgeAward, BadgeDefinition, BadgeResponse, BlobOperations, BlobPermissionInput, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertEvidenceParams, CreateHypercertParams, CreateHypercertResult, CreateOrganizationParams, CreateProjectParams, CreateResult, CreateWithSidecarsParams, DID, FundingReceipt, HypercertClaim, HypercertCollection, HypercertCollectionItem, HypercertContributionDetails, HypercertContributor, HypercertContributorInformation, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertImageRecord, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertProject, HypercertProjectWithMetadata, HypercertRights, HypercertWithMetadata, HypercertWorkScopeTag, IdentityAttr, IdentityPermissionInput, IncludePermissionInput, LexiconArrayField, LexiconBlobField, LexiconBooleanField, LexiconDoc, LexiconField, LexiconFieldType, LexiconIntegerField, LexiconNumberField, LexiconObjectField, LexiconRecordDef, LexiconRefField, LexiconStringField, LexiconUnknownField, ListParams, LocationParams, LoggerInterface, MultiSidecarResult, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, Permission, PermissionInput, ProfileOperations, ProgressStep, RecordOperations, RepoAction, RepoPermissionInput, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, RpcPermissionInput, Session, SessionStore, SidecarRecordParams, SidecarResult, StateStore, StrongRef, TransitionScope, UpdateProjectParams, UpdateResult, ValidationResult };