@hypercerts-org/sdk-core 0.4.0-beta.0 → 0.6.0-beta.0

package/src/repository/HypercertOperationsImpl.ts

@@ -1,1146 +0,0 @@
-/**
- * HypercertOperationsImpl - High-level hypercert operations.
- *
- * This module provides the implementation for creating and managing
- * hypercerts, including related records like rights, locations,
- * contributions, measurements, and evaluations.
- *
- * @packageDocumentation
- */
-
-import type { Agent } from "@atproto/api";
-import { EventEmitter } from "eventemitter3";
-import { NetworkError, ValidationError } from "../core/errors.js";
-import type { LoggerInterface } from "../core/interfaces.js";
-import type { LexiconRegistry } from "./LexiconRegistry.js";
-import {
-  HYPERCERT_COLLECTIONS,
-  type BlobRef,
-  type HypercertEvidence,
-  type HypercertClaim,
-  type HypercertRights,
-  type HypercertContribution,
-  type HypercertMeasurement,
-  type HypercertEvaluation,
-  type HypercertCollection,
-  type HypercertLocation,
-} from "../services/hypercerts/types.js";
-import type {
-  HypercertOperations,
-  HypercertEvents,
-  CreateHypercertParams,
-  CreateHypercertResult,
-} from "./interfaces.js";
-import type { CreateResult, UpdateResult, PaginatedList, ListParams, ProgressStep } from "./types.js";
-
-/**
- * Implementation of high-level hypercert operations.
- *
- * This class provides a convenient API for creating and managing hypercerts
- * with automatic handling of:
- *
- * - Image upload and blob reference management
- * - Rights record creation and linking
- * - Location attachment with optional GeoJSON support
- * - Contribution tracking
- * - Measurement and evaluation records
- * - Hypercert collections
- *
- * The class extends EventEmitter to provide real-time progress notifications
- * during complex operations.
- *
- * @remarks
- * This class is typically not instantiated directly. Access it through
- * {@link Repository.hypercerts}.
- *
- * **Record Relationships**:
- * - Hypercert → Rights (required, 1:1)
- * - Hypercert → Location (optional, 1:many)
- * - Hypercert → Contribution (optional, 1:many)
- * - Hypercert → Measurement (optional, 1:many)
- * - Hypercert → Evaluation (optional, 1:many)
- * - Collection → Hypercerts (1:many via claims array)
- *
- * @example Creating a hypercert with progress tracking
- * ```typescript
- * repo.hypercerts.on("recordCreated", ({ uri }) => {
- *   console.log(`Hypercert created: ${uri}`);
- * });
- *
- * const result = await repo.hypercerts.create({
- *   title: "Climate Impact",
- *   description: "Reduced emissions by 100 tons",
- *   workScope: "Climate",
- *   workTimeframeFrom: "2024-01-01",
- *   workTimeframeTo: "2024-12-31",
- *   rights: { name: "CC-BY", type: "license", description: "..." },
- *   onProgress: (step) => console.log(`${step.name}: ${step.status}`),
- * });
- * ```
- *
- * @internal
- */
-export class HypercertOperationsImpl extends EventEmitter<HypercertEvents> implements HypercertOperations {
-  /**
-   * Creates a new HypercertOperationsImpl.
-   *
-   * @param agent - AT Protocol Agent for making API calls
-   * @param repoDid - DID of the repository to operate on
-   * @param _serverUrl - Server URL (reserved for future use)
-   * @param lexiconRegistry - Registry for record validation
-   * @param logger - Optional logger for debugging
-   *
-   * @internal
-   */
-  constructor(
-    private agent: Agent,
-    private repoDid: string,
-    private _serverUrl: string,
-    private lexiconRegistry: LexiconRegistry,
-    private logger?: LoggerInterface,
-  ) {
-    super();
-  }
-
-  /**
-   * Emits a progress event to the optional progress handler.
-   *
-   * @param onProgress - Progress callback from create params
-   * @param step - Progress step information
-   * @internal
-   */
-  private emitProgress(onProgress: ((step: ProgressStep) => void) | undefined, step: ProgressStep): void {
-    if (onProgress) {
-      try {
-        onProgress(step);
-      } catch (err) {
-        this.logger?.error(`Error in progress handler: ${err instanceof Error ? err.message : "Unknown"}`);
-      }
-    }
-  }
-
-  /**
-   * Creates a new hypercert with all related records.
-   *
-   * This method orchestrates the creation of a hypercert and its associated
-   * records in the correct order:
-   *
-   * 1. Upload image (if provided)
-   * 2. Create rights record
-   * 3. Create hypercert record (referencing rights)
-   * 4. Attach location (if provided)
-   * 5. Create contributions (if provided)
-   *
-   * @param params - Creation parameters (see {@link CreateHypercertParams})
-   * @returns Promise resolving to URIs and CIDs of all created records
-   * @throws {@link ValidationError} if any record fails validation
-   * @throws {@link NetworkError} if any API call fails
-   *
-   * @remarks
-   * The operation is not atomic - if a later step fails, earlier records
-   * will still exist. The result object will contain URIs for all
-   * successfully created records.
-   *
-   * **Progress Steps**:
-   * - `uploadImage`: Image blob upload
-   * - `createRights`: Rights record creation
-   * - `createHypercert`: Main hypercert record creation
-   * - `attachLocation`: Location record creation
-   * - `createContributions`: Contribution records creation
-   *
-   * @example Minimal hypercert
-   * ```typescript
-   * const result = await repo.hypercerts.create({
-   *   title: "My Impact",
-   *   description: "Description of impact work",
-   *   workScope: "Education",
-   *   workTimeframeFrom: "2024-01-01",
-   *   workTimeframeTo: "2024-06-30",
-   *   rights: {
-   *     name: "Attribution",
-   *     type: "license",
-   *     description: "CC-BY-4.0",
-   *   },
-   * });
-   * ```
-   *
-   * @example Full hypercert with all options
-   * ```typescript
-   * const result = await repo.hypercerts.create({
-   *   title: "Reforestation Project",
-   *   description: "Planted 10,000 trees...",
-   *   shortDescription: "10K trees planted",
-   *   workScope: "Environment",
-   *   workTimeframeFrom: "2024-01-01",
-   *   workTimeframeTo: "2024-12-31",
-   *   rights: { name: "Open", type: "impact", description: "..." },
-   *   image: coverImageBlob,
-   *   location: { value: "Amazon, Brazil", name: "Amazon Basin" },
-   *   contributions: [
-   *     { contributors: ["did:plc:org1"], role: "coordinator" },
-   *     { contributors: ["did:plc:org2"], role: "implementer" },
-   *   ],
-   *   evidence: [{ uri: "https://...", description: "Satellite data" }],
-   *   onProgress: console.log,
-   * });
-   * ```
-   */
-  async create(params: CreateHypercertParams): Promise<CreateHypercertResult> {
-    const createdAt = new Date().toISOString();
-    const result: CreateHypercertResult = {
-      hypercertUri: "",
-      rightsUri: "",
-      hypercertCid: "",
-      rightsCid: "",
-    };
-
-    try {
-      // Step 1: Upload image if provided
-      let imageBlobRef: BlobRef | undefined;
-      if (params.image) {
-        this.emitProgress(params.onProgress, { name: "uploadImage", status: "start" });
-        try {
-          const arrayBuffer = await params.image.arrayBuffer();
-          const uint8Array = new Uint8Array(arrayBuffer);
-          const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
-            encoding: params.image.type || "image/jpeg",
-          });
-          if (uploadResult.success) {
-            imageBlobRef = {
-              $type: "blob",
-              ref: uploadResult.data.blob.ref,
-              mimeType: uploadResult.data.blob.mimeType,
-              size: uploadResult.data.blob.size,
-            };
-          }
-          this.emitProgress(params.onProgress, {
-            name: "uploadImage",
-            status: "success",
-            data: { size: params.image.size },
-          });
-        } catch (error) {
-          this.emitProgress(params.onProgress, { name: "uploadImage", status: "error", error: error as Error });
-          throw new NetworkError(
-            `Failed to upload image: ${error instanceof Error ? error.message : "Unknown"}`,
-            error,
-          );
-        }
-      }
-
-      // Step 2: Create rights record
-      this.emitProgress(params.onProgress, { name: "createRights", status: "start" });
-      const rightsRecord: Omit<HypercertRights, "$type"> = {
-        rightsName: params.rights.name,
-        rightsType: params.rights.type,
-        rightsDescription: params.rights.description,
-        createdAt,
-      };
-
-      const rightsValidation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.RIGHTS, rightsRecord);
-      if (!rightsValidation.valid) {
-        throw new ValidationError(`Invalid rights record: ${rightsValidation.error}`);
-      }
-
-      const rightsResult = await this.agent.com.atproto.repo.createRecord({
-        repo: this.repoDid,
-        collection: HYPERCERT_COLLECTIONS.RIGHTS,
-        record: rightsRecord as Record<string, unknown>,
-      });
-
-      if (!rightsResult.success) {
-        throw new NetworkError("Failed to create rights record");
-      }
-
-      result.rightsUri = rightsResult.data.uri;
-      result.rightsCid = rightsResult.data.cid;
-      this.emit("rightsCreated", { uri: result.rightsUri, cid: result.rightsCid });
-      this.emitProgress(params.onProgress, {
-        name: "createRights",
-        status: "success",
-        data: { uri: result.rightsUri },
-      });
-
-      // Step 3: Create hypercert record
-      this.emitProgress(params.onProgress, { name: "createHypercert", status: "start" });
-      const hypercertRecord: Record<string, unknown> = {
-        title: params.title,
-        description: params.description,
-        workScope: params.workScope,
-        workTimeframeFrom: params.workTimeframeFrom,
-        workTimeframeTo: params.workTimeframeTo,
-        rights: { uri: result.rightsUri, cid: result.rightsCid },
-        createdAt,
-      };
-
-      if (params.shortDescription) {
-        hypercertRecord.shortDescription = params.shortDescription;
-      }
-
-      if (imageBlobRef) {
-        hypercertRecord.image = imageBlobRef;
-      }
-
-      if (params.evidence && params.evidence.length > 0) {
-        hypercertRecord.evidence = params.evidence;
-      }
-
-      const hypercertValidation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.CLAIM, hypercertRecord);
-      if (!hypercertValidation.valid) {
-        throw new ValidationError(`Invalid hypercert record: ${hypercertValidation.error}`);
-      }
-
-      const hypercertResult = await this.agent.com.atproto.repo.createRecord({
-        repo: this.repoDid,
-        collection: HYPERCERT_COLLECTIONS.CLAIM,
-        record: hypercertRecord,
-      });
-
-      if (!hypercertResult.success) {
-        throw new NetworkError("Failed to create hypercert record");
-      }
-
-      result.hypercertUri = hypercertResult.data.uri;
-      result.hypercertCid = hypercertResult.data.cid;
-      this.emit("recordCreated", { uri: result.hypercertUri, cid: result.hypercertCid });
-      this.emitProgress(params.onProgress, {
-        name: "createHypercert",
-        status: "success",
-        data: { uri: result.hypercertUri },
-      });
-
-      // Step 4: Attach location if provided
-      if (params.location) {
-        this.emitProgress(params.onProgress, { name: "attachLocation", status: "start" });
-        try {
-          const locationResult = await this.attachLocation(result.hypercertUri, params.location);
-          result.locationUri = locationResult.uri;
-          this.emitProgress(params.onProgress, {
-            name: "attachLocation",
-            status: "success",
-            data: { uri: result.locationUri },
-          });
-        } catch (error) {
-          this.emitProgress(params.onProgress, { name: "attachLocation", status: "error", error: error as Error });
-          this.logger?.warn(`Failed to attach location: ${error instanceof Error ? error.message : "Unknown"}`);
-        }
-      }
-
-      // Step 5: Create contributions if provided
-      if (params.contributions && params.contributions.length > 0) {
-        this.emitProgress(params.onProgress, { name: "createContributions", status: "start" });
-        result.contributionUris = [];
-        try {
-          for (const contrib of params.contributions) {
-            const contribResult = await this.addContribution({
-              hypercertUri: result.hypercertUri,
-              contributors: contrib.contributors,
-              role: contrib.role,
-              description: contrib.description,
-            });
-            result.contributionUris.push(contribResult.uri);
-          }
-          this.emitProgress(params.onProgress, {
-            name: "createContributions",
-            status: "success",
-            data: { count: result.contributionUris.length },
-          });
-        } catch (error) {
-          this.emitProgress(params.onProgress, { name: "createContributions", status: "error", error: error as Error });
-          this.logger?.warn(`Failed to create contributions: ${error instanceof Error ? error.message : "Unknown"}`);
-        }
-      }
-
-      return result;
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(
-        `Failed to create hypercert: ${error instanceof Error ? error.message : "Unknown"}`,
-        error,
-      );
-    }
-  }
-
-  /**
-   * Updates an existing hypercert record.
-   *
-   * @param params - Update parameters
-   * @param params.uri - AT-URI of the hypercert to update
-   * @param params.updates - Partial record with fields to update
-   * @param params.image - New image blob, `null` to remove, `undefined` to keep existing
-   * @returns Promise resolving to update result
-   * @throws {@link ValidationError} if the URI format is invalid or record fails validation
-   * @throws {@link NetworkError} if the update fails
-   *
-   * @remarks
-   * This is a partial update - only specified fields are changed.
-   * The `createdAt` and `rights` fields cannot be changed.
-   *
-   * @example Update title and description
-   * ```typescript
-   * await repo.hypercerts.update({
-   *   uri: "at://did:plc:abc/org.hypercerts.hypercert/xyz",
-   *   updates: {
-   *     title: "Updated Title",
-   *     description: "New description",
-   *   },
-   * });
-   * ```
-   *
-   * @example Update with new image
-   * ```typescript
-   * await repo.hypercerts.update({
-   *   uri: hypercertUri,
-   *   updates: { title: "New Title" },
-   *   image: newImageBlob,
-   * });
-   * ```
-   *
-   * @example Remove image
-   * ```typescript
-   * await repo.hypercerts.update({
-   *   uri: hypercertUri,
-   *   updates: {},
-   *   image: null,  // Explicitly remove image
-   * });
-   * ```
-   */
-  async update(params: {
-    uri: string;
-    updates: Partial<Omit<HypercertClaim, "$type" | "createdAt" | "rights">>;
-    image?: Blob | null;
-  }): Promise<UpdateResult> {
-    try {
-      const uriMatch = params.uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-      if (!uriMatch) {
-        throw new ValidationError(`Invalid URI format: ${params.uri}`);
-      }
-      const [, , collection, rkey] = uriMatch;
-
-      const existing = await this.agent.com.atproto.repo.getRecord({
-        repo: this.repoDid,
-        collection,
-        rkey,
-      });
-
-      // The existing record comes from ATProto, use it directly
-      // TypeScript ensures type safety through the HypercertClaim interface
-      const existingRecord = existing.data.value as HypercertClaim;
-
-      const recordForUpdate: Record<string, unknown> = {
-        ...existingRecord,
-        ...params.updates,
-        createdAt: existingRecord.createdAt,
-        rights: existingRecord.rights,
-      };
-
-      // Handle image update
-      delete (recordForUpdate as { image?: unknown }).image;
-      if (params.image !== undefined) {
-        if (params.image === null) {
-          // Remove image
-        } else {
-          const arrayBuffer = await params.image.arrayBuffer();
-          const uint8Array = new Uint8Array(arrayBuffer);
-          const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
-            encoding: params.image.type || "image/jpeg",
-          });
-          if (uploadResult.success) {
-            recordForUpdate.image = {
-              $type: "blob",
-              ref: uploadResult.data.blob.ref,
-              mimeType: uploadResult.data.blob.mimeType,
-              size: uploadResult.data.blob.size,
-            };
-          }
-        }
-      } else if (existingRecord.image) {
-        // Preserve existing image
-        recordForUpdate.image = existingRecord.image;
-      }
-
-      const validation = this.lexiconRegistry.validate(collection, recordForUpdate);
-      if (!validation.valid) {
-        throw new ValidationError(`Invalid hypercert record: ${validation.error}`);
-      }
-
-      const result = await this.agent.com.atproto.repo.putRecord({
-        repo: this.repoDid,
-        collection,
-        rkey,
-        record: recordForUpdate,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to update hypercert");
-      }
-
-      this.emit("recordUpdated", { uri: result.data.uri, cid: result.data.cid });
-      return { uri: result.data.uri, cid: result.data.cid };
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(
-        `Failed to update hypercert: ${error instanceof Error ? error.message : "Unknown"}`,
-        error,
-      );
-    }
-  }
-
-  /**
-   * Gets a hypercert by its AT-URI.
-   *
-   * @param uri - AT-URI of the hypercert (e.g., "at://did:plc:abc/org.hypercerts.hypercert/xyz")
-   * @returns Promise resolving to hypercert URI, CID, and parsed record
-   * @throws {@link ValidationError} if the URI format is invalid or record doesn't match schema
-   * @throws {@link NetworkError} if the record cannot be fetched
-   *
-   * @example
-   * ```typescript
-   * const { uri, cid, record } = await repo.hypercerts.get(hypercertUri);
-   * console.log(`${record.title}: ${record.description}`);
-   * ```
-   */
-  async get(uri: string): Promise<{ uri: string; cid: string; record: HypercertClaim }> {
-    try {
-      const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-      if (!uriMatch) {
-        throw new ValidationError(`Invalid URI format: ${uri}`);
-      }
-      const [, , collection, rkey] = uriMatch;
-
-      const result = await this.agent.com.atproto.repo.getRecord({
-        repo: this.repoDid,
-        collection,
-        rkey,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to get hypercert");
-      }
-
-      // Validate with lexicon registry (more lenient - doesn't require $type)
-      const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.CLAIM, result.data.value);
-      if (!validation.valid) {
-        throw new ValidationError(`Invalid hypercert record format: ${validation.error}`);
-      }
-
-      return {
-        uri: result.data.uri,
-        cid: result.data.cid ?? "",
-        record: result.data.value as HypercertClaim,
-      };
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(`Failed to get hypercert: ${error instanceof Error ? error.message : "Unknown"}`, error);
-    }
-  }
-
-  /**
-   * Lists hypercerts in the repository with pagination.
-   *
-   * @param params - Optional pagination parameters
-   * @returns Promise resolving to paginated list of hypercerts
-   * @throws {@link NetworkError} if the list operation fails
-   *
-   * @example
-   * ```typescript
-   * // Get first page
-   * const { records, cursor } = await repo.hypercerts.list({ limit: 20 });
-   *
-   * // Get next page
-   * if (cursor) {
-   *   const nextPage = await repo.hypercerts.list({ limit: 20, cursor });
-   * }
-   * ```
-   */
-  async list(params?: ListParams): Promise<PaginatedList<{ uri: string; cid: string; record: HypercertClaim }>> {
-    try {
-      const result = await this.agent.com.atproto.repo.listRecords({
-        repo: this.repoDid,
-        collection: HYPERCERT_COLLECTIONS.CLAIM,
-        limit: params?.limit,
-        cursor: params?.cursor,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to list hypercerts");
-      }
-
-      return {
-        records:
-          result.data.records?.map((r) => ({
-            uri: r.uri,
-            cid: r.cid,
-            record: r.value as HypercertClaim,
-          })) || [],
-        cursor: result.data.cursor ?? undefined,
-      };
-    } catch (error) {
-      if (error instanceof NetworkError) throw error;
-      throw new NetworkError(`Failed to list hypercerts: ${error instanceof Error ? error.message : "Unknown"}`, error);
-    }
-  }
-
-  /**
-   * Deletes a hypercert record.
-   *
-   * @param uri - AT-URI of the hypercert to delete
-   * @throws {@link ValidationError} if the URI format is invalid
-   * @throws {@link NetworkError} if the deletion fails
-   *
-   * @remarks
-   * This only deletes the hypercert record itself. Related records
-   * (rights, locations, contributions) are not automatically deleted.
-   *
-   * @example
-   * ```typescript
-   * await repo.hypercerts.delete(hypercertUri);
-   * ```
-   */
-  async delete(uri: string): Promise<void> {
-    try {
-      const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-      if (!uriMatch) {
-        throw new ValidationError(`Invalid URI format: ${uri}`);
-      }
-      const [, , collection, rkey] = uriMatch;
-
-      const result = await this.agent.com.atproto.repo.deleteRecord({
-        repo: this.repoDid,
-        collection,
-        rkey,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to delete hypercert");
-      }
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(
-        `Failed to delete hypercert: ${error instanceof Error ? error.message : "Unknown"}`,
-        error,
-      );
-    }
-  }
-
-  /**
-   * Attaches a location to an existing hypercert.
-   *
-   * @param hypercertUri - AT-URI of the hypercert to attach location to
-   * @param location - Location data
-   * @param location.value - Location value (address, coordinates, or description)
-   * @param location.name - Optional human-readable name
-   * @param location.description - Optional description
-   * @param location.srs - Spatial Reference System (e.g., "EPSG:4326")
-   * @param location.geojson - Optional GeoJSON blob for precise boundaries
-   * @returns Promise resolving to location record URI and CID
-   * @throws {@link ValidationError} if validation fails
-   * @throws {@link NetworkError} if the operation fails
-   *
-   * @example Simple location
-   * ```typescript
-   * await repo.hypercerts.attachLocation(hypercertUri, {
-   *   value: "San Francisco, CA",
-   *   name: "SF Bay Area",
-   * });
-   * ```
-   *
-   * @example Location with GeoJSON
-   * ```typescript
-   * const geojsonBlob = new Blob([JSON.stringify(geojson)], {
-   *   type: "application/geo+json"
-   * });
-   *
-   * await repo.hypercerts.attachLocation(hypercertUri, {
-   *   value: "Custom Region",
-   *   srs: "EPSG:4326",
-   *   geojson: geojsonBlob,
-   * });
-   * ```
-   */
-  async attachLocation(
-    hypercertUri: string,
-    location: { value: string; name?: string; description?: string; srs?: string; geojson?: Blob },
-  ): Promise<CreateResult> {
-    try {
-      // Get hypercert to get CID
-      const hypercert = await this.get(hypercertUri);
-      const createdAt = new Date().toISOString();
-
-      let locationValue: string | BlobRef = location.value;
-      if (location.geojson) {
-        const arrayBuffer = await location.geojson.arrayBuffer();
-        const uint8Array = new Uint8Array(arrayBuffer);
-        const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
-          encoding: location.geojson.type || "application/geo+json",
-        });
-        if (uploadResult.success) {
-          locationValue = {
-            $type: "blob",
-            ref: uploadResult.data.blob.ref,
-            mimeType: uploadResult.data.blob.mimeType,
-            size: uploadResult.data.blob.size,
-          };
-        }
-      }
-
-      const locationRecord: Omit<HypercertLocation, "$type"> = {
-        hypercert: { uri: hypercert.uri, cid: hypercert.cid },
-        value: locationValue,
-        createdAt,
-        name: location.name,
-        description: location.description,
-        srs: location.srs,
-      };
-
-      const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.LOCATION, locationRecord);
-      if (!validation.valid) {
-        throw new ValidationError(`Invalid location record: ${validation.error}`);
-      }
-
-      const result = await this.agent.com.atproto.repo.createRecord({
-        repo: this.repoDid,
-        collection: HYPERCERT_COLLECTIONS.LOCATION,
-        record: locationRecord as Record<string, unknown>,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to attach location");
-      }
-
-      this.emit("locationAttached", { uri: result.data.uri, cid: result.data.cid, hypercertUri });
-      return { uri: result.data.uri, cid: result.data.cid };
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(`Failed to attach location: ${error instanceof Error ? error.message : "Unknown"}`, error);
-    }
-  }
-
-  /**
-   * Adds evidence to an existing hypercert.
-   *
-   * @param hypercertUri - AT-URI of the hypercert
-   * @param evidence - Array of evidence items to add
-   * @returns Promise resolving to update result
-   * @throws {@link ValidationError} if validation fails
-   * @throws {@link NetworkError} if the operation fails
-   *
-   * @remarks
-   * Evidence is appended to existing evidence, not replaced.
-   *
-   * @example
-   * ```typescript
-   * await repo.hypercerts.addEvidence(hypercertUri, [
-   *   { uri: "https://example.com/report.pdf", description: "Impact report" },
-   *   { uri: "https://example.com/data.csv", description: "Raw data" },
-   * ]);
-   * ```
-   */
-  async addEvidence(hypercertUri: string, evidence: HypercertEvidence[]): Promise<UpdateResult> {
-    try {
-      const existing = await this.get(hypercertUri);
-      const existingEvidence = existing.record.evidence || [];
-      const updatedEvidence = [...existingEvidence, ...evidence];
-
-      const result = await this.update({
-        uri: hypercertUri,
-        updates: { evidence: updatedEvidence },
-      });
-
-      this.emit("evidenceAdded", { uri: result.uri, cid: result.cid });
-      return result;
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(`Failed to add evidence: ${error instanceof Error ? error.message : "Unknown"}`, error);
-    }
-  }
-
-  /**
-   * Creates a contribution record.
-   *
-   * @param params - Contribution parameters
-   * @param params.hypercertUri - Optional hypercert to link (can be standalone)
-   * @param params.contributors - Array of contributor DIDs
-   * @param params.role - Role of the contributors (e.g., "coordinator", "implementer")
-   * @param params.description - Optional description of the contribution
-   * @returns Promise resolving to contribution record URI and CID
-   * @throws {@link ValidationError} if validation fails
-   * @throws {@link NetworkError} if the operation fails
-   *
-   * @example
-   * ```typescript
-   * await repo.hypercerts.addContribution({
-   *   hypercertUri: hypercertUri,
-   *   contributors: ["did:plc:alice", "did:plc:bob"],
-   *   role: "implementer",
-   *   description: "On-ground implementation team",
-   * });
-   * ```
-   */
-  async addContribution(params: {
-    hypercertUri?: string;
-    contributors: string[];
-    role: string;
-    description?: string;
-  }): Promise<CreateResult> {
-    try {
-      const createdAt = new Date().toISOString();
-      const contributionRecord: Omit<HypercertContribution, "$type"> = {
-        contributors: params.contributors,
-        role: params.role,
-        createdAt,
-        description: params.description,
-      };
-
-      if (params.hypercertUri) {
-        const hypercert = await this.get(params.hypercertUri);
-        contributionRecord.hypercert = { uri: hypercert.uri, cid: hypercert.cid };
-      }
-
-      const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.CONTRIBUTION, contributionRecord);
-      if (!validation.valid) {
-        throw new ValidationError(`Invalid contribution record: ${validation.error}`);
-      }
-
-      const result = await this.agent.com.atproto.repo.createRecord({
-        repo: this.repoDid,
-        collection: HYPERCERT_COLLECTIONS.CONTRIBUTION,
-        record: contributionRecord as Record<string, unknown>,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to create contribution");
-      }
-
-      this.emit("contributionCreated", { uri: result.data.uri, cid: result.data.cid });
-      return { uri: result.data.uri, cid: result.data.cid };
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(
-        `Failed to add contribution: ${error instanceof Error ? error.message : "Unknown"}`,
-        error,
-      );
-    }
-  }
-
-  /**
-   * Creates a measurement record for a hypercert.
-   *
-   * Measurements quantify the impact claimed in a hypercert with
-   * specific metrics and values.
-   *
-   * @param params - Measurement parameters
-   * @param params.hypercertUri - AT-URI of the hypercert being measured
-   * @param params.measurers - DIDs of entities who performed the measurement
-   * @param params.metric - Name of the metric (e.g., "CO2 Reduced", "Trees Planted")
-   * @param params.value - Measured value with units (e.g., "100 tons", "10000")
-   * @param params.methodUri - Optional URI describing the measurement methodology
-   * @param params.evidenceUris - Optional URIs to supporting evidence
-   * @returns Promise resolving to measurement record URI and CID
-   * @throws {@link ValidationError} if validation fails
-   * @throws {@link NetworkError} if the operation fails
-   *
-   * @example
-   * ```typescript
-   * await repo.hypercerts.addMeasurement({
-   *   hypercertUri: hypercertUri,
-   *   measurers: ["did:plc:auditor"],
-   *   metric: "Carbon Offset",
-   *   value: "150 tons CO2e",
-   *   methodUri: "https://example.com/methodology",
-   *   evidenceUris: ["https://example.com/audit-report"],
-   * });
-   * ```
-   */
-  async addMeasurement(params: {
-    hypercertUri: string;
-    measurers: string[];
-    metric: string;
-    value: string;
-    methodUri?: string;
-    evidenceUris?: string[];
-  }): Promise<CreateResult> {
-    try {
-      const hypercert = await this.get(params.hypercertUri);
-      const createdAt = new Date().toISOString();
-
-      const measurementRecord: Omit<HypercertMeasurement, "$type"> = {
-        hypercert: { uri: hypercert.uri, cid: hypercert.cid },
-        measurers: params.measurers,
-        metric: params.metric,
-        value: params.value,
-        createdAt,
-        measurementMethodURI: params.methodUri,
-        evidenceURI: params.evidenceUris,
-      };
-
-      const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.MEASUREMENT, measurementRecord);
-      if (!validation.valid) {
-        throw new ValidationError(`Invalid measurement record: ${validation.error}`);
-      }
-
-      const result = await this.agent.com.atproto.repo.createRecord({
-        repo: this.repoDid,
-        collection: HYPERCERT_COLLECTIONS.MEASUREMENT,
-        record: measurementRecord as Record<string, unknown>,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to create measurement");
-      }
-
-      return { uri: result.data.uri, cid: result.data.cid };
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(`Failed to add measurement: ${error instanceof Error ? error.message : "Unknown"}`, error);
-    }
-  }
-
-  /**
-   * Creates an evaluation record for a hypercert or other subject.
-   *
-   * Evaluations provide third-party assessments of impact claims.
-   *
-   * @param params - Evaluation parameters
-   * @param params.subjectUri - AT-URI of the record being evaluated
-   * @param params.evaluators - DIDs of evaluating entities
-   * @param params.summary - Summary of the evaluation findings
-   * @returns Promise resolving to evaluation record URI and CID
-   * @throws {@link ValidationError} if validation fails
-   * @throws {@link NetworkError} if the operation fails
-   *
-   * @example
-   * ```typescript
-   * await repo.hypercerts.addEvaluation({
-   *   subjectUri: hypercertUri,
-   *   evaluators: ["did:plc:evaluator-org"],
-   *   summary: "Verified impact claims through site visit and data analysis",
-   * });
-   * ```
-   */
-  async addEvaluation(params: { subjectUri: string; evaluators: string[]; summary: string }): Promise<CreateResult> {
-    try {
-      const subject = await this.get(params.subjectUri);
-      const createdAt = new Date().toISOString();
-
-      const evaluationRecord: Omit<HypercertEvaluation, "$type"> = {
-        subject: { uri: subject.uri, cid: subject.cid },
-        evaluators: params.evaluators,
-        summary: params.summary,
-        createdAt,
-      };
-
-      const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.EVALUATION, evaluationRecord);
-      if (!validation.valid) {
-        throw new ValidationError(`Invalid evaluation record: ${validation.error}`);
-      }
-
-      const result = await this.agent.com.atproto.repo.createRecord({
-        repo: this.repoDid,
-        collection: HYPERCERT_COLLECTIONS.EVALUATION,
-        record: evaluationRecord as Record<string, unknown>,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to create evaluation");
-      }
-
-      return { uri: result.data.uri, cid: result.data.cid };
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(`Failed to add evaluation: ${error instanceof Error ? error.message : "Unknown"}`, error);
-    }
-  }
-
-  /**
-   * Creates a collection of hypercerts.
-   *
-   * Collections group related hypercerts with optional weights
-   * for relative importance.
-   *
-   * @param params - Collection parameters
-   * @param params.title - Collection title
-   * @param params.claims - Array of hypercert references with weights
-   * @param params.shortDescription - Optional short description
-   * @param params.coverPhoto - Optional cover image blob
-   * @returns Promise resolving to collection record URI and CID
-   * @throws {@link ValidationError} if validation fails
-   * @throws {@link NetworkError} if the operation fails
-   *
-   * @example
-   * ```typescript
-   * const collection = await repo.hypercerts.createCollection({
-   *   title: "Climate Projects 2024",
-   *   shortDescription: "Our climate impact portfolio",
-   *   claims: [
-   *     { uri: hypercert1Uri, cid: hypercert1Cid, weight: "0.5" },
-   *     { uri: hypercert2Uri, cid: hypercert2Cid, weight: "0.3" },
-   *     { uri: hypercert3Uri, cid: hypercert3Cid, weight: "0.2" },
-   *   ],
-   *   coverPhoto: coverImageBlob,
-   * });
-   * ```
-   */
-  async createCollection(params: {
-    title: string;
-    claims: Array<{ uri: string; cid: string; weight: string }>;
-    shortDescription?: string;
-    coverPhoto?: Blob;
-  }): Promise<CreateResult> {
-    try {
-      const createdAt = new Date().toISOString();
-
-      let coverPhotoRef: BlobRef | undefined;
-      if (params.coverPhoto) {
-        const arrayBuffer = await params.coverPhoto.arrayBuffer();
-        const uint8Array = new Uint8Array(arrayBuffer);
-        const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
-          encoding: params.coverPhoto.type || "image/jpeg",
-        });
-        if (uploadResult.success) {
-          coverPhotoRef = {
-            $type: "blob",
-            ref: uploadResult.data.blob.ref,
-            mimeType: uploadResult.data.blob.mimeType,
-            size: uploadResult.data.blob.size,
-          };
-        }
-      }
-
-      const collectionRecord: Record<string, unknown> = {
-        title: params.title,
-        claims: params.claims.map((c) => ({ claim: { uri: c.uri, cid: c.cid }, weight: c.weight })),
-        createdAt,
-      };
-
-      if (params.shortDescription) {
-        collectionRecord.shortDescription = params.shortDescription;
-      }
-
-      if (coverPhotoRef) {
-        collectionRecord.coverPhoto = coverPhotoRef;
-      }
-
-      const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.COLLECTION, collectionRecord);
-      if (!validation.valid) {
-        throw new ValidationError(`Invalid collection record: ${validation.error}`);
-      }
-
-      const result = await this.agent.com.atproto.repo.createRecord({
-        repo: this.repoDid,
-        collection: HYPERCERT_COLLECTIONS.COLLECTION,
-        record: collectionRecord,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to create collection");
-      }
-
-      this.emit("collectionCreated", { uri: result.data.uri, cid: result.data.cid });
-      return { uri: result.data.uri, cid: result.data.cid };
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(
-        `Failed to create collection: ${error instanceof Error ? error.message : "Unknown"}`,
-        error,
-      );
-    }
-  }
-
-  /**
-   * Gets a collection by its AT-URI.
-   *
-   * @param uri - AT-URI of the collection
-   * @returns Promise resolving to collection URI, CID, and parsed record
-   * @throws {@link ValidationError} if the URI format is invalid or record doesn't match schema
-   * @throws {@link NetworkError} if the record cannot be fetched
-   *
-   * @example
-   * ```typescript
-   * const { record } = await repo.hypercerts.getCollection(collectionUri);
-   * console.log(`Collection: ${record.title}`);
-   * console.log(`Contains ${record.claims.length} hypercerts`);
-   * ```
-   */
-  async getCollection(uri: string): Promise<{ uri: string; cid: string; record: HypercertCollection }> {
-    try {
-      const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
-      if (!uriMatch) {
-        throw new ValidationError(`Invalid URI format: ${uri}`);
-      }
-      const [, , collection, rkey] = uriMatch;
-
-      const result = await this.agent.com.atproto.repo.getRecord({
-        repo: this.repoDid,
-        collection,
-        rkey,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to get collection");
-      }
-
-      // Validate with lexicon registry (more lenient - doesn't require $type)
-      const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.COLLECTION, result.data.value);
-      if (!validation.valid) {
-        throw new ValidationError(`Invalid collection record format: ${validation.error}`);
-      }
-
-      return {
-        uri: result.data.uri,
-        cid: result.data.cid ?? "",
-        record: result.data.value as HypercertCollection,
-      };
-    } catch (error) {
-      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
-      throw new NetworkError(`Failed to get collection: ${error instanceof Error ? error.message : "Unknown"}`, error);
-    }
-  }
-
-  /**
-   * Lists collections in the repository with pagination.
-   *
-   * @param params - Optional pagination parameters
-   * @returns Promise resolving to paginated list of collections
-   * @throws {@link NetworkError} if the list operation fails
-   *
-   * @example
-   * ```typescript
-   * const { records } = await repo.hypercerts.listCollections();
-   * for (const { record } of records) {
-   *   console.log(`${record.title}: ${record.claims.length} claims`);
-   * }
-   * ```
-   */
-  async listCollections(
-    params?: ListParams,
-  ): Promise<PaginatedList<{ uri: string; cid: string; record: HypercertCollection }>> {
-    try {
-      const result = await this.agent.com.atproto.repo.listRecords({
-        repo: this.repoDid,
-        collection: HYPERCERT_COLLECTIONS.COLLECTION,
-        limit: params?.limit,
-        cursor: params?.cursor,
-      });
-
-      if (!result.success) {
-        throw new NetworkError("Failed to list collections");
-      }
-
-      return {
-        records:
-          result.data.records?.map((r) => ({
-            uri: r.uri,
-            cid: r.cid,
-            record: r.value as HypercertCollection,
-          })) || [],
-        cursor: result.data.cursor ?? undefined,
-      };
-    } catch (error) {
-      if (error instanceof NetworkError) throw error;
-      throw new NetworkError(
-        `Failed to list collections: ${error instanceof Error ? error.message : "Unknown"}`,
-        error,
-      );
-    }
-  }
-}