@wayq/beekon-rn 0.0.1 → 0.0.3

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

@@ -1,79 +1,66 @@
 import type { BeekonConfig } from './types/config';
 import type { BeekonState } from './types/state';
-import type { Position } from './types/position';
+import type { Location } from './types/location';
 /**
  * Public facade for the Beekon SDK. Mirrors 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.
+ * Lifecycle: `configure(config)` → `start()` → ... → `stop()` (idempotent).
+ * Subscribe to `onState` / `onLocation` for live updates; query
+ * `history(from, to)` for persisted fixes.
  *
  * **Threading:** Methods are safe to call from any JS context. Subscribers'
  * 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. In background, the JS engine is not guaranteed to be
+ * alive — for past fixes, use `history()`.
  */
 declare class BeekonImpl {
     /**
-     * Initialize the SDK. Idempotent; safe to call more than once. Must be
-     * called once before `configure()`.
+     * Set tracking parameters. Optional — `start()` falls back to the previously
+     * persisted config or the SDK default (30s / 100m) if never configured.
      *
-     * 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.
+     * While tracking, the new gate values take effect on the next admitted fix
+     * without restarting the underlying location subscription.
      */
     configure(config: BeekonConfig): Promise<void>;
     /**
-     * Begin tracking. Transitions state from `idle` → `starting` → `tracking`.
+     * Begin tracking. State transitions to `tracking`.
      *
-     * Errors:
-     * - `PERMISSION_DENIED` — location permission not granted.
-     * - `LOCATION_SERVICES_DISABLED` (iOS) — system location services off.
-     * - `SERVICE_FAILED` — native service couldn't start.
+     * Throws a `BeekonError` with kind:
+     * - `'permissionDenied'` — location permission not granted.
+     * - `'locationServicesDisabled'` — system location services off (or GMS
+     *   unavailable on Android).
      */
     start(): Promise<void>;
-    /** Stop tracking. Idempotent. State → `stopped`. */
+    /** Stop tracking. Idempotent. State transitions to `stopped(user)`. */
     stop(): Promise<void>;
     /**
-     * Final teardown — releases native resources. Most apps don't need this;
-     * `stop()` is sufficient between sessions.
-     */
-    shutdown(): 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
+     * 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: positions older than 7 days OR beyond the most recent 100K are
+     * Retention: fixes older than 7 days OR beyond the most recent 100K are
      * pruned automatically.
+     *
+     * Throws `BeekonError` with kind `'storageFailure'` on database read failure.
      */
-    history(from: Date, to: Date): Promise<Position[]>;
+    history(from: Date, to: Date): Promise<Location[]>;
     /**
      * 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).
+     * semantics, matching the native `state` flow / AsyncStream).
      */
     onState(cb: (s: BeekonState) => void): () => void;
     /**
-     * Subscribe to gated positions as they arrive. Returns an unsubscribe
+     * Subscribe to gated locations 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()`.
+     * alive. For fixes emitted while JS was asleep, use `history()`.
      */
-    onPosition(cb: (p: Position) => void): () => void;
+    onLocation(cb: (l: Location) => 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,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAQjD;;;;;;;;;;;;;;;;GAgBG;AACH,cAAM,UAAU;IACd;;;;;;OAMG;IACG,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpD;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,uEAAuE;IACjE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;;;;;;;;OASG;IACG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IASxD;;;;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"}

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

@@ -1,6 +1,6 @@
 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 { BeekonState, StopReason } from './types/state';
+export type { Location } from './types/location';
+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;AAClC,YAAY,EAAE,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC9E,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC"}

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

@@ -1,8 +1,15 @@
 import type { BeekonConfig } from '../types/config';
 import type { BeekonState } from '../types/state';
-import type { Position } from '../types/position';
-import type { WireConfig, WirePosition, WireState } from '../NativeBeekonRn';
+import type { Location } from '../types/location';
+import type { WireConfig, WireLocation, WireState } from '../NativeBeekonRn';
 export declare function configToWire(config: BeekonConfig): WireConfig;
-export declare function wireToPosition(w: WirePosition): Position;
+export declare function wireToLocation(w: WireLocation): Location;
 export declare function wireToState(w: WireState): BeekonState;
+/**
+ * Re-throw a native promise rejection as a typed `BeekonError`. Native modules
+ * encode the kind in the error code string (`PERMISSION_DENIED`,
+ * `LOCATION_SERVICES_DISABLED`, `STORAGE_FAILURE`); anything else falls
+ * through as the original error.
+ */
+export 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;AACpD,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAK7E,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAM7D;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,QAAQ,CAUxD;AAeD,wBAAgB,WAAW,CAAC,CAAC,EAAE,SAAS,GAAG,WAAW,CAYrD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAQtD"}

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

@@ -1,41 +1,33 @@
-import type { Preset } from './preset';
 /**
- * Foreground service notification config — required when running on Android
- * because Android 8+ requires a persistent notification while a foreground
- * service is active. Ignored on iOS.
+ * Foreground-service notification overrides. Android-only — required by the
+ * platform because every location foreground service must show a persistent
+ * notification. All fields are optional; missing values resolve at runtime
+ * against the host app's label and icon. Ignored on iOS.
  */
 export type AndroidNotificationConfig = {
-    /** NotificationChannel id (Android 8+). */
-    channelId: string;
-    /** User-visible channel display name. */
-    channelName: string;
-    /** Foreground notification id. Must be > 0. */
-    notificationId: number;
-    /** Notification title shown in the status bar. */
-    title: string;
-    /** Notification body text. */
-    text: string;
+    /** Notification title. Defaults to "Location active". */
+    title?: string;
+    /** Notification body text. Defaults to the host app's label. */
+    text?: string;
     /**
-     * Drawable resource name for the notification icon (e.g. `ic_notification`).
-     * Resolved at runtime via `Resources.getIdentifier()` against the host app's
-     * `res/drawable*` folders. Pass the resource name without extension or
-     * `R.drawable.` prefix.
+     * Drawable resource name (e.g. `ic_notification`) — resolved at runtime via
+     * `Resources.getIdentifier()` against the host app's `res/drawable*` folders.
+     * Pass the resource name without extension or `R.drawable.` prefix. Defaults
+     * to the host app's `applicationInfo.icon`.
      */
-    smallIconResName: string;
+    smallIconResName?: string;
 };
+/**
+ * Tracking configuration. Two knobs: a minimum time interval and a minimum
+ * distance between emitted fixes. A fix is admitted only when **both** gates
+ * are satisfied. Pass `0` to disable a gate.
+ */
 export type BeekonConfig = {
-    /** Sampling preset. Default: `'balanced'`. */
-    preset?: Preset;
-    /** Override the preset's distance gate (meters). */
-    distanceFilterMeters?: number;
-    /** Override the preset's interval (milliseconds). */
-    intervalMillis?: number;
-    /**
-     * Required when running on Android. Ignored on iOS. The plugin throws
-     * `NOT_CONFIGURED` if missing on Android.
-     */
+    /** Minimum seconds between admitted fixes. Default: `30`. `0` disables the time gate. */
+    intervalSeconds?: number;
+    /** Minimum metres between admitted fixes. Default: `100`. `0` disables the distance gate. */
+    distanceMeters?: number;
+    /** Android-only notification overrides. Ignored on iOS. */
     androidNotification?: AndroidNotificationConfig;
-    /** Optional license key. Reserved for future use. */
-    licenseKey?: string;
 };
 //# 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;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,yFAAyF;IACzF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6FAA6F;IAC7F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,yBAAyB,CAAC;CACjD,CAAC"}

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

@@ -0,0 +1,14 @@
+/**
+ * Error kinds thrown from `Beekon.start()` / `Beekon.history()`. Match the
+ * native `BeekonError` cases byte-for-byte.
+ */
+export type BeekonErrorKind = 'permissionDenied' | 'locationServicesDisabled' | 'storageFailure';
+/**
+ * Typed error surfaced from the bridge. The native module rejects promises
+ * with the kind encoded as the error code; the facade re-wraps into this.
+ */
+export 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;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,0BAA0B,GAC1B,gBAAgB,CAAC;AAErB;;;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/location.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A single location fix as emitted by the native SDK after gating. Fields map
+ * 1:1 to `in.wayq.beekon.Location` on Android and `BeekonKit.Location` on iOS.
+ *
+ * `lat`, `lng`, and `timestamp` are always present. The four optional fields
+ * are `null` when the OS did not report a value — the SDK never invents a
+ * value to mask absence (e.g. a stationary device returns `bearing === null`,
+ * not `0`).
+ */
+export type Location = {
+    /** Latitude in degrees, WGS-84. */
+    lat: number;
+    /** Longitude in degrees, WGS-84. */
+    lng: number;
+    /** Horizontal accuracy in meters (1-sigma); `null` if unreported. */
+    accuracy: number | null;
+    /** Speed in m/s; `null` if unreported. */
+    speed: number | null;
+    /** Bearing in degrees `[0, 360)` clockwise from true north; `null` if unreported. */
+    bearing: number | null;
+    /** Altitude in meters above the WGS-84 ellipsoid; `null` if unreported. */
+    altitude: number | null;
+    /** Time the OS provider reported this fix (not when JS received it). */
+    timestamp: Date;
+};
+//# 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;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,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,wEAAwE;IACxE,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC"}

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

@@ -1,22 +1,22 @@
 /**
- * Why tracking is paused. Names match the native `PauseReason` enum on both
- * platforms byte-for-byte.
+ * Reason a tracking session ended. Mirrors `StopReason` on both platforms.
+ *
+ * `'system'` is Android-only — surfaces when the OS terminates the foreground
+ * service (memory pressure, force-stop). iOS will never emit `'system'`.
  */
-export type PauseReason = 'permissionRevoked' | 'locationDisabled' | 'unknown';
+export type StopReason = 'user' | 'permissionDenied' | 'locationServicesDisabled' | 'system';
 /**
- * Tracking state. Mirrors the native `BeekonState` sealed hierarchy on both
+ * Tracking state. Mirrors the native `BeekonState` sealed type on both
  * platforms. Use the `kind` field as a discriminator.
+ *
+ * Lifecycle: `idle → tracking → stopped(reason)`.
  */
 export type BeekonState = {
     kind: 'idle';
-} | {
-    kind: 'starting';
 } | {
     kind: 'tracking';
-} | {
-    kind: 'paused';
-    reason: PauseReason;
 } | {
     kind: 'stopped';
+    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;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,kBAAkB,GAClB,0BAA0B,GAC1B,QAAQ,CAAC;AAEb;;;;;GAKG;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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wayq/beekon-rn",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "React Native binding for the Beekon location SDK (Android + iOS).",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -116,7 +116,7 @@
     "type": "modules",
     "jsSrcsDir": "src",
     "android": {
-      "javaPackageName": "com.wayq.beekonrn"
+      "javaPackageName": "in.wayq.beekonrn"
     }
   },
   "prettier": {

package/scripts/fetch-beekonkit.sh

@@ -13,9 +13,12 @@
 
 set -euo pipefail
 
-VERSION="0.0.1"
+VERSION="0.0.3"
 URL="https://github.com/wayqteam/beekon-ios-binary/releases/download/v${VERSION}/BeekonKit.xcframework.zip"
-EXPECTED_SHA="f7bd79a6d61994977318daa6d722866abd0a61d7d7e5834ab5307df39b6ee60e"
+# TODO(0.0.3): replace with the SHA256 emitted by `scripts/build-xcframework.sh`
+# when the v0.0.3 BeekonKit binary is cut and uploaded. v0.0.3 is the first
+# release with nullable Location fields (accuracy/speed/bearing/altitude).
+EXPECTED_SHA="c2f1990dd7064314deffc4af430839b0c8b7e61851e591c34fb683aed2fff127"
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 DEST_DIR="${ROOT}/ios/Frameworks"

package/src/NativeBeekonRn.ts

@@ -5,60 +5,56 @@
  *
  * 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.
+ * recursive structures. The state variants are encoded as a `type`
+ * discriminator string with sibling fields nullable per variant.
  */
 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;
+  title?: string;
+  text?: string;
+  smallIconResName?: string;
 };
 
 export type WireConfig = {
-  /** One of: 'saver' | 'balanced' | 'precision'. */
-  preset: string;
-  distanceFilterMeters?: number;
-  intervalMillis?: number;
+  /** Required at the wire level — the TS facade applies defaults (30 / 100). */
+  intervalSeconds: number;
+  /** Required at the wire level — the TS facade applies defaults (30 / 100). */
+  distanceMeters: number;
+  /** Android-only. iOS native module ignores. */
   androidNotification?: WireAndroidNotification;
-  licenseKey?: string;
 };
 
-export type WirePosition = {
+export type WireLocation = {
   lat: number;
   lng: number;
-  accuracy: number;
-  speed: number;
-  bearing: number;
-  altitude: number;
   timestampMs: number;
+  /** `null` when the OS did not report a value (e.g. low-confidence fix). */
+  accuracy: number | null;
+  speed: number | null;
+  bearing: number | null;
+  altitude: number | null;
 };
 
 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' | 'system'.
    */
-  pauseReason?: string;
+  stopReason?: string;
 };
 
 export interface Spec extends TurboModule {
-  initialize(): Promise<void>;
   configure(config: WireConfig): Promise<void>;
   start(): Promise<void>;
   stop(): Promise<void>;
-  shutdown(): Promise<void>;
-  history(fromMs: number, toMs: number): Promise<WirePosition[]>;
+  history(fromMs: number, toMs: number): Promise<WireLocation[]>;
 
   readonly onState: CodegenTypes.EventEmitter<WireState>;
-  readonly onPosition: CodegenTypes.EventEmitter<WirePosition>;
+  readonly onLocation: CodegenTypes.EventEmitter<WireLocation>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('BeekonRn');

package/src/beekon.ts

@@ -1,93 +1,95 @@
 import NativeBeekon from './NativeBeekonRn';
 import type { BeekonConfig } from './types/config';
 import type { BeekonState } from './types/state';
-import type { Position } from './types/position';
-import { configToWire, wireToPosition, wireToState } from './internal/mappers';
+import type { Location } from './types/location';
+import {
+  configToWire,
+  wireToLocation,
+  wireToState,
+  rethrowAsBeekonError,
+} from './internal/mappers';
 
 /**
  * Public facade for the Beekon SDK. Mirrors 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.
+ * Lifecycle: `configure(config)` → `start()` → ... → `stop()` (idempotent).
+ * Subscribe to `onState` / `onLocation` for live updates; query
+ * `history(from, to)` for persisted fixes.
  *
  * **Threading:** Methods are safe to call from any JS context. Subscribers'
  * 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. In background, the JS engine is not guaranteed to be
+ * alive — for past fixes, use `history()`.
  */
 class BeekonImpl {
   /**
-   * Initialize the SDK. Idempotent; safe to call more than once. Must be
-   * called once before `configure()`.
+   * Set tracking parameters. Optional — `start()` falls back to the previously
+   * persisted config or the SDK default (30s / 100m) if never configured.
    *
-   * Errors:
-   * - `NO_GMS_AVAILABLE` (Android) — Google Play Services missing.
-   */
-  async init(): Promise<void> {
-    return NativeBeekon.initialize();
-  }
-
-  /**
-   * 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.
+   * While tracking, the new gate values take effect on the next admitted fix
+   * without restarting the underlying location subscription.
    */
   async configure(config: BeekonConfig): Promise<void> {
-    return NativeBeekon.configure(configToWire(config));
+    try {
+      await NativeBeekon.configure(configToWire(config));
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
   }
 
   /**
-   * Begin tracking. Transitions state from `idle` → `starting` → `tracking`.
+   * Begin tracking. State transitions to `tracking`.
    *
-   * Errors:
-   * - `PERMISSION_DENIED` — location permission not granted.
-   * - `LOCATION_SERVICES_DISABLED` (iOS) — system location services off.
-   * - `SERVICE_FAILED` — native service couldn't start.
+   * Throws a `BeekonError` with kind:
+   * - `'permissionDenied'` — location permission not granted.
+   * - `'locationServicesDisabled'` — system location services off (or GMS
+   *   unavailable on Android).
    */
   async start(): Promise<void> {
-    return NativeBeekon.start();
+    try {
+      await NativeBeekon.start();
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
   }
 
-  /** Stop tracking. Idempotent. State → `stopped`. */
+  /** Stop tracking. Idempotent. State transitions to `stopped(user)`. */
   async stop(): Promise<void> {
-    return NativeBeekon.stop();
+    try {
+      await NativeBeekon.stop();
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
   }
 
   /**
-   * Final teardown — releases native resources. Most apps don't need this;
-   * `stop()` is sufficient between sessions.
-   */
-  async shutdown(): Promise<void> {
-    return NativeBeekon.shutdown();
-  }
-
-  /**
-   * Read persisted positions in the time range [from, to]. Returns positions
-   * in chronological order. Reads come from the SDK's local storage (Room on
+   * 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: positions older than 7 days OR beyond the most recent 100K are
+   * Retention: fixes older than 7 days OR beyond the most recent 100K are
    * pruned automatically.
+   *
+   * Throws `BeekonError` with kind `'storageFailure'` on database read failure.
    */
-  async history(from: Date, to: Date): Promise<Position[]> {
-    const wires = await NativeBeekon.history(from.getTime(), to.getTime());
-    return wires.map(wireToPosition);
+  async history(from: Date, to: Date): Promise<Location[]> {
+    try {
+      const wires = await NativeBeekon.history(from.getTime(), to.getTime());
+      return wires.map(wireToLocation);
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
   }
 
   /**
    * 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).
+   * semantics, matching the native `state` flow / AsyncStream).
    */
   onState(cb: (s: BeekonState) => void): () => void {
     const subscription = NativeBeekon.onState((wire) => cb(wireToState(wire)));
@@ -95,13 +97,13 @@ class BeekonImpl {
   }
 
   /**
-   * Subscribe to gated positions as they arrive. Returns an unsubscribe
+   * Subscribe to gated locations 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()`.
+   * alive. For fixes emitted while JS was asleep, use `history()`.
    */
-  onPosition(cb: (p: Position) => void): () => void {
-    const subscription = NativeBeekon.onPosition((wire) =>
-      cb(wireToPosition(wire))
+  onLocation(cb: (l: Location) => void): () => void {
+    const subscription = NativeBeekon.onLocation((wire) =>
+      cb(wireToLocation(wire))
     );
     return () => subscription.remove();
   }

package/src/index.tsx

@@ -1,5 +1,5 @@
 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 { BeekonState, StopReason } from './types/state';
+export type { Location } from './types/location';
+export { BeekonError, type BeekonErrorKind } from './types/error';