feat: add updateMeasurement function

Author: Kzoeps

.changeset/update-measurement-api.md

@@ -16,10 +16,11 @@ Update measurement API to align with lexicon beta.12+ schema
 **Breaking Changes (sdk-react):**
 
 - Removed `OrgHypercertsDefs` export (WorkScope types removed from lexicon)
-- `UpdateHypercertParams.workScope` now accepts `string | { uri: string; cid: string } | { $type: string }`
+- `UpdateHypercertParams.workScope` now accepts `string | StrongRef` (i.e., `string | { uri: string; cid: string }`)
 
 **New Features:**
 
+- Added `updateMeasurement()` method with `UpdateMeasurementParams` type (subject is immutable)
 - Support for `locations` array to specify where measurements were taken
 - Added `startDate` and `endDate` for measurement timeframes
 - Added `methodType` for short methodology identifiers

packages/sdk-core/src/repository/HypercertOperationsImpl.ts

@@ -35,6 +35,7 @@ import {
   type UpdateCollectionParams,
   type UpdateProjectParams,
   type CreateMeasurementParams,
+  type UpdateMeasurementParams,
 } from "../services/hypercerts/types.js";
 import type {
   CreateHypercertEvidenceParams,
@@ -1190,6 +1191,45 @@ export class HypercertOperationsImpl extends EventEmitter<HypercertEvents> imple
     }
   }
 
+  /**
+   * Applies updates to an existing measurement record, preserving immutable fields.
+   *
+   * @param existing - The existing measurement record
+   * @param updates - The updates to apply
+   * @returns Promise resolving to the updated measurement record
+   * @internal
+   */
+  private async applyMeasurementUpdates(
+    existing: HypercertMeasurement,
+    updates: UpdateMeasurementParams,
+  ): Promise<HypercertMeasurement> {
+    const record: HypercertMeasurement = {
+      ...existing,
+      // Preserve immutable fields
+      $type: existing.$type,
+      subject: existing.subject,
+      createdAt: existing.createdAt,
+    };
+
+    if (updates.metric !== undefined) record.metric = updates.metric;
+    if (updates.unit !== undefined) record.unit = updates.unit;
+    if (updates.value !== undefined) record.value = updates.value;
+    if (updates.startDate !== undefined) record.startDate = updates.startDate;
+    if (updates.endDate !== undefined) record.endDate = updates.endDate;
+    if (updates.methodType !== undefined) record.methodType = updates.methodType;
+    if (updates.methodURI !== undefined) record.methodURI = updates.methodURI;
+    if (updates.evidenceURI !== undefined) record.evidenceURI = updates.evidenceURI;
+    if (updates.measurers !== undefined) record.measurers = updates.measurers;
+    if (updates.comment !== undefined) record.comment = updates.comment;
+    if (updates.commentFacets !== undefined) record.commentFacets = updates.commentFacets;
+
+    if (updates.locations !== undefined) {
+      record.locations = await this.processLocations(updates.locations);
+    }
+
+    return record;
+  }
+
   /**
    * Processes contribution parameters, creating contributor/contribution records if necessary.
    *
@@ -1530,7 +1570,7 @@ export class HypercertOperationsImpl extends EventEmitter<HypercertEvents> imple
    * @example Basic measurement
    * ```typescript
    * await repo.hypercerts.addMeasurement({
-   *   subjectUri: hypercertUri,
+   *   subject: hypercertUri,
    *   metric: "Carbon Offset",
    *   unit: "tons CO2e",
    *   value: "150",
@@ -1549,31 +1589,26 @@ export class HypercertOperationsImpl extends EventEmitter<HypercertEvents> imple
    *   locations: [{ uri: "at://...", cid: "..." }],
    *   measurers: ["did:plc:auditor"],
    *   methodType: "satellite-imagery",
-   *   methodUri: "https://example.com/methodology",
-   *   evidenceUris: ["https://example.com/audit-report"],
+   *   methodURI: "https://example.com/methodology",
+   *   evidenceURI: ["https://example.com/audit-report"],
    *   comment: "Verified via satellite imagery",
    * });
    * ```
    */
   async addMeasurement(params: CreateMeasurementParams): Promise<CreateResult> {
     try {
-      // Resolve subject to get CID
       const subject = await this.resolveToStrongRef(params.subject);
       const createdAt = new Date().toISOString();
 
-      // Resolve locations if provided (reuse existing processLocations helper)
       const locationRefs = await this.processLocations(params.locations);
 
-      // Cast to Record<string, unknown> to avoid type mismatches between
-      // different Bluesky client packages (@atproto/api vs @atcute/bluesky)
       const measurementRecord: HypercertMeasurement = {
         $type: HYPERCERT_COLLECTIONS.MEASUREMENT,
         subject: { uri: subject.uri, cid: subject.cid },
         metric: params.metric,
         unit: params.unit,
         value: params.value,
         createdAt,
-        // Optional fields
         startDate: params.startDate,
         endDate: params.endDate,
         locations: locationRefs,
@@ -1607,6 +1642,78 @@ export class HypercertOperationsImpl extends EventEmitter<HypercertEvents> imple
     }
   }
 
+  /**
+   * Updates a measurement record.
+   *
+   * Note: The `subject` field is immutable and cannot be changed after creation.
+   *
+   * @param uri - AT-URI of the measurement to update
+   * @param updates - Fields to update (subject is excluded as it's immutable)
+   * @returns Promise resolving to updated measurement URI and CID
+   * @throws {@link ValidationError} if validation fails or URI format is invalid
+   * @throws {@link NetworkError} if the measurement is not found or update fails
+   *
+   * @example Updating a measurement value
+   * ```typescript
+   * await repo.hypercerts.updateMeasurement(
+   *   "at://did:plc:test/org.hypercerts.claim.measurement/xyz",
+   *   { value: "200", comment: "Re-verified measurement" }
+   * );
+   * ```
+   */
+  async updateMeasurement(uri: string, updates: UpdateMeasurementParams): Promise<UpdateResult> {
+    try {
+      const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
+      if (!uriMatch) {
+        throw new ValidationError(`Invalid URI format: ${uri}`);
+      }
+      const [, , collection, rkey] = uriMatch;
+
+      if (collection !== HYPERCERT_COLLECTIONS.MEASUREMENT) {
+        throw new ValidationError(
+          `URI must target a measurement collection. Expected '${HYPERCERT_COLLECTIONS.MEASUREMENT}', got '${collection}'`,
+        );
+      }
+
+      const existing = await this.agent.com.atproto.repo.getRecord({
+        repo: this.repoDid,
+        collection,
+        rkey,
+      });
+
+      if (!existing.success) {
+        throw new NetworkError(`Measurement not found: ${uri}`);
+      }
+
+      const recordForUpdate = await this.applyMeasurementUpdates(existing.data.value as HypercertMeasurement, updates);
+
+      const validation = validate(recordForUpdate, HYPERCERT_COLLECTIONS.MEASUREMENT, "main", false);
+      if (!validation.success) {
+        throw new ValidationError(`Invalid measurement record: ${validation.error?.message}`);
+      }
+
+      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 measurement");
+      }
+
+      this.emit("measurementUpdated", { 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 measurement: ${error instanceof Error ? error.message : "Unknown"}`,
+        error,
+      );
+    }
+  }
+
   /**
    * Creates an evaluation record for a hypercert or other subject.
    *

packages/sdk-core/src/repository/interfaces.ts

@@ -21,6 +21,7 @@ import type {
   UpdateCollectionParams,
   UpdateProjectParams,
   CreateMeasurementParams,
+  UpdateMeasurementParams,
   StrongRef,
 } from "../services/hypercerts/types.js";
 import type {
@@ -844,6 +845,11 @@ export interface HypercertEvents {
    * Emitted when a location is removed from a project.
    */
   locationRemovedFromProject: { projectUri: string };
+
+  /**
+   * Emitted when a measurement is updated.
+   */
+  measurementUpdated: { uri: string; cid: string };
 }
 
 /**
@@ -976,7 +982,7 @@ export interface HypercertOperations extends EventEmitter<HypercertEvents> {
    * @example Basic measurement
    * ```typescript
    * await repo.hypercerts.addMeasurement({
-   *   subjectUri: hypercertUri,
+   *   subject: hypercertUri,
    *   metric: "Carbon Offset",
    *   unit: "tons CO2e",
    *   value: "150",
@@ -995,14 +1001,35 @@ export interface HypercertOperations extends EventEmitter<HypercertEvents> {
    *   locations: [{ uri: "at://...", cid: "..." }],
    *   measurers: ["did:plc:auditor"],
    *   methodType: "satellite-imagery",
-   *   methodUri: "https://example.com/methodology",
-   *   evidenceUris: ["https://example.com/audit-report"],
+   *   methodURI: "https://example.com/methodology",
+   *   evidenceURI: ["https://example.com/audit-report"],
    *   comment: "Verified via satellite imagery",
    * });
    * ```
    */
   addMeasurement(params: CreateMeasurementParams): Promise<CreateResult>;
 
+  /**
+   * Updates a measurement record.
+   *
+   * Note: The `subject` field is immutable and cannot be changed after creation.
+   *
+   * @param uri - AT-URI of the measurement to update
+   * @param updates - Fields to update (subject is excluded as it's immutable)
+   * @returns Promise resolving to updated measurement URI and CID
+   * @throws {@link ValidationError} if validation fails or URI format is invalid
+   * @throws {@link NetworkError} if the measurement is not found or update fails
+   *
+   * @example Updating a measurement value
+   * ```typescript
+   * await repo.hypercerts.updateMeasurement(
+   *   "at://did:plc:test/org.hypercerts.claim.measurement/xyz",
+   *   { value: "200", comment: "Re-verified measurement" }
+   * );
+   * ```
+   */
+  updateMeasurement(uri: string, updates: UpdateMeasurementParams): Promise<UpdateResult>;
+
   /**
    * Creates an evaluation record.
    *

packages/sdk-core/src/services/hypercerts/types.ts

@@ -9,7 +9,7 @@
 // Re-export BlobRef from ATProto lexicon
 export { BlobRef } from "@atproto/lexicon";
 export type { JsonBlobRef } from "@atproto/lexicon";
-import type { OverrideProperties, SetOptional } from "type-fest";
+import type { Except, OverrideProperties, SetOptional } from "type-fest";
 
 // Re-export everything from lexicon package
 export {
@@ -385,6 +385,14 @@ export type CreateProjectResult = CreateCollectionResult;
 // Measurement Types
 // ============================================================================
 
+/**
+ * SDK type for measurement records.
+ * Alias for the lexicon Main type, used in SDK operations.
+ *
+ * @see HypercertMeasurement - Equivalent alias
+ */
+export type Measurement = OrgHypercertsClaimMeasurement.Main;
+
 /**
  * SDK input parameters for creating a measurement.
  *
@@ -419,6 +427,7 @@ export type CreateProjectResult = CreateCollectionResult;
  * };
  * ```
  */
+
 export type CreateMeasurementParams = OverrideProperties<
   SetOptional<OrgHypercertsClaimMeasurement.Main, "$type" | "createdAt">,
   {
@@ -437,3 +446,56 @@ export type CreateMeasurementParams = OverrideProperties<
     locations?: LocationParams[];
   }
 >;
+
+/**
+ * SDK input parameters for updating a measurement.
+ * All fields are optional for partial/patch updates.
+ *
+ * Note: `subject` is excluded as it is immutable after creation.
+ *
+ * @example Updating a measurement's value
+ * ```typescript
+ * const updateParams: UpdateMeasurementParams = {
+ *   value: "200",
+ *   comment: "Updated measurement after re-verification",
+ * };
+ * ```
+ *
+ * @example Updating locations
+ * ```typescript
+ * const updateParams: UpdateMeasurementParams = {
+ *   locations: [{ uri: "at://did:plc:.../app.certified.location/new", cid: "..." }],
+ * };
+ * ```
+ */
+export type UpdateMeasurementParams = Partial<Except<CreateMeasurementParams, "subject">>;
+
+/**
+ * Union type for referencing measurements in SDK methods.
+ *
+ * Accepts:
+ * 1. **string** - AT-URI pointing to an existing measurement record
+ * 2. **StrongRef** - Direct reference with uri and cid
+ * 3. **CreateMeasurementParams** - Inline measurement object for creation
+ *
+ * @example Using an AT-URI
+ * ```typescript
+ * const measurement: MeasurementParams = "at://did:plc:abc/org.hypercerts.claim.measurement/xyz";
+ * ```
+ *
+ * @example Using a StrongRef
+ * ```typescript
+ * const measurement: MeasurementParams = { uri: "at://...", cid: "bafyrei..." };
+ * ```
+ *
+ * @example Using inline params
+ * ```typescript
+ * const measurement: MeasurementParams = {
+ *   subject: "at://did:plc:abc/org.hypercerts.claim.activity/xyz",
+ *   metric: "Carbon Offset",
+ *   unit: "tons CO2e",
+ *   value: "150",
+ * };
+ * ```
+ */
+export type MeasurementParams = string | StrongRef | CreateMeasurementParams;