Merge pull request #2569 from ably/integration/chat-single-channel

Chat single channel updates

Author: splindsay-92

content/chat/connect.textile

@@ -144,15 +144,15 @@ If a client briefly loses connection to Ably, for example when driving through a
 During periods of discontinuity greater than 2 minutes then you will need to take steps to recover any missed messages, such as by calling "history":/docs/chat/rooms/history.
 
 blang[javascript,swift,kotlin].
-  Each feature of the Chat SDK provides an @onDiscontinuity()@ handler to assist with this. These methods enable you to register a listener that will be notified when discontinuity occurs in that feature so that you can handle it, as needed.
+  The Chat SDK provides an @onDiscontinuity()@ handler exposed via the Room object to assist with this. This method enables you to register a listener that will be notified when discontinuity occurs in the room so that you can handle it, as needed.
 
 blang[react].
   Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a listener to be notified of, and handle, periods of discontinuity.
 
 For example, for messages:
 
 ```[javascript]
-const { off } = room.messages.onDiscontinuity((reason?: ErrorInfo) => {
+const { off } = room.onDiscontinuity((reason: ErrorInfo) => {
   // Recover from the discontinuity
 });
 ```
@@ -173,14 +173,14 @@ const MyComponent = () => {
 ```
 
 ```[swift]
-let subscription = room.messages.onDiscontinuity()
+let subscription = room.onDiscontinuity()
 for await error in subscription {
   print("Recovering from the error: \(error)")
 }
 ```
 
 ```[kotlin]
-val subscription = room.messages.onDiscontinuity { reason: ErrorInfo? ->
+val subscription = room.onDiscontinuity { reason: ErrorInfo ->
   // Recover from the discontinuity
 }
 ```
@@ -207,10 +207,4 @@ blang[react,swift].
 blang[react].
 
 blang[javascript,swift,kotlin].
-  The following discontinuity handlers are available:
-
-  * <span lang="javascript">"Messages":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#onDiscontinuity</span><span lang="swift">"Messages":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages</span>
-  * <span lang="javascript">"Presence":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#onDiscontinuity</span><span lang="swift">"Presence":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/presence</span>
-  * <span lang="javascript">"Occupancy":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#onDiscontinuity</span><span lang="swift">"Occupancy":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/occupancy</span>
-  * <span lang="javascript">"Typing indicators":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#onDiscontinuity</span><span lang="swift">"Typing indicators":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/typing</span>
-  * <span lang="javascript">"Room reactions":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#onDiscontinuity</span><span lang="swift">"Room reactions":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomreactions</span>
+  The discontinuity handler is accessible via the <span lang="javascript">"Room":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Room.html#onDiscontinuity</span><span lang="swift">"Room":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/room</span><span lang="kotlin">"Room":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-room/index.html</span> object.

content/chat/getting-started/javascript.textile

@@ -163,7 +163,7 @@ h2(#step-5). Step 5: Show who is typing a message
 
 Typing indicators enable you to display messages to clients when someone is currently typing. An event is emitted when someone starts typing, when they press a keystroke, and then another event is emitted after a configurable amount of time has passed without a key press.
 
-In practice the @typing.start()@ method would be called on keypress, however for demonstration purposes we will call it and wait for the default period of time to pass for a stop event to be emitted. Using your original client, add the following lines to @getStarted()@ to subscribe to typing events and emit one, then run it with @npx ts-node index.ts@:
+In practice the @typing.keystroke()@ method would be called on keypress, however for demonstration purposes we will call it and wait for the default period of time to pass for a stop event to be emitted. Using your original client, add the following lines to @getStarted()@ to subscribe to typing events and emit one, then run it with @npx ts-node index.ts@:
 
 ```[javascript]
 room.typing.subscribe((typingEvent) => {
@@ -174,7 +174,7 @@ room.typing.subscribe((typingEvent) => {
   }
 });
 
-await room.typing.start()
+await room.typing.keystroke()
 // A client types
 await room.typing.stop()
 ```

content/chat/rooms/index.textile

@@ -11,31 +11,36 @@ languages:
 
 Rooms are used to organize and logically separate your users and chat messages into 'rooms'. They are the entry object into using chat and provide access to all other chat features, such as messages, online status and typing indicators. A room can represent a 1:1 chat between an agent and a customer, a private message between two users in a chat application, a large group conversation, or the chat section of a livestream with thousands of users.
 
-You also control which features are enabled in a room when you create one. For instance, you might only want to utilize typing indicators in direct messages between users.
+h2(#channel-relationship). Channel <> Room relationship
+
+It is important to note that each room is backed by a single Ably Pub/Sub channel. You may need to be aware of this when using some integrations with Ably, such as the "Pulsar":https://ably.com/docs/integrations/streaming/pulsar#creating-pulsar-rule connectors, or if you are operating in an environment where a Chat SDK is not available.
+
+The channel name is the same as the room ID with an appended suffix of @::$chat@ (e.g @some-room-id::$chat@). In most cases, you will not need to worry about this, as the Chat SDK handles the channel creation and management for you and capabilities can be configured at the room level.
+
 
 h2(#create). Create or retrieve a room
 
-Users send messages to a room and subscribe to the room in order to receive messages. Other features, such as indicating which users are online, or which users are typing are configured as part of a room's options.
+Users send messages to a room and subscribe to the room in order to receive messages.
 
 blang[javascript,swift,kotlin].
   A @room@ is created, or an existing one is retrieved from the @rooms@ collection using the <span lang="javascript">"@rooms.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#get</span><span lang="swift">"@rooms.get()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/rooms/get%28roomid%3Aoptions%3A%29</span><span lang="kotlin">"@rooms.get()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-rooms/get.html</span> method:
 
 blang[react].
   The "@ChatRoomProvider@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.ChatRoomProvider.html provides access to a specific chat room to all child components in the component tree.
 
-  Pass in the ID of the room to use, and select which which additional chat features you want enabled for that room. This is configured by passing a "@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html object to the provider.
+  Pass in the ID of the room to use. If you need to provide further feature configuration, such as enabling occupancy messages, you can pass in an optional "@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html object to the provider.
 
   <aside data-type='note'>
   <p>All components that utilize chat feature hooks must be children of a @ChatRoomProvider@. This includes @useRoom@, "@useMessages@":/docs/chat/rooms/messages, "@useOccupancy@":/docs/chat/rooms/occupancy, "@usePresence@":/docs/chat/rooms/presence, "@usePresenceListener@":/docs/chat/rooms/presence, "@useRoomReactions@":/docs/chat/rooms/reactions and "@useTyping@":/docs/chat/rooms/typing.</p>
   </aside>
 
 ```[javascript]
-const room = await chatClient.rooms.get('basketball-stream', AllFeaturesEnabled);
+const room = await chatClient.rooms.get('basketball-stream', {occupancy: {enableEvents: true}});
 ```
 
 ```[react]
 import * as Ably from 'ably';
-import { LogLevel, AllFeaturesEnabled } from '@ably/chat';
+import { LogLevel } from '@ably/chat';
 import { ChatClientProvider, ChatRoomProvider } from '@ably/chat/react';
 
 const realtimeClient = new Ably.Realtime({ key: '{{API_KEY}}', clientId: 'clientId' });
@@ -46,7 +51,7 @@ const App = () => {
     <ChatClientProvider client={chatClient}>
       <ChatRoomProvider
         id="my-room-id"
-        options={AllFeaturesEnabled}
+        options={{occupancy: {enableEvents: true}}}
       >
         <RestOfYourApp />
       </ChatRoomProvider>
@@ -56,11 +61,11 @@ const App = () => {
 ```
 
 ```[swift]
-let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: RoomOptions())
+let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: .init(occupancy: .init(enableEvents: true)))
 ```
 
 ```[kotlin]
-val room = chatClient.rooms.get(roomId = "basketball-stream", options = RoomOptions())
+val room = chatClient.rooms.get(roomId = "basketball-stream")
 ```
 
 blang[react].
@@ -71,67 +76,50 @@ blang[react].
   </aside>
 
 blang[javascript,swift,kotlin].
-  When you create or retrieve a room using @rooms.get()@, you need to choose which additional chat features you want enabled for that room. This is configured by passing a <span lang="javascript">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html</span><span lang="swift">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomoptions</span><span lang="kotlin">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-room-options/index.html</span> object as the second argument. In addition to setting which features are enabled, @RoomOptions@ also configures the properties of the associated features, such as the timeout period for typing indicators.
+  When you create or retrieve a room using @rooms.get()@, you can provide custom configuration for some features for that room by passing a <span lang="javascript">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomOptions.html</span><span lang="swift">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/roomoptions</span><span lang="kotlin">"@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-room-options/index.html</span> object as the second argument. If you do not provide a @RoomOptions@ object, the default settings will be used.
 
   ```[javascript]
-  const presence = {enter: false};
-  const reactions = {};
-  const occupancy = {};
   const typing = {timeoutMs: 5000};
   const room = await chatClient.rooms.get('basketball-stream', {presence, reactions, typing, occupancy});
   ```
 
   ```[swift]
   let presence = PresenceOptions(enter: false)
-  let typing = TypingOptions(timeout: 5.0) // seconds
+  let typing = TypingOptions(heartbeatThrottle: 5.0) // seconds
   // using defaults for reactions and occupancy
-  let options = RoomOptions(presence: presence, typing: typing, reactions: nil, occupancy: nil)
+  let options = RoomOptions(presence: presence, typing: typing, reactions: .init(), occupancy: .init())
   let room = try await chatClient.rooms.get(roomID: "basketball-stream", options: options)
   ```
 
   ```[kotlin]
-  val presence = PresenceOptions(enter = false)
-  val typing = TypingOptions(timeoutMs = 5_000) // 5 seconds
-  val options = RoomOptions(presence = presence, typing = typing)
-  val room = chatClient.rooms.get(roomId = "basketball-stream", options = options)
-  ```
-
-blang[javascript].
-  You can also use the @AllFeaturesEnabled@ property for each @RoomOption@ to configure whether preconfigured example settings should be used:
-
-  ```[javascript]
-  const room = await chatClient.rooms.get('basketball-stream', {presence: AllFeaturesEnabled.presence});
-  ```
-
-  Or configure each feature using your own values:
-
-  ```[javascript]
-  const room = await chatClient.rooms.get('basketball-stream', {typing: {timeoutMs: 5000}});
+  val room = chatClient.rooms.get(roomId = "basketball-stream") {
+    typing {
+      heartbeatThrottle = 5.seconds
+    }
+    presence {
+      enableEvents = true
+    }
+    occupancy {
+      enableEvents = true
+    }
+  }
   ```
 
 blang[react,swift,kotlin].
 
-Enable each feature using its associated option. The details of the options available to each feature are documented on their respective pages:
+The details of the options available to each feature are documented on their respective pages:
 
-blang[javascript].
-  | Feature | @RoomOption@ | Default settings |
-  | "Presence":/docs/chat/rooms/presence | @presence@ | @AllFeaturesEnabled.presence@ |
-  | "Occupancy":/docs/chat/rooms/occupancy | @occupancy@ | @AllFeaturesEnabled.occupancy@ |
-  | "Typing indicators":/docs/chat/rooms/typing | @typing@ | @AllFeaturesEnabled.typing@ |
-  | "Room reactions":/docs/chat/rooms/reactions | @reactions@ | @AllFeaturesEnabled.reactions@ |
-
-blang[swift,kotlin].
+blang[javascript,swift,kotlin].
   | Feature | @RoomOption@ | Default settings |
-  | "Presence":/docs/chat/rooms/presence | @presence@ | @PresenceOptions()@ |
-  | "Occupancy":/docs/chat/rooms/occupancy | @occupancy@ | @OccupancyOptions()@ |
-  | "Typing indicators":/docs/chat/rooms/typing | @typing@ | @TypingOptions()@ |
-  | "Room reactions":/docs/chat/rooms/reactions | @reactions@ | @RoomReactionsOptions()@ |
+  | "Presence":/docs/chat/rooms/presence | @presence.enableEvents@ | @true@ |
+  | "Occupancy":/docs/chat/rooms/occupancy | @occupancy.enableEvents@ | @false@ |
+  | "Typing indicators":/docs/chat/rooms/typing | @typing.heartbeatThrottleMs@ | @10000@ |
 
 h3(#release). Release a room
 
 Releasing a room allows the underlying resources to be garbage collected or released.
 
-Releasing a room may be optional for many applications. If you have multiple transient rooms, such as in the case of a 1:1 support chat, then it is may be more beneficial.
+Releasing a room may be optional for many applications. If you have multiple transient rooms, such as in the case of a 1:1 support chat, then it may be more beneficial. Also, proactively disconnecting rather than waiting for the standard two-minute timeout can help reduce costs and improve performance.
 
 blang[javascript,swift,kotlin].
   Once <span lang="javascript">"@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Rooms.html#release</span><span lang="swift">"@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/rooms/release%28roomid%3A%29</span><span lang="kotlin">"@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-kotlin/main/dokka/chat-android/com.ably.chat/-rooms/release.html</span> has been called, the room will be unusable and a new instance will need to be created using "@rooms.get()@":#create if you want to reuse it.

content/chat/rooms/messages.textile

@@ -305,7 +305,7 @@ const MyComponent = () => {
 
 ```[swift]
 let messagesList: [Message]
-let messagesSubscription = try await room().messages.subscribe()
+let messagesSubscription = try await room.messages.subscribe()
 for await message in messagesSubscription {
   switch message.action {
       case .create:
@@ -415,7 +415,7 @@ const MyComponent = () => {
 
 ```[swift]
 let messageToDelete: Message
-let deletedMessage = try await room().messages.delete(
+let deletedMessage = try await room.messages.delete(
   message: messageToDelete,
   params: .init(description: "Message deleted by user")
 )
@@ -492,7 +492,7 @@ const MyComponent = () => {
 
 ```[swift]
 let messagesList: [Message]
-let messagesSubscription = try await room().messages.subscribe()
+let messagesSubscription = try await room.messages.subscribe()
 for await message in messagesSubscription {
   switch message.action {
       case .create:

content/chat/rooms/occupancy.textile

@@ -12,7 +12,7 @@ languages:
 Occupancy enables you to view the number of users currently online in a room. This feature can be used to display user counts to highlight popular, or trending chat rooms.
 
 <aside data-type='note'>
-<p>Occupancy needs to be "enabled":/docs/chat/rooms#create when creating or retrieving a room.</p>
+<p>Occupancy generates messages on any client entering/leaving a room, and so increases the number of billable messages sent in a room - as such, it is disabled by default and needs to be "enabled":/docs/chat/rooms#create when creating or retrieving a room.</p>
 </aside>
 
 h2(#subscribe). Subscribe to room occupancy

content/chat/rooms/presence.textile

@@ -11,10 +11,6 @@ languages:
 
 Subscribe to the online status of room members using the presence feature. Presence enables you to show which members are currently online, indicate when a user goes offline, and have users optionally set additional information about their profile, or their current status within the application.
 
-<aside data-type='note'>
-<p>Presence needs to be "enabled":/docs/chat/rooms#create when creating or retrieving a room.</p>
-</aside>
-
 h2(#subscribe). Subscribe to presence
 
 blang[javascript,swift,kotlin].
@@ -297,16 +293,10 @@ h2(#options). Presence options
 
 The following options can be set when "creating a room":/docs/chat/rooms#create that are specific to presence:
 
-blang[javascript].
-
-  |_. Property |_. Description |_. Default |
-  | enter | Set whether the client has permissions to enter the presence set. Calling @presence.enter()@ is still required. | true |
-  | subscribe | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true |
-
-blang[react].
+blang[javascript,react].
 
   |_. Property |_. Description |_. Default |
-  | subscribe | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true |
+  | enableEvents | Set whether the client has permissions to subscribe to the presence set. Calling @presence.subscribe()@ is still required. | true |
 
 h2(#retrieve). Retrieve the presence set
 

content/chat/rooms/reactions.textile

@@ -13,10 +13,6 @@ Users can send reactions to the entire chat room to show their sentiment as to w
 
 Room reactions are ephemeral and not stored or aggregated by Ably. The intention being that they show the overall sentiment of a room at a point in time.
 
-<aside data-type='note'>
-<p>Room reactions need to be "enabled":/docs/chat/rooms#create when creating or retrieving a room.</p>
-</aside>
-
 h2(#subscribe). Subscribe to room reactions
 
 blang[javascript,swift,kotlin].