[DX-631] Pub/Sub JavaScript SDK API references (realtime interface)

src/data/nav/pubsub.ts

@@ -405,6 +405,45 @@ export default {
           link: '/docs/api',
           index: true,
         },
+        {
+          name: 'JavaScript SDK',
+          pages: [
+            {
+              name: 'Realtime interface',
+              pages: [
+                { name: 'Realtime client', link: '/docs/pub-sub/api/javascript/realtime/realtime-client' },
+                { name: 'Auth', link: '/docs/pub-sub/api/javascript/realtime/auth' },
+                { name: 'Connection', link: '/docs/pub-sub/api/javascript/realtime/connection' },
+                { name: 'Crypto', link: '/docs/pub-sub/api/javascript/realtime/crypto' },
+                {
+                  name: 'Channels and messages',
+                  pages: [
+                    { name: 'Channels', link: '/docs/pub-sub/api/javascript/realtime/channels' },
+                    { name: 'RealtimeChannel', link: '/docs/pub-sub/api/javascript/realtime/realtime-channel' },
+                    { name: 'ChannelDetails', link: '/docs/pub-sub/api/javascript/realtime/channel-details' },
+                    { name: 'Message', link: '/docs/pub-sub/api/javascript/realtime/message' },
+                    { name: 'RealtimeAnnotations', link: '/docs/pub-sub/api/javascript/realtime/realtime-annotations' },
+                  ],
+                },
+                {
+                  name: 'Presence',
+                  pages: [
+                    { name: 'RealtimePresence', link: '/docs/pub-sub/api/javascript/realtime/realtime-presence' },
+                    { name: 'PresenceMessage', link: '/docs/pub-sub/api/javascript/realtime/presence-message' },
+                  ],
+                },
+                {
+                  name: 'Push notifications',
+                  pages: [
+                    { name: 'Push', link: '/docs/pub-sub/api/javascript/realtime/push' },
+                    { name: 'PushChannel', link: '/docs/pub-sub/api/javascript/realtime/push-channel' },
+                    { name: 'PushAdmin', link: '/docs/pub-sub/api/javascript/realtime/push-admin' },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
         {
           name: 'Realtime SDK',
           pages: [
@@ -589,6 +628,11 @@ export default {
           name: 'SSE API',
           link: '/docs/api/sse',
         },
+        {
+          link: 'https://ably.com/docs/sdk/js/v2.0/',
+          name: 'JavaScript SDK (TypeDoc)',
+          external: true,
+        },
       ],
     },
   ],

src/pages/docs/pub-sub/api/javascript/realtime/channel-details.mdx

@@ -0,0 +1,101 @@
+---
+title: ChannelDetails
+meta_description: "API reference for channel metadata (ChannelDetails) in the Ably Pub/Sub JavaScript Realtime SDK."
+meta_keywords: "Ably Pub/Sub SDK, JavaScript, channel metadata, ChannelDetails, ChannelStatus, occupancy, metrics, metachannel"
+---
+
+Channel metadata describes the current state of a channel, including whether it is active and its [occupancy](/docs/presence-occupancy/occupancy) metrics. It is represented by the `ChannelDetails` type.
+
+A realtime client receives `ChannelDetails` payloads in two ways:
+
+- By subscribing to a [metachannel](/docs/metadata-stats/metadata) such as `[meta]channel.lifecycle`, where each message's `data` is a `ChannelDetails` object describing a channel lifecycle event.
+- By subscribing to a channel with the [`occupancy` channel option](/docs/channels/options#occupancy) enabled, which delivers `[meta]occupancy` events whose `data` contains the channel's occupancy metrics.
+
+The canonical, typed way to fetch a channel's current `ChannelDetails` on demand is the REST SDK's `channel.status()` method; over a realtime connection the same information arrives asynchronously as the events described above.
+
+<Code>
+```javascript
+// Receive channel lifecycle events, each carrying a ChannelDetails payload
+const metaChannel = realtime.channels.get('[meta]channel.lifecycle');
+await metaChannel.subscribe((message) => {
+  const details = message.data;
+  console.log(details.channelId, details.status.occupancy.metrics.connections);
+});
+
+// Receive occupancy events by enabling the occupancy channel option
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', {
+  params: { occupancy: 'metrics' },
+});
+await channel.subscribe('[meta]occupancy', (message) => {
+  console.log(message.data.metrics);
+});
+```
+</Code>
+
+## ChannelDetails <a id="ChannelDetails"/>
+
+A `ChannelDetails` object contains information about a channel, along with its current state in a `ChannelStatus` object.
+
+<Table id='ChannelDetailsProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| channelId | The name of the channel, including any qualifier. | String |
+| status | The current state of the channel. | <Table id='ChannelStatus'/> |
+
+</Table>
+
+<Table id='ChannelStatus' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| isActive | Whether the channel is active. For events indicating regional activity, this reflects activity in that region rather than global activity. | Boolean |
+| occupancy | The occupancy of the channel. For events indicating regional activity, this reflects activity in that region rather than global activity. | <Table id='ChannelOccupancy'/> |
+
+</Table>
+
+<Table id='ChannelOccupancy' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| metrics | The occupancy metrics for the channel. | <Table id='ChannelMetrics'/> |
+
+</Table>
+
+<Table id='ChannelMetrics' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| connections | The number of connections attached to the channel. | Number |
+| publishers | The number of connections attached to the channel that are authorized to publish. | Number |
+| subscribers | The number of connections attached that are authorized to subscribe to messages. | Number |
+| presenceConnections | The number of connections that are authorized to enter members into the presence set. | Number |
+| presenceMembers | The number of members currently entered into the presence set. | Number |
+| presenceSubscribers | The number of connections that are authorized to subscribe to presence messages. | Number |
+
+</Table>
+
+## Example
+
+The following is an example of a `ChannelDetails` payload:
+
+<Code>
+```json
+{
+  "channelId": "foo",
+  "status": {
+    "isActive": true,
+    "occupancy": {
+      "metrics": {
+        "connections": 1,
+        "publishers": 1,
+        "subscribers": 1,
+        "presenceConnections": 1,
+        "presenceMembers": 0,
+        "presenceSubscribers": 1
+      }
+    }
+  }
+}
+```
+</Code>

src/pages/docs/pub-sub/api/javascript/realtime/channels.mdx

@@ -0,0 +1,189 @@
+---
+title: Channels
+meta_description: "API reference for the Channels interface in the Ably Pub/Sub JavaScript Realtime SDK."
+meta_keywords: "Ably Pub/Sub SDK, JavaScript, Channels API, get, getDerived, release, ChannelOptions, DeriveOptions"
+---
+
+The `Channels` interface is used to create and destroy [`RealtimeChannel`](/docs/pub-sub/api/javascript/realtime/realtime-channel) objects. Access it via the `channels` property of a [`Realtime`](/docs/pub-sub/api/javascript/realtime/realtime-client) client instance.
+
+<Code>
+```javascript
+const channels = realtime.channels;
+```
+</Code>
+
+## Properties
+
+The `Channels` interface has the following properties:
+
+<Table id='ChannelsProperties'>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| all | A map of all the channels that have been instantiated via [`get()`](#get) and have not yet been released via [`release()`](#release). | `Record<String, RealtimeChannel>` |
+
+</Table>
+
+## Get a channel <a id="get"/>
+
+<MethodSignature>{`channels.get(name: string, channelOptions?: ChannelOptions): RealtimeChannel`}</MethodSignature>
+
+Creates a new [`RealtimeChannel`](/docs/pub-sub/api/javascript/realtime/realtime-channel) object if none for the given name exists, or returns the existing channel object. The channel is created or returned with the supplied `ChannelOptions`.
+
+<Code>
+```javascript
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+// With channel options
+const encryptedChannel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', {
+  cipher: { key: '<key>' }
+});
+```
+</Code>
+
+### Parameters <a id="get-params"/>
+
+The `get()` method takes the following parameters:
+
+<Table id='GetParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| name | Required | The name of the channel. | String |
+| channelOptions | Optional | Options for the channel, such as encryption or channel parameters. | <Table id='ChannelOptions'/> |
+
+</Table>
+
+<Table id='ChannelOptions' hidden>
+
+| Property | Required | Description | Type |
+| --- | --- | --- | --- |
+| cipher | Optional | Requests [encryption](/docs/channels/options/encryption) for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length, and key). | <Table id='CipherParams'/> or <Table id='CipherParamOptions'/> |
+| params | Optional | [Channel parameters](/docs/channels/options) that configure the behavior of the channel. Supported params include [`rewind`](/docs/channels/options/rewind), [`delta`](/docs/channels/options/deltas), [`occupancy`](/docs/presence-occupancy/occupancy), and [`echo`](/docs/channels/options/echo). | `Record<String, String>` |
+| modes | Optional | An array of channel mode values that restrict the operations a client can perform on a channel. | Array of <Table id='ChannelMode'/> |
+| attachOnSubscribe | Optional | Whether calling [`subscribe()`](/docs/pub-sub/api/javascript/realtime/realtime-channel#subscribe) on a channel or presence object should trigger an implicit attach. Default: `true`. | Boolean |
+
+</Table>
+
+<Table id='CipherParams' hidden>
+
+| Property | Description | Type |
+| --- | --- | --- |
+| key | The private key used for encryption and decryption. Do not set this value directly; pass a key to [`Crypto.getDefaultParams()`](/docs/pub-sub/api/javascript/realtime/crypto#get-default-params) instead. | `unknown` |
+| algorithm | The name of the algorithm. Default: `AES`. | String |
+| keyLength | The key length in bits of the cipher. Either 128 or 256. Default: 256. | Number |
+| mode | The cipher mode. Default: `CBC`. | String |
+
+</Table>
+
+<Table id='CipherParamOptions' hidden>
+
+| Property | Required | Description | Type |
+| --- | --- | --- | --- |
+| key | Required | The private key used for encryption and decryption. Can be binary or base64-encoded. | `ArrayBuffer`, `Uint8Array`, or String |
+| algorithm | Optional | The name of the algorithm. Default: `AES`. | String |
+| keyLength | Optional | The key length in bits. Either 128 or 256. Default: 256. | Number |
+| mode | Optional | The cipher mode. Default: `CBC`. | String |
+
+</Table>
+
+<Table id='ChannelMode' hidden>
+
+| Value | Description |
+| --- | --- |
+| PUBLISH | The client can publish messages to the channel. |
+| SUBSCRIBE | The client can subscribe to messages on the channel. |
+| PRESENCE | The client can enter the presence set on the channel. |
+| PRESENCE_SUBSCRIBE | The client can subscribe to presence events on the channel. |
+| OBJECT_PUBLISH | The client can publish LiveObjects messages on the channel. |
+| OBJECT_SUBSCRIBE | The client can subscribe to LiveObjects messages on the channel. |
+| ANNOTATION_PUBLISH | The client can publish annotations on the channel. |
+| ANNOTATION_SUBSCRIBE | The client can subscribe to annotations on the channel. |
+
+</Table>
+
+### Returns <a id="get-returns"/>
+
+`RealtimeChannel`
+
+Returns a [`RealtimeChannel`](/docs/pub-sub/api/javascript/realtime/realtime-channel) object for the given name. If a channel with that name already exists, the existing object is returned.
+
+## Get a derived channel <a id="get-derived"/>
+
+<MethodSignature>{`channels.getDerived(name: string, deriveOptions: DeriveOptions, channelOptions?: ChannelOptions): RealtimeChannel`}</MethodSignature>
+
+Creates a new [`RealtimeChannel`](/docs/pub-sub/api/javascript/realtime/realtime-channel) object if none for the given name exists, or returns the existing channel object. The channel is created or returned with the specified `DeriveOptions` and optional `ChannelOptions`.
+
+Derived channels enable you to subscribe to a filtered subset of messages on a channel using [subscription filters](/docs/channels#subscription-filters).
+
+<Aside data-type='experimental'>
+`getDerived()` is a preview feature and may change in a future non-major release.
+</Aside>
+
+<Code>
+```javascript
+const derived = realtime.channels.getDerived('{{RANDOM_CHANNEL_NAME}}', {
+  filter: "name == 'important'"
+});
+```
+</Code>
+
+### Parameters <a id="get-derived-params"/>
+
+The `getDerived()` method takes the following parameters:
+
+<Table id='GetDerivedParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| name | Required | The name of the channel. | String |
+| deriveOptions | Required | The derive options used to filter the channel. | <Table id='DeriveOptions'/> |
+| channelOptions | Optional | Options for the channel. | <Table id='ChannelOptions'/> |
+
+</Table>
+
+<Table id='DeriveOptions' hidden>
+
+| Property | Required | Description | Type |
+| --- | --- | --- | --- |
+| filter | Optional | The [JMESPath](https://jmespath.org/) query filter string used to derive the new channel. | String |
+
+</Table>
+
+### Returns <a id="get-derived-returns"/>
+
+`RealtimeChannel`
+
+Returns a derived [`RealtimeChannel`](/docs/pub-sub/api/javascript/realtime/realtime-channel) object configured with the supplied filter.
+
+## Release a channel <a id="release"/>
+
+<MethodSignature>{`channels.release(name: string): void`}</MethodSignature>
+
+Releases all SDK-held references to a [`RealtimeChannel`](/docs/pub-sub/api/javascript/realtime/realtime-channel) object, enabling it to be garbage collected. Useful for applications that work with a continually changing set of channels on a single client and need to avoid unbounded memory growth; if this does not describe your application, don't call it.
+
+<Aside data-type='important'>
+This method has no guardrails: using a channel reference after `release()` has been called is undefined behaviour.
+</Aside>
+
+This method only affects the local client-side representation of the channel. The channel itself on the Ably platform is not deleted or changed, and other client instances (in the same or different processes) are unaffected.
+
+Channels not already in the `initialized`, `detached`, or `failed` [state](/docs/channels/states) are detached before release. After release, calling [`channels.get()`](#get) with the same name returns a fresh channel object in the `initialized` state.
+
+<Code>
+```javascript
+realtime.channels.release('{{RANDOM_CHANNEL_NAME}}');
+```
+</Code>
+
+### Parameters <a id="release-params"/>
+
+The `release()` method takes the following parameters:
+
+<Table id='ReleaseParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| name | Required | The name of the channel to release. | String |
+
+</Table>