Merge pull request #2766 from ably/chat/move-to-pv4

Chat: Move to V4 Message Structure

Author: splindsay-92

examples/package.json

@@ -100,8 +100,8 @@
     "spaces-member-location-react": "yarn workspace spaces-member-location-react dev"
   },
   "dependencies": {
-    "@ably/chat": "^0.13.0",
-    "@ably/chat-react-ui-components": "^0.1.1",
+    "@ably/chat": "^0.14.0",
+    "@ably/chat-react-ui-components": "^0.1.2",
     "@ably/spaces": "^0.4.0",
     "ably": "^2.9.0",
     "cors": "^2.8.5",

examples/yarn.lock

@@ -2,17 +2,17 @@
 # yarn lockfile v1
 
 
-"@ably/chat-react-ui-components@^0.1.1":
-  version "0.1.1"
-  resolved "https://registry.yarnpkg.com/@ably/chat-react-ui-components/-/chat-react-ui-components-0.1.1.tgz#102c20c00b110fa26e3663a92eb6767fa9336783"
-  integrity sha512-OqpKp2kXKNqkfpSYVomU5R1TIoc/k+HDxQzbtAJtYuH67DEp7JgNi8Xqidv0wwuFfaVPzNIlWwyhbcwIVJY/LQ==
+"@ably/chat-react-ui-components@^0.1.2":
+  version "0.1.2"
+  resolved "https://registry.yarnpkg.com/@ably/chat-react-ui-components/-/chat-react-ui-components-0.1.2.tgz#692919b0d1e66a0b6267057918a4fd6f4354bd1d"
+  integrity sha512-WEEFburLyNieOb3Fvu/KXO1h/M93cUiAo8hsp3EoJOT1y0rFcVLdnDKDm+BPIHCT0PIVMr1sWZJQ9anuqT0y6A==
   dependencies:
     clsx "^2.1.1"
 
-"@ably/chat@^0.13.0":
-  version "0.13.0"
-  resolved "https://registry.yarnpkg.com/@ably/chat/-/chat-0.13.0.tgz#5b6391fd22b684c3ce896dac3d1b821de14f1de8"
-  integrity sha512-YbTzSn6H821qP6XkqQZwUe4+3IclHuLn15hXBl+fFnu0bHeh9hT4JQyB7t/nGlv4gvCCQpHIRhkksxqGLWiTBg==
+"@ably/chat@^0.14.0":
+  version "0.14.0"
+  resolved "https://registry.yarnpkg.com/@ably/chat/-/chat-0.14.0.tgz#8a7d7be46301977bd2cbd01021f67be8980d0370"
+  integrity sha512-9QsJdHVcyYDP0cTHXh7towHI9tM+SbmEMMVK10+0y1N1epl6FBSEeBDMn1fH5i73nxbKleUxjBltWiXlQz4InA==
   dependencies:
     async-mutex "^0.5.0"
     dequal "^2.0.3"

src/components/Examples/ExamplesRenderer.tsx

@@ -42,7 +42,7 @@ const getDependencies = (id: string, products: string[], activeLanguage: Languag
     minifaker: '1.34.1',
     ...(products.includes('auth') ? { cors: '^2.8.5' } : {}),
     ...(products.includes('chat')
-      ? { '@ably/chat': '^0.13.0', '@ably/chat-react-ui-components': '^0.1.1', clsx: '^2.1.1' }
+      ? { '@ably/chat': '^0.14.0', '@ably/chat-react-ui-components': '^0.1.2', clsx: '^2.1.1' }
       : {}),
     ...(products.includes('spaces') ? { '@ably/spaces': '^0.4.0' } : {}),
     ...(id === 'spaces-component-locking' ? { 'usehooks-ts': '^3.1.0' } : {}),

src/data/languages/languageData.ts

@@ -24,8 +24,8 @@ export default {
     laravel: '1.0',
   },
   chat: {
-    javascript: '0.13',
-    react: '0.13',
+    javascript: '0.14',
+    react: '0.14',
     swift: '0.6',
     kotlin: '0.7',
   },

src/pages/docs/chat/rooms/media.mdx

@@ -187,7 +187,7 @@ Use a function or component to display the message and its media:
 function createMessageDOM(message) {
   const container = document.createElement("div");
   container.setAttribute('data-message-serial', message.serial)
-  container.setAttribute('data-message-version', message.version)
+  container.setAttribute('data-message-version', message.version?.serial)
 
   const text = document.createElement("div");
   text.innerText = message.text;

src/pages/docs/chat/rooms/messages.mdx

@@ -67,11 +67,12 @@ The following is the structure of a message:
   "text": "What a shot!",
   "headers": {},
   "metadata": {},
-  "createdAt": new Date("2024-06-12T11:37:59.988Z"),
-  "action": "message.create",
-  "version": "01826232498871-001@abcdefghij:001",
   "timestamp": new Date("2024-06-12T11:37:59.988Z"),
-  "operation": {},
+  "action": "message.create",
+  "version": {
+    "serial": "01826232498871-001@abcdefghij:001",
+    "timestamp": new Date("2024-06-12T11:37:59.988Z")
+  }
 }
 ```
 </Code>
@@ -85,14 +86,14 @@ The following are the properties of a message:
 | text | The message contents. | String |
 | headers | Optional headers for adding additional information to a message, such as the relative timestamp of a livestream video, or flagging a message as important. Do not use the headers for authoritative information. There is no server-side validation. When reading headers treat them like user input. | Object |
 | metadata | Optional additional metadata about the message, such as animations, effects or links to other resources such as images. This information is not read by Ably. Do not use metadata for authoritative information. There is no server-side validation. When reading metadata treat it like user input. | Object |
-| createdAt | The time the message was created. | Date |
+| timestamp | The time the message was created. | Date |
 | action | The latest action performed on this message, such as `message.create`, `message.update` or `message.delete`.  | String |
-| version | An Ably-generated ID used to uniquely identify the version of the message. It provides a deterministic global ordering of message versions. The `version` is identical to `serial` if the action is `message.create`.  | String |
-| timestamp | The time the action was performed. It will be identical to `createdAt` if the action is a `message.create`. | Date |
-| operation | For updates and deletions, this provides additional details about the action. It may contain the following properties: | Object or undefined |
-| | `clientId`: The client identifier of the user associated with the action. | String or undefined |
-| | `description`: Optional description for the action. | String or undefined |
-| | `metadata`: Optional additional metadata about the action. | Object or undefined |
+| version | Contains information about the current version of the message. For `message.create` actions, only `serial` and `timestamp` are set. For `message.update` and `message.delete` actions, additional fields are included. | Object |
+| | `serial`:  An Ably-generated ID used to uniquely identify the version of the message. It provides a deterministic global ordering of message versions. The `version.serial` is identical to `serial` if the action is `message.create`. | String |
+| | `timestamp`:  The time the action was performed. It will be identical to `timestamp` if the action is a `message.create`. | Date |
+| | `clientId`:  The client identifier of the user that created this version of the message. Only set for `message.update` and `message.delete` actions. | String or undefined |
+| | `description`:  Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | String or undefined |
+| | `metadata`:  Optional description provided by the client that created this message version. Only set for `message.update` and `message.delete` actions. | Object or undefined |
 
 See [below](#global-ordering) for more information on how to apply deterministic global ordering to the chat messages in your application.
 
@@ -390,27 +391,30 @@ The following is the structure of an updated message:
   "text": "What a shot! Edit: I meant to say 'What a dunk!'",
   "headers": {},
   "metadata": {},
-  "createdAt": new Date("2024-06-12T11:37:59.988Z")S,
+  "timestamp": new Date("2024-06-12T11:37:59.988Z"),
   "action": "message.update",
-  "version": "01826232498871-001@abcdefghij:001",
-  "timestamp": new Date("2024-11-21T15:49:25.425Z"),
-  "operation": {
+  "version": {
+    "serial": "01826232498871-001@abcdefghij:001",
+    "timestamp": new Date("2024-11-21T15:49:25.425Z"),
     "clientId": "basketLover014",
     "description": "Message updated by client",
     "metadata": {}
-  },
+  }
 }
 ```
 </Code>
 
 The updated message response is identical to the structure of a message, with the following differences:
 
-| Property | Description |
-| -------- | ----------- |
-| action | Set to `message.update`. |
-| version | Set to the serial of the update action. |
-| timestamp | Set to the time the message was updated. |
-| operation | Set to the details the actioning client provided in the request. |
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| action | Set to `message.update`. | string |
+| version | Contains additional fields compared to `message.create` action: | object |
+| | `serial`: Set to the serial of the update action. | string |
+| | `timestamp`: Set to the time the message was updated. | Date |
+| | `clientId`: The client identifier of the user who performed the update. | String or undefined |
+| | `description`: Optional description provided in the update request. | String or undefined |
+| | `metadata`: Optional metadata provided in the update request.  | Object or undefined |
 
 ## Delete a message <a id="delete"/>
 
@@ -489,7 +493,6 @@ Use the [`useMessages`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typed
 <Code>
 ```javascript
 import { ChatMessageEventType } from '@ably/chat';
-
 const {unsubscribe} = room.messages.subscribe((event) => {
   switch (event.type) {
     case ChatMessageEventType.Created:
@@ -586,36 +589,39 @@ The following is the structure of a deleted message:
   "text": "",
   "headers": {},
   "metadata": {},
-  "createdAt": new Date("2024-06-12T11:37:59.988Z"),
+  "timestamp": new Date("2024-06-12T11:37:59.988Z"),
   "action": "message.delete",
-  "version": "01826232498871-001@abcdefghij:001",
-  "timestamp": new Date("2024-11-21T15:49:25.425Z"),
-  "operation": {
+  "version": {
+    "serial": "01826232498871-001@abcdefghij:001",
+    "timestamp": new Date("2024-11-21T15:49:25.425Z"),
     "clientId": "basketLover014",
     "description": "Message deleted by client",
     "metadata": {}
-  },
+  }
 }
 ```
 </Code>
 
 The deleted message response is identical to the structure of a message, with the following differences:
 
-| Property | Description |
-| -------- | ----------- |
-| action | Set to `message.delete`. |
-| version | Set to the serial of the deletion action. |
-| timestamp | Set to the time the message was deleted. |
-| operation | Set to the details the actioning client provided in the request. |
-| text | Set to the empty string. |
-| metadata | Set to the empty object. |
-| headers | Set to the empty object. |
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| action | Set to `message.delete`. | string |
+| version | Contains additional fields compared to `message.create` action: | object |
+| | `serial`: Set to the serial of the deletion action. | string |
+| | `timestamp`: Set to the time the message was deleted. | Date |
+| | `clientId`: The client identifier of the user who performed the deletion. | String or undefined |
+| | `description`: Optional description provided in the delete request. | String or undefined |
+| | `metadata`: Optional metadata provided in the delete request. | Object or undefined |
+| text | Set to the empty string. | string |
+| metadata | Set to the empty object. | Object |
+| headers | Set to the empty object. | Object |
 
 ## Ordering chat message events <a id="global-ordering"/>
 
 Chat messages and update events are delivered in realtime to clients connected to a particular region in the order in which that region receives them. The order in which a given region receives these events may be different from the "global" order of events, i.e. the true time-based order in which events happened.
 
-Chat messages are uniquely identified by their `serial` and may have multiple `versions` as a result of edit and delete operations. Both `serial` and `version` are lexicographically sortable strings. This means they can be used to enforce a deterministic global ordering based on string comparison.
+Chat messages are uniquely identified by their `serial` and may have multiple `versions` as a result of edit and delete operations. Both `serial` and `version.serial` are lexicographically sortable strings. This means they can be used to enforce a deterministic global ordering based on string comparison.
 
 ### Ordering new messages <a id="ordering-new"/>
 
@@ -625,15 +631,15 @@ The `Message` object also has convenience methods [`before`](https://sdk.ably.co
 
 ### Ordering updates and deletes <a id="ordering-update-delete"/>
 
-Applying an action to a message produces a new version, which is uniquely identified by the `version` property. When two message instances share the same `serial` they represent the same chat message, but they can represent different versions. Lexicographically sorting the two message instances by the `version` property gives the global order of the message versions: the message instance with a greater `version` is newer, the message instance with a lower `version` is older, and if their `version` is equal then they are the same version.
+Applying an action to a message produces a new version, which is uniquely identified by the `version.serial` property. When two message instances share the same `serial` they represent the same chat message, but they can represent different versions. Lexicographically sorting the two message instances by the `version.serial` property gives the global order of the message versions: the message instance with a greater `version.serial` is newer, the message instance with a lower `version.serial` is older, and if their `version.serial` is equal then they are the same version.
 
-The `Message` object also has convenience methods [`isOlderVersionOf`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html#isolderversionof), [`isNewerVersionOf`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html#isnewerversionof) and [`isSameVersionAs`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html#issameversionas) which provide the same comparison.
+The `Message` object also has convenience methods [`isOlderVersionOf`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html#isolderversionof), [`isNewerVersionOf`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html#isnewerversionof) and [`isSameVersionAs`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html#issameversionas) which provide the same comparison by comparing the `version.serial` values internally.
 
 Update and Delete events provide the message payload without message reactions. To correctly use message reactions, always use the [`with()`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html#with) method to apply the event to the message instance.
 
 ## Keep messages updated using with() <a id="keep-messages-updated"/>
 
-The [`Message`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html) object has a method [`with`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html#with) that takes a [`MessageEvent`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageEvent.html), automatically compares versions, and returns the newest `Message` instance. For updates and deletes, if `with` is called with an event that is older than the message, the message is returned. If it is called with a newer event, the message from the event is returned. For message reaction events, the reactions will be correctly applied to the returned message.
+The [`Message`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html) object has a method [`with`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Message.html#with) that takes a [`MessageEvent`](https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageEvent.html), automatically compares version serials, and returns the newest `Message` instance. For updates and deletes, if `message.with(event)` is called with an `event` that has an older `version.serial` than the `message`, then the `message` is returned unchanged. If it is called with a newer event (greater `version.serial`), then the message from the event is returned. For message reaction events, the reactions will be correctly applied to the returned message.
 
 `Message.with()` also ensures that reactions from existing messages are copied over to the new message instance in the case of UPDATEs or DELETEs.