@xmtp/node-sdk 3.2.1-dev.cb2628c → 3.2.2

package/README.md

@@ -9,7 +9,7 @@ To keep up with the latest SDK developments, see the [Issues tab](https://githu
 
 ## Documentation
 
-To learn how to use the XMTP client SDK for Node and get answers to frequently asked questions, see the [XMTP documentation](https://docs.xmtp.org/).
+To learn how to use the XMTP client SDK for Node, see [Get started with the XMTP Node SDK](https://docs.xmtp.org/sdks/node).
 
 ## SDK reference
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ContentCodec, ContentTypeId, EncodedContent } from '@xmtp/content-type-primitives';
 import * as _xmtp_node_bindings from '@xmtp/node-bindings';
-import { LogLevel, Message, Conversation as Conversation$1, ListMessagesOptions, ConsentState, PermissionUpdateType, PermissionPolicy, MetadataField, Identifier, Conversations as Conversations$1, CreateGroupOptions, CreateDmOptions, ListConversationsOptions, ConversationType, Client as Client$1, Consent, ConsentEntityType, SignatureRequestType } from '@xmtp/node-bindings';
-export { Consent, ConsentEntityType, ConsentState, ContentType, ContentTypeId, ConversationListItem, ConversationType, CreateDmOptions, CreateGroupOptions, DeliveryStatus, EncodedContent, GroupMember, GroupMembershipState, GroupMessageKind, GroupMetadata, GroupPermissions, GroupPermissionsOptions, HmacKey, Identifier, IdentifierKind, InboxState, Installation, KeyPackageStatus, Lifetime, ListConversationsOptions, ListMessagesOptions, LogLevel, LogOptions, Message, MessageDisappearingSettings, MetadataField, PermissionLevel, PermissionPolicy, PermissionPolicySet, PermissionUpdateType, SignatureRequestType, SortDirection } from '@xmtp/node-bindings';
+import { LogLevel, Message, Conversation as Conversation$1, ListMessagesOptions, ConsentState, PermissionUpdateType, PermissionPolicy, MetadataField, Identifier, Conversations as Conversations$1, CreateGroupOptions, CreateDmOptions, ListConversationsOptions, ConversationType, Client as Client$1, Consent, ConsentEntityType, SignatureRequestHandle } from '@xmtp/node-bindings';
+export { Consent, ConsentEntityType, ConsentState, ContentType, ContentTypeId, ConversationListItem, ConversationType, CreateDmOptions, CreateGroupOptions, DeliveryStatus, EncodedContent, GroupMember, GroupMembershipState, GroupMessageKind, GroupMetadata, GroupPermissions, GroupPermissionsOptions, HmacKey, Identifier, IdentifierKind, InboxState, Installation, KeyPackageStatus, Lifetime, ListConversationsOptions, ListMessagesOptions, LogLevel, LogOptions, Message, MessageDisappearingSettings, MetadataField, PermissionLevel, PermissionPolicy, PermissionPolicySet, PermissionUpdateType, SignatureRequestHandle, SortDirection } from '@xmtp/node-bindings';
 import { GroupUpdatedCodec } from '@xmtp/content-type-group-updated';
 import { TextCodec } from '@xmtp/content-type-text';
 
@@ -115,21 +115,16 @@ type ResolveValue<T> = {
 type StreamCallback<T> = (err: Error | null, value: T | undefined) => void;
 declare class AsyncStream<T> {
     #private;
-    onReturn: (() => void) | undefined;
-    onError: ((error: Error) => void) | undefined;
     constructor();
-    get error(): Error | null;
+    get error(): Error | undefined;
     get isDone(): boolean;
+    set onReturn(callback: () => void);
+    set onError(callback: (error: Error) => void);
+    set onDone(callback: () => void);
     callback: StreamCallback<T>;
     next: () => Promise<ResolveValue<T>>;
-    return: (value?: T) => Promise<{
-        done: boolean;
-        value: T | undefined;
-    }>;
-    end: () => Promise<{
-        done: boolean;
-        value: T | undefined;
-    }>;
+    return: (value?: T) => Promise<ResolveValue<T>>;
+    end: () => Promise<ResolveValue<T>>;
     [Symbol.asyncIterator](): this;
 }
 
@@ -234,7 +229,7 @@ declare class Conversation<ContentTypes = unknown> {
      * @param callback - Optional callback function for handling new stream values
      * @returns Stream instance for new messages
      */
-    stream(callback?: StreamCallback<DecodedMessage<ContentTypes>>): AsyncStream<DecodedMessage<ContentTypes>>;
+    stream(callback?: StreamCallback<DecodedMessage<ContentTypes>>, onFail?: () => void): AsyncStream<DecodedMessage<ContentTypes>>;
     /**
      * Publishes pending messages that were sent optimistically
      *
@@ -314,7 +309,7 @@ declare class Conversation<ContentTypes = unknown> {
      *
      * @returns The HMAC keys for this conversation
      */
-    getHmacKeys(): _xmtp_node_bindings.HmacKey[];
+    getHmacKeys(): Record<string, _xmtp_node_bindings.HmacKey[]>;
     /**
      * Retrieves information for this conversation to help with debugging
      *
@@ -594,42 +589,42 @@ declare class Conversations<ContentTypes = unknown> {
      * @param callback - Optional callback function for handling new stream value
      * @returns Stream instance for new conversations
      */
-    stream(callback?: StreamCallback<Group<ContentTypes> | Dm<ContentTypes>>): AsyncStream<Group<ContentTypes> | Dm<ContentTypes>>;
+    stream(callback?: StreamCallback<Group<ContentTypes> | Dm<ContentTypes>>, onFail?: () => void): AsyncStream<Group<ContentTypes> | Dm<ContentTypes>>;
     /**
      * Creates a stream for new group conversations
      *
      * @param callback - Optional callback function for handling new stream value
      * @returns Stream instance for new group conversations
      */
-    streamGroups(callback?: StreamCallback<Group<ContentTypes>>): AsyncStream<Group<ContentTypes>>;
+    streamGroups(callback?: StreamCallback<Group<ContentTypes>>, onFail?: () => void): AsyncStream<Group<ContentTypes>>;
     /**
      * Creates a stream for new DM conversations
      *
      * @param callback - Optional callback function for handling new stream value
      * @returns Stream instance for new DM conversations
      */
-    streamDms(callback?: StreamCallback<Dm<ContentTypes>>): AsyncStream<Dm<ContentTypes>>;
+    streamDms(callback?: StreamCallback<Dm<ContentTypes>>, onFail?: () => void): AsyncStream<Dm<ContentTypes>>;
     /**
      * Creates a stream for all new messages
      *
      * @param callback - Optional callback function for handling new stream value
      * @returns Stream instance for new messages
      */
-    streamAllMessages(callback?: StreamCallback<DecodedMessage<ContentTypes>>, conversationType?: ConversationType, consentStates?: ConsentState[]): Promise<AsyncStream<DecodedMessage<ContentTypes>>>;
+    streamAllMessages(callback?: StreamCallback<DecodedMessage<ContentTypes>>, conversationType?: ConversationType, consentStates?: ConsentState[], onFail?: () => void): Promise<AsyncStream<DecodedMessage<ContentTypes>>>;
     /**
      * Creates a stream for all new group messages
      *
      * @param callback - Optional callback function for handling new stream value
      * @returns Stream instance for new group messages
      */
-    streamAllGroupMessages(callback?: StreamCallback<DecodedMessage<ContentTypes>>, consentStates?: ConsentState[]): Promise<AsyncStream<DecodedMessage<ContentTypes>>>;
+    streamAllGroupMessages(callback?: StreamCallback<DecodedMessage<ContentTypes>>, consentStates?: ConsentState[], onFail?: () => void): Promise<AsyncStream<DecodedMessage<ContentTypes>>>;
     /**
      * Creates a stream for all new DM messages
      *
      * @param callback - Optional callback function for handling new stream value
      * @returns Stream instance for new DM messages
      */
-    streamAllDmMessages(callback?: StreamCallback<DecodedMessage<ContentTypes>>, consentStates?: ConsentState[]): Promise<AsyncStream<DecodedMessage<ContentTypes>>>;
+    streamAllDmMessages(callback?: StreamCallback<DecodedMessage<ContentTypes>>, consentStates?: ConsentState[], onFail?: () => void): Promise<AsyncStream<DecodedMessage<ContentTypes>>>;
     /**
      * Retrieves HMAC keys for all conversations
      *
@@ -638,6 +633,21 @@ declare class Conversations<ContentTypes = unknown> {
     hmacKeys(): Record<string, _xmtp_node_bindings.HmacKey[]>;
 }
 
+/**
+ * Debug information helpers for the client
+ *
+ * This class is not intended to be initialized directly.
+ */
+declare class DebugInformation {
+    #private;
+    constructor(client: Client$1, options?: ClientOptions);
+    apiStatistics(): _xmtp_node_bindings.ApiStats;
+    apiIdentityStatistics(): _xmtp_node_bindings.IdentityStats;
+    apiAggregateStatistics(): string;
+    clearAllStatistics(): void;
+    uploadDebugArchive(serverUrl?: string): Promise<string>;
+}
+
 type PreferenceUpdate = {
     type: string;
     HmacKeyUpdate?: {
@@ -702,14 +712,14 @@ declare class Preferences {
      * @param callback - Optional callback function for handling stream updates
      * @returns Stream instance for consent updates
      */
-    streamConsent(callback?: StreamCallback<Consent[]>): AsyncStream<Consent[]>;
+    streamConsent(callback?: StreamCallback<Consent[]>, onFail?: () => void): AsyncStream<Consent[]>;
     /**
      * Creates a stream of user preference updates
      *
      * @param callback - Optional callback function for handling stream updates
      * @returns Stream instance for preference updates
      */
-    streamPreferences(callback?: StreamCallback<PreferenceUpdate>): AsyncStream<PreferenceUpdate>;
+    streamPreferences(callback?: StreamCallback<PreferenceUpdate>, onFail?: () => void): AsyncStream<PreferenceUpdate>;
 }
 
 type SignMessage = (message: string) => Promise<Uint8Array> | Uint8Array;
@@ -728,11 +738,15 @@ type Signer = {
     getChainId: GetChainId;
 };
 
-type ExtractCodecContentType<C> = C extends ContentCodec<infer T> ? T : never;
+type ExtractCodecContentTypes<C extends ContentCodec[] = []> = [
+    ...C,
+    GroupUpdatedCodec,
+    TextCodec
+][number] extends ContentCodec<infer T> ? T : never;
 /**
  * Client for interacting with the XMTP network
  */
-declare class Client<ContentTypes = unknown> {
+declare class Client<ContentTypes = ExtractCodecContentTypes> {
     #private;
     /**
      * Creates a new XMTP client instance
@@ -761,7 +775,7 @@ declare class Client<ContentTypes = unknown> {
      */
     static create<ContentCodecs extends ContentCodec[] = []>(signer: Signer, options?: Omit<ClientOptions, "codecs"> & {
         codecs?: ContentCodecs;
-    }): Promise<Client<ExtractCodecContentType<[...ContentCodecs, GroupUpdatedCodec, TextCodec][number]>>>;
+    }): Promise<Client<ExtractCodecContentTypes<ContentCodecs>>>;
     /**
      * Creates a new client instance with an identifier
      *
@@ -774,7 +788,7 @@ declare class Client<ContentTypes = unknown> {
      */
     static build<ContentCodecs extends ContentCodec[] = []>(identifier: Identifier, options?: Omit<ClientOptions, "codecs"> & {
         codecs?: ContentCodecs;
-    }): Promise<Client<ExtractCodecContentType<[...ContentCodecs, GroupUpdatedCodec, TextCodec][number]>>>;
+    }): Promise<Client<ExtractCodecContentTypes<ContentCodecs>>>;
     /**
      * Gets the client options
      */
@@ -811,6 +825,12 @@ declare class Client<ContentTypes = unknown> {
      * @throws {ClientNotInitializedError} if the client is not initialized
      */
     get conversations(): Conversations<ContentTypes>;
+    /**
+     * Gets the debug information helpersfor this client
+     *
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     */
+    get debugInformation(): DebugInformation;
     /**
      * Gets the preferences manager for this client
      *
@@ -818,7 +838,24 @@ declare class Client<ContentTypes = unknown> {
      */
     get preferences(): Preferences;
     /**
-     * Creates signature text for creating a new inbox
+     * Adds a signature to a signature request using the client's signer (or the
+     * provided signer)
+     *
+     * WARNING: This function should be used with caution. It is only provided
+     * for use in special cases where the provided workflows do not meet the
+     * requirements of an application.
+     *
+     * It is highly recommended to use the `register`, `unsafe_addAccount`,
+     * `removeAccount`, `revokeAllOtherInstallations`, or `revokeInstallations`
+     * methods instead.
+     *
+     * @param signatureRequest - The signature request to add the signature to
+     * @throws {ClientNotInitializedError} if the client is not initialized
+     * @throws {SignerUnavailableError} if no signer is available
+     */
+    unsafe_addSignature(signatureRequest: SignatureRequestHandle, signer?: Signer): Promise<void>;
+    /**
+     * Returns a signature request handler for creating a new inbox
      *
      * WARNING: This function should be used with caution. It is only provided
      * for use in special cases where the provided workflows do not meet the
@@ -829,9 +866,10 @@ declare class Client<ContentTypes = unknown> {
      * @returns The signature text
      * @throws {ClientNotInitializedError} if the client is not initialized
      */
-    unsafe_createInboxSignatureText(): Promise<string | null | undefined>;
+    unsafe_createInboxSignatureRequest(): Promise<SignatureRequestHandle | null>;
     /**
-     * Creates signature text for adding a new account to the client's inbox
+     * Returns a signature request handler for adding a new account to the
+     * client's inbox
      *
      * WARNING: This function should be used with caution. It is only provided
      * for use in special cases where the provided workflows do not meet the
@@ -847,9 +885,10 @@ declare class Client<ContentTypes = unknown> {
      * @returns The signature text
      * @throws {ClientNotInitializedError} if the client is not initialized
      */
-    unsafe_addAccountSignatureText(newAccountIdentifier: Identifier, allowInboxReassign?: boolean): Promise<string | undefined>;
+    unsafe_addAccountSignatureRequest(newAccountIdentifier: Identifier, allowInboxReassign?: boolean): Promise<SignatureRequestHandle>;
     /**
-     * Creates signature text for removing an account from the client's inbox
+     * Returns a signature request handler for removing an account from the
+     * client's inbox
      *
      * WARNING: This function should be used with caution. It is only provided
      * for use in special cases where the provided workflows do not meet the
@@ -861,10 +900,10 @@ declare class Client<ContentTypes = unknown> {
      * @returns The signature text
      * @throws {ClientNotInitializedError} if the client is not initialized
      */
-    unsafe_removeAccountSignatureText(identifier: Identifier): Promise<string | undefined>;
+    unsafe_removeAccountSignatureRequest(identifier: Identifier): Promise<SignatureRequestHandle>;
     /**
-     * Creates signature text for revoking all other installations of the
-     * client's inbox
+     * Returns a signature request handler for revoking all other installations
+     * of the client's inbox
      *
      * WARNING: This function should be used with caution. It is only provided
      * for use in special cases where the provided workflows do not meet the
@@ -875,10 +914,10 @@ declare class Client<ContentTypes = unknown> {
      * @returns The signature text
      * @throws {ClientNotInitializedError} if the client is not initialized
      */
-    unsafe_revokeAllOtherInstallationsSignatureText(): Promise<string | undefined>;
+    unsafe_revokeAllOtherInstallationsSignatureRequest(): Promise<SignatureRequestHandle>;
     /**
-     * Creates signature text for revoking specific installations of the
-     * client's inbox
+     * Returns a signature request handler for revoking specific installations
+     * of the client's inbox
      *
      * WARNING: This function should be used with caution. It is only provided
      * for use in special cases where the provided workflows do not meet the
@@ -890,10 +929,10 @@ declare class Client<ContentTypes = unknown> {
      * @returns The signature text
      * @throws {ClientNotInitializedError} if the client is not initialized
      */
-    unsafe_revokeInstallationsSignatureText(installationIds: Uint8Array[]): Promise<string | undefined>;
+    unsafe_revokeInstallationsSignatureRequest(installationIds: Uint8Array[]): Promise<SignatureRequestHandle>;
     /**
-     * Creates signature text for changing the recovery identifier for this
-     * client's inbox
+     * Returns a signature request handler for changing the recovery identifier
+     * for this client's inbox
      *
      * WARNING: This function should be used with caution. It is only provided
      * for use in special cases where the provided workflows do not meet the
@@ -905,9 +944,9 @@ declare class Client<ContentTypes = unknown> {
      * @returns The signature text
      * @throws {ClientNotInitializedError} if the client is not initialized
      */
-    unsafe_changeRecoveryIdentifierSignatureText(identifier: Identifier): Promise<string | undefined>;
+    unsafe_changeRecoveryIdentifierSignatureRequest(identifier: Identifier): Promise<SignatureRequestHandle>;
     /**
-     * Adds a signature for a specific request type
+     * Applies a signature request to the client
      *
      * WARNING: This function should be used with caution. It is only provided
      * for use in special cases where the provided workflows do not meet the
@@ -917,26 +956,9 @@ declare class Client<ContentTypes = unknown> {
      * `removeAccount`, `revokeAllOtherInstallations`, or `revokeInstallations`
      * methods instead.
      *
-     * @param signatureType - The type of signature request
-     * @param signatureText - The text to sign
-     * @param signer - The signer to use
      * @throws {ClientNotInitializedError} if the client is not initialized
      */
-    unsafe_addSignature(signatureType: SignatureRequestType, signatureText: string, signer: Signer): Promise<void>;
-    /**
-     * Applies all pending signatures
-     *
-     * WARNING: This function should be used with caution. It is only provided
-     * for use in special cases where the provided workflows do not meet the
-     * requirements of an application.
-     *
-     * It is highly recommended to use the `register`, `unsafe_addAccount`,
-     * `removeAccount`, `revokeAllOtherInstallations`, or `revokeInstallations`
-     * methods instead.
-     *
-     * @throws {ClientNotInitializedError} if the client is not initialized
-     */
-    unsafe_applySignatures(): Promise<void>;
+    unsafe_applySignatureRequest(signatureRequest: SignatureRequestHandle): Promise<void>;
     /**
      * Registers the client with the XMTP network
      *
@@ -960,9 +982,8 @@ declare class Client<ContentTypes = unknown> {
      *
      * @param newAccountSigner - The signer for the new account
      * @param allowInboxReassign - Whether to allow inbox reassignment
-     * @throws {ClientNotInitializedError} if the client is not initialized
      * @throws {AccountAlreadyAssociatedError} if the account is already associated with an inbox ID
-     * @throws {GenerateSignatureError} if the signature cannot be generated
+     * @throws {ClientNotInitializedError} if the client is not initialized
      * @throws {SignerUnavailableError} if no signer is available
      */
     unsafe_addAccount(newAccountSigner: Signer, allowInboxReassign?: boolean): Promise<void>;
@@ -973,7 +994,6 @@ declare class Client<ContentTypes = unknown> {
      *
      * @param identifier - The identifier of the account to remove
      * @throws {ClientNotInitializedError} if the client is not initialized
-     * @throws {GenerateSignatureError} if the signature cannot be generated
      * @throws {SignerUnavailableError} if no signer is available
      */
     removeAccount(identifier: Identifier): Promise<void>;
@@ -983,7 +1003,6 @@ declare class Client<ContentTypes = unknown> {
      * Requires a signer, use `Client.create` to create a client with a signer.
      *
      * @throws {ClientNotInitializedError} if the client is not initialized
-     * @throws {GenerateSignatureError} if the signature cannot be generated
      * @throws {SignerUnavailableError} if no signer is available
      */
     revokeAllOtherInstallations(): Promise<void>;
@@ -995,9 +1014,25 @@ declare class Client<ContentTypes = unknown> {
      * @param installationIds - The installation IDs to revoke
      * @throws {ClientNotInitializedError} if the client is not initialized
      * @throws {SignerUnavailableError} if no signer is available
-     * @throws {GenerateSignatureError} if the signature cannot be generated
      */
     revokeInstallations(installationIds: Uint8Array[]): Promise<void>;
+    /**
+     * 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 revokeInstallations(signer: Signer, inboxId: string, installationIds: Uint8Array[], env?: XmtpEnv): Promise<void>;
+    /**
+     * Gets the inbox state for the specified inbox IDs without a client
+     *
+     * @param env - The environment to use
+     * @param inboxIds - The inbox IDs to get the state for
+     * @returns The inbox state for the specified inbox IDs
+     */
+    static inboxStateFromInboxIds(inboxIds: string[], env?: XmtpEnv): Promise<_xmtp_node_bindings.InboxState[]>;
     /**
      * Changes the recovery identifier for the client's inbox
      *
@@ -1006,7 +1041,6 @@ declare class Client<ContentTypes = unknown> {
      * @param identifier - The new recovery identifier
      * @throws {ClientNotInitializedError} if the client is not initialized
      * @throws {SignerUnavailableError} if no signer is available
-     * @throws {GenerateSignatureError} if the signature cannot be generated
      */
     changeRecoveryIdentifier(identifier: Identifier): Promise<void>;
     /**
@@ -1101,7 +1135,7 @@ declare class Client<ContentTypes = unknown> {
      * @param options - Optional network options
      * @returns Whether the address is authorized
      */
-    static isAddressAuthorized(inboxId: string, address: string, options?: NetworkOptions): Promise<boolean>;
+    static isAddressAuthorized(inboxId: string, address: string, env?: XmtpEnv): Promise<boolean>;
     /**
      * Checks if an installation is authorized for an inbox
      *
@@ -1110,7 +1144,7 @@ declare class Client<ContentTypes = unknown> {
      * @param options - Optional network options
      * @returns Whether the installation is authorized
      */
-    static isInstallationAuthorized(inboxId: string, installation: Uint8Array, options?: NetworkOptions): Promise<boolean>;
+    static isInstallationAuthorized(inboxId: string, installation: Uint8Array, env?: XmtpEnv): Promise<boolean>;
     /**
      * Gets the version of the Node bindings
      */
@@ -1120,4 +1154,27 @@ declare class Client<ContentTypes = unknown> {
 declare const generateInboxId: (identifier: Identifier) => string;
 declare const getInboxIdForIdentifier: (identifier: Identifier, env?: XmtpEnv) => Promise<string | null>;
 
-export { ApiUrls, AsyncStream, Client, type ClientOptions, Conversation, Conversations, DecodedMessage, Dm, Group, HistorySyncUrls, type NetworkOptions, type OtherOptions, type PreferenceUpdate, type Signer, type StorageOptions, type StreamCallback, type XmtpEnv, generateInboxId, getInboxIdForIdentifier };
+declare class CodecNotFoundError extends Error {
+    constructor(contentType: ContentTypeId);
+}
+declare class InboxReassignError extends Error {
+    constructor();
+}
+declare class AccountAlreadyAssociatedError extends Error {
+    constructor(inboxId: string);
+}
+declare class InvalidGroupMembershipChangeError extends Error {
+    constructor(messageId: string);
+}
+declare class MissingContentTypeError extends Error {
+    constructor();
+}
+declare class SignerUnavailableError extends Error {
+    constructor();
+}
+declare class ClientNotInitializedError extends Error {
+    constructor();
+}
+
+export { AccountAlreadyAssociatedError, ApiUrls, AsyncStream, Client, ClientNotInitializedError, CodecNotFoundError, Conversation, Conversations, DecodedMessage, Dm, Group, HistorySyncUrls, InboxReassignError, InvalidGroupMembershipChangeError, MissingContentTypeError, SignerUnavailableError, generateInboxId, getInboxIdForIdentifier };
+export type { ClientOptions, ExtractCodecContentTypes, NetworkOptions, OtherOptions, PreferenceUpdate, Signer, StorageOptions, StreamCallback, XmtpEnv };