@xmtp/browser-sdk 6.4.0 → 6.4.1

package/src/Client.ts

@@ -1,5 +1,11 @@
 import { type ContentCodec } from "@xmtp/content-type-primitives";
-import { LogLevel, type Identifier } from "@xmtp/wasm-bindings";
+import {
+  Backend,
+  LogLevel,
+  type ArchiveOptions,
+  type Identifier,
+  type InboxState,
+} from "@xmtp/wasm-bindings";
 import { CodecRegistry } from "@/CodecRegistry";
 import { Conversations } from "@/Conversations";
 import { DebugInformation } from "@/DebugInformation";
@@ -10,6 +16,7 @@ import type {
   ExtractCodecContentTypes,
   XmtpEnv,
 } from "@/types/options";
+import { createBackend } from "@/utils/createBackend";
 import {
   AccountAlreadyAssociatedError,
   InboxReassignError,
@@ -22,6 +29,23 @@ import { toSafeSigner, type SafeSigner, type Signer } from "@/utils/signer";
 import { uuid } from "@/utils/uuid";
 import { WorkerBridge } from "@/utils/WorkerBridge";
 
+/**
+ * Resolves a `Backend` instance from either a `Backend` or an `XmtpEnv` string.
+ *
+ * @param envOrBackend - A `Backend` instance, or an `XmtpEnv` string
+ * @param gatewayHost - Optional gateway host (only used when `envOrBackend` is an `XmtpEnv`)
+ * @returns A `Backend` instance
+ */
+const resolveBackend = async (
+  envOrBackend?: XmtpEnv | Backend,
+  gatewayHost?: string,
+): Promise<Backend> => {
+  if (envOrBackend instanceof Backend) {
+    return envOrBackend;
+  }
+  return createBackend({ env: envOrBackend, gatewayHost });
+};
+
 /**
  * Client for interacting with the XMTP network
  */
@@ -30,6 +54,7 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
   #codecRegistry: CodecRegistry;
   #conversations: Conversations<ContentTypes>;
   #debugInformation: DebugInformation;
+  #env?: XmtpEnv;
   #identifier?: Identifier;
   #inboxId?: string;
   #installationId?: string;
@@ -50,6 +75,21 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
    * @param options - Optional configuration for the client
    */
   constructor(options?: ClientOptions) {
+    /*
+     * The Browser SDK runs XMTP's WASM bindings inside a Web Worker.
+     * The SDK sends options to the worker via postMessage(), which uses the
+     * structured clone algorithm. Codecs contain functions that can't be
+     * cloned, so we mark the codecs property as non-enumerable to exclude
+     * it from serialization.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#things_that_dont_work_with_structured_clone
+     */
+    if (options) {
+      Object.defineProperty(options, "codecs", {
+        value: options.codecs,
+        enumerable: false,
+      });
+    }
     const worker = new Worker(new URL("./workers/client", import.meta.url), {
       type: "module",
     });
@@ -57,8 +97,8 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
       options?.loggingLevel !== undefined &&
       options.loggingLevel !== LogLevel.Off;
     this.#worker = new WorkerBridge<ClientWorkerAction>(worker, enableLogging);
-    this.#options = options;
     this.#codecRegistry = new CodecRegistry([...(options?.codecs ?? [])]);
+    this.#options = options;
     this.#conversations = new Conversations(
       this,
       this.#worker,
@@ -82,6 +122,7 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
       options: this.#options,
     });
     this.#appVersion = result.appVersion;
+    this.#env = result.env as XmtpEnv;
     this.#identifier = identifier;
     this.#inboxId = result.inboxId;
     this.#installationId = result.installationId;
@@ -231,6 +272,13 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
     return this.#appVersion;
   }
 
+  /**
+   * Gets the XMTP environment used by this client
+   */
+  get env() {
+    return this.#env;
+  }
+
   /**
    * Creates signature text for creating a new inbox
    *
@@ -544,10 +592,27 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
   /**
    * Revokes specific installations of the client's inbox without a client
    *
-   * @param env - The environment to use
    * @param signer - The signer to use
    * @param inboxId - The inbox ID to revoke installations for
    * @param installationIds - The installation IDs to revoke
+   * @param backend - Optional `Backend` instance created with `createBackend()`
+   */
+  static async revokeInstallations(
+    signer: Signer,
+    inboxId: string,
+    installationIds: Uint8Array[],
+    backend?: Backend,
+  ): Promise<void>;
+  /**
+   * Revokes specific installations of the client's inbox without a client
+   *
+   * @param signer - The signer to use
+   * @param inboxId - The inbox ID to revoke installations for
+   * @param installationIds - The installation IDs to revoke
+   * @param env - The environment to use
+   * @param gatewayHost - Optional gateway host
+   * @deprecated Pass a `Backend` instance created with `createBackend()` instead
+   * of `XmtpEnv` and `gatewayHost`.
    */
   static async revokeInstallations(
     signer: Signer,
@@ -555,30 +620,53 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
     installationIds: Uint8Array[],
     env?: XmtpEnv,
     gatewayHost?: string,
+  ): Promise<void>;
+  static async revokeInstallations(
+    signer: Signer,
+    inboxId: string,
+    installationIds: Uint8Array[],
+    envOrBackend?: XmtpEnv | Backend,
+    gatewayHost?: string,
   ) {
-    await utilsRevokeInstallations(
-      signer,
-      inboxId,
-      installationIds,
-      env,
-      gatewayHost,
-    );
+    const backend = await resolveBackend(envOrBackend, gatewayHost);
+    await utilsRevokeInstallations(backend, signer, inboxId, installationIds);
   }
 
+  /**
+   * Fetches the inbox states for the specified inbox IDs from the network
+   * without a client
+   *
+   * @param inboxIds - The inbox IDs to get the state for
+   * @param backend - Optional `Backend` instance created with `createBackend()`
+   * @returns The inbox states for the specified inbox IDs
+   */
+  static async fetchInboxStates(
+    inboxIds: string[],
+    backend?: Backend,
+  ): Promise<InboxState[]>;
   /**
    * Fetches the inbox states for the specified inbox IDs from the network
    * without a client
    *
    * @param inboxIds - The inbox IDs to get the state for
    * @param env - The environment to use
+   * @param gatewayHost - Optional gateway host
    * @returns The inbox states for the specified inbox IDs
+   * @deprecated Pass a `Backend` instance created with `createBackend()` instead
+   * of `XmtpEnv` and `gatewayHost`.
    */
   static async fetchInboxStates(
     inboxIds: string[],
     env?: XmtpEnv,
     gatewayHost?: string,
+  ): Promise<InboxState[]>;
+  static async fetchInboxStates(
+    inboxIds: string[],
+    envOrBackend?: XmtpEnv | Backend,
+    gatewayHost?: string,
   ) {
-    return utilsInboxStateFromInboxIds(inboxIds, env, gatewayHost);
+    const backend = await resolveBackend(envOrBackend, gatewayHost);
+    return utilsInboxStateFromInboxIds(backend, inboxIds);
   }
 
   /**
@@ -625,17 +713,40 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
     return this.#worker.action("client.canMessage", { identifiers });
   }
 
+  /**
+   * Checks if the specified identifiers can be messaged
+   *
+   * @param identifiers - The identifiers to check
+   * @param backend - Optional `Backend` instance created with `createBackend()`
+   * @returns Map of identifiers to whether they can be messaged
+   */
+  static async canMessage(
+    identifiers: Identifier[],
+    backend?: Backend,
+  ): Promise<Map<string, boolean>>;
   /**
    * 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
+   * @deprecated Pass a `Backend` instance created with `createBackend()` instead
+   * of `XmtpEnv`.
    */
-  static async canMessage(identifiers: Identifier[], env?: XmtpEnv) {
+  /* eslint-disable @typescript-eslint/unified-signatures */
+  static async canMessage(
+    identifiers: Identifier[],
+    env?: XmtpEnv,
+  ): Promise<Map<string, boolean>>;
+  /* eslint-enable @typescript-eslint/unified-signatures */
+  static async canMessage(
+    identifiers: Identifier[],
+    envOrBackend?: XmtpEnv | Backend,
+  ) {
+    const backend = await resolveBackend(envOrBackend);
     const canMessageMap = new Map<string, boolean>();
     for (const identifier of identifiers) {
-      const inboxId = await getInboxIdForIdentifier(identifier, env);
+      const inboxId = await getInboxIdForIdentifier(backend, identifier);
       canMessageMap.set(
         identifier.identifier.toLowerCase(),
         inboxId !== undefined,
@@ -720,9 +831,14 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
   /**
    * Send a sync request to other devices on the network
    *
+   * @param options - Archive options specifying what to sync
+   * @param serverUrl - The server URL for the sync request
    * @returns Promise that resolves when the sync request is sent
    */
-  async sendSyncRequest() {
-    return this.#worker.action("client.sendSyncRequest");
+  async sendSyncRequest(options: ArchiveOptions, serverUrl: string) {
+    return this.#worker.action("client.sendSyncRequest", {
+      options,
+      serverUrl,
+    });
   }
 }

package/src/Conversations.ts

@@ -295,7 +295,7 @@ export class Conversations<ContentTypes = unknown> {
   /**
    * Creates a new group conversation with the specified inbox IDs
    *
-   * @param inboxIds - Array of inbox IDs for group members
+   * @param inboxIds - Array of inbox IDs for other group members (the creator is included automatically)
    * @param options - Optional group creation options
    * @returns Promise that resolves with the new group
    */

package/src/WorkerClient.ts

@@ -1,11 +1,12 @@
 import {
   verifySignedWithPublicKey,
+  type ArchiveOptions,
   type Client,
   type Identifier,
   type KeyPackageStatus,
   type SignatureRequestHandle,
 } from "@xmtp/wasm-bindings";
-import type { ClientOptions } from "@/types/options";
+import type { ClientOptions, XmtpEnv } from "@/types/options";
 import { createClient } from "@/utils/createClient";
 import type { SafeSigner } from "@/utils/signer";
 import { WorkerConversations } from "@/WorkerConversations";
@@ -16,10 +17,12 @@ export class WorkerClient {
   #client: Client;
   #conversations: WorkerConversations;
   #debugInformation: WorkerDebugInformation;
+  #env: XmtpEnv;
   #preferences: WorkerPreferences;
 
-  constructor(client: Client) {
+  constructor(client: Client, env: XmtpEnv) {
     this.#client = client;
+    this.#env = env;
     const conversations = client.conversations();
     this.#conversations = new WorkerConversations(this, conversations);
     this.#debugInformation = new WorkerDebugInformation(client);
@@ -30,8 +33,8 @@ export class WorkerClient {
     identifier: Identifier,
     options?: Omit<ClientOptions, "codecs">,
   ) {
-    const client = await createClient(identifier, options);
-    return new WorkerClient(client);
+    const { client, env } = await createClient(identifier, options);
+    return new WorkerClient(client, env);
   }
 
   get libxmtpVersion() {
@@ -42,6 +45,10 @@ export class WorkerClient {
     return this.#client.appVersion;
   }
 
+  get env() {
+    return this.#env;
+  }
+
   get accountIdentifier() {
     return this.#client.accountIdentifier;
   }
@@ -144,7 +151,7 @@ export class WorkerClient {
   }
 
   async getInboxIdByIdentifier(identifier: Identifier) {
-    return this.#client.findInboxIdByIdentifier(identifier);
+    return this.#client.findInboxIdByIdentity(identifier);
   }
 
   signWithInstallationKey(signatureText: string) {
@@ -185,7 +192,7 @@ export class WorkerClient {
     ) as Promise<Map<string, KeyPackageStatus>>;
   }
 
-  async sendSyncRequest() {
-    return this.#client.sendSyncRequest();
+  async sendSyncRequest(options: ArchiveOptions, serverUrl: string) {
+    return this.#client.device_sync().sendSyncRequest(options, serverUrl);
   }
 }

package/src/WorkerConversation.ts

@@ -153,19 +153,19 @@ export class WorkerConversation {
   }
 
   async addMembersByIdentifiers(identifiers: Identifier[]) {
-    return this.#group.addMembers(identifiers);
+    return this.#group.addMembersByIdentity(identifiers);
   }
 
   async addMembers(inboxIds: string[]) {
-    return this.#group.addMembersByInboxId(inboxIds);
+    return this.#group.addMembers(inboxIds);
   }
 
   async removeMembersByIdentifiers(identifiers: Identifier[]) {
-    return this.#group.removeMembers(identifiers);
+    return this.#group.removeMembersByIdentity(identifiers);
   }
 
   async removeMembers(inboxIds: string[]) {
-    return this.#group.removeMembersByInboxId(inboxIds);
+    return this.#group.removeMembers(inboxIds);
   }
 
   async addAdmin(inboxId: string) {

package/src/constants.ts

@@ -1,6 +1,7 @@
 /**
  * Pre-configured URLs for the XMTP network based on the environment
  *
+ * @deprecated Use `createBackend()` instead.
  * @constant
  * @property {string} local - The local URL for the XMTP network
  * @property {string} dev - The development URL for the XMTP network
@@ -24,4 +25,8 @@ export const HistorySyncUrls = {
   local: "http://localhost:5558",
   dev: "https://message-history.dev.ephemera.network",
   production: "https://message-history.production.ephemera.network",
+  "testnet-staging": "https://message-history.dev.ephemera.network",
+  "testnet-dev": "https://message-history.dev.ephemera.network",
+  testnet: "https://message-history.dev.ephemera.network",
+  mainnet: "https://message-history.production.ephemera.network",
 } as const;

package/src/index.ts

@@ -5,6 +5,7 @@ export { Conversation } from "./Conversation";
 export { Dm } from "./Dm";
 export { Group } from "./Group";
 export { DecodedMessage } from "./DecodedMessage";
+export { createBackend } from "./utils/createBackend";
 export { generateInboxId, getInboxIdForIdentifier } from "./utils/inboxId";
 export { metadataFieldName } from "./utils/metadata";
 export { ApiUrls, HistorySyncUrls } from "./constants";
@@ -16,7 +17,10 @@ export type {
   Action,
   Actions,
   ApiStats,
+  ArchiveOptions,
   Attachment,
+  Backend,
+  BackendBuilder,
   Consent,
   ConversationDebugInfo,
   ConversationListItem,
@@ -50,7 +54,6 @@ export type {
   Reaction,
   ReadReceipt,
   RemoteAttachment,
-  RemoteAttachmentInfo,
   Reply,
   SendMessageOpts,
   SignatureRequestHandle,
@@ -62,6 +65,7 @@ export type {
 } from "@xmtp/wasm-bindings";
 export {
   ActionStyle,
+  BackupElementSelectionOption,
   ConsentEntityType,
   ConsentState,
   ContentType,

package/src/types/actions/client.ts

@@ -1,4 +1,8 @@
-import type { Identifier, KeyPackageStatus } from "@xmtp/wasm-bindings";
+import type {
+  ArchiveOptions,
+  Identifier,
+  KeyPackageStatus,
+} from "@xmtp/wasm-bindings";
 import type { ClientOptions } from "@/types/options";
 import type { SafeSigner } from "@/utils/signer";
 
@@ -8,6 +12,7 @@ export type ClientAction =
       id: string;
       result: {
         appVersion: string;
+        env: string;
         inboxId: string;
         installationId: string;
         installationIdBytes: Uint8Array;
@@ -216,5 +221,8 @@ export type ClientAction =
       action: "client.sendSyncRequest";
       id: string;
       result: undefined;
-      data: undefined;
+      data: {
+        options: ArchiveOptions;
+        serverUrl: string;
+      };
     };

package/src/types/options.ts

@@ -5,6 +5,7 @@ import type {
 import type {
   Actions,
   Attachment,
+  Backend,
   DeletedMessage,
   GroupUpdated,
   Intent,
@@ -17,10 +18,16 @@ import type {
   TransactionReference,
   WalletSendCalls,
 } from "@xmtp/wasm-bindings";
-import type { ApiUrls } from "@/constants";
 import type { DecodedMessage } from "@/DecodedMessage";
 
-export type XmtpEnv = keyof typeof ApiUrls;
+export type XmtpEnv =
+  | "local"
+  | "dev"
+  | "production"
+  | "testnet-staging"
+  | "testnet-dev"
+  | "testnet"
+  | "mainnet";
 
 /**
  * Network options
@@ -35,15 +42,29 @@ export type NetworkOptions = {
    * specific endpoint
    */
   apiUrl?: string;
+  /**
+   * gatewayHost can be used to override the gateway endpoint
+   */
+  gatewayHost?: string;
+  /**
+   * Custom app version
+   */
+  appVersion?: string;
+};
+
+/**
+ * Device sync options
+ */
+export type DeviceSyncOptions = {
   /**
    * historySyncUrl can be used to override the `env` flag and connect to a
    * specific endpoint for syncing history
    */
   historySyncUrl?: string | null;
   /**
-   * gatewayHost can be used to override the gateway endpoint
+   * Disable device sync
    */
-  gatewayHost?: string | null;
+  disableDeviceSync?: boolean;
 };
 
 export type ContentOptions = {
@@ -98,17 +119,10 @@ export type OtherOptions = {
    * Disable automatic registration when creating a client
    */
   disableAutoRegister?: boolean;
-  /**
-   * Disable device sync
-   */
-  disableDeviceSync?: boolean;
-  /**
-   * Custom app version
-   */
-  appVersion?: string;
 };
 
-export type ClientOptions = NetworkOptions &
+export type ClientOptions = (NetworkOptions | { backend: Backend }) &
+  DeviceSyncOptions &
   ContentOptions &
   StorageOptions &
   OtherOptions;

package/src/utils/createBackend.ts

@@ -0,0 +1,45 @@
+import init, {
+  BackendBuilder,
+  XmtpEnv as BindingsEnv,
+  type Backend,
+} from "@xmtp/wasm-bindings";
+import type { NetworkOptions, XmtpEnv } from "@/types/options";
+
+const envMap: Record<XmtpEnv, BindingsEnv> = {
+  local: BindingsEnv.Local,
+  dev: BindingsEnv.Dev,
+  production: BindingsEnv.Production,
+  "testnet-staging": BindingsEnv.TestnetStaging,
+  "testnet-dev": BindingsEnv.TestnetDev,
+  testnet: BindingsEnv.Testnet,
+  mainnet: BindingsEnv.Mainnet,
+};
+
+const reverseEnvMap: Record<BindingsEnv, XmtpEnv> = {
+  [BindingsEnv.Local]: "local",
+  [BindingsEnv.Dev]: "dev",
+  [BindingsEnv.Production]: "production",
+  [BindingsEnv.TestnetStaging]: "testnet-staging",
+  [BindingsEnv.TestnetDev]: "testnet-dev",
+  [BindingsEnv.Testnet]: "testnet",
+  [BindingsEnv.Mainnet]: "mainnet",
+};
+
+export const envToString = (env: BindingsEnv): XmtpEnv => {
+  return reverseEnvMap[env];
+};
+
+export const createBackend = async (
+  options?: NetworkOptions,
+): Promise<Backend> => {
+  await init();
+  const env = options?.env ?? "dev";
+  let builder = new BackendBuilder(envMap[env]);
+  // WASM builder methods consume `self` and return a new instance,
+  // so we must reassign from the return value.
+  if (options?.apiUrl) builder = builder.setApiUrl(options.apiUrl);
+  if (options?.gatewayHost)
+    builder = builder.setGatewayHost(options.gatewayHost);
+  if (options?.appVersion) builder = builder.setAppVersion(options.appVersion);
+  return builder.build();
+};

package/src/utils/createClient.ts

@@ -1,51 +1,85 @@
 import {
-  createClient as createWasmClient,
-  DeviceSyncWorkerMode,
+  createClientWithBackend,
+  DeviceSyncMode,
   generateInboxId,
   getInboxIdForIdentifier,
+  type Backend,
   type Identifier,
 } from "@xmtp/wasm-bindings";
-import { ApiUrls, HistorySyncUrls } from "@/constants";
-import type { ClientOptions } from "@/types/options";
+import type { ClientOptions, NetworkOptions } from "@/types/options";
+import { createBackend, envToString } from "@/utils/createBackend";
+
+const networkOptionKeys = [
+  "env",
+  "apiUrl",
+  "gatewayHost",
+  "appVersion",
+] as const;
+
+const hasBackend = (options: object): options is { backend: Backend } => {
+  return "backend" in options;
+};
+
+const resolveBackend = async (
+  options?: Omit<ClientOptions, "codecs">,
+): Promise<Backend> => {
+  if (!options) {
+    return createBackend();
+  }
+
+  if (hasBackend(options)) {
+    // Validate that no NetworkOptions fields are also set
+    const conflicting = networkOptionKeys.filter(
+      (key) =>
+        key in options && (options as Record<string, unknown>)[key] != null,
+    );
+    if (conflicting.length > 0) {
+      throw new Error(
+        `Cannot specify both 'backend' and network options (${conflicting.join(", ")}). ` +
+          `Use either a pre-built Backend or network options, not both.`,
+      );
+    }
+    return options.backend;
+  }
+
+  // No backend provided — build one from NetworkOptions
+  return createBackend(options as NetworkOptions);
+};
 
 export const createClient = async (
   identifier: Identifier,
   options?: Omit<ClientOptions, "codecs">,
 ) => {
-  const env = options?.env || "dev";
-  const host = options?.apiUrl || ApiUrls[env];
-  const gatewayHost = options?.gatewayHost || undefined;
-  const isSecure = host.startsWith("https");
+  const backend = await resolveBackend(options);
+
   const inboxId =
-    (await getInboxIdForIdentifier(host, gatewayHost, isSecure, identifier)) ||
+    (await getInboxIdForIdentifier(backend, identifier)) ||
     generateInboxId(identifier);
+
+  const envString = envToString(backend.env);
+
   const dbPath =
     options?.dbPath === undefined
-      ? `xmtp-${env}-${inboxId}.db3`
+      ? `xmtp-${envString}-${inboxId}.db3`
       : options.dbPath;
+
   const isLogging =
     options &&
     (options.loggingLevel !== undefined ||
       options.structuredLogging ||
       options.performanceLogging);
 
-  const historySyncUrl =
-    options?.historySyncUrl === undefined
-      ? HistorySyncUrls[env]
-      : options.historySyncUrl;
-
-  const deviceSyncWorkerMode = options?.disableDeviceSync
-    ? DeviceSyncWorkerMode.Disabled
-    : DeviceSyncWorkerMode.Enabled;
+  const deviceSyncMode = options?.disableDeviceSync
+    ? DeviceSyncMode.Disabled
+    : DeviceSyncMode.Enabled;
 
-  return createWasmClient(
-    host,
+  const client = await createClientWithBackend(
+    backend,
     inboxId,
     identifier,
     dbPath,
     options?.dbEncryptionKey,
-    historySyncUrl,
-    deviceSyncWorkerMode,
+    deviceSyncMode,
     isLogging
       ? {
           structured: options.structuredLogging ?? false,
@@ -54,11 +88,8 @@ export const createClient = async (
         }
       : undefined,
     undefined, // allowOffline
-    options?.appVersion,
-    options?.gatewayHost,
     undefined, // nonce
-    undefined, // authCallback
-    undefined, // authHandle
-    undefined, // clientMode
   );
+
+  return { client, env: envString };
 };