@xmtp/browser-sdk 1.1.4 → 2.0.1

package/src/Conversation.ts

@@ -11,20 +11,28 @@ import type {
   SafeMessage,
 } from "@/utils/conversions";
 import { nsToDate } from "@/utils/date";
+import { MissingContentTypeError } from "@/utils/errors";
 
+/**
+ * Represents a conversation
+ *
+ * This class is not intended to be initialized directly.
+ */
 export class Conversation {
+  #addedByInboxId?: SafeConversation["addedByInboxId"];
   #client: Client;
-
+  #createdAtNs?: SafeConversation["createdAtNs"];
   #id: string;
-
   #isActive?: SafeConversation["isActive"];
-
-  #addedByInboxId?: SafeConversation["addedByInboxId"];
-
   #metadata?: SafeConversation["metadata"];
 
-  #createdAtNs?: SafeConversation["createdAtNs"];
-
+  /**
+   * Creates a new conversation instance
+   *
+   * @param client - The client instance managing the conversation
+   * @param id - The unique identifier for this conversation
+   * @param data - Optional conversation data to initialize with
+   */
   constructor(client: Client, id: string, data?: SafeConversation) {
     this.#client = client;
     this.#id = id;
@@ -62,12 +70,22 @@ export class Conversation {
     return this.#metadata;
   }
 
+  /**
+   * Gets the conversation members
+   *
+   * @returns Promise that resolves with the conversation members
+   */
   async members() {
     return this.#client.sendMessage("getGroupMembers", {
       id: this.#id,
     });
   }
 
+  /**
+   * Synchronizes conversation data from the network
+   *
+   * @returns Promise that resolves with the updated conversation data
+   */
   async sync() {
     const data = await this.#client.sendMessage("syncGroup", {
       id: this.#id,
@@ -76,17 +94,28 @@ export class Conversation {
     return data;
   }
 
+  /**
+   * Publishes pending messages that were sent optimistically
+   *
+   * @returns Promise that resolves when publishing is complete
+   */
   async publishMessages() {
     return this.#client.sendMessage("publishGroupMessages", {
       id: this.#id,
     });
   }
 
+  /**
+   * Sends a message optimistically
+   *
+   * @param content - The content to send
+   * @param contentType - Optional content type of the message content
+   * @returns Promise that resolves with the message ID
+   * @throws {MissingContentTypeError} When content type is required but not provided
+   */
   async sendOptimistic(content: any, contentType?: ContentTypeId) {
     if (typeof content !== "string" && !contentType) {
-      throw new Error(
-        "Content type is required when sending content other than text",
-      );
+      throw new MissingContentTypeError();
     }
 
     const safeEncodedContent =
@@ -101,11 +130,17 @@ export class Conversation {
     });
   }
 
+  /**
+   * Sends a message
+   *
+   * @param content - The content to send
+   * @param contentType - Optional content type of the message content
+   * @returns Promise that resolves with the message ID after it has been sent
+   * @throws {MissingContentTypeError} When content type is required but not provided
+   */
   async send(content: any, contentType?: ContentTypeId) {
     if (typeof content !== "string" && !contentType) {
-      throw new Error(
-        "Content type is required when sending content other than text",
-      );
+      throw new MissingContentTypeError();
     }
 
     const safeEncodedContent =
@@ -120,6 +155,12 @@ export class Conversation {
     });
   }
 
+  /**
+   * Lists messages in this conversation
+   *
+   * @param options - Optional filtering and pagination options
+   * @returns Promise that resolves with an array of decoded messages
+   */
   async messages(options?: SafeListMessagesOptions) {
     const messages = await this.#client.sendMessage("getGroupMessages", {
       id: this.#id,
@@ -129,12 +170,23 @@ export class Conversation {
     return messages.map((message) => new DecodedMessage(this.#client, message));
   }
 
+  /**
+   * Gets the consent state for this conversation
+   *
+   * @returns Promise that resolves with the current consent state
+   */
   async consentState() {
     return this.#client.sendMessage("getGroupConsentState", {
       id: this.#id,
     });
   }
 
+  /**
+   * Updates the consent state for this conversation
+   *
+   * @param state - The new consent state to set
+   * @returns Promise that resolves when the update is complete
+   */
   async updateConsentState(state: ConsentState) {
     return this.#client.sendMessage("updateGroupConsentState", {
       id: this.#id,
@@ -142,12 +194,24 @@ export class Conversation {
     });
   }
 
+  /**
+   * Gets the message disappearing settings for this conversation
+   *
+   * @returns Promise that resolves with the current message disappearing settings
+   */
   async messageDisappearingSettings() {
     return this.#client.sendMessage("getGroupMessageDisappearingSettings", {
       id: this.#id,
     });
   }
 
+  /**
+   * Updates message disappearing settings for this conversation
+   *
+   * @param fromNs - The timestamp from which messages should start disappearing
+   * @param inNs - The duration after which messages should disappear
+   * @returns Promise that resolves when the update is complete
+   */
   async updateMessageDisappearingSettings(fromNs: bigint, inNs: bigint) {
     return this.#client.sendMessage("updateGroupMessageDisappearingSettings", {
       id: this.#id,
@@ -156,18 +220,34 @@ export class Conversation {
     });
   }
 
+  /**
+   * Removes message disappearing settings from this conversation
+   *
+   * @returns Promise that resolves when the settings are removed
+   */
   async removeMessageDisappearingSettings() {
     return this.#client.sendMessage("removeGroupMessageDisappearingSettings", {
       id: this.#id,
     });
   }
 
+  /**
+   * Checks if message disappearing is enabled for this conversation
+   *
+   * @returns Promise that resolves with whether message disappearing is enabled
+   */
   async isMessageDisappearingEnabled() {
     return this.#client.sendMessage("isGroupMessageDisappearingEnabled", {
       id: this.#id,
     });
   }
 
+  /**
+   * Creates a stream for new messages in this conversation
+   *
+   * @param callback - Optional callback function for handling new stream values
+   * @returns AsyncStream instance for new messages
+   */
   async stream(callback?: StreamCallback<DecodedMessage>) {
     const streamId = v4();
     const asyncStream = new AsyncStream<DecodedMessage>();
@@ -205,4 +285,15 @@ export class Conversation {
       id: this.#id,
     });
   }
+
+  /**
+   * Retrieves HMAC keys for this conversation
+   *
+   * @returns Promise that resolves with the HMAC keys
+   */
+  async getHmacKeys() {
+    return this.#client.sendMessage("getGroupHmacKeys", {
+      id: this.#id,
+    });
+  }
 }

package/src/Conversations.ts

@@ -17,23 +17,52 @@ import type {
   SafeMessage,
 } from "@/utils/conversions";
 
+/**
+ * Manages conversations
+ *
+ * This class is not intended to be initialized directly.
+ */
 export class Conversations {
   #client: Client;
 
+  /**
+   * Creates a new conversations instance
+   *
+   * @param client - The client instance managing the conversations
+   */
   constructor(client: Client) {
     this.#client = client;
   }
 
+  /**
+   * Synchronizes conversations for the current client from the network
+   *
+   * @returns Promise that resolves when sync is complete
+   */
   async sync() {
     return this.#client.sendMessage("syncConversations", undefined);
   }
 
+  /**
+   * Synchronizes all conversations and messages from the network with optional
+   * consent state filtering, then uploads conversation and message history to
+   * the history sync server
+   *
+   * @param consentStates - Optional array of consent states to filter by
+   * @returns Promise that resolves when sync is complete
+   */
   async syncAll(consentStates?: ConsentState[]) {
     return this.#client.sendMessage("syncAllConversations", {
       consentStates,
     });
   }
 
+  /**
+   * Retrieves a conversation by its ID
+   *
+   * @param id - The conversation ID to look up
+   * @returns Promise that resolves with the conversation, if found
+   */
   async getConversationById(id: string) {
     const data = await this.#client.sendMessage("getConversationById", {
       id,
@@ -46,6 +75,12 @@ export class Conversations {
     return undefined;
   }
 
+  /**
+   * Retrieves a message by its ID
+   *
+   * @param id - The message ID to look up
+   * @returns Promise that resolves with the decoded message, if found
+   */
   async getMessageById(id: string) {
     const data = await this.#client.sendMessage("getMessageById", {
       id,
@@ -53,6 +88,12 @@ export class Conversations {
     return data ? new DecodedMessage(this.#client, data) : undefined;
   }
 
+  /**
+   * Retrieves a DM by inbox ID
+   *
+   * @param inboxId - The inbox ID to look up
+   * @returns Promise that resolves with the DM, if found
+   */
   async getDmByInboxId(inboxId: string) {
     const data = await this.#client.sendMessage("getDmByInboxId", {
       inboxId,
@@ -60,6 +101,12 @@ export class Conversations {
     return data ? new Dm(this.#client, data.id, data) : undefined;
   }
 
+  /**
+   * Lists all conversations with optional filtering
+   *
+   * @param options - Optional filtering and pagination options
+   * @returns Promise that resolves with an array of conversations
+   */
   async list(options?: SafeListConversationsOptions) {
     const conversations = await this.#client.sendMessage("getConversations", {
       options,
@@ -72,6 +119,12 @@ export class Conversations {
     );
   }
 
+  /**
+   * Lists all group conversations with optional filtering
+   *
+   * @param options - Optional filtering and pagination options
+   * @returns Promise that resolves with an array of groups
+   */
   async listGroups(
     options?: Omit<SafeListConversationsOptions, "conversation_type">,
   ) {
@@ -84,6 +137,12 @@ export class Conversations {
     );
   }
 
+  /**
+   * Lists all DM conversations with optional filtering
+   *
+   * @param options - Optional filtering and pagination options
+   * @returns Promise that resolves with an array of DMs
+   */
   async listDms(
     options?: Omit<SafeListConversationsOptions, "conversation_type">,
   ) {
@@ -96,6 +155,13 @@ export class Conversations {
     );
   }
 
+  /**
+   * Creates a new group conversation with the specified identifiers
+   *
+   * @param identifiers - Array of identifiers for group members
+   * @param options - Optional group creation options
+   * @returns Promise that resolves with the new group
+   */
   async newGroupWithIdentifiers(
     identifiers: Identifier[],
     options?: SafeCreateGroupOptions,
@@ -111,6 +177,13 @@ export class Conversations {
     return new Group(this.#client, conversation.id, conversation);
   }
 
+  /**
+   * Creates a new group conversation with the specified inbox IDs
+   *
+   * @param inboxIds - Array of inbox IDs for group members
+   * @param options - Optional group creation options
+   * @returns Promise that resolves with the new group
+   */
   async newGroup(inboxIds: string[], options?: SafeCreateGroupOptions) {
     const conversation = await this.#client.sendMessage(
       "newGroupWithInboxIds",
@@ -123,6 +196,13 @@ export class Conversations {
     return new Group(this.#client, conversation.id, conversation);
   }
 
+  /**
+   * Creates a new DM conversation with the specified identifier
+   *
+   * @param identifier - Identifier for the DM recipient
+   * @param options - Optional DM creation options
+   * @returns Promise that resolves with the new DM
+   */
   async newDmWithIdentifier(
     identifier: Identifier,
     options?: SafeCreateDmOptions,
@@ -135,6 +215,13 @@ export class Conversations {
     return new Dm(this.#client, conversation.id, conversation);
   }
 
+  /**
+   * Creates a new DM conversation with the specified inbox ID
+   *
+   * @param inboxId - Inbox ID for the DM recipient
+   * @param options - Optional DM creation options
+   * @returns Promise that resolves with the new DM
+   */
   async newDm(inboxId: string, options?: SafeCreateDmOptions) {
     const conversation = await this.#client.sendMessage("newDmWithInboxId", {
       inboxId,
@@ -144,10 +231,22 @@ export class Conversations {
     return new Dm(this.#client, conversation.id, conversation);
   }
 
+  /**
+   * Retrieves HMAC keys for all conversations
+   *
+   * @returns Promise that resolves with the HMAC keys for all conversations
+   */
   async getHmacKeys() {
     return this.#client.sendMessage("getHmacKeys", undefined);
   }
 
+  /**
+   * Creates a stream for new conversations
+   *
+   * @param callback - Optional callback function for handling new stream value
+   * @param conversationType - Optional type to filter conversations
+   * @returns AsyncStream instance for new conversations
+   */
   async stream<T extends Group | Dm = Group | Dm>(
     callback?: StreamCallback<T>,
     conversationType?: ConversationType,
@@ -189,14 +288,33 @@ export class Conversations {
     return asyncStream;
   }
 
+  /**
+   * Creates a stream for new group conversations
+   *
+   * @param callback - Optional callback function for handling new stream value
+   * @returns AsyncStream instance for new group conversations
+   */
   async streamGroups(callback?: StreamCallback<Group>) {
     return this.stream<Group>(callback, ConversationType.Group);
   }
 
+  /**
+   * Creates a stream for new DM conversations
+   *
+   * @param callback - Optional callback function for handling new stream value
+   * @returns AsyncStream instance for new DM conversations
+   */
   async streamDms(callback?: StreamCallback<Dm>) {
     return this.stream<Dm>(callback, ConversationType.Dm);
   }
 
+  /**
+   * Creates a stream for all new messages
+   *
+   * @param callback - Optional callback function for handling new stream value
+   * @param conversationType - Optional conversation type to filter messages
+   * @returns AsyncStream instance for new messages
+   */
   async streamAllMessages(
     callback?: StreamCallback<DecodedMessage>,
     conversationType?: ConversationType,
@@ -232,10 +350,22 @@ export class Conversations {
     return asyncStream;
   }
 
+  /**
+   * Creates a stream for all new group messages
+   *
+   * @param callback - Optional callback function for handling new stream value
+   * @returns AsyncStream instance for new group messages
+   */
   async streamAllGroupMessages(callback?: StreamCallback<DecodedMessage>) {
     return this.streamAllMessages(callback, ConversationType.Group);
   }
 
+  /**
+   * Creates a stream for all new DM messages
+   *
+   * @param callback - Optional callback function for handling new stream value
+   * @returns AsyncStream instance for new DM messages
+   */
   async streamAllDmMessages(callback?: StreamCallback<DecodedMessage>) {
     return this.streamAllMessages(callback, ConversationType.Dm);
   }

package/src/DecodedMessage.ts

@@ -6,31 +6,39 @@ import { fromSafeContentTypeId, type SafeMessage } from "@/utils/conversions";
 export type MessageKind = "application" | "membership_change";
 export type MessageDeliveryStatus = "unpublished" | "published" | "failed";
 
+/**
+ * Represents a decoded XMTP message
+ *
+ * This class transforms network messages into a structured format with
+ * content decoding.
+ *
+ * @class
+ * @property {any} content - The decoded content of the message
+ * @property {ContentTypeId} contentType - The content type of the message content
+ * @property {string} conversationId - Unique identifier for the conversation
+ * @property {MessageDeliveryStatus} deliveryStatus - Current delivery status of the message ("unpublished" | "published" | "failed")
+ * @property {string} [fallback] - Optional fallback text for the message
+ * @property {number} [compression] - Optional compression level applied to the message
+ * @property {string} id - Unique identifier for the message
+ * @property {MessageKind} kind - Type of message ("application" | "membership_change")
+ * @property {Map<string, string>} parameters - Additional parameters associated with the message
+ * @property {SafeMessage["content"]} encodedContent - Raw encoded content of the message
+ * @property {string} senderInboxId - Identifier for the sender's inbox
+ * @property {bigint} sentAtNs - Timestamp when the message was sent (in nanoseconds)
+ */
 export class DecodedMessage {
   #client: Client;
-
   content: any;
-
   contentType: ContentTypeId;
-
   conversationId: string;
-
   deliveryStatus: MessageDeliveryStatus;
-
   fallback?: string;
-
   compression?: number;
-
   id: string;
-
   kind: MessageKind;
-
   parameters: Map<string, string>;
-
   encodedContent: SafeMessage["content"];
-
   senderInboxId: string;
-
   sentAtNs: bigint;
 
   constructor(client: Client, message: SafeMessage) {

package/src/Dm.ts

@@ -2,17 +2,33 @@ import type { Client } from "@/Client";
 import { Conversation } from "@/Conversation";
 import type { SafeConversation } from "@/utils/conversions";
 
+/**
+ * Represents a direct message conversation between two inboxes
+ *
+ * This class is not intended to be initialized directly.
+ */
 export class Dm extends Conversation {
   #client: Client;
-
   #id: string;
 
+  /**
+   * Creates a new direct message conversation instance
+   *
+   * @param client - The client instance managing this direct message conversation
+   * @param id - Identifier for the direct message conversation
+   * @param data - Optional conversation data to initialize with
+   */
   constructor(client: Client, id: string, data?: SafeConversation) {
     super(client, id, data);
     this.#client = client;
     this.#id = id;
   }
 
+  /**
+   * Retrieves the inbox ID of the other participant in the DM
+   *
+   * @returns Promise that resolves with the peer's inbox ID
+   */
   async peerInboxId() {
     return this.#client.sendMessage("getDmPeerInboxId", {
       id: this.#id,