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

package/src/repository/ProfileOperationsImpl.ts

@@ -0,0 +1,281 @@
+/**
+ * ProfileOperationsImpl - User profile operations.
+ *
+ * This module provides the implementation for AT Protocol profile
+ * management, including fetching and updating user profiles.
+ *
+ * @packageDocumentation
+ */
+
+import type { Agent } from "@atproto/api";
+import { NetworkError } from "../core/errors.js";
+import type { ProfileOperations } from "./interfaces.js";
+import type { UpdateResult } from "./types.js";
+
+/**
+ * Implementation of profile operations for user profile management.
+ *
+ * Profiles in AT Protocol are stored as records in the `app.bsky.actor.profile`
+ * collection with the special rkey "self". This class provides a convenient
+ * API for reading and updating profile data.
+ *
+ * @remarks
+ * This class is typically not instantiated directly. Access it through
+ * {@link Repository.profile}.
+ *
+ * **Profile Fields**:
+ * - `handle`: Read-only, managed by the PDS
+ * - `displayName`: User's display name (max 64 chars typically)
+ * - `description`: Profile bio (max 256 chars typically)
+ * - `avatar`: Profile picture blob reference
+ * - `banner`: Banner image blob reference
+ * - `website`: User's website URL (may not be available on all servers)
+ *
+ * @example
+ * ```typescript
+ * // Get profile
+ * const profile = await repo.profile.get();
+ * console.log(`${profile.displayName} (@${profile.handle})`);
+ *
+ * // Update profile
+ * await repo.profile.update({
+ *   displayName: "New Name",
+ *   description: "Updated bio",
+ * });
+ *
+ * // Update with new avatar
+ * const avatarBlob = new Blob([imageData], { type: "image/png" });
+ * await repo.profile.update({ avatar: avatarBlob });
+ *
+ * // Remove a field
+ * await repo.profile.update({ website: null });
+ * ```
+ *
+ * @internal
+ */
+export class ProfileOperationsImpl implements ProfileOperations {
+  /**
+   * Creates a new ProfileOperationsImpl.
+   *
+   * @param agent - AT Protocol Agent for making API calls
+   * @param repoDid - DID of the repository/user
+   * @param _serverUrl - Server URL (reserved for future use)
+   *
+   * @internal
+   */
+  constructor(
+    private agent: Agent,
+    private repoDid: string,
+    private _serverUrl: string,
+  ) {}
+
+  /**
+   * Gets the repository's profile.
+   *
+   * @returns Promise resolving to profile data
+   * @throws {@link NetworkError} if the profile cannot be fetched
+   *
+   * @remarks
+   * This method fetches the full profile using the `getProfile` API,
+   * which includes resolved information like follower counts on some
+   * servers. For hypercerts SDK usage, the basic profile fields are
+   * returned.
+   *
+   * **Note**: The `website` field may not be available on all AT Protocol
+   * servers. Standard Bluesky profiles don't include this field.
+   *
+   * @example
+   * ```typescript
+   * const profile = await repo.profile.get();
+   *
+   * console.log(`Handle: @${profile.handle}`);
+   * console.log(`Name: ${profile.displayName || "(not set)"}`);
+   * console.log(`Bio: ${profile.description || "(no bio)"}`);
+   *
+   * if (profile.avatar) {
+   *   // Avatar is a URL or blob reference
+   *   console.log(`Avatar: ${profile.avatar}`);
+   * }
+   * ```
+   */
+  async get(): Promise<{
+    handle: string;
+    displayName?: string;
+    description?: string;
+    avatar?: string;
+    banner?: string;
+    website?: string;
+  }> {
+    try {
+      const result = await this.agent.getProfile({ actor: this.repoDid });
+
+      if (!result.success) {
+        throw new NetworkError("Failed to get profile");
+      }
+
+      return {
+        handle: result.data.handle,
+        displayName: result.data.displayName,
+        description: result.data.description,
+        avatar: result.data.avatar,
+        banner: result.data.banner,
+        // Note: website may not be available in standard profile
+      };
+    } catch (error) {
+      if (error instanceof NetworkError) throw error;
+      throw new NetworkError(
+        `Failed to get profile: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error,
+      );
+    }
+  }
+
+  /**
+   * Updates the repository's profile.
+   *
+   * @param params - Fields to update. Pass `null` to remove a field.
+   *                 Omitted fields are preserved from the existing profile.
+   * @returns Promise resolving to update result with new URI and CID
+   * @throws {@link NetworkError} if the update fails
+   *
+   * @remarks
+   * This method performs a read-modify-write operation:
+   * 1. Fetches the existing profile record
+   * 2. Merges in the provided updates
+   * 3. Writes the updated profile back
+   *
+   * **Image Handling**: When providing `avatar` or `banner` as a Blob,
+   * the image is automatically uploaded and the blob reference is stored
+   * in the profile.
+   *
+   * **Field Removal**: Pass `null` to explicitly remove a field. Omitting
+   * a field (not including it in params) preserves the existing value.
+   *
+   * @example Update display name and bio
+   * ```typescript
+   * await repo.profile.update({
+   *   displayName: "Alice",
+   *   description: "Building impact certificates",
+   * });
+   * ```
+   *
+   * @example Update avatar image
+   * ```typescript
+   * // From a file input
+   * const file = document.getElementById("avatar").files[0];
+   * await repo.profile.update({ avatar: file });
+   *
+   * // From raw data
+   * const response = await fetch("https://example.com/my-avatar.png");
+   * const blob = await response.blob();
+   * await repo.profile.update({ avatar: blob });
+   * ```
+   *
+   * @example Remove description
+   * ```typescript
+   * // Removes the description field entirely
+   * await repo.profile.update({ description: null });
+   * ```
+   *
+   * @example Multiple updates at once
+   * ```typescript
+   * const newAvatar = new Blob([avatarData], { type: "image/png" });
+   * const newBanner = new Blob([bannerData], { type: "image/jpeg" });
+   *
+   * await repo.profile.update({
+   *   displayName: "New Name",
+   *   description: "New bio",
+   *   avatar: newAvatar,
+   *   banner: newBanner,
+   * });
+   * ```
+   */
+  async update(params: {
+    displayName?: string | null;
+    description?: string | null;
+    avatar?: Blob | null;
+    banner?: Blob | null;
+    website?: string | null;
+  }): Promise<UpdateResult> {
+    try {
+      // Get existing profile record
+      const existing = await this.agent.com.atproto.repo.getRecord({
+        repo: this.repoDid,
+        collection: "app.bsky.actor.profile",
+        rkey: "self",
+      });
+
+      const existingProfile = (existing.data.value as Record<string, unknown>) || {};
+
+      // Build updated profile
+      const updatedProfile: Record<string, unknown> = { ...existingProfile };
+
+      if (params.displayName !== undefined) {
+        if (params.displayName === null) {
+          delete updatedProfile.displayName;
+        } else {
+          updatedProfile.displayName = params.displayName;
+        }
+      }
+
+      if (params.description !== undefined) {
+        if (params.description === null) {
+          delete updatedProfile.description;
+        } else {
+          updatedProfile.description = params.description;
+        }
+      }
+
+      // Handle avatar upload
+      if (params.avatar !== undefined) {
+        if (params.avatar === null) {
+          delete updatedProfile.avatar;
+        } else {
+          const arrayBuffer = await params.avatar.arrayBuffer();
+          const uint8Array = new Uint8Array(arrayBuffer);
+          const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
+            encoding: params.avatar.type || "image/jpeg",
+          });
+          if (uploadResult.success) {
+            updatedProfile.avatar = uploadResult.data.blob;
+          }
+        }
+      }
+
+      // Handle banner upload
+      if (params.banner !== undefined) {
+        if (params.banner === null) {
+          delete updatedProfile.banner;
+        } else {
+          const arrayBuffer = await params.banner.arrayBuffer();
+          const uint8Array = new Uint8Array(arrayBuffer);
+          const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
+            encoding: params.banner.type || "image/jpeg",
+          });
+          if (uploadResult.success) {
+            updatedProfile.banner = uploadResult.data.blob;
+          }
+        }
+      }
+
+      const result = await this.agent.com.atproto.repo.putRecord({
+        repo: this.repoDid,
+        collection: "app.bsky.actor.profile",
+        rkey: "self",
+        record: updatedProfile,
+      });
+
+      if (!result.success) {
+        throw new NetworkError("Failed to update profile");
+      }
+
+      return { uri: result.data.uri, cid: result.data.cid };
+    } catch (error) {
+      if (error instanceof NetworkError) throw error;
+      throw new NetworkError(
+        `Failed to update profile: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error,
+      );
+    }
+  }
+}

package/src/repository/RecordOperationsImpl.ts

@@ -0,0 +1,340 @@
+/**
+ * RecordOperationsImpl - Low-level record CRUD operations.
+ *
+ * This module provides the implementation for direct AT Protocol
+ * record operations (create, read, update, delete, list).
+ *
+ * @packageDocumentation
+ */
+
+import type { Agent } from "@atproto/api";
+import { NetworkError, ValidationError } from "../core/errors.js";
+import type { LexiconRegistry } from "./LexiconRegistry.js";
+import type { RecordOperations } from "./interfaces.js";
+import type { CreateResult, UpdateResult, PaginatedList } from "./types.js";
+
+/**
+ * Implementation of low-level AT Protocol record operations.
+ *
+ * This class provides direct access to the AT Protocol repository API
+ * for CRUD operations on records. It handles:
+ *
+ * - Lexicon validation before create/update operations
+ * - Error mapping to SDK error types
+ * - Response normalization
+ *
+ * @remarks
+ * This class is typically not instantiated directly. Access it through
+ * {@link Repository.records}.
+ *
+ * All operations are performed against the repository DID specified
+ * at construction time. To operate on a different repository, create
+ * a new Repository instance using {@link Repository.repo}.
+ *
+ * @example
+ * ```typescript
+ * // Access through Repository
+ * const repo = sdk.repository(session);
+ *
+ * // Create a record
+ * const { uri, cid } = await repo.records.create({
+ *   collection: "org.example.myRecord",
+ *   record: { title: "Hello", createdAt: new Date().toISOString() },
+ * });
+ *
+ * // Update the record
+ * const rkey = uri.split("/").pop()!;
+ * await repo.records.update({
+ *   collection: "org.example.myRecord",
+ *   rkey,
+ *   record: { title: "Updated", createdAt: new Date().toISOString() },
+ * });
+ * ```
+ *
+ * @internal
+ */
+export class RecordOperationsImpl implements RecordOperations {
+  /**
+   * Creates a new RecordOperationsImpl.
+   *
+   * @param agent - AT Protocol Agent for making API calls
+   * @param repoDid - DID of the repository to operate on
+   * @param lexiconRegistry - Registry for record validation
+   *
+   * @internal
+   */
+  constructor(
+    private agent: Agent,
+    private repoDid: string,
+    private lexiconRegistry: LexiconRegistry,
+  ) {}
+
+  /**
+   * Creates a new record in the specified collection.
+   *
+   * @param params - Creation parameters
+   * @param params.collection - NSID of the collection (e.g., "org.hypercerts.hypercert")
+   * @param params.record - Record data conforming to the collection's lexicon schema
+   * @param params.rkey - Optional record key. If not provided, a TID (timestamp-based ID)
+   *                      is automatically generated by the server.
+   * @returns Promise resolving to the created record's URI and CID
+   * @throws {@link ValidationError} if the record doesn't conform to the lexicon schema
+   * @throws {@link NetworkError} if the API request fails
+   *
+   * @remarks
+   * The record is validated against the collection's lexicon before sending
+   * to the server. If no lexicon is registered for the collection, validation
+   * is skipped (allowing custom record types).
+   *
+   * **AT-URI Format**: `at://{did}/{collection}/{rkey}`
+   *
+   * @example
+   * ```typescript
+   * const result = await repo.records.create({
+   *   collection: "org.hypercerts.hypercert",
+   *   record: {
+   *     title: "My Hypercert",
+   *     description: "...",
+   *     createdAt: new Date().toISOString(),
+   *   },
+   * });
+   * console.log(`Created: ${result.uri}`);
+   * // Output: Created: at://did:plc:abc123/org.hypercerts.hypercert/xyz789
+   * ```
+   */
+  async create(params: { collection: string; record: unknown; rkey?: string }): Promise<CreateResult> {
+    const validation = this.lexiconRegistry.validate(params.collection, params.record);
+    if (!validation.valid) {
+      throw new ValidationError(`Invalid record for collection ${params.collection}: ${validation.error}`);
+    }
+
+    try {
+      const result = await this.agent.com.atproto.repo.createRecord({
+        repo: this.repoDid,
+        collection: params.collection,
+        record: params.record as Record<string, unknown>,
+        rkey: params.rkey,
+      });
+
+      if (!result.success) {
+        throw new NetworkError("Failed to create record");
+      }
+
+      return { uri: result.data.uri, cid: result.data.cid };
+    } catch (error) {
+      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
+      throw new NetworkError(
+        `Failed to create record: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error,
+      );
+    }
+  }
+
+  /**
+   * Updates an existing record (full replacement).
+   *
+   * @param params - Update parameters
+   * @param params.collection - NSID of the collection
+   * @param params.rkey - Record key (the last segment of the AT-URI)
+   * @param params.record - New record data (completely replaces existing record)
+   * @returns Promise resolving to the updated record's URI and new CID
+   * @throws {@link ValidationError} if the record doesn't conform to the lexicon schema
+   * @throws {@link NetworkError} if the API request fails
+   *
+   * @remarks
+   * This is a full replacement operation, not a partial update. The entire
+   * record is replaced with the new data. To preserve existing fields,
+   * first fetch the record with {@link get}, modify it, then update.
+   *
+   * @example
+   * ```typescript
+   * // Get existing record
+   * const existing = await repo.records.get({
+   *   collection: "org.hypercerts.hypercert",
+   *   rkey: "xyz789",
+   * });
+   *
+   * // Update with modified data
+   * const updated = await repo.records.update({
+   *   collection: "org.hypercerts.hypercert",
+   *   rkey: "xyz789",
+   *   record: {
+   *     ...existing.value,
+   *     title: "Updated Title",
+   *   },
+   * });
+   * ```
+   */
+  async update(params: { collection: string; rkey: string; record: unknown }): Promise<UpdateResult> {
+    const validation = this.lexiconRegistry.validate(params.collection, params.record);
+    if (!validation.valid) {
+      throw new ValidationError(`Invalid record for collection ${params.collection}: ${validation.error}`);
+    }
+
+    try {
+      const result = await this.agent.com.atproto.repo.putRecord({
+        repo: this.repoDid,
+        collection: params.collection,
+        rkey: params.rkey,
+        record: params.record as Record<string, unknown>,
+      });
+
+      if (!result.success) {
+        throw new NetworkError("Failed to update record");
+      }
+
+      return { uri: result.data.uri, cid: result.data.cid };
+    } catch (error) {
+      if (error instanceof ValidationError || error instanceof NetworkError) throw error;
+      throw new NetworkError(
+        `Failed to update record: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error,
+      );
+    }
+  }
+
+  /**
+   * Gets a single record by collection and key.
+   *
+   * @param params - Get parameters
+   * @param params.collection - NSID of the collection
+   * @param params.rkey - Record key
+   * @returns Promise resolving to the record's URI, CID, and value
+   * @throws {@link NetworkError} if the record is not found or request fails
+   *
+   * @example
+   * ```typescript
+   * const record = await repo.records.get({
+   *   collection: "org.hypercerts.hypercert",
+   *   rkey: "xyz789",
+   * });
+   *
+   * console.log(record.uri);    // at://did:plc:abc123/org.hypercerts.hypercert/xyz789
+   * console.log(record.cid);    // bafyrei...
+   * console.log(record.value);  // { title: "...", description: "...", ... }
+   * ```
+   */
+  async get(params: { collection: string; rkey: string }): Promise<{ uri: string; cid: string; value: unknown }> {
+    try {
+      const result = await this.agent.com.atproto.repo.getRecord({
+        repo: this.repoDid,
+        collection: params.collection,
+        rkey: params.rkey,
+      });
+
+      if (!result.success) {
+        throw new NetworkError("Failed to get record");
+      }
+
+      return { uri: result.data.uri, cid: result.data.cid ?? "", value: result.data.value };
+    } catch (error) {
+      if (error instanceof NetworkError) throw error;
+      throw new NetworkError(
+        `Failed to get record: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error,
+      );
+    }
+  }
+
+  /**
+   * Lists records in a collection with pagination.
+   *
+   * @param params - List parameters
+   * @param params.collection - NSID of the collection
+   * @param params.limit - Maximum number of records to return (server may impose its own limit)
+   * @param params.cursor - Pagination cursor from a previous response
+   * @returns Promise resolving to paginated list of records
+   * @throws {@link NetworkError} if the request fails
+   *
+   * @remarks
+   * Records are returned in reverse chronological order (newest first).
+   * Use the `cursor` from the response to fetch subsequent pages.
+   *
+   * @example Paginating through all records
+   * ```typescript
+   * let cursor: string | undefined;
+   * const allRecords = [];
+   *
+   * do {
+   *   const page = await repo.records.list({
+   *     collection: "org.hypercerts.hypercert",
+   *     limit: 100,
+   *     cursor,
+   *   });
+   *   allRecords.push(...page.records);
+   *   cursor = page.cursor;
+   * } while (cursor);
+   *
+   * console.log(`Total records: ${allRecords.length}`);
+   * ```
+   */
+  async list(params: {
+    collection: string;
+    limit?: number;
+    cursor?: string;
+  }): Promise<PaginatedList<{ uri: string; cid: string; value: unknown }>> {
+    try {
+      const result = await this.agent.com.atproto.repo.listRecords({
+        repo: this.repoDid,
+        collection: params.collection,
+        limit: params.limit,
+        cursor: params.cursor,
+      });
+
+      if (!result.success) {
+        throw new NetworkError("Failed to list records");
+      }
+
+      return {
+        records: result.data.records?.map((r) => ({ uri: r.uri, cid: r.cid, value: r.value })) || [],
+        cursor: result.data.cursor ?? undefined,
+      };
+    } catch (error) {
+      if (error instanceof NetworkError) throw error;
+      throw new NetworkError(
+        `Failed to list records: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error,
+      );
+    }
+  }
+
+  /**
+   * Deletes a record from a collection.
+   *
+   * @param params - Delete parameters
+   * @param params.collection - NSID of the collection
+   * @param params.rkey - Record key to delete
+   * @throws {@link NetworkError} if the deletion fails
+   *
+   * @remarks
+   * Deletion is permanent. The record's AT-URI cannot be reused (the same
+   * rkey can be used for a new record, but it will have a different CID).
+   *
+   * @example
+   * ```typescript
+   * await repo.records.delete({
+   *   collection: "org.hypercerts.hypercert",
+   *   rkey: "xyz789",
+   * });
+   * ```
+   */
+  async delete(params: { collection: string; rkey: string }): Promise<void> {
+    try {
+      const result = await this.agent.com.atproto.repo.deleteRecord({
+        repo: this.repoDid,
+        collection: params.collection,
+        rkey: params.rkey,
+      });
+
+      if (!result.success) {
+        throw new NetworkError("Failed to delete record");
+      }
+    } catch (error) {
+      if (error instanceof NetworkError) throw error;
+      throw new NetworkError(
+        `Failed to delete record: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error,
+      );
+    }
+  }
+}