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

package/src/repository/CollaboratorOperationsImpl.ts

@@ -30,9 +30,11 @@ import type { RepositoryRole, RepositoryAccessGrant } from "./types.js";
  * - `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
@@ -105,6 +107,27 @@ export class CollaboratorOperationsImpl implements CollaboratorOperations {
     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
+   */
+  private parsePermissions(permissionArray: string[]): CollaboratorPermissions {
+    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.
    *
@@ -135,7 +158,7 @@ export class CollaboratorOperationsImpl implements CollaboratorOperations {
   async grant(params: { userDid: string; role: RepositoryRole }): Promise<void> {
     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({
@@ -169,7 +192,7 @@ export class CollaboratorOperationsImpl implements CollaboratorOperations {
    * ```
    */
   async revoke(params: { userDid: string }): Promise<void> {
-    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({
@@ -186,7 +209,10 @@ export class CollaboratorOperationsImpl implements CollaboratorOperations {
   /**
    * 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
@@ -195,23 +221,37 @@ export class CollaboratorOperationsImpl implements CollaboratorOperations {
    *
    * @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(): Promise<RepositoryAccessGrant[]> {
+  async list(params?: { limit?: number; cursor?: string }): Promise<{
+    collaborators: RepositoryAccessGrant[];
+    cursor?: string;
+  }> {
+    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.atproto.sds.listCollaborators?repo=${encodeURIComponent(this.repoDid)}`,
+      `${this.serverUrl}/xrpc/com.sds.repo.listCollaborators?${queryParams.toString()}`,
       { method: "GET" },
     );
 
@@ -220,22 +260,30 @@ export class CollaboratorOperationsImpl implements CollaboratorOperations {
     }
 
     const data = await response.json();
-    return (data.collaborators || []).map(
+    const collaborators = (data.collaborators || []).map(
       (c: {
         userDid: string;
-        permissions: CollaboratorPermissions;
+        permissions: string[]; // SDS API returns string array
         grantedBy: string;
         grantedAt: string;
         revokedAt?: string;
-      }) => ({
-        userDid: c.userDid,
-        role: this.permissionsToRole(c.permissions),
-        permissions: c.permissions,
-        grantedBy: c.grantedBy,
-        grantedAt: c.grantedAt,
-        revokedAt: c.revokedAt,
-      }),
+      }) => {
+        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,
+    };
   }
 
   /**
@@ -259,7 +307,7 @@ export class CollaboratorOperationsImpl implements CollaboratorOperations {
    */
   async hasAccess(userDid: string): Promise<boolean> {
     try {
-      const collaborators = await this.list();
+      const { collaborators } = await this.list();
       return collaborators.some((c) => c.userDid === userDid && !c.revokedAt);
     } catch {
       return false;
@@ -281,8 +329,114 @@ export class CollaboratorOperationsImpl implements CollaboratorOperations {
    * ```
    */
   async getRole(userDid: string): Promise<RepositoryRole | null> {
-    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(): Promise<CollaboratorPermissions> {
+    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 as CollaboratorPermissions;
+  }
+
+  /**
+   * 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: { newOwnerDid: string }): Promise<void> {
+    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}`);
+    }
+  }
 }

package/src/repository/HypercertOperationsImpl.ts

@@ -208,7 +208,7 @@ export class HypercertOperationsImpl extends EventEmitter<HypercertEvents> imple
           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,
             };
@@ -676,7 +676,7 @@ export class HypercertOperationsImpl extends EventEmitter<HypercertEvents> imple
         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,
           };
@@ -999,7 +999,7 @@ export class HypercertOperationsImpl extends EventEmitter<HypercertEvents> imple
         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,
           };

package/src/repository/OrganizationOperationsImpl.ts

@@ -29,8 +29,8 @@ import type { OrganizationInfo } from "./types.js";
  * {@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
@@ -109,10 +109,18 @@ export class OrganizationOperationsImpl implements OrganizationOperations {
    * ```
    */
   async create(params: { name: string; description?: string; handle?: string }): Promise<OrganizationInfo> {
-    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) {
@@ -126,8 +134,15 @@ export class OrganizationOperationsImpl implements OrganizationOperations {
       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,
+      },
     };
   }
 
@@ -155,8 +170,8 @@ export class OrganizationOperationsImpl implements OrganizationOperations {
    */
   async get(did: string): Promise<OrganizationInfo | null> {
     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;
     }
@@ -165,7 +180,10 @@ export class OrganizationOperationsImpl implements OrganizationOperations {
   /**
    * 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
@@ -177,21 +195,25 @@ export class OrganizationOperationsImpl implements OrganizationOperations {
    *
    * @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}`);
@@ -201,9 +223,29 @@ export class OrganizationOperationsImpl implements OrganizationOperations {
    * }
    * ```
    */
-  async list(): Promise<OrganizationInfo[]> {
+  async list(params?: { limit?: number; cursor?: string }): Promise<{
+    organizations: OrganizationInfo[];
+    cursor?: string;
+  }> {
+    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.atproto.sds.listRepositories?userDid=${encodeURIComponent(this.session.did || this.session.sub)}`,
+      `${this.serverUrl}/xrpc/com.sds.organization.list?${queryParams.toString()}`,
       { method: "GET" },
     );
 
@@ -212,23 +254,29 @@ export class OrganizationOperationsImpl implements OrganizationOperations {
     }
 
     const data = await response.json();
-    return (data.repositories || []).map(
+    const organizations = (data.organizations || []).map(
       (r: {
         did: string;
         handle: string;
         name: string;
         description?: string;
-        accessType: "owner" | "collaborator";
+        createdAt?: string;
+        accessType: "owner" | "shared" | "none";
         permissions: CollaboratorPermissions;
       }) => ({
         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,
+    };
   }
 }

package/src/repository/interfaces.ts

@@ -773,6 +773,17 @@ export interface HypercertOperations extends EventEmitter<HypercertEvents> {
  * const hasAccess = await repo.collaborators.hasAccess("did:plc:someone");
  * const role = await repo.collaborators.getRole("did:plc:someone");
  *
+ * // Get current user permissions
+ * const permissions = await repo.collaborators.getPermissions();
+ * if (permissions.admin) {
+ *   // Can manage collaborators
+ * }
+ *
+ * // Transfer ownership
+ * await repo.collaborators.transferOwnership({
+ *   newOwnerDid: "did:plc:new-owner",
+ * });
+ *
  * // Revoke access
  * await repo.collaborators.revoke({ userDid: "did:plc:former-user" });
  * ```
@@ -798,9 +809,15 @@ export interface CollaboratorOperations {
   /**
    * 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
    */
-  list(): Promise<RepositoryAccessGrant[]>;
+  list(params?: { limit?: number; cursor?: string }): Promise<{
+    collaborators: RepositoryAccessGrant[];
+    cursor?: string;
+  }>;
 
   /**
    * Checks if a user has any access to the repository.
@@ -817,6 +834,24 @@ export interface CollaboratorOperations {
    * @returns Promise resolving to role, or `null` if no access
    */
   getRole(userDid: string): Promise<RepositoryRole | null>;
+
+  /**
+   * Gets the current user's permissions for this repository.
+   *
+   * @returns Promise resolving to permission flags
+   */
+  getPermissions(): Promise<import("../core/types.js").CollaboratorPermissions>;
+
+  /**
+   * Transfers repository ownership to another user.
+   *
+   * **WARNING**: This action is irreversible. The new owner will have
+   * full control of the repository.
+   *
+   * @param params - Transfer parameters
+   * @param params.newOwnerDid - DID of the user to transfer ownership to
+   */
+  transferOwnership(params: { newOwnerDid: string }): Promise<void>;
 }
 
 /**
@@ -862,7 +897,13 @@ export interface OrganizationOperations {
   /**
    * 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
    */
-  list(): Promise<OrganizationInfo[]>;
+  list(params?: { limit?: number; cursor?: string }): Promise<{
+    organizations: OrganizationInfo[];
+    cursor?: string;
+  }>;
 }

package/src/repository/types.ts

@@ -85,7 +85,7 @@ export interface OrganizationInfo {
   name: string;
   description?: string;
   createdAt: string;
-  accessType: "owner" | "collaborator";
+  accessType: "owner" | "shared" | "none";
   permissions: CollaboratorPermissions;
   collaboratorCount?: number;
   profile?: {

package/tests/repository/BlobOperationsImpl.test.ts

@@ -28,11 +28,14 @@ describe("BlobOperationsImpl", () => {
   describe("upload", () => {
     it("should upload a blob successfully", async () => {
       const mockBlob = new Blob(["test content"], { type: "text/plain" });
+      const mockCID = {
+        toString: () => "bafyrei123",
+      };
       mockAgent.com.atproto.repo.uploadBlob.mockResolvedValue({
         success: true,
         data: {
           blob: {
-            ref: { $link: "bafyrei123" },
+            ref: mockCID,
             mimeType: "text/plain",
             size: 12,
           },
@@ -61,10 +64,9 @@ describe("BlobOperationsImpl", () => {
 
       await blobOps.upload(mockBlob);
 
-      expect(mockAgent.com.atproto.repo.uploadBlob).toHaveBeenCalledWith(
-        expect.any(Uint8Array),
-        { encoding: "image/png" },
-      );
+      expect(mockAgent.com.atproto.repo.uploadBlob).toHaveBeenCalledWith(expect.any(Uint8Array), {
+        encoding: "image/png",
+      });
     });
 
     it("should default to application/octet-stream for blobs without type", async () => {
@@ -82,10 +84,9 @@ describe("BlobOperationsImpl", () => {
 
       await blobOps.upload(mockBlob);
 
-      expect(mockAgent.com.atproto.repo.uploadBlob).toHaveBeenCalledWith(
-        expect.any(Uint8Array),
-        { encoding: "application/octet-stream" },
-      );
+      expect(mockAgent.com.atproto.repo.uploadBlob).toHaveBeenCalledWith(expect.any(Uint8Array), {
+        encoding: "application/octet-stream",
+      });
     });
 
     it("should throw NetworkError when API returns success: false", async () => {