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

package/dist/index.d.ts

@@ -766,9 +766,10 @@ declare const OrganizationSchema: z.ZodObject<{
     /**
      * 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: z.ZodEnum<["owner", "collaborator"]>;
+    accessType: z.ZodEnum<["owner", "shared", "none"]>;
 }, "strip", z.ZodTypeAny, {
     did: string;
     handle: string;
@@ -782,7 +783,7 @@ declare const OrganizationSchema: z.ZodObject<{
         admin: boolean;
         owner: boolean;
     };
-    accessType: "owner" | "collaborator";
+    accessType: "owner" | "shared" | "none";
     description?: string | undefined;
 }, {
     did: string;
@@ -797,7 +798,7 @@ declare const OrganizationSchema: z.ZodObject<{
         admin: boolean;
         owner: boolean;
     };
-    accessType: "owner" | "collaborator";
+    accessType: "owner" | "shared" | "none";
     description?: string | undefined;
 }>;
 /**
@@ -1022,7 +1023,7 @@ interface OrganizationInfo {
     name: string;
     description?: string;
     createdAt: string;
-    accessType: "owner" | "collaborator";
+    accessType: "owner" | "shared" | "none";
     permissions: CollaboratorPermissions;
     collaboratorCount?: number;
     profile?: {
@@ -1089,16 +1090,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.
  *
@@ -1845,6 +1836,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" });
  * ```
@@ -1873,9 +1875,18 @@ 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.
      *
@@ -1890,6 +1901,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.
@@ -1936,9 +1965,18 @@ 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/dist/index.mjs

@@ -1669,7 +1669,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,
             };
@@ -2176,7 +2176,7 @@ class HypercertOperationsImpl extends 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,
                         };
@@ -2601,7 +2601,7 @@ class HypercertOperationsImpl extends 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,
                     };
@@ -2886,7 +2886,7 @@ class HypercertOperationsImpl extends 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,
                     };
@@ -3040,9 +3040,11 @@ class HypercertOperationsImpl extends 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
@@ -3115,6 +3117,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.
      *
@@ -3144,7 +3166,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({
@@ -3176,7 +3198,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({
@@ -3191,7 +3213,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
@@ -3200,34 +3225,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.
@@ -3250,7 +3290,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 {
@@ -3272,10 +3312,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}`);
+        }
+    }
 }
 
 /**
@@ -3302,8 +3440,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
@@ -3381,10 +3519,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}`);
@@ -3396,8 +3541,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,
+            },
         };
     }
     /**
@@ -3424,8 +3576,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;
@@ -3434,7 +3586,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
@@ -3446,21 +3601,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}`);
@@ -3470,21 +3629,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,
+        };
     }
 }
 
@@ -4407,9 +4583,10 @@ const OrganizationSchema = 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: z.enum(["owner", "collaborator"]),
+    accessType: z.enum(["owner", "shared", "none"]),
 });
 /**
  * Zod schema for collaborator data.