@wayq/beekon-rn 0.1.0 → 0.1.2

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

@@ -16,6 +16,43 @@ export type BeekonGeofence = {
     notifyOnEntry?: boolean;
     /** Emit an event on exit. Default: `true`. */
     notifyOnExit?: boolean;
+    /**
+     * Optional per-geofence notification the SDK renders natively at crossing time —
+     * offline and even when the app is killed. Omit it to handle crossings yourself
+     * via `Beekon.onGeofenceEvent`. `onEnter` requires `notifyOnEntry`; `onExit`
+     * requires `notifyOnExit`; in self-managed mode `delivery` must be `'local'`.
+     */
+    notification?: GeofenceNotification;
+};
+/** Where a geofence-crossing notification is delivered. Mirrors `NotificationDelivery` on the natives. */
+export type NotificationDelivery = 'local' | 'cloud';
+/** Relative prominence of a geofence notification. Mirrors `NotificationImportance`. */
+export type NotificationImportance = 'high' | 'default';
+/** Per-direction content the SDK renders natively for a geofence crossing. */
+export type NotificationContent = {
+    /** Notification title. */
+    title: string;
+    /** Notification body. */
+    body: string;
+    /** Relative prominence. Default `'high'`. */
+    importance?: NotificationImportance;
+    /** Optional deep-link URI delivered in the notification for the host to route on tap. */
+    deepLink?: string;
+    /** Optional flat string payload delivered in the notification for routing on tap. */
+    data?: Record<string, string>;
+};
+/**
+ * An optional per-geofence notification rendered natively at crossing time.
+ * Mirrors `GeofenceNotification` on both native SDKs. The presence of `onEnter` /
+ * `onExit` selects which directions notify.
+ */
+export type GeofenceNotification = {
+    /** Delivery channel. `'local'` (offline, device-rendered) is the default and only implemented mode. */
+    delivery: NotificationDelivery;
+    /** Content rendered on entry. Requires `notifyOnEntry`. */
+    onEnter?: NotificationContent;
+    /** Content rendered on exit. Requires `notifyOnExit`. */
+    onExit?: NotificationContent;
 };
 /** Whether a {@link GeofenceEvent} marks entering or exiting a geofence. */
 export type Transition = 'enter' | 'exit';

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

@@ -1 +1 @@
-{"version":3,"file":"geofence.d.ts","sourceRoot":"","sources":["../../../../src/types/geofence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,IAAI,EAAE,UAAU,CAAC;IACjB,kCAAkC;IAClC,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC"}
+{"version":3,"file":"geofence.d.ts","sourceRoot":"","sources":["../../../../src/types/geofence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;CACrC,CAAC;AAEF,0GAA0G;AAC1G,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,OAAO,CAAC;AAErD,wFAAwF;AACxF,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,SAAS,CAAC;AAExD,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG;IAChC,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,UAAU,CAAC,EAAE,sBAAsB,CAAC;IACpC,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,uGAAuG;IACvG,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,2DAA2D;IAC3D,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,yDAAyD;IACzD,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,IAAI,EAAE,UAAU,CAAC;IACjB,kCAAkC;IAClC,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC"}

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

@@ -39,4 +39,40 @@ export type PermissionStatus = {
     /** `true` when background tracking is authorized. */
     canTrackInBackground: boolean;
 };
+/**
+ * A permission Beekon may require, normalized across platforms. Mirrors the
+ * native `BeekonPermission`.
+ *
+ * - `'location'` — foreground location; required for all tracking.
+ * - `'backgroundLocation'` — background revival, geofences, stationary resume.
+ * - `'activityRecognition'` — motion-based stationary detection.
+ * - `'notifications'` — the foreground-service notification (**Android only**).
+ */
+export type BeekonPermission = 'location' | 'backgroundLocation' | 'activityRecognition' | 'notifications';
+/**
+ * How badly a {@link PermissionRequirement} is needed.
+ *
+ * - `'required'` — tracking cannot start, or an explicitly-enabled feature is dead, without it.
+ * - `'recommended'` — an active feature silently degrades without it; tracking still runs.
+ */
+export type PermissionImportance = 'required' | 'recommended';
+/**
+ * One permission Beekon needs **for the current configuration**, each marked
+ * satisfied against the live grant — returned by `Beekon.getRequiredPermissions()`.
+ * Mirrors the native `PermissionRequirement`.
+ *
+ * Beekon never *requests* permission — the app owns that. This is the
+ * config-aware "doctor" companion to {@link PermissionStatus}: it reports
+ * activity-recognition (and, on Android, notifications) too.
+ */
+export type PermissionRequirement = {
+    /** The normalized permission. */
+    permission: BeekonPermission;
+    /** Whether tracking/a feature breaks (`'required'`) or merely degrades (`'recommended'`) when absent. */
+    importance: PermissionImportance;
+    /** Whether the live OS grant covers it right now. */
+    satisfied: boolean;
+    /** Human-readable explanation of why Beekon needs it / what degrades without it. */
+    rationale: string;
+};
 //# sourceMappingURL=permission.d.ts.map

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

@@ -1 +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"}
+{"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;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,oBAAoB,GACpB,qBAAqB,GACrB,eAAe,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,aAAa,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,iCAAiC;IACjC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,yGAAyG;IACzG,UAAU,EAAE,oBAAoB,CAAC;IACjC,qDAAqD;IACrD,SAAS,EAAE,OAAO,CAAC;IACnB,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wayq/beekon-rn",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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.1.0"
+VERSION="0.1.2"
 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
+# SHA256 of the v0.1.2 BeekonKit.xcframework.zip. Matches the SwiftPM
+# `binaryTarget` checksum in beekon-ios-binary's Package.swift at tag v0.1.2
 # (SwiftPM's compute-checksum is the SHA256 of the zip).
-EXPECTED_SHA="8a39d9360a05f117226381036a10d3cfeb71237f99fd8d800cfafda42d9657f2"
+EXPECTED_SHA="43b1f959699654020f32d3e8e4e1de6aacba8e32628c69a7477c1b2ba084a4a4"
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 DEST_DIR="${ROOT}/ios/Frameworks"

package/src/NativeBeekonRn.ts

@@ -156,6 +156,9 @@ export type WireGeofence = {
   radiusMeters: number;
   notifyOnEntry: boolean;
   notifyOnExit: boolean;
+  // Optional notification as a canonical JSON string (rendering is native-only).
+  // Flat string keeps Codegen happy and lets the payload schema grow without re-running codegen.
+  notificationJson?: string;
 };
 
 export type WireGeofenceEvent = {
@@ -233,6 +236,20 @@ export type WirePermissionStatus = {
   accuracy: string;
 };
 
+/**
+ * Flat wire form of one `PermissionRequirement` (read-only). `permission` is one
+ * of 'location' | 'backgroundLocation' | 'activityRecognition' | 'notifications'
+ * ('notifications' Android-only); `importance` is 'required' | 'recommended'.
+ * The mappers translate to the public string-literal unions with a defensive
+ * fallback.
+ */
+export type WirePermissionRequirement = {
+  permission: string;
+  importance: string;
+  satisfied: boolean;
+  rationale: string;
+};
+
 export interface Spec extends TurboModule {
   /**
    * The config crosses as an untyped object (`ReadableMap` on Android,
@@ -288,6 +305,13 @@ export interface Spec extends TurboModule {
    */
   getPermissionStatus(): Promise<WirePermissionStatus>;
 
+  /**
+   * The permissions Beekon needs for the active configuration, each marked
+   * satisfied against the live grant (read-only; never prompts). The config-aware
+   * companion to `getPermissionStatus`. Call after `configure`.
+   */
+  getRequiredPermissions(): Promise<WirePermissionRequirement[]>;
+
   /** 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. */

package/src/beekon.ts

@@ -7,7 +7,10 @@ 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 {
+  PermissionRequirement,
+  PermissionStatus,
+} from './types/permission';
 import type { BeekonState } from './types/state';
 import type { SyncStatus } from './types/sync';
 import {
@@ -21,6 +24,7 @@ import {
   wireToLicenseStatus,
   wireToLocation,
   wireToLogEntry,
+  wireToPermissionRequirement,
   wireToPermissionStatus,
   wireToState,
   wireToSyncStatus,
@@ -368,6 +372,21 @@ class BeekonImpl {
     return wireToPermissionStatus(await NativeBeekon.getPermissionStatus());
   }
 
+  /**
+   * The permissions Beekon needs **for the current configuration**, each marked
+   * `satisfied` against the live grant — the config-aware "doctor" companion to
+   * `getPermissionStatus()`. Unlike that location-only snapshot, this reports
+   * activity-recognition (and, on Android, notifications) too, derived from the
+   * active mode and tracking config. Read-only; never prompts. Call after
+   * `configure()`; in cloud mode (server-owned config) it returns the
+   * conservative list.
+   */
+  async getRequiredPermissions(): Promise<PermissionRequirement[]> {
+    return (await NativeBeekon.getRequiredPermissions()).map(
+      wireToPermissionRequirement
+    );
+  }
+
   /**
    * Read persisted diagnostic log entries in the inclusive range `[from, to]`,
    * oldest first. Entries survive process death, so this recovers what the SDK

package/src/index.tsx

@@ -26,6 +26,10 @@ export type { Location } from './types/location';
 export type {
   BeekonGeofence,
   GeofenceEvent,
+  GeofenceNotification,
+  NotificationContent,
+  NotificationDelivery,
+  NotificationImportance,
   Transition,
 } from './types/geofence';
 export type { BeekonState, StopReason } from './types/state';
@@ -33,6 +37,9 @@ export type {
   PermissionStatus,
   PermissionLevel,
   PermissionAccuracy,
+  BeekonPermission,
+  PermissionImportance,
+  PermissionRequirement,
 } from './types/permission';
 export type { SyncStatus, SyncFailure } from './types/sync';
 export type { LicenseStatus, LicenseInvalidReason } from './types/license';

package/src/internal/mappers.ts

@@ -15,13 +15,20 @@ import type { LogEntry } from '../types/log';
 import type {
   BeekonGeofence,
   GeofenceEvent,
+  GeofenceNotification,
+  NotificationContent,
+  NotificationDelivery,
+  NotificationImportance,
   Transition,
 } from '../types/geofence';
 import type { LicenseInvalidReason, LicenseStatus } from '../types/license';
 import type { Location } from '../types/location';
 import type {
+  BeekonPermission,
   PermissionAccuracy,
+  PermissionImportance,
   PermissionLevel,
+  PermissionRequirement,
   PermissionStatus,
 } from '../types/permission';
 import type { BeekonState, StopReason } from '../types/state';
@@ -37,6 +44,7 @@ import type {
   WireLicenseStatus,
   WireLocation,
   WireLogEntry,
+  WirePermissionRequirement,
   WirePermissionStatus,
   WireState,
   WireSyncStatus,
@@ -158,9 +166,90 @@ export function geofenceToWire(g: BeekonGeofence): WireGeofence {
     radiusMeters: g.radiusMeters,
     notifyOnEntry: g.notifyOnEntry ?? true,
     notifyOnExit: g.notifyOnExit ?? true,
+    notificationJson: notificationToJson(g.notification),
   };
 }
 
+// Serialize a notification to the canonical JSON string the native SDKs understand
+// (rendering is native-only). Optional keys are omitted; undefined ⇒ undefined.
+function notificationToJson(
+  n: GeofenceNotification | undefined
+): string | undefined {
+  if (!n) return undefined;
+  const obj: Record<string, unknown> = {
+    delivery: n.delivery === 'cloud' ? 'cloud' : 'local',
+  };
+  if (n.onEnter) obj.onEnter = contentToObj(n.onEnter);
+  if (n.onExit) obj.onExit = contentToObj(n.onExit);
+  return JSON.stringify(obj);
+}
+
+function contentToObj(c: NotificationContent): Record<string, unknown> {
+  const obj: Record<string, unknown> = {
+    title: c.title,
+    body: c.body,
+    importance: c.importance === 'default' ? 'default' : 'high',
+  };
+  if (c.deepLink != null) obj.deepLink = c.deepLink;
+  if (c.data && Object.keys(c.data).length > 0) obj.data = c.data;
+  return obj;
+}
+
+// Parse a canonical notification JSON string. Tolerant: malformed input, an unknown
+// enum, or content missing title/body degrades to undefined/defaults.
+function notificationFromJson(
+  json: string | undefined
+): GeofenceNotification | undefined {
+  if (!json) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== 'object' || parsed === null) return undefined;
+  const obj = parsed as Record<string, unknown>;
+  const onEnter = contentFromObj(obj.onEnter);
+  const onExit = contentFromObj(obj.onExit);
+  if (!onEnter && !onExit) return undefined;
+  const delivery: NotificationDelivery =
+    obj.delivery === 'cloud' ? 'cloud' : 'local';
+  return {
+    delivery,
+    ...(onEnter ? { onEnter } : {}),
+    ...(onExit ? { onExit } : {}),
+  };
+}
+
+function contentFromObj(raw: unknown): NotificationContent | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const r = raw as Record<string, unknown>;
+  if (
+    typeof r.title !== 'string' ||
+    typeof r.body !== 'string' ||
+    !r.title ||
+    !r.body
+  ) {
+    return undefined;
+  }
+  const importance: NotificationImportance =
+    r.importance === 'default' ? 'default' : 'high';
+  const data: Record<string, string> = {};
+  if (typeof r.data === 'object' && r.data !== null) {
+    for (const [k, v] of Object.entries(r.data as Record<string, unknown>)) {
+      if (typeof v === 'string') data[k] = v;
+    }
+  }
+  const content: NotificationContent = {
+    title: r.title,
+    body: r.body,
+    importance,
+  };
+  if (typeof r.deepLink === 'string') content.deepLink = r.deepLink;
+  if (Object.keys(data).length > 0) content.data = data;
+  return content;
+}
+
 // `expiresAt` (a `Date`) becomes epoch millis on the wire; the native side
 // converts to epoch seconds. String maps travel as `WireKeyValue[]`.
 export function authToWire(a: AuthConfig): WireAuthConfig {
@@ -240,6 +329,7 @@ export function wireToGeofence(w: WireGeofence): BeekonGeofence {
     radiusMeters: w.radiusMeters,
     notifyOnEntry: w.notifyOnEntry,
     notifyOnExit: w.notifyOnExit,
+    notification: notificationFromJson(w.notificationJson),
   };
 }
 
@@ -300,6 +390,30 @@ export function wireToPermissionStatus(
   };
 }
 
+export function wireToPermissionRequirement(
+  w: WirePermissionRequirement
+): PermissionRequirement {
+  return {
+    permission: oneOf<BeekonPermission>(
+      w.permission,
+      [
+        'location',
+        'backgroundLocation',
+        'activityRecognition',
+        'notifications',
+      ],
+      'location'
+    ),
+    importance: oneOf<PermissionImportance>(
+      w.importance,
+      ['required', 'recommended'],
+      'recommended'
+    ),
+    satisfied: w.satisfied,
+    rationale: w.rationale,
+  };
+}
+
 export function wireToSyncStatus(w: WireSyncStatus): SyncStatus {
   switch (w.type) {
     case 'idle':

package/src/types/geofence.ts

@@ -16,6 +16,47 @@ export type BeekonGeofence = {
   notifyOnEntry?: boolean;
   /** Emit an event on exit. Default: `true`. */
   notifyOnExit?: boolean;
+  /**
+   * Optional per-geofence notification the SDK renders natively at crossing time —
+   * offline and even when the app is killed. Omit it to handle crossings yourself
+   * via `Beekon.onGeofenceEvent`. `onEnter` requires `notifyOnEntry`; `onExit`
+   * requires `notifyOnExit`; in self-managed mode `delivery` must be `'local'`.
+   */
+  notification?: GeofenceNotification;
+};
+
+/** Where a geofence-crossing notification is delivered. Mirrors `NotificationDelivery` on the natives. */
+export type NotificationDelivery = 'local' | 'cloud';
+
+/** Relative prominence of a geofence notification. Mirrors `NotificationImportance`. */
+export type NotificationImportance = 'high' | 'default';
+
+/** Per-direction content the SDK renders natively for a geofence crossing. */
+export type NotificationContent = {
+  /** Notification title. */
+  title: string;
+  /** Notification body. */
+  body: string;
+  /** Relative prominence. Default `'high'`. */
+  importance?: NotificationImportance;
+  /** Optional deep-link URI delivered in the notification for the host to route on tap. */
+  deepLink?: string;
+  /** Optional flat string payload delivered in the notification for routing on tap. */
+  data?: Record<string, string>;
+};
+
+/**
+ * An optional per-geofence notification rendered natively at crossing time.
+ * Mirrors `GeofenceNotification` on both native SDKs. The presence of `onEnter` /
+ * `onExit` selects which directions notify.
+ */
+export type GeofenceNotification = {
+  /** Delivery channel. `'local'` (offline, device-rendered) is the default and only implemented mode. */
+  delivery: NotificationDelivery;
+  /** Content rendered on entry. Requires `notifyOnEntry`. */
+  onEnter?: NotificationContent;
+  /** Content rendered on exit. Requires `notifyOnExit`. */
+  onExit?: NotificationContent;
 };
 
 /** Whether a {@link GeofenceEvent} marks entering or exiting a geofence. */

package/src/types/permission.ts

@@ -46,3 +46,46 @@ export type PermissionStatus = {
   /** `true` when background tracking is authorized. */
   canTrackInBackground: boolean;
 };
+
+/**
+ * A permission Beekon may require, normalized across platforms. Mirrors the
+ * native `BeekonPermission`.
+ *
+ * - `'location'` — foreground location; required for all tracking.
+ * - `'backgroundLocation'` — background revival, geofences, stationary resume.
+ * - `'activityRecognition'` — motion-based stationary detection.
+ * - `'notifications'` — the foreground-service notification (**Android only**).
+ */
+export type BeekonPermission =
+  | 'location'
+  | 'backgroundLocation'
+  | 'activityRecognition'
+  | 'notifications';
+
+/**
+ * How badly a {@link PermissionRequirement} is needed.
+ *
+ * - `'required'` — tracking cannot start, or an explicitly-enabled feature is dead, without it.
+ * - `'recommended'` — an active feature silently degrades without it; tracking still runs.
+ */
+export type PermissionImportance = 'required' | 'recommended';
+
+/**
+ * One permission Beekon needs **for the current configuration**, each marked
+ * satisfied against the live grant — returned by `Beekon.getRequiredPermissions()`.
+ * Mirrors the native `PermissionRequirement`.
+ *
+ * Beekon never *requests* permission — the app owns that. This is the
+ * config-aware "doctor" companion to {@link PermissionStatus}: it reports
+ * activity-recognition (and, on Android, notifications) too.
+ */
+export type PermissionRequirement = {
+  /** The normalized permission. */
+  permission: BeekonPermission;
+  /** Whether tracking/a feature breaks (`'required'`) or merely degrades (`'recommended'`) when absent. */
+  importance: PermissionImportance;
+  /** Whether the live OS grant covers it right now. */
+  satisfied: boolean;
+  /** Human-readable explanation of why Beekon needs it / what degrades without it. */
+  rationale: string;
+};