feat(push): support realtime message data in batch-publish channel items

[maratal]

Fixes #345

Summary

• Mirrors the --message flag added to push publish in Realtime message send + push message send on channel #310
• Channel-based batch items may now include an optional "message" field whose value is sent as realtime message data alongside the push notification in extras.push
• No change for recipient-based items (message field is ignored/not applicable)

Example

[
  {
    "channels": ["my-channel"],
    "payload": {"notification": {"title": "Hello", "body": "World"}},
    "message": "Hello from push"
  }
]

or with a JSON object as message data:

[
  {
    "channels": ["my-channel"],
    "payload": {"notification": {"title": "Hello"}},
    "message": {"event": "push", "text": "Hello"}
  }
]

Test plan

• pnpm test:unit passes (20 tests in batch-publish, 3 new ones covering string message, JSON object message, and omitted message)
• pnpm exec eslint . clean

🤖 Generated with Claude Code

[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 16, 2026 10:52pm

[Copilot]

Pull request overview

Adds support for including realtime message data alongside channel-routed push notifications in push:batch-publish, aligning batch behavior with the --message capability introduced for push publish (PR #310).

Changes:

• Extend channel-routed batch items to accept an optional message field and forward it as messages.data when publishing via POST /messages.
• Update CLI help/examples and argument description to document the new message field for channel items.
• Add unit tests covering string message data, JSON object message data, and the omission case.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/commands/push/batch-publish.ts	Maps optional message on channel batch items to realtime message data while still wrapping push payload under extras.push; updates examples/arg description.
test/unit/commands/push/batch-publish.test.ts	Adds unit tests verifying message is forwarded into messages.data (string/object) and omitted when absent.

---

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

[claude-code-ably-assistant]

Walkthrough

This PR extends push batch-publish so that channel-based batch items can include an optional "message" field whose value is sent as realtime message data alongside the push notification in extras.push. It mirrors the --message flag added to push publish in #310 and fixes #345. Recipient-based items are unaffected.

Changes

Area	Files	Summary
Commands	src/commands/push/batch-publish.ts	Adds support for optional message field in channel batch items; maps it to the data field of the realtime message object sent to /messages
Tests	test/unit/commands/push/batch-publish.test.ts	Adds 3 new unit tests: string message data, JSON object message data, and omitted message (no data field emitted)

Review Notes

• Behavioral change: Channel batch items now accept a new optional "message" field. Existing payloads without this field are unaffected — the data field is only added when entry.message !== undefined.
• Type safety: The message object is typed as Record<string, unknown>, which is permissive. The message field in the batch item schema is not formally typed (it flows through from raw JSON), so callers can pass any JSON-serialisable value — same pattern as the existing push publish --message flag.
• No new dependencies — pure logic change using existing Ably REST request() path.
• Recipient-based items: No change; the PR description states message is ignored/not applicable there, but no test explicitly asserts this. Low risk, but worth noting.
• Doc string updated on the payload arg to describe the new "message" field — reviewers should verify the wording is accurate and complete.

[claude-code-ably-assistant]

Review Summary

File	Status	Issues
src/commands/push/batch-publish.ts	✅ OK	—
test/unit/commands/push/batch-publish.test.ts	✅ OK	—

Assessment

The change is minimal, correct, and well-tested. The entry.message !== undefined guard is the right approach — it correctly passes falsy-but-present values ("", 0, false) to the API while skipping the field entirely when absent. This mirrors how Ably message data fields are handled elsewhere.

Three things worth noting, none blocking:

1. null edge case — if a user passes "message": null" in the JSON, null !== undefined evaluates to true, so messageObj.data = null gets sent to the API. The PR description says the field accepts "string or JSON", but the code accepts any value including null. Unlikely to cause problems in practice since the Ably API will either accept or reject it, but worth knowing the guard isn't a type filter.

2. Recipient items silently forward the message field — recipientItems.map(({ entry }) => entry) sends the raw entry object, so if a user includes "message" on a recipient item, it goes to /push/batch/publish as-is. The PR description says "message field is ignored/not applicable" for recipients, but it's actually forwarded to the API rather than stripped. The API will likely ignore it, but the behaviour is technically different from what the description says. Not a bug, just a documentation nuance.

3. Test assertion for "omit" case — expect.not.objectContaining({ data: expect.anything() }) passes when data is absent, null, or undefined — which is exactly the right matcher here since expect.anything() excludes both null and undefined. No issue, just confirming the matcher semantics are intentional.

LGTM. Ready to merge.