@wayq/beekon-rn 0.0.8 → 0.0.9

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/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.0.9",
   "description": "React Native binding for the Beekon location SDK (Android + iOS).",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/scripts/fetch-beekonkit.sh

@@ -13,12 +13,12 @@
 
 set -euo pipefail
 
-VERSION="0.0.8"
+VERSION="0.0.9"
 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
+# 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="6f5e75bd90ef67c2e6466336edce4c3a33b5d44aa592fb5a6fa2b46eeab005e7"
 
 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;
 };
@@ -232,12 +267,24 @@ export interface Spec extends TurboModule {
    */
   licenseStatus(): Promise<WireLicenseStatus>;
 
+  /** 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,12 @@
 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 { BeekonState } from './types/state';
 import type { SyncStatus } from './types/sync';
 import {
@@ -17,6 +19,7 @@ import {
   wireToGeofenceEvent,
   wireToLicenseStatus,
   wireToLocation,
+  wireToLogEntry,
   wireToState,
   wireToSyncStatus,
 } from './internal/mappers';
@@ -42,6 +45,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 +83,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 +140,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 +170,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 +193,7 @@ class BeekonImpl {
    */
   async configure(config: BeekonConfig): Promise<void> {
     this.hub.ensureSubscribed();
+    this.activateLicenseNudge();
     await NativeBeekon.configure(configToWire(config));
   }
 
@@ -174,6 +205,7 @@ class BeekonImpl {
    */
   async start(): Promise<void> {
     this.hub.ensureSubscribed();
+    this.activateLicenseNudge();
     await NativeBeekon.start();
   }
 
@@ -194,6 +226,7 @@ class BeekonImpl {
    */
   async resumeIfNeeded(): Promise<void> {
     this.hub.ensureSubscribed();
+    this.activateLicenseNudge();
     await NativeBeekon.resumeIfNeeded();
   }
 
@@ -321,6 +354,63 @@ class BeekonImpl {
     return wireToLicenseStatus(await NativeBeekon.licenseStatus());
   }
 
+  /**
+   * 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 +465,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 {

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;
+  }
+}

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,
@@ -29,6 +31,7 @@ import type {
   WireKeyValue,
   WireLicenseStatus,
   WireLocation,
+  WireLogEntry,
   WireState,
   WireSyncStatus,
 } from '../NativeBeekonRn';
@@ -44,6 +47,7 @@ const DEFAULTS = {
   detectActivity: false,
   syncIntervalSeconds: 300,
   syncBatchSize: 100,
+  syncThreshold: 0,
   authStrategy: 'bearer' as AuthStrategy,
   authBodyFormat: 'form' as AuthBodyFormat,
   authSkewMarginSeconds: 60,
@@ -51,6 +55,7 @@ const DEFAULTS = {
     string,
     string
   >,
+  logLevel: 'info' as LogLevel,
 };
 
 // --- Public → wire ---------------------------------------------------------
@@ -62,9 +67,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 +131,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 +246,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':
@@ -290,6 +349,7 @@ function toStopReason(s: string | undefined): StopReason {
       'permissionDenied',
       'locationServicesDisabled',
       'locationUnavailable',
+      'cloudModeUnavailable',
       'system',
     ],
     // The native side always populates the reason for a `stopped` state; an