Docs for annotations

* Add annotations docs

* Add .claude to gitignore

* Update message / annotations docs for protocol v4 messages

* Add clipped flag to annotations doc

---------

Co-authored-by: Simon Woolf <[email protected]>
Co-authored-by: Vlad Velici <[email protected]>

Author: 3 people

.gitignore

@@ -22,3 +22,4 @@ config/nginx-redirects.conf
 src/gatsby-types.d.ts
 .idea/*
 **/*.swp
+.claude

content/api/realtime-sdk/messages.textile

@@ -25,3 +25,8 @@ h2(#properties).
   python:  Attributes
 
 <%= partial partial_version('types/_message') %>
+
+h2(#message-annotations).
+  default: MessageAnnotations
+
+<%= partial partial_version('types/_message_annotations') %>

content/api/realtime-sdk/types.textile

@@ -87,10 +87,10 @@ blang[jsall].
 
   <%= partial partial_version('types/_message_action') %>
 
-  h3(#message-operation).
-    default: Operation
+h3(#message-annotations).
+  default: MessageAnnotations
 
-  <%= partial partial_version('types/_operation') %>
+<%= partial partial_version('types/_message_annotations') %>
 
 h3(#presence-message).
   default: PresenceMessage

content/partials/core-features/_authentication_capabilities.textile

@@ -5,6 +5,8 @@ The following capability operations are available for API keys and issued tokens
 - presence := can register presence on a channel (enter, update and leave)
 - object-subscribe := can subscribe to updates to objects on a channel
 - object-publish := can update objects on a channel
+- annotation-subscribe := can subscribe to individual annotations on a channel
+- annotation-publish := can publish annotations to messages on a channel
 - history := can retrieve message and presence state history on channels
 - stats := can retrieve current and historical usage statistics for an app
 - push-subscribe := can subscribe devices for push notifications

content/partials/types/_message.textile

@@ -51,7 +51,7 @@ h6(#timestamp).
   default: timestamp
   csharp: Timestamp
 
-Timestamp when the message was received by the Ably, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>.__Type: <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>__
+Timestamp when the message was first received by the Ably, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>.__Type: <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>__
 
 h6(#encoding).
   default: encoding
@@ -69,22 +69,12 @@ blang[jsall].
   h6(#serial).
     default: serial
 
-  This message's unique serial (an identifier that will be the same in all future updates of this message).<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 to a message. Serial will only be set if you enable annotations in "channel rules":/docs/channels#rules .<br>__Type: @String@__
 
-  h6(#created-at).
-    default: createdAt
+  h6(#annotations).
+    default: annotations
 
-  The timestamp of the very first version of a given message (will differ from @timestamp@ only if the message has been updated or deleted).<br>__Type: @Integer@__
-
-  h6(#version).
-    default: version
-
-  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.<br>__Type: @String@__
-
-  h6(#operation).
-    default: operation
-
-  In the case of an updated or deleted message, this will contain metadata about the update or delete operation.<br>__Type: "@Operation@":/docs/api/realtime-sdk/types#message-operation__
+  An object containing information about annotations that have been made to the object.<br>__Type: "@MessageAnnotations@":/docs/api/realtime-sdk/types#message-annotations__
 
 h3(constructors).
   default: Message constructors

content/partials/types/_message_annotations.textile

@@ -0,0 +1,7 @@
+h4.
+  default: Properties
+  java:    Members
+  ruby:    Attributes
+  python:  Attributes
+
+- <span lang="default">summary</span> := An object whose keys are annotation types, and the values are aggregated summaries for that annotation type<br>__Type: @Record<String, JsonObject>@__

content/partials/types/_operation.textile

@@ -195,6 +195,10 @@ export default {
           name: 'Message batching',
           link: '/docs/messages/batch',
         },
+        {
+          name: 'Message annotations',
+          link: '/docs/messages/annotations',
+        },
       ],
     },
     {

src/data/nav/pubsub.ts

@@ -40,6 +40,8 @@ The following capability operations are available for API keys and issued tokens
 | **presence** | Can register presence on a channel (enter, update and leave) |
 | **object-subscribe** | Can subscribe to updates to objects on a channel |
 | **object-publish** | Can update objects on a channel |
+| **annotation-subscribe** | Can subscribe to individual annotations on a channel |
+| **annotation-publish** | Can publish annotations to messages on a channel |
 | **history** | Can retrieve message and presence state history on channels |
 | **stats** | Can retrieve current and historical usage statistics for an app |
 | **push-subscribe** | Can subscribe devices for push notifications |

src/pages/docs/auth/capabilities.mdx

@@ -200,6 +200,7 @@ The channel rules related to enabling features are:
 | Push notifications enabled | If checked, publishing messages with a push payload in the `extras` field is permitted. This triggers the delivery of a [Push Notification](/docs/push) to devices registered for push on the channel. |
 | Server-side batching | If enabled, messages are grouped into batches before being sent to subscribers. [Server-side batching](/docs/messages/batch#server-side) reduces the overall message count, lowers costs, and mitigates the risk of hitting rate limits during high-throughput scenarios. |
 | Message conflation | If enabled, messages are aggregated over a set period of time and evaluated against a conflation key. All but the latest message for each conflation key value will be discarded, and the resulting message, or messages, will be delivered to subscribers as a single batch once the period of time elapses. [Message conflation](/docs/messages#conflation) reduces costs in high-throughput scenarios by removing redundant and outdated messages. |
+| Message annotations, updates, and deletes | If enabled, allows message "annotations":/docs/messages/annotations to be used, as well as updates and deletes to be published to messages. Note that these features are currently Experimental, still in development, and subject to change. When this feature is enabled, messages will be "persisted":/docs/storage-history/storage#all-message-persistence (necessary in order from them later be annotated or updated), and "continuous history":/docs/storage-history/history#continuous-history features will not work.
 
 To set a channel rule in the Ably dashboard: