@xmtp/browser-sdk 6.5.0 → 7.0.0

package/src/Client.ts

@@ -1,6 +1,17 @@
 import { type ContentCodec } from "@xmtp/content-type-primitives";
-import { LogLevel, type Identifier } from "@xmtp/wasm-bindings";
+import {
+  Backend,
+  BackupElementSelectionOption,
+  LogLevel,
+  type ArchiveMetadata,
+  type ArchiveOptions,
+  type AvailableArchiveInfo,
+  type GroupSyncSummary,
+  type Identifier,
+  type InboxState,
+} from "@xmtp/wasm-bindings";
 import { CodecRegistry } from "@/CodecRegistry";
+import { HistorySyncUrls } from "@/constants";
 import { Conversations } from "@/Conversations";
 import { DebugInformation } from "@/DebugInformation";
 import { Preferences } from "@/Preferences";
@@ -10,6 +21,7 @@ import type {
   ExtractCodecContentTypes,
   XmtpEnv,
 } from "@/types/options";
+import { createBackend } from "@/utils/createBackend";
 import {
   AccountAlreadyAssociatedError,
   InboxReassignError,
@@ -22,6 +34,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 +59,7 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
   #codecRegistry: CodecRegistry;
   #conversations: Conversations<ContentTypes>;
   #debugInformation: DebugInformation;
+  #env?: XmtpEnv;
   #identifier?: Identifier;
   #inboxId?: string;
   #installationId?: string;
@@ -97,6 +127,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;
@@ -246,6 +277,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
    *
@@ -559,10 +597,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,
@@ -570,30 +625,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);
   }
 
   /**
@@ -640,17 +718,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,
@@ -732,12 +833,152 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
     });
   }
 
+  /**
+   * Get the default archive options (consent and messages)
+   */
+  #getDefaultArchiveOptions(): ArchiveOptions {
+    return {
+      elements: [
+        BackupElementSelectionOption.Consent,
+        BackupElementSelectionOption.Messages,
+      ],
+      excludeDisappearingMessages: false,
+    };
+  }
+
+  /**
+   * Get the default server URL based on the environment
+   */
+  #getDefaultServerUrl(): string {
+    const env = this.#env ?? "dev";
+    return HistorySyncUrls[env];
+  }
+
   /**
    * Send a sync request to other devices on the network
    *
+   * @param options - Archive options specifying what to sync (defaults to consent and messages)
+   * @param serverUrl - The server URL for the sync request (defaults to environment-specific URL)
    * @returns Promise that resolves when the sync request is sent
    */
-  async sendSyncRequest() {
-    return this.#worker.action("client.sendSyncRequest");
+  async sendSyncRequest(options?: ArchiveOptions, serverUrl?: string) {
+    const resolvedOptions = options ?? this.#getDefaultArchiveOptions();
+    const resolvedServerUrl = serverUrl ?? this.#getDefaultServerUrl();
+
+    return this.#worker.action("client.sendSyncRequest", {
+      options: resolvedOptions,
+      serverUrl: resolvedServerUrl,
+    });
+  }
+
+  /**
+   * Send a sync archive to the sync group
+   *
+   * @param pin - The pin used for reference when importing
+   * @param options - Archive options specifying what to sync (defaults to consent and messages)
+   * @param serverUrl - The server URL for the sync archive (defaults to environment-specific URL)
+   * @returns Promise that resolves when the sync archive is sent
+   */
+  async sendSyncArchive(
+    pin: string,
+    options?: ArchiveOptions,
+    serverUrl?: string,
+  ) {
+    const resolvedOptions = options ?? this.#getDefaultArchiveOptions();
+    const resolvedServerUrl = serverUrl ?? this.#getDefaultServerUrl();
+
+    return this.#worker.action("client.sendSyncArchive", {
+      options: resolvedOptions,
+      serverUrl: resolvedServerUrl,
+      pin,
+    });
+  }
+
+  /**
+   * Process a sync archive that matches the pin given
+   *
+   * @param archivePin - Optional pin to match. If not provided, processes the last archive sent
+   * @returns Promise that resolves when the archive is processed
+   */
+  async processSyncArchive(archivePin?: string | null) {
+    return this.#worker.action("client.processSyncArchive", {
+      archivePin,
+    });
+  }
+
+  /**
+   * List the archives available for import in the sync group
+   *
+   * You may need to manually sync the sync group before calling
+   * this function to see recently uploaded archives.
+   *
+   * @param daysCutoff - Number of days to look back for archives
+   * @returns Promise that resolves with array of available archive information
+   */
+  async listAvailableArchives(
+    daysCutoff: number,
+  ): Promise<AvailableArchiveInfo[]> {
+    return this.#worker.action("client.listAvailableArchives", {
+      daysCutoff,
+    });
+  }
+
+  /**
+   * Export archive data to bytes for later restoration
+   *
+   * @param key - Encryption key for the archive
+   * @param opts - Archive options specifying what to include (defaults to consent and messages)
+   * @returns Promise that resolves with the archive data as bytes
+   */
+  async createArchive(
+    key: Uint8Array,
+    opts?: ArchiveOptions,
+  ): Promise<Uint8Array> {
+    const resolvedOpts = opts ?? this.#getDefaultArchiveOptions();
+
+    return this.#worker.action("client.createArchive", {
+      opts: resolvedOpts,
+      key,
+    });
+  }
+
+  /**
+   * Import an archive from bytes
+   *
+   * @param data - The archive data as bytes
+   * @param key - Encryption key for the archive
+   * @returns Promise that resolves when the archive is imported
+   */
+  async importArchive(data: Uint8Array, key: Uint8Array) {
+    return this.#worker.action("client.importArchive", {
+      data,
+      key,
+    });
+  }
+
+  /**
+   * Load the metadata for an archive to see what it contains
+   *
+   * @param data - The archive data as bytes
+   * @param key - Encryption key for the archive
+   * @returns Promise that resolves with the archive metadata
+   */
+  async archiveMetadata(
+    data: Uint8Array,
+    key: Uint8Array,
+  ): Promise<ArchiveMetadata> {
+    return this.#worker.action("client.archiveMetadata", {
+      data,
+      key,
+    });
+  }
+
+  /**
+   * Manually sync all device sync groups
+   *
+   * @returns Promise that resolves with a summary of the sync operation
+   */
+  async syncAllDeviceSyncGroups(): Promise<GroupSyncSummary> {
+    return this.#worker.action("client.syncAllDeviceSyncGroups");
   }
 }

package/src/WorkerClient.ts

@@ -1,11 +1,15 @@
 import {
   verifySignedWithPublicKey,
+  type ArchiveMetadata,
+  type ArchiveOptions,
+  type AvailableArchiveInfo,
   type Client,
+  type GroupSyncSummary,
   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 +20,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 +36,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 +48,10 @@ export class WorkerClient {
     return this.#client.appVersion;
   }
 
+  get env() {
+    return this.#env;
+  }
+
   get accountIdentifier() {
     return this.#client.accountIdentifier;
   }
@@ -144,7 +154,7 @@ export class WorkerClient {
   }
 
   async getInboxIdByIdentifier(identifier: Identifier) {
-    return this.#client.findInboxIdByIdentifier(identifier);
+    return this.#client.findInboxIdByIdentity(identifier);
   }
 
   signWithInstallationKey(signatureText: string) {
@@ -185,7 +195,45 @@ 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);
+  }
+
+  async sendSyncArchive(
+    options: ArchiveOptions,
+    serverUrl: string,
+    pin: string,
+  ) {
+    return this.#client.device_sync().sendSyncArchive(options, serverUrl, pin);
+  }
+
+  async processSyncArchive(archivePin?: string | null) {
+    return this.#client.device_sync().processSyncArchive(archivePin);
+  }
+
+  listAvailableArchives(daysCutoff: number): AvailableArchiveInfo[] {
+    return this.#client.device_sync().listAvailableArchives(BigInt(daysCutoff));
+  }
+
+  async createArchive(
+    opts: ArchiveOptions,
+    key: Uint8Array,
+  ): Promise<Uint8Array> {
+    return this.#client.device_sync().createArchive(opts, key);
+  }
+
+  async importArchive(data: Uint8Array, key: Uint8Array) {
+    return this.#client.device_sync().importArchive(data, key);
+  }
+
+  async archiveMetadata(
+    data: Uint8Array,
+    key: Uint8Array,
+  ): Promise<ArchiveMetadata> {
+    return this.#client.device_sync().archiveMetadata(data, key);
+  }
+
+  async syncAllDeviceSyncGroups(): Promise<GroupSyncSummary> {
+    return this.#client.device_sync().syncAllDeviceSyncGroups();
   }
 }

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,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,
@@ -62,6 +67,7 @@ export type {
 } from "@xmtp/wasm-bindings";
 export {
   ActionStyle,
+  BackupElementSelectionOption,
   ConsentEntityType,
   ConsentState,
   ContentType,

package/src/types/actions/client.ts

@@ -1,4 +1,11 @@
-import type { Identifier, KeyPackageStatus } from "@xmtp/wasm-bindings";
+import type {
+  ArchiveMetadata,
+  ArchiveOptions,
+  AvailableArchiveInfo,
+  GroupSyncSummary,
+  Identifier,
+  KeyPackageStatus,
+} from "@xmtp/wasm-bindings";
 import type { ClientOptions } from "@/types/options";
 import type { SafeSigner } from "@/utils/signer";
 
@@ -8,6 +15,7 @@ export type ClientAction =
       id: string;
       result: {
         appVersion: string;
+        env: string;
         inboxId: string;
         installationId: string;
         installationIdBytes: Uint8Array;
@@ -216,5 +224,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;
     };