Updates deletes

content/partials/types/_message.textile

@@ -64,18 +64,23 @@ blang[jsall].
   h6(#action).
     default: action
 
-  The action type of the message, one of the "@MessageAction@":/docs/api/realtime-sdk/types#message-action enum values.<br>__Type: @int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }@__
+  The action type of the message, one of the "@MessageAction@":#message-action enum values.<br>__Type: @int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }@__
 
   h6(#serial).
     default: serial
 
-  A server-assigned identifier that will be the same in all future updates of this message. It  can be used to add annotations to a message. Serial will only be set if you enable annotations in "channel rules":/docs/channels#rules .<br>__Type: @String@__
+  A server-assigned identifier that will be the same in all future updates of this message. It can be used to add "annotations":/docs/messages/annotations to a message or to "update or delete":/docs/messages/updates-deletes it. Serial will only be set if you enable annotations, updates, and deletes in "channel rules":/docs/channels#rules .<br>__Type: @String@__
 
   h6(#annotations).
     default: annotations
 
   An object containing information about annotations that have been made to the object.<br>__Type: "@MessageAnnotations@":/docs/api/realtime-sdk/types#message-annotations__
 
+  h6(#version).
+    default: version
+
+  An object containing version metadata for messages that have been updated or deleted. See "updating and deleting messages":/docs/messages/updates-deletes for more information.<br>__Type: "@MessageVersion@":#message-version__
+
 h3(constructors).
   default: Message constructors
 
@@ -112,3 +117,15 @@ h4. Parameters
 h4. Returns
 
 An @Array@ of "@Message@":/docs/api/realtime-sdk/types#message objects
+
+h3(#message-version).
+  default: MessageVersion
+
+h4. Properties
+
+|_. Property |_. Description |_. Type |
+| serial | An Ably-generated ID that uniquely identifies this version of the message. Can be compared lexicographically to determine version ordering. For an original message with an action of @message.create@, this will be equal to the top-level @serial@. | @String@ |
+| timestamp | The time this version was created (when the update or delete operation was performed). For an original message, this will be equal to the top-level @timestamp@. | <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span> |
+| clientId | The client identifier of the user who performed the update or delete operation. Only present for @message.update@ and @message.delete@ actions. | @String@ (optional) |
+| description | Optional description provided when the update or delete was performed. Only present for @message.update@ and @message.delete@ actions. | @String@ (optional) |
+| metadata | Optional metadata provided when the update or delete was performed. Only present for @message.update@ and @message.delete@ actions. | @Object@ (optional) |

content/partials/types/_message_action.textile

@@ -1,11 +1,61 @@
-@Message@ @action@ is a String representing the action type of the message.
+blang[default].
+  @MessageAction@ is an enum representing the action type of the message.
 
-```[javascript]
-  const MessageActions = [
+  ```
+    enum MessageAction {
+      MESSAGE_CREATE,  // 0
+      MESSAGE_UPDATE,  // 1
+      MESSAGE_DELETE,  // 2
+      META,            // 3
+      MESSAGE_SUMMARY  // 4
+    }
+  ```
+
+blang[jsall].
+  @Message@ @action@ is a String representing the action type of the message.
+
+  ```[javascript]
+    var MessageActions = [
       'message.create',
       'message.update',
       'message.delete',
       'meta',
       'message.summary'
-  ]
-```
+    ]
+  ```
+
+blang[java].
+  @io.ably.lib.types.Message.Action@ is an enum representing the action type of the message.
+
+  ```[java]
+    public enum Action {
+      MESSAGE_CREATE,  // 0
+      MESSAGE_UPDATE,  // 1
+      MESSAGE_DELETE,  // 2
+      META,            // 3
+      MESSAGE_SUMMARY  // 4
+    }
+  ```
+
+blang[objc,swift].
+  @ARTMessageAction@ is an enum representing the action type of the message.
+
+  ```[objc]
+    typedef NS_ENUM(NSUInteger, ARTMessageAction) {
+        ARTMessageActionCreate,
+        ARTMessageActionUpdate,
+        ARTMessageActionDelete,
+        ARTMessageActionMeta,
+        ARTMessageActionMessageSummary
+    };
+  ```
+
+  ```[swift]
+    enum ARTMessageAction : UInt {
+      case Create
+      case Update
+      case Delete
+      case Meta
+      case Summary
+    }
+  ```

src/data/nav/pubsub.ts

@@ -199,6 +199,10 @@ export default {
           name: 'Message annotations',
           link: '/docs/messages/annotations',
         },
+        {
+          name: 'Updates and deletes',
+          link: '/docs/messages/updates-deletes',
+        },
       ],
     },
     {

src/pages/docs/api/realtime-sdk/channels.mdx

@@ -816,6 +816,85 @@ Failure to retrieve the message history will trigger the `errback` callbacks of
 
 </If>
 
+<If lang="javascript,nodejs">
+
+#### getMessage
+
+`getMessage(serialOrMessage: string | Message): Promise<Message>`
+
+Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities).
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| serialOrMessage | Either the serial identifier string of the message to retrieve, or a [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](/docs/api/realtime-sdk/messages) |
+
+##### Returns
+
+Returns a promise which, upon success, will be fulfilled with a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error.
+
+#### updateMessage
+
+`updateMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<Message>`
+
+Publishes an update to an existing message with patch semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities).
+
+See [updating and deleting messages](/docs/messages/updates-deletes) for more information.
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the fields to update | [`Message`](/docs/api/realtime-sdk/messages) |
+| operation | An optional `MessageOperation` object containing metadata about the update operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) |
+| params | Optional parameters sent as part of the query string | `Record<string, any>` (optional) |
+
+##### Returns
+
+Returns a promise which, upon success, will be fulfilled with a [`Message`](/docs/api/realtime-sdk/messages) object containing the updated message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error.
+
+#### deleteMessage
+
+`deleteMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<Message>`
+
+Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses patch semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-delete-own** or **message-delete-any** [capability](/docs/auth/capabilities).
+
+See [updating and deleting messages](/docs/messages/updates-deletes) for more information.
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | [`Message`](/docs/api/realtime-sdk/messages) |
+| operation | An optional `MessageOperation` object containing metadata about the delete operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) |
+| params | Optional parameters sent as part of the query string | `Record<string, any>` (optional) |
+
+##### Returns
+
+Returns a promise which, upon success, will be fulfilled with a [`Message`](/docs/api/realtime-sdk/messages) object containing the deleted message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error.
+
+#### getMessageVersions
+
+`getMessageVersions(serialOrMessage: string | Message, params?: Record<string, any>): Promise<PaginatedResult<Message>>`
+
+Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/auth/capabilities).
+
+See [updating and deleting messages](/docs/messages/updates-deletes) for more information.
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| serialOrMessage | Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](/docs/api/realtime-sdk/messages) |
+| params | Optional parameters sent as part of the query string | `Record<string, any>` (optional) |
+
+##### Returns
+
+Returns a promise which, upon success, will be fulfilled with a [`PaginatedResult`](#paginated-result) object containing an array of [`Message`](/docs/api/realtime-sdk/messages) objects representing all versions of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error.
+
+</If>
+
 <If lang="javascript,nodejs">
 #### setOptions
 
@@ -1847,22 +1926,23 @@ Timestamp when the message was first received by the Ably, as <If lang="javascri
 This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.
 **Type: `String`**
 
-<If lang="javascript,nodejs">
+<If lang="javascript,nodejs,objc,swift,java">
 
-#### action
+### action <a id="action" />
 
-The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values.
-**Type: `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }`**
+The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values.<br />_Type: `enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }`_
 
-#### serial
+### serial <a id="serial" />
 
-A server-assigned identifier that will be the same in all future updates of this message. It can be used to add annotations to a message. Serial will only be set if you enable annotations in [channel rules](/docs/channels#rules).
-**Type: `String`**
+A server-assigned identifier that will be the same in all future updates of this message. It can be used to add [annotations](/docs/messages/annotations) to a message or to [update or delete](/docs/messages/updates-deletes) it. Serial will only be set if you enable annotations, updates, and deletes in [channel rules](/docs/channels#rules).<br />_Type: `String`_
+
+### annotations <a id="annotations" />
+
+An object containing information about annotations that have been made to the object.<br />_Type: [`MessageAnnotations`](/docs/api/realtime-sdk/types#message-annotations)_
 
-#### annotations
+### version <a id="version" />
 
-An object containing information about annotations that have been made to the object.
-**Type: [`MessageAnnotations`](/docs/api/realtime-sdk/types#message-annotations)**
+An object containing version metadata for messages that have been updated or deleted. See [updating and deleting messages](/docs/messages/updates-deletes) for more information.<br />_Type: [`MessageVersion`](#message-version)_
 
 </If>
 

src/pages/docs/api/realtime-sdk/messages.mdx

@@ -48,20 +48,24 @@ Timestamp when the message was first received by the Ably, as <If lang="javascri
 
 This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the `data` payload.<br />_Type: `String`_
 
-<If lang="javascript,nodejs">
+<If lang="javascript,nodejs,objc,swift,java">
 
-### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">action</If> <a id="action" />
+### action <a id="action" />
 
-The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values.<br />_Type: `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }`_
+The action type of the message, one of the [`MessageAction`](/docs/api/realtime-sdk/types#message-action) enum values.<br />_Type: `enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY }`_
 
-### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">serial</If> <a id="serial" />
+### serial <a id="serial" />
 
-A server-assigned identifier that will be the same in all future updates of this message. It  can be used to add annotations to a message. Serial will only be set if you enable annotations in [channel rules](/docs/channels#rules).<br />_Type: `String`_
+A server-assigned identifier that will be the same in all future updates of this message. It can be used to add [annotations](/docs/messages/annotations) to a message or to [update or delete](/docs/messages/updates-deletes) it. Serial will only be set if you enable annotations, updates, and deletes in [channel rules](/docs/channels#rules).<br />_Type: `String`_
 
-### <If lang="javascript,nodejs,flutter,objc,swift,ruby,java">annotations</If> <a id="annotations" />
+### annotations <a id="annotations" />
 
 An object containing information about annotations that have been made to the object.<br />_Type: [`MessageAnnotations`](/docs/api/realtime-sdk/types#message-annotations)_
 
+### version <a id="version" />
+
+An object containing version metadata for messages that have been updated or deleted. See [updating and deleting messages](/docs/messages/updates-deletes) for more information.<br />_Type: [`MessageVersion`](#message-version)_
+
 </If>
 
 ### Message constructors <a id="constructors" />
@@ -107,3 +111,15 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects
 | Property | Description | Type |
 |----------|-------------|------|
 | summary | An object whose keys are annotation types, and the values are aggregated summaries for that annotation type | `Record<String, JsonObject>` |
+
+## MessageVersion <a id="message-version" />
+
+#### <If lang="javascript,nodejs,flutter,objc,csharp,swift">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>
+
+| Property | Description | Type |
+|----------|-------------|------|
+| serial | An Ably-generated ID that uniquely identifies this version of the message. Can be compared lexicographically to determine version ordering. For an original message with an action of `message.create`, this will be equal to the top-level `serial`. | `String` |
+| timestamp | The time this version was created (when the update or delete operation was performed). For an original message, this will be equal to the top-level `timestamp`. | <If lang="javascript,nodejs,flutter">`Integer`</If><If lang="java">`Long Integer`</If><If lang="csharp">`DateTimeOffset`</If><If lang="ruby">`Time`</If><If lang="objc,swift">`NSDate`</If> |
+| clientId | The client identifier of the user who performed the update or delete operation. Only present for `message.update` and `message.delete` actions. | `String` (optional) |
+| description | Optional description provided when the update or delete was performed. Only present for `message.update` and `message.delete` actions. | `String` (optional) |
+| metadata | Optional metadata provided when the update or delete was performed. Only present for `message.update` and `message.delete` actions. | `Object` (optional) |

src/pages/docs/api/realtime-sdk/types.mdx

@@ -480,9 +480,24 @@ A static factory method to create an array of [`Messages`](/docs/api/realtime-sd
 
 An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects
 
-<If lang="javascript,nodejs">
+### <If lang="javascript,nodejs,csharp,flutter,ruby,go">Message action</If><If lang="objc,swift">ARTMessageAction</If><If lang="java">io.ably.lib.types.Message.Action</If> <a id="message-action" />
 
-### Message action <a id="#message-action" />
+<If lang="csharp,flutter,ruby,go">
+
+<Code>
+```
+enum MessageAction {
+  MESSAGE_CREATE,  // 0
+  MESSAGE_UPDATE,  // 1
+  MESSAGE_DELETE,  // 2
+  META,            // 3
+  MESSAGE_SUMMARY  // 4
+}
+```
+</Code>
+
+</If>
+<If lang="javascript,nodejs">
 
 `Message` `action` is a String representing the action type of the message.
 
@@ -515,6 +530,57 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects
 ```
 </Code>
 
+</If>
+</If>
+<If lang="java">
+`io.ably.lib.types.Message.Action` is an enum representing the action type of the message.
+
+<Code>
+```java
+  public enum Action {
+    MESSAGE_CREATE,  // 0
+    MESSAGE_UPDATE,  // 1
+    MESSAGE_DELETE,  // 2
+    META,            // 3
+    MESSAGE_SUMMARY  // 4
+  }
+```
+</Code>
+
+</If>
+<If lang="objc,swift">
+
+`ARTMessageAction` is an enum representing the action type of the message.
+
+<If lang="objc">
+
+<Code>
+```objc
+  typedef NS_ENUM(NSUInteger, ARTMessageAction) {
+      ARTMessageActionCreate,
+      ARTMessageActionUpdate,
+      ARTMessageActionDelete,
+      ARTMessageActionMeta,
+      ARTMessageActionMessageSummary
+  };
+```
+</Code>
+
+</If>
+<If lang="swift">
+
+<Code>
+```swift
+  enum ARTMessageAction : UInt {
+    case Create
+    case Update
+    case Delete
+    case Meta
+    case Summary
+  }
+```
+</Code>
+
 </If>
 </If>