@xmtp/node-sdk 5.5.0 → 6.0.0-dev.3f65d25

package/dist/index.js

@@ -1,5 +1,6 @@
-import { generateInboxId as generateInboxId$1, getInboxIdForIdentifier as getInboxIdForIdentifier$1, contentTypeIntent, contentTypeActions, contentTypeWalletSendCalls, contentTypeLeaveRequest, contentTypeReadReceipt, contentTypeGroupUpdated, contentTypeTransactionReference, contentTypeMultiRemoteAttachment, contentTypeRemoteAttachment, contentTypeAttachment, contentTypeReaction, contentTypeReply, contentTypeMarkdown, contentTypeText, createClient as createClient$1, revokeInstallationsSignatureRequest, applySignatureRequest, inboxStateFromInboxIds, verifySignedWithPublicKey, isAddressAuthorized, isInstallationAuthorized } from '@xmtp/node-bindings';
-export { ActionStyle, ConsentEntityType, ConsentState, ContentType, ConversationType, DeliveryStatus, GroupMembershipState, GroupMessageKind, GroupPermissionsOptions, IdentifierKind, ListConversationsOrderBy, LogLevel, MessageSortBy, MetadataField, PermissionLevel, PermissionPolicy, PermissionUpdateType, ReactionAction, ReactionSchema, SortDirection, contentTypeActions, contentTypeAttachment, contentTypeGroupUpdated, contentTypeIntent, contentTypeLeaveRequest, contentTypeMarkdown, contentTypeMultiRemoteAttachment, contentTypeReaction, contentTypeReadReceipt, contentTypeRemoteAttachment, contentTypeReply, contentTypeText, contentTypeTransactionReference, contentTypeWalletSendCalls, decryptAttachment, encodeActions, encodeAttachment, encodeIntent, encodeMarkdown, encodeMultiRemoteAttachment, encodeReaction, encodeReadReceipt, encodeRemoteAttachment, encodeText, encodeTransactionReference, encodeWalletSendCalls, encryptAttachment } from '@xmtp/node-bindings';
+import { BackendBuilder, generateInboxId as generateInboxId$1, getInboxIdByIdentity, contentTypeIntent, contentTypeActions, contentTypeWalletSendCalls, contentTypeLeaveRequest, contentTypeReadReceipt, contentTypeGroupUpdated, contentTypeTransactionReference, contentTypeMultiRemoteAttachment, contentTypeRemoteAttachment, contentTypeAttachment, contentTypeReaction, contentTypeReply, contentTypeMarkdown, contentTypeText, createClientWithBackend, revokeInstallationsSignatureRequest, applySignatureRequest, fetchInboxStatesByInboxIds, verifySignedWithPublicKey, isAddressAuthorized, isInstallationAuthorized, Backend } from '@xmtp/node-bindings';
+export { ActionStyle, BackupElementSelectionOption, ConsentEntityType, ConsentState, ContentType, ConversationType, DeliveryStatus, GroupMembershipState, GroupMessageKind, GroupPermissionsOptions, IdentifierKind, ListConversationsOrderBy, LogLevel, MessageSortBy, MetadataField, PermissionLevel, PermissionPolicy, PermissionUpdateType, ReactionAction, ReactionSchema, SortDirection, WorkerKind, contentTypeActions, contentTypeAttachment, contentTypeGroupUpdated, contentTypeIntent, contentTypeLeaveRequest, contentTypeMarkdown, contentTypeMultiRemoteAttachment, contentTypeReaction, contentTypeReadReceipt, contentTypeRemoteAttachment, contentTypeReply, contentTypeText, contentTypeTransactionReference, contentTypeWalletSendCalls, decryptAttachment, encodeActions, encodeAttachment, encodeIntent, encodeMarkdown, encodeMultiRemoteAttachment, encodeReaction, encodeReadReceipt, encodeRemoteAttachment, encodeText, encodeTransactionReference, encodeWalletSendCalls, encryptAttachment, flushTelemetry, initLogging } from '@xmtp/node-bindings';
+import { randomBytes } from 'node:crypto';
 import { contentTypeToString } from '@xmtp/content-type-primitives';
 import { isPromise } from 'node:util/types';
 import { join } from 'node:path';
@@ -8,6 +9,7 @@ import process from 'node:process';
 /**
  * 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
@@ -30,6 +32,43 @@ 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",
+};
+
+const envMap = {
+    local: "Local" /* BindingsEnv.Local */,
+    dev: "Dev" /* BindingsEnv.Dev */,
+    production: "Production" /* BindingsEnv.Production */,
+    "testnet-staging": "TestnetStaging" /* BindingsEnv.TestnetStaging */,
+    "testnet-dev": "TestnetDev" /* BindingsEnv.TestnetDev */,
+    testnet: "Testnet" /* BindingsEnv.Testnet */,
+    mainnet: "Mainnet" /* BindingsEnv.Mainnet */,
+};
+const reverseEnvMap = {
+    ["Local" /* BindingsEnv.Local */]: "local",
+    ["Dev" /* BindingsEnv.Dev */]: "dev",
+    ["Production" /* BindingsEnv.Production */]: "production",
+    ["TestnetStaging" /* BindingsEnv.TestnetStaging */]: "testnet-staging",
+    ["TestnetDev" /* BindingsEnv.TestnetDev */]: "testnet-dev",
+    ["Testnet" /* BindingsEnv.Testnet */]: "testnet",
+    ["Mainnet" /* BindingsEnv.Mainnet */]: "mainnet",
+};
+const envToString = (env) => {
+    return reverseEnvMap[env];
+};
+const createBackend = async (options) => {
+    const env = options?.env ?? "dev";
+    const builder = new BackendBuilder(envMap[env]);
+    if (options?.apiUrl)
+        builder.setApiUrl(options.apiUrl);
+    if (options?.gatewayHost)
+        builder.setGatewayHost(options.gatewayHost);
+    if (options?.appVersion)
+        builder.setAppVersion(options.appVersion);
+    return builder.build();
 };
 
 class InboxReassignError extends Error {
@@ -72,10 +111,8 @@ class StreamInvalidRetryAttemptsError extends Error {
 const generateInboxId = (identifier, nonce) => {
     return generateInboxId$1(identifier, nonce);
 };
-const getInboxIdForIdentifier = async (identifier, env = "dev", gatewayHost) => {
-    const host = ApiUrls[env];
-    const isSecure = host.startsWith("https");
-    return getInboxIdForIdentifier$1(host, gatewayHost, isSecure, identifier);
+const getInboxIdForIdentifier = async (backend, identifier) => {
+    return getInboxIdByIdentity(backend, identifier);
 };
 
 function isHexString(value) {
@@ -709,7 +746,7 @@ class Conversation {
      * @returns The HMAC keys for this conversation
      */
     hmacKeys() {
-        return this.#conversation.getHmacKeys();
+        return this.#conversation.hmacKeys();
     }
     /**
      * Gets the metadata for this conversation
@@ -785,8 +822,10 @@ class Conversation {
      * @param sendOptions - Options for sending the message
      * @param sendOptions.shouldPush - Indicates whether this message should be
      * included in push notifications
-     * @param sendOptions.isOptimistic - Indicates whether this message should be
+     * @param sendOptions.optimistic - Indicates whether this message should be
      * sent optimistically and published later via `publishMessages`
+     * @param sendOptions.idempotencyKey - Optional idempotency key; re-sending
+     * identical content with the same key produces the same deduplicated message id
      * @returns Promise that resolves with the message ID after it has been sent
      */
     async send(encodedContent, sendOptions) {
@@ -799,121 +838,120 @@ class Conversation {
      * Sends a text message
      *
      * @param text - The text to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendText(text, isOptimistic) {
-        return this.#conversation.sendText(text, isOptimistic);
+    async sendText(text, opts) {
+        return this.#conversation.sendText(text, opts);
     }
     /**
      * Sends a markdown message
      *
      * @param markdown - The markdown to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendMarkdown(markdown, isOptimistic) {
-        return this.#conversation.sendMarkdown(markdown, isOptimistic);
+    async sendMarkdown(markdown, opts) {
+        return this.#conversation.sendMarkdown(markdown, opts);
     }
     /**
      * Sends a reaction message
      *
      * @param reaction - The reaction to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendReaction(reaction, isOptimistic) {
-        return this.#conversation.sendReaction(reaction, isOptimistic);
+    async sendReaction(reaction, opts) {
+        return this.#conversation.sendReaction(reaction, opts);
     }
     /**
      * Sends a read receipt message
      *
-     * @param readReceipt - The read receipt to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendReadReceipt(isOptimistic) {
-        return this.#conversation.sendReadReceipt(isOptimistic);
+    async sendReadReceipt(opts) {
+        return this.#conversation.sendReadReceipt(opts);
     }
     /**
      * Sends a reply message
      *
      * @param reply - The reply to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendReply(reply, isOptimistic) {
-        return this.#conversation.sendReply(reply, isOptimistic);
+    async sendReply(reply, opts) {
+        return this.#conversation.sendReply(reply, opts);
     }
     /**
      * Sends a transaction reference message
      *
      * @param transactionReference - The transaction reference to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendTransactionReference(transactionReference, isOptimistic) {
-        return this.#conversation.sendTransactionReference(transactionReference, isOptimistic);
+    async sendTransactionReference(transactionReference, opts) {
+        return this.#conversation.sendTransactionReference(transactionReference, opts);
     }
     /**
      * Sends a wallet send calls message
      *
      * @param walletSendCalls - The wallet send calls to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendWalletSendCalls(walletSendCalls, isOptimistic) {
-        return this.#conversation.sendWalletSendCalls(walletSendCalls, isOptimistic);
+    async sendWalletSendCalls(walletSendCalls, opts) {
+        return this.#conversation.sendWalletSendCalls(walletSendCalls, opts);
     }
     /**
      * Sends a actions message
      *
      * @param actions - The actions to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendActions(actions, isOptimistic) {
-        return this.#conversation.sendActions(actions, isOptimistic);
+    async sendActions(actions, opts) {
+        return this.#conversation.sendActions(actions, opts);
     }
     /**
      * Sends a intent message
      *
      * @param intent - The intent to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendIntent(intent, isOptimistic) {
-        return this.#conversation.sendIntent(intent, isOptimistic);
+    async sendIntent(intent, opts) {
+        return this.#conversation.sendIntent(intent, opts);
     }
     /**
      * Sends an attachment message
      *
      * @param attachment - The attachment to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendAttachment(attachment, isOptimistic) {
-        return this.#conversation.sendAttachment(attachment, isOptimistic);
+    async sendAttachment(attachment, opts) {
+        return this.#conversation.sendAttachment(attachment, opts);
     }
     /**
      * Sends a multi remote attachment message
      *
      * @param multiRemoteAttachment - The multi remote attachment to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendMultiRemoteAttachment(multiRemoteAttachment, isOptimistic) {
-        return this.#conversation.sendMultiRemoteAttachment(multiRemoteAttachment, isOptimistic);
+    async sendMultiRemoteAttachment(multiRemoteAttachment, opts) {
+        return this.#conversation.sendMultiRemoteAttachment(multiRemoteAttachment, opts);
     }
     /**
      * Sends a remote attachment message
      *
      * @param remoteAttachment - The remote attachment to send
-     * @param isOptimistic - Whether to send the message optimistically
+     * @param opts - Send options (optimistic delivery, idempotency key)
      * @returns Promise that resolves with the message ID after it has been sent
      */
-    async sendRemoteAttachment(remoteAttachment, isOptimistic) {
-        return this.#conversation.sendRemoteAttachment(remoteAttachment, isOptimistic);
+    async sendRemoteAttachment(remoteAttachment, opts) {
+        return this.#conversation.sendRemoteAttachment(remoteAttachment, opts);
     }
     /**
      * Lists messages in this conversation
@@ -922,7 +960,7 @@ class Conversation {
      * @returns Promise that resolves with an array of decoded messages
      */
     async messages(options) {
-        const messages = await this.#conversation.findEnrichedMessages(options);
+        const messages = await this.#conversation.listEnrichedMessages(options);
         return messages.map((message) => new DecodedMessage(this.#codecRegistry, message));
     }
     /**
@@ -1016,7 +1054,7 @@ class Conversation {
      * (nanoseconds since epoch)
      */
     async lastReadTimes() {
-        return this.#conversation.getLastReadTimes();
+        return this.#conversation.lastReadTimes();
     }
 }
 
@@ -1051,7 +1089,7 @@ class Dm extends Conversation {
         return this.#conversation.dmPeerInboxId();
     }
     async duplicateDms() {
-        const duplicateDms = await this.#conversation.findDuplicateDms();
+        const duplicateDms = await this.#conversation.duplicateDms();
         return duplicateDms.map((dm) => new Dm(this.#client, this.#codecRegistry, dm));
     }
 }
@@ -1154,13 +1192,13 @@ class Group extends Conversation {
      * The list of admins of the group
      */
     listAdmins() {
-        return this.#conversation.adminList();
+        return this.#conversation.listAdmins();
     }
     /**
      * The list of super admins of the group
      */
     listSuperAdmins() {
-        return this.#conversation.superAdminList();
+        return this.#conversation.listSuperAdmins();
     }
     /**
      * Checks if an inbox is an admin of the group
@@ -1186,7 +1224,7 @@ class Group extends Conversation {
      * @param identifiers Array of member identifiers to add
      */
     async addMembersByIdentifiers(identifiers) {
-        return this.#conversation.addMembers(identifiers);
+        return this.#conversation.addMembersByIdentity(identifiers);
     }
     /**
      * Adds members to the group using inbox IDs
@@ -1194,7 +1232,7 @@ class Group extends Conversation {
      * @param inboxIds Array of inbox IDs to add
      */
     async addMembers(inboxIds) {
-        return this.#conversation.addMembersByInboxId(inboxIds);
+        return this.#conversation.addMembers(inboxIds);
     }
     /**
      * Removes members from the group using identifiers
@@ -1202,7 +1240,7 @@ class Group extends Conversation {
      * @param identifiers Array of member identifiers to remove
      */
     async removeMembersByIdentifiers(identifiers) {
-        return this.#conversation.removeMembers(identifiers);
+        return this.#conversation.removeMembersByIdentity(identifiers);
     }
     /**
      * Removes members from the group using inbox IDs
@@ -1210,7 +1248,7 @@ class Group extends Conversation {
      * @param inboxIds Array of inbox IDs to remove
      */
     async removeMembers(inboxIds) {
-        return this.#conversation.removeMembersByInboxId(inboxIds);
+        return this.#conversation.removeMembers(inboxIds);
     }
     /**
      * Promotes a group member to admin status
@@ -1294,8 +1332,8 @@ class Conversations {
      */
     async getConversationById(id) {
         try {
-            // findGroupById will throw if group is not found
-            const group = this.#conversations.findGroupById(id);
+            // getConversationById will throw if group is not found
+            const group = this.#conversations.getConversationById(id);
             const metadata = await group.groupMetadata();
             switch (metadata.conversationType()) {
                 case 1 /* ConversationType.Group */:
@@ -1319,8 +1357,8 @@ class Conversations {
      */
     getDmByInboxId(inboxId) {
         try {
-            // findDmByTargetInboxId will throw if group is not found
-            const group = this.#conversations.findDmByTargetInboxId(inboxId);
+            // getDmByInboxId will throw if group is not found
+            const group = this.#conversations.getDmByInboxId(inboxId);
             return new Dm(this.#client, this.#codecRegistry, group);
         }
         catch {
@@ -1350,8 +1388,8 @@ class Conversations {
      */
     getMessageById(id) {
         try {
-            // findEnrichedMessageById will throw if message is not found
-            const message = this.#conversations.findEnrichedMessageById(id);
+            // getEnrichedMessageById will throw if message is not found
+            const message = this.#conversations.getEnrichedMessageById(id);
             return new DecodedMessage(this.#codecRegistry, message);
         }
         catch {
@@ -1378,7 +1416,7 @@ class Conversations {
      * @see https://docs.xmtp.org/chat-apps/core-messaging/create-conversations#create-a-new-group-chat
      */
     async createGroupWithIdentifiers(identifiers, options) {
-        const group = await this.#conversations.createGroup(identifiers, options);
+        const group = await this.#conversations.createGroupByIdentity(identifiers, options);
         const conversation = new Group(this.#client, this.#codecRegistry, group);
         return conversation;
     }
@@ -1391,7 +1429,7 @@ class Conversations {
      * @see https://docs.xmtp.org/chat-apps/core-messaging/create-conversations#create-a-new-group-chat
      */
     async createGroup(inboxIds, options) {
-        const group = await this.#conversations.createGroupByInboxId(inboxIds, options);
+        const group = await this.#conversations.createGroup(inboxIds, options);
         const conversation = new Group(this.#client, this.#codecRegistry, group);
         return conversation;
     }
@@ -1404,7 +1442,7 @@ class Conversations {
      * @see https://docs.xmtp.org/agents/build-agents/create-conversations#by-ethereum-address-1
      */
     async createDmWithIdentifier(identifier, options) {
-        const group = await this.#conversations.createDm(identifier, options);
+        const group = await this.#conversations.createDmByIdentity(identifier, options);
         const conversation = new Dm(this.#client, this.#codecRegistry, group);
         return conversation;
     }
@@ -1417,7 +1455,7 @@ class Conversations {
      * @see https://docs.xmtp.org/agents/build-agents/create-conversations#by-inbox-id-1
      */
     async createDm(inboxId, options) {
-        const group = await this.#conversations.createDmByInboxId(inboxId, options);
+        const group = await this.#conversations.createDm(inboxId, options);
         const conversation = new Dm(this.#client, this.#codecRegistry, group);
         return conversation;
     }
@@ -1496,7 +1534,7 @@ class Conversations {
      * @see https://docs.xmtp.org/chat-apps/list-stream-sync/sync-and-syncall#sync-all-new-welcomes-conversations-messages-and-preferences
      */
     async syncAll(consentStates) {
-        return this.#conversations.syncAllConversations(consentStates);
+        return this.#conversations.syncAll(consentStates);
     }
     /**
      * Creates a stream for new conversations
@@ -1664,7 +1702,7 @@ class Conversations {
      * @see https://docs.xmtp.org/chat-apps/push-notifs/push-notifs#get-hmac-keys-for-a-conversation
      */
     hmacKeys() {
-        return this.#conversations.getHmacKeys();
+        return this.#conversations.hmacKeys();
     }
 }
 
@@ -1711,7 +1749,7 @@ class Preferences {
         this.#conversations = conversations;
     }
     sync() {
-        return this.#client.syncPreferences();
+        return this.#conversations.syncPreferences();
     }
     /**
      * Retrieves the current inbox state of this client from the local database
@@ -1737,7 +1775,7 @@ class Preferences {
      * @returns Promise that resolves with the inbox states for the inbox IDs
      */
     async getInboxStates(inboxIds) {
-        return this.#client.addressesFromInboxId(false, inboxIds);
+        return this.#client.fetchInboxStatesByInboxIds(inboxIds, false);
     }
     /**
      * Retrieves the latest inbox states for specified inbox IDs from the network
@@ -1746,7 +1784,7 @@ class Preferences {
      * @returns Promise that resolves with the inbox states for the inbox IDs
      */
     async fetchInboxStates(inboxIds) {
-        return this.#client.addressesFromInboxId(true, inboxIds);
+        return this.#client.fetchInboxStatesByInboxIds(inboxIds, true);
     }
     /**
      * Updates consent states for multiple records
@@ -1799,13 +1837,36 @@ class Preferences {
     }
 }
 
+const networkOptionKeys = [
+    "env",
+    "apiUrl",
+    "gatewayHost",
+    "appVersion",
+];
+const hasBackend = (options) => {
+    return "backend" in options;
+};
+const resolveBackend$1 = async (options) => {
+    if (!options) {
+        return createBackend();
+    }
+    if (hasBackend(options)) {
+        // Validate that no NetworkOptions fields are also set
+        const conflicting = networkOptionKeys.filter((key) => key in options && options[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);
+};
 const createClient = async (identifier, options) => {
-    const env = options?.env || "dev";
-    const host = options?.apiUrl || ApiUrls[env];
-    const gatewayHost = options?.gatewayHost || undefined;
-    const isSecure = host.startsWith("https");
-    const inboxId = (await getInboxIdForIdentifier(identifier, env, gatewayHost)) ||
+    const backend = await resolveBackend$1(options);
+    const inboxId = (await getInboxIdForIdentifier(backend, identifier)) ||
         generateInboxId(identifier, options?.nonce);
+    const env = envToString(backend.env);
     let dbPath;
     if (options?.dbPath === undefined) {
         // Default: auto-generated path
@@ -1822,19 +1883,50 @@ const createClient = async (identifier, options) => {
     const logOptions = {
         structured: options?.structuredLogging ?? false,
         level: options?.loggingLevel ?? "Off" /* LogLevel.Off */,
+        stdoutLevel: options?.stdoutLoggingLevel,
+        otelEndpoint: options?.otelEndpoint,
+        resourceAttributes: options?.resourceAttributes,
     };
-    const historySyncUrl = options?.historySyncUrl === undefined
-        ? HistorySyncUrls[env]
-        : options.historySyncUrl;
     const deviceSyncWorkerMode = options?.disableDeviceSync
         ? "Disabled" /* SyncWorkerMode.Disabled */
         : "Enabled" /* SyncWorkerMode.Enabled */;
     const dbEncryptionKey = isHexString(options?.dbEncryptionKey)
         ? Buffer.from(options.dbEncryptionKey.replace(/^0x/, ""), "hex")
         : options?.dbEncryptionKey;
-    return createClient$1(host, gatewayHost, isSecure, dbPath, inboxId, identifier, dbEncryptionKey, historySyncUrl, deviceSyncWorkerMode, logOptions, undefined, options?.appVersion);
+    const client = await createClientWithBackend(backend, {
+        dbPath: dbPath ?? undefined,
+        encryptionKey: dbEncryptionKey,
+        maxDbPoolSize: options?.maxDbPoolSize,
+        minDbPoolSize: options?.minDbPoolSize,
+        useSingleConnection: options?.useSingleConnection,
+    }, inboxId, identifier, deviceSyncWorkerMode, options?.workerConfig, logOptions, undefined, // allowOffline
+    options?.nonce);
+    return { client, env };
 };
 
+/**
+ * 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, gatewayHost) => {
+    if (envOrBackend instanceof Backend) {
+        return envOrBackend;
+    }
+    return createBackend({ env: envOrBackend, gatewayHost });
+};
+const createEphemeralIdentifier = () => ({
+    identifier: `0x${randomBytes(20).toString("hex")}`,
+    identifierKind: 0 /* IdentifierKind.Ethereum */,
+});
+const toInboxUpdatesCountMap = (value) => {
+    if (value instanceof Map) {
+        return value;
+    }
+    return new Map(Object.entries(value));
+};
 /**
  * Client for interacting with the XMTP network
  */
@@ -1843,6 +1935,7 @@ class Client {
     #codecRegistry;
     #conversations;
     #debugInformation;
+    #env;
     #preferences;
     #signer;
     #identifier;
@@ -1872,7 +1965,9 @@ class Client {
             return;
         }
         this.#identifier = identifier;
-        this.#client = await createClient(identifier, this.#options);
+        const { client, env } = await createClient(identifier, this.#options);
+        this.#client = client;
+        this.#env = env;
         const conversations = this.#client.conversations();
         this.#conversations = new Conversations(this, this.#codecRegistry, conversations);
         this.#debugInformation = new DebugInformation(this.#client);
@@ -1925,6 +2020,17 @@ class Client {
     get appVersion() {
         return this.#client?.appVersion();
     }
+    /**
+     * Gets the XMTP environment the client is connected to
+     *
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     */
+    get env() {
+        if (!this.#env) {
+            throw new ClientNotInitializedError();
+        }
+        return this.#env;
+    }
     /**
      * Gets the client options
      */
@@ -2014,6 +2120,24 @@ class Client {
         }
         return this.#preferences;
     }
+    /**
+     * Cleanly shuts down the client: cancels in-flight workers and detached
+     * streams, then releases the database connection.
+     *
+     * This is idempotent — calling it more than once resolves without error.
+     * Await this before deleting the database file or dropping the client
+     * reference to avoid log noise from background tasks running against a
+     * closed database.
+     *
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     * @returns Promise that resolves when the client has shut down
+     */
+    async close() {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        return this.#client.close();
+    }
     /**
      * Adds a signature to a signature request using the client's signer (or the
      * provided signer)
@@ -2206,7 +2330,7 @@ class Client {
             return;
         }
         await this.unsafe_addSignature(signatureRequest);
-        await this.#client?.registerIdentity(signatureRequest);
+        await this.#client?.registerIdentity(signatureRequest, this.#options?.waitForRegistrationVisible);
     }
     /**
      * Adds a new account to the client inbox
@@ -2282,18 +2406,10 @@ class Client {
         await this.unsafe_addSignature(signatureRequest);
         await this.unsafe_applySignatureRequest(signatureRequest);
     }
-    /**
-     * 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
-     */
-    static async revokeInstallations(signer, inboxId, installationIds, env, gatewayHost) {
-        const host = ApiUrls[env ?? "dev"];
+    static async revokeInstallations(signer, inboxId, installationIds, envOrBackend, gatewayHost) {
+        const backend = await resolveBackend(envOrBackend, gatewayHost);
         const identifier = await signer.getIdentifier();
-        const signatureRequest = await revokeInstallationsSignatureRequest(host, gatewayHost, identifier, inboxId, installationIds);
+        const signatureRequest = await revokeInstallationsSignatureRequest(backend, identifier, inboxId, installationIds);
         const signatureText = await signatureRequest.signatureText();
         const signature = await signer.signMessage(signatureText);
         switch (signer.type) {
@@ -2304,7 +2420,7 @@ class Client {
                 await signatureRequest.addEcdsaSignature(signature);
                 break;
         }
-        await applySignatureRequest(host, gatewayHost, signatureRequest);
+        await applySignatureRequest(backend, signatureRequest);
     }
     /**
      * Changes the recovery identifier for the client's inbox
@@ -2334,6 +2450,32 @@ class Client {
         const canMessage = await this.#client.canMessage(identifiers);
         return new Map(Object.entries(canMessage));
     }
+    /**
+     * 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
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     */
+    async fetchLatestInboxUpdatesCount(inboxIds) {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        const result = await this.#client.fetchInboxUpdatesCount(inboxIds, true);
+        return toInboxUpdatesCountMap(result);
+    }
+    /**
+     * Fetches the latest inbox updates count for the client's inbox
+     *
+     * @returns The latest inbox updates count
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     */
+    async fetchOwnInboxUpdatesCount() {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        return this.#client.fetchOwnInboxUpdatesCount(true);
+    }
     /**
      * Fetches the key package statuses from the network for the specified
      * installation IDs
@@ -2346,7 +2488,7 @@ class Client {
         if (!this.#client) {
             throw new ClientNotInitializedError();
         }
-        return this.#client.getKeyPackageStatusesForInstallationIds(installationIds);
+        return this.#client.fetchKeyPackageStatusesByInstallationIds(installationIds);
     }
     /**
      * Fetches the inbox ID for a given identifier from the local database
@@ -2360,7 +2502,7 @@ class Client {
         if (!this.#client) {
             throw new ClientNotInitializedError();
         }
-        return this.#client.findInboxIdByIdentifier(identifier);
+        return this.#client.getInboxIdByIdentity(identifier);
     }
     /**
      * Signs a message with the installation key
@@ -2395,29 +2537,31 @@ class Client {
             return false;
         }
     }
-    /**
-     * Fetches the inbox states for the specified inbox IDs from the network
-     * without a client
-     *
-     * @param env - The environment to use
-     * @param inboxIds - The inbox IDs to get the state for
-     * @returns The inbox states for the specified inbox IDs
-     */
-    static async fetchInboxStates(inboxIds, env, gatewayHost) {
-        const host = ApiUrls[env ?? "dev"];
-        return inboxStateFromInboxIds(host, gatewayHost, inboxIds);
+    static async fetchInboxStates(inboxIds, envOrBackend, gatewayHost) {
+        const backend = await resolveBackend(envOrBackend, gatewayHost);
+        return fetchInboxStatesByInboxIds(backend, inboxIds);
+    }
+    static async fetchLatestInboxUpdatesCount(inboxIds, envOrBackend, gatewayHost) {
+        const backend = await resolveBackend(envOrBackend, gatewayHost);
+        // The node-bindings Client is a napi-rs class with no explicit close/free
+        // method. Release is non-deterministic: once this reference goes out of
+        // scope, JS GC will eventually invoke the Rust Drop impl and reclaim the
+        // underlying resources. If this becomes a bottleneck, switch to an
+        // explicit disposal API if/when the bindings expose one.
+        const { client } = await createClient(createEphemeralIdentifier(), {
+            backend,
+            dbPath: null,
+            disableDeviceSync: true,
+        });
+        const result = await client.fetchInboxUpdatesCount(inboxIds, true);
+        return toInboxUpdatesCountMap(result);
     }
-    /**
-     * 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
-     */
-    static async canMessage(identifiers, env) {
+    /* eslint-enable @typescript-eslint/unified-signatures */
+    static async canMessage(identifiers, envOrBackend) {
+        const backend = await resolveBackend(envOrBackend);
         const canMessageMap = new Map();
         for (const identifier of identifiers) {
-            const inboxId = await getInboxIdForIdentifier(identifier, env);
+            const inboxId = await getInboxIdForIdentifier(backend, identifier);
             canMessageMap.set(identifier.identifier.toLowerCase(), inboxId !== null);
         }
         return canMessageMap;
@@ -2439,42 +2583,150 @@ class Client {
             return false;
         }
     }
+    static async isAddressAuthorized(inboxId, address, envOrBackend, gatewayHost) {
+        const backend = await resolveBackend(envOrBackend, gatewayHost);
+        return await isAddressAuthorized(backend, inboxId, address);
+    }
+    static async isInstallationAuthorized(inboxId, installation, envOrBackend, gatewayHost) {
+        const backend = await resolveBackend(envOrBackend, gatewayHost);
+        return await isInstallationAuthorized(backend, inboxId, installation);
+    }
     /**
-     * Checks if an address is authorized for an inbox
-     *
-     * @param inboxId - The inbox ID to check
-     * @param address - The address to check
-     * @param options - Optional network options
-     * @returns Whether the address is authorized
+     * Get the default archive options (consent and messages)
      */
-    static async isAddressAuthorized(inboxId, address, env, gatewayHost) {
-        const host = ApiUrls[env ?? "dev"];
-        return await isAddressAuthorized(host, gatewayHost, inboxId, address);
+    #getDefaultArchiveOptions() {
+        return {
+            elements: [
+                "Consent" /* BackupElementSelectionOption.Consent */,
+                "Messages" /* BackupElementSelectionOption.Messages */,
+            ],
+            excludeDisappearingMessages: false,
+        };
     }
     /**
-     * Checks if an installation is authorized for an inbox
-     *
-     * @param inboxId - The inbox ID to check
-     * @param installation - The installation to check
-     * @param options - Optional network options
-     * @returns Whether the installation is authorized
+     * Get the default server URL based on the environment
      */
-    static async isInstallationAuthorized(inboxId, installation, env, gatewayHost) {
-        const host = ApiUrls[env ?? "dev"];
-        return await isInstallationAuthorized(host, gatewayHost, inboxId, installation);
+    #getDefaultServerUrl() {
+        const env = this.env;
+        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() {
+    async sendSyncRequest(options, serverUrl) {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        const resolvedOptions = options ?? this.#getDefaultArchiveOptions();
+        const resolvedServerUrl = serverUrl ?? this.#getDefaultServerUrl();
+        return this.#client
+            .deviceSync()
+            .sendSyncRequest(resolvedOptions, 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, options, serverUrl) {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        const resolvedOptions = options ?? this.#getDefaultArchiveOptions();
+        const resolvedServerUrl = serverUrl ?? this.#getDefaultServerUrl();
+        return this.#client
+            .deviceSync()
+            .sendSyncArchive(resolvedOptions, 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) {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        return this.#client.deviceSync().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 Array of available archive information
+     */
+    listAvailableArchives(daysCutoff) {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        return this.#client.deviceSync().listAvailableArchives(daysCutoff);
+    }
+    /**
+     * Archive application elements to file for later restoration
+     *
+     * @param path - The file path to save the archive
+     * @param key - Encryption key for the archive
+     * @param opts - Archive options specifying what to include (defaults to consent and messages)
+     * @returns Promise that resolves when the archive is created
+     */
+    async createArchive(path, key, opts) {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        const resolvedOpts = opts ?? this.#getDefaultArchiveOptions();
+        return this.#client.deviceSync().createArchive(path, resolvedOpts, key);
+    }
+    /**
+     * Import a previous archive from a file
+     *
+     * @param path - The file path to the archive
+     * @param key - Encryption key for the archive
+     * @returns Promise that resolves when the archive is imported
+     */
+    async importArchive(path, key) {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        return this.#client.deviceSync().importArchive(path, key);
+    }
+    /**
+     * Load the metadata for an archive to see what it contains
+     *
+     * Reads only the metadata without loading the entire file, so this function is quick.
+     *
+     * @param path - The file path to the archive
+     * @param key - Encryption key for the archive
+     * @returns Promise that resolves with the archive metadata
+     */
+    async archiveMetadata(path, key) {
+        if (!this.#client) {
+            throw new ClientNotInitializedError();
+        }
+        return this.#client.deviceSync().archiveMetadata(path, key);
+    }
+    /**
+     * Manually sync all device sync groups
+     *
+     * @returns Promise that resolves with a summary of the sync operation
+     */
+    async syncAllDeviceSyncGroups() {
         if (!this.#client) {
             throw new ClientNotInitializedError();
         }
-        return this.#client.sendSyncRequest();
+        return this.#client.deviceSync().syncAllDeviceSyncGroups();
     }
 }
 
-export { AccountAlreadyAssociatedError, ApiUrls, Client, ClientNotInitializedError, Conversation, Conversations, DecodedMessage, Dm, Group, HistorySyncUrls, InboxReassignError, MissingContentTypeError, SignerUnavailableError, StreamFailedError, StreamInvalidRetryAttemptsError, generateInboxId, getInboxIdForIdentifier, isActions, isAttachment, isGroupUpdated, isHexString, isIntent, isLeaveRequest, isMarkdown, isMultiRemoteAttachment, isReaction, isReadReceipt, isRemoteAttachment, isReply, isText, isTextReply, isTransactionReference, isWalletSendCalls, validHex };
+export { AccountAlreadyAssociatedError, ApiUrls, Client, ClientNotInitializedError, Conversation, Conversations, DecodedMessage, Dm, Group, HistorySyncUrls, InboxReassignError, MissingContentTypeError, SignerUnavailableError, StreamFailedError, StreamInvalidRetryAttemptsError, createBackend, envToString, generateInboxId, getInboxIdForIdentifier, isActions, isAttachment, isGroupUpdated, isHexString, isIntent, isLeaveRequest, isMarkdown, isMultiRemoteAttachment, isReaction, isReadReceipt, isRemoteAttachment, isReply, isText, isTextReply, isTransactionReference, isWalletSendCalls, validHex };
 //# sourceMappingURL=index.js.map