Realtime message send + push message send on channel

[umair-ably]

Allows sending a realtime message and a push message when using push commands targeting a channel.

Opted for a flag instead of a positional arg so it's clearer what the realtime message data is and what the push object is. There are also checks to guard against using the flag where it is incompatible e.g. using the message flag with a client id push.

Fixes #256

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
cli-web-cli	Ready	Preview, Comment	Apr 13, 2026 1:36pm

[claude-code-ably-assistant]

Walkthrough

This PR adds a --message flag to push publish that lets users include realtime message data alongside a push notification when publishing via a channel. The flag attaches the data as the Ably message's data field (parsed as JSON if possible, otherwise as a plain string), enabling a single publish call to deliver both a push notification and a realtime message payload. Guards prevent misuse when targeting a device or client directly.

Changes

Area	Files	Summary
Commands	src/commands/push/publish.ts	Adds --message flag; builds composite publish message with extras.push + data; adds validation/warning guards; surfaces messageData: true in JSON output
Tests	test/unit/commands/push/publish.test.ts	Adds 5 new test cases covering string data, JSON data, error when used without --channel, warning when overridden by direct recipient, and JSON output shape
Docs	README.md	Regenerated with new --message flag description and two new usage examples

Review Notes

• Behavioral note — messageData: true in JSON output: The JSON result includes messageData: true as a boolean rather than echoing back the actual message data. Callers who need to confirm what was sent cannot recover the value from this output. Worth discussing whether to include the actual data (or omit the field entirely, since the caller already knows what they passed).
• Silent --message with direct recipient: When --device-id/--client-id/--recipient overrides --channel, --message emits a warning but is silently dropped. This is consistent with how --channel itself is handled in that path — the pattern is deliberate.
• JSON parsing fallback: Message data is parsed with JSON.parse and falls back to a raw string on failure. This is intentional and tested.
• No new dependencies. No breaking changes — purely additive.

[claude-code-ably-assistant]

Review Summary

The feature is well-scoped: a --message flag for push publish that includes realtime message data alongside the push extras when publishing via --channel. The validation logic is correct (errors if --message used without --channel, warns if a direct recipient overrides --channel). Two issues worth addressing:

---

1. messageData: true in JSON output omits actual content

File: src/commands/push/publish.ts, lines 293–303

...(flags.message ? { messageData: true } : {}),

The JSON result confirms that a message was included (messageData: true) but drops the actual content that was sent. A programmatic consumer using --json for auditing or pipeline verification can't tell what data was published — just that something was.

The fix is straightforward: emit the actual parsed value instead of the boolean sentinel:

...(flags.message ? { messageData: publishMessage.data } : {}),

publishMessage.data is already set at this point (lines 283–288), so this costs nothing and makes the JSON output self-describing.

---

2. Non-standard test describe block

File: test/unit/commands/push/publish.test.ts, line 201

describe("--message flag (realtime message data)", () => {

This is a sibling of "functionality" and "error handling" but doesn't match any of the 5 required standard block names. The new test cases belong in the existing describe("functionality" block (happy-path tests) and describe("error handling" block (the "fail without --channel" case). The test coverage itself is solid — it's just the placement that needs adjusting.

---

Both changes are small. The JSON output issue is the more meaningful one since it affects consumers relying on --json for automation.

[maratal]

LGTM