@wayq/beekon-rn 0.0.1 → 0.0.5

package/src/internal/mappers.ts

@@ -1,50 +1,241 @@
 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 {
+  AccuracyMode,
+  ActivityType,
+  LocationQuality,
+  LocationTrigger,
+  MotionState,
+  StationaryMode,
+} from '../types/enums';
+import type {
+  BeekonGeofence,
+  GeofenceEvent,
+  Transition,
+} from '../types/geofence';
+import type { Location } from '../types/location';
+import type { BeekonState, StopReason } from '../types/state';
+import type { SyncFailure, SyncStatus } from '../types/sync';
+import { BeekonError, type BeekonErrorKind } from '../types/error';
+import type {
+  WireConfig,
+  WireGeofence,
+  WireGeofenceEvent,
+  WireKeyValue,
+  WireLocation,
+  WireState,
+  WireSyncStatus,
+} from '../NativeBeekonRn';
+
+// Config defaults. Kept here (not in the wire layer) so the native modules can
+// treat every wire field as present.
+const DEFAULTS = {
+  minTimeBetweenLocationsSeconds: 30,
+  minDistanceBetweenLocationsMeters: 100,
+  accuracyMode: 'balanced' as AccuracyMode,
+  whenStationary: 'pause' as StationaryMode,
+  stationaryRadiusMeters: 5,
+  detectActivity: false,
+  syncIntervalSeconds: 300,
+  syncBatchSize: 100,
+};
+
+// --- Public → wire ---------------------------------------------------------
+
+export function recordToEntries(
+  record: Record<string, string> | undefined
+): WireKeyValue[] {
+  if (!record) return [];
+  return Object.keys(record).map((key) => ({ key, value: record[key]! }));
+}
 
 export function configToWire(config: BeekonConfig): WireConfig {
+  const sync = config.sync;
+  return {
+    minTimeBetweenLocationsSeconds:
+      config.minTimeBetweenLocationsSeconds ??
+      DEFAULTS.minTimeBetweenLocationsSeconds,
+    minDistanceBetweenLocationsMeters:
+      config.minDistanceBetweenLocationsMeters ??
+      DEFAULTS.minDistanceBetweenLocationsMeters,
+    accuracyMode: config.accuracyMode ?? DEFAULTS.accuracyMode,
+    whenStationary: config.whenStationary ?? DEFAULTS.whenStationary,
+    stationaryRadiusMeters:
+      config.stationaryRadiusMeters ?? DEFAULTS.stationaryRadiusMeters,
+    detectActivity: config.detectActivity ?? DEFAULTS.detectActivity,
+    sync: sync
+      ? {
+          url: sync.url,
+          headers: recordToEntries(sync.headers),
+          intervalSeconds: sync.intervalSeconds ?? DEFAULTS.syncIntervalSeconds,
+          batchSize: sync.batchSize ?? DEFAULTS.syncBatchSize,
+        }
+      : undefined,
+    notification: config.notification
+      ? { title: config.notification.title, text: config.notification.text }
+      : undefined,
+  };
+}
+
+export function geofenceToWire(g: BeekonGeofence): WireGeofence {
   return {
-    preset: config.preset ?? 'balanced',
-    distanceFilterMeters: config.distanceFilterMeters,
-    intervalMillis: config.intervalMillis,
-    androidNotification: config.androidNotification,
-    licenseKey: config.licenseKey,
+    id: g.id,
+    lat: g.latitude,
+    lng: g.longitude,
+    radiusMeters: g.radiusMeters,
+    notifyOnEntry: g.notifyOnEntry ?? true,
+    notifyOnExit: g.notifyOnExit ?? true,
   };
 }
 
-export function wireToPosition(w: WirePosition): Position {
+// --- Wire → public ---------------------------------------------------------
+
+export function wireToLocation(w: WireLocation): Location {
   return {
-    lat: w.lat,
-    lng: w.lng,
+    id: w.id,
+    latitude: w.lat,
+    longitude: w.lng,
+    timestamp: new Date(w.timestampMs),
     accuracy: w.accuracy,
     speed: w.speed,
     bearing: w.bearing,
     altitude: w.altitude,
-    timestamp: new Date(w.timestampMs),
+    quality: oneOf<LocationQuality>(
+      w.quality,
+      ['ok', 'lowAccuracy', 'implausibleSpeed'],
+      'ok'
+    ),
+    trigger: oneOf<LocationTrigger>(
+      w.trigger,
+      ['interval', 'motion', 'checkIn', 'geofence', 'manual'],
+      'interval'
+    ),
+    motion: oneOf<MotionState>(
+      w.motion,
+      ['moving', 'stationary', 'unknown'],
+      'unknown'
+    ),
+    activity:
+      w.activity == null
+        ? null
+        : oneOf<ActivityType>(
+            w.activity,
+            [
+              'stationary',
+              'walking',
+              'running',
+              'cycling',
+              'automotive',
+              'unknown',
+            ],
+            'unknown'
+          ),
+    isMock: w.isMock,
+  };
+}
+
+export function wireToGeofence(w: WireGeofence): BeekonGeofence {
+  return {
+    id: w.id,
+    latitude: w.lat,
+    longitude: w.lng,
+    radiusMeters: w.radiusMeters,
+    notifyOnEntry: w.notifyOnEntry,
+    notifyOnExit: w.notifyOnExit,
   };
 }
 
-function toPauseReason(s: string | undefined): PauseReason {
-  if (s === 'permissionRevoked' || s === 'locationDisabled') return s;
-  return 'unknown';
+export function wireToGeofenceEvent(w: WireGeofenceEvent): GeofenceEvent {
+  return {
+    id: w.id,
+    geofenceId: w.geofenceId,
+    type: oneOf<Transition>(w.type, ['enter', 'exit'], 'enter'),
+    timestamp: new Date(w.timestampMs),
+  };
 }
 
 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:
+      // Forward-compat: treat unknown as idle rather than throwing.
+      return { kind: 'idle' };
+  }
+}
+
+export function wireToSyncStatus(w: WireSyncStatus): SyncStatus {
+  switch (w.type) {
+    case 'idle':
+      return { kind: 'idle' };
+    case 'pending':
+      return { kind: 'pending' };
+    case 'failed':
+      return { kind: 'failed', reason: toSyncFailure(w.failure) };
     default:
-      // Defensive fallback. Native should never emit an unknown state, but
-      // forward-compat: treat as idle rather than throwing.
       return { kind: 'idle' };
   }
 }
+
+function toStopReason(s: string | undefined): StopReason {
+  return oneOf<StopReason>(
+    s,
+    [
+      'user',
+      'permissionDenied',
+      'locationServicesDisabled',
+      'locationUnavailable',
+      'system',
+    ],
+    // The native side always populates the reason for a `stopped` state; an
+    // unknown/missing value means the wire contract was violated — fall back to
+    // `system` rather than throwing on a subscriber.
+    'system'
+  );
+}
+
+function toSyncFailure(s: string | undefined): SyncFailure {
+  return oneOf<SyncFailure>(s, ['auth', 'rejected'], 'rejected');
+}
+
+/** Validate a wire enum string against the known set, with a safe fallback. */
+function oneOf<T extends string>(
+  value: string | null | undefined,
+  allowed: readonly T[],
+  fallback: T
+): T {
+  return (allowed as readonly string[]).includes(value ?? '')
+    ? (value as T)
+    : fallback;
+}
+
+// --- Errors ----------------------------------------------------------------
+
+/**
+ * Re-throw a native promise rejection as a typed {@link BeekonError}. The native
+ * modules encode the kind in the error-code string (`STORAGE_FAILURE`,
+ * `INVALID_GEOFENCE`); 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 'STORAGE_FAILURE':
+      return 'storage';
+    case 'INVALID_GEOFENCE':
+      return 'invalidGeofence';
+    default:
+      return undefined;
+  }
+}

package/src/types/config.ts

@@ -1,42 +1,65 @@
-import type { Preset } from './preset';
+import type { AccuracyMode, StationaryMode } from './enums';
 
 /**
- * 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** — the platform
+ * requires every location foreground service to show a persistent notification.
+ * Both fields are optional; missing values fall back to native defaults.
+ * 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;
+export type NotificationConfig = {
+  /** Notification title. Defaults to "Tracking location". */
+  title?: string;
+  /** Notification body text. Defaults to no body. */
+  text?: string;
+};
+
+/**
+ * Server-upload configuration. Presence of {@link BeekonConfig.sync} turns on
+ * batched uploads of stored locations and geofence events; omitting it keeps
+ * tracking local-only.
+ */
+export type SyncConfig = {
+  /** Ingest endpoint — an `http` or `https` URL. */
+  url: string;
+  /** Extra HTTP headers sent with every upload (e.g. `Authorization`). */
+  headers?: Record<string, 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.
+   * Target seconds between uploads. The SDK enforces a 60s floor; background
+   * uploads may be delayed to the OS scheduler floor (~15 min). Default: `300`.
    */
-  smallIconResName: string;
+  intervalSeconds?: number;
+  /** Maximum locations per upload. Clamped to `[1, 1000]`. Default: `100`. */
+  batchSize?: number;
 };
 
+/**
+ * Tracking configuration. Every field is optional — `Beekon.start()` falls back
+ * to the previously persisted config, or to the documented defaults below if
+ * never configured.
+ *
+ * The two gate knobs (`minTimeBetweenLocationsSeconds`,
+ * `minDistanceBetweenLocationsMeters`) admit a fix only when **both** 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;
+  /** Minimum seconds between admitted fixes (10s floor). Default: `30`. */
+  minTimeBetweenLocationsSeconds?: number;
+  /** Minimum metres between admitted fixes. `0` disables it. Default: `100`. */
+  minDistanceBetweenLocationsMeters?: number;
+  /** Accuracy / battery preset. Default: `'balanced'`. */
+  accuracyMode?: AccuracyMode;
+  /** Behaviour while stationary. Default: `'pause'`. */
+  whenStationary?: StationaryMode;
+  /** Stationary exit-geofence radius, clamped to `[5, 1000]`. Default: `5`. */
+  stationaryRadiusMeters?: number;
   /**
-   * Required when running on Android. Ignored on iOS. The plugin throws
-   * `NOT_CONFIGURED` if missing on Android.
+   * Detect physical activity (walking, driving, …). Requires the
+   * `ACTIVITY_RECOGNITION` permission on Android and the `NSMotionUsageDescription`
+   * Info.plist key on iOS. Default: `false`.
    */
-  androidNotification?: AndroidNotificationConfig;
-  /** Optional license key. Reserved for future use. */
-  licenseKey?: string;
+  detectActivity?: boolean;
+  /** Server-upload configuration. Omit to keep tracking local-only. */
+  sync?: SyncConfig;
+  /** Android-only notification overrides. Ignored on iOS. */
+  notification?: NotificationConfig;
 };

package/src/types/enums.ts

@@ -0,0 +1,64 @@
+/**
+ * Value enums shared across the public API, expressed as string-literal unions
+ * (idiomatic TS). Each mirrors the like-named enum on both native SDKs by value;
+ * the wire layer carries them as plain strings and the mappers translate.
+ */
+
+/**
+ * Accuracy / battery-life preset for the location provider.
+ *
+ * - `'high'` — highest precision, highest battery cost (GPS-grade).
+ * - `'balanced'` — city-block precision, balanced battery (the default).
+ * - `'low'` — coarse, lowest battery.
+ */
+export type AccuracyMode = 'high' | 'balanced' | 'low';
+
+/**
+ * Behaviour while the device is stationary.
+ *
+ * - `'keepTracking'` — GPS stays on.
+ * - `'pause'` — GPS off while stationary, silent resume on movement (default).
+ * - `'pauseWithCheckIns'` — GPS off, but a location is recorded roughly every
+ *   15 minutes.
+ */
+export type StationaryMode = 'keepTracking' | 'pause' | 'pauseWithCheckIns';
+
+/**
+ * Why a {@link Location} was admitted and persisted.
+ *
+ * - `'interval'` — a scheduled fix that passed the time/distance gate.
+ * - `'motion'` — the device started or stopped moving.
+ * - `'checkIn'` — a periodic check-in while stationary.
+ * - `'geofence'` — a geofence crossing.
+ * - `'manual'` — an explicit request.
+ */
+export type LocationTrigger =
+  | 'interval'
+  | 'motion'
+  | 'checkIn'
+  | 'geofence'
+  | 'manual';
+
+/**
+ * The gate's quality verdict for a {@link Location}.
+ *
+ * - `'ok'` — passed the accuracy and speed checks.
+ * - `'lowAccuracy'` — worse than the usable accuracy threshold.
+ * - `'implausibleSpeed'` — an implausible jump from the previous fix.
+ */
+export type LocationQuality = 'ok' | 'lowAccuracy' | 'implausibleSpeed';
+
+/** Device motion when a {@link Location} was captured. */
+export type MotionState = 'moving' | 'stationary' | 'unknown';
+
+/**
+ * Detected physical activity. Only populated when
+ * {@link BeekonConfig.detectActivity} is enabled; otherwise `null`.
+ */
+export type ActivityType =
+  | 'stationary'
+  | 'walking'
+  | 'running'
+  | 'cycling'
+  | 'automotive'
+  | 'unknown';

package/src/types/error.ts

@@ -0,0 +1,25 @@
+/**
+ * Error kinds thrown across the bridge. These are the **only** errors Beekon
+ * throws — permission / location-services / lifecycle problems never throw; they
+ * surface on the `onState` stream as `stopped(reason)` instead.
+ *
+ * - `'storage'` — a local-store (SQLite) read/write failed. Thrown by
+ *   `getLocations()`, `deleteLocations()`, and `pendingUploadCount()`.
+ * - `'invalidGeofence'` — a geofence passed to `addGeofences()` failed
+ *   validation (empty/oversized id, or non-positive radius).
+ */
+export type BeekonErrorKind = 'storage' | 'invalidGeofence';
+
+/**
+ * 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/geofence.ts

@@ -0,0 +1,37 @@
+/**
+ * A circular geofence registered via `Beekon.addGeofences()`. Mirrors
+ * `BeekonGeofence` on both native SDKs. The SDK pages registrations
+ * automatically, so you may register more than the OS geofence limit.
+ */
+export type BeekonGeofence = {
+  /** Unique id, 1–100 characters. Re-adding an existing id replaces it. */
+  id: string;
+  /** Center latitude in degrees, WGS-84. */
+  latitude: number;
+  /** Center longitude in degrees, WGS-84. */
+  longitude: number;
+  /** Radius in metres. Must be `> 0`; `>= 100` is recommended for reliability. */
+  radiusMeters: number;
+  /** Emit an event on entry. Default: `true`. */
+  notifyOnEntry?: boolean;
+  /** Emit an event on exit. Default: `true`. */
+  notifyOnExit?: boolean;
+};
+
+/** Whether a {@link GeofenceEvent} marks entering or exiting a geofence. */
+export type Transition = 'enter' | 'exit';
+
+/**
+ * A geofence entry/exit crossing, delivered via `Beekon.onGeofenceEvent()`.
+ * Mirrors `GeofenceEvent` on both native SDKs.
+ */
+export type GeofenceEvent = {
+  /** Unique event id. Used as the dedup key on upload. */
+  id: string;
+  /** The {@link BeekonGeofence.id} that was crossed. */
+  geofenceId: string;
+  /** Whether the device entered or exited. */
+  type: Transition;
+  /** When the crossing happened. */
+  timestamp: Date;
+};

package/src/types/location.ts

@@ -0,0 +1,45 @@
+import type {
+  ActivityType,
+  LocationQuality,
+  LocationTrigger,
+  MotionState,
+} from './enums';
+
+/**
+ * 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.
+ *
+ * `id`, `latitude`, `longitude`, and `timestamp` are always present. The four
+ * optional numeric 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`). `activity` is `null` unless
+ * {@link BeekonConfig.detectActivity} is enabled.
+ */
+export type Location = {
+  /** Stable, unique storage id. Used as the dedup key on upload. */
+  id: string;
+  /** Latitude in degrees, WGS-84. */
+  latitude: number;
+  /** Longitude in degrees, WGS-84. */
+  longitude: number;
+  /** Time the OS provider reported this fix (not when JS received it). */
+  timestamp: Date;
+  /** 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;
+  /** The gate's quality verdict for this fix. */
+  quality: LocationQuality;
+  /** Why this fix was captured. */
+  trigger: LocationTrigger;
+  /** Device motion when this fix was captured. */
+  motion: MotionState;
+  /** Detected activity, or `null` unless activity detection is enabled. */
+  activity: ActivityType | null;
+  /** `true` if the OS flagged this fix as mock/simulated. */
+  isMock: boolean;
+};

package/src/types/state.ts

@@ -1,16 +1,32 @@
 /**
- * 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.
+ *
+ * - `'user'` — `Beekon.stop()` was called.
+ * - `'permissionDenied'` — location permission is missing or was revoked
+ *   (user-fixable in Settings).
+ * - `'locationServicesDisabled'` — system-wide location services are off
+ *   (user-fixable in Settings).
+ * - `'locationUnavailable'` — no usable location backend on this device (e.g.
+ *   Google Play Services absent/outdated on Android). Not user-fixable.
+ * - `'system'` — the OS terminated tracking (e.g. foreground-service kill,
+ *   or an unrecoverable internal error).
  */
-export type PauseReason = 'permissionRevoked' | 'locationDisabled' | 'unknown';
+export type StopReason =
+  | 'user'
+  | 'permissionDenied'
+  | 'locationServicesDisabled'
+  | 'locationUnavailable'
+  | '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)`. `start()` / `stop()` never
+ * throw — this stream is the single source of truth for whether tracking is
+ * active and why it stopped.
  */
 export type BeekonState =
   | { kind: 'idle' }
-  | { kind: 'starting' }
   | { kind: 'tracking' }
-  | { kind: 'paused'; reason: PauseReason }
-  | { kind: 'stopped' };
+  | { kind: 'stopped'; reason: StopReason };

package/src/types/sync.ts

@@ -0,0 +1,23 @@
+/**
+ * Why a server upload failed terminally. Mirrors `SyncFailure` on both
+ * platforms.
+ *
+ * - `'auth'` — `401`/`403`; credentials were rejected. Refresh them (via
+ *   `Beekon.configure()` with new `sync.headers`) and sync resumes.
+ * - `'rejected'` — `400`/`422`; the server rejected the payload. A payload bug;
+ *   it won't self-resolve.
+ */
+export type SyncFailure = 'auth' | 'rejected';
+
+/**
+ * Upload health, delivered via `Beekon.onSyncStatus()`. Mirrors the native
+ * `SyncStatus` sealed type. Use the `kind` field as a discriminator.
+ *
+ * - `'idle'` — caught up, or sync is not configured.
+ * - `'pending'` — uploading or retrying (healthy).
+ * - `'failed'` — a terminal failure the app must act on.
+ */
+export type SyncStatus =
+  | { kind: 'idle' }
+  | { kind: 'pending' }
+  | { kind: 'failed'; reason: SyncFailure };