@xmtp/browser-sdk 1.1.4 → 2.0.1

package/src/Group.ts

@@ -8,19 +8,18 @@ import type { Client } from "@/Client";
 import { Conversation } from "@/Conversation";
 import type { SafeConversation } from "@/utils/conversions";
 
+/**
+ * Represents a group conversation between multiple inboxes
+ *
+ * This class is not intended to be initialized directly.
+ */
 export class Group extends Conversation {
+  #admins: SafeConversation["admins"] = [];
   #client: Client;
-
+  #description?: SafeConversation["description"];
   #id: string;
-
-  #name?: SafeConversation["name"];
-
   #imageUrl?: SafeConversation["imageUrl"];
-
-  #description?: SafeConversation["description"];
-
-  #admins: SafeConversation["admins"] = [];
-
+  #name?: SafeConversation["name"];
   #superAdmins: SafeConversation["superAdmins"] = [];
 
   #syncData(data?: SafeConversation) {
@@ -31,6 +30,13 @@ export class Group extends Conversation {
     this.#superAdmins = data?.superAdmins ?? [];
   }
 
+  /**
+   * Creates a new group conversation instance
+   *
+   * @param client - The client instance managing this group conversation
+   * @param id - Identifier for the group conversation
+   * @param data - Optional conversation data to initialize with
+   */
   constructor(client: Client, id: string, data?: SafeConversation) {
     super(client, id, data);
     this.#client = client;
@@ -38,16 +44,29 @@ export class Group extends Conversation {
     this.#syncData(data);
   }
 
+  /**
+   * Synchronizes the group's data with the network
+   *
+   * @returns Updated group data
+   */
   async sync() {
     const data = await super.sync();
     this.#syncData(data);
     return data;
   }
 
+  /**
+   * The name of the group
+   */
   get name() {
     return this.#name;
   }
 
+  /**
+   * Updates the group's name
+   *
+   * @param name The new name for the group
+   */
   async updateName(name: string) {
     await this.#client.sendMessage("updateGroupName", {
       id: this.#id,
@@ -56,10 +75,18 @@ export class Group extends Conversation {
     this.#name = name;
   }
 
+  /**
+   * The image URL of the group
+   */
   get imageUrl() {
     return this.#imageUrl;
   }
 
+  /**
+   * Updates the group's image URL
+   *
+   * @param imageUrl The new image URL for the group
+   */
   async updateImageUrl(imageUrl: string) {
     await this.#client.sendMessage("updateGroupImageUrlSquare", {
       id: this.#id,
@@ -68,10 +95,18 @@ export class Group extends Conversation {
     this.#imageUrl = imageUrl;
   }
 
+  /**
+   * The description of the group
+   */
   get description() {
     return this.#description;
   }
 
+  /**
+   * Updates the group's description
+   *
+   * @param description The new description for the group
+   */
   async updateDescription(description: string) {
     await this.#client.sendMessage("updateGroupDescription", {
       id: this.#id,
@@ -80,14 +115,25 @@ export class Group extends Conversation {
     this.#description = description;
   }
 
+  /**
+   * The list of admins of the group by inbox ID
+   */
   get admins() {
     return this.#admins;
   }
 
+  /**
+   * The list of super admins of the group by inbox ID
+   */
   get superAdmins() {
     return this.#superAdmins;
   }
 
+  /**
+   * Fetches and updates the list of group admins from the server
+   *
+   * @returns Array of admin inbox IDs
+   */
   async listAdmins() {
     const admins = await this.#client.sendMessage("getGroupAdmins", {
       id: this.#id,
@@ -96,6 +142,11 @@ export class Group extends Conversation {
     return admins;
   }
 
+  /**
+   * Fetches and updates the list of group super admins from the server
+   *
+   * @returns Array of super admin inbox IDs
+   */
   async listSuperAdmins() {
     const superAdmins = await this.#client.sendMessage("getGroupSuperAdmins", {
       id: this.#id,
@@ -104,12 +155,24 @@ export class Group extends Conversation {
     return superAdmins;
   }
 
+  /**
+   * Retrieves the group's permissions
+   *
+   * @returns The group's permissions
+   */
   async permissions() {
     return this.#client.sendMessage("getGroupPermissions", {
       id: this.#id,
     });
   }
 
+  /**
+   * Updates a specific permission policy for the group
+   *
+   * @param permissionType The type of permission to update
+   * @param policy The new permission policy
+   * @param metadataField Optional metadata field for the permission
+   */
   async updatePermission(
     permissionType: PermissionUpdateType,
     policy: PermissionPolicy,
@@ -123,16 +186,33 @@ export class Group extends Conversation {
     });
   }
 
+  /**
+   * Checks if an inbox is an admin of the group
+   *
+   * @param inboxId The inbox ID to check
+   * @returns Boolean indicating if the inbox is an admin
+   */
   async isAdmin(inboxId: string) {
     const admins = await this.listAdmins();
     return admins.includes(inboxId);
   }
 
+  /**
+   * Checks if an inbox is a super admin of the group
+   *
+   * @param inboxId The inbox ID to check
+   * @returns Boolean indicating if the inbox is a super admin
+   */
   async isSuperAdmin(inboxId: string) {
     const superAdmins = await this.listSuperAdmins();
     return superAdmins.includes(inboxId);
   }
 
+  /**
+   * Adds members to the group using identifiers
+   *
+   * @param identifiers Array of member identifiers to add
+   */
   async addMembersByIdentifiers(identifiers: Identifier[]) {
     return this.#client.sendMessage("addGroupMembers", {
       id: this.#id,
@@ -140,6 +220,11 @@ export class Group extends Conversation {
     });
   }
 
+  /**
+   * Adds members to the group using inbox IDs
+   *
+   * @param inboxIds Array of inbox IDs to add
+   */
   async addMembers(inboxIds: string[]) {
     return this.#client.sendMessage("addGroupMembersByInboxId", {
       id: this.#id,
@@ -147,6 +232,11 @@ export class Group extends Conversation {
     });
   }
 
+  /**
+   * Removes members from the group using identifiers
+   *
+   * @param identifiers Array of member identifiers to remove
+   */
   async removeMembersByIdentifiers(identifiers: Identifier[]) {
     return this.#client.sendMessage("removeGroupMembers", {
       id: this.#id,
@@ -154,6 +244,11 @@ export class Group extends Conversation {
     });
   }
 
+  /**
+   * Removes members from the group using inbox IDs
+   *
+   * @param inboxIds Array of inbox IDs to remove
+   */
   async removeMembers(inboxIds: string[]) {
     return this.#client.sendMessage("removeGroupMembersByInboxId", {
       id: this.#id,
@@ -161,6 +256,11 @@ export class Group extends Conversation {
     });
   }
 
+  /**
+   * Promotes a group member to admin status
+   *
+   * @param inboxId The inbox ID of the member to promote
+   */
   async addAdmin(inboxId: string) {
     return this.#client.sendMessage("addGroupAdmin", {
       id: this.#id,
@@ -168,6 +268,11 @@ export class Group extends Conversation {
     });
   }
 
+  /**
+   * Removes admin status from a group member
+   *
+   * @param inboxId The inbox ID of the admin to demote
+   */
   async removeAdmin(inboxId: string) {
     return this.#client.sendMessage("removeGroupAdmin", {
       id: this.#id,
@@ -175,6 +280,11 @@ export class Group extends Conversation {
     });
   }
 
+  /**
+   * Promotes a group member to super admin status
+   *
+   * @param inboxId The inbox ID of the member to promote
+   */
   async addSuperAdmin(inboxId: string) {
     return this.#client.sendMessage("addGroupSuperAdmin", {
       id: this.#id,
@@ -182,6 +292,11 @@ export class Group extends Conversation {
     });
   }
 
+  /**
+   * Removes super admin status from a group member
+   *
+   * @param inboxId The inbox ID of the super admin to demote
+   */
   async removeSuperAdmin(inboxId: string) {
     return this.#client.sendMessage("removeGroupSuperAdmin", {
       id: this.#id,

package/src/Preferences.ts

@@ -4,19 +4,42 @@ import { AsyncStream, type StreamCallback } from "@/AsyncStream";
 import type { SafeConsent } from "@/utils/conversions";
 import type { Client } from "./Client";
 
+/**
+ * Manages user preferences and consent states
+ *
+ * This class is not intended to be initialized directly.
+ */
 export class Preferences {
   #client: Client;
 
+  /**
+   * Creates a new preferences instance
+   *
+   * @param client - The client instance managing preferences
+   */
   constructor(client: Client) {
     this.#client = client;
   }
 
+  /**
+   * Retrieves the current inbox state
+   *
+   * @param refreshFromNetwork - Optional flag to force refresh from network
+   * @returns Promise that resolves with the inbox state
+   */
   async inboxState(refreshFromNetwork?: boolean) {
     return this.#client.sendMessage("inboxState", {
       refreshFromNetwork: refreshFromNetwork ?? false,
     });
   }
 
+  /**
+   * Retrieves inbox state for specific inbox IDs
+   *
+   * @param inboxIds - Array of inbox IDs to get state for
+   * @param refreshFromNetwork - Optional flag to force refresh from network
+   * @returns Promise that resolves with the inbox state for the inbox IDs
+   */
   async inboxStateFromInboxIds(
     inboxIds: string[],
     refreshFromNetwork?: boolean,
@@ -27,18 +50,43 @@ export class Preferences {
     });
   }
 
+  /**
+   * Gets the latest inbox state for a specific inbox
+   *
+   * @param inboxId - The inbox ID to get state for
+   * @returns Promise that resolves with the latest inbox state
+   */
   async getLatestInboxState(inboxId: string) {
     return this.#client.sendMessage("getLatestInboxState", { inboxId });
   }
 
+  /**
+   * Updates consent states for multiple records
+   *
+   * @param records - Array of consent records to update
+   * @returns Promise that resolves when consent states are updated
+   */
   async setConsentStates(records: SafeConsent[]) {
     return this.#client.sendMessage("setConsentStates", { records });
   }
 
+  /**
+   * Retrieves consent state for a specific entity
+   *
+   * @param entityType - Type of entity to get consent for
+   * @param entity - Entity identifier
+   * @returns Promise that resolves with the consent state
+   */
   async getConsentState(entityType: ConsentEntityType, entity: string) {
     return this.#client.sendMessage("getConsentState", { entityType, entity });
   }
 
+  /**
+   * Creates a stream of consent state updates
+   *
+   * @param callback - Optional callback function for handling stream updates
+   * @returns AsyncStream instance for consent updates
+   */
   async streamConsent(callback?: StreamCallback<SafeConsent[]>) {
     const streamId = v4();
     const asyncStream = new AsyncStream<SafeConsent[]>();
@@ -61,6 +109,12 @@ export class Preferences {
     return asyncStream;
   }
 
+  /**
+   * Creates a stream of user preference updates
+   *
+   * @param callback - Optional callback function for handling stream updates
+   * @returns AsyncStream instance for preference updates
+   */
   async streamPreferences(callback?: StreamCallback<UserPreference[]>) {
     const streamId = v4();
     const asyncStream = new AsyncStream<UserPreference[]>();

package/src/Utils.ts

@@ -2,28 +2,45 @@ import type { Identifier } from "@xmtp/wasm-bindings";
 import type { XmtpEnv } from "@/types/options";
 import { UtilsWorkerClass } from "@/UtilsWorkerClass";
 
+/**
+ * Utility class that provides helper functions for XMTP inbox IDs
+ */
 export class Utils extends UtilsWorkerClass {
-  #enableLogging: boolean;
+  /**
+   * Creates a new Utils instance
+   *
+   * @param enableLogging - Optional flag to enable logging
+   */
   constructor(enableLogging?: boolean) {
     const worker = new Worker(new URL("./workers/utils", import.meta.url), {
       type: "module",
     });
     super(worker, enableLogging ?? false);
-    this.#enableLogging = enableLogging ?? false;
   }
 
+  /**
+   * Generates an inbox ID for a given identifier
+   *
+   * @param identifier - The identifier to generate an inbox ID for
+   * @returns Promise that resolves with the generated inbox ID
+   */
   async generateInboxId(identifier: Identifier) {
     return this.sendMessage("generateInboxId", {
       identifier,
-      enableLogging: this.#enableLogging,
     });
   }
 
+  /**
+   * Gets the inbox ID for a specific identifier and optional environment
+   *
+   * @param identifier - The identifier to get the inbox ID for
+   * @param env - Optional XMTP environment configuration (default: "dev")
+   * @returns Promise that resolves with the inbox ID for the identifier
+   */
   async getInboxIdForIdentifier(identifier: Identifier, env?: XmtpEnv) {
     return this.sendMessage("getInboxIdForIdentifier", {
       identifier,
       env,
-      enableLogging: this.#enableLogging,
     });
   }
 }

package/src/UtilsWorkerClass.ts

@@ -27,6 +27,13 @@ export class UtilsWorkerClass {
     this.#worker.addEventListener("message", this.handleMessage);
     this.#worker.addEventListener("error", handleError);
     this.#enableLogging = enableLogging;
+    void this.init(enableLogging);
+  }
+
+  async init(enableLogging: boolean) {
+    return this.sendMessage("init", {
+      enableLogging,
+    });
   }
 
   sendMessage<A extends UtilsEventsActions>(

package/src/WorkerClient.ts

@@ -2,6 +2,7 @@ import {
   verifySignedWithPublicKey,
   type Client,
   type Identifier,
+  type KeyPackageStatus,
   type SignatureRequestType,
 } from "@xmtp/wasm-bindings";
 import type { ClientOptions } from "@/types";
@@ -23,10 +24,9 @@ export class WorkerClient {
 
   static async create(
     identifier: Identifier,
-    encryptionKey: Uint8Array,
     options?: Omit<ClientOptions, "codecs">,
   ) {
-    const client = await createClient(identifier, encryptionKey, options);
+    const client = await createClient(identifier, options);
     return new WorkerClient(client);
   }
 
@@ -100,6 +100,16 @@ export class WorkerClient {
     }
   }
 
+  async changeRecoveryIdentifierSignatureText(identifier: Identifier) {
+    try {
+      return await this.#client.changeRecoveryIdentifierSignatureText(
+        identifier,
+      );
+    } catch {
+      return undefined;
+    }
+  }
+
   async addEcdsaSignature(type: SignatureRequestType, bytes: Uint8Array) {
     return this.#client.addEcdsaSignature(type, bytes);
   }
@@ -162,4 +172,10 @@ export class WorkerClient {
       return false;
     }
   }
+
+  async getKeyPackageStatusesForInstallationIds(installationIds: string[]) {
+    return this.#client.getKeyPackageStatusesForInstallationIds(
+      installationIds,
+    ) as Promise<Map<string, KeyPackageStatus>>;
+  }
 }

package/src/WorkerConversation.ts

@@ -4,6 +4,7 @@ import {
   type Conversation,
   type EncodedContent,
   type GroupMember,
+  type HmacKey,
   type Identifier,
   type Message,
   type MetadataField,
@@ -214,4 +215,8 @@ export class WorkerConversation {
   pausedForVersion() {
     return this.#group.pausedForVersion();
   }
+
+  getHmacKeys() {
+    return this.#group.getHmacKeys() as HmacKey[];
+  }
 }

package/src/constants.ts

@@ -1,9 +1,25 @@
+/**
+ * Pre-configured URLs for the XMTP network based on the environment
+ *
+ * @constant
+ * @property {string} local - The local URL for the XMTP network
+ * @property {string} dev - The development URL for the XMTP network
+ * @property {string} production - The production URL for the XMTP network
+ */
 export const ApiUrls = {
   local: "http://localhost:5555",
   dev: "https://dev.xmtp.network",
   production: "https://production.xmtp.network",
 } as const;
 
+/**
+ * Pre-configured URLs for the XMTP history sync service based on the environment
+ *
+ * @constant
+ * @property {string} local - The local URL for the XMTP history sync service
+ * @property {string} dev - The development URL for the XMTP history sync service
+ * @property {string} production - The production URL for the XMTP history sync service
+ */
 export const HistorySyncUrls = {
   local: "http://localhost:5558",
   dev: "https://message-history.dev.ephemera.network",

package/src/index.ts

@@ -41,7 +41,6 @@ export {
   Message,
   MessageDisappearingSettings,
   MetadataField,
-  Opfs,
   PermissionLevel,
   PermissionPolicy,
   PermissionPolicySet,

package/src/types/clientEvents.ts

@@ -25,8 +25,10 @@ import type {
   SafeCreateGroupOptions,
   SafeEncodedContent,
   SafeGroupMember,
+  SafeHmacKey,
   SafeHmacKeys,
   SafeInboxState,
+  SafeKeyPackageStatus,
   SafeListConversationsOptions,
   SafeListMessagesOptions,
   SafeMessage,
@@ -58,7 +60,6 @@ export type ClientEvents =
       };
       data: {
         identifier: Identifier;
-        encryptionKey: Uint8Array;
         options?: ClientOptions;
       };
     }
@@ -98,6 +99,14 @@ export type ClientEvents =
         installationIds: Uint8Array[];
       };
     }
+  | {
+      action: "changeRecoveryIdentifierSignatureText";
+      id: string;
+      result: string | undefined;
+      data: {
+        identifier: Identifier;
+      };
+    }
   | {
       action: "addEcdsaSignature";
       id: string;
@@ -221,6 +230,14 @@ export type ClientEvents =
         publicKey: Uint8Array;
       };
     }
+  | {
+      action: "getKeyPackageStatusesForInstallationIds";
+      id: string;
+      result: Map<string, SafeKeyPackageStatus>;
+      data: {
+        installationIds: string[];
+      };
+    }
   /**
    * Conversations actions
    */
@@ -641,8 +658,15 @@ export type ClientEvents =
       data: {
         id: string;
       };
+    }
+  | {
+      action: "getGroupHmacKeys";
+      id: string;
+      result: SafeHmacKey[];
+      data: {
+        id: string;
+      };
     };
-
 export type ClientEventsActions = ClientEvents["action"];
 
 export type ClientEventsClientMessageData =

package/src/types/options.ts

@@ -37,7 +37,11 @@ export type StorageOptions = {
   /**
    * Path to the local DB
    */
-  dbPath?: string;
+  dbPath?: string | null;
+  /**
+   * Encryption key for the local DB
+   */
+  dbEncryptionKey?: Uint8Array;
 };
 
 export type OtherOptions = {

package/src/types/utilsEvents.ts

@@ -11,13 +11,20 @@ import type {
 } from "@/types";
 
 export type UtilsEvents =
+  | {
+      action: "init";
+      id: string;
+      result: undefined;
+      data: {
+        enableLogging: boolean;
+      };
+    }
   | {
       action: "generateInboxId";
       id: string;
       result: string;
       data: {
         identifier: Identifier;
-        enableLogging: boolean;
       };
     }
   | {
@@ -27,7 +34,6 @@ export type UtilsEvents =
       data: {
         identifier: Identifier;
         env?: XmtpEnv;
-        enableLogging: boolean;
       };
     };
 

package/src/utils/conversions.ts

@@ -23,6 +23,7 @@ import {
   type Identifier,
   type InboxState,
   type Installation,
+  type KeyPackageStatus,
   type Message,
   type PermissionLevel,
   type PermissionPolicy,
@@ -477,3 +478,23 @@ export const fromSafeMessageDisappearingSettings = (
   settings: SafeMessageDisappearingSettings,
 ): MessageDisappearingSettings =>
   new MessageDisappearingSettings(settings.fromNs, settings.inNs);
+
+export type SafeKeyPackageStatus = {
+  lifetime?: {
+    notBefore: bigint;
+    notAfter: bigint;
+  };
+  validationError?: string;
+};
+
+export const toSafeKeyPackageStatus = (
+  status: KeyPackageStatus,
+): SafeKeyPackageStatus => ({
+  lifetime: status.lifetime
+    ? {
+        notBefore: status.lifetime.not_before,
+        notAfter: status.lifetime.not_after,
+      }
+    : undefined,
+  validationError: status.validationError,
+});