@wayq/beekon-rn 0.0.3 → 0.0.6

package/src/internal/mappers.ts

@@ -1,43 +1,198 @@
+import type { AuthConfig, AuthTokens } from '../types/auth';
 import type { BeekonConfig } from '../types/config';
-import type { BeekonState, StopReason } from '../types/state';
+import type {
+  AccuracyMode,
+  ActivityType,
+  AuthBodyFormat,
+  AuthStrategy,
+  LocationQuality,
+  LocationTrigger,
+  MotionState,
+  StationaryMode,
+} from '../types/enums';
+import type {
+  BeekonGeofence,
+  GeofenceEvent,
+  Transition,
+} from '../types/geofence';
 import type { Location } from '../types/location';
+import type { BeekonState, StopReason } from '../types/state';
+import type { SyncFailure, SyncStatus } from '../types/sync';
 import { BeekonError, type BeekonErrorKind } from '../types/error';
-import type { WireConfig, WireLocation, WireState } from '../NativeBeekonRn';
+import type {
+  WireAuthConfig,
+  WireAuthTokens,
+  WireConfig,
+  WireGeofence,
+  WireGeofenceEvent,
+  WireKeyValue,
+  WireLocation,
+  WireState,
+  WireSyncStatus,
+} from '../NativeBeekonRn';
+
+// Config defaults. Kept here (not in the wire layer) so the native modules can
+// treat every wire field as present.
+const DEFAULTS = {
+  minTimeBetweenLocationsSeconds: 30,
+  minDistanceBetweenLocationsMeters: 100,
+  accuracyMode: 'balanced' as AccuracyMode,
+  whenStationary: 'pause' as StationaryMode,
+  stationaryRadiusMeters: 5,
+  detectActivity: false,
+  syncIntervalSeconds: 300,
+  syncBatchSize: 100,
+  authStrategy: 'bearer' as AuthStrategy,
+  authBodyFormat: 'form' as AuthBodyFormat,
+  authSkewMarginSeconds: 60,
+  authRefreshHeaders: { Authorization: 'Bearer {accessToken}' } as Record<
+    string,
+    string
+  >,
+};
 
-const DEFAULT_INTERVAL_SECONDS = 30;
-const DEFAULT_DISTANCE_METERS = 100;
+// --- Public → wire ---------------------------------------------------------
+
+export function recordToEntries(
+  record: Record<string, string> | undefined
+): WireKeyValue[] {
+  if (!record) return [];
+  return Object.keys(record).map((key) => ({ key, value: record[key]! }));
+}
 
 export function configToWire(config: BeekonConfig): WireConfig {
+  const sync = config.sync;
+  return {
+    minTimeBetweenLocationsSeconds:
+      config.minTimeBetweenLocationsSeconds ??
+      DEFAULTS.minTimeBetweenLocationsSeconds,
+    minDistanceBetweenLocationsMeters:
+      config.minDistanceBetweenLocationsMeters ??
+      DEFAULTS.minDistanceBetweenLocationsMeters,
+    accuracyMode: config.accuracyMode ?? DEFAULTS.accuracyMode,
+    whenStationary: config.whenStationary ?? DEFAULTS.whenStationary,
+    stationaryRadiusMeters:
+      config.stationaryRadiusMeters ?? DEFAULTS.stationaryRadiusMeters,
+    detectActivity: config.detectActivity ?? DEFAULTS.detectActivity,
+    sync: sync
+      ? {
+          url: sync.url,
+          headers: recordToEntries(sync.headers),
+          intervalSeconds: sync.intervalSeconds ?? DEFAULTS.syncIntervalSeconds,
+          batchSize: sync.batchSize ?? DEFAULTS.syncBatchSize,
+          auth: sync.auth ? authToWire(sync.auth) : undefined,
+        }
+      : undefined,
+    notification: config.notification
+      ? {
+          title: config.notification.title,
+          text: config.notification.text,
+          smallIcon: config.notification.smallIcon,
+        }
+      : undefined,
+  };
+}
+
+export function geofenceToWire(g: BeekonGeofence): WireGeofence {
+  return {
+    id: g.id,
+    lat: g.latitude,
+    lng: g.longitude,
+    radiusMeters: g.radiusMeters,
+    notifyOnEntry: g.notifyOnEntry ?? true,
+    notifyOnExit: g.notifyOnExit ?? true,
+  };
+}
+
+// `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 {
   return {
-    intervalSeconds: config.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS,
-    distanceMeters: config.distanceMeters ?? DEFAULT_DISTANCE_METERS,
-    androidNotification: config.androidNotification,
+    accessToken: a.accessToken,
+    refreshToken: a.refreshToken,
+    expiresAtMs: a.expiresAt?.getTime(),
+    strategy: a.strategy ?? DEFAULTS.authStrategy,
+    refreshUrl: a.refreshUrl,
+    refreshPayload: recordToEntries(a.refreshPayload),
+    refreshHeaders: recordToEntries(
+      a.refreshHeaders ?? DEFAULTS.authRefreshHeaders
+    ),
+    refreshBodyFormat: a.refreshBodyFormat ?? DEFAULTS.authBodyFormat,
+    responseMapping: {
+      accessToken: a.responseMapping?.accessToken,
+      refreshToken: a.responseMapping?.refreshToken,
+      expiresIn: a.responseMapping?.expiresIn,
+      expiresAt: a.responseMapping?.expiresAt,
+    },
+    skewMarginSeconds: a.skewMarginSeconds ?? DEFAULTS.authSkewMarginSeconds,
+    seedEpoch: a.seedEpoch,
   };
 }
 
+// --- Wire → public ---------------------------------------------------------
+
 export function wireToLocation(w: WireLocation): Location {
   return {
-    lat: w.lat,
-    lng: w.lng,
+    id: w.id,
+    latitude: w.lat,
+    longitude: w.lng,
+    timestamp: new Date(w.timestampMs),
     accuracy: w.accuracy,
     speed: w.speed,
     bearing: w.bearing,
     altitude: w.altitude,
-    timestamp: new Date(w.timestampMs),
+    quality: oneOf<LocationQuality>(
+      w.quality,
+      ['ok', 'lowAccuracy', 'implausibleSpeed'],
+      'ok'
+    ),
+    trigger: oneOf<LocationTrigger>(
+      w.trigger,
+      ['interval', 'motion', 'checkIn', 'geofence', 'manual'],
+      'interval'
+    ),
+    motion: oneOf<MotionState>(
+      w.motion,
+      ['moving', 'stationary', 'unknown'],
+      'unknown'
+    ),
+    activity:
+      w.activity == null
+        ? null
+        : oneOf<ActivityType>(
+            w.activity,
+            [
+              'stationary',
+              'walking',
+              'running',
+              'cycling',
+              'automotive',
+              'unknown',
+            ],
+            'unknown'
+          ),
+    isMock: w.isMock,
   };
 }
 
-function toStopReason(s: string | undefined): StopReason {
-  switch (s) {
-    case 'user':
-    case 'permissionDenied':
-    case 'locationServicesDisabled':
-    case 'system':
-      return s;
-    default:
-      // Defensive — native should never emit an unknown reason.
-      return 'user';
-  }
+export function wireToGeofence(w: WireGeofence): BeekonGeofence {
+  return {
+    id: w.id,
+    latitude: w.lat,
+    longitude: w.lng,
+    radiusMeters: w.radiusMeters,
+    notifyOnEntry: w.notifyOnEntry,
+    notifyOnExit: w.notifyOnExit,
+  };
+}
+
+export function wireToGeofenceEvent(w: WireGeofenceEvent): GeofenceEvent {
+  return {
+    id: w.id,
+    geofenceId: w.geofenceId,
+    type: oneOf<Transition>(w.type, ['enter', 'exit'], 'enter'),
+    timestamp: new Date(w.timestampMs),
+  };
 }
 
 export function wireToState(w: WireState): BeekonState {
@@ -54,11 +209,67 @@ export function wireToState(w: WireState): BeekonState {
   }
 }
 
+export function wireToSyncStatus(w: WireSyncStatus): SyncStatus {
+  switch (w.type) {
+    case 'idle':
+      return { kind: 'idle' };
+    case 'pending':
+      return { kind: 'pending' };
+    case 'failed':
+      return { kind: 'failed', reason: toSyncFailure(w.failure) };
+    default:
+      return { kind: 'idle' };
+  }
+}
+
+/** `expiresAtMs` (epoch millis) becomes a `Date`; `null` propagates faithfully. */
+export function wireToAuthTokens(w: WireAuthTokens): AuthTokens {
+  return {
+    accessToken: w.accessToken,
+    refreshToken: w.refreshToken,
+    expiresAt: w.expiresAtMs == null ? null : new Date(w.expiresAtMs),
+    epoch: w.epoch,
+  };
+}
+
+function toStopReason(s: string | undefined): StopReason {
+  return oneOf<StopReason>(
+    s,
+    [
+      'user',
+      'permissionDenied',
+      'locationServicesDisabled',
+      'locationUnavailable',
+      'system',
+    ],
+    // The native side always populates the reason for a `stopped` state; an
+    // unknown/missing value means the wire contract was violated — fall back to
+    // `system` rather than throwing on a subscriber.
+    'system'
+  );
+}
+
+function toSyncFailure(s: string | undefined): SyncFailure {
+  return oneOf<SyncFailure>(s, ['auth', 'rejected'], 'rejected');
+}
+
+/** Validate a wire enum string against the known set, with a safe fallback. */
+function oneOf<T extends string>(
+  value: string | null | undefined,
+  allowed: readonly T[],
+  fallback: T
+): T {
+  return (allowed as readonly string[]).includes(value ?? '')
+    ? (value as T)
+    : fallback;
+}
+
+// --- Errors ----------------------------------------------------------------
+
 /**
- * Re-throw a native promise rejection as a typed `BeekonError`. Native modules
- * encode the kind in the error code string (`PERMISSION_DENIED`,
- * `LOCATION_SERVICES_DISABLED`, `STORAGE_FAILURE`); anything else falls
- * through as the original error.
+ * Re-throw a native promise rejection as a typed {@link BeekonError}. The native
+ * modules encode the kind in the error-code string (`STORAGE_FAILURE`,
+ * `INVALID_GEOFENCE`); anything else falls through as the original error.
  */
 export function rethrowAsBeekonError(e: unknown): never {
   const code = (e as { code?: string } | undefined)?.code;
@@ -72,12 +283,16 @@ export function rethrowAsBeekonError(e: unknown): never {
 
 function codeToKind(code: string | undefined): BeekonErrorKind | undefined {
   switch (code) {
+    case 'STORAGE_FAILURE':
+      return 'storage';
+    case 'INVALID_GEOFENCE':
+      return 'invalidGeofence';
     case 'PERMISSION_DENIED':
       return 'permissionDenied';
     case 'LOCATION_SERVICES_DISABLED':
       return 'locationServicesDisabled';
-    case 'STORAGE_FAILURE':
-      return 'storageFailure';
+    case 'LOCATION_UNAVAILABLE':
+      return 'locationUnavailable';
     default:
       return undefined;
   }

package/src/types/auth.ts

@@ -0,0 +1,101 @@
+import type { AuthBodyFormat, AuthStrategy } from './enums';
+
+/**
+ * Where the SDK reads rotated tokens from the JSON response to a refresh
+ * request. Mirrors the native `AuthResponseMapping` (iOS) / `ResponseMapping`
+ * (Android).
+ *
+ * Each value is a response key. An omitted field falls back to common-name
+ * detection: `access_token`/`accessToken`/`token` for the access token,
+ * `refresh_token`/`refreshToken` for a rotated refresh token, and `expires_in`
+ * (relative seconds) or `expires_at`/`expires` (absolute epoch seconds) for the
+ * expiry. The default (all-omitted) is pure common-name detection.
+ */
+export type AuthResponseMapping = {
+  /** Response key holding the new access token. Omitted uses common-name detection. */
+  accessToken?: string;
+  /** Response key holding a rotated refresh token. Omitted uses common-name detection. */
+  refreshToken?: string;
+  /** Response key holding a relative lifetime in seconds. Omitted uses detection. */
+  expiresIn?: string;
+  /** Response key holding an absolute expiry in epoch seconds. Omitted uses detection. */
+  expiresAt?: string;
+};
+
+/**
+ * Declarative recipe for native token refresh, set on `SyncConfig.auth`.
+ * Mirrors the native `AuthConfig`.
+ *
+ * When present, the SDK attaches the access token to every upload (per
+ * {@link AuthConfig.strategy}), refreshes it **proactively** before
+ * {@link AuthConfig.expiresAt} and **reactively** on a `401`/`403`, then retries
+ * the upload — all natively, so it works in the background and on a cold launch
+ * with no host involvement. Omit {@link AuthConfig.refreshUrl} to disable
+ * refresh and keep the legacy behaviour (a `401`/`403` pauses sync and surfaces
+ * `SyncFailure 'auth'`).
+ *
+ * **Tokens are a seed, not config.** {@link AuthConfig.accessToken},
+ * {@link AuthConfig.refreshToken} and {@link AuthConfig.expiresAt} are supplied
+ * once; the SDK then owns and rotates the live token set in secure storage
+ * (Keychain / encrypted prefs). Observe rotations via `Beekon.onAuthTokens()` to
+ * mirror the tokens into your own session store.
+ *
+ * Requires the native SDK ≥ 0.0.6; with an older native binary the recipe is
+ * ignored and only static `SyncConfig.headers` apply.
+ */
+export type AuthConfig = {
+  /** Initial access token. A seed: the SDK owns and rotates it after first persist. */
+  accessToken?: string;
+  /** Initial refresh token POSTed to {@link AuthConfig.refreshUrl}. A seed. */
+  refreshToken?: string;
+  /** Absolute expiry of {@link AuthConfig.accessToken}. Omitted disables proactive refresh. */
+  expiresAt?: Date;
+  /** How the access token is attached. Default: `'bearer'`. */
+  strategy?: AuthStrategy;
+  /** Authorization server's refresh endpoint. Omitted disables refresh. */
+  refreshUrl?: string;
+  /**
+   * Form fields POSTed to {@link AuthConfig.refreshUrl}. A value containing
+   * `{refreshToken}` is substituted with the current refresh token. Default: empty.
+   */
+  refreshPayload?: Record<string, string>;
+  /**
+   * Headers sent on the refresh request. A value containing `{accessToken}` is
+   * substituted with the current access token. Default:
+   * `{ Authorization: 'Bearer {accessToken}' }`.
+   */
+  refreshHeaders?: Record<string, string>;
+  /** Encoding of the refresh request body. Default: `'form'`. */
+  refreshBodyFormat?: AuthBodyFormat;
+  /** Where to read rotated tokens from the refresh response. Default: detection. */
+  responseMapping?: AuthResponseMapping;
+  /** Seconds before {@link AuthConfig.expiresAt} at which a proactive refresh fires. Default: `60`. */
+  skewMarginSeconds?: number;
+  /**
+   * Optional monotonic re-seed signal. When greater than the SDK's stored epoch,
+   * a re-supplied seed replaces the rotated token set (e.g. after the user
+   * re-authenticates). Omitted adopts a re-supplied seed only when no token has
+   * been stored yet.
+   */
+  seedEpoch?: number;
+};
+
+/**
+ * A token set the SDK rotated, delivered via `Beekon.onAuthTokens()`. Mirrors
+ * the native `AuthTokens` (iOS) / `TokenRefresh` (Android).
+ *
+ * Treat these as sensitive: they are delivered in-process only and are never
+ * logged or persisted to plaintext. Use them to mirror the SDK's current
+ * credentials into your own session store. The latest rotation is replayed to
+ * new subscribers (replay-1).
+ */
+export type AuthTokens = {
+  /** The rotated access token now in use. */
+  accessToken: string;
+  /** The current refresh token (rotated if the server returned a new one), or `null`. */
+  refreshToken: string | null;
+  /** Absolute expiry of {@link AuthTokens.accessToken}, or `null` if the response carried none. */
+  expiresAt: Date | null;
+  /** The SDK's monotonic token generation, incremented on each successful refresh. */
+  epoch: number;
+};

package/src/types/config.ts

@@ -1,33 +1,81 @@
+import type { AuthConfig } from './auth';
+import type { AccuracyMode, StationaryMode } from './enums';
+
 /**
- * Foreground-service notification overrides. Android-only — required by the
- * platform because every location foreground service must show a persistent
- * notification. All fields are optional; missing values resolve at runtime
- * against the host app's label and icon. Ignored on iOS.
+ * Foreground-service notification overrides. **Android-only** — the platform
+ * requires every location foreground service to show a persistent notification.
+ * Both fields are optional; missing values fall back to native defaults.
+ * Ignored on iOS.
  */
-export type AndroidNotificationConfig = {
-  /** Notification title. Defaults to "Location active". */
+export type NotificationConfig = {
+  /** Notification title. Defaults to "Tracking location". */
   title?: string;
-  /** Notification body text. Defaults to the host app's label. */
+  /** Notification body text. Defaults to no body. */
   text?: string;
   /**
-   * Drawable resource name (e.g. `ic_notification`) — resolved at runtime via
-   * `Resources.getIdentifier()` against the host app's `res/drawable*` folders.
-   * Pass the resource name without extension or `R.drawable.` prefix. Defaults
-   * to the host app's `applicationInfo.icon`.
+   * Status-bar icon, given as an Android drawable or mipmap resource **name**
+   * — `"ic_notification"`, `"drawable/ic_x"`, or `"mipmap/ic_x"`. Android
+   * renders the small icon from its alpha channel only, so supply a monochrome
+   * silhouette on a transparent background. Falls back to the host app's
+   * launcher icon when omitted or unresolvable.
    */
-  smallIconResName?: string;
+  smallIcon?: string;
 };
 
 /**
- * Tracking configuration. Two knobs: a minimum time interval and a minimum
- * distance between emitted fixes. A fix is admitted only when **both** gates
- * are satisfied. Pass `0` to disable a gate.
+ * Server-upload configuration. Presence of {@link BeekonConfig.sync} turns on
+ * batched uploads of stored locations and geofence events; omitting it keeps
+ * tracking local-only.
  */
-export type BeekonConfig = {
-  /** Minimum seconds between admitted fixes. Default: `30`. `0` disables the time gate. */
+export type SyncConfig = {
+  /** Ingest endpoint — an `http` or `https` URL. */
+  url: string;
+  /** Extra HTTP headers sent with every upload (e.g. `Authorization`). */
+  headers?: Record<string, string>;
+  /**
+   * Target seconds between uploads. The SDK enforces a 60s floor; background
+   * uploads may be delayed to the OS scheduler floor (~15 min). Default: `300`.
+   */
   intervalSeconds?: number;
-  /** Minimum metres between admitted fixes. Default: `100`. `0` disables the distance gate. */
-  distanceMeters?: number;
+  /** Maximum locations per upload. Clamped to `[1, 1000]`. Default: `100`. */
+  batchSize?: number;
+  /**
+   * Declarative token-refresh recipe. When set, the SDK attaches and natively
+   * refreshes the access token (proactively before expiry, reactively on
+   * `401`/`403`). Omit to keep the legacy static-{@link SyncConfig.headers}
+   * behaviour. Requires the native SDK ≥ 0.0.6. See {@link AuthConfig}.
+   */
+  auth?: AuthConfig;
+};
+
+/**
+ * Tracking configuration. Every field 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 = {
+  /** Minimum seconds between admitted fixes (10s floor). Default: `30`. */
+  minTimeBetweenLocationsSeconds?: number;
+  /** Minimum metres between admitted fixes. `0` disables it. Default: `100`. */
+  minDistanceBetweenLocationsMeters?: number;
+  /** Accuracy / battery preset. Default: `'balanced'`. */
+  accuracyMode?: AccuracyMode;
+  /** Behaviour while stationary. Default: `'pause'`. */
+  whenStationary?: StationaryMode;
+  /** Stationary exit-geofence radius, clamped to `[5, 1000]`. Default: `5`. */
+  stationaryRadiusMeters?: number;
+  /**
+   * Detect physical activity (walking, driving, …). Requires the
+   * `ACTIVITY_RECOGNITION` permission on Android and the `NSMotionUsageDescription`
+   * Info.plist key on iOS. Default: `false`.
+   */
+  detectActivity?: boolean;
+  /** Server-upload configuration. Omit to keep tracking local-only. */
+  sync?: SyncConfig;
   /** Android-only notification overrides. Ignored on iOS. */
-  androidNotification?: AndroidNotificationConfig;
+  notification?: NotificationConfig;
 };

package/src/types/enums.ts

@@ -0,0 +1,80 @@
+/**
+ * Value enums shared across the public API, expressed as string-literal unions
+ * (idiomatic TS). Each mirrors the like-named enum on both native SDKs by value;
+ * the wire layer carries them as plain strings and the mappers translate.
+ */
+
+/**
+ * Accuracy / battery-life preset for the location provider.
+ *
+ * - `'high'` — highest precision, highest battery cost (GPS-grade).
+ * - `'balanced'` — city-block precision, balanced battery (the default).
+ * - `'low'` — coarse, lowest battery.
+ */
+export type AccuracyMode = 'high' | 'balanced' | 'low';
+
+/**
+ * Behaviour while the device is stationary.
+ *
+ * - `'keepTracking'` — GPS stays on.
+ * - `'pause'` — GPS off while stationary, silent resume on movement (default).
+ * - `'pauseWithCheckIns'` — GPS off, but a location is recorded roughly every
+ *   15 minutes.
+ */
+export type StationaryMode = 'keepTracking' | 'pause' | 'pauseWithCheckIns';
+
+/**
+ * Why a {@link Location} was admitted and persisted.
+ *
+ * - `'interval'` — a scheduled fix that passed the time/distance gate.
+ * - `'motion'` — the device started or stopped moving.
+ * - `'checkIn'` — a periodic check-in while stationary.
+ * - `'geofence'` — a geofence crossing.
+ * - `'manual'` — an explicit request.
+ */
+export type LocationTrigger =
+  | 'interval'
+  | 'motion'
+  | 'checkIn'
+  | 'geofence'
+  | 'manual';
+
+/**
+ * The gate's quality verdict for a {@link Location}.
+ *
+ * - `'ok'` — passed the accuracy and speed checks.
+ * - `'lowAccuracy'` — worse than the usable accuracy threshold.
+ * - `'implausibleSpeed'` — an implausible jump from the previous fix.
+ */
+export type LocationQuality = 'ok' | 'lowAccuracy' | 'implausibleSpeed';
+
+/** Device motion when a {@link Location} was captured. */
+export type MotionState = 'moving' | 'stationary' | 'unknown';
+
+/**
+ * Detected physical activity. Only populated when
+ * {@link BeekonConfig.detectActivity} is enabled; otherwise `null`.
+ */
+export type ActivityType =
+  | 'stationary'
+  | 'walking'
+  | 'running'
+  | 'cycling'
+  | 'automotive'
+  | 'unknown';
+
+/**
+ * How the access token is attached to upload requests (token refresh).
+ *
+ * - `'bearer'` — `Authorization: Bearer <accessToken>` (JWT / OAuth2 style, default).
+ * - `'raw'` — `Authorization: <accessToken>` (the raw token, no scheme).
+ */
+export type AuthStrategy = 'bearer' | 'raw';
+
+/**
+ * Encoding of the token-refresh request body.
+ *
+ * - `'form'` — `application/x-www-form-urlencoded` (default; most OAuth2 endpoints).
+ * - `'json'` — `application/json`.
+ */
+export type AuthBodyFormat = 'form' | 'json';

package/src/types/error.ts

@@ -1,15 +1,33 @@
 /**
- * Error kinds thrown from `Beekon.start()` / `Beekon.history()`. Match the
- * native `BeekonError` cases byte-for-byte.
+ * Error kinds thrown across the bridge.
+ *
+ * Lifecycle problems on the tracking path never throw — they surface on the
+ * `onState` stream as `stopped(reason)`. The exceptions are the storage/geofence
+ * kinds below and the precondition kinds thrown by the explicit one-shot
+ * `getCurrentLocation()` (which has no `onState` arc of its own to report on; a
+ * plain timeout returns `null` instead of throwing).
+ *
+ * - `'storage'` — a local-store (SQLite) read/write failed. Thrown by
+ *   `getLocations()`, `deleteLocations()`, and `pendingUploadCount()`.
+ * - `'invalidGeofence'` — a geofence passed to `addGeofences()` failed
+ *   validation (empty/oversized id, or non-positive radius).
+ * - `'permissionDenied'` — location permission is missing. Thrown by
+ *   `getCurrentLocation()`.
+ * - `'locationServicesDisabled'` — system location services are off. Thrown by
+ *   `getCurrentLocation()`.
+ * - `'locationUnavailable'` — location is otherwise unavailable (e.g. Play
+ *   Services absent/old). Thrown by `getCurrentLocation()`.
  */
 export type BeekonErrorKind =
+  | 'storage'
+  | 'invalidGeofence'
   | 'permissionDenied'
   | 'locationServicesDisabled'
-  | 'storageFailure';
+  | 'locationUnavailable';
 
 /**
- * Typed error surfaced from the bridge. The native module rejects promises
- * with the kind encoded as the error code; the facade re-wraps into this.
+ * Typed error surfaced from the bridge. The native module rejects promises with
+ * the kind encoded as the error code; the facade re-wraps into this.
  */
 export class BeekonError extends Error {
   public readonly kind: BeekonErrorKind;

package/src/types/geofence.ts

@@ -0,0 +1,37 @@
+/**
+ * A circular geofence registered via `Beekon.addGeofences()`. Mirrors
+ * `BeekonGeofence` on both native SDKs. The SDK pages registrations
+ * automatically, so you may register more than the OS geofence limit.
+ */
+export type BeekonGeofence = {
+  /** Unique id, 1–100 characters. Re-adding an existing id replaces it. */
+  id: string;
+  /** Center latitude in degrees, WGS-84. */
+  latitude: number;
+  /** Center longitude in degrees, WGS-84. */
+  longitude: number;
+  /** Radius in metres. Must be `> 0`; `>= 100` is recommended for reliability. */
+  radiusMeters: number;
+  /** Emit an event on entry. Default: `true`. */
+  notifyOnEntry?: boolean;
+  /** Emit an event on exit. Default: `true`. */
+  notifyOnExit?: boolean;
+};
+
+/** Whether a {@link GeofenceEvent} marks entering or exiting a geofence. */
+export type Transition = 'enter' | 'exit';
+
+/**
+ * A geofence entry/exit crossing, delivered via `Beekon.onGeofenceEvent()`.
+ * Mirrors `GeofenceEvent` on both native SDKs.
+ */
+export type GeofenceEvent = {
+  /** Unique event id. Used as the dedup key on upload. */
+  id: string;
+  /** The {@link BeekonGeofence.id} that was crossed. */
+  geofenceId: string;
+  /** Whether the device entered or exited. */
+  type: Transition;
+  /** When the crossing happened. */
+  timestamp: Date;
+};