@wayq/beekon-rn 0.0.8 → 0.0.9

package/BeekonRn.podspec

@@ -11,7 +11,7 @@ Pod::Spec.new do |s|
   s.authors      = package["author"]
 
   # iOS 17.0 floor reflects this wrapper's React Native baseline (RN 0.85), not
-  # a BeekonKit constraint — BeekonKit 0.0.8 itself supports iOS 13+ (with
+  # a BeekonKit constraint — BeekonKit 0.0.9 itself supports iOS 13+ (with
   # 13–16 fallback paths). Kept at 17.0 to avoid any consumer regression; do not
   # lower below React Native's own minimum.
   s.platforms    = { :ios => "17.0" }

package/CHANGELOG.md

@@ -6,6 +6,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 Beekon is pre-1.0 — releases may contain breaking changes.
 
+## [0.0.9] - 2026-06-14
+
+### Added
+
+- **Cloud mode** (cloud-mode-v1): point a project key (`bkproj_…`) at Beekon
+  Cloud and let the server own tracking config, geofences, and the license.
+  Built via `BeekonConfig.cloud(...)`; cloud config takes the project key and an
+  optional `endpoint` (default `https://api.getbeekon.com`). Requires the native
+  SDKs ≥ 0.0.9.
+- **Diagnostic logging** (log-format-v1): `getLog` / `exportLog` / `clearLog` /
+  `setLogLevel` / `log` plus the `onLog` subscription and `LogEntry` / `LogLevel`
+  types; `logLevel` on each config arm sets the threshold. Requires the native
+  SDKs ≥ 0.0.9.
+- **`SyncConfig.syncThreshold`** ([beekon#20]): pending-fix count that triggers
+  an early upload of regular fixes ahead of the `intervalSeconds` schedule (not
+  subject to the Android ~15 min WorkManager floor). `0` (the default) leaves
+  regular fixes to the schedule. Independent of this setting, a geofence event
+  and a session stop with pending fixes always flush immediately while sync is
+  configured. Requires the native SDKs ≥ 0.0.9.
+
+### Changed
+
+- **BREAKING:** `BeekonConfig` is now a sealed two-arm discriminated union
+  (`CloudConfig | SelfManagedConfig`) built via `BeekonConfig.cloud(...)` /
+  `BeekonConfig.selfManaged(...)`; the flat config object is gone and a `mode`
+  discriminator (`'cloud'` | `'selfManaged'`) is now required. Tracking params,
+  `sync`, and `licenseKey` live only on the `selfManaged` arm.
+
+[beekon#20]: https://github.com/wayqteam/beekon/issues/20
+
 ## [0.0.8]
 
 Built against the native **0.0.8** API; requires native ≥ 0.0.8 at runtime.

package/README.md

@@ -33,6 +33,8 @@ Capture GPS in the foreground and background, keep a queryable history on the de
 - On-device history you can query at any time
 - Geofencing with enter and exit events
 - Optional batched server sync with automatic retry
+- Beekon Cloud mode: point at a project with a `bkproj_` key and let the server own tracking config, geofences, and license
+- Diagnostic logging: query/export an on-device log buffer and stream live entries for field debugging
 - Activity detection (walking, running, cycling, automotive)
 - Built for the React Native New Architecture
 
@@ -133,6 +135,7 @@ const offLocation = Beekon.onLocation((location) => {
 
 // Configure is optional. Request OS permissions before starting.
 await Beekon.configure({
+  mode: 'selfManaged',
   minTimeBetweenLocationsSeconds: 30,
   minDistanceBetweenLocationsMeters: 100,
 });
@@ -151,7 +154,7 @@ offLocation();
 Beekon.onState((state) => {
   if (state.kind === 'stopped') {
     // 'user' | 'permissionDenied' | 'locationServicesDisabled'
-    //   | 'locationUnavailable' | 'system'
+    //   | 'locationUnavailable' | 'cloudModeUnavailable' | 'system'
     console.log('stopped:', state.reason);
   }
 });
@@ -190,6 +193,7 @@ Add a `sync` config to upload recorded fixes and geofence events to your backend
 
 ```ts
 await Beekon.configure({
+  mode: 'selfManaged',
   sync: {
     url: 'https://api.example.com/locations',
     headers: { Authorization: 'Bearer <token>' },
@@ -212,6 +216,7 @@ The supplied tokens are a **seed**: the SDK owns and rotates the live token set
 
 ```ts
 await Beekon.configure({
+  mode: 'selfManaged',
   sync: {
     url: 'https://api.example.com/locations',
     auth: {
@@ -237,9 +242,33 @@ const offAuth = Beekon.onAuthTokens((tokens) => {
 
 The refresh recipe is persisted in plaintext to survive a cold launch — **do not** put static client secrets in `refreshHeaders` or `refreshPayload`. Requires the native SDK ≥ 0.0.6; with an older native binary the recipe is ignored and only static `sync.headers` apply.
 
+### License
+
+Supply a Beekon license token (a `license-format-v1` JWS) with `licenseKey`. It is the highest-priority channel, overriding the platform manifest value (`in.wayq.beekon.license` meta-data on Android, `BeekonLicenseKey` in `Info.plist` on iOS); `undefined`, blank, or whitespace-only means unset. A token is app-id- and product-bound, so it is safe to commit to source control.
+
+```ts
+await Beekon.configure({
+  mode: 'selfManaged',
+  licenseKey: '<license-format-v1 JWS>',
+});
+```
+
+The license is **purely observational** — no status ever blocks, degrades, or delays the SDK. Read the current platform's status once with `licenseStatus()`, or subscribe with `onLicenseStatus` (the latest status is delivered immediately):
+
+```ts
+const status = await Beekon.licenseStatus();
+console.log('license:', status.status); // 'evaluation' | 'licensed' | ...
+
+const offLicense = Beekon.onLicenseStatus((s) => {
+  if (s.status === 'licensed') console.log('tier:', s.tier);
+});
+```
+
+Android and iOS validate independently and may legally report different statuses for the same app (for example a license scoped to `["android"]` reads `licensed` on Android and `invalid` / `productMismatch` on iOS). The value reflects only the platform you are running on.
+
 ## Configuration
 
-All options are optional; defaults are shown.
+`BeekonConfig` is a sealed two-arm union — pass `mode: 'selfManaged'` (the options below, all optional) or `mode: 'cloud'` (`{ projectKey, endpoint?, notification?, logLevel? }`, where the server owns tracking/geofences/license). Self-managed options (defaults shown):
 
 | Option | Default | Description |
 |---|---|---|
@@ -249,8 +278,9 @@ All options are optional; defaults are shown.
 | `whenStationary` | `'pause'` | `'keepTracking'` \| `'pause'` \| `'pauseWithCheckIns'`. |
 | `stationaryRadiusMeters` | `5` | Distance the device must move to count as moving again. |
 | `detectActivity` | `false` | Detect physical activity. Requires the motion permission. |
-| `sync` | – | Server upload settings: `{ url, headers?, intervalSeconds?, batchSize?, auth? }`. See [Token refresh](#token-refresh). |
+| `sync` | – | Server upload settings: `{ url, headers?, intervalSeconds?, batchSize?, syncThreshold?, auth? }`. See [Token refresh](#token-refresh). |
 | `notification` | – | Android-only tracking notification: `{ title?, text?, smallIcon? }`. `smallIcon` is a drawable/mipmap resource name. |
+| `licenseKey` | – | Beekon license token (`license-format-v1` JWS). Highest-priority supply channel; overrides the platform manifest value. See [License](#license). |
 
 A fix is recorded only when **both** the time and distance filters are satisfied.
 
@@ -271,6 +301,12 @@ A fix is recorded only when **both** the time and distance filters are satisfied
 | `addGeofences(geofences)` | Register circular regions. |
 | `removeGeofences(ids)` | Unregister geofences by id. |
 | `listGeofences()` | Currently registered geofences. |
+| `licenseStatus()` | Current platform's license status (a `LicenseStatus`). Observational only. See [License](#license). |
+| `getLog(from, to)` | Persisted diagnostic log entries in a date range (oldest first). |
+| `exportLog()` | Serialize the log buffer to an NDJSON file; resolves the file path. |
+| `clearLog()` | Delete all persisted diagnostic log entries. |
+| `setLogLevel(level)` | Change the diagnostic log verbosity threshold at runtime. |
+| `log(level, message)` | Write a host-app breadcrumb into the SDK log pipeline (category `app`). |
 
 Subscriptions — each returns an unsubscribe function:
 
@@ -281,6 +317,8 @@ Subscriptions — each returns an unsubscribe function:
 | `onGeofenceEvent(cb)` | Geofence enter and exit events. |
 | `onSyncStatus(cb)` | Upload status. The current status is delivered immediately. |
 | `onAuthTokens(cb)` | Token rotations from native refresh (see [Token refresh](#token-refresh)). The latest rotation is delivered immediately. |
+| `onLicenseStatus(cb)` | License status changes (see [License](#license)). The current status is delivered immediately. |
+| `onLog(cb)` | Diagnostic log entries as they are recorded (broadcast, no replay). |
 
 `getLocations`, `deleteLocations`, `pendingUploadCount`, and `addGeofences` reject with a `BeekonError` on failure — check `error.kind` (`'storage'` or `'invalidGeofence'`). `getCurrentLocation` rejects with `error.kind` `'permissionDenied'`, `'locationServicesDisabled'`, or `'locationUnavailable'` on a precondition failure. Other methods resolve normally; tracking-lifecycle problems are reported through `onState` rather than thrown.
 
@@ -312,7 +350,7 @@ type BeekonState =
       kind: 'stopped';
       reason:
         | 'user' | 'permissionDenied' | 'locationServicesDisabled'
-        | 'locationUnavailable' | 'system';
+        | 'locationUnavailable' | 'cloudModeUnavailable' | 'system';
     };
 
 type SyncStatus =
@@ -365,6 +403,30 @@ type AuthTokens = {
   expiresAt: Date | null;
   epoch: number; // monotonic generation, bumped on each refresh
 };
+
+// Returned by `licenseStatus()` / delivered by `onLicenseStatus`. Observational
+// only — no status ever blocks the SDK. Use `status` as the discriminator.
+type LicenseStatus =
+  | { status: 'notDetermined' }
+  | { status: 'evaluation' }
+  | { status: 'expired' }
+  | { status: 'updateEntitlementLapsed' }
+  | { status: 'licensed'; tier: string; entitlements: string[] }
+  | { status: 'invalid'; reason: LicenseInvalidReason };
+
+type LicenseInvalidReason =
+  | 'malformed' | 'unknownKey' | 'badSignature'
+  | 'appIdMismatch' | 'productMismatch' | 'unsupportedVersion';
+
+type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
+
+type LogEntry = {
+  id: string;        // UUIDv7
+  timestamp: Date;
+  level: LogLevel;
+  category: string;  // e.g. 'location', 'sync'; host breadcrumbs use 'app'
+  message: string;
+};
 ```
 
 Optional numeric fields on `Location` are `null` when the device did not report them — never `0`.
@@ -381,7 +443,7 @@ A complete, runnable example is in the [`example/`](./example) directory.
 
 ## License
 
-Proprietary — evaluation use only without a separate written agreement with wayqteam. See [LICENSE.txt](./LICENSE.txt).
+Proprietary — evaluation use only without a separate written agreement with WayQ Technologies Pvt Ltd. See [LICENSE.txt](./LICENSE.txt).
 
 ---
 

package/android/build.gradle

@@ -79,7 +79,7 @@ dependencies {
   // the SDK reaches v1 stability. 0.0.7 is the release that ships the license
   // API (setWrapperInfo / BeekonConfig.licenseKey / Beekon.licenseStatus);
   // 0.0.8 embeds the production ES256 verification keyset.
-  implementation "io.github.wayqteam:beekon:0.0.8"
+  implementation "io.github.wayqteam:beekon:0.0.9"
   // Kotlin coroutines — required for collecting Beekon's StateFlow/SharedFlow.
   // Beekon already depends on coroutines transitively, but declaring it here
   // makes the dependency intent explicit.

package/android/src/main/java/in/wayq/beekonrn/BeekonRnModule.kt

@@ -25,6 +25,8 @@ import `in`.wayq.beekon.Location
 import `in`.wayq.beekon.LocationQuality
 import `in`.wayq.beekon.LocationTrigger
 import `in`.wayq.beekon.LocationUnavailableReason
+import `in`.wayq.beekon.LogEntry
+import `in`.wayq.beekon.LogLevel
 import `in`.wayq.beekon.MotionState
 import `in`.wayq.beekon.NotificationConfig
 import `in`.wayq.beekon.StationaryMode
@@ -64,6 +66,7 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
     scope.launch { Beekon.syncStatus.collect { emitOnSyncStatus(syncStatusToWire(it)) } }
     scope.launch { Beekon.authChanges.collect { emitOnAuthTokens(tokenRefreshToWire(it)) } }
     scope.launch { Beekon.licenseStatus.collect { emitOnLicenseStatus(licenseStatusToWire(it)) } }
+    scope.launch { Beekon.logs.collect { emitOnLog(logEntryToWire(it)) } }
   }
 
   // ---------------------------------------------------------------------------
@@ -232,6 +235,55 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
     promise.resolve(licenseStatusToWire(Beekon.licenseStatus.value))
   }
 
+  // ---------------------------------------------------------------------------
+  // Diagnostic logs (spec diagnostics/log-format-v1)
+  // ---------------------------------------------------------------------------
+
+  override fun getLog(fromMs: Double, toMs: Double, promise: Promise) {
+    scope.launch {
+      try {
+        val from = Instant.ofEpochMilli(fromMs.toLong())
+        val to = Instant.ofEpochMilli(toMs.toLong())
+        val arr: WritableArray = Arguments.createArray()
+        for (e in Beekon.getLog(from, to)) arr.pushMap(logEntryToWire(e))
+        promise.resolve(arr)
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message ?: "getLog failed", t)
+      }
+    }
+  }
+
+  override fun exportLog(promise: Promise) {
+    scope.launch {
+      try {
+        promise.resolve(Beekon.exportLog())
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message ?: "exportLog failed", t)
+      }
+    }
+  }
+
+  override fun clearLog(promise: Promise) {
+    scope.launch {
+      try {
+        Beekon.clearLog()
+        promise.resolve(null)
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message ?: "clearLog failed", t)
+      }
+    }
+  }
+
+  override fun setLogLevel(level: String, promise: Promise) {
+    Beekon.setLogLevel(toLogLevel(level))
+    promise.resolve(null)
+  }
+
+  override fun log(level: String, message: String, promise: Promise) {
+    Beekon.log(toLogLevel(level), message)
+    promise.resolve(null)
+  }
+
   override fun invalidate() {
     super.invalidate()
     scope.cancel()
@@ -241,20 +293,47 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
   // Mappers: wire (ReadableMap/Array) → Kotlin
   // ---------------------------------------------------------------------------
 
+  // GATED on beekon native 0.0.9 (sealed BeekonConfig) — does not compile against
+  // the pinned 0.0.8 dep (the flat BeekonConfig(...) constructor). Switches on the
+  // wire `mode` (cloud-mode-v1 §2) to build the matching sealed arm. A cloud
+  // configuration with an empty/invalid projectKey throws
+  // BeekonException.InvalidConfiguration, which the configure() catch turns into a
+  // promise rejection via errorCode().
   private fun wireToConfig(map: ReadableMap): BeekonConfig {
-    val sync =
-      if (map.hasKey("sync") && !map.isNull("sync")) {
-        map.getMap("sync")?.let { wireToSyncConfig(it) }
-      } else {
-        null
-      }
     val notification =
       if (map.hasKey("notification") && !map.isNull("notification")) {
         map.getMap("notification")?.let { wireToNotification(it) }
       } else {
         null
       }
-    return BeekonConfig(
+
+    if (optString(map, "mode") == "cloud") {
+      val projectKey = optString(map, "projectKey") ?: ""
+      val endpoint = optString(map, "endpoint")
+      // Omitted endpoint → fall back to the constructor's baked-in default.
+      return if (endpoint != null) {
+        BeekonConfig.Cloud(
+          projectKey = projectKey,
+          endpoint = endpoint,
+          notification = notification ?: NotificationConfig(),
+          logLevel = toLogLevel(optString(map, "logLevel")),
+        )
+      } else {
+        BeekonConfig.Cloud(
+          projectKey = projectKey,
+          notification = notification ?: NotificationConfig(),
+          logLevel = toLogLevel(optString(map, "logLevel")),
+        )
+      }
+    }
+
+    val sync =
+      if (map.hasKey("sync") && !map.isNull("sync")) {
+        map.getMap("sync")?.let { wireToSyncConfig(it) }
+      } else {
+        null
+      }
+    return BeekonConfig.SelfManaged(
       minTimeBetweenLocationsSeconds =
         map.getDouble("minTimeBetweenLocationsSeconds").toLong(),
       minDistanceBetweenLocationsMeters =
@@ -268,6 +347,7 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
       // Passed through verbatim; absent/null means unset — the SDK falls through
       // to the manifest meta-data, then evaluation (license-format-v1 §9).
       licenseKey = optString(map, "licenseKey"),
+      logLevel = toLogLevel(optString(map, "logLevel")),
     )
   }
 
@@ -283,6 +363,7 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
       headers = entriesToMap(map.getArray("headers")),
       intervalSeconds = map.getDouble("intervalSeconds").toLong(),
       batchSize = map.getDouble("batchSize").toInt(),
+      syncThreshold = if (map.hasKey("syncThreshold")) map.getDouble("syncThreshold").toInt() else 0,
       auth = auth,
     )
   }
@@ -484,6 +565,16 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
     return m
   }
 
+  private fun logEntryToWire(e: LogEntry): WritableMap {
+    val m = Arguments.createMap()
+    m.putString("id", e.id)
+    m.putDouble("timestampMs", e.timestamp.toEpochMilli().toDouble())
+    m.putString("level", e.level.wire)
+    m.putString("category", e.category)
+    m.putString("message", e.message)
+    return m
+  }
+
   private fun putNullableDouble(map: WritableMap, key: String, value: Double?) {
     if (value == null) map.putNull(key) else map.putDouble(key, value)
   }
@@ -514,11 +605,18 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
     else -> AuthBodyFormat.Form
   }
 
+  // Wire token (lowercase) -> native LogLevel; unknown/absent defaults to Info.
+  private fun toLogLevel(s: String?): LogLevel =
+    LogLevel.fromWire(s ?: "") ?: LogLevel.Info
+
+  // GATED on beekon native 0.0.9 (StopReason.CloudModeUnavailable) — the new arm
+  // does not exist on the pinned 0.0.8 dep, so this `when` is non-exhaustive there.
   private fun stopReasonToWire(r: StopReason): String = when (r) {
     StopReason.User -> "user"
     StopReason.PermissionDenied -> "permissionDenied"
     StopReason.LocationServicesDisabled -> "locationServicesDisabled"
     StopReason.LocationUnavailable -> "locationUnavailable"
+    StopReason.CloudModeUnavailable -> "cloudModeUnavailable"
     StopReason.System -> "system"
   }
 
@@ -580,6 +678,6 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
     // Reported to the native verifier via setWrapperInfo (diagnostics only — the
     // verifier consumes only the product). Keep in sync with package.json
     // "version" on release.
-    private const val WRAPPER_VERSION = "0.0.7"
+    private const val WRAPPER_VERSION = "0.0.9"
   }
 }

package/ios/BeekonRn.mm

@@ -35,6 +35,9 @@
         }
         onLicenseStatus:^(NSDictionary *_Nonnull ls) {
           [weakSelf emitOnLicenseStatus:ls];
+        }
+        onLog:^(NSDictionary *_Nonnull e) {
+          [weakSelf emitOnLog:e];
         }];
   }
   return self;
@@ -147,6 +150,38 @@
   [_impl licenseStatusWithResolver:resolve rejecter:reject];
 }
 
+// MARK: - Diagnostic logs
+
+- (void)getLog:(double)fromMs
+          toMs:(double)toMs
+       resolve:(RCTPromiseResolveBlock)resolve
+        reject:(RCTPromiseRejectBlock)reject {
+  [_impl getLogFromMs:fromMs toMs:toMs resolver:resolve rejecter:reject];
+}
+
+- (void)exportLog:(RCTPromiseResolveBlock)resolve
+           reject:(RCTPromiseRejectBlock)reject {
+  [_impl exportLogWithResolver:resolve rejecter:reject];
+}
+
+- (void)clearLog:(RCTPromiseResolveBlock)resolve
+          reject:(RCTPromiseRejectBlock)reject {
+  [_impl clearLogWithResolver:resolve rejecter:reject];
+}
+
+- (void)setLogLevel:(NSString *)level
+            resolve:(RCTPromiseResolveBlock)resolve
+             reject:(RCTPromiseRejectBlock)reject {
+  [_impl setLogLevel:level resolver:resolve rejecter:reject];
+}
+
+- (void)log:(NSString *)level
+    message:(NSString *)message
+    resolve:(RCTPromiseResolveBlock)resolve
+     reject:(RCTPromiseRejectBlock)reject {
+  [_impl logWithLevel:level message:message resolver:resolve rejecter:reject];
+}
+
 - (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
     (const facebook::react::ObjCTurboModule::InitParams &)params {
   return std::make_shared<facebook::react::NativeBeekonRnSpecJSI>(params);