Allow passing a backend into static methods (#1724)

# Allowing passing a backend into static methods

- Upgrades to a `dev` release of the Node and WASM bindings, which changes the way backend configuration is passed for all static methods
- This deprecates the old way of passing configuration in to static methods `Client.someStaticMethod(env, gatewayHost, ...)` and replaces it with a new method that takes a backend. We don't break the old way, but if you use it you will see a deprecation warning in your IDE.
- Makes some changes to the `ClientOptions` to allow callers to pass in a backend explicitly. This lets you re-use the same backend between static methods and instantiated clients like we do on mobile.
- Deprecates the `ApiUrls` and moves those constants to Rust

## Changes

### Design Documentation
- Add comprehensive design document outlining the migration strategy and backwards compatibility approach

### Bindings Updates
- Upgrade `@xmtp/wasm-bindings` from 1.9.1 to 1.10.0-dev.a2bdd0a
- Upgrade `@xmtp/node-bindings` from 1.10.0-dev.55280fa to 1.10.0-dev.a2bdd0a
- Fix method renames: `findInboxIdByIdentifier` → `findInboxIdByIdentity`, member management method updates
- Update `sendSyncRequest` to accept `ArchiveOptions` and `serverUrl` parameters

### New Backend Utilities
- Add `createBackend` utility in both SDKs that wraps `BackendBuilder` with proper environment mapping
- Export `Backend`, `BackendBuilder`, and `createBackend` from both SDK index files

### Type System Refactoring
- Move `appVersion` from `OtherOptions` to `NetworkOptions`
- Extract `DeviceSyncOptions` containing `historySyncUrl` and `disableDeviceSync`
- Update `ClientOptions` to union type: `(NetworkOptions | { backend: Backend }) & DeviceSyncOptions & ...`
- Add runtime validation preventing simultaneous `backend` and `NetworkOptions` usage

### Static Method Migration
- Update all static methods to accept `envOrBackend?: XmtpEnv | Backend` parameter
- Add `resolveBackend` helper that handles backwards compatibility
- Deprecate `env` and `gatewayHost` parameters with JSDoc annotations
- Methods updated:
  - `Client.revokeInstallations`
  - `Client.fetchInboxStates` 
  - `Client.canMessage`
  - `Client.isAddressAuthorized` (node-sdk only)
  - `Client.isInstallationAuthorized` (node-sdk only)

### Client Creation Updates
- Replace `createClient`/`createWasmClient` with `createClientWithBackend`
- Update `getInboxIdForIdentifier` to use `Backend` instead of raw host parameters
- Migrate utility functions (`inboxState`, `installations`) to accept `Backend`

### Testing
- Add comprehensive tests for `createBackend` in both SDKs
- Mock `BackendBuilder.build()` in node-sdk tests for Tokio runtime compatibility
- Use real WASM bindings in browser-sdk tests
- Update test helpers to work with new type system

The migration maintains full backwards compatibility - existing code using `env` and `gatewayHost` parameters continues to work unchanged, while new code can use the more flexible `Backend` approach.

<!-- Macroscope's pull request summary starts here -->
<!-- Macroscope will only edit the content between these invisible markers, and the markers themselves will not be visible in the GitHub rendered markdown. -->
<!-- If you delete either of the start / end markers from your PR's description, Macroscope will append its summary at the bottom of the description. -->
> [!NOTE]
> ### Allow passing a Backend instance into static Client methods across browser and node SDKs
> - Adds a `createBackend` utility (browser and node) that constructs a typed `Backend` from env/apiUrl/gatewayHost options, and exports it from both SDKs.
> - Overloads static methods (`canMessage`, `fetchInboxStates`, `revokeInstallations`, `isAddressAuthorized`, `isInstallationAuthorized`) to accept either a pre-built `Backend` or the legacy `env`+`gatewayHost` strings (now deprecated).
> - Adds a `Client.env` getter so callers can read the environment after initialization; the worker response for `client.init` now includes `env`.
> - Updates `sendSyncRequest` to require `(options: ArchiveOptions, serverUrl: string)`; `ConversationsNavbar` resolves `serverUrl` from `HistorySyncUrls[client.env]`.
> - Expands `XmtpEnv` to an explicit string union (`local | dev | production | testnet-staging | testnet-dev | testnet | mainnet`) and introduces `DeviceSyncOptions` split from `NetworkOptions`.
> - Risk: `sendSyncRequest` signature is breaking — callers that invoke it with no arguments will need to pass `options` and `serverUrl`.
>
> <!-- Macroscope's review summary starts here -->
>
> <sup><a href="https://app.macroscope.com">Macroscope</a> summarized 35cc13b.</sup>
> <!-- Macroscope's review summary ends here -->
>
<!-- macroscope-ui-refresh -->
<!-- Macroscope's pull request summary ends here -->

Author: neekolas

apps/xmtp.chat/src/components/App/AppLayout.tsx

@@ -43,12 +43,10 @@ export const AppLayout: React.FC = () => {
   }, [client]);
 
   useEffect(() => {
-    if (!client) {
+    const sessionSdkEnv = client?.env;
+    if (!client || !sessionSdkEnv) {
       return;
     }
-
-    // the session's actual SDK environment from client options
-    const sessionSdkEnv = client.options?.env ?? "dev";
     const isInvalidEnvironment =
       !envParam ||
       !isValidEnvironment(envParam) ||

apps/xmtp.chat/src/components/Conversations/ConversationsNavbar.tsx

@@ -1,4 +1,8 @@
 import { Badge, Box, Group, Stack, Text } from "@mantine/core";
+import {
+  BackupElementSelectionOption,
+  HistorySyncUrls,
+} from "@xmtp/browser-sdk";
 import { useCallback, useEffect, useRef } from "react";
 import { ConversationsList } from "@/components/Conversations/ConversationList";
 import { ConversationsMenu } from "@/components/Conversations/ConversationsMenu";
@@ -48,7 +52,21 @@ export const ConversationsNavbar: React.FC = () => {
   }, [syncAll, startStreams, stopStreams]);
 
   const handleSendSyncRequest = useCallback(async () => {
-    await client.sendSyncRequest();
+    const env = client.env;
+    if (!env) {
+      return;
+    }
+    const serverUrl = HistorySyncUrls[env];
+    await client.sendSyncRequest(
+      {
+        elements: [
+          BackupElementSelectionOption.Messages,
+          BackupElementSelectionOption.Consent,
+        ],
+        excludeDisappearingMessages: false,
+      },
+      serverUrl,
+    );
   }, [client]);
 
   // loading conversations on mount, and start streaming

apps/xmtp.chat/src/contexts/XMTPContext.tsx

@@ -2,7 +2,9 @@ import {
   Client,
   type BuiltInContentTypes,
   type ClientOptions,
+  type NetworkOptions,
   type Signer,
+  type XmtpEnv,
 } from "@xmtp/browser-sdk";
 import {
   createContext,
@@ -20,7 +22,7 @@ export type ContentTypes = BuiltInContentTypes;
 export type InitializeClientOptions = {
   apiUrl?: string;
   dbEncryptionKey?: Uint8Array;
-  env?: ClientOptions["env"];
+  env?: XmtpEnv;
   loggingLevel?: ClientOptions["loggingLevel"];
   signer: Signer;
   gatewayHost?: string;
@@ -122,7 +124,7 @@ export const XMTPProvider: React.FC<XMTPProviderProps> = ({
             dbEncryptionKey,
             appVersion: "xmtp.chat/0",
             gatewayHost,
-          });
+          } as Omit<ClientOptions & NetworkOptions, "codecs">);
           setClient(xmtpClient);
         } catch (e) {
           setClient(undefined);

apps/xmtp.chat/src/helpers/attachment.ts

@@ -146,7 +146,7 @@ export const getFileType = (filename: string) => {
   }
 };
 
-export const formatFileSize = (fileSize: number) => {
+export const formatFileSize = (fileSize: number | undefined) => {
   if (!fileSize) return "";
   const kb = fileSize / 1024;
   if (kb < 1024) {

apps/xmtp.chat/src/helpers/names.ts

@@ -1,4 +1,5 @@
 import {
+  createBackend,
   getInboxIdForIdentifier,
   IdentifierKind,
   type XmtpEnv,
@@ -84,14 +85,11 @@ export const getInboxIdForAddress = async (
     return null;
   }
 
-  const inboxId = await getInboxIdForIdentifier(
-    {
-      identifier: address.toLowerCase(),
-      identifierKind: IdentifierKind.Ethereum,
-    },
-    environment,
-    gatewayHost,
-  );
+  const backend = await createBackend({ env: environment, gatewayHost });
+  const inboxId = await getInboxIdForIdentifier(backend, {
+    identifier: address.toLowerCase(),
+    identifierKind: IdentifierKind.Ethereum,
+  });
 
   return inboxId ?? null;
 };

content-types/content-type-primitives/package.json

@@ -62,7 +62,7 @@
     ]
   },
   "dependencies": {
-    "@xmtp/node-bindings": "1.9.1"
+    "@xmtp/node-bindings": "1.10.0-dev.2334796"
   },
   "devDependencies": {
     "@rollup/plugin-terser": "^0.4.4",

packages/xmtp-cli/package.json

@@ -88,7 +88,7 @@
     "@oclif/plugin-help": "^6.2.37",
     "@oclif/plugin-not-found": "^3.2.74",
     "@oclif/plugin-warn-if-update-available": "^3.1.55",
-    "@xmtp/node-sdk": "5.3.0",
+    "@xmtp/node-sdk": "5.4.0",
     "viem": "^2.44.4"
   },
   "devDependencies": {

packages/xmtp-cli/src/commands/client/info.ts

@@ -34,7 +34,8 @@ application instance using your identity.`;
   async run(): Promise<void> {
     const client = await this.initClient();
 
-    const options = client.options ?? {};
+    const options = client.options;
+    const hasNetworkOptions = options && "env" in options;
 
     const properties = {
       address: client.accountIdentifier?.identifier,
@@ -46,17 +47,17 @@ application instance using your identity.`;
     };
 
     const clientOptions = {
-      env: options.env,
-      apiUrl: options.apiUrl,
-      historySyncUrl: options.historySyncUrl,
-      gatewayHost: options.gatewayHost,
-      dbPath: options.dbPath,
-      loggingLevel: options.loggingLevel,
-      structuredLogging: options.structuredLogging,
-      disableAutoRegister: options.disableAutoRegister,
-      disableDeviceSync: options.disableDeviceSync,
-      appVersion: options.appVersion,
-      nonce: options.nonce,
+      env: client.env,
+      apiUrl: hasNetworkOptions ? options.apiUrl : undefined,
+      historySyncUrl: options?.historySyncUrl,
+      gatewayHost: hasNetworkOptions ? options.gatewayHost : undefined,
+      dbPath: options?.dbPath,
+      loggingLevel: options?.loggingLevel,
+      structuredLogging: options?.structuredLogging,
+      disableAutoRegister: options?.disableAutoRegister,
+      disableDeviceSync: options?.disableDeviceSync,
+      appVersion: hasNetworkOptions ? options.appVersion : undefined,
+      nonce: options?.nonce,
     };
 
     if (this.jsonOutput) {

packages/xmtp-cli/src/utils/client.ts

@@ -1,6 +1,12 @@
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
-import { Client, IdentifierKind, LogLevel, type Signer } from "@xmtp/node-sdk";
+import {
+  Client,
+  IdentifierKind,
+  LogLevel,
+  type NetworkOptions,
+  type Signer,
+} from "@xmtp/node-sdk";
 import { isHex, toBytes } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import type { XmtpConfig } from "./config.js";
@@ -79,15 +85,19 @@ export async function createClient(config: XmtpConfig): Promise<Client> {
     await mkdir(dirname(config.dbPath), { recursive: true });
   }
 
-  const client = await Client.create(signer, {
+  const networkOptions: NetworkOptions = {
     env: config.env,
+    gatewayHost: config.gatewayHost,
+    appVersion: config.appVersion,
+  };
+
+  const client = await Client.create(signer, {
+    ...networkOptions,
     dbEncryptionKey: hexToBytes(config.dbEncryptionKey),
     dbPath: config.dbPath ?? undefined,
-    gatewayHost: config.gatewayHost,
     loggingLevel: parseLogLevel(config.logLevel),
     structuredLogging: config.structuredLogging,
     disableDeviceSync: config.disableDeviceSync,
-    appVersion: config.appVersion,
   });
 
   return client;

sdks/agent-sdk/package.json

@@ -66,7 +66,7 @@
   },
   "dependencies": {
     "@xmtp/content-type-primitives": "3.0.1",
-    "@xmtp/node-sdk": "5.3.0",
+    "@xmtp/node-sdk": "5.4.0",
     "viem": "^2.37.6"
   },
   "devDependencies": {