From b1a4fe1f9cb44f0253bc5302629284febabf1178 Mon Sep 17 00:00:00 2001 From: kele-leanes Date: Tue, 21 Nov 2023 10:41:21 -0300 Subject: [PATCH] add Conversation documentation --- src/lib/Conversation.ts | 87 +++++++++++++++++++++++++++++++++++------ 1 file changed, 75 insertions(+), 12 deletions(-) diff --git a/src/lib/Conversation.ts b/src/lib/Conversation.ts index 0f3df09fd..f5ef5489b 100644 --- a/src/lib/Conversation.ts +++ b/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} 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} 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 { 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} 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 { 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} 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 { 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} 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 { 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 {