@booleanmaths/booleanmaths-rn-sdk 0.2.0 → 0.4.0

package/BooleanmathsRnSdk.podspec

@@ -10,11 +10,39 @@ Pod::Spec.new do |s|
   s.license      = package["license"]
   s.authors      = package["author"]
 
+  # No platform override needed. BooleanMathsSDK has declared a 15.1 floor since
+  # 1.0.1, which is exactly React Native's min_ios_version_supported — pinning a
+  # higher floor here would push it onto every consuming app.
   s.platforms    = { :ios => min_ios_version_supported }
   s.source       = { :git => "https://github.com/medront/react-native-booleanmaths-sdk.git", :tag => "v#{s.version}" }
 
+  # Globs `swift` so ios/BMBooleanMathsBridge.swift is compiled. That shim is
+  # mandatory, not stylistic: BooleanMaths is a pure Swift `@MainActor final
+  # class` with no Objective-C surface, so the .mm cannot reach it directly.
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  # Does not match the generated BooleanmathsRnSdk-Swift.h, which the .mm needs.
   s.private_header_files = "ios/**/*.h"
 
+  s.swift_version = "5.9"
+
+  # `~> 1.1` resolves to >= 1.1, < 2.0. The earlier pin carried a `.1` patch
+  # component purely to exclude 1.0.0, which is still published on Trunk carrying
+  # an iOS 17.0 deployment target and would break the install for any app below
+  # iOS 17. A 1.1 floor excludes it outright, so the patch component is no longer
+  # load-bearing and the range can stay open across minors.
+  s.dependency "BooleanMathsSDK", "~> 1.1"
+
+  # Mirrors Android's BuildConfig.WRAPPER_VERSION, which is read from
+  # package.json so the reported wrapper_version cannot drift from the published
+  # npm version — s.version is that same value. Consumed by the .mm as an
+  # Objective-C preprocessor define; it does not reach Swift.
+  #
+  # $(inherited) is load-bearing: without it this replaces the pod target's
+  # inherited defines instead of appending, dropping DEBUG, RCT_NEW_ARCH_ENABLED
+  # and the FOLLY_* flags that React Native's own xcconfig sets.
+  s.pod_target_xcconfig = {
+    "GCC_PREPROCESSOR_DEFINITIONS" => "$(inherited) BMRN_WRAPPER_VERSION=\\\"#{s.version}\\\""
+  }
+
   install_modules_dependencies(s)
 end

package/README.md

@@ -5,42 +5,92 @@ and attribution.
 
 This package is a thin TurboModule bridge over the native
 [`com.booleanmaths:bm-sdk`](https://central.sonatype.com/artifact/com.booleanmaths/bm-sdk)
-Android SDK.
+Android SDK and the
+[`BooleanMathsSDK`](https://cocoapods.org/pods/BooleanMathsSDK) iOS SDK.
 
----
+**One import, one API, both platforms.** There are no platform-specific entry
+points — `import { BooleanMaths } from '@booleanmaths/booleanmaths-rn-sdk'` and
+call the same methods everywhere.
 
-## ⚠️ Platform support
+---
 
-> **There is no BooleanMaths iOS SDK yet.** The native SDK is published for
-> **Android only**. On iOS (and on web) this package installs and builds
-> normally, but **every SDK call is a no-op and no events are tracked**.
+## Platform support
 
 | Platform | Native SDK | Behaviour |
 | :------- | :--------- | :-------- |
-| Android  | ✅ `com.booleanmaths:bm-sdk:1.0.9` | Fully functional |
-| iOS      | ❌ not published | Silent no-op, **never crashes** |
+| Android  | ✅ `com.booleanmaths:bm-sdk:1.0.12` | Fully functional |
+| iOS      | ✅ `BooleanMathsSDK 1.1.0` | Event tracking fully functional — see below |
 | Web      | ❌ not published | Silent no-op, **never crashes** |
 
+### What iOS supports
+
+Event tracking is complete and at parity with Android. Attribution features
+are not — they are deferred to a later release, so their absence is scope
+rather than a bug.
+
+| Feature | Android | iOS |
+| :------ | :-----: | :-: |
+| `initialize()` | ✅ | ✅ |
+| `trackEvent()` with nested properties | ✅ | ✅ |
+| `wrapper_type` / `wrapper_version` on every event | ✅ | ✅ |
+| `isDebug` → `environment` on every event | ✅ | ✅ |
+| `app_info` (package, version, install/update times) on every event | ✅ | ✅ |
+| Automatic `app_opened` | ✅ | ✅ |
+| Automatic `FirstOpen` (once per install) | ✅ | ✅ — but with no attribution payload, see below |
+| Visitor ID and 30-minute session handling | ✅ | ✅ |
+| Durable on-device queue surviving app restarts | ✅ | ✅ |
+| Automatic flush when the app backgrounds | ✅ | ✅ |
+| `getHelloMessage()` bridge smoke test | ✅ | ✅ |
+| **Deep links / universal links** (`DeepLinkClick`) | ✅ | ❌ |
+| **Push-notification attribution** (`NotificationClick`) | ✅ | ❌ |
+| **`handleIntent()` / `handleNotificationIntent()`** | ✅ | ❌ no-op |
+| **Install attribution** on `FirstOpen` | ✅ Play Install Referrer | ❌ `data` is `{}` |
+
+Notes on the iOS gaps:
+
+- **`handleIntent()` is safe to call on iOS.** It reaches a native no-op and
+  logs one dev-mode notice. Shared code does not need to branch on platform.
+- **`FirstOpen` still fires on iOS**, once per install — it just carries no
+  campaign payload. `data` is `{}` (present but empty), so the wire shape will
+  not change when Apple Search Ads attribution lands.
+- On iOS there is **no `DeepLinkClick` or `NotificationClick` event at all**,
+  and consequently no `data.attribution` block on subsequent events.
+- **`flush()` is not exposed to JavaScript** on either platform. The iOS SDK
+  flushes automatically on `willResignActive` / `didBecomeActive`; it will be
+  exposed only once Android has an equivalent, so it can ship as a genuinely
+  cross-platform API.
+- macOS and tvOS are out of scope. The native SDK compiles for them; this
+  wrapper targets iOS only.
+
 ### Why it does not crash
 
-Two independent guards, so a missing iOS SDK can never take your app down:
+Two independent guards, so an unsupported platform or an incomplete native
+install can never take your app down:
 
 1. **JavaScript gate.** `BooleanMaths` checks `Platform.OS` against an
-   allowlist (currently `['android']`) and returns before touching the native
+   allowlist (`['android', 'ios']`) and returns before touching the native
    bridge. It also verifies the TurboModule actually resolved, which covers a
-   broken or incomplete native install.
-2. **Native backstop.** iOS still ships a real TurboModule
-   ([`ios/BooleanmathsRnSdk.mm`](ios/BooleanmathsRnSdk.mm)) whose methods are
-   no-ops. So even a direct call into the bridge is harmless.
+   broken or incomplete native install — most often a JS install without a
+   native rebuild.
+2. **Native backstop.** Every native call is wrapped so failures are logged
+   rather than thrown into JavaScript
+   ([`safely()`](android/src/main/java/com/booleanmathsrnsdk/BooleanmathsRnSdkModule.kt)
+   on Android, `BMSafely()` in
+   [`ios/BooleanmathsRnSdk.mm`](ios/BooleanmathsRnSdk.mm)). Analytics should
+   never crash the host app.
+
+On web the JavaScript gate is the whole story: a separate no-op implementation
+([`src/BooleanMaths.tsx`](src/BooleanMaths.tsx)) is resolved by the bundler, so
+shared code can call the SDK unconditionally without platform checks.
 
 In development (`__DEV__`) you get **one** console warning per app launch, not
 one per call.
 
-### The fix: gate your own analytics code
+### Optionally gate your own analytics code
 
 Calling the SDK unconditionally is safe — you do not *need* to branch. But if
-you want to avoid dead work, skip the dev warning, or show different UI, branch
-on `isSupported`:
+you want to avoid dead work on web, skip the dev warning, or show different UI,
+branch on `isSupported`:
 
 ```ts
 import { BooleanMaths } from '@booleanmaths/booleanmaths-rn-sdk';
@@ -48,21 +98,12 @@ import { BooleanMaths } from '@booleanmaths/booleanmaths-rn-sdk';
 if (BooleanMaths.isSupported) {
   BooleanMaths.initialize(API_KEY, PIXEL_ID);
 } else {
-  // Fall back to another analytics provider on iOS, or do nothing.
+  // Web, or a native install that needs rebuilding. Fall back or do nothing.
 }
 ```
 
-`isSupported` is a plain boolean, evaluated at module load — cheap to read as
-often as you like.
-
-### When the iOS SDK ships
-
-Two changes, no API break for consumers:
-
-1. Add the iOS dependency to [`BooleanmathsRnSdk.podspec`](BooleanmathsRnSdk.podspec)
-   and implement the method bodies in [`ios/BooleanmathsRnSdk.mm`](ios/BooleanmathsRnSdk.mm).
-2. Add `'ios'` to `SUPPORTED_PLATFORMS` in
-   [`src/BooleanMaths.native.tsx`](src/BooleanMaths.native.tsx).
+`isSupported` is `true` on Android and iOS. It is a plain boolean, evaluated at
+module load — cheap to read as often as you like.
 
 ---
 
@@ -78,14 +119,17 @@ Then rebuild the native app — a Metro reload is **not** enough:
 
 ```sh
 npx react-native run-android
+# and/or
+cd ios && pod install && cd .. && npx react-native run-ios
 ```
 
 ### Requirements
 
 - React Native **0.80+** with the **New Architecture** enabled (this is a
   TurboModule)
-- Android **minSdkVersion 24** or higher (the native SDK requires it)
-- `compileSdkVersion 36`, Java 17
+- **Android:** `minSdkVersion` 24 or higher (the native SDK requires it),
+  `compileSdkVersion 36`, Java 17
+- **iOS:** deployment target **15.1** or higher, and **Xcode 16+**
 
 ### Android
 
@@ -98,20 +142,44 @@ To pin a different native SDK version, set this in your app's **root**
 ```gradle
 buildscript {
     ext {
-        BooleanmathsRnSdk_bmSdkVersion = "1.0.9"
+        BooleanmathsRnSdk_bmSdkVersion = "1.0.12"
     }
 }
 ```
 
+> ⚠️ **1.0.10 is the floor.** The wrapper calls
+> `BooleanMathsSDK.initialize(context, apiKey, pixelId, isDebug)`, and the
+> four-argument overload only exists from 1.0.10. Pinning anything older fails
+> the Kotlin compile with an unresolved-overload error rather than degrading at
+> runtime.
+
 ### iOS
 
-Run `pod install` as usual. This installs the no-op stub described above — it
-compiles and links, it just does not track anything.
+Autolinking picks the module up; run `pod install` to pull in the native SDK.
 
 ```sh
 cd ios && pod install
 ```
 
+That resolves `BooleanMathsSDK` from CocoaPods Trunk. Points worth knowing:
+
+- **Minimum deployment target is iOS 15.1**, matching React Native's own floor,
+  so adopting this SDK does not raise your app's minimum iOS version.
+- **The pod is constrained to `~> 1.1`** — that is, `>= 1.1, < 2.0`. The floor
+  matters: version 1.0.0 is still published with an iOS 17.0 floor, and
+  resolving to it would break the install for apps below iOS 17. Confirm your
+  `Podfile.lock` shows `BooleanMathsSDK (1.1.0)` or newer.
+- **The SDK ships as a closed-source, vendored *dynamic* XCFramework.**
+  CocoaPods embeds and re-signs it with your app's identity. If you use
+  `use_frameworks!`, both `:linkage => :static` and `:linkage => :dynamic`
+  are supported.
+- **No privacy manifest work needed.** The SDK bundles its own
+  `PrivacyInfo.xcprivacy` inside the XCFramework, so App Store
+  privacy-manifest requirements are covered by the pod.
+- **Xcode 16+ is required.** The SDK's `.swiftinterface` is emitted at Swift 6.
+  Library evolution is enabled, so it is not pinned to the exact Xcode that
+  built it — but the toolchain must understand Swift 6.
+
 ---
 
 ## Usage
@@ -122,6 +190,9 @@ import { BooleanMaths } from '@booleanmaths/booleanmaths-rn-sdk';
 // Once, as early as possible — typically in your root component.
 BooleanMaths.initialize('YOUR_API_KEY', 'YOUR_PIXEL_ID');
 
+// Or, to mark this build's events as development rather than production:
+BooleanMaths.initialize('YOUR_API_KEY', 'YOUR_PIXEL_ID', __DEV__);
+
 // Anywhere afterwards.
 BooleanMaths.trackEvent('purchase', {
   orderId: 'ORD-1024',
@@ -144,11 +215,51 @@ ignored.
 
 ## API
 
-### `BooleanMaths.initialize(apiKey, pixelId): void`
+### `BooleanMaths.initialize(apiKey, pixelId, isDebug?): void`
+
+Initializes the native SDK. Also registers this wrapper with the native SDK
+**before** initializing, so that even the automatic `FirstOpen` and `app_opened`
+events emitted during initialization already carry
+`wrapper_type: "react-native"` and the wrapper version. That version is read
+from `package.json` on both platforms, so it cannot drift from the published npm
+version.
+
+On Android it additionally forwards the launch intent (see
+[Deep links](#deep-links-and-notification-attribution)); there is no iOS
+equivalent.
+
+`isDebug` defaults to `false`. See [Debug mode](#debug-mode) below.
+
+### Debug mode
+
+Passing `isDebug: true` does two things on both platforms:
+
+1. **Every event this process tracks is stamped `environment: "development"`**
+   instead of `"production"`, in the `setup` block of the request payload.
+2. **The native SDK's verbose logging is switched on.** Warnings and errors —
+   "SDK is already initialized", network failures, malformed intents — are
+   logged *regardless* of this flag, so a broken integration is still
+   diagnosable in a production build. Only the routine per-event chatter
+   ("Persisted event", "Sending payload") is gated.
+
+The flag is recorded **per event, when the event is queued** — not when the
+queue is flushed. An event written by a debug build therefore stays marked as
+development even if it only reaches the network later, after an app restart.
+Both platforms migrated their local queue schemas for this (Room v6 → v7 on
+Android, SQLite v1 → v2 on iOS); the migration is automatic and no events are
+lost.
 
-Initializes the native SDK. Also registers this wrapper with the native SDK so
-every event carries `wrapper_type: "react-native"` and the wrapper version, and
-forwards the launch intent (see [Deep links](#deep-links-and-notification-attribution)).
+The wrapper deliberately **does not** default this to `__DEV__`. Which
+environment events land in is a backend-routing decision, not a bundler one —
+release builds pointed at a development pixel are a normal QA setup. Pass
+`__DEV__` yourself if that is the behaviour you want:
+
+```ts
+BooleanMaths.initialize(API_KEY, PIXEL_ID, __DEV__);
+```
+
+Requires native SDK `bm-sdk` **1.0.10+** on Android and `BooleanMathsSDK`
+**1.1.0+** on iOS; both are the versions this wrapper depends on.
 
 ### `BooleanMaths.trackEvent(name, properties?): void`
 
@@ -157,14 +268,19 @@ numbers, booleans, nested objects, and arrays.
 
 ### `BooleanMaths.handleIntent(): void`
 
-**Android only** (no-op elsewhere). Forwards the current Activity's intent to
-the native SDK so ad deep links, app links and push-notification campaign data
-are attributed. Safe to call repeatedly — the native SDK de-duplicates intents
-it has already seen.
+**Android only.** Forwards the current Activity's intent to the native SDK so
+ad deep links, app links and push-notification campaign data are attributed.
+Safe to call repeatedly — the native SDK de-duplicates intents it has already
+seen.
 
 This is the single entry point for every kind of launch intent; native SDK
 1.0.9 unified them behind one method.
 
+**A no-op on iOS**, and safe to call there — it logs one dev-mode notice and
+returns. The reason is scope, not platform support: intents are an Android
+concept, and iOS deep links / universal links are deferred to a later release.
+You do not need to branch on platform before calling it.
+
 ### `BooleanMaths.handleNotificationIntent(): void`
 
 Deprecated alias of `handleIntent()`, kept so existing callers keep working.
@@ -174,16 +290,26 @@ behavioural difference — prefer `handleIntent()` in new code.
 ### `BooleanMaths.getHelloMessage(): string | null`
 
 Bridge smoke test. Returns the native SDK's hello string, or `null` where there
-is no native SDK.
+is no native SDK. The string comes from the native SDK itself on both platforms
+(not from this wrapper), so a correct value also proves the native artifact
+actually linked — which on iOS is the quickest way to confirm the XCFramework
+was embedded.
 
 ### `BooleanMaths.isSupported: boolean`
 
-`true` only where a real native SDK is linked. Currently Android only.
+`true` only where a real native SDK is linked — Android and iOS. `false` on
+web, and on any platform where the native module failed to resolve (typically a
+JS install without a native rebuild).
 
 ---
 
 ## Deep links and notification attribution
 
+> **Android only.** This entire section does not apply to iOS, where
+> `handleIntent()` is a no-op and no `DeepLinkClick` / `NotificationClick`
+> events are produced. The code below is still safe to run unchanged on iOS —
+> the calls simply do nothing.
+
 The native SDK registers its `ActivityLifecycleCallbacks` **inside**
 `initialize()`. In a React Native app that runs long after `MainActivity`'s
 `onActivityCreated` has already fired, so **the intent that cold-started your
@@ -277,19 +403,27 @@ intent without `ACTION_VIEW` takes the `NotificationClick` path instead — see
 
 The native SDK tracks these without any call from you:
 
-| Event | When |
-| :---- | :--- |
-| `app_opened` | First Activity creation / SDK initialization |
-| `FirstOpen` | Once per install, with Google Play Install Referrer attribution |
-| `DeepLinkClick` | An `ACTION_VIEW` intent is handled — ad deep links and app links. Campaign fields nest under `data.link` |
-| `NotificationClick` | Any other intent carrying campaign data is handled. Fields nest under `data.notification` |
+| Event | When | Android | iOS |
+| :---- | :--- | :-----: | :-: |
+| `app_opened` | First Activity creation / SDK initialization | ✅ | ✅ |
+| `FirstOpen` | Once per install | ✅ with Google Play Install Referrer attribution | ✅ but `data` is `{}` |
+| `DeepLinkClick` | An `ACTION_VIEW` intent is handled — ad deep links and app links. Campaign fields nest under `data.link` | ✅ | ❌ |
+| `NotificationClick` | Any other intent carrying campaign data is handled. Fields nest under `data.notification` | ✅ | ❌ |
+
+On both platforms `FirstOpen` precedes `app_opened`, so a new install's stream
+reads in order. `FirstOpen` is PascalCase on the wire on purpose — the two
+platforms match byte-for-byte and backend install reporting keys off that exact
+string.
 
 Visitor ID and session ID (30-minute timeout) are generated and persisted
-natively. Campaign data from a handled intent is also persisted by
-`AttributionManager` and attached to **every subsequent event** as
-`data.attribution` — natively, so `trackEvent` needs no extra work from you.
+natively on both platforms.
+
+**Attribution is Android-only.** Campaign data from a handled intent is
+persisted by `AttributionManager` and attached to **every subsequent event** as
+`data.attribution`. iOS produces no `data.attribution` block, since it handles
+no intents; Apple Search Ads attribution is deferred to a later release.
 
-### What counts as a campaign intent (native SDK v1.0.9)
+### What counts as a campaign intent (native SDK v1.0.12)
 
 `handleIntent` ignores an intent when **all** of these hold, which is what a
 plain launcher tap looks like:
@@ -320,7 +454,34 @@ de-duplicated in a `WeakHashMap`, so re-forwarding the same intent is a no-op.
 
 ## How properties cross the bridge
 
-Two normalizations happen on the Android side, both worth knowing:
+Each platform normalizes `properties` at the native boundary before handing it
+to the SDK. The rules differ because the two SDKs serialize differently — the
+observable payload is the same in the cases that matter.
+
+| Input | Android | iOS |
+| :---- | :------ | :-- |
+| `null` / `undefined` object value | Key dropped | Key dropped |
+| `null` inside an array | Preserved (indices must not shift) | Preserved |
+| Nested objects and arrays | Recursed | Recursed |
+| Whole numbers (`3`) | Coerced to integer — see the Gson caveat below | No action needed; `JSONSerialization` already emits `3`, not `3.0` |
+| Fractions (`999.5`) | Untouched | Untouched |
+| Booleans | Untouched | Untouched |
+| **`NaN` / `Infinity`** | Passed through as-is | **Key dropped** — see below |
+
+### iOS: why `NaN` is dropped rather than passed through
+
+This one is load-bearing, not cosmetic. The iOS SDK guards its writes with
+`JSONSerialization.isValidJSONObject(...)` and **silently discards the payload**
+when that returns false. A JS `NaN` or `Infinity` arrives as a non-finite
+`NSNumber` and invalidates the whole object — so a single bad property value
+could discard the event, or the entire outgoing batch. The wrapper strips those
+keys at the boundary so the rest of the event survives.
+
+`NSDate` and anything else not JSON-representable is dropped for the same
+reason. Everything is handled recursively, so a `NaN` nested three objects deep
+costs you that one key and nothing else.
+
+### Android normalization
 
 - **Integral numbers are converted to integers.** React Native passes every JS
   number across the bridge as a `Double`, so `{ count: 3 }` would otherwise be
@@ -332,7 +493,7 @@ Two normalizations happen on the Android side, both worth knowing:
   { "value": 2499, "items": [{ "quantity": 2, "price": 999.5 }] }
   ```
 
-  > ⚠️ **Known native SDK limitation (still present in v1.0.9).** The integers do *not* survive
+  > ⚠️ **Known native SDK limitation (still present in v1.0.12).** The integers do *not* survive
   > to the wire. `EventDispatcher` re-reads the stored payload with
   > `gson.fromJson(properties, Map::class.java)`, and Gson coerces every number
   > in a raw `Map` to `Double` — so the request body ends up with `2499.0` and
@@ -346,28 +507,50 @@ Two normalizations happen on the Android side, both worth knowing:
   serializes with Gson, which omits null map values anyway, so the emitted JSON
   is identical. Nulls **inside arrays** are preserved so indices do not shift.
 
-Failures in the native bridge are logged (`adb logcat -s BooleanmathsRnSdk`)
-rather than thrown into JavaScript — analytics should never crash the host app.
+Failures in the native bridge are logged rather than thrown into JavaScript —
+analytics should never crash the host app. Android logs to
+`adb logcat -s BooleanmathsRnSdk`; iOS logs through `RCTLogError`, visible in
+Xcode's console and Metro.
 
 ---
 
 ## Troubleshooting
 
 **No events arriving.** Confirm `BooleanMaths.isSupported` is `true`, then check
-`adb logcat -s BooleanMathsSDK:D BooleanmathsRnSdk:D`. The native SDK logs each
-persisted event and the full payload it sends.
+the native logs — `adb logcat -s BooleanMathsSDK:D BooleanmathsRnSdk:D` on
+Android, or Xcode's console on iOS. The native SDK logs each persisted event and
+the full payload it sends.
 
 **Warning: "native module could not be found".** The JS installed but the native
-side did not. Rebuild the app (`npx react-native run-android`) rather than just
-reloading Metro; on iOS run `pod install`.
-
-**Events show a delay.** By design. Each `trackEvent` enqueues an immediate
-sync attempt, but WorkManager also runs a periodic 15-minute batch job and
-requires network connectivity.
-
-**Deep link not attributed.** See
-[Deep links](#deep-links-and-notification-attribution) — the launch intent needs
-explicit forwarding, and `singleTask` activities need `setIntent`.
+side did not. Rebuild the app (`npx react-native run-android`, or `pod install`
+followed by `npx react-native run-ios`) rather than just reloading Metro.
+
+**iOS: crash at launch with a dyld "Library not loaded" / "image not found"
+error naming `BooleanMathsSDK`.** The XCFramework is a *dynamic* framework and
+was not embedded. Confirm the `[CP] Embed Pods Frameworks` build phase exists on
+your app target, then `pod deintegrate && pod install`. This is the one iOS
+failure mode that builds cleanly and only shows up at runtime.
+
+**iOS: `getHelloMessage()` returns an empty string.** The bridge resolved but the
+native SDK call failed — check the Xcode console for a
+`BooleanMaths getHelloMessage failed` error. An empty string here specifically
+means the XCFramework did not link correctly.
+
+**iOS: `pod install` fails to resolve `BooleanMathsSDK`.** Run
+`pod repo update`, and confirm your app's deployment target is 15.1 or higher.
+If the lockfile pinned `1.0.0`, delete that entry and reinstall — 1.0.0 carries
+an iOS 17.0 floor.
+
+**Events show a delay.** By design on both platforms. Each `trackEvent`
+enqueues an immediate sync attempt; Android's WorkManager also runs a periodic
+15-minute batch job and requires network connectivity, and iOS flushes when the
+app backgrounds.
+
+**Deep link not attributed.** Android only — see
+[Deep links](#deep-links-and-notification-attribution); the launch intent needs
+explicit forwarding, and `singleTask` activities need `setIntent`. On iOS deep
+link attribution is not implemented at all
+([what iOS supports](#what-ios-supports)).
 
 ---
 

package/android/build.gradle

@@ -6,7 +6,7 @@ buildscript {
     // Version of the native Android SDK (com.booleanmaths:bm-sdk) this wrapper
     // is built against. Override with `ext.BooleanmathsRnSdk_bmSdkVersion` in
     // your app's root build.gradle to pin a different one.
-    bmSdkVersion: "1.0.9"
+    bmSdkVersion: "1.0.12"
   ]
 
   ext.getExtOrDefault = { prop ->

package/android/src/main/java/com/booleanmathsrnsdk/BooleanmathsRnSdkModule.kt

@@ -8,17 +8,22 @@ import com.facebook.react.bridge.ReadableMap
 class BooleanmathsRnSdkModule(reactContext: ReactApplicationContext) :
   NativeBooleanmathsRnSdkSpec(reactContext) {
 
-  override fun initializeSdk(apiKey: String, pixelId: String) {
+  override fun initializeSdk(apiKey: String, pixelId: String, isDebug: Boolean) {
     safely("initialize") {
       // Stamp the wrapper identity *before* initialize() so the automatic
       // `app_opened` and `FirstOpen` events that the native SDK tracks during
       // initialization already carry wrapper_type / wrapper_version.
       applyWrapperConfig()
 
+      // `isDebug` is passed explicitly rather than left to the native default:
+      // it decides the `environment` field ("development" / "production") that
+      // every event carries, and it gates the native SDK's verbose logging.
+      // The JS wrapper always supplies it, defaulting to false.
       BooleanMathsSDK.initialize(
         reactApplicationContext.applicationContext,
         apiKey,
-        pixelId
+        pixelId,
+        isDebug
       )
 
       // ...and again afterwards, because the native SDK can only persist the

package/ios/BMBooleanMathsBridge.swift

@@ -0,0 +1,151 @@
+import Foundation
+import BooleanMathsSDK
+
+/// Objective-C-visible shim over the pure Swift `BooleanMathsSDK`.
+///
+/// This file is mandatory, not a stylistic layer. `BooleanMaths` is declared
+/// `@MainActor public final class` — it is not `@objc` and not `NSObject`-derived
+/// (and cannot trivially become `@objc`, which requires `NSObject` inheritance).
+/// The SDK's generated `BooleanMathsSDK-Swift.h` therefore contains zero
+/// `@interface` declarations, so `#import <BooleanMathsSDK/...>` from
+/// `BooleanmathsRnSdk.mm` resolves to an empty module and the TurboModule cannot
+/// see the SDK at all.
+///
+/// Everything here takes only Objective-C-representable types and is reached
+/// from the `.mm` through the pod's generated `BooleanmathsRnSdk-Swift.h`.
+///
+/// Behaviour is specified by the Android module
+/// (`android/src/main/java/com/booleanmathsrnsdk/BooleanmathsRnSdkModule.kt`),
+/// which is the reference implementation for this wrapper.
+@objc(BMBooleanMathsBridge)
+public final class BMBooleanMathsBridge: NSObject {
+
+  /// Matches Android's `BuildConfig.WRAPPER_TYPE`.
+  private static let wrapperType = "react-native"
+
+  // MARK: - Public API
+
+  /// Initializes the native SDK and stamps this wrapper's identity onto it.
+  ///
+  /// `@MainActor` because `BooleanMaths.initialize` is main-actor isolated. The
+  /// caller in `BooleanmathsRnSdk.mm` hops with `dispatch_async` before invoking
+  /// this — never `dispatch_sync`, which deadlocks when the JS thread is the
+  /// main thread.
+  ///
+  /// Named `initializeSdk` rather than `initialize` for the same reason the
+  /// codegen spec is: `+[NSObject initialize]` already exists.
+  @MainActor
+  @objc(initializeSdkWithApiKey:pixelId:isDebug:wrapperVersion:)
+  public static func initializeSdk(
+    apiKey: String,
+    pixelId: String,
+    isDebug: Bool,
+    wrapperVersion: String
+  ) {
+    // Before `initialize`, not after: `initialize` itself emits `FirstOpen` and
+    // `app_opened` internally, and those must already carry wrapper_type /
+    // wrapper_version. Same ordering rationale as Android.
+    //
+    // Do NOT port Android's second, post-initialize call. Android needs it
+    // because its native SDK can only persist to SharedPreferences once it holds
+    // an application context, which it acquires inside initialize(). iOS has no
+    // such gap: `WrapperConfigStore.set` writes to UserDefaults unconditionally,
+    // and `initialize` calls `rehydrate()`, which fills each field only where it
+    // is still nil — so a value set earlier in the process outranks the
+    // persisted one. One call, before initialize, is correct and sufficient.
+    BooleanMaths.shared.setWrapperConfig(type: wrapperType, version: wrapperVersion)
+
+    // `isDebug` is passed explicitly rather than left to the SDK's default: it
+    // decides the `environment` field ("development" / "production") stamped on
+    // every event, and it gates the SDK's verbose logging. The JS wrapper always
+    // supplies it, defaulting to false. Same contract as Android.
+    BooleanMaths.shared.initialize(apiKey: apiKey, pixelId: pixelId, isDebug: isDebug)
+
+    // There is no iOS equivalent of Android's forwardCurrentIntent(): deep links
+    // are deferred on iOS, so nothing is forwarded here. See `handleIntent` in
+    // BooleanmathsRnSdk.mm.
+  }
+
+  /// Records a custom event. `properties` is sanitized first — see
+  /// `sanitized(value:allowNull:)` for why that is load-bearing.
+  ///
+  /// `@MainActor` because `BooleanMaths.track` is main-actor isolated.
+  @MainActor
+  @objc(trackEventWithName:properties:)
+  public static func trackEvent(name: String, properties: [String: Any]?) {
+    BooleanMaths.shared.track(name, properties: sanitized(dictionary: properties ?? [:]))
+  }
+
+  /// Bridge smoke test. Deliberately not main-actor isolated: the TurboModule
+  /// method is synchronous and returns the value directly, so it must not hop
+  /// threads. `BooleanMaths.getHelloMessage()` is `nonisolated static` in the SDK
+  /// specifically to allow this.
+  ///
+  /// A real SDK call rather than a wrapper-side literal, so it also proves the
+  /// XCFramework actually linked.
+  @objc(getHelloMessage)
+  public static func getHelloMessage() -> String {
+    BooleanMaths.getHelloMessage()
+  }
+
+  // MARK: - Properties sanitization
+
+  // `EventDispatcher` and `EventStore` both guard on
+  // `JSONSerialization.isValidJSONObject(...)` and silently drop the payload when
+  // it returns false. A JS `NaN` or `Infinity` arrives here as a non-finite
+  // NSNumber and makes the whole object invalid — so one bad property value can
+  // discard the event, or the entire outgoing batch. Android guards the same case
+  // in `normalizeValue`.
+
+  private static func sanitized(dictionary: [String: Any]) -> [String: Any] {
+    var result = [String: Any](minimumCapacity: dictionary.count)
+
+    for (key, value) in dictionary {
+      guard let clean = sanitized(value: value, allowNull: false) else { continue }
+      result[key] = clean
+    }
+
+    return result
+  }
+
+  /// Nulls are preserved inside arrays — dropping them would shift indices.
+  /// Android preserves them deliberately for the same reason.
+  private static func sanitized(array: [Any]) -> [Any] {
+    array.map { sanitized(value: $0, allowNull: true) ?? NSNull() }
+  }
+
+  private static func sanitized(value: Any, allowNull: Bool) -> Any? {
+    switch value {
+    case is NSNull:
+      // Dropped as an object value (matching Android, whose Gson omits null map
+      // values anyway), kept inside an array.
+      return allowNull ? NSNull() : nil
+
+    case let number as NSNumber:
+      // Must be tested before any `as Bool` cast: `NSNumber(1) as? Bool`
+      // succeeds under Swift bridging, so checking Bool first would silently
+      // turn `{ count: 1 }` into `{ count: true }`. Booleans arrive from React
+      // Native as CFBoolean, match here, and serialize as true/false unchanged.
+      //
+      // No whole-number coercion: Android's `toWholeNumberOrSelf` fixes a
+      // Gson-specific artifact, whereas JSONSerialization already emits `3`
+      // rather than `3.0`.
+      return number.doubleValue.isFinite ? number : nil
+
+    case let string as String:
+      return string
+
+    case let nested as [String: Any]:
+      return sanitized(dictionary: nested)
+
+    case let nested as [Any]:
+      return sanitized(array: nested)
+
+    default:
+      // NSDate and anything else not JSON-representable, plus dictionaries with
+      // non-String keys. React Native never produces these from a JS object, but
+      // passing one through would invalidate the payload.
+      return nil
+    }
+  }
+}

package/ios/BooleanmathsRnSdk.h

@@ -1,19 +1,20 @@
 #import <BooleanmathsRnSdkSpec/BooleanmathsRnSdkSpec.h>
 
 /**
- * iOS no-op implementation of the BooleanMaths SDK.
+ * iOS implementation of the BooleanMaths TurboModule, backed by the
+ * `BooleanMathsSDK` pod (>= 1.0.1, minimum iOS 15.1).
  *
- * There is no native BooleanMaths iOS SDK published yet (the native SDK ships
- * for Android only, as `com.booleanmaths:bm-sdk`). This class exists so that
- * the TurboModule still resolves on iOS and every call degrades into a
- * harmless no-op instead of crashing the host app.
+ * The SDK itself is pure Swift and exposes no Objective-C surface, so this class
+ * does not talk to it directly — every call goes through
+ * `BMBooleanMathsBridge` (`ios/BMBooleanMathsBridge.swift`), which explains why
+ * in detail.
  *
- * In practice these methods are never reached: the JavaScript layer gates on
- * `Platform.OS` and returns before touching the bridge. They are implemented
- * anyway as a backstop.
+ * `initializeSdk` and `trackEvent` hop to the main queue because the SDK is
+ * `@MainActor`; `getHelloMessage` deliberately does not, being synchronous and
+ * value-returning. Failures are logged and swallowed rather than thrown into JS.
  *
- * When an iOS SDK becomes available, replace the bodies below and flip
- * `SUPPORTED_PLATFORMS` in `src/BooleanMaths.native.tsx` to include 'ios'.
+ * `handleIntent` and `handleNotificationIntent` remain no-ops: intents are an
+ * Android concept and iOS deep links are out of scope for this release.
  */
 @interface BooleanmathsRnSdk : NSObject <NativeBooleanmathsRnSdkSpec>
 

package/ios/BooleanmathsRnSdk.mm

@@ -2,50 +2,105 @@
 
 #import <React/RCTLog.h>
 
+// The generated header for BMBooleanMathsBridge.swift. Both paths are needed so
+// this builds under static and dynamic pod linkage alike.
+#if __has_include(<BooleanmathsRnSdk/BooleanmathsRnSdk-Swift.h>)
+#import <BooleanmathsRnSdk/BooleanmathsRnSdk-Swift.h>
+#else
+#import "BooleanmathsRnSdk-Swift.h"
+#endif
+
+// Injected by BooleanmathsRnSdk.podspec from package.json's version, mirroring
+// Android's BuildConfig.WRAPPER_VERSION. Only reached if that xcconfig failed to
+// apply, in which case a wrong-looking wrapper_version is far better than a
+// build error in a consumer's app.
+#ifndef BMRN_WRAPPER_VERSION
+#define BMRN_WRAPPER_VERSION "unknown"
+#endif
+
 @implementation BooleanmathsRnSdk
 
 /**
- * Logs the "no iOS SDK" warning at most once per app launch so it is visible
- * without flooding the console if something does call through.
+ * Analytics must never take the host app down. Mirrors Android's `safely()`
+ * helper: log the failure and swallow it rather than surfacing it to JS.
+ */
+static void BMSafely(NSString *operation, void (^block)(void))
+{
+  @try {
+    block();
+  } @catch (NSException *exception) {
+    RCTLogError(@"[@booleanmaths/booleanmaths-rn-sdk] BooleanMaths %@ failed: %@", operation, exception);
+  }
+}
+
+/**
+ * Logs the "deep links are Android-only" notice at most once per app launch, so
+ * it is visible without flooding the console.
  */
-static void BMWarnUnsupportedOnce(void)
+static void BMWarnIntentUnsupportedOnce(void)
 {
   static dispatch_once_t onceToken;
   dispatch_once(&onceToken, ^{
-    RCTLogWarn(@"[@booleanmaths/booleanmaths-rn-sdk] The BooleanMaths native SDK is not available on iOS "
-               @"(Android only for now). All SDK calls are no-ops and no events will be "
-               @"tracked on this platform.");
+    RCTLogWarn(@"[@booleanmaths/booleanmaths-rn-sdk] Deep-link and notification intent forwarding is "
+               @"Android-only; handleIntent() is a no-op on iOS. Event tracking is fully supported — "
+               @"only intent attribution is unavailable.");
   });
 }
 
-- (void)initializeSdk:(NSString *)apiKey pixelId:(NSString *)pixelId
+- (void)initializeSdk:(NSString *)apiKey pixelId:(NSString *)pixelId isDebug:(BOOL)isDebug
 {
-  BMWarnUnsupportedOnce();
+  // Captured outside the block: it is a compile-time constant, not thread state.
+  NSString *wrapperVersion = @BMRN_WRAPPER_VERSION;
+
+  // BooleanMaths is @MainActor. dispatch_async, never dispatch_sync — the latter
+  // deadlocks whenever the JS thread is the main thread.
+  dispatch_async(dispatch_get_main_queue(), ^{
+    BMSafely(@"initialize", ^{
+      [BMBooleanMathsBridge initializeSdkWithApiKey:apiKey
+                                            pixelId:pixelId
+                                            isDebug:isDebug
+                                     wrapperVersion:wrapperVersion];
+    });
+  });
 }
 
 - (void)trackEvent:(NSString *)name properties:(NSDictionary *)properties
 {
-  BMWarnUnsupportedOnce();
+  dispatch_async(dispatch_get_main_queue(), ^{
+    BMSafely(@"trackEvent", ^{
+      [BMBooleanMathsBridge trackEventWithName:name properties:properties];
+    });
+  });
 }
 
 - (void)handleIntent
 {
-  // Android-only concept; nothing to do on iOS even once an iOS SDK exists.
-  BMWarnUnsupportedOnce();
+  // Deliberately still a no-op. Intents are an Android concept, and iOS deep
+  // links / universal links are deferred — their absence here is scope, not a
+  // missing implementation.
+  BMWarnIntentUnsupportedOnce();
 }
 
 - (void)handleNotificationIntent
 {
   // Alias of handleIntent, mirroring the Android bridge.
-  BMWarnUnsupportedOnce();
+  BMWarnIntentUnsupportedOnce();
 }
 
 - (NSString *)getHelloMessage
 {
-  BMWarnUnsupportedOnce();
+  // No dispatch: this is synchronous and returns a value, so it must not hop
+  // threads. The SDK's getHelloMessage() is `nonisolated static` to allow it.
+  @try {
+    return [BMBooleanMathsBridge getHelloMessage];
+  } @catch (NSException *exception) {
+    RCTLogError(@"[@booleanmaths/booleanmaths-rn-sdk] BooleanMaths getHelloMessage failed: %@", exception);
 
-  // Deliberately not nil: the codegen spec declares a non-optional string.
-  return @"BooleanMaths SDK is not available on iOS";
+    // Empty rather than a plausible-looking message: this method exists to prove
+    // the native SDK linked, so a failure must read as a failure. The codegen
+    // spec declares a non-optional string, so it cannot be nil.
+    return @"";
+  }
 }
 
 - (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:

package/lib/module/BooleanMaths.js

@@ -17,7 +17,7 @@ function warnOnce() {
 }
 export const BooleanMaths = {
   isSupported: false,
-  initialize(_apiKey, _pixelId) {
+  initialize(_apiKey, _pixelId, _isDebug) {
     warnOnce();
   },
   trackEvent(_name, _properties) {

package/lib/module/BooleanMaths.js.map

@@ -1 +1 @@
-{"version":3,"names":["hasWarned","warnOnce","__DEV__","console","warn","BooleanMaths","isSupported","initialize","_apiKey","_pixelId","trackEvent","_name","_properties","handleIntent","handleNotificationIntent","getHelloMessage"],"sourceRoot":"../../src","sources":["BooleanMaths.tsx"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAIA,SAAS,GAAG,KAAK;AAErB,SAASC,QAAQA,CAAA,EAAG;EAClB,IAAID,SAAS,IAAI,OAAOE,OAAO,KAAK,WAAW,IAAI,CAACA,OAAO,EAAE;IAC3D;EACF;EAEAF,SAAS,GAAG,IAAI;EAEhBG,OAAO,CAACC,IAAI,CACV,sFAAsF,GACpF,2EAA2E,GAC3E,8DACJ,CAAC;AACH;AAEA,OAAO,MAAMC,YAA6B,GAAG;EAC3CC,WAAW,EAAE,KAAK;EAElBC,UAAUA,CAACC,OAAe,EAAEC,QAAgB,EAAQ;IAClDR,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDS,UAAUA,CAACC,KAAa,EAAEC,WAAyC,EAAQ;IACzEX,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDY,YAAYA,CAAA,EAAS;IACnBZ,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDa,wBAAwBA,CAAA,EAAS;IAC/Bb,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDc,eAAeA,CAAA,EAAkB;IAC/Bd,QAAQ,CAAC,CAAC;IACV,OAAO,IAAI;EACb;AACF,CAAC","ignoreList":[]}
+{"version":3,"names":["hasWarned","warnOnce","__DEV__","console","warn","BooleanMaths","isSupported","initialize","_apiKey","_pixelId","_isDebug","trackEvent","_name","_properties","handleIntent","handleNotificationIntent","getHelloMessage"],"sourceRoot":"../../src","sources":["BooleanMaths.tsx"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAIA,SAAS,GAAG,KAAK;AAErB,SAASC,QAAQA,CAAA,EAAG;EAClB,IAAID,SAAS,IAAI,OAAOE,OAAO,KAAK,WAAW,IAAI,CAACA,OAAO,EAAE;IAC3D;EACF;EAEAF,SAAS,GAAG,IAAI;EAEhBG,OAAO,CAACC,IAAI,CACV,sFAAsF,GACpF,2EAA2E,GAC3E,8DACJ,CAAC;AACH;AAEA,OAAO,MAAMC,YAA6B,GAAG;EAC3CC,WAAW,EAAE,KAAK;EAElBC,UAAUA,CAACC,OAAe,EAAEC,QAAgB,EAAEC,QAAkB,EAAQ;IACtET,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDU,UAAUA,CAACC,KAAa,EAAEC,WAAyC,EAAQ;IACzEZ,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDa,YAAYA,CAAA,EAAS;IACnBb,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDc,wBAAwBA,CAAA,EAAS;IAC/Bd,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDe,eAAeA,CAAA,EAAkB;IAC/Bf,QAAQ,CAAC,CAAC;IACV,OAAO,IAAI;EACb;AACF,CAAC","ignoreList":[]}

package/lib/module/BooleanMaths.native.js

@@ -3,11 +3,15 @@
 import { Platform } from 'react-native';
 import NativeBooleanmathsRnSdk from "./NativeBooleanmathsRnSdk.js";
 /**
- * The BooleanMaths native SDK currently ships for Android only. There is no
- * iOS artifact yet, so on iOS every call below short-circuits and the SDK
- * behaves as a silent no-op rather than crashing the app.
+ * The BooleanMaths native SDK ships for Android (`com.booleanmaths:bm-sdk`) and
+ * iOS (`BooleanMathsSDK`). Any other platform — including out-of-tree React
+ * Native targets — has no native artifact, so every call below short-circuits
+ * and the SDK behaves as a silent no-op rather than crashing the app.
+ *
+ * Note that `handleIntent` is a no-op on iOS even though iOS is supported here:
+ * intents are an Android concept. See its JSDoc in `./types`.
  */
-const SUPPORTED_PLATFORMS = ['android'];
+const SUPPORTED_PLATFORMS = ['android', 'ios'];
 const isPlatformSupported = SUPPORTED_PLATFORMS.includes(Platform.OS);
 
 /**
@@ -23,7 +27,7 @@ function warnOnce() {
   }
   hasWarned = true;
   if (!isPlatformSupported) {
-    console.warn(`[@booleanmaths/booleanmaths-rn-sdk] The BooleanMaths native SDK is not available on ${Platform.OS} ` + '(Android only for now). All SDK calls are no-ops on this platform and no ' + 'events will be tracked. Gate your calls on `BooleanMaths.isSupported` to ' + 'silence this warning — see the README\'s "Platform support" section.');
+    console.warn(`[@booleanmaths/booleanmaths-rn-sdk] The BooleanMaths native SDK is not available on ${Platform.OS} ` + '(Android and iOS only). All SDK calls are no-ops on this platform and no ' + 'events will be tracked. Gate your calls on `BooleanMaths.isSupported` to ' + 'silence this warning — see the README\'s "Platform support" section.');
     return;
   }
   console.warn('[@booleanmaths/booleanmaths-rn-sdk] The native module could not be found on ' + `${Platform.OS}. Rebuild the app after installing the package (a Metro ` + 'reload is not enough), and on iOS run `pod install`. All SDK calls are ' + 'no-ops until this is fixed.');
@@ -44,12 +48,16 @@ function forwardCurrentIntent() {
 }
 export const BooleanMaths = {
   isSupported,
-  initialize(apiKey, pixelId) {
+  initialize(apiKey, pixelId, isDebug = false) {
     if (!isSupported) {
       warnOnce();
       return;
     }
-    NativeBooleanmathsRnSdk.initializeSdk(apiKey, pixelId);
+
+    // Coerced rather than passed through: the codegen spec declares a
+    // non-optional boolean, and a truthy non-boolean from untyped JS would
+    // arrive at the native side as a type mismatch rather than a flag.
+    NativeBooleanmathsRnSdk.initializeSdk(apiKey, pixelId, Boolean(isDebug));
   },
   trackEvent(name, properties = {}) {
     if (!isSupported) {

package/lib/module/BooleanMaths.native.js.map

@@ -1 +1 @@
-{"version":3,"names":["Platform","NativeBooleanmathsRnSdk","SUPPORTED_PLATFORMS","isPlatformSupported","includes","OS","isSupported","hasWarned","warnOnce","__DEV__","console","warn","forwardCurrentIntent","handleIntent","BooleanMaths","initialize","apiKey","pixelId","initializeSdk","trackEvent","name","properties","handleNotificationIntent","getHelloMessage"],"sourceRoot":"../../src","sources":["BooleanMaths.native.tsx"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,cAAc;AACvC,OAAOC,uBAAuB,MAAM,8BAA2B;AAG/D;AACA;AACA;AACA;AACA;AACA,MAAMC,mBAAsD,GAAG,CAAC,SAAS,CAAC;AAE1E,MAAMC,mBAAmB,GAAGD,mBAAmB,CAACE,QAAQ,CAACJ,QAAQ,CAACK,EAAE,CAAC;;AAErE;AACA;AACA;AACA;AACA;AACA,MAAMC,WAAW,GAAGH,mBAAmB,IAAIF,uBAAuB,IAAI,IAAI;AAE1E,IAAIM,SAAS,GAAG,KAAK;AAErB,SAASC,QAAQA,CAAA,EAAG;EAClB,IAAID,SAAS,IAAI,CAACE,OAAO,EAAE;IACzB;EACF;EAEAF,SAAS,GAAG,IAAI;EAEhB,IAAI,CAACJ,mBAAmB,EAAE;IACxBO,OAAO,CAACC,IAAI,CACV,uFAAuFX,QAAQ,CAACK,EAAE,GAAG,GACnG,2EAA2E,GAC3E,2EAA2E,GAC3E,sEACJ,CAAC;IACD;EACF;EAEAK,OAAO,CAACC,IAAI,CACV,8EAA8E,GAC5E,GAAGX,QAAQ,CAACK,EAAE,0DAA0D,GACxE,yEAAyE,GACzE,6BACJ,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,SAASO,oBAAoBA,CAAA,EAAS;EACpC,IAAI,CAACN,WAAW,EAAE;IAChBE,QAAQ,CAAC,CAAC;IACV;EACF;EAEAP,uBAAuB,CAAEY,YAAY,CAAC,CAAC;AACzC;AAEA,OAAO,MAAMC,YAA6B,GAAG;EAC3CR,WAAW;EAEXS,UAAUA,CAACC,MAAc,EAAEC,OAAe,EAAQ;IAChD,IAAI,CAACX,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV;IACF;IAEAP,uBAAuB,CAAEiB,aAAa,CAACF,MAAM,EAAEC,OAAO,CAAC;EACzD,CAAC;EAEDE,UAAUA,CAACC,IAAY,EAAEC,UAAuC,GAAG,CAAC,CAAC,EAAQ;IAC3E,IAAI,CAACf,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV;IACF;IAEAP,uBAAuB,CAAEkB,UAAU,CAACC,IAAI,EAAEC,UAAU,CAAC;EACvD,CAAC;EAEDR,YAAY,EAAED,oBAAoB;EAElCU,wBAAwB,EAAEV,oBAAoB;EAE9CW,eAAeA,CAAA,EAAkB;IAC/B,IAAI,CAACjB,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV,OAAO,IAAI;IACb;IAEA,OAAOP,uBAAuB,CAAEsB,eAAe,CAAC,CAAC;EACnD;AACF,CAAC","ignoreList":[]}
+{"version":3,"names":["Platform","NativeBooleanmathsRnSdk","SUPPORTED_PLATFORMS","isPlatformSupported","includes","OS","isSupported","hasWarned","warnOnce","__DEV__","console","warn","forwardCurrentIntent","handleIntent","BooleanMaths","initialize","apiKey","pixelId","isDebug","initializeSdk","Boolean","trackEvent","name","properties","handleNotificationIntent","getHelloMessage"],"sourceRoot":"../../src","sources":["BooleanMaths.native.tsx"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,cAAc;AACvC,OAAOC,uBAAuB,MAAM,8BAA2B;AAG/D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,mBAAsD,GAAG,CAC7D,SAAS,EACT,KAAK,CACN;AAED,MAAMC,mBAAmB,GAAGD,mBAAmB,CAACE,QAAQ,CAACJ,QAAQ,CAACK,EAAE,CAAC;;AAErE;AACA;AACA;AACA;AACA;AACA,MAAMC,WAAW,GAAGH,mBAAmB,IAAIF,uBAAuB,IAAI,IAAI;AAE1E,IAAIM,SAAS,GAAG,KAAK;AAErB,SAASC,QAAQA,CAAA,EAAG;EAClB,IAAID,SAAS,IAAI,CAACE,OAAO,EAAE;IACzB;EACF;EAEAF,SAAS,GAAG,IAAI;EAEhB,IAAI,CAACJ,mBAAmB,EAAE;IACxBO,OAAO,CAACC,IAAI,CACV,uFAAuFX,QAAQ,CAACK,EAAE,GAAG,GACnG,2EAA2E,GAC3E,2EAA2E,GAC3E,sEACJ,CAAC;IACD;EACF;EAEAK,OAAO,CAACC,IAAI,CACV,8EAA8E,GAC5E,GAAGX,QAAQ,CAACK,EAAE,0DAA0D,GACxE,yEAAyE,GACzE,6BACJ,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,SAASO,oBAAoBA,CAAA,EAAS;EACpC,IAAI,CAACN,WAAW,EAAE;IAChBE,QAAQ,CAAC,CAAC;IACV;EACF;EAEAP,uBAAuB,CAAEY,YAAY,CAAC,CAAC;AACzC;AAEA,OAAO,MAAMC,YAA6B,GAAG;EAC3CR,WAAW;EAEXS,UAAUA,CAACC,MAAc,EAAEC,OAAe,EAAEC,OAAgB,GAAG,KAAK,EAAQ;IAC1E,IAAI,CAACZ,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV;IACF;;IAEA;IACA;IACA;IACAP,uBAAuB,CAAEkB,aAAa,CAACH,MAAM,EAAEC,OAAO,EAAEG,OAAO,CAACF,OAAO,CAAC,CAAC;EAC3E,CAAC;EAEDG,UAAUA,CAACC,IAAY,EAAEC,UAAuC,GAAG,CAAC,CAAC,EAAQ;IAC3E,IAAI,CAACjB,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV;IACF;IAEAP,uBAAuB,CAAEoB,UAAU,CAACC,IAAI,EAAEC,UAAU,CAAC;EACvD,CAAC;EAEDV,YAAY,EAAED,oBAAoB;EAElCY,wBAAwB,EAAEZ,oBAAoB;EAE9Ca,eAAeA,CAAA,EAAkB;IAC/B,IAAI,CAACnB,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV,OAAO,IAAI;IACb;IAEA,OAAOP,uBAAuB,CAAEwB,eAAe,CAAC,CAAC;EACnD;AACF,CAAC","ignoreList":[]}

package/lib/module/NativeBooleanmathsRnSdk.js.map

@@ -1 +1 @@
-{"version":3,"names":["TurboModuleRegistry","get"],"sourceRoot":"../../src","sources":["NativeBooleanmathsRnSdk.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAA0B,cAAc;AAsBpE;AACA;AACA;AACA;AACA,eAAeA,mBAAmB,CAACC,GAAG,CAAO,mBAAmB,CAAC","ignoreList":[]}
+{"version":3,"names":["TurboModuleRegistry","get"],"sourceRoot":"../../src","sources":["NativeBooleanmathsRnSdk.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAA0B,cAAc;AA2BpE;AACA;AACA;AACA;AACA,eAAeA,mBAAmB,CAACC,GAAG,CAAO,mBAAmB,CAAC","ignoreList":[]}

package/lib/typescript/src/BooleanMaths.native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BooleanMaths.native.d.ts","sourceRoot":"","sources":["../../../src/BooleanMaths.native.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAA+B,MAAM,YAAS,CAAC;AA4D5E,eAAO,MAAM,YAAY,EAAE,eAiC1B,CAAC"}
+{"version":3,"file":"BooleanMaths.native.d.ts","sourceRoot":"","sources":["../../../src/BooleanMaths.native.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAA+B,MAAM,YAAS,CAAC;AAmE5E,eAAO,MAAM,YAAY,EAAE,eAoC1B,CAAC"}

package/lib/typescript/src/NativeBooleanmathsRnSdk.d.ts

@@ -5,8 +5,13 @@ export interface Spec extends TurboModule {
      * already taken by `NativeModule.initialize()` on Android and by
      * `+[NSObject initialize]` on iOS. The public JS API exposes this as
      * `BooleanMaths.initialize()`.
+     *
+     * `isDebug` is required here even though it is optional on the public API —
+     * codegen has no notion of a default, so `BooleanMaths.initialize` always
+     * passes an explicit boolean. Same arrangement as `trackEvent`'s
+     * `properties`.
      */
-    initializeSdk(apiKey: string, pixelId: string): void;
+    initializeSdk(apiKey: string, pixelId: string, isDebug: boolean): void;
     trackEvent(name: string, properties: Object): void;
     /** Android only. No-op elsewhere. */
     handleIntent(): void;

package/lib/typescript/src/NativeBooleanmathsRnSdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativeBooleanmathsRnSdk.d.ts","sourceRoot":"","sources":["../../../src/NativeBooleanmathsRnSdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAErE,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACrD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,qCAAqC;IACrC,YAAY,IAAI,IAAI,CAAC;IACrB;;;OAGG;IACH,wBAAwB,IAAI,IAAI,CAAC;IACjC,qDAAqD;IACrD,eAAe,IAAI,MAAM,CAAC;CAC3B;AAED;;;GAGG;;AACH,wBAAkE"}
+{"version":3,"file":"NativeBooleanmathsRnSdk.d.ts","sourceRoot":"","sources":["../../../src/NativeBooleanmathsRnSdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAErE,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACvE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,qCAAqC;IACrC,YAAY,IAAI,IAAI,CAAC;IACrB;;;OAGG;IACH,wBAAwB,IAAI,IAAI,CAAC;IACjC,qDAAqD;IACrD,eAAe,IAAI,MAAM,CAAC;CAC3B;AAED;;;GAGG;;AACH,wBAAkE"}

package/lib/typescript/src/types.d.ts

@@ -15,8 +15,21 @@ export interface BooleanMathsApi {
      *
      * Calling this more than once is harmless — the native SDK ignores
      * subsequent calls.
+     *
+     * @param isDebug Marks this process as a development build. Every event it
+     * tracks is stamped `environment: "development"` instead of `"production"`,
+     * and the native SDKs' verbose logging is switched on. Defaults to `false`.
+     *
+     * The flag is recorded per event when the event is queued, not when the
+     * queue is flushed, so events written by a debug build stay marked as
+     * development even if they only sync later.
+     *
+     * It is deliberately *not* derived from `__DEV__` inside the wrapper —
+     * where an event lands is a backend-routing decision, not a bundler one, and
+     * some teams want release builds pointed at development. Pass `__DEV__`
+     * yourself if that is the behaviour you want.
      */
-    initialize(apiKey: string, pixelId: string): void;
+    initialize(apiKey: string, pixelId: string, isDebug?: boolean): void;
     /**
      * Records a custom event. Events are persisted locally and synced in the
      * background, so this never blocks and never throws on network failure.
@@ -28,10 +41,14 @@ export interface BooleanMathsApi {
      * Forwards the current Activity's intent to the native SDK so ad deep links,
      * app links and push-notification campaign data are attributed.
      *
-     * This is the primary entry point for every kind of launch intent. Android
-     * only — a no-op on every other platform. Call it from your deep-link
-     * handler; `initialize` already forwards the launch intent itself (see the
-     * README for why that needs special handling).
+     * This is the primary entry point for every kind of launch intent. Call it
+     * from your deep-link handler; `initialize` already forwards the launch
+     * intent itself (see the README for why that needs special handling).
+     *
+     * **Android only.** A no-op on iOS — not because iOS is unsupported (event
+     * tracking works fully there), but because intents are an Android concept and
+     * iOS deep links / universal links are out of scope for now. Safe to call
+     * unconditionally from shared code; on iOS it logs one dev-mode notice.
      *
      * Safe to call repeatedly — the native SDK de-duplicates intents it has
      * already processed.
@@ -47,12 +64,17 @@ export interface BooleanMathsApi {
     handleNotificationIntent(): void;
     /**
      * Returns the native SDK's hello message, or `null` when there is no native
-     * SDK on this platform. Useful as a bridge smoke test.
+     * SDK on this platform.
+     *
+     * Useful as a bridge smoke test: the string comes from the native SDK itself
+     * on both Android and iOS, so a correct value also proves the native artifact
+     * actually linked.
      */
     getHelloMessage(): string | null;
     /**
-     * `true` only on platforms where a real BooleanMaths native SDK is linked.
-     * Currently Android only.
+     * `true` only on platforms where a real BooleanMaths native SDK is linked —
+     * Android and iOS. `false` on web, and on any platform where the native
+     * module failed to resolve (typically a JS install without a native rebuild).
      */
     readonly isSupported: boolean;
 }

package/lib/typescript/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,yBAAyB,EAAE,GAC3B;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,yBAAyB,CAAA;CAAE,CAAC;AAEjD,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC9C,MAAM,EACN,yBAAyB,CAC1B,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAElD;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAEzE;;;;;;;;;;;OAWG;IACH,YAAY,IAAI,IAAI,CAAC;IAErB;;;;;;OAMG;IACH,wBAAwB,IAAI,IAAI,CAAC;IAEjC;;;OAGG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,yBAAyB,EAAE,GAC3B;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,yBAAyB,CAAA;CAAE,CAAC;AAEjD,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC9C,MAAM,EACN,yBAAyB,CAC1B,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAErE;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAEzE;;;;;;;;;;;;;;;OAeG;IACH,YAAY,IAAI,IAAI,CAAC;IAErB;;;;;;OAMG;IACH,wBAAwB,IAAI,IAAI,CAAC;IAEjC;;;;;;;OAOG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IAEjC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@booleanmaths/booleanmaths-rn-sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "React Native SDK for BooleanMaths — track user events and attribution in mobile apps.",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/BooleanMaths.native.tsx

@@ -3,11 +3,18 @@ import NativeBooleanmathsRnSdk from './NativeBooleanmathsRnSdk';
 import type { BooleanMathsApi, BooleanMathsEventProperties } from './types';
 
 /**
- * The BooleanMaths native SDK currently ships for Android only. There is no
- * iOS artifact yet, so on iOS every call below short-circuits and the SDK
- * behaves as a silent no-op rather than crashing the app.
+ * The BooleanMaths native SDK ships for Android (`com.booleanmaths:bm-sdk`) and
+ * iOS (`BooleanMathsSDK`). Any other platform — including out-of-tree React
+ * Native targets — has no native artifact, so every call below short-circuits
+ * and the SDK behaves as a silent no-op rather than crashing the app.
+ *
+ * Note that `handleIntent` is a no-op on iOS even though iOS is supported here:
+ * intents are an Android concept. See its JSDoc in `./types`.
  */
-const SUPPORTED_PLATFORMS: ReadonlyArray<typeof Platform.OS> = ['android'];
+const SUPPORTED_PLATFORMS: ReadonlyArray<typeof Platform.OS> = [
+  'android',
+  'ios',
+];
 
 const isPlatformSupported = SUPPORTED_PLATFORMS.includes(Platform.OS);
 
@@ -30,7 +37,7 @@ function warnOnce() {
   if (!isPlatformSupported) {
     console.warn(
       `[@booleanmaths/booleanmaths-rn-sdk] The BooleanMaths native SDK is not available on ${Platform.OS} ` +
-        '(Android only for now). All SDK calls are no-ops on this platform and no ' +
+        '(Android and iOS only). All SDK calls are no-ops on this platform and no ' +
         'events will be tracked. Gate your calls on `BooleanMaths.isSupported` to ' +
         'silence this warning — see the README\'s "Platform support" section.'
     );
@@ -63,13 +70,16 @@ function forwardCurrentIntent(): void {
 export const BooleanMaths: BooleanMathsApi = {
   isSupported,
 
-  initialize(apiKey: string, pixelId: string): void {
+  initialize(apiKey: string, pixelId: string, isDebug: boolean = false): void {
     if (!isSupported) {
       warnOnce();
       return;
     }
 
-    NativeBooleanmathsRnSdk!.initializeSdk(apiKey, pixelId);
+    // Coerced rather than passed through: the codegen spec declares a
+    // non-optional boolean, and a truthy non-boolean from untyped JS would
+    // arrive at the native side as a type mismatch rather than a flag.
+    NativeBooleanmathsRnSdk!.initializeSdk(apiKey, pixelId, Boolean(isDebug));
   },
 
   trackEvent(name: string, properties: BooleanMathsEventProperties = {}): void {

package/src/BooleanMaths.tsx

@@ -26,7 +26,7 @@ function warnOnce() {
 export const BooleanMaths: BooleanMathsApi = {
   isSupported: false,
 
-  initialize(_apiKey: string, _pixelId: string): void {
+  initialize(_apiKey: string, _pixelId: string, _isDebug?: boolean): void {
     warnOnce();
   },
 

package/src/NativeBooleanmathsRnSdk.ts

@@ -6,8 +6,13 @@ export interface Spec extends TurboModule {
    * already taken by `NativeModule.initialize()` on Android and by
    * `+[NSObject initialize]` on iOS. The public JS API exposes this as
    * `BooleanMaths.initialize()`.
+   *
+   * `isDebug` is required here even though it is optional on the public API —
+   * codegen has no notion of a default, so `BooleanMaths.initialize` always
+   * passes an explicit boolean. Same arrangement as `trackEvent`'s
+   * `properties`.
    */
-  initializeSdk(apiKey: string, pixelId: string): void;
+  initializeSdk(apiKey: string, pixelId: string, isDebug: boolean): void;
   trackEvent(name: string, properties: Object): void;
   /** Android only. No-op elsewhere. */
   handleIntent(): void;

package/src/types.ts

@@ -25,8 +25,21 @@ export interface BooleanMathsApi {
    *
    * Calling this more than once is harmless — the native SDK ignores
    * subsequent calls.
+   *
+   * @param isDebug Marks this process as a development build. Every event it
+   * tracks is stamped `environment: "development"` instead of `"production"`,
+   * and the native SDKs' verbose logging is switched on. Defaults to `false`.
+   *
+   * The flag is recorded per event when the event is queued, not when the
+   * queue is flushed, so events written by a debug build stay marked as
+   * development even if they only sync later.
+   *
+   * It is deliberately *not* derived from `__DEV__` inside the wrapper —
+   * where an event lands is a backend-routing decision, not a bundler one, and
+   * some teams want release builds pointed at development. Pass `__DEV__`
+   * yourself if that is the behaviour you want.
    */
-  initialize(apiKey: string, pixelId: string): void;
+  initialize(apiKey: string, pixelId: string, isDebug?: boolean): void;
 
   /**
    * Records a custom event. Events are persisted locally and synced in the
@@ -40,10 +53,14 @@ export interface BooleanMathsApi {
    * Forwards the current Activity's intent to the native SDK so ad deep links,
    * app links and push-notification campaign data are attributed.
    *
-   * This is the primary entry point for every kind of launch intent. Android
-   * only — a no-op on every other platform. Call it from your deep-link
-   * handler; `initialize` already forwards the launch intent itself (see the
-   * README for why that needs special handling).
+   * This is the primary entry point for every kind of launch intent. Call it
+   * from your deep-link handler; `initialize` already forwards the launch
+   * intent itself (see the README for why that needs special handling).
+   *
+   * **Android only.** A no-op on iOS — not because iOS is unsupported (event
+   * tracking works fully there), but because intents are an Android concept and
+   * iOS deep links / universal links are out of scope for now. Safe to call
+   * unconditionally from shared code; on iOS it logs one dev-mode notice.
    *
    * Safe to call repeatedly — the native SDK de-duplicates intents it has
    * already processed.
@@ -61,13 +78,18 @@ export interface BooleanMathsApi {
 
   /**
    * Returns the native SDK's hello message, or `null` when there is no native
-   * SDK on this platform. Useful as a bridge smoke test.
+   * SDK on this platform.
+   *
+   * Useful as a bridge smoke test: the string comes from the native SDK itself
+   * on both Android and iOS, so a correct value also proves the native artifact
+   * actually linked.
    */
   getHelloMessage(): string | null;
 
   /**
-   * `true` only on platforms where a real BooleanMaths native SDK is linked.
-   * Currently Android only.
+   * `true` only on platforms where a real BooleanMaths native SDK is linked —
+   * Android and iOS. `false` on web, and on any platform where the native
+   * module failed to resolve (typically a JS install without a native rebuild).
    */
   readonly isSupported: boolean;
 }