Docs: Add content type statuses, update read receipts doc (#40)

* docs: add status, update read receipts doc

* docs: edits from ry <3

README.md

@@ -11,6 +11,7 @@ To learn more about the contents of this repository, see this README and the REA
 - [`content-type-remote-attachment`](packages/content-type-remote-attachment)
 - [`content-type-reaction`](packages/content-type-reaction)
 - [`content-type-reply`](packages/content-type-reply)
+- [`content-type-read-receipt`](packages/content-type-read-receipt)
 
 ## Requirements
 

packages/content-type-reaction/README.md

@@ -1,5 +1,7 @@
 # Reaction content type
 
+![Status](https://img.shields.io/badge/Content_type_status-Standards--track-yellow) ![Status](https://img.shields.io/badge/Reference_implementation_status-Beta-yellow)
+
 This package provides an XMTP content type to support reactions to messages.
 
 > **Open for feedback**  
@@ -49,12 +51,11 @@ Now that you have a reaction, you can send it:
 ```tsx
 await conversation.messages.send(reaction, {
   contentType: ContentTypeReaction,
-  contentFallback: `[Reaction] ${client.address} reacted to ${someMessage.content} with:\n\n${reaction.content}`,
 });
 ```
 
-> **Note**
-> Use `contentFallback` to enable clients that don't support these content types to still display some useful context. For cases where clients *do* support these types, they can use the content fallback as alt text for accessibility purposes.
+> **Note**  
+> `contentFallback` text is provided by the codec and gives clients that _don't_ support a content type the option to display some useful context. For cases where clients *do* support the content type, they can use the content fallback as alt text for accessibility purposes.
 
 ## Receive a reaction
 

packages/content-type-read-receipt/README.md

@@ -1,7 +1,14 @@
 # Read receipt content type
 
+![Status](https://img.shields.io/badge/Content_type_status-Standards--track-yellow) ![Status](https://img.shields.io/badge/Reference_implementation_status-Alpha-orange)
+
 This package provides an XMTP content type to support read receipts to messages.
 
+> **Important**  
+> This standards-track content type is in **Alpha** status as this implementation doesn't work efficiently with the current protocol architecture. This inefficiency will be addressed in a future protocol release.
+
+Until then, if you must support read receipts, we recommend that you use this implementation and **not build your own custom content type.**
+
 > **Open for feedback**  
 > 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).
 
@@ -28,29 +35,24 @@ yarn add @xmtp/content-type-read-receipt
 pnpm i @xmtp/content-type-read-receipt
 ```
 
-## Create a read receipt
+## Provide an opt-out option
 
-With XMTP, read receipts are represented as objects with the following keys:
+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.
 
-- `timestamp`: The timestamp the read receipt was sent, in ISO 8601 format
+## Create a read receipt
+
+With XMTP, read receipts are represented as empty objects.
 
 ```tsx
-const readReceipt: ReadReceipt = {
-  timestamp: new Date().toISOString();
-};
+const readReceipt: ReadReceipt = {};
 ```
 
 ## 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,
-);
+await conversation.messages.send({}, ContentTypeReadReceipt);
 ```
 
 ## Receive a read receipt
@@ -69,11 +71,10 @@ if (message.contentType.sameAs(ContentTypeReadReceipt)) {
 
 ## 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.
+Generally, a read receipt indicator should be displayed under the message it's associated with. The indicator can include a timestamp. Ultimately, how you choose to display a read receipt indicator is completely up to you.
 
-## UX best practices
-
-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.
+> **Important**  
+> The read receipt is provided as an **empty message** whose timestamp provides the data needed for the indicators. **Be sure to filter out read receipt empty messages and not display them to users.**
 
 ## Playground implementation
 
@@ -83,7 +84,7 @@ A read receipt is sent when a user opens a conversation only if the most recent
 
 To try it out, see the [XMTP React playground](https://github.com/xmtp/xmtp-react-playground).
 
-A read receipt is shown if the most recent message was from the other party and a read receipt for that message exists.
+A read receipt indicator is shown if the most recent message was from the other party and a read receipt for that message exists.
 
 ## Developing
 

packages/content-type-remote-attachment/README.md

@@ -1,5 +1,7 @@
 # Remote attachment content type
 
+![Status](https://img.shields.io/badge/Content_type_status-Standards--track-yellow) ![Status](https://img.shields.io/badge/Reference_implementation_status-Stable-brightgreen)
+
 The [remote-attachment](https://github.com/xmtp/xmtp-js-content-types/tree/main/remote-attachment) package provides an XMTP content type to support sending file attachments that are stored off-network. Use it to enable your app to send and receive message attachments.
 
 > **Open for feedback**  
@@ -130,11 +132,11 @@ Now that you have a remote attachment, you can send it:
 ```tsx
 await conversation.messages.send(remoteAttachment, {
   contentType: ContentTypeRemoteAttachment,
-  contentFallback: "a screenshot of 1MB of text",
 });
 ```
 
-Note that we’re using `contentFallback` to enable clients that don't support these content types to still display something. For cases where clients *do* support these types, they can use the content fallback as alt text for accessibility purposes.
+> **Note**  
+> `contentFallback` text is provided by the codec and gives clients that _don't_ support a content type the option to display some useful context. For cases where clients *do* support the content type, they can use the content fallback as alt text for accessibility purposes.
 
 ## Receive a remote attachment
 

packages/content-type-reply/README.md

@@ -1,5 +1,7 @@
 # Reply content type
 
+![Status](https://img.shields.io/badge/Content_type_status-Standards--track-yellow) ![Status](https://img.shields.io/badge/Reference_implementation_status-Beta-yellow)
+
 This package provides an XMTP content type to support direct replies to messages.
 
 > **Open for feedback**  
@@ -47,12 +49,11 @@ Now that you have a reply, you can send it:
 ```tsx
 await conversation.messages.send(reply, {
   contentType: ContentTypeReply,
-  contentFallback: `[Reply] ${client.address} replied to ${someMessage.content} with:\n\n${reply.content}`,
 });
 ```
 
-> **Note**
-> Use `contentFallback` to enable clients that don't support these content types to still display some useful context. For cases where clients *do* support these types, they can use the content fallback as alt text for accessibility purposes.
+> **Note**  
+> `contentFallback` text is provided by the codec and gives clients that _don't_ support a content type the option to display some useful context. For cases where clients *do* support the content type, they can use the content fallback as alt text for accessibility purposes.
 
 ## Receive a reply