@xmtp/browser-sdk 1.1.4 → 2.0.0

package/src/Client.ts

@@ -16,30 +16,46 @@ import { ClientWorkerClass } from "@/ClientWorkerClass";
 import { Conversations } from "@/Conversations";
 import { Preferences } from "@/Preferences";
 import type { ClientOptions, XmtpEnv } from "@/types";
+import { Utils } from "@/Utils";
 import {
   fromSafeEncodedContent,
   toSafeEncodedContent,
   type SafeMessage,
 } from "@/utils/conversions";
+import {
+  AccountAlreadyAssociatedError,
+  CodecNotFoundError,
+  GenerateSignatureError,
+  InboxReassignError,
+  InvalidGroupMembershipChangeError,
+  SignerUnavailableError,
+} from "@/utils/errors";
 import { type Signer } from "@/utils/signer";
 
+/**
+ * Client for interacting with the XMTP network
+ */
 export class Client extends ClientWorkerClass {
   #codecs: Map<string, ContentCodec>;
   #conversations: Conversations;
-  #encryptionKey: Uint8Array;
+  #identifier?: Identifier;
   #inboxId: string | undefined;
   #installationId: string | undefined;
   #installationIdBytes: Uint8Array | undefined;
   #isReady = false;
   #preferences: Preferences;
-  #signer: Signer;
-  options?: ClientOptions;
+  #signer?: Signer;
+  #options?: ClientOptions;
 
-  constructor(
-    signer: Signer,
-    encryptionKey: Uint8Array,
-    options?: ClientOptions,
-  ) {
+  /**
+   * Creates a new XMTP client instance
+   *
+   * This class is not intended to be initialized directly.
+   * Use `Client.create` or `Client.build` instead.
+   *
+   * @param options - Optional configuration for the client
+   */
+  constructor(options?: ClientOptions) {
     const worker = new Worker(new URL("./workers/client", import.meta.url), {
       type: "module",
     });
@@ -47,9 +63,7 @@ export class Client extends ClientWorkerClass {
       worker,
       options?.loggingLevel !== undefined && options.loggingLevel !== "off",
     );
-    this.options = options;
-    this.#encryptionKey = encryptionKey;
-    this.#signer = signer;
+    this.#options = options;
     this.#conversations = new Conversations(this);
     this.#preferences = new Preferences(this);
     const codecs = [
@@ -62,26 +76,38 @@ export class Client extends ClientWorkerClass {
     );
   }
 
-  async init() {
+  /**
+   * Initializes the client with the provided identifier
+   *
+   * This is not meant to be called directly.
+   * Use `Client.create` or `Client.build` instead.
+   *
+   * @param identifier - The identifier to initialize the client with
+   */
+  async init(identifier: Identifier) {
     const result = await this.sendMessage("init", {
-      identifier: await this.#signer.getIdentifier(),
-      encryptionKey: this.#encryptionKey,
-      options: this.options,
+      identifier,
+      options: this.#options,
     });
+    this.#identifier = identifier;
     this.#inboxId = result.inboxId;
     this.#installationId = result.installationId;
     this.#installationIdBytes = result.installationIdBytes;
     this.#isReady = true;
   }
 
-  static async create(
-    signer: Signer,
-    encryptionKey: Uint8Array,
-    options?: ClientOptions,
-  ) {
-    const client = new Client(signer, encryptionKey, options);
+  /**
+   * Creates a new client instance with a signer
+   *
+   * @param signer - The signer to use for authentication
+   * @param options - Optional configuration for the client
+   * @returns A new client instance
+   */
+  static async create(signer: Signer, options?: ClientOptions) {
+    const client = new Client(options);
+    client.#signer = signer;
 
-    await client.init();
+    await client.init(await signer.getIdentifier());
 
     if (!options?.disableAutoRegister) {
       await client.register();
@@ -90,63 +116,115 @@ export class Client extends ClientWorkerClass {
     return client;
   }
 
+  /**
+   * Creates a new client instance with an identifier
+   *
+   * Clients created with this method must already be registered.
+   * Any methods called that require a signer will throw an error.
+   *
+   * @param identifier - The identifier to use
+   * @param options - Optional configuration for the client
+   * @returns A new client instance
+   */
+  static async build(identifier: Identifier, options?: ClientOptions) {
+    const client = new Client({
+      ...options,
+      disableAutoRegister: true,
+    });
+    await client.init(identifier);
+    return client;
+  }
+
+  /**
+   * Gets the client options
+   */
+  get options() {
+    return this.#options;
+  }
+
+  /**
+   * Gets whether the client has been initialized
+   */
   get isReady() {
     return this.#isReady;
   }
 
+  /**
+   * Gets the inbox ID associated with this client
+   */
   get inboxId() {
     return this.#inboxId;
   }
 
-  async accountIdentifier() {
-    return this.#signer.getIdentifier();
+  /**
+   * Gets the account identifier for this client
+   */
+  get accountIdentifier() {
+    return this.#identifier;
   }
 
+  /**
+   * Gets the installation ID for this client
+   */
   get installationId() {
     return this.#installationId;
   }
 
+  /**
+   * Gets the installation ID bytes for this client
+   */
   get installationIdBytes() {
     return this.#installationIdBytes;
   }
 
+  /**
+   * Gets the conversations manager for this client
+   */
   get conversations() {
     return this.#conversations;
   }
 
+  /**
+   * Gets the preferences manager for this client
+   */
   get preferences() {
     return this.#preferences;
   }
 
   /**
+   * Creates signature text for creating a new inbox
+   *
    * WARNING: This function should be used with caution. It is only provided
    * for use in special cases where the provided workflows do not meet the
    * requirements of an application.
    *
-   * It is highly recommended to use the `register` function instead.
+   * It is highly recommended to use the `register` method instead.
+   *
+   * @returns The signature text
    */
   async unsafe_createInboxSignatureText() {
     return this.sendMessage("createInboxSignatureText", undefined);
   }
 
   /**
+   * Creates signature text for adding a new account to the client's inbox
+   *
    * WARNING: This function should be used with caution. It is only provided
    * for use in special cases where the provided workflows do not meet the
    * requirements of an application.
    *
-   * It is highly recommended to use the `unsafe_addAccount` function instead.
+   * It is highly recommended to use the `unsafe_addAccount` method instead.
    *
-   * The `allowInboxReassign` parameter must be true or this function will
-   * throw an error.
+   * @param newIdentifier - The identifier of the new account
+   * @param allowInboxReassign - Whether to allow inbox reassignment
+   * @returns The signature text
    */
   async unsafe_addAccountSignatureText(
     newIdentifier: Identifier,
     allowInboxReassign: boolean = false,
   ) {
     if (!allowInboxReassign) {
-      throw new Error(
-        "Unable to create add account signature text, `allowInboxReassign` must be true",
-      );
+      throw new InboxReassignError();
     }
 
     return this.sendMessage("addAccountSignatureText", {
@@ -155,11 +233,16 @@ export class Client extends ClientWorkerClass {
   }
 
   /**
+   * Creates signature text for removing an account from the client's inbox
+   *
    * WARNING: This function should be used with caution. It is only provided
    * for use in special cases where the provided workflows do not meet the
    * requirements of an application.
    *
-   * It is highly recommended to use the `removeAccount` function instead.
+   * It is highly recommended to use the `removeAccount` method instead.
+   *
+   * @param identifier - The identifier of the account to remove
+   * @returns The signature text
    */
   async unsafe_removeAccountSignatureText(identifier: Identifier) {
     return this.sendMessage("removeAccountSignatureText", {
@@ -168,12 +251,16 @@ export class Client extends ClientWorkerClass {
   }
 
   /**
+   * Creates signature text for revoking all other installations of the
+   * client's inbox
+   *
    * WARNING: This function should be used with caution. It is only provided
    * for use in special cases where the provided workflows do not meet the
    * requirements of an application.
    *
-   * It is highly recommended to use the `revokeAllOtherInstallations` function
-   * instead.
+   * It is highly recommended to use the `revokeAllOtherInstallations` method instead.
+   *
+   * @returns The signature text
    */
   async unsafe_revokeAllOtherInstallationsSignatureText() {
     return this.sendMessage(
@@ -183,11 +270,17 @@ export class Client extends ClientWorkerClass {
   }
 
   /**
+   * Creates signature text for revoking specific installations of the
+   * client's inbox
+   *
    * WARNING: This function should be used with caution. It is only provided
    * for use in special cases where the provided workflows do not meet the
    * requirements of an application.
    *
-   * It is highly recommended to use the `revokeInstallations` function instead.
+   * It is highly recommended to use the `revokeInstallations` method instead.
+   *
+   * @param installationIds - The installation IDs to revoke
+   * @returns The signature text
    */
   async unsafe_revokeInstallationsSignatureText(installationIds: Uint8Array[]) {
     return this.sendMessage("revokeInstallationsSignatureText", {
@@ -196,13 +289,39 @@ export class Client extends ClientWorkerClass {
   }
 
   /**
+   * Creates signature text for changing the recovery identifier for this
+   * client's inbox
+   *
    * WARNING: This function should be used with caution. It is only provided
    * for use in special cases where the provided workflows do not meet the
    * requirements of an application.
    *
-   * It is highly recommended to use the `register`, `addAccount`,
+   * It is highly recommended to use the `changeRecoveryIdentifier` method instead.
+   *
+   * @param identifier - The new recovery identifier
+   * @returns The signature text
+   */
+  async unsafe_changeRecoveryIdentifierSignatureText(identifier: Identifier) {
+    return this.sendMessage("changeRecoveryIdentifierSignatureText", {
+      identifier,
+    });
+  }
+
+  /**
+   * Adds a signature for a specific request type
+   *
+   * WARNING: This function should be used with caution. It is only provided
+   * for use in special cases where the provided workflows do not meet the
+   * requirements of an application.
+   *
+   * It is highly recommended to use the `register`, `unsafe_addAccount`,
    * `removeAccount`, `revokeAllOtherInstallations`, or `revokeInstallations`
-   * functions instead.
+   * methods instead.
+   *
+   * @param signatureType - The type of signature request
+   * @param signatureText - The text to sign
+   * @param signer - The signer to use
+   * @warning This is an unsafe operation and should be used with caution
    */
   async unsafe_addSignature(
     signatureType: SignatureRequestType,
@@ -230,19 +349,32 @@ export class Client extends ClientWorkerClass {
   }
 
   /**
+   * Applies all pending signatures
+   *
    * WARNING: This function should be used with caution. It is only provided
    * for use in special cases where the provided workflows do not meet the
    * requirements of an application.
    *
-   * It is highly recommended to use the `register`, `addAccount`,
+   * It is highly recommended to use the `register`, `unsafe_addAccount`,
    * `removeAccount`, `revokeAllOtherInstallations`, or `revokeInstallations`
-   * functions instead.
+   * methods instead.
    */
   async unsafe_applySignatures() {
     return this.sendMessage("applySignatures", undefined);
   }
 
+  /**
+   * Registers the client with the XMTP network
+   *
+   * Requires a signer, use `Client.create` to create a client with a signer.
+   *
+   * @throws {SignerUnavailableError} if no signer is available
+   */
   async register() {
+    if (!this.#signer) {
+      throw new SignerUnavailableError();
+    }
+
     const signatureText = await this.unsafe_createInboxSignatureText();
 
     // if the signature text is not available, the client is already registered
@@ -260,12 +392,22 @@ export class Client extends ClientWorkerClass {
   }
 
   /**
+   * Adds a new account to the client inbox
+   *
    * WARNING: This function should be used with caution. Adding a wallet already
-   * associated with an inboxId will cause the wallet to lose access to
+   * associated with an inbox ID will cause the wallet to lose access to
    * that inbox.
    *
    * The `allowInboxReassign` parameter must be true to reassign an inbox
    * already associated with a different account.
+   *
+   * Requires a signer, use `Client.create` to create a client with a signer.
+   *
+   * @param newAccountSigner - The signer for the new account
+   * @param allowInboxReassign - Whether to allow inbox reassignment
+   * @throws {AccountAlreadyAssociatedError} if the account is already associated with an inbox ID
+   * @throws {GenerateSignatureError} if the signature cannot be generated
+   * @throws {SignerUnavailableError} if no signer is available
    */
   async unsafe_addAccount(
     newAccountSigner: Signer,
@@ -277,9 +419,7 @@ export class Client extends ClientWorkerClass {
     );
 
     if (existingInboxId && !allowInboxReassign) {
-      throw new Error(
-        `Signer address already associated with inbox ${existingInboxId}`,
-      );
+      throw new AccountAlreadyAssociatedError(existingInboxId);
     }
 
     const signatureText = await this.unsafe_addAccountSignatureText(
@@ -288,7 +428,7 @@ export class Client extends ClientWorkerClass {
     );
 
     if (!signatureText) {
-      throw new Error("Unable to generate add account signature text");
+      throw new GenerateSignatureError(SignatureRequestType.AddWallet);
     }
 
     await this.unsafe_addSignature(
@@ -300,12 +440,25 @@ export class Client extends ClientWorkerClass {
     await this.unsafe_applySignatures();
   }
 
+  /**
+   * Removes an account from the client's inbox
+   *
+   * Requires a signer, use `Client.create` to create a client with a signer.
+   *
+   * @param accountIdentifier - The identifier of the account to remove
+   * @throws {GenerateSignatureError} if the signature cannot be generated
+   * @throws {SignerUnavailableError} if no signer is available
+   */
   async removeAccount(accountIdentifier: Identifier) {
+    if (!this.#signer) {
+      throw new SignerUnavailableError();
+    }
+
     const signatureText =
       await this.unsafe_removeAccountSignatureText(accountIdentifier);
 
     if (!signatureText) {
-      throw new Error("Unable to generate remove account signature text");
+      throw new GenerateSignatureError(SignatureRequestType.RevokeWallet);
     }
 
     await this.unsafe_addSignature(
@@ -317,13 +470,25 @@ export class Client extends ClientWorkerClass {
     await this.unsafe_applySignatures();
   }
 
+  /**
+   * Revokes all other installations of the client's inbox
+   *
+   * Requires a signer, use `Client.create` to create a client with a signer.
+   *
+   * @throws {GenerateSignatureError} if the signature cannot be generated
+   * @throws {SignerUnavailableError} if no signer is available
+   */
   async revokeAllOtherInstallations() {
+    if (!this.#signer) {
+      throw new SignerUnavailableError();
+    }
+
     const signatureText =
       await this.unsafe_revokeAllOtherInstallationsSignatureText();
 
     if (!signatureText) {
-      throw new Error(
-        "Unable to generate revoke all other installations signature text",
+      throw new GenerateSignatureError(
+        SignatureRequestType.RevokeInstallations,
       );
     }
 
@@ -336,12 +501,27 @@ export class Client extends ClientWorkerClass {
     await this.unsafe_applySignatures();
   }
 
+  /**
+   * Revokes specific installations of the client's inbox
+   *
+   * Requires a signer, use `Client.create` to create a client with a signer.
+   *
+   * @param installationIds - The installation IDs to revoke
+   * @throws {GenerateSignatureError} if the signature cannot be generated
+   * @throws {SignerUnavailableError} if no signer is available
+   */
   async revokeInstallations(installationIds: Uint8Array[]) {
+    if (!this.#signer) {
+      throw new SignerUnavailableError();
+    }
+
     const signatureText =
       await this.unsafe_revokeInstallationsSignatureText(installationIds);
 
     if (!signatureText) {
-      throw new Error("Unable to generate revoke installations signature text");
+      throw new GenerateSignatureError(
+        SignatureRequestType.RevokeInstallations,
+      );
     }
 
     await this.unsafe_addSignature(
@@ -353,48 +533,107 @@ export class Client extends ClientWorkerClass {
     await this.unsafe_applySignatures();
   }
 
+  /**
+   * Changes the recovery identifier for the client's inbox
+   *
+   * Requires a signer, use `Client.create` to create a client with a signer.
+   *
+   * @param identifier - The new recovery identifier
+   * @throws {GenerateSignatureError} if the signature cannot be generated
+   * @throws {SignerUnavailableError} if no signer is available
+   */
+  async changeRecoveryIdentifier(identifier: Identifier) {
+    if (!this.#signer) {
+      throw new SignerUnavailableError();
+    }
+
+    const signatureText =
+      await this.unsafe_changeRecoveryIdentifierSignatureText(identifier);
+
+    if (!signatureText) {
+      throw new GenerateSignatureError(
+        SignatureRequestType.ChangeRecoveryIdentifier,
+      );
+    }
+
+    await this.unsafe_addSignature(
+      SignatureRequestType.ChangeRecoveryIdentifier,
+      signatureText,
+      this.#signer,
+    );
+
+    await this.unsafe_applySignatures();
+  }
+
+  /**
+   * Checks if the client is registered with the XMTP network
+   *
+   * @returns Whether the client is registered
+   */
   async isRegistered() {
     return this.sendMessage("isRegistered", undefined);
   }
 
+  /**
+   * Checks if the client can message the specified identifiers
+   *
+   * @param identifiers - The identifiers to check
+   * @returns Whether the client can message the identifiers
+   */
   async canMessage(identifiers: Identifier[]) {
     return this.sendMessage("canMessage", { identifiers });
   }
 
+  /**
+   * Checks if the specified identifiers can be messaged
+   *
+   * @param identifiers - The identifiers to check
+   * @param env - Optional XMTP environment
+   * @returns Map of identifiers to whether they can be messaged
+   */
   static async canMessage(identifiers: Identifier[], env?: XmtpEnv) {
-    const signer: Signer = {
-      type: "EOA",
-      getIdentifier: () => ({
-        identifier: "0x0000000000000000000000000000000000000000",
-        identifierKind: "Ethereum",
-      }),
-      signMessage: () => new Uint8Array(),
-    };
-    const client = await Client.create(
-      signer,
-      window.crypto.getRandomValues(new Uint8Array(32)),
-      {
-        disableAutoRegister: true,
-        env,
-      },
-    );
-    return client.canMessage(identifiers);
+    const canMessageMap = new Map<string, boolean>();
+    const utils = new Utils();
+    for (const identifier of identifiers) {
+      const inboxId = await utils.getInboxIdForIdentifier(identifier, env);
+      canMessageMap.set(identifier.identifier, inboxId !== undefined);
+    }
+    utils.close();
+    return canMessageMap;
   }
 
+  /**
+   * Finds the inbox ID for a given identifier
+   *
+   * @param identifier - The identifier to look up
+   * @returns The inbox ID, if found
+   */
   async findInboxIdByIdentifier(identifier: Identifier) {
     return this.sendMessage("findInboxIdByIdentifier", { identifier });
   }
 
+  /**
+   * Gets the codec for a given content type
+   *
+   * @param contentType - The content type to get the codec for
+   * @returns The codec, if found
+   */
   codecFor(contentType: ContentTypeId) {
     return this.#codecs.get(contentType.toString());
   }
 
+  /**
+   * Encodes content for a given content type
+   *
+   * @param content - The content to encode
+   * @param contentType - The content type to encode for
+   * @returns The encoded content
+   * @throws {CodecNotFoundError} if no codec is found for the content type
+   */
   encodeContent(content: any, contentType: ContentTypeId) {
     const codec = this.codecFor(contentType);
     if (!codec) {
-      throw new Error(
-        `Codec not found for "${contentType.toString()}" content type`,
-      );
+      throw new CodecNotFoundError(contentType);
     }
     const encoded = codec.encode(content, this);
     const fallback = codec.fallback(content);
@@ -404,12 +643,19 @@ export class Client extends ClientWorkerClass {
     return toSafeEncodedContent(encoded);
   }
 
+  /**
+   * Decodes a message for a given content type
+   *
+   * @param message - The message to decode
+   * @param contentType - The content type to decode for
+   * @returns The decoded content
+   * @throws {CodecNotFoundError} if no codec is found for the content type
+   * @throws {InvalidGroupMembershipChangeError} if the message is an invalid group membership change
+   */
   decodeContent(message: SafeMessage, contentType: ContentTypeId) {
     const codec = this.codecFor(contentType);
     if (!codec) {
-      throw new Error(
-        `Codec not found for "${contentType.toString()}" content type`,
-      );
+      throw new CodecNotFoundError(contentType);
     }
 
     // throw an error if there's an invalid group membership change message
@@ -417,7 +663,7 @@ export class Client extends ClientWorkerClass {
       contentType.sameAs(ContentTypeGroupUpdated) &&
       message.kind !== GroupMessageKind.MembershipChange
     ) {
-      throw new Error("Error decoding group membership change");
+      throw new InvalidGroupMembershipChangeError(message.id);
     }
 
     const encodedContent = fromSafeEncodedContent(message.content);
@@ -425,10 +671,23 @@ export class Client extends ClientWorkerClass {
     return codec.decode(encodedContent, this);
   }
 
+  /**
+   * Signs a message with the installation key
+   *
+   * @param signatureText - The text to sign
+   * @returns The signature
+   */
   signWithInstallationKey(signatureText: string) {
     return this.sendMessage("signWithInstallationKey", { signatureText });
   }
 
+  /**
+   * Verifies a signature was made with the installation key
+   *
+   * @param signatureText - The text that was signed
+   * @param signatureBytes - The signature bytes to verify
+   * @returns Whether the signature is valid
+   */
   verifySignedWithInstallationKey(
     signatureText: string,
     signatureBytes: Uint8Array,
@@ -439,6 +698,14 @@ export class Client extends ClientWorkerClass {
     });
   }
 
+  /**
+   * Verifies a signature was made with a public key
+   *
+   * @param signatureText - The text that was signed
+   * @param signatureBytes - The signature bytes to verify
+   * @param publicKey - The public key to verify against
+   * @returns Whether the signature is valid
+   */
   verifySignedWithPublicKey(
     signatureText: string,
     signatureBytes: Uint8Array,
@@ -450,4 +717,16 @@ export class Client extends ClientWorkerClass {
       publicKey,
     });
   }
+
+  /**
+   * Gets the key package statuses for the specified installation IDs
+   *
+   * @param installationIds - The installation IDs to check
+   * @returns The key package statuses
+   */
+  async getKeyPackageStatusesForInstallationIds(installationIds: string[]) {
+    return this.sendMessage("getKeyPackageStatusesForInstallationIds", {
+      installationIds,
+    });
+  }
 }