Add new fields for mutable messages

descriptions.md

@@ -592,6 +592,20 @@ Enumerates the possible types of `PresenceMessage` (and corresponding presence e
 | LEAVE | TP2 | A member who was present has now left the channel's presence set. This may be a result of an explicit request to leave, or implicit from the member detaching from the channel or disconnecting from Ably and not reconnecting within a grace period. |
 | UPDATE | TP2 | An already present member has updated their member data. |
 
+## enum MessageAction
+
+Enumerates the possible types of `Message` there can be.
+
+| Enum | Spec | Description |
+|---|---|---|
+| MESSAGE_UNSET | TM5 | (The field is unset, eg a `Message` retrieved from before the `action` field was added) |
+| MESSAGE_CREATE | TM5 | A normal message that has been published by a user. |
+| MESSAGE_UPDATE | TM5 | An update that modifies a previously-published message (referenced by `serial`). |
+| MESSAGE_DELETE | TM5 | A deletion of a previously-published message (referenced by `serial`). |
+| ANNOTATION_CREATE | TM5 | An annotation added to a previously-published message (referenced by serial). |
+| ANNOTATION_DELETE | TM5 | A deletion of a annotation that was previously added to a published message. |
+| META_OCCUPANCY | TM5 | Channel metadata containing information on what the current occupancy of the channel is. |
+
 ## class ConnectionDetails
 
 Contains any constraints a client should adhere to and provides additional metadata about a [`Connection`]{@link Connection}, such as if a request to [`publish()`]{@link RealtimeClient#publish} a message that exceeds the maximum message size should be rejected immediately without communicating with Ably.
@@ -635,7 +649,24 @@ Contains an individual message that is sent to, or received from, Ably.
 | extras: JsonObject? ||| TM2i | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include [`push`]{@link Push}, [`delta`]{@link DeltaExtras}, [`ref`]{@link ReferenceExtras} and `headers`. |
 | id: String ||| TM2a | A Unique ID assigned by Ably to this message. |
 | name: String? ||| TM2g | The event name. |
-| timestamp: Time ||| TM2f | Timestamp of when the message was received by Ably, as milliseconds since the Unix epoch. |
+| action: MessageAction ||| TM2j | Which one of the [`MessageAction`]{@link MessageAction} types this message represents. |
+| timestamp: Time ||| TM2f | Timestamp of when the message was received by Ably, as milliseconds since the Unix epoch. (This is the timestamp of the current version of the message) |
+| serial: String? ||| TM2k | This message's unique serial (an identifier that — unlike the id — will remain the same in all future updates of this message, and can be used to update or delete that message). Lexicographically-comparable with other serials and with the `version` field. |
+| version: String? ||| TM2p | The version of the message, lexicographically-comparable with other versions (that share the same serial) Will differ from the serial only if the message has been updated or deleted. |
+| refSerial: String? ||| TM2l | If this message references another, the serial of that referenced message. |
+| refType: String? ||| TM2m | If this message references another, the type of reference that is. |
+| createdAt: Time? ||| TM2o | The timestamp of the very first version of a given message (will differ from `timestamp` only if the message has been updated or deleted). |
+| operation: Operation? ||| TM2n | In the case of an updated or deleted message, this will contain metadata about the update or delete operation. |
+
+## class Operation
+
+In the case of an updated or deleted message, this will contain metadata about the update or delete operation.
+
+| Method / Property | Parameter | Returns | Spec | Description |
+|---|---|---|---|---|
+| clientId: String? ||| TM2n1 | ClientId of the user who triggered the update or delete. |
+| description: String? ||| TM2n2 | Reason for the update or delete provided by of the user who triggered it. |
+| metadata: Dict<string, string>? ||| TM2n3 | Arbitrary metadata contributed by the user who triggered the update or delete. |
 
 ## class PresenceMessage