DX-1211: Auth interface docstrings (prerequisites, side-effects, failure modes)

[umair-ably]

Stacked on DX-1211/silent-failure-hints. Review the diff against that base, not main. Merge the parent first.

Applies docstringRules.md to the public Auth interface in ably.d.ts, surfacing the call-site prerequisites and failure modes a caller cannot infer from the type signature (the DX-1211 class of silent/architectural pitfall). Same effort as the already-landed RealtimeChannel/RealtimePresence pass; one subsystem = one PR.

Members (5 audited; 3 deprecated v1-callback overloads skipped)

Member	What was surfaced
revokeTokens	basic-auth (API key, not token) requirement; non-code "revocable tokens enabled on the key" prerequisite (+ feature-page @see)
requestToken	token-issuing prerequisite (authCallback/authUrl/key); callback-contract detail offloaded to the @see
createTokenRequest	a local API key must be available to sign the request
authorize	re-auth side-effect (resolves once the token takes effect on a connected connection); token-issuing prerequisite; RSA10a key-immutability (authorize() cannot change the API key)
clientId	adds the canonical @see

Conventions

• Folded prose, no headings/labels, no em-dashes, no numeric error codes (failures framed as "rejects with an {@link ErrorInfo}").
• Every member carries an @see to the canonical JS API reference.
• Every claim re-derived from src/ (file:line) in an adversarial verify pass before applying.

Validation

• npm run docs (TypeDoc, treatWarningsAsErrors) — clean (all {@link} resolve)
• eslint ably.d.ts — exit 0 · prettier --check — clean

Reviewer notes / follow-ups

• @see anchors: the canonical reference (ably/docs #3400) is not yet published, so 4 of 5 anchors are convention-derived per §6 and unverified (#revoke-tokens is corroborated). @see is not validated by TypeDoc, so re-check the slugs when #3400 ships.
• clientId change is cosmetic (@see only) — the drafter's null/wildcard value claims were rejected by verification as inaccurate. Fine to drop if you'd rather treat it as a pure accessor.

🤖 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: 35c23c4d-ca12-4bc7-93b8-66e8b61496b1

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-1211/auth-docstrings

---

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.}