From 92b40708ca0f95132320ca962b784a33b7f069d6 Mon Sep 17 00:00:00 2001 From: Owen Pearson Date: Wed, 9 Nov 2022 18:03:34 +0000 Subject: [PATCH 1/4] fix: add PresenceCallback typings for no data/params signatures --- ably.d.ts | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/ably.d.ts b/ably.d.ts index 3cad48e4a7..1d756405c4 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -2079,6 +2079,12 @@ declare namespace Types { * @param callback - A function which, upon success, will be called with an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. */ get(params?: RealtimePresenceParams, callback?: realtimePresenceGetCallback): void; + /** + * Retrieves the current members present on the channel and the metadata for each member, such as their {@link PresenceAction} and ID. Returns an array of {@link PresenceMessage} objects. + * + * @param callback - A function which, upon success, will be called with an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. + */ + get(callback?: realtimePresenceGetCallback): void; /** * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link PresenceMessage} objects for the channel. If the channel is configured to persist messages, then presence messages can be retrieved from history for up to 72 hours in the past. If not, presence messages can only be retrieved from history for up to two minutes in the past. * @@ -2086,6 +2092,12 @@ declare namespace Types { * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. */ history(params?: RealtimeHistoryParams, callback?: paginatedResultCallback): void; + /** + * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link PresenceMessage} objects for the channel. If the channel is configured to persist messages, then presence messages can be retrieved from history for up to 72 hours in the past. If not, presence messages can only be retrieved from history for up to two minutes in the past. + * + * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link PresenceMessage} objects. Upon failure, the function will be called with information about the error. + */ + history(callback?: paginatedResultCallback): void; /** * Registers a listener that is called each time a {@link PresenceMessage} matching a given {@link PresenceAction}, or an action within an array of {@link PresenceAction | `PresenceAction`s}, is received on the channel, such as a new member entering the presence set. * @@ -2106,12 +2118,18 @@ declare namespace Types { */ subscribe(listener: messageCallback, callbackWhenAttached?: errorCallback): void; /** - * Enters the presence set for the channel, optionally passing a `data` payload. A `clientId` is required to be present on a channel. + * Enters the presence set for the channel, passing a `data` payload. A `clientId` is required to be present on a channel. * * @param data - The payload associated with the presence member. * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. */ enter(data?: any, callback?: errorCallback): void; + /** + * Enters the presence set for the channel. A `clientId` is required to be present on a channel. + * + * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + */ + enter(callback?: errorCallback): void; /** * Updates the `data` payload for a presence member. If called before entering the presence set, this is treated as an {@link PresenceAction.ENTER} event. * @@ -2126,6 +2144,12 @@ declare namespace Types { * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. */ leave(data?: any, callback?: errorCallback): void; + /** + * Leaves the presence set for the channel. A client must have previously entered the presence set before they can leave it. + * + * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + */ + leave(callback?: errorCallback): void; /** * Enters the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. * @@ -2134,6 +2158,13 @@ declare namespace Types { * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. */ enterClient(clientId: string, data?: any, callback?: errorCallback): void; + /** + * Enters the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. + * + * @param clientId - The ID of the client to enter into the presence set. + * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + */ + enterClient(clientId: string, callback?: errorCallback): void; /** * Updates the `data` payload for a presence member using a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. * @@ -2150,6 +2181,13 @@ declare namespace Types { * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. */ leaveClient(clientId: string, data?: any, callback?: errorCallback): void; + /** + * Leaves the presence set of the channel for a given `clientId`. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard `clientId`. + * + * @param clientId - The ID of the client to leave the presence set for. + * @param callback - A function which will be called upon completion of the operation. If the operation succeeded, then the function will be called with `null`. If it failed, the function will be called with information about the error. + */ + leaveClient(clientId: string, callback?: errorCallback): void; } /** From 74c638ba2e153018c091dc1636b4c8b9b76b299b Mon Sep 17 00:00:00 2001 From: Owen Pearson Date: Wed, 9 Nov 2022 18:05:53 +0000 Subject: [PATCH 2/4] fix: add typing for ChannelCallbacks.history with no params --- ably.d.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ably.d.ts b/ably.d.ts index 1d756405c4..9ada3e1b02 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -2298,6 +2298,12 @@ declare namespace Types { * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Message} objects. Upon failure, the function will be called with information about the error. */ history(params?: RestHistoryParams, callback?: paginatedResultCallback): void; + /** + * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link Message} objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past. + * + * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Message} objects. Upon failure, the function will be called with information about the error. + */ + history(callback?: paginatedResultCallback): void; /** * Publishes a single message to the channel with the given event name and payload. * From 8f18eab4e53db769cee66b7b16c2e1a1ff40dfb4 Mon Sep 17 00:00:00 2001 From: Owen Pearson Date: Wed, 9 Nov 2022 18:07:04 +0000 Subject: [PATCH 3/4] fix: add typing for RealtimeChannelCallbacks.history with no params --- ably.d.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ably.d.ts b/ably.d.ts index 9ada3e1b02..e69600fe72 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -2523,6 +2523,12 @@ declare namespace Types { * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Message} objects. Upon failure, the function will be called with information about the error. */ history(params?: RealtimeHistoryParams, callback?: paginatedResultCallback): void; + /** + * Retrieves a {@link Types.PaginatedResult} object, containing an array of historical {@link Message} objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past. + * + * @param callback - A function which, upon success, will be called with a {@link Types.PaginatedResult} object containing an array of {@link Message} objects. Upon failure, the function will be called with information about the error. + */ + history(callback?: paginatedResultCallback): void; /** * Sets the {@link ChannelOptions} for the channel. * From 3b0f71776ae49cf4304ff7e658e5e980482bed95 Mon Sep 17 00:00:00 2001 From: Owen Pearson Date: Wed, 9 Nov 2022 18:18:41 +0000 Subject: [PATCH 4/4] fix: add AuthCallbacks signatures with no params/options --- ably.d.ts | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/ably.d.ts b/ably.d.ts index e69600fe72..a25a510a58 100644 --- a/ably.d.ts +++ b/ably.d.ts @@ -1914,6 +1914,19 @@ declare namespace Types { * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. */ authorize(tokenParams?: TokenParams, authOptions?: AuthOptions, callback?: tokenDetailsCallback): void; + /** + * 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} passed in as the new default, to be used for all subsequent implicit or explicit token requests. Any {@link TokenParams} object passed in entirely replaces, as opposed to being merged with, the current client library saved value. + * + * @param tokenParams - A {@link TokenParams} object. + * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. + */ + authorize(tokenParams?: TokenParams, callback?: tokenDetailsCallback): void; + /** + * 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. + * + * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. + */ + authorize(callback?: tokenDetailsCallback): 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). * @@ -1926,6 +1939,19 @@ declare namespace Types { authOptions?: AuthOptions | null, callback?: tokenRequestCallback ): void; + /** + * Creates and signs an Ably {@link TokenRequest} based on the specified (or if none specified, the client library stored) {@link TokenParams}. Note this can only be used when the API `key` value is available locally. Otherwise, the Ably {@link TokenParams} 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. When the {@link TokenRequest} is omitted or `null`, the default token parameters 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). + * + * @param tokenParams - A {@link TokenParams} object. + * @param callback - A function which, upon success, will be called with a {@link TokenRequest} object. Upon failure, the function will be called with information about the error. + */ + createTokenRequest(tokenParams?: TokenParams | null, callback?: tokenRequestCallback): void; + /** + * Creates and signs an Ably {@link TokenRequest} based on the 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. 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. 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). + * + * @param callback - A function which, upon success, will be called with a {@link TokenRequest} object. Upon failure, the function will be called with information about the error. + */ + createTokenRequest(callback?: tokenRequestCallback): 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). * @@ -1938,6 +1964,19 @@ declare namespace Types { authOptions?: AuthOptions | null, callback?: tokenDetailsCallback ): void; + /** + * Calls the `requestToken` REST API endpoint to obtain an Ably Token according to the specified {@link TokenParams}. 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). + * + * @param TokenParams - A {@link TokenParams} object. + * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. + */ + requestToken(TokenParams?: TokenParams | null, callback?: tokenDetailsCallback): void; + /** + * Calls the `requestToken` REST API endpoint to obtain an Ably Token. 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. 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). + * + * @param callback - A function which, upon success, will be called with a {@link TokenDetails} object. Upon failure, the function will be called with information about the error. + */ + requestToken(callback?: tokenDetailsCallback): void; } /**