[DX-630] Add Kotlin Chat API references

src/data/nav/chat.ts

@@ -300,9 +300,53 @@ export default {
           external: true,
         },
         {
-          link: 'https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/',
-          name: 'Kotlin SDK',
-          external: true,
+          name: 'Kotlin',
+          pages: [
+            {
+              link: '/docs/chat/api/kotlin/chat-client',
+              name: 'ChatClient',
+            },
+            {
+              link: '/docs/chat/api/kotlin/connection',
+              name: 'Connection',
+            },
+            {
+              link: '/docs/chat/api/kotlin/rooms',
+              name: 'Rooms',
+            },
+            {
+              link: '/docs/chat/api/kotlin/room',
+              name: 'Room',
+            },
+            {
+              link: '/docs/chat/api/kotlin/messages',
+              name: 'Messages',
+            },
+            {
+              link: '/docs/chat/api/kotlin/message',
+              name: 'Message',
+            },
+            {
+              link: '/docs/chat/api/kotlin/message-reactions',
+              name: 'MessageReactions',
+            },
+            {
+              link: '/docs/chat/api/kotlin/presence',
+              name: 'Presence',
+            },
+            {
+              link: '/docs/chat/api/kotlin/occupancy',
+              name: 'Occupancy',
+            },
+            {
+              link: '/docs/chat/api/kotlin/typing',
+              name: 'Typing',
+            },
+            {
+              link: '/docs/chat/api/kotlin/room-reactions',
+              name: 'RoomReactions',
+            },
+          ],
         },
         {
           link: 'https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/',

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

@@ -0,0 +1,189 @@
+---
+title: ChatClient
+meta_description: "API reference for the ChatClient interface in the Ably Chat Kotlin SDK."
+meta_keywords: "Ably Chat SDK, Kotlin, ChatClient API, constructor, rooms, connection, clientId, realtime"
+---
+
+The `ChatClient` interface 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 factory function.
+
+<Code>
+```kotlin
+import com.ably.chat.ChatClient
+import com.ably.chat.LogLevel
+
+val realtimeClient = createRealtimeClient {
+    key = "{{API_KEY}}"
+    clientId = "<clientId>"
+}
+val chatClient = 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/kotlin/rooms) |
+| connection | The connection object, used to monitor the connection status with Ably. | [Connection](/docs/chat/api/kotlin/connection) |
+| clientId | The client ID configured on the underlying Ably Realtime client. Used to identify the current user. | String? |
+| realtime | The underlying Ably Realtime client instance. Note: this property is experimental and may change in a future release. | RealtimeClient |
+| 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. | `((LogEntry) -> Unit)?` |
+| stateDispatcher | Optional | The coroutine dispatcher used for managing state updates within the chat client. Allows controlling concurrency and dispatching of state management tasks. Note: this property is experimental and may change in a future release. | `CoroutineDispatcher` |
+
+</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>
+
+## Create a chat client <a id="constructor"/>
+
+<MethodSignature>{`ChatClient(realtimeClient: RealtimeClient, clientOptions: ChatClientOptions = buildChatClientOptions()): ChatClient`}</MethodSignature>
+
+Create a new `ChatClient` instance by passing an Ably Realtime client and optional configuration options. `ChatClient` is a top-level factory function, not a class constructor.
+
+<Code>
+```kotlin
+import com.ably.chat.ChatClient
+import com.ably.chat.buildChatClientOptions
+import com.ably.chat.LogLevel
+
+val realtimeClient = createRealtimeClient {
+    key = "{{API_KEY}}"
+    clientId = "user-123"
+}
+
+val chatClient = ChatClient(realtimeClient, buildChatClientOptions {
+    logLevel = LogLevel.Debug
+})
+```
+</Code>
+
+A DSL builder overload is also available:
+
+<MethodSignature>{`ChatClient(realtimeClient: RealtimeClient, init: MutableChatClientOptions.() -> Unit): ChatClient`}</MethodSignature>
+
+<Code>
+```kotlin
+val chatClient = ChatClient(realtimeClient) {
+    logLevel = LogLevel.Debug
+}
+```
+</Code>
+
+### Parameters <a id="constructor-params"/>
+
+The `ChatClient()` factory function takes the following parameters:
+
+<Table id='ConstructorParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| realtimeClient | Required | An instance of the Ably Realtime client, configured with your API key and a `clientId`. The `clientId` is required for all chat operations. | RealtimeClient |
+| clientOptions | Optional | Configuration options for the Chat client. | <Table id='ChatClientOptions'/> |
+
+</Table>
+
+## ChatException <a id="chatexception"/>
+
+A specialized exception class for errors that occur during chat operations. `ChatException` extends `RuntimeException` and wraps an [`ErrorInfo`](#errorinfo) object containing detailed error information. All suspend functions in the SDK throw `ChatException` on failure.
+
+<Table id='ChatExceptionProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| errorInfo | Detailed error information including Ably-specific error codes and HTTP status codes. | [ErrorInfo](#errorinfo) |
+| message | The exception message. | String? |
+| cause | The underlying cause of the exception, if any. | Throwable? |
+
+</Table>
+
+<Code>
+```kotlin
+import com.ably.chat.ChatException
+
+try {
+    room.messages.send(text = "Hello!")
+} catch (e: ChatException) {
+    println("Error code: ${e.errorInfo.code}")
+    println("Message: ${e.errorInfo.message}")
+    println("Status: ${e.errorInfo.statusCode}")
+}
+```
+</Code>
+
+## 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 thrown by the SDK are compatible with the `ErrorInfo` structure.
+
+<Table id='ErrorInfo'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| code | Ably-specific error code. | Int |
+| statusCode | HTTP status code corresponding to this error, where applicable. | Int |
+| message | Additional information about the error. | String |
+| href | A URL providing more information about the error. | String? |
+| cause | The underlying cause of the error. | ErrorInfo? |
+| requestId | The request ID if the error originated from an API request. | String? |
+
+</Table>
+
+## Example
+
+<Code>
+```kotlin
+import com.ably.chat.ChatClient
+import com.ably.chat.LogLevel
+
+val realtimeClient = createRealtimeClient {
+    key = "{{API_KEY}}"
+    clientId = "user-123"
+}
+
+val chatClient = ChatClient(realtimeClient) {
+    logLevel = LogLevel.Debug
+}
+
+// Access rooms
+val room = chatClient.rooms.get("my-room")
+
+// Check connection status
+println(chatClient.connection.status)
+
+// Get current user ID
+println(chatClient.clientId)
+```
+</Code>