@xmtp/browser-sdk 6.5.0 → 7.0.0-dev.b5cdc06

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,12 @@ export type {
   Action,
   Actions,
   ApiStats,
+  ArchiveMetadata,
+  ArchiveOptions,
   Attachment,
+  AvailableArchiveInfo,
+  Backend,
+  BackendBuilder,
   Consent,
   ConversationDebugInfo,
   ConversationListItem,
@@ -50,7 +56,6 @@ export type {
   Reaction,
   ReadReceipt,
   RemoteAttachment,
-  RemoteAttachmentInfo,
   Reply,
   SendMessageOpts,
   SignatureRequestHandle,
@@ -59,9 +64,12 @@ export type {
   UserPreferenceUpdate,
   WalletCall,
   WalletSendCalls,
+  WorkerConfigOptions,
+  WorkerIntervalOverride,
 } from "@xmtp/wasm-bindings";
 export {
   ActionStyle,
+  BackupElementSelectionOption,
   ConsentEntityType,
   ConsentState,
   ContentType,
@@ -81,6 +89,7 @@ export {
   ReactionAction,
   ReactionSchema,
   SortDirection,
+  WorkerKind,
 } from "@xmtp/wasm-bindings";
 export * from "./utils/signer";
 export * from "./utils/errors";

package/src/types/actions/client.ts

@@ -1,5 +1,15 @@
-import type { Identifier, KeyPackageStatus } from "@xmtp/wasm-bindings";
-import type { ClientOptions } from "@/types/options";
+import type {
+  ArchiveMetadata,
+  ArchiveOptions,
+  AvailableArchiveInfo,
+  GroupSyncSummary,
+  Identifier,
+  KeyPackageStatus,
+} from "@xmtp/wasm-bindings";
+import type {
+  ClientOptions,
+  VisibilityConfirmationOptions,
+} from "@/types/options";
 import type { SafeSigner } from "@/utils/signer";
 
 export type ClientAction =
@@ -8,6 +18,7 @@ export type ClientAction =
       id: string;
       result: {
         appVersion: string;
+        env: string;
         inboxId: string;
         installationId: string;
         installationIdBytes: Uint8Array;
@@ -104,6 +115,7 @@ export type ClientAction =
       data: {
         signer: SafeSigner;
         signatureRequestId: string;
+        waitForRegistrationVisible?: VisibilityConfirmationOptions;
       };
     }
   | {
@@ -169,6 +181,20 @@ export type ClientAction =
         identifiers: Identifier[];
       };
     }
+  | {
+      action: "client.fetchLatestInboxUpdatesCount";
+      id: string;
+      result: Record<string, number>;
+      data: {
+        inboxIds: string[];
+      };
+    }
+  | {
+      action: "client.fetchOwnInboxUpdatesCount";
+      id: string;
+      result: number;
+      data: Record<string, never>;
+    }
   | {
       action: "client.getInboxIdByIdentifier";
       id: string;
@@ -216,5 +242,67 @@ export type ClientAction =
       action: "client.sendSyncRequest";
       id: string;
       result: undefined;
+      data: {
+        options: ArchiveOptions;
+        serverUrl: string;
+      };
+    }
+  | {
+      action: "client.sendSyncArchive";
+      id: string;
+      result: undefined;
+      data: {
+        options: ArchiveOptions;
+        serverUrl: string;
+        pin: string;
+      };
+    }
+  | {
+      action: "client.processSyncArchive";
+      id: string;
+      result: undefined;
+      data: {
+        archivePin?: string | null;
+      };
+    }
+  | {
+      action: "client.listAvailableArchives";
+      id: string;
+      result: AvailableArchiveInfo[];
+      data: {
+        daysCutoff: number;
+      };
+    }
+  | {
+      action: "client.createArchive";
+      id: string;
+      result: Uint8Array;
+      data: {
+        opts: ArchiveOptions;
+        key: Uint8Array;
+      };
+    }
+  | {
+      action: "client.importArchive";
+      id: string;
+      result: undefined;
+      data: {
+        data: Uint8Array;
+        key: Uint8Array;
+      };
+    }
+  | {
+      action: "client.archiveMetadata";
+      id: string;
+      result: ArchiveMetadata;
+      data: {
+        data: Uint8Array;
+        key: Uint8Array;
+      };
+    }
+  | {
+      action: "client.syncAllDeviceSyncGroups";
+      id: string;
+      result: GroupSyncSummary;
       data: undefined;
     };

package/src/types/options.ts

@@ -5,6 +5,7 @@ import type {
 import type {
   Actions,
   Attachment,
+  Backend,
   DeletedMessage,
   GroupUpdated,
   Intent,
@@ -16,11 +17,21 @@ import type {
   RemoteAttachment,
   TransactionReference,
   WalletSendCalls,
+  WasmVisibilityConfirmationOptions,
+  WorkerConfigOptions,
 } from "@xmtp/wasm-bindings";
-import type { ApiUrls } from "@/constants";
 import type { DecodedMessage } from "@/DecodedMessage";
 
-export type XmtpEnv = keyof typeof ApiUrls;
+export type VisibilityConfirmationOptions = WasmVisibilityConfirmationOptions;
+
+export type XmtpEnv =
+  | "local"
+  | "dev"
+  | "production"
+  | "testnet-staging"
+  | "testnet-dev"
+  | "testnet"
+  | "mainnet";
 
 /**
  * Network options
@@ -35,15 +46,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 = {
@@ -95,20 +120,28 @@ export type OtherOptions = {
    */
   loggingLevel?: LogLevel;
   /**
-   * Disable automatic registration when creating a client
+   * Tuning for the background worker scheduler (intervals, jitter, per-worker
+   * overrides, and disabled workers). All fields are optional; omitting this
+   * object preserves the default worker behavior.
+   *
+   * Intervals are specified in nanoseconds.
    */
-  disableAutoRegister?: boolean;
+  workerConfig?: WorkerConfigOptions;
   /**
-   * Disable device sync
+   * Disable automatic registration when creating a client
    */
-  disableDeviceSync?: boolean;
+  disableAutoRegister?: boolean;
   /**
-   * Custom app version
+   * Options for waiting until client registration is visible on the network.
+   *
+   * When set, `registerIdentity` will wait for the specified quorum of nodes
+   * to confirm the registration before resolving.
    */
-  appVersion?: string;
+  waitForRegistrationVisible?: VisibilityConfirmationOptions;
 };
 
-export type ClientOptions = NetworkOptions &
+export type ClientOptions = (NetworkOptions | { backend: Backend }) &
+  DeviceSyncOptions &
   ContentOptions &
   StorageOptions &
   OtherOptions;

package/src/utils/WorkerBridge.ts

@@ -65,7 +65,7 @@ export class WorkerBridge<T extends UnknownAction> {
     });
     const promise = new Promise((resolve, reject) => {
       this.#promises.set(promiseId, {
-        resolve: resolve as (value: unknown) => void,
+        resolve: resolve,
         reject,
       });
     });

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,92 @@
 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 { createBackend, envToString } from "@/utils/createBackend";
+
+type CreateClientOptions = ClientOptions extends infer T
+  ? T extends ClientOptions
+    ? Omit<T, "codecs">
+    : never
+  : never;
+
+const networkOptionKeys = [
+  "env",
+  "apiUrl",
+  "gatewayHost",
+  "appVersion",
+] as const;
+
+const hasBackend = (options: object): options is { backend: Backend } => {
+  return "backend" in options;
+};
+
+const resolveBackend = async (
+  options?: CreateClientOptions,
+): 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);
+};
 
 export const createClient = async (
   identifier: Identifier,
-  options?: Omit<ClientOptions, "codecs">,
+  options?: CreateClientOptions,
 ) => {
-  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,
+    options?.workerConfig,
     isLogging
       ? {
           structured: options.structuredLogging ?? false,
@@ -54,11 +95,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,