@xdevplatform/chat-xdk 0.1.0 → 0.2.1

package/index.d.ts

@@ -10,6 +10,11 @@ export interface PublicKeys {
   identity: string;
   /** Base64-encoded signing public key */
   signing: string;
+  /**
+   * Always the empty string; reserved. The registered key version set via
+   * setKeyVersion is tracked internally and not surfaced here.
+   */
+  version: string;
 }
 
 /**
@@ -34,7 +39,8 @@ export interface PublicKeyRegistrationPayload {
 }
 
 /**
- * Result from encrypt*ForApi methods.
+ * Result from encryptMessage, encryptReply, encryptAddReaction, and
+ * encryptRemoveReaction.
  */
 export interface SendPayload {
   /** Base64-encoded Thrift MessageCreateEvent. */
@@ -52,7 +58,7 @@ export interface SendPayload {
 }
 
 /**
- * Result from signAddMembers / signKeyChange.
+ * An action signature authenticating a conversation key change or member add.
  */
 export interface ActionSignature {
   messageId: string;
@@ -60,19 +66,8 @@ export interface ActionSignature {
   signature: string;
   signatureVersion: string;
   publicKeyVersion: string;
-  signaturePayload: string;
-}
-
-/**
- * A recipient for encryptConversationKeyForRecipients.
- */
-export interface RecipientInput {
-  /** The recipient's user ID (snowflake string). */
-  userId: string;
-  /** Base64-encoded identity public key (SEC1 or SPKI). */
-  publicKey: string;
-  /** Key version string from the X API. */
-  keyVersion: string;
+  /** Omitted for conversation-key changes; the signed payload embeds the plaintext conversation key. */
+  signaturePayload?: string;
 }
 
 /**
@@ -124,8 +119,8 @@ export interface DecryptEventsResult {
   messages: DecryptedMessage[];
   /** Extracted conversation keys (for caching). */
   conversationKeys: ConversationKeyResult;
-  /** Errors encountered during decryption (index → error message). */
-  errors: { [index: number]: string };
+  /** Errors encountered during decryption (event index, as a string key → error message). */
+  errors: { [index: string]: string };
 }
 
 /**
@@ -137,7 +132,7 @@ export interface ImageDimensions {
 }
 
 /**
- * Encrypted key for a single recipient (from encryptConversationKeyForRecipients).
+ * Encrypted conversation key for a single participant.
  */
 export interface EncryptedKeyForRecipient {
   userId: string;
@@ -146,7 +141,7 @@ export interface EncryptedKeyForRecipient {
 }
 
 /**
- * A public key input for prepareConversationKeys.
+ * A public key input for prepareConversationKeyChange / prepareGroupMembersChange.
  *
  * Represents a single public key version for a user, as returned by the
  * X API `GET /2/dm/encryption/public_keys` endpoint.
@@ -164,26 +159,209 @@ export interface PublicKeyInput {
 }
 
 /**
- * Result from prepareConversationKeys.
+ * Result from prepareConversationKeyChange / prepareGroupMembersChange.
  *
- * Contains everything needed to POST to the X API for group creation
- * or key initialization — no further transformation required.
+ * Contains everything needed to POST the change to the X API: the new key
+ * (to keep locally), the per-participant encrypted copies, and the action
+ * signature that lets recipients verify the change.
  */
-export interface PreparedConversationKeys {
+export interface PreparedConversationChange {
+  /** Conversation id the change applies to (derived for a one-to-one, or the id you passed). */
+  conversationId: string;
   /** Raw conversation key bytes (32 bytes). Store locally for encrypting messages. */
   conversationKey: Uint8Array;
   /** Timestamp-based version string for this conversation key. */
   conversationKeyVersion: string;
   /** Encrypted keys for each participant, ready to POST to the API. */
   participantKeys: EncryptedKeyForRecipient[];
+  /** Action signatures authenticating the change, ready to POST to the API. */
+  actionSignatures: ActionSignature[];
 }
 
 /**
  * Entity descriptor tuple: [startByteOffset, endByteOffset, entityType].
- * entityType is one of: "url", "mention", "hashtag", "cashtag", "email", "address", "phoneNumber".
+ * entityType is one of: "url", "mention", "hashtag", "cashtag", "email",
+ * "address", "phoneNumber" (the snake_case spelling "phone_number" is
+ * accepted too). Unrecognized entity types are silently dropped — the
+ * message encrypts without that entity and no error is raised.
  */
 export type EntityTuple = [number, number, string];
 
+/**
+ * Parameters for encryptMessage.
+ */
+export interface EncryptMessageParams {
+  /** ID of the message being sent. */
+  messageId: string;
+  /** User ID of the sender. */
+  senderId: string;
+  /** ID of the conversation the message belongs to. */
+  conversationId: string;
+  /** Raw 32-byte conversation key used to encrypt the message content. */
+  conversationKey: Uint8Array;
+  /** The plaintext message text. */
+  text: string;
+  /** Version of the conversation key used for encryption. */
+  conversationKeyVersion: string;
+  /** Version of the signing key used to sign the message. */
+  signingKeyVersion: string;
+  /** Optional rich-text entities (URLs, mentions, etc.) to embed. */
+  entities?: EntityTuple[] | null;
+  /** Optional attachments (posts, URLs, media, etc.) to include in the message. */
+  attachments?: AttachmentDescriptor[] | null;
+  /** Whether to send a push notification. Omitted defaults to true. */
+  shouldNotify?: boolean | null;
+  /** Optional TTL in milliseconds for disappearing messages. */
+  ttlMsec?: number | null;
+}
+
+/**
+ * Parameters for encryptReply.
+ */
+export interface EncryptReplyParams {
+  /** ID of the reply message being sent. */
+  messageId: string;
+  /** User ID of the sender. */
+  senderId: string;
+  /** ID of the conversation the reply belongs to. */
+  conversationId: string;
+  /** Raw 32-byte conversation key used to encrypt the message content. */
+  conversationKey: Uint8Array;
+  /** The plaintext reply text. */
+  text: string;
+  /** Version of the conversation key used for encryption. */
+  conversationKeyVersion: string;
+  /** Version of the signing key used to sign the message. */
+  signingKeyVersion: string;
+  /** The sequenceId of the message being replied to. */
+  replyToSequenceId: string;
+  /**
+   * The sender ID of the message being replied to (for preview).
+   * Prefer a string: snowflake user ids exceed the range where JavaScript
+   * numbers stay exact. Numbers are accepted only while integral and within
+   * `Number.MAX_SAFE_INTEGER`.
+   */
+  replyToSenderId?: string | number | null;
+  /** The text of the message being replied to (for preview). */
+  replyToText?: string | null;
+  /** Optional rich-text entities (URLs, mentions, etc.) to embed in the outgoing message. */
+  entities?: EntityTuple[] | null;
+  /** Optional attachments (posts, URLs, media, etc.) to include in the outgoing message. */
+  attachments?: AttachmentDescriptor[] | null;
+  /** Optional rich-text entities from the original message (for the reply preview). */
+  replyToEntities?: EntityTuple[] | null;
+  /** Optional attachments from the original message (for the reply preview). */
+  replyToAttachments?: AttachmentDescriptor[] | null;
+  /** Whether to send a push notification. Omitted defaults to true. */
+  shouldNotify?: boolean | null;
+  /** Optional TTL in milliseconds for disappearing messages. */
+  ttlMsec?: number | null;
+}
+
+/**
+ * Parameters for encryptAddReaction and encryptRemoveReaction.
+ *
+ * All fields are required; the same params object can be passed to both
+ * methods to add and later remove the same reaction.
+ */
+export interface EncryptReactionParams {
+  /** ID of the reaction message being sent. */
+  messageId: string;
+  /** User ID of the sender. */
+  senderId: string;
+  /** ID of the conversation the reaction belongs to. */
+  conversationId: string;
+  /** Raw 32-byte conversation key used to encrypt the reaction content. */
+  conversationKey: Uint8Array;
+  /** The sequenceId of the message being reacted to. */
+  targetMessageSequenceId: string;
+  /** The reaction emoji. */
+  emoji: string;
+  /** Version of the conversation key used for encryption. */
+  conversationKeyVersion: string;
+  /** Version of the signing key used to sign the message. */
+  signingKeyVersion: string;
+}
+
+/**
+ * Parameters for prepareConversationKeyChange.
+ */
+export interface ConversationKeyChangeParams {
+  /** User ID of the sender signing the change. */
+  senderId: string;
+  /** Version of the signing key used to sign the change. */
+  signingKeyVersion: string;
+  /** Identity public keys for every participant the new key is encrypted for. */
+  publicKeys: PublicKeyInput[];
+  /**
+   * Conversation the change applies to. Omit for a one-to-one (the canonical
+   * id is derived from the two participants); pass the existing id for a
+   * group key rotation.
+   */
+  conversationId?: string | null;
+}
+
+/**
+ * Parameters for prepareGroupMembersChange.
+ *
+ * The current* fields snapshot the group state the change is made against.
+ * An unset optional signs the null sentinel, so every binding produces
+ * identical signed bytes.
+ */
+export interface GroupMembersChangeParams {
+  /** User ID of the sender signing the change. */
+  senderId: string;
+  /** Version of the signing key used to sign the change. */
+  signingKeyVersion: string;
+  /** Identity public keys for every participant of the updated roster. */
+  publicKeys: PublicKeyInput[];
+  /** ID of the group conversation being changed. */
+  conversationId: string;
+  /** User IDs being added to the group. */
+  newMemberIds: string[];
+  /** User IDs of the current members. */
+  currentMemberIds: string[];
+  /** User IDs of the current admins. */
+  currentAdminIds: string[];
+  /** User IDs of members whose join is still pending. */
+  currentPendingMemberIds: string[];
+  /** The group's current title, if set. */
+  currentTitle?: string | null;
+  /** The group's current avatar URL, if set. */
+  currentAvatarUrl?: string | null;
+  /** The group's current message TTL in milliseconds, if set. */
+  currentTtlMsec?: number | null;
+  /** The group's current screen-capture-blocking state; omit when unset. */
+  currentScreenCaptureBlockingEnabled?: boolean | null;
+}
+
+/**
+ * Parameters for prepareGroupCreate.
+ *
+ * An unset optional signs the null sentinel, so every binding produces
+ * identical signed bytes.
+ */
+export interface GroupCreateParams {
+  /** User ID of the sender signing the create. */
+  senderId: string;
+  /** Version of the signing key used to sign the create. */
+  signingKeyVersion: string;
+  /** Identity public keys for every participant of the new group. */
+  publicKeys: PublicKeyInput[];
+  /** ID of the new group conversation (the g-prefixed id minted by the initialize endpoint). */
+  conversationId: string;
+  /** User IDs of the group's members. */
+  memberIds: string[];
+  /** User IDs of the group's admins. */
+  adminIds: string[];
+  /** The group's title, if set. */
+  title?: string | null;
+  /** The group's avatar URL, if set. */
+  avatarUrl?: string | null;
+  /** The group's message TTL in milliseconds, if set. */
+  ttlMsec?: number | null;
+}
+
 // NOTE: AttachmentDescriptor uses snake_case as it's part of the Thrift protocol
 // and matches the wire format used by the X API
 /**
@@ -221,7 +399,12 @@ export interface Event {
   attachments?: AttachmentInfo[];
   /** For message events: media hash keys derived from attachments (if any). */
   mediaHashes?: MediaHashReference[];
-  /** For keyChange events: the new conversation key version (a snowflake/timestamp string). */
+  /**
+   * The conversation key version (a snowflake/timestamp string). On message
+   * events: the version the message and any attached media were encrypted
+   * under — decrypt them with the matching key from the conversationKeys
+   * map. On keyChange events: the new key version introduced by the change.
+   */
   keyVersion?: string;
   /** For keyChange events: encrypted conversation keys, one per participant. */
   participantKeys?: ParticipantKey[];
@@ -231,8 +414,8 @@ export interface Event {
 
 /**
  * Decrypted message content. Permissive convenience shape: `contentType`
- * discriminates which fields are present. For the precisely-typed discriminated
- * union, import `MessageContent` from the package's `./types` entry.
+ * discriminates which fields are present (e.g. `text` on 'text' content,
+ * `emoji`/`targetMessageId` on reactions, `newText` on edits).
  */
 export interface MessageContent {
   /**
@@ -281,9 +464,8 @@ export interface MediaHashReference {
 
 /**
  * An attachment on a decrypted message. Permissive convenience shape: the
- * fields are flattened and `attachmentType` discriminates which apply. For the
- * precisely-typed per-variant union, import `AttachmentInfo` from the package's
- * `./types` entry.
+ * per-variant fields are flattened and `attachmentType` discriminates which
+ * apply ('media', 'url', 'post', 'unifiedCard', or 'money').
  */
 export interface AttachmentInfo {
   /** One of: 'media', 'url', 'post', 'unifiedCard', 'money'. */
@@ -314,7 +496,18 @@ export interface AttachmentInfo {
 export interface CreateChatOptions {
   /** 
    * Juicebox configuration JSON from the X API.
-   * Obtain this from: GET /2/dm/encryption/juicebox/config
+   * Obtain this from the `juicebox_config` field of
+   * GET /2/users/:id/public_keys (your own user, `public_key.fields=juicebox_config`).
+   *
+   * Accepted shapes match the native bindings and are checked in this
+   * order: the `sdk_config` wrapper (its embedded SDK config string is
+   * unwrapped for the Juicebox client), the X API `juicebox_config` object
+   * (its `key_store_token_map_json` string is used verbatim so realm public
+   * keys and server thresholds are preserved), a bare `token_map` array
+   * (converted to a realms config with majority recover threshold — no
+   * realm public keys, so only suitable for realms that don't require
+   * them), or a raw realms config. Realm auth tokens always come from
+   * `getAuthToken`, not the config.
    */
   juiceboxConfig: string;
   
@@ -335,11 +528,52 @@ export interface CreateChatOptions {
   getAuthToken: (realmId: string) => Promise<string>;
 
   /**
-   * Optional number of PIN guesses allowed before lockout.
+   * Optional override for the number of PIN guesses allowed before lockout.
+   * A non-negative integer wins over the config, including across later
+   * `updateConfig()` calls. When omitted, the config's `max_guess_count`
+   * applies when it is a non-negative integer (0 included), defaulting to
+   * 20 for the `sdk_config` and `key_store_token_map_json` shapes and 5
+   * otherwise.
    */
   maxGuessCount?: number;
 }
 
+/**
+ * Incremental stream encryptor for large payloads.
+ *
+ * Feed plaintext with `push`; call `finish` once to emit the final frame.
+ * `finish()` consumes and frees the WASM object — do not call `free()` after
+ * it (doing so throws). Call `free()` only when abandoning a stream without
+ * finishing it.
+ */
+export declare class StreamEncryptor {
+  /** Encrypt a plaintext chunk, returning ciphertext available so far. */
+  push(plaintext: Uint8Array): Uint8Array;
+  /** Emit the final frame; consumes and frees the encryptor. */
+  finish(): Uint8Array;
+  /** Release the underlying WASM object when abandoning an unfinished stream. */
+  free(): void;
+}
+
+/**
+ * Incremental stream decryptor for large payloads.
+ *
+ * Feed ciphertext with `push`; call `finish` once at end of input. `finish`
+ * throws if the stream ended before its final frame (truncation), so do not
+ * treat plaintext from `push` as complete until `finish` succeeds.
+ * `finish()` consumes and frees the WASM object — do not call `free()` after
+ * it (doing so throws). Call `free()` only when abandoning a stream without
+ * finishing it.
+ */
+export declare class StreamDecryptor {
+  /** Decrypt a ciphertext chunk, returning plaintext available so far. */
+  push(ciphertext: Uint8Array): Uint8Array;
+  /** Decrypt the final frame; consumes and frees the decryptor. */
+  finish(): Uint8Array;
+  /** Release the underlying WASM object when abandoning an unfinished stream. */
+  free(): void;
+}
+
 /**
  * Common interface for all Chat methods (shared by Chat and ChatWithJuicebox).
  *
@@ -347,12 +581,19 @@ export interface CreateChatOptions {
  * `ChatWithJuicebox` (returned by `createChat()`) adds Juicebox lifecycle methods.
  */
 interface ChatCrypto {
-  /** When enabled, `decryptEvent` throws for unverified messages. */
+  /**
+   * When enabled — the default — `decryptEvent` throws for any signed event
+   * whose signature cannot be verified (invalid, missing, or no matching
+   * signing key) instead of returning it with `verified: false`.
+   */
   setRejectUnverified(reject: boolean): void;
 
   /** Generate new keypairs and return the registration payload. */
   generateKeypairs(): PublicKeyRegistrationPayload;
 
+  /** Set the registered public key version (call after unlock()). */
+  setKeyVersion(version: string): void;
+
   /** Get current public keys. */
   getPublicKeys(): PublicKeys;
 
@@ -371,9 +612,6 @@ interface ChatCrypto {
   /** Decrypt an encrypted conversation key (ECIES). */
   decryptConversationKey(encryptedKeyB64: string): Uint8Array;
 
-  /** Generate a new conversation key. */
-  generateConversationKey(): Uint8Array;
-
   /** Extract and decrypt conversation keys from raw KeyChange event strings. */
   extractConversationKeys(events: string[]): ConversationKeyResult;
 
@@ -386,12 +624,22 @@ interface ChatCrypto {
    * 3. Decrypts the message using the appropriate conversation key
    *
    * @param events - Raw base64-encoded event strings from the webhook
-   * @param signingKeys - All known signing keys for all participants (with userId)
+   * @param signingKeys - All known signing keys for all participants (with
+   * userId). Under the default reject-unverified policy, omitting this makes
+   * every signed event land in `errors`; only after
+   * `setRejectUnverified(false)` are such events returned with
+   * `verified: false`.
    */
   decryptEvents(events: string[], signingKeys?: SigningKeyEntry[]): DecryptEventsResult;
 
-  /** Decrypt a raw webhook event payload. */
-  decryptEvent(eventB64: string, conversationKeys: ConversationKeyMap, signingKeys?: SigningKeyEntry[]): Event;
+  /**
+   * Decrypt a raw webhook event payload.
+   *
+   * Under the default reject-unverified policy, omitting `signingKeys` makes
+   * every signed event throw; only after `setRejectUnverified(false)` are
+   * such events returned with `verified: false`.
+   */
+  decryptEvent(eventB64: string, conversationKeys?: ConversationKeyMap | null, signingKeys?: SigningKeyEntry[]): Event;
 
   /** Sign data. Returns raw signature bytes (64 bytes). */
   sign(data: Uint8Array): Uint8Array;
@@ -399,17 +647,20 @@ interface ChatCrypto {
   /** Verify a signature. */
   verify(publicKeyB64: string, signature: Uint8Array, data: Uint8Array): boolean;
 
+  /** Verify that an identity key signed a signing key (key binding). */
+  verifyKeyBinding(identityPublicKeyB64: string, signingPublicKeyB64: string, identityPublicKeySignatureB64: string): boolean;
+
   /** Encrypt a text message. */
-  encryptMessage(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
+  encryptMessage(params: EncryptMessageParams): SendPayload;
 
   /** Encrypt a reply. */
-  encryptReply(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, replyToSequenceId: string, replyToSenderId?: number | null, replyToText?: string | null, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, replyToEntities?: EntityTuple[] | null, replyToAttachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
+  encryptReply(params: EncryptReplyParams): SendPayload;
 
   /** Encrypt a reaction-add. */
-  encryptAddReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
+  encryptAddReaction(params: EncryptReactionParams): SendPayload;
 
   /** Encrypt a reaction-remove. */
-  encryptRemoveReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
+  encryptRemoveReaction(params: EncryptReactionParams): SendPayload;
 
   /** Encrypt a stream (e.g. media). */
   encryptStream(plaintext: Uint8Array, conversationKey: Uint8Array): Uint8Array;
@@ -417,33 +668,59 @@ interface ChatCrypto {
   /** Decrypt a streaming-encrypted payload (e.g. media). */
   decryptStream(encrypted: Uint8Array, conversationKey: Uint8Array): Uint8Array;
 
+  /** Create an incremental stream encryptor for large payloads. */
+  streamEncryptor(conversationKey: Uint8Array): StreamEncryptor;
+
+  /** Create an incremental stream decryptor for large payloads. */
+  streamDecryptor(conversationKey: Uint8Array): StreamDecryptor;
+
   /** Encrypt a UTF-8 string and return base64 ciphertext. Use for metadata fields like group names. */
   encrypt(plaintext: string, conversationKey: Uint8Array): string;
 
   /** Decrypt a base64-encoded ciphertext and return the UTF-8 plaintext. Use for metadata fields like group names. */
   decrypt(ciphertextB64: string, conversationKey: Uint8Array): string;
 
-  /** Encrypt a conversation key for one or more recipients. */
-  encryptConversationKeyForRecipients(conversationKey: Uint8Array, recipients: RecipientInput[]): EncryptedKeyForRecipient[];
-
   /**
-   * Prepare conversation keys for all participants in one call.
+   * Prepare a signed conversation-key change, ready to send to the X API.
    *
-   * This is the recommended method for both group creation and key
-   * initialization. Pass the flat array of public keys from the X API;
-   * the SDK groups by userId, picks the latest version per user,
-   * generates a fresh conversation key, and encrypts it for everyone.
+   * Use this to start a one-to-one or rotate an existing conversation's key
+   * (one-to-one or group). Creating a group or adding members requires a
+   * paired group signature as well — use prepareGroupCreate or
+   * prepareGroupMembersChange for those.
    *
-   * @param publicKeys - Array of PublicKeyInput from the X API
-   * @returns PreparedConversationKeys ready to POST to the API
+   * Pass the flat array of public keys (self plus recipients) from the X API
+   * in params.publicKeys. Omit params.conversationId for a one-to-one (it is
+   * derived from the two participants); pass the existing id for a group key
+   * rotation.
+   *
+   * @returns PreparedConversationChange ready to POST to the API
    */
-  prepareConversationKeys(publicKeys: PublicKeyInput[]): PreparedConversationKeys;
+  prepareConversationKeyChange(params: ConversationKeyChangeParams): PreparedConversationChange;
 
-  /** Build and sign a GroupMemberAdd action signature. */
-  signAddMembers(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, newMemberIds: string[], currentMemberIds: string[], currentAdminIds: string[], currentPendingMemberIds: string[], conversationKeyVersion: string, currentTitle?: string | null, currentAvatarUrl?: string | null, currentTtlMsec?: number | null): ActionSignature;
+  /**
+   * Prepare a signed group member-add change, ready to send to the X API.
+   *
+   * Use this when adding members to an existing group. Creating the group is
+   * prepareGroupCreate; a key rotation without a roster change is
+   * prepareConversationKeyChange.
+   *
+   * @returns PreparedConversationChange with two action signatures: the
+   * conversation-key change and the member add
+   */
+  prepareGroupMembersChange(params: GroupMembersChangeParams): PreparedConversationChange;
 
-  /** Build and sign a ConversationKeyChange action signature. */
-  signKeyChange(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, conversationKeyVersion: string, conversationKey: Uint8Array): ActionSignature;
+  /**
+   * Prepare a signed group create, ready to send to the X API.
+   *
+   * Use this once, when creating a group (conversationId is the g-prefixed id
+   * minted by the initialize endpoint). Later key rotations use
+   * prepareConversationKeyChange; roster additions use
+   * prepareGroupMembersChange.
+   *
+   * @returns PreparedConversationChange with two action signatures: the
+   * conversation-key change and the group create
+   */
+  prepareGroupCreate(params: GroupCreateParams): PreparedConversationChange;
 }
 
 /** Internal crypto engine wrapped by ChatWithJuicebox. Not part of the public API. */
@@ -460,25 +737,25 @@ declare class Chat implements ChatCrypto {
   hasIdentityKey(): boolean;
   lock(): void;
   decryptConversationKey(encryptedKeyB64: string): Uint8Array;
-  generateConversationKey(): Uint8Array;
   extractConversationKeys(events: string[]): ConversationKeyResult;
   decryptEvents(events: string[], signingKeys?: SigningKeyEntry[]): DecryptEventsResult;
-  decryptEvent(eventB64: string, conversationKeys: ConversationKeyMap, signingKeys?: SigningKeyEntry[]): Event;
+  decryptEvent(eventB64: string, conversationKeys?: ConversationKeyMap | null, signingKeys?: SigningKeyEntry[]): Event;
   sign(data: Uint8Array): Uint8Array;
   verify(publicKeyB64: string, signature: Uint8Array, data: Uint8Array): boolean;
   verifyKeyBinding(identityPublicKeyB64: string, signingPublicKeyB64: string, identityPublicKeySignatureB64: string): boolean;
-  encryptMessage(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
-  encryptReply(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, replyToSequenceId: string, replyToSenderId?: number | null, replyToText?: string | null, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, replyToEntities?: EntityTuple[] | null, replyToAttachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
-  encryptAddReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
-  encryptRemoveReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
+  encryptMessage(params: EncryptMessageParams): SendPayload;
+  encryptReply(params: EncryptReplyParams): SendPayload;
+  encryptAddReaction(params: EncryptReactionParams): SendPayload;
+  encryptRemoveReaction(params: EncryptReactionParams): SendPayload;
   encryptStream(plaintext: Uint8Array, conversationKey: Uint8Array): Uint8Array;
   decryptStream(encrypted: Uint8Array, conversationKey: Uint8Array): Uint8Array;
+  streamEncryptor(conversationKey: Uint8Array): StreamEncryptor;
+  streamDecryptor(conversationKey: Uint8Array): StreamDecryptor;
   encrypt(plaintext: string, conversationKey: Uint8Array): string;
   decrypt(ciphertextB64: string, conversationKey: Uint8Array): string;
-  encryptConversationKeyForRecipients(conversationKey: Uint8Array, recipients: RecipientInput[]): EncryptedKeyForRecipient[];
-  prepareConversationKeys(publicKeys: PublicKeyInput[]): PreparedConversationKeys;
-  signAddMembers(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, newMemberIds: string[], currentMemberIds: string[], currentAdminIds: string[], currentPendingMemberIds: string[], conversationKeyVersion: string, currentTitle?: string | null, currentAvatarUrl?: string | null, currentTtlMsec?: number | null): ActionSignature;
-  signKeyChange(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, conversationKeyVersion: string, conversationKey: Uint8Array): ActionSignature;
+  prepareConversationKeyChange(params: ConversationKeyChangeParams): PreparedConversationChange;
+  prepareGroupMembersChange(params: GroupMembersChangeParams): PreparedConversationChange;
+  prepareGroupCreate(params: GroupCreateParams): PreparedConversationChange;
 }
 
 /**
@@ -497,6 +774,11 @@ export declare class ChatWithJuicebox implements ChatCrypto {
   delete(): Promise<void>;
   /** The new PIN must meet the same strength requirements as setup(). */
   changePin(oldPin: string | Uint8Array, newPin: string | Uint8Array): Promise<void>;
+  /**
+   * Re-create the Juicebox client from a new config (e.g. refreshed auth
+   * tokens) and re-resolve the PIN guess budget from it; an explicit
+   * createChat `maxGuessCount` override keeps winning.
+   */
   updateConfig(juiceboxConfig: string): void;
 
   setRejectUnverified(reject: boolean): void;
@@ -509,31 +791,43 @@ export declare class ChatWithJuicebox implements ChatCrypto {
   hasIdentityKey(): boolean;
   lock(): void;
   decryptConversationKey(encryptedKeyB64: string): Uint8Array;
-  generateConversationKey(): Uint8Array;
   extractConversationKeys(events: string[]): ConversationKeyResult;
   decryptEvents(events: string[], signingKeys?: SigningKeyEntry[]): DecryptEventsResult;
-  decryptEvent(eventB64: string, conversationKeys: ConversationKeyMap, signingKeys?: SigningKeyEntry[]): Event;
+  decryptEvent(eventB64: string, conversationKeys?: ConversationKeyMap | null, signingKeys?: SigningKeyEntry[]): Event;
   sign(data: Uint8Array): Uint8Array;
   verify(publicKeyB64: string, signature: Uint8Array, data: Uint8Array): boolean;
   verifyKeyBinding(identityPublicKeyB64: string, signingPublicKeyB64: string, identityPublicKeySignatureB64: string): boolean;
-  encryptMessage(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
-  encryptReply(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, text: string, conversationKeyVersion: string, signingKeyVersion: string, replyToSequenceId: string, replyToSenderId?: number | null, replyToText?: string | null, entities?: EntityTuple[] | null, attachments?: AttachmentDescriptor[] | null, replyToEntities?: EntityTuple[] | null, replyToAttachments?: AttachmentDescriptor[] | null, shouldNotify?: boolean | null, ttlMsec?: number | null): SendPayload;
-  encryptAddReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
-  encryptRemoveReaction(messageId: string, senderId: string, conversationId: string, conversationKey: Uint8Array, targetMessageSequenceId: string, emoji: string, conversationKeyVersion: string, signingKeyVersion: string): SendPayload;
+  encryptMessage(params: EncryptMessageParams): SendPayload;
+  encryptReply(params: EncryptReplyParams): SendPayload;
+  encryptAddReaction(params: EncryptReactionParams): SendPayload;
+  encryptRemoveReaction(params: EncryptReactionParams): SendPayload;
   encryptStream(plaintext: Uint8Array, conversationKey: Uint8Array): Uint8Array;
   decryptStream(encrypted: Uint8Array, conversationKey: Uint8Array): Uint8Array;
+  streamEncryptor(conversationKey: Uint8Array): StreamEncryptor;
+  streamDecryptor(conversationKey: Uint8Array): StreamDecryptor;
   encrypt(plaintext: string, conversationKey: Uint8Array): string;
   decrypt(ciphertextB64: string, conversationKey: Uint8Array): string;
-  encryptConversationKeyForRecipients(conversationKey: Uint8Array, recipients: RecipientInput[]): EncryptedKeyForRecipient[];
-  prepareConversationKeys(publicKeys: PublicKeyInput[]): PreparedConversationKeys;
-  signAddMembers(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, newMemberIds: string[], currentMemberIds: string[], currentAdminIds: string[], currentPendingMemberIds: string[], conversationKeyVersion: string, currentTitle?: string | null, currentAvatarUrl?: string | null, currentTtlMsec?: number | null): ActionSignature;
-  signKeyChange(publicKeyVersion: string, messageId: string, senderId: string, conversationId: string, conversationKeyVersion: string, conversationKey: Uint8Array): ActionSignature;
+  prepareConversationKeyChange(params: ConversationKeyChangeParams): PreparedConversationChange;
+  prepareGroupMembersChange(params: GroupMembersChangeParams): PreparedConversationChange;
+  prepareGroupCreate(params: GroupCreateParams): PreparedConversationChange;
+
+  /**
+   * Release the WASM-side crypto engine: clears key material (`lock()`) and
+   * frees the underlying WASM object. The instance must not be used
+   * afterwards. When reusing the instance, `lock()` alone suffices for key
+   * hygiene.
+   */
+  free(): void;
 }
 
 /**
  * Create a Chat instance with integrated Juicebox key storage.
  *
  * Each call creates an independent instance with its own Juicebox client.
+ * The Juicebox auth-token callback is a process-wide global that each
+ * instance re-arms before its own operations, so sequential use of multiple
+ * instances is fine but concurrent Juicebox operations across instances in
+ * one process are not supported.
  */
 export declare function createChat(options: CreateChatOptions): Promise<ChatWithJuicebox>;