@wayq/beekon-rn 0.0.1

package/BeekonRn.podspec

@@ -0,0 +1,37 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "BeekonRn"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  # Match RN 0.85 default Podfile floor (15.1). Native BeekonKit's floor is
+  # 15.0 so this is satisfied. Bump only if RN raises its default.
+  s.platforms    = { :ios => "15.1" }
+  s.source       = { :git => "https://github.com/wayqteam/beekon.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
+  # them private so they don't leak into the consuming app's umbrella.
+  s.private_header_files = "ios/**/*.h"
+
+  # Native Beekon SDK as a vendored xcframework. The zip is fetched from
+  # `wayqteam/beekon-ios-binary`'s GitHub Release at this version into
+  # `ios/Frameworks/` by `scripts/fetch-beekonkit.sh`, run via `yarn prepare`,
+  # and bundled in the npm tarball at publish time. SHA256 verified before
+  # extraction.
+  s.vendored_frameworks = "ios/Frameworks/BeekonKit.xcframework"
+
+  # Swift 5.10 covers BeekonKit's binary and our wrapper. Don't pin higher
+  # than necessary — consumer apps may use newer Xcode.
+  s.swift_versions = ["5.10", "6.0"]
+
+  # `install_modules_dependencies` wires React-Codegen, RCT-Folly, and the
+  # rest of the New Architecture deps. Must be last so it can override.
+  install_modules_dependencies(s)
+end

package/LICENSE.txt

@@ -0,0 +1,14 @@
+Beekon SDK
+Copyright (c) 2026 wayqteam. All rights reserved.
+
+This software is licensed for evaluation use only. No production deployment,
+redistribution, sublicensing, or commercial use is permitted without a separate
+written agreement with wayqteam.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM USE OF THE SOFTWARE.
+
+For licensing inquiries: contact wayqteam.

package/README.md

@@ -0,0 +1,122 @@
+# @wayq/beekon-rn
+
+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 / Dart APIs in shape: `init / configure / start / stop`, callback-backed `state` and `positions` streams, and a `history(from, to)` query.
+
+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 (same rule as the Flutter binding).
+
+See [`../docs/REQUIREMENTS.md`](../docs/REQUIREMENTS.md) for the full cross-platform spec.
+
+## Requirements
+
+| Area | Floor |
+|---|---|
+| React Native | 0.76+ (target 0.85) |
+| iOS | 15.1 |
+| Android | API 24 |
+| New Architecture | required (Old Arch is unsupported) |
+
+## Install
+
+```sh
+npm install @wayq/beekon-rn
+# or
+yarn add @wayq/beekon-rn
+```
+
+iOS:
+
+```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.
+
+## 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.
+
+**Android** (`AndroidManifest.xml`):
+
+```xml
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
+<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" />
+```
+
+**iOS** (`Info.plist`):
+
+```xml
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>...</string>
+<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+<string>...</string>
+<key>UIBackgroundModes</key>
+<array><string>location</string></array>
+```
+
+## Usage
+
+```ts
+import { Beekon, type BeekonState, type Position } from '@wayq/beekon-rn';
+
+// Subscribe — returns an unsubscribe function.
+const offState = Beekon.onState((s: BeekonState) => console.log('state', s));
+const offPos = Beekon.onPosition((p: Position) => console.log('pos', p));
+
+// Initialize once at startup.
+await Beekon.init();
+
+// Configure (Android requires `androidNotification`; iOS ignores it).
+await Beekon.configure({
+  preset: 'balanced', // or 'saver' / 'precision'
+  androidNotification: {
+    channelId: 'beekon_tracking',
+    channelName: 'Beekon location tracking',
+    notificationId: 1001,
+    title: 'Tracking',
+    text: 'Recording your route',
+    smallIconResName: 'ic_notification', // drawable in your app
+  },
+});
+
+await Beekon.start();
+// ... later
+await Beekon.stop();
+
+// Read past positions.
+const pts = await Beekon.history(new Date(Date.now() - 3600_000), new Date());
+
+// Cleanup.
+offState();
+offPos();
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `Beekon.init()` | One-time initialization. Idempotent. |
+| `Beekon.configure(config)` | Set sampling / Android notification config. |
+| `Beekon.start()` | Begin tracking. State → `starting` → `tracking`. |
+| `Beekon.stop()` | Stop tracking. Idempotent. State → `stopped`. |
+| `Beekon.shutdown()` | Final teardown. Most apps don't need this. |
+| `Beekon.history(from, to)` | Read persisted positions in range. |
+| `Beekon.onState(cb)` | Subscribe to state. Returns unsubscribe fn. |
+| `Beekon.onPosition(cb)` | Subscribe to gated positions. Returns unsubscribe fn. |
+
+Errors are thrown as `Error` instances with stable platform-agnostic codes:
+`NOT_INITIALISED`, `NOT_CONFIGURED`, `PERMISSION_DENIED`, `LOCATION_SERVICES_DISABLED` (iOS), `NO_GMS_AVAILABLE` (Android), `SERVICE_FAILED`, `INTERNAL_ERROR`.
+
+## Storage and retention
+
+The native SDKs persist every gated position 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.
+
+## License
+
+Proprietary — see [LICENSE.txt](LICENSE.txt). Evaluation use only without a separate written agreement with wayqteam.

package/android/build.gradle

@@ -0,0 +1,81 @@
+buildscript {
+  ext.BeekonRn = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return BeekonRn[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.wayq.beekonrn"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  // 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.1"
+  // Kotlin coroutines — required for collecting Beekon's StateFlow/SharedFlow.
+  // Beekon already depends on coroutines transitively, but declaring it here
+  // makes the dependency intent explicit.
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0"
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

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

@@ -0,0 +1,233 @@
+package com.wayq.beekonrn
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableArray
+import com.facebook.react.bridge.WritableMap
+import com.wayq.beekon.Beekon
+import com.wayq.beekon.BeekonConfig
+import com.wayq.beekon.BeekonError
+import com.wayq.beekon.BeekonState
+import com.wayq.beekon.NotificationConfig
+import com.wayq.beekon.PauseReason
+import com.wayq.beekon.Position
+import com.wayq.beekon.Preset
+import java.time.Instant
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.collect
+import kotlinx.coroutines.launch
+
+class BeekonRnModule(private val reactContext: ReactApplicationContext) :
+  NativeBeekonRnSpec(reactContext) {
+
+  // Default dispatcher (not Main.immediate) — Codegen's emitOnX is thread-safe
+  // and marshals to JS internally, so collecting on Main buys nothing and
+  // risks jank if any mapper does work. SupervisorJob so a single failure
+  // doesn't tear down siblings.
+  private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
+  private var stateJob: Job? = null
+  private var positionsJob: Job? = null
+
+  override fun initialize(promise: Promise) {
+    scope.launch {
+      try {
+        Beekon.initialize(reactContext.applicationContext)
+
+        // Idempotent: re-init replaces collectors. Native flows are hot
+        // (StateFlow / SharedFlow) so resubscription replays the latest value.
+        stateJob?.cancel()
+        positionsJob?.cancel()
+        stateJob = scope.launch {
+          Beekon.state.collect { s -> emitOnState(stateToWire(s)) }
+        }
+        positionsJob = scope.launch {
+          Beekon.positions.collect { p -> emitOnPosition(positionToWire(p)) }
+        }
+        promise.resolve(null)
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message ?: "init failed", t)
+      }
+    }
+  }
+
+  override fun configure(config: ReadableMap, promise: Promise) {
+    scope.launch {
+      try {
+        Beekon.configure(wireToConfig(config))
+        promise.resolve(null)
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message ?: "configure failed", t)
+      }
+    }
+  }
+
+  override fun start(promise: Promise) {
+    scope.launch {
+      try {
+        Beekon.start()
+        promise.resolve(null)
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message ?: "start failed", t)
+      }
+    }
+  }
+
+  override fun stop(promise: Promise) {
+    scope.launch {
+      try {
+        Beekon.stop()
+        promise.resolve(null)
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message ?: "stop failed", t)
+      }
+    }
+  }
+
+  override fun shutdown(promise: Promise) {
+    scope.launch {
+      try {
+        stateJob?.cancel()
+        positionsJob?.cancel()
+        Beekon.shutdown()
+        promise.resolve(null)
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message ?: "shutdown failed", t)
+      }
+    }
+  }
+
+  override fun history(fromMs: Double, toMs: Double, promise: Promise) {
+    scope.launch {
+      try {
+        val from = Instant.ofEpochMilli(fromMs.toLong())
+        val to = Instant.ofEpochMilli(toMs.toLong())
+        val positions = Beekon.history(from, to)
+        val arr: WritableArray = Arguments.createArray()
+        for (p in positions) arr.pushMap(positionToWire(p))
+        promise.resolve(arr)
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message ?: "history failed", t)
+      }
+    }
+  }
+
+  override fun invalidate() {
+    super.invalidate()
+    scope.cancel()
+  }
+
+  // ---------------------------------------------------------------------------
+  // Mappers (Wire ↔ Kotlin types)
+  // ---------------------------------------------------------------------------
+
+  private fun wireToConfig(map: ReadableMap): BeekonConfig {
+    val preset = when (map.getString("preset")) {
+      "saver" -> Preset.Saver
+      "precision" -> Preset.Precision
+      else -> Preset.Balanced
+    }
+    val distanceFilterMeters =
+      if (map.hasKey("distanceFilterMeters") && !map.isNull("distanceFilterMeters"))
+        map.getDouble("distanceFilterMeters").toFloat()
+      else null
+    val intervalMillis =
+      if (map.hasKey("intervalMillis") && !map.isNull("intervalMillis"))
+        map.getDouble("intervalMillis").toLong()
+      else null
+    val notifMap = map.getMap("androidNotification")
+      ?: throw IllegalArgumentException(
+        "androidNotification is required when running on Android"
+      )
+    val licenseKey =
+      if (map.hasKey("licenseKey") && !map.isNull("licenseKey"))
+        map.getString("licenseKey")
+      else null
+
+    return BeekonConfig(
+      preset = preset,
+      distanceFilterMeters = distanceFilterMeters,
+      intervalMillis = intervalMillis,
+      notification = wireToNotificationConfig(notifMap),
+      licenseKey = licenseKey,
+    )
+  }
+
+  private fun wireToNotificationConfig(map: ReadableMap): NotificationConfig {
+    val resName = map.getString("smallIconResName")
+      ?: throw IllegalArgumentException("smallIconResName is required")
+    val pkg = reactContext.packageName
+    val iconId = reactContext.resources.getIdentifier(resName, "drawable", pkg)
+    if (iconId == 0) {
+      throw IllegalArgumentException(
+        "drawable resource '$resName' not found in package '$pkg'"
+      )
+    }
+    return NotificationConfig(
+      channelId = map.getString("channelId")
+        ?: throw IllegalArgumentException("channelId is required"),
+      channelName = map.getString("channelName")
+        ?: throw IllegalArgumentException("channelName is required"),
+      notificationId = map.getInt("notificationId"),
+      title = map.getString("title")
+        ?: throw IllegalArgumentException("title is required"),
+      text = map.getString("text")
+        ?: throw IllegalArgumentException("text is required"),
+      smallIcon = iconId,
+    )
+  }
+
+  private fun positionToWire(p: Position): WritableMap {
+    val m = Arguments.createMap()
+    m.putDouble("lat", p.lat)
+    m.putDouble("lng", p.lng)
+    m.putDouble("accuracy", p.accuracy.toDouble())
+    m.putDouble("speed", p.speed.toDouble())
+    m.putDouble("bearing", p.bearing.toDouble())
+    m.putDouble("altitude", p.altitude)
+    m.putDouble("timestampMs", p.timestamp.toEpochMilli().toDouble())
+    return m
+  }
+
+  private fun stateToWire(s: BeekonState): WritableMap {
+    val m = Arguments.createMap()
+    when (s) {
+      BeekonState.Idle -> m.putString("type", "idle")
+      BeekonState.Starting -> m.putString("type", "starting")
+      BeekonState.Tracking -> m.putString("type", "tracking")
+      is BeekonState.Paused -> {
+        m.putString("type", "paused")
+        m.putString("pauseReason", pauseReasonToWire(s.reason))
+      }
+      BeekonState.Stopped -> m.putString("type", "stopped")
+    }
+    return m
+  }
+
+  private fun pauseReasonToWire(r: PauseReason): String = when (r) {
+    PauseReason.PermissionRevoked -> "permissionRevoked"
+    PauseReason.LocationDisabled -> "locationDisabled"
+    PauseReason.Unknown -> "unknown"
+  }
+
+  // Maps native error sealed types to stable JS-side codes. Same code strings
+  // on iOS so JS can switch on them platform-agnostically.
+  private fun errorCode(t: Throwable): String = when (t) {
+    is BeekonError.NotInitialised -> "NOT_INITIALISED"
+    is BeekonError.NotConfigured -> "NOT_CONFIGURED"
+    is BeekonError.PermissionDenied -> "PERMISSION_DENIED"
+    is BeekonError.NoGmsAvailable -> "NO_GMS_AVAILABLE"
+    is BeekonError.ServiceFailed -> "SERVICE_FAILED"
+    is BeekonError.InternalError -> "INTERNAL_ERROR"
+    else -> "INTERNAL_ERROR"
+  }
+
+  companion object {
+    const val NAME = NativeBeekonRnSpec.NAME
+  }
+}

package/android/src/main/java/com/wayq/beekonrn/BeekonRnPackage.kt

@@ -0,0 +1,31 @@
+package com.wayq.beekonrn
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import java.util.HashMap
+
+class BeekonRnPackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return if (name == BeekonRnModule.NAME) {
+      BeekonRnModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
+    mapOf(
+      BeekonRnModule.NAME to ReactModuleInfo(
+        name = BeekonRnModule.NAME,
+        className = BeekonRnModule.NAME,
+        canOverrideExistingModule = false,
+        needsEagerInit = false,
+        isCxxModule = false,
+        isTurboModule = true
+      )
+    )
+  }
+}

package/ios/BeekonRn.h

@@ -0,0 +1,5 @@
+#import <BeekonRnSpec/BeekonRnSpec.h>
+
+@interface BeekonRn : NSObject <NativeBeekonRnSpec>
+
+@end

package/ios/BeekonRn.mm

@@ -0,0 +1,80 @@
+#import "BeekonRn.h"
+// Auto-generated bridging header from the Swift impl in this same target.
+#import "BeekonRn-Swift.h"
+
+@implementation BeekonRn {
+  BeekonRnImpl *_impl;
+}
+
+- (instancetype)init {
+  self = [super init];
+  if (self) {
+    __weak __typeof(self) weakSelf = self;
+    _impl = [[BeekonRnImpl alloc]
+             initWithOnState:^(NSDictionary *_Nonnull s) {
+               [weakSelf emitOnState:s];
+             }
+                  onPosition:^(NSDictionary *_Nonnull p) {
+                    [weakSelf emitOnPosition:p];
+                  }];
+  }
+  return self;
+}
+
+- (void)initialize:(RCTPromiseResolveBlock)resolve
+            reject:(RCTPromiseRejectBlock)reject {
+  [_impl initializeWithResolver:resolve rejecter:reject];
+}
+
+- (void)configure:(JS::NativeBeekonRn::WireConfig &)config
+          resolve:(RCTPromiseResolveBlock)resolve
+           reject:(RCTPromiseRejectBlock)reject {
+  // Codegen passes the struct; round-trip through NSDictionary so the Swift
+  // side can decode generically without an iOS-specific spec import.
+  // (`config.toDictionary()` may also be available depending on RN version.)
+  NSDictionary *dict = @{
+    @"preset": config.preset() ?: @"balanced",
+    @"distanceFilterMeters": config.distanceFilterMeters().has_value()
+        ? @(config.distanceFilterMeters().value())
+        : (id)[NSNull null],
+    @"intervalMillis": config.intervalMillis().has_value()
+        ? @(config.intervalMillis().value())
+        : (id)[NSNull null],
+    @"licenseKey": config.licenseKey() ?: (id)[NSNull null],
+  };
+  // Note: iOS doesn't use androidNotification — passed but ignored.
+  [_impl configure:dict resolver:resolve rejecter:reject];
+}
+
+- (void)start:(RCTPromiseResolveBlock)resolve
+       reject:(RCTPromiseRejectBlock)reject {
+  [_impl startWithResolver:resolve rejecter:reject];
+}
+
+- (void)stop:(RCTPromiseResolveBlock)resolve
+      reject:(RCTPromiseRejectBlock)reject {
+  [_impl stopWithResolver:resolve rejecter:reject];
+}
+
+- (void)shutdown:(RCTPromiseResolveBlock)resolve
+          reject:(RCTPromiseRejectBlock)reject {
+  [_impl shutdownWithResolver:resolve rejecter:reject];
+}
+
+- (void)history:(double)fromMs
+           toMs:(double)toMs
+        resolve:(RCTPromiseResolveBlock)resolve
+         reject:(RCTPromiseRejectBlock)reject {
+  [_impl historyFromMs:fromMs toMs:toMs 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);
+}
+
++ (NSString *)moduleName {
+  return @"BeekonRn";
+}
+
+@end