@wayq/beekon-rn 0.0.9 → 0.1.2

package/src/types/permission.ts

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