@hypercerts-org/sdk-core 0.7.0-beta.0 → 0.9.0-beta.0

package/README.md

@@ -33,11 +33,15 @@ const session = await sdk.callback(callbackParams);
 const repo = sdk.getRepository(session);
 const claim = await repo.hypercerts.create({
   title: "Tree Planting Initiative 2025",
-  description: "Planted 1000 trees in the rainforest",
-  impact: {
-    scope: ["Environmental Conservation"],
-    work: { from: "2025-01-01", to: "2025-12-31" },
-    contributors: ["did:plc:contributor1"],
+  shortDescription: "1000 trees planted in rainforest",
+  description: "Planted 1000 trees in the Amazon rainforest region",
+  workScope: "Environmental Conservation",
+  workTimeFrameFrom: "2025-01-01T00:00:00Z",
+  workTimeFrameTo: "2025-12-31T23:59:59Z",
+  rights: {
+    name: "Attribution",
+    type: "license",
+    description: "CC-BY-4.0",
   },
 });
 ```
@@ -607,21 +611,134 @@ await mockStore.set(mockSession);
 
 ### Working with Lexicons
 
+The SDK exports lexicon types and validation utilities from the `@hypercerts-org/lexicon` package for direct record manipulation and validation.
+
+#### Lexicon Types
+
+All lexicon types are available with proper TypeScript support:
+
+```typescript
+import type {
+  HypercertClaim,
+  HypercertRights,
+  HypercertContribution,
+  HypercertCollection,
+  HypercertMeasurement,
+  HypercertEvaluation,
+  HypercertLocation,
+  StrongRef,
+} from "@hypercerts-org/sdk-core";
+
+// Create a properly typed hypercert claim
+const claim: HypercertClaim = {
+  $type: "org.hypercerts.claim",
+  title: "Community Garden Project",
+  shortDescription: "Urban garden serving 50 families", // REQUIRED
+  description: "Detailed description...",
+  workScope: "Food Security",
+  workTimeFrameFrom: "2024-01-01T00:00:00Z",  // Note: Capital 'F'
+  workTimeFrameTo: "2024-12-31T00:00:00Z",    // Note: Capital 'F'
+  rights: { uri: "at://...", cid: "..." },
+  createdAt: new Date().toISOString(),
+};
+```
+
+#### Validation
+
+Validate records before creating them:
+
+```typescript
+import {
+  validate,
+  OrgHypercertsClaim,
+  HYPERCERT_COLLECTIONS,
+} from "@hypercerts-org/sdk-core";
+
+// Validate using the lexicon package
+const validation = validate(
+  HYPERCERT_COLLECTIONS.CLAIM,  // "org.hypercerts.claim"
+  claim
+);
+
+if (!validation.valid) {
+  console.error("Validation failed:", validation.error);
+}
+
+// Or use type-specific validators
+const isValid = OrgHypercertsClaim.isMain(claim);
+const validationResult = OrgHypercertsClaim.validateMain(claim);
+```
+
+#### Using LexiconRegistry
+
+For repository-level validation:
+
 ```typescript
 import {
   LexiconRegistry,
   HYPERCERT_LEXICONS,
   HYPERCERT_COLLECTIONS,
-} from "@hypercerts-org/sdk-core/lexicons";
+} from "@hypercerts-org/sdk-core";
 
 const registry = new LexiconRegistry();
 registry.registerLexicons(HYPERCERT_LEXICONS);
 
 // Validate a record
-const isValid = registry.validate(
-  "org.hypercerts.claim",
+const result = registry.validate(
+  HYPERCERT_COLLECTIONS.CLAIM,
   claimData
 );
+
+if (!result.valid) {
+  console.error("Invalid record:", result.error);
+}
+```
+
+#### Creating Records with Proper Types
+
+```typescript
+import type {
+  HypercertContribution,
+  StrongRef,
+} from "@hypercerts-org/sdk-core";
+import { HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk-core";
+
+// Create a contribution record
+const contribution: HypercertContribution = {
+  $type: HYPERCERT_COLLECTIONS.CONTRIBUTION,
+  hypercert: {
+    uri: "at://did:plc:abc/org.hypercerts.claim/xyz",
+    cid: "bafyrei...",
+  } as StrongRef,
+  contributors: ["did:plc:contributor1", "did:plc:contributor2"],
+  role: "implementer",
+  description: "On-ground implementation team",
+  workTimeframeFrom: "2024-01-01T00:00:00Z",  // Note: lowercase 'f' for contributions
+  workTimeframeTo: "2024-06-30T00:00:00Z",    // Note: lowercase 'f' for contributions
+  createdAt: new Date().toISOString(),
+};
+
+// Use with repository operations
+await repo.records.create({
+  collection: HYPERCERT_COLLECTIONS.CONTRIBUTION,
+  record: contribution,
+});
+```
+
+#### Available Lexicon Collections
+
+```typescript
+import { HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk-core";
+
+// Collection NSIDs
+HYPERCERT_COLLECTIONS.CLAIM           // "org.hypercerts.claim"
+HYPERCERT_COLLECTIONS.RIGHTS          // "org.hypercerts.claim.rights"
+HYPERCERT_COLLECTIONS.CONTRIBUTION    // "org.hypercerts.claim.contribution"
+HYPERCERT_COLLECTIONS.MEASUREMENT     // "org.hypercerts.claim.measurement"
+HYPERCERT_COLLECTIONS.EVALUATION      // "org.hypercerts.claim.evaluation"
+HYPERCERT_COLLECTIONS.EVIDENCE        // "org.hypercerts.claim.evidence"
+HYPERCERT_COLLECTIONS.COLLECTION      // "org.hypercerts.collection"
+HYPERCERT_COLLECTIONS.LOCATION        // "app.certified.location"
 ```
 
 ## Development

package/dist/index.cjs

@@ -2270,6 +2270,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             // Step 2: Create rights record
             this.emitProgress(params.onProgress, { name: "createRights", status: "start" });
             const rightsRecord = {
+                $type: lexicon.HYPERCERT_COLLECTIONS.RIGHTS,
                 rightsName: params.rights.name,
                 rightsType: params.rights.type,
                 rightsDescription: params.rights.description,
@@ -2298,17 +2299,16 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             // Step 3: Create hypercert record
             this.emitProgress(params.onProgress, { name: "createHypercert", status: "start" });
             const hypercertRecord = {
+                $type: lexicon.HYPERCERT_COLLECTIONS.CLAIM,
                 title: params.title,
+                shortDescription: params.shortDescription,
                 description: params.description,
                 workScope: params.workScope,
-                workTimeframeFrom: params.workTimeframeFrom,
-                workTimeframeTo: params.workTimeframeTo,
+                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;
             }
@@ -2645,6 +2645,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      * await repo.hypercerts.attachLocation(hypercertUri, {
      *   value: "San Francisco, CA",
      *   name: "SF Bay Area",
+     *   srs: "EPSG:4326",
      * });
      * ```
      *
@@ -2663,32 +2664,54 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async attachLocation(hypercertUri, location) {
         try {
-            // Get hypercert to get CID
-            const hypercert = await this.get(hypercertUri);
+            // Validate required srs field
+            if (!location.srs) {
+                throw new ValidationError("srs (Spatial Reference System) is required. Example: 'EPSG:4326' for WGS84 coordinates, or 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' for CRS84.");
+            }
+            // Validate that hypercert exists (unused but confirms hypercert is valid)
+            await this.get(hypercertUri);
             const createdAt = new Date().toISOString();
-            let locationValue = location.value;
+            // Determine location type and prepare location data
+            let locationData;
+            let locationType;
             if (location.geojson) {
+                // Upload GeoJSON as a blob
                 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 = {
+                    locationData = {
                         $type: "blob",
                         ref: { $link: uploadResult.data.blob.ref.toString() },
                         mimeType: uploadResult.data.blob.mimeType,
                         size: uploadResult.data.blob.size,
                     };
+                    locationType = "geojson-point";
+                }
+                else {
+                    throw new NetworkError("Failed to upload GeoJSON blob");
                 }
             }
+            else {
+                // Use value as a URI reference
+                locationData = {
+                    $type: "app.certified.defs#uri",
+                    uri: location.value,
+                };
+                locationType = "coordinate-decimal";
+            }
+            // Build location record according to app.certified.location lexicon
             const locationRecord = {
-                hypercert: { uri: hypercert.uri, cid: hypercert.cid },
-                value: locationValue,
+                $type: lexicon.HYPERCERT_COLLECTIONS.LOCATION,
+                lpVersion: "1.0",
+                srs: location.srs,
+                locationType,
+                location: locationData,
                 createdAt,
                 name: location.name,
                 description: location.description,
-                srs: location.srs,
             };
             const validation = this.lexiconRegistry.validate(lexicon.HYPERCERT_COLLECTIONS.LOCATION, locationRecord);
             if (!validation.valid) {
@@ -2775,10 +2798,12 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
         try {
             const createdAt = new Date().toISOString();
             const contributionRecord = {
+                $type: lexicon.HYPERCERT_COLLECTIONS.CONTRIBUTION,
                 contributors: params.contributors,
                 role: params.role,
                 createdAt,
                 description: params.description,
+                hypercert: { uri: "", cid: "" }, // Will be set below if hypercertUri provided
             };
             if (params.hypercertUri) {
                 const hypercert = await this.get(params.hypercertUri);
@@ -2839,6 +2864,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             const hypercert = await this.get(params.hypercertUri);
             const createdAt = new Date().toISOString();
             const measurementRecord = {
+                $type: lexicon.HYPERCERT_COLLECTIONS.MEASUREMENT,
                 hypercert: { uri: hypercert.uri, cid: hypercert.cid },
                 measurers: params.measurers,
                 metric: params.metric,
@@ -2894,6 +2920,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             const subject = await this.get(params.subjectUri);
             const createdAt = new Date().toISOString();
             const evaluationRecord = {
+                $type: lexicon.HYPERCERT_COLLECTIONS.EVALUATION,
                 subject: { uri: subject.uri, cid: subject.cid },
                 evaluators: params.evaluators,
                 summary: params.summary,
@@ -2968,6 +2995,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
                 }
             }
             const collectionRecord = {
+                $type: lexicon.HYPERCERT_COLLECTIONS.COLLECTION,
                 title: params.title,
                 claims: params.claims.map((c) => ({ claim: { uri: c.uri, cid: c.cid }, weight: c.weight })),
                 createdAt,