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

package/src/Client.ts

@@ -1,6 +1,18 @@
 import { type ContentCodec } from "@xmtp/content-type-primitives";
-import { LogLevel, type Identifier } from "@xmtp/wasm-bindings";
+import {
+  Backend,
+  BackupElementSelectionOption,
+  IdentifierKind,
+  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 +22,8 @@ import type {
   ExtractCodecContentTypes,
   XmtpEnv,
 } from "@/types/options";
+import { createBackend } from "@/utils/createBackend";
+import { createClient as createLowLevelClient } from "@/utils/createClient";
 import {
   AccountAlreadyAssociatedError,
   InboxReassignError,
@@ -22,6 +36,45 @@ 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 });
+};
+
+const createEphemeralIdentifier = (): Identifier => {
+  const bytes = new Uint8Array(20);
+  globalThis.crypto.getRandomValues(bytes);
+
+  return {
+    identifier: `0x${Array.from(bytes, (byte) =>
+      byte.toString(16).padStart(2, "0"),
+    ).join("")}`,
+    identifierKind: IdentifierKind.Ethereum,
+  };
+};
+
+const toInboxUpdatesCountMap = (
+  value: Map<string, number> | Record<string, number>,
+) => {
+  if (value instanceof Map) {
+    return value;
+  }
+
+  return new Map(Object.entries(value));
+};
+
 /**
  * Client for interacting with the XMTP network
  */
@@ -30,6 +83,7 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
   #codecRegistry: CodecRegistry;
   #conversations: Conversations<ContentTypes>;
   #debugInformation: DebugInformation;
+  #env?: XmtpEnv;
   #identifier?: Identifier;
   #inboxId?: string;
   #installationId?: string;
@@ -97,6 +151,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 +301,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
    *
@@ -421,6 +483,7 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
     return this.#worker.action("client.registerIdentity", {
       signer,
       signatureRequestId,
+      waitForRegistrationVisible: this.#options?.waitForRegistrationVisible,
     });
   }
 
@@ -559,10 +622,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 +650,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 +743,66 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
     return this.#worker.action("client.canMessage", { identifiers });
   }
 
+  /**
+   * Fetches the latest inbox updates count for the specified inbox IDs
+   *
+   * @param inboxIds - The inbox IDs to check
+   * @returns Map of inbox IDs to their updates count
+   */
+  async fetchLatestInboxUpdatesCount(inboxIds: string[]) {
+    const result = await this.#worker.action(
+      "client.fetchLatestInboxUpdatesCount",
+      {
+        inboxIds,
+      },
+    );
+
+    return toInboxUpdatesCountMap(result);
+  }
+
+  /**
+   * Fetches the latest inbox updates count for the client's inbox
+   *
+   * @returns The latest inbox updates count
+   */
+  async fetchOwnInboxUpdatesCount() {
+    return this.#worker.action("client.fetchOwnInboxUpdatesCount", {});
+  }
+
+  /**
+   * 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,
@@ -659,6 +811,60 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
     return canMessageMap;
   }
 
+  /**
+   * Fetches the latest inbox updates count for the specified inbox IDs
+   * without a client
+   *
+   * @param inboxIds - The inbox IDs to check
+   * @param backend - Optional `Backend` instance created with `createBackend()`
+   * @returns Map of inbox IDs to their updates count
+   */
+  static async fetchLatestInboxUpdatesCount(
+    inboxIds: string[],
+    backendOrEnv?: Backend | XmtpEnv,
+  ): Promise<Map<string, number>>;
+  /**
+   * Fetches the latest inbox updates count for the specified inbox IDs
+   * without a client
+   *
+   * @param inboxIds - The inbox IDs to check
+   * @param env - Optional XMTP environment
+   * @param gatewayHost - Optional gateway host
+   * @returns Map of inbox IDs to their updates count
+   * @deprecated Pass a `Backend` instance created with `createBackend()` instead
+   * of `XmtpEnv` and `gatewayHost`.
+   */
+  static async fetchLatestInboxUpdatesCount(
+    inboxIds: string[],
+    env?: XmtpEnv,
+    gatewayHost?: string,
+  ): Promise<Map<string, number>>;
+  static async fetchLatestInboxUpdatesCount(
+    inboxIds: string[],
+    envOrBackend?: XmtpEnv | Backend,
+    gatewayHost?: string,
+  ) {
+    const backend = await resolveBackend(envOrBackend, gatewayHost);
+    const { client } = await createLowLevelClient(createEphemeralIdentifier(), {
+      backend,
+      dbPath: null,
+      disableDeviceSync: true,
+    });
+    // The wasm-bindings Client holds WASM-linear-memory allocations that are
+    // not reclaimed by the JS GC. Free the ephemeral client in finally so the
+    // allocation is released even if the fetch rejects.
+    try {
+      const result = (await client.fetchLatestInboxUpdatesCount(
+        true,
+        inboxIds,
+      )) as Record<string, number> | Map<string, number>;
+
+      return toInboxUpdatesCountMap(result);
+    } finally {
+      client.free();
+    }
+  }
+
   /**
    * Fetches the inbox ID for a given identifier from the local database
    * If not found, fetches from the network
@@ -732,12 +938,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,19 @@
 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,
+  VisibilityConfirmationOptions,
+  XmtpEnv,
+} from "@/types/options";
 import { createClient } from "@/utils/createClient";
 import type { SafeSigner } from "@/utils/signer";
 import { WorkerConversations } from "@/WorkerConversations";
@@ -16,10 +24,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 +40,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 +52,10 @@ export class WorkerClient {
     return this.#client.appVersion;
   }
 
+  get env() {
+    return this.#env;
+  }
+
   get accountIdentifier() {
     return this.#client.accountIdentifier;
   }
@@ -80,6 +94,19 @@ export class WorkerClient {
     >;
   }
 
+  async fetchLatestInboxUpdatesCount(inboxIds: string[]) {
+    const result = (await this.#client.fetchLatestInboxUpdatesCount(
+      true,
+      inboxIds,
+    )) as Map<string, number> | Record<string, number>;
+
+    return result instanceof Map ? Object.fromEntries(result) : result;
+  }
+
+  async fetchOwnInboxUpdatesCount() {
+    return this.#client.fetchOwnInboxUpdatesCount(true);
+  }
+
   async addSignature(
     signatureRequest: SignatureRequestHandle,
     signer: SafeSigner,
@@ -138,13 +165,17 @@ export class WorkerClient {
   async registerIdentity(
     signer: SafeSigner,
     signatureRequest: SignatureRequestHandle,
+    visibilityConfirmationOptions?: VisibilityConfirmationOptions,
   ) {
     await this.addSignature(signatureRequest, signer);
-    await this.#client.registerIdentity(signatureRequest);
+    await this.#client.registerIdentity(
+      signatureRequest,
+      visibilityConfirmationOptions,
+    );
   }
 
   async getInboxIdByIdentifier(identifier: Identifier) {
-    return this.#client.findInboxIdByIdentifier(identifier);
+    return this.#client.findInboxIdByIdentity(identifier);
   }
 
   signWithInstallationKey(signatureText: string) {
@@ -185,7 +216,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;