@xmtp/node-sdk 5.5.0 → 6.0.0-dev.4b2b209

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import { ContentCodec, ContentTypeId } from '@xmtp/content-type-primitives';
 import * as _xmtp_node_bindings from '@xmtp/node-bindings';
-import { ContentTypeId as ContentTypeId$1, DeliveryStatus, GroupMessageKind, Reaction, DecodedMessage as DecodedMessage$1, LeaveRequest, ReadReceipt, Attachment, RemoteAttachment, TransactionReference, WalletSendCalls, Actions, Intent, MultiRemoteAttachment, GroupUpdated, DeletedMessage, LogLevel, Identifier, StreamCloser, Conversation as Conversation$1, Message, EncodedContent, SendMessageOpts, Reply, ListMessagesOptions, ConsentState, PermissionUpdateType, PermissionPolicy, MetadataField, Conversations as Conversations$1, CreateGroupOptions, CreateDmOptions, ListConversationsOptions, ConversationType, Client as Client$1, Consent, ConsentEntityType, UserPreferenceUpdate, SignatureRequestHandle } from '@xmtp/node-bindings';
-export { Action, ActionStyle, Actions, ApiStats, Attachment, Consent, ConsentEntityType, ConsentState, ContentType, ConversationDebugInfo, ConversationListItem, ConversationType, CreateDmOptions, CreateGroupOptions, Cursor, DeliveryStatus, EncryptedAttachment, GroupMember, GroupMembershipState, GroupMessageKind, GroupMetadata, GroupPermissions, GroupPermissionsOptions, GroupSyncSummary, GroupUpdated, HmacKey, Identifier, IdentifierKind, IdentityStats, Inbox, InboxState, Installation, Intent, KeyPackageStatus, LeaveRequest, Lifetime, ListConversationsOptions, ListConversationsOrderBy, ListMessagesOptions, LogLevel, LogOptions, Message, MessageDisappearingSettings, MessageSortBy, MetadataField, MetadataFieldChange, MultiRemoteAttachment, PermissionLevel, PermissionPolicy, PermissionPolicySet, PermissionUpdateType, Reaction, ReactionAction, ReactionSchema, ReadReceipt, RemoteAttachment, RemoteAttachmentInfo, Reply, SendMessageOpts, SignatureRequestHandle, SortDirection, TransactionMetadata, TransactionReference, UserPreferenceUpdate, WalletCall, WalletSendCalls, 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 { ContentTypeId as ContentTypeId$1, DeliveryStatus, GroupMessageKind, Reaction, DecodedMessage as DecodedMessage$1, LeaveRequest, ReadReceipt, Attachment, RemoteAttachment, TransactionReference, WalletSendCalls, Actions, Intent, MultiRemoteAttachment, GroupUpdated, DeletedMessage, Backend, LogLevel, VisibilityConfirmationOptions, XmtpEnv as XmtpEnv$1, Identifier, StreamCloser, Conversation as Conversation$1, Message, EncodedContent, SendMessageOpts, Reply, ListMessagesOptions, ConsentState, PermissionUpdateType, PermissionPolicy, MetadataField, Conversations as Conversations$1, CreateGroupOptions, CreateDmOptions, ListConversationsOptions, ConversationType, Client as Client$1, Consent, ConsentEntityType, UserPreferenceUpdate, SignatureRequestHandle, InboxState, ArchiveOptions, AvailableArchiveInfo, ArchiveMetadata, GroupSyncSummary } from '@xmtp/node-bindings';
+export { Action, ActionStyle, Actions, ApiStats, ArchiveMetadata, ArchiveOptions, Attachment, AvailableArchiveInfo, Backend, BackendBuilder, BackupElementSelectionOption, Consent, ConsentEntityType, ConsentState, ContentType, ConversationDebugInfo, ConversationListItem, ConversationType, CreateDmOptions, CreateGroupOptions, Cursor, DeliveryStatus, EncryptedAttachment, GroupMember, GroupMembershipState, GroupMessageKind, GroupMetadata, GroupPermissions, GroupPermissionsOptions, GroupSyncSummary, GroupUpdated, HmacKey, Identifier, IdentifierKind, IdentityStats, Inbox, InboxState, Installation, Intent, KeyPackageStatus, LeaveRequest, Lifetime, ListConversationsOptions, ListConversationsOrderBy, ListMessagesOptions, LogLevel, LogOptions, Message, MessageDisappearingSettings, MessageSortBy, MetadataField, MetadataFieldChange, MultiRemoteAttachment, PermissionLevel, PermissionPolicy, PermissionPolicySet, PermissionUpdateType, Reaction, ReactionAction, ReactionSchema, ReadReceipt, RemoteAttachment, Reply, SendMessageOpts, SignatureRequestHandle, SortDirection, TransactionMetadata, TransactionReference, UserPreferenceUpdate, VisibilityConfirmationOptions, WalletCall, WalletSendCalls, 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';
 
 /**
  * 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
@@ -28,6 +29,10 @@ declare const HistorySyncUrls: {
     readonly local: "http://localhost:5558";
     readonly dev: "https://message-history.dev.ephemera.network";
     readonly production: "https://message-history.production.ephemera.network";
+    readonly "testnet-staging": "https://message-history.dev.ephemera.network";
+    readonly "testnet-dev": "https://message-history.dev.ephemera.network";
+    readonly testnet: "https://message-history.dev.ephemera.network";
+    readonly mainnet: "https://message-history.production.ephemera.network";
 };
 
 declare class CodecRegistry {
@@ -86,7 +91,7 @@ declare function validHex(value: unknown): HexString;
 /**
  * XMTP environment
  */
-type XmtpEnv = keyof typeof ApiUrls;
+type XmtpEnv = "local" | "dev" | "production" | "testnet-staging" | "testnet-dev" | "testnet" | "mainnet";
 /**
  * Network options
  */
@@ -102,6 +107,23 @@ type NetworkOptions = {
      * specific endpoint
      */
     apiUrl?: string;
+    /**
+     * The host of the XMTP Gateway for your application
+     *
+     * Only valid for `dev` and `production` environments
+     *
+     * @see https://docs.xmtp.org/fund-agents-apps/run-gateway
+     */
+    gatewayHost?: string;
+    /**
+     * Custom app version
+     */
+    appVersion?: string;
+};
+/**
+ * Device sync options
+ */
+type DeviceSyncOptions = {
     /**
      * historySyncUrl can be used to override the `env` flag and connect to a
      * specific endpoint for syncing history
@@ -110,13 +132,9 @@ type NetworkOptions = {
      */
     historySyncUrl?: string | null;
     /**
-     * The host of the XMTP Gateway for your application
-     *
-     * Only valid for `testnet` and `mainnet` environments
-     *
-     * @see:https://docs.xmtp.org/fund-agents-apps/run-gateway
+     * Disable device sync
      */
-    gatewayHost?: string;
+    disableDeviceSync?: boolean;
 };
 /**
  * Storage options
@@ -170,21 +188,22 @@ type OtherOptions = {
      * Disable automatic registration when creating a client
      */
     disableAutoRegister?: boolean;
-    /**
-     * Disable device sync
-     */
-    disableDeviceSync?: boolean;
-    /**
-     * Custom app version
-     */
-    appVersion?: string;
     /**
      * The nonce to use when generating an inbox ID
      * (default: undefined = 1)
      */
     nonce?: bigint;
+    /**
+     * 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;
 };
-type ClientOptions = NetworkOptions & StorageOptions & ContentOptions & OtherOptions;
+type ClientOptions = (NetworkOptions | {
+    backend: Backend;
+}) & DeviceSyncOptions & StorageOptions & ContentOptions & OtherOptions;
 type EnrichedReply<T = unknown, U = unknown> = {
     referenceId: string;
     content: T;
@@ -194,6 +213,9 @@ type EnrichedReply<T = unknown, U = unknown> = {
 type BuiltInContentTypes = string | LeaveRequest | Reaction | ReadReceipt | Attachment | RemoteAttachment | TransactionReference | WalletSendCalls | Actions | Intent | MultiRemoteAttachment | GroupUpdated | DeletedMessage;
 type ExtractCodecContentTypes<C extends ContentCodec[] = []> = C extends readonly [] ? BuiltInContentTypes : [...C][number] extends ContentCodec<infer T> ? T | BuiltInContentTypes | EnrichedReply<T | BuiltInContentTypes, T | BuiltInContentTypes> : BuiltInContentTypes;
 
+declare const envToString: (env: XmtpEnv$1) => XmtpEnv;
+declare const createBackend: (options?: NetworkOptions) => Promise<Backend>;
+
 declare class InboxReassignError extends Error {
     constructor();
 }
@@ -217,7 +239,7 @@ declare class StreamInvalidRetryAttemptsError extends Error {
 }
 
 declare const generateInboxId: (identifier: Identifier, nonce?: bigint) => string;
-declare const getInboxIdForIdentifier: (identifier: Identifier, env?: XmtpEnv, gatewayHost?: string) => Promise<string | null>;
+declare const getInboxIdForIdentifier: (backend: Backend, identifier: Identifier) => Promise<string | null>;
 
 type SignMessage = (message: string) => Promise<Uint8Array> | Uint8Array;
 type GetIdentifier = () => Promise<Identifier> | Identifier;
@@ -1141,6 +1163,12 @@ declare class Client<ContentTypes = ExtractCodecContentTypes> {
      * Gets the app version used by the client
      */
     get appVersion(): string | undefined;
+    /**
+     * Gets the XMTP environment the client is connected to
+     *
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     */
+    get env(): XmtpEnv;
     /**
      * Gets the client options
      */
@@ -1371,10 +1399,22 @@ declare 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 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 revokeInstallations(signer: Signer, inboxId: string, installationIds: Uint8Array[], env?: XmtpEnv, gatewayHost?: string): Promise<void>;
     /**
@@ -1395,6 +1435,23 @@ declare class Client<ContentTypes = ExtractCodecContentTypes> {
      * @throws {ClientNotInitializedError} if the client is not initialized
      */
     canMessage(identifiers: Identifier[]): Promise<Map<string, boolean>>;
+    /**
+     * Fetches the latest inbox updates count for the specified inbox IDs
+     *
+     * @param inboxIds - The inbox IDs to check
+     * @param refreshFromNetwork - Whether to refresh from the network
+     * @returns Map of inbox IDs to their updates count
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     */
+    fetchLatestInboxUpdatesCount(inboxIds: string[], _refreshFromNetwork?: boolean): Promise<Map<string, number>>;
+    /**
+     * Fetches the latest inbox updates count for the client's inbox
+     *
+     * @param refreshFromNetwork - Whether to refresh from the network
+     * @returns The latest inbox updates count
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     */
+    fetchOwnInboxUpdatesCount(_refreshFromNetwork?: boolean): Promise<number>;
     /**
      * Fetches the key package statuses from the network for the specified
      * installation IDs
@@ -1434,17 +1491,62 @@ declare class Client<ContentTypes = ExtractCodecContentTypes> {
      * 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
+     * @param backend - Optional `Backend` instance created with `createBackend()`
      * @returns The inbox states for the specified inbox IDs
      */
-    static fetchInboxStates(inboxIds: string[], env?: XmtpEnv, gatewayHost?: string): Promise<_xmtp_node_bindings.InboxState[]>;
+    static 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 fetchInboxStates(inboxIds: string[], env?: XmtpEnv, gatewayHost?: string): Promise<InboxState[]>;
+    /**
+     * 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()`
+     * @param refreshFromNetwork - Whether to refresh from the network
+     * @returns Map of inbox IDs to their updates count
+     */
+    static fetchLatestInboxUpdatesCount(inboxIds: string[], backendOrEnv?: Backend | XmtpEnv, refreshFromNetwork?: boolean): 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 - The environment to use
+     * @param gatewayHost - Optional gateway host
+     * @param refreshFromNetwork - Whether to refresh from the network
+     * @returns Map of inbox IDs to their updates count
+     * @deprecated Pass a `Backend` instance created with `createBackend()` instead
+     * of `XmtpEnv` and `gatewayHost`.
+     */
+    static fetchLatestInboxUpdatesCount(inboxIds: string[], env?: XmtpEnv, gatewayHost?: string, refreshFromNetwork?: boolean): Promise<Map<string, number>>;
+    /**
+     * 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 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 canMessage(identifiers: Identifier[], env?: XmtpEnv): Promise<Map<string, boolean>>;
     /**
@@ -1461,8 +1563,20 @@ declare class Client<ContentTypes = ExtractCodecContentTypes> {
      *
      * @param inboxId - The inbox ID to check
      * @param address - The address to check
-     * @param options - Optional network options
+     * @param backend - Optional `Backend` instance created with `createBackend()`
+     * @returns Whether the address is authorized
+     */
+    static isAddressAuthorized(inboxId: string, address: string, backend?: Backend): Promise<boolean>;
+    /**
+     * Checks if an address is authorized for an inbox
+     *
+     * @param inboxId - The inbox ID to check
+     * @param address - The address to check
+     * @param env - The environment to use
+     * @param gatewayHost - Optional gateway host
      * @returns Whether the address is authorized
+     * @deprecated Pass a `Backend` instance created with `createBackend()` instead
+     * of `XmtpEnv` and `gatewayHost`.
      */
     static isAddressAuthorized(inboxId: string, address: string, env?: XmtpEnv, gatewayHost?: string): Promise<boolean>;
     /**
@@ -1470,17 +1584,90 @@ declare class Client<ContentTypes = ExtractCodecContentTypes> {
      *
      * @param inboxId - The inbox ID to check
      * @param installation - The installation to check
-     * @param options - Optional network options
+     * @param backend - Optional `Backend` instance created with `createBackend()`
      * @returns Whether the installation is authorized
      */
+    static isInstallationAuthorized(inboxId: string, installation: Uint8Array, backend?: Backend): Promise<boolean>;
+    /**
+     * Checks if an installation is authorized for an inbox
+     *
+     * @param inboxId - The inbox ID to check
+     * @param installation - The installation to check
+     * @param env - The environment to use
+     * @param gatewayHost - Optional gateway host
+     * @returns Whether the installation is authorized
+     * @deprecated Pass a `Backend` instance created with `createBackend()` instead
+     * of `XmtpEnv` and `gatewayHost`.
+     */
     static isInstallationAuthorized(inboxId: string, installation: Uint8Array, env?: XmtpEnv, gatewayHost?: string): Promise<boolean>;
     /**
      * 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
      */
-    sendSyncRequest(): Promise<void>;
+    sendSyncRequest(options?: ArchiveOptions, serverUrl?: string): Promise<void>;
+    /**
+     * 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
+     */
+    sendSyncArchive(pin: string, options?: ArchiveOptions, serverUrl?: string): Promise<void>;
+    /**
+     * 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
+     */
+    processSyncArchive(archivePin?: string | null): Promise<void>;
+    /**
+     * 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: number): AvailableArchiveInfo[];
+    /**
+     * 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
+     */
+    createArchive(path: string, key: Uint8Array, opts?: ArchiveOptions): Promise<void>;
+    /**
+     * 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
+     */
+    importArchive(path: string, key: Uint8Array): Promise<void>;
+    /**
+     * 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
+     */
+    archiveMetadata(path: string, key: Uint8Array): Promise<ArchiveMetadata>;
+    /**
+     * Manually sync all device sync groups
+     *
+     * @returns Promise that resolves with a summary of the sync operation
+     */
+    syncAllDeviceSyncGroups(): Promise<GroupSyncSummary>;
 }
 
-export { AccountAlreadyAssociatedError, ApiUrls, Client, ClientNotInitializedError, Conversation, Conversations, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY, DecodedMessage, Dm, Group, HistorySyncUrls, InboxReassignError, MissingContentTypeError, SignerUnavailableError, StreamFailedError, StreamInvalidRetryAttemptsError, createStream, generateInboxId, getInboxIdForIdentifier, isActions, isAttachment, isGroupUpdated, isHexString, isIntent, isLeaveRequest, isMarkdown, isMultiRemoteAttachment, isReaction, isReadReceipt, isRemoteAttachment, isReply, isText, isTextReply, isTransactionReference, isWalletSendCalls, validHex };
-export type { AsyncStreamProxy, BuiltInContentTypes, ClientOptions, ContentOptions, EOASigner, EnrichedReply, ExtractCodecContentTypes, HexString, NetworkOptions, OtherOptions, SCWSigner, Signer, StorageOptions, StreamCallback, StreamFunction, StreamOptions, StreamValueMutator, XmtpEnv };
+export { AccountAlreadyAssociatedError, ApiUrls, Client, ClientNotInitializedError, Conversation, Conversations, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY, DecodedMessage, Dm, Group, HistorySyncUrls, InboxReassignError, MissingContentTypeError, SignerUnavailableError, StreamFailedError, StreamInvalidRetryAttemptsError, createBackend, createStream, envToString, generateInboxId, getInboxIdForIdentifier, isActions, isAttachment, isGroupUpdated, isHexString, isIntent, isLeaveRequest, isMarkdown, isMultiRemoteAttachment, isReaction, isReadReceipt, isRemoteAttachment, isReply, isText, isTextReply, isTransactionReference, isWalletSendCalls, validHex };
+export type { AsyncStreamProxy, BuiltInContentTypes, ClientOptions, ContentOptions, DeviceSyncOptions, EOASigner, EnrichedReply, ExtractCodecContentTypes, HexString, NetworkOptions, OtherOptions, SCWSigner, Signer, StorageOptions, StreamCallback, StreamFunction, StreamOptions, StreamValueMutator, XmtpEnv };