[DX-789] Implement pubsub message annotations by sacOO7 · Pull Request #148 · ably/ably-cli

sacOO7 · 2026-03-05T09:18:13Z

Need to merge Fix pubsub channels subscribe and history formatting #151 first
Fixes https://ably.atlassian.net/browse/DX-789

vercel · 2026-03-05T09:18:18Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cli-web-cli	Ready	Preview, Comment	Mar 6, 2026 9:42am

coderabbitai · 2026-03-05T09:18:24Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 93c2c3fc-6bdb-4e52-a5b2-462ead7bcb7e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feature/pubsub-message-annotations

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

- Updated CLAUDE.md to not truncate external markdown documentation # Conflicts: # .claude/CLAUDE.md

…pect to CLAUDE.md

ably channels annotations publish <channelName> <msgSerial> <annotationType> ably channels annotations delete <channelName> <msgSerial> <annotationType> ably channels annotations get <channelName> <msgSerial> ably channels annotations subscribe <channelName>

Copilot

Pull request overview

Adds Ably Channel Message Annotations support to the CLI (DX-789) by introducing new channels annotations subcommands plus supporting validation, mocks, and tests.

Changes:

Introduces new commands: channels annotations publish|delete|get|subscribe.
Adds shared annotation-type parsing/validation utilities.
Extends test mocks and adds unit + E2E coverage for the new commands.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`src/commands/channels/annotations.ts`	Adds `channels:annotations` topic command entry point.
`src/commands/channels/annotations/publish.ts`	Implements publishing annotations with param validation and JSON/human output.
`src/commands/channels/annotations/delete.ts`	Implements deleting annotations with param validation and JSON/human output.
`src/commands/channels/annotations/get.ts`	Implements fetching annotations for a message via REST.
`src/commands/channels/annotations/subscribe.ts`	Implements long-running subscription to annotation events with `--duration` support.
`src/utils/annotation-validation.ts`	Centralizes annotation type parsing + required-flag validation.
`test/helpers/mock-ably-realtime.ts`	Adds `annotations` support to realtime channel mock.
`test/helpers/mock-ably-rest.ts`	Adds `annotations` support to REST channel mock.
`test/unit/commands/channels/annotations/*.test.ts`	Adds unit coverage for validation + new commands.
`test/e2e/channels/channel-annotations-e2e.test.ts`	Adds E2E coverage for publish/get/delete/subscribe flows.
`ANNOTATIONS_IMPL.md`	Documents the implementation plan and SDK behavior notes.
`.claude/CLAUDE.md`	Minor formatting + adds guidance about not truncating fetched markdown docs.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-06T09:51:14Z

src/commands/channels/annotations/publish.ts

+      const client = await this.createAblyRealtimeClient(flags);
+      if (!client) return;
+
+      const channel = client.channels.get(args.channel);


channels.get() is called without setting the Ably channel mode required for annotation publishing. The Ably SDK expects ANNOTATION_PUBLISH mode for annotation publish/delete; without it, channel.annotations.publish() can fail at runtime. Request the channel with { modes: ["ANNOTATION_PUBLISH"] } (and preserve/merge any other modes if needed).

Suggested change

const channel = client.channels.get(args.channel);

const channel = client.channels.get(args.channel, { modes: ["ANNOTATION_PUBLISH"] });

Copilot · 2026-03-06T09:51:15Z

src/commands/channels/annotations/delete.ts

+      const client = await this.createAblyRealtimeClient(flags);
+      if (!client) return;
+
+      const channel = client.channels.get(args.channel);


channels.get() is called without setting the Ably channel mode required for annotation publishing. The Ably SDK expects ANNOTATION_PUBLISH mode for annotation publish/delete; without it, channel.annotations.delete() can fail at runtime. Request the channel with { modes: ["ANNOTATION_PUBLISH"] }.

Suggested change

const channel = client.channels.get(args.channel);

const channel = client.channels.get(args.channel, {

modes: ["ANNOTATION_PUBLISH"],

});

Copilot · 2026-03-06T09:51:15Z

src/commands/channels/annotations/subscribe.ts

+      // 6. Wait until interrupted or timeout
+      const exitReason = await waitUntilInterruptedOrTimeout(flags.duration);
+
+      // 7. Auto-unsubscribe on cleanup
+      channel.annotations.unsubscribe();
+      this.logCliEvent(
+        flags,
+        "annotations:subscribe",
+        "cleanup",
+        "Unsubscribed from annotations",
+        { exitReason },
+      );


Cleanup after the --duration timeout won’t run in non-test mode: waitUntilInterruptedOrTimeout() calls process.exit(0) on timeout (src/utils/long-running.ts:42-48), so execution never reaches channel.annotations.unsubscribe() / logCliEvent() below. To ensure unsubscribe/logging happens, avoid relying on waitUntilInterruptedOrTimeout()’s timeout exit (e.g., implement the duration timer in this command and call this.exit() after cleanup, or change the helper to always resolve and let callers decide when to exit).

Copilot · 2026-03-06T09:51:15Z

src/commands/channels/annotations/subscribe.ts

+
+      this.logCliEvent(
+        flags,
+        "annotations",


logCliEvent uses two different event namespaces in the same command ("annotations" vs "annotations:subscribe"). This makes downstream log filtering/analytics harder and inconsistent with other commands. Use a single consistent namespace (typically the command id, e.g. "annotations:subscribe") for all events emitted from this command.

Suggested change

"annotations",

"annotations:subscribe",

vercel bot deployed to Preview March 5, 2026 09:18 View deployment

sacOO7 force-pushed the feature/pubsub-message-annotations branch from 1ac56f2 to ba412bc Compare March 5, 2026 09:19

vercel bot deployed to Preview March 5, 2026 09:20 View deployment

[DX-789] Created implementation plan for pubsub message annotations

d146303

- Updated CLAUDE.md to not truncate external markdown documentation # Conflicts: # .claude/CLAUDE.md

sacOO7 force-pushed the feature/pubsub-message-annotations branch from ba412bc to d146303 Compare March 6, 2026 08:41

vercel bot deployed to Preview March 6, 2026 08:42 View deployment

sacOO7 changed the base branch from main to fix/pubsub-subscribe-history-formatting March 6, 2026 08:43

Updated implementation plan for message annotations, updated with res…

aac81ec

…pect to CLAUDE.md

vercel bot deployed to Preview March 6, 2026 09:13 View deployment

vercel bot deployed to Preview March 6, 2026 09:42 View deployment

sacOO7 requested a review from Copilot March 6, 2026 09:46

Copilot started reviewing on behalf of sacOO7 March 6, 2026 09:46 View session

Copilot AI reviewed Mar 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DX-789] Implement pubsub message annotations#148

[DX-789] Implement pubsub message annotations#148
sacOO7 wants to merge 3 commits intofix/pubsub-subscribe-history-formattingfrom
feature/pubsub-message-annotations

sacOO7 commented Mar 5, 2026 •

edited

Loading

Uh oh!

vercel bot commented Mar 5, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Mar 5, 2026 •

edited

Loading

Review skipped

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Copilot AI Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

	const channel = client.channels.get(args.channel);
	const channel = client.channels.get(args.channel, { modes: ["ANNOTATION_PUBLISH"] });

-      const channel = client.channels.get(args.channel);
+      const channel = client.channels.get(args.channel, {
+        modes: ["ANNOTATION_PUBLISH"],
+      });

Conversation

sacOO7 commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

sacOO7 commented Mar 5, 2026 •

edited

Loading

vercel bot commented Mar 5, 2026 •

edited

Loading

coderabbitai bot commented Mar 5, 2026 •

edited

Loading