@wayq/beekon-rn 0.0.3 → 0.0.5

package/src/beekon.ts

@@ -1,111 +1,281 @@
 import NativeBeekon from './NativeBeekonRn';
 import type { BeekonConfig } from './types/config';
-import type { BeekonState } from './types/state';
+import type { BeekonGeofence, GeofenceEvent } from './types/geofence';
 import type { Location } from './types/location';
+import type { BeekonState } from './types/state';
+import type { SyncStatus } from './types/sync';
 import {
   configToWire,
+  geofenceToWire,
+  recordToEntries,
+  rethrowAsBeekonError,
+  wireToGeofence,
+  wireToGeofenceEvent,
   wireToLocation,
   wireToState,
-  rethrowAsBeekonError,
+  wireToSyncStatus,
 } from './internal/mappers';
 
+type Listener<T> = (value: T) => void;
+
+/**
+ * Fans the four native EventEmitters out to multiple JS subscribers and adds
+ * replay-1 semantics for `state` / `syncStatus` (RN EventEmitters don't replay,
+ * so we cache the latest value and hand it to new subscribers immediately —
+ * matching the native StateFlow / AsyncStream contract). `location` /
+ * `geofenceEvent` are plain fan-out with no replay.
+ *
+ * Native subscriptions are opened once, on first use, and kept for the app
+ * lifetime — the native module collects its flows continuously regardless, so
+ * this only keeps the JS cache warm.
+ */
+class EventHub {
+  private subscribed = false;
+  private readonly stateListeners = new Set<Listener<BeekonState>>();
+  private readonly locationListeners = new Set<Listener<Location>>();
+  private readonly geofenceListeners = new Set<Listener<GeofenceEvent>>();
+  private readonly syncListeners = new Set<Listener<SyncStatus>>();
+  private lastState: BeekonState | undefined;
+  private lastSyncStatus: SyncStatus | undefined;
+
+  /** Idempotent: opens the native subscriptions the first time it is called. */
+  ensureSubscribed(): void {
+    if (this.subscribed) return;
+    this.subscribed = true;
+    NativeBeekon.onState((w) => {
+      const s = wireToState(w);
+      this.lastState = s;
+      this.stateListeners.forEach((cb) => cb(s));
+    });
+    NativeBeekon.onLocation((w) => {
+      const l = wireToLocation(w);
+      this.locationListeners.forEach((cb) => cb(l));
+    });
+    NativeBeekon.onGeofenceEvent((w) => {
+      const g = wireToGeofenceEvent(w);
+      this.geofenceListeners.forEach((cb) => cb(g));
+    });
+    NativeBeekon.onSyncStatus((w) => {
+      const s = wireToSyncStatus(w);
+      this.lastSyncStatus = s;
+      this.syncListeners.forEach((cb) => cb(s));
+    });
+  }
+
+  onState(cb: Listener<BeekonState>): () => void {
+    this.ensureSubscribed();
+    this.stateListeners.add(cb);
+    if (this.lastState !== undefined) cb(this.lastState);
+    return () => {
+      this.stateListeners.delete(cb);
+    };
+  }
+
+  onLocation(cb: Listener<Location>): () => void {
+    this.ensureSubscribed();
+    this.locationListeners.add(cb);
+    return () => {
+      this.locationListeners.delete(cb);
+    };
+  }
+
+  onGeofenceEvent(cb: Listener<GeofenceEvent>): () => void {
+    this.ensureSubscribed();
+    this.geofenceListeners.add(cb);
+    return () => {
+      this.geofenceListeners.delete(cb);
+    };
+  }
+
+  onSyncStatus(cb: Listener<SyncStatus>): () => void {
+    this.ensureSubscribed();
+    this.syncListeners.add(cb);
+    if (this.lastSyncStatus !== undefined) cb(this.lastSyncStatus);
+    return () => {
+      this.syncListeners.delete(cb);
+    };
+  }
+}
+
 /**
- * Public facade for the Beekon SDK. Mirrors the native APIs:
+ * Public facade for the Beekon SDK — a 1:1 mirror of the native APIs:
  *
  * - Android: `in.wayq.beekon.Beekon` (object)
  * - iOS:     `BeekonKit.Beekon.shared` (actor)
  *
- * Lifecycle: `configure(config)` → `start()` → ... → `stop()` (idempotent).
- * Subscribe to `onState` / `onLocation` for live updates; query
- * `history(from, to)` for persisted fixes.
+ * There is **no `initialize()`** — the native SDKs auto-initialize. Lifecycle:
+ * `configure(config)` (optional; defaults 30s / 100m) → `start()` → … →
+ * `stop()`. `start()` / `stop()` **never throw** — `onState` is the single
+ * source of truth for whether tracking is active and why it stopped.
  *
- * **Threading:** Methods are safe to call from any JS context. Subscribers'
+ * **Threading:** methods are safe to call from any JS context; subscriber
  * callbacks fire on the JS thread.
  *
- * **Persistence invariant:** the SDK persists every gated fix natively; JS is
- * a passive observer. In background, the JS engine is not guaranteed to be
- * alive — for past fixes, use `history()`.
+ * **Persistence invariant:** the SDK persists every gated fix natively; JS is a
+ * passive observer that is not guaranteed to be alive in the background. For
+ * past fixes use `getLocations()`.
  */
 class BeekonImpl {
+  private readonly hub = new EventHub();
+
   /**
    * Set tracking parameters. Optional — `start()` falls back to the previously
-   * persisted config or the SDK default (30s / 100m) if never configured.
-   *
-   * While tracking, the new gate values take effect on the next admitted fix
-   * without restarting the underlying location subscription.
+   * persisted config, or the SDK defaults if never configured. While tracking,
+   * gate thresholds take effect on the next admitted fix without restarting the
+   * location subscription; `accuracyMode` applies on the next `start()`.
    */
   async configure(config: BeekonConfig): Promise<void> {
+    this.hub.ensureSubscribed();
+    await NativeBeekon.configure(configToWire(config));
+  }
+
+  /**
+   * Begin tracking. Never throws — observe `onState` for the outcome
+   * (`stopped(reason)` on a permission / services / system problem). Beekon
+   * ships no permission API: request permissions in the host app, then observe
+   * `onState`.
+   */
+  async start(): Promise<void> {
+    this.hub.ensureSubscribed();
+    await NativeBeekon.start();
+  }
+
+  /** Stop tracking. Idempotent. Registered geofences keep firing. */
+  async stop(): Promise<void> {
+    this.hub.ensureSubscribed();
+    await NativeBeekon.stop();
+  }
+
+  /**
+   * Resume tracking if a session was active before the app was terminated. A
+   * no-op if the user explicitly stopped. Call early in app startup.
+   *
+   * Note: on a background relaunch the JS engine may not be running, so true
+   * cold-launch resume also requires native host wiring (Android: call
+   * `Beekon.start()` from `Application.onCreate`; iOS: `registerBackgroundTasks`
+   * in the AppDelegate). See the README.
+   */
+  async resumeIfNeeded(): Promise<void> {
+    this.hub.ensureSubscribed();
+    await NativeBeekon.resumeIfNeeded();
+  }
+
+  /**
+   * Read persisted fixes in the inclusive range `[from, to]`, oldest first.
+   * Reads come from the SDK's local storage (Room on Android, GRDB on iOS) — the
+   * source of truth even when JS was asleep. With sync enabled, rows are deleted
+   * locally once the server accepts them, so this returns only un-uploaded fixes.
+   *
+   * Throws `BeekonError` with kind `'storage'` on a database read failure.
+   */
+  async getLocations(from: Date, to: Date): Promise<Location[]> {
     try {
-      await NativeBeekon.configure(configToWire(config));
+      const wires = await NativeBeekon.getLocations(
+        from.getTime(),
+        to.getTime()
+      );
+      return wires.map(wireToLocation);
     } catch (e) {
       rethrowAsBeekonError(e);
     }
   }
 
   /**
-   * Begin tracking. State transitions to `tracking`.
-   *
-   * Throws a `BeekonError` with kind:
-   * - `'permissionDenied'` — location permission not granted.
-   * - `'locationServicesDisabled'` — system location services off (or GMS
-   *   unavailable on Android).
+   * Delete stored locations captured at or before `before` (all of them when
+   * `before` is omitted). Returns the number of rows removed. Throws
+   * `BeekonError` with kind `'storage'` on a failure.
    */
-  async start(): Promise<void> {
+  async deleteLocations(before?: Date): Promise<number> {
     try {
-      await NativeBeekon.start();
+      // Negative is the wire sentinel for "delete all" (see NativeBeekonRn.ts).
+      return await NativeBeekon.deleteLocations(before ? before.getTime() : -1);
     } catch (e) {
       rethrowAsBeekonError(e);
     }
   }
 
-  /** Stop tracking. Idempotent. State transitions to `stopped(user)`. */
-  async stop(): Promise<void> {
+  /**
+   * The number of stored locations not yet uploaded. Throws `BeekonError` with
+   * kind `'storage'` on a failure.
+   */
+  async pendingUploadCount(): Promise<number> {
     try {
-      await NativeBeekon.stop();
+      return await NativeBeekon.pendingUploadCount();
     } catch (e) {
       rethrowAsBeekonError(e);
     }
   }
 
   /**
-   * Read persisted fixes in the time range [from, to]. Returns fixes in
-   * chronological order. Reads come from the SDK's local storage (Room on
-   * Android, GRDB on iOS) — the source of truth even when JS was asleep.
-   *
-   * Retention: fixes older than 7 days OR beyond the most recent 100K are
-   * pruned automatically.
-   *
-   * Throws `BeekonError` with kind `'storageFailure'` on database read failure.
+   * Request an immediate upload. Best-effort and self-retrying; a no-op when
+   * sync is not configured.
    */
-  async history(from: Date, to: Date): Promise<Location[]> {
+  async sync(): Promise<void> {
+    await NativeBeekon.sync();
+  }
+
+  /** Set custom key/value fields (e.g. `user_id`) included with every upload. */
+  async setExtras(extras: Record<string, string>): Promise<void> {
+    await NativeBeekon.setExtras(recordToEntries(extras));
+  }
+
+  /**
+   * Register geofences. Re-adding an `id` replaces the existing one. Throws
+   * `BeekonError` with kind `'invalidGeofence'` if any entry fails validation —
+   * none are added when one is invalid.
+   */
+  async addGeofences(geofences: BeekonGeofence[]): Promise<void> {
     try {
-      const wires = await NativeBeekon.history(from.getTime(), to.getTime());
-      return wires.map(wireToLocation);
+      await NativeBeekon.addGeofences(geofences.map(geofenceToWire));
     } catch (e) {
       rethrowAsBeekonError(e);
     }
   }
 
+  /** Unregister geofences by id. Unknown ids are ignored. */
+  async removeGeofences(ids: string[]): Promise<void> {
+    await NativeBeekon.removeGeofences(ids);
+  }
+
+  /** The currently registered geofences. */
+  async listGeofences(): Promise<BeekonGeofence[]> {
+    const wires = await NativeBeekon.listGeofences();
+    return wires.map(wireToGeofence);
+  }
+
   /**
-   * Subscribe to state transitions. Returns an unsubscribe function. The
-   * current state is delivered to new subscribers immediately (replay-1
-   * semantics, matching the native `state` flow / AsyncStream).
+   * Subscribe to tracking-state transitions (`idle` / `tracking` /
+   * `stopped(reason)`). The current state is delivered to new subscribers
+   * immediately (replay-1). Returns an unsubscribe function.
    */
   onState(cb: (s: BeekonState) => void): () => void {
-    const subscription = NativeBeekon.onState((wire) => cb(wireToState(wire)));
-    return () => subscription.remove();
+    return this.hub.onState(cb);
   }
 
   /**
-   * Subscribe to gated locations as they arrive. Returns an unsubscribe
-   * function. Broadcast (no replay) — only delivers while the JS engine is
-   * alive. For fixes emitted while JS was asleep, use `history()`.
+   * Subscribe to gated locations as they arrive. Broadcast (no replay) — only
+   * delivers while the JS engine is alive. For fixes emitted while JS was
+   * asleep, use `getLocations()`. Returns an unsubscribe function.
    */
   onLocation(cb: (l: Location) => void): () => void {
-    const subscription = NativeBeekon.onLocation((wire) =>
-      cb(wireToLocation(wire))
-    );
-    return () => subscription.remove();
+    return this.hub.onLocation(cb);
+  }
+
+  /**
+   * Subscribe to geofence enter / exit crossings. Broadcast (no replay).
+   * Returns an unsubscribe function.
+   */
+  onGeofenceEvent(cb: (e: GeofenceEvent) => void): () => void {
+    return this.hub.onGeofenceEvent(cb);
+  }
+
+  /**
+   * Subscribe to upload health (`idle` / `pending` / `failed(reason)`). The
+   * current status is delivered to new subscribers immediately (replay-1).
+   * Returns an unsubscribe function.
+   */
+  onSyncStatus(cb: (s: SyncStatus) => void): () => void {
+    return this.hub.onSyncStatus(cb);
   }
 }
 

package/src/index.tsx

@@ -1,5 +1,24 @@
 export { Beekon } from './beekon';
-export type { BeekonConfig, AndroidNotificationConfig } from './types/config';
-export type { BeekonState, StopReason } from './types/state';
+
+export type {
+  BeekonConfig,
+  SyncConfig,
+  NotificationConfig,
+} from './types/config';
+export type {
+  AccuracyMode,
+  StationaryMode,
+  LocationTrigger,
+  LocationQuality,
+  MotionState,
+  ActivityType,
+} from './types/enums';
 export type { Location } from './types/location';
+export type {
+  BeekonGeofence,
+  GeofenceEvent,
+  Transition,
+} from './types/geofence';
+export type { BeekonState, StopReason } from './types/state';
+export type { SyncStatus, SyncFailure } from './types/sync';
 export { BeekonError, type BeekonErrorKind } from './types/error';

package/src/internal/mappers.ts

@@ -1,43 +1,156 @@
 import type { BeekonConfig } from '../types/config';
-import type { BeekonState, StopReason } from '../types/state';
+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, WireLocation, WireState } from '../NativeBeekonRn';
+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,
+};
 
-const DEFAULT_INTERVAL_SECONDS = 30;
-const DEFAULT_DISTANCE_METERS = 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 {
-    intervalSeconds: config.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS,
-    distanceMeters: config.distanceMeters ?? DEFAULT_DISTANCE_METERS,
-    androidNotification: config.androidNotification,
+    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 {
+    id: g.id,
+    lat: g.latitude,
+    lng: g.longitude,
+    radiusMeters: g.radiusMeters,
+    notifyOnEntry: g.notifyOnEntry ?? true,
+    notifyOnExit: g.notifyOnExit ?? true,
+  };
+}
+
+// --- 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,
   };
 }
 
-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 wireToGeofence(w: WireGeofence): BeekonGeofence {
+  return {
+    id: w.id,
+    latitude: w.lat,
+    longitude: w.lng,
+    radiusMeters: w.radiusMeters,
+    notifyOnEntry: w.notifyOnEntry,
+    notifyOnExit: w.notifyOnExit,
+  };
+}
+
+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 {
@@ -54,11 +167,57 @@ export function wireToState(w: WireState): BeekonState {
   }
 }
 
+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:
+      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 `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.
+ * 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;
@@ -72,12 +231,10 @@ export function rethrowAsBeekonError(e: unknown): never {
 
 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';
+      return 'storage';
+    case 'INVALID_GEOFENCE':
+      return 'invalidGeofence';
     default:
       return undefined;
   }