[DX-627] Adds an API reference for Chat in JavaScript

src/data/nav/chat.ts

@@ -212,9 +212,53 @@ export default {
           name: 'Overview',
         },
         {
-          link: 'https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/modules/chat-js.html',
-          name: 'JavaScript SDK',
-          external: true,
+          name: 'JavaScript',
+          pages: [
+            {
+              link: '/docs/chat/api/javascript/chat-client',
+              name: 'ChatClient',
+            },
+            {
+              link: '/docs/chat/api/javascript/connection',
+              name: 'Connection',
+            },
+            {
+              link: '/docs/chat/api/javascript/rooms',
+              name: 'Rooms',
+            },
+            {
+              link: '/docs/chat/api/javascript/room',
+              name: 'Room',
+            },
+            {
+              link: '/docs/chat/api/javascript/messages',
+              name: 'Messages',
+            },
+            {
+              link: '/docs/chat/api/javascript/message',
+              name: 'Message',
+            },
+            {
+              link: '/docs/chat/api/javascript/message-reactions',
+              name: 'MessageReactions',
+            },
+            {
+              link: '/docs/chat/api/javascript/presence',
+              name: 'Presence',
+            },
+            {
+              link: '/docs/chat/api/javascript/occupancy',
+              name: 'Occupancy',
+            },
+            {
+              link: '/docs/chat/api/javascript/typing',
+              name: 'Typing',
+            },
+            {
+              link: '/docs/chat/api/javascript/room-reactions',
+              name: 'RoomReactions',
+            },
+          ],
         },
         {
           link: 'https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/modules/chat-react.html',

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

@@ -0,0 +1,173 @@
+---
+title: ChatClient
+meta_description: "API reference for the ChatClient class in the Ably Chat JavaScript SDK."
+meta_keywords: "Ably Chat SDK, JavaScript, ChatClient API, constructor, dispose, rooms, connection, clientId, realtime"
+---
+
+The `ChatClient` class is the main entry point for using the Ably Chat SDK. It provides access to chat rooms, connection management, and the underlying Ably Realtime client.
+
+The Chat SDK is built on top of the Ably Pub/Sub SDK and uses that to establish a connection with Ably. Instantiate a realtime client using the Pub/Sub SDK and pass the generated client into the Chat constructor.
+
+<Code>
+```javascript
+import { LogLevel } from '@ably/chat'
+
+const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', clientId: '<clientId>'});
+const chatClient = new ChatClient(realtimeClient, { logLevel: LogLevel.Error });
+```
+</Code>
+
+An API key is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using basic authentication, or to generate tokens for untrusted clients using [JWT authentication](/docs/auth/token#jwt).
+
+<Aside data-type='important'>
+Basic authentication should never be used on the client-side in production, as it exposes your Ably API key. Instead, use JWT authentication.
+</Aside>
+
+## Properties
+
+The `ChatClient` interface has the following properties:
+
+<Table id='ChatClientProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| rooms | The rooms object, used to get or create chat room instances. | [Rooms](/docs/chat/api/javascript/rooms) |
+| connection | The connection object, used to monitor the connection status with Ably. | [Connection](/docs/chat/api/javascript/connection) |
+| clientId | The client ID configured on the underlying Ably Realtime client. Used to identify the current user. May be `undefined` until authenticated with a token. | String or Undefined |
+| realtime | The underlying Ably Realtime client instance. | Ably.Realtime |
+| clientOptions | The resolved configuration options with defaults applied. | <Table id='ChatClientOptions'/> |
+
+</Table>
+
+<Table id='ChatClientOptions' hidden>
+
+| Property | Required | Description | Type |
+| --- | --- | --- | --- |
+| logLevel | Optional | The logging level to use. Default: `LogLevel.Error`. | <Table id='LogLevel'/> |
+| logHandler | Optional | A custom log handler function that receives log messages from the SDK. | <Table id='LogHandler'/> |
+
+</Table>
+
+<Table id='LogLevel' hidden>
+
+| Value | Description |
+| --- | --- |
+| Trace | Log all messages. |
+| Debug | Log debug, info, warn, and error messages. |
+| Info | Log info, warn, and error messages. |
+| Warn | Log warn and error messages. |
+| Error | Log error messages only. |
+| Silent | Disable logging. |
+
+</Table>
+
+<Table id='LogHandler' hidden>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| message | Required | The log message. | String |
+| level | Required | The severity level of the log message. | <Table id='LogLevel'/> |
+| context | Optional | Additional contextual data associated with the log entry. | <Table id='LogContext'/> |
+
+</Table>
+
+<Table id='LogContext' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| | Additional contextual key-value pairs associated with a log message. | `Record<string, any>` |
+
+</Table>
+
+## Create a new chat client <a id="constructor"/>
+
+<MethodSignature>{`new ChatClient(realtime: Realtime, clientOptions?: ChatClientOptions)`}</MethodSignature>
+
+Create a new `ChatClient` instance by passing an Ably Realtime client and optional configuration options.
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { ChatClient } from '@ably/chat';
+
+const realtimeClient = new Ably.Realtime({
+  key: '{{API_KEY}}',
+  clientId: 'user-123'
+});
+
+const chatClient = new ChatClient(realtimeClient, clientOptions);
+```
+</Code>
+
+### Parameters <a id="constructor-params"/>
+
+The `ChatClient()` constructor takes the following parameters:
+
+<Table id='ConstructorParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| realtime | Required | An instance of the Ably Realtime client, configured with your API key and a `clientId`. The `clientId` is required for all chat operations. | Ably.Realtime |
+| clientOptions | Optional | Configuration options for the Chat client. | <Table id='ChatClientOptions'/> |
+
+</Table>
+
+## Dispose of the chat client <a id="dispose"/>
+
+<MethodSignature>{`chatClient.dispose(): Promise<void>`}</MethodSignature>
+
+Disposes of the ChatClient instance and releases all resources, including all chat rooms. After calling this method, the ChatClient instance is no longer usable.
+
+<Code>
+```javascript
+await chatClient.dispose();
+```
+</Code>
+
+### Returns <a id="dispose-returns"/>
+
+`Promise<void>`
+
+Returns a promise. The promise is fulfilled when the client has been disposed, or rejected with an [`ErrorInfo`](#errorinfo) object.
+
+## ErrorInfo <a id="errorinfo"/>
+
+A standardized, generic Ably error object that contains an Ably-specific status code, and a generic HTTP status code. All errors returned from Ably are compatible with the `ErrorInfo` structure.
+
+<Table id='ErrorInfo'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| code | Ably-specific error code. | Number |
+| statusCode | HTTP status code corresponding to this error, where applicable. | Number |
+| message | Additional information about the error. | String |
+| cause | The underlying cause of the error, where applicable. | String, ErrorInfo, or Error |
+
+</Table>
+
+## Example
+
+<Code>
+```javascript
+import * as Ably from 'ably';
+import { ChatClient, LogLevel } from '@ably/chat';
+
+const realtimeClient = new Ably.Realtime({
+  key: '{{API_KEY}}',
+  clientId: 'user-123'
+});
+
+const chatClient = new ChatClient(realtimeClient, {
+  logLevel: LogLevel.Debug
+});
+
+// Access rooms
+const room = await chatClient.rooms.get('my-room');
+
+// Check connection status
+console.log(chatClient.connection.status);
+
+// Get current user ID
+console.log(chatClient.clientId);
+```
+</Code>

src/pages/docs/chat/api/javascript/connection.mdx

@@ -0,0 +1,139 @@
+---
+title: Connection
+meta_description: "API reference for the Connection interface in the Ably Chat JavaScript SDK."
+meta_keywords: "Ably Chat SDK, JavaScript, Connection API, onStatusChange, status, error, ConnectionStatus"
+---
+
+The `Connection` interface represents the connection to Ably and provides methods to monitor connection status changes. Access the connection via `chatClient.connection`.
+
+<Code>
+```javascript
+const connection = chatClient.connection;
+```
+</Code>
+
+## Properties
+
+The `Connection` interface has the following properties:
+
+<Table id='ConnectionProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| status | The current connection status. | <Table id='ConnectionStatus'/> |
+| error | The error that caused the connection to enter its current status, if any. | [ErrorInfo](/docs/chat/api/javascript/chat-client#errorinfo) or Undefined |
+
+</Table>
+
+<Table id='ConnectionStatus' hidden>
+
+| Status | Description |
+| --- | --- |
+| Initialized | A temporary state for when the library is first initialized. The value is `initialized`. |
+| Connecting | The library is currently connecting to Ably. The value is `connecting`. |
+| Connected | A connection exists and is active. The value is `connected`. |
+| Disconnected | The library is currently disconnected from Ably, but will attempt to reconnect. The value is `disconnected`. |
+| Suspended | The library is in an extended state of disconnection, but will attempt to reconnect. The value is `suspended`. |
+| Failed | The library is currently disconnected from Ably and will not attempt to reconnect. The value is `failed`. |
+| Closing | An explicit request by the developer to close the connection has been sent to the Ably service. The value is `closing`. |
+| Closed | The connection has been explicitly closed by the client. No reconnection attempts are made automatically. The value is `closed`. |
+
+</Table>
+
+## Subscribe to connection status changes <a id="onStatusChange"/>
+
+<MethodSignature>{`connection.onStatusChange(listener: ConnectionStatusListener): StatusSubscription`}</MethodSignature>
+
+Registers a listener to be notified of connection status changes.
+
+<Code>
+```javascript
+const { off } = chatClient.connection.onStatusChange((change) => {
+  console.log('Status changed from', change.previous, 'to', change.current);
+  if (change.error) {
+    console.error('Error:', change.error);
+  }
+  if (change.retryIn) {
+    console.log('Retrying in', change.retryIn, 'ms');
+  }
+});
+
+// To unsubscribe
+off();
+```
+</Code>
+
+### Parameters <a id="onStatusChange-params"/>
+
+The `onStatusChange()` method takes the following parameters:
+
+<Table id='OnStatusChangeParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| listener | Required | A callback invoked on status changes. | <Table id='ConnectionStatusListener' /> |
+
+</Table>
+
+<Table id='ConnectionStatusListener' hidden>
+
+| Parameter | Description | Type |
+| --- | --- | --- |
+| change | The status change event. | <Table id='ConnectionStatusChange' /> |
+
+</Table>
+
+<Table id='ConnectionStatusChange' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| current | The new connection status. | <Table id='ConnectionStatus' /> |
+| previous | The previous connection status. | <Table id='ConnectionStatus' /> |
+| error | An error that provides a reason why the connection has entered the new status, if applicable. | [ErrorInfo](/docs/chat/api/javascript/chat-client#errorinfo) or Undefined |
+| retryIn | The time in milliseconds that the client will wait before attempting to reconnect, if applicable. | Number or Undefined |
+
+</Table>
+
+### Returns <a id="onStatusChange-returns"/>
+
+`StatusSubscription`
+
+Returns an object with the following methods:
+
+#### Deregister the listener <a id="onStatusChange-off"/>
+
+<MethodSignature>off(): void</MethodSignature>
+
+Call `off()` to deregister the connection status listener.
+
+### Example
+
+<Code>
+```javascript
+import { ConnectionStatus } from '@ably/chat';
+
+// Monitor connection status
+const { off } = chatClient.connection.onStatusChange((change) => {
+  switch (change.current) {
+    case ConnectionStatus.Connected:
+      console.log('Connected to Ably');
+      break;
+    case ConnectionStatus.Disconnected:
+      console.log('Disconnected, will retry...');
+      break;
+    case ConnectionStatus.Suspended:
+      console.log('Connection suspended, retrying in', change.retryIn, 'ms');
+      break;
+    case ConnectionStatus.Failed:
+      console.error('Connection failed:', change.error);
+      break;
+  }
+});
+
+// Check current status
+console.log('Current status:', chatClient.connection.status);
+
+// Clean up when done
+off();
+```
+</Code>