@hypercerts-org/sdk-core 0.6.0-beta.0 → 0.8.0-beta.0

package/dist/index.d.ts

@@ -1242,11 +1242,11 @@ interface CreateHypercertParams {
          */
         description?: string;
         /**
-         * Spatial Reference System identifier.
+         * Spatial Reference System identifier (required if location is provided).
          *
          * @example "EPSG:4326" for WGS84
          */
-        srs?: string;
+        srs: string;
         /**
          * GeoJSON file as a Blob for precise boundaries.
          */
@@ -1723,13 +1723,18 @@ interface HypercertOperations extends EventEmitter<HypercertEvents> {
      *
      * @param uri - AT-URI of the hypercert
      * @param location - Location data
+     * @param location.value - Location value (address, coordinates, or description)
+     * @param location.srs - Spatial Reference System (required). Use 'EPSG:4326' for WGS84 lat/lon coordinates.
+     * @param location.name - Optional human-readable location name
+     * @param location.description - Optional description of the location
+     * @param location.geojson - Optional GeoJSON blob for precise boundaries
      * @returns Promise resolving to location record result
      */
     attachLocation(uri: string, location: {
         value: string;
         name?: string;
         description?: string;
-        srs?: string;
+        srs: string;
         geojson?: Blob;
     }): Promise<CreateResult>;
     /**
@@ -2987,6 +2992,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 +3532,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.
  *
@@ -2195,6 +2269,7 @@ class HypercertOperationsImpl extends EventEmitter {
             // Step 2: Create rights record
             this.emitProgress(params.onProgress, { name: "createRights", status: "start" });
             const rightsRecord = {
+                $type: HYPERCERT_COLLECTIONS.RIGHTS,
                 rightsName: params.rights.name,
                 rightsType: params.rights.type,
                 rightsDescription: params.rights.description,
@@ -2223,6 +2298,7 @@ class HypercertOperationsImpl extends EventEmitter {
             // Step 3: Create hypercert record
             this.emitProgress(params.onProgress, { name: "createHypercert", status: "start" });
             const hypercertRecord = {
+                $type: HYPERCERT_COLLECTIONS.CLAIM,
                 title: params.title,
                 description: params.description,
                 workScope: params.workScope,
@@ -2570,6 +2646,7 @@ class HypercertOperationsImpl extends EventEmitter {
      * await repo.hypercerts.attachLocation(hypercertUri, {
      *   value: "San Francisco, CA",
      *   name: "SF Bay Area",
+     *   srs: "EPSG:4326",
      * });
      * ```
      *
@@ -2588,32 +2665,54 @@ class HypercertOperationsImpl extends EventEmitter {
      */
     async attachLocation(hypercertUri, location) {
         try {
-            // Get hypercert to get CID
-            const hypercert = await this.get(hypercertUri);
+            // Validate required srs field
+            if (!location.srs) {
+                throw new ValidationError("srs (Spatial Reference System) is required. Example: 'EPSG:4326' for WGS84 coordinates, or 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' for CRS84.");
+            }
+            // Validate that hypercert exists (unused but confirms hypercert is valid)
+            await this.get(hypercertUri);
             const createdAt = new Date().toISOString();
-            let locationValue = location.value;
+            // Determine location type and prepare location data
+            let locationData;
+            let locationType;
             if (location.geojson) {
+                // Upload GeoJSON as a blob
                 const arrayBuffer = await location.geojson.arrayBuffer();
                 const uint8Array = new Uint8Array(arrayBuffer);
                 const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
                     encoding: location.geojson.type || "application/geo+json",
                 });
                 if (uploadResult.success) {
-                    locationValue = {
+                    locationData = {
                         $type: "blob",
                         ref: { $link: uploadResult.data.blob.ref.toString() },
                         mimeType: uploadResult.data.blob.mimeType,
                         size: uploadResult.data.blob.size,
                     };
+                    locationType = "geojson-point";
+                }
+                else {
+                    throw new NetworkError("Failed to upload GeoJSON blob");
                 }
             }
+            else {
+                // Use value as a URI reference
+                locationData = {
+                    $type: "app.certified.defs#uri",
+                    uri: location.value,
+                };
+                locationType = "coordinate-decimal";
+            }
+            // Build location record according to app.certified.location lexicon
             const locationRecord = {
-                hypercert: { uri: hypercert.uri, cid: hypercert.cid },
-                value: locationValue,
+                $type: HYPERCERT_COLLECTIONS.LOCATION,
+                lpVersion: "1.0",
+                srs: location.srs,
+                locationType,
+                location: locationData,
                 createdAt,
                 name: location.name,
                 description: location.description,
-                srs: location.srs,
             };
             const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.LOCATION, locationRecord);
             if (!validation.valid) {
@@ -2700,10 +2799,12 @@ class HypercertOperationsImpl extends EventEmitter {
         try {
             const createdAt = new Date().toISOString();
             const contributionRecord = {
+                $type: HYPERCERT_COLLECTIONS.CONTRIBUTION,
                 contributors: params.contributors,
                 role: params.role,
                 createdAt,
                 description: params.description,
+                hypercert: { uri: "", cid: "" }, // Will be set below if hypercertUri provided
             };
             if (params.hypercertUri) {
                 const hypercert = await this.get(params.hypercertUri);
@@ -2764,6 +2865,7 @@ class HypercertOperationsImpl extends EventEmitter {
             const hypercert = await this.get(params.hypercertUri);
             const createdAt = new Date().toISOString();
             const measurementRecord = {
+                $type: HYPERCERT_COLLECTIONS.MEASUREMENT,
                 hypercert: { uri: hypercert.uri, cid: hypercert.cid },
                 measurers: params.measurers,
                 metric: params.metric,
@@ -2819,6 +2921,7 @@ class HypercertOperationsImpl extends EventEmitter {
             const subject = await this.get(params.subjectUri);
             const createdAt = new Date().toISOString();
             const evaluationRecord = {
+                $type: HYPERCERT_COLLECTIONS.EVALUATION,
                 subject: { uri: subject.uri, cid: subject.cid },
                 evaluators: params.evaluators,
                 summary: params.summary,
@@ -2893,6 +2996,7 @@ class HypercertOperationsImpl extends EventEmitter {
                 }
             }
             const collectionRecord = {
+                $type: HYPERCERT_COLLECTIONS.COLLECTION,
                 title: params.title,
                 claims: params.claims.map((c) => ({ claim: { uri: c.uri, cid: c.cid }, weight: c.weight })),
                 createdAt,
@@ -3771,11 +3875,10 @@ class Repository {
         this.lexiconRegistry = lexiconRegistry;
         this._isSDS = isSDS;
         this.logger = logger;
-        // Create Agent with OAuth session
-        this.agent = new Agent(session);
-        // Configure Agent to use the specified server URL (PDS or SDS)
-        // This ensures queries are routed to the correct server
-        this.agent.api.xrpc.uri = new URL(serverUrl);
+        // 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);
@@ -4625,5 +4728,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