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

package/README.md

@@ -44,7 +44,100 @@ const claim = await repo.hypercerts.create({
 
 ## Core Concepts
 
-### 1. Authentication
+### 1. PDS vs SDS: Understanding Server Types
+
+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
+- **Example**: `sds.hypercerts.org`
+
+```typescript
+// Connect to user's PDS (default)
+const pdsRepo = sdk.repository(session);
+await pdsRepo.hypercerts.create({ ... }); // Creates in user's PDS
+
+// Connect to SDS for collaboration features
+const sdsRepo = sdk.repository(session, { server: "sds" });
+await sdsRepo.organizations.create({ name: "My Org" }); // SDS-only feature
+
+// Switch to organization repository (still on SDS)
+const orgs = await sdsRepo.organizations.list();
+const orgRepo = sdsRepo.repo(orgs.organizations[0].did);
+await orgRepo.hypercerts.list(); // Queries organization's hypercerts on SDS
+```
+
+#### How Repository Routing Works
+
+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
+   ```
+
+3. **Key Implementation Details**
+   - Each Repository uses a `ConfigurableAgent` that wraps your OAuth session's fetch handler
+   - The agent routes all requests to the specified server URL (PDS, SDS, or custom)
+   - When you call `.repo(did)`, a new Repository is created with the same server configuration
+   - Your OAuth session provides authentication (DPoP, access tokens), while the agent handles routing
+   - This enables simultaneous connections to multiple servers with one authentication session
+
+#### Common Patterns
+
+```typescript
+// Pattern 1: Personal hypercerts on PDS
+const myRepo = sdk.repository(session);
+await myRepo.hypercerts.create({ title: "My Personal Impact" });
+
+// Pattern 2: Organization hypercerts on SDS
+const sdsRepo = sdk.repository(session, { server: "sds" });
+const orgRepo = sdsRepo.repo(organizationDid);
+await orgRepo.hypercerts.create({ title: "Team Impact" });
+
+// Pattern 3: Reading another user's hypercerts
+const otherUserRepo = myRepo.repo("did:plc:other-user");
+await otherUserRepo.hypercerts.list(); // Read-only access to their PDS
+
+// Pattern 4: Collaborating on organization data
+const sdsRepo = sdk.repository(session, { server: "sds" });
+await sdsRepo.collaborators.grant({
+  userDid: "did:plc:teammate",
+  role: "editor",
+});
+const orgRepo = sdsRepo.repo(organizationDid);
+// Teammate can now access orgRepo and create hypercerts
+```
+
+### 2. Authentication
 
 The SDK uses OAuth 2.0 for authentication with support for both PDS (Personal Data Server) and SDS (Shared Data Server).
 
@@ -67,7 +160,7 @@ const session = await sdk.restoreSession("did:plc:user123");
 const repo = sdk.getRepository(session);
 ```
 
-### 2. Working with Hypercerts
+### 3. Working with Hypercerts
 
 #### Creating a Hypercert
 
@@ -144,7 +237,7 @@ await repo.hypercerts.delete(
 );
 ```
 
-### 3. Contributions and Measurements
+### 4. Contributions and Measurements
 
 #### Adding Contributions
 
@@ -174,7 +267,7 @@ const measurement = await repo.hypercerts.addMeasurement({
 });
 ```
 
-### 4. Blob Operations (Images & Files)
+### 5. Blob Operations (Images & Files)
 
 ```typescript
 // Upload an image or file
@@ -188,7 +281,7 @@ const blobData = await repo.blobs.get(
 );
 ```
 
-### 5. Organizations (SDS only)
+### 6. Organizations (SDS only)
 
 Organizations allow multiple users to collaborate on shared repositories.
 
@@ -216,7 +309,7 @@ const org = await repo.organizations.get("did:plc:org123");
 console.log(`${org.name} - ${org.description}`);
 ```
 
-### 6. Collaborator Management (SDS only)
+### 7. Collaborator Management (SDS only)
 
 Manage who has access to your repository and what they can do.
 
@@ -285,7 +378,7 @@ await repo.collaborators.transferOwnership({
 });
 ```
 
-### 7. Generic Record Operations
+### 8. Generic Record Operations
 
 For working with any ATProto record type:
 
@@ -330,7 +423,7 @@ const { records, cursor } = await repo.records.list({
 });
 ```
 
-### 8. Profile Management (PDS only)
+### 9. Profile Management (PDS only)
 
 ```typescript
 // Get user profile
@@ -457,6 +550,35 @@ try {
 
 ## Advanced Usage
 
+### Multi-Server Routing with ConfigurableAgent
+
+The `ConfigurableAgent` allows you to create custom agents that route to specific servers:
+
+```typescript
+import { ConfigurableAgent } from "@hypercerts-org/sdk-core";
+
+// Authenticate once with your PDS
+const session = await sdk.callback(params);
+
+// Create agents for different servers using the same session
+const pdsAgent = new ConfigurableAgent(session, "https://bsky.social");
+const sdsAgent = new ConfigurableAgent(session, "https://sds.hypercerts.org");
+const orgAgent = new ConfigurableAgent(session, "https://sds-org-a.example.com");
+
+// Use agents directly with AT Protocol APIs
+await pdsAgent.com.atproto.repo.createRecord({...});
+await sdsAgent.com.atproto.repo.listRecords({...});
+
+// Or pass to Repository for high-level operations
+// (Repository internally uses ConfigurableAgent)
+```
+
+This is useful for:
+- Connecting to multiple SDS instances simultaneously
+- Testing against different server environments
+- Building tools that work across multiple organizations
+- Direct AT Protocol API access with custom routing
+
 ### Custom Session Storage
 
 ```typescript

package/dist/index.cjs

@@ -2,8 +2,8 @@
 
 var oauthClientNode = require('@atproto/oauth-client-node');
 var lexicon$1 = require('@atproto/lexicon');
-var api = require('@atproto/api');
 var lexicon = require('@hypercerts-org/lexicon');
+var api = require('@atproto/api');
 var eventemitter3 = require('eventemitter3');
 var zod = require('zod');
 
@@ -1246,6 +1246,80 @@ class LexiconRegistry {
     }
 }
 
+/**
+ * ConfigurableAgent - Agent with configurable service URL routing.
+ *
+ * This module provides an Agent extension that allows routing requests to
+ * a specific server URL, overriding the default URL from the OAuth session.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Agent subclass that routes requests to a configurable service URL.
+ *
+ * The standard Agent uses the service URL embedded in the OAuth session's
+ * fetch handler. This class allows overriding that URL to route requests
+ * to different servers (e.g., PDS vs SDS, or multiple SDS instances).
+ *
+ * @remarks
+ * This is particularly useful for:
+ * - Routing to a Shared Data Server (SDS) while authenticated via PDS
+ * - Supporting multiple SDS instances for different organizations
+ * - Testing against different server environments
+ *
+ * @example Basic usage
+ * ```typescript
+ * const session = await sdk.authorize("user.bsky.social");
+ *
+ * // Create agent routing to SDS instead of session's default PDS
+ * const sdsAgent = new ConfigurableAgent(session, "https://sds.hypercerts.org");
+ *
+ * // All requests will now go to the SDS
+ * await sdsAgent.com.atproto.repo.createRecord({...});
+ * ```
+ *
+ * @example Multiple SDS instances
+ * ```typescript
+ * // Route to organization A's SDS
+ * const orgAAgent = new ConfigurableAgent(session, "https://sds-org-a.example.com");
+ *
+ * // Route to organization B's SDS
+ * const orgBAgent = new ConfigurableAgent(session, "https://sds-org-b.example.com");
+ * ```
+ */
+class ConfigurableAgent extends api.Agent {
+    /**
+     * Creates a ConfigurableAgent that routes to a specific service URL.
+     *
+     * @param session - OAuth session for authentication
+     * @param serviceUrl - Base URL of the server to route requests to
+     *
+     * @remarks
+     * The agent wraps the session's fetch handler to intercept requests and
+     * prepend the custom service URL instead of using the session's default.
+     */
+    constructor(session, serviceUrl) {
+        // Create a custom fetch handler that uses our service URL
+        const customFetchHandler = async (pathname, init) => {
+            // Construct the full URL with our custom service
+            const url = new URL(pathname, serviceUrl).toString();
+            // Use the session's fetch handler for authentication (DPoP, etc.)
+            return session.fetchHandler(url, init);
+        };
+        // Initialize the parent Agent with our custom fetch handler
+        super(customFetchHandler);
+        this.customServiceUrl = serviceUrl;
+    }
+    /**
+     * Gets the service URL this agent routes to.
+     *
+     * @returns The base URL of the configured service
+     */
+    getServiceUrl() {
+        return this.customServiceUrl;
+    }
+}
+
 /**
  * RecordOperationsImpl - Low-level record CRUD operations.
  *
@@ -3119,23 +3193,24 @@ class CollaboratorOperationsImpl {
         return "viewer";
     }
     /**
-     * Converts a permission string array to a permissions object.
+     * Normalizes permissions from SDS API format to SDK format.
      *
-     * The SDS API returns permissions as an array of strings (e.g., ["read", "create"]).
-     * This method converts them to the boolean flag format used by the SDK.
+     * The SDS API returns permissions as an object with boolean flags
+     * (e.g., `{ read: true, create: true, update: false, ... }`).
+     * This method ensures all expected fields are present with default values.
      *
-     * @param permissionArray - Array of permission strings from SDS API
-     * @returns Permission flags object
+     * @param permissions - Permissions object from SDS API
+     * @returns Normalized permission flags object
      * @internal
      */
-    parsePermissions(permissionArray) {
+    parsePermissions(permissions) {
         return {
-            read: permissionArray.includes("read"),
-            create: permissionArray.includes("create"),
-            update: permissionArray.includes("update"),
-            delete: permissionArray.includes("delete"),
-            admin: permissionArray.includes("admin"),
-            owner: permissionArray.includes("owner"),
+            read: permissions.read ?? false,
+            create: permissions.create ?? false,
+            update: permissions.update ?? false,
+            delete: permissions.delete ?? false,
+            admin: permissions.admin ?? false,
+            owner: permissions.owner ?? false,
         };
     }
     /**
@@ -3771,8 +3846,10 @@ class Repository {
         this.lexiconRegistry = lexiconRegistry;
         this._isSDS = isSDS;
         this.logger = logger;
-        // Create Agent with OAuth session
-        this.agent = new api.Agent(session);
+        // Create a ConfigurableAgent that routes requests to the specified server URL
+        // This allows routing to PDS, SDS, or any custom server while maintaining
+        // the OAuth session's authentication
+        this.agent = new ConfigurableAgent(session, serverUrl);
         this.lexiconRegistry.addToAgent(this.agent);
         // Register hypercert lexicons
         this.lexiconRegistry.registerMany(lexicon.HYPERCERT_LEXICONS);
@@ -4692,6 +4769,7 @@ exports.ATProtoSDKError = ATProtoSDKError;
 exports.AuthenticationError = AuthenticationError;
 exports.CollaboratorPermissionsSchema = CollaboratorPermissionsSchema;
 exports.CollaboratorSchema = CollaboratorSchema;
+exports.ConfigurableAgent = ConfigurableAgent;
 exports.InMemorySessionStore = InMemorySessionStore;
 exports.InMemoryStateStore = InMemoryStateStore;
 exports.LexiconRegistry = LexiconRegistry;