@sharib/geopulse-react-native 0.3.4 → 0.4.0

package/README.md

@@ -1,10 +1,10 @@
 # @sharib/geopulse-react-native
 
-> **🚧 Not live for public sign-up yet.** Thanks for installing this early! The admin portal
-> (where you create a project and get the `apiKey`/`applicationId` below) isn't open to public
-> sign-up yet, so `initialize()` will fail for most people right now. This isn't a bug on your
-> end, and there's nothing to fix. We're actively finishing this up, so check back soon. If you
-> need access now, reach out to the GeoPulse team directly.
+> **Beta.** GeoPulse and this SDK are in beta: the API may change before 1.0, and there is no
+> uptime guarantee yet. Questions, bugs and feature requests:
+> [GitHub issues](https://github.com/sharibkhan1/geofends/issues). The Terms of Service and
+> Privacy Policy are in the admin portal at `/terms` and `/privacy`; see also
+> [Privacy and store disclosures](#privacy-and-store-disclosures) below.
 
 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
@@ -12,12 +12,35 @@ built-in simulator), and reports `geofence.enter` / `geofence.exit` events to th
 backend, with a persistent, backoff-retried offline queue so a flaky connection never loses
 an event.
 
+## Requirements
+
+- **React Native ≥ 0.73 and React ≥ 18** (peer dependencies; developed and tested against React
+  Native 0.86 / React 19.2 only, so please report problems on older versions).
+- **Expo, or a bare React Native app with Expo modules.** Location comes from `expo-location`,
+  which needs the Expo modules runtime. In an Expo app (including Expo Go and development
+  builds) that is already there. In a bare React Native app, run `npx install-expo-modules`
+  first.
+- Native modules the SDK relies on: `expo-location`, `@react-native-async-storage/async-storage`
+  and `@react-native-community/netinfo`. They are dependencies of the SDK, so installing the SDK
+  installs them (see Installation). Rebuild your native app after adding the SDK.
+- Location permission (foreground only) declared in your app config. See [Permissions](#permissions).
+- A GeoPulse account: create a project and an application in the admin portal to get your
+  `apiKey` and `applicationId`.
+
 ## Installation
 
 ```bash
 npm install @sharib/geopulse-react-native
 ```
 
+That is the only install command: the SDK brings the packages it needs. Two cases need one extra step:
+
+- If `npx expo-doctor` says one of those packages is not the version your Expo SDK expects (npm installs
+  the newest allowed version when your app has none yet), run `npx expo install --fix`.
+- In a bare React Native app without Expo, run `npx install-expo-modules` first. React Native's own
+  autolinking only links packages your app lists itself, so if a native module is reported as missing, add
+  it with `npx expo install <package>`.
+
 ## Initialization
 
 Get `apiKey` and `applicationId` from the admin portal's `/sdk` page (the application created
@@ -34,8 +57,8 @@ await GeoPulse.initialize({
 ```
 
 `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,
+(`getProjectConfig`). This is the "SDK receives project configuration" step. It throws if
+`apiKey` or `applicationId` is 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
@@ -71,17 +94,44 @@ associated Experience (a banner/card/message):
 
 ```ts
 GeoPulse.on("experience.received", (payload) => {
-  // payload: ExperienceDeliveryPayload: { deliveryId, campaignId, experience: {...}, event: {...} }
+  // payload: ExperienceDeliveryPayload: { deliveryId, campaignId, revision, isUpdate, experience: {...}, event: {...} }
   showBanner(payload.experience);
 });
+
+GeoPulse.on("experience.removed", ({ deliveryId, campaignId }) => {
+  hideBanner(deliveryId);
+});
 ```
 
-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, so
-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.
+- `isUpdate` is `true` when an admin edited an experience the user was already shown: show the new
+  content in place of the old (use `deliveryId` to find it).
+- `experience.removed` fires when an admin deleted or disabled the campaign while the user is still
+  inside the location: remove what you showed.
+
+No push notifications are involved. The SDK fetches its own device's pending experiences over the
+connection it already uses for config/ingestion: once on `start()`, right after an event the backend
+says created one, and on a slow fallback timer (`GeoPulseConfig.experiencePollIntervalMs`, default 15
+minutes). While the user is **inside a geofence with the app open**, the SDK also keeps one WebSocket
+open so the server can tell it the moment an admin changes something that affects them; it closes when
+they leave. Idle devices send no repeated requests. The SDK acknowledges each experience
+automatically, so you never need to call anything to mark it "seen", and it never re-fires the same
+`deliveryId` and `revision` twice. There's no `getActiveExperiences()`: the two events above are the
+whole surface: the SDK transports and notifies, your app owns the UI. How long each kind of admin
+change takes to arrive is in the portal's Setup Guide ("Why changes take a moment").
+
+## How often the SDK talks to the server
+
+It only sends an event when the user **enters or leaves** a geofence, never while they stand still.
+To keep call volume (and your bill) low, the SDK holds itself back:
+
+- one event per geofence per 2 minutes, at most 3 uploads a minute, whatever the user does;
+- leaving only counts once the user is clearly outside (about 20 m past the edge, or more if the GPS fix
+  is less accurate); GPS fixes worse than 100 m are ignored;
+- the state is saved, so reopening the app while still inside does not report a second "enter";
+- when the server answers "too many requests" the SDK waits as long as it is told; a request the
+  server will never accept (for example a deleted geofence) is dropped instead of retried forever;
+- the offline queue holds at most 100 events and drops anything older than 24 hours;
+- the geofence list is re-read about once an hour while the app is open, and on every launch.
 
 ## Status / diagnostics
 
@@ -112,7 +162,10 @@ 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
+update would. The one difference: while the simulator is running, the 2-minute per-geofence cooldown is off and
+the saved "inside" state is not kept across reloads, so you can enter and exit as quickly as you like and
+an "enter" fires again after a reload. (The backend still applies its own limits, for example a webhook rule
+fires at most once per 2 minutes for the same device and geofence.) 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
@@ -134,6 +187,21 @@ const sdk = new GeoPulseSdk({
 
 This SDK requests **foreground location only**, never background location. Concretely:
 
+Minimal Expo `app.json` that covers both platforms:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      ["expo-location", { "locationWhenInUsePermission": "This app uses your location to detect nearby places." }]
+    ],
+    "android": { "permissions": ["ACCESS_COARSE_LOCATION", "ACCESS_FINE_LOCATION"] }
+  }
+}
+```
+
+Use your own wording for the permission text: it is what your users see, and the stores review it.
+
 - **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
@@ -151,6 +219,33 @@ This SDK requests **foreground location only**, never background location. Concr
   filter and a 5s minimum interval. That's a reasonable foreground default, not tuned for
   high-precision or high-frequency tracking.
 
+## Privacy and store disclosures
+
+Your app sends its end users' location data to GeoPulse, so **you** must disclose that to them and
+to the app stores. What the SDK sends:
+
+- **When:** only when a user enters or exits one of your geofences, while the app is in the
+  foreground. Continuous location is processed on the device and is not uploaded.
+- **What:** the user's precise coordinates and a timestamp at that moment, the geofence and
+  location ids, your application id, a random device id the SDK generates and stores on the
+  device (not an advertising id), the platform (`ios`/`android`) and the SDK version.
+- **Where it goes:** your GeoPulse project. It is visible to the members of your organization in
+  the portal and is forwarded to any webhook endpoints you configure.
+
+What that means for you:
+
+- Your **privacy policy** must say you collect precise location and a device identifier, why, and
+  who processes it (GeoPulse acts as your service provider).
+- **Apple App Privacy ("nutrition label"):** declare *Precise Location* and *Device ID*, collected
+  for app functionality and/or analytics, according to how you use them.
+- **Google Play Data safety form:** declare *Approximate and Precise location* and *Device or other
+  IDs* as collected, with the purposes that apply to your app.
+- Show a clear, honest permission prompt text (see [Permissions](#permissions)), and ask for
+  consent where the law of your users' region requires it.
+
+This section is guidance, not legal advice: the store forms are your responsibility, so check
+them against how your app really behaves.
+
 ## Troubleshooting
 
 - **`initialize()` rejects with a fetch/network error**: check `functionsBaseUrl` is reachable

package/dist/index.d.ts

@@ -90,6 +90,10 @@ 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;
@@ -108,6 +112,16 @@ interface ExperienceDeliveryPayload {
         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;
@@ -120,7 +134,11 @@ interface GeoPulseConfig {
     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. */
+    /**
+     * 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;
@@ -142,6 +160,12 @@ interface DeviceIdentity {
     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
@@ -166,20 +190,77 @@ declare class ApiClient {
      * since GET requests carry no body.
      */
     getProjectConfig(identity: DeviceIdentity): Promise<SdkProjectConfig>;
-    ingestEvent(payload: LocationEventPayload): Promise<{
-        id: string;
-        deduplicated: boolean;
-    }>;
+    ingestEvent(payload: LocationEventPayload): Promise<IngestResult>;
     /** Polled by GeoPulseSdk's experience-polling loop — see core/geo-pulse-sdk.ts. */
-    getPendingExperiences(deviceId: string): Promise<ExperienceDeliveryPayload[]>;
+    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
@@ -254,20 +335,29 @@ interface EventQueueStore {
  * 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(). */
+    /** 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>;
-    markAttemptFailed(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";
@@ -328,7 +418,7 @@ interface DiagnosticsSnapshot {
 
 type EventListener = (event: LocationEventPayload) => void;
 type ExperienceListener = (payload: ExperienceDeliveryPayload) => void;
-/** Mirrors SyncManager's own default retry interval — see sync/sync-manager.ts's DEFAULT_RETRY_INTERVAL_MS. A host app that wants faster demo feedback (see apps/playground) can override via GeoPulseConfig.experiencePollIntervalMs. */
+type ExperienceRemovedListener = (payload: RevokedExperience) => void;
 /** The SDK key resolved to a different application than `config.applicationId`. */
 declare class ApplicationMismatchError extends Error {
     constructor();
@@ -351,6 +441,15 @@ interface GeoPulseSdkDependencies {
     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;
@@ -369,11 +468,24 @@ declare class GeoPulseSdk {
     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 seenExperienceDeliveryIds;
+    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;
@@ -399,8 +511,10 @@ declare class GeoPulseSdk {
     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;
@@ -433,7 +547,25 @@ declare class GeoPulseSdk {
      */
     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;
 }
@@ -527,6 +659,7 @@ declare function ExperienceView({ experience }: {
 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>;
@@ -552,4 +685,4 @@ declare const GeoPulse: {
     };
 };
 
-export { 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 SdkGeofenceConfig, type SdkStatus, SimulatedLocationProvider, SimulatedPermissionProvider };
+export { 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 };