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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/CHANGELOG.md +73 -0
  2. package/README.md +178 -39
  3. package/dist/index.cjs +393 -268
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.ts +197 -149
  6. package/dist/index.mjs +393 -268
  7. package/dist/index.mjs.map +1 -1
  8. package/dist/types.d.ts +197 -148
  9. package/package.json +3 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,78 @@
1
1
  # @hypercerts-org/sdk-core
2
2
 
3
+ ## 0.10.0-beta.6
4
+
5
+ ### Minor Changes
6
+
7
+ - [#101](https://github.com/hypercerts-org/hypercerts-sdk/pull/101)
8
+ [`bf93b3c`](https://github.com/hypercerts-org/hypercerts-sdk/commit/bf93b3cf5d5eccb12de31c4fe6f95ed3676c746e) Thanks
9
+ [@aspiers](https://github.com/aspiers)! - feat: align collection/project types with lexicon + add inline location
10
+ support
11
+
12
+ This is a BREAKING change.
13
+
14
+ **Type Alignment with Lexicon:**
15
+ - Changed `createCollection` to use lexicon-aligned `items` array instead of `claims`
16
+ - Updated avatar/banner handling to use proper lexicon union types
17
+ - Simplified project methods to delegate to collection methods
18
+ - Added `CreateCollectionParams`, `UpdateCollectionParams`, and result types derived from lexicon
19
+ - Improved type safety by deriving SDK input types from lexicon definitions
20
+
21
+ **Inline Location Support:**
22
+
23
+ `AttachLocationParams` now supports three ways to specify location:
24
+ 1. **StrongRef** - Direct reference with uri and cid (no record creation)
25
+ 2. **AT-URI string** - Reference to existing location record
26
+ 3. **Location object** - Full location data to create a new location record
27
+
28
+ **Changes:**
29
+ - Add `AttachLocationParams` union type supporting StrongRef, string URI, or location object
30
+ - Add optional `location` field to `CreateCollectionParams`
31
+ - Add optional `location` field to `UpdateCollectionParams` (supports `null` to remove)
32
+ - Update `CreateCollectionResult` to include optional `locationUri` field
33
+ - Implement location handling in `createCollection()` - supports all three forms
34
+ - Add tests for collection creation with StrongRef, string URI, and location object
35
+
36
+ **Example Usage:**
37
+
38
+ ```typescript
39
+ // Create a project with location (StrongRef - direct reference)
40
+ const project = await repo.hypercerts.createProject({
41
+ title: "Climate Initiative",
42
+ items: [...],
43
+ location: { uri: "at://did:plc:alice/app.certified.location/abc", cid: "bafy..." },
44
+ });
45
+
46
+ // Create with location (AT-URI string - fetches CID)
47
+ const project2 = await repo.hypercerts.createProject({
48
+ title: "Forest Project",
49
+ items: [...],
50
+ location: "at://did:plc:bob/app.certified.location/xyz",
51
+ });
52
+
53
+ // Create with location (location object - creates new record)
54
+ const project3 = await repo.hypercerts.createProject({
55
+ title: "Ocean Project",
56
+ items: [...],
57
+ location: {
58
+ lpVersion: "1.0",
59
+ srs: "EPSG:4326",
60
+ locationType: "coordinate-decimal",
61
+ location: "37.7749, -122.4194",
62
+ },
63
+ });
64
+
65
+ // Update project to change location
66
+ await repo.hypercerts.updateProject(project.uri, {
67
+ location: "at://did:plc:alice/app.certified.location/new",
68
+ });
69
+
70
+ // Remove location
71
+ await repo.hypercerts.updateProject(project.uri, {
72
+ location: null,
73
+ });
74
+ ```
75
+
3
76
  ## 0.10.0-beta.5
4
77
 
5
78
  ### Minor Changes
package/README.md CHANGED
@@ -411,7 +411,130 @@ const measurement = await repo.hypercerts.addMeasurement({
411
411
  });
412
412
  ```
413
413
 
414
- ### 5. Blob Operations (Images & Files)
414
+ ### 5. Collections and Projects
415
+
416
+ Collections organize multiple hypercerts into logical groupings. Projects are a special type of collection with
417
+ `type="project"`.
418
+
419
+ #### Creating a Collection
420
+
421
+ ```typescript
422
+ // Create a collection with weighted items
423
+ const collection = await repo.hypercerts.createCollection({
424
+ title: "Climate Projects 2024",
425
+ shortDescription: "Our climate impact portfolio",
426
+ description: "A curated collection of climate-related hypercerts",
427
+ items: [
428
+ {
429
+ itemIdentifier: { uri: hypercert1Uri, cid: hypercert1Cid },
430
+ itemWeight: "0.5",
431
+ },
432
+ {
433
+ itemIdentifier: { uri: hypercert2Uri, cid: hypercert2Cid },
434
+ itemWeight: "0.3",
435
+ },
436
+ {
437
+ itemIdentifier: { uri: hypercert3Uri, cid: hypercert3Cid },
438
+ itemWeight: "0.2",
439
+ },
440
+ ],
441
+ avatar: avatarBlob, // optional
442
+ banner: bannerBlob, // optional
443
+ });
444
+
445
+ console.log("Created collection:", collection.uri);
446
+ ```
447
+
448
+ #### Creating a Project
449
+
450
+ Projects are collections with automatic `type="project"`:
451
+
452
+ ```typescript
453
+ const project = await repo.hypercerts.createProject({
454
+ title: "Rainforest Restoration",
455
+ shortDescription: "Multi-year restoration initiative",
456
+ description: "Comprehensive rainforest restoration project",
457
+ items: [
458
+ {
459
+ itemIdentifier: { uri: activity1Uri, cid: activity1Cid },
460
+ itemWeight: "0.6",
461
+ },
462
+ {
463
+ itemIdentifier: { uri: activity2Uri, cid: activity2Cid },
464
+ itemWeight: "0.4",
465
+ },
466
+ ],
467
+ });
468
+ ```
469
+
470
+ #### Attaching Locations
471
+
472
+ Both collections and projects can have location data attached as a sidecar record:
473
+
474
+ ```typescript
475
+ // Attach location to a project
476
+ const locationResult = await repo.hypercerts.attachLocationToProject(projectUri, {
477
+ lpVersion: "1.0",
478
+ srs: "EPSG:4326",
479
+ locationType: "coordinate-decimal",
480
+ location: "https://example.com/location.geojson", // or use a Blob
481
+ name: "Project Site",
482
+ description: "Main restoration site coordinates",
483
+ });
484
+
485
+ // Also works for collections
486
+ await repo.hypercerts.attachLocationToCollection(collectionUri, locationParams);
487
+ ```
488
+
489
+ #### Listing and Retrieving
490
+
491
+ ```typescript
492
+ // Get a specific collection
493
+ const collection = await repo.hypercerts.getCollection(collectionUri);
494
+
495
+ // List all collections
496
+ const { records } = await repo.hypercerts.listCollections();
497
+
498
+ // Get a specific project
499
+ const project = await repo.hypercerts.getProject(projectUri);
500
+
501
+ // List all projects
502
+ const { records } = await repo.hypercerts.listProjects();
503
+ ```
504
+
505
+ #### Updating Collections and Projects
506
+
507
+ ```typescript
508
+ // Update collection
509
+ await repo.hypercerts.updateCollection(collectionUri, {
510
+ title: "Updated Title",
511
+ items: [
512
+ /* updated items */
513
+ ],
514
+ avatar: newAvatarBlob, // or null to remove
515
+ });
516
+
517
+ // Update project (same API)
518
+ await repo.hypercerts.updateProject(projectUri, {
519
+ shortDescription: "Updated description",
520
+ banner: null, // removes banner
521
+ });
522
+ ```
523
+
524
+ #### Deleting
525
+
526
+ ```typescript
527
+ // Delete collection
528
+ await repo.hypercerts.deleteCollection(collectionUri);
529
+
530
+ // Delete project
531
+ await repo.hypercerts.deleteProject(projectUri);
532
+
533
+ // Remove location from project
534
+ await repo.hypercerts.removeLocationFromProject(projectUri);
535
+ ```
536
+
537
+ ### 6. Blob Operations (Images & Files)
415
538
 
416
539
  ```typescript
417
540
  // Upload an image or file
@@ -422,7 +545,7 @@ console.log("Blob uploaded:", blobResult.ref.$link);
422
545
  const blobData = await repo.blobs.get("did:plc:user123", "bafyreiabc123...");
423
546
  ```
424
547
 
425
- ### 6. Organizations (SDS only)
548
+ ### 7. Organizations (SDS only)
426
549
 
427
550
  Organizations allow multiple users to collaborate on shared repositories.
428
551
 
@@ -450,7 +573,7 @@ const org = await repo.organizations.get("did:plc:org123");
450
573
  console.log(`${org.name} - ${org.description}`);
451
574
  ```
452
575
 
453
- ### 7. Collaborator Management (SDS only)
576
+ ### 8. Collaborator Management (SDS only)
454
577
 
455
578
  Manage who has access to your repository and what they can do.
456
579
 
@@ -519,7 +642,7 @@ await repo.collaborators.transferOwnership({
519
642
  });
520
643
  ```
521
644
 
522
- ### 8. Generic Record Operations
645
+ ### 9. Generic Record Operations
523
646
 
524
647
  For working with any ATProto record type:
525
648
 
@@ -564,7 +687,7 @@ const { records, cursor } = await repo.records.list({
564
687
  });
565
688
  ```
566
689
 
567
- ### 9. Profile Management (PDS only)
690
+ ### 10. Profile Management (PDS only)
568
691
 
569
692
  ```typescript
570
693
  // Get user profile
@@ -584,40 +707,56 @@ await repo.profile.update({
584
707
 
585
708
  ### Repository Operations
586
709
 
587
- | Operation | Method | PDS | SDS | Returns |
588
- | ------------------ | ---------------------------------------- | --- | --- | ---------------------------- |
589
- | **Records** | | | | |
590
- | Create record | `repo.records.create()` | ✅ | ✅ | `{ uri, cid }` |
591
- | Get record | `repo.records.get()` | ✅ | ✅ | Record data |
592
- | Update record | `repo.records.update()` | ✅ | ✅ | `{ uri, cid }` |
593
- | Delete record | `repo.records.delete()` | ✅ | ✅ | void |
594
- | List records | `repo.records.list()` | ✅ | ✅ | `{ records, cursor? }` |
595
- | **Hypercerts** | | | | |
596
- | Create hypercert | `repo.hypercerts.create()` | ✅ | ✅ | `{ uri, cid, value }` |
597
- | Get hypercert | `repo.hypercerts.get()` | ✅ | ✅ | Full hypercert |
598
- | Update hypercert | `repo.hypercerts.update()` | ✅ | ✅ | `{ uri, cid }` |
599
- | Delete hypercert | `repo.hypercerts.delete()` | ✅ | ✅ | void |
600
- | List hypercerts | `repo.hypercerts.list()` | ✅ | ✅ | `{ records, cursor? }` |
601
- | Add contribution | `repo.hypercerts.addContribution()` | ✅ | ✅ | Contribution |
602
- | Add measurement | `repo.hypercerts.addMeasurement()` | ✅ | ✅ | Measurement |
603
- | **Blobs** | | | | |
604
- | Upload blob | `repo.blobs.upload()` | ✅ | ✅ | `{ ref, mimeType, size }` |
605
- | Get blob | `repo.blobs.get()` | ✅ | ✅ | Blob data |
606
- | **Profile** | | | | |
607
- | Get profile | `repo.profile.get()` | ✅ | ❌ | Profile data |
608
- | Update profile | `repo.profile.update()` | ✅ | ❌ | void |
609
- | **Organizations** | | | | |
610
- | Create org | `repo.organizations.create()` | ❌ | ✅ | `{ did, name, ... }` |
611
- | Get org | `repo.organizations.get()` | ❌ | ✅ | Organization |
612
- | List orgs | `repo.organizations.list()` | ❌ | ✅ | `{ organizations, cursor? }` |
613
- | **Collaborators** | | | | |
614
- | Grant access | `repo.collaborators.grant()` | ❌ | ✅ | void |
615
- | Revoke access | `repo.collaborators.revoke()` | ❌ | ✅ | void |
616
- | List collaborators | `repo.collaborators.list()` | ❌ | ✅ | `{ collaborators, cursor? }` |
617
- | Check access | `repo.collaborators.hasAccess()` | ❌ | ✅ | boolean |
618
- | Get role | `repo.collaborators.getRole()` | ❌ | ✅ | Role string |
619
- | Get permissions | `repo.collaborators.getPermissions()` | ❌ | ✅ | Permissions |
620
- | Transfer ownership | `repo.collaborators.transferOwnership()` | ❌ | ✅ | void |
710
+ | Operation | Method | PDS | SDS | Returns |
711
+ | ------------------ | ------------------------------------------------ | --- | --- | ---------------------------- |
712
+ | **Records** | | | | |
713
+ | Create record | `repo.records.create()` | ✅ | ✅ | `{ uri, cid }` |
714
+ | Get record | `repo.records.get()` | ✅ | ✅ | Record data |
715
+ | Update record | `repo.records.update()` | ✅ | ✅ | `{ uri, cid }` |
716
+ | Delete record | `repo.records.delete()` | ✅ | ✅ | void |
717
+ | List records | `repo.records.list()` | ✅ | ✅ | `{ records, cursor? }` |
718
+ | **Hypercerts** | | | | |
719
+ | Create hypercert | `repo.hypercerts.create()` | ✅ | ✅ | `{ uri, cid, value }` |
720
+ | Get hypercert | `repo.hypercerts.get()` | ✅ | ✅ | Full hypercert |
721
+ | Update hypercert | `repo.hypercerts.update()` | ✅ | ✅ | `{ uri, cid }` |
722
+ | Delete hypercert | `repo.hypercerts.delete()` | ✅ | ✅ | void |
723
+ | List hypercerts | `repo.hypercerts.list()` | ✅ | ✅ | `{ records, cursor? }` |
724
+ | Add contribution | `repo.hypercerts.addContribution()` | ✅ | ✅ | Contribution |
725
+ | Add measurement | `repo.hypercerts.addMeasurement()` | ✅ | ✅ | Measurement |
726
+ | **Collections** | | | | |
727
+ | Create collection | `repo.hypercerts.createCollection()` | ✅ | ✅ | `{ uri, cid, record }` |
728
+ | Get collection | `repo.hypercerts.getCollection()` | ✅ | ✅ | Collection data |
729
+ | List collections | `repo.hypercerts.listCollections()` | ✅ | ✅ | `{ records, cursor? }` |
730
+ | Update collection | `repo.hypercerts.updateCollection()` | ✅ | ✅ | `{ uri, cid }` |
731
+ | Delete collection | `repo.hypercerts.deleteCollection()` | ✅ | ✅ | void |
732
+ | Attach location | `repo.hypercerts.attachLocationToCollection()` | ✅ | ✅ | `{ uri, cid }` |
733
+ | Remove location | `repo.hypercerts.removeLocationFromCollection()` | ✅ | ✅ | void |
734
+ | **Projects** | | | | |
735
+ | Create project | `repo.hypercerts.createProject()` | ✅ | ✅ | `{ uri, cid, record }` |
736
+ | Get project | `repo.hypercerts.getProject()` | ✅ | ✅ | Project data |
737
+ | List projects | `repo.hypercerts.listProjects()` | ✅ | ✅ | `{ records, cursor? }` |
738
+ | Update project | `repo.hypercerts.updateProject()` | ✅ | ✅ | `{ uri, cid }` |
739
+ | Delete project | `repo.hypercerts.deleteProject()` | ✅ | ✅ | void |
740
+ | Attach location | `repo.hypercerts.attachLocationToProject()` | ✅ | ✅ | `{ uri, cid }` |
741
+ | Remove location | `repo.hypercerts.removeLocationFromProject()` | ✅ | ✅ | void |
742
+ | **Blobs** | | | | |
743
+ | Upload blob | `repo.blobs.upload()` | ✅ | ✅ | `{ ref, mimeType, size }` |
744
+ | Get blob | `repo.blobs.get()` | ✅ | ✅ | Blob data |
745
+ | **Profile** | | | | |
746
+ | Get profile | `repo.profile.get()` | ✅ | ❌ | Profile data |
747
+ | Update profile | `repo.profile.update()` | ✅ | ❌ | void |
748
+ | **Organizations** | | | | |
749
+ | Create org | `repo.organizations.create()` | ❌ | ✅ | `{ did, name, ... }` |
750
+ | Get org | `repo.organizations.get()` | ❌ | ✅ | Organization |
751
+ | List orgs | `repo.organizations.list()` | ❌ | ✅ | `{ organizations, cursor? }` |
752
+ | **Collaborators** | | | | |
753
+ | Grant access | `repo.collaborators.grant()` | ❌ | ✅ | void |
754
+ | Revoke access | `repo.collaborators.revoke()` | ❌ | ✅ | void |
755
+ | List collaborators | `repo.collaborators.list()` | ❌ | ✅ | `{ collaborators, cursor? }` |
756
+ | Check access | `repo.collaborators.hasAccess()` | ❌ | ✅ | boolean |
757
+ | Get role | `repo.collaborators.getRole()` | ❌ | ✅ | Role string |
758
+ | Get permissions | `repo.collaborators.getPermissions()` | ❌ | ✅ | Permissions |
759
+ | Transfer ownership | `repo.collaborators.transferOwnership()` | ❌ | ✅ | void |
621
760
 
622
761
  ## Type System
623
762