@wayq/beekon-rn 0.0.1 → 0.0.3

package/src/internal/mappers.ts

@@ -1,19 +1,21 @@
 import type { BeekonConfig } from '../types/config';
-import type { BeekonState, PauseReason } from '../types/state';
-import type { Position } from '../types/position';
-import type { WireConfig, WirePosition, WireState } from '../NativeBeekonRn';
+import type { BeekonState, StopReason } from '../types/state';
+import type { Location } from '../types/location';
+import { BeekonError, type BeekonErrorKind } from '../types/error';
+import type { WireConfig, WireLocation, WireState } from '../NativeBeekonRn';
+
+const DEFAULT_INTERVAL_SECONDS = 30;
+const DEFAULT_DISTANCE_METERS = 100;
 
 export function configToWire(config: BeekonConfig): WireConfig {
   return {
-    preset: config.preset ?? 'balanced',
-    distanceFilterMeters: config.distanceFilterMeters,
-    intervalMillis: config.intervalMillis,
+    intervalSeconds: config.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS,
+    distanceMeters: config.distanceMeters ?? DEFAULT_DISTANCE_METERS,
     androidNotification: config.androidNotification,
-    licenseKey: config.licenseKey,
   };
 }
 
-export function wireToPosition(w: WirePosition): Position {
+export function wireToLocation(w: WireLocation): Location {
   return {
     lat: w.lat,
     lng: w.lng,
@@ -25,26 +27,58 @@ export function wireToPosition(w: WirePosition): Position {
   };
 }
 
-function toPauseReason(s: string | undefined): PauseReason {
-  if (s === 'permissionRevoked' || s === 'locationDisabled') return s;
-  return 'unknown';
+function toStopReason(s: string | undefined): StopReason {
+  switch (s) {
+    case 'user':
+    case 'permissionDenied':
+    case 'locationServicesDisabled':
+    case 'system':
+      return s;
+    default:
+      // Defensive — native should never emit an unknown reason.
+      return 'user';
+  }
 }
 
 export function wireToState(w: WireState): BeekonState {
   switch (w.type) {
     case 'idle':
       return { kind: 'idle' };
-    case 'starting':
-      return { kind: 'starting' };
     case 'tracking':
       return { kind: 'tracking' };
-    case 'paused':
-      return { kind: 'paused', reason: toPauseReason(w.pauseReason) };
     case 'stopped':
-      return { kind: 'stopped' };
+      return { kind: 'stopped', reason: toStopReason(w.stopReason) };
     default:
-      // Defensive fallback. Native should never emit an unknown state, but
-      // forward-compat: treat as idle rather than throwing.
+      // Forward-compat: treat unknown as idle rather than throwing.
       return { kind: 'idle' };
   }
 }
+
+/**
+ * Re-throw a native promise rejection as a typed `BeekonError`. Native modules
+ * encode the kind in the error code string (`PERMISSION_DENIED`,
+ * `LOCATION_SERVICES_DISABLED`, `STORAGE_FAILURE`); anything else falls
+ * through as the original error.
+ */
+export function rethrowAsBeekonError(e: unknown): never {
+  const code = (e as { code?: string } | undefined)?.code;
+  const message = (e as { message?: string } | undefined)?.message ?? String(e);
+  const kind = codeToKind(code);
+  if (kind) {
+    throw new BeekonError(kind, message);
+  }
+  throw e;
+}
+
+function codeToKind(code: string | undefined): BeekonErrorKind | undefined {
+  switch (code) {
+    case 'PERMISSION_DENIED':
+      return 'permissionDenied';
+    case 'LOCATION_SERVICES_DISABLED':
+      return 'locationServicesDisabled';
+    case 'STORAGE_FAILURE':
+      return 'storageFailure';
+    default:
+      return undefined;
+  }
+}

package/src/types/config.ts

@@ -1,42 +1,33 @@
-import type { Preset } from './preset';
-
 /**
- * Foreground service notification config — required when running on Android
- * because Android 8+ requires a persistent notification while a foreground
- * service is active. Ignored on iOS.
+ * Foreground-service notification overrides. Android-only — required by the
+ * platform because every location foreground service must show a persistent
+ * notification. All fields are optional; missing values resolve at runtime
+ * against the host app's label and icon. Ignored on iOS.
  */
 export type AndroidNotificationConfig = {
-  /** NotificationChannel id (Android 8+). */
-  channelId: string;
-  /** User-visible channel display name. */
-  channelName: string;
-  /** Foreground notification id. Must be > 0. */
-  notificationId: number;
-  /** Notification title shown in the status bar. */
-  title: string;
-  /** Notification body text. */
-  text: string;
+  /** Notification title. Defaults to "Location active". */
+  title?: string;
+  /** Notification body text. Defaults to the host app's label. */
+  text?: string;
   /**
-   * Drawable resource name for the notification icon (e.g. `ic_notification`).
-   * Resolved at runtime via `Resources.getIdentifier()` against the host app's
-   * `res/drawable*` folders. Pass the resource name without extension or
-   * `R.drawable.` prefix.
+   * Drawable resource name (e.g. `ic_notification`) — resolved at runtime via
+   * `Resources.getIdentifier()` against the host app's `res/drawable*` folders.
+   * Pass the resource name without extension or `R.drawable.` prefix. Defaults
+   * to the host app's `applicationInfo.icon`.
    */
-  smallIconResName: string;
+  smallIconResName?: string;
 };
 
+/**
+ * Tracking configuration. Two knobs: a minimum time interval and a minimum
+ * distance between emitted fixes. A fix is admitted only when **both** gates
+ * are satisfied. Pass `0` to disable a gate.
+ */
 export type BeekonConfig = {
-  /** Sampling preset. Default: `'balanced'`. */
-  preset?: Preset;
-  /** Override the preset's distance gate (meters). */
-  distanceFilterMeters?: number;
-  /** Override the preset's interval (milliseconds). */
-  intervalMillis?: number;
-  /**
-   * Required when running on Android. Ignored on iOS. The plugin throws
-   * `NOT_CONFIGURED` if missing on Android.
-   */
+  /** Minimum seconds between admitted fixes. Default: `30`. `0` disables the time gate. */
+  intervalSeconds?: number;
+  /** Minimum metres between admitted fixes. Default: `100`. `0` disables the distance gate. */
+  distanceMeters?: number;
+  /** Android-only notification overrides. Ignored on iOS. */
   androidNotification?: AndroidNotificationConfig;
-  /** Optional license key. Reserved for future use. */
-  licenseKey?: string;
 };

package/src/types/error.ts

@@ -0,0 +1,22 @@
+/**
+ * Error kinds thrown from `Beekon.start()` / `Beekon.history()`. Match the
+ * native `BeekonError` cases byte-for-byte.
+ */
+export type BeekonErrorKind =
+  | 'permissionDenied'
+  | 'locationServicesDisabled'
+  | 'storageFailure';
+
+/**
+ * Typed error surfaced from the bridge. The native module rejects promises
+ * with the kind encoded as the error code; the facade re-wraps into this.
+ */
+export class BeekonError extends Error {
+  public readonly kind: BeekonErrorKind;
+
+  constructor(kind: BeekonErrorKind, message: string) {
+    super(message);
+    this.name = 'BeekonError';
+    this.kind = kind;
+  }
+}

package/src/types/location.ts

@@ -0,0 +1,25 @@
+/**
+ * A single location fix as emitted by the native SDK after gating. Fields map
+ * 1:1 to `in.wayq.beekon.Location` on Android and `BeekonKit.Location` on iOS.
+ *
+ * `lat`, `lng`, and `timestamp` are always present. The four optional fields
+ * are `null` when the OS did not report a value — the SDK never invents a
+ * value to mask absence (e.g. a stationary device returns `bearing === null`,
+ * not `0`).
+ */
+export type Location = {
+  /** Latitude in degrees, WGS-84. */
+  lat: number;
+  /** Longitude in degrees, WGS-84. */
+  lng: number;
+  /** Horizontal accuracy in meters (1-sigma); `null` if unreported. */
+  accuracy: number | null;
+  /** Speed in m/s; `null` if unreported. */
+  speed: number | null;
+  /** Bearing in degrees `[0, 360)` clockwise from true north; `null` if unreported. */
+  bearing: number | null;
+  /** Altitude in meters above the WGS-84 ellipsoid; `null` if unreported. */
+  altitude: number | null;
+  /** Time the OS provider reported this fix (not when JS received it). */
+  timestamp: Date;
+};

package/src/types/state.ts

@@ -1,16 +1,22 @@
 /**
- * Why tracking is paused. Names match the native `PauseReason` enum on both
- * platforms byte-for-byte.
+ * Reason a tracking session ended. Mirrors `StopReason` on both platforms.
+ *
+ * `'system'` is Android-only — surfaces when the OS terminates the foreground
+ * service (memory pressure, force-stop). iOS will never emit `'system'`.
  */
-export type PauseReason = 'permissionRevoked' | 'locationDisabled' | 'unknown';
+export type StopReason =
+  | 'user'
+  | 'permissionDenied'
+  | 'locationServicesDisabled'
+  | 'system';
 
 /**
- * Tracking state. Mirrors the native `BeekonState` sealed hierarchy on both
+ * Tracking state. Mirrors the native `BeekonState` sealed type on both
  * platforms. Use the `kind` field as a discriminator.
+ *
+ * Lifecycle: `idle → tracking → stopped(reason)`.
  */
 export type BeekonState =
   | { kind: 'idle' }
-  | { kind: 'starting' }
   | { kind: 'tracking' }
-  | { kind: 'paused'; reason: PauseReason }
-  | { kind: 'stopped' };
+  | { kind: 'stopped'; reason: StopReason };

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

@@ -1,233 +0,0 @@
-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/lib/module/types/position.js

@@ -1,2 +0,0 @@
-"use strict";
-//# sourceMappingURL=position.js.map

package/lib/module/types/preset.js

@@ -1,2 +0,0 @@
-"use strict";
-//# sourceMappingURL=preset.js.map

package/lib/module/types/preset.js.map

@@ -1 +0,0 @@
-{"version":3,"names":[],"sourceRoot":"../../../src","sources":["types/preset.ts"],"mappings":"","ignoreList":[]}

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

@@ -1,24 +0,0 @@
-/**
- * A single location fix as emitted by the native SDK after gating. Fields map
- * 1:1 to `com.wayq.beekon.Position` on Android and `Beekon.Position` on iOS.
- *
- * The SDK does NOT smooth or filter positions beyond the gate — values are
- * forwarded as the OS provider reported them (raw passthrough).
- */
-export type Position = {
-    /** Latitude in degrees, WGS-84. */
-    lat: number;
-    /** Longitude in degrees, WGS-84. */
-    lng: number;
-    /** Horizontal accuracy in meters (1-sigma). */
-    accuracy: number;
-    /** Speed in m/s. May be 0 if the OS provider doesn't supply it. */
-    speed: number;
-    /** Bearing in degrees clockwise from true north. */
-    bearing: number;
-    /** Altitude in meters above the WGS-84 ellipsoid. */
-    altitude: number;
-    /** Time the OS provider reported this fix (not when JS received it). */
-    timestamp: Date;
-};
-//# sourceMappingURL=position.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../../src/types/position.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC"}

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

@@ -1,12 +0,0 @@
-/**
- * Sampling preset. Determines the gating interval and distance threshold the
- * native SDK uses before emitting a position. Per `docs/REQUIREMENTS.md`:
- *
- * | Preset    | Interval | Distance | Battery (typical) |
- * |-----------|----------|----------|-------------------|
- * | saver     | 60_000ms | 150 m    | 3–8%              |
- * | balanced  | 30_000ms | 100 m    | 5–10%             |
- * | precision | 10_000ms | 30 m     | 15–25%            |
- */
-export type Preset = 'saver' | 'balanced' | 'precision';
-//# sourceMappingURL=preset.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"preset.d.ts","sourceRoot":"","sources":["../../../../src/types/preset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,CAAC"}

package/src/types/position.ts

@@ -1,23 +0,0 @@
-/**
- * A single location fix as emitted by the native SDK after gating. Fields map
- * 1:1 to `com.wayq.beekon.Position` on Android and `Beekon.Position` on iOS.
- *
- * The SDK does NOT smooth or filter positions beyond the gate — values are
- * forwarded as the OS provider reported them (raw passthrough).
- */
-export type Position = {
-  /** Latitude in degrees, WGS-84. */
-  lat: number;
-  /** Longitude in degrees, WGS-84. */
-  lng: number;
-  /** Horizontal accuracy in meters (1-sigma). */
-  accuracy: number;
-  /** Speed in m/s. May be 0 if the OS provider doesn't supply it. */
-  speed: number;
-  /** Bearing in degrees clockwise from true north. */
-  bearing: number;
-  /** Altitude in meters above the WGS-84 ellipsoid. */
-  altitude: number;
-  /** Time the OS provider reported this fix (not when JS received it). */
-  timestamp: Date;
-};

package/src/types/preset.ts

@@ -1,11 +0,0 @@
-/**
- * Sampling preset. Determines the gating interval and distance threshold the
- * native SDK uses before emitting a position. Per `docs/REQUIREMENTS.md`:
- *
- * | Preset    | Interval | Distance | Battery (typical) |
- * |-----------|----------|----------|-------------------|
- * | saver     | 60_000ms | 150 m    | 3–8%              |
- * | balanced  | 30_000ms | 100 m    | 5–10%             |
- * | precision | 10_000ms | 30 m     | 15–25%            |
- */
-export type Preset = 'saver' | 'balanced' | 'precision';