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

package/src/Client.ts

@@ -1,12 +1,18 @@
 import { type ContentCodec } from "@xmtp/content-type-primitives";
 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";
@@ -17,6 +23,7 @@ import type {
   XmtpEnv,
 } from "@/types/options";
 import { createBackend } from "@/utils/createBackend";
+import { createClient as createLowLevelClient } from "@/utils/createClient";
 import {
   AccountAlreadyAssociatedError,
   InboxReassignError,
@@ -46,6 +53,28 @@ const resolveBackend = async (
   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
  */
@@ -454,6 +483,7 @@ export class Client<ContentTypes = ExtractCodecContentTypes> {
     return this.#worker.action("client.registerIdentity", {
       signer,
       signatureRequestId,
+      waitForRegistrationVisible: this.#options?.waitForRegistrationVisible,
     });
   }
 
@@ -713,6 +743,32 @@ 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
    *
@@ -755,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
@@ -828,17 +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
-   * @param serverUrl - The server URL for the sync request
+   * @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(options: ArchiveOptions, serverUrl: string) {
+  async sendSyncRequest(options?: ArchiveOptions, serverUrl?: string) {
+    const resolvedOptions = options ?? this.#getDefaultArchiveOptions();
+    const resolvedServerUrl = serverUrl ?? this.#getDefaultServerUrl();
+
     return this.#worker.action("client.sendSyncRequest", {
-      options,
-      serverUrl,
+      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/Conversation.ts

@@ -140,6 +140,19 @@ export class Conversation<ContentTypes = unknown> {
     });
   }
 
+  /**
+   * Decodes, decrypts, and persists a raw envelope from a group message stream.
+   *
+   * @param envelopeBytes - Raw protobuf-encoded envelope bytes from the stream
+   * @returns The processed and stored messages
+   */
+  async processStreamedMessage(envelopeBytes: Uint8Array) {
+    return this.#worker.action("conversation.processStreamedMessage", {
+      id: this.#id,
+      envelopeBytes,
+    });
+  }
+
   /**
    * Sends a message
    *

package/src/WorkerClient.ts

@@ -1,12 +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, XmtpEnv } 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";
@@ -87,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,
@@ -145,9 +165,13 @@ 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) {
@@ -195,4 +219,42 @@ export class WorkerClient {
   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

@@ -188,6 +188,10 @@ export class WorkerConversation {
     return this.#group.publishMessages();
   }
 
+  async processStreamedMessage(envelopeBytes: Uint8Array) {
+    return this.#group.processStreamedGroupMessage(envelopeBytes);
+  }
+
   async send(encodedContent: EncodedContent, opts?: SendMessageOpts) {
     return this.#group.send(encodedContent, opts ?? { shouldPush: true });
   }

package/src/index.ts

@@ -17,8 +17,10 @@ export type {
   Action,
   Actions,
   ApiStats,
+  ArchiveMetadata,
   ArchiveOptions,
   Attachment,
+  AvailableArchiveInfo,
   Backend,
   BackendBuilder,
   Consent,
@@ -62,6 +64,8 @@ export type {
   UserPreferenceUpdate,
   WalletCall,
   WalletSendCalls,
+  WorkerConfigOptions,
+  WorkerIntervalOverride,
 } from "@xmtp/wasm-bindings";
 export {
   ActionStyle,
@@ -85,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,9 +1,15 @@
 import type {
+  ArchiveMetadata,
   ArchiveOptions,
+  AvailableArchiveInfo,
+  GroupSyncSummary,
   Identifier,
   KeyPackageStatus,
 } from "@xmtp/wasm-bindings";
-import type { ClientOptions } from "@/types/options";
+import type {
+  ClientOptions,
+  VisibilityConfirmationOptions,
+} from "@/types/options";
 import type { SafeSigner } from "@/utils/signer";
 
 export type ClientAction =
@@ -109,6 +115,7 @@ export type ClientAction =
       data: {
         signer: SafeSigner;
         signatureRequestId: string;
+        waitForRegistrationVisible?: VisibilityConfirmationOptions;
       };
     }
   | {
@@ -174,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;
@@ -225,4 +246,63 @@ export type ClientAction =
         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/actions/conversation.ts

@@ -8,6 +8,7 @@ import type {
   GroupMember,
   Intent,
   ListMessagesOptions,
+  Message,
   MessageDisappearingSettings,
   MultiRemoteAttachment,
   Reaction,
@@ -50,6 +51,15 @@ export type ConversationAction =
         id: string;
       };
     }
+  | {
+      action: "conversation.processStreamedMessage";
+      id: string;
+      result: Message[];
+      data: {
+        id: string;
+        envelopeBytes: Uint8Array;
+      };
+    }
   | {
       action: "conversation.messages";
       id: string;

package/src/types/options.ts

@@ -17,9 +17,13 @@ import type {
   RemoteAttachment,
   TransactionReference,
   WalletSendCalls,
+  WasmVisibilityConfirmationOptions,
+  WorkerConfigOptions,
 } from "@xmtp/wasm-bindings";
 import type { DecodedMessage } from "@/DecodedMessage";
 
+export type VisibilityConfirmationOptions = WasmVisibilityConfirmationOptions;
+
 export type XmtpEnv =
   | "local"
   | "dev"
@@ -115,10 +119,25 @@ export type OtherOptions = {
    * Logging level
    */
   loggingLevel?: LogLevel;
+  /**
+   * 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.
+   */
+  workerConfig?: WorkerConfigOptions;
   /**
    * Disable automatic registration when creating a client
    */
   disableAutoRegister?: boolean;
+  /**
+   * 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.
+   */
+  waitForRegistrationVisible?: VisibilityConfirmationOptions;
 };
 
 export type ClientOptions = (NetworkOptions | { backend: Backend }) &

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/createClient.ts

@@ -6,9 +6,15 @@ import {
   type Backend,
   type Identifier,
 } from "@xmtp/wasm-bindings";
-import type { ClientOptions, NetworkOptions } from "@/types/options";
+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",
@@ -21,7 +27,7 @@ const hasBackend = (options: object): options is { backend: Backend } => {
 };
 
 const resolveBackend = async (
-  options?: Omit<ClientOptions, "codecs">,
+  options?: CreateClientOptions,
 ): Promise<Backend> => {
   if (!options) {
     return createBackend();
@@ -43,12 +49,12 @@ const resolveBackend = async (
   }
 
   // No backend provided — build one from NetworkOptions
-  return createBackend(options as NetworkOptions);
+  return createBackend(options);
 };
 
 export const createClient = async (
   identifier: Identifier,
-  options?: Omit<ClientOptions, "codecs">,
+  options?: CreateClientOptions,
 ) => {
   const backend = await resolveBackend(options);
 
@@ -80,6 +86,7 @@ export const createClient = async (
     dbPath,
     options?.dbEncryptionKey,
     deviceSyncMode,
+    options?.workerConfig,
     isLogging
       ? {
           structured: options.structuredLogging ?? false,