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

package/src/repository/ProfileOperationsImpl.ts

@@ -1,281 +0,0 @@
-/**
- * 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

@@ -1,340 +0,0 @@
-/**
- * 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,
-      );
-    }
-  }
-}