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

package/README.md

@@ -1,3 +1,329 @@
-# Temporary Holding Version
+# @damn-coding/geopulse-react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **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
+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.
+
+## 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 @damn-coding/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
+automatically for you during onboarding is named "Playground"). The SDK connects to the hosted
+GeoPulse backend automatically, with nothing else to configure:
+
+```ts
+import { GeoPulse } from "@damn-coding/geopulse-react-native";
+
+await GeoPulse.initialize({
+  apiKey: "gp_test_xxx",
+  applicationId: "app_xxx",
+});
+```
+
+`initialize()` fetches the application's currently active geofences from the backend
+(`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
+
+```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, revision, isUpdate, experience: {...}, event: {...} }
+  showBanner(payload.experience);
+});
+
+GeoPulse.on("experience.removed", ({ deliveryId, campaignId }) => {
+  hideBanner(deliveryId);
+});
+```
+
+### Experience types, and more than one at once
+
+An experience has a `type`: `alert`, `banner`, `card` or `message`.
+
+- **`alert`** is the popup: show it over whatever the user is doing (a React Native `Modal`).
+- **`banner`**, **`card`** and **`message`** belong inline in one of your own screens. Do not pop them up.
+
+`ExperienceView` draws any of them; `isAlertExperience(payload)` tells you which way to show it. Several
+campaigns can match the same place (an admin can add up to 5 per geofence), and each one arrives as its own
+`experience.received`, so keep a list, replace an entry that has the same `deliveryId` (that is an update),
+and remove it on `experience.removed`:
+
+```tsx
+import { ExperienceView, isAlertExperience } from "@damn-coding/geopulse-react-native";
+
+const [inline, setInline] = useState<ExperienceDeliveryPayload[]>([]);
+const [alerts, setAlerts] = useState<ExperienceDeliveryPayload[]>([]); // shown one at a time
+
+useEffect(() => {
+  const upsert = (list: ExperienceDeliveryPayload[], p: ExperienceDeliveryPayload) => [...list.filter((x) => x.deliveryId !== p.deliveryId), p];
+  const onReceived = (p: ExperienceDeliveryPayload) =>
+    isAlertExperience(p) ? setAlerts((l) => upsert(l, p)) : setInline((l) => upsert(l, p));
+  const onRemoved = ({ deliveryId }: { deliveryId: string }) => {
+    setAlerts((l) => l.filter((x) => x.deliveryId !== deliveryId));
+    setInline((l) => l.filter((x) => x.deliveryId !== deliveryId));
+  };
+  GeoPulse.on("experience.received", onReceived);
+  GeoPulse.on("experience.removed", onRemoved);
+  return () => {
+    GeoPulse.off("experience.received", onReceived);
+    GeoPulse.off("experience.removed", onRemoved);
+  };
+}, []);
+
+// inline.map((p) => <ExperienceView key={p.deliveryId} experience={p.experience} />) inside your screen,
+// and <Modal visible={alerts.length > 0}> showing <ExperienceView experience={alerts[0].experience} /> with a Dismiss button.
+```
+
+- `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
+
+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 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
+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 "@damn-coding/geopulse-react-native";
+
+const sdk = new GeoPulseSdk({
+  locationProvider: new DeviceLocationProvider(),
+  permissionProvider: new ExpoPermissionProvider(),
+});
+```
+
+## Permissions
+
+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
+  requested, so 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. 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
+  from the device (an emulator URL like `127.0.0.1` is not reachable from a physical device or
+  even always from a simulator, so 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).