Merge pull request #55 from hypercerts-org/fix/sds_endpoints_and_namespaces

Endpoints and nsids for sds operations

Author: bitbeckers

.changeset/fix-sds-endpoints-and-nsids.md

@@ -0,0 +1,7 @@
+---
+"@hypercerts-org/sdk-core": patch
+"@hypercerts-org/lexicon": patch
+"@hypercerts-org/sdk-react": patch
+---
+
+Fix endpoints and NSIDs for SDS operations in CollaboratorOperations and OrganizationOperations

.changeset/ignore-local-npmrc.md

@@ -0,0 +1,4 @@
+---
+---
+
+Ignore local npmrc file in git

packages/lexicon/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercerts-org/lexicon",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "ATProto lexicon definitions and TypeScript types for the Hypercerts protocol",
   "type": "module",
   "main": "dist/index.cjs",

packages/sdk-core/README.md

@@ -77,14 +77,57 @@ const existingSession = await sdk.restoreSession("did:plc:...");
 
 ```
 repo
-├── .records      → create, get, update, delete, list
-├── .blobs        → upload, get
-├── .profile      → get, update
-├── .hypercerts   → create, get, update, delete, list, addContribution, addMeasurement
-├── .collaborators → grant, revoke, list, hasAccess (SDS only)
+├── .records       → create, get, update, delete, list
+├── .blobs         → upload, get
+├── .profile       → get, update (PDS only)
+├── .hypercerts    → create, get, update, delete, list, addContribution, addMeasurement
+├── .collaborators → grant, revoke, list, hasAccess, getRole, getPermissions, transferOwnership (SDS only)
 └── .organizations → create, get, list (SDS only)
 ```
 
+### Collaborator Operations (SDS only)
+
+```typescript
+// Grant access to a user
+await repo.collaborators.grant({
+  userDid: "did:plc:user123",
+  role: "editor", // viewer | editor | admin | owner
+});
+
+// Revoke access
+await repo.collaborators.revoke({ userDid: "did:plc:user123" });
+
+// List all collaborators
+const collaborators = await repo.collaborators.list();
+
+// Check if user has access
+const hasAccess = await repo.collaborators.hasAccess("did:plc:user123");
+
+// Get user's role
+const role = await repo.collaborators.getRole("did:plc:user123");
+
+// Get current user's permissions
+const permissions = await repo.collaborators.getPermissions();
+if (permissions.admin) {
+  // Can manage collaborators
+}
+
+// Transfer ownership (irreversible!)
+await repo.collaborators.transferOwnership({
+  newOwnerDid: "did:plc:new-owner",
+});
+```
+
+### SDS vs PDS Operations
+
+| Operation | PDS | SDS | Namespace |
+|-----------|-----|-----|-----------|
+| Records (CRUD) | ✅ | ✅ | `com.atproto.repo.*` |
+| Blobs | ✅ | ✅ | `com.atproto.repo.uploadBlob`, `com.atproto.sync.getBlob` |
+| Profile | ✅ | ❌ | `app.bsky.actor.profile` |
+| Organizations | ❌ | ✅ | `com.sds.organization.*` |
+| Collaborators | ❌ | ✅ | `com.sds.repo.*` |
+
 ## Errors
 
 ```typescript

packages/sdk-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercerts-org/sdk-core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic ATProto SDK core for authentication, repository operations, and lexicon management",
   "main": "dist/index.cjs",
   "repository": {

packages/sdk-core/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}`);
+    }
+  }
 }

packages/sdk-core/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" },
     );
 

packages/sdk-core/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>;
 }
 
 /**