@wayq/beekon-rn 0.0.1

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

@@ -0,0 +1,80 @@
+import type { BeekonConfig } from './types/config';
+import type { BeekonState } from './types/state';
+import type { Position } from './types/position';
+/**
+ * Public facade for the Beekon SDK. Mirrors the native APIs:
+ *
+ * - Android: `com.wayq.beekon.Beekon` (object)
+ * - iOS:     `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.
+ *
+ * **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()`.
+ */
+declare class BeekonImpl {
+    /**
+     * 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.
+     */
+    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.
+     */
+    start(): Promise<void>;
+    /** Stop tracking. Idempotent. State → `stopped`. */
+    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
+     * 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.
+     */
+    history(from: Date, to: Date): Promise<Position[]>;
+    /**
+     * 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).
+     */
+    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()`.
+     */
+    onPosition(cb: (p: Position) => void): () => void;
+}
+export declare const Beekon: BeekonImpl;
+export {};
+//# sourceMappingURL=beekon.d.ts.map

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

@@ -0,0 +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"}

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

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

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

@@ -0,0 +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"}

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

@@ -0,0 +1,8 @@
+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';
+export declare function configToWire(config: BeekonConfig): WireConfig;
+export declare function wireToPosition(w: WirePosition): Position;
+export declare function wireToState(w: WireState): BeekonState;
+//# sourceMappingURL=mappers.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,41 @@
+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.
+ */
+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;
+    /**
+     * 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.
+     */
+    smallIconResName: string;
+};
+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.
+     */
+    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

@@ -0,0 +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"}

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

@@ -0,0 +1,24 @@
+/**
+ * A single location fix as emitted by the native SDK after gating. Fields map
+ * 1:1 to `com.wayq.beekon.Position` on Android and `Beekon.Position` on iOS.
+ *
+ * The SDK does NOT smooth or filter positions beyond the gate — values are
+ * forwarded as the OS provider reported them (raw passthrough).
+ */
+export type Position = {
+    /** Latitude in degrees, WGS-84. */
+    lat: number;
+    /** Longitude in degrees, WGS-84. */
+    lng: number;
+    /** Horizontal accuracy in meters (1-sigma). */
+    accuracy: number;
+    /** Speed in m/s. May be 0 if the OS provider doesn't supply it. */
+    speed: number;
+    /** Bearing in degrees clockwise from true north. */
+    bearing: number;
+    /** Altitude in meters above the WGS-84 ellipsoid. */
+    altitude: number;
+    /** Time the OS provider reported this fix (not when JS received it). */
+    timestamp: Date;
+};
+//# sourceMappingURL=position.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../../src/types/position.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC"}

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

@@ -0,0 +1,12 @@
+/**
+ * Sampling preset. Determines the gating interval and distance threshold the
+ * native SDK uses before emitting a position. Per `docs/REQUIREMENTS.md`:
+ *
+ * | Preset    | Interval | Distance | Battery (typical) |
+ * |-----------|----------|----------|-------------------|
+ * | saver     | 60_000ms | 150 m    | 3–8%              |
+ * | balanced  | 30_000ms | 100 m    | 5–10%             |
+ * | precision | 10_000ms | 30 m     | 15–25%            |
+ */
+export type Preset = 'saver' | 'balanced' | 'precision';
+//# sourceMappingURL=preset.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preset.d.ts","sourceRoot":"","sources":["../../../../src/types/preset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * Why tracking is paused. Names match the native `PauseReason` enum on both
+ * platforms byte-for-byte.
+ */
+export type PauseReason = 'permissionRevoked' | 'locationDisabled' | 'unknown';
+/**
+ * Tracking state. Mirrors the native `BeekonState` sealed hierarchy on both
+ * platforms. Use the `kind` field as a discriminator.
+ */
+export type BeekonState = {
+    kind: 'idle';
+} | {
+    kind: 'starting';
+} | {
+    kind: 'tracking';
+} | {
+    kind: 'paused';
+    reason: PauseReason;
+} | {
+    kind: 'stopped';
+};
+//# sourceMappingURL=state.d.ts.map

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

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,137 @@
+{
+  "name": "@wayq/beekon-rn",
+  "version": "0.0.1",
+  "description": "React Native binding for the Beekon location SDK (Android + iOS).",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "scripts/fetch-beekonkit.sh",
+    "*.podspec",
+    "LICENSE.txt",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace @wayq/beekon-rn-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build ios/Frameworks lib",
+    "fetch-beekonkit": "bash scripts/fetch-beekonkit.sh",
+    "prepare": "yarn fetch-beekonkit && bob build",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\""
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android",
+    "location",
+    "tracking",
+    "gps",
+    "background-location",
+    "geolocation",
+    "beekon",
+    "turbo-module"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wayqteam/beekon.git",
+    "directory": "beekon-rn"
+  },
+  "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"
+  },
+  "homepage": "https://github.com/wayqteam/beekon/tree/main/beekon-rn#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.0.3",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@react-native/babel-preset": "0.85.0",
+    "@react-native/eslint-config": "0.85.0",
+    "@types/react": "^19.2.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "react": "19.2.3",
+    "react-native": "0.85.0",
+    "react-native-builder-bob": "^0.41.0",
+    "turbo": "^2.8.21",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "BeekonRnSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.wayq.beekonrn"
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "create-react-native-library": {
+    "type": "turbo-module",
+    "languages": "kotlin-objc",
+    "tools": [
+      "eslint"
+    ],
+    "version": "0.62.0"
+  }
+}

package/scripts/fetch-beekonkit.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Fetches BeekonKit.xcframework from wayqteam/beekon-ios-binary's GitHub
+# Release at the pinned version, verifies SHA256, and extracts it into
+# ios/Frameworks/. Idempotent: skips if the framework is already present.
+#
+# Run via `yarn prepare` (CI: pre-publish) and once locally before iOS dev
+# (e.g. `bash scripts/fetch-beekonkit.sh` → `cd example/ios && pod install`).
+#
+# The SHA256 must match the value posted in the binary repo's release notes,
+# and the URL must match the binary repo's `Package.swift` entry. Bumping the
+# native version means updating BOTH constants below (and in the podspec
+# comment), then re-running.
+
+set -euo pipefail
+
+VERSION="0.0.1"
+URL="https://github.com/wayqteam/beekon-ios-binary/releases/download/v${VERSION}/BeekonKit.xcframework.zip"
+EXPECTED_SHA="f7bd79a6d61994977318daa6d722866abd0a61d7d7e5834ab5307df39b6ee60e"
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+DEST_DIR="${ROOT}/ios/Frameworks"
+TARGET="${DEST_DIR}/BeekonKit.xcframework"
+
+if [ -d "${TARGET}" ]; then
+  echo "fetch-beekonkit: ${TARGET} already present, skipping"
+  exit 0
+fi
+
+mkdir -p "${DEST_DIR}"
+ZIP="${DEST_DIR}/BeekonKit.xcframework.zip"
+
+echo "fetch-beekonkit: downloading ${URL}"
+curl -fsSL "${URL}" -o "${ZIP}"
+
+# `shasum` ships with macOS, `sha256sum` with most Linux distros. CI publish
+# runs on Linux for cost reasons, so support both.
+if command -v shasum >/dev/null 2>&1; then
+  actual=$(shasum -a 256 "${ZIP}" | awk '{print $1}')
+elif command -v sha256sum >/dev/null 2>&1; then
+  actual=$(sha256sum "${ZIP}" | awk '{print $1}')
+else
+  echo "fetch-beekonkit: neither shasum nor sha256sum found in PATH" >&2
+  rm -f "${ZIP}"
+  exit 1
+fi
+
+if [ "${actual}" != "${EXPECTED_SHA}" ]; then
+  echo "fetch-beekonkit: SHA256 mismatch" >&2
+  echo "  expected: ${EXPECTED_SHA}" >&2
+  echo "  actual:   ${actual}" >&2
+  rm -f "${ZIP}"
+  exit 1
+fi
+
+echo "fetch-beekonkit: SHA256 verified, extracting"
+unzip -q -o "${ZIP}" -d "${DEST_DIR}"
+rm "${ZIP}"
+echo "fetch-beekonkit: ${TARGET} ready"

package/src/NativeBeekonRn.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+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;
+};
+
+export type WireConfig = {
+  /** One of: 'saver' | 'balanced' | 'precision'. */
+  preset: string;
+  distanceFilterMeters?: number;
+  intervalMillis?: number;
+  androidNotification?: WireAndroidNotification;
+  licenseKey?: string;
+};
+
+export type WirePosition = {
+  lat: number;
+  lng: number;
+  accuracy: number;
+  speed: number;
+  bearing: number;
+  altitude: number;
+  timestampMs: number;
+};
+
+export type WireState = {
+  /** One of: 'idle' | 'starting' | 'tracking' | 'paused' | 'stopped'. */
+  type: string;
+  /**
+   * Only populated when `type === 'paused'`. One of:
+   * 'permissionRevoked' | 'locationDisabled' | 'unknown'.
+   */
+  pauseReason?: 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[]>;
+
+  readonly onState: CodegenTypes.EventEmitter<WireState>;
+  readonly onPosition: CodegenTypes.EventEmitter<WirePosition>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('BeekonRn');

package/src/beekon.ts

@@ -0,0 +1,110 @@
+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';
+
+/**
+ * Public facade for the Beekon SDK. Mirrors the native APIs:
+ *
+ * - Android: `com.wayq.beekon.Beekon` (object)
+ * - iOS:     `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.
+ *
+ * **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()`.
+ */
+class BeekonImpl {
+  /**
+   * 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.
+   */
+  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.
+   */
+  async configure(config: BeekonConfig): Promise<void> {
+    return NativeBeekon.configure(configToWire(config));
+  }
+
+  /**
+   * 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.
+   */
+  async start(): Promise<void> {
+    return NativeBeekon.start();
+  }
+
+  /** Stop tracking. Idempotent. State → `stopped`. */
+  async stop(): Promise<void> {
+    return NativeBeekon.stop();
+  }
+
+  /**
+   * 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
+   * 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.
+   */
+  async history(from: Date, to: Date): Promise<Position[]> {
+    const wires = await NativeBeekon.history(from.getTime(), to.getTime());
+    return wires.map(wireToPosition);
+  }
+
+  /**
+   * 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).
+   */
+  onState(cb: (s: BeekonState) => void): () => void {
+    const subscription = NativeBeekon.onState((wire) => cb(wireToState(wire)));
+    return () => subscription.remove();
+  }
+
+  /**
+   * 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()`.
+   */
+  onPosition(cb: (p: Position) => void): () => void {
+    const subscription = NativeBeekon.onPosition((wire) =>
+      cb(wireToPosition(wire))
+    );
+    return () => subscription.remove();
+  }
+}
+
+export const Beekon = new BeekonImpl();

package/src/index.tsx

@@ -0,0 +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';

package/src/internal/mappers.ts

@@ -0,0 +1,50 @@
+import type { BeekonConfig } from '../types/config';
+import type { BeekonState, PauseReason } from '../types/state';
+import type { Position } from '../types/position';
+import type { WireConfig, WirePosition, WireState } from '../NativeBeekonRn';
+
+export function configToWire(config: BeekonConfig): WireConfig {
+  return {
+    preset: config.preset ?? 'balanced',
+    distanceFilterMeters: config.distanceFilterMeters,
+    intervalMillis: config.intervalMillis,
+    androidNotification: config.androidNotification,
+    licenseKey: config.licenseKey,
+  };
+}
+
+export function wireToPosition(w: WirePosition): Position {
+  return {
+    lat: w.lat,
+    lng: w.lng,
+    accuracy: w.accuracy,
+    speed: w.speed,
+    bearing: w.bearing,
+    altitude: w.altitude,
+    timestamp: new Date(w.timestampMs),
+  };
+}
+
+function toPauseReason(s: string | undefined): PauseReason {
+  if (s === 'permissionRevoked' || s === 'locationDisabled') return s;
+  return 'unknown';
+}
+
+export function wireToState(w: WireState): BeekonState {
+  switch (w.type) {
+    case 'idle':
+      return { kind: 'idle' };
+    case 'starting':
+      return { kind: 'starting' };
+    case 'tracking':
+      return { kind: 'tracking' };
+    case 'paused':
+      return { kind: 'paused', reason: toPauseReason(w.pauseReason) };
+    case 'stopped':
+      return { kind: 'stopped' };
+    default:
+      // Defensive fallback. Native should never emit an unknown state, but
+      // forward-compat: treat as idle rather than throwing.
+      return { kind: 'idle' };
+  }
+}