Added support for optional message version and annotations

Author: sacOO7

src/commands/channels/history.ts

@@ -95,6 +95,8 @@ export default class ChannelsHistory extends AblyBaseCommand {
           indexPrefix: `[${index + 1}] ${formatTimestamp(formatMessageTimestamp(message.timestamp))}`,
           serial: message.serial,
           timestamp: message.timestamp ?? Date.now(),
+          version: message.version,
+          annotations: message.annotations,
         }),
       );
 

src/commands/channels/subscribe.ts

@@ -204,6 +204,8 @@ export default class ChannelsSubscribe extends AblyBaseCommand {
             id: message.id,
             serial: message.serial,
             timestamp: message.timestamp ?? Date.now(),
+            version: message.version,
+            annotations: message.annotations,
             ...(flags["sequence-numbers"]
               ? { sequencePrefix: `${chalk.dim(`[${this.sequenceCounter}]`)} ` }
               : {}),

src/utils/output.ts

@@ -1,4 +1,5 @@
 import chalk, { type ChalkInstance } from "chalk";
+import type * as Ably from "ably";
 import { formatMessageData, isJsonData } from "./json-formatter.js";
 
 export function progress(message: string): string {
@@ -79,6 +80,8 @@ export interface MessageDisplayFields {
   sequencePrefix?: string;
   serial?: string;
   timestamp: number;
+  version?: Ably.MessageVersion;
+  annotations?: Ably.MessageAnnotations;
 }
 
 /**
@@ -119,6 +122,36 @@ export function formatMessagesOutput(messages: MessageDisplayFields[]): string {
       lines.push(`${chalk.dim("Serial:")} ${msg.serial}`);
     }
 
+    if (
+      msg.version &&
+      Object.keys(msg.version).length > 0 &&
+      msg.version.serial &&
+      msg.version.serial !== msg.serial
+    ) {
+      lines.push(`${chalk.dim("Version:")}`);
+      if (msg.version.serial) {
+        lines.push(`  ${chalk.dim("Serial:")} ${msg.version.serial}`);
+      }
+      if (msg.version.timestamp !== undefined) {
+        lines.push(`  ${chalk.dim("Timestamp:")} ${msg.version.timestamp}`);
+      }
+      if (msg.version.clientId) {
+        lines.push(
+          `  ${chalk.dim("Client ID:")} ${chalk.blue(msg.version.clientId)}`,
+        );
+      }
+    }
+
+    if (msg.annotations && Object.keys(msg.annotations.summary).length > 0) {
+      lines.push(`${chalk.dim("Annotations:")}`);
+      for (const [type, entry] of Object.entries(msg.annotations.summary)) {
+        lines.push(
+          `  ${chalk.dim(`${type}:`)}`,
+          `    ${formatMessageData(entry)}`,
+        );
+      }
+    }
+
     if (isJsonData(msg.data)) {
       lines.push(`${chalk.dim("Data:")}\n${formatMessageData(msg.data)}`);
     } else {
@@ -149,6 +182,8 @@ export function toMessageJson(
     ...(msg.id ? { id: msg.id } : {}),
     ...(msg.clientId ? { clientId: msg.clientId } : {}),
     ...(msg.serial ? { serial: msg.serial } : {}),
+    ...(msg.version ? { version: msg.version } : {}),
+    ...(msg.annotations ? { annotations: msg.annotations } : {}),
     data: msg.data,
   };
 }

test/unit/commands/channels/history.test.ts

@@ -16,6 +16,22 @@ describe("channels:history command", () => {
           timestamp: 1700000000000,
           clientId: "client-1",
           connectionId: "conn-1",
+          version: {
+            serial: "v1-serial",
+            timestamp: 1700000000000,
+            clientId: "updater-1",
+          },
+          annotations: {
+            summary: {
+              "reaction:distinct.v1": {
+                "👍": {
+                  total: 3,
+                  clientIds: ["c1", "c2", "c3"],
+                  clipped: false,
+                },
+              },
+            },
+          },
         },
         {
           id: "msg-2",
@@ -94,6 +110,27 @@ describe("channels:history command", () => {
       expect(stdout).toContain("msg-1");
     });
 
+    it("should display version fields when present", async () => {
+      const { stdout } = await runCommand(
+        ["channels:history", "test-channel"],
+        import.meta.url,
+      );
+
+      expect(stdout).toContain("Version:");
+      expect(stdout).toContain("v1-serial");
+      expect(stdout).toContain("updater-1");
+    });
+
+    it("should display annotations summary when present", async () => {
+      const { stdout } = await runCommand(
+        ["channels:history", "test-channel"],
+        import.meta.url,
+      );
+
+      expect(stdout).toContain("Annotations:");
+      expect(stdout).toContain("reaction:distinct.v1:");
+    });
+
     it("should handle empty history", async () => {
       const mock = getMockAblyRest();
       const channel = mock.channels._getChannel("test-channel");
@@ -124,6 +161,45 @@ describe("channels:history command", () => {
       expect(result[0].data).toEqual({ text: "Hello world" });
     });
 
+    it("should include version in JSON output when present", async () => {
+      const { stdout } = await runCommand(
+        ["channels:history", "test-channel", "--json"],
+        import.meta.url,
+      );
+
+      const result = JSON.parse(stdout);
+      expect(result[0]).toHaveProperty("version");
+      expect(result[0].version).toEqual({
+        serial: "v1-serial",
+        timestamp: 1700000000000,
+        clientId: "updater-1",
+      });
+      // Second message has no version
+      expect(result[1]).not.toHaveProperty("version");
+    });
+
+    it("should include annotations in JSON output when present", async () => {
+      const { stdout } = await runCommand(
+        ["channels:history", "test-channel", "--json"],
+        import.meta.url,
+      );
+
+      const result = JSON.parse(stdout);
+      expect(result[0]).toHaveProperty("annotations");
+      expect(result[0].annotations.summary).toHaveProperty(
+        "reaction:distinct.v1",
+      );
+      expect(
+        result[0].annotations.summary["reaction:distinct.v1"]["👍"],
+      ).toEqual({
+        total: 3,
+        clientIds: ["c1", "c2", "c3"],
+        clipped: false,
+      });
+      // Second message has no annotations
+      expect(result[1]).not.toHaveProperty("annotations");
+    });
+
     it("should respect --limit flag", async () => {
       const mock = getMockAblyRest();
       const channel = mock.channels._getChannel("test-channel");

test/unit/commands/channels/subscribe.test.ts

@@ -121,6 +121,18 @@ describe("channels:subscribe command", () => {
         id: "msg-123",
         clientId: "publisher-client",
         connectionId: "conn-456",
+        version: {
+          serial: "ver-serial-1",
+          timestamp: Date.now(),
+          clientId: "version-client",
+        },
+        annotations: {
+          summary: {
+            "reaction:distinct.v1": {
+              "👍": { total: 2, clientIds: ["c1", "c2"], clipped: false },
+            },
+          },
+        },
       });
 
       const { stdout } = await commandPromise;
@@ -136,6 +148,13 @@ describe("channels:subscribe command", () => {
       expect(stdout).toContain("publisher-client");
       expect(stdout).toContain("Data:");
       expect(stdout).toContain("hello world");
+      // Version fields
+      expect(stdout).toContain("Version:");
+      expect(stdout).toContain("ver-serial-1");
+      expect(stdout).toContain("version-client");
+      // Annotations
+      expect(stdout).toContain("Annotations:");
+      expect(stdout).toContain("reaction:distinct.v1:");
     });
 
     it("should run with --json flag without errors", async () => {