@damn-coding/geopulse-react-native 0.0.0-stage → 0.5.1

package/dist/index.d.ts

@@ -0,0 +1,702 @@
+import React from 'react';
+
+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", "alert"];
+type ExperienceType = (typeof EXPERIENCE_TYPES)[number];
+declare const ANCHOR_POINTS: readonly ["top-left", "top-center", "top-right", "center-left", "center", "center-right", "bottom-left", "bottom-center", "bottom-right"];
+type AnchorPoint = (typeof ANCHOR_POINTS)[number];
+interface AnchoredPosition {
+    anchor: AnchorPoint;
+    offsetX?: number | null;
+    offsetY?: number | null;
+}
+interface ContainerStyle {
+    backgroundColor?: string | null;
+    borderColor?: string | null;
+    borderWidth?: number | null;
+    borderRadius?: number | null;
+    padding?: number | null;
+    backgroundImageUrl?: string | null;
+    backgroundImageFit?: "cover" | "contain" | "stretch";
+    widthMode?: "fill" | "fixed";
+    width?: number | null;
+    heightMode?: "auto" | "fixed";
+    height?: number | null;
+}
+interface TextStyle {
+    visible?: boolean;
+    color?: string | null;
+    fontSize?: number | null;
+    fontWeight?: "normal" | "bold";
+}
+interface ButtonStyle {
+    visible?: boolean;
+    backgroundColor?: string | null;
+    textColor?: string | null;
+    borderRadius?: number | null;
+    position?: AnchoredPosition | null;
+}
+interface ExperienceStyleV2 {
+    version: 2;
+    container?: ContainerStyle;
+    title?: TextStyle;
+    body?: TextStyle;
+    button?: ButtonStyle;
+}
+interface ExperienceStyleLegacy {
+    backgroundColor: string | null;
+    textColor: string | null;
+    accentColor: string | null;
+}
+type ExperienceStyle = ExperienceStyleV2 | ExperienceStyleLegacy;
+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;
+    /** Changes when the experience's content is edited; absent on older backends. */
+    revision?: number;
+    /** Set by the SDK, never the backend: true when this replaces content the user was already shown for the same delivery. */
+    isUpdate?: boolean;
+    experience: {
+        id: string;
+        type: ExperienceType;
+        title: string;
+        body: string;
+        imageUrl: string | null;
+        cardNavigationUrl: string | null;
+        ctaLabel: string | null;
+        ctaUrl: string | null;
+        style: ExperienceStyle | null;
+    };
+    event: {
+        id: string;
+        type: GeofenceEventType;
+        geofenceId: string;
+        timestamp: string;
+    };
+}
+/** A delivery the user was already shown that the app must now remove (its campaign was deleted or disabled). */
+interface RevokedExperience {
+    deliveryId: string;
+    campaignId: string;
+}
+/** Response body of `getPendingExperiences`; `revoked` is absent on older backends. */
+interface PendingExperiencesResponse {
+    experiences: ExperienceDeliveryPayload[];
+    revoked?: RevokedExperience[];
+}
+
+interface GeoPulseConfig {
+    apiKey: string;
+    applicationId: string;
+    /**
+     * Internal override for the GeoPulse backend URL — only for GeoPulse's own
+     * local development (e.g. apps/playground against a local backend).
+     * Customers never set this; it defaults to `DEFAULT_BACKEND_URL`.
+     */
+    functionsBaseUrl?: string;
+    /** How often to retry queued (previously failed) events, in milliseconds. Defaults to 30s. */
+    retryIntervalMs?: number;
+    /**
+     * Fallback interval for polling pending campaign experiences, in milliseconds. Defaults to 15 minutes.
+     * Experiences are normally fetched right after an event the backend says created one, once on
+     * `start()`, and when the server pushes a change to a phone inside a geofence, so this only catches anything missed. Lower it only if you need that safety net faster.
+     */
+    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;
+}
+interface IngestResult {
+    id: string;
+    deduplicated: boolean;
+    /** False when the backend created no experience for this event, so polling for one would find nothing. Absent on older backends — treat as "maybe". */
+    experiencesPending?: boolean;
+}
+/**
+ * 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;
+    /** Optional so existing callers keep working; when set, the backend rejects a key bound to a different application. */
+    private readonly applicationId?;
+    constructor(baseUrl: string, sdkKey: string, 
+    /** Optional so existing callers keep working; when set, the backend rejects a key bound to a different application. */
+    applicationId?: string | undefined);
+    private headers;
+    /**
+     * `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<IngestResult>;
+    /** Polled by GeoPulseSdk's experience-polling loop — see core/geo-pulse-sdk.ts. */
+    getPendingExperiences(deviceId: string): Promise<Required<PendingExperiencesResponse>>;
+    /** Confirms a delivery was surfaced via `experience.received`, so it stops appearing in future polls. */
+    acknowledgeExperienceDelivery(deliveryId: string): Promise<void>;
+}
+
+interface StateMachineOptions {
+    /** How far past the edge a position must be before an exit counts (GPS jitter at the boundary). Default 20 m, or the fix's accuracy if larger. */
+    exitBufferMeters?: number;
+    /** Fixes less accurate than this are ignored: they cannot tell inside from outside. Default 100 m. */
+    maxAccuracyMeters?: number;
+    /** Minimum time between two transitions of the same geofence. Default 2 minutes. */
+    cooldownMs?: number;
+    now?: () => number;
+}
+
+/**
+ * Structured, easy-to-disable debug logging (spec section 22). Every call
+ * site passes a short lifecycle label matching the examples in this
+ * package's README ("Configuration synced", "Event queued", ...) plus
+ * optional structured details — never the SDK key, never a raw event
+ * payload body, never anything from `GeoPulseConfig` beyond `applicationId`.
+ */
+declare class Logger {
+    private enabled;
+    constructor(enabled: boolean);
+    setEnabled(enabled: boolean): void;
+    log(message: string, details?: Record<string, unknown>): void;
+    warn(message: string, details?: Record<string, unknown>): void;
+}
+
+/** The part of a WebSocket the client uses; React Native's built-in `WebSocket` satisfies it, and tests pass a fake. */
+interface RealtimeSocket {
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code: number;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+interface RealtimeOptions {
+    /** Backend base URL (https://...). The socket goes to the same host over wss://. */
+    baseUrl: string;
+    sdkKey: string;
+    applicationId: string;
+    deviceId: string;
+    /** The server says something changed for this device: fetch it. */
+    onChanged: () => void;
+    /** The server accepted the connection. Anything changed while we were disconnected is fetched now. */
+    onConnected: () => void;
+    createSocket?: (url: string) => RealtimeSocket;
+    logger?: Logger;
+}
+/** What the host app (index.ts) hands to GeoPulseSdk: just connect and disconnect. */
+interface RealtimeConnection {
+    connect(): void;
+    disconnect(): void;
+    isConnected(): boolean;
+}
+
+interface LocationUpdate {
+    latitude: number;
+    longitude: number;
+    timestamp: string;
+    /** Horizontal accuracy radius in meters, when the provider knows it. A big value means the fix cannot be trusted near a geofence edge. */
+    accuracy?: number;
+}
+/**
+ * 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.
+ *
+ * Every operation runs one at a time. The store keeps the whole queue in one value, so each change is read, modify,
+ * write; two overlapping ones (a retry finishing while a new event is queued) would otherwise overwrite each other and
+ * lose an event.
+ */
+declare class PendingEventQueue {
+    private readonly store;
+    private chain;
+    constructor(store?: EventQueueStore);
+    private serialized;
+    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(). Drops events too old to ever be accepted. */
+    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>;
+    /** `minDelayMs` lets a 429's Retry-After push the next attempt later than the normal backoff. */
+    markAttemptFailed(eventId: string, minDelayMs?: number): Promise<void>;
+    markSent(eventId: string): Promise<void>;
+    private get;
+    /** Keeps the queue within MAX_QUEUE_SIZE by dropping the oldest events that are not being sent right now. */
+    private trim;
+}
+
+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;
+type ExperienceRemovedListener = (payload: RevokedExperience) => void;
+/** The SDK key resolved to a different application than `config.applicationId`. */
+declare class ApplicationMismatchError extends Error {
+    constructor();
+}
+/**
+ * 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;
+    /** Where the geofence state machine keeps its memory across restarts. Defaults to memory only (lost on restart). */
+    stateStore?: KeyValueStore;
+    /** Tuning for tests (cooldown, exit buffer, clock). */
+    stateMachineOptions?: StateMachineOptions;
+    /**
+     * Builds the push connection used while the user is inside a geofence. Not set by default: the core has no
+     * WebSocket dependency, and src/index.ts supplies the real one.
+     */
+    createRealtimeClient?: (options: RealtimeOptions) => RealtimeConnection;
+}
+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 geofenceStateStore;
+    private geofenceStateRestored;
+    private realtime;
+    private readonly createRealtime;
+    private lastConfigFetchAt;
+    private configRefreshInFlight;
+    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 seenExperienceRevisions;
+    private readonly experienceRemovedListeners;
+    private readonly removedDeliveryIds;
+    private experiencePollTimer;
+    private experiencePollInFlight;
+    /** Set while a poll that was refused with "too many requests" waits to be tried again. */
+    private pollRetryTimer;
+    /** Set when a poll was asked for while one was already running; that one may have queried before the new delivery existed. */
+    private experiencePollRequested;
+    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;
+    on(eventName: "experience.removed", callback: ExperienceRemovedListener): void;
+    off(eventName: GeofenceEventType, callback: EventListener): void;
+    off(eventName: "experience.received", callback: ExperienceListener): void;
+    off(eventName: "experience.removed", callback: ExperienceRemovedListener): 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;
+    /**
+     * The backend says in its ingest response whether the event created an experience for this
+     * device. Poll right away if so (or if it doesn't say — an older backend), skip if it says
+     * there is nothing. Does nothing unless polling is active, so a stopped SDK never polls.
+     */
+    private handleEventDelivered;
+    /** One poll at a time: a second request while one is running makes it run once more afterwards, rather than overlapping. */
+    private pollForExperiences;
+    private pollForExperiencesOnce;
+    private schedulePollRetry;
+    /**
+     * Re-reads the geofence list when it is an hour old, so a geofence an admin added, moved, resized or removed reaches a phone
+     * that keeps the app open (otherwise only a restart picks it up). Runs from the poll timer, so it costs no timer of its own.
+     * A failure keeps the list we have. A disabled application stops the SDK.
+     */
+    private refreshConfigIfStale;
+    /** Keeps the push connection open exactly while the user is inside a geofence. */
+    private syncRealtime;
+    private persistGeofenceState;
+    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;
+}
+
+type ExperienceContent = ExperienceDeliveryPayload["experience"];
+declare function CardExperience({ content }: {
+    content: ExperienceContent;
+}): React.JSX.Element;
+declare function BannerExperience({ content }: {
+    content: ExperienceContent;
+}): React.JSX.Element;
+/**
+ * The popup type. This component only draws the content, the same as the others; showing it over the
+ * screen is the host app's job (put it in a React Native `Modal`, see the README), because only the app
+ * knows what else is on screen. Use `isAlertExperience` to decide popup versus inline.
+ */
+declare function AlertExperience({ content }: {
+    content: ExperienceContent;
+}): React.JSX.Element;
+/** True for the one experience type meant to interrupt the user (a popup). Banner, card and message belong inline in a screen. */
+declare function isAlertExperience(payload: {
+    experience: {
+        type: string;
+    };
+}): boolean;
+declare function MessageExperience({ content }: {
+    content: ExperienceContent;
+}): React.JSX.Element;
+/** Picks the right renderer by `experience.type` — the one component most host apps need. */
+declare function ExperienceView({ experience }: {
+    experience: ExperienceContent;
+}): React.JSX.Element;
+
+/** `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;
+    (eventName: "experience.removed", callback: (payload: RevokedExperience) => 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 { AlertExperience, ApplicationMismatchError, BannerExperience, CardExperience, type ConfigurationStatus, DeviceLocationProvider, type DiagnosticsSnapshot, type ExperienceDeliveryPayload, ExperienceView, ExpoPermissionProvider, GeoPulse, type GeoPulseConfig, GeoPulseSdk, type GeofenceEventType, type LocationEventPayload, type LocationProvider, type LocationUpdate, ManualNetworkMonitor, MessageExperience, NetInfoNetworkMonitor, type NetworkMonitor, type NetworkStatus, type PermissionProvider, type PermissionStatus, type RevokedExperience, type SdkGeofenceConfig, type SdkStatus, SimulatedLocationProvider, SimulatedPermissionProvider, isAlertExperience };