From a4b54aaf17624782c0a4264544a0e59a8b46de95 Mon Sep 17 00:00:00 2001 From: andreykropotov Date: Mon, 7 Sep 2026 19:40:43 +0400 Subject: [PATCH 1/3] fix(tracking): let syncCart and syncFavorites report an empty collection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The wrapper rejected an empty list with an ArgumentError, so an emptied cart could not be reported from Flutter at all. The native SDKs deliberately do the opposite — Android's `putEmptyItemsIfNone` always sends the list — so the check contradicted the platform instead of guarding it. --- lib/src/tracking/tracking_api.dart | 13 ++++++------- test/tracking_namespace_test.dart | 13 ++++++++++--- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/lib/src/tracking/tracking_api.dart b/lib/src/tracking/tracking_api.dart index 6ce74a8..064324b 100644 --- a/lib/src/tracking/tracking_api.dart +++ b/lib/src/tracking/tracking_api.dart @@ -6,7 +6,7 @@ import 'tracking_models.dart'; /// Standard tracking events — the `tracking` namespace of the SDK. /// -/// Reached through an SDK handle: `Rees46.getInstance().tracking.productView('sku-1')`. +/// Reached through an SDK handle: `REES46.getInstance().tracking.productView('sku-1')`. /// Every method routes to the native namespace of the same name, so an event fired from Dart /// is the same request the native SDKs send. class TrackingApi { @@ -44,10 +44,10 @@ class TrackingApi { } /// Full cart contents after a change (`cart` with `full_cart`). + /// + /// An empty list is the way to report an emptied cart: the native SDKs always + /// send the list, so `items` goes on the wire as `[]`. Future syncCart(List items) { - if (items.isEmpty) { - throw ArgumentError.value(items, 'items', 'must be non-empty'); - } return _api.trackSyncCart(items.map((e) => e._wire).toList(), _shopId); } @@ -64,10 +64,9 @@ class TrackingApi { } /// Full favorites contents after a change (`wish` with `full_wish`). + /// + /// An empty list reports emptied favorites, the same way [syncCart] does. Future syncFavorites(List itemIds) { - if (itemIds.isEmpty) { - throw ArgumentError.value(itemIds, 'itemIds', 'must be non-empty'); - } return _api.trackSyncFavorites(itemIds, _shopId); } diff --git a/test/tracking_namespace_test.dart b/test/tracking_namespace_test.dart index f432d34..137c00e 100644 --- a/test/tracking_namespace_test.dart +++ b/test/tracking_namespace_test.dart @@ -226,9 +226,16 @@ void main() { ); }); - test('empty collections throw', () { - expect(() => sdk.tracking.syncCart(const []), throwsArgumentError); - expect(() => sdk.tracking.syncFavorites(const []), throwsArgumentError); + test('an empty collection is sent, not rejected', () async { + // Emptying the cart or the favorites is a real event: the native SDKs + // always send the list, so the wrapper must not stand in the way. + final cart = capture('trackSyncCart'); + await sdk.tracking.syncCart(const []); + expect(cart()[0], isEmpty); + + final favorites = capture('trackSyncFavorites'); + await sdk.tracking.syncFavorites(const []); + expect(favorites()[0], isEmpty); }); }); From 7eeb58570273105938fb4e185f20e7ca35e54da1 Mon Sep 17 00:00:00 2001 From: andreykropotov Date: Mon, 7 Sep 2026 19:40:43 +0400 Subject: [PATCH 2/3] docs(tracking): attribute events to the campaign that brought the user in MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The attribution examples used a recommender block as the source, including as the stored one. A stored source describes where the user arrived from — a bulk push, a chain — and the values come from the link that opened the app. --- README.md | 74 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 39 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 724fdbf..9ea3884 100644 --- a/README.md +++ b/README.md @@ -67,15 +67,15 @@ late final PersonalizationSdk sdk; void main() { WidgetsFlutterBinding.ensureInitialized(); - sdk = Rees46.initialize( - const Rees46Config(shopId: 'YOUR_SHOP_ID'), + sdk = REES46.initialize( + const REES46Config(shopId: 'YOUR_SHOP_ID'), ); runApp(const MyApp()); } ``` -`Rees46` is the entry point. `Rees46.initialize` **returns the handle +`REES46` is the entry point. `REES46.initialize` **returns the handle synchronously** and starts native initialization in the background; calls issued right after are queued natively until the session is ready, so the handle is usable straight away. A broken setup surfaces as a `PlatformException` on the @@ -99,12 +99,12 @@ there is simply no token to send. Keep one place that owns the handle, so no widget re-initializes: ```dart -class Rees46Service { +class REES46Service { static const _shopId = 'YOUR_SHOP_ID'; - static PersonalizationSdk get sdk => Rees46.isInitialized(_shopId) - ? Rees46.getInstance(_shopId) - : Rees46.initialize(const Rees46Config(shopId: _shopId)); + static PersonalizationSdk get sdk => REES46.isInitialized(_shopId) + ? REES46.getInstance(_shopId) + : REES46.initialize(const REES46Config(shopId: _shopId)); } ``` @@ -124,12 +124,12 @@ Each gets its own native instance with isolated storage, session and `did`. ```dart // Registered now, initialized on first use. -Rees46.registerShops(const [ - Rees46Config(shopId: 'shop-a'), - Rees46Config(shopId: 'shop-b'), +REES46.registerShops(const [ + REES46Config(shopId: 'shop-a'), + REES46Config(shopId: 'shop-b'), ]); // pass eagerInit: true to initialize up front -final shopA = Rees46.getInstance('shop-a'); +final shopA = REES46.getInstance('shop-a'); ``` Address instances explicitly once more than one is registered: `getInstance()` @@ -154,7 +154,7 @@ Awaiting is optional — fire-and-forget from UI code is fine. With several shops the namespace follows the instance: ```dart -await Rees46.getInstance('shop-b').tracking.productView('sku-1'); +await REES46.getInstance('shop-b').tracking.productView('sku-1'); ``` ### Catalog @@ -202,8 +202,10 @@ await sdk.tracking.syncFavorites(const ['sku-1', 'sku-2']); await sdk.tracking.removeFromFavorites('sku-1'); ``` -`syncCart` and `syncFavorites` reject an empty list with an `ArgumentError` — -drop the last item through `removeFromCart` / `removeFromFavorites` instead. +An empty list is how an emptied cart or wishlist is reported: `items` goes on +the wire as `[]` alongside `full_cart` / `full_wish`, which is what the native +SDKs send. Removing a single product is still `removeFromCart` / +`removeFromFavorites`. ### Stories @@ -289,39 +291,41 @@ duplicated under `payload`. The SDK's own keys are reserved and rejected — ### Attribution -Events can carry the tool the user came from. Per call, for one event: +Events can carry the campaign the user arrived from — a bulk mobile push, a +chain. Both values come from the link that opened the app, which carries them as +`recommended_by` and `recommended_code`: -```dart -await sdk.tracking.productView( - 'sku-1', - source: const TrackingSource( - type: TrackingSourceType.dynamicBlock, - code: 'main_page_block', - ), -); +``` +myshop://product/sku-1?recommended_by=bulk&recommended_code=jkIWdXSRfwVyK ``` -`source` is accepted by `productView`, `addToCart` and `addToFavorites` — the -events a recommendation leads to. - -Or stored once, for the events that follow — the case where the source outlives -a single call, such as a user entering the catalog from a recommender block: +A campaign brings the user in and then colours everything they do next, so store +it once when you handle the link: ```dart await sdk.tracking.setSource( - const TrackingSource( - type: TrackingSourceType.dynamicBlock, - code: 'main_page_block', - ), + const TrackingSource(type: TrackingSourceType.bulk, code: 'jkIWdXSRfwVyK'), ); -// Carries source=main_page_block without being told to. +// Carries recommended_by=bulk without being told to. await sdk.tracking.productView('sku-1'); ``` The stored source lives natively per shop, survives restarts, and is kept for 48 -hours or until it is replaced. A per-call `source` wins over the stored one, and -an order is attributed by the `recommendedSource` of the `purchase` call itself. +hours or until it is replaced. + +To attribute a single event instead of everything that follows, pass `source` per +call — `productView`, `addToCart` and `addToFavorites` accept it: + +```dart +await sdk.tracking.addToCart( + const TrackingItem(id: 'sku-1', quantity: 1), + source: const TrackingSource(type: TrackingSourceType.chain, code: 'welcome_2'), +); +``` + +A per-call `source` wins over the stored one, and an order is attributed by the +`recommendedSource` of the `purchase` call itself. | `TrackingSourceType` | Wire value | Set by | |---|---|---| From d6678d669727b8cd996034ad642fcd0ea87b41b8 Mon Sep 17 00:00:00 2001 From: andreykropotov Date: Mon, 7 Sep 2026 19:40:43 +0400 Subject: [PATCH 3/3] refactor(sdk)!: spell the facade REES46 The public entry point carried the brand as `Rees46`; it is spelled REES46. Renames `Rees46`, `Rees46Config`, `Rees46Error` and `Rees46SdkFactory` along with the doc comments and the pigeon-generated header. BREAKING CHANGE: `Rees46` and friends are now `REES46`. --- .../pigeon/PersonalizationApi.g.kt | 2 +- example/lib/main.dart | 10 +-- example/lib/multi_instance_pane.dart | 28 +++--- ios/Classes/pigeon/PersonalizationApi.g.swift | 4 +- lib/src/multi_instance/instance_resolver.dart | 2 +- lib/src/multi_instance/push_event.dart | 2 +- lib/src/multi_instance/rees46.dart | 36 ++++---- lib/src/multi_instance/rees46_config.dart | 10 +-- lib/src/multi_instance/sdk_exceptions.dart | 14 +-- lib/src/personalization_sdk.dart | 10 +-- lib/src/pigeon/personalization_api.g.dart | 2 +- pigeons/personalization_api.dart | 4 +- test/multi_instance/handle_push_test.dart | 44 +++++----- test/multi_instance/rees46_facade_test.dart | 86 +++++++++---------- 14 files changed, 127 insertions(+), 127 deletions(-) diff --git a/android/src/main/kotlin/com/rees46/rees46_flutter_sdk/pigeon/PersonalizationApi.g.kt b/android/src/main/kotlin/com/rees46/rees46_flutter_sdk/pigeon/PersonalizationApi.g.kt index c923cd5..3721566 100644 --- a/android/src/main/kotlin/com/rees46/rees46_flutter_sdk/pigeon/PersonalizationApi.g.kt +++ b/android/src/main/kotlin/com/rees46/rees46_flutter_sdk/pigeon/PersonalizationApi.g.kt @@ -495,7 +495,7 @@ interface PersonalizationHostApi { fun getCollection(collectionId: String, shopId: String?, callback: (Result) -> Unit) /** * Routes a push to the shop it belongs to (payload `shop_id`) and tracks it - * via the native `Rees46.handlePush`. [event] is the index of the Dart + * via the native `REES46.handlePush`. [event] is the index of the Dart * `PushEvent` enum: 0 = received, 1 = delivered, 2 = clicked. The native side * maps it to its own vocabulary (Android `PushEventType`, iOS `PushEvent`). */ diff --git a/example/lib/main.dart b/example/lib/main.dart index fdc94c2..0a28a95 100644 --- a/example/lib/main.dart +++ b/example/lib/main.dart @@ -136,10 +136,10 @@ final List<_TrackingDemo> _trackingDemos = [ ]; class _InitPageState extends State { - // Initialized through the multi-instance [Rees46] facade — the same entry + // Initialized through the multi-instance [REES46] facade — the same entry // point the iOS/Android demos use — so shop A is registered in the facade and // the Multi-instance screen reaches the very same instance via - // Rees46.getInstance(shopId). Bound to shop A explicitly, so every call stays + // REES46.getInstance(shopId). Bound to shop A explicitly, so every call stays // unambiguous even after that screen brings a second shop to life. Assigned in // [_initialize] (rebuilt on re-initialize). late PersonalizationSdk _sdk; @@ -288,10 +288,10 @@ class _InitPageState extends State { // Initialize shop A through the multi-instance facade — the unified entry // point, same as iOS/Android. Returns the handle and registers the shop, // so the Multi-instance screen resolves the very same instance via - // Rees46.getInstance(shopId). Re-initializing rebuilds the handle with the + // REES46.getInstance(shopId). Re-initializing rebuilds the handle with the // current toggles. - _sdk = Rees46.initialize( - Rees46Config( + _sdk = REES46.initialize( + REES46Config( shopId: _shopId, apiDomain: _apiDomain, stream: _stream, diff --git a/example/lib/multi_instance_pane.dart b/example/lib/multi_instance_pane.dart index f5e9663..42b48e6 100644 --- a/example/lib/multi_instance_pane.dart +++ b/example/lib/multi_instance_pane.dart @@ -8,7 +8,7 @@ import 'package:rees46_sdk/rees46_sdk.dart'; /// default; shop B is registered lazily and comes to life the moment this screen /// resolves it. Everything each instance sends carries its own `shop_id`/`did`, /// so the two session cards (did/sid) are the in-app proof of isolation. Also -/// exercises the fail-fast resolution contract and `Rees46.handlePush` routing. +/// exercises the fail-fast resolution contract and `REES46.handlePush` routing. /// /// (The native demos also show per-shop Stories; the Flutter SDK exposes no /// stories widget, so that part is omitted here.) @@ -42,20 +42,20 @@ class _MultiInstancePaneState extends State { super.initState(); // Shop A — eager default. - _shopA = Rees46.isInitialized(MultiInstancePane.shopIdA) - ? Rees46.getInstance(MultiInstancePane.shopIdA) - : Rees46.initialize( - const Rees46Config(shopId: MultiInstancePane.shopIdA), + _shopA = REES46.isInitialized(MultiInstancePane.shopIdA) + ? REES46.getInstance(MultiInstancePane.shopIdA) + : REES46.initialize( + const REES46Config(shopId: MultiInstancePane.shopIdA), ); // Shop B — registered lazily, then materialized right here by resolving it. - if (!Rees46.isInitialized(MultiInstancePane.shopIdB) && - !Rees46.pendingShopIds.contains(MultiInstancePane.shopIdB)) { - Rees46.registerShops(const [ - Rees46Config(shopId: MultiInstancePane.shopIdB), + if (!REES46.isInitialized(MultiInstancePane.shopIdB) && + !REES46.pendingShopIds.contains(MultiInstancePane.shopIdB)) { + REES46.registerShops(const [ + REES46Config(shopId: MultiInstancePane.shopIdB), ]); } - _shopB = Rees46.getInstance(MultiInstancePane.shopIdB); // B is born here + _shopB = REES46.getInstance(MultiInstancePane.shopIdB); // B is born here _shopA.setPushNotificationCallbacks( onReceived: (p) => _addLog('✓ shop A onReceived: ${_pushLabel(p)}'), @@ -125,7 +125,7 @@ class _MultiInstancePaneState extends State { 'title': note, 'body': note, }; - final routed = await Rees46.handlePush(payload, PushEvent.received); + final routed = await REES46.handlePush(payload, PushEvent.received); final result = routed != null ? 'routed:$routed' : 'dropped'; setState(() => _lastPushResult = result); _addLog('injected shop_id=${shopId ?? '—'} → $result'); @@ -180,13 +180,13 @@ class _MultiInstancePaneState extends State { children: [ ElevatedButton( onPressed: () => - _runContract('getInstance()', () => Rees46.getInstance()), + _runContract('getInstance()', () => REES46.getInstance()), child: const Text('getInstance() → Ambiguous'), ), ElevatedButton( onPressed: () => _runContract( 'getInstance("nope")', - () => Rees46.getInstance('nope'), + () => REES46.getInstance('nope'), ), child: const Text('getInstance("nope") → Unknown'), ), @@ -200,7 +200,7 @@ class _MultiInstancePaneState extends State { const SizedBox(height: 16), const Text( - 'Push routing (Rees46.handlePush)', + 'Push routing (REES46.handlePush)', style: TextStyle(fontWeight: FontWeight.bold), ), Wrap( diff --git a/ios/Classes/pigeon/PersonalizationApi.g.swift b/ios/Classes/pigeon/PersonalizationApi.g.swift index cc8146b..59a99a8 100644 --- a/ios/Classes/pigeon/PersonalizationApi.g.swift +++ b/ios/Classes/pigeon/PersonalizationApi.g.swift @@ -531,7 +531,7 @@ protocol PersonalizationHostApi { /// Dart layer parses the result into [CollectionResponse]. func getCollection(collectionId: String, shopId: String?, completion: @escaping (Result) -> Void) /// Routes a push to the shop it belongs to (payload `shop_id`) and tracks it - /// via the native `Rees46.handlePush`. [event] is the index of the Dart + /// via the native `REES46.handlePush`. [event] is the index of the Dart /// `PushEvent` enum: 0 = received, 1 = delivered, 2 = clicked. The native side /// maps it to its own vocabulary (Android `PushEventType`, iOS `PushEvent`). func handlePush(payload: [String: String], event: Int64, completion: @escaping (Result) -> Void) @@ -935,7 +935,7 @@ class PersonalizationHostApiSetup { getCollectionChannel.setMessageHandler(nil) } /// Routes a push to the shop it belongs to (payload `shop_id`) and tracks it - /// via the native `Rees46.handlePush`. [event] is the index of the Dart + /// via the native `REES46.handlePush`. [event] is the index of the Dart /// `PushEvent` enum: 0 = received, 1 = delivered, 2 = clicked. The native side /// maps it to its own vocabulary (Android `PushEventType`, iOS `PushEvent`). let handlePushChannel = FlutterBasicMessageChannel(name: "dev.flutter.pigeon.personalization_flutter_sdk.PersonalizationHostApi.handlePush\(channelSuffix)", binaryMessenger: binaryMessenger, codec: codec) diff --git a/lib/src/multi_instance/instance_resolver.dart b/lib/src/multi_instance/instance_resolver.dart index 7615deb..fd241c7 100644 --- a/lib/src/multi_instance/instance_resolver.dart +++ b/lib/src/multi_instance/instance_resolver.dart @@ -1,4 +1,4 @@ -/// Pure decision logic behind [Rees46.getInstance]: given the requested `shopId` +/// Pure decision logic behind [REES46.getInstance]: given the requested `shopId` /// (or none) and the sets of live and pending shops, decides which instance to /// return, whether one must be lazily materialized, or which error to raise. /// diff --git a/lib/src/multi_instance/push_event.dart b/lib/src/multi_instance/push_event.dart index 9e7f57e..dd1c8f3 100644 --- a/lib/src/multi_instance/push_event.dart +++ b/lib/src/multi_instance/push_event.dart @@ -1,4 +1,4 @@ -/// Push lifecycle event routed by [Rees46.handlePush]. +/// Push lifecycle event routed by [REES46.handlePush]. /// /// The Flutter vocabulary — `received` / `delivered` / `clicked` — matches the /// SDK's existing push callbacks. Native maps it to its own set: Android diff --git a/lib/src/multi_instance/rees46.dart b/lib/src/multi_instance/rees46.dart index 1704e8c..09dcbce 100644 --- a/lib/src/multi_instance/rees46.dart +++ b/lib/src/multi_instance/rees46.dart @@ -8,7 +8,7 @@ import 'sdk_exceptions.dart'; /// Builds and initializes a [PersonalizationSdk] handle for [config]. Injectable /// so tests can resolve shops without touching native or Pigeon. -typedef Rees46SdkFactory = PersonalizationSdk Function(Rees46Config config); +typedef REES46SdkFactory = PersonalizationSdk Function(REES46Config config); /// Public entry point for the Flutter SDK — the unified, multi-instance API. /// @@ -18,12 +18,12 @@ typedef Rees46SdkFactory = PersonalizationSdk Function(Rees46Config config); /// /// ```dart /// // Single shop: -/// final sdk = Rees46.initialize(Rees46Config(shopId: 'SHOP_ID')); +/// final sdk = REES46.initialize(REES46Config(shopId: 'SHOP_ID')); /// sdk.trackEvent('category', ...); /// /// // Several shops, initialized lazily on first use: -/// Rees46.registerShops([Rees46Config(shopId: 'shop-a'), Rees46Config(shopId: 'shop-b')]); -/// Rees46.getInstance('shop-a').trackEvent('category', ...); +/// REES46.registerShops([REES46Config(shopId: 'shop-a'), REES46Config(shopId: 'shop-b')]); +/// REES46.getInstance('shop-a').trackEvent('category', ...); /// ``` /// /// ## Why the facade holds a shop-id mirror @@ -37,14 +37,14 @@ typedef Rees46SdkFactory = PersonalizationSdk Function(Rees46Config config); /// remains the source of truth for the instances themselves. /// /// Per-call routing to a specific native instance (threading `shopId` through -/// every Pigeon call) lands once the native `Rees46` facade ships in the +/// every Pigeon call) lands once the native `REES46` facade ships in the /// consumed artifacts — see the plan (`Multi-instance — Flutter Plan`, step F3). /// Until then single-shop [initialize] is fully functional and the resolution /// contract below is complete and tested. -class Rees46 { - Rees46._(); +class REES46 { + REES46._(); - static final Rees46 _instance = Rees46._(); + static final REES46 _instance = REES46._(); /// Live (initialized) instances by shop id. The Dart-side mirror of the /// native registry — used for resolution only. @@ -52,14 +52,14 @@ class Rees46 { /// Shops registered lazily and not yet initialized. Materialized on the first /// [getInstance] for the shop. - final Map _pending = {}; + final Map _pending = {}; - Rees46SdkFactory _factory = _defaultFactory; + REES46SdkFactory _factory = _defaultFactory; - static PersonalizationSdk _defaultFactory(Rees46Config config) { + static PersonalizationSdk _defaultFactory(REES46Config config) { final sdk = PersonalizationSdk(shopId: config.shopId); // F1: delegates to the existing single-shop native init. Per-call `shopId` - // routing to the native `Rees46` facade lands in plan step F3. + // routing to the native `REES46` facade lands in plan step F3. sdk.initialize(config.toSdkInitConfig()); return sdk; } @@ -71,7 +71,7 @@ class Rees46 { /// Initializes an SDK instance for [config] immediately and returns it. The /// instance is registered, so it is also reachable via [getInstance]. Any /// pending registration for the same shop is cleared. - static PersonalizationSdk initialize(Rees46Config config) => + static PersonalizationSdk initialize(REES46Config config) => _instance._initialize(config); /// Registers [configs] without initializing them. Initialization happens @@ -79,7 +79,7 @@ class Rees46 { /// the current region is needed. Pass [eagerInit] = true to initialize every /// shop up front — the super-shop case, where instances must stay consistent. static void registerShops( - List configs, { + List configs, { bool eagerInit = false, }) => _instance._registerShops(configs, eagerInit: eagerInit); @@ -99,7 +99,7 @@ class Rees46 { _instance._isInitialized(shopId); /// Routes a push to the shop it belongs to (the payload's `shop_id`) and tracks - /// [event] for it via the native `Rees46.handlePush`, then fires that shop's + /// [event] for it via the native `REES46.handlePush`, then fires that shop's /// registered push callbacks. Call this from a host that owns its messaging /// service. /// @@ -126,14 +126,14 @@ class Rees46 { // Instance implementation // --------------------------------------------------------------------------- - PersonalizationSdk _initialize(Rees46Config config) { + PersonalizationSdk _initialize(REES46Config config) { final sdk = _factory(config); _live[config.shopId] = sdk; _pending.remove(config.shopId); return sdk; } - void _registerShops(List configs, {required bool eagerInit}) { + void _registerShops(List configs, {required bool eagerInit}) { for (final config in configs) { if (eagerInit) { _initialize(config); @@ -210,7 +210,7 @@ class Rees46 { /// Test-only: overrides the factory that builds/initializes instances so shop /// resolution can be exercised without touching native or Pigeon. @visibleForTesting - static set debugFactory(Rees46SdkFactory factory) => + static set debugFactory(REES46SdkFactory factory) => _instance._factory = factory; /// Test-only: drops all live and pending registrations and restores the diff --git a/lib/src/multi_instance/rees46_config.dart b/lib/src/multi_instance/rees46_config.dart index 15ac466..1abbebc 100644 --- a/lib/src/multi_instance/rees46_config.dart +++ b/lib/src/multi_instance/rees46_config.dart @@ -1,17 +1,17 @@ import '../sdk_init_config.dart'; /// Configuration for one SDK instance (one shop), passed to -/// [Rees46.initialize] / [Rees46.registerShops]. +/// [REES46.initialize] / [REES46.registerShops]. /// -/// Mirrors the native `Rees46Config` (Android/iOS). It is a superset of the +/// Mirrors the native `REES46Config` (Android/iOS). It is a superset of the /// legacy [SdkInitConfig]: the same init fields plus an optional [storageKey] /// for the storage-partition key (defaults to `shopId` natively). /// /// `storageKey` is **reserved for parity** and not wired end-to-end yet: the /// Pigeon `InitConfig` has no `storageKey` field, so the native default /// (partition == `shopId`) applies until the bridge threads it (plan step F2). -class Rees46Config { - const Rees46Config({ +class REES46Config { + const REES46Config({ required this.shopId, this.apiDomain, this.stream, @@ -49,7 +49,7 @@ class Rees46Config { needReInitialization: needReInitialization, ); - Rees46Config copyWith({String? shopId, String? storageKey}) => Rees46Config( + REES46Config copyWith({String? shopId, String? storageKey}) => REES46Config( shopId: shopId ?? this.shopId, apiDomain: apiDomain, stream: stream, diff --git a/lib/src/multi_instance/sdk_exceptions.dart b/lib/src/multi_instance/sdk_exceptions.dart index 86bf4d4..97dcebc 100644 --- a/lib/src/multi_instance/sdk_exceptions.dart +++ b/lib/src/multi_instance/sdk_exceptions.dart @@ -1,9 +1,9 @@ -/// Exceptions raised by [Rees46] shop resolution. +/// Exceptions raised by [REES46] shop resolution. /// /// They mirror the native contract so the same failure modes surface /// identically on every platform (see `Multi-instance — Contracts`): /// * Android — `UnknownShopIdException` / `AmbiguousShopException` -/// * iOS — `Rees46Error.unknownShopId` / `.ambiguousShop` +/// * iOS — `REES46Error.unknownShopId` / `.ambiguousShop` /// /// The Flutter SDK is a thin bridge over the native SDKs, so these are raised by /// the Dart facade's own resolver (a mirror of the registered shop-ids) — the @@ -15,7 +15,7 @@ library; class UnknownShopIdException implements Exception { const UnknownShopIdException(this.shopId, [this.customMessage]); - /// The requested shop id, or `null` when [Rees46.getInstance] was called with + /// The requested shop id, or `null` when [REES46.getInstance] was called with /// no id while nothing at all is registered. final String? shopId; @@ -26,15 +26,15 @@ class UnknownShopIdException implements Exception { customMessage ?? (shopId != null ? 'No shop is registered for shopId=$shopId. ' - 'Call Rees46.initialize(...) or Rees46.registerShops(...) first.' + 'Call REES46.initialize(...) or REES46.registerShops(...) first.' : 'No shop has been registered. ' - 'Call Rees46.initialize(...) or Rees46.registerShops(...) first.'); + 'Call REES46.initialize(...) or REES46.registerShops(...) first.'); @override String toString() => 'UnknownShopIdException: $message'; } -/// Thrown when [Rees46.getInstance] is called with no shop id while more than +/// Thrown when [REES46.getInstance] is called with no shop id while more than /// one shop is registered — the default instance is ambiguous. class AmbiguousShopException implements Exception { const AmbiguousShopException(this.registeredShopIds, [this.customMessage]); @@ -47,7 +47,7 @@ class AmbiguousShopException implements Exception { String get message => customMessage ?? - 'More than one shop is registered — call Rees46.getInstance(shopId) with ' + 'More than one shop is registered — call REES46.getInstance(shopId) with ' 'an explicit id. Registered: $registeredShopIds.'; @override diff --git a/lib/src/personalization_sdk.dart b/lib/src/personalization_sdk.dart index a39ae76..04b57ef 100644 --- a/lib/src/personalization_sdk.dart +++ b/lib/src/personalization_sdk.dart @@ -27,8 +27,8 @@ class PersonalizationSdk { final PushNotificationCallbacks _pushCallbacks = PushNotificationCallbacks(); /// The shop this handle is bound to, or `null` for the legacy default - /// instance. Set by [Rees46.initialize] / [Rees46.getInstance]. Reserved for - /// per-call routing once the native `Rees46` facade is wired (plan step F3); + /// instance. Set by [REES46.initialize] / [REES46.getInstance]. Reserved for + /// per-call routing once the native `REES46` facade is wired (plan step F3); /// stored now so multi-instance handles carry their identity. final String? shopId; @@ -67,15 +67,15 @@ class PersonalizationSdk { return _api.getStoredPushToken(shopId); } - /// Routes [payload] to the native `Rees46.handlePush` for [event] (the entry a - /// host with its own messaging service calls). Prefer [Rees46.handlePush], + /// Routes [payload] to the native `REES46.handlePush` for [event] (the entry a + /// host with its own messaging service calls). Prefer [REES46.handlePush], /// which resolves the target shop and drops unroutable pushes first. Future handlePush(Map payload, PushEvent event) { return _api.handlePush(payload, event.index); } /// Fires this handle's registered push callbacks for [event]. Used by - /// [Rees46.handlePush] to deliver an inbound push to the shop it routed to, + /// [REES46.handlePush] to deliver an inbound push to the shop it routed to, /// independent of the process-global Pigeon push channel (real FCM inbound /// routing by `shop_id` is FL-5). void dispatchInboundPush(PushEvent event, Map payload) { diff --git a/lib/src/pigeon/personalization_api.g.dart b/lib/src/pigeon/personalization_api.g.dart index f09d8f5..f5a1867 100644 --- a/lib/src/pigeon/personalization_api.g.dart +++ b/lib/src/pigeon/personalization_api.g.dart @@ -1037,7 +1037,7 @@ class PersonalizationHostApi { } /// Routes a push to the shop it belongs to (payload `shop_id`) and tracks it - /// via the native `Rees46.handlePush`. [event] is the index of the Dart + /// via the native `REES46.handlePush`. [event] is the index of the Dart /// `PushEvent` enum: 0 = received, 1 = delivered, 2 = clicked. The native side /// maps it to its own vocabulary (Android `PushEventType`, iOS `PushEvent`). Future handlePush(Map payload, int event) async { diff --git a/pigeons/personalization_api.dart b/pigeons/personalization_api.dart index eb80664..a7c73a5 100644 --- a/pigeons/personalization_api.dart +++ b/pigeons/personalization_api.dart @@ -139,7 +139,7 @@ class TrackingSourceWire { } // Multi-instance: every per-instance method carries a trailing `String? shopId` -// so the native bridge can resolve the target instance via the native `Rees46` +// so the native bridge can resolve the target instance via the native `REES46` // facade. `shopId == null` means the legacy single/default instance (the // back-compat fallback). `initialize` needs no extra param — its shop id is // inside [InitConfig]; `getPlatformVersion` touches no instance. @@ -251,7 +251,7 @@ abstract class PersonalizationHostApi { String getCollection(String collectionId, String? shopId); /// Routes a push to the shop it belongs to (payload `shop_id`) and tracks it - /// via the native `Rees46.handlePush`. [event] is the index of the Dart + /// via the native `REES46.handlePush`. [event] is the index of the Dart /// `PushEvent` enum: 0 = received, 1 = delivered, 2 = clicked. The native side /// maps it to its own vocabulary (Android `PushEventType`, iOS `PushEvent`). @async diff --git a/test/multi_instance/handle_push_test.dart b/test/multi_instance/handle_push_test.dart index ade26e3..b093a15 100644 --- a/test/multi_instance/handle_push_test.dart +++ b/test/multi_instance/handle_push_test.dart @@ -5,9 +5,9 @@ import 'package:rees46_sdk/src/multi_instance/rees46_config.dart'; import 'package:rees46_sdk/src/personalization_sdk.dart'; import 'package:rees46_sdk/src/pigeon/personalization_api.g.dart' as pigeon; -/// F4 contract: [Rees46.handlePush] resolves the target shop from the payload's +/// F4 contract: [REES46.handlePush] resolves the target shop from the payload's /// `shop_id` (drop on unknown/ambiguous), tracks natively, and fires that shop's -/// callbacks — mirror of the native `Rees46.handlePush` routing. +/// callbacks — mirror of the native `REES46.handlePush` routing. void main() { TestWidgetsFlutterBinding.ensureInitialized(); @@ -17,7 +17,7 @@ void main() { late List> nativeCalls; late Map handles; - Rees46Config cfg(String shopId) => Rees46Config(shopId: shopId); + REES46Config cfg(String shopId) => REES46Config(shopId: shopId); Map push(String? shopId) => { 'shop_id': ?shopId, @@ -42,7 +42,7 @@ void main() { [], ); }); - Rees46.debugFactory = (config) { + REES46.debugFactory = (config) { final sdk = PersonalizationSdk(shopId: config.shopId); handles[config.shopId] = sdk; return sdk; @@ -52,14 +52,14 @@ void main() { tearDown(() { TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger .setMockMessageHandler(handlePushChannel, null); - Rees46.reset(); + REES46.reset(); }); test('routes to the shop named by shop_id and tracks natively', () async { - Rees46.initialize(cfg('A')); - Rees46.initialize(cfg('B')); + REES46.initialize(cfg('A')); + REES46.initialize(cfg('B')); - final routed = await Rees46.handlePush(push('B'), PushEvent.received); + final routed = await REES46.handlePush(push('B'), PushEvent.received); expect(routed, 'B'); expect(nativeCalls, hasLength(1)); @@ -67,52 +67,52 @@ void main() { }); test('unknown shop is dropped — no native call', () async { - Rees46.initialize(cfg('A')); + REES46.initialize(cfg('A')); - final routed = await Rees46.handlePush(push('zzz'), PushEvent.received); + final routed = await REES46.handlePush(push('zzz'), PushEvent.received); expect(routed, isNull); expect(nativeCalls, isEmpty); }); test('no shop_id with a single live shop falls back to it', () async { - Rees46.initialize(cfg('A')); + REES46.initialize(cfg('A')); - final routed = await Rees46.handlePush(push(null), PushEvent.received); + final routed = await REES46.handlePush(push(null), PushEvent.received); expect(routed, 'A'); expect(nativeCalls, hasLength(1)); }); test('no shop_id with two live shops is ambiguous and dropped', () async { - Rees46.initialize(cfg('A')); - Rees46.initialize(cfg('B')); + REES46.initialize(cfg('A')); + REES46.initialize(cfg('B')); - final routed = await Rees46.handlePush(push(null), PushEvent.received); + final routed = await REES46.handlePush(push(null), PushEvent.received); expect(routed, isNull); expect(nativeCalls, isEmpty); }); test('materializes a pending shop and routes to it', () async { - Rees46.registerShops([cfg('A')]); - expect(Rees46.liveShopIds, isEmpty); + REES46.registerShops([cfg('A')]); + expect(REES46.liveShopIds, isEmpty); - final routed = await Rees46.handlePush(push('A'), PushEvent.received); + final routed = await REES46.handlePush(push('A'), PushEvent.received); expect(routed, 'A'); - expect(Rees46.liveShopIds, ['A']); // materialized on the push + expect(REES46.liveShopIds, ['A']); // materialized on the push }); test('fires only the target shop callbacks', () async { - Rees46.initialize(cfg('A')); - Rees46.initialize(cfg('B')); + REES46.initialize(cfg('A')); + REES46.initialize(cfg('B')); Map? gotA; Map? gotB; handles['A']!.setPushNotificationCallbacks(onReceived: (p) => gotA = p); handles['B']!.setPushNotificationCallbacks(onReceived: (p) => gotB = p); - await Rees46.handlePush(push('B'), PushEvent.received); + await REES46.handlePush(push('B'), PushEvent.received); expect(gotB, isNotNull); expect(gotB!['shop_id'], 'B'); diff --git a/test/multi_instance/rees46_facade_test.dart b/test/multi_instance/rees46_facade_test.dart index 466dca4..5520d39 100644 --- a/test/multi_instance/rees46_facade_test.dart +++ b/test/multi_instance/rees46_facade_test.dart @@ -12,96 +12,96 @@ void main() { // resolution contract testable without native or a live Pigeon channel. late List built; - Rees46Config cfg(String shopId) => Rees46Config(shopId: shopId); + REES46Config cfg(String shopId) => REES46Config(shopId: shopId); setUp(() { built = []; - Rees46.debugFactory = (config) { + REES46.debugFactory = (config) { built.add(config.shopId); return PersonalizationSdk(shopId: config.shopId); }; }); - tearDown(Rees46.reset); + tearDown(REES46.reset); group('initialize', () { test('returns a handle bound to the shop and marks it live', () { - final sdk = Rees46.initialize(cfg('a')); + final sdk = REES46.initialize(cfg('a')); expect(sdk.shopId, 'a'); expect(built, ['a']); - expect(Rees46.isInitialized('a'), isTrue); - expect(Rees46.liveShopIds, ['a']); + expect(REES46.isInitialized('a'), isTrue); + expect(REES46.liveShopIds, ['a']); }); test('clears any pending registration for the same shop', () { - Rees46.registerShops([cfg('a')]); - expect(Rees46.pendingShopIds, ['a']); + REES46.registerShops([cfg('a')]); + expect(REES46.pendingShopIds, ['a']); - Rees46.initialize(cfg('a')); + REES46.initialize(cfg('a')); - expect(Rees46.pendingShopIds, isEmpty); - expect(Rees46.liveShopIds, ['a']); + expect(REES46.pendingShopIds, isEmpty); + expect(REES46.liveShopIds, ['a']); }); }); group('registerShops', () { test('lazy by default — registers without building', () { - Rees46.registerShops([cfg('a'), cfg('b')]); + REES46.registerShops([cfg('a'), cfg('b')]); expect(built, isEmpty); - expect(Rees46.pendingShopIds, ['a', 'b']); - expect(Rees46.isInitialized('a'), isFalse); + expect(REES46.pendingShopIds, ['a', 'b']); + expect(REES46.isInitialized('a'), isFalse); }); test('eagerInit builds every shop up front', () { - Rees46.registerShops([cfg('a'), cfg('b')], eagerInit: true); + REES46.registerShops([cfg('a'), cfg('b')], eagerInit: true); expect(built, ['a', 'b']); - expect(Rees46.liveShopIds, ['a', 'b']); - expect(Rees46.pendingShopIds, isEmpty); + expect(REES46.liveShopIds, ['a', 'b']); + expect(REES46.pendingShopIds, isEmpty); }); }); group('getInstance', () { test('no id, single live shop → that instance', () { - Rees46.initialize(cfg('a')); - expect(Rees46.getInstance().shopId, 'a'); + REES46.initialize(cfg('a')); + expect(REES46.getInstance().shopId, 'a'); }); test('explicit id returns the matching live instance', () { - Rees46.initialize(cfg('a')); - Rees46.initialize(cfg('b')); - expect(Rees46.getInstance('b').shopId, 'b'); + REES46.initialize(cfg('a')); + REES46.initialize(cfg('b')); + expect(REES46.getInstance('b').shopId, 'b'); }); test('materializes a pending shop on first use', () { - Rees46.registerShops([cfg('a')]); + REES46.registerShops([cfg('a')]); expect(built, isEmpty); - final sdk = Rees46.getInstance('a'); + final sdk = REES46.getInstance('a'); expect(sdk.shopId, 'a'); expect(built, ['a']); - expect(Rees46.liveShopIds, ['a']); - expect(Rees46.pendingShopIds, isEmpty); + expect(REES46.liveShopIds, ['a']); + expect(REES46.pendingShopIds, isEmpty); }); test('materializes a pending shop only once', () { - Rees46.registerShops([cfg('a')]); - final first = Rees46.getInstance('a'); - final second = Rees46.getInstance('a'); + REES46.registerShops([cfg('a')]); + final first = REES46.getInstance('a'); + final second = REES46.getInstance('a'); expect(built, ['a']); // built once expect(identical(first, second), isTrue); }); test('no id with several shops → AmbiguousShopException', () { - Rees46.initialize(cfg('a')); - Rees46.registerShops([cfg('b')]); + REES46.initialize(cfg('a')); + REES46.registerShops([cfg('b')]); expect( - () => Rees46.getInstance(), + () => REES46.getInstance(), throwsA( isA().having( (e) => e.registeredShopIds, @@ -113,9 +113,9 @@ void main() { }); test('unknown id → UnknownShopIdException', () { - Rees46.initialize(cfg('a')); + REES46.initialize(cfg('a')); expect( - () => Rees46.getInstance('nope'), + () => REES46.getInstance('nope'), throwsA( isA().having( (e) => e.shopId, @@ -128,7 +128,7 @@ void main() { test('no id with nothing registered → UnknownShopIdException', () { expect( - () => Rees46.getInstance(), + () => REES46.getInstance(), throwsA(isA()), ); }); @@ -136,17 +136,17 @@ void main() { group('isInitialized', () { test('null id true only when exactly one live shop', () { - expect(Rees46.isInitialized(), isFalse); - Rees46.initialize(cfg('a')); - expect(Rees46.isInitialized(), isTrue); - Rees46.initialize(cfg('b')); - expect(Rees46.isInitialized(), isFalse); // ambiguous default + expect(REES46.isInitialized(), isFalse); + REES46.initialize(cfg('a')); + expect(REES46.isInitialized(), isTrue); + REES46.initialize(cfg('b')); + expect(REES46.isInitialized(), isFalse); // ambiguous default }); test('pending shop is not counted as initialized', () { - Rees46.registerShops([cfg('a')]); - expect(Rees46.isInitialized('a'), isFalse); - expect(Rees46.isInitialized(), isFalse); + REES46.registerShops([cfg('a')]); + expect(REES46.isInitialized('a'), isFalse); + expect(REES46.isInitialized(), isFalse); }); }); }