@wayq/beekon-rn 0.0.1 → 0.0.5

package/scripts/fetch-beekonkit.sh

@@ -13,9 +13,12 @@
 
 set -euo pipefail
 
-VERSION="0.0.1"
+VERSION="0.0.5"
 URL="https://github.com/wayqteam/beekon-ios-binary/releases/download/v${VERSION}/BeekonKit.xcframework.zip"
-EXPECTED_SHA="f7bd79a6d61994977318daa6d722866abd0a61d7d7e5834ab5307df39b6ee60e"
+# SHA256 of the v0.0.5 BeekonKit.xcframework.zip. Matches the SwiftPM
+# `binaryTarget` checksum in beekon-ios-binary's Package.swift at tag v0.0.5
+# (SwiftPM's compute-checksum is the SHA256 of the zip).
+EXPECTED_SHA="437bf493d7de19d8df9599da097be162796a8304eb2d7826cf2505c33d4603f7"
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 DEST_DIR="${ROOT}/ios/Frameworks"

package/src/NativeBeekonRn.ts

@@ -1,64 +1,150 @@
 /**
- * Codegen TurboModule spec — DO NOT export Wire* types from `src/index.tsx`.
- * The public TS API in `src/beekon.ts` and `src/types/` is what consumers use;
- * mappers in `src/internal/mappers.ts` convert between the two.
+ * Codegen TurboModule spec — the single source React Native's Codegen reads to
+ * generate the native interface. **DO NOT export Wire* types from
+ * `src/index.tsx`.** The public TS API in `src/beekon.ts` and `src/types/` is
+ * what consumers use; mappers in `src/internal/mappers.ts` convert between the
+ * two.
  *
- * Wire types are flat (primitives + nested flat objects) because Codegen's
- * TS-to-Kotlin/ObjC type derivation has limited support for unions and
- * recursive structures. State variants are encoded as a `type` discriminator
- * string with sibling fields nullable per variant.
+ * Wire types are deliberately **flat** (primitives + flat nested objects +
+ * arrays) because Codegen's TS→Kotlin/ObjC derivation has no support for unions
+ * or recursive structures:
+ *
+ * - **Enums travel as plain `string`** (e.g. `accuracyMode`, `quality`); the
+ *   mappers translate to/from the public string-literal unions with a defensive
+ *   fallback, so an unknown value never crashes a subscriber.
+ * - **Sum types** (`WireState`, `WireSyncStatus`) are a `type` discriminator
+ *   string plus sibling fields nullable per variant.
+ * - **String maps** (`headers`, `extras`) travel as `WireKeyValue[]` pairs —
+ *   Codegen has no portable dictionary type.
+ * - **Timestamps** are epoch-milliseconds; intervals are seconds.
  */
 import type { CodegenTypes, TurboModule } from 'react-native';
 import { TurboModuleRegistry } from 'react-native';
 
-export type WireAndroidNotification = {
-  channelId: string;
-  channelName: string;
-  notificationId: number;
-  title: string;
-  text: string;
-  smallIconResName: string;
+/** A single string map entry — see `headers` / `setExtras`. */
+export type WireKeyValue = {
+  key: string;
+  value: string;
+};
+
+export type WireSyncConfig = {
+  url: string;
+  headers: WireKeyValue[];
+  intervalSeconds: number;
+  batchSize: number;
+};
+
+/** Android-only foreground-service notification overrides. iOS ignores it. */
+export type WireNotificationConfig = {
+  title?: string;
+  text?: string;
 };
 
 export type WireConfig = {
-  /** One of: 'saver' | 'balanced' | 'precision'. */
-  preset: string;
-  distanceFilterMeters?: number;
-  intervalMillis?: number;
-  androidNotification?: WireAndroidNotification;
-  licenseKey?: string;
+  /** All fields required at the wire level — the TS facade applies defaults. */
+  minTimeBetweenLocationsSeconds: number;
+  minDistanceBetweenLocationsMeters: number;
+  /** One of: 'high' | 'balanced' | 'low'. */
+  accuracyMode: string;
+  /** One of: 'keepTracking' | 'pause' | 'pauseWithCheckIns'. */
+  whenStationary: string;
+  stationaryRadiusMeters: number;
+  detectActivity: boolean;
+  /** Omitted keeps tracking local-only. */
+  sync?: WireSyncConfig;
+  /** Android-only; the iOS native module ignores it. */
+  notification?: WireNotificationConfig;
 };
 
-export type WirePosition = {
+export type WireLocation = {
+  id: string;
   lat: number;
   lng: number;
-  accuracy: number;
-  speed: number;
-  bearing: number;
-  altitude: number;
+  timestampMs: number;
+  /** `null` when the OS did not report a value. */
+  accuracy: number | null;
+  speed: number | null;
+  bearing: number | null;
+  altitude: number | null;
+  /** One of: 'ok' | 'lowAccuracy' | 'implausibleSpeed'. */
+  quality: string;
+  /** One of: 'interval' | 'motion' | 'checkIn' | 'geofence' | 'manual'. */
+  trigger: string;
+  /** One of: 'moving' | 'stationary' | 'unknown'. */
+  motion: string;
+  /** Activity enum string, or `null` unless activity detection is enabled. */
+  activity: string | null;
+  isMock: boolean;
+};
+
+export type WireGeofence = {
+  id: string;
+  lat: number;
+  lng: number;
+  radiusMeters: number;
+  notifyOnEntry: boolean;
+  notifyOnExit: boolean;
+};
+
+export type WireGeofenceEvent = {
+  id: string;
+  geofenceId: string;
+  /** One of: 'enter' | 'exit'. */
+  type: string;
   timestampMs: number;
 };
 
 export type WireState = {
-  /** One of: 'idle' | 'starting' | 'tracking' | 'paused' | 'stopped'. */
+  /** One of: 'idle' | 'tracking' | 'stopped'. */
   type: string;
   /**
-   * Only populated when `type === 'paused'`. One of:
-   * 'permissionRevoked' | 'locationDisabled' | 'unknown'.
+   * Only populated when `type === 'stopped'`. One of: 'user' |
+   * 'permissionDenied' | 'locationServicesDisabled' | 'locationUnavailable' |
+   * 'system'.
    */
-  pauseReason?: string;
+  stopReason?: string;
+};
+
+export type WireSyncStatus = {
+  /** One of: 'idle' | 'pending' | 'failed'. */
+  type: string;
+  /** Only populated when `type === 'failed'`. One of: 'auth' | 'rejected'. */
+  failure?: string;
 };
 
 export interface Spec extends TurboModule {
-  initialize(): Promise<void>;
-  configure(config: WireConfig): Promise<void>;
+  /**
+   * The config crosses as an untyped object (`ReadableMap` on Android,
+   * `NSDictionary` on iOS) and is parsed natively. Typing it as the nested
+   * {@link WireConfig} struct would force the iOS ObjC++ layer to walk Codegen's
+   * generated C++ structs; the facade still builds a `WireConfig`-shaped value
+   * via `configToWire`, so the shape is enforced upstream.
+   */
+  configure(config: CodegenTypes.UnsafeObject): Promise<void>;
   start(): Promise<void>;
   stop(): Promise<void>;
-  shutdown(): Promise<void>;
-  history(fromMs: number, toMs: number): Promise<WirePosition[]>;
+  resumeIfNeeded(): Promise<void>;
+
+  getLocations(fromMs: number, toMs: number): Promise<WireLocation[]>;
+  /**
+   * A negative `beforeMs` deletes all stored locations (the wire encoding of
+   * the public `deleteLocations()` no-argument case). A plain `number` is used
+   * rather than `number | null` for portable Codegen support across platforms.
+   */
+  deleteLocations(beforeMs: number): Promise<number>;
+  pendingUploadCount(): Promise<number>;
+
+  sync(): Promise<void>;
+  setExtras(entries: WireKeyValue[]): Promise<void>;
+
+  addGeofences(geofences: WireGeofence[]): Promise<void>;
+  removeGeofences(ids: string[]): Promise<void>;
+  listGeofences(): Promise<WireGeofence[]>;
 
   readonly onState: CodegenTypes.EventEmitter<WireState>;
-  readonly onPosition: CodegenTypes.EventEmitter<WirePosition>;
+  readonly onLocation: CodegenTypes.EventEmitter<WireLocation>;
+  readonly onGeofenceEvent: CodegenTypes.EventEmitter<WireGeofenceEvent>;
+  readonly onSyncStatus: CodegenTypes.EventEmitter<WireSyncStatus>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('BeekonRn');

package/src/beekon.ts

@@ -1,109 +1,281 @@
 import NativeBeekon from './NativeBeekonRn';
 import type { BeekonConfig } from './types/config';
+import type { BeekonGeofence, GeofenceEvent } from './types/geofence';
+import type { Location } from './types/location';
 import type { BeekonState } from './types/state';
-import type { Position } from './types/position';
-import { configToWire, wireToPosition, wireToState } from './internal/mappers';
+import type { SyncStatus } from './types/sync';
+import {
+  configToWire,
+  geofenceToWire,
+  recordToEntries,
+  rethrowAsBeekonError,
+  wireToGeofence,
+  wireToGeofenceEvent,
+  wireToLocation,
+  wireToState,
+  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: `com.wayq.beekon.Beekon` (object)
- * - iOS:     `Beekon.shared` (actor)
+ * - Android: `in.wayq.beekon.Beekon` (object)
+ * - iOS:     `BeekonKit.Beekon.shared` (actor)
  *
- * Lifecycle: `init()` once → `configure(config)` → `start()` → ... →
- * `stop()` (idempotent) or `shutdown()` (final teardown). Subscribe to
- * `onState` / `onPosition` for live updates; query `history(from, to)` for
- * persisted points.
+ * 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 position natively;
- * JS is a passive observer. In background, the JS engine is not guaranteed to
- * be alive — for past points, 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();
+
   /**
-   * Initialize the SDK. Idempotent; safe to call more than once. Must be
-   * called once before `configure()`.
-   *
-   * Errors:
-   * - `NO_GMS_AVAILABLE` (Android) — Google Play Services missing.
+   * Set tracking parameters. Optional — `start()` falls back to the previously
+   * 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 init(): Promise<void> {
-    return NativeBeekon.initialize();
+  async configure(config: BeekonConfig): Promise<void> {
+    this.hub.ensureSubscribed();
+    await NativeBeekon.configure(configToWire(config));
   }
 
   /**
-   * Set sampling and platform-specific config. Replaces any previous config.
-   * Must be called before `start()`.
+   * 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.
    *
-   * Errors:
-   * - `NOT_INITIALISED` — `init()` was not called first.
-   * - `NOT_CONFIGURED` — Android only, `androidNotification` was missing.
+   * 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 configure(config: BeekonConfig): Promise<void> {
-    return NativeBeekon.configure(configToWire(config));
+  async resumeIfNeeded(): Promise<void> {
+    this.hub.ensureSubscribed();
+    await NativeBeekon.resumeIfNeeded();
   }
 
   /**
-   * Begin tracking. Transitions state from `idle` → `starting` → `tracking`.
+   * 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.
    *
-   * Errors:
-   * - `PERMISSION_DENIED` — location permission not granted.
-   * - `LOCATION_SERVICES_DISABLED` (iOS) — system location services off.
-   * - `SERVICE_FAILED` — native service couldn't start.
+   * Throws `BeekonError` with kind `'storage'` on a database read failure.
    */
-  async start(): Promise<void> {
-    return NativeBeekon.start();
+  async getLocations(from: Date, to: Date): Promise<Location[]> {
+    try {
+      const wires = await NativeBeekon.getLocations(
+        from.getTime(),
+        to.getTime()
+      );
+      return wires.map(wireToLocation);
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
   }
 
-  /** Stop tracking. Idempotent. State → `stopped`. */
-  async stop(): Promise<void> {
-    return NativeBeekon.stop();
+  /**
+   * 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 deleteLocations(before?: Date): Promise<number> {
+    try {
+      // Negative is the wire sentinel for "delete all" (see NativeBeekonRn.ts).
+      return await NativeBeekon.deleteLocations(before ? before.getTime() : -1);
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
   }
 
   /**
-   * Final teardown — releases native resources. Most apps don't need this;
-   * `stop()` is sufficient between sessions.
+   * The number of stored locations not yet uploaded. Throws `BeekonError` with
+   * kind `'storage'` on a failure.
    */
-  async shutdown(): Promise<void> {
-    return NativeBeekon.shutdown();
+  async pendingUploadCount(): Promise<number> {
+    try {
+      return await NativeBeekon.pendingUploadCount();
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
   }
 
   /**
-   * Read persisted positions in the time range [from, to]. Returns positions
-   * 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: positions older than 7 days OR beyond the most recent 100K are
-   * pruned automatically.
+   * Request an immediate upload. Best-effort and self-retrying; a no-op when
+   * sync is not configured.
    */
-  async history(from: Date, to: Date): Promise<Position[]> {
-    const wires = await NativeBeekon.history(from.getTime(), to.getTime());
-    return wires.map(wireToPosition);
+  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));
   }
 
   /**
-   * 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).
+   * 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 {
+      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 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. 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 {
+    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 gated positions as they arrive. Returns an unsubscribe
-   * function. Broadcast (no replay) — only delivers while the JS engine is
-   * alive. For points emitted while JS was asleep, use `history()`.
+   * Subscribe to upload health (`idle` / `pending` / `failed(reason)`). The
+   * current status is delivered to new subscribers immediately (replay-1).
+   * Returns an unsubscribe function.
    */
-  onPosition(cb: (p: Position) => void): () => void {
-    const subscription = NativeBeekon.onPosition((wire) =>
-      cb(wireToPosition(wire))
-    );
-    return () => subscription.remove();
+  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 { Preset } from './types/preset';
-export type { BeekonState, PauseReason } from './types/state';
-export type { Position } from './types/position';
+
+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';