Integration branch for ably_pubsub_device_flutter v2 package

.claude/skills/release/SKILL.md

@@ -18,7 +18,7 @@ Then perform these steps in order:
 
 2. Update the version in these files:
    - `pubspec.yaml` — the `version` property
-   - `README.md` — the `ably_flutter: ^OLD_VERSION` line in the Installation section (update to `^NEW_VERSION`)
+   - `README.md` — the `ably_pubsub_device_flutter: ^OLD_VERSION` line in the Installation section (update to `^NEW_VERSION`)
 
 3. Regenerate lock files:
 

.github/workflows/flutter_integration.yaml

@@ -21,10 +21,10 @@ jobs:
           flutter-version: '3.29'
           cache: true
 
-      # test_integration package depends on ably_flutter, so before we run integration
+      # test_integration package depends on ably_pubsub_device_flutter, so before we run integration
       # tests it's best to perform dependency update in both packages, to make sure that
       # integration tests are run with exactly the same dependencies as specified in
-      # current version of ably_flutter package
+      # current version of ably_pubsub_device_flutter package
       - name: Update dependencies
         run: |
           flutter pub get

.github/workflows/ios_unit_tests.yml

@@ -23,10 +23,10 @@ jobs:
 
       - name: Set up iOS test project
         # --skip-tests sets up the CocoaPods workspace (downloads all deps, generates
-        # the ably_flutter-Unit-Tests scheme) without booting a simulator
+        # the ably_pubsub_device_flutter-Unit-Tests scheme) without booting a simulator
         run: |
           cd ios
-          pod lib lint ably_flutter.podspec \
+          pod lib lint ably_pubsub_device_flutter.podspec \
             --allow-warnings \
             --skip-tests \
             --validation-dir=/tmp/ably_test_build \
@@ -45,6 +45,6 @@ jobs:
         run: |
           xcodebuild test \
             -workspace /tmp/ably_test_build/App.xcworkspace \
-            -scheme ably_flutter-Unit-Tests \
+            -scheme ably_pubsub_device_flutter-Unit-Tests \
             -destination "id=$SIMULATOR_ID,arch=arm64" \
             CODE_SIGNING_ALLOWED=NO

API_REF_INTRO_BLURB.md

@@ -1,7 +1,7 @@
 # Ably Flutter Client Library SDK API Reference
 
-The Flutter Client Library SDK supports a realtime and a REST interface. The Flutter API references are generated from the [Ably Flutter Client Library SDK source code](https://github.com/ably/ably-pubsub-flutter/) using [dartdoc](https://dart.dev/tools/dart-doc) and structured by classes.
+The Flutter Client Library SDK supports a realtime interface. The Flutter API references are generated from the [Ably Flutter Client Library SDK source code](https://github.com/ably/ably-pubsub-flutter/) using [dartdoc](https://dart.dev/tools/dart-doc) and structured by classes.
 
-The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels. The REST interface is stateless and typically implemented server-side. It is used to make requests such as retrieving statistics, token authentication and publishing to a channel.
+The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels.
 
 View the [Ably docs](https://ably.com/docs/) for conceptual information on using Ably, and for API references featuring all languages. The combined [API references](https://ably.com/docs/api/) are organized by features and split between the [realtime](https://ably.com/docs/api/realtime-sdk) and [REST](https://ably.com/docs/api/rest-sdk) interfaces.

PushNotifications.md

@@ -93,11 +93,11 @@ The example app contains an example of how to use the Push Notification function
 
 ### Ensure `WidgetsBinding` is initialized
 
-If you invoke any methods from the `ably_flutter` package before calling `runApp()`, you must call `WidgetsFlutterBinding.ensureInitialized();`. This is done to ensure all platform methods will be successfully received by the native Ably plugin on the host platform.
+If you invoke any methods from the `ably_pubsub_device_flutter` package before calling `runApp()`, you must call `WidgetsFlutterBinding.ensureInitialized();`. This is done to ensure all platform methods will be successfully received by the native Ably plugin on the host platform.
 
 ### Device activation
 
-- Create a rest or realtime client: e.g. `final realtime = ably.Realtime(options: clientOptions);`
+- Create a realtime client: e.g. `final realtime = ably.createClient(options: clientOptions);`
 - Activate the device for push notifications with Ably: `ablyClient.push.activate();`. This only
   needs to be done once, and will be used across all future app launches, as long as the app is not deactivated. This method will throw an AblyException if it fails.
 - The `Future` returned by `activate` is not guaranteed to complete quickly. For example, if there is no internet connection, `activate` will wait until it is available. Therefore, there is no guarantee any code awaiting the completion of the `Future` will run.
@@ -162,7 +162,7 @@ If you're working in Objective-C then this will look something like this in `App
 If you're working in Swift then this will look something like this in `AppDelegate.swift`:
 
 ```swift
-import ably_flutter
+import ably_pubsub_device_flutter
 
 @UIApplicationMain
 @objc class AppDelegate: FlutterAppDelegate {
@@ -178,7 +178,7 @@ import ably_flutter
 
 ### Subscribing to channels for push notifications
 
-- Get the Realtime/ Rest channel: `final channel = realtime!.channels.get(Constants.channelNameForPushNotifications)`
+- Get the realtime channel: `final channel = realtime!.channels.get(Constants.channelNameForPushNotifications)`
 - Subscribe the device to the **push channel**, by either using the device ID or client ID:
     - `channel.push.subscribeClient()` or `channel.push.subscribeDevice()`
     - This is different to subscribing to a channel for messages.
@@ -238,7 +238,7 @@ Requesting permissions:
 
 ```dart
 // Create an Ably client to access the push field
-final realtime = ably.Realtime(options: clientOptions);
+final realtime = ably.createClient(options: clientOptions);
 final push = realtime.push;
 // Request permission from user on iOS
 bool permissionGranted = await push.requestPermission();
@@ -601,6 +601,6 @@ ActivationContext.getActivationContext(this).onNewRegistrationToken(Registration
 
 **iOS:** Ensure you set the `sound` key in the `push.notification` object when sending the Ably message.
 
-### When building my application, I get the following error: `Manifest merger failed : uses-sdk:minSdkVersion 16 cannot be smaller than version 19 declared in library [:ably_flutter]`
+### When building my application, I get the following error: `Manifest merger failed : uses-sdk:minSdkVersion 16 cannot be smaller than version 19 declared in library [:ably_pubsub_device_flutter]`
 
 A fresh Flutter project generates an Android project with a `minSdkVersion` of 16, but Ably-flutter only supports API level 19 (Android Kitkat 4.4, which was released in 2013) and above. In `android/app/build.gradle`, change `minSdkVersion 16` to `minSdkVersion 19`.

README.md

@@ -1,5 +1,5 @@
 ![Ably Pub/Sub Flutter Header](images/flutter-github.png)
-[![Pub Version](https://img.shields.io/pub/v/ably_flutter)](https://pub.dev/packages/ably_flutter)
+[![Pub Version](https://img.shields.io/pub/v/ably_pubsub_device_flutter)](https://pub.dev/packages/ably_pubsub_device_flutter)
 [![License](https://badgen.net/github/license/ably/ably-pubsub-flutter)](https://github.com/ably/ably-pubsub-flutter/blob/main/LICENSE)
 
 ---
@@ -54,17 +54,17 @@ Add the Ably Flutter package to your project by including it in your `pubspec.ya
 
 ```yaml
 dependencies:
-  ably_flutter: ^1.2.44
+  ably_pubsub_device_flutter: ^1.2.44
 ```
 
 Once added to your dependencies, import it in your Dart code:
 
 ```dart
-import 'package:ably_flutter/ably_flutter.dart' as ably;
+import 'package:ably_pubsub_device_flutter/ably_pubsub_device_flutter.dart' as ably;
 ```
 
 > [!NOTE]
-> When increasing the version of `ably_flutter` in your `pubspec.yaml`, if there are breaking changes, follow the [updating / migration guide](UPDATING.md).
+> When increasing the version of `ably_pubsub_device_flutter` in your `pubspec.yaml`, if there are breaking changes, follow the [updating / migration guide](UPDATING.md).
 
 ---
 
@@ -73,24 +73,24 @@ import 'package:ably_flutter/ably_flutter.dart' as ably;
 The following code connects to Ably's realtime messaging service, subscribes to a channel to receive messages, and publishes a test message to that same channel:
 
 ```dart
-  // Initialize Ably Realtime client
+  // Initialize Ably Pub/Sub client
   final clientOptions = ably.ClientOptions(
     key: 'your-ably-api-key',
     clientId: 'me',
   );
 
-  final realtimeClient = ably.Realtime(options: clientOptions);
+  final pubSubClient = ably.createClient(options: clientOptions);
 
   // Wait for connection to be established
-  await realtimeClient.connection
+  await pubSubClient.connection
       .on(ably.ConnectionEvent.connected)
       .first
       .then((stateChange) {
     print('Connected to Ably');
   });
 
   // Get a reference to the 'test-channel' channel
-  final channel = realtimeClient.channels.get('test-channel');
+  final channel = pubSubClient.channels.get('test-channel');
 
   // Subscribe to all messages published to this channel
   channel.subscribe().listen((ably.Message message) {

UPDATING.md

@@ -2,6 +2,27 @@
 
 This guide lists the changes needed to upgrade from one version of Ably to a newer one when there are breaking changes.
 
+## [Upgrading from v1.2.x]
+
+- The package has been renamed from `ably_flutter` to `ably_pubsub_device_flutter`. Update the dependency in your `pubspec.yaml` and every import:
+  - `ably_flutter: ^1.2.x` becomes `ably_pubsub_device_flutter: ^2.0.0`.
+  - `import 'package:ably_flutter/ably_flutter.dart' as ably;` becomes `import 'package:ably_pubsub_device_flutter/ably_pubsub_device_flutter.dart' as ably;`.
+  - On iOS, the pod and Swift module are renamed too, so an AppDelegate that did `import ably_flutter` now needs `import ably_pubsub_device_flutter`.
+- The `Realtime` client has been renamed to `PubSubClient`, and it is now created with the top-level `ably.createClient()` function rather than a constructor. `PubSubClient` no longer has a public constructor, and `Realtime.fromKey(key)` and the `key` parameter have both been removed; pass the key through `ClientOptions` instead.
+  - Replace `ably.Realtime(options: clientOptions)` with `ably.createClient(options: clientOptions)`.
+  - Replace `ably.Realtime.fromKey(key)` / `ably.Realtime(key: key)` with `ably.createClient(options: ably.ClientOptions(key: key))`.
+- All previously deprecated API has been removed:
+  - `Connection.recoveryKey`. Use `Connection.createRecoveryKey()`.
+  - `ClientOptions.logHandler` and the `LogHandler` typedef. Log output is handled by the underlying native SDK; use `ClientOptions.logLevel` to control verbosity.
+  - `ClientOptions.fallbackHostsUseDefault`. There is no replacement; default fallback hosts are used automatically unless `ClientOptions.fallbackHosts` is set.
+  - `ClientOptions.fromKey(key)` and `AuthOptions.fromKey(key)`. Use the constructors' named `key` parameter instead.
+- The REST client has been removed. Use `PubSubClient` instead:
+  - Replace `ably.Rest(options: clientOptions)` / `ably.Rest.fromKey(key)` with `ably.createClient(options: clientOptions)` / `ably.createClient(options: ably.ClientOptions(key: key))`, and use `channels`, `auth`, `push` and `time()` on the `PubSubClient` in place of their `Rest` equivalents.
+  - `RestChannel`, `RestChannels`, `RestPresence`, `RestChannelOptions`, `RestHistoryParams` and `RestPresenceParams` have been removed. Use `RealtimeChannel`, `RealtimeChannels`, `RealtimePresence`, `RealtimeChannelOptions`, `RealtimeHistoryParams` and `RealtimePresenceParams`.
+  - `Message.fromEncoded`, `Message.fromEncodedArray`, `PresenceMessage.fromEncoded` and `PresenceMessage.fromEncodedArray` now take a `RealtimeChannelOptions` instead of a `RestChannelOptions`.
+  - `Push` and `PushChannel` no longer accept a `rest` client; they now require a `realtime` client.
+- `RealtimeChannels.release()` now returns a `Future<void>`, which completes once the channel has been released. A realtime channel can only be released when it is in the `INITIALIZED`, `DETACHED`, or `FAILED` state. Releasing a channel in any other state no longer detaches it implicitly. Instead, the future completes with an `AblyException` with code 90011 and the channel is not released. To release an attached channel, `await channel.detach()` first and then `await realtime.channels.release(name)`.
+
 ## [Upgrading from v1.2.13]
 
 - Updated SDK constraint to `>=2.14.0 <3.0.0`

analysis_options.yaml

@@ -73,7 +73,6 @@ linter:
     - no_runtimeType_toString
     - omit_local_variable_types
     - only_throw_errors
-    - package_api_docs
     - prefer_adjacent_string_concatenation
     - prefer_asserts_in_initializer_lists
     - prefer_expression_function_bodies

android/settings.gradle

@@ -1 +1 @@
-rootProject.name = 'ably_flutter'
+rootProject.name = 'ably_pubsub_device_flutter'

android/src/main/java/io/ably/flutter/plugin/AblyInstanceStore.java

@@ -8,8 +8,6 @@
 import io.ably.lib.push.Push;
 import io.ably.lib.push.PushChannel;
 import io.ably.lib.realtime.AblyRealtime;
-import io.ably.lib.rest.AblyBase;
-import io.ably.lib.rest.AblyRest;
 import io.ably.lib.types.AblyException;
 import io.ably.lib.types.AsyncPaginatedResult;
 import io.ably.lib.types.ClientOptions;
@@ -31,7 +29,6 @@ class AblyInstanceStore {
     // suggests using LongSparseArray. More information at https://stackoverflow.com/a/31413003
     // It may be simpler to go back to HashMap because this is an unmeasured memory optimisation.
     // > the Hashmap and the SparseArray are very similar for data structure sizes under 1,000
-    private final LongSparseArray<AblyRest> restInstances = new LongSparseArray<>();
     private final LongSparseArray<AblyRealtime> realtimeInstances = new LongSparseArray<>();
     private final LongSparseArray<AsyncPaginatedResult<Object>> paginatedResults = new LongSparseArray<>();
     private final AtomicLong nextHandle = new AtomicLong(1);
@@ -43,8 +40,8 @@ static synchronized AblyInstanceStore getInstance() {
     /**
      * A reserved client handle. Safe to be used from any thread.
      *
-     * Instances support the creation of a single Rest or Realtime instance, where only one of the
-     * create methods may be called and it may only be called once.
+     * Instances support the creation of a single Realtime instance, where the create method may
+     * only be called once.
      */
     interface ClientHandle {
         /**
@@ -54,25 +51,13 @@ interface ClientHandle {
          */
         long getHandle();
 
-        /**
-         * Create an {@link AblyRest} instance and store it using this handle.
-         * @param clientOptions The Ably client options for the new Rest instance.
-         * @param applicationContext The Android application context to supply to the new Rest
-         * instance using its {@link AblyRest#setAndroidContext(Context)} method.
-         * @return The handle used to store the instance. Same as {@link #getHandle()}.
-         * @throws IllegalStateException If this handle has already been used to create a Rest or
-         * Realtime instance.
-         * @throws AblyException If the {@link AblyRest} instance creation failed.
-         */
-        long createRest(ClientOptions clientOptions, Context applicationContext) throws AblyException;
-
         /**
          * Create an {@link AblyRealtime} instance and store it using this handle.
          * @param clientOptions The Ably client options for the new Realtime instance.
          * @param applicationContext The Android application context to supply to the new Realtime
          * instance using its {@link AblyRealtime#setAndroidContext(Context)} method.
          * @return The handle used to store the instance. Same as {@link #getHandle()}.
-         * @throws IllegalStateException If this handle has already been used to create a Rest or
+         * @throws IllegalStateException If this handle has already been used to create a
          * Realtime instance.
          * @throws AblyException If the {@link AblyRealtime} instance creation failed.
          */
@@ -92,15 +77,6 @@ public long getHandle() {
             return handle;
         }
 
-        @Override
-        public synchronized long createRest(final ClientOptions clientOptions, final Context applicationContext) throws AblyException {
-            final long handle = use();
-            final AblyRest rest = new AblyRest(clientOptions);
-            rest.setAndroidContext(applicationContext);
-            restInstances.put(handle, rest);
-            return handle;
-        }
-
         @Override
         public synchronized long createRealtime(final ClientOptions clientOptions, final Context applicationContext) throws AblyException {
             final long handle = use();
@@ -123,36 +99,16 @@ synchronized ClientHandle reserveClientHandle() {
         return new ReservedClientHandle(nextHandle.getAndIncrement());
     }
 
-    synchronized AblyRest getRest(final long handle) {
-        return restInstances.get(handle);
-    }
-
     synchronized AblyRealtime getRealtime(final long handle) {
         return realtimeInstances.get(handle);
     }
 
-    /**
-     * Gets the Ably client (either REST or Realtime) when the interface being
-     * used is the same (e.g. When using Push from AblyBase / when it does
-     * not matter).
-     *
-     * This method relies on the fact handles are unique between all Ably clients,
-     * (both rest and realtime).
-     * @param handle integer handle to either AblyRealtime or AblyRest
-     * @return AblyBase
-     */
-    synchronized AblyBase getAblyClient(final long handle) {
-        AblyRealtime realtime = getRealtime(handle);
-        return (realtime != null) ? realtime : getRest(handle);
-    }
-
     synchronized Push getPush(final long handle) {
-        AblyRealtime realtime = getRealtime(handle);
-        return (realtime != null) ? realtime.push : getRest(handle).push;
+        return getRealtime(handle).push;
     }
-    
+
     synchronized PushChannel getPushChannel(final long handle, final String channelName) {
-        return getAblyClient(handle)
+        return getRealtime(handle)
                 .channels
                 .get(channelName).push;
     }
@@ -183,7 +139,6 @@ synchronized void reset() {
             }
         }
         realtimeInstances.clear();
-        restInstances.clear();
         paginatedResults.clear();
     }
 }