Merge pull request #2315 from ably/ECO-5135

[ECO-5135] Updates the Chat docs to include code examples for chat-swift

content/chat/connect.textile

@@ -5,6 +5,7 @@ product: chat
 languages:
   - javascript
   - react
+  - swift
 ---
 
 When you "instantiate":/chat/setup#instantiate a client, a realtime connection is established and maintained with Ably. You can interact with the connection using the @ChatClient.connection@ object in order to monitor a client's connection status.
@@ -21,8 +22,8 @@ A connection can have any of the following statuses:
 | suspended | A long term failure condition when no current connection exists because there is no network connectivity or available host. The suspended status is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended status, an SDK will periodically attempt to open a new connection every 30 seconds. Rooms will be reattached on a successful reconnection, however message history will not be automatically recovered. |
 | failed | This status is entered if the SDK encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, such as an attempt to connect with an incorrect API key, or some local terminal error, such as that the token in use has expired and the SDK does not have any way to renew it. |
 
-blang[javascript].
-  Use the "@status@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#status property to check which status a connection is currently in:
+blang[javascript,swift].
+  Use the <span lang="javascript">"@status@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#status</span><span lang="swift">"@status@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connectionstatus</span> property to check which status a connection is currently in:
 
 blang[react].
   Use the "@currentStatus@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseChatConnectionResponse.html#currentStatus property returned in the response of the "@useChatConnection@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat-react.useChatConnection.html hook to check which status a connection is currently in:
@@ -47,6 +48,10 @@ const MyComponent = () => {
 };
 ```
 
+```[swift]
+let status = await chatClient.connection.status
+```
+
 blang[react].
   Hooks related to chat features, such as @useMessages@ and @useTyping@, also return the current @connectionStatus@ in their response.
 
@@ -64,14 +69,11 @@ blang[react].
   };
   ```
 
-blang[javascript].
-
-blang[javascript].
-  Use the "@connection.onStatusChange()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#onStatusChange method to register a listener for status change updates:
-
-blang[react].
   Listeners can also be registered to monitor the changes in connection status. Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a status change listener. Changing the value provided for a listener will cause the previously registered listener instance to stop receiving events. All messages will be received by exactly one listener.
 
+blang[javascript,swift].
+  Use the <span lang="javascript">"@connection.onStatusChange()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_js.Connection.html#onStatusChange</span><span lang="swift">"@connection.onStatusChange()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/connection/onstatuschange%28%29-76t7</span> method to register a listener for status change updates.
+
 ```[javascript]
 const { off } = chatClient.connection.onStatusChange((change) => console.log(change));
 ```
@@ -89,28 +91,41 @@ const MyComponent = () => {
 };
 ```
 
+```[swift]
+let subscription = chatClient.connection.onStatusChange()
+for await statusChange in subscription {
+  print("Connection status changed to: \(statusChange.current)")
+}
+```
+
 blang[javascript].
-  To remove the connection status listener, call the @off()@ function returned in the @subscribe()@ response:
+  Use the @off()@ function returned in the @onStatusChange()@ response to remove a listener:
+
+blang[react,swift].
 
+blang[javascript].
   ```[javascript]
   off();
   ```
 
+blang[react,swift].
+
+blang[javascript].
   Use the "@connection.offAllStatusChange()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Connection.html#offAllStatusChange method to remove all connection status listeners:
 
   ```[javascript]
   chatClient.connection.offAllStatusChange();
   ```
 
-blang[react].
+blang[react,swift].
 
 h2(#discontinuity). Handle connection discontinuity
 
 If a client briefly loses connection to Ably, for example when driving through a tunnel, the SDK will attempt to recover the connection. If the disruption lasts for less than 2 minutes, then on reconnection the SDK will automatically reattach to any rooms and replay any missed messages.
 
 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":/chat/rooms/history.
 
-blang[javascript].
+blang[javascript,swift].
   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.
 
 blang[react].
@@ -139,19 +154,32 @@ const MyComponent = () => {
 };
 ```
 
-blang[react].
+```[swift]
+let subscription = room.messages.onDiscontinuity()
+for await error in subscription {
+  print("Recovering from the error: \(error)")
+}
+```
 
 blang[javascript].
   Use the @off()@ function returned in the @onDiscontinuity()@ response to remove a listener:
 
+blang[react,swift].
+
+blang[javascript].
   ```[javascript]
   off();
   ```
 
+blang[react,swift].
+
+blang[react].
+
+blang[javascript,swift].
   The following discontinuity handlers are available:
 
-  * "Messages":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#onDiscontinuity
-  * "Presence":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Presence.html#onDiscontinuity
-  * "Occupancy":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Occupancy.html#onDiscontinuity
-  * "Typing indicators":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Typing.html#onDiscontinuity
-  * "Room reactions":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.RoomReactions.html#onDiscontinuity
+  * <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>

content/chat/rooms/history.textile

@@ -5,14 +5,15 @@ product: chat
 languages:
   - javascript
   - react
+  - swift
 ---
 
 The history feature enables users to retrieve messages that have been previously sent in a room. Ably stores chat messages for 24 hours by default. You can extend this up to 30 days by "contacting us":https://forms.gle/SmCLNFoRrYmkbZSf8.
 
 h2(#get). Retrieve previously sent messages
 
-blang[javascript].
-  Use the "@messages.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#get method to retrieve messages that have been previously sent to a room:
+blang[javascript,swift].
+  Use the <span lang="javascript">"@messages.get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.Messages.html#get</span><span lang="swift">"@messages.get()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messages/get%28options%3A%29</span> method to retrieve messages that have been previously sent to a room:
 
 blang[react].
     Use the "@get()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseMessagesResponse.html#get method available from the response of the @useMessages@ hook to retrieve messages that have been previously sent to a room.
@@ -50,6 +51,16 @@ const MyComponent = () => {
 };
 ```
 
+```[swift]
+let paginatedResult = try await room.messages.get(options: .init(orderBy: .newestFirst))
+print(paginatedResult.items)
+if let next = try await paginatedResult.next {
+    print(next.items)
+} else {
+    print("End of messages")
+}
+```
+
 The following optional parameters can be passed when retrieving previously sent messages:
 
 |_. Parameter |_. Description |
@@ -62,8 +73,8 @@ h2(#subscribe). Retrieve messages sent prior to subscribing
 
 Users can also retrieve historical messages that were sent to a room before the point that they registered a listener by "subscribing":/chat/rooms/messages#subscribe. The order of messages returned is from most recent, to oldest. This is useful for providing conversational context when a user first joins a room, or when they subsequently rejoin it later on. It also ensures that the message history they see is continuous, without any overlap of messages being returned between their subscription and their history call.
 
-blang[javascript].
-  Use the "@getPreviousMessages()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#getPreviousMessages function returned as part of a "message subscription":/chat/rooms/messages#subscribe response to only retrieve messages that were received before the listener was subscribed to the room:
+blang[javascript,swift].
+  Use the <span lang="javascript">"@getPreviousMessages()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-js.MessageSubscriptionResponse.html#getPreviousMessages</span><span lang="swift">"@getPreviousMessages()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/AblyChat/documentation/ablychat/messagesubscription/getpreviousmessages%28params%3A%29</span> function returned as part of a "message subscription":/chat/rooms/messages#subscribe response to only retrieve messages that were received before the listener was subscribed to the room:
 
 blang[react].
   Use the "@getPrevious()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat-react.UseMessagesResponse.html#getPreviousMessages method available from the response of the @useMessages@ hook to only retrieve messages that were received before the listener subscribed to the room. As long as a defined value is provided for the listener, and there are no message discontinuities, @getPreviousMessages()@ will return messages from the same point across component renders. If the listener becomes undefined, the subscription to messages will be removed. If you subsequently redefine the listener then @getPreviousMessages()@ will return messages from the new point of subscription.
@@ -114,6 +125,17 @@ const MyComponent = () => {
 };
 ```
 
+```[swift]
+let messagesSubscription = try await room.messages.subscribe()
+let paginatedResult = try await messagesSubscription.getPreviousMessages(params: .init(limit: 50)) // `orderBy` here is ignored and always `newestFirst`
+print(paginatedResult.items)
+if let next = try await paginatedResult.next {
+    print(next.items)
+} else {
+    print("End of messages")
+}
+```
+
 The following parameters can be passed when retrieving previously sent messages:
 
 |_. Parameter |_. Description |