Integration: MAU-based account support and SDK dependency upgrades for next release

[ttypic]

Integration branch collecting the changes required for the next CLI release to
work with MAU-based (monthly active users) Ably accounts. It also brings the
Pub/Sub, Chat and Spaces SDKs up to date, since the newer SDK versions are
needed for MAU-based account support.

[vercel]

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

Project	Deployment	Actions	Updated
cli-web-cli	Ready	Preview	Oct 13, 2026 12:49pm UTC

[claude-code-ably-assistant]

Walkthrough

This integration PR adds MAU (Monthly Active Users) account support by replacing the ably v2 dependency with @ably/pubsub-server — the server-specific split package whose traffic is exempt from MAU counting. It also upgrades @ably/chat and @ably/spaces to canary builds that are built on the same v3 core, ensuring all CLI-initiated connections are classified as server traffic.

Changes

Area	Files	Summary
Config	package.json, pnpm-lock.yaml	Replace ably with @ably/pubsub-server; bump @ably/chat and @ably/spaces to canary versions built on v3 core
Base Commands	src/base-command.ts, src/chat-base-command.ts, src/spaces-base-command.ts	Switch client construction to createHttpClient/createRealtimeClient from @ably/pubsub-server; use createChatClient/createSpacesClient wrappers
Commands	24 files under src/commands/	Update import type * as Ably from to use @ably/pubsub-server; type references updated from Ably.Rest/Ably.Realtime to Ably.PubSubHttpClient/Ably.PubSubRealtimeClient
Utils	src/utils/history.ts, src/utils/message.ts, src/utils/output.ts	Align type imports with new package
Tests	test/helpers/, test/setup.ts, test/e2e/, test/unit/	Update mock helpers and e2e auth helpers for new client types; minor cleanup
Docs	AGENTS.md, docs/Testing.md	Update package name references to reflect new dependency
Skills	.claude/skills/ably-new-command/SKILL.md, references/patterns.md	Update AI coding conventions to reference @ably/pubsub-server types and construction patterns

Review Notes

• Breaking for local dev: Anyone with a locally built copy will need to pnpm install to pick up the new @ably/pubsub-server package and the updated canary builds of Chat/Spaces.
• Canary dependencies: @ably/chat and @ably/spaces are pinned to specific canary SHA builds (canary.20261001T1209.783b80e6 / canary.20261001T1221.ca08adce). These are pre-release — reviewers should confirm these canaries are stable enough for a release branch and that there's a plan to pin to stable versions before shipping.
• Type surface: Ably.PubSubRealtimeClient / Ably.PubSubHttpClient replace Ably.Realtime / Ably.Rest throughout. Verify that all SDK method calls still compile correctly — the diff is +216/-209 lines across ~45 files, mostly mechanical renaming.
• connections/test.ts has the largest non-trivial command change (+7/-6); worth a closer look to ensure the connection test logic is still correct after the client construction changes.
• Test helpers (ably-event-emitter.ts +12/-3, e2e-test-helper.ts +6/-5): more substantial changes than other test files — confirm mocks still faithfully represent the new client API shape.

[claude-code-ably-assistant]

Review: Integration/MAU — SDK migration to @ably/pubsub-server

This is a well-scoped SDK migration PR. The mechanical changes are correct and complete — no leftover ably package imports remain anywhere in src/ or test/. The overall approach is solid.

One item worth flagging

test/helpers/ably-event-emitter.ts — module-level client instantiation with undocumented internal access

The new code creates a real createRealtimeClient(...) call at module import time to reach the internal EventEmitter constructor:

const realtimeClient = createRealtimeClient({
  key: "appId.keyId:keySecret",
  autoConnect: false,
});
export const EventEmitter = (
  realtimeClient.constructor as unknown as { EventEmitter: new () => AblyEventEmitter }
).EventEmitter;
realtimeClient.close();

Two concerns:

1. Fragility: .constructor.EventEmitter is an undocumented SDK internal. The old code accessed Ably.Realtime.EventEmitter (a static on the class — also undocumented, but at least reachable without instantiation). The new pattern's access path breaks silently at runtime if the SDK restructures its class hierarchy — TypeScript won't catch it because the cast to unknown as { EventEmitter: ... } bypasses type checking. A runtime undefined is not a constructor error in tests could be hard to trace.

2. Module-level side effect: The client is created (and closed) when the module is first imported, not lazily inside a test. While autoConnect: false prevents WebSocket connections, the SDK still runs initialization code. This is a minor concern but worth being aware of.

Why it had to change: The old approach worked because ably exported the Realtime constructor as a named export, making Ably.Realtime.EventEmitter directly accessible. @ably/pubsub-server only exports factories (createRealtimeClient), not the class itself, so there's no static property to access without an instance. This is a genuine API surface limitation.

Suggested path: Ask the @ably/pubsub-server team whether EventEmitter can be exported directly, or expose a test helper API. Alternatively, a simple hand-rolled EventEmitter shim in test helpers that satisfies the AblyEventEmitter interface would remove the SDK dependency entirely.

This doesn't block the PR — it's test helper code, not production code, and the behavior should work correctly in practice. But it's worth tracking.

---

Everything else looks good

• All new Ably.Rest(...) → createHttpClient(...) ✓
• All new Ably.Realtime(...) → createRealtimeClient(...) ✓
• All new ChatClient(...) → createChatClient(...) ✓
• The dynamic-import hack in spaces-base-command.ts (20+ lines of moduleAsRecord.default.default || ... fallbacks) replaced with a clean synchronous createSpacesClient() call — net improvement
• The x-ably-clientType: "server" JWT claim added to the E2E revocation test is a correct fix; @ably/pubsub-server always connects as a server and token auth enforces this
• spaces-base-command.createSpacesClient correctly changed from async to sync to match the new synchronous factory
• Type renames (Ably.Rest → Ably.PubSubHttpClient, Ably.Realtime → Ably.PubSubRealtimeClient) are consistent throughout