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

package/CHANGELOG.md

@@ -1,5 +1,231 @@
 # @hypercerts-org/sdk-core
 
+## 0.10.0-beta.6
+
+### Minor Changes
+
+- [#101](https://github.com/hypercerts-org/hypercerts-sdk/pull/101)
+  [`bf93b3c`](https://github.com/hypercerts-org/hypercerts-sdk/commit/bf93b3cf5d5eccb12de31c4fe6f95ed3676c746e) Thanks
+  [@aspiers](https://github.com/aspiers)! - feat: align collection/project types with lexicon + add inline location
+  support
+
+  This is a BREAKING change.
+
+  **Type Alignment with Lexicon:**
+  - Changed `createCollection` to use lexicon-aligned `items` array instead of `claims`
+  - Updated avatar/banner handling to use proper lexicon union types
+  - Simplified project methods to delegate to collection methods
+  - Added `CreateCollectionParams`, `UpdateCollectionParams`, and result types derived from lexicon
+  - Improved type safety by deriving SDK input types from lexicon definitions
+
+  **Inline Location Support:**
+
+  `AttachLocationParams` now supports three ways to specify location:
+  1. **StrongRef** - Direct reference with uri and cid (no record creation)
+  2. **AT-URI string** - Reference to existing location record
+  3. **Location object** - Full location data to create a new location record
+
+  **Changes:**
+  - Add `AttachLocationParams` union type supporting StrongRef, string URI, or location object
+  - Add optional `location` field to `CreateCollectionParams`
+  - Add optional `location` field to `UpdateCollectionParams` (supports `null` to remove)
+  - Update `CreateCollectionResult` to include optional `locationUri` field
+  - Implement location handling in `createCollection()` - supports all three forms
+  - Add tests for collection creation with StrongRef, string URI, and location object
+
+  **Example Usage:**
+
+  ```typescript
+  // Create a project with location (StrongRef - direct reference)
+  const project = await repo.hypercerts.createProject({
+    title: "Climate Initiative",
+    items: [...],
+    location: { uri: "at://did:plc:alice/app.certified.location/abc", cid: "bafy..." },
+  });
+
+  // Create with location (AT-URI string - fetches CID)
+  const project2 = await repo.hypercerts.createProject({
+    title: "Forest Project",
+    items: [...],
+    location: "at://did:plc:bob/app.certified.location/xyz",
+  });
+
+  // Create with location (location object - creates new record)
+  const project3 = await repo.hypercerts.createProject({
+    title: "Ocean Project",
+    items: [...],
+    location: {
+      lpVersion: "1.0",
+      srs: "EPSG:4326",
+      locationType: "coordinate-decimal",
+      location: "37.7749, -122.4194",
+    },
+  });
+
+  // Update project to change location
+  await repo.hypercerts.updateProject(project.uri, {
+    location: "at://did:plc:alice/app.certified.location/new",
+  });
+
+  // Remove location
+  await repo.hypercerts.updateProject(project.uri, {
+    location: null,
+  });
+  ```
+
+## 0.10.0-beta.5
+
+### Minor Changes
+
+- [#87](https://github.com/hypercerts-org/hypercerts-sdk/pull/87)
+  [`85b1350`](https://github.com/hypercerts-org/hypercerts-sdk/commit/85b13502791e49966dae3d0dd0e833905c59abe3) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Add comprehensive project support to SDK
+
+  **Core SDK (`@hypercerts-org/sdk-core`):**
+  - Add project CRUD operations (createProject, getProject, listProjects, updateProject, deleteProject)
+  - Add project events (projectCreated, projectUpdated, projectDeleted)
+  - Support for avatar and coverPhoto blob uploads
+  - Activities array with weight values
+  - Location reference support
+  - 34 comprehensive tests with full coverage
+
+  **React SDK (`@hypercerts-org/sdk-react`):**
+  - Add useProjects and useProject hooks
+  - Project query keys for cache management
+  - TypeScript types for projects (Project, CreateProjectParams, UpdateProjectParams)
+  - Test factory support for project hooks
+  - Full pagination and optimistic updates support
+
+  Projects organize multiple hypercert activities with metadata including title, shortDescription, description (Leaflet
+  documents), avatar, cover photo, activities with weights, and location references.
+
+- [#98](https://github.com/hypercerts-org/hypercerts-sdk/pull/98)
+  [`f9dd27f`](https://github.com/hypercerts-org/hypercerts-sdk/commit/f9dd27f78de0ee49aab9079e76566f272b161cd0) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Add BaseOperations abstract class for building custom lexicon
+  operations. Developers can now extend BaseOperations to create type-safe, validated operation classes for their custom
+  lexicons, with built-in helpers for record creation, validation, and strongRef management.
+
+- [#98](https://github.com/hypercerts-org/hypercerts-sdk/pull/98)
+  [`e850310`](https://github.com/hypercerts-org/hypercerts-sdk/commit/e850310d26e0561bdcfb778a6ef3bedbb7453eed) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Add comprehensive documentation and examples for custom lexicons.
+  Includes custom-lexicons.md guide, sidecar-pattern.md guide, and a complete working example with tests demonstrating
+  how to create and use custom lexicons for evaluating hypercerts.
+
+- [#84](https://github.com/hypercerts-org/hypercerts-sdk/pull/84)
+  [`3157c18`](https://github.com/hypercerts-org/hypercerts-sdk/commit/3157c188c70e2f9473ee14eddaf635e3fbd346a1) Thanks
+  [@Kzoeps](https://github.com/Kzoeps)! - Evidence records are now created separately instead of being embedded inline
+  in hypercerts
+  - `create()` now calls `addEvidence()` for each evidence item using `Promise.all()` for parallel creation
+  - Remove inline evidence embedding from hypercert records
+  - Add `evidenceUris?: string[]` to `CreateHypercertResult` interface
+  - Add `createEvidenceWithProgress()` helper method with "addEvidence" progress tracking
+  - `addEvidence()` SDK constructs `$type`, `createdAt`, and `subject` fields internally
+
+  **Breaking Changes:**
+  - Evidence is no longer embedded in the hypercert record - use `result.evidenceUris` to access evidence record URIs
+  - `addEvidence()` now accepts a single `CreateHypercertEvidenceParams` object instead of
+    `(uri: string, evidence: HypercertEvidence[])`
+
+- [#98](https://github.com/hypercerts-org/hypercerts-sdk/pull/98)
+  [`0cd3b26`](https://github.com/hypercerts-org/hypercerts-sdk/commit/0cd3b26eb779246e9ef094f614f2f77807926f1b) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Add LexiconRegistry for custom lexicon management. Developers can now
+  register custom lexicon schemas at runtime and validate records against registered schemas before creation. The
+  registry supports:
+  - Registering custom lexicon definitions from JSON
+  - Validating records against registered schemas
+  - Querying registered lexicons
+  - Managing lexicon lifecycle (register/unregister)
+
+  This enables developers to extend the SDK with custom record types that can reference hypercerts and other records
+  using strongRefs.
+
+- [#98](https://github.com/hypercerts-org/hypercerts-sdk/pull/98)
+  [`b87cb22`](https://github.com/hypercerts-org/hypercerts-sdk/commit/b87cb2265d924b531eef8d58c669dc931b61e561) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Add lexicon development utilities for custom lexicons. Developers can
+  now use helper functions for AT-URI parsing, strongRef creation, lexicon schema building, and sidecar pattern
+  implementation. This includes:
+  - AT-URI utilities: parseAtUri, buildAtUri, extractRkeyFromUri, isValidAtUri
+  - StrongRef utilities: createStrongRef, createStrongRefFromResult, validateStrongRef
+  - Lexicon builders: createStringField, createIntegerField, createStrongRefField, createRecordDef, createLexiconDoc,
+    and more
+  - Sidecar pattern: createSidecarRecord, attachSidecar, createWithSidecars, batchCreateSidecars
+
+- [#88](https://github.com/hypercerts-org/hypercerts-sdk/pull/88)
+  [`19c78df`](https://github.com/hypercerts-org/hypercerts-sdk/commit/19c78dfef448fb43d353d95721c13f3a35618fb3) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - feat: add HTTP loopback URL support for local development
+
+  Enable local development and testing with HTTP loopback URLs (`http://localhost`, `http://127.0.0.1`, `http://[::1]`)
+  while maintaining security for production deployments.
+
+  **Configuration Updates**
+  - Custom URL validator accepting HTTPS URLs or HTTP loopback addresses
+  - Update `OAuthConfigSchema` to allow loopback URLs for `clientId`, `redirectUri`, `jwksUri`
+  - Add optional `developmentMode` boolean flag to suppress warnings
+  - Update `ServerConfigSchema` to allow loopback URLs for PDS/SDS servers
+  - Export `isLoopbackUrl()` helper function and TypeScript types (`LoopbackUrl`, `HttpsUrl`,
+    `DevelopmentOrProductionUrl`)
+
+  **Development Mode Features**
+  - Automatic loopback detection with informative logging
+  - Warning when using loopback URLs without explicit `developmentMode` flag
+  - Info logs indicating development mode is active
+  - Clear guidance about authorization server requirements
+
+  **Testing**
+  - 28 new unit tests for loopback URL validation
+  - Tests cover localhost, 127.0.0.1, and [::1] (IPv6) loopback addresses
+  - Tests verify rejection of non-loopback HTTP URLs
+  - Tests ensure HTTPS URLs always accepted
+
+  **Documentation**
+  - Comprehensive local development guide in Core SDK README
+  - NextJS App Router example with loopback configuration
+  - API route setup examples (OAuth callback, JWKS endpoint)
+  - Important notes about authorization server support and production safety
+  - Local development example added to React SDK factory JSDoc
+
+  **Breaking Changes**: None - fully backward compatible
+
+  **Migration**: No migration needed for existing configurations. Existing HTTPS URLs continue to work without changes.
+
+  This feature enables developers to test the SDK locally without requiring HTTPS certificates, while the underlying
+  `@atproto/oauth-client-node` library handles loopback OAuth flows per the AT Protocol specification.
+
+- [#98](https://github.com/hypercerts-org/hypercerts-sdk/pull/98)
+  [`3554580`](https://github.com/hypercerts-org/hypercerts-sdk/commit/3554580d77d9467c88c779e75a96a08d3e17bfd7) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Add automatic lexicon validation to RecordOperations. Records are now
+  validated against registered lexicon schemas before being sent to the server, catching schema violations early.
+  Validation can be bypassed using the `skipValidation` parameter for advanced use cases.
+
+- [#96](https://github.com/hypercerts-org/hypercerts-sdk/pull/96)
+  [`eea06a7`](https://github.com/hypercerts-org/hypercerts-sdk/commit/eea06a7f5e4f655ccac635fa8842ea32a6dfde64) Thanks
+  [@Kzoeps](https://github.com/Kzoeps)! - Refactor location attachment to match lexicon specifications
+
+  **New Features:**
+  - Add `AttachLocationParams` interface exported from SDK for type-safe location attachment
+  - Location data now properly uses `org.hypercerts.defs#uri` (for string URIs) or `org.hypercerts.defs#smallBlob` (for
+    GeoJSON blobs) to match lexicon spec
+  - Add `lpVersion` and `locationType` fields to location parameters for better protocol compliance
+
+  **Improvements:**
+  - Centralized blob upload logic with new `handleBlobUpload()` helper method
+  - Simplified location type detection - now based on content type (string vs Blob) instead of separate `geojson`
+    parameter
+  - Improved type safety with structured `AttachLocationParams` interface
+
+  **Breaking Changes:**
+  - `attachLocation()` signature changed from `(uri, { value, name?, description?, srs, geojson? })` to
+    `(uri, AttachLocationParams)`
+  - `AttachLocationParams` now requires: `lpVersion`, `srs`, `locationType`, and `location` (string | Blob)
+  - The `location` field in `CreateHypercertParams` now uses `AttachLocationParams` type instead of inline object
+  - Removed separate `value` and `geojson` fields - use single `location` field with either string or Blob
+
+- [#98](https://github.com/hypercerts-org/hypercerts-sdk/pull/98)
+  [`e0ef6e9`](https://github.com/hypercerts-org/hypercerts-sdk/commit/e0ef6e9cb9138590e81b4a2929ca27ae557d2f39) Thanks
+  [@bitbeckers](https://github.com/bitbeckers)! - Integrate LexiconRegistry into SDK and Repository. The SDK now
+  initializes a LexiconRegistry with hypercert lexicons by default and exposes it via `getLexiconRegistry()`. Repository
+  instances receive the registry and pass it to RecordOperations for future validation support.
+
 ## 0.10.0-beta.4
 
 ### Minor Changes

package/README.md

@@ -51,6 +51,99 @@ const claim = await repo.hypercerts.create({
 });
 ```
 
+## Local Development
+
+For local development and testing, you can use HTTP loopback URLs with `localhost` or `127.0.0.1`:
+
+### NextJS App Router Example
+
+```typescript
+// lib/atproto.ts
+import { createATProtoSDK } from "@hypercerts-org/sdk-core";
+
+const sdk = createATProtoSDK({
+  oauth: {
+    // Use localhost for client_id (loopback client)
+    clientId: "http://localhost/",
+
+    // Use 127.0.0.1 with your app's port for redirect
+    redirectUri: "http://127.0.0.1:3000/api/auth/callback",
+
+    scope: "atproto",
+
+    // Serve JWKS from your app
+    jwksUri: "http://127.0.0.1:3000/.well-known/jwks.json",
+
+    // Load from environment variable
+    jwkPrivate: process.env.ATPROTO_JWK_PRIVATE!,
+
+    // Optional: suppress warnings
+    developmentMode: true,
+  },
+  servers: {
+    // Point to local PDS for testing
+    pds: "http://localhost:2583",
+  },
+  logger: console, // Enable debug logging
+});
+
+export default sdk;
+```
+
+### API Route Setup
+
+```typescript
+// app/api/auth/callback/route.ts
+import sdk from "@/lib/atproto";
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+
+  try {
+    const session = await sdk.callback(searchParams);
+
+    // Store session (use secure httpOnly cookie in production)
+    return Response.json({ success: true, did: session.sub });
+  } catch (error) {
+    return Response.json({ error: "Authentication failed" }, { status: 401 });
+  }
+}
+```
+
+### Serve JWKS Endpoint
+
+```typescript
+// app/.well-known/jwks.json/route.ts
+export async function GET() {
+  const jwk = JSON.parse(process.env.ATPROTO_JWK_PRIVATE!);
+
+  // Return public keys only (remove private key 'd' parameter)
+  const publicKeys = jwk.keys.map(({ d, ...publicKey }) => publicKey);
+
+  return Response.json({ keys: publicKeys });
+}
+```
+
+### Environment Variables
+
+```bash
+# .env.local
+ATPROTO_JWK_PRIVATE='{"keys":[{"kty":"EC","crv":"P-256",...}]}'
+```
+
+### Important Notes
+
+> **Authorization Server Support**: The AT Protocol OAuth spec makes loopback support **optional**. Most AT Protocol
+> servers support loopback clients for development, but verify your target authorization server supports this feature.
+
+> **Port Matching**: Redirect URIs can use any port - the authorization server ignores port numbers when validating
+> loopback redirects (only the path must match).
+
+> **Production Use**: ⚠️ Never use HTTP loopback URLs in production. Always use HTTPS with proper TLS certificates.
+
+> **IP vs Hostname**: Use `http://localhost/` for `clientId` and `http://127.0.0.1:<port>` for `redirectUri` and
+> `jwksUri` (this is the recommended pattern per AT Protocol spec).
+
 ## Core Concepts
 
 ### 1. PDS vs SDS: Understanding Server Types
@@ -318,7 +411,130 @@ const measurement = await repo.hypercerts.addMeasurement({
 });
 ```
 
-### 5. Blob Operations (Images & Files)
+### 5. Collections and Projects
+
+Collections organize multiple hypercerts into logical groupings. Projects are a special type of collection with
+`type="project"`.
+
+#### Creating a Collection
+
+```typescript
+// Create a collection with weighted items
+const collection = await repo.hypercerts.createCollection({
+  title: "Climate Projects 2024",
+  shortDescription: "Our climate impact portfolio",
+  description: "A curated collection of climate-related hypercerts",
+  items: [
+    {
+      itemIdentifier: { uri: hypercert1Uri, cid: hypercert1Cid },
+      itemWeight: "0.5",
+    },
+    {
+      itemIdentifier: { uri: hypercert2Uri, cid: hypercert2Cid },
+      itemWeight: "0.3",
+    },
+    {
+      itemIdentifier: { uri: hypercert3Uri, cid: hypercert3Cid },
+      itemWeight: "0.2",
+    },
+  ],
+  avatar: avatarBlob, // optional
+  banner: bannerBlob, // optional
+});
+
+console.log("Created collection:", collection.uri);
+```
+
+#### Creating a Project
+
+Projects are collections with automatic `type="project"`:
+
+```typescript
+const project = await repo.hypercerts.createProject({
+  title: "Rainforest Restoration",
+  shortDescription: "Multi-year restoration initiative",
+  description: "Comprehensive rainforest restoration project",
+  items: [
+    {
+      itemIdentifier: { uri: activity1Uri, cid: activity1Cid },
+      itemWeight: "0.6",
+    },
+    {
+      itemIdentifier: { uri: activity2Uri, cid: activity2Cid },
+      itemWeight: "0.4",
+    },
+  ],
+});
+```
+
+#### Attaching Locations
+
+Both collections and projects can have location data attached as a sidecar record:
+
+```typescript
+// Attach location to a project
+const locationResult = await repo.hypercerts.attachLocationToProject(projectUri, {
+  lpVersion: "1.0",
+  srs: "EPSG:4326",
+  locationType: "coordinate-decimal",
+  location: "https://example.com/location.geojson", // or use a Blob
+  name: "Project Site",
+  description: "Main restoration site coordinates",
+});
+
+// Also works for collections
+await repo.hypercerts.attachLocationToCollection(collectionUri, locationParams);
+```
+
+#### Listing and Retrieving
+
+```typescript
+// Get a specific collection
+const collection = await repo.hypercerts.getCollection(collectionUri);
+
+// List all collections
+const { records } = await repo.hypercerts.listCollections();
+
+// Get a specific project
+const project = await repo.hypercerts.getProject(projectUri);
+
+// List all projects
+const { records } = await repo.hypercerts.listProjects();
+```
+
+#### Updating Collections and Projects
+
+```typescript
+// Update collection
+await repo.hypercerts.updateCollection(collectionUri, {
+  title: "Updated Title",
+  items: [
+    /* updated items */
+  ],
+  avatar: newAvatarBlob, // or null to remove
+});
+
+// Update project (same API)
+await repo.hypercerts.updateProject(projectUri, {
+  shortDescription: "Updated description",
+  banner: null, // removes banner
+});
+```
+
+#### Deleting
+
+```typescript
+// Delete collection
+await repo.hypercerts.deleteCollection(collectionUri);
+
+// Delete project
+await repo.hypercerts.deleteProject(projectUri);
+
+// Remove location from project
+await repo.hypercerts.removeLocationFromProject(projectUri);
+```
+
+### 6. Blob Operations (Images & Files)
 
 ```typescript
 // Upload an image or file
@@ -329,7 +545,7 @@ console.log("Blob uploaded:", blobResult.ref.$link);
 const blobData = await repo.blobs.get("did:plc:user123", "bafyreiabc123...");
 ```
 
-### 6. Organizations (SDS only)
+### 7. Organizations (SDS only)
 
 Organizations allow multiple users to collaborate on shared repositories.
 
@@ -357,7 +573,7 @@ const org = await repo.organizations.get("did:plc:org123");
 console.log(`${org.name} - ${org.description}`);
 ```
 
-### 7. Collaborator Management (SDS only)
+### 8. Collaborator Management (SDS only)
 
 Manage who has access to your repository and what they can do.
 
@@ -426,7 +642,7 @@ await repo.collaborators.transferOwnership({
 });
 ```
 
-### 8. Generic Record Operations
+### 9. Generic Record Operations
 
 For working with any ATProto record type:
 
@@ -471,7 +687,7 @@ const { records, cursor } = await repo.records.list({
 });
 ```
 
-### 9. Profile Management (PDS only)
+### 10. Profile Management (PDS only)
 
 ```typescript
 // Get user profile
@@ -491,40 +707,56 @@ 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                  |
+| **Collections**    |                                                  |     |     |                              |
+| Create collection  | `repo.hypercerts.createCollection()`             | ✅  | ✅  | `{ uri, cid, record }`       |
+| Get collection     | `repo.hypercerts.getCollection()`                | ✅  | ✅  | Collection data              |
+| List collections   | `repo.hypercerts.listCollections()`              | ✅  | ✅  | `{ records, cursor? }`       |
+| Update collection  | `repo.hypercerts.updateCollection()`             | ✅  | ✅  | `{ uri, cid }`               |
+| Delete collection  | `repo.hypercerts.deleteCollection()`             | ✅  | ✅  | void                         |
+| Attach location    | `repo.hypercerts.attachLocationToCollection()`   | ✅  | ✅  | `{ uri, cid }`               |
+| Remove location    | `repo.hypercerts.removeLocationFromCollection()` | ✅  | ✅  | void                         |
+| **Projects**       |                                                  |     |     |                              |
+| Create project     | `repo.hypercerts.createProject()`                | ✅  | ✅  | `{ uri, cid, record }`       |
+| Get project        | `repo.hypercerts.getProject()`                   | ✅  | ✅  | Project data                 |
+| List projects      | `repo.hypercerts.listProjects()`                 | ✅  | ✅  | `{ records, cursor? }`       |
+| Update project     | `repo.hypercerts.updateProject()`                | ✅  | ✅  | `{ uri, cid }`               |
+| Delete project     | `repo.hypercerts.deleteProject()`                | ✅  | ✅  | void                         |
+| Attach location    | `repo.hypercerts.attachLocationToProject()`      | ✅  | ✅  | `{ uri, cid }`               |
+| Remove location    | `repo.hypercerts.removeLocationFromProject()`    | ✅  | ✅  | void                         |
+| **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
 
@@ -713,20 +945,52 @@ const validationResult = OrgHypercertsClaim.validateMain(claim);
 
 #### Using LexiconRegistry
 
-For repository-level validation:
+The SDK automatically initializes a LexiconRegistry with all hypercert lexicons. You can access it to validate records
+or register custom lexicons:
 
 ```typescript
-import { LexiconRegistry, HYPERCERT_LEXICONS, HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk-core";
-
-const registry = new LexiconRegistry();
-registry.registerLexicons(HYPERCERT_LEXICONS);
+// Access the registry from the SDK
+const registry = sdk.getLexiconRegistry();
 
 // Validate a record
-const result = registry.validate(HYPERCERT_COLLECTIONS.CLAIM, claimData);
+const result = registry.validate("org.hypercerts.claim.activity", claimData);
 
 if (!result.valid) {
   console.error("Invalid record:", result.error);
 }
+
+// Register a custom lexicon
+registry.registerFromJSON({
+  lexicon: 1,
+  id: "org.myapp.customRecord",
+  defs: {
+    main: {
+      type: "record",
+      key: "tid",
+      record: {
+        type: "object",
+        required: ["$type", "title"],
+        properties: {
+          $type: { type: "string", const: "org.myapp.customRecord" },
+          title: { type: "string" },
+          createdAt: { type: "string", format: "datetime" },
+        },
+      },
+    },
+  },
+});
+
+// Check if a lexicon is registered
+if (registry.isRegistered("org.myapp.customRecord")) {
+  console.log("Custom lexicon is ready to use");
+}
+```
+
+You can also access the registry from a Repository instance:
+
+```typescript
+const repo = sdk.repository(session);
+const registry = repo.getLexiconRegistry();
 ```
 
 #### Creating Records with Proper Types