Merge main into integration/liveobjects 2025-05-08

.circleci/config.yml

@@ -67,6 +67,17 @@ jobs:
             - config
             - public
 
+  validate-llms-txt:
+    executor:
+      name: default
+    steps:
+      - checkout
+      - attach_workspace:
+          at: .
+      - run:
+          name: Validate llms.txt
+          command: yarn validate-llms-txt
+
   test-nginx:
     docker:
       - image: heroku/heroku:24-build
@@ -143,4 +154,7 @@ workflows:
       - test-nginx:
           requires:
             - build
+      - validate-llms-txt:
+          requires:
+            - build
 

.env.example

@@ -11,8 +11,7 @@ ASSET_PREFIX=
 
 INKEEP_CHAT_ENABLED=
 INKEEP_CHAT_API_KEY=
-INKEEP_CHAT_INTEGRATION_ID=
-INKEEP_CHAT_ORGANIZATION_ID=
+CONVERSATIONS_API_URL='http://localhost:3000/api/conversations'
 
 INSIGHTS_ENABLED=false
 INSIGHTS_DEBUG=true

.prettierignore

@@ -0,0 +1,3 @@
+# Ignore all mdx files in src/pages - we need to be able to render components on one line for inlining
+src/pages/**/*.mdx
+src/pages/**/*.md

CONTRIBUTING.md

@@ -180,7 +180,7 @@ There are three types of admonition that can be used; `note`, `important` and `f
 
 #### Feature changes
 
-Two additional types of admonition are used to display features that have been added or updated in a version update; `new` and `updated`.
+Three additional types of admonition are used to display features that have been added or updated in a version update; `new`, `updated` and `experimental`.
 
 ```html
 <aside data-type='updated'>
@@ -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">
+```

bin/validate-llms.txt.ts

@@ -0,0 +1,47 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as glob from 'glob';
+
+const PUBLIC_DIR = path.join(process.cwd(), 'public');
+const LLMS_FILE = path.join(PUBLIC_DIR, 'llms.txt');
+
+function countHtmlFiles(): number {
+  const htmlFiles = glob.sync('**/*.html', { cwd: PUBLIC_DIR });
+  return htmlFiles.length;
+}
+
+function countLlmsLines(): number {
+  const content = fs.readFileSync(LLMS_FILE, 'utf-8');
+  return content.split('\n').filter((line) => line.trim().length > 0).length;
+}
+
+function validateCounts(htmlCount: number, llmsCount: number): boolean {
+  const difference = Math.abs(htmlCount - llmsCount);
+  const maxAllowedDifference = Math.ceil(htmlCount * 0.75); // 75% of html count
+  return difference <= maxAllowedDifference;
+}
+
+function main() {
+  try {
+    const htmlCount = countHtmlFiles();
+    const llmsCount = countLlmsLines();
+    const isValid = validateCounts(htmlCount, llmsCount);
+
+    console.log(`HTML files found: ${htmlCount}`);
+    console.log(`Lines in llms.txt: ${llmsCount}`);
+
+    if (!isValid) {
+      console.error(
+        `Error: The number of lines in llms.txt (${llmsCount}) is not within 75% of the number of HTML files (${htmlCount})`,
+      );
+      process.exit(1);
+    }
+
+    console.log('Validation successful!');
+  } catch (error) {
+    console.error('Error during validation:', error);
+    process.exit(1);
+  }
+}
+
+main();

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/realtime-sdk/messages.textile

@@ -57,93 +57,4 @@ h2(#properties).
   ruby:    Attributes
   python:  Attributes
 
-A @Message@ represents an individual message that is sent to or received from Ably.
-
-h6(#name).
-  default: name
-  csharp: Name
-
-The event name, if provided. <br>__Type: @String@__
-
-h6(#data).
-  default: data
-  csharp: Data
-
-The message payload, if provided.<br>__Type: <span lang="default">@String@, @StringBuffer@, @JSON Object@</span><span lang="java">@String@, @ByteArray@, @JSONObject@, @JSONArray@</span><span lang="csharp">@String@, @byte[]@, @plain C# object that can be serialized to JSON@</span><span lang="ruby">@String@, @Binary@ (ASCII-8BIT String), @Hash@, @Array@</span><span lang="python">@String@, @Bytearray@, @Dict@, @List@</span><span lang="php">@String@, @Binary String@, @Associative Array@, @Array@</span><span lang="objc">@NSString *@, @NSData *@, @NSDictionary *@, @NSArray *@</span><span lang="swift">@String@, @NSData@, @Dictionary@, @Array@</span><span lang="flutter">@String@, @Map@, @List@</span>__
-
-h6(#extras).
-  default: extras
-  csharp: Extras
-
-Metadata and/or ancillary payloads, if provided. The only currently valid payloads for extras are the "@push@":/docs/push/publish#payload, "@ref@":/docs/channels/messages#interactions and "@privileged@":/docs/integrations/webhooks#skipping objects.<br>__Type: <span lang="java">@JSONObject@, @JSONArray@</span><span lang="csharp">plain C# object that can be converted to JSON</span><span lang="jsall">@JSON Object@</span><span lang="ruby">@Hash@, @Array@</span><span lang="python">@Dict@, @List@</span><span lang="swift">@Dictionary@, @Array@</span><span lang="objc">@NSDictionary *@, @NSArray *@</span><span lang="php">@Associative Array@, @Array@</span>__
-
-h6(#id).
-  default: id
-  csharp: Id
-
-A Unique ID assigned by Ably to this message.<br>__Type: @String@__
-
-h6(#client-id).
-  default: clientId
-  csharp: ClientId
-  ruby: client_id
-  python: client_id
-
-The client ID of the publisher of this message.<br>__Type: @String@__
-
-h6(#connection-id).
-  default: connectionId
-  csharp: ConnectionId
-  ruby: connection_id
-  python: connection_id
-
-The connection ID of the publisher of this message.<br>__Type: @String@__
-
-h6(#timestamp).
-  default: timestamp
-  csharp: Timestamp
-
-Timestamp when the message was received by the Ably, as <span lang="default">milliseconds since the epoch</span><span lang="ruby">a @Time@ object</span><br>.__Type: <span lang="default">@Integer@</span><span lang="java">@Long Integer@</span><span lang="csharp">@DateTimeOffset@</span><span lang="ruby">@Time@</span><span lang="objc,swift">@NSDate@</span>__
-
-h6(#encoding).
-  default: encoding
-  csharp: Encoding
-
-This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the @data@ payload.<br>__Type: @String@__
-
-h2(methods).
-  default: Message methods
-
-h6(#message-from-encoded).
-  default: Message.fromEncoded
-
-bq(definition).
-  default: Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message
-
-A static factory method to create a "@Message@":/docs/api/realtime-sdk/types#message from a deserialized @Message@-like object encoded using Ably's wire protocol.
-
-h4. Parameters
-
-- encodedMsg := a @Message@-like deserialized object.<br>__Type: @Object@__
-- channelOptions := an optional "@ChannelOptions@":/docs/api/realtime-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.<br>__Type: @Object@__
-
-h4. Returns
-
-A "@Message@":/docs/api/realtime-sdk/types#message object
-
-h6(#message-from-encoded-array).
-  default: Message.fromEncodedArray
-
-bq(definition).
-  default: Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[]
-
-A static factory method to create an array of "@Messages@":/docs/api/realtime-sdk/types#message from an array of deserialized @Message@-like object encoded using Ably's wire protocol.
-
-h4. Parameters
-
-- encodedMsgs := an array of @Message@-like deserialized objects.<br>__Type: @Array@__
-- channelOptions := an optional "@ChannelOptions@":/docs/api/realtime-sdk/types#channel-options. If you have an encrypted channel, use this to allow the library can decrypt the data.<br>__Type: @Object@__
-
-h4. Returns
-
-An @Array@ of "@Message@":/docs/api/realtime-sdk/types#message objects
+<%= partial partial_version('types/_message') %>