Merge main into integration/liveobjects

.env.example

@@ -11,8 +11,6 @@ ASSET_PREFIX=
 
 INKEEP_CHAT_ENABLED=
 INKEEP_CHAT_API_KEY=
-INKEEP_CHAT_INTEGRATION_ID=
-INKEEP_CHAT_ORGANIZATION_ID=
 
 INSIGHTS_ENABLED=false
 INSIGHTS_DEBUG=true

CONTRIBUTING.md

@@ -340,3 +340,153 @@ API references make use of [partials](content/partials/) where content is reused
 The Control API is a REST API and the spec can be found in [`static/open-specs/control-v1.yaml](static/open-specs/control-v1.yaml).
 
 This is then referenced in [`src/pages/api/control-api.tsx](src/pages/api/control-api.tsx) for rendering.
+
+### Contributing to Examples
+
+The `examples` directory contains feature-specific demonstrations of how to use Ably in different environments, organized by framework. Each example resides in a structured path like `/examples/<feature>/react` or `/examples/<feature>/javascript`, showcasing practical implementations for various use cases.
+
+#### Example file structure
+
+1. Create a new directory for your example under `/examples`, this should be named after the feature/example you're building, e.g. `chat-typing-indicator`.
+2. Inside this directory, create a subdirectory named after the language or framework (e.g., `javascript`, `react`). You can have both `javascript` and `react` subdirectories within the same example directory.
+
+Currently, we support Javascript (Typescript) and React, both using Vite.
+
+#### Create the project
+
+To create a new project using Vite, follow the instructions below for either JavaScript/TypeScript or React.
+
+##### JavaScript/TypeScript
+
+1. Open your terminal.
+2. Navigate to the directory where you want to create your project.
+3. Run the following command to create a new Vite project:
+
+```sh
+npm create vite@latest javascript -- --template vanilla
+```
+
+4. Navigate into your project directory:
+
+```sh
+cd javascript
+```
+
+##### React
+
+1. Open your terminal.
+2. Navigate to the directory where you want to create your project.
+3. Run the following command to create a new Vite project with React template:
+
+```sh
+npm create vite@latest react -- --template react
+```
+
+4. Navigate into your project directory:
+
+```sh
+cd react
+```
+
+After following these steps, you will have a Vite project set up with JavaScript/TypeScript or React, ready for further development.
+
+#### README.md
+
+Each example must include a `README.md` file with instructions to get the developer running the example locally as quick as possible. These instructions should follow the structure below:
+
+- **Introduction**: Describe the Ably features used, what problem is this solving for the intended audience?
+- **Resources**: List components and functions from the Ably SDKs and their purposes.
+- **Getting started**: Provide step-by-step instructions:
+  1. Clone the docs repository.
+  2. Navigate to the examples directory.
+  3. Rename environment variable files. (`.env.example` -> `.env.local`)
+  4. Update environment variables.
+  5. Install dependencies with `yarn install`.
+  6. Run the project.
+- **Opening in CodeSandbox**: Instructions for opening the example in CodeSandbox. (At this moment, this heading contains the renaming of the environment variables)
+
+#### NPM Workspaces
+
+Add entries for each example to the `/examples/package.json` file under `workspaces` and `scripts`, an example of this is shown below:
+
+```json
+"workspaces": [
+  "chat-typing-indicator/react",
+  "chat-typing-indicator/javascript",
+],
+"scripts": {
+  "chat-typing-indicator-javascript": "yarn workspace chat-typing-indicator-javascript dev",
+  "chat-typing-indicator-react": "yarn workspace chat-typing-indicator-react dev",
+},
+```
+
+The intention of the scripts entries is to make the command simpler for the developer to run locally.
+
+#### Shared configurations
+
+All examples use config from the examples root directory. Update these files inside your project directory:
+
+- `vite.config.ts`:
+
+  ```typescript
+  import { defineConfig } from 'vite';
+  import baseConfig from '../../vite.config';
+
+  export default defineConfig({
+    ...baseConfig,
+    envDir: '../../',
+  });
+  ```
+
+- `tailwind.config.ts`:
+
+  ```typescript
+  import baseConfig from '../../tailwind.config';
+  import type { Config } from 'tailwindcss';
+
+  const config: Config = {
+    ...baseConfig,
+    content: ['./src/**/*.{js,ts,tsx}', './index.html'],
+  };
+
+  export default config;
+  ```
+
+- `tsconfig.json`:
+
+  ```json
+  {
+    "extends": "../../tsconfig.json"
+  }
+  ```
+
+- `vite-env.d.ts` (Javascript only):
+
+  ```typescript
+  interface ImportMetaEnv {
+    readonly VITE_ABLY_KEY: string;
+  }
+
+  interface ImportMeta {
+    readonly env: ImportMetaEnv;
+  }
+  ```
+
+
+#### Styling consistency
+
+For styling consistency purposes, each example will need to use [Franken-ui](https://franken-ui.dev/) for components, and any other styling to use tailwindcss. Some examples for this are the button and input components below:
+
+**Button:**
+
+```html
+<button class="uk-btn uk-btn-md uk-btn-primary py-2 rounded">
+  Submit
+</button>
+```
+
+**Input:**
+
+```html
+<input type="text" class="uk-input uk-width-1-1 uk-border-rounded-left">
+```

content/account/control-api.textile

@@ -169,13 +169,10 @@ The only operation available at the account-level is to retrieve account-wide st
 To retrieve account-level statistics:
 
 ```[sh]
-curl --location --request POST 'https://control.ably.net/v1/accounts/${ACCOUNT_ID}/stats' \
---header 'Content-Type: application/json' \
---header 'Authorization: Bearer ${ACCESS_TOKEN}' \
---data-raw '{
-    "unit": "minute",
-    "limit": 2
-}'
+curl --request GET \
+  --url 'https://control.ably.net/v1/accounts/${ACCOUNT_ID}/stats?unit=minute&limit=2' \
+  --header 'Authorization: Bearer ${ACCESS_TOKEN}' \
+  --header 'Content-Type: application/json'
 ```
 
 See the "API reference":/docs/api/control-api#tag/accounts/paths/~1accounts~1{account_id}~1stats/get for information on the request body.

content/api/rest-api.textile

@@ -29,6 +29,7 @@ jump_to:
     - list channel subscriptions#list-channel-subscriptions
     - list channels#list-channels
     - publish directly to device#push-publish
+    - publish via batch push API#push-publish-batch
   Authentication API:
     - requestToken#request-token
     - revokeTokens#revoke-tokens
@@ -1152,6 +1153,56 @@ A successful request returns an empty response.
 
 An unsuccessful request returns an error.
 
+h3(#push-publish-batch). Publish via batch push API
+
+Convenience endpoint to deliver multiple push notification payloads to multiple devices or browsers in a single request by specifying a list of recipients and corresponding payloads.
+Currently, the batch push endpoint allows a maximum of 10,000 notifications per request (note that each recipient for a given payload counts as a separate notification).
+
+h6. POST rest.ably.io/push/batch/publish
+
+The request body is an array of objects of the form:
+
+bc[json]. {
+  recipient: <recipient object or array of recipient objects>
+  payload: <object>
+}
+
+Where the recipient and payload fields are the same as those used in the "Publish a push notification to a single device":#push-publish endpoint.
+
+Example request:
+
+bc[sh]. curl -X POST https://rest.ably.io/push/admin/batch/publish \
+ -u "{{API_KEY}}" \
+ -H "Content-Type: application/json" \
+ --data \
+ '
+[
+  {
+    "recipient": {
+      "deviceId": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+    },
+    "payload": {
+      "notification": {
+        "title": "Message 1",
+        "body": "Example push notification from Ably."
+      }
+    }
+  },
+  {
+    "recipient": {
+      "clientId": "myClientId"
+    },
+    "payload": {
+      "notification": {
+        "title": "Message 2",
+        "body": "Example push notification from Ably."
+      }
+    }
+  }
+]
+'
+
+
 h2(#authentication). Authentication
 
 h3(#request-token). Request an access token

content/chat/connect.textile

@@ -50,7 +50,7 @@ const MyComponent = () => {
 ```
 
 ```[swift]
-let status = await chatClient.connection.status
+let status = chatClient.connection.status
 ```
 
 ```[kotlin]

content/chat/index.textile

@@ -1,6 +1,7 @@
 ---
 title: About Chat
 meta_description: "Learn more about Ably Chat and the features that enable you to quickly build functionality into new and existing applications."
+product: chat
 redirect_from: /docs/products/chat
 ---
 

content/chat/rooms/index.textile

@@ -270,7 +270,7 @@ const MyComponent = () => {
 ```
 
 ```[swift]
-let status = try await room.status
+let status = room.status
 ```
 
 ```[kotlin]
@@ -288,7 +288,7 @@ blang[javascript,swift,kotlin].
   ```
 
   ```[swift]
-  let statusSubscription = try await room.onStatusChange()
+  let statusSubscription = room.onStatusChange()
   for await status in statusSubscription {
     print("Room status: \(status)")
   }

content/chat/rooms/occupancy.textile

@@ -49,7 +49,7 @@ const MyComponent = () => {
 ```
 
 ```[swift]
-let occupancySubscription = try await room.occupancy.subscribe()
+let occupancySubscription = room.occupancy.subscribe()
 for await event in occupancySubscription {
   occupancyInfo = "Connections: \(event.presenceMembers) (\(event.connections))"
 }

content/chat/rooms/presence.textile

@@ -60,7 +60,7 @@ const MyComponent = () => {
 ```
 
 ```[swift]
-let presenceSubscription = try await room.presence.subscribe(events: [.enter, .leave, .update])
+let presenceSubscription = room.presence.subscribe(events: [.enter, .leave, .update])
 for await event in presenceSubscription {
     print("Presence event `\(event.action)` from `\(event.clientId)` with data `\(event.data)`")
 }
@@ -89,10 +89,10 @@ blang[javascript,swift].
 
   ```[swift]
   // Subscribe to only 'enter' events:
-  let presenceSubscription = try await room.presence.subscribe(event: .enter)
+  let presenceSubscription = room.presence.subscribe(event: .enter)
 
   // Subscribe to 'update' and 'leave' events:
-  let presenceSubscription = try await room.presence.subscribe(events: [.leave, .update])
+  let presenceSubscription = room.presence.subscribe(events: [.leave, .update])
   ```
 
 blang[react,kotlin].

content/chat/rooms/reactions.textile

@@ -45,7 +45,7 @@ const MyComponent = () => {
 ```
 
 ```[swift]
-let reactionSubscription = try await room.reactions.subscribe()
+let reactionSubscription = room.reactions.subscribe()
 for await reaction in reactionSubscription {
   print("Received a reaction of type \(reaction.type), and metadata \(reaction.metadata)")
 }

content/chat/rooms/typing.textile

@@ -49,7 +49,7 @@ const MyComponent = () => {
 ```
 
 ```[swift]
-let typingSubscription = try await room.typing.subscribe()
+let typingSubscription = room.typing.subscribe()
 for await typing in typingSubscription {
   typingInfo = typing.currentlyTyping.isEmpty ? "" :
                 "Typing: \(typing.currentlyTyping.joined(separator: ", "))..."

content/livesync/mongodb/index.textile

@@ -23,10 +23,6 @@ The integration rule exists as a "database connector" component that is entirely
 
 When a change event is received over the Change Streams API it is published to an Ably channel. When you configure the integration rule, you can specify how change events are mapped to individual Ably channels. Clients can then subscribe to database changes by subscribing to Ably channels. Ably "Auth":/docs/auth and "Capabilities":/docs/auth/capabilities control which channels a client can interact with.
 
-h2(#development-status). Development status
-
-The MongoDB database connector is currently in beta status. Your "feedback":https://docs.google.com/forms/d/e/1FAIpQLSd00n1uxgXWPGvMjKwMVL1UDhFKMeh3bSrP52j9AfXifoU-Pg/viewform will help prioritize improvements and fixes for subsequent releases.
-
 h2(#integration-rule). Integration rule
 
 h3(#create). Create a rule

content/metadata-stats/metadata/subscribe.textile

@@ -36,7 +36,7 @@ It is never possible to publish or be present on a metachannel, however you can
 The following is an example of a capability that provides access to subscribe to all metachannels:
 
 ```[json]
-{"[meta]*":["subscribe"]}
+{"[meta]*":["subscribe"]}
 ```
 
 h2(#connection-lifecycle). Connection lifecycle events