Add chat message reactions spec

Author: vladvelici

textile/chat-features.textile

@@ -326,6 +326,16 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and
 ** @(CHA-M4a)@ @[Testable]@ A subscription can be registered to receive incoming messages. Adding a subscription has no side effects on the status of the room or the underlying realtime channel.
 ** @(CHA-M4b)@ @[Testable]@ A subscription can de-registered from incoming messages. Removing a subscription has no side effects on the status of the room or the underlying realtime channel.
 
+* @(CHA-M11)@ A @Message@ must have a method @with@ to apply changes from events (@MessageEvent@ and @MessageReactionSummaryEvent@) to produce updated message instances.
+  ** @(CHA-M11a)@ @[Testable]@ When the method receives a @MessageEvent@ of type @created@, it must throw an @ErrorInfo@ with code @40000@ and status code @400@.
+  ** @(CHA-M11b)@ @[Testable]@ For @MessageEvent@ the method must verify that the @message.serial@ in the event matches the message's own serial. If they don't match, an error with code @40000@ and status code @400@ must be thrown.
+  ** @(CHA-M11c)@ @[Testable]@ For @MessageEvent@ of type @update@ and @delete@, if the event's @message.version@ is less than or equal to the current message's @version@, the original message must be returned unchanged.
+  ** @(CHA-M11d)@ @[Testable]@ For @MessageEvent@ of type @update@ and @delete@, if the event's @message.version@ is greater than the current message's @version@, the method must return a new message based on the event and deep-copying the reactions from the original message.
+  ** @(CHA-M11e)@ @[Testable]@ For @MessageReactionSummaryEvent@, the method must verify that the @summary.messageSerial@ in the event matches the message's own serial. If they don't match, an error with code @40000@ and status code @400@ must be thrown.
+  ** @(CHA-M11f)@ @[Testable]@ For @MessageReactionSummaryEvent@, the method must return a new @Message@ instance (deep copy) with the updated reactions, preserving all other properties of the original message.
+  ** @(CHA-M11g)@ @[Testable]@ For @MessageReactionSummaryEvent@, the method must deep-copy the reactions from the event before applying them to the returned message instance.
+  ** @(CHA-M11h)@ @[Testable]@ The method must not alter the original message instance.
+
 <div class=deprecated>
 ** @(CHA-M4c)@ @[Testable]@ @(deprecated)@ When a realtime message with @name@ set to @message.created@  is received, it is translated into a message event, which contains a @type@ field with the event type as well as a @message@ field containing the "@Message Struct@":#chat-structs-message. This event is then broadcast to all subscribers.
 </div>
@@ -354,6 +364,59 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and
 * @(CHA-M6b)@ @[Testable]@ If the REST API returns an error, then the method must throw its @ErrorInfo@ representation.
 * @(CHA-M7)@ This specification point has been removed. It was valid up until the single-channel migration.
 
+h2(#messageReactions). Message Reactions
+
+Users can add reactions to messages, such as thumbs-up or heart emojis. Summaries (counts per reaction, and who reacted) of the message reactions are stored with the message and are visible to all users in the room. Message reactions are powered by Pub/Sub message annotations.
+
+@MessagesReactions@ object is the entry point for interacting with Message Reactions. It shall be exposed to consumers via a @reactions@ property insde the @Messages@ obejct. From the @Room@ level: @room.messages.reactions@.
+
+* @(CHA-MR1)@ Message reactions are powered by Pub/Sub message annotations. The annotation type used is of the format @reaction:<aggregation>@.
+
+* @(CHA-MR2)@ There are three types of message reactions, each corresponding to a different annotation aggregation type.
+  ** @(CHA-MR2a)@ @[Testable]@ Reactions of type @Unique@ use the annotation type @reaction:unique.v1@. In this type, each client can add a specific reaction emoji only once.
+  ** @(CHA-MR2b)@ @[Testable]@ Reactions of type @Distinct@ use the annotation type @reaction:distinct.v1@. Each client can add multiple different reactions, but each emoji only once.
+  ** @(CHA-MR2c)@ @[Testable]@ Reactions of type @Multiple@ use the annotation type @reaction:multiple.v1@. In this type, each client can add any reaction multiple times including duplicates.
+
+* @(CHA-MR3)@ @[Testable]@ The @reactions@ property of the @Message@ object is an object or map that contains summaries for all message reaction types, keyed by reaction type and not annotation type (eg. "distinct" and not "reaction:distinct.v1").
+** @(CHA-MR3a)@ @[Testable]@ The values for each reaction type summary are the same as defined in PubSub for the respective annotation aggregation types.
+  ** @(CHA-MR3b)@ @[Testable]@ For @Unique@ reaction types, the summary is at @Message.reactions.unique@ and is of type @Dict<string, SummaryClientIdList>@ (see @TM7b2@).
+  ** @(CHA-MR3b3)@ @[Testable]@ For @Distinct@ reaction types, the summary is at @Message.reactions.distinct@ and is of type @Dict<string, SummaryClientIdList>@ (see @TM7b1@).
+  ** @(CHA-MR3b2)@ @[Testable]@ For @Multiple@ reaction types, the summary is at @Message.reactions.multiple@ and is of type @Dict<string, SummaryClientIdCounts>@ (see @TM7b3@).
+
+* @(CHA-MR4)@ @[Testable]@ Sending a reaction is done via the @add@ method of the @MessagesReactions@ object (@room.messages.reactions.add@). The method accepts a message (or message serial), and an object where the @reaction@ (ie. emoji string), @type@ (optional) and @count@ (optional, only valid for type @multiple@) are specified.
+** @(CHA-MR4a)@ @[Testable]@ If @type@ is not specified, the default type for the room used.
+
+* @(CHA-MR5)@ @[Testable]@ Users may configure a default message reactions type for a room. This configuration is provided at the @RoomOptions.messages.defaultMessageReactionType@ property, or idiomatic equivalent. The default value is @distinct@.
+
+* @(CHA-MR6)@ @[Testable]@ Subscribing to message reactions is done via the @subscribe@ method of the @MessagesReactions@ object (@room.messages.reactions.subscribe@). The method accepts a callback (or similar idomatic construct) that receives message reactions summary events of type @MessageReactionSummaryEvent@.
+
+* @(CHA-MR7)@ The @MessageReactionSummaryEvent@ interface provides information about reaction summaries for messages.
+  ** @(CHA-MR7a)@ @[Testable]@ The event must include a @type@ field set to indicate it's a reaction summary event.
+  ** @(CHA-MR7b)@ @[Testable]@ The event must include a @summary@ object containing:
+    *** @(CHA-MR7b1)@ @[Testable]@ The @messageSerial@ identifying which message the reactions belong to.
+    *** @(CHA-MR7b2)@ @[Testable]@ A @unique@ field containing reaction summaries for unique-type reactions.
+    *** @(CHA-MR7b3)@ @[Testable]@ A @distinct@ field containing reaction summaries for distinct-type reactions.
+    *** @(CHA-MR7b4)@ @[Testable]@ A @multiple@ field containing reaction summaries for multiple-type reactions.
+
+* @(CHA-MR8)@ @[Testable]@ Subscribing to raw message reactions (as individual annotations) is done via the @subscribeRaw@ method of the @MessagesReactions@ object (@room.messages.reactions.subscribeRaw@). The method accepts a callback (or similar idomatic construct) that receives individual annotations of type @MessageReactionRawEvent@.
+* @(CHA-MR8a)@ @[Testable]@ Subscribing to raw message reactions throws an error if the room is not configured to support raw message reactions by setting room option @RoomOptions.messages.rawMessageReactions@ to @true@ (defaults to @false@).
+
+* @(CHA-MR9)@ The @MessageReactionRawEvent@ interface provides information about individual message reaction events.
+  ** @(CHA-MR9a)@ @[Testable]@ The event must include a @type@ field indicating whether a reaction was added or removed.
+  ** @(CHA-MR9b)@ @[Testable]@ The event must include a @timestamp@ field containing the date/time when the event occurred.
+  ** @(CHA-MR9c)@ @[Testable]@ The event must include a @reaction@ object containing:
+    *** @(CHA-MR9c1)@ @[Testable]@ A @messageSerial@ identifying which message the reaction belongs to.
+    *** @(CHA-MR9c2)@ @[Testable]@ A @type@ field indicating the reaction type (unique, distinct, or multiple).
+    *** @(CHA-MR9c3)@ @[Testable]@ A @reaction@ field containing the reaction string (typically an emoji).
+    *** @(CHA-MR9c4)@ @[Testable]@ An optional @count@ field for reactions of type Multiple.
+    *** @(CHA-MR9c5)@ @[Testable]@ A @clientId@ identifying the user who added or removed the reaction.
+  ** @(CHA-MR9d)@ Raw message reactions should not be used to update the message reaction summary on the client-side as this is likely to produce wrong results. Message reaction summaries are to be used for this.
+
+* @(CHA-MR10)@ @[Testable]@ The room option @RoomOptions.messages.rawMessageReactions@ controls whether raw message reactions are enabled or not. The default value is @false@. 
+  ** @(CHA-MR10a)@ @[Testable]@ If the room option is set to @true@, the SDK will add the @ANNOTATION_SUBSCRIBE@ channel mode to the realtime channel used for the room.
+
+* @(CHA-MR11)@ @[Testable]@ The SDK always adds the @ANNOTATION_PUBLISH@ channel mode to the realtime channel used for the room.
+
 h2(#reactions). Ephemeral Room Reactions
 
 Ephemeral room reactions are one-time events that are sent to the room, such as thumbs-up or heart emojis. They are supposed to capture the current emotions in the room (e.g. everyone spamming the :tada: emoji when a team scores the winning goal).
@@ -747,6 +810,92 @@ h4(#rest-fetching-messages-response). Response V3
 
 An array of V2 "@Message@ structs":#chat-structs-message-v2
 
+
+h3(#rest-sending-message-reactions). Sending message reactions
+
+h4(#rest-sending-messages-reactions-request-v3). Request V3
+
+Below is the full REST payload format for the V3 endpoint. The @count@ field is optional and it is only accepted for reactions of type @reaction:multiple.v1@.
+
+<pre>
+  POST /chat/v3/rooms/<roomId>/messages/<serial>/reactions
+  {
+    "type": "reaction:multiple.v1",
+    "reaction": "🔥",
+    "count": 5
+  }
+</pre>
+
+h4(#rest-sending-messages-response-v3). Response V3
+
+A successful request shall result in status code @201 Created@.
+
+The response body is as follows showing the serial of the new annotation.
+
+<pre>
+  {
+    "serial": "01746631786947-000@cbfVqJopQBorrt95348450",
+  }
+</pre>
+
+h4(#rest-sending-messages-realtime-v3). Corresponding Realtime Event V3
+
+Note this is an Annotation not a Message. ChannelMessage action is 21. The annotations are under the @annotations@ key.
+
+<pre>
+  {
+    "action" : 0,
+    "clientId" : "user-1",
+    "messageSerial" : "01746631762878-000@cbfVqJopQBorrt95348450:000",
+    "name" : "🔥",
+    "serial" : "01746631786947-000@cbfVqJopQBorrt95348450:000",
+    "type" : "reaction:multiple.v1",
+    "count": 5
+  }
+</pre>
+
+A message summary event is also broadcast to the channel after adding or removing one or more annotations.
+
+h3(#rest-deleting-message-reactions). Deleting message reactions
+
+h4(#rest-deleting-messages-reactions-request-v3). Request V3
+
+Below is the full REST payload format for the V3 endpoint. The @reaction@ param is ignored for reactions of type @reaction:unique.v1@ but it is required for all other reaction types.
+
+<pre>
+  DELETE /chat/v3/rooms/<roomId>/messages/<serial>/reactions?type=<reactionType>&reaction=<reaction>
+</pre>
+
+h4(#rest-sending-messages-response-v3). Response V3
+
+A successful request shall result in status code @200 OK@.
+
+The response body is as follows showing the serial of the new annotation (annotation delete is also an annotation with annotation @action=1@).
+
+<pre>
+  {
+    "serial": "01746632464399-000@cbfVqJopQBorrt95348450",
+  }
+</pre>
+
+h4(#rest-sending-messages-realtime-v3). Corresponding Realtime Event V3
+
+Note this is an Annotation not a Message. ChannelMessage action is 21. The annotations are under the @annotations@ key.
+
+<pre>
+  {
+    "action" : 1,
+    "clientId" : "user-1",
+    "messageSerial" : "01746631762878-000@cbfVqJopQBorrt95348450:000",
+    "name" : "❤️",
+    "serial" : "01746632464399-000@cbfVqJopQBorrt95348450:000",
+    "type" : "reaction:distinct.v1"
+  }
+</pre>
+
+A message summary event is also broadcast to the channel after adding or removing one or more annotations.
+
+
 h2(#realtime-api). Chat Realtime API
 
 This section describes the message formats for chat events that occur over a Realtime connection.
@@ -872,6 +1021,11 @@ h4(#chat-structs-message-v2). Messages V2
             "bar": 1
           }
         },
+    },
+    "reactions": {
+      "unique": {"like": {"total": 2, "clientIds": ["userOne", "userTwo"]}, "love": {"total": 1, "clientIds": ["userThree"]}},
+      "distinct": {"like": {"total": 2, "clientIds": ["userOne", "userTwo"]}, "love": {"total": 1, "clientIds": ["userOne"]}},
+      "multiple": {"like": {"total": 5, "clientIds": {"userOne": 3, "userTwo": 2}}, "love": {"total": 10, "clientIds": {"userOne": 10}}},
     }
   }
 </pre>
@@ -888,6 +1042,85 @@ Determining the global order of messages may be achieved by lexicographically co
 
 Determining the global order of message versions may be achieved by lexicographically comparing the @version@. See @CHA-M10@ for more information.
 
+When keeping a @Message@ updated, use the @Message.with(event)@ method to apply events to ensure correctness. The @with@ method returnes message instances with the event applied to them. If the event is not applicable due to being for an older version of the message, the method will return the message unchanged. If the event is applicable, a new instance will be returned with the event applied. @Message.with()@ correctly handles message reactions. See @CHA-M11@ for more information.
+
+
+h3(#chat-structs-message-reactions-summary-event). Message reactions reaction summary
+
+<pre>
+  {
+    type: "reaction.summary",
+    summary: {
+      messageSerial: "01726585978590-001@abcdefghij:001",
+      "unique": {
+        "like": {
+          "total": 2,
+          "clientIds": ["userOne", "userTwo"]
+        },
+        "love": {
+          "total": 1,
+          "clientIds": ["userThree"]
+        }
+      },
+      "distinct": {
+        "like" : {
+            "clientIds" : [
+              "userOne",
+              "userTwo"
+            ],
+            "total" : 2
+        },
+        "love" : {
+            "clientIds" : [
+              "userOne"
+            ],
+            "total" : 1
+        }
+      },
+      "multiple": {
+        "like" : {
+            "clientIds" : {
+              "userOne" : 3,
+              "userTwo" : 2
+            },
+            "total" : 5
+        },
+        "love" : {
+            "clientIds" : {
+              "userOne" : 10
+            },
+            "total" : 10
+        }
+      }
+    }
+  }
+</pre>
+
+
+h3(#chat-structs-message-reactions-raw-event). Message reactions raw reaction event
+
+<pre>
+  {
+    type: "reaction.create",
+    timestamp: DateTime(),
+    reaction: {
+      messageSerial: "01726585978590-001@abcdefghij:001",
+      type: "reaction:multiple.v1",
+      reaction: ":like:",
+      count: 3,
+      clientId: "user1",
+    };
+  }
+</pre>
+
+Event @type@ can be @reaction.update@ or @reaction.delete@.
+
+Event @reaction.type@ can be @reaction:unique.v1@, @reaction:distinct.v1@ or @reaction:multiple.v1@.
+
+@reaction.count@ is optional and only set for @reaction:multiple.v1@.
+
+
+
 h3(#chat-structs-ephemeral-reactions). Ephemeral Room Reactions
 
 <pre>