From 06f784c04af4274e24f71f8197c58a926fa5f83f Mon Sep 17 00:00:00 2001 From: umair Date: Tue, 9 Jun 2026 15:22:05 +0100 Subject: [PATCH 1/5] DX-1211: rewrite Auth interface docstrings (prerequisites, side-effects, 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) --- ably.d.ts | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/ably.d.ts b/ably.d.ts index 68a6fbe1e..69a31dd0b 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -2000,15 +2000,22 @@ export declare interface RealtimeClient { 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). + * + * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#client-id */ clientId: string; /** - * 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. * * @param tokenParams - A {@link TokenParams} object. * @param authOptions - An {@link AuthOptions} object. * @returns A promise which, upon success, will be fulfilled with a {@link TokenDetails} object. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error. + * @example + * ```ts + * const tokenDetails = await realtime.auth.authorize({ clientId: 'bob' }); + * ``` + * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#authorize */ authorize(tokenParams?: TokenParams, authOptions?: AuthOptions): Promise; /** @@ -2031,11 +2038,16 @@ export declare interface Auth { callback: StandardCallback, ): void; /** - * 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. * * @param tokenParams - A {@link TokenParams} object. * @param authOptions - An {@link AuthOptions} object. * @returns A promise which, upon success, will be fulfilled with a {@link TokenRequest} object. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error. + * @example + * ```ts + * const tokenRequest = await realtime.auth.createTokenRequest({ clientId: 'bob' }); + * ``` + * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#create-token-request */ createTokenRequest(tokenParams?: TokenParams, authOptions?: AuthOptions): Promise; /** @@ -2058,11 +2070,16 @@ export declare interface Auth { callback: StandardCallback, ): 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). + * 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}. * * @param TokenParams - A {@link TokenParams} object. * @param authOptions - An {@link AuthOptions} object. * @returns A promise which, upon success, will be fulfilled with a {@link TokenDetails} object. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error. + * @example + * ```ts + * const tokenDetails = await realtime.auth.requestToken({ clientId: 'bob' }); + * ``` + * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#request-token */ requestToken(TokenParams?: TokenParams, authOptions?: AuthOptions): Promise; /** @@ -2085,11 +2102,21 @@ export declare interface Auth { callback: StandardCallback, ): void; /** - * 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 + * token-authenticated client cannot revoke tokens and the call rejects with an {@link ErrorInfo}. + * Only tokens issued by an API key that had revocable tokens enabled before the token was issued + * can be revoked. * * @param specifiers - An array of {@link TokenRevocationTargetSpecifier} objects. * @param options - A set of options which are used to modify the revocation request. * @returns A promise which, upon success, will be fulfilled with a {@link BatchResult} containing information about the result of the token revocation request for each provided [`TokenRevocationTargetSpecifier`]{@link TokenRevocationTargetSpecifier}. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error. + * @example + * ```ts + * const result = await rest.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]); + * ``` + * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#revoke-tokens + * @see https://ably.com/docs/auth/revocation */ revokeTokens( specifiers: TokenRevocationTargetSpecifier[], From af311680e6dc0ad5674671283baeda1e2e325e45 Mon Sep 17 00:00:00 2001 From: umair Date: Thu, 25 Jun 2026 16:59:35 +0100 Subject: [PATCH 2/5] DX-1211: address PR #2242 review feedback on Auth docstrings 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) --- ably.d.ts | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/ably.d.ts b/ably.d.ts index 69a31dd0b..116720236 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -1999,14 +1999,22 @@ export declare interface RealtimeClient { */ 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). + * 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. * * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#client-id */ clientId: string; /** - * 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 is not 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 is rejected with an {@link ErrorInfo}. + * + * 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. * * @param tokenParams - A {@link TokenParams} object. * @param authOptions - An {@link AuthOptions} object. @@ -2038,7 +2046,11 @@ export declare interface Auth { callback: StandardCallback, ): void; /** - * 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 none 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's stored defaults are used, as specified at instantiation or later updated by an `authorize()` request. Any values passed in replace, rather than merge with, those defaults. * * @param tokenParams - A {@link TokenParams} object. * @param authOptions - An {@link AuthOptions} object. @@ -2070,7 +2082,9 @@ export declare interface Auth { callback: StandardCallback, ): void; /** - * 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 {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the client's stored defaults are used, as specified at instantiation or later updated by an `authorize()` request. Any values passed in replace, rather than merge 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}. * * @param TokenParams - A {@link TokenParams} object. * @param authOptions - An {@link AuthOptions} object. @@ -2103,10 +2117,10 @@ export declare interface Auth { ): void; /** * 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 - * token-authenticated client cannot revoke tokens and the call rejects with an {@link ErrorInfo}. - * Only tokens issued by an API key that had revocable tokens enabled before the token was issued - * can be revoked. + * + * The client making this call must be authenticated with an API key (basic auth), not a token. A token-authenticated client cannot revoke tokens and the call rejects with an {@link ErrorInfo}. + * + * Only tokens issued by an API key that had revocable tokens enabled before the token was issued can be revoked. * * @param specifiers - An array of {@link TokenRevocationTargetSpecifier} objects. * @param options - A set of options which are used to modify the revocation request. From aceeef5522798a9ab5e72890148057ae5ac0bb47 Mon Sep 17 00:00:00 2001 From: umair Date: Thu, 2 Jul 2026 15:36:39 +0100 Subject: [PATCH 3/5] DX-1211: fix Auth docstring subjects and unify stored-defaults phrasing 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 --- ably.d.ts | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/ably.d.ts b/ably.d.ts index 116720236..dbdbf4ee0 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -1999,7 +1999,11 @@ export declare interface RealtimeClient { */ 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. + * The client ID currently in effect for this client, used to identify it when publishing messages or entering presence. + * + * The value is resolved from the `clientId` in {@link ClientOptions} or from the `clientId` implicit in the token in use. A conflict between the two raises an {@link ErrorInfo}. + * + * The value is unset for an anonymous client, for example a key-authenticated client with no `clientId` configured. Guard against an unset value despite the declared type. * * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#client-id */ @@ -2008,13 +2012,13 @@ export declare interface Auth { /** * 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. + * 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. * - * The client must be able to issue tokens, so a `key`, `authUrl`, or `authCallback` must be configured in {@link ClientOptions}. If one of these is not configured the call rejects with an {@link ErrorInfo}. + * The client must have a way to obtain a token, so the resolved {@link AuthOptions} must include one of `authCallback`, `authUrl`, or `key`, or supply a token directly. Without any of these 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 is rejected with an {@link ErrorInfo}. * - * 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. + * Any {@link TokenParams} and {@link AuthOptions} passed in are stored as the new defaults for subsequent token requests. They replace, rather than merge with, the stored defaults. * * @param tokenParams - A {@link TokenParams} object. * @param authOptions - An {@link AuthOptions} object. @@ -2046,7 +2050,7 @@ export declare interface Auth { callback: StandardCallback, ): void; /** - * Creates and signs an Ably {@link TokenRequest} based on the specified {@link TokenParams} and {@link AuthOptions}. If none are specified it uses those previously stored by the library. Use this to implement an Ably Token request callback for use by other clients. + * Creates and signs an Ably {@link TokenRequest} based on the specified {@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 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. * @@ -2082,9 +2086,11 @@ export declare interface Auth { callback: StandardCallback, ): 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 client's stored defaults are used, as specified at instantiation or later updated by an `authorize()` request. Any values passed in replace, rather than merge with, those defaults. + * Obtains 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 client's stored defaults are used, as specified at instantiation or later updated by an `authorize()` request. Any values passed in replace, rather than merge 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}. + * 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 cannot request a new one and the call rejects with an {@link ErrorInfo}. * * @param TokenParams - A {@link TokenParams} object. * @param authOptions - An {@link AuthOptions} object. From 983b04c440ee0099cd75314b1eae78bdecab2f94 Mon Sep 17 00:00:00 2001 From: umair Date: Fri, 3 Jul 2026 11:40:01 +0100 Subject: [PATCH 4/5] DX-1211: single @see on revokeTokens with the revocation page inlined at the prerequisite Co-Authored-By: Claude Fable 5 --- ably.d.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ably.d.ts b/ably.d.ts index dbdbf4ee0..b34ac85d9 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -2126,7 +2126,7 @@ export declare interface Auth { * * The client making this call must be authenticated with an API key (basic auth), not a token. A token-authenticated client cannot revoke tokens and the call rejects with an {@link ErrorInfo}. * - * Only tokens issued by an API key that had revocable tokens enabled before the token was issued can be revoked. + * Only tokens issued by an API key that had [revocable tokens](https://ably.com/docs/auth/revocation) enabled before the token was issued can be revoked. * * @param specifiers - An array of {@link TokenRevocationTargetSpecifier} objects. * @param options - A set of options which are used to modify the revocation request. @@ -2136,7 +2136,6 @@ export declare interface Auth { * const result = await rest.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]); * ``` * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#revoke-tokens - * @see https://ably.com/docs/auth/revocation */ revokeTokens( specifiers: TokenRevocationTargetSpecifier[], From 8989f4c1401b27cb35fb38552f2a28365bf0055a Mon Sep 17 00:00:00 2001 From: umair Date: Thu, 30 Jul 2026 11:12:29 +0100 Subject: [PATCH 5/5] DX-1211: address 16 Jul review feedback on Auth docstrings and fix the clientId @see anchor From m-hulbert's 2026-07-16 review of PR #2242, with each change traced back to auth.ts / connectionmanager.ts: - clientId: drop "currently in effect" for the identity the client is identified as, and describe resolution as coming from the token the client authenticated with rather than "the token in use" - authorize: drop "live connection", which is not Ably terminology, and use one construction for both state references (C8); the three onAuthUpdated paths are re-authenticating a connection already in the `connected` state, or starting/restarting it from any other state - clientId, authorize, createTokenRequest, requestToken: restore a link to the relevant authentication concept, inline at the prerequisite and with no second @see, per the E4 shape confirmed on PR #2243 revokeTokens; this partially reverses the E1 link drop in af31168, which the reviewer asked about - clientId: point the @see at #properties, the anchor that actually exists on the now-published reference page; the methods carry kebab alias anchors () but properties sit in a table under one #properties h2, so #client-id resolved to the page top The reject sentence on authorize deliberately stays generic: the connected path only rejects on `failed`, so listing `closed` and `suspended` would be false there. All @see and inline URLs re-verified against the served HTML now that the reference is live. Co-Authored-By: Claude Opus 5 (1M context) --- ably.d.ts | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/ably.d.ts b/ably.d.ts index b34ac85d9..8fa7a23bb 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -1999,22 +1999,22 @@ export declare interface RealtimeClient { */ export declare interface Auth { /** - * The client ID currently in effect for this client, used to identify it when publishing messages or entering presence. + * The client ID this client is identified as when publishing messages or entering presence. * - * The value is resolved from the `clientId` in {@link ClientOptions} or from the `clientId` implicit in the token in use. A conflict between the two raises an {@link ErrorInfo}. + * The value is resolved from the `clientId` in {@link ClientOptions}, or from the `clientId` in the token the client authenticated with. A conflict between the two raises an {@link ErrorInfo}. * - * The value is unset for an anonymous client, for example a key-authenticated client with no `clientId` configured. Guard against an unset value despite the declared type. + * The value is unset for an anonymous client, for example a key-authenticated client with no `clientId` configured. A populated value makes this an [identified client](https://ably.com/docs/auth/identified-clients). Guard against an unset value despite the declared type. * - * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#client-id + * @see https://ably.com/docs/pub-sub/api/javascript/realtime/auth#properties */ clientId: string; /** * 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. + * On a realtime client it re-authenticates a connection that is already in the `connected` state, and otherwise starts or restarts the connection. The returned promise resolves only once the new token has taken effect on a connection in the `connected` state. It rejects with an {@link ErrorInfo} if re-authentication fails or the connection cannot be established. * - * The client must have a way to obtain a token, so the resolved {@link AuthOptions} must include one of `authCallback`, `authUrl`, or `key`, or supply a token directly. Without any of these the call rejects with an {@link ErrorInfo}. + * The client must have a way to obtain a token, so the resolved {@link AuthOptions} must include one of the [token authentication](https://ably.com/docs/auth/token) mechanisms `authCallback`, `authUrl`, or `key`, or a token supplied directly. Without any of these 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 is rejected with an {@link ErrorInfo}. * @@ -2052,7 +2052,7 @@ export declare interface Auth { /** * Creates and signs an Ably {@link TokenRequest} based on the specified {@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 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. + * 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 client using [token authentication](https://ably.com/docs/auth/token) 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's stored defaults are used, as specified at instantiation or later updated by an `authorize()` request. Any values passed in replace, rather than merge with, those defaults. * @@ -2090,7 +2090,7 @@ export declare interface Auth { * * Both {@link TokenParams} and {@link AuthOptions} are optional. When omitted or `null`, the client's stored defaults are used, as specified at instantiation or later updated by an `authorize()` request. Any values passed in replace, rather than merge 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 cannot request a new one and the call rejects with an {@link ErrorInfo}. + * The client must have a way to obtain a token, so the resolved {@link AuthOptions} must include one of the [token authentication](https://ably.com/docs/auth/token) mechanisms `authCallback`, `authUrl`, or `key`. A client given only a literal token cannot request a new one and the call rejects with an {@link ErrorInfo}. * * @param TokenParams - A {@link TokenParams} object. * @param authOptions - An {@link AuthOptions} object.