@wayq/beekon-rn 0.0.1 → 0.0.5

package/lib/typescript/src/beekon.d.ts

@@ -1,79 +1,114 @@
 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 type { SyncStatus } from './types/sync';
 /**
- * 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()`.
  */
 declare class BeekonImpl {
+    private readonly hub;
     /**
-     * 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.
-     */
-    init(): Promise<void>;
-    /**
-     * Set sampling and platform-specific config. Replaces any previous config.
-     * Must be called before `start()`.
-     *
-     * Errors:
-     * - `NOT_INITIALISED` — `init()` was not called first.
-     * - `NOT_CONFIGURED` — Android only, `androidNotification` was 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()`.
      */
     configure(config: BeekonConfig): Promise<void>;
     /**
-     * Begin tracking. Transitions state from `idle` → `starting` → `tracking`.
-     *
-     * Errors:
-     * - `PERMISSION_DENIED` — location permission not granted.
-     * - `LOCATION_SERVICES_DISABLED` (iOS) — system location services off.
-     * - `SERVICE_FAILED` — native service couldn't 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`.
      */
     start(): Promise<void>;
-    /** Stop tracking. Idempotent. State → `stopped`. */
+    /** Stop tracking. Idempotent. Registered geofences keep firing. */
     stop(): Promise<void>;
     /**
-     * Final teardown — releases native resources. Most apps don't need this;
-     * `stop()` is sufficient between sessions.
+     * 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.
      */
-    shutdown(): Promise<void>;
+    resumeIfNeeded(): Promise<void>;
     /**
-     * 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.
+     * 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.
      *
-     * Retention: positions older than 7 days OR beyond the most recent 100K are
-     * pruned automatically.
+     * Throws `BeekonError` with kind `'storage'` on a database read failure.
+     */
+    getLocations(from: Date, to: Date): Promise<Location[]>;
+    /**
+     * 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.
+     */
+    deleteLocations(before?: Date): Promise<number>;
+    /**
+     * The number of stored locations not yet uploaded. Throws `BeekonError` with
+     * kind `'storage'` on a failure.
+     */
+    pendingUploadCount(): Promise<number>;
+    /**
+     * Request an immediate upload. Best-effort and self-retrying; a no-op when
+     * sync is not configured.
+     */
+    sync(): Promise<void>;
+    /** Set custom key/value fields (e.g. `user_id`) included with every upload. */
+    setExtras(extras: Record<string, string>): Promise<void>;
+    /**
+     * 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.
      */
-    history(from: Date, to: Date): Promise<Position[]>;
+    addGeofences(geofences: BeekonGeofence[]): Promise<void>;
+    /** Unregister geofences by id. Unknown ids are ignored. */
+    removeGeofences(ids: string[]): Promise<void>;
+    /** The currently registered geofences. */
+    listGeofences(): Promise<BeekonGeofence[]>;
     /**
-     * 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).
+     * 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;
     /**
-     * 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 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;
+    /**
+     * Subscribe to geofence enter / exit crossings. Broadcast (no replay).
+     * Returns an unsubscribe function.
+     */
+    onGeofenceEvent(cb: (e: GeofenceEvent) => void): () => void;
+    /**
+     * 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;
+    onSyncStatus(cb: (s: SyncStatus) => void): () => void;
 }
 export declare const Beekon: BeekonImpl;
 export {};

package/lib/typescript/src/beekon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"beekon.d.ts","sourceRoot":"","sources":["../../../src/beekon.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGjD;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,UAAU;IACd;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;;;;OAOG;IACG,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,oDAAoD;IAC9C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKxD;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI;IAKjD;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;CAMlD;AAED,eAAO,MAAM,MAAM,YAAmB,CAAC"}
+{"version":3,"file":"beekon.d.ts","sourceRoot":"","sources":["../../../src/beekon.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AA8F/C;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,UAAU;IACd,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IAEtC;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,mEAAmE;IAC7D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B;;;;;;;;OAQG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrC;;;;;;;OAOG;IACG,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAY7D;;;;OAIG;IACG,eAAe,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IASrD;;;OAGG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;IAQ3C;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,+EAA+E;IACzE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D;;;;OAIG;IACG,YAAY,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9D,2DAA2D;IACrD,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,0CAA0C;IACpC,aAAa,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAKhD;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI;IAIjD;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;IAIjD;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IAI3D;;;;OAIG;IACH,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;CAGtD;AAED,eAAO,MAAM,MAAM,YAAmB,CAAC"}

package/lib/typescript/src/index.d.ts

@@ -1,6 +1,9 @@
 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';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC9E,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,YAAY,EACV,YAAY,EACZ,UAAU,EACV,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,EACf,WAAW,EACX,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EACV,cAAc,EACd,aAAa,EACb,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/lib/typescript/src/internal/mappers.d.ts

@@ -1,8 +1,21 @@
 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 type { WireConfig, WirePosition, WireState } from '../NativeBeekonRn';
+import type { SyncStatus } from '../types/sync';
+import type { WireConfig, WireGeofence, WireGeofenceEvent, WireKeyValue, WireLocation, WireState, WireSyncStatus } from '../NativeBeekonRn';
+export declare function recordToEntries(record: Record<string, string> | undefined): WireKeyValue[];
 export declare function configToWire(config: BeekonConfig): WireConfig;
-export declare function wireToPosition(w: WirePosition): Position;
+export declare function geofenceToWire(g: BeekonGeofence): WireGeofence;
+export declare function wireToLocation(w: WireLocation): Location;
+export declare function wireToGeofence(w: WireGeofence): BeekonGeofence;
+export declare function wireToGeofenceEvent(w: WireGeofenceEvent): GeofenceEvent;
 export declare function wireToState(w: WireState): BeekonState;
+export declare function wireToSyncStatus(w: WireSyncStatus): SyncStatus;
+/**
+ * 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 declare function rethrowAsBeekonError(e: unknown): never;
 //# sourceMappingURL=mappers.d.ts.map

package/lib/typescript/src/internal/mappers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mappers.d.ts","sourceRoot":"","sources":["../../../../src/internal/mappers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE7E,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAQ7D;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,QAAQ,CAUxD;AAOD,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,GAAG,WAAW,CAiBrD"}
+{"version":3,"file":"mappers.d.ts","sourceRoot":"","sources":["../../../../src/internal/mappers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AASpD,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAe,UAAU,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACf,MAAM,mBAAmB,CAAC;AAiB3B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GACzC,YAAY,EAAE,CAGhB;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CA0B7D;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,cAAc,GAAG,YAAY,CAS9D;AAID,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,QAAQ,CA0CxD;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,cAAc,CAS9D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAOvE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,GAAG,WAAW,CAYrD;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,UAAU,CAW9D;AAoCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAQtD"}

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

@@ -1,41 +1,63 @@
-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;
 };
 //# sourceMappingURL=config.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,yBAAyB,CAAC;IAChD,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,yEAAyE;IACzE,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,8EAA8E;IAC9E,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sDAAsD;IACtD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,6EAA6E;IAC7E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC,CAAC"}

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

@@ -0,0 +1,48 @@
+/**
+ * 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';
+//# sourceMappingURL=enums.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../../../src/types/enums.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,OAAO,GAAG,mBAAmB,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,QAAQ,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAExE,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,YAAY,GACZ,SAAS,GACT,SAAS,GACT,SAAS,GACT,YAAY,GACZ,SAAS,CAAC"}

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

@@ -0,0 +1,20 @@
+/**
+ * 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 declare class BeekonError extends Error {
+    readonly kind: BeekonErrorKind;
+    constructor(kind: BeekonErrorKind, message: string);
+}
+//# sourceMappingURL=error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../../src/types/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,iBAAiB,CAAC;AAE5D;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,IAAI,EAAE,eAAe,CAAC;gBAE1B,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD"}

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

@@ -0,0 +1,36 @@
+/**
+ * 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;
+};
+//# sourceMappingURL=geofence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"geofence.d.ts","sourceRoot":"","sources":["../../../../src/types/geofence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,IAAI,EAAE,UAAU,CAAC;IACjB,kCAAkC;IAClC,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC"}

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

@@ -0,0 +1,40 @@
+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;
+};
+//# sourceMappingURL=location.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../../../../src/types/location.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,eAAe,EACf,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,SAAS,EAAE,IAAI,CAAC;IAChB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qFAAqF;IACrF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+CAA+C;IAC/C,OAAO,EAAE,eAAe,CAAC;IACzB,iCAAiC;IACjC,OAAO,EAAE,eAAe,CAAC;IACzB,gDAAgD;IAChD,MAAM,EAAE,WAAW,CAAC;IACpB,yEAAyE;IACzE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC"}

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

@@ -1,22 +1,31 @@
 /**
- * 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';
+    reason: StopReason;
 };
 //# sourceMappingURL=state.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../../src/types/state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,SAAS,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../../src/types/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,kBAAkB,GAClB,0BAA0B,GAC1B,qBAAqB,GACrB,QAAQ,CAAC;AAEb;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC"}

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

@@ -0,0 +1,27 @@
+/**
+ * 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;
+};
+//# sourceMappingURL=sync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/types/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wayq/beekon-rn",
-  "version": "0.0.1",
+  "version": "0.0.5",
   "description": "React Native binding for the Beekon location SDK (Android + iOS).",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -53,15 +53,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/wayqteam/beekon.git",
-    "directory": "beekon-rn"
+    "url": "git+https://github.com/wayqteam/beekon-rn.git"
   },
   "author": "wayqteam <wayqteam@users.noreply.github.com> (https://github.com/wayqteam)",
   "license": "SEE LICENSE IN LICENSE.txt",
   "bugs": {
-    "url": "https://github.com/wayqteam/beekon/issues"
+    "url": "https://github.com/wayqteam/beekon-rn/issues"
   },
-  "homepage": "https://github.com/wayqteam/beekon/tree/main/beekon-rn#readme",
+  "homepage": "https://github.com/wayqteam/beekon-rn#readme",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -116,7 +115,7 @@
     "type": "modules",
     "jsSrcsDir": "src",
     "android": {
-      "javaPackageName": "com.wayq.beekonrn"
+      "javaPackageName": "in.wayq.beekonrn"
     }
   },
   "prettier": {