DX-1211: RealtimePresence interface docstrings

[umair-ably]

Stacked on #2243 (RealtimeChannel docstrings, base DX-1211/realtimechannel-docstrings); review/merge that first. Rewrites the JSDoc on the RealtimePresence public surface in ably.d.ts per docstringRules.md: terse folded prose that surfaces call-site prerequisites, side-effects, and failure modes (the DX-1211 silent-failure class), with an @see companion link to the canonical reference.

Scope

ably.d.ts only (+83/−19). 11 members rewritten (counting overload groups once).

Highlights

• subscribe() (DX-1211 core): documents the silent missing-presence_subscribe-mode trap — the channel attaches but the server never delivers presence events, so the listener silently never fires; also notes attachOnSubscribe: false skips the implicit attach. On both active overloads.
• get(): same mode prerequisite, but the failure shape differs — resolves with an empty array rather than rejecting (or rejects with a hinted ErrorInfo under strictMode).
• syncComplete: precise semantics — flips back to false on a new sync, is true after the local set is cleared, so it only means "no sync in progress", not "attached"; points to get() as the way to wait for a sync.
• enter()/update()/leave(): identified-client prerequisite (rejects on missing/wildcard clientId), with pointers to the *Client() variants; enter() documents automatic re-enter on re-attach and that a re-enter failure surfaces as a channel update event, not a rejection.
• leave(): unlike enter(), does not implicitly attach — proceeds only while attached/attaching and rejects otherwise.
• enterClient()/updateClient()/leaveClient(): wildcard-clientId key/token prerequisite is server-enforced, so violations reject with a server-returned ErrorInfo.
• unsubscribe(): all six overloads clarify the removal is local-only — no detach, no presence leave.
• history(): non-code persistence channel-rule prerequisite (72h vs the 2-minute default retention).

Validation

npm run docs (TypeDoc treatWarningsAsErrors), prettier --check, and eslint all pass. A clean TypeDoc build confirms every {@link} resolves and nothing became undocumented.

Reviewer notes

• @see anchors follow the kebab-case convention (matching the Auth and RealtimeChannel PRs) but are unverified — ably/docs #3400 isn't live yet and @see is not TypeDoc-validated.
• During this pass a confirmed library bug was found (presence ops queued while the channel is attaching can resolve silently without ever reaching the server in some failure paths); it is deliberately not documented here pending a decision on whether to fix the code instead.

🤖 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: 0ced6770-74c0-463e-9f8c-4092a8dc21fd

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