@wayq/beekon-rn 0.0.3 → 0.0.5

package/BeekonRn.podspec

@@ -13,7 +13,7 @@ Pod::Spec.new do |s|
   # BeekonKit targets iOS 17.0 (uses CLLocationUpdate.liveUpdates). The
   # consuming app must also target iOS 17.0 or higher.
   s.platforms    = { :ios => "17.0" }
-  s.source       = { :git => "https://github.com/wayqteam/beekon.git", :tag => "v#{s.version}" }
+  s.source       = { :git => "https://github.com/wayqteam/beekon-rn.git", :tag => "v#{s.version}" }
 
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
   # Headers are only for the auto-generated `BeekonRn-Swift.h` interop — keep

package/README.md

@@ -2,9 +2,11 @@
 
 React Native binding for the [Beekon](https://github.com/wayqteam/beekon) location SDK.
 
-A thin pass-through over the native Android (`io.github.wayqteam:beekon`) and iOS (`BeekonKit`) libraries. The public TypeScript surface mirrors the Kotlin / Swift APIs in shape: `configure / start / stop`, callback-backed `state` and `locations` streams, and a `history(from, to)` query.
+A thin pass-through over the native Android (`io.github.wayqteam:beekon`) and iOS (`BeekonKit`) libraries at version **0.0.5**. The public TypeScript surface mirrors the Kotlin / Swift APIs in shape: a 12-method `Beekon` singleton, four callback streams (`state`, `locations`, `geofenceEvents`, `syncStatus`), geofencing, and optional server sync.
 
-Built on the React Native New Architecture (TurboModules + Codegen). The binding is a thin delegation layer — all logic, persistence, and OS integration lives natively. **Writes never cross into JavaScript**: in background the JS engine isn't guaranteed to be alive, so the native libraries own the persistence path end-to-end.
+Built on the React Native New Architecture (TurboModules + Codegen). The binding contains no location logic — all tracking, persistence, geofencing, and OS integration live natively. **Writes never cross into JavaScript**: in the background the JS engine isn't guaranteed to be alive, so the native libraries own the persistence path end-to-end.
+
+There is **no `initialize()`** — the native SDKs auto-initialize. `start()` / `stop()` **never throw**: subscribe to `onState` to learn whether tracking is active and why it stopped.
 
 ## Requirements
 
@@ -12,7 +14,7 @@ Built on the React Native New Architecture (TurboModules + Codegen). The binding
 |---|---|
 | React Native | 0.76+ (target 0.85) |
 | iOS | 17.0 |
-| Android | API 26 |
+| Android | **API 26** (required by the native AAR) |
 | New Architecture | required (Old Arch is unsupported) |
 
 ## Install
@@ -23,19 +25,17 @@ npm install @wayq/beekon-rn
 yarn add @wayq/beekon-rn
 ```
 
-iOS:
+iOS — the package fetches and bundles `BeekonKit.xcframework` (SHA256-verified) during `prepare`, so just install pods:
 
 ```sh
 cd ios && pod install
 ```
 
-The package bundles `BeekonKit.xcframework` directly — no manual SwiftPM setup needed.
-
-Android: Maven Central is auto-included by the autolinker. The native AAR (`io.github.wayqteam:beekon`) is pulled transitively.
+Android — Maven Central is auto-included by the autolinker; the native AAR (`io.github.wayqteam:beekon`) is pulled transitively.
 
 ## Permissions
 
-The library does NOT request permissions itself — your app must. Use a library like [`react-native-permissions`](https://github.com/zoontek/react-native-permissions) or platform APIs.
+The library does NOT request permissions — your app must (e.g. via [`react-native-permissions`](https://github.com/zoontek/react-native-permissions) or `PermissionsAndroid`). Foreground location works without background location.
 
 **Android** (`AndroidManifest.xml`):
 
@@ -45,46 +45,85 @@ The library does NOT request permissions itself — your app must. Use a library
 <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
 <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
 <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+<!-- Only when BeekonConfig.detectActivity is enabled -->
+<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
 ```
 
 **iOS** (`Info.plist`):
 
 ```xml
 <key>NSLocationWhenInUseUsageDescription</key>
-<string>...</string>
+<string>…</string>
 <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
-<string>...</string>
+<string>…</string>
+<!-- Only when BeekonConfig.detectActivity is enabled -->
+<key>NSMotionUsageDescription</key>
+<string>…</string>
 <key>UIBackgroundModes</key>
-<array><string>location</string></array>
+<array>
+  <string>location</string>
+  <string>fetch</string>
+</array>
+<key>BGTaskSchedulerPermittedIdentifiers</key>
+<array>
+  <string>in.wayq.beekon.sync</string>
+</array>
+```
+
+## Background-task registration (iOS)
+
+For background sync scheduling and cold-launch resume, register Beekon's background task **synchronously during app launch** (it must run before `didFinishLaunchingWithOptions` returns). In your `AppDelegate.swift`:
+
+```swift
+import BeekonRn
+
+func application(_ application: UIApplication,
+  didFinishLaunchingWithOptions launchOptions: …) -> Bool {
+  BeekonRnImpl.registerBackgroundTasks()
+  // … React Native setup …
+  return true
+}
 ```
 
+Foreground tracking and the JS streams work without this; only background sync / relaunch need it.
+
+## Cold-launch resume (Android)
+
+To resume tracking after the OS killed the process, call `in.wayq.beekon.Beekon.start()` from your `Application.onCreate` (native — the JS engine may not be running on a background relaunch). From JS, `Beekon.resumeIfNeeded()` covers the foreground case.
+
 ## Usage
 
 ```ts
 import { Beekon, type BeekonState, type Location } from '@wayq/beekon-rn';
 
-// Subscribe — returns an unsubscribe function. State replays the latest value
-// to new subscribers; locations is broadcast (no replay).
+// Subscribe — each returns an unsubscribe function. `onState` / `onSyncStatus`
+// replay the latest value to new subscribers; `onLocation` / `onGeofenceEvent`
+// are broadcast (no replay).
 const offState = Beekon.onState((s: BeekonState) => console.log('state', s));
 const offLoc = Beekon.onLocation((l: Location) => console.log('location', l));
 
-// Configure. Defaults: 30 s / 100 m. Pass 0 to disable a gate.
+// Configure (optional; defaults below). Pass 0 to disable a gate.
 await Beekon.configure({
-  intervalSeconds: 10,
-  distanceMeters: 30,
-  androidNotification: {
-    title: 'Tracking',
-    text: 'Recording your route',
-    smallIconResName: 'ic_notification', // drawable in your app
+  minTimeBetweenLocationsSeconds: 30, // default 30
+  minDistanceBetweenLocationsMeters: 100, // default 100
+  accuracyMode: 'balanced', // 'high' | 'balanced' | 'low'
+  whenStationary: 'pause', // 'keepTracking' | 'pause' | 'pauseWithCheckIns'
+  detectActivity: false,
+  // Optional server upload:
+  sync: {
+    url: 'https://example.com/ingest',
+    headers: { Authorization: 'Bearer …' },
   },
+  // Android-only foreground-service notification:
+  notification: { title: 'Tracking', text: 'Recording your route' },
 });
 
-await Beekon.start();
-// ... later
+await Beekon.start(); // never throws — observe onState
+// … later
 await Beekon.stop();
 
-// Read past fixes.
-const fixes = await Beekon.history(new Date(Date.now() - 3600_000), new Date());
+// History (local store; source of truth even when JS was asleep).
+const fixes = await Beekon.getLocations(new Date(Date.now() - 3600_000), new Date());
 
 // Cleanup.
 offState();
@@ -95,21 +134,34 @@ offLoc();
 
 | Method | Description |
 |---|---|
-| `Beekon.configure(config)` | Set sampling thresholds. Optional. |
-| `Beekon.start()` | Begin tracking. State → `tracking`. |
-| `Beekon.stop()` | Stop tracking. Idempotent. State → `stopped` (`reason: 'user'`). |
-| `Beekon.history(from, to)` | Read persisted fixes in range. |
-| `Beekon.onState(cb)` | Subscribe to state. Returns unsubscribe fn. |
-| `Beekon.onLocation(cb)` | Subscribe to gated fixes. Returns unsubscribe fn. |
-
-State is a discriminated union on `kind`: `'idle' | 'tracking' | 'stopped'`. The `'stopped'` variant carries a `reason: 'user' | 'permissionDenied' | 'locationServicesDisabled' | 'system'` (`'system'` is Android-only).
-
-Errors are thrown as `BeekonError` instances with `kind`:
-`'permissionDenied'`, `'locationServicesDisabled'`, `'storageFailure'`.
-
-## Storage and retention
-
-The native SDKs persist every gated fix locally (Room on Android, GRDB on iOS) — JS is a passive reader. Retention: **TTL 7 days OR most recent 100 K rows**, whichever is smaller; auto-pruned on each write batch.
+| `configure(config)` | Set config. Optional, idempotent. Does not throw. |
+| `start()` | Begin tracking. Never throws — observe `onState`. |
+| `stop()` | Stop tracking. Idempotent. Never throws. |
+| `resumeIfNeeded()` | Resume a session active before the app was terminated. |
+| `getLocations(from, to)` | Read persisted fixes in `[from, to]`. Throws `'storage'`. |
+| `deleteLocations(before?)` | Delete fixes at/before `before` (all when omitted). Throws `'storage'`. |
+| `pendingUploadCount()` | Count of fixes not yet uploaded. Throws `'storage'`. |
+| `sync()` | Request an immediate upload (no-op if sync unconfigured). |
+| `setExtras(extras)` | Custom key/value fields sent with every upload. |
+| `addGeofences(geofences)` | Register geofences. Throws `'invalidGeofence'`. |
+| `removeGeofences(ids)` | Unregister geofences by id. |
+| `listGeofences()` | The currently registered geofences. |
+| `onState(cb)` | Subscribe to state. Replay-1. Returns unsubscribe fn. |
+| `onLocation(cb)` | Subscribe to gated fixes. No replay. |
+| `onGeofenceEvent(cb)` | Subscribe to geofence enter/exit. No replay. |
+| `onSyncStatus(cb)` | Subscribe to upload health. Replay-1. |
+
+`BeekonState` is a discriminated union on `kind`: `'idle' | 'tracking' | 'stopped'`. The `'stopped'` variant carries `reason: 'user' | 'permissionDenied' | 'locationServicesDisabled' | 'locationUnavailable' | 'system'`.
+
+`SyncStatus` is a union on `kind`: `'idle' | 'pending' | 'failed'`; `'failed'` carries `reason: 'auth' | 'rejected'`.
+
+`Location` carries `id`, `latitude`, `longitude`, `timestamp`, the nullable `accuracy` / `speed` / `bearing` / `altitude`, plus `quality`, `trigger`, `motion`, `activity` (`null` unless `detectActivity`), and `isMock`. Optional numeric fields are `null` when the OS did not report a value — never `0`.
+
+The **only** thrown errors are `BeekonError` instances with `kind: 'storage' | 'invalidGeofence'`. Permission / services / lifecycle problems are not thrown — they surface on `onState` as `stopped(reason)`.
+
+## Storage, retention, and sync
+
+The native SDKs persist every gated fix locally (Room on Android, GRDB on iOS) — JS is a passive reader. Retention: **TTL 7 days OR the most recent 100 K rows**, whichever is smaller; auto-pruned on each write batch. With `sync` configured, accepted rows are deleted locally after upload, so `getLocations` / `pendingUploadCount` return only un-uploaded fixes.
 
 ## License
 

package/android/build.gradle

@@ -1,7 +1,8 @@
 buildscript {
   ext.BeekonRn = [
     kotlinVersion: "2.1.20",
-    minSdkVersion: 24,
+    // minSdk 26 is required by the native Beekon AAR (io.github.wayqteam:beekon).
+    minSdkVersion: 26,
     compileSdkVersion: 36,
     targetSdkVersion: 36
   ]
@@ -57,8 +58,12 @@ android {
   }
 
   compileOptions {
-    sourceCompatibility JavaVersion.VERSION_1_8
-    targetCompatibility JavaVersion.VERSION_1_8
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
   }
 }
 
@@ -72,7 +77,7 @@ dependencies {
   // Native Beekon SDK — published from beekon-android/ via Maven Central.
   // Pinned exact in v0.x to avoid surprise breakage; loosen to a range when
   // the SDK reaches v1 stability.
-  implementation "io.github.wayqteam:beekon:0.0.3"
+  implementation "io.github.wayqteam:beekon:0.0.5"
   // Kotlin coroutines — required for collecting Beekon's StateFlow/SharedFlow.
   // Beekon already depends on coroutines transitively, but declaring it here
   // makes the dependency intent explicit.