@wayq/beekon-rn 0.0.5 → 0.0.6

package/BeekonRn.podspec

@@ -10,8 +10,10 @@ 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-rn.git", :tag => "v#{s.version}" }
 

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 at version **0.0.5**. The public TypeScript surface mirrors the Kotlin / Swift APIs in shape: a 12-method `Beekon` singleton, four callback streams (`state`, `locations`, `geofenceEvents`, `syncStatus`), geofencing, and optional server sync.
+<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 contains no location logic — all tracking, persistence, geofencing, and OS integration live natively. **Writes never cross into JavaScript**: in the 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>
 
-There is **no `initialize()`** — the native SDKs auto-initialize. `start()` / `stop()` **never throw**: subscribe to `onState` to learn whether tracking is active and why it stopped.
+<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** (required by the native AAR) |
-| 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 — the package fetches and bundles `BeekonKit.xcframework` (SHA256-verified) during `prepare`, so just install pods:
+**iOS** — install pods:
 
 ```sh
 cd ios && pod install
 ```
 
-Android — Maven Central is auto-included by the autolinker; the native AAR (`io.github.wayqteam:beekon`) is pulled transitively.
+**Android** — no additional steps; the module links automatically.
+
+## 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 — your app must (e.g. via [`react-native-permissions`](https://github.com/zoontek/react-native-permissions) or `PermissionsAndroid`). Foreground location works without background location.
+### Android
 
-**Android** (`AndroidManifest.xml`):
+In `android/app/src/main/AndroidManifest.xml`:
 
 ```xml
 <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
@@ -45,20 +72,21 @@ The library does NOT request permissions — your app must (e.g. via [`react-nat
 <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 when BeekonConfig.detectActivity is enabled -->
+<!-- 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>
-<!-- Only when BeekonConfig.detectActivity is enabled -->
-<key>NSMotionUsageDescription</key>
-<string>…</string>
+<string>Explain why your app uses location in the background.</string>
 <key>UIBackgroundModes</key>
 <array>
   <string>location</string>
@@ -68,101 +96,295 @@ The library does NOT request permissions — your app must (e.g. via [`react-nat
 <array>
   <string>in.wayq.beekon.sync</string>
 </array>
+<!-- Only if you enable detectActivity -->
+<key>NSMotionUsageDescription</key>
+<string>Explain why your app detects activity.</string>
 ```
 
-## Background-task registration (iOS)
-
-For background sync scheduling and cold-launch resume, register Beekon's background task **synchronously during app launch** (it must run before `didFinishLaunchingWithOptions` returns). In your `AppDelegate.swift`:
+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: …) -> Bool {
+func application(
+  _ application: UIApplication,
+  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+) -> Bool {
   BeekonRnImpl.registerBackgroundTasks()
-  // … React Native setup …
+  // ...your existing setup...
   return true
 }
 ```
 
-Foreground tracking and the JS streams work without this; only background sync / relaunch need it.
+## Usage
 
-## Cold-launch resume (Android)
+### Start tracking
 
-To resume tracking after the OS killed the process, call `in.wayq.beekon.Beekon.start()` from your `Application.onCreate` (native — the JS engine may not be running on a background relaunch). From JS, `Beekon.resumeIfNeeded()` covers the foreground case.
+```ts
+import { Beekon } from '@wayq/beekon-rn';
 
-## Usage
+const offState = Beekon.onState((state) => {
+  console.log('state:', state.kind); // 'idle' | 'tracking' | 'stopped'
+});
+
+const offLocation = Beekon.onLocation((location) => {
+  console.log(location.latitude, location.longitude, location.timestamp);
+});
+
+// Configure is optional. Request OS permissions before starting.
+await Beekon.configure({
+  minTimeBetweenLocationsSeconds: 30,
+  minDistanceBetweenLocationsMeters: 100,
+});
+
+await Beekon.start();
+
+// Later:
+await Beekon.stop();
+offState();
+offLocation();
+```
+
+`start()` and `stop()` never throw. Observe `onState` to learn whether tracking began and why it stopped:
+
+```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
-import { Beekon, type BeekonState, type Location } from '@wayq/beekon-rn';
+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']);
+```
 
-// Subscribe — each returns an unsubscribe function. `onState` / `onSyncStatus`
-// replay the latest value to new subscribers; `onLocation` / `onGeofenceEvent`
-// are broadcast (no replay).
-const offState = Beekon.onState((s: BeekonState) => console.log('state', s));
-const offLoc = Beekon.onLocation((l: Location) => console.log('location', l));
+### Server sync
 
-// Configure (optional; defaults below). Pass 0 to disable a gate.
+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({
-  minTimeBetweenLocationsSeconds: 30, // default 30
-  minDistanceBetweenLocationsMeters: 100, // default 100
-  accuracyMode: 'balanced', // 'high' | 'balanced' | 'low'
-  whenStationary: 'pause', // 'keepTracking' | 'pause' | 'pauseWithCheckIns'
-  detectActivity: false,
-  // Optional server upload:
   sync: {
-    url: 'https://example.com/ingest',
-    headers: { Authorization: 'Bearer …' },
+    url: 'https://api.example.com/locations',
+    headers: { Authorization: 'Bearer <token>' },
+    // intervalSeconds defaults to 300, batchSize to 100
   },
-  // Android-only foreground-service notification:
-  notification: { title: 'Tracking', text: 'Recording your route' },
 });
 
-await Beekon.start(); // never throws — observe onState
-// … later
-await Beekon.stop();
+Beekon.setExtras({ userId: 'abc123' }); // attached to every upload
+
+Beekon.onSyncStatus((status) => {
+  console.log('sync:', status.kind); // 'idle' | 'pending' | 'failed'
+});
+```
 
-// History (local store; source of truth even when JS was asleep).
-const fixes = await Beekon.getLocations(new Date(Date.now() - 3600_000), new Date());
+#### Token refresh
 
-// Cleanup.
-offState();
-offLoc();
+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 |
 |---|---|
-| `configure(config)` | Set config. Optional, idempotent. Does not throw. |
-| `start()` | Begin tracking. Never throws — observe `onState`. |
-| `stop()` | Stop tracking. Idempotent. Never throws. |
-| `resumeIfNeeded()` | Resume a session active before the app was terminated. |
-| `getLocations(from, to)` | Read persisted fixes in `[from, to]`. Throws `'storage'`. |
-| `deleteLocations(before?)` | Delete fixes at/before `before` (all when omitted). Throws `'storage'`. |
-| `pendingUploadCount()` | Count of fixes not yet uploaded. Throws `'storage'`. |
-| `sync()` | Request an immediate upload (no-op if sync unconfigured). |
-| `setExtras(extras)` | Custom key/value fields sent with every upload. |
-| `addGeofences(geofences)` | Register geofences. Throws `'invalidGeofence'`. |
+| `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()` | The currently registered geofences. |
-| `onState(cb)` | Subscribe to state. Replay-1. Returns unsubscribe fn. |
-| `onLocation(cb)` | Subscribe to gated fixes. No replay. |
-| `onGeofenceEvent(cb)` | Subscribe to geofence enter/exit. No replay. |
-| `onSyncStatus(cb)` | Subscribe to upload health. Replay-1. |
+| `listGeofences()` | Currently registered geofences. |
 
-`BeekonState` is a discriminated union on `kind`: `'idle' | 'tracking' | 'stopped'`. The `'stopped'` variant carries `reason: 'user' | 'permissionDenied' | 'locationServicesDisabled' | 'locationUnavailable' | 'system'`.
+Subscriptions — each returns an unsubscribe function:
 
-`SyncStatus` is a union on `kind`: `'idle' | 'pending' | 'failed'`; `'failed'` carries `reason: 'auth' | 'rejected'`.
+| 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. |
 
-`Location` carries `id`, `latitude`, `longitude`, `timestamp`, the nullable `accuracy` / `speed` / `bearing` / `altitude`, plus `quality`, `trigger`, `motion`, `activity` (`null` unless `detectActivity`), and `isMock`. Optional numeric fields are `null` when the OS did not report a value — never `0`.
+`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.
 
-The **only** thrown errors are `BeekonError` instances with `kind: 'storage' | 'invalidGeofence'`. Permission / services / lifecycle problems are not thrown — they surface on `onState` as `stopped(reason)`.
+## Types
 
-## Storage, retention, and sync
+```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 the most recent 100 K rows**, whichever is smaller; auto-pruned on each write batch. With `sync` configured, accepted rows are deleted locally after upload, so `getLocations` / `pendingUploadCount` return only un-uploaded fixes.
+- **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

@@ -77,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.5"
+  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.