@sharib/geopulse-react-native 0.1.1

package/README.md

@@ -0,0 +1,194 @@
+# @sharib/geopulse-react-native
+
+On-device geofence detection and event sync for React Native / Expo apps. Fetches an
+application's configured geofences from GeoPulse, watches location (real device or the
+built-in simulator), and reports `geofence.enter` / `geofence.exit` events to the GeoPulse
+backend — with a persistent, backoff-retried offline queue so a flaky connection never loses
+an event.
+
+## Installation
+
+```bash
+npm install @sharib/geopulse-react-native
+```
+
+## Initialization
+
+Get `apiKey` and `applicationId` from the admin portal's `/sdk` page (the application created
+automatically for you during onboarding is named "Playground"). `functionsBaseUrl` is the
+deployed Cloud Functions base URL, e.g. `https://us-central1-<your-project-id>.cloudfunctions.net`
+(or your local Functions emulator's URL during development):
+
+```ts
+import { GeoPulse } from "@sharib/geopulse-react-native";
+
+await GeoPulse.initialize({
+  apiKey: "gp_test_xxx",
+  applicationId: "app_xxx",
+  functionsBaseUrl: "https://us-central1-your-project.cloudfunctions.net",
+});
+```
+
+`initialize()` fetches the application's currently active geofences from the backend
+(`getProjectConfig`) — this is the "SDK receives project configuration" step. It throws if any
+of the three fields above are missing, or if the backend call fails (bad/revoked SDK key,
+network error, etc.) — check `GeoPulse.getStatus()` (`"error"`) if you need to react to that.
+
+## Start / stop
+
+```ts
+await GeoPulse.start(); // requests location permission, begins watching location
+GeoPulse.stop();
+```
+
+`start()` throws if `initialize()` hasn't completed successfully, or if location permission is
+denied.
+
+## Events
+
+```ts
+const onEnter = (event) => console.log("entered", event.geofenceId, event);
+GeoPulse.on("geofence.enter", onEnter);
+GeoPulse.on("geofence.exit", (event) => console.log("exited", event));
+
+// later
+GeoPulse.off("geofence.enter", onEnter);
+```
+
+An event fires at most once per actual state transition — moving around *inside* a geofence
+never re-fires `geofence.enter`, and a geofence that's still active in your config never fires
+`geofence.exit` just because you didn't move (see `src/geofencing/state-machine.ts` in this
+package's source for the exact transition rules this guarantees).
+
+## Experiences (campaign delivery)
+
+If a geofence event matches an active Campaign in the admin portal, the SDK surfaces the
+associated Experience (a banner/card/message):
+
+```ts
+GeoPulse.on("experience.received", (payload) => {
+  // payload: ExperienceDeliveryPayload — { deliveryId, campaignId, experience: {...}, event: {...} }
+  showBanner(payload.experience);
+});
+```
+
+No push notifications involved: the SDK polls its own device's pending experiences on a timer
+(`GeoPulseConfig.experiencePollIntervalMs`, defaults to 30s) over the same connection it already
+uses for config/ingestion, and acknowledges each one automatically once it's fired the event —
+you never need to call anything to mark it "seen." The SDK also never re-fires the same
+`deliveryId` twice. There's no `getActiveExperiences()`: `on("experience.received")` is the
+whole surface — the SDK transports and notifies, your app owns the UI.
+
+## Status / diagnostics
+
+Beyond the two required by the spec (`getStatus`, `getPermissionStatus`), a rich diagnostics
+snapshot and a few small read-only accessors exist so a host app can build a status screen
+without duplicating SDK-internal state:
+
+```ts
+GeoPulse.getStatus(); // "idle" | "initializing" | "initialized" | "running" | "stopped" | "error"
+await GeoPulse.getPermissionStatus(); // "granted" | "denied" | "undetermined"
+await GeoPulse.getDiagnostics(); // rich snapshot: network status, config status, pending events, last sync, etc.
+GeoPulse.getApplicationId(); // string | null — resolved server-side, not just an echo of what you passed in
+GeoPulse.getDeviceId(); // string | null — persisted across app restarts
+// getDiagnostics() also includes `locationError: string | null` — set if the location provider
+// failed to start (e.g. OS location services off).
+GeoPulse.getConfiguredGeofences(); // the geofences fetched by initialize()
+GeoPulse.getLastKnownLocation(); // most recent location update, or null
+await GeoPulse.getPendingEventCount(); // events waiting in the offline queue right now
+```
+
+## Simulator
+
+Real device movement isn't required to test any of this. In development builds (`__DEV__ ===
+true`), `GeoPulse` runs on a simulated location provider by default:
+
+```ts
+GeoPulse.simulator.setLocation({ latitude: 33.4484, longitude: -112.074 });
+```
+
+Each call runs through the exact same geofence engine and event pipeline as a real device
+update would — the simulator is a location *source*, not a shortcut that fakes an event
+directly.
+
+**The simulator is inert in production builds.** `GeoPulse.simulator.setLocation(...)` is a
+no-op (with a console warning) once `__DEV__` is false — release builds run on
+`DeviceLocationProvider` (real `expo-location`) instead, automatically, with no code change
+required. If you need real device location *during development* instead of the simulator,
+construct your own instance rather than using the `GeoPulse` singleton:
+
+```ts
+import { GeoPulseSdk, DeviceLocationProvider, ExpoPermissionProvider } from "@sharib/geopulse-react-native";
+
+const sdk = new GeoPulseSdk({
+  locationProvider: new DeviceLocationProvider(),
+  permissionProvider: new ExpoPermissionProvider(),
+});
+```
+
+## Permissions
+
+This SDK requests **foreground location only** — never background location. Concretely:
+
+- **iOS**: `NSLocationWhenInUseUsageDescription` must be set in your app's `app.json` (or
+  `Info.plist` directly for a bare RN app); `expo-location`'s config plugin sets this from the
+  `locationWhenInUsePermission` option. No `NSLocationAlwaysAndWhenInUseUsageDescription` is
+  requested — the SDK will never prompt for "Always" access.
+- **Android**: `ACCESS_FINE_LOCATION` (and `ACCESS_COARSE_LOCATION` as a fallback) in the
+  manifest, via your app's `app.json`'s `android.permissions`. No `ACCESS_BACKGROUND_LOCATION`.
+- **Foreground-only limitation**: location updates (and therefore geofence detection) only run
+  while the app is in the foreground. Backgrounding the app pauses detection — an enter/exit
+  that happens while the app is backgrounded will not be caught until the app is foregrounded
+  again and a new location update arrives. This is a deliberate scope boundary for this phase,
+  not an oversight — background geofencing needs a materially different architecture (a native
+  background task, plus battery/OS-throttling tradeoffs) and is planned for a later phase. Do
+  not present this SDK as providing production-grade background geofencing.
+- **Battery**: `DeviceLocationProvider` uses `Location.Accuracy.Balanced` with a 10m distance
+  filter and a 5s minimum interval — a reasonable foreground default, not tuned for
+  high-precision or high-frequency tracking.
+
+## Troubleshooting
+
+- **`initialize()` rejects with "requires functionsBaseUrl"** — you only passed
+  `apiKey`/`applicationId`; add `functionsBaseUrl` (see Initialization above).
+- **`initialize()` rejects with a fetch/network error** — check `functionsBaseUrl` is reachable
+  from the device (an emulator URL like `127.0.0.1` is not reachable from a physical device or
+  even always from a simulator — use your machine's LAN IP or a deployed URL instead).
+- **`start()` rejects with "Location permission not granted"** — the user denied the OS
+  permission prompt (real device), or `PermissionProvider.request()` didn't resolve
+  `"granted"` (simulator mode always grants — this only happens with `DeviceLocationProvider`).
+- **No `geofence.enter` ever fires in the simulator** — confirm `GeoPulse.getConfiguredGeofences()`
+  isn't empty; if it is, no geofence exists yet for this application's project in the admin
+  portal, or `initialize()` was called before the SDK key's application had one created.
+- **Events show up in `getPendingEventCount()` but never seem to send** — each queued event has
+  its own exponential-backoff schedule; a recently-failed event isn't retried again immediately.
+  Retries also fire as soon as the network monitor reports connectivity restored, so this should
+  resolve quickly once you're actually back online — if it doesn't, check `functionsBaseUrl` is
+  reachable at all.
+
+## Internal architecture
+
+```
+src/
+  core/         SDK lifecycle + diagnostics (GeoPulseSdk), Logger — the only module that wires everything else together
+  config/       GeoPulseConfig type, device-id persistence, config caching
+  location/     LocationProvider abstraction: SimulatedLocationProvider (default in dev) + DeviceLocationProvider (expo-location)
+  geofencing/   GeofenceStateMachine — haversine distance + INSIDE/OUTSIDE transition tracking
+  events/       Event payload construction + id generation
+  storage/      Offline pending-event queue (InMemoryEventQueueStore for tests, AsyncStorageEventQueueStore for the real app)
+  sync/         SyncManager (send-or-queue, backoff retry), centralized retry policy, NetworkMonitor
+  permissions/  PermissionProvider abstraction: SimulatedPermissionProvider (default in dev) + ExpoPermissionProvider
+  firebase/     ApiClient — plain-fetch HTTPS client for the Cloud Functions endpoints (no Firebase SDK on-device)
+  index.ts      Public API (GeoPulse) — wires the real RN adapters; everything else is injectable for testing
+```
+
+Every module except `location/device-location-provider.ts`,
+`permissions/expo-permission-provider.ts`, `storage/async-storage-store.ts`,
+`config/async-storage-key-value-store.ts`, and `sync/netinfo-network-monitor.ts` has zero React
+Native dependencies and runs under plain Node/Vitest — those five are the only files that
+import an RN-only package, and nothing in `core/`, `geofencing/`, `events/`, `sync/`
+(excluding the one file above), or `firebase/` imports them (see the comments at the top of
+`storage/index.ts`, `location/index.ts`, `config/index.ts`, `permissions/index.ts`, and
+`sync/index.ts`). That split is what makes `GeoPulseSdk` and the geofence engine unit-testable
+without a device, simulator, or Metro bundler — run `pnpm test` from this package's directory
+(55 tests as of this phase).

package/dist/index.d.ts

@@ -0,0 +1,489 @@
+declare const GEOFENCE_EVENT_TYPES: readonly ["geofence.enter", "geofence.exit"];
+type GeofenceEventType = (typeof GEOFENCE_EVENT_TYPES)[number];
+declare const DEVICE_PLATFORMS: readonly ["ios", "android", "web", "unknown"];
+type DevicePlatform = (typeof DEVICE_PLATFORMS)[number];
+declare const EXPERIENCE_TYPES: readonly ["banner", "card", "message"];
+type ExperienceType = (typeof EXPERIENCE_TYPES)[number];
+interface ExperienceStyle {
+    backgroundColor: string | null;
+    textColor: string | null;
+    accentColor: string | null;
+}
+interface GeofenceCenter {
+    latitude: number;
+    longitude: number;
+}
+interface SdkGeofenceConfig {
+    id: string;
+    name: string;
+    locationId: string;
+    locationName: string;
+    center: GeofenceCenter;
+    radiusMeters: number;
+}
+interface SdkProjectConfig {
+    applicationId: string;
+    projectId: string;
+    applicationEnabled: boolean;
+    configVersion: string;
+    geofences: SdkGeofenceConfig[];
+}
+interface LocationEventPayload {
+    id: string;
+    type: GeofenceEventType;
+    projectId: string;
+    applicationId: string;
+    geofenceId: string;
+    locationId: string;
+    deviceId: string;
+    timestamp: string;
+    latitude: number;
+    longitude: number;
+    metadata: Record<string, string>;
+    sdkVersion: string;
+    attempts: number;
+}
+interface ExperienceDeliveryPayload {
+    type: "location.experience";
+    deliveryId: string;
+    campaignId: string;
+    experience: {
+        id: string;
+        type: ExperienceType;
+        title: string;
+        body: string;
+        imageUrl: string | null;
+        ctaLabel: string | null;
+        ctaUrl: string | null;
+        style: ExperienceStyle | null;
+    };
+    event: {
+        id: string;
+        type: GeofenceEventType;
+        geofenceId: string;
+        timestamp: string;
+    };
+}
+
+interface GeoPulseConfig {
+    apiKey: string;
+    applicationId: string;
+    /**
+     * Base URL of the deployed GeoPulse Cloud Functions (e.g.
+     * `https://us-central1-<project-id>.cloudfunctions.net`, or the local
+     * Functions emulator's URL during development). Not part of the minimal
+     * `{ apiKey, applicationId }` example in the docs because it's
+     * deployment-specific, but required in practice — `initialize()` throws a
+     * clear error if it's missing.
+     */
+    functionsBaseUrl?: string;
+    /** How often to retry queued (previously failed) events, in milliseconds. Defaults to 30s. */
+    retryIntervalMs?: number;
+    /** How often to poll for pending campaign experiences (Phase 5B), in milliseconds. Defaults to 30s, mirroring `retryIntervalMs`. A host app that wants faster demo feedback (see apps/playground) can pass a smaller value. */
+    experiencePollIntervalMs?: number;
+    /** Enables the lifecycle/event debug log lines described in this package's README. Defaults to `__DEV__`. Never logs the SDK key or event payload bodies. */
+    debug?: boolean;
+}
+
+/**
+ * Minimal persistent key-value abstraction, shared by device-id.ts and
+ * config-cache.ts — deliberately smaller than `storage/EventQueueStore`
+ * (which manages a whole collection) since these two only ever need "get
+ * one string" / "set one string".
+ */
+interface KeyValueStore {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+}
+
+interface DeviceIdentity {
+    deviceId: string;
+    platform: DevicePlatform;
+    sdkVersion: string;
+}
+/**
+ * Named `firebase/` per this project's spec ("communication with GeoPulse
+ * backend"), but deliberately does NOT use the Firebase client SDK — it
+ * talks to the Cloud Functions HTTPS endpoints over plain `fetch` (built
+ * into both React Native's JS runtime and Node 18+, so this file is
+ * testable without any RN runtime at all). That keeps the SDK's dependency
+ * footprint small and means device requests carry only the app-scoped SDK
+ * key, never a Firebase credential of any kind.
+ */
+declare class ApiClient {
+    private readonly baseUrl;
+    private readonly sdkKey;
+    constructor(baseUrl: string, sdkKey: string);
+    /**
+     * `identity` doubles as this device's registration/heartbeat (see
+     * functions/src/events/get-project-config.ts) — sent as query params
+     * since GET requests carry no body.
+     */
+    getProjectConfig(identity: DeviceIdentity): Promise<SdkProjectConfig>;
+    ingestEvent(payload: LocationEventPayload): Promise<{
+        id: string;
+        deduplicated: boolean;
+    }>;
+    /** Polled by GeoPulseSdk's experience-polling loop — see core/geo-pulse-sdk.ts. */
+    getPendingExperiences(deviceId: string): Promise<ExperienceDeliveryPayload[]>;
+    /** Confirms a delivery was surfaced via `experience.received`, so it stops appearing in future polls. */
+    acknowledgeExperienceDelivery(deliveryId: string): Promise<void>;
+}
+
+interface LocationUpdate {
+    latitude: number;
+    longitude: number;
+    timestamp: string;
+}
+/**
+ * The SDK's own abstraction over "something that produces location
+ * updates" — deliberately small (start/stop) so both the mandatory
+ * simulator and a real device provider implement it identically, and the
+ * core lifecycle (../core) never needs to know which one it's driving.
+ */
+interface LocationProvider {
+    /**
+     * `onError` covers a provider that fails to start at all (e.g. a real
+     * device with location services turned off) — implementations must catch
+     * their own internal failures and report them here rather than letting an
+     * exception escape `start()` unhandled (see `DeviceLocationProvider` for
+     * why: an uncaught rejection from a native module is exactly the kind of
+     * thing that shouldn't be able to crash the host app).
+     */
+    start(onUpdate: (location: LocationUpdate) => void, onError?: (error: Error) => void): Promise<void> | void;
+    stop(): void;
+}
+
+type PermissionStatus = "granted" | "denied" | "undetermined";
+interface PermissionProvider {
+    getStatus(): Promise<PermissionStatus>;
+    request(): Promise<PermissionStatus>;
+}
+
+/**
+ * "sending" is a short-lived marker set immediately before an upload
+ * attempt and cleared right after (success removes the record entirely;
+ * failure moves it back to "pending"/"failed") — it exists specifically so
+ * two overlapping retry passes (e.g. a manual retry racing the timer) don't
+ * both attempt the same event at once. There is no "delivered" status
+ * stored here: a delivered event is removed from the queue, not
+ * transitioned — see PendingEventQueue's class doc for why.
+ */
+declare const QUEUED_EVENT_STATUSES: readonly ["pending", "sending", "failed"];
+type QueuedEventStatus = (typeof QUEUED_EVENT_STATUSES)[number];
+interface QueuedEvent {
+    eventId: string;
+    /** Flattened copies of the corresponding `payload` fields, purely so diagnostics/inspection don't need to unwrap `payload` for the common case. */
+    type: GeofenceEventType;
+    applicationId: string;
+    deviceId: string;
+    locationId: string;
+    geofenceId: string;
+    timestamp: string;
+    payload: LocationEventPayload;
+    attempts: number;
+    status: QueuedEventStatus;
+    createdAt: string;
+    lastAttemptAt: string | null;
+    /** Backoff scheduling — retryPending() skips any event whose nextAttemptAt is still in the future. Null means "ready now" (never attempted, or immediately retryable). */
+    nextAttemptAt: string | null;
+}
+/**
+ * Storage abstraction so the queue's retry/dedupe logic (storage/queue.ts)
+ * is testable in plain Node — `InMemoryEventQueueStore` for tests and as a
+ * safe default, `AsyncStorageEventQueueStore` for the real RN app. Kept
+ * intentionally minimal (get/save/remove over the whole set) so a future
+ * SQLite-backed store is a drop-in replacement without touching
+ * `PendingEventQueue`'s logic — see this package's README.
+ */
+interface EventQueueStore {
+    getAll(): Promise<QueuedEvent[]>;
+    save(event: QueuedEvent): Promise<void>;
+    remove(eventId: string): Promise<void>;
+}
+
+/**
+ * The local pending-event queue (spec: "Offline queue" / "reliable SDK
+ * event queue"). An event is only ever in this queue between a failed send
+ * attempt and a successful retry — there's no "delivered" status because a
+ * delivered event is simply removed (`markSent`), which is also what makes
+ * retrying an already-sent event harmless: it's not in the queue to retry.
+ */
+declare class PendingEventQueue {
+    private readonly store;
+    constructor(store?: EventQueueStore);
+    enqueue(payload: LocationEventPayload): Promise<void>;
+    /** Every queued event, regardless of retry timing — used for diagnostics/pending counts. */
+    listPending(): Promise<QueuedEvent[]>;
+    /** Only events whose backoff window has elapsed (or that have never been attempted) — used by SyncManager.retryPending(). */
+    listReadyForRetry(now?: Date): Promise<QueuedEvent[]>;
+    /** Marks an event as in-flight so a concurrent retry pass won't also pick it up. */
+    markSending(eventId: string): Promise<void>;
+    markAttemptFailed(eventId: string): Promise<void>;
+    markSent(eventId: string): Promise<void>;
+    private get;
+}
+
+type NetworkStatus = "online" | "offline" | "unknown";
+interface NetworkMonitor {
+    getStatus(): NetworkStatus;
+    /** Calls `listener` whenever connectivity changes. Returns an unsubscribe function. */
+    subscribe(listener: (status: NetworkStatus) => void): () => void;
+}
+/**
+ * Default/test implementation — starts "online" (optimistic default: if we
+ * can't observe connectivity, assume the network call itself is the
+ * ultimate source of truth rather than blocking on a monitor). Tests (and
+ * the Node/non-RN environment generally) drive it explicitly via
+ * `setStatus`; see `sync/netinfo-network-monitor.ts` for the real RN
+ * implementation, kept in its own file for the same reason
+ * `storage/async-storage-store.ts` is — see that file's comment.
+ */
+declare class ManualNetworkMonitor implements NetworkMonitor {
+    private status;
+    private readonly listeners;
+    getStatus(): NetworkStatus;
+    setStatus(status: NetworkStatus): void;
+    subscribe(listener: (status: NetworkStatus) => void): () => void;
+}
+
+type SdkStatus = "idle" | "initializing" | "initialized" | "running" | "stopped" | "error";
+type ConfigurationStatus = "unsynced" | "synced" | "cached" | "unavailable";
+/**
+ * `GeoPulse.getDiagnostics()` — a superset of `getStatus()`, purpose-built
+ * for a developer-facing status screen (spec section 10/11) rather than
+ * for the SDK's own internal decisions, which is why this is a separate
+ * method instead of changing what `getStatus()` returns: the existing
+ * playground code (and any Phase 2 integration) already depends on
+ * `getStatus()` returning the plain `SdkStatus` string.
+ */
+interface DiagnosticsSnapshot {
+    initialized: boolean;
+    running: boolean;
+    locationAvailable: boolean;
+    permissionStatus: PermissionStatus | "unknown";
+    networkStatus: "online" | "offline" | "unknown";
+    configurationStatus: ConfigurationStatus;
+    configVersion: string | null;
+    pendingEvents: number;
+    /** Sum of `attempts` across every currently-queued event — a rough "how much retrying is backed up" signal for a diagnostics screen. */
+    totalRetryAttempts: number;
+    /** Set when the location provider failed to start (e.g. OS location services disabled) — see LocationProvider's `onError`. Null when location started cleanly or hasn't been attempted yet. */
+    locationError: string | null;
+    lastEventAt: string | null;
+    lastEventType: GeofenceEventType | null;
+    lastSyncAt: string | null;
+    lastUploadResult: "success" | "failure" | null;
+    deviceId: string | null;
+    sdkVersion: string;
+    /** Count of distinct campaign experiences received via `experience.received` this session (Phase 5B). Resets on app restart, not persisted — purely a live "is the pipeline working" signal for a status screen. */
+    experiencesReceivedCount: number;
+}
+
+type EventListener = (event: LocationEventPayload) => void;
+type ExperienceListener = (payload: ExperienceDeliveryPayload) => void;
+/**
+ * Everything the SDK talks to outside of itself, injectable so
+ * `GeoPulseSdk` (this whole lifecycle) is unit-testable without an RN
+ * runtime — tests construct it with fakes; `src/index.ts` (the real public
+ * entrypoint) constructs the default instance with the real RN adapters.
+ */
+interface GeoPulseSdkDependencies {
+    locationProvider?: LocationProvider;
+    permissionProvider?: PermissionProvider;
+    queue?: PendingEventQueue;
+    createApiClient?: (config: GeoPulseConfig) => ApiClient;
+    deviceIdStore?: KeyValueStore;
+    configCacheStore?: KeyValueStore;
+    networkMonitor?: NetworkMonitor;
+    /** Defaults to "unknown" — src/index.ts supplies the real `Platform.OS` so this file stays RN-free. */
+    getPlatform?: () => DevicePlatform;
+    /** Overrides GeoPulseConfig.debug — mainly for tests that want to assert on log output. */
+    debug?: boolean;
+}
+declare class GeoPulseSdk {
+    private status;
+    private config;
+    private apiClient;
+    private syncManager;
+    private resolvedProjectId;
+    private resolvedApplicationId;
+    private applicationEnabled;
+    private configVersion;
+    private configurationStatus;
+    private geofences;
+    private lastKnownLocation;
+    private lastEvent;
+    private deviceId;
+    private locationError;
+    private unsubscribeNetwork;
+    private readonly stateMachine;
+    private readonly listeners;
+    private readonly experienceListeners;
+    /** Client-side duplicate protection (spec section 14) — belt-and-suspenders alongside the server-side ack; a delivery already acked but re-observed before the ack lands must not fire `experience.received` twice. */
+    private readonly seenExperienceDeliveryIds;
+    private experiencePollTimer;
+    private experiencesReceivedCount;
+    private readonly logger;
+    private readonly locationProvider;
+    private readonly permissionProvider;
+    private readonly queue;
+    private readonly buildApiClient;
+    private readonly deviceIdStore;
+    private readonly configCache;
+    private readonly networkMonitor;
+    private readonly getPlatform;
+    private experiencePollIntervalMs;
+    constructor(dependencies?: GeoPulseSdkDependencies);
+    /**
+     * Resolves this device's persistent id, then fetches (or falls back to
+     * cached) project configuration. Must succeed — fresh or cached — before
+     * `start()`; if neither is available (first-ever run with no network),
+     * this rethrows and `getStatus()` reports "error".
+     */
+    initialize(config: GeoPulseConfig): Promise<void>;
+    start(): Promise<void>;
+    stop(): void;
+    getStatus(): SdkStatus;
+    getPermissionStatus(): Promise<PermissionStatus>;
+    on(eventName: GeofenceEventType, callback: EventListener): void;
+    on(eventName: "experience.received", callback: ExperienceListener): void;
+    off(eventName: GeofenceEventType, callback: EventListener): void;
+    off(eventName: "experience.received", callback: ExperienceListener): void;
+    getConfiguredGeofences(): SdkGeofenceConfig[];
+    /** The server-resolved application id (from `getProjectConfig`), or null before `initialize()` completes. */
+    getApplicationId(): string | null;
+    getLastKnownLocation(): LocationUpdate | null;
+    getPendingEventCount(): Promise<number>;
+    /** Null until `initialize()` resolves it — persisted across app restarts (see config/device-id.ts). */
+    getDeviceId(): string | null;
+    /**
+     * The rich developer-diagnostics snapshot (spec section 10/11) — a
+     * superset of `getStatus()`, not a replacement for it (see core/types.ts's
+     * `DiagnosticsSnapshot` doc for why these are two separate methods).
+     */
+    getDiagnostics(): Promise<DiagnosticsSnapshot>;
+    /**
+     * Only functional when the SDK is running the simulated location
+     * provider (the default outside of production builds — see
+     * src/index.ts) and gated by `__DEV__` so it's inert in a production
+     * bundle even if a caller somehow held a reference to it.
+     */
+    simulateLocation(coords: {
+        latitude: number;
+        longitude: number;
+    }): void;
+    /**
+     * The Phase 5B delivery mechanism: poll immediately on `start()` (so a
+     * demo doesn't wait a full interval for the first check), then on a
+     * timer. A poll failure (network blip, backend down) is logged and
+     * swallowed — it must never crash the SDK or the host app (spec section
+     * 13), and the next tick tries again on its own.
+     */
+    private startExperiencePolling;
+    private stopExperiencePolling;
+    private pollForExperiences;
+    private applyProjectConfig;
+    private handleLocationUpdate;
+}
+
+/**
+ * Real, foreground-only device location via expo-location. Does not
+ * request or use background location — see this package's README for the
+ * platform permission requirements and why background tracking is
+ * explicitly out of scope for this phase.
+ */
+declare class DeviceLocationProvider implements LocationProvider {
+    private subscription;
+    /**
+     * `watchPositionAsync` rejects if location services are off at the OS
+     * level (distinct from the app's own permission grant, which is checked
+     * before this ever runs) — caught here and reported via `onError` instead
+     * of left to reject this method's own promise, so a caller that doesn't
+     * wrap `GeoPulse.start()` in a try/catch still can't end up with an
+     * unhandled rejection from deep inside a native module.
+     */
+    start(onUpdate: (location: LocationUpdate) => void, onError?: (error: Error) => void): Promise<void>;
+    stop(): void;
+}
+
+/**
+ * The mandatory simulation provider (spec section 7) — lets the geofence
+ * flow be exercised end to end without physically travelling anywhere.
+ * `setLocation` is the playground simulator screen's only way to move the
+ * "user"; everything downstream (geofence engine, event generation, sync)
+ * runs exactly as it would for a real device update, because both
+ * providers speak the same `LocationProvider` interface.
+ */
+declare class SimulatedLocationProvider implements LocationProvider {
+    private onUpdate;
+    private currentLocation;
+    start(onUpdate: (location: LocationUpdate) => void): void;
+    stop(): void;
+    setLocation(coords: {
+        latitude: number;
+        longitude: number;
+    }): void;
+    getCurrentLocation(): LocationUpdate | null;
+}
+
+/**
+ * Foreground-only — see this package's README ("Permissions" section) for
+ * why background permission is explicitly out of scope for this phase.
+ * Requests only the foreground permission; never touches
+ * `requestBackgroundPermissionsAsync`.
+ */
+declare class ExpoPermissionProvider implements PermissionProvider {
+    getStatus(): Promise<PermissionStatus>;
+    request(): Promise<PermissionStatus>;
+}
+
+/**
+ * Used with the simulated location provider (see ../location) — a
+ * simulated user obviously isn't gated by the OS location permission
+ * dialog, so this always reports "granted" rather than requiring a real
+ * device's permission state to test the geofence flow end to end.
+ */
+declare class SimulatedPermissionProvider implements PermissionProvider {
+    getStatus(): Promise<PermissionStatus>;
+    request(): Promise<PermissionStatus>;
+}
+
+/** Real connectivity detection for the RN app. Isolated in its own file — see storage/async-storage-store.ts's comment for why. */
+declare class NetInfoNetworkMonitor implements NetworkMonitor {
+    private status;
+    constructor();
+    getStatus(): NetworkStatus;
+    subscribe(listener: (status: NetworkStatus) => void): () => void;
+}
+
+/** `sdk.on`/`sdk.off` are already overloaded this way (see core/geo-pulse-sdk.ts) — this just re-states the same public shape for the plain-object `GeoPulse` singleton below. */
+type OnOff = {
+    (eventName: GeofenceEventType, callback: (event: LocationEventPayload) => void): void;
+    (eventName: "experience.received", callback: (payload: ExperienceDeliveryPayload) => void): void;
+};
+declare const GeoPulse: {
+    initialize: (config: GeoPulseConfig) => Promise<void>;
+    start: () => Promise<void>;
+    stop: () => void;
+    getStatus: () => SdkStatus;
+    getPermissionStatus: () => Promise<PermissionStatus>;
+    on: OnOff;
+    off: OnOff;
+    getConfiguredGeofences: () => SdkGeofenceConfig[];
+    getApplicationId: () => string | null;
+    getLastKnownLocation: () => LocationUpdate | null;
+    getPendingEventCount: () => Promise<number>;
+    getDeviceId: () => string | null;
+    /** Rich developer-diagnostics snapshot — see core/types.ts's DiagnosticsSnapshot doc. */
+    getDiagnostics: () => Promise<DiagnosticsSnapshot>;
+    /** Development-only. No-ops (with a console warning) in a production build — see GeoPulseSdk.simulateLocation. */
+    simulator: {
+        setLocation: (coords: {
+            latitude: number;
+            longitude: number;
+        }) => void;
+    };
+};
+
+export { type ConfigurationStatus, DeviceLocationProvider, type DiagnosticsSnapshot, type ExperienceDeliveryPayload, ExpoPermissionProvider, GeoPulse, type GeoPulseConfig, GeoPulseSdk, type GeofenceEventType, type LocationEventPayload, type LocationProvider, type LocationUpdate, ManualNetworkMonitor, NetInfoNetworkMonitor, type NetworkMonitor, type NetworkStatus, type PermissionProvider, type PermissionStatus, type SdkGeofenceConfig, type SdkStatus, SimulatedLocationProvider, SimulatedPermissionProvider };