DX-1211: Auth interface docstrings (prerequisites, side-effects, failure modes) by umair-ably · Pull Request #2242 · ably/ably-js

umair-ably · 2026-06-09T14:22:38Z

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

Summary by CodeRabbit

Documentation
- Clarified how client identity is resolved, including behavior for anonymous clients.
- Documented authorization outcomes, token and connection handling, API key behavior, and default replacement rules.
- Clarified requirements and limitations for creating, requesting, and revoking tokens, including supported authentication methods and revocable-token prerequisites.

coderabbitai · 2026-06-09T14:22:47Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bcbc85f0-e2bd-4f26-ad1e-96d10b903a87

📥 Commits

Reviewing files that changed from the base of the PR and between ee7c0ab and a73de14.

📒 Files selected for processing (1)

ably.d.ts

🚧 Files skipped from review as they are similar to previous changes (1)

ably.d.ts

Walkthrough

Updated ably.d.ts JSDoc for Auth client identity, authorization, token creation and requests, and token revocation semantics.

Changes

Auth interface documentation

Layer / File(s)	Summary
Auth method runtime contracts `ably.d.ts`	Clarifies `clientId` resolution, authorization behavior, token acquisition requirements, parameter replacement semantics, and token revocation authentication and eligibility rules.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Suggested reviewers: m-hulbert

Poem

A rabbit reads the Auth notes bright,
Clarifying tokens by moonlight,
Keys stand firm, defaults don’t blend,
Revocations know where they end,
Clear docs hop into sight.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the Auth interface docstring updates and their focus on prerequisites, side effects, and failure modes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch DX-1211/auth-docstrings

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

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

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

m-hulbert

Just a few suggestions on splitting up long sentences and large walls of text into paragraphs, but see what you think.

m-hulbert · 2026-06-23T15:05:21Z


  /**
-   * Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token has been obtained. Also stores any {@link TokenParams} and {@link AuthOptions} passed in as the new defaults, to be used for all subsequent implicit or explicit token requests. Any {@link TokenParams} and {@link AuthOptions} objects passed in entirely replace, as opposed to being merged with, the current client library saved values.
+   * Instructs the library to get a new token immediately. On a realtime client it re-authenticates the live connection, or initiates a connection if not connected, and the returned promise resolves only once the new token has taken effect on a `connected` connection, rejecting with an {@link ErrorInfo} if re-authentication fails or the connection cannot be (re)established. The client must be able to issue tokens, so a `key`, `authUrl`, or `authCallback` must be configured in {@link ClientOptions}, otherwise the call rejects with an {@link ErrorInfo}; `authorize()` cannot change the API key, so passing an `authOptions.key` that differs from the one the client was constructed with also rejects. Any {@link TokenParams} and {@link AuthOptions} passed in are stored as the new defaults for all subsequent token requests and entirely replace, rather than merge with, the current saved values.


Suggested change

* Instructs the library to get a new token immediately. On a realtime client it re-authenticates the live connection, or initiates a connection if not connected, and the returned promise resolves only once the new token has taken effect on a `connected` connection, rejecting with an {@link ErrorInfo} if re-authentication fails or the connection cannot be (re)established. The client must be able to issue tokens, so a `key`, `authUrl`, or `authCallback` must be configured in {@link ClientOptions}, otherwise the call rejects with an {@link ErrorInfo}; `authorize()` cannot change the API key, so passing an `authOptions.key` that differs from the one the client was constructed with also rejects. Any {@link TokenParams} and {@link AuthOptions} passed in are stored as the new defaults for all subsequent token requests and entirely replace, rather than merge with, the current saved values.

* Instructs the library to get a new token immediately.

*

* On a realtime client it re-authenticates the live connection, or initiates a connection if not currently connected. The returned promise resolves only once the new token has taken effect on a `connected` connection. It rejects with an {@link ErrorInfo} if re-authentication fails or the connection cannot be (re)established.

*

* The client must be able to issue tokens, so a `key`, `authUrl`, or `authCallback` must be configured in {@link ClientOptions}. If one of these isn't configured the call rejects with an {@link ErrorInfo}.

*

* `authorize()` cannot change the API key, so passing an `authOptions.key` that differs from the one the client was constructed with will be rejected.

*

* Any {@link TokenParams} and {@link AuthOptions} passed in are stored as the new defaults for all subsequent token requests and entirely replace, rather than merge with, the current saved values.

AFAIK you can create paragraphs using empty lines, which helps break up this wall of text. I'd also push for shorter sentences where possible as some of those got quite convoluted.

m-hulbert · 2026-06-23T15:14:35Z

  ): never;
  /**
-   * Creates and signs an Ably {@link TokenRequest} based on the specified (or if none specified, the client library stored) {@link TokenParams} and {@link AuthOptions}. Note this can only be used when the API `key` value is available locally. Otherwise, the Ably {@link TokenRequest} must be obtained from the key owner. Use this to generate an Ably {@link TokenRequest} in order to implement an Ably Token request callback for use by other clients. Both {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the default token parameters and authentication options for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication).
+   * Creates and signs an Ably {@link TokenRequest} based on the specified (or if none specified, the client library stored) {@link TokenParams} and {@link AuthOptions}. Use this to implement an Ably Token request callback for use by other clients. An API `key` value must be available locally to sign the request, supplied either in the client's {@link ClientOptions} or as `key` in the `authOptions` argument; without one the call rejects with an {@link ErrorInfo}, since a token-authenticated client cannot construct token requests itself and must instead obtain the {@link TokenRequest} from the key owner. Both {@link TokenParams} and {@link AuthOptions} are optional; when omitted or `null`, the client library's stored defaults (those set at construction or by a later `authorize` call) are used, and any values passed in replace, rather than merge with, those defaults.


Suggested change

* Creates and signs an Ably {@link TokenRequest} based on the specified (or if none specified, the client library stored) {@link TokenParams} and {@link AuthOptions}. Use this to implement an Ably Token request callback for use by other clients. An API `key` value must be available locally to sign the request, supplied either in the client's {@link ClientOptions} or as `key` in the `authOptions` argument; without one the call rejects with an {@link ErrorInfo}, since a token-authenticated client cannot construct token requests itself and must instead obtain the {@link TokenRequest} from the key owner. Both {@link TokenParams} and {@link AuthOptions} are optional; when omitted or `null`, the client library's stored defaults (those set at construction or by a later `authorize` call) are used, and any values passed in replace, rather than merge with, those defaults.

* Creates and signs an Ably {@link TokenRequest} based on the specified {@link TokenParams} and {@link AuthOptions}. If no `TokenRequest` or `TokenParams` are specified it uses those previously stored by the library. Use this to implement an Ably Token request callback for use by other clients.

*

* An API `key` value must be available locally to sign the request, supplied either in the client's {@link ClientOptions} or as `key` in the `authOptions` argument. Without a `key` the call rejects with an {@link ErrorInfo}, since a token-authenticated client cannot construct token requests itself and must instead obtain the {@link TokenRequest} from the key owner.

*

* Both {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the client library's stored defaults (those set at construction or by a later `authorize()` call) are used, and any values passed in replace, rather than merge with, those defaults.

m-hulbert · 2026-06-23T15:20:48Z

  ): never;
  /**
-   * Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}. Both {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the default token parameters and authentication options for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication).
+   * Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}. Both are optional; when omitted or `null`, the client's stored defaults are used, as specified in the {@link ClientOptions} at instantiation or later updated by an `authorize` request, and any values passed in are used instead of, rather than merged with, those defaults. The client must have a usable way to obtain a token, so the resolved {@link AuthOptions} must include one of `authCallback`, `authUrl`, or `key`; a client given only a literal token or `tokenDetails` with no renewal mechanism cannot request a new token and the call rejects with an {@link ErrorInfo}.


Suggested change

* Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}. Both are optional; when omitted or `null`, the client's stored defaults are used, as specified in the {@link ClientOptions} at instantiation or later updated by an `authorize` request, and any values passed in are used instead of, rather than merged with, those defaults. The client must have a usable way to obtain a token, so the resolved {@link AuthOptions} must include one of `authCallback`, `authUrl`, or `key`; a client given only a literal token or `tokenDetails` with no renewal mechanism cannot request a new token and the call rejects with an {@link ErrorInfo}.

* Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}. Both properties are optional. When omitted or `null`, the client's stored defaults are used, as specified in the {@link ClientOptions} at instantiation or later updated by an `authorize()` request. Any values passed in are used instead of, rather than merged with, those defaults.

*

* The client must have a way to obtain a token, so the resolved {@link AuthOptions} must include one of `authCallback`, `authUrl`, or `key`. A client given only a literal token or `tokenDetails` with no renewal mechanism cannot request a new token and the call rejects with an {@link ErrorInfo}.

On the 2nd paragraph I've made here - unsure if those 2 sentences are supposed to be related. They were separated by a semi-colon but I'm not sure they are.

Small note here on inconsistency between the descriptions too in how we refer to the default values and authorize().

Could argue whether the user needs to know that it's calling the REST API, but I won't go and rewrite everything as that's not the point 🙂

m-hulbert · 2026-06-23T15:23:13Z

  /**
-   * Revokes the tokens specified by the provided array of {@link TokenRevocationTargetSpecifier}s. Only tokens issued by an API key that had revocable tokens enabled before the token was issued can be revoked. See the [token revocation docs](https://ably.com/docs/core-features/authentication#token-revocation) for more information.
+   * Revokes the tokens specified by the provided array of {@link TokenRevocationTargetSpecifier}s.
+   * The client must be authenticated with an API key (basic auth), not a token; a


This reads a bit confusing as it makes it sound like the client you're trying to revoke a token for needs to be authenticated by a key.

@see

Apply the docstrings-standards.md review pass to the Auth interface, incorporating m-hulbert's PR #2242 suggestions: - Split walls of text into blank-line paragraphs, shorten sentences, and remove semicolons from descriptions (A1/A2). - authorize: five paragraphs with active reject voice and an ErrorInfo on each failure mode. - createTokenRequest: promote the defaults parenthetical to a sentence and correct the reviewer's "TokenRequest" arg slip (the method takes no TokenRequest parameter). - requestToken/createTokenRequest: one verbatim stored-defaults phrasing, and authorize() with parentheses (C5/F2). - revokeTokens: anchor the basic-auth prerequisite to the calling client to remove the ambiguity m-hulbert flagged (D5). - clientId: drop the inline identified-clients link now that the canonical @see is present (E1). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@see

Apply the docstrings-standards.md review pass to the Auth interface, incorporating m-hulbert's PR #2242 suggestions: - Split walls of text into blank-line paragraphs, shorten sentences, and remove semicolons from descriptions (A1/A2). - authorize: five paragraphs with active reject voice and an ErrorInfo on each failure mode. - createTokenRequest: promote the defaults parenthetical to a sentence and correct the reviewer's "TokenRequest" arg slip (the method takes no TokenRequest parameter). - requestToken/createTokenRequest: one verbatim stored-defaults phrasing, and authorize() with parentheses (C5/F2). - revokeTokens: anchor the basic-auth prerequisite to the calling client to remove the ambiguity m-hulbert flagged (D5). - clientId: drop the inline identified-clients link now that the canonical @see is present (E1). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@see

Apply the docstrings-standards.md review pass to the Auth interface, incorporating m-hulbert's PR #2242 suggestions: - Split walls of text into blank-line paragraphs, shorten sentences, and remove semicolons from descriptions (A1/A2). - authorize: five paragraphs with active reject voice and an ErrorInfo on each failure mode. - createTokenRequest: promote the defaults parenthetical to a sentence and correct the reviewer's "TokenRequest" arg slip (the method takes no TokenRequest parameter). - requestToken/createTokenRequest: one verbatim stored-defaults phrasing, and authorize() with parentheses (C5/F2). - revokeTokens: anchor the basic-auth prerequisite to the calling client to remove the ambiguity m-hulbert flagged (D5). - clientId: drop the inline identified-clients link now that the canonical @see is present (E1). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ably.d.ts`:
- Around line 2041-2043: Clarify the documentation around the stored defaults
and replacement behavior for the relevant authorization method: when a per-call
authOptions object is supplied, it replaces the stored options, so it must
include key to sign the request; callers must omit authOptions to use the key
configured in ClientOptions. Preserve the existing null/omitted behavior and
TokenParams/AuthOptions references.
- Around line 1992-1996: Update the Auth.clientId declaration to allow undefined
alongside string, matching the documented and runtime behavior for anonymous
clients while preserving string support for authenticated clients.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 06c53de9-2509-4571-b99d-827d07a1c758

📥 Commits

Reviewing files that changed from the base of the PR and between 85a204c and 608cf94.

📒 Files selected for processing (1)

ably.d.ts

@see

…ts, failure modes) Apply docstringRules.md to the public Auth interface in ably.d.ts so silent and architectural call-site prerequisites are discoverable at the call site: - revokeTokens: basic-auth (API key, not token) requirement; non-code "revocable tokens enabled on the key" prerequisite, with a feature-page @see. - requestToken: token-issuing prerequisite (authCallback/authUrl/key); callback contract detail (content-types, size flags) offloaded to the @see. - createTokenRequest: a local API key must be available to sign the request. - authorize: re-authenticates the live connection (resolves once the token takes effect on a connected connection), token-issuing prerequisite, and the RSA10a key-immutability rule (authorize() cannot change the API key). - clientId: adds the canonical @see. Folded prose, no numeric error codes; every behavioural method carries one simple @example and every member an @see to the canonical JS API reference. TypeDoc (treatWarningsAsErrors), eslint, and prettier are clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@see

Apply the docstrings-standards.md review pass to the Auth interface, incorporating m-hulbert's PR #2242 suggestions: - Split walls of text into blank-line paragraphs, shorten sentences, and remove semicolons from descriptions (A1/A2). - authorize: five paragraphs with active reject voice and an ErrorInfo on each failure mode. - createTokenRequest: promote the defaults parenthetical to a sentence and correct the reviewer's "TokenRequest" arg slip (the method takes no TokenRequest parameter). - requestToken/createTokenRequest: one verbatim stored-defaults phrasing, and authorize() with parentheses (C5/F2). - revokeTokens: anchor the basic-auth prerequisite to the calling client to remove the ambiguity m-hulbert flagged (D5). - clientId: drop the inline identified-clients link now that the canonical @see is present (E1). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

From the 2026-07-02 docstrings-pr-review run, re-verified against the post-review-feedback text: - clientId: rewrite the ClientOptions-copied description around the identity actually in effect on this client, how it resolves (options or token), and the 40102 conflict, anchored to the traced auth.ts behaviour - authorize: the prerequisite was anchored to the wrong subject and claimed the call rejects when ClientOptions lacks a token source; authorize() saves passed authOptions before validating, so the requirement is on the resolved AuthOptions (including a directly supplied token) - requestToken: drop the REST-endpoint mechanism opener; split purpose, stored defaults, and prerequisite into their own paragraphs - createTokenRequest: drop the stored-defaults sentence that duplicated the paragraph below it - stored-defaults concept now phrased identically across authorize, createTokenRequest, and requestToken Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… at the prerequisite Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

m-hulbert · 2026-07-16T12:40:39Z

 export declare interface Auth {
  /**
-   * A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string, except it cannot contain a `*`. This option is primarily intended to be used in situations where the library is instantiated with a key. Note that a `clientId` may also be implicit in a token used to instantiate the library. An error is raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. Find out more about [identified clients](https://ably.com/docs/core-features/authentication#identified-clients).
+   * The client ID currently in effect for this client, used to identify it when publishing messages or entering presence.


I'm not sure about 'in effect' here.

m-hulbert · 2026-07-16T12:41:39Z

  /**
-   * A client ID, used for identifying this client when publishing messages or for presence purposes. The `clientId` can be any non-empty string, except it cannot contain a `*`. This option is primarily intended to be used in situations where the library is instantiated with a key. Note that a `clientId` may also be implicit in a token used to instantiate the library. An error is raised if a `clientId` specified here conflicts with the `clientId` implicit in the token. Find out more about [identified clients](https://ably.com/docs/core-features/authentication#identified-clients).
+   * The client ID currently in effect for this client, used to identify it when publishing messages or entering presence.
+   *


'token in use' or more like 'the token that authenticated this client' or the wording from before?

m-hulbert · 2026-07-16T13:28:39Z

-   * Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token has been obtained. Also stores any {@link TokenParams} and {@link AuthOptions} passed in as the new defaults, to be used for all subsequent implicit or explicit token requests. Any {@link TokenParams} and {@link AuthOptions} objects passed in entirely replace, as opposed to being merged with, the current client library saved values.
+   * Instructs the library to get a new token immediately.
+   *
+   * On a realtime client it re-authenticates the live connection, or initiates a connection if not currently connected. The returned promise resolves only once the new token has taken effect on a `connected` connection. It rejects with an {@link ErrorInfo} if re-authentication fails or the connection cannot be established.


Is "live connection" the right terminology here? We're also mixing code-styled and plain text for states.

m-hulbert · 2026-07-16T13:32:05Z

  ): void;
  /**
-   * Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}. Both {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the default token parameters and authentication options for the client library are used, as specified in the {@link ClientOptions} when the client library was instantiated, or later updated with an explicit `authorize` request. Values passed in are used instead of, rather than being merged with, the default values. To understand why an Ably {@link TokenRequest} may be issued to clients in favor of a token, see [Token Authentication explained](https://ably.com/docs/core-features/authentication/#token-authentication).
+   * Obtains an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}.


Thoughts on whether some of these should retain a link to the different methods of authentication?

github-actions Bot temporarily deployed to staging/pull/2242/bundle-report June 9, 2026 14:23 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/typedoc June 9, 2026 14:23 Inactive

umair-ably force-pushed the DX-1211/auth-docstrings branch from 4d45490 to c81b62a Compare June 9, 2026 14:31

github-actions Bot temporarily deployed to staging/pull/2242/bundle-report June 9, 2026 14:32 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/typedoc June 9, 2026 14:33 Inactive

umair-ably mentioned this pull request Jun 9, 2026

DX-1211: RealtimeChannel interface docstrings #2243

Draft

m-hulbert reviewed Jun 23, 2026

View reviewed changes

umair-ably force-pushed the DX-1211/silent-failure-hints branch from 7c617fe to 729d8f0 Compare June 25, 2026 10:47

umair-ably force-pushed the DX-1211/auth-docstrings branch from c81b62a to 75ca7f8 Compare June 25, 2026 10:47

github-actions Bot temporarily deployed to staging/pull/2242/bundle-report June 25, 2026 10:48 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/typedoc June 25, 2026 10:49 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/bundle-report June 25, 2026 16:00 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/typedoc June 25, 2026 16:00 Inactive

umair-ably force-pushed the DX-1211/auth-docstrings branch from 2a86111 to 7906161 Compare June 25, 2026 16:50

umair-ably force-pushed the DX-1211/silent-failure-hints branch from 729d8f0 to 8eb6588 Compare July 2, 2026 14:49

umair-ably force-pushed the DX-1211/auth-docstrings branch from 7906161 to 963b791 Compare July 2, 2026 14:50

github-actions Bot temporarily deployed to staging/pull/2242/bundle-report July 2, 2026 14:50 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/typedoc July 2, 2026 14:51 Inactive

umair-ably force-pushed the DX-1211/auth-docstrings branch from 963b791 to c54b363 Compare July 3, 2026 10:34

umair-ably force-pushed the DX-1211/silent-failure-hints branch from 8eb6588 to d22cf9a Compare July 3, 2026 10:34

github-actions Bot temporarily deployed to staging/pull/2242/bundle-report July 3, 2026 10:35 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/typedoc July 3, 2026 10:35 Inactive

umair-ably force-pushed the DX-1211/auth-docstrings branch from c54b363 to b368d48 Compare July 3, 2026 10:40

github-actions Bot temporarily deployed to staging/pull/2242/bundle-report July 3, 2026 10:41 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/typedoc July 3, 2026 10:42 Inactive

umair-ably force-pushed the DX-1211/silent-failure-hints branch from e81bf4b to c56022a Compare July 3, 2026 12:59

umair-ably force-pushed the DX-1211/auth-docstrings branch from b368d48 to 6a9f6ba Compare July 3, 2026 12:59

github-actions Bot temporarily deployed to staging/pull/2242/bundle-report July 3, 2026 13:00 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/typedoc July 3, 2026 13:00 Inactive

umair-ably force-pushed the DX-1211/silent-failure-hints branch from c56022a to 85a204c Compare July 14, 2026 08:49

umair-ably force-pushed the DX-1211/auth-docstrings branch from 6a9f6ba to 608cf94 Compare July 14, 2026 08:55

github-actions Bot temporarily deployed to staging/pull/2242/features July 14, 2026 08:56 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/bundle-report July 14, 2026 08:56 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/typedoc July 14, 2026 08:56 Inactive

umair-ably requested a review from m-hulbert July 14, 2026 08:58

umair-ably marked this pull request as ready for review July 14, 2026 08:58

coderabbitai Bot reviewed Jul 14, 2026

View reviewed changes

Comment thread ably.d.ts

github-actions Bot temporarily deployed to staging/pull/2242/features July 14, 2026 11:35 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/bundle-report July 14, 2026 11:35 Inactive

github-actions Bot temporarily deployed to staging/pull/2242/typedoc July 14, 2026 11:35 Inactive

Base automatically changed from DX-1211/silent-failure-hints to main July 15, 2026 09:37

umair-ably and others added 4 commits July 15, 2026 10:38

DX-1211: single @see on revokeTokens with the revocation page inlined…

a73de14

… at the prerequisite Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

umair-ably force-pushed the DX-1211/auth-docstrings branch from ee7c0ab to a73de14 Compare July 15, 2026 09:38

github-actions Bot deployed to staging/pull/2242/bundle-report July 15, 2026 09:39 View deployment

github-actions Bot deployed to staging/pull/2242/features July 15, 2026 09:39 View deployment

github-actions Bot deployed to staging/pull/2242/typedoc July 15, 2026 09:40 View deployment

ably deleted a comment from coderabbitai Bot Jul 15, 2026

m-hulbert reviewed Jul 16, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

DX-1211: Auth interface docstrings (prerequisites, side-effects, failure modes)#2242
umair-ably wants to merge 4 commits into
mainfrom
DX-1211/auth-docstrings

umair-ably commented Jun 9, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 9, 2026 •

edited

Loading

Uh oh!

m-hulbert left a comment

Uh oh!

m-hulbert Jun 23, 2026

Uh oh!

m-hulbert Jun 23, 2026

Uh oh!

m-hulbert Jun 23, 2026

Uh oh!

m-hulbert Jun 23, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

m-hulbert Jul 16, 2026

Uh oh!

m-hulbert Jul 16, 2026

Uh oh!

m-hulbert Jul 16, 2026

Uh oh!

m-hulbert Jul 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

-   * Instructs the library to get a new token immediately. On a realtime client it re-authenticates the live connection, or initiates a connection if not connected, and the returned promise resolves only once the new token has taken effect on a `connected` connection, rejecting with an {@link ErrorInfo} if re-authentication fails or the connection cannot be (re)established. The client must be able to issue tokens, so a `key`, `authUrl`, or `authCallback` must be configured in {@link ClientOptions}, otherwise the call rejects with an {@link ErrorInfo}; `authorize()` cannot change the API key, so passing an `authOptions.key` that differs from the one the client was constructed with also rejects. Any {@link TokenParams} and {@link AuthOptions} passed in are stored as the new defaults for all subsequent token requests and entirely replace, rather than merge with, the current saved values.
+   * Instructs the library to get a new token immediately.
+   *
+   * On a realtime client it re-authenticates the live connection, or initiates a connection if not currently connected. The returned promise resolves only once the new token has taken effect on a `connected` connection. It rejects with an {@link ErrorInfo} if re-authentication fails or the connection cannot be (re)established.
+   *
+   * The client must be able to issue tokens, so a `key`, `authUrl`, or `authCallback` must be configured in {@link ClientOptions}. If one of these isn't configured the call rejects with an {@link ErrorInfo}.
+   *
+   * `authorize()` cannot change the API key, so passing an `authOptions.key` that differs from the one the client was constructed with will be rejected.
+   *
+   * Any {@link TokenParams} and {@link AuthOptions} passed in are stored as the new defaults for all subsequent token requests and entirely replace, rather than merge with, the current saved values.

-   * Creates and signs an Ably {@link TokenRequest} based on the specified (or if none specified, the client library stored) {@link TokenParams} and {@link AuthOptions}. Use this to implement an Ably Token request callback for use by other clients. An API `key` value must be available locally to sign the request, supplied either in the client's {@link ClientOptions} or as `key` in the `authOptions` argument; without one the call rejects with an {@link ErrorInfo}, since a token-authenticated client cannot construct token requests itself and must instead obtain the {@link TokenRequest} from the key owner. Both {@link TokenParams} and {@link AuthOptions} are optional; when omitted or `null`, the client library's stored defaults (those set at construction or by a later `authorize` call) are used, and any values passed in replace, rather than merge with, those defaults.
+   * Creates and signs an Ably {@link TokenRequest} based on the specified {@link TokenParams} and {@link AuthOptions}. If no `TokenRequest` or `TokenParams` are specified it uses those previously stored by the library. Use this to implement an Ably Token request callback for use by other clients.
+   *
+   * An API `key` value must be available locally to sign the request, supplied either in the client's {@link ClientOptions} or as `key` in the `authOptions` argument.  Without a `key` the call rejects with an {@link ErrorInfo}, since a token-authenticated client cannot construct token requests itself and must instead obtain the {@link TokenRequest} from the key owner.
+   *
+   * Both {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the client library's stored defaults (those set at construction or by a later `authorize()` call) are used, and any values passed in replace, rather than merge with, those defaults.

-   * Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}. Both are optional; when omitted or `null`, the client's stored defaults are used, as specified in the {@link ClientOptions} at instantiation or later updated by an `authorize` request, and any values passed in are used instead of, rather than merged with, those defaults. The client must have a usable way to obtain a token, so the resolved {@link AuthOptions} must include one of `authCallback`, `authUrl`, or `key`; a client given only a literal token or `tokenDetails` with no renewal mechanism cannot request a new token and the call rejects with an {@link ErrorInfo}.
+   * Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams} and {@link AuthOptions}. Both properties are optional. When omitted or `null`, the client's stored defaults are used, as specified in the {@link ClientOptions} at instantiation or later updated by an `authorize()` request. Any values passed in are used instead of, rather than merged with, those defaults.
+   *
+   * The client must have a way to obtain a token, so the resolved {@link AuthOptions} must include one of `authCallback`, `authUrl`, or `key`. A client given only a literal token or `tokenDetails` with no renewal mechanism cannot request a new token and the call rejects with an {@link ErrorInfo}.

Uh oh!

Conversation

umair-ably commented Jun 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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

Conventions

Validation

Reviewer notes / follow-ups

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

m-hulbert left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

umair-ably commented Jun 9, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 9, 2026 •

edited

Loading