Merge remote-tracking branch 'origin/main' into liveobjects/noop-diffs-and-empty-synthetic-list

Author: sacOO7

.github/workflows/bundle-report.yml

@@ -32,7 +32,7 @@ jobs:
       - uses: aws-actions/configure-aws-credentials@67fbcbb121271f7775d2e7715933280b06314838 # v1
         with:
           aws-region: eu-west-2
-          role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-js
+          role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-pubsub-js
           role-session-name: '${{ github.run_id }}-${{ github.run_number }}'
       - uses: ably/sdk-upload-action@8c6179796fc7ee8fc9bb28d5223ffef005b985cc # v1
         with:

.github/workflows/check.yml

@@ -28,6 +28,16 @@ jobs:
       - run: npm run lint
       - run: npm run format:check
       - run: npx tsc --noEmit ably.d.ts modular.d.ts
+      # Redundant today: `npm ci` above runs `prepare`, which builds `webpack:all`, and its
+      # ts-loader already typechecks this same tsconfig program - so a type error fails that
+      # step first. Kept explicit so the guarantee does not rest on that incidental side
+      # effect: adding `transpileOnly` or dropping the webpack bundles would silently remove
+      # it, and nothing would tell us.
+      - run: npx tsc --noEmit -p tsconfig.json
+      # The error-code union is generated from the ably-common submodule at its pinned
+      # commit; fail if the committed copy has drifted from the registry.
+      - run: npm run generate:errorcodes-ts
+      - run: git diff --exit-code -- src/common/lib/types/errorcodes.ts
       # for some reason, this doesn't work in CI using `npx attw --pack .`
       - run: npm pack
       - run: npx attw ably-$(node -e "console.log(require('./package.json').version)").tgz --summary --exclude-entrypoints 'ably/modular'

.github/workflows/docs.yml

@@ -60,7 +60,7 @@ jobs:
         uses: aws-actions/configure-aws-credentials@67fbcbb121271f7775d2e7715933280b06314838 # v1
         with:
           aws-region: eu-west-2
-          role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-js
+          role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-pubsub-js
           role-session-name: '${{ github.run_id }}-${{ github.run_number }}'
 
       - name: Upload Documentation

.github/workflows/features.yml

@@ -14,6 +14,6 @@ jobs:
       id-token: write
     uses: ably/features/.github/workflows/sdk-features.yml@6b3fc7a8ede2ebdd7a6325314f3a96c6466f1453 # main
     with:
-      repository-name: ably-js
+      repository-name: ably-pubsub-js
     secrets:
       ABLY_AWS_ACCOUNT_ID_SDK: ${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}

.gitignore

@@ -1,5 +1,5 @@
 .DS_Store
-ably-js.iml
+ably-pubsub-js.iml
 .idea
 node_modules
 npm-debug.log

.prettierignore

@@ -1 +1,5 @@
 test/common/ably-common/
+
+# Generated by `npm run generate:errorcodes-ts`; the generator is the only thing that
+# should change it, and CI diffs it against the registry.
+src/common/lib/types/errorcodes.ts

CHANGELOG.md

@@ -2,6 +2,26 @@
 
 This contains only the most important and/or user-facing changes; for a full changelog, see the commit history.
 
+## [2.28.0](https://github.com/ably/ably-js/tree/2.28.0) (2026-08-21)
+
+[Full Changelog](https://github.com/ably/ably-js/compare/2.27.0...2.28.0)
+
+### What's Changed
+
+- Roll out e2e encryption of `data` payloads on annotations. They were previously a message type whose publish path deliberately did not apply the channel's encryption (and were documented accordingly), but the reasons for this no longer apply, so there is no reason now not to enable e2e encryption on annotation payloads. [#2277](https://github.com/ably/ably-js/pull/2277)
+
+## [2.27.0](https://github.com/ably/ably-js/tree/2.27.0) (2026-08-10)
+
+[Full Changelog](https://github.com/ably/ably-js/compare/2.26.0...2.27.0)
+
+### What's Changed
+
+- Fall back to the base transport when a proxy rejects the WebSocket handshake outright, rather than reporting `disconnected` after exhausting every host [#2285](https://github.com/ably/ably-js/pull/2285)
+- Move connection resumability decisions from the client to the server: `Connection#id`, `Connection#key` and a channel's `channelSerial` are retained through `SUSPENDED`, and reconnection always attempts a resume. `Connection#createRecoveryKey()` consequently returns a recovery key in `SUSPENDED`, where it previously returned `null` [#2273](https://github.com/ably/ably-js/pull/2273)
+- Fix a resumed attach advancing the channel's attach serial, which broke the contiguity of `untilAttach` history with the realtime message stream [#2276](https://github.com/ably/ably-js/pull/2276)
+- Fix stale presence members surviving when a new presence sync replaces one still in progress [#2261](https://github.com/ably/ably-js/pull/2261)
+- Expand the docstrings on `Auth`, `RealtimeChannel`, `RealtimePresence`, `RealtimeAnnotations` and `RestAnnotations` to cover prerequisites, side effects and failure modes, and link the REST `Channel` and `Presence` members to their reference pages [#2242](https://github.com/ably/ably-js/pull/2242) [#2243](https://github.com/ably/ably-js/pull/2243) [#2244](https://github.com/ably/ably-js/pull/2244) [#2245](https://github.com/ably/ably-js/pull/2245) [#2282](https://github.com/ably/ably-js/pull/2282)
+
 ## [2.26.0](https://github.com/ably/ably-js/tree/2.26.0) (2026-07-22)
 
 [Full Changelog](https://github.com/ably/ably-js/compare/2.25.0...2.26.0)

CLAUDE.md

@@ -22,6 +22,26 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full test-suite, debugging, and
 
 ## Coding Conventions
 
+### Error codes
+
+`ErrorInfo.code` is typed as `ErrorCode`, a union of every code registered in [ably-common](https://github.com/ably/ably-common/tree/main/errors/codes). It is generated into [errorcodes.ts](./src/common/lib/types/errorcodes.ts) from the pinned `ably-common` submodule and committed. CI regenerates it at that pin and fails on a diff, so never hand-edit it.
+
+Pick the registered code whose `identifier` matches the failure, and pair it with the HTTP status that code's registry entry documents. `statusCode` is a plain `number`, so a wrong status still compiles — check it against the registry rather than copying a neighbouring call.
+
+If the code you need is not in the union, `tsc` rejects it:
+
+```text
+error TS2345: Argument of type '40199' is not assignable to parameter of type 'ErrorCode'.
+```
+
+That means the code is not registered. Do not cast around it. Instead:
+
+1. Add the code under `errors/codes/` in [ably-common](https://github.com/ably/ably-common) and get that merged.
+2. Bump the `test/common/ably-common` submodule pin here to a commit that contains it.
+3. Run `npm run generate:errorcodes-ts` and commit the regenerated `errorcodes.ts`.
+
+Errors decoded from the server are exempt: the server chose the code and may use one this client version does not know about, so build those with `ErrorInfo.fromWireValues` instead of `ErrorInfo.fromValues`.
+
 ### Error messages and remediations
 
 Errors constructed by the SDK (`ErrorInfo` / `PartialErrorInfo`) carry a `message` and, in most cases, a `remediation` (see the `ErrorInfo.remediation` docstring in [ably.d.ts](./ably.d.ts)). The two fields have distinct jobs:

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to ably-js
+# Contributing to ably-pubsub-js
 
 ## Contributing
 
@@ -7,7 +7,7 @@
 3. Create your feature branch (`git checkout -b my-new-feature`)
 4. Commit your changes (`git commit -am 'Add some feature'`)
 5. Ensure you have added suitable tests and the test suite is passing(`npm test`)
-6. Ensure the [type definitions](https://github.com/ably/ably-js/blob/main/ably.d.ts) have been updated if the public API has changed
+6. Ensure the [type definitions](https://github.com/ably/ably-pubsub-js/blob/main/ably.d.ts) have been updated if the public API has changed
 7. Push the branch (`git push origin my-new-feature`)
 8. Create a new Pull Request
 
@@ -23,7 +23,7 @@
 8. Run `git tag <VERSION_NUMBER>` with the new version and push the tag to GitHub with `git push <REMOTE> <VERSION_NUMBER>` (usually `git push origin <VERSION_NUMBER>`)
 9. Run `npm publish .` (should require OTP) - publishes to NPM
 10. Run the GitHub action "Publish to CDN" with the new tag name
-11. Visit https://github.com/ably/ably-js/tags and create a GitHub release based on the new tag (for release notes, you generally can just copy the notes you added to the CHANGELOG)
+11. Visit https://github.com/ably/ably-pubsub-js/tags and create a GitHub release based on the new tag (for release notes, you generally can just copy the notes you added to the CHANGELOG)
 12. Update the [Ably Changelog](https://changelog.ably.com/) (via [headwayapp](https://headwayapp.co/)) with these changes (again, you can just copy the notes you added to the CHANGELOG)
 
 ## Building the library
@@ -34,7 +34,7 @@ Since webpack builds are slow, commands are also available to only build the out
 
 ## Coding conventions
 
-Coding conventions, including how to write `ErrorInfo` error messages and remediations, are documented in [CLAUDE.md](./CLAUDE.md).
+Coding conventions, including how to choose an `ErrorInfo` error code and how to write error messages and remediations, are documented in [CLAUDE.md](./CLAUDE.md).
 
 ## Test suite
 

README.md

@@ -1,6 +1,6 @@
 ![Ably Chat Header](/images/JavaScriptSDK-github.png)
 [![npm version](https://img.shields.io/npm/v/ably.svg?style=flat)](https://img.shields.io/npm/v/ably.svg?style=flat)
-[![License](https://badgen.net/github/license/ably/ably-js)](https://github.com/ably/ably-js/blob/main/LICENSE)
+[![License](https://badgen.net/github/license/ably/ably-pubsub-js)](https://github.com/ably/ably-pubsub-js/blob/main/LICENSE)
 
 ---
 
@@ -35,13 +35,13 @@ Ably aims to support a wide range of platforms and all current browser versions,
 
 The following platforms are supported:
 
-| Platform    | Support                                                                                  |
-| ----------- | ---------------------------------------------------------------------------------------- |
-| JavaScript  | ES2017                                                                                   |
-| Node.js     | See `engines` in [package.json](https://github.com/ably/ably-js/blob/main/package.json). |
-| React       | >=16.8.x                                                                                 |
-| TypeScript  | Type definitions are included in the package.                                            |
-| Web Workers | Browser bundle and [modular](#modular-variant) support.                                  |
+| Platform    | Support                                                                                         |
+| ----------- | ----------------------------------------------------------------------------------------------- |
+| JavaScript  | ES2017                                                                                          |
+| Node.js     | See `engines` in [package.json](https://github.com/ably/ably-pubsub-js/blob/main/package.json). |
+| React       | >=16.8.x                                                                                        |
+| TypeScript  | Type definitions are included in the package.                                                   |
+| Web Workers | Browser bundle and [modular](#modular-variant) support.                                         |
 
 > [!NOTE]
 > Versions 1.2.x of the SDK support Internet Explorer >=9 and other older browsers, as well as Node.js >=8.17.
@@ -133,7 +133,7 @@ In order to further reduce bundle size, the modular variant of the SDK performs
 
 If you require more verbose logging, use the default variant of the SDK.
 
-For more information view the [TypeDoc references](https://sdk.ably.com/builds/ably/ably-js/main/typedoc/modules/modular.html).
+For more information view the [TypeDoc references](https://sdk.ably.com/builds/ably/ably-pubsub-js/main/typedoc/modules/modular.html).
 
 </details>
 
@@ -147,13 +147,13 @@ Read the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines to contribute to Ably.
 
 ## Releases
 
-The [CHANGELOG.md](/ably/ably-js/blob/main/CHANGELOG.md) contains details of the latest releases for this SDK. You can also view all Ably releases on [changelog.ably.com](https://changelog.ably.com).
+The [CHANGELOG.md](/ably/ably-pubsub-js/blob/main/CHANGELOG.md) contains details of the latest releases for this SDK. You can also view all Ably releases on [changelog.ably.com](https://changelog.ably.com).
 
 ---
 
 ## Support, feedback, and troubleshooting
 
-For help or technical support, visit Ably's [support page](https://ably.com/support) or [GitHub Issues](https://github.com/ably/ably-js-nativescript/issues) for community-reported bugs and discussions.
+For help or technical support, visit Ably's [support page](https://ably.com/support) or [GitHub Issues](https://github.com/ably/ably-pubsub-js/issues) for community-reported bugs and discussions.
 
 ### Chrome extensions
 
@@ -221,7 +221,7 @@ export default function AblyClientProvider({ children }) {
 }
 ```
 
-Avoid creating the client inside [React](https://github.com/ably/ably-js/blob/main/docs/react.md#Usage) component bodies, as this leads to a new connection on every render. Use the `useEffect` + `useState` pattern shown above, or move the client to a shared provider at the layout level.
+Avoid creating the client inside [React](https://github.com/ably/ably-pubsub-js/blob/main/docs/react.md#Usage) component bodies, as this leads to a new connection on every render. Use the `useEffect` + `useState` pattern shown above, or move the client to a shared provider at the layout level.
 
 In development environments that use Hot Module Replacement (HMR), such as React, Vite, or Next.js, saving a file can recreate the Ably.Realtime client, while previous instances remain connected. Over time, this leads to a growing number of active connections with each code edit. To fix: Move the client to a separate file (e.g., `ably-client.js`) and import it. This ensures the client is recreated only when that file changes.