@wayq/beekon-rn 0.0.9 → 0.1.2

package/BeekonRn.podspec

@@ -15,7 +15,7 @@ Pod::Spec.new do |s|
   # 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}" }
+  s.source       = { :git => "https://github.com/beekonlabs/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
@@ -23,7 +23,7 @@ Pod::Spec.new do |s|
   s.private_header_files = "ios/**/*.h"
 
   # Native Beekon SDK as a vendored xcframework. The zip is fetched from
-  # `wayqteam/beekon-ios-binary`'s GitHub Release at this version into
+  # `beekonlabs/beekon-ios-binary`'s GitHub Release at this version into
   # `ios/Frameworks/` by `scripts/fetch-beekonkit.sh`, run via `yarn prepare`,
   # and bundled in the npm tarball at publish time. SHA256 verified before
   # extraction.

package/CHANGELOG.md

@@ -6,6 +6,69 @@ 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.1.2] - 2026-06-28
+
+### Added
+
+- **Per-geofence local notifications.** A `BeekonGeofence` may now carry an
+  optional `notification` (`GeofenceNotification`) that the SDK renders natively
+  at crossing time — offline and even when the app is killed. It takes a
+  required `delivery` (`'local'` is the only implemented mode; `'cloud'` is
+  reserved) plus optional `onEnter` / `onExit` `NotificationContent` (`title`
+  and `body` required; optional `importance` defaulting to `'high'`, `deepLink`,
+  and a flat `data` string map). `onEnter` requires `notifyOnEntry` and `onExit`
+  requires `notifyOnExit`; in self-managed mode `delivery` must be `'local'`.
+  Adds the `GeofenceNotification`, `NotificationContent`, `NotificationDelivery`,
+  and `NotificationImportance` types. Requires the native SDKs ≥ 0.1.2.
+- **`getRequiredPermissions()` — config-aware permission doctor.** Resolves the
+  OS permissions the *current configuration* needs as a
+  `PermissionRequirement[]`, each marked `satisfied` against the live grant —
+  the companion to the location-only `getPermissionStatus()` snapshot. Each
+  entry carries `permission` (`BeekonPermission`: `location` /
+  `backgroundLocation` / `activityRecognition` / `notifications`), `importance`
+  (`required` / `recommended`), `satisfied`, and a human-readable `rationale`,
+  reporting activity-recognition and, on Android, notifications too. Read-only;
+  never prompts — Beekon still never *requests* permission. Call after
+  `configure()`; in cloud mode it returns the conservative list. Adds the
+  `PermissionRequirement` and `PermissionImportance` types. Requires the native
+  SDKs ≥ 0.1.2.
+
+## [0.1.1] - 2026-06-23
+
+### Changed
+
+- **Native SDK pins bumped to 0.1.1** — Android Maven coordinate and iOS
+  xcframework (`fetch-beekonkit.sh` `VERSION` + `EXPECTED_SHA`) now track
+  BeekonKit / `beekon` 0.1.1 (device control plane, build-time license gate,
+  and related native fixes since 0.1.0).
+
+### Added
+
+- **Build-gate product id** — native registration now declares the React Native
+  wrapper product id for build-time license enforcement (build-gate-v1).
+
+## [0.1.0] - 2026-06-15
+
+### Changed
+
+- **Moved to the `beekonlabs` GitHub org.** The Android native dependency
+  coordinate is now `io.github.beekonlabs:beekon` (was `io.github.wayqteam:beekon`),
+  and the iOS xcframework is fetched from `github.com/beekonlabs/beekon-ios-binary`.
+  This is internal to the module — the npm package name (`@wayq/beekon-rn`) is
+  unchanged and no consumer code changes are required.
+
+### Added
+
+- **`getPermissionStatus()` — read-only permission query.** Resolves the current
+  location grant as a `PermissionStatus` (`level`: `notDetermined` / `denied` /
+  `restricted` / `foreground` / `background`; nullable `accuracy`: `full` /
+  `reduced`) for pre-start checks, without ever prompting. Adds the
+  `PermissionLevel` / `PermissionAccuracy` types and `isAuthorized` /
+  `canTrackInBackground`. Beekon still never *requests* permission — the app owns
+  that; during tracking, loss surfaces on `onState`. On Android, "not yet asked"
+  and "denied" both report `notDetermined`; `restricted` is iOS-only. Requires
+  the native SDKs ≥ the release that adds the API.
+
 ## [0.0.9] - 2026-06-14
 
 ### Added
@@ -34,7 +97,7 @@ Beekon is pre-1.0 — releases may contain breaking changes.
   discriminator (`'cloud'` | `'selfManaged'`) is now required. Tracking params,
   `sync`, and `licenseKey` live only on the `selfManaged` arm.
 
-[beekon#20]: https://github.com/wayqteam/beekon/issues/20
+[beekon#20]: https://github.com/beekonlabs/beekon/issues/20
 
 ## [0.0.8]
 
@@ -43,7 +106,7 @@ No binding API changes.
 
 ### Changed
 
-- Native pins bumped to `0.0.8` (Maven `io.github.wayqteam:beekon`, `BeekonKit`
+- Native pins bumped to `0.0.8` (Maven `io.github.beekonlabs:beekon`, `BeekonKit`
   xcframework). 0.0.8 embeds the production ES256 license verification keyset,
   so genuine `license-format-v1` tokens resolve to `licensed` / `evaluation`
   on-device, and hardens wire/license conformance. The license surface remains a
@@ -70,7 +133,7 @@ Built against the native **0.0.7** API; requires native ≥ 0.0.7 at runtime.
     degrades, or delays the SDK; Android and iOS may legally diverge for the
     same app.
   - The binding identifies itself to the verifier as the `rn` product.
-- Native pins bumped to `0.0.7` (Maven `io.github.wayqteam:beekon`, `BeekonKit`
+- Native pins bumped to `0.0.7` (Maven `io.github.beekonlabs:beekon`, `BeekonKit`
   xcframework).
 
 ## [0.0.6]
@@ -110,7 +173,7 @@ Built against the native **0.0.6** API; requires native ≥ 0.0.6 at runtime.
 - `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
+- Native pins bumped to `0.0.6` (Maven `io.github.beekonlabs:beekon`, iOS
   `BeekonKit.xcframework`).
 
 ## [0.0.5]
@@ -140,7 +203,7 @@ release. The TypeScript surface is a faithful 1:1 mirror of the native `Beekon`
   `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
+- Native pins bumped to `0.0.5` (Maven `io.github.beekonlabs:beekon`, SwiftPM
   `beekon-ios-binary`).
 
 ### Removed
@@ -151,7 +214,7 @@ release. The TypeScript surface is a faithful 1:1 mirror of the native `Beekon`
 ## [0.0.3]
 
 First synchronized release across all four registries (Maven Central,
-`wayqteam/beekon-ios-binary` xcframework, pub.dev, npm). `Location`
+`beekonlabs/beekon-ios-binary` xcframework, pub.dev, npm). `Location`
 accuracy/speed/bearing/altitude are nullable to faithfully represent providers
 that don't deliver them.
 
@@ -162,7 +225,7 @@ Initial release.
 ### Added
 
 - React Native (New Architecture / TurboModule) binding for the native Beekon
-  location SDKs (Android `io.github.wayqteam:beekon`, iOS `BeekonKit`
+  location SDKs (Android `io.github.beekonlabs:beekon`, iOS `BeekonKit`
   xcframework).
 - Public API mirroring the native surface: `Beekon.configure / start / stop /
   getLocations`, plus `onState` / `onLocation` subscriptions.

package/LICENSE.txt

@@ -1,9 +1,9 @@
 Beekon SDK
-Copyright (c) 2026 wayqteam. All rights reserved.
+Copyright (c) 2026 beekonlabs. All rights reserved.
 
 This software is licensed for evaluation use only. No production deployment,
 redistribution, sublicensing, or commercial use is permitted without a separate
-written agreement with wayqteam.
+written agreement with beekonlabs.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
@@ -11,4 +11,4 @@ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
 FROM USE OF THE SOFTWARE.
 
-For licensing inquiries: contact wayqteam.
+For licensing inquiries: contact beekonlabs.

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   Background location tracking for React Native.<br/>
-  Native location stack on each platform — tracking survives backgrounding and termination.
+  A native location stack on each platform — tracking survives backgrounding and termination.
 </p>
 
 <p align="center">
@@ -17,24 +17,22 @@
 
 <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>
+  <a href="https://github.com/beekonlabs/beekon"><strong>GitHub</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.
+Capture location in the foreground and background, keep a queryable history on the device, define geofences, and optionally upload to a backend **you** control. Nothing leaves the device unless you set a `sync` endpoint. 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
+- Battery-aware capture: time/distance filtering, accuracy presets, auto-pause while stationary
 - On-device history you can query at any time
-- Geofencing with enter and exit events
+- Geofencing with enter and exit events, plus optional per-geofence local notifications that fire offline and even when the app is killed
 - Optional batched server sync with automatic retry
-- Beekon Cloud mode: point at a project with a `bkproj_` key and let the server own tracking config, geofences, and license
-- Diagnostic logging: query/export an on-device log buffer and stream live entries for field debugging
+- Diagnostic logging: query/export an on-device buffer, stream live entries
 - Activity detection (walking, running, cycling, automotive)
 - Built for the React Native New Architecture
 
@@ -46,19 +44,107 @@ Capture GPS in the foreground and background, keep a queryable history on the de
 | iOS | 17.0 |
 | Android | 8.0 (API level 26) |
 
-## Installation
+## Install
 
 ```sh
 npm install @wayq/beekon-rn
 ```
 
-**iOS** — install pods:
+**iOS** — `cd ios && pod install`. **Android** — no extra steps; the module links automatically. See [Setup](#permissions-and-setup) for the OS config.
 
-```sh
-cd ios && pod install
+## Quick start
+
+```ts
+import { Beekon } from '@wayq/beekon-rn';
+
+const offState = Beekon.onState((state) => console.log('state:', state.kind));
+const offLocation = Beekon.onLocation((loc) =>
+  console.log(loc.latitude, loc.longitude, loc.timestamp),
+);
+
+// Configure is optional. Request OS permissions before starting (see Setup).
+await Beekon.configure({
+  mode: 'selfManaged',
+  minTimeBetweenLocationsSeconds: 30,
+  minDistanceBetweenLocationsMeters: 100,
+});
+
+await Beekon.start();
+```
+
+`start()` and `stop()` never throw. Observe `onState` to learn whether tracking began and why it stopped (`'user' | 'permissionDenied' | 'locationServicesDisabled' | 'locationUnavailable' | 'system'`).
+
+## Send to your backend
+
+Add a `sync` config and Beekon uploads fixes and geofence events to your backend — batched, retried, and removed from the device once your server accepts them. Without a `sync` config, all data stays on the device.
+
+```ts
+await Beekon.configure({
+  mode: 'selfManaged',
+  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));
+```
+
+Your server receives a small JSON envelope and acknowledges it with a status code. **[Build your ingest endpoint](https://docs.getbeekon.com/backend/ingest/)** is a complete, working example. For rotating bearer tokens, set `sync.auth` and the SDK attaches and **natively refreshes** the token — proactively before expiry, reactively on a `401`/`403` — even in the background. See [Auth & token refresh](https://docs.getbeekon.com/backend/auth/).
+
+## More
+
+```ts
+// History (stored on the device, survives restarts)
+const since = new Date(Date.now() - 24 * 60 * 60 * 1000);
+const fixes = await Beekon.getLocations(since, new Date());
+
+// Geofences — enter/exit events that keep firing across launches
+await Beekon.addGeofences([
+  { id: 'office', latitude: 37.331, longitude: -122.031, radiusMeters: 150 },
+]);
+const offGeofence = Beekon.onGeofenceEvent((e) => console.log(e.geofenceId, e.type));
+
+// Per-geofence local notification — rendered natively at crossing time,
+// offline and even when the app is killed. Add `notification` to a geofence:
+await Beekon.addGeofences([
+  {
+    id: 'home',
+    latitude: 37.331,
+    longitude: -122.031,
+    radiusMeters: 150,
+    notification: {
+      delivery: 'local', // 'local' is the only implemented mode ('cloud' reserved)
+      onEnter: { title: 'Welcome home', body: 'You arrived', deepLink: 'myapp://home' },
+      onExit: { title: 'On the move', body: 'You left home', importance: 'default' },
+    },
+  },
+]);
+
+// One-shot fix, independent of tracking (null on timeout)
+const fix = await Beekon.getCurrentLocation();
+
+// Pre-start permission check (the app still owns the request)
+const status = await Beekon.getPermissionStatus();
+
+// Config-aware "permission doctor" — the OS permissions the CURRENT config
+// needs, each marked `satisfied` against the live grant (never prompts).
+// Call after configure(). Reports activity-recognition and, on Android,
+// notifications — not just location.
+const required = await Beekon.getRequiredPermissions();
+for (const r of required) {
+  // r.permission, r.importance ('required' | 'recommended'), r.satisfied, r.rationale
+  if (!r.satisfied) console.log(`${r.permission} (${r.importance}): ${r.rationale}`);
+}
+
+// Diagnostics — runtime level, live tail, NDJSON export for bug reports
+await Beekon.setLogLevel('debug');
+const logPath = await Beekon.exportLog();
 ```
 
-**Android** — no additional steps; the module links automatically.
+A **license key** is optional and purely observational — `configure({ mode: 'selfManaged', licenseKey: '<JWS>' })`, then read `licenseStatus()`; without one, Beekon runs in evaluation mode. The package ships full TypeScript types, so methods, config, and events are typed in your editor. Complete API and guides: **[docs.getbeekon.com](https://docs.getbeekon.com)**.
 
 ## Permissions and setup
 
@@ -78,7 +164,7 @@ In `android/app/src/main/AndroidManifest.xml`:
 <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
 ```
 
-While tracking, Android shows a persistent notification (required by the system). Set its title and text with the `notification` option.
+While tracking, Android shows a persistent notification (required by the system). Set its title and text with the `notification` config option.
 
 ### iOS
 
@@ -103,7 +189,7 @@ In `Info.plist`:
 <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`:
+Register Beekon's background task once during launch (required for background sync and to resume tracking after termination). In `AppDelegate.swift`:
 
 ```swift
 import BeekonRn
@@ -118,325 +204,24 @@ func application(
 }
 ```
 
-## Usage
-
-### Start tracking
-
-```ts
-import { Beekon } from '@wayq/beekon-rn';
-
-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({
-  mode: 'selfManaged',
-  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' | 'cloudModeUnavailable' | '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({
-  mode: 'selfManaged',
-  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({
-  mode: 'selfManaged',
-  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.
-
-### License
-
-Supply a Beekon license token (a `license-format-v1` JWS) with `licenseKey`. It is the highest-priority channel, overriding the platform manifest value (`in.wayq.beekon.license` meta-data on Android, `BeekonLicenseKey` in `Info.plist` on iOS); `undefined`, blank, or whitespace-only means unset. A token is app-id- and product-bound, so it is safe to commit to source control.
-
-```ts
-await Beekon.configure({
-  mode: 'selfManaged',
-  licenseKey: '<license-format-v1 JWS>',
-});
-```
-
-The license is **purely observational** — no status ever blocks, degrades, or delays the SDK. Read the current platform's status once with `licenseStatus()`, or subscribe with `onLicenseStatus` (the latest status is delivered immediately):
+## API at a glance
 
-```ts
-const status = await Beekon.licenseStatus();
-console.log('license:', status.status); // 'evaluation' | 'licensed' | ...
-
-const offLicense = Beekon.onLicenseStatus((s) => {
-  if (s.status === 'licensed') console.log('tier:', s.tier);
-});
-```
-
-Android and iOS validate independently and may legally report different statuses for the same app (for example a license scoped to `["android"]` reads `licensed` on Android and `invalid` / `productMismatch` on iOS). The value reflects only the platform you are running on.
+Methods: `configure` · `start` · `stop` · `resumeIfNeeded` · `getCurrentLocation` · `getLocations` · `deleteLocations` · `pendingUploadCount` · `sync` · `setExtras` · `addGeofences` · `removeGeofences` · `listGeofences` · `getPermissionStatus` · `getRequiredPermissions` · `licenseStatus` · `getLog` · `exportLog` · `clearLog` · `setLogLevel` · `log`.
 
-## Configuration
+Subscriptions (each returns an unsubscribe function): `onState` · `onLocation` · `onGeofenceEvent` · `onSyncStatus` · `onAuthTokens` · `onLicenseStatus` · `onLog`.
 
-`BeekonConfig` is a sealed two-arm union — pass `mode: 'selfManaged'` (the options below, all optional) or `mode: 'cloud'` (`{ projectKey, endpoint?, notification?, logLevel? }`, where the server owns tracking/geofences/license). Self-managed options (defaults 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?, syncThreshold?, auth? }`. See [Token refresh](#token-refresh). |
-| `notification` | – | Android-only tracking notification: `{ title?, text?, smallIcon? }`. `smallIcon` is a drawable/mipmap resource name. |
-| `licenseKey` | – | Beekon license token (`license-format-v1` JWS). Highest-priority supply channel; overrides the platform manifest value. See [License](#license). |
-
-A fix is recorded only when **both** the time and distance filters are satisfied.
-
-## API
-
-| Method | Description |
-|---|---|
-| `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. |
-| `licenseStatus()` | Current platform's license status (a `LicenseStatus`). Observational only. See [License](#license). |
-| `getLog(from, to)` | Persisted diagnostic log entries in a date range (oldest first). |
-| `exportLog()` | Serialize the log buffer to an NDJSON file; resolves the file path. |
-| `clearLog()` | Delete all persisted diagnostic log entries. |
-| `setLogLevel(level)` | Change the diagnostic log verbosity threshold at runtime. |
-| `log(level, message)` | Write a host-app breadcrumb into the SDK log pipeline (category `app`). |
-
-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. |
-| `onLicenseStatus(cb)` | License status changes (see [License](#license)). The current status is delivered immediately. |
-| `onLog(cb)` | Diagnostic log entries as they are recorded (broadcast, no replay). |
-
-`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.
-
-## Types
-
-```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' | 'cloudModeUnavailable' | '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
-};
-
-// Returned by `licenseStatus()` / delivered by `onLicenseStatus`. Observational
-// only — no status ever blocks the SDK. Use `status` as the discriminator.
-type LicenseStatus =
-  | { status: 'notDetermined' }
-  | { status: 'evaluation' }
-  | { status: 'expired' }
-  | { status: 'updateEntitlementLapsed' }
-  | { status: 'licensed'; tier: string; entitlements: string[] }
-  | { status: 'invalid'; reason: LicenseInvalidReason };
-
-type LicenseInvalidReason =
-  | 'malformed' | 'unknownKey' | 'badSignature'
-  | 'appIdMismatch' | 'productMismatch' | 'unsupportedVersion';
-
-type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
-
-type LogEntry = {
-  id: string;        // UUIDv7
-  timestamp: Date;
-  level: LogLevel;
-  category: string;  // e.g. 'location', 'sync'; host breadcrumbs use 'app'
-  message: string;
-};
-```
-
-Optional numeric fields on `Location` are `null` when the device did not report them — never `0`.
+Every method, type, and event is documented at **[docs.getbeekon.com](https://docs.getbeekon.com)** and typed in the package.
 
 ## Notes
 
-- **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).
+- **Retention.** Fixes are kept for up to 7 days, or the most recent 100,000 fixes, whichever comes first.
+- **Background relaunch.** Call `resumeIfNeeded()` early in startup to restore tracking after the system terminates the app. On Android, also resume from `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).
 
+## Beekon Cloud
+
+Prefer managed ingest, a console, and server-owned config instead of running your own backend? **Beekon Cloud** is in private beta — see the [docs](https://docs.getbeekon.com/cloud/).
+
 ## Example
 
 A complete, runnable example is in the [`example/`](./example) directory.