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

package/dist/index.d.ts

@@ -2987,6 +2987,69 @@ declare class ATProtoSDK {
  */
 declare function createATProtoSDK(config: ATProtoSDKConfig): ATProtoSDK;
 
+/**
+ * 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");
+ * ```
+ */
+declare class ConfigurableAgent extends Agent {
+    private customServiceUrl;
+    /**
+     * 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: Session, serviceUrl: string);
+    /**
+     * Gets the service URL this agent routes to.
+     *
+     * @returns The base URL of the configured service
+     */
+    getServiceUrl(): string;
+}
+
 /**
  * Base error class for all SDK errors.
  *
@@ -3464,5 +3527,5 @@ declare class InMemoryStateStore implements StateStore {
     clear(): void;
 }
 
-export { ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AuthenticationError, CollaboratorPermissionsSchema, CollaboratorSchema, InMemorySessionStore, InMemoryStateStore, LexiconRegistry, NetworkError, OAuthConfigSchema, OrganizationSchema, Repository, SDSRequiredError, ServerConfigSchema, SessionExpiredError, TimeoutConfigSchema, ValidationError, createATProtoSDK };
+export { ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AuthenticationError, CollaboratorPermissionsSchema, CollaboratorSchema, ConfigurableAgent, InMemorySessionStore, InMemoryStateStore, LexiconRegistry, NetworkError, OAuthConfigSchema, OrganizationSchema, Repository, SDSRequiredError, ServerConfigSchema, SessionExpiredError, TimeoutConfigSchema, ValidationError, createATProtoSDK };
 export type { ATProtoSDKConfig, AuthorizeOptions, BlobOperations, BlobRef, CacheInterface, Collaborator, CollaboratorOperations, CollaboratorPermissions, CreateHypercertParams, CreateHypercertResult, CreateResult, DID, HypercertClaim, HypercertCollection, HypercertCollectionClaimItem, HypercertContribution, HypercertEvaluation, HypercertEvents, HypercertEvidence, HypercertImage, HypercertLocation, HypercertMeasurement, HypercertOperations, HypercertRights, HypercertWithMetadata, ListParams, LoggerInterface, Organization, OrganizationInfo, OrganizationOperations, PaginatedList, ProfileOperations, ProgressStep, RecordOperations, RepositoryAccessGrant, RepositoryOptions, RepositoryRole, Session, SessionStore, StateStore, StrongRef, UpdateResult, ValidationResult };

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { JoseKey, NodeOAuthClient } from '@atproto/oauth-client-node';
 import { Lexicons } from '@atproto/lexicon';
-import { Agent } from '@atproto/api';
 import { HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS } from '@hypercerts-org/lexicon';
 export { AppCertifiedLocation, ComAtprotoRepoStrongRef, HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS, OrgHypercertsClaim, OrgHypercertsClaimContribution, OrgHypercertsClaimEvaluation, OrgHypercertsClaimEvidence, OrgHypercertsClaimMeasurement, OrgHypercertsClaimRights, OrgHypercertsCollection, ids, lexicons, schemaDict, schemas, validate } from '@hypercerts-org/lexicon';
+import { Agent } from '@atproto/api';
 import { EventEmitter } from 'eventemitter3';
 import { z } from 'zod';
 
@@ -1245,6 +1245,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 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.
  *
@@ -3118,23 +3192,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,
         };
     }
     /**
@@ -3770,8 +3845,10 @@ class Repository {
         this.lexiconRegistry = lexiconRegistry;
         this._isSDS = isSDS;
         this.logger = logger;
-        // Create Agent with OAuth session
-        this.agent = new 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(HYPERCERT_LEXICONS);
@@ -4621,5 +4698,5 @@ const CollaboratorSchema = z.object({
     revokedAt: z.string().optional(),
 });
 
-export { ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AuthenticationError, CollaboratorPermissionsSchema, CollaboratorSchema, InMemorySessionStore, InMemoryStateStore, LexiconRegistry, NetworkError, OAuthConfigSchema, OrganizationSchema, Repository, SDSRequiredError, ServerConfigSchema, SessionExpiredError, TimeoutConfigSchema, ValidationError, createATProtoSDK };
+export { ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AuthenticationError, CollaboratorPermissionsSchema, CollaboratorSchema, ConfigurableAgent, InMemorySessionStore, InMemoryStateStore, LexiconRegistry, NetworkError, OAuthConfigSchema, OrganizationSchema, Repository, SDSRequiredError, ServerConfigSchema, SessionExpiredError, TimeoutConfigSchema, ValidationError, createATProtoSDK };
 //# sourceMappingURL=index.mjs.map