@wayq/beekon-rn 0.0.8 → 0.1.0

package/src/internal/mappers.ts

@@ -7,9 +7,11 @@ import type {
   AuthStrategy,
   LocationQuality,
   LocationTrigger,
+  LogLevel,
   MotionState,
   StationaryMode,
 } from '../types/enums';
+import type { LogEntry } from '../types/log';
 import type {
   BeekonGeofence,
   GeofenceEvent,
@@ -17,6 +19,11 @@ import type {
 } from '../types/geofence';
 import type { LicenseInvalidReason, LicenseStatus } from '../types/license';
 import type { Location } from '../types/location';
+import type {
+  PermissionAccuracy,
+  PermissionLevel,
+  PermissionStatus,
+} from '../types/permission';
 import type { BeekonState, StopReason } from '../types/state';
 import type { SyncFailure, SyncStatus } from '../types/sync';
 import { BeekonError, type BeekonErrorKind } from '../types/error';
@@ -29,6 +36,8 @@ import type {
   WireKeyValue,
   WireLicenseStatus,
   WireLocation,
+  WireLogEntry,
+  WirePermissionStatus,
   WireState,
   WireSyncStatus,
 } from '../NativeBeekonRn';
@@ -44,6 +53,7 @@ const DEFAULTS = {
   detectActivity: false,
   syncIntervalSeconds: 300,
   syncBatchSize: 100,
+  syncThreshold: 0,
   authStrategy: 'bearer' as AuthStrategy,
   authBodyFormat: 'form' as AuthBodyFormat,
   authSkewMarginSeconds: 60,
@@ -51,6 +61,7 @@ const DEFAULTS = {
     string,
     string
   >,
+  logLevel: 'info' as LogLevel,
 };
 
 // --- Public → wire ---------------------------------------------------------
@@ -62,9 +73,53 @@ export function recordToEntries(
   return Object.keys(record).map((key) => ({ key, value: record[key]! }));
 }
 
+function notificationToWire(config: BeekonConfig): WireConfig['notification'] {
+  return config.notification
+    ? {
+        title: config.notification.title,
+        text: config.notification.text,
+        smallIcon: config.notification.smallIcon,
+      }
+    : undefined;
+}
+
+// Switches on the sealed-config arm (cloud-mode-v1 §2). The wire form is flat
+// and carries both arms' slots; only the active arm's fields are populated. The
+// tracking-param slots are filled with defaults regardless so the wire struct
+// stays fully-populated — the native cloud arm ignores them and derives config
+// from the server.
 export function configToWire(config: BeekonConfig): WireConfig {
+  const tracking = {
+    minTimeBetweenLocationsSeconds: DEFAULTS.minTimeBetweenLocationsSeconds,
+    minDistanceBetweenLocationsMeters:
+      DEFAULTS.minDistanceBetweenLocationsMeters,
+    accuracyMode: DEFAULTS.accuracyMode,
+    whenStationary: DEFAULTS.whenStationary,
+    stationaryRadiusMeters: DEFAULTS.stationaryRadiusMeters,
+    detectActivity: DEFAULTS.detectActivity,
+  };
+
+  if (config.mode === 'cloud') {
+    return {
+      mode: 'cloud',
+      // Passed through verbatim; the native cloud arm trims and validates it.
+      projectKey: config.projectKey,
+      // Omitted means the native baked-in default (https://api.getbeekon.com).
+      endpoint: config.endpoint,
+      ...tracking,
+      // Cloud config is server-owned: no local sync or license key.
+      sync: undefined,
+      notification: notificationToWire(config),
+      licenseKey: undefined,
+      logLevel: config.logLevel ?? DEFAULTS.logLevel,
+    };
+  }
+
   const sync = config.sync;
   return {
+    mode: 'selfManaged',
+    projectKey: undefined,
+    endpoint: undefined,
     minTimeBetweenLocationsSeconds:
       config.minTimeBetweenLocationsSeconds ??
       DEFAULTS.minTimeBetweenLocationsSeconds,
@@ -82,20 +137,16 @@ export function configToWire(config: BeekonConfig): WireConfig {
           headers: recordToEntries(sync.headers),
           intervalSeconds: sync.intervalSeconds ?? DEFAULTS.syncIntervalSeconds,
           batchSize: sync.batchSize ?? DEFAULTS.syncBatchSize,
+          syncThreshold: sync.syncThreshold ?? DEFAULTS.syncThreshold,
           auth: sync.auth ? authToWire(sync.auth) : undefined,
         }
       : undefined,
-    notification: config.notification
-      ? {
-          title: config.notification.title,
-          text: config.notification.text,
-          smallIcon: config.notification.smallIcon,
-        }
-      : undefined,
+    notification: notificationToWire(config),
     // Passed through verbatim — `undefined` is omitted and the native SDK falls
     // through to manifest/Info.plist. No wrapper-side trimming or fallback
     // (blank/whitespace handling lives in the native SDK; spec §9).
     licenseKey: config.licenseKey,
+    logLevel: config.logLevel ?? DEFAULTS.logLevel,
   };
 }
 
@@ -201,6 +252,20 @@ export function wireToGeofenceEvent(w: WireGeofenceEvent): GeofenceEvent {
   };
 }
 
+export function wireToLogEntry(w: WireLogEntry): LogEntry {
+  return {
+    id: w.id,
+    timestamp: new Date(w.timestampMs),
+    level: oneOf<LogLevel>(
+      w.level,
+      ['off', 'error', 'warn', 'info', 'debug', 'verbose'],
+      'info'
+    ),
+    category: w.category,
+    message: w.message,
+  };
+}
+
 export function wireToState(w: WireState): BeekonState {
   switch (w.type) {
     case 'idle':
@@ -215,6 +280,26 @@ export function wireToState(w: WireState): BeekonState {
   }
 }
 
+export function wireToPermissionStatus(
+  w: WirePermissionStatus
+): PermissionStatus {
+  const level = oneOf<PermissionLevel>(
+    w.level,
+    ['notDetermined', 'denied', 'restricted', 'foreground', 'background'],
+    'notDetermined'
+  );
+  // '' is the wire encoding of null (not granted); an unknown non-empty value
+  // degrades to null rather than guessing a precision.
+  const accuracy: PermissionAccuracy | null =
+    w.accuracy === 'full' || w.accuracy === 'reduced' ? w.accuracy : null;
+  return {
+    level,
+    accuracy,
+    isAuthorized: level === 'foreground' || level === 'background',
+    canTrackInBackground: level === 'background',
+  };
+}
+
 export function wireToSyncStatus(w: WireSyncStatus): SyncStatus {
   switch (w.type) {
     case 'idle':
@@ -290,6 +375,7 @@ function toStopReason(s: string | undefined): StopReason {
       'permissionDenied',
       'locationServicesDisabled',
       'locationUnavailable',
+      'cloudModeUnavailable',
       'system',
     ],
     // The native side always populates the reason for a `stopped` state; an

package/src/types/config.ts

@@ -1,5 +1,5 @@
 import type { AuthConfig } from './auth';
-import type { AccuracyMode, StationaryMode } from './enums';
+import type { AccuracyMode, LogLevel, StationaryMode } from './enums';
 
 /**
  * Foreground-service notification overrides. **Android-only** — the platform
@@ -23,8 +23,8 @@ export type NotificationConfig = {
 };
 
 /**
- * Server-upload configuration. Presence of {@link BeekonConfig.sync} turns on
- * batched uploads of stored locations and geofence events; omitting it keeps
+ * Server-upload configuration. Presence of {@link SelfManagedConfig.sync} turns
+ * on batched uploads of stored locations and geofence events; omitting it keeps
  * tracking local-only.
  */
 export type SyncConfig = {
@@ -39,6 +39,15 @@ export type SyncConfig = {
   intervalSeconds?: number;
   /** Maximum locations per upload. Clamped to `[1, 1000]`. Default: `100`. */
   batchSize?: number;
+  /**
+   * Pending-fix count that triggers an early upload of regular fixes, ahead of
+   * the {@link SyncConfig.intervalSeconds} schedule (not subject to the Android
+   * ~15 min floor). `0` (the default) leaves regular fixes to the schedule.
+   * Negative values are treated as `0`. Independent of this setting, a geofence
+   * event and a session stop with pending fixes always flush immediately while
+   * sync is configured. Requires the native SDK ≥ 0.0.9. Default: `0`.
+   */
+  syncThreshold?: number;
   /**
    * Declarative token-refresh recipe. When set, the SDK attaches and natively
    * refreshes the access token (proactively before expiry, reactively on
@@ -49,15 +58,58 @@ export type SyncConfig = {
 };
 
 /**
- * Tracking configuration. Every field is optional — `Beekon.start()` falls back
- * to the previously persisted config, or to the documented defaults below if
- * never configured.
+ * **Cloud-mode** configuration (cloud-mode-v1 §2). Point the SDK at Beekon
+ * Cloud (or a self-hosted Beekon backend) with a project key; the **server**
+ * owns the tracking parameters, sync cadence, geofences, and the license. This
+ * arm therefore exposes **only** the project credential, an optional endpoint
+ * override, the platform-universal Android `notification`, and `logLevel` — it
+ * deliberately does NOT expose tracking params, `sync`, or `licenseKey` (those
+ * are server-owned or derived).
+ */
+export type CloudConfig = {
+  /** Arm discriminator — selects cloud mode. */
+  mode: 'cloud';
+  /**
+   * Opaque project credential (prefix `bkproj_`). A **bearer secret** on a
+   * separate credential plane from the license token — do **not** commit it to
+   * source control. Surrounding whitespace is trimmed and an empty key is
+   * rejected natively.
+   */
+  projectKey: string;
+  /**
+   * Base URL of the Beekon backend. Omit for Beekon Cloud (the SDK uses the
+   * baked-in `https://api.getbeekon.com`); set it to a self-hosted Beekon
+   * backend's base URL (the `/v1/token`, `/v1/config`, `/v1/ingest` suffixes
+   * are derived). Default: unset (`https://api.getbeekon.com`).
+   */
+  endpoint?: string;
+  /** Android-only notification overrides. Ignored on iOS. */
+  notification?: NotificationConfig;
+  /**
+   * Diagnostic log verbosity threshold. See {@link SelfManagedConfig.logLevel}.
+   * Default: `'info'`.
+   */
+  logLevel?: LogLevel;
+};
+
+/**
+ * **Self-managed** configuration (cloud-mode-v1 §2 / self-managed-mode-v1).
+ * The app owns all configuration locally — tracking parameters, an optional
+ * `sync` (omit ⇒ local-only; set ⇒ custom-backend ingest), an optional
+ * `licenseKey`, plus `notification` and `logLevel`. This is the pre-cloud
+ * behaviour.
+ *
+ * Every field other than `mode` is optional — `Beekon.start()` falls back to
+ * the previously persisted config, or to the documented defaults below if never
+ * configured.
  *
  * The two gate knobs (`minTimeBetweenLocationsSeconds`,
  * `minDistanceBetweenLocationsMeters`) admit a fix only when **both** are
  * satisfied; pass `0` to disable a gate.
  */
-export type BeekonConfig = {
+export type SelfManagedConfig = {
+  /** Arm discriminator — selects self-managed mode. */
+  mode: 'selfManaged';
   /** Minimum seconds between admitted fixes (10s floor). Default: `30`. */
   minTimeBetweenLocationsSeconds?: number;
   /** Minimum metres between admitted fixes. `0` disables it. Default: `100`. */
@@ -91,4 +143,44 @@ export type BeekonConfig = {
    * useless to anyone else. Default: unset.
    */
   licenseKey?: string;
+  /**
+   * Diagnostic log verbosity threshold. Entries at or below this level are
+   * recorded to the persisted ring buffer and {@link Beekon.onLog}. `'info'`
+   * (the default) keeps coordinates out of the buffer — they appear only at
+   * `'debug'`/`'verbose'`. Change at runtime with {@link Beekon.setLogLevel}.
+   * Requires the native SDK ≥ 0.0.9. Default: `'info'`.
+   */
+  logLevel?: LogLevel;
 };
+
+/**
+ * Tracking configuration. A **sealed two-arm** discriminated union (cloud-mode-v1
+ * §2): the `mode` tag selects {@link CloudConfig} (server-owned config) or
+ * {@link SelfManagedConfig} (app-owned config). Each arm exposes only that arm's
+ * fields — the cloud arm cannot carry tracking params / sync / a license key.
+ *
+ * Build a value with the {@link BeekonConfig.cloud} / {@link BeekonConfig.selfManaged}
+ * factories, or with a plain object literal that includes the `mode` tag.
+ */
+export type BeekonConfig = CloudConfig | SelfManagedConfig;
+
+/**
+ * Factory helpers mirroring the native sealed-type constructors
+ * (`BeekonConfig.cloud(...)` / `BeekonConfig.selfManaged(...)`). They stamp the
+ * `mode` discriminator so each call site can express only its arm's fields.
+ *
+ * Merged with the {@link BeekonConfig} type so `BeekonConfig` is usable as both
+ * a type and a value.
+ */
+export const BeekonConfig = {
+  /** Build a {@link CloudConfig}. `projectKey` is required. */
+  cloud(options: Omit<CloudConfig, 'mode'>): CloudConfig {
+    return { mode: 'cloud', ...options };
+  },
+  /** Build a {@link SelfManagedConfig}. Every field is optional. */
+  selfManaged(
+    options: Omit<SelfManagedConfig, 'mode'> = {}
+  ): SelfManagedConfig {
+    return { mode: 'selfManaged', ...options };
+  },
+} as const;

package/src/types/enums.ts

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

package/src/types/log.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;
+};

package/src/types/permission.ts

@@ -0,0 +1,48 @@
+/**
+ * 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;
+};

package/src/types/state.ts

@@ -8,6 +8,9 @@
  *   (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).
  */
@@ -16,6 +19,7 @@ export type StopReason =
   | 'permissionDenied'
   | 'locationServicesDisabled'
   | 'locationUnavailable'
+  | 'cloudModeUnavailable'
   | 'system';
 
 /**