@wayq/beekon-rn 0.0.3 → 0.0.6

package/BeekonRn.podspec

@@ -10,10 +10,12 @@ Pod::Spec.new do |s|
   s.license      = package["license"]
   s.authors      = package["author"]
 
-  # BeekonKit targets iOS 17.0 (uses CLLocationUpdate.liveUpdates). The
-  # consuming app must also target iOS 17.0 or higher.
+  # iOS 17.0 floor reflects this wrapper's React Native baseline (RN 0.85), not
+  # a BeekonKit constraint — BeekonKit 0.0.6 itself supports iOS 13+ (with
+  # 13–16 fallback paths). Kept at 17.0 to avoid any consumer regression; do not
+  # lower below React Native's own minimum.
   s.platforms    = { :ios => "17.0" }
-  s.source       = { :git => "https://github.com/wayqteam/beekon.git", :tag => "v#{s.version}" }
+  s.source       = { :git => "https://github.com/wayqteam/beekon-rn.git", :tag => "v#{s.version}" }
 
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
   # Headers are only for the auto-generated `BeekonRn-Swift.h` interop — keep

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to `@wayq/beekon-rn` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Beekon is pre-1.0 — releases may contain breaking changes.
+
+## [0.0.6]
+
+Built against the native **0.0.6** API; requires native ≥ 0.0.6 at runtime.
+
+### Added
+
+- **Native token refresh** — `SyncConfig.auth` (`AuthConfig`) lets the SDK attach
+  and natively refresh the upload access token, proactively before expiry and
+  reactively on a `401`/`403`, and retry the upload — all natively, so it works in
+  the background and on a cold launch with no host involvement. Rotated credentials
+  surface on the new `Beekon.onAuthTokens()` subscription (`AuthTokens`). Adds the
+  `AuthConfig`, `AuthResponseMapping`, `AuthTokens` types and the `AuthStrategy` /
+  `AuthBodyFormat` enums. Omitting `auth` keeps the legacy static-`headers`
+  behaviour. The refresh recipe is persisted in plaintext to survive cold launch —
+  do not put static client secrets in `refreshHeaders`/`refreshPayload`.
+- **`getCurrentLocation({ timeoutMs, accuracy })`** — a one-shot current location,
+  independent of any tracking session (resolves `null` on timeout; never starts or
+  stops tracking; the fix is not persisted and does not appear on `onLocation`).
+  Re-introduces thrown `BeekonError` kinds `'permissionDenied'`,
+  `'locationServicesDisabled'`, and `'locationUnavailable'` on a precondition
+  failure (0.0.5 had removed the `PERMISSION_DENIED` / `LOCATION_SERVICES_DISABLED`
+  thrown errors; they now surface again, but only from `getCurrentLocation()` —
+  tracking-lifecycle problems still report through `onState` as `Stopped(reason)`).
+- **`NotificationConfig.smallIcon`** — a custom Android status-bar icon (drawable /
+  mipmap resource name) for the foreground-service tracking notification.
+
+### Changed
+
+- `androidNotification` (type `AndroidNotificationConfig`) renamed to `notification`
+  (type `NotificationConfig`) — **breaking**. The config remains Android-only; iOS
+  ignores it.
+- `deleteLocations(before)` cutoff is now strictly **before** `before` (exclusive
+  `<`), aligning both natives and all wrappers; the prior wording said "at or
+  before".
+- `resumeIfNeeded()` now calls the guarded native `Beekon.resumeIfNeeded()` on
+  Android (previously `Beekon.start()`): it re-adopts a previously-active,
+  non-user-stopped session only, mirroring iOS.
+- Native pins bumped to `0.0.6` (Maven `io.github.wayqteam:beekon`, iOS
+  `BeekonKit.xcframework`).
+
+## [0.0.5]
+
+Full rebuild against the native **0.0.5** API — a breaking, no-backward-compat
+release. The TypeScript surface is a faithful 1:1 mirror of the native `Beekon`
+(Android) / `Beekon.shared` (iOS).
+
+### Added
+
+- **Server sync**: `SyncConfig` on `BeekonConfig`, plus `sync()`, `setExtras()`,
+  `pendingUploadCount()`, and the `onSyncStatus` subscription
+  (`SyncIdle`/`SyncPending`/`SyncFailed`).
+- **Geofencing**: `addGeofences()` / `removeGeofences()` / `listGeofences()` and
+  the `onGeofenceEvent` subscription (`BeekonGeofence`, `GeofenceEvent`,
+  `Transition`).
+- **Richer config**: `accuracyMode`, `whenStationary`, `stationaryRadiusMeters`,
+  `detectActivity`.
+- **Richer `Location`**: `id`, `quality`, `trigger`, `motion`, `activity`,
+  `isMock`.
+- `deleteLocations(before)`, `resumeIfNeeded()` (wrapper-only cold-launch resume,
+  not part of the native spec), and `StopReason 'locationUnavailable'`.
+
+### Changed
+
+- `intervalSeconds` → `minTimeBetweenLocationsSeconds`; `distanceMeters` →
+  `minDistanceBetweenLocationsMeters`.
+- `getLocations(from: Date, to: Date)` replaces the prior history call.
+- Notification config is now `androidNotification` (Android-only; iOS ignores it).
+- Native pins bumped to `0.0.5` (Maven `io.github.wayqteam:beekon`, SwiftPM
+  `beekon-ios-binary`).
+
+### Removed
+
+- `PERMISSION_DENIED` / `LOCATION_SERVICES_DISABLED` thrown errors — permission
+  and service problems now surface only on `onState` as `Stopped(reason)`.
+
+## [0.0.3]
+
+First synchronized release across all four registries (Maven Central,
+`wayqteam/beekon-ios-binary` xcframework, pub.dev, npm). `Location`
+accuracy/speed/bearing/altitude are nullable to faithfully represent providers
+that don't deliver them.
+
+## [0.0.1]
+
+Initial release.
+
+### Added
+
+- React Native (New Architecture / TurboModule) binding for the native Beekon
+  location SDKs (Android `io.github.wayqteam:beekon`, iOS `BeekonKit`
+  xcframework).
+- Public API mirroring the native surface: `Beekon.configure / start / stop /
+  getLocations`, plus `onState` / `onLocation` subscriptions.
+- `BeekonConfig`, `BeekonState` (`idle → tracking → stopped(reason)`),
+  `Location`, and typed `BeekonError` kinds.

package/README.md

@@ -1,43 +1,70 @@
-# @wayq/beekon-rn
+<p align="center">
+  <img src="assets/icon.png" alt="Beekon" width="140" />
+</p>
 
-React Native binding for the [Beekon](https://github.com/wayqteam/beekon) location SDK.
+<h1 align="center">@wayq/beekon-rn</h1>
 
-A thin pass-through over the native Android (`io.github.wayqteam:beekon`) and iOS (`BeekonKit`) libraries. The public TypeScript surface mirrors the Kotlin / Swift APIs in shape: `configure / start / stop`, callback-backed `state` and `locations` streams, and a `history(from, to)` query.
+<p align="center">
+  Background location tracking for React Native.<br/>
+  Native location stack on each platform — tracking survives backgrounding and termination.
+</p>
 
-Built on the React Native New Architecture (TurboModules + Codegen). The binding is a thin delegation layer — all logic, persistence, and OS integration lives natively. **Writes never cross into JavaScript**: in background the JS engine isn't guaranteed to be alive, so the native libraries own the persistence path end-to-end.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@wayq/beekon-rn"><img alt="npm" src="https://img.shields.io/npm/v/@wayq/beekon-rn?label=npm&logo=npm&logoColor=white&color=CB3837&style=flat-square"></a>
+  <img alt="React Native · New Architecture" src="https://img.shields.io/badge/React%20Native-New%20Arch-61DAFB?logo=react&logoColor=white&style=flat-square">
+  <img alt="Platforms · Android | iOS" src="https://img.shields.io/badge/platforms-Android%20%7C%20iOS-61DAFB?style=flat-square">
+</p>
+
+<p align="center">
+  <a href="https://docs.getbeekon.com"><strong>Docs</strong></a> ·
+  <a href="https://console.getbeekon.com"><strong>Console</strong></a> ·
+  <a href="https://getbeekon.com"><strong>getbeekon.com</strong></a> ·
+  <a href="https://github.com/wayqteam/beekon"><strong>Umbrella</strong></a>
+</p>
+
+---
+
+Capture GPS in the foreground and background, keep a queryable history on the device, define geofences, and optionally sync to your own server. The JavaScript API is fully typed.
+
+## Features
+
+- Foreground and background tracking that survives app termination
+- Battery-aware capture: time and distance filtering, accuracy presets, and automatic pausing while the device is stationary
+- On-device history you can query at any time
+- Geofencing with enter and exit events
+- Optional batched server sync with automatic retry
+- Activity detection (walking, running, cycling, automotive)
+- Built for the React Native New Architecture
 
 ## Requirements
 
-| Area | Floor |
+| | Minimum |
 |---|---|
-| React Native | 0.76+ (target 0.85) |
+| React Native | 0.76 (New Architecture) |
 | iOS | 17.0 |
-| Android | API 26 |
-| New Architecture | required (Old Arch is unsupported) |
+| Android | 8.0 (API level 26) |
 
-## Install
+## Installation
 
 ```sh
 npm install @wayq/beekon-rn
-# or
-yarn add @wayq/beekon-rn
 ```
 
-iOS:
+**iOS** — install pods:
 
 ```sh
 cd ios && pod install
 ```
 
-The package bundles `BeekonKit.xcframework` directly — no manual SwiftPM setup needed.
+**Android** — no additional steps; the module links automatically.
 
-Android: Maven Central is auto-included by the autolinker. The native AAR (`io.github.wayqteam:beekon`) is pulled transitively.
+## Permissions and setup
 
-## Permissions
+Beekon does not request permissions on your behalf. Declare them in your app and request them at runtime (for example with `PermissionsAndroid` or `react-native-permissions`).
 
-The library does NOT request permissions itself — your app must. Use a library like [`react-native-permissions`](https://github.com/zoontek/react-native-permissions) or platform APIs.
+### Android
 
-**Android** (`AndroidManifest.xml`):
+In `android/app/src/main/AndroidManifest.xml`:
 
 ```xml
 <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
@@ -45,72 +72,319 @@ The library does NOT request permissions itself — your app must. Use a library
 <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
 <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
 <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+<!-- Only if you enable detectActivity -->
+<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
 ```
 
-**iOS** (`Info.plist`):
+While tracking, Android shows a persistent notification (required by the system). Set its title and text with the `notification` option.
+
+### iOS
+
+In `Info.plist`:
 
 ```xml
 <key>NSLocationWhenInUseUsageDescription</key>
-<string>...</string>
+<string>Explain why your app uses location.</string>
 <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
-<string>...</string>
+<string>Explain why your app uses location in the background.</string>
 <key>UIBackgroundModes</key>
-<array><string>location</string></array>
+<array>
+  <string>location</string>
+  <string>fetch</string>
+</array>
+<key>BGTaskSchedulerPermittedIdentifiers</key>
+<array>
+  <string>in.wayq.beekon.sync</string>
+</array>
+<!-- Only if you enable detectActivity -->
+<key>NSMotionUsageDescription</key>
+<string>Explain why your app detects activity.</string>
+```
+
+Register Beekon's background task once during launch (required for background sync and to resume tracking after the app is terminated). In `AppDelegate.swift`:
+
+```swift
+import BeekonRn
+
+func application(
+  _ application: UIApplication,
+  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+) -> Bool {
+  BeekonRnImpl.registerBackgroundTasks()
+  // ...your existing setup...
+  return true
+}
 ```
 
 ## Usage
 
+### Start tracking
+
 ```ts
-import { Beekon, type BeekonState, type Location } from '@wayq/beekon-rn';
+import { Beekon } from '@wayq/beekon-rn';
 
-// Subscribe — returns an unsubscribe function. State replays the latest value
-// to new subscribers; locations is broadcast (no replay).
-const offState = Beekon.onState((s: BeekonState) => console.log('state', s));
-const offLoc = Beekon.onLocation((l: Location) => console.log('location', l));
+const offState = Beekon.onState((state) => {
+  console.log('state:', state.kind); // 'idle' | 'tracking' | 'stopped'
+});
 
-// Configure. Defaults: 30 s / 100 m. Pass 0 to disable a gate.
+const offLocation = Beekon.onLocation((location) => {
+  console.log(location.latitude, location.longitude, location.timestamp);
+});
+
+// Configure is optional. Request OS permissions before starting.
 await Beekon.configure({
-  intervalSeconds: 10,
-  distanceMeters: 30,
-  androidNotification: {
-    title: 'Tracking',
-    text: 'Recording your route',
-    smallIconResName: 'ic_notification', // drawable in your app
-  },
+  minTimeBetweenLocationsSeconds: 30,
+  minDistanceBetweenLocationsMeters: 100,
 });
 
 await Beekon.start();
-// ... later
+
+// Later:
 await Beekon.stop();
+offState();
+offLocation();
+```
 
-// Read past fixes.
-const fixes = await Beekon.history(new Date(Date.now() - 3600_000), new Date());
+`start()` and `stop()` never throw. Observe `onState` to learn whether tracking began and why it stopped:
 
-// Cleanup.
-offState();
-offLoc();
+```ts
+Beekon.onState((state) => {
+  if (state.kind === 'stopped') {
+    // 'user' | 'permissionDenied' | 'locationServicesDisabled'
+    //   | 'locationUnavailable' | 'system'
+    console.log('stopped:', state.reason);
+  }
+});
+```
+
+### Read history
+
+Recorded fixes are stored on the device and remain available even after the app is closed.
+
+```ts
+const since = new Date(Date.now() - 24 * 60 * 60 * 1000);
+const fixes = await Beekon.getLocations(since, new Date());
+
+await Beekon.deleteLocations();      // delete everything
+await Beekon.deleteLocations(since); // delete up to a cutoff
 ```
 
+### Geofences
+
+```ts
+await Beekon.addGeofences([
+  { id: 'office', latitude: 37.331, longitude: -122.031, radiusMeters: 150 },
+]);
+
+const offGeofence = Beekon.onGeofenceEvent((event) => {
+  console.log(event.geofenceId, event.type); // 'enter' | 'exit'
+});
+
+await Beekon.listGeofences();
+await Beekon.removeGeofences(['office']);
+```
+
+### Server sync
+
+Add a `sync` config to upload recorded fixes and geofence events to your backend. Uploads are batched, retried automatically, and removed from the device once your server accepts them. Without a `sync` config, all data stays on the device.
+
+```ts
+await Beekon.configure({
+  sync: {
+    url: 'https://api.example.com/locations',
+    headers: { Authorization: 'Bearer <token>' },
+    // intervalSeconds defaults to 300, batchSize to 100
+  },
+});
+
+Beekon.setExtras({ userId: 'abc123' }); // attached to every upload
+
+Beekon.onSyncStatus((status) => {
+  console.log('sync:', status.kind); // 'idle' | 'pending' | 'failed'
+});
+```
+
+#### Token refresh
+
+Set `sync.auth` (an `AuthConfig`) to let the SDK attach and **natively** refresh the upload access token — proactively before it expires and reactively on a `401`/`403`, then retry the upload. This runs in the background and survives a cold launch with no host involvement. Without `auth`, a `401`/`403` pauses sync and surfaces `SyncFailure 'auth'`; re-seed by calling `configure()` again to resume.
+
+The supplied tokens are a **seed**: the SDK owns and rotates the live token set in secure storage (Keychain / encrypted prefs) after first persist. Subscribe with `onAuthTokens` to mirror rotations into your own session store.
+
+```ts
+await Beekon.configure({
+  sync: {
+    url: 'https://api.example.com/locations',
+    auth: {
+      accessToken: '<initial access token>',
+      refreshToken: '<initial refresh token>',
+      expiresAt: new Date(Date.now() + 3600_000),
+      refreshUrl: 'https://auth.example.com/oauth/token',
+      refreshPayload: {
+        grant_type: 'refresh_token',
+        refresh_token: '{refreshToken}', // substituted with the current token
+      },
+      // strategy defaults to 'bearer', refreshBodyFormat to 'form',
+      // skewMarginSeconds to 60. responseMapping defaults to common-name detection.
+    },
+  },
+});
+
+const offAuth = Beekon.onAuthTokens((tokens) => {
+  // Persist the rotated set into your own session store.
+  console.log('rotated:', tokens.accessToken, tokens.expiresAt, tokens.epoch);
+});
+```
+
+The refresh recipe is persisted in plaintext to survive a cold launch — **do not** put static client secrets in `refreshHeaders` or `refreshPayload`. Requires the native SDK ≥ 0.0.6; with an older native binary the recipe is ignored and only static `sync.headers` apply.
+
+## Configuration
+
+All options are optional; defaults are shown.
+
+| Option | Default | Description |
+|---|---|---|
+| `minTimeBetweenLocationsSeconds` | `30` | Minimum seconds between recorded fixes. `0` disables the time filter. |
+| `minDistanceBetweenLocationsMeters` | `100` | Minimum metres between recorded fixes. `0` disables the distance filter. |
+| `accuracyMode` | `'balanced'` | `'high'` \| `'balanced'` \| `'low'`. Trades accuracy against battery. |
+| `whenStationary` | `'pause'` | `'keepTracking'` \| `'pause'` \| `'pauseWithCheckIns'`. |
+| `stationaryRadiusMeters` | `5` | Distance the device must move to count as moving again. |
+| `detectActivity` | `false` | Detect physical activity. Requires the motion permission. |
+| `sync` | – | Server upload settings: `{ url, headers?, intervalSeconds?, batchSize?, auth? }`. See [Token refresh](#token-refresh). |
+| `notification` | – | Android-only tracking notification: `{ title?, text?, smallIcon? }`. `smallIcon` is a drawable/mipmap resource name. |
+
+A fix is recorded only when **both** the time and distance filters are satisfied.
+
 ## API
 
 | Method | Description |
 |---|---|
-| `Beekon.configure(config)` | Set sampling thresholds. Optional. |
-| `Beekon.start()` | Begin tracking. State → `tracking`. |
-| `Beekon.stop()` | Stop tracking. Idempotent. State → `stopped` (`reason: 'user'`). |
-| `Beekon.history(from, to)` | Read persisted fixes in range. |
-| `Beekon.onState(cb)` | Subscribe to state. Returns unsubscribe fn. |
-| `Beekon.onLocation(cb)` | Subscribe to gated fixes. Returns unsubscribe fn. |
+| `configure(config)` | Apply settings. Optional; may be called while tracking. |
+| `start()` | Begin tracking. |
+| `stop()` | Stop tracking. |
+| `resumeIfNeeded()` | Resume a session that was active before the app closed. |
+| `getCurrentLocation(options?)` | One-shot current fix, independent of tracking. Resolves `null` on timeout. `options`: `{ timeoutMs?, accuracy? }`. |
+| `getLocations(from, to)` | Recorded fixes within a date range. |
+| `deleteLocations(before?)` | Delete fixes (all if `before` is omitted); returns the count removed. |
+| `pendingUploadCount()` | Number of fixes not yet uploaded. |
+| `sync()` | Request an immediate upload. |
+| `setExtras(extras)` | Custom fields included with every upload. |
+| `addGeofences(geofences)` | Register circular regions. |
+| `removeGeofences(ids)` | Unregister geofences by id. |
+| `listGeofences()` | Currently registered geofences. |
+
+Subscriptions — each returns an unsubscribe function:
+
+| Subscription | Delivers |
+|---|---|
+| `onState(cb)` | Tracking state changes. The current state is delivered immediately. |
+| `onLocation(cb)` | Each newly recorded fix. |
+| `onGeofenceEvent(cb)` | Geofence enter and exit events. |
+| `onSyncStatus(cb)` | Upload status. The current status is delivered immediately. |
+| `onAuthTokens(cb)` | Token rotations from native refresh (see [Token refresh](#token-refresh)). The latest rotation is delivered immediately. |
 
-State is a discriminated union on `kind`: `'idle' | 'tracking' | 'stopped'`. The `'stopped'` variant carries a `reason: 'user' | 'permissionDenied' | 'locationServicesDisabled' | 'system'` (`'system'` is Android-only).
+`getLocations`, `deleteLocations`, `pendingUploadCount`, and `addGeofences` reject with a `BeekonError` on failure — check `error.kind` (`'storage'` or `'invalidGeofence'`). `getCurrentLocation` rejects with `error.kind` `'permissionDenied'`, `'locationServicesDisabled'`, or `'locationUnavailable'` on a precondition failure. Other methods resolve normally; tracking-lifecycle problems are reported through `onState` rather than thrown.
 
-Errors are thrown as `BeekonError` instances with `kind`:
-`'permissionDenied'`, `'locationServicesDisabled'`, `'storageFailure'`.
+## Types
 
-## Storage and retention
+```ts
+type Location = {
+  id: string;
+  latitude: number;
+  longitude: number;
+  timestamp: Date;
+  accuracy: number | null; // metres
+  speed: number | null; // m/s
+  bearing: number | null; // degrees from true north
+  altitude: number | null; // metres
+  quality: 'ok' | 'lowAccuracy' | 'implausibleSpeed';
+  trigger: 'interval' | 'motion' | 'checkIn' | 'geofence' | 'manual';
+  motion: 'moving' | 'stationary' | 'unknown';
+  activity:
+    | 'stationary' | 'walking' | 'running'
+    | 'cycling' | 'automotive' | 'unknown' | null;
+  isMock: boolean;
+};
+
+type BeekonState =
+  | { kind: 'idle' }
+  | { kind: 'tracking' }
+  | {
+      kind: 'stopped';
+      reason:
+        | 'user' | 'permissionDenied' | 'locationServicesDisabled'
+        | 'locationUnavailable' | 'system';
+    };
+
+type SyncStatus =
+  | { kind: 'idle' }
+  | { kind: 'pending' }
+  | { kind: 'failed'; reason: 'auth' | 'rejected' };
+
+type BeekonGeofence = {
+  id: string;
+  latitude: number;
+  longitude: number;
+  radiusMeters: number;
+  notifyOnEntry?: boolean; // default true
+  notifyOnExit?: boolean; // default true
+};
+
+type GeofenceEvent = {
+  id: string;
+  geofenceId: string;
+  type: 'enter' | 'exit';
+  timestamp: Date;
+};
+
+// Set on `SyncConfig.auth` to enable native token refresh. The token fields are
+// a seed — the SDK rotates them after first persist.
+type AuthConfig = {
+  accessToken?: string;
+  refreshToken?: string;
+  expiresAt?: Date;
+  strategy?: 'bearer' | 'raw'; // default 'bearer'
+  refreshUrl?: string; // omit to disable refresh
+  refreshPayload?: Record<string, string>; // '{refreshToken}' substituted
+  refreshHeaders?: Record<string, string>; // '{accessToken}' substituted
+  refreshBodyFormat?: 'form' | 'json'; // default 'form'
+  responseMapping?: {
+    accessToken?: string;
+    refreshToken?: string;
+    expiresIn?: string;
+    expiresAt?: string;
+  };
+  skewMarginSeconds?: number; // default 60
+  seedEpoch?: number;
+};
+
+// Delivered by `onAuthTokens` after each native rotation. Sensitive — in-process
+// only, never logged.
+type AuthTokens = {
+  accessToken: string;
+  refreshToken: string | null;
+  expiresAt: Date | null;
+  epoch: number; // monotonic generation, bumped on each refresh
+};
+```
+
+Optional numeric fields on `Location` are `null` when the device did not report them — never `0`.
+
+## Notes
 
-The native SDKs persist every gated fix locally (Room on Android, GRDB on iOS) — JS is a passive reader. Retention: **TTL 7 days OR most recent 100 K rows**, whichever is smaller; auto-pruned on each write batch.
+- **Retention.** Fixes are kept on the device for up to 7 days, or the most recent 100,000 fixes, whichever comes first.
+- **Background relaunch.** Call `resumeIfNeeded()` early in your app to restore tracking after the system terminates it. On Android, also resume from your `Application.onCreate` (see the example app).
+- **Android background limits.** Some manufacturers aggressively stop background services; if tracking halts unexpectedly, see [dontkillmyapp.com](https://dontkillmyapp.com).
+
+## Example
+
+A complete, runnable example is in the [`example/`](./example) directory.
 
 ## License
 
-Proprietary — see [LICENSE.txt](LICENSE.txt). Evaluation use only without a separate written agreement with wayqteam.
+Proprietary — evaluation use only without a separate written agreement with wayqteam. See [LICENSE.txt](./LICENSE.txt).
+
+---
+
+<p align="center">
+  © WayQ Technologies Pvt Ltd
+</p>

package/android/build.gradle

@@ -1,7 +1,8 @@
 buildscript {
   ext.BeekonRn = [
     kotlinVersion: "2.1.20",
-    minSdkVersion: 24,
+    // minSdk 26 is required by the native Beekon AAR (io.github.wayqteam:beekon).
+    minSdkVersion: 26,
     compileSdkVersion: 36,
     targetSdkVersion: 36
   ]
@@ -57,8 +58,12 @@ android {
   }
 
   compileOptions {
-    sourceCompatibility JavaVersion.VERSION_1_8
-    targetCompatibility JavaVersion.VERSION_1_8
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
   }
 }
 
@@ -72,7 +77,7 @@ dependencies {
   // Native Beekon SDK — published from beekon-android/ via Maven Central.
   // Pinned exact in v0.x to avoid surprise breakage; loosen to a range when
   // the SDK reaches v1 stability.
-  implementation "io.github.wayqteam:beekon:0.0.3"
+  implementation "io.github.wayqteam:beekon:0.0.6"
   // Kotlin coroutines — required for collecting Beekon's StateFlow/SharedFlow.
   // Beekon already depends on coroutines transitively, but declaring it here
   // makes the dependency intent explicit.