DX-1209: inline fix-it hints on SDK ErrorInfo throw sites

[umair-ably]

Summary

• Adopts the message (what failed) / hint (how to fix) split that DX-1204 introduced for detectV1Callback and applies it to every ErrorInfo throw in the SDK where a fix-it hint adds value. The split lets agents (and humans) read the what in err.message and act on the how in err.hint without parsing prose.
• Covers ~80 inline throw sites across 19 files — the high-traffic codes LLM agents and migrating users will trip on first: channel-state / publish-shape / presence-clientId / auth-options / push-state / message-serial / capability / pagination / plugin-missing / derived-channel / vcdiff / endpoint-vs-host.
• Server-relayed codes are deliberately out of scope here (40140 token expired, 40160 capability, 40300 forbidden, 42910 rate-limit, etc.). Propagating hints from the server is being tracked separately.

Themes / where this sits

This is the foundation slice of LLMEvalUpdatedPlan.md A1 (TKT-6) and aligns with the team's "Theme 3 — errors guide self-healing" target for the quarter. It's defence-in-depth alongside DX-1204 (v1-callback runtime throws with a hint) and DX-1205 (legacy-import shims with a hint).

What's in scope vs deliberately not

Hint added (~80 sites):

• realtimechannel.ts — channel options validation, publish shape (40013), max size (40009), detach-while-failed, invalidStateError (90001), release-state, attach/detach timeout (90007), untilAttach, sendUpdate missing serial (40003), sync() not-attached.
• realtimepresence.ts — clientId missing for enter/update/leave (40012), leave-in-incompatible-state (90001), get() on suspended (91005), untilAttach, auto-re-enter failure (91004).
• auth.ts — no auth options (40160), incompatible key (40102 ×2), authUrl/authCallback errors (40170 ×9), no-renewable-token (40171), no/invalid key (40101 ×2), empty/wildcard/non-string clientId (40012 ×3), token clientId mismatch (RSA15c), token-shape rejection.
• baseclient.ts, defaults.ts, rest.ts, baserealtime.ts, paginatedresource.ts, utils.ts, connectionmanager.ts, basemessage.ts — see commit message for the per-file rundown.
• push.ts, pushactivation.ts, pushchannel.ts, getW3CDeviceDetails.ts — push platform/state, registration callback, device-identity preconditions.
• restchannel.ts, restchannelmixin.ts, restannotations.ts, realtimeannotations.ts — message-serial requirements, annotation shape / mode.

Skipped (per A1 scope):

• LiveObjects 92xxx — messages are already specific; adding a hint is low value.
• Transport 80xxx connection-lifecycle codes — auto-recovered by the SDK; a hint would encourage user retry code that fights the SDK.
• 50000 internal errors — only actionable advice is file an issue, not worth a per-site hint.
• Server-relayed codes (40140 family, 40160, 40300, 42910, etc.) — the SDK does not construct these, the server does. Propagating server-supplied hints is separate ongoing work.

Accuracy verification

Hints were verified against the actual code at each throw site (not just the docs) — flagged and fixed issues during review:

• MAX_TOKEN_LENGTH = 2^17 ≈ 128 KB (not the 384 KB the first draft claimed).
• Vcdiff plugin is @ably/vcdiff-decoder (not the legacy fork URL still referenced in the error string).
• auth.authorize() rejects any key change, not just cross-app keys.
• annotation_subscribe (mode) vs annotation-subscribe (token capability) — both forms are real and the hint uses each correctly.

Out of scope but flagged

While reviewing throw sites I noticed four pre-existing ErrorInfo constructions with code and statusCode swapped (signature is (message, code, statusCode)):

• src/plugins/push/getW3CDeviceDetails.ts:31, :40 — new ErrorInfo('…', 400, 40000)
• src/common/lib/util/utils.ts:472, :479 — new ErrorInfo('…', 400, 40010)

These pre-date DX-1204 and aren't touched here. Worth a separate ticket — the hint additions in this PR are stamped onto these malformed ErrorInfos in those files.

Base branch

⚠️ This PR targets DX-1205/legacy-import-shims, not main. We're stacking — merge DX-1205 (#2227) first, then this branch auto-retargets to main or can be rebased.

Test plan

• npx mocha test/unit/*.test.js — 23 passing (existing + new test/unit/error-hints.test.js).
• npx tsc --noEmit — clean.
• npm run build:node — clean.
• New test/unit/error-hints.test.js pins exact hint strings for the construction-time inline throws that don't require a live connection (invalid key, wildcard clientId, no auth options, endpoint/environment conflict, missing-plugin). Drift fails the test.
• Future: extend pinning to the connection-required sites (presence, channel-state, etc.) once the broader DX-1209/1210 series lands the eval-harness work.

🤖 Generated with Claude Code

[coderabbitai]

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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 51ec4bcb-af14-47d8-bece-df7d22424034

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
• Commit unit tests in branch DX-1209/error-hints

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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