@xmtp/browser-sdk 2.0.13 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmtp/browser-sdk",
-  "version": "2.0.13",
+  "version": "2.1.0",
   "description": "XMTP client SDK for browsers written in TypeScript",
   "keywords": [
     "xmtp",
@@ -63,8 +63,7 @@
     "@xmtp/content-type-group-updated": "^2.0.2",
     "@xmtp/content-type-primitives": "^2.0.2",
     "@xmtp/content-type-text": "^2.0.2",
-    "@xmtp/proto": "^3.78.0",
-    "@xmtp/wasm-bindings": "1.1.7",
+    "@xmtp/wasm-bindings": "1.2.0",
     "uuid": "^11.1.0"
   },
   "devDependencies": {
@@ -73,19 +72,18 @@
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@types/uuid": "^10.0.0",
-    "@vitest/browser": "^3.1.1",
-    "@vitest/coverage-v8": "^3.1.1",
+    "@vitest/browser": "^3.1.4",
+    "@vitest/coverage-v8": "^3.1.4",
     "@web/rollup-plugin-copy": "^0.5.1",
-    "playwright": "^1.51.1",
-    "rollup": "^4.39.0",
+    "playwright": "^1.52.0",
+    "rollup": "^4.41.1",
     "rollup-plugin-dts": "^6.1.1",
-    "rollup-plugin-filesize": "^10.0.0",
     "rollup-plugin-tsconfig-paths": "^1.5.2",
     "typescript": "^5.8.3",
-    "viem": "^2.26.2",
-    "vite": "^6.2.5",
+    "viem": "^2.30.5",
+    "vite": "^6.3.5",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.1.1"
+    "vitest": "^3.1.4"
   },
   "engines": {
     "node": ">=20"

package/src/Client.ts

@@ -15,7 +15,7 @@ import {
 import { ClientWorkerClass } from "@/ClientWorkerClass";
 import { Conversations } from "@/Conversations";
 import { Preferences } from "@/Preferences";
-import type { ClientOptions, XmtpEnv } from "@/types";
+import type { ClientOptions, XmtpEnv } from "@/types/options";
 import { Utils } from "@/Utils";
 import {
   fromSafeEncodedContent,
@@ -32,18 +32,25 @@ import {
 } from "@/utils/errors";
 import { type Signer } from "@/utils/signer";
 
+export type ExtractCodecContentTypes<C extends ContentCodec[] = []> =
+  [...C, GroupUpdatedCodec, TextCodec][number] extends ContentCodec<infer T>
+    ? T
+    : never;
+
 /**
  * Client for interacting with the XMTP network
  */
-export class Client extends ClientWorkerClass {
+export class Client<
+  ContentTypes = ExtractCodecContentTypes,
+> extends ClientWorkerClass {
   #codecs: Map<string, ContentCodec>;
-  #conversations: Conversations;
+  #conversations: Conversations<ContentTypes>;
   #identifier?: Identifier;
   #inboxId: string | undefined;
   #installationId: string | undefined;
   #installationIdBytes: Uint8Array | undefined;
   #isReady = false;
-  #preferences: Preferences;
+  #preferences: Preferences<ContentTypes>;
   #signer?: Signer;
   #options?: ClientOptions;
 
@@ -85,7 +92,7 @@ export class Client extends ClientWorkerClass {
    * @param identifier - The identifier to initialize the client with
    */
   async init(identifier: Identifier) {
-    const result = await this.sendMessage("init", {
+    const result = await this.sendMessage("client.init", {
       identifier,
       options: this.#options,
     });
@@ -103,8 +110,13 @@ export class Client extends ClientWorkerClass {
    * @param options - Optional configuration for the client
    * @returns A new client instance
    */
-  static async create(signer: Signer, options?: ClientOptions) {
-    const client = new Client(options);
+  static async create<ContentCodecs extends ContentCodec[] = []>(
+    signer: Signer,
+    options?: Omit<ClientOptions, "codecs"> & {
+      codecs?: ContentCodecs;
+    },
+  ) {
+    const client = new Client<ExtractCodecContentTypes<ContentCodecs>>(options);
     client.#signer = signer;
 
     await client.init(await signer.getIdentifier());
@@ -126,8 +138,13 @@ export class Client extends ClientWorkerClass {
    * @param options - Optional configuration for the client
    * @returns A new client instance
    */
-  static async build(identifier: Identifier, options?: ClientOptions) {
-    const client = new Client({
+  static async build<ContentCodecs extends ContentCodec[] = []>(
+    identifier: Identifier,
+    options?: Omit<ClientOptions, "codecs"> & {
+      codecs?: ContentCodecs;
+    },
+  ) {
+    const client = new Client<ExtractCodecContentTypes<ContentCodecs>>({
       ...options,
       disableAutoRegister: true,
     });
@@ -210,7 +227,7 @@ export class Client extends ClientWorkerClass {
    * @returns The signature text
    */
   async unsafe_createInboxSignatureText() {
-    return this.sendMessage("createInboxSignatureText", undefined);
+    return this.sendMessage("client.createInboxSignatureText", undefined);
   }
 
   /**
@@ -234,7 +251,7 @@ export class Client extends ClientWorkerClass {
       throw new InboxReassignError();
     }
 
-    return this.sendMessage("addAccountSignatureText", {
+    return this.sendMessage("client.addAccountSignatureText", {
       newIdentifier,
     });
   }
@@ -252,7 +269,7 @@ export class Client extends ClientWorkerClass {
    * @returns The signature text
    */
   async unsafe_removeAccountSignatureText(identifier: Identifier) {
-    return this.sendMessage("removeAccountSignatureText", {
+    return this.sendMessage("client.removeAccountSignatureText", {
       identifier,
     });
   }
@@ -271,7 +288,7 @@ export class Client extends ClientWorkerClass {
    */
   async unsafe_revokeAllOtherInstallationsSignatureText() {
     return this.sendMessage(
-      "revokeAllOtherInstallationsSignatureText",
+      "client.revokeAllOtherInstallationsSignatureText",
       undefined,
     );
   }
@@ -290,7 +307,7 @@ export class Client extends ClientWorkerClass {
    * @returns The signature text
    */
   async unsafe_revokeInstallationsSignatureText(installationIds: Uint8Array[]) {
-    return this.sendMessage("revokeInstallationsSignatureText", {
+    return this.sendMessage("client.revokeInstallationsSignatureText", {
       installationIds,
     });
   }
@@ -309,7 +326,7 @@ export class Client extends ClientWorkerClass {
    * @returns The signature text
    */
   async unsafe_changeRecoveryIdentifierSignatureText(identifier: Identifier) {
-    return this.sendMessage("changeRecoveryIdentifierSignatureText", {
+    return this.sendMessage("client.changeRecoveryIdentifierSignatureText", {
       identifier,
     });
   }
@@ -339,7 +356,7 @@ export class Client extends ClientWorkerClass {
 
     switch (signer.type) {
       case "SCW":
-        await this.sendMessage("addScwSignature", {
+        await this.sendMessage("client.addScwSignature", {
           type: signatureType,
           bytes: signature,
           chainId: signer.getChainId(),
@@ -347,7 +364,7 @@ export class Client extends ClientWorkerClass {
         });
         break;
       case "EOA":
-        await this.sendMessage("addEcdsaSignature", {
+        await this.sendMessage("client.addEcdsaSignature", {
           type: signatureType,
           bytes: signature,
         });
@@ -367,7 +384,7 @@ export class Client extends ClientWorkerClass {
    * methods instead.
    */
   async unsafe_applySignatures() {
-    return this.sendMessage("applySignatures", undefined);
+    return this.sendMessage("client.applySignatures", undefined);
   }
 
   /**
@@ -395,7 +412,7 @@ export class Client extends ClientWorkerClass {
       this.#signer,
     );
 
-    return this.sendMessage("registerIdentity", undefined);
+    return this.sendMessage("client.registerIdentity", undefined);
   }
 
   /**
@@ -578,7 +595,7 @@ export class Client extends ClientWorkerClass {
    * @returns Whether the client is registered
    */
   async isRegistered() {
-    return this.sendMessage("isRegistered", undefined);
+    return this.sendMessage("client.isRegistered", undefined);
   }
 
   /**
@@ -588,7 +605,7 @@ export class Client extends ClientWorkerClass {
    * @returns Whether the client can message the identifiers
    */
   async canMessage(identifiers: Identifier[]) {
-    return this.sendMessage("canMessage", { identifiers });
+    return this.sendMessage("client.canMessage", { identifiers });
   }
 
   /**
@@ -619,7 +636,7 @@ export class Client extends ClientWorkerClass {
    * @returns The inbox ID, if found
    */
   async findInboxIdByIdentifier(identifier: Identifier) {
-    return this.sendMessage("findInboxIdByIdentifier", { identifier });
+    return this.sendMessage("client.findInboxIdByIdentifier", { identifier });
   }
 
   /**
@@ -628,9 +645,9 @@ export class Client extends ClientWorkerClass {
    * @param contentType - The content type to get the codec for
    * @returns The codec, if found
    */
-  codecFor<T = unknown>(contentType: ContentTypeId) {
+  codecFor<ContentType = unknown>(contentType: ContentTypeId) {
     return this.#codecs.get(contentType.toString()) as
-      | ContentCodec<T>
+      | ContentCodec<ContentType>
       | undefined;
   }
 
@@ -642,7 +659,7 @@ export class Client extends ClientWorkerClass {
    * @returns The encoded content
    * @throws {CodecNotFoundError} if no codec is found for the content type
    */
-  encodeContent(content: unknown, contentType: ContentTypeId) {
+  encodeContent(content: ContentTypes, contentType: ContentTypeId) {
     const codec = this.codecFor(contentType);
     if (!codec) {
       throw new CodecNotFoundError(contentType);
@@ -664,8 +681,11 @@ export class Client extends ClientWorkerClass {
    * @throws {CodecNotFoundError} if no codec is found for the content type
    * @throws {InvalidGroupMembershipChangeError} if the message is an invalid group membership change
    */
-  decodeContent<T = unknown>(message: SafeMessage, contentType: ContentTypeId) {
-    const codec = this.codecFor<T>(contentType);
+  decodeContent<ContentType = unknown>(
+    message: SafeMessage,
+    contentType: ContentTypeId,
+  ) {
+    const codec = this.codecFor<ContentType>(contentType);
     if (!codec) {
       throw new CodecNotFoundError(contentType);
     }
@@ -690,7 +710,9 @@ export class Client extends ClientWorkerClass {
    * @returns The signature
    */
   signWithInstallationKey(signatureText: string) {
-    return this.sendMessage("signWithInstallationKey", { signatureText });
+    return this.sendMessage("client.signWithInstallationKey", {
+      signatureText,
+    });
   }
 
   /**
@@ -704,7 +726,7 @@ export class Client extends ClientWorkerClass {
     signatureText: string,
     signatureBytes: Uint8Array,
   ) {
-    return this.sendMessage("verifySignedWithInstallationKey", {
+    return this.sendMessage("client.verifySignedWithInstallationKey", {
       signatureText,
       signatureBytes,
     });
@@ -723,7 +745,7 @@ export class Client extends ClientWorkerClass {
     signatureBytes: Uint8Array,
     publicKey: Uint8Array,
   ) {
-    return this.sendMessage("verifySignedWithPublicKey", {
+    return this.sendMessage("client.verifySignedWithPublicKey", {
       signatureText,
       signatureBytes,
       publicKey,
@@ -737,8 +759,26 @@ export class Client extends ClientWorkerClass {
    * @returns The key package statuses
    */
   async getKeyPackageStatusesForInstallationIds(installationIds: string[]) {
-    return this.sendMessage("getKeyPackageStatusesForInstallationIds", {
+    return this.sendMessage("client.getKeyPackageStatusesForInstallationIds", {
       installationIds,
     });
   }
+
+  apiStatistics() {
+    return this.sendMessage("client.apiStatistics", undefined);
+  }
+
+  apiIdentityStatistics() {
+    return this.sendMessage("client.apiIdentityStatistics", undefined);
+  }
+
+  apiAggregateStatistics() {
+    return this.sendMessage("client.apiAggregateStatistics", undefined);
+  }
+
+  async uploadDebugArchive(serverUrl?: string) {
+    return this.sendMessage("client.uploadDebugArchive", {
+      serverUrl,
+    });
+  }
 }

package/src/ClientWorkerClass.ts

@@ -1,21 +1,31 @@
 import { v4 } from "uuid";
 import type {
-  ClientEventsActions,
-  ClientEventsErrorData,
-  ClientEventsResult,
-  ClientEventsWorkerMessageData,
-  ClientSendMessageData,
-} from "@/types";
+  ActionErrorData,
+  ActionName,
+  ActionWithoutData,
+  ClientWorkerAction,
+  ExtractActionData,
+  ExtractActionResult,
+} from "@/types/actions";
 import type {
-  ClientStreamEvents,
-  ClientStreamEventsErrorData,
-} from "@/types/clientStreamEvents";
+  StreamAction,
+  StreamActionErrorData,
+} from "@/types/actions/streams";
 
 const handleError = (event: ErrorEvent) => {
-  console.error(`Worker error on line ${event.lineno} in "${event.filename}"`);
   console.error(event.message);
 };
 
+/**
+ * Class that sets up a worker and provides communications for client functions
+ *
+ * This class is not meant to be used directly, it is extended by the Client class
+ * to provide an interface to the worker.
+ *
+ * @param worker - The worker to use for the client class
+ * @param enableLogging - Whether to enable logging in the worker
+ * @returns A new ClientWorkerClass instance
+ */
 export class ClientWorkerClass {
   #worker: Worker;
 
@@ -32,13 +42,22 @@ export class ClientWorkerClass {
   constructor(worker: Worker, enableLogging: boolean) {
     this.#worker = worker;
     this.#worker.addEventListener("message", this.handleMessage);
-    this.#worker.addEventListener("error", handleError);
+    if (enableLogging) {
+      this.#worker.addEventListener("error", handleError);
+    }
     this.#enableLogging = enableLogging;
   }
 
-  sendMessage<A extends ClientEventsActions>(
+  /**
+   * Sends an action message to the client worker
+   *
+   * @param action - The action to send to the worker
+   * @param data - The data to send to the worker
+   * @returns A promise that resolves when the action is completed
+   */
+  sendMessage<A extends ActionName<ClientWorkerAction>>(
     action: A,
-    data: ClientSendMessageData<A>,
+    data: ExtractActionData<ClientWorkerAction, A>,
   ) {
     const promiseId = v4();
     this.#worker.postMessage({
@@ -46,17 +65,29 @@ export class ClientWorkerClass {
       id: promiseId,
       data,
     });
-    const promise = new Promise<ClientEventsResult<A>>((resolve, reject) => {
+    const promise = new Promise((resolve, reject) => {
       this.#promises.set(promiseId, {
         resolve: resolve as (value: unknown) => void,
         reject,
       });
     });
-    return promise;
+    return promise as [ExtractActionResult<ClientWorkerAction, A>] extends [
+      undefined,
+    ]
+      ? Promise<void>
+      : Promise<ExtractActionResult<ClientWorkerAction, A>>;
   }
 
+  /**
+   * Handles a message from the client worker
+   *
+   * @param event - The event to handle
+   */
   handleMessage = (
-    event: MessageEvent<ClientEventsWorkerMessageData | ClientEventsErrorData>,
+    event: MessageEvent<
+      | ActionWithoutData<ClientWorkerAction>
+      | ActionErrorData<ClientWorkerAction>
+    >,
   ) => {
     const eventData = event.data;
     if (this.#enableLogging) {
@@ -73,12 +104,19 @@ export class ClientWorkerClass {
     }
   };
 
-  handleStreamMessage = <T extends ClientStreamEvents["result"]>(
+  /**
+   * Handles a stream message from the client worker
+   *
+   * @param streamId - The ID of the stream to handle
+   * @param callback - The callback to handle the stream message
+   * @returns A function to remove the stream handler
+   */
+  handleStreamMessage = <T extends StreamAction["result"]>(
     streamId: string,
     callback: (error: Error | null, value: T | null) => void,
   ) => {
     const streamHandler = (
-      event: MessageEvent<ClientStreamEvents | ClientStreamEventsErrorData>,
+      event: MessageEvent<StreamAction | StreamActionErrorData>,
     ) => {
       const eventData = event.data;
       if (eventData.streamId === streamId) {
@@ -96,9 +134,14 @@ export class ClientWorkerClass {
     };
   };
 
+  /**
+   * Removes all event listeners and terminates the worker
+   */
   close() {
     this.#worker.removeEventListener("message", this.handleMessage);
-    this.#worker.removeEventListener("error", handleError);
+    if (this.#enableLogging) {
+      this.#worker.removeEventListener("error", handleError);
+    }
     this.#worker.terminate();
   }
 }