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

package/dist/types.d.ts

@@ -1242,16 +1242,6 @@ interface HypercertWithMetadata {
     record: HypercertClaim;
 }
 
-/**
- * Repository interfaces - Operation contracts for repository functionality.
- *
- * This module defines the interfaces for all repository operations,
- * providing clear contracts for record management, blob handling,
- * profile management, and domain-specific operations.
- *
- * @packageDocumentation
- */
-
 /**
  * Parameters for creating a new hypercert.
  *
@@ -1998,6 +1988,17 @@ 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" });
  * ```
@@ -2043,6 +2044,24 @@ 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<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>;
 }
 /**
  * Organization operations for SDS organization management.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercerts-org/sdk-core",
-  "version": "0.2.0-beta.0",
+  "version": "0.4.0-beta.0",
   "description": "Framework-agnostic ATProto SDK core for authentication, repository operations, and lexicon management",
   "main": "dist/index.cjs",
   "repository": {
@@ -75,7 +75,7 @@
     "@atproto/oauth-client-node": "^0.3.10",
     "eventemitter3": "^5.0.1",
     "zod": "^3.24.4",
-    "@hypercerts-org/lexicon": "0.2.0-beta.0"
+    "@hypercerts-org/lexicon": "0.4.0-beta.0"
   },
   "scripts": {
     "test": "vitest",

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
@@ -135,7 +137,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 +171,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({
@@ -211,7 +213,7 @@ export class CollaboratorOperationsImpl implements CollaboratorOperations {
    */
   async list(): Promise<RepositoryAccessGrant[]> {
     const response = await this.session.fetchHandler(
-      `${this.serverUrl}/xrpc/com.atproto.sds.listCollaborators?repo=${encodeURIComponent(this.repoDid)}`,
+      `${this.serverUrl}/xrpc/com.sds.repo.listCollaborators?repo=${encodeURIComponent(this.repoDid)}`,
       { method: "GET" },
     );
 
@@ -285,4 +287,110 @@ export class CollaboratorOperationsImpl implements CollaboratorOperations {
     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/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,7 +109,7 @@ 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 response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.organization.create`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(params),
@@ -203,7 +203,7 @@ export class OrganizationOperationsImpl implements OrganizationOperations {
    */
   async list(): Promise<OrganizationInfo[]> {
     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?userDid=${encodeURIComponent(this.session.did || this.session.sub)}`,
       { method: "GET" },
     );
 

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" });
  * ```
@@ -817,6 +828,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>;
 }
 
 /**

package/tests/repository/CollaboratorOperationsImpl.test.ts

@@ -28,7 +28,7 @@ describe("CollaboratorOperationsImpl", () => {
       await collaboratorOps.grant({ userDid: "did:plc:newuser", role: "viewer" });
 
       expect(mockSession.fetchHandler).toHaveBeenCalledWith(
-        `${serverUrl}/xrpc/com.atproto.sds.grantAccess`,
+        `${serverUrl}/xrpc/com.sds.repo.grantAccess`,
         expect.objectContaining({
           method: "POST",
           body: expect.stringContaining('"read":true'),
@@ -88,9 +88,7 @@ describe("CollaboratorOperationsImpl", () => {
         statusText: "Forbidden",
       });
 
-      await expect(
-        collaboratorOps.grant({ userDid: "did:plc:newuser", role: "viewer" }),
-      ).rejects.toThrow(NetworkError);
+      await expect(collaboratorOps.grant({ userDid: "did:plc:newuser", role: "viewer" })).rejects.toThrow(NetworkError);
     });
   });
 
@@ -104,7 +102,7 @@ describe("CollaboratorOperationsImpl", () => {
       await collaboratorOps.revoke({ userDid: "did:plc:revokeduser" });
 
       expect(mockSession.fetchHandler).toHaveBeenCalledWith(
-        `${serverUrl}/xrpc/com.atproto.sds.revokeAccess`,
+        `${serverUrl}/xrpc/com.sds.repo.revokeAccess`,
         expect.objectContaining({
           method: "POST",
         }),
@@ -121,9 +119,7 @@ describe("CollaboratorOperationsImpl", () => {
         statusText: "Not Found",
       });
 
-      await expect(
-        collaboratorOps.revoke({ userDid: "did:plc:user" }),
-      ).rejects.toThrow(NetworkError);
+      await expect(collaboratorOps.revoke({ userDid: "did:plc:user" })).rejects.toThrow(NetworkError);
     });
   });
 
@@ -320,4 +316,123 @@ describe("CollaboratorOperationsImpl", () => {
       expect(result).toBeNull();
     });
   });
+
+  describe("getPermissions", () => {
+    it("should get current user permissions successfully", async () => {
+      mockSession.fetchHandler.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          permissions: {
+            read: true,
+            create: true,
+            update: true,
+            delete: false,
+            admin: false,
+            owner: false,
+          },
+        }),
+      });
+
+      const result = await collaboratorOps.getPermissions();
+
+      expect(mockSession.fetchHandler).toHaveBeenCalledWith(
+        `${serverUrl}/xrpc/com.sds.repo.getPermissions?repo=${encodeURIComponent(repoDid)}`,
+        expect.objectContaining({
+          method: "GET",
+        }),
+      );
+
+      expect(result.read).toBe(true);
+      expect(result.create).toBe(true);
+      expect(result.update).toBe(true);
+      expect(result.delete).toBe(false);
+      expect(result.admin).toBe(false);
+      expect(result.owner).toBe(false);
+    });
+
+    it("should handle owner permissions", async () => {
+      mockSession.fetchHandler.mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          permissions: {
+            read: true,
+            create: true,
+            update: true,
+            delete: true,
+            admin: true,
+            owner: true,
+          },
+        }),
+      });
+
+      const result = await collaboratorOps.getPermissions();
+
+      expect(result.owner).toBe(true);
+      expect(result.admin).toBe(true);
+    });
+
+    it("should throw NetworkError on failure", async () => {
+      mockSession.fetchHandler.mockResolvedValue({
+        ok: false,
+        statusText: "Forbidden",
+      });
+
+      await expect(collaboratorOps.getPermissions()).rejects.toThrow(NetworkError);
+    });
+  });
+
+  describe("transferOwnership", () => {
+    it("should transfer ownership successfully", async () => {
+      mockSession.fetchHandler.mockResolvedValue({
+        ok: true,
+        json: async () => ({}),
+      });
+
+      await collaboratorOps.transferOwnership({ newOwnerDid: "did:plc:new-owner" });
+
+      expect(mockSession.fetchHandler).toHaveBeenCalledWith(
+        `${serverUrl}/xrpc/com.sds.repo.transferOwnership`,
+        expect.objectContaining({
+          method: "POST",
+        }),
+      );
+
+      const body = JSON.parse(mockSession.fetchHandler.mock.calls[0][1].body);
+      expect(body.repo).toBe(repoDid);
+      expect(body.newOwner).toBe("did:plc:new-owner");
+    });
+
+    it("should throw NetworkError on failure", async () => {
+      mockSession.fetchHandler.mockResolvedValue({
+        ok: false,
+        statusText: "Forbidden",
+      });
+
+      await expect(collaboratorOps.transferOwnership({ newOwnerDid: "did:plc:new-owner" })).rejects.toThrow(
+        NetworkError,
+      );
+    });
+
+    it("should throw NetworkError when not owner", async () => {
+      mockSession.fetchHandler.mockResolvedValue({
+        ok: false,
+        statusText: "Forbidden: Only the owner can transfer ownership",
+      });
+
+      await expect(collaboratorOps.transferOwnership({ newOwnerDid: "did:plc:new-owner" })).rejects.toThrow(
+        NetworkError,
+      );
+    });
+
+    it("should throw NetworkError when new owner does not exist", async () => {
+      mockSession.fetchHandler.mockResolvedValue({
+        ok: false,
+        statusText: "Not Found: New owner DID not found",
+      });
+
+      await expect(collaboratorOps.transferOwnership({ newOwnerDid: "did:plc:nonexistent" })).rejects.toThrow(
+        NetworkError,
+      );
+    });
+  });
 });

package/tests/repository/OrganizationOperationsImpl.test.ts

@@ -44,7 +44,7 @@ describe("OrganizationOperationsImpl", () => {
       expect(result.permissions.owner).toBe(true);
 
       expect(mockSession.fetchHandler).toHaveBeenCalledWith(
-        `${serverUrl}/xrpc/com.atproto.sds.createRepository`,
+        `${serverUrl}/xrpc/com.sds.organization.create`,
         expect.objectContaining({
           method: "POST",
           headers: { "Content-Type": "application/json" },