@wayq/beekon-rn 0.0.7 → 0.0.9

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/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';
 
 /**