@hypercerts-org/sdk-core 0.10.0-beta.0 → 0.10.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,273 @@
+# @hypercerts-org/sdk-core
+
+## 1.0.0-beta.0
+
+### Major Changes
+
+- [#66](https://github.com/hypercerts-org/hypercerts-sdk/pull/66)
+  [`7c33673`](https://github.com/hypercerts-org/hypercerts-sdk/commit/7c33673fd5f53d92ba160ced1d1582178fa7c455) Thanks
+  [@aspiers](https://github.com/aspiers)! - feat: migrate to published @hypercerts-org/lexicon package
+
+  This release migrates the SDK from using a local `packages/lexicon` workspace to consuming the published
+  `@hypercerts-org/lexicon` package from npm.
+
+  **Benefits:**
+  - **Single source of truth**: Lexicon definitions now come from a dedicated, independently versioned package
+  - **Reduced codebase**: Removes ~3,000 lines of duplicated lexicon code from this repository
+  - **Better versioning**: Lexicon can be updated independently via semver dependency updates
+  - **Simplified architecture**: No longer maintaining duplicate lexicon tooling in monorepo
+  - **Improved maintainability**: Clearer separation of concerns between SDK and lexicon definitions
+
+  **Breaking Changes:**
+  1. **Removed `LexiconRegistry` class**: Use the `validate()` function instead
+  2. **Removed `ValidationResult` type**: Validation functions now throw errors on validation failure
+  3. **Renamed type exports** to match lexicon package conventions:
+     - `OrgHypercertsClaim` → `OrgHypercertsClaimActivity`
+     - `OrgHypercertsCollection` → `OrgHypercertsClaimCollection`
+  4. **Renamed constant exports** to use consistent naming:
+     - `schemas` → `HYPERCERTS_SCHEMAS`
+     - `schemaDict` → `HYPERCERTS_SCHEMA_DICT`
+     - `ids` → `HYPERCERTS_NSIDS`
+     - `lexicons` now exported as type-only (use `HYPERCERTS_LEXICON_JSON` or `HYPERCERTS_LEXICON_DOC` for runtime
+       values)
+
+  **Migration Guide:**
+
+  **Validation:**
+
+  ```typescript
+  // Before
+  import { LexiconRegistry, HYPERCERT_LEXICONS, HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk-core";
+  const registry = new LexiconRegistry();
+  registry.registerLexicons(HYPERCERT_LEXICONS);
+  const result = registry.validate(HYPERCERT_COLLECTIONS.CLAIM, claimData);
+  if (!result.valid) {
+    console.error("Invalid record:", result.error);
+  }
+
+  // After
+  import { validate, HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk-core";
+  try {
+    validate(HYPERCERT_COLLECTIONS.CLAIM, claimData);
+  } catch (error) {
+    console.error("Invalid record:", error);
+  }
+  ```
+
+  **Type imports:**
+
+  ```typescript
+  // Before
+  import { OrgHypercertsClaim, OrgHypercertsCollection } from "@hypercerts-org/sdk-core";
+
+  // After
+  import { OrgHypercertsClaimActivity, OrgHypercertsClaimCollection } from "@hypercerts-org/sdk-core";
+  ```
+
+  **Constant imports:**
+
+  ```typescript
+  // Before
+  import { schemas, schemaDict, ids } from "@hypercerts-org/sdk-core";
+
+  // After
+  import { HYPERCERTS_SCHEMAS, HYPERCERTS_SCHEMA_DICT, HYPERCERTS_NSIDS } from "@hypercerts-org/sdk-core";
+  ```
+
+  **Other Changes:**
+  - Added dependency on `@hypercerts-org/lexicon@0.10.0-beta.3`
+  - Updated all lexicon type exports to use namespaced imports from lexicon package
+  - Improved hypercert validation with new test coverage
+  - Enhanced test mocks and fixtures for better testability
+
+  **For SDK users**: If you're using `LexiconRegistry`, follow the migration guide above. If you're only using the
+  high-level Repository API, no changes are required.
+
+### Minor Changes
+
+- [#60](https://github.com/hypercerts-org/hypercerts-sdk/pull/60)
+  [`f7594f8`](https://github.com/hypercerts-org/hypercerts-sdk/commit/f7594f838fd7e64837da702f7498e84a49b28bf5) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Implement ConfigurableAgent for proper multi-server routing
+
+  This release introduces the `ConfigurableAgent` class that enables proper routing of AT Protocol requests to different
+  servers (PDS, SDS, or custom instances) while maintaining OAuth authentication from a single session.
+
+  **Breaking Changes:**
+  - Repository now uses `ConfigurableAgent` internally instead of standard `Agent`
+  - This fixes the issue where invalid `agent.service` and `agent.api.xrpc.uri` property assignments were causing
+    TypeScript errors
+
+  **New Features:**
+  - `ConfigurableAgent` class exported from `@hypercerts-org/sdk-core`
+  - Support for simultaneous connections to multiple SDS instances with one OAuth session
+  - Proper request routing based on configured service URL rather than session defaults
+
+  **Bug Fixes:**
+  - Remove invalid Agent property assignments that caused TypeScript compilation errors (TS2339)
+  - Replace all `any` types in test files with proper type annotations
+  - Eliminate build warnings from missing type declarations
+
+  **Architecture:** The new routing system wraps the OAuth session's fetch handler to prepend the target server URL,
+  ensuring requests go to the intended destination while maintaining full authentication (DPoP, access tokens, etc.).
+  This enables use cases like:
+  - Routing to SDS while authenticated via PDS
+  - Accessing multiple organization SDS instances simultaneously
+  - Testing against different server environments
+  - Dynamic switching between PDS and SDS operations
+
+  **Migration:** No action required - the change is transparent to existing code. The Repository API remains unchanged.
+
+- [#46](https://github.com/hypercerts-org/hypercerts-sdk/pull/46)
+  [`eda4ac2`](https://github.com/hypercerts-org/hypercerts-sdk/commit/eda4ac233e09764d83f042ba7df94d4c9884cc01) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Initial release of sdk-core package with ATProto SDK for
+  authentication, repository operations, and lexicon management
+
+- [#65](https://github.com/hypercerts-org/hypercerts-sdk/pull/65)
+  [`826b50c`](https://github.com/hypercerts-org/hypercerts-sdk/commit/826b50c140a56fee4feeb6b6c83d1123e44c5118) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - feat(auth): add OAuth scopes and granular permissions system
+
+  Add comprehensive OAuth permissions system with support for granular permissions and easy email access:
+
+  **Permission System**
+  - Zod schemas for all ATProto permission types (account, repo, blob, rpc, identity, include)
+  - Support for both transitional (legacy) and granular permission models
+  - Type-safe permission builder with fluent API
+  - 14 pre-built scope presets (EMAIL_READ, POSTING_APP, FULL_ACCESS, etc.)
+  - 8 utility functions for working with scopes
+
+  **Email Access**
+  - New `getAccountEmail()` method to retrieve user email from authenticated session
+  - Returns null when permission not granted
+  - Comprehensive error handling
+
+  **Enhanced OAuth Integration**
+  - Automatic scope validation with helpful warnings
+  - Migration suggestions from transitional to granular permissions
+  - Improved documentation with comprehensive examples
+
+  **Breaking Changes**: None - fully backward compatible
+
+  **New Exports**:
+  - `PermissionBuilder` - Fluent API for building type-safe scopes
+  - `ScopePresets` - 14 ready-to-use permission presets
+  - Utility functions: `buildScope()`, `parseScope()`, `hasPermission()`, `validateScope()`, etc.
+  - Permission schemas and types for TypeScript consumers
+
+  See README for usage examples and migration guide.
+
+- [#56](https://github.com/hypercerts-org/hypercerts-sdk/pull/56)
+  [`caceacb`](https://github.com/hypercerts-org/hypercerts-sdk/commit/caceacbc5572a590c750a95ccfda23fff2dd0c61) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Add pagination support and fix React hooks for SDS operations
+
+  **Breaking Changes (sdk-core):**
+  - `CollaboratorOperations.list()` now returns `{ collaborators: RepositoryAccessGrant[], cursor?: string }` instead of
+    `RepositoryAccessGrant[]`
+  - `OrganizationOperations.list()` now returns `{ organizations: OrganizationInfo[], cursor?: string }` instead of
+    `OrganizationInfo[]`
+
+  **Features:**
+  - Add cursor-based pagination support to collaborator and organization list operations
+  - Support optional `limit` and `cursor` parameters for paginated queries
+  - Update internal methods (`hasAccess`, `getRole`, `get`) to handle new pagination structure
+
+  **Bug Fixes (sdk-core):**
+  - Fix permissions parsing in `CollaboratorOperationsImpl.list()` to match actual SDS API format (object with boolean
+    flags)
+  - Prevent `TypeError: permissionArray.includes is not a function` by correctly handling permissions as objects
+  - Fix Agent service URL configuration to route queries to the correct server (PDS or SDS)
+  - Resolve "Could not find repo" errors when querying SDS repositories by ensuring Agent uses SDS service endpoint
+  - Update test mocks to use the actual SDS API response format
+
+  **Bug Fixes (sdk-react):**
+  - Fix `useCollaborators` hook to correctly destructure paginated response
+  - Fix `useOrganizations` hook to correctly destructure paginated response
+  - All React hooks now properly handle the new pagination structure
+
+  **Documentation:**
+  - Comprehensive README updates with clear examples for all SDK operations
+  - Added pagination examples throughout documentation
+  - Improved code samples with realistic use cases
+
+  **Tests:**
+  - All 317 tests passing (181 sdk-core + 136 sdk-react)
+  - Updated test mocks to match new pagination response structure
+  - Build completes with zero warnings
+
+### Patch Changes
+
+- [#58](https://github.com/hypercerts-org/hypercerts-sdk/pull/58)
+  [`bcde5fa`](https://github.com/hypercerts-org/hypercerts-sdk/commit/bcde5faeb11dba6d99967a434e8ec32d67b3aca5) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Fix collaborator permissions parsing to align with SDS API response
+  format. The SDS API returns permissions as objects with boolean flags (`{ read: true, create: true, ... }`) rather
+  than string arrays. This fix simplifies the permissions parser to handle only the actual format returned by the API.
+
+- [#64](https://github.com/hypercerts-org/hypercerts-sdk/pull/64)
+  [`f83f03a`](https://github.com/hypercerts-org/hypercerts-sdk/commit/f83f03a8e505d57d38b45f3a50213ca1035c1229) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - fix(lexicon): correct field names and types to match lexicon schema
+  - Fix `workTimeframeFrom/To` -> `workTimeFrameFrom/To` (capital 'F' in Frame)
+  - Make `shortDescription` required for hypercert claims per lexicon schema
+  - Update all interfaces, implementations, and tests to use correct field names
+  - Add comprehensive lexicon documentation to README
+
+- [#62](https://github.com/hypercerts-org/hypercerts-sdk/pull/62)
+  [`4b80edc`](https://github.com/hypercerts-org/hypercerts-sdk/commit/4b80edca4162c4ce929edb28ffffa3f99f21cb74) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - fix(sdk-core): add required $type field to all record creation
+  operations
+
+  The AT Protocol requires all records to include a `$type` field, but the SDK was omitting it during record creation,
+  causing validation errors like "Record/$type must be a string". This fix:
+  - Adds `$type` field to all record types (rights, claims, locations, contributions, measurements, evaluations,
+    collections)
+  - Fixes location record implementation to match `app.certified.location` lexicon schema
+  - Makes `srs` (Spatial Reference System) field required for location records with proper validation
+  - Updates interfaces and documentation to reflect required fields
+
+  Breaking change: `location.srs` is now required when creating locations (use "EPSG:4326" for standard WGS84
+  coordinates).
+
+- [#59](https://github.com/hypercerts-org/hypercerts-sdk/pull/59)
+  [`7020fcc`](https://github.com/hypercerts-org/hypercerts-sdk/commit/7020fcc9845a4d4c2f792536611fc3bb5e3c4fe3) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Configure npm publishing to exclude source code and development files.
+  Packages now only include the compiled `dist/` folder, README, and necessary runtime files (lexicon schemas). This
+  reduces package sizes and prevents unnecessary files from being published to npm.
+
+- [#60](https://github.com/hypercerts-org/hypercerts-sdk/pull/60)
+  [`39accd9`](https://github.com/hypercerts-org/hypercerts-sdk/commit/39accd954422c901b7faf93e08be88e68a4f849a) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - fix(sdk-core): ensure repository operations route to correct server
+  (PDS/SDS)
+
+  **Problem:** When using OAuth authentication to access organization repositories on SDS via
+  `repo.repo(organizationDid)`, all operations like `hypercerts.list()` and `hypercerts.listCollections()` were
+  incorrectly routing to the user's PDS instead of the SDS server, causing "Could not find repo" errors.
+
+  **Root Cause:** The AT Protocol Agent was created from the OAuth session but only had its `api.xrpc.uri` property
+  configured. Without setting the Agent's `service` property, it continued using the session's default PDS URL for all
+  requests, even when switched to organization repositories.
+
+  **Solution:** Set both `agent.service` and `agent.api.xrpc.uri` to the specified server URL in the Repository
+  constructor. This ensures that:
+  - Initial repository creation routes to the correct server (PDS or SDS)
+  - Repository switching via `.repo(did)` maintains the same server routing
+  - All operation implementations (HypercertOperationsImpl, RecordOperationsImpl, ProfileOperationsImpl,
+    BlobOperationsImpl) now route correctly
+
+  **Documentation:** Added comprehensive PDS/SDS orchestration explanation to README covering:
+  - Server type comparison and use cases
+  - How repository routing works internally
+  - Common patterns for personal vs organization hypercerts
+  - Key implementation details about Agent configuration
+
+- [#56](https://github.com/hypercerts-org/hypercerts-sdk/pull/56)
+  [`cb3268d`](https://github.com/hypercerts-org/hypercerts-sdk/commit/cb3268d78614efaf15aecc57a5dc3bce8313f3ca) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Fix SDS organization and collaborator operations to match API
+  contracts
+  - Add required creatorDid parameter to organization.create endpoint
+  - Fix organization.list to parse organizations field instead of repositories
+  - Update accessType values to match SDS API: owner|shared|none (was owner|collaborator)
+  - Add permission string array parser for collaborator.list endpoint
+  - Update type definitions to match actual SDS API response formats
+
+- [#55](https://github.com/hypercerts-org/hypercerts-sdk/pull/55)
+  [`23c3d9a`](https://github.com/hypercerts-org/hypercerts-sdk/commit/23c3d9a3b71f326df68b65420c83f7ae42c2432d) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Fix endpoints and NSIDs for SDS operations in CollaboratorOperations
+  and OrganizationOperations

package/README.md

@@ -53,12 +53,14 @@ const claim = await repo.hypercerts.create({
 The SDK supports two types of AT Protocol servers:
 
 #### Personal Data Server (PDS)
+
 - **Purpose**: User's own data storage (e.g., Bluesky)
 - **Use case**: Individual hypercerts, personal records
 - **Features**: Profile management, basic CRUD operations
 - **Example**: `bsky.social`, any Bluesky PDS
 
 #### Shared Data Server (SDS)
+
 - **Purpose**: Collaborative data storage with access control
 - **Use case**: Organization hypercerts, team collaboration
 - **Features**: Organizations, multi-user access, role-based permissions
@@ -84,25 +86,27 @@ await orgRepo.hypercerts.list(); // Queries organization's hypercerts on SDS
 The SDK uses a `ConfigurableAgent` to route requests to different servers while maintaining your OAuth authentication:
 
 1. **Initial Repository Creation**
+
    ```typescript
    // User authenticates (OAuth session knows user's PDS)
    const session = await sdk.callback(params);
-   
+
    // Create PDS repository - routes to user's PDS
    const pdsRepo = sdk.repository(session);
-   
+
    // Create SDS repository - routes to SDS server
    const sdsRepo = sdk.repository(session, { server: "sds" });
    ```
 
 2. **Switching Repositories with `.repo()`**
+
    ```typescript
    // Start with user's SDS repository
    const userSdsRepo = sdk.repository(session, { server: "sds" });
-   
+
    // Switch to organization's repository
    const orgRepo = userSdsRepo.repo("did:plc:org-did");
-   
+
    // All operations on orgRepo still route to SDS, not user's PDS
    await orgRepo.hypercerts.list(); // ✅ Queries SDS
    await orgRepo.collaborators.list(); // ✅ Queries SDS
@@ -171,33 +175,34 @@ const repo = sdk.getRepository(session);
 Control exactly what your app can access using type-safe permission builders:
 
 ```typescript
-import { PermissionBuilder, ScopePresets, buildScope } from '@hypercerts-org/sdk-core';
+import { PermissionBuilder, ScopePresets, buildScope } from "@hypercerts-org/sdk-core";
 
 // Use ready-made presets
-const scope = ScopePresets.EMAIL_AND_PROFILE;  // Request email + profile access
-const scope = ScopePresets.POSTING_APP;        // Full posting capabilities
+const scope = ScopePresets.EMAIL_AND_PROFILE; // Request email + profile access
+const scope = ScopePresets.POSTING_APP; // Full posting capabilities
 
 // Or build custom permissions
 const scope = buildScope(
   new PermissionBuilder()
-    .accountEmail('read')                      // Read user's email
-    .repoWrite('app.bsky.feed.post')          // Create/update posts
-    .blob(['image/*', 'video/*'])             // Upload media
-    .build()
+    .accountEmail("read") // Read user's email
+    .repoWrite("app.bsky.feed.post") // Create/update posts
+    .blob(["image/*", "video/*"]) // Upload media
+    .build(),
 );
 
 // Use in OAuth configuration
 const sdk = createATProtoSDK({
   oauth: {
-    clientId: 'your-client-id',
-    redirectUri: 'https://your-app.com/callback',
-    scope: scope,  // Your custom scope
+    clientId: "your-client-id",
+    redirectUri: "https://your-app.com/callback",
+    scope: scope, // Your custom scope
     // ... other config
-  }
+  },
 });
 ```
 
 **Available Presets:**
+
 - `EMAIL_READ` - User's email address
 - `PROFILE_READ` / `PROFILE_WRITE` - Profile access
 - `POST_WRITE` - Create posts
@@ -218,7 +223,7 @@ const hypercert = await repo.hypercerts.create({
   description: "Research on carbon capture technologies",
   image: imageBlob, // optional: File or Blob
   externalUrl: "https://example.com/project",
-  
+
   impact: {
     scope: ["Climate Change", "Carbon Capture"],
     work: {
@@ -227,7 +232,7 @@ const hypercert = await repo.hypercerts.create({
     },
     contributors: ["did:plc:researcher1", "did:plc:researcher2"],
   },
-  
+
   rights: {
     license: "CC-BY-4.0",
     allowsDerivatives: true,
@@ -242,9 +247,7 @@ console.log("Created hypercert:", hypercert.uri);
 
 ```typescript
 // Get a specific hypercert by URI
-const hypercert = await repo.hypercerts.get(
-  "at://did:plc:user123/org.hypercerts.claim/abc123"
-);
+const hypercert = await repo.hypercerts.get("at://did:plc:user123/org.hypercerts.claim/abc123");
 
 // List all hypercerts in the repository
 const { records } = await repo.hypercerts.list();
@@ -263,26 +266,21 @@ if (cursor) {
 
 ```typescript
 // Update an existing hypercert
-await repo.hypercerts.update(
-  "at://did:plc:user123/org.hypercerts.claim/abc123",
-  {
-    title: "Updated Climate Research Project",
-    description: "Expanded scope to include renewable energy",
-    impact: {
-      scope: ["Climate Change", "Carbon Capture", "Renewable Energy"],
-      work: { from: "2024-01-01", to: "2026-12-31" },
-      contributors: ["did:plc:researcher1", "did:plc:researcher2"],
-    },
-  }
-);
+await repo.hypercerts.update("at://did:plc:user123/org.hypercerts.claim/abc123", {
+  title: "Updated Climate Research Project",
+  description: "Expanded scope to include renewable energy",
+  impact: {
+    scope: ["Climate Change", "Carbon Capture", "Renewable Energy"],
+    work: { from: "2024-01-01", to: "2026-12-31" },
+    contributors: ["did:plc:researcher1", "did:plc:researcher2"],
+  },
+});
 ```
 
 #### Deleting a Hypercert
 
 ```typescript
-await repo.hypercerts.delete(
-  "at://did:plc:user123/org.hypercerts.claim/abc123"
-);
+await repo.hypercerts.delete("at://did:plc:user123/org.hypercerts.claim/abc123");
 ```
 
 ### 4. Contributions and Measurements
@@ -323,10 +321,7 @@ const blobResult = await repo.blobs.upload(imageFile);
 console.log("Blob uploaded:", blobResult.ref.$link);
 
 // Download a blob
-const blobData = await repo.blobs.get(
-  "did:plc:user123",
-  "bafyreiabc123..."
-);
+const blobData = await repo.blobs.get("did:plc:user123", "bafyreiabc123...");
 ```
 
 ### 6. Organizations (SDS only)
@@ -491,40 +486,40 @@ await repo.profile.update({
 
 ### Repository Operations
 
-| Operation | Method | PDS | SDS | Returns |
-|-----------|--------|-----|-----|---------|
-| **Records** | | | | |
-| Create record | `repo.records.create()` | ✅ | ✅ | `{ uri, cid }` |
-| Get record | `repo.records.get()` | ✅ | ✅ | Record data |
-| Update record | `repo.records.update()` | ✅ | ✅ | `{ uri, cid }` |
-| Delete record | `repo.records.delete()` | ✅ | ✅ | void |
-| List records | `repo.records.list()` | ✅ | ✅ | `{ records, cursor? }` |
-| **Hypercerts** | | | | |
-| Create hypercert | `repo.hypercerts.create()` | ✅ | ✅ | `{ uri, cid, value }` |
-| Get hypercert | `repo.hypercerts.get()` | ✅ | ✅ | Full hypercert |
-| Update hypercert | `repo.hypercerts.update()` | ✅ | ✅ | `{ uri, cid }` |
-| Delete hypercert | `repo.hypercerts.delete()` | ✅ | ✅ | void |
-| List hypercerts | `repo.hypercerts.list()` | ✅ | ✅ | `{ records, cursor? }` |
-| Add contribution | `repo.hypercerts.addContribution()` | ✅ | ✅ | Contribution |
-| Add measurement | `repo.hypercerts.addMeasurement()` | ✅ | ✅ | Measurement |
-| **Blobs** | | | | |
-| Upload blob | `repo.blobs.upload()` | ✅ | ✅ | `{ ref, mimeType, size }` |
-| Get blob | `repo.blobs.get()` | ✅ | ✅ | Blob data |
-| **Profile** | | | | |
-| Get profile | `repo.profile.get()` | ✅ | ❌ | Profile data |
-| Update profile | `repo.profile.update()` | ✅ | ❌ | void |
-| **Organizations** | | | | |
-| Create org | `repo.organizations.create()` | ❌ | ✅ | `{ did, name, ... }` |
-| Get org | `repo.organizations.get()` | ❌ | ✅ | Organization |
-| List orgs | `repo.organizations.list()` | ❌ | ✅ | `{ organizations, cursor? }` |
-| **Collaborators** | | | | |
-| Grant access | `repo.collaborators.grant()` | ❌ | ✅ | void |
-| Revoke access | `repo.collaborators.revoke()` | ❌ | ✅ | void |
-| List collaborators | `repo.collaborators.list()` | ❌ | ✅ | `{ collaborators, cursor? }` |
-| Check access | `repo.collaborators.hasAccess()` | ❌ | ✅ | boolean |
-| Get role | `repo.collaborators.getRole()` | ❌ | ✅ | Role string |
-| Get permissions | `repo.collaborators.getPermissions()` | ❌ | ✅ | Permissions |
-| Transfer ownership | `repo.collaborators.transferOwnership()` | ❌ | ✅ | void |
+| Operation          | Method                                   | PDS | SDS | Returns                      |
+| ------------------ | ---------------------------------------- | --- | --- | ---------------------------- |
+| **Records**        |                                          |     |     |                              |
+| Create record      | `repo.records.create()`                  | ✅  | ✅  | `{ uri, cid }`               |
+| Get record         | `repo.records.get()`                     | ✅  | ✅  | Record data                  |
+| Update record      | `repo.records.update()`                  | ✅  | ✅  | `{ uri, cid }`               |
+| Delete record      | `repo.records.delete()`                  | ✅  | ✅  | void                         |
+| List records       | `repo.records.list()`                    | ✅  | ✅  | `{ records, cursor? }`       |
+| **Hypercerts**     |                                          |     |     |                              |
+| Create hypercert   | `repo.hypercerts.create()`               | ✅  | ✅  | `{ uri, cid, value }`        |
+| Get hypercert      | `repo.hypercerts.get()`                  | ✅  | ✅  | Full hypercert               |
+| Update hypercert   | `repo.hypercerts.update()`               | ✅  | ✅  | `{ uri, cid }`               |
+| Delete hypercert   | `repo.hypercerts.delete()`               | ✅  | ✅  | void                         |
+| List hypercerts    | `repo.hypercerts.list()`                 | ✅  | ✅  | `{ records, cursor? }`       |
+| Add contribution   | `repo.hypercerts.addContribution()`      | ✅  | ✅  | Contribution                 |
+| Add measurement    | `repo.hypercerts.addMeasurement()`       | ✅  | ✅  | Measurement                  |
+| **Blobs**          |                                          |     |     |                              |
+| Upload blob        | `repo.blobs.upload()`                    | ✅  | ✅  | `{ ref, mimeType, size }`    |
+| Get blob           | `repo.blobs.get()`                       | ✅  | ✅  | Blob data                    |
+| **Profile**        |                                          |     |     |                              |
+| Get profile        | `repo.profile.get()`                     | ✅  | ❌  | Profile data                 |
+| Update profile     | `repo.profile.update()`                  | ✅  | ❌  | void                         |
+| **Organizations**  |                                          |     |     |                              |
+| Create org         | `repo.organizations.create()`            | ❌  | ✅  | `{ did, name, ... }`         |
+| Get org            | `repo.organizations.get()`               | ❌  | ✅  | Organization                 |
+| List orgs          | `repo.organizations.list()`              | ❌  | ✅  | `{ organizations, cursor? }` |
+| **Collaborators**  |                                          |     |     |                              |
+| Grant access       | `repo.collaborators.grant()`             | ❌  | ✅  | void                         |
+| Revoke access      | `repo.collaborators.revoke()`            | ❌  | ✅  | void                         |
+| List collaborators | `repo.collaborators.list()`              | ❌  | ✅  | `{ collaborators, cursor? }` |
+| Check access       | `repo.collaborators.hasAccess()`         | ❌  | ✅  | boolean                      |
+| Get role           | `repo.collaborators.getRole()`           | ❌  | ✅  | Role string                  |
+| Get permissions    | `repo.collaborators.getPermissions()`    | ❌  | ✅  | Permissions                  |
+| Transfer ownership | `repo.collaborators.transferOwnership()` | ❌  | ✅  | void                         |
 
 ## Type System
 
@@ -549,15 +544,15 @@ if (OrgHypercertsClaim.isRecord(data)) {
 }
 ```
 
-| Lexicon Type | SDK Alias |
-|--------------|-----------|
-| `OrgHypercertsClaim.Main` | `HypercertClaim` |
-| `OrgHypercertsClaimRights.Main` | `HypercertRights` |
+| Lexicon Type                          | SDK Alias               |
+| ------------------------------------- | ----------------------- |
+| `OrgHypercertsClaim.Main`             | `HypercertClaim`        |
+| `OrgHypercertsClaimRights.Main`       | `HypercertRights`       |
 | `OrgHypercertsClaimContribution.Main` | `HypercertContribution` |
-| `OrgHypercertsClaimMeasurement.Main` | `HypercertMeasurement` |
-| `OrgHypercertsClaimEvaluation.Main` | `HypercertEvaluation` |
-| `OrgHypercertsCollection.Main` | `HypercertCollection` |
-| `AppCertifiedLocation.Main` | `HypercertLocation` |
+| `OrgHypercertsClaimMeasurement.Main`  | `HypercertMeasurement`  |
+| `OrgHypercertsClaimEvaluation.Main`   | `HypercertEvaluation`   |
+| `OrgHypercertsCollection.Main`        | `HypercertCollection`   |
+| `AppCertifiedLocation.Main`           | `HypercertLocation`     |
 
 ## Error Handling
 
@@ -622,6 +617,7 @@ await sdsAgent.com.atproto.repo.listRecords({...});
 ```
 
 This is useful for:
+
 - Connecting to multiple SDS instances simultaneously
 - Testing against different server environments
 - Building tools that work across multiple organizations
@@ -655,7 +651,8 @@ 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.
+The SDK exports lexicon types and validation utilities from the `@hypercerts-org/lexicon` package for direct record
+manipulation and validation.
 
 #### Lexicon Types
 
@@ -680,8 +677,8 @@ const claim: HypercertClaim = {
   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'
+  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(),
 };
@@ -692,16 +689,12 @@ const claim: HypercertClaim = {
 Validate records before creating them:
 
 ```typescript
-import {
-  validate,
-  OrgHypercertsClaim,
-  HYPERCERT_COLLECTIONS,
-} from "@hypercerts-org/sdk-core";
+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
+  HYPERCERT_COLLECTIONS.CLAIM, // "org.hypercerts.claim"
+  claim,
 );
 
 if (!validation.valid) {
@@ -718,20 +711,13 @@ const validationResult = OrgHypercertsClaim.validateMain(claim);
 For repository-level validation:
 
 ```typescript
-import {
-  LexiconRegistry,
-  HYPERCERT_LEXICONS,
-  HYPERCERT_COLLECTIONS,
-} from "@hypercerts-org/sdk-core";
+import { LexiconRegistry, HYPERCERT_LEXICONS, HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk-core";
 
 const registry = new LexiconRegistry();
 registry.registerLexicons(HYPERCERT_LEXICONS);
 
 // Validate a record
-const result = registry.validate(
-  HYPERCERT_COLLECTIONS.CLAIM,
-  claimData
-);
+const result = registry.validate(HYPERCERT_COLLECTIONS.CLAIM, claimData);
 
 if (!result.valid) {
   console.error("Invalid record:", result.error);
@@ -741,10 +727,7 @@ if (!result.valid) {
 #### Creating Records with Proper Types
 
 ```typescript
-import type {
-  HypercertContribution,
-  StrongRef,
-} from "@hypercerts-org/sdk-core";
+import type { HypercertContribution, StrongRef } from "@hypercerts-org/sdk-core";
 import { HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk-core";
 
 // Create a contribution record
@@ -757,8 +740,8 @@ const contribution: HypercertContribution = {
   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
+  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(),
 };
 
@@ -775,14 +758,14 @@ await repo.records.create({
 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"
+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