add Conversation documentation

src/lib/Conversation.ts

@@ -36,7 +36,18 @@ export class Conversation {
     );
   }
 
-  // TODO: Support pagination and conversation ID here
+/**
+ * Lists messages in a conversation with optional filters.
+ *
+ * @param {number} limit - Optional limit to the number of messages to return.
+ * @param {number | Date} before - Optional timestamp to filter messages before.
+ * @param {number | Date} after - Optional timestamp to filter messages after.
+ * @param {"SORT_DIRECTION_ASCENDING" | "SORT_DIRECTION_DESCENDING"} direction - Optional sorting direction for messages.
+ * @returns {Promise<DecodedMessage[]>} A Promise that resolves to an array of decoded messages.
+ * @throws {Error} Throws an error if there is an issue with listing messages.
+ *
+ * @todo Support pagination and conversation ID in future implementations.
+ */
   async messages(
     limit?: number | undefined,
     before?: number | Date | undefined,
@@ -58,7 +69,15 @@ export class Conversation {
     }
   }
 
-  // TODO: support conversation ID
+  /**
+   * Sends a message to the current conversation.
+   *
+   * @param {string | MessageContent} content - The content of the message. It can be either a string or a structured MessageContent object.
+   * @returns {Promise<string>} A Promise that resolves to a string identifier for the sent message.
+   * @throws {Error} Throws an error if there is an issue with sending the message.
+   *
+   * @todo Support specifying a conversation ID in future implementations.
+   */
   async send(content: string | MessageContent): Promise<string> {
     try {
       if (typeof content === "string") {
@@ -71,15 +90,21 @@ export class Conversation {
     }
   }
 
-  // Prepare the message to be sent.
-  //
-  // Instead of immediately `.send`ing a message, you can `.prepare` it first.
-  // This yields a `PreparedLocalMessage` object, which you can send later.
-  // This is useful to help construct a robust pending-message queue
-  // that can survive connectivity outages and app restarts.
-  //
-  // Note: the sendPreparedMessage() method is available on both this `Conversation`
-  //       or the top-level `Client` (when you don't have the `Conversation` handy).
+  /**
+   * Prepares a message to be sent, yielding a `PreparedLocalMessage` object.
+   *
+   * Instead of immediately sending a message, you can prepare it first using this method.
+   * This yields a `PreparedLocalMessage` object, which you can send later.
+   * This is useful to help construct a robust pending-message queue
+   * that can survive connectivity outages and app restarts.
+   *
+   * Note: the {@linkcode Conversation.sendPreparedMessage | sendPreparedMessage} method is available on both this {@linkcode Conversation}
+   *       or the top-level `Client` (when you don't have the `Conversation` handy).
+   *
+   * @param {string | MessageContent} content - The content of the message. It can be either a string or a structured MessageContent object.
+   * @returns {Promise<PreparedLocalMessage>} A Promise that resolves to a `PreparedLocalMessage` object.
+   * @throws {Error} Throws an error if there is an issue with preparing the message.
+   */
   async prepareMessage(content: string | MessageContent): Promise<PreparedLocalMessage> {
     try {
       if (typeof content === "string") {
@@ -92,6 +117,16 @@ export class Conversation {
     }
   }
 
+  /**
+   * Sends a prepared local message.
+   *
+   * This asynchronous method takes a `PreparedLocalMessage` and sends it.
+   * Prepared messages are created using the {@linkcode Conversation.prepareMessage | prepareMessage} method.
+   *
+   * @param {PreparedLocalMessage} prepared - The prepared local message to be sent.
+   * @returns {Promise<string>} A Promise that resolves to a string identifier for the sent message.
+   * @throws {Error} Throws an error if there is an issue with sending the prepared message.
+   */
   async sendPreparedMessage(prepared: PreparedLocalMessage): Promise<string> {
     try {
       return await XMTP.sendPreparedMessage(this.clientAddress, prepared);
@@ -101,6 +136,16 @@ export class Conversation {
     }
   }
 
+  /**
+   * Decodes an encrypted message, yielding a `DecodedMessage` object.
+   *
+   * This asynchronous method takes an encrypted message and decodes it.
+   * The result is a `DecodedMessage` object containing the decoded content and metadata.
+   *
+   * @param {string} encryptedMessage - The encrypted message to be decoded.
+   * @returns {Promise<DecodedMessage>} A Promise that resolves to a `DecodedMessage` object.
+   * @throws {Error} Throws an error if there is an issue with decoding the message.
+   */
   async decodeMessage(encryptedMessage: string): Promise<DecodedMessage> {
     try {
       return await XMTP.decodeMessage(
@@ -114,10 +159,28 @@ export class Conversation {
     }
   }
 
+  /**
+   * Retrieves the consent state for the current conversation.
+   *
+   * This asynchronous method determine the consent state
+   * for the current conversation, indicating whether the user has allowed, denied,
+   * or is yet to provide consent.
+   *
+   * @returns {Promise<"allowed" | "denied" | "unknown">} A Promise that resolves to the consent state, which can be "allowed," "denied," or "unknown."
+   */
   async consentState(): Promise<"allowed" | "denied" | "unknown"> {
     return await XMTP.conversationConsentState(this.clientAddress, this.topic);
   }
-
+  /**
+   * Sets up a real-time message stream for the current conversation.
+   *
+   * This method subscribes to incoming messages in real-time and listens for new message events.
+   * When a new message is detected, the provided callback function is invoked with the details of the message.
+   * Additionally, this method returns a function that can be called to unsubscribe and end the message stream.
+   *
+   * @param {Function} callback - A callback function that will be invoked with the new DecodedMessage when a message is received.
+   * @returns {Function} A function that, when called, unsubscribes from the message stream and ends real-time updates.
+   */
   streamMessages(
     callback: (message: DecodedMessage) => Promise<void>,
   ): () => void {