@xmtp/browser-sdk 6.5.0 → 7.0.0

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 };
 };

package/src/utils/inboxId.ts

@@ -1,10 +1,9 @@
 import init, {
   generateInboxId as wasmGenerateInboxId,
   getInboxIdForIdentifier as wasmGetInboxIdForIdentifier,
+  type Backend,
   type Identifier,
 } from "@xmtp/wasm-bindings";
-import { ApiUrls } from "@/constants";
-import type { XmtpEnv } from "@/types/options";
 
 /**
  * Generates an inbox ID for a given identifier
@@ -22,25 +21,16 @@ export const generateInboxId = async (
 };
 
 /**
- * Gets the inbox ID for a specific identifier and optional environment
+ * Gets the inbox ID for a specific identifier using a Backend
  *
+ * @param backend - The Backend instance for API communication
  * @param identifier - The identifier to get the inbox ID for
- * @param env - Optional XMTP environment configuration (default: "dev")
- * @param gatewayHost - Optional gateway host override
  * @returns Promise that resolves with the inbox ID for the identifier
  */
 export const getInboxIdForIdentifier = async (
+  backend: Backend,
   identifier: Identifier,
-  env?: XmtpEnv,
-  gatewayHost?: string,
 ): Promise<string | undefined> => {
   await init();
-  const host = env ? ApiUrls[env] : ApiUrls.dev;
-  const isSecure = host.startsWith("https");
-  return wasmGetInboxIdForIdentifier(
-    host,
-    gatewayHost ?? null,
-    isSecure,
-    identifier,
-  );
+  return wasmGetInboxIdForIdentifier(backend, identifier);
 };

package/src/utils/inboxState.ts

@@ -1,23 +1,19 @@
 import init, {
   inboxStateFromInboxIds as wasmInboxStateFromInboxIds,
+  type Backend,
 } from "@xmtp/wasm-bindings";
-import { ApiUrls } from "@/constants";
-import type { XmtpEnv } from "@/types/options";
 
 /**
- * Gets the inbox state for the specified inbox IDs without a client
+ * Gets the inbox state for the specified inbox IDs using a Backend
  *
+ * @param backend - The Backend instance for API communication
  * @param inboxIds - The inbox IDs to get the state for
- * @param env - Optional XMTP environment configuration (default: "dev")
- * @param gatewayHost - Optional gateway host override
  * @returns The inbox state for the specified inbox IDs
  */
 export const inboxStateFromInboxIds = async (
+  backend: Backend,
   inboxIds: string[],
-  env?: XmtpEnv,
-  gatewayHost?: string,
 ) => {
   await init();
-  const host = ApiUrls[env ?? "dev"];
-  return wasmInboxStateFromInboxIds(host, gatewayHost ?? null, inboxIds);
+  return wasmInboxStateFromInboxIds(backend, inboxIds);
 };

package/src/utils/installations.ts

@@ -1,11 +1,10 @@
 import init, {
   applySignatureRequest,
   revokeInstallationsSignatureRequest,
+  type Backend,
   type Identifier,
   type SignatureRequestHandle,
 } from "@xmtp/wasm-bindings";
-import { ApiUrls } from "@/constants";
-import type { XmtpEnv } from "@/types/options";
 import type { Signer } from "@/utils/signer";
 
 /**
@@ -17,28 +16,24 @@ import type { Signer } from "@/utils/signer";
  *
  * It is highly recommended to use the `revokeInstallations` function instead.
  *
+ * @param backend - The Backend instance for API communication
  * @param identifier - The identifier to revoke installations for
  * @param inboxId - The inbox ID to revoke installations for
  * @param installationIds - The installation IDs to revoke
- * @param env - Optional XMTP environment configuration (default: "dev")
- * @param gatewayHost - Optional gateway host override
  * @returns The signature text and signature request ID
  */
 export const revokeInstallationsSignatureText = async (
+  backend: Backend,
   identifier: Identifier,
   inboxId: string,
   installationIds: Uint8Array[],
-  env?: XmtpEnv,
-  gatewayHost?: string,
 ): Promise<{
   signatureText: string;
   signatureRequest: SignatureRequestHandle;
 }> => {
   await init();
-  const host = ApiUrls[env ?? "dev"];
   const signatureRequest = revokeInstallationsSignatureRequest(
-    host,
-    gatewayHost ?? null,
+    backend,
     identifier,
     inboxId,
     installationIds,
@@ -50,32 +45,28 @@ export const revokeInstallationsSignatureText = async (
 /**
  * Revokes installations for a given inbox ID
  *
+ * @param backend - The Backend instance for API communication
  * @param signer - The signer to use
  * @param inboxId - The inbox ID to revoke installations for
  * @param installationIds - The installation IDs to revoke
- * @param env - Optional XMTP environment configuration (default: "dev")
- * @param gatewayHost - Optional gateway host override
  * @returns Promise that resolves when the revoke installations operation is complete
  */
 export const revokeInstallations = async (
+  backend: Backend,
   signer: Signer,
   inboxId: string,
   installationIds: Uint8Array[],
-  env?: XmtpEnv,
-  gatewayHost?: string,
 ): Promise<void> => {
   await init();
   const identifier = await signer.getIdentifier();
   const { signatureText, signatureRequest } =
     await revokeInstallationsSignatureText(
+      backend,
       identifier,
       inboxId,
       installationIds,
-      env,
-      gatewayHost,
     );
   const signature = await signer.signMessage(signatureText);
-  const host = ApiUrls[env ?? "dev"];
 
   switch (signer.type) {
     case "EOA":
@@ -91,5 +82,5 @@ export const revokeInstallations = async (
       break;
   }
 
-  await applySignatureRequest(host, gatewayHost ?? null, signatureRequest);
+  await applySignatureRequest(backend, signatureRequest);
 };

package/src/utils/signer.ts

@@ -1,4 +1,6 @@
-import type { Identifier } from "@xmtp/wasm-bindings";
+import { IdentifierKind, type Identifier } from "@xmtp/wasm-bindings";
+import { toBytes } from "viem";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
 
 type SignMessage = (message: string) => Promise<Uint8Array> | Uint8Array;
 type GetIdentifier = () => Promise<Identifier> | Identifier;
@@ -36,6 +38,40 @@ export type SafeSigner =
       blockNumber?: bigint;
     };
 
+export const createEOASigner = (key = generatePrivateKey()): Signer => {
+  const account = privateKeyToAccount(key);
+  return {
+    type: "EOA",
+    getIdentifier: () => ({
+      identifier: account.address.toLowerCase(),
+      identifierKind: IdentifierKind.Ethereum,
+    }),
+    signMessage: async (message: string) => {
+      const signature = await account.signMessage({ message });
+      return toBytes(signature);
+    },
+  };
+};
+
+export const createSCWSigner = (
+  address: `0x${string}`,
+  signMessage: (message: string) => Promise<string> | string,
+  chainId: bigint,
+): Signer => {
+  return {
+    type: "SCW",
+    getIdentifier: () => ({
+      identifier: address.toLowerCase(),
+      identifierKind: IdentifierKind.Ethereum,
+    }),
+    signMessage: async (message: string) => {
+      const signature = await signMessage(message);
+      return toBytes(signature);
+    },
+    getChainId: () => chainId,
+  };
+};
+
 export const toSafeSigner = async (
   signer: Signer,
   signature: Uint8Array,

package/src/workers/client.ts

@@ -91,6 +91,7 @@ self.onmessage = async (
         action,
         result: {
           appVersion: maybeClient.appVersion,
+          env: maybeClient.env,
           inboxId: maybeClient.inboxId,
           installationId: maybeClient.installationId,
           installationIdBytes: maybeClient.installationIdBytes,
@@ -338,10 +339,45 @@ self.onmessage = async (
         break;
       }
       case "client.sendSyncRequest": {
-        await client.sendSyncRequest();
+        await client.sendSyncRequest(data.options, data.serverUrl);
         postMessage({ id, action, result: undefined });
         break;
       }
+      case "client.sendSyncArchive": {
+        await client.sendSyncArchive(data.options, data.serverUrl, data.pin);
+        postMessage({ id, action, result: undefined });
+        break;
+      }
+      case "client.processSyncArchive": {
+        await client.processSyncArchive(data.archivePin);
+        postMessage({ id, action, result: undefined });
+        break;
+      }
+      case "client.listAvailableArchives": {
+        const result = client.listAvailableArchives(data.daysCutoff);
+        postMessage({ id, action, result });
+        break;
+      }
+      case "client.createArchive": {
+        const result = await client.createArchive(data.opts, data.key);
+        postMessage({ id, action, result });
+        break;
+      }
+      case "client.importArchive": {
+        await client.importArchive(data.data, data.key);
+        postMessage({ id, action, result: undefined });
+        break;
+      }
+      case "client.archiveMetadata": {
+        const result = await client.archiveMetadata(data.data, data.key);
+        postMessage({ id, action, result });
+        break;
+      }
+      case "client.syncAllDeviceSyncGroups": {
+        const result = await client.syncAllDeviceSyncGroups();
+        postMessage({ id, action, result });
+        break;
+      }
       /**
        * Debug information actions
        */