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

package/dist/index.cjs

@@ -1670,7 +1670,7 @@ class BlobOperationsImpl {
                 throw new NetworkError("Failed to upload blob");
             }
             return {
-                ref: result.data.blob.ref,
+                ref: { $link: result.data.blob.ref.toString() },
                 mimeType: result.data.blob.mimeType,
                 size: result.data.blob.size,
             };
@@ -2177,7 +2177,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
                     if (uploadResult.success) {
                         imageBlobRef = {
                             $type: "blob",
-                            ref: uploadResult.data.blob.ref,
+                            ref: { $link: uploadResult.data.blob.ref.toString() },
                             mimeType: uploadResult.data.blob.mimeType,
                             size: uploadResult.data.blob.size,
                         };
@@ -2602,7 +2602,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
                 if (uploadResult.success) {
                     locationValue = {
                         $type: "blob",
-                        ref: uploadResult.data.blob.ref,
+                        ref: { $link: uploadResult.data.blob.ref.toString() },
                         mimeType: uploadResult.data.blob.mimeType,
                         size: uploadResult.data.blob.size,
                     };
@@ -2887,7 +2887,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
                 if (uploadResult.success) {
                     coverPhotoRef = {
                         $type: "blob",
-                        ref: uploadResult.data.blob.ref,
+                        ref: { $link: uploadResult.data.blob.ref.toString() },
                         mimeType: uploadResult.data.blob.mimeType,
                         size: uploadResult.data.blob.size,
                     };
@@ -3041,9 +3041,11 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
  * - `owner`: Full control including ownership management
  *
  * **SDS API Endpoints Used**:
- * - `com.atproto.sds.grantAccess`: Grant access to a user
- * - `com.atproto.sds.revokeAccess`: Revoke access from a user
- * - `com.atproto.sds.listCollaborators`: List all collaborators
+ * - `com.sds.repo.grantAccess`: Grant access to a user
+ * - `com.sds.repo.revokeAccess`: Revoke access from a user
+ * - `com.sds.repo.listCollaborators`: List all collaborators
+ * - `com.sds.repo.getPermissions`: Get current user's permissions
+ * - `com.sds.repo.transferOwnership`: Transfer repository ownership
  *
  * @example
  * ```typescript
@@ -3116,6 +3118,26 @@ class CollaboratorOperationsImpl {
             return "editor";
         return "viewer";
     }
+    /**
+     * Converts a permission string array to a permissions object.
+     *
+     * 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.
+     *
+     * @param permissionArray - Array of permission strings from SDS API
+     * @returns Permission flags object
+     * @internal
+     */
+    parsePermissions(permissionArray) {
+        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"),
+        };
+    }
     /**
      * Grants repository access to a user.
      *
@@ -3145,7 +3167,7 @@ class CollaboratorOperationsImpl {
      */
     async grant(params) {
         const permissions = this.roleToPermissions(params.role);
-        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.atproto.sds.grantAccess`, {
+        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.repo.grantAccess`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -3177,7 +3199,7 @@ class CollaboratorOperationsImpl {
      * ```
      */
     async revoke(params) {
-        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.atproto.sds.revokeAccess`, {
+        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.repo.revokeAccess`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -3192,7 +3214,10 @@ class CollaboratorOperationsImpl {
     /**
      * Lists all collaborators on the repository.
      *
-     * @returns Promise resolving to array of access grants
+     * @param params - Optional pagination parameters
+     * @param params.limit - Maximum number of results (1-100, default 50)
+     * @param params.cursor - Pagination cursor from previous response
+     * @returns Promise resolving to collaborators and optional cursor
      * @throws {@link NetworkError} if the list operation fails
      *
      * @remarks
@@ -3201,34 +3226,49 @@ class CollaboratorOperationsImpl {
      *
      * @example
      * ```typescript
-     * const collaborators = await repo.collaborators.list();
+     * // Get first page
+     * const page1 = await repo.collaborators.list({ limit: 10 });
+     * console.log(`Found ${page1.collaborators.length} collaborators`);
+     *
+     * // Get next page if available
+     * if (page1.cursor) {
+     *   const page2 = await repo.collaborators.list({ limit: 10, cursor: page1.cursor });
+     * }
      *
      * // Filter active collaborators
-     * const active = collaborators.filter(c => !c.revokedAt);
-     *
-     * // Group by role
-     * const byRole = {
-     *   owners: active.filter(c => c.role === "owner"),
-     *   admins: active.filter(c => c.role === "admin"),
-     *   editors: active.filter(c => c.role === "editor"),
-     *   viewers: active.filter(c => c.role === "viewer"),
-     * };
+     * const active = page1.collaborators.filter(c => !c.revokedAt);
      * ```
      */
-    async list() {
-        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.atproto.sds.listCollaborators?repo=${encodeURIComponent(this.repoDid)}`, { method: "GET" });
+    async list(params) {
+        const queryParams = new URLSearchParams({
+            repo: this.repoDid,
+        });
+        if (params?.limit !== undefined) {
+            queryParams.set("limit", params.limit.toString());
+        }
+        if (params?.cursor) {
+            queryParams.set("cursor", params.cursor);
+        }
+        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.repo.listCollaborators?${queryParams.toString()}`, { method: "GET" });
         if (!response.ok) {
             throw new NetworkError(`Failed to list collaborators: ${response.statusText}`);
         }
         const data = await response.json();
-        return (data.collaborators || []).map((c) => ({
-            userDid: c.userDid,
-            role: this.permissionsToRole(c.permissions),
-            permissions: c.permissions,
-            grantedBy: c.grantedBy,
-            grantedAt: c.grantedAt,
-            revokedAt: c.revokedAt,
-        }));
+        const collaborators = (data.collaborators || []).map((c) => {
+            const permissions = this.parsePermissions(c.permissions);
+            return {
+                userDid: c.userDid,
+                role: this.permissionsToRole(permissions),
+                permissions: permissions,
+                grantedBy: c.grantedBy,
+                grantedAt: c.grantedAt,
+                revokedAt: c.revokedAt,
+            };
+        });
+        return {
+            collaborators,
+            cursor: data.cursor,
+        };
     }
     /**
      * Checks if a user has any access to the repository.
@@ -3251,7 +3291,7 @@ class CollaboratorOperationsImpl {
      */
     async hasAccess(userDid) {
         try {
-            const collaborators = await this.list();
+            const { collaborators } = await this.list();
             return collaborators.some((c) => c.userDid === userDid && !c.revokedAt);
         }
         catch {
@@ -3273,10 +3313,108 @@ class CollaboratorOperationsImpl {
      * ```
      */
     async getRole(userDid) {
-        const collaborators = await this.list();
+        const { collaborators } = await this.list();
         const collab = collaborators.find((c) => c.userDid === userDid && !c.revokedAt);
         return collab?.role ?? null;
     }
+    /**
+     * Gets the current user's permissions for this repository.
+     *
+     * @returns Promise resolving to the permission flags
+     * @throws {@link NetworkError} if the request fails
+     *
+     * @remarks
+     * This is useful for checking what actions the current user can perform
+     * before attempting operations that might fail due to insufficient permissions.
+     *
+     * @example
+     * ```typescript
+     * const permissions = await repo.collaborators.getPermissions();
+     *
+     * if (permissions.admin) {
+     *   // Show admin UI
+     *   console.log("You can manage collaborators");
+     * }
+     *
+     * if (permissions.create) {
+     *   console.log("You can create records");
+     * }
+     * ```
+     *
+     * @example Conditional UI rendering
+     * ```typescript
+     * const permissions = await repo.collaborators.getPermissions();
+     *
+     * // Show/hide UI elements based on permissions
+     * const canEdit = permissions.update;
+     * const canDelete = permissions.delete;
+     * const isAdmin = permissions.admin;
+     * const isOwner = permissions.owner;
+     * ```
+     */
+    async getPermissions() {
+        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.repo.getPermissions?repo=${encodeURIComponent(this.repoDid)}`, { method: "GET" });
+        if (!response.ok) {
+            throw new NetworkError(`Failed to get permissions: ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data.permissions;
+    }
+    /**
+     * Transfers repository ownership to another user.
+     *
+     * @param params - Transfer parameters
+     * @param params.newOwnerDid - DID of the user to transfer ownership to
+     * @throws {@link NetworkError} if the transfer fails
+     *
+     * @remarks
+     * **IMPORTANT**: This action is irreversible. Once ownership is transferred:
+     * - The new owner gains full control of the repository
+     * - Your role will be changed to admin (or specified role)
+     * - You cannot transfer ownership back without the new owner's approval
+     *
+     * **Requirements**:
+     * - You must be the current owner
+     * - The new owner must have an existing account
+     * - The new owner will be notified of the ownership transfer
+     *
+     * @example
+     * ```typescript
+     * // Transfer ownership to another user
+     * await repo.collaborators.transferOwnership({
+     *   newOwnerDid: "did:plc:new-owner",
+     * });
+     *
+     * console.log("Ownership transferred successfully");
+     * // You are now an admin, not the owner
+     * ```
+     *
+     * @example With confirmation
+     * ```typescript
+     * const confirmTransfer = await askUser(
+     *   "Are you sure you want to transfer ownership? This cannot be undone."
+     * );
+     *
+     * if (confirmTransfer) {
+     *   await repo.collaborators.transferOwnership({
+     *     newOwnerDid: "did:plc:new-owner",
+     *   });
+     * }
+     * ```
+     */
+    async transferOwnership(params) {
+        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.repo.transferOwnership`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                repo: this.repoDid,
+                newOwner: params.newOwnerDid,
+            }),
+        });
+        if (!response.ok) {
+            throw new NetworkError(`Failed to transfer ownership: ${response.statusText}`);
+        }
+    }
 }
 
 /**
@@ -3303,8 +3441,8 @@ class CollaboratorOperationsImpl {
  * {@link Repository.organizations} on an SDS-connected repository.
  *
  * **SDS API Endpoints Used**:
- * - `com.atproto.sds.createRepository`: Create a new organization
- * - `com.atproto.sds.listRepositories`: List accessible organizations
+ * - `com.sds.organization.create`: Create a new organization
+ * - `com.sds.organization.list`: List accessible organizations
  *
  * **Access Types**:
  * - `"owner"`: User created or owns the organization
@@ -3382,10 +3520,17 @@ class OrganizationOperationsImpl {
      * ```
      */
     async create(params) {
-        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.atproto.sds.createRepository`, {
+        const userDid = this.session.did || this.session.sub;
+        if (!userDid) {
+            throw new NetworkError("No authenticated user found");
+        }
+        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.organization.create`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(params),
+            body: JSON.stringify({
+                ...params,
+                creatorDid: userDid,
+            }),
         });
         if (!response.ok) {
             throw new NetworkError(`Failed to create organization: ${response.statusText}`);
@@ -3397,8 +3542,15 @@ class OrganizationOperationsImpl {
             name: data.name,
             description: data.description,
             createdAt: data.createdAt || new Date().toISOString(),
-            accessType: "owner",
-            permissions: { read: true, create: true, update: true, delete: true, admin: true, owner: true },
+            accessType: data.accessType || "owner",
+            permissions: data.permissions || {
+                read: true,
+                create: true,
+                update: true,
+                delete: true,
+                admin: true,
+                owner: true,
+            },
         };
     }
     /**
@@ -3425,8 +3577,8 @@ class OrganizationOperationsImpl {
      */
     async get(did) {
         try {
-            const orgs = await this.list();
-            return orgs.find((o) => o.did === did) ?? null;
+            const { organizations } = await this.list();
+            return organizations.find((o) => o.did === did) ?? null;
         }
         catch {
             return null;
@@ -3435,7 +3587,10 @@ class OrganizationOperationsImpl {
     /**
      * Lists organizations the current user has access to.
      *
-     * @returns Promise resolving to array of organization info
+     * @param params - Optional pagination parameters
+     * @param params.limit - Maximum number of results (1-100, default 50)
+     * @param params.cursor - Pagination cursor from previous response
+     * @returns Promise resolving to organizations and optional cursor
      * @throws {@link NetworkError} if the list operation fails
      *
      * @remarks
@@ -3447,21 +3602,25 @@ class OrganizationOperationsImpl {
      *
      * @example
      * ```typescript
-     * const orgs = await repo.organizations.list();
+     * // Get first page
+     * const page1 = await repo.organizations.list({ limit: 20 });
+     * console.log(`Found ${page1.organizations.length} organizations`);
      *
-     * // Filter by access type
-     * const owned = orgs.filter(o => o.accessType === "owner");
-     * const collaborated = orgs.filter(o => o.accessType === "collaborator");
+     * // Get next page if available
+     * if (page1.cursor) {
+     *   const page2 = await repo.organizations.list({ limit: 20, cursor: page1.cursor });
+     * }
      *
-     * console.log(`You own ${owned.length} organizations`);
-     * console.log(`You collaborate on ${collaborated.length} organizations`);
+     * // Filter by access type
+     * const owned = page1.organizations.filter(o => o.accessType === "owner");
+     * const shared = page1.organizations.filter(o => o.accessType === "shared");
      * ```
      *
      * @example Display organization details
      * ```typescript
-     * const orgs = await repo.organizations.list();
+     * const { organizations } = await repo.organizations.list();
      *
-     * for (const org of orgs) {
+     * for (const org of organizations) {
      *   console.log(`${org.name} (@${org.handle})`);
      *   console.log(`  DID: ${org.did}`);
      *   console.log(`  Access: ${org.accessType}`);
@@ -3471,21 +3630,38 @@ class OrganizationOperationsImpl {
      * }
      * ```
      */
-    async list() {
-        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.atproto.sds.listRepositories?userDid=${encodeURIComponent(this.session.did || this.session.sub)}`, { method: "GET" });
+    async list(params) {
+        const userDid = this.session.did || this.session.sub;
+        if (!userDid) {
+            throw new NetworkError("No authenticated user found");
+        }
+        const queryParams = new URLSearchParams({
+            userDid,
+        });
+        if (params?.limit !== undefined) {
+            queryParams.set("limit", params.limit.toString());
+        }
+        if (params?.cursor) {
+            queryParams.set("cursor", params.cursor);
+        }
+        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.organization.list?${queryParams.toString()}`, { method: "GET" });
         if (!response.ok) {
             throw new NetworkError(`Failed to list organizations: ${response.statusText}`);
         }
         const data = await response.json();
-        return (data.repositories || []).map((r) => ({
+        const organizations = (data.organizations || []).map((r) => ({
             did: r.did,
             handle: r.handle,
             name: r.name,
             description: r.description,
-            createdAt: new Date().toISOString(), // SDS may not return this
+            createdAt: r.createdAt || new Date().toISOString(),
             accessType: r.accessType,
             permissions: r.permissions,
         }));
+        return {
+            organizations,
+            cursor: data.cursor,
+        };
     }
 }
 
@@ -4408,9 +4584,10 @@ const OrganizationSchema = zod.z.object({
     /**
      * How the current user relates to this organization.
      * - `"owner"`: User created or owns the organization
-     * - `"collaborator"`: User was invited to collaborate
+     * - `"shared"`: User was invited to collaborate (has permissions)
+     * - `"none"`: User has no access to this organization
      */
-    accessType: zod.z.enum(["owner", "collaborator"]),
+    accessType: zod.z.enum(["owner", "shared", "none"]),
 });
 /**
  * Zod schema for collaborator data.