@wayq/beekon-rn 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -6,6 +6,47 @@ 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.1.2] - 2026-06-28
+
+### Added
+
+- **Per-geofence local notifications.** A `BeekonGeofence` may now carry an
+  optional `notification` (`GeofenceNotification`) that the SDK renders natively
+  at crossing time — offline and even when the app is killed. It takes a
+  required `delivery` (`'local'` is the only implemented mode; `'cloud'` is
+  reserved) plus optional `onEnter` / `onExit` `NotificationContent` (`title`
+  and `body` required; optional `importance` defaulting to `'high'`, `deepLink`,
+  and a flat `data` string map). `onEnter` requires `notifyOnEntry` and `onExit`
+  requires `notifyOnExit`; in self-managed mode `delivery` must be `'local'`.
+  Adds the `GeofenceNotification`, `NotificationContent`, `NotificationDelivery`,
+  and `NotificationImportance` types. Requires the native SDKs ≥ 0.1.2.
+- **`getRequiredPermissions()` — config-aware permission doctor.** Resolves the
+  OS permissions the *current configuration* needs as a
+  `PermissionRequirement[]`, each marked `satisfied` against the live grant —
+  the companion to the location-only `getPermissionStatus()` snapshot. Each
+  entry carries `permission` (`BeekonPermission`: `location` /
+  `backgroundLocation` / `activityRecognition` / `notifications`), `importance`
+  (`required` / `recommended`), `satisfied`, and a human-readable `rationale`,
+  reporting activity-recognition and, on Android, notifications too. Read-only;
+  never prompts — Beekon still never *requests* permission. Call after
+  `configure()`; in cloud mode it returns the conservative list. Adds the
+  `PermissionRequirement` and `PermissionImportance` types. Requires the native
+  SDKs ≥ 0.1.2.
+
+## [0.1.1] - 2026-06-23
+
+### Changed
+
+- **Native SDK pins bumped to 0.1.1** — Android Maven coordinate and iOS
+  xcframework (`fetch-beekonkit.sh` `VERSION` + `EXPECTED_SHA`) now track
+  BeekonKit / `beekon` 0.1.1 (device control plane, build-time license gate,
+  and related native fixes since 0.1.0).
+
+### Added
+
+- **Build-gate product id** — native registration now declares the React Native
+  wrapper product id for build-time license enforcement (build-gate-v1).
+
 ## [0.1.0] - 2026-06-15
 
 ### Changed

package/README.md

@@ -30,7 +30,7 @@ Capture location in the foreground and background, keep a queryable history on t
 - Foreground and background tracking that survives app termination
 - Battery-aware capture: time/distance filtering, accuracy presets, auto-pause while stationary
 - On-device history you can query at any time
-- Geofencing with enter and exit events
+- Geofencing with enter and exit events, plus optional per-geofence local notifications that fire offline and even when the app is killed
 - Optional batched server sync with automatic retry
 - Diagnostic logging: query/export an on-device buffer, stream live entries
 - Activity detection (walking, running, cycling, automotive)
@@ -107,12 +107,38 @@ await Beekon.addGeofences([
 ]);
 const offGeofence = Beekon.onGeofenceEvent((e) => console.log(e.geofenceId, e.type));
 
+// Per-geofence local notification — rendered natively at crossing time,
+// offline and even when the app is killed. Add `notification` to a geofence:
+await Beekon.addGeofences([
+  {
+    id: 'home',
+    latitude: 37.331,
+    longitude: -122.031,
+    radiusMeters: 150,
+    notification: {
+      delivery: 'local', // 'local' is the only implemented mode ('cloud' reserved)
+      onEnter: { title: 'Welcome home', body: 'You arrived', deepLink: 'myapp://home' },
+      onExit: { title: 'On the move', body: 'You left home', importance: 'default' },
+    },
+  },
+]);
+
 // One-shot fix, independent of tracking (null on timeout)
 const fix = await Beekon.getCurrentLocation();
 
 // Pre-start permission check (the app still owns the request)
 const status = await Beekon.getPermissionStatus();
 
+// Config-aware "permission doctor" — the OS permissions the CURRENT config
+// needs, each marked `satisfied` against the live grant (never prompts).
+// Call after configure(). Reports activity-recognition and, on Android,
+// notifications — not just location.
+const required = await Beekon.getRequiredPermissions();
+for (const r of required) {
+  // r.permission, r.importance ('required' | 'recommended'), r.satisfied, r.rationale
+  if (!r.satisfied) console.log(`${r.permission} (${r.importance}): ${r.rationale}`);
+}
+
 // Diagnostics — runtime level, live tail, NDJSON export for bug reports
 await Beekon.setLogLevel('debug');
 const logPath = await Beekon.exportLog();
@@ -180,7 +206,7 @@ func application(
 
 ## API at a glance
 
-Methods: `configure` · `start` · `stop` · `resumeIfNeeded` · `getCurrentLocation` · `getLocations` · `deleteLocations` · `pendingUploadCount` · `sync` · `setExtras` · `addGeofences` · `removeGeofences` · `listGeofences` · `getPermissionStatus` · `licenseStatus` · `getLog` · `exportLog` · `clearLog` · `setLogLevel` · `log`.
+Methods: `configure` · `start` · `stop` · `resumeIfNeeded` · `getCurrentLocation` · `getLocations` · `deleteLocations` · `pendingUploadCount` · `sync` · `setExtras` · `addGeofences` · `removeGeofences` · `listGeofences` · `getPermissionStatus` · `getRequiredPermissions` · `licenseStatus` · `getLog` · `exportLog` · `clearLog` · `setLogLevel` · `log`.
 
 Subscriptions (each returns an unsubscribe function): `onState` · `onLocation` · `onGeofenceEvent` · `onSyncStatus` · `onAuthTokens` · `onLicenseStatus` · `onLog`.
 

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.beekonlabs:beekon:0.1.0"
+  implementation "io.github.beekonlabs:beekon:0.1.2"
   // 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/AndroidManifest.xml

@@ -1,2 +1,12 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!--
+      Declares the build-time license-gate product id (build-gate-v1 §6): a static
+      <meta-data> that manifest-merges into the host so the gate validates against
+      the `rn` product, mirroring the runtime setWrapperInfo("rn", …). No runtime effect.
+    -->
+    <application>
+        <meta-data
+            android:name="in.wayq.beekon.product"
+            android:value="rn" />
+    </application>
 </manifest>

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

@@ -18,8 +18,10 @@ import `in`.wayq.beekon.Beekon
 import `in`.wayq.beekon.BeekonConfig
 import `in`.wayq.beekon.BeekonException
 import `in`.wayq.beekon.BeekonGeofence
+import `in`.wayq.beekon.BeekonPermission
 import `in`.wayq.beekon.BeekonState
 import `in`.wayq.beekon.GeofenceEvent
+import `in`.wayq.beekon.GeofenceNotification
 import `in`.wayq.beekon.LicenseStatus
 import `in`.wayq.beekon.Location
 import `in`.wayq.beekon.LocationQuality
@@ -29,6 +31,11 @@ import `in`.wayq.beekon.LogEntry
 import `in`.wayq.beekon.LogLevel
 import `in`.wayq.beekon.MotionState
 import `in`.wayq.beekon.NotificationConfig
+import `in`.wayq.beekon.NotificationContent
+import `in`.wayq.beekon.NotificationDelivery
+import `in`.wayq.beekon.NotificationImportance
+import `in`.wayq.beekon.PermissionImportance
+import `in`.wayq.beekon.PermissionRequirement
 import `in`.wayq.beekon.PermissionStatus
 import `in`.wayq.beekon.StationaryMode
 import `in`.wayq.beekon.StopReason
@@ -38,6 +45,7 @@ import `in`.wayq.beekon.SyncStatus
 import `in`.wayq.beekon.Transition
 import java.time.Instant
 import kotlinx.coroutines.CoroutineScope
+import org.json.JSONObject
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.cancel
@@ -241,6 +249,13 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
     promise.resolve(permissionStatusToWire(Beekon.getPermissionStatus()))
   }
 
+  override fun getRequiredPermissions(promise: Promise) {
+    // Synchronous, non-throwing read on the native SDK.
+    val arr: WritableArray = Arguments.createArray()
+    for (r in Beekon.getRequiredPermissions()) arr.pushMap(permissionRequirementToWire(r))
+    promise.resolve(arr)
+  }
+
   // ---------------------------------------------------------------------------
   // Diagnostic logs (spec diagnostics/log-format-v1)
   // ---------------------------------------------------------------------------
@@ -446,6 +461,7 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
         radiusMeters = m.getDouble("radiusMeters"),
         notifyOnEntry = m.getBoolean("notifyOnEntry"),
         notifyOnExit = m.getBoolean("notifyOnExit"),
+        notification = GeofenceNotificationWire.decode(m.getString("notificationJson")),
       )
     }
     return out
@@ -494,6 +510,7 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
     m.putDouble("radiusMeters", g.radiusMeters)
     m.putBoolean("notifyOnEntry", g.notifyOnEntry)
     m.putBoolean("notifyOnExit", g.notifyOnExit)
+    g.notification?.let { m.putString("notificationJson", GeofenceNotificationWire.encode(it)) }
     return m
   }
 
@@ -540,6 +557,27 @@ class BeekonRnModule(reactContext: ReactApplicationContext) :
     PermissionStatus.Accuracy.Reduced -> "reduced"
   }
 
+  private fun permissionRequirementToWire(r: PermissionRequirement): WritableMap {
+    val m = Arguments.createMap()
+    m.putString("permission", permissionKindToWire(r.permission))
+    m.putString("importance", permissionImportanceToWire(r.importance))
+    m.putBoolean("satisfied", r.satisfied)
+    m.putString("rationale", r.rationale)
+    return m
+  }
+
+  private fun permissionKindToWire(p: BeekonPermission): String = when (p) {
+    BeekonPermission.Location -> "location"
+    BeekonPermission.BackgroundLocation -> "backgroundLocation"
+    BeekonPermission.ActivityRecognition -> "activityRecognition"
+    BeekonPermission.Notifications -> "notifications"
+  }
+
+  private fun permissionImportanceToWire(i: PermissionImportance): String = when (i) {
+    PermissionImportance.Required -> "required"
+    PermissionImportance.Recommended -> "recommended"
+  }
+
   private fun syncStatusToWire(s: SyncStatus): WritableMap {
     val m = Arguments.createMap()
     when (s) {
@@ -705,6 +743,72 @@ 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.1.0"
+    private const val WRAPPER_VERSION = "0.1.2"
+  }
+}
+
+/**
+ * Wrapper-local (de)serialization for [GeofenceNotification] in the canonical JSON shape shared
+ * with the native SDKs. The SDK's own `GeofenceNotificationJson` is `internal`, so the module
+ * cannot reuse it; this mirrors it exactly. Tolerant: unknown enums fall back to defaults and a
+ * malformed/empty payload yields null.
+ */
+private object GeofenceNotificationWire {
+  fun encode(n: GeofenceNotification): String {
+    val obj = JSONObject()
+    obj.put("delivery", if (n.delivery == NotificationDelivery.Cloud) "cloud" else "local")
+    n.onEnter?.let { obj.put("onEnter", contentToJson(it)) }
+    n.onExit?.let { obj.put("onExit", contentToJson(it)) }
+    return obj.toString()
+  }
+
+  fun decode(json: String?): GeofenceNotification? {
+    if (json.isNullOrBlank()) return null
+    return runCatching {
+      val obj = JSONObject(json)
+      val onEnter = contentFromJson(obj.optJSONObject("onEnter"))
+      val onExit = contentFromJson(obj.optJSONObject("onExit"))
+      if (onEnter == null && onExit == null) {
+        null
+      } else {
+        val delivery = if (obj.optString("delivery", "local") == "cloud") {
+          NotificationDelivery.Cloud
+        } else {
+          NotificationDelivery.Local
+        }
+        GeofenceNotification(onEnter = onEnter, onExit = onExit, delivery = delivery)
+      }
+    }.getOrNull()
+  }
+
+  private fun contentToJson(c: NotificationContent): JSONObject {
+    val obj = JSONObject()
+    obj.put("title", c.title)
+    obj.put("body", c.body)
+    obj.put("importance", if (c.importance == NotificationImportance.Default) "default" else "high")
+    c.deepLink?.let { obj.put("deepLink", it) }
+    if (c.data.isNotEmpty()) {
+      val data = JSONObject()
+      for ((k, v) in c.data) data.put(k, v)
+      obj.put("data", data)
+    }
+    return obj
+  }
+
+  private fun contentFromJson(obj: JSONObject?): NotificationContent? {
+    if (obj == null) return null
+    val title = obj.optString("title", "")
+    val body = obj.optString("body", "")
+    if (title.isEmpty() || body.isEmpty()) return null
+    val importance = if (obj.optString("importance", "high") == "default") {
+      NotificationImportance.Default
+    } else {
+      NotificationImportance.High
+    }
+    val deepLink = if (obj.has("deepLink") && !obj.isNull("deepLink")) obj.optString("deepLink") else null
+    val data = obj.optJSONObject("data")?.let { d ->
+      buildMap { for (key in d.keys()) put(key, d.optString(key)) }
+    } ?: emptyMap()
+    return NotificationContent(title = title, body = body, importance = importance, deepLink = deepLink, data = data)
   }
 }

package/ios/BeekonRn.swift

@@ -37,7 +37,7 @@ import BeekonKit
   // 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 static let wrapperVersion = "0.1.0"
+  private static let wrapperVersion = "0.1.2"
 
   @objc public init(
     onState: @escaping (NSDictionary) -> Void,
@@ -353,6 +353,18 @@ import BeekonKit
     resolve(permissionStatusToWire(Beekon.shared.getPermissionStatus()))
   }
 
+  @objc public func getRequiredPermissionsWithResolver(
+    _ resolve: @escaping @Sendable (Any?) -> Void,
+    rejecter _: @escaping @Sendable (String?, String?, Error?) -> Void
+  ) {
+    // `getRequiredPermissions()` is actor-isolated (`await`).
+    Task { [weak self] in
+      guard let self = self else { return }
+      let requirements = await Beekon.shared.getRequiredPermissions()
+      resolve(requirements.map { self.permissionRequirementToWire($0) })
+    }
+  }
+
   // MARK: - Diagnostic logs (spec diagnostics/log-format-v1)
 
   @objc public func getLogFromMs(
@@ -504,7 +516,12 @@ import BeekonKit
           longitude: lng,
           radiusMeters: radius,
           notifyOnEntry: (m["notifyOnEntry"] as? NSNumber)?.boolValue ?? true,
-          notifyOnExit: (m["notifyOnExit"] as? NSNumber)?.boolValue ?? true
+          notifyOnExit: (m["notifyOnExit"] as? NSNumber)?.boolValue ?? true,
+          // Native `GeofenceNotification` is Codable in the canonical shape; a malformed
+          // string degrades to nil rather than failing the add.
+          notification: (m["notificationJson"] as? String).flatMap {
+            try? JSONDecoder().decode(GeofenceNotification.self, from: Data($0.utf8))
+          }
         )
       )
     }
@@ -573,14 +590,19 @@ import BeekonKit
   }
 
   private func geofenceToWire(_ g: BeekonGeofence) -> NSDictionary {
-    return [
-      "id": g.id,
-      "lat": g.latitude,
-      "lng": g.longitude,
-      "radiusMeters": g.radiusMeters,
-      "notifyOnEntry": g.notifyOnEntry,
-      "notifyOnExit": g.notifyOnExit,
-    ]
+    let m = NSMutableDictionary()
+    m["id"] = g.id
+    m["lat"] = g.latitude
+    m["lng"] = g.longitude
+    m["radiusMeters"] = g.radiusMeters
+    m["notifyOnEntry"] = g.notifyOnEntry
+    m["notifyOnExit"] = g.notifyOnExit
+    if let notification = g.notification,
+       let data = try? JSONEncoder().encode(notification),
+       let json = String(data: data, encoding: .utf8) {
+      m["notificationJson"] = json
+    }
+    return m
   }
 
   private func geofenceEventToWire(_ e: GeofenceEvent) -> NSDictionary {
@@ -630,6 +652,34 @@ import BeekonKit
     }
   }
 
+  private func permissionRequirementToWire(_ r: PermissionRequirement) -> NSDictionary {
+    return [
+      "permission": permissionKindToWire(r.permission),
+      "importance": permissionImportanceToWire(r.importance),
+      "satisfied": r.satisfied,
+      "rationale": r.rationale,
+    ]
+  }
+
+  private func permissionKindToWire(_ p: PermissionRequirement.Permission) -> String {
+    switch p {
+    case .location: return "location"
+    case .backgroundLocation: return "backgroundLocation"
+    case .activityRecognition: return "activityRecognition"
+    case .notifications: return "notifications"
+    // BeekonKit enums are non-frozen (library-evolution binary); handle unknowns.
+    @unknown default: return "location"
+    }
+  }
+
+  private func permissionImportanceToWire(_ i: PermissionRequirement.Importance) -> String {
+    switch i {
+    case .required: return "required"
+    case .recommended: return "recommended"
+    @unknown default: return "recommended"
+    }
+  }
+
   private func stateToWire(_ s: BeekonState) -> NSDictionary {
     switch s {
     case .idle: