@wayq/beekon-rn 0.0.9 → 0.1.0

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