Docs for realtime update/delete, new return type, adding append, and rest api changes for public preview release

src/components/Layout/mdx/Admonition.tsx

@@ -3,7 +3,7 @@ import cn from '@ably/ui/core/utils/cn';
 import Aside from 'src/components/blocks/dividers/Aside';
 import { HtmlComponentPropsData } from 'src/components/html-component-props';
 
-const LEGACY_ADMONITION_TYPES = ['new', 'updated', 'experimental'];
+const LEGACY_ADMONITION_TYPES = ['new', 'updated', 'experimental', 'public-preview'];
 
 type AdmonitionVariant = 'neutral' | 'note' | 'further-reading' | 'important' | 'warning';
 

src/components/blocks/dividers/Aside.tsx

@@ -19,6 +19,7 @@ const versioningColors: { [key: string]: { bg: string; text: string } } = {
   new: { bg: '#FFF0BA', text: '#AC8600' },
   updated: { bg: '#FFB8F1', text: '#9C007E' },
   experimental: { bg: '#D8BCFB', text: '#460894' },
+  'public-preview': { bg: '#B8E6FF', text: '#005A8C' },
 };
 
 const Aside = ({ data, attribs }: HtmlComponentProps<'div'>) => {

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

@@ -824,6 +824,8 @@ Failure to retrieve the message history will trigger the `errback` callbacks of
 
 Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities).
 
+See [updating and deleting messages: retrieving the latest version](/docs/messages/updates-deletes#get) for more information.
+
 ##### Parameters
 
 | Parameter | Description | Type |
@@ -836,51 +838,68 @@ Returns a promise which, upon success, will be fulfilled with a [`Message`](/doc
 
 #### updateMessage
 
-`updateMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<void>`
+`updateMessage(message: Message, operation?: MessageOperation): Promise<UpdateDeleteResult>`
 
-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).
+Publishes an update to an existing message with shallow mixin 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.
+See [updating and deleting messages: updates](/docs/messages/updates-deletes#update) 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. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error.
+Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new 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.
 
 #### deleteMessage
 
-`deleteMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<void>`
+`deleteMessage(message: Message, operation?: MessageOperation): Promise<UpdateDeleteResult>`
 
-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).
+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 shallow mixin 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.
+See [updating and deleting messages: deletes](/docs/messages/updates-deletes#delete) 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. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error.
+Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new 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.
+
+#### appendMessage
+
+`appendMessage(message: Message, operation?: MessageOperation): Promise<UpdateDeleteResult>`
+
+Appends data to an existing message. The supplied `data` field is appended to the previous message's data, while all other fields (`name`, `extras`) replace the previous values if provided. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities).
+
+See [updating and deleting messages: appends](/docs/messages/updates-deletes#append) for more information.
+
+##### Parameters
+
+| Parameter | Description | Type |
+|-----------|-------------|------|
+| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the data to append | [`Message`](/docs/api/realtime-sdk/messages) |
+| operation | An optional `MessageOperation` object containing metadata about the append operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) |
+
+##### Returns
+
+Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new 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.
 
 #### 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.
+See [updating and deleting messages: message versions](/docs/messages/updates-deletes#versions) for more information.
 
 ##### Parameters
 

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

@@ -432,7 +432,7 @@ This will typically be empty as all messages received from Ably are automaticall
 
 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 }`_
+_Type: `int enum { MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, META, MESSAGE_SUMMARY, MESSAGE_APPEND }`_
 
 ### serial <a id="#serial" />
 
@@ -498,6 +498,7 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects
       'message.delete',
       'meta',
       'message.summary'
+      'message.append',
   ]
 ```
 </Code>
@@ -513,6 +514,7 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects
       'message.delete',
       'meta',
       'message.summary'
+      'message.append',
   ]
 ```
 </Code>
@@ -530,6 +532,7 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects
     MESSAGE_DELETE,  // 2
     META,            // 3
     MESSAGE_SUMMARY  // 4
+    MESSAGE_APPEND,  // 5
   }
 ```
 </Code>
@@ -549,6 +552,7 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects
       ARTMessageActionDelete,
       ARTMessageActionMeta,
       ARTMessageActionMessageSummary
+      ARTMessageActionAppend,
   };
 ```
 </Code>
@@ -564,6 +568,7 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects
     case Delete
     case Meta
     case Summary
+    case Append
   }
 ```
 </Code>
@@ -580,6 +585,26 @@ An `Array` of [`Message`](/docs/api/realtime-sdk/types#message) objects
 |----------|-------------|------|
 | summary | An object whose keys are annotation types, and the values are aggregated summaries for that annotation type | `Record<String, JsonObject>` |
 
+### PublishResult <a id="publish-result" />
+
+Contains the result of a publish operation.
+
+#### <If lang="javascript,nodejs,csharp,flutter,objc,swift,go">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>
+
+| Property | Description | Type |
+|----------|-------------|------|
+| <If lang="javascript,nodejs,java,objc,swift,ruby,python,flutter">serials</If><If lang="csharp,go">Serials</If> | An array of message serials corresponding 1:1 to the messages that were published. A serial may be null if the message was discarded due to a configured conflation rule. | `String[]` |
+
+### UpdateDeleteResult <a id="update-delete-result" />
+
+Contains the result of an update, delete, or append message operation.
+
+#### <If lang="javascript,nodejs,csharp,flutter,objc,swift,go">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>
+
+| Property | Description | Type |
+|----------|-------------|------|
+| <If lang="javascript,nodejs,java,objc,swift,ruby,python,flutter">versionSerial</If><If lang="csharp,go">VersionSerial</If> | The serial of the version of the updated, deleted, or appended message. Will be null if the message was superseded by a subsequent update before it could be published. | `String` |
+
 ### <If lang="javascript,nodejs,flutter,go">PresenceMessage</If><If lang="java">io.ably.lib.types.PresenceMessage</If><If lang="ruby">Ably::Models::PresenceMessage</If><If lang="objc,swift">ARTPresenceMessage</If><If lang="csharp">IO.Ably.PresenceMessage</If> <a id="#presence-message" />
 
 A `PresenceMessage` represents an individual presence update that is sent to or received from Ably.

src/pages/docs/api/rest-api.mdx

@@ -682,24 +682,27 @@ See [MessageAction](/docs/api/realtime-sdk/types#message-action) for the possibl
 
 An unsuccessful request returns an error. A 404 error is returned if a message with that serial does not exist.
 
-### Update a message <a id="update-message" />
+### Update, delete, or append to a message <a id="update-message" />
 
 #### PATCH main.realtime.ably.net/channels/\<channelId\>/messages/\<serial\>
 
-Update an existing message on a channel, the message with the specified serial. This endpoint requires that the channel is configured with the "Message annotations, updates, and deletes" channel rule.
+Update, delete, or append to an existing message on a channel, identified by its serial. This endpoint requires that the channel is configured with the "Message annotations, updates, and deletes" channel rule.
 
-See [Updating and deleting messages](/docs/messages/updates-deletes#update) for more information about message updates and field semantics.
+See [Updating and deleting messages](/docs/messages/updates-deletes) for more information about this feature.
 
-The request body contains the message fields to update, along with optional operation metadata. Any fields not specified will be left as their original values.
+The request body contains a Message object with an `action` field specifying the operation, the fields to update, and optional operation metadata in `version`. Any fields not specified will be left as their original values (shallow mixin semantics). For appends, the `data` field is concatenated to the existing message's data rather than replacing it.
+
+The `action` should be set to a [MessageAction](/docs/api/realtime-sdk/types#message-action) int enum: `MESSAGE_UPDATE` (1), `MESSAGE_DELETE` (2), or `MESSAGE_APPEND` (5).
 
 <Code>
 ```json
 {
+  action: <MessageAction int enum, 1|2|5>,
   name: <optional new event name>,
   data: <optional new message payload>,
   encoding: <optional encoding if data was encoded>,
   extras: <optional new extras field>,
-  operation: {
+  version: {
     clientId: <optional, client id performing the update>,
     description: <optional description of why the update was made>,
     metadata: <optional metadata object>
@@ -717,8 +720,9 @@ curl -X PATCH https://main.realtime.ably.net/channels/rest-example/messages/0182
  -H "Content-Type: application/json" \
  --data \
  '{
+   "action": 1,
    "data": "updated message content",
-   "operation": {
+   "version": {
      "description": "Fixed typo"
    }
  }'
@@ -735,116 +739,19 @@ curl -X PATCH https://main.realtime.ably.net/channels/rest-example/messages/0182
 
 ##### Capabilities
 
-- `message-update-own` := Can update your own messages (messages where the original publisher's `clientId` matches the updater's `clientId`, where both are [identified](/docs/auth/identified-clients))
-- `message-update-any` := Can update any message on the channel
+- `message-update-own` := Can update or append to your own messages (messages where the original publisher's `clientId` matches the updater's `clientId`, where both are [identified](/docs/auth/identified-clients))
+- `message-update-any` := Can update or append to any message on the channel
+- `message-delete-own` := Can delete your own messages
+- `message-delete-any` := Can delete any message on the channel
 
 ##### Returns
 
-A successful request returns the updated @Message@ object with the new version information.
-
-See [MessageAction](/docs/api/realtime-sdk/types#message-action) for the possible values of the `action` enum.
+Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result), an object with a single `versionSerial` field: the serial of the version of the updated, deleted, or appended message, or `null` if the message was superseded by a subsequent update before it could be published.
 
 <Code>
 ```json
 {
-  serial: <permanent message serial identifier>,
-  name: <event name>,
-  data: <updated message payload>,
-  timestamp: <original message timestamp in ms since epoch>,
-  clientId: <client id of original publisher>,
-  action: <MessageAction int enum>,
-  version: {
-    serial: <new version serial identifier>,
-    clientId: <client id of user who made the update>,
-    timestamp: <update timestamp in ms since epoch>,
-    description: <description of the operation if provided>,
-    metadata: <metadata object if provided>
-  }
-}
-```
-</Code>
-
-An unsuccessful request returns an error.
-
-### Delete a message <a id="delete-message" />
-
-#### POST main.realtime.ably.net/channels/\<channelId\>/messages/\<serial\>/delete
-
-Delete a message on a channel, the message with the specified serial. This is a 'soft' delete that publishes a new version of the message with an action of `message.delete`. The full message history remains accessible through the [message versions](message-versions) endpoint. This endpoint requires that the channel is configured with the "Message annotations, updates, and deletes" channel rule.
-
-See [Updating and deleting messages](/docs/messages/updates-deletes#update) for more information about message updates and field semantics.
-
-The request body contains the message fields to update, along with optional operation metadata. Any fields not specified will be left as their original values.
-
-<Code>
-```json
-{
-  name: <optional new event name for the deleted version>,
-  data: <optional new data for the deleted version>,
-  encoding: <optional encoding if data was encoded>,
-  extras: <optional new extras field>,
-  operation: {
-    clientId: <optional, client id performing the delete>,
-    description: <optional description of why the delete was made>,
-    metadata: <optional metadata object>
-  }
-}
-```
-</Code>
-
-Example request:
-
-<Code>
-```shell
-curl -X POST https://main.realtime.ably.net/channels/rest-example/messages/01826232498871-001@abcdefghij:001/delete \
- -u "{{API_KEY}}" \
- -H "Content-Type: application/json" \
- --data \
- '{
-   "operation": {
-     "description": "Content violation"
-   }
- }'
-```
-</Code>
-
-##### Options
-
-| Property | Value |
-|----------|-------|
-| Content-Type | `application/json`, `application/x-msgpack` or `application/x-www-form-urlencoded` |
-| Accept | `application/json` by default, or `application/x-msgpack`, `text/html` |
-| Auth required | yes ([basic](basic-authentication) or [token](token-authentication) with `message-delete-own` or `message-delete-any` capability) |
-
-##### Capabilities
-
-| Capability | Description |
-|------------|-------------|
-| `message-delete-own` | Can delete your own messages (messages where the original publisher's `clientId` matches the deleter's `clientId`, where both are [identified](/docs/auth/identified-clients)) |
-| `message-delete-any` | Can delete any message on the channel |
-
-##### Returns
-
-A successful request returns the updated `Message` object with `action` set to `message.delete`.
-
-See [MessageAction](/docs/api/realtime-sdk/types#message-action) for the possible values of the `action` enum.
-
-<Code>
-```shell
-{
-  serial: <permanent message serial identifier>,
-  name: <event name if provided>,
-  data: <data if provided>,
-  timestamp: <original message timestamp in ms since epoch>,
-  clientId: <client id of original publisher>,
-  action: <MessageAction int enum>,
-  version: {
-    serial: <new version serial identifier>,
-    clientId: <client id of user who made the delete>,
-    timestamp: <delete timestamp in ms since epoch>,
-    description: <description of the operation if provided>,
-    metadata: <metadata object if provided>
-  }
+  "versionSerial": "01826232512345-002@abcdefghij:002"
 }
 ```
 </Code>