@wayq/beekon-rn 0.0.8 → 0.1.0

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,yEAAyE;IACzE,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,8EAA8E;IAC9E,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sDAAsD;IACtD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,6EAA6E;IAC7E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,8CAA8C;IAC9C,IAAI,EAAE,OAAO,CAAC;IACd;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,qDAAqD;IACrD,IAAI,EAAE,aAAa,CAAC;IACpB,yEAAyE;IACzE,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,8EAA8E;IAC9E,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sDAAsD;IACtD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,6EAA6E;IAC7E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY;IACvB,6DAA6D;8BAC9C,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,KAAG,WAAW;IAGtD,kEAAkE;qCAEvD,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,KACvC,iBAAiB;CAGZ,CAAC"}

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

@@ -59,4 +59,12 @@ export type AuthStrategy = 'bearer' | 'raw';
  * - `'json'` — `application/json`.
  */
 export type AuthBodyFormat = 'form' | 'json';
+/**
+ * Diagnostic log verbosity threshold. Ordered by increasing verbosity; an entry
+ * is recorded only when its level is at or below the active threshold
+ * ({@link BeekonConfig.logLevel} or {@link Beekon.setLogLevel}). The default is
+ * `'info'`, so coordinates (logged only at `'debug'`/`'verbose'`) stay out of the
+ * buffer. Mirrors the native `LogLevel`; see `spec/diagnostics/log-format-v1`.
+ */
+export type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
 //# sourceMappingURL=enums.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../../../src/types/enums.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,OAAO,GAAG,mBAAmB,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,QAAQ,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAExE,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,YAAY,GACZ,SAAS,GACT,SAAS,GACT,SAAS,GACT,YAAY,GACZ,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC"}
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../../../src/types/enums.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,OAAO,GAAG,mBAAmB,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,QAAQ,GACR,SAAS,GACT,UAAU,GACV,QAAQ,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAExE,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,YAAY,GACZ,SAAS,GACT,SAAS,GACT,SAAS,GACT,YAAY,GACZ,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC"}

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

@@ -0,0 +1,22 @@
+import type { LogLevel } from './enums';
+/**
+ * A single diagnostic log record from the Beekon SDK.
+ *
+ * Delivered live on {@link Beekon.onLog} and read back from the persisted ring
+ * buffer via {@link Beekon.getLog}. Entries survive process death — the point of
+ * the buffer is post-hoc field diagnosis. Mirrors the native `LogEntry`; see
+ * `spec/diagnostics/log-format-v1`.
+ */
+export type LogEntry = {
+    /** UUIDv7 — orders and dedups entries. */
+    id: string;
+    /** When the entry was recorded. */
+    timestamp: Date;
+    /** Severity. Always one of `'error'`…`'verbose'`. */
+    level: LogLevel;
+    /** Originating subsystem (e.g. `'location'`, `'sync'`); host breadcrumbs use `'app'`. */
+    category: string;
+    /** Human-readable, already-redacted text. */
+    message: string;
+};
+//# sourceMappingURL=log.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../../../src/types/log.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,SAAS,EAAE,IAAI,CAAC;IAChB,qDAAqD;IACrD,KAAK,EAAE,QAAQ,CAAC;IAChB,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC"}

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

@@ -0,0 +1,42 @@
+/**
+ * How far the host app's location grant reaches. Mirrors the native
+ * `PermissionStatus` level on both platforms.
+ *
+ * Normalized — not platform permission constants. `'restricted'` is **iOS-only**
+ * (MDM / Screen Time); on Android "not yet asked" and "denied" cannot be told
+ * apart without an `Activity`, so both report `'notDetermined'`.
+ *
+ * - `'notDetermined'` — not yet decided; request to proceed.
+ * - `'denied'` — the user denied access (iOS). User-fixable in Settings.
+ * - `'restricted'` — blocked by an unchangeable policy (iOS-only).
+ * - `'foreground'` — granted while in use; foreground tracking only.
+ * - `'background'` — granted at all times; background tracking works.
+ */
+export type PermissionLevel = 'notDetermined' | 'denied' | 'restricted' | 'foreground' | 'background';
+/**
+ * Precision of a granted location authorization. `null` unless granted.
+ *
+ * - `'full'` — precise location.
+ * - `'reduced'` — approximate only (iOS 14 / Android 12 "approximate").
+ */
+export type PermissionAccuracy = 'full' | 'reduced';
+/**
+ * A point-in-time snapshot of the location-permission grant, returned by
+ * `Beekon.getPermissionStatus()`. Mirrors the native `PermissionStatus`.
+ *
+ * Beekon never *requests* permission — the app owns that. This is a read-only
+ * query for pre-start checks; it never prompts. It is a snapshot, not an
+ * observer: once tracking is running, permission loss surfaces on the `onState`
+ * stream as `{ kind: 'stopped', reason: 'permissionDenied' }`.
+ */
+export type PermissionStatus = {
+    /** How far the grant reaches. */
+    level: PermissionLevel;
+    /** Precision of the grant, or `null` when not authorized. */
+    accuracy: PermissionAccuracy | null;
+    /** `true` when authorized at all — foreground or background. */
+    isAuthorized: boolean;
+    /** `true` when background tracking is authorized. */
+    canTrackInBackground: boolean;
+};
+//# sourceMappingURL=permission.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../../../../src/types/permission.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,QAAQ,GACR,YAAY,GACZ,YAAY,GACZ,YAAY,CAAC;AAEjB;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iCAAiC;IACjC,KAAK,EAAE,eAAe,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC,gEAAgE;IAChE,YAAY,EAAE,OAAO,CAAC;IACtB,qDAAqD;IACrD,oBAAoB,EAAE,OAAO,CAAC;CAC/B,CAAC"}

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

@@ -8,10 +8,13 @@
  *   (user-fixable in Settings).
  * - `'locationUnavailable'` — no usable location backend on this device (e.g.
  *   Google Play Services absent/outdated on Android). Not user-fixable.
+ * - `'cloudModeUnavailable'` — the SDK was configured for cloud mode but the
+ *   running build cannot operate it (cloud-mode-v1). Not user-fixable; switch to
+ *   a self-managed config or a cloud-capable SDK build.
  * - `'system'` — the OS terminated tracking (e.g. foreground-service kill,
  *   or an unrecoverable internal error).
  */
-export type StopReason = 'user' | 'permissionDenied' | 'locationServicesDisabled' | 'locationUnavailable' | 'system';
+export type StopReason = 'user' | 'permissionDenied' | 'locationServicesDisabled' | 'locationUnavailable' | 'cloudModeUnavailable' | 'system';
 /**
  * Tracking state. Mirrors the native `BeekonState` sealed type on both
  * platforms. Use the `kind` field as a discriminator.

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

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../../src/types/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,kBAAkB,GAClB,0BAA0B,GAC1B,qBAAqB,GACrB,QAAQ,CAAC;AAEb;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../../src/types/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,kBAAkB,GAClB,0BAA0B,GAC1B,qBAAqB,GACrB,sBAAsB,GACtB,QAAQ,CAAC;AAEb;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wayq/beekon-rn",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "description": "React Native binding for the Beekon location SDK (Android + iOS).",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -58,14 +58,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/wayqteam/beekon-rn.git"
+    "url": "git+https://github.com/beekonlabs/beekon-rn.git"
   },
-  "author": "wayqteam <wayqteam@users.noreply.github.com> (https://github.com/wayqteam)",
+  "author": "beekonlabs <beekonlabs@users.noreply.github.com> (https://github.com/beekonlabs)",
   "license": "SEE LICENSE IN LICENSE.txt",
   "bugs": {
-    "url": "https://github.com/wayqteam/beekon-rn/issues"
+    "url": "https://github.com/beekonlabs/beekon-rn/issues"
   },
-  "homepage": "https://github.com/wayqteam/beekon-rn#readme",
+  "homepage": "https://github.com/beekonlabs/beekon-rn#readme",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"

package/scripts/fetch-beekonkit.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Fetches BeekonKit.xcframework from wayqteam/beekon-ios-binary's GitHub
+# Fetches BeekonKit.xcframework from beekonlabs/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.
 #
@@ -13,12 +13,12 @@
 
 set -euo pipefail
 
-VERSION="0.0.8"
-URL="https://github.com/wayqteam/beekon-ios-binary/releases/download/v${VERSION}/BeekonKit.xcframework.zip"
-# SHA256 of the v0.0.8 BeekonKit.xcframework.zip. Matches the SwiftPM
-# `binaryTarget` checksum in beekon-ios-binary's Package.swift at tag v0.0.8
+VERSION="0.1.0"
+URL="https://github.com/beekonlabs/beekon-ios-binary/releases/download/v${VERSION}/BeekonKit.xcframework.zip"
+# SHA256 of the v0.0.9 BeekonKit.xcframework.zip. Matches the SwiftPM
+# `binaryTarget` checksum in beekon-ios-binary's Package.swift at tag v0.0.9
 # (SwiftPM's compute-checksum is the SHA256 of the zip).
-EXPECTED_SHA="c404ec60d4ec8950027dac671d60c88a47209d203112b59637f6c3f358f18c7b"
+EXPECTED_SHA="8a39d9360a05f117226381036a10d3cfeb71237f99fd8d800cfafda42d9657f2"
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 DEST_DIR="${ROOT}/ios/Frameworks"

package/src/NativeBeekonRn.ts

@@ -59,6 +59,7 @@ export type WireSyncConfig = {
   headers: WireKeyValue[];
   intervalSeconds: number;
   batchSize: number;
+  syncThreshold: number;
   /** Token-refresh recipe; omitted keeps static-header auth. */
   auth?: WireAuthConfig;
 };
@@ -71,7 +72,27 @@ export type WireNotificationConfig = {
 };
 
 export type WireConfig = {
-  /** All fields required at the wire level — the TS facade applies defaults. */
+  /**
+   * Configuration-ownership discriminator (cloud-mode-v1 §2). One of: 'cloud' |
+   * 'selfManaged'. The native side switches on this to build the matching arm of
+   * the sealed `BeekonConfig`.
+   */
+  mode: string;
+  /**
+   * Cloud arm only: the opaque project credential (`bkproj_…`). Omitted/empty for
+   * the self-managed arm; the native cloud arm trims it and rejects an empty key.
+   */
+  projectKey?: string;
+  /**
+   * Cloud arm only: base-URL override. Omitted means the native baked-in default
+   * (`https://api.getbeekon.com`). Ignored by the self-managed arm.
+   */
+  endpoint?: string;
+  /**
+   * Self-managed arm only (ignored by the cloud arm, which derives tracking
+   * config from the server). All fields required at the wire level — the TS
+   * facade applies defaults.
+   */
   minTimeBetweenLocationsSeconds: number;
   minDistanceBetweenLocationsMeters: number;
   /** One of: 'high' | 'balanced' | 'low'. */
@@ -91,6 +112,20 @@ export type WireConfig = {
    * object, so this field documents the shape rather than altering codegen.
    */
   licenseKey?: string;
+  /**
+   * Diagnostic log verbosity threshold (spec `diagnostics/log-format-v1` §1).
+   * One of: 'off' | 'error' | 'warn' | 'info' | 'debug' | 'verbose'.
+   */
+  logLevel: string;
+};
+
+export type WireLogEntry = {
+  id: string;
+  timestampMs: number;
+  /** One of: 'error' | 'warn' | 'info' | 'debug' | 'verbose'. */
+  level: string;
+  category: string;
+  message: string;
 };
 
 export type WireLocation = {
@@ -137,7 +172,7 @@ export type WireState = {
   /**
    * Only populated when `type === 'stopped'`. One of: 'user' |
    * 'permissionDenied' | 'locationServicesDisabled' | 'locationUnavailable' |
-   * 'system'.
+   * 'cloudModeUnavailable' | 'system'.
    */
   stopReason?: string;
 };
@@ -183,6 +218,21 @@ export type WireLicenseStatus = {
   reason: string | null;
 };
 
+/**
+ * Flat wire form of the current location-permission grant (read-only). `level`
+ * is the wire-stable identifier; `accuracy` is `''` (not null — Codegen has no
+ * portable nullable-enum) when location is not granted, else 'full' | 'reduced'.
+ */
+export type WirePermissionStatus = {
+  /**
+   * One of: 'notDetermined' | 'denied' | 'restricted' | 'foreground' |
+   * 'background'.
+   */
+  level: string;
+  /** 'full' | 'reduced', or '' when not granted. */
+  accuracy: string;
+};
+
 export interface Spec extends TurboModule {
   /**
    * The config crosses as an untyped object (`ReadableMap` on Android,
@@ -232,12 +282,30 @@ export interface Spec extends TurboModule {
    */
   licenseStatus(): Promise<WireLicenseStatus>;
 
+  /**
+   * The current location-permission grant (read-only; never prompts). For
+   * pre-start checks — during tracking, permission loss surfaces on `onState`.
+   */
+  getPermissionStatus(): Promise<WirePermissionStatus>;
+
+  /** Persisted diagnostic log entries in `[fromMs, toMs]`, oldest first. */
+  getLog(fromMs: number, toMs: number): Promise<WireLogEntry[]>;
+  /** Serialize the whole log buffer to an NDJSON file; resolves its path. */
+  exportLog(): Promise<string>;
+  /** Delete all persisted diagnostic log entries. */
+  clearLog(): Promise<void>;
+  /** Set the diagnostic log threshold at runtime. */
+  setLogLevel(level: string): Promise<void>;
+  /** Write a host-app breadcrumb (category `app`) into the log pipeline. */
+  log(level: string, message: string): Promise<void>;
+
   readonly onState: CodegenTypes.EventEmitter<WireState>;
   readonly onLocation: CodegenTypes.EventEmitter<WireLocation>;
   readonly onGeofenceEvent: CodegenTypes.EventEmitter<WireGeofenceEvent>;
   readonly onSyncStatus: CodegenTypes.EventEmitter<WireSyncStatus>;
   readonly onAuthTokens: CodegenTypes.EventEmitter<WireAuthTokens>;
   readonly onLicenseStatus: CodegenTypes.EventEmitter<WireLicenseStatus>;
+  readonly onLog: CodegenTypes.EventEmitter<WireLogEntry>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('BeekonRn');

package/src/beekon.ts

@@ -1,10 +1,13 @@
 import NativeBeekon from './NativeBeekonRn';
+import { LicenseNudge } from './internal/licenseNudge';
 import type { AuthTokens } from './types/auth';
 import type { BeekonConfig } from './types/config';
-import type { AccuracyMode } from './types/enums';
+import type { AccuracyMode, LogLevel } from './types/enums';
 import type { BeekonGeofence, GeofenceEvent } from './types/geofence';
 import type { LicenseStatus } from './types/license';
 import type { Location } from './types/location';
+import type { LogEntry } from './types/log';
+import type { PermissionStatus } from './types/permission';
 import type { BeekonState } from './types/state';
 import type { SyncStatus } from './types/sync';
 import {
@@ -17,6 +20,8 @@ import {
   wireToGeofenceEvent,
   wireToLicenseStatus,
   wireToLocation,
+  wireToLogEntry,
+  wireToPermissionStatus,
   wireToState,
   wireToSyncStatus,
 } from './internal/mappers';
@@ -42,6 +47,7 @@ class EventHub {
   private readonly syncListeners = new Set<Listener<SyncStatus>>();
   private readonly authTokenListeners = new Set<Listener<AuthTokens>>();
   private readonly licenseListeners = new Set<Listener<LicenseStatus>>();
+  private readonly logListeners = new Set<Listener<LogEntry>>();
   private lastState: BeekonState | undefined;
   private lastSyncStatus: SyncStatus | undefined;
   private lastAuthTokens: AuthTokens | undefined;
@@ -79,6 +85,10 @@ class EventHub {
       this.lastLicenseStatus = s;
       this.licenseListeners.forEach((cb) => cb(s));
     });
+    NativeBeekon.onLog((w) => {
+      const e = wireToLogEntry(w);
+      this.logListeners.forEach((cb) => cb(e));
+    });
   }
 
   onState(cb: Listener<BeekonState>): () => void {
@@ -132,6 +142,14 @@ class EventHub {
       this.licenseListeners.delete(cb);
     };
   }
+
+  onLog(cb: Listener<LogEntry>): () => void {
+    this.ensureSubscribed();
+    this.logListeners.add(cb);
+    return () => {
+      this.logListeners.delete(cb);
+    };
+  }
 }
 
 /**
@@ -154,6 +172,20 @@ class EventHub {
  */
 class BeekonImpl {
   private readonly hub = new EventHub();
+  private readonly licenseNudge = new LicenseNudge();
+  private licenseNudgeAttached = false;
+
+  /**
+   * Echo the evaluation-mode nudge to the JS console once, on first lifecycle
+   * use — so it only activates for apps actually using the SDK. Metro shows JS
+   * console only, so this is how the native nudge reaches an RN dev. See
+   * {@link LicenseNudge}.
+   */
+  private activateLicenseNudge(): void {
+    if (this.licenseNudgeAttached) return;
+    this.licenseNudgeAttached = true;
+    this.licenseNudge.attach((cb) => this.hub.onLicenseStatus(cb));
+  }
 
   /**
    * Set tracking parameters. Optional — `start()` falls back to the previously
@@ -163,6 +195,7 @@ class BeekonImpl {
    */
   async configure(config: BeekonConfig): Promise<void> {
     this.hub.ensureSubscribed();
+    this.activateLicenseNudge();
     await NativeBeekon.configure(configToWire(config));
   }
 
@@ -174,6 +207,7 @@ class BeekonImpl {
    */
   async start(): Promise<void> {
     this.hub.ensureSubscribed();
+    this.activateLicenseNudge();
     await NativeBeekon.start();
   }
 
@@ -194,6 +228,7 @@ class BeekonImpl {
    */
   async resumeIfNeeded(): Promise<void> {
     this.hub.ensureSubscribed();
+    this.activateLicenseNudge();
     await NativeBeekon.resumeIfNeeded();
   }
 
@@ -321,6 +356,75 @@ class BeekonImpl {
     return wireToLicenseStatus(await NativeBeekon.licenseStatus());
   }
 
+  /**
+   * The current location-permission grant — a point-in-time read for
+   * **pre-start** checks, returned without ever prompting. Beekon never requests
+   * permission; the app owns that. A snapshot, not an observer: once tracking is
+   * running, permission loss surfaces on `onState` as
+   * `{ kind: 'stopped', reason: 'permissionDenied' }`. On Android, "not yet
+   * asked" and "denied" both report `'notDetermined'`; `'restricted'` is iOS-only.
+   */
+  async getPermissionStatus(): Promise<PermissionStatus> {
+    return wireToPermissionStatus(await NativeBeekon.getPermissionStatus());
+  }
+
+  /**
+   * Read persisted diagnostic log entries in the inclusive range `[from, to]`,
+   * oldest first. Entries survive process death, so this recovers what the SDK
+   * did during a background session — the key to diagnosing field issues. Throws
+   * `BeekonError` with kind `'storage'` on a read failure. Requires native ≥ 0.0.9.
+   */
+  async getLog(from: Date, to: Date): Promise<LogEntry[]> {
+    try {
+      const wires = await NativeBeekon.getLog(from.getTime(), to.getTime());
+      return wires.map(wireToLogEntry);
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
+  }
+
+  /**
+   * Serialize the whole diagnostic log buffer to an NDJSON file and resolve its
+   * path. The app owns the file — attach it to a support email, share it, or
+   * upload it. Throws `BeekonError` with kind `'storage'` on a failure. Requires
+   * native ≥ 0.0.9.
+   */
+  async exportLog(): Promise<string> {
+    try {
+      return await NativeBeekon.exportLog();
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
+  }
+
+  /** Delete all persisted diagnostic log entries. Requires native ≥ 0.0.9. */
+  async clearLog(): Promise<void> {
+    try {
+      await NativeBeekon.clearLog();
+    } catch (e) {
+      rethrowAsBeekonError(e);
+    }
+  }
+
+  /**
+   * Set the diagnostic log verbosity threshold at runtime — no restart needed.
+   * Raise to `'debug'`/`'verbose'` for field diagnosis, then lower again. A later
+   * `configure` re-applies `BeekonConfig.logLevel` and supersedes this. Requires
+   * native ≥ 0.0.9.
+   */
+  async setLogLevel(level: LogLevel): Promise<void> {
+    await NativeBeekon.setLogLevel(level);
+  }
+
+  /**
+   * Write a host-app breadcrumb into the same pipeline as the SDK's own logs
+   * (category `app`), so app and SDK events interleave in one timeline. Requires
+   * native ≥ 0.0.9.
+   */
+  async log(level: LogLevel, message: string): Promise<void> {
+    await NativeBeekon.log(level, message);
+  }
+
   /**
    * Subscribe to tracking-state transitions (`idle` / `tracking` /
    * `stopped(reason)`). The current state is delivered to new subscribers
@@ -375,6 +479,15 @@ class BeekonImpl {
   onLicenseStatus(cb: (s: LicenseStatus) => void): () => void {
     return this.hub.onLicenseStatus(cb);
   }
+
+  /**
+   * Subscribe to diagnostic log entries as they are recorded — SDK subsystems
+   * plus host breadcrumbs from {@link log}. Broadcast (no replay); read history
+   * with {@link getLog}. Returns an unsubscribe function. Requires native ≥ 0.0.9.
+   */
+  onLog(cb: (e: LogEntry) => void): () => void {
+    return this.hub.onLog(cb);
+  }
 }
 
 export const Beekon = new BeekonImpl();

package/src/index.tsx

@@ -1,7 +1,11 @@
 export { Beekon } from './beekon';
 
+// `BeekonConfig` is a merged type + value (the `cloud` / `selfManaged`
+// factories), so it is a value export — its type meaning travels with it.
+export { BeekonConfig } from './types/config';
 export type {
-  BeekonConfig,
+  CloudConfig,
+  SelfManagedConfig,
   SyncConfig,
   NotificationConfig,
 } from './types/config';
@@ -14,7 +18,9 @@ export type {
   ActivityType,
   AuthStrategy,
   AuthBodyFormat,
+  LogLevel,
 } from './types/enums';
+export type { LogEntry } from './types/log';
 export type { AuthConfig, AuthResponseMapping, AuthTokens } from './types/auth';
 export type { Location } from './types/location';
 export type {
@@ -23,6 +29,11 @@ export type {
   Transition,
 } from './types/geofence';
 export type { BeekonState, StopReason } from './types/state';
+export type {
+  PermissionStatus,
+  PermissionLevel,
+  PermissionAccuracy,
+} from './types/permission';
 export type { SyncStatus, SyncFailure } from './types/sync';
 export type { LicenseStatus, LicenseInvalidReason } from './types/license';
 export { BeekonError, type BeekonErrorKind } from './types/error';

package/src/internal/licenseNudge.ts

@@ -0,0 +1,80 @@
+import type { LicenseStatus } from '../types/license';
+
+// The debug nudge: a prominent multi-line banner mirroring the native debug
+// banner. Every line carries the prefix (greppability). Neutral by design — no
+// "release is unaffected", no advertised opt-out — so it nudges toward a key.
+const BANNER = [
+  '[Beekon][license] ════════════════════════════════════════════════════',
+  '[Beekon][license]  Beekon is running without a license key.',
+  '[Beekon][license]  Get one:  https://getbeekon.com/pricing',
+  '[Beekon][license]  Then add it via BeekonConfig.licenseKey.',
+  '[Beekon][license] ════════════════════════════════════════════════════',
+].join('\n');
+
+function isDev(): boolean {
+  const g = globalThis as { __DEV__?: boolean };
+  return g.__DEV__ === true;
+}
+
+function acknowledged(): boolean {
+  const g = globalThis as { BEEKON_EVALUATION_MODE?: boolean };
+  return g.BEEKON_EVALUATION_MODE === true;
+}
+
+function defaultLog(message: string): void {
+  // The dev-console nudge: Metro surfaces JS console output, not native logs.
+  console.warn(message);
+}
+
+/**
+ * Echoes the evaluation-mode license nudge into the JS console.
+ *
+ * The native SDKs log the license notice to the platform stream (iOS unified
+ * logging, Android Logcat), but Metro shows only JS `console.*` — neither native
+ * stream reaches it, so a React Native developer never sees the "you're
+ * unlicensed" nudge in the terminal they actually watch. This mirrors the
+ * **evaluation** notice (no key supplied) onto `console.warn` so it surfaces in
+ * Metro, on **both** platforms.
+ *
+ * Debug-only (`__DEV__`): a release bundle never console-warns. Fires **at most
+ * once per JS context** on the first `evaluation` status, mirroring the native
+ * once-per-transition guarantee. Purely a log line — it never blocks, degrades,
+ * or delays the SDK (license-format-v1 policy anchor).
+ *
+ * Silence it without a key by setting `globalThis.BEEKON_EVALUATION_MODE = true`
+ * before the SDK initializes — the JS analog of the native `BeekonEvaluationMode`
+ * plist / `in.wayq.beekon.evaluationMode` manifest acknowledgment.
+ */
+export class LicenseNudge {
+  private emitted = false;
+  private unsubscribe: (() => void) | undefined;
+  private readonly log: (message: string) => void;
+  private readonly enabled: boolean;
+
+  constructor(options?: {
+    log?: (message: string) => void;
+    enabled?: boolean;
+  }) {
+    this.log = options?.log ?? defaultLog;
+    this.enabled = options?.enabled ?? (isDev() && !acknowledged());
+  }
+
+  /**
+   * Subscribe via [subscribe] — a replay-1 license-status subscription that
+   * returns an unsubscribe function — and emit the banner the first time the
+   * status is `evaluation`. A no-op when disabled; idempotent.
+   */
+  attach(subscribe: (cb: (status: LicenseStatus) => void) => () => void): void {
+    if (!this.enabled || this.unsubscribe !== undefined) return;
+    this.unsubscribe = subscribe((status) => this.onStatus(status));
+  }
+
+  private onStatus(status: LicenseStatus): void {
+    if (this.emitted || status.status !== 'evaluation') return;
+    this.emitted = true;
+    this.log(BANNER);
+    // One-shot per process — drop the subscription once nudged.
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+  }
+}