Feature/pub 1765 annotations examples

examples/liveobjects-live-counter/javascript/README.md

@@ -1,4 +1,4 @@
-# Synchronizing numeric values with LiveCounter
+# Synchronize numeric values with LiveCounter
 
 Enable clients to update and synchronize numerical values in an application in realtime.
 
@@ -25,35 +25,35 @@ Find out more about [LiveCounter](/docs/liveobjects/counter).
 
 1. Clone the [Ably docs](https://github.com/ably/docs) repository where this example can be found:
 
-```sh
-git clone [email protected]:ably/docs.git
-```
+  ```sh
+  git clone [email protected]:ably/docs.git
+  ```
 
 2. Change directory:
 
-```sh
-cd /examples/
-```
+  ```sh
+  cd /examples/
+  ```
 
 3. Rename the environment file:
 
-```sh
-mv .env.example .env.local
-```
+  ```sh
+  mv .env.example .env.local
+  ```
 
 4. In `.env.local` update the value of `VITE_ABLY_KEY` to be your Ably API key.
 
 5. Install dependencies:
 
-```sh
-yarn install
-```
+  ```sh
+  yarn install
+  ```
 
 6. Run the server:
 
-```sh
-yarn run liveobjects-live-counter-javascript
-```
+  ```sh
+  yarn run liveobjects-live-counter-javascript
+  ```
 
 7. Try it out by opening two tabs to [http://localhost:5173/](http://localhost:5173/) with your browser to see the result.
 

examples/liveobjects-live-map/javascript/README.md

@@ -1,4 +1,4 @@
-# Synchronizing key/value map data structures with LiveMap
+# Synchronize key/value map data structures with LiveMap
 
 Enable clients to update and synchronize key/value data in an application in realtime.
 
@@ -25,35 +25,35 @@ Find out more about [LiveMap](/docs/liveobjects/map).
 
 1. Clone the [Ably docs](https://github.com/ably/docs) repository where this example can be found:
 
-```sh
-git clone [email protected]:ably/docs.git
-```
+  ```sh
+  git clone [email protected]:ably/docs.git
+  ```
 
 2. Change directory:
 
-```sh
-cd /examples/
-```
+  ```sh
+  cd /examples/
+  ```
 
 3. Rename the environment file:
 
-```sh
-mv .env.example .env.local
-```
+  ```sh
+  mv .env.example .env.local
+  ```
 
 4. In `.env.local` update the value of `VITE_ABLY_KEY` to be your Ably API key.
 
 5. Install dependencies:
 
-```sh
-yarn install
-```
+  ```sh
+  yarn install
+  ```
 
 6. Run the server:
 
-```sh
-yarn run liveobjects-live-map-javascript
-```
+  ```sh
+  yarn run liveobjects-live-map-javascript
+  ```
 
 7. Try it out by opening two tabs to [http://localhost:5173/](http://localhost:5173/) with your browser to see the result.
 

examples/package.json

@@ -43,6 +43,7 @@
     "pub-sub-presence/javascript",
     "pub-sub-rewind/react",
     "pub-sub-rewind/javascript",
+    "pub-sub-message-annotations/javascript",
     "spaces-avatar-stack/react",
     "spaces-avatar-stack/javascript",
     "spaces-component-locking/react",
@@ -90,6 +91,7 @@
     "pub-sub-presence-react": "yarn workspace pub-sub-presence-react dev",
     "pub-sub-rewind-javascript": "yarn workspace pub-sub-rewind-javascript dev",
     "pub-sub-rewind-react": "yarn workspace pub-sub-rewind-react dev",
+    "pub-sub-message-annotations-javascript": "yarn workspace pub-sub-message-annotations-javascript dev",
     "spaces-avatar-stack-javascript": "yarn workspace spaces-avatar-stack-javascript dev",
     "spaces-avatar-stack-react": "yarn workspace spaces-avatar-stack-react dev",
     "spaces-component-locking-javascript": "yarn workspace spaces-component-locking-javascript dev",
@@ -103,7 +105,7 @@
     "@ably/chat": "^0.14.0",
     "@ably/chat-react-ui-components": "^0.1.2",
     "@ably/spaces": "^0.4.0",
-    "ably": "^2.9.0",
+    "ably": "^2.13.0",
     "cors": "^2.8.5",
     "franken-ui": "^2.0.0",
     "minifaker": "^1.34.1",

examples/pub-sub-message-annotations/javascript/.gitignore

@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

examples/pub-sub-message-annotations/javascript/README.md

@@ -0,0 +1,87 @@
+# Adding annotations to messages with Pub/Sub
+
+Enable users to annotate messages with additional data, such as reactions, flags, or other contextual information without modifying the original message content.
+
+Message annotations provide a powerful way to extend messages with additional information. Unlike editing a message, annotations allow multiple clients to add their own metadata while preserving the original message. This is ideal for implementing features like reactions, content categorization, moderation flags, or any other metadata that enhances message context.
+
+Message annotations are implemented using [Ably Pub/Sub](/docs/channels). The Pub/Sub SDK with annotations provides a way to add structured metadata to messages, with support for different annotation types and automatic summarization.
+
+## Resources
+
+Use the following methods to work with message annotations in a pub/sub application:
+
+- [`channels.get()`](/docs/channels#create) - creates a new or retrieves an existing `channel`. Specify the `ANNOTATION_PUBLISH` and `ANNOTATION_SUBSCRIBE` modes to publish and subscribe to message annotations.
+- [`channel.subscribe()`](/docs/pub-sub#subscribe) - subscribes to message events within a specific channel by registering a listener. Message events with a `message.create` action are received when a user publishes a message. Message events with a `message.summary` action are received when a user publishes or deletes an annotation.
+<!-- TODO links -->
+- `channel.annotations.publish()` - publishes an annotation for a specific message
+- `channel.annotations.subscribe()` - subscribes to receive individual annotation events
+- `channel.annotations.delete()` - deletes a previously published annotation
+
+<!-- TODO link -->
+Find out more about annotations.
+
+## Annotation Types
+
+This example demonstrates five common annotation types, each suited to different use cases:
+
+<!-- TODO -->
+
+## Features
+
+This example demonstrates:
+
+1. Publishing regular messages to a channel
+2. Adding different types of annotations to messages
+3. Viewing both summarized and raw annotation data
+4. Deleting annotations
+
+## Getting started
+
+1. Clone the [Ably docs](https://github.com/ably/docs) repository where this example can be found:
+
+  ```sh
+  git clone [email protected]:ably/docs.git
+  ```
+
+2. Change directory:
+
+  ```sh
+  cd /examples/
+  ```
+
+3. Rename the environment file:
+
+  ```sh
+  mv .env.example .env.local
+  ```
+
+4. In `.env.local` update the value of `VITE_ABLY_KEY` to be your Ably API key.
+
+5. Install dependencies:
+
+  ```sh
+  yarn install
+  ```
+
+6. Enable the "Annotations, updates and deletes" channel rule that matches the channel name you'll be using (by default we use a channel name of `annotation:pub-sub-message-annotations`, so if using this, [create this rule](https://ably.com/docs/channels#rules) for the "annotation" channel namespace).
+
+7. Run the server:
+
+  ```sh
+  yarn run pub-sub-message-annotations-javascript
+  ```
+
+8. Try it out by opening two tabs to [http://localhost:5173/](http://localhost:5173/) with your browser to see the result. Specify different client IDs in the URL (e.g., `?clientId=user1` and `?clientId=user2`) to see how annotations from different clients are handled and summarized
+
+## How to use this example
+
+1. Enter a message in the input field and click "Publish" to send it to the channel
+2. Click on a message to expand it and reveal the annotation interface
+3. Select an annotation type, enter a value, and click "Publish" to add an annotation
+4. Switch between the "Summary" and "Raw Annotations" tabs to see different views
+5. Open the example in multiple browser tabs with different client IDs (e.g., `?clientId=user1` and `?clientId=user2`) to see how annotations from different clients are handled and summarized
+6. Delete annotations by clicking the trash icon in the raw annotations view and see how the summary is updated
+
+## Open in CodeSandbox
+
+In CodeSandbox, rename the `.env.example` file to `.env.local` and update the value of your `VITE_ABLY_KEY` variable to use your Ably API key.

examples/pub-sub-message-annotations/javascript/index.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link href='https://fonts.googleapis.com/css?family=Inter' rel='stylesheet'>
+  <link rel="stylesheet" href="src/styles.css" />
+  <title>Pub/Sub message annotations</title>
+</head>
+
+<body class="font-inter">
+  <div class="flex justify-center items-start min-h-screen p-4 uk-text-primary">
+    <div class="w-full max-w-screen-sm mt-5 flex flex-col space-y-4">
+      <div class="flex space-x-2">
+        <input id="message-input" placeholder="Publish a message" class="uk-input uk-width-1-1 uk-border-rounded-left h-10 border rounded-md px-3 bg-white" type="text" value="">
+        <button id="publish-button" class="uk-btn uk-btn-sm uk-btn-primary mb-1 rounded-md hover:uk-btn-primary+1 active:uk-btn-primary+2 h-10">Publish</button>
+      </div>
+      <div id="messages"></div>
+    </div>
+  </div>
+  <script type="module" src="src/script.ts"></script>
+</body>
+
+</html>

examples/pub-sub-message-annotations/javascript/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "pub-sub-message-annotations-javascript",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  }
+}

examples/pub-sub-message-annotations/javascript/src/ably.ts

@@ -0,0 +1,33 @@
+import * as Ably from 'ably';
+import { clientId, channelName } from './config';
+
+// Singleton Ably client instance
+let client: Ably.Realtime | null = null;
+
+// Lazily creates and returns the Ably client instance with configured clientId
+function getClient(): Ably.Realtime {
+  if (!client) {
+    client = new Ably.Realtime({
+      clientId,
+      key: import.meta.env.VITE_ABLY_KEY as string,
+    });
+  }
+  return client;
+}
+
+// Returns the configured channel with all annotation modes enabled
+export function getChannel() {
+  return getClient().channels.get(`${channelName}`, {
+    modes: ['PUBLISH', 'SUBSCRIBE', 'ANNOTATION_PUBLISH', 'ANNOTATION_SUBSCRIBE'],
+  });
+}
+
+// Publishes a new annotation for a specific message
+export function publishAnnotation(message: Ably.InboundMessage, annotation: Ably.OutboundAnnotation) {
+  return getChannel().annotations.publish(message, annotation);
+}
+
+// Deletes a specific annotation from a message
+export function deleteAnnotation(messageSerial: string, annotation: Ably.OutboundAnnotation) {
+  return getChannel().annotations.delete(messageSerial, annotation);
+}