Skip to content

Commit 3bb67a1

Browse files
m-hulbertm-hulbert
committed
Chat JS API references
1 parent f3ed2b9 commit 3bb67a1

File tree

15 files changed

+2874
-0
lines changed

15 files changed

+2874
-0
lines changed

‎src/data/nav/chat.ts‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,63 @@ export default {
160160
link: '/docs/api/chat-rest',
161161
name: 'REST API',
162162
},
163+
{
164+
name: 'JavaScript SDK',
165+
pages: [
166+
{
167+
name: 'Chat client',
168+
link: '/docs/chat/api/javascript/chat-client',
169+
},
170+
{
171+
name: 'Authentication',
172+
link: '/docs/chat/api/javascript/auth',
173+
},
174+
{
175+
name: 'Connection',
176+
link: '/docs/chat/api/javascript/connection',
177+
},
178+
{
179+
name: 'Rooms',
180+
link: '/docs/chat/api/javascript/rooms',
181+
},
182+
{
183+
name: 'Room',
184+
link: '/docs/chat/api/javascript/room',
185+
},
186+
{
187+
name: 'Room reactions',
188+
link: '/docs/chat/api/javascript/room-reactions',
189+
},
190+
{
191+
name: 'Message',
192+
link: '/docs/chat/api/javascript/message',
193+
},
194+
{
195+
name: 'Messages',
196+
link: '/docs/chat/api/javascript/messages',
197+
},
198+
{
199+
name: 'Message reactions',
200+
link: '/docs/chat/api/javascript/messages-reactions',
201+
},
202+
{
203+
name: 'Presence',
204+
link: '/docs/chat/api/javascript/presence',
205+
},
206+
{
207+
name: 'Occupancy',
208+
link: '/docs/chat/api/javascript/occupancy',
209+
},
210+
{
211+
name: 'Typing',
212+
link: '/docs/chat/api/javascript/typing',
213+
},
214+
{
215+
name: 'ErrorInfo',
216+
link: '/docs/chat/api/javascript/error-info',
217+
},
218+
],
219+
},
163220
],
164221
},
165222
],

‎src/pages/docs/chat/api/javascript/auth.mdx‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: Authentication
3+
meta_description: ""
4+
---
5+
6+
The [ChatClient](/docs/chat/api/javascript/chat-client) requires a realtime client generated by the core [Pub/Sub SDK](LINK) to establish a connection with Ably. This realtime client is used to handle authentication with Ably.
7+
8+
There are broadly three mechanisms of authentication with Ably:
9+
10+
* JSON Web Tokens (JWT): a standard JWT constructed to be compatible with Ably.
11+
* Ably Tokens: a token generated by the Ably service for authentication. Your server can create a tokenRequest for clients to authenticate with Ably, or it can request an Ably Token directly from Ably and pass that to clients.
12+
* Basic authentication: a method of authenticating using only your API key. This should only be used during development or server-side where it cannot be exposed.
13+
14+
JWTs are recommended for authenticating in a production environment. Use Ably Tokens your JWT is too large, such as when you are requesting a large set of capabilities, or have very long clientIds. This is because there is a limit on URL length in browsers when using JWTs as an accessToken query param. The other use-case for Ably Tokens is because claims are publicly visible in JWTs. Ably Tokens are encrypted so clientIds and capabilities cannot be inspected.
15+
16+
---
17+
18+
## Pub/Sub constructor
19+
20+
The Pub/Sub constructor instantiates a realtime client that can be passed to the [`ChatClient`](/docs/chat/api/javascript/chat-client).
21+
22+
`new Ably.Realtime(ClientOptions clientOptions)`
23+
24+
### Parameters
25+
26+
Use the following parameters:
27+
28+
| Parameter | Description | Type |
29+
| --------- | ----------- | ---- |
30+
| `clientOptions` | The options to pass to customize the client connection. | [`ClientOptions`](#clientoptions) |
31+
32+
### ClientOptions
33+
34+
The following `ClientOptions` can be set:
35+
36+
| Property | Description | Type |
37+
| -------- | ----------- | ---- |
38+
| `clientId` | *Optional* The identity of the client. It may also be implicit within an Ably Token or JWT. This is required to use the Chat SDK. | String |
39+
| `authUrl` | *Optional* A URL that the SDK uses to obtain a fresh Ably Token or JWT. | String |
40+
| `authCallback` | *Optional* A function in the form `function(tokenParams, callback(err, tokenOrTokenRequest))` which is called when a fresh Ably Token or JWT is required. | Callable |
41+
| `key` | *Optional* A full API key obtained from your Ably dashboard. This should only used with basic authentication for your authentication server or for clients in development environments. | String |
42+
43+
---
44+
45+
## Auth
46+
47+
The `Auth` interface creates TokenRequest objects and obtains Ably Tokens from Ably to issue to less-trusted clients.
48+
49+
Access it via `RealtimeClient.Auth`.
50+
51+
### Properties
52+
53+
It has the following properties:
54+
55+
| Property | Description | Type |
56+
| -------- | ----------- | ---- |
57+
| `clientId` | The identity of the client. It may also be implicit within an Ably Token or JWT. This is required to use the Chat SDK. | String |
58+
59+
---
60+
61+
## Fetch a new token <a id="authorize"/>
62+
63+
`auth.authorize()`
64+
65+
Instructs the SDK to fetch a new Ably Token or JWT.
66+
67+
It upgrades the current realtime connection to use the new token if the client is already connected. If they haven't yet connected then it initiates a connection to Ably.
68+
69+
Any [`TokenParams`](#tokenparams) and [`AuthOptions`](#authoptions) will be used as the new defaults for subsequent implicit and explicit token requests. They also entirely replace, as opposed to merging with, the current stored values.
70+
71+
`authorize(TokenParams tokenParams?, AuthOptions authOptions?): Promise<TokenDetails>`
72+
73+
### Parameters
74+
75+
Use the following parameters:
76+
77+
| Parameter | Description | Type |
78+
| --------- | ----------- | ---- |
79+
| `tokenParams` | *Optional* The parameters of the token for the request. | [`TokenParams`](#tokenparams) |
80+
| `authOptions` | *Optional* The authentication options for the request. | [`AuthOptions`](#authoptions) |
81+
82+
#### TokenParams
83+
84+
An object used in the parameters of token authentication requests for defining the required attributes of a token.
85+
86+
It has the following properties:
87+
88+
| Property | Description | Type |
89+
| -------- | ----------- | ---- |
90+
| `capability` | *Optional* The JSON stringified [capabilities](/docs/auth/capabilities) for the token. If the request is successful, this will be an intersection of these capabilities and the issuing API key. | String |
91+
| `clientId` | *Optional* The identity of the client. This is required to use the Chat SDK. | String |
92+
| `nonce` | *Optional* An opaque string of at least 16 characters to ensure uniqueness of the request. | String |
93+
| `timestamp` | *Optional* The timestamp of the request in milliseconds since the Unix epoch. Used with the `nonce` to ensure uniqueness of the request. | Integer |
94+
| `ttl` | *Optional* The time to live for the token in milliseconds. The default is 60 minutes. | Integer |
95+
96+
#### AuthOptions
97+
98+
An object used when making authentication requests. If supplied it will replace the default values provided when the connection was established rather than merging with them.
99+
100+
It has the following properties:
101+
102+
| Property | Description | Type |
103+
| -------- | ----------- | ---- |
104+
| `authCallback` | *Optional* A function in the form `function(tokenParams, callback(err, tokenOrTokenRequest))` which is called when a fresh Ably Token or JWT is required. | Callable |
105+
| `authUrl` | *Optional* A URL that the SDK uses to obtain a fresh Ably Token or JWT. | String |
106+
| `authMethod` | *Optional* The HTTP method to use for `authUrl` requests. Either `GET` or `POST`. The default is `GET`. | String |
107+
| `authHeaders` | *Optional* A set of key-value pair headers to add to `authUrl` requests. | Object |
108+
| `authParams` | *Optional* A set of key-value pairs to add to `authUrl` requests. When the `authMethod` is `GET` params are added to the URL. When the `authMethod` is `POST` they are sent as URL-encoded form data. | Object |
109+
| `tokenDetails` | *Optional* An authenticated `TokenDetails` object. This is commonly used in testing. In production it is preferable to use a method that renews the token automatically since they are short-lived. | [`TokenDetails`](#tokendetails) |
110+
| `key` | *Optional* A full API key string. Used for basic authentication requests. | String |
111+
| `token` | *Optional* An authenticated token. Either a `TokenDetails` object, a token string from the `token` property of a `TokenDetails` component of a `TokenRequest` response, or a JWT. This is commonly used in testing. In production it is preferable to use a method that renews the token automatically since they are short-lived. | String \| Object |
112+
| `queryTime` | *Optional* If `true`, queries Ably for the current time when issuing `TokenRequests`. The default is `false`. | Boolean |
113+
| `useTokenAuth` | *Optional* If `true`, forces the SDK to use token authentication. | Boolean |
114+
115+
#### TokenDetails
116+
117+
Contains an Ably Token and its associated metadata.
118+
119+
It has the following properties:
120+
121+
| Property | Description | Type |
122+
| -------- | ----------- | ---- |
123+
| `token` | The Ably Token itself. | String |
124+
| `expires` | The timestamp of when the token expires in milliseconds since the Unix epoch. | Integer |
125+
| `issued` | The timestamp of when the token was issued in milliseconds since the Unix epoch. | Integer |
126+
| `capability` | *Optional* The [capabilities](/docs/auth/capabilities) associated with the token. | String |
127+
| `clientId` | *Optional* The identity of the client. This is required to use the Chat SDK. | String |
128+
129+
#### TokenRequest
130+
131+
Contains the properties of a request for a token to Ably. Tokens are generated using [`requestToken()`](#requesttoken).
132+
133+
It has the following properties:
134+
135+
| Property | Description | Type |
136+
| -------- | ----------- | ---- |
137+
| `keyName` | The name of the API key against which the request was is made. Note that the name is public, whereas the secret is private. | String |
138+
| `timestamp` | The timestamp of when the request was made in milliseconds since the Unix epoch. | Integer |
139+
| `capability` | The [capabilities](/docs/auth/capabilities) for the token. If the request is successful, this will be an intersection of these capabilities and the issuing API key. | String |
140+
| `nonce` | An opaque string of at least 16 characters to ensure uniqueness of the request. | String |
141+
| `mac` | The Message Authentication Code (MAC) for the request. | String |
142+
| `ttl` | *Optional* The time to live for the token in milliseconds. | Integer |
143+
| `clientId` | *Optional* The identity of the client. This is required to use the Chat SDK. | String |
144+
145+
### Returns
146+
147+
Returns a promise. On success, the promise is fulfilled with the new [`TokenDetails`](#tokendetails) once the connection has been upgraded or initiated. On failure, the connection will move to the `SUSPENDED` or `FAILED` state, and the promise will be rejected with an [`ErrorInfo`](/docs/chat/api/javascript/error-info) object which explains the error.
148+
149+
---
150+
151+
## Create a tokenRequest <a id="createTokenRequest"/>
152+
153+
`auth.createTokenRequest()`
154+
155+
Creates and signs an Ably [`TokenRequest`](#tokenrequest) based on the specified [`TokenParams`](#tokenparams) and [`AuthOptions`](#authoptions). If no `TokenParams` or `AuthOptions` are specified it will use those already stored by the SDK, set in the [`ClientOptions`](#clientoptions) when the SDK was instantiated or updated via an [`authorize()`](#authorize) request. New values replace the existing ones rather than merging with them.
156+
157+
`createTokenRequest(TokenParams tokenParams?, AuthOptions authOptions?): Promise<TokenRequest>`
158+
159+
### Parameters
160+
161+
Use the following parameters:
162+
163+
| Parameter | Description | Type |
164+
| --------- | ----------- | ---- |
165+
| `tokenParams` | *Optional* The parameters of the token for the request. | [`TokenParams`](#tokenparams) |
166+
| `authOptions` | *Optional* The authentication options for the request. | [`AuthOptions`](#authoptions) |
167+
168+
### Returns
169+
170+
Returns a promise. On success it will be fulfilled with a [`TokenRequest`](#tokenrequest) object. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/chat/api/javascript/error-info) object which explains the error.
171+
172+
---
173+
174+
## Request a token <a id="requesttoken"/>
175+
176+
`auth.requestToken()`
177+
178+
Calls the `requestToken` endpoint to obtain an Ably Token according to the specified [`TokenParams`](#tokenparams) and [`AuthOptions`](#authoptions). If no `TokenParams` or `AuthOptions` are specified it will use those already stored by the SDK, set in the [`ClientOptions`](#clientoptions) when the SDK was instantiated or updated via an [`authorize()`](#authorize) request. New values replace the existing ones rather than merging with them.
179+
180+
`requestToken(TokenParams tokenParams?, AuthOptions authOptions?): Promise<TokenDetails>`
181+
182+
### Parameters
183+
184+
Use the following parameters:
185+
186+
| Parameter | Description | Type |
187+
| --------- | ----------- | ---- |
188+
| `tokenParams` | *Optional* The parameters of the token for the request. | [`TokenParams`](#tokenparams) |
189+
| `authOptions` | *Optional* The authentication options for the request. | [`AuthOptions`](#authoptions) |
190+
191+
### Returns
192+
193+
Returns a promise. On success it will be fulfilled with a [`TokenDetails`](#tokendetails) object. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/chat/api/javascript/error-info) object which explains the error.

‎src/pages/docs/chat/api/javascript/chat-client.mdx‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: ChatClient
3+
meta_description: ""
4+
---
5+
6+
The `ChatClient` class is the core client for Ably Chat.
7+
8+
---
9+
10+
## Accessors
11+
12+
| Property | Description | Type |
13+
| -------- | ----------- | ---- |
14+
| `clientId` | The clientId of the current client. | String |
15+
| `clientOptions` | The resolved client options for the client, including any defaults that have been set. | [`ChatClientOptions`](#chatclientoptions) |
16+
| `connection` | The underlying connection to Ably, which can be used to monitor the client's connection to Ably servers. | [`Connection`](/docs/chat/api/javascript/connection) |
17+
| `realtime` | The underlying Ably Realtime client. | [`Realtime`](#realtime) |
18+
| `rooms` | The rooms object, which provides access to chat rooms. | [`Rooms`](/docs/chat/api/javascript/rooms) |
19+
20+
---
21+
22+
## Constructor
23+
24+
`new ChatClient()`
25+
26+
Creates a new ChatClient instance.
27+
28+
`new ChatClient(realtime: Realtime, clientOptions?: ChatClientOptions): ChatClient`
29+
30+
### Parameters
31+
32+
Use the following parameters:
33+
34+
| Parameter | Description | Type |
35+
| --------- | ----------- | ---- |
36+
| `realtime` | The Ably Realtime client. | [`Realtime`](https://sdk.ably.com/builds/ably/ably-js/main/typedoc/) |
37+
| `clientOptions` | *Optional* The client options. | [`ChatClientOptions`](#chatclientoptions) |
38+
39+
#### ChatClientOptions
40+
41+
The following `ChatClientOptions` can be set:
42+
43+
| Properties | Description | Type |
44+
| ---------- | ----------- | ---- |
45+
| `logLevel` | *Optional* The logging level to use. | [`LogLevel`](#loglevel) |
46+
| `logHandler` | *Optional* A custom log handler. | [`LogHandler`](#loghandler) |
47+
48+
#### LogLevel
49+
50+
An enum representing the different log levels.
51+
52+
It has the following members:
53+
54+
| Member | Description |
55+
| ------ | ----------- |
56+
| `Silent` | No logging will be performed. |
57+
| `Trace` | Something routine and expected has occurred. This level will provide logs for the vast majority of operations and function calls. |
58+
| `Debug` | Development information, messages that are useful when trying to debug library behavior, but superfluous to normal operation. |
59+
| `Info` | Informational messages. Operationally significant to the library but not out of the ordinary. |
60+
| `Warn` | Anything that is not immediately an error, but could cause unexpected behavior in the future. For example, passing an invalid value to an option. Indicates that some action should be taken to prevent future errors. |
61+
| `Error` | A given operation has failed and cannot be automatically recovered. The error may threaten the continuity of operation. |
62+
63+
#### LogHandler
64+
65+
A function that handles log messages.
66+
67+
`LogHandler: (message: string, level: LogLevel, context?: LogContext) => void`
68+
69+
Use the following parameters:
70+
71+
| Parameter | Description | Type |
72+
| --------- | ----------- | ---- |
73+
| `message` | The message being logged. | String |
74+
| `logLevel` | The log level of the message. | [`LogLevel`](#loglevel) |
75+
| `context` | *Optional* The context of the log message as key-value pairs. | [`LogContext`](#logcontext) |
76+
77+
#### LogContext
78+
79+
Represents the context of a log message. It is an object of key-value pairs that can be used to provide additional context to a log message.
80+
81+
`LogContext: Record<string, any>`
82+
83+
### Returns
84+
85+
Returns a new `ChatClient` instance.
86+
87+
<Code>
88+
```javascript
89+
import * as Ably from 'ably';
90+
import { ChatClient } from '@ably/chat';
91+
92+
const realtimeClient = new Ably.Realtime({ key: 'your-api-key' });
93+
const chatClient = new ChatClient(realtimeClient, {
94+
logLevel: 'debug'
95+
});
96+
```
97+
</Code>
98+
99+
---
100+
101+
## Realtime
102+
103+
The Chat constructor requires a realtime client generated using the core [Pub/Sub SDK]() to establish a connection with Ably. The realtime client handles [authentication](/docs/chat/api/javascript/auth) with Ably.
104+
105+
`new Ably.Realtime(ClientOptions clientOptions)`
106+
107+
### Parameters
108+
109+
Use the following parameters:
110+
111+
| Parameter | Description | Type |
112+
| --------- | ----------- | ---- |
113+
| `clientOptions` | The options to pass to customize the client connection. | [`ClientOptions`](#clientoptions) |
114+
115+
### ClientOptions
116+
117+
The following `ClientOptions` can be set:
118+
119+
| Property | Description | Type |
120+
| -------- | ----------- | ---- |
121+
| `clientId` | *Optional* The identity of the client. It may also be implicit within an Ably Token or JWT. This is required to use the Chat SDK. | String |
122+
| `authUrl` | *Optional* A URL that the SDK uses to obtain a fresh Ably Token or JWT. | String |
123+
| `authCallback` | *Optional* A function in the form `function(tokenParams, callback(err, tokenOrTokenRequest))` which is called when a fresh Ably Token or JWT is required. | Callable |
124+
| `key` | *Optional* A full API key obtained from your Ably dashboard. This should only used with basic authentication for your authentication server or for clients in development environments. | String |

0 commit comments

Comments
 (0)