From 68eea3467f7f565088db8d3fd77eccbe94cca01d Mon Sep 17 00:00:00 2001 From: daria-github Date: Wed, 9 Aug 2023 11:57:43 -0700 Subject: [PATCH 1/4] read receipt read me draft --- packages/content-type-read-receipt/README.md | 105 ++++++++++++++++++- 1 file changed, 104 insertions(+), 1 deletion(-) diff --git a/packages/content-type-read-receipt/README.md b/packages/content-type-read-receipt/README.md index dc0ae1e..10cf9fa 100644 --- a/packages/content-type-read-receipt/README.md +++ b/packages/content-type-read-receipt/README.md @@ -1 +1,104 @@ -## Coming soon +# Read receipt content type + +This package provides an XMTP content type to support read receipts to messages. + +## What’s a read receipt? + +A read receipt is a message sent to confirm that a previously sent message has been read by the recipient. With XMTP, read receipts are special messages with the ReadReceipt content type. They contain a timestamp of when the original message was read. + +When someone receives a message on an app with read receipts enabled, their XMTP client can send a read receipt when they open that message. + +## Why read receipts? + +Read receipts give the sender confirmation that the recipient has read their message. This avoids uncertainty on whether a message was seen, without needing to rely on responses. + +## Install the package + +```bash +# npm +npm i @xmtp/content-type-read-receipt + +# yarn +yarn add @xmtp/content-type-read-receipt + +# pnpm +pnpm i @xmtp/content-type-read-receipt +``` + +## Create a read receipt + +With XMTP, read receipts are represented as objects with the following keys: + +- `timestamp`: The timestamp the read receipt was sent + +```tsx +const readReceipt: ReadReceipt = { + timestamp: new Date().toISOString(); +}; +``` + +## Send a read receipt + +If a sender has opened a conversation and has not yet sent a read receipt for its received messages (this can either be done with each message or the most recent message and is an individual app decision), you can send a read receipt like so: + +```tsx +await conversation.messages.send( + { + timestamp: new Date().toISOString(), + }, + ContentTypeReadReceipt, +); +``` + +## Receive a read receipt + +Now that you can send a read receipt, you can also receive a read receipt that was sent from another user. For example: + +```tsx +// Assume `loadLastMessage` is a thing you have +const message: DecodedMessage = await loadLastMessage(); + +if (message.contentType.sameAs(ContentTypeReadReceipt)) { + // We have a read receipt + return; +} +``` + +## Display the read receipt + +Generally, read receipts should be displayed under the message it's associated with, and can include a timestamp or no timestamp. Ultimately, how you choose to display read receipts is completely up to you. + +## UX Notes + +While this is a per-app decision, we do recommend having this as a toggle in your app so users can also opt-out should they choose not to send read receipts to messages from their recipients. + +## Playground Implementation + +In our playground implementation, we store our read receipts in IndexDB in its own table, separate from regular messages. + +We send a read receipt when a user opens a conversation only if the most recent message was from the other party, and there is no read receipt after that last message timestamp in the read receipts table. Our decision to do this for the last message instead of for all received messages had to do with not wanting to potentially double the # of messages by sending read receipts for every single message. + +You can view that playground implementation here: https://github.com/xmtp/xmtp-react-playground + +We show a read receipt if the most recent message was from the other party and a read receipt for that message exists. + +## Developing + +Run `yarn dev` to build the content type and watch for changes, which will trigger a rebuild. + +## Testing + +Before running unit tests, start the required Docker container at the root of this repository. For more info, see [Running tests](../../README.md#running-tests). + +## Useful commands + +- `yarn build`: Builds the content type +- `yarn clean`: Removes `node_modules`, `dist`, and `.turbo` folders +- `yarn dev`: Builds the content type and watches for changes, which will trigger a rebuild +- `yarn format`: Runs Prettier format and write changes +- `yarn format:check`: Runs Prettier format check +- `yarn lint`: Runs ESLint +- `yarn test:setup`: Starts a necessary Docker container for testing +- `yarn test:teardown`: Stops Docker container for testing +- `yarn test`: Runs all unit tests +- `yarn typecheck`: Runs `tsc` From 786722b62bf7b17347519b55c584d8337a5345b2 Mon Sep 17 00:00:00 2001 From: daria-github Date: Wed, 9 Aug 2023 13:55:05 -0700 Subject: [PATCH 2/4] addressed code comments --- packages/content-type-read-receipt/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/content-type-read-receipt/README.md b/packages/content-type-read-receipt/README.md index 10cf9fa..bd2349f 100644 --- a/packages/content-type-read-receipt/README.md +++ b/packages/content-type-read-receipt/README.md @@ -29,7 +29,7 @@ pnpm i @xmtp/content-type-read-receipt With XMTP, read receipts are represented as objects with the following keys: -- `timestamp`: The timestamp the read receipt was sent +- `timestamp`: The timestamp the read receipt was sent, in ISO 8601 format ```tsx const readReceipt: ReadReceipt = { @@ -74,7 +74,7 @@ While this is a per-app decision, we do recommend having this as a toggle in you ## Playground Implementation -In our playground implementation, we store our read receipts in IndexDB in its own table, separate from regular messages. +In our playground implementation, we store our read receipts in IndexedDB in its own table, separate from regular messages. We send a read receipt when a user opens a conversation only if the most recent message was from the other party, and there is no read receipt after that last message timestamp in the read receipts table. Our decision to do this for the last message instead of for all received messages had to do with not wanting to potentially double the # of messages by sending read receipts for every single message. From 5887bf48af7884075c50c37aee6e6819d54b0d49 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Wed, 9 Aug 2023 14:44:38 -0700 Subject: [PATCH 3/4] docs: some edits from jha --- packages/content-type-read-receipt/README.md | 23 +++++++++++--------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/packages/content-type-read-receipt/README.md b/packages/content-type-read-receipt/README.md index bd2349f..c9806dc 100644 --- a/packages/content-type-read-receipt/README.md +++ b/packages/content-type-read-receipt/README.md @@ -2,15 +2,18 @@ This package provides an XMTP content type to support read receipts to messages. +> **Open for feedback** +> You are welcome to provide feedback on this implementation by commenting on the [Read Receipts content type proposal](https://github.com/xmtp/XIPs/pull/27). + ## What’s a read receipt? -A read receipt is a message sent to confirm that a previously sent message has been read by the recipient. With XMTP, read receipts are special messages with the ReadReceipt content type. They contain a timestamp of when the original message was read. +A read receipt is a message sent to confirm that a previously sent message has been read by the recipient. With XMTP, read receipts are special messages with the `ReadReceipt` content type. They contain a timestamp of when the original message was read. -When someone receives a message on an app with read receipts enabled, their XMTP client can send a read receipt when they open that message. +When someone receives a message using an app with read receipts enabled, their XMTP client can send a read receipt when they open that message. ## Why read receipts? -Read receipts give the sender confirmation that the recipient has read their message. This avoids uncertainty on whether a message was seen, without needing to rely on responses. +Read receipts give the sender confirmation that the recipient has read their message. This avoids uncertainty about whether a message was seen, without needing to rely on a manual response. ## Install the package @@ -68,19 +71,19 @@ if (message.contentType.sameAs(ContentTypeReadReceipt)) { Generally, read receipts should be displayed under the message it's associated with, and can include a timestamp or no timestamp. Ultimately, how you choose to display read receipts is completely up to you. -## UX Notes +## UX best practices -While this is a per-app decision, we do recommend having this as a toggle in your app so users can also opt-out should they choose not to send read receipts to messages from their recipients. +While this is a per-app decision, the best practice is to provide users with the option to opt out of sending read receipts. If a user opts out, when they read a message, a read receipt will not be sent to the sender of the message. -## Playground Implementation +## Playground implementation -In our playground implementation, we store our read receipts in IndexedDB in its own table, separate from regular messages. +In the XMTP React playground implementation, read receipts are stored in IndexedDB in their own table, separate from regular messages. -We send a read receipt when a user opens a conversation only if the most recent message was from the other party, and there is no read receipt after that last message timestamp in the read receipts table. Our decision to do this for the last message instead of for all received messages had to do with not wanting to potentially double the # of messages by sending read receipts for every single message. +A read receipt is sent when a user opens a conversation only if the most recent message was from the other party, and there is no read receipt after that last message timestamp in the read receipts table. The decision to do this for the last message instead of for all received messages has to do with not wanting to potentially double the number of messages by sending read receipts for every single message. -You can view that playground implementation here: https://github.com/xmtp/xmtp-react-playground +To try it out, see the [XMTP React playground](https://github.com/xmtp/xmtp-react-playground). -We show a read receipt if the most recent message was from the other party and a read receipt for that message exists. +A read receipt is shown if the most recent message was from the other party and a read receipt for that message exists. ## Developing From 1c6a012e4166c74c3c4eca914e32cdd65b8b47d5 Mon Sep 17 00:00:00 2001 From: daria-github Date: Thu, 10 Aug 2023 10:11:37 -0700 Subject: [PATCH 4/4] updated proposal link --- packages/content-type-read-receipt/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/content-type-read-receipt/README.md b/packages/content-type-read-receipt/README.md index c9806dc..41d31ef 100644 --- a/packages/content-type-read-receipt/README.md +++ b/packages/content-type-read-receipt/README.md @@ -3,7 +3,7 @@ This package provides an XMTP content type to support read receipts to messages. > **Open for feedback** -> You are welcome to provide feedback on this implementation by commenting on the [Read Receipts content type proposal](https://github.com/xmtp/XIPs/pull/27). +> You are welcome to provide feedback on this implementation by commenting on the [Read Receipts content type proposal](https://github.com/orgs/xmtp/discussions/43). ## What’s a read receipt?