@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.
- package/CHANGELOG.md +73 -0
- package/README.md +178 -39
- package/dist/index.cjs +393 -268
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +197 -149
- package/dist/index.mjs +393 -268
- package/dist/index.mjs.map +1 -1
- package/dist/types.d.ts +197 -148
- 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.
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
|
588
|
-
| ------------------ |
|
|
589
|
-
| **Records** |
|
|
590
|
-
| Create record | `repo.records.create()`
|
|
591
|
-
| Get record | `repo.records.get()`
|
|
592
|
-
| Update record | `repo.records.update()`
|
|
593
|
-
| Delete record | `repo.records.delete()`
|
|
594
|
-
| List records | `repo.records.list()`
|
|
595
|
-
| **Hypercerts** |
|
|
596
|
-
| Create hypercert | `repo.hypercerts.create()`
|
|
597
|
-
| Get hypercert | `repo.hypercerts.get()`
|
|
598
|
-
| Update hypercert | `repo.hypercerts.update()`
|
|
599
|
-
| Delete hypercert | `repo.hypercerts.delete()`
|
|
600
|
-
| List hypercerts | `repo.hypercerts.list()`
|
|
601
|
-
| Add contribution | `repo.hypercerts.addContribution()`
|
|
602
|
-
| Add measurement | `repo.hypercerts.addMeasurement()`
|
|
603
|
-
| **
|
|
604
|
-
|
|
|
605
|
-
| Get
|
|
606
|
-
|
|
|
607
|
-
|
|
|
608
|
-
|
|
|
609
|
-
|
|
|
610
|
-
|
|
|
611
|
-
|
|
|
612
|
-
|
|
|
613
|
-
|
|
|
614
|
-
|
|
|
615
|
-
|
|
|
616
|
-
|
|
|
617
|
-
|
|
|
618
|
-
|
|
|
619
|
-
|
|
|
620
|
-
|
|
|
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
|
|