@sharib/geopulse-react-native 0.1.1

package/dist/index.js

@@ -0,0 +1,1036 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DeviceLocationProvider: () => DeviceLocationProvider,
+  ExpoPermissionProvider: () => ExpoPermissionProvider,
+  GeoPulse: () => GeoPulse,
+  GeoPulseSdk: () => GeoPulseSdk,
+  ManualNetworkMonitor: () => ManualNetworkMonitor,
+  NetInfoNetworkMonitor: () => NetInfoNetworkMonitor,
+  SimulatedLocationProvider: () => SimulatedLocationProvider,
+  SimulatedPermissionProvider: () => SimulatedPermissionProvider
+});
+module.exports = __toCommonJS(index_exports);
+var import_react_native = require("react-native");
+
+// src/config/async-storage-key-value-store.ts
+var import_async_storage = __toESM(require("@react-native-async-storage/async-storage"));
+var AsyncStorageKeyValueStore = class {
+  async getItem(key) {
+    return import_async_storage.default.getItem(key);
+  }
+  async setItem(key, value) {
+    await import_async_storage.default.setItem(key, value);
+  }
+};
+
+// src/config/types.ts
+var SDK_VERSION = "0.3.0";
+
+// src/config/key-value-store.ts
+var InMemoryKeyValueStore = class {
+  data = /* @__PURE__ */ new Map();
+  async getItem(key) {
+    return this.data.get(key) ?? null;
+  }
+  async setItem(key, value) {
+    this.data.set(key, value);
+  }
+};
+
+// src/events/uuid.ts
+function generateEventId() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+    const random = Math.random() * 16 | 0;
+    const value = char === "x" ? random : random & 3 | 8;
+    return value.toString(16);
+  });
+}
+
+// src/config/device-id.ts
+var DEVICE_ID_STORAGE_KEY = "@geopulse/device-id";
+async function getOrCreateDeviceId(store) {
+  const existing = await store.getItem(DEVICE_ID_STORAGE_KEY);
+  if (existing) {
+    return existing;
+  }
+  const deviceId = generateEventId();
+  await store.setItem(DEVICE_ID_STORAGE_KEY, deviceId);
+  return deviceId;
+}
+
+// src/config/config-cache.ts
+var CONFIG_CACHE_STORAGE_KEY = "@geopulse/config-cache";
+var ConfigCache = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  async save(config) {
+    const cached = { config, fetchedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    await this.store.setItem(CONFIG_CACHE_STORAGE_KEY, JSON.stringify(cached));
+  }
+  async load() {
+    const raw = await this.store.getItem(CONFIG_CACHE_STORAGE_KEY);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/protocol.ts
+var SDK_KEY_HEADER = "x-geopulse-sdk-key";
+var SDK_ENDPOINTS = {
+  GET_PROJECT_CONFIG: "getProjectConfig",
+  INGEST_LOCATION_EVENT: "ingestLocationEvent",
+  GET_PENDING_EXPERIENCES: "getPendingExperiences",
+  ACKNOWLEDGE_EXPERIENCE_DELIVERY: "acknowledgeExperienceDelivery"
+};
+var EARTH_RADIUS_METERS = 6371e3;
+function toRadians(degrees) {
+  return degrees * Math.PI / 180;
+}
+function calculateDistanceMeters(from, to) {
+  const lat1 = toRadians(from.latitude);
+  const lat2 = toRadians(to.latitude);
+  const deltaLat = toRadians(to.latitude - from.latitude);
+  const deltaLng = toRadians(to.longitude - from.longitude);
+  const a = Math.sin(deltaLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(deltaLng / 2) ** 2;
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+  return EARTH_RADIUS_METERS * c;
+}
+
+// src/firebase/api-client.ts
+var REQUEST_TIMEOUT_MS = 15e3;
+async function fetchWithTimeout(url, init) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function fetchOrThrow(callName, url, init) {
+  try {
+    return await fetchWithTimeout(url, init);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${callName} request failed: ${message}`);
+  }
+}
+var ApiClient = class {
+  constructor(baseUrl, sdkKey) {
+    this.baseUrl = baseUrl;
+    this.sdkKey = sdkKey;
+  }
+  baseUrl;
+  sdkKey;
+  /**
+   * `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.
+   */
+  async getProjectConfig(identity) {
+    const query = new URLSearchParams({
+      deviceId: identity.deviceId,
+      platform: identity.platform,
+      sdkVersion: identity.sdkVersion
+    });
+    const response = await fetchOrThrow("getProjectConfig", `${this.baseUrl}/${SDK_ENDPOINTS.GET_PROJECT_CONFIG}?${query.toString()}`, {
+      method: "GET",
+      headers: { [SDK_KEY_HEADER]: this.sdkKey }
+    });
+    if (!response.ok) {
+      throw new Error(`getProjectConfig failed with status ${response.status}`);
+    }
+    return await response.json();
+  }
+  async ingestEvent(payload) {
+    const response = await fetchOrThrow("ingestLocationEvent", `${this.baseUrl}/${SDK_ENDPOINTS.INGEST_LOCATION_EVENT}`, {
+      method: "POST",
+      headers: { [SDK_KEY_HEADER]: this.sdkKey, "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      throw new Error(`ingestLocationEvent failed with status ${response.status}`);
+    }
+    return await response.json();
+  }
+  /** Polled by GeoPulseSdk's experience-polling loop — see core/geo-pulse-sdk.ts. */
+  async getPendingExperiences(deviceId) {
+    const query = new URLSearchParams({ deviceId });
+    const response = await fetchOrThrow("getPendingExperiences", `${this.baseUrl}/${SDK_ENDPOINTS.GET_PENDING_EXPERIENCES}?${query.toString()}`, {
+      method: "GET",
+      headers: { [SDK_KEY_HEADER]: this.sdkKey }
+    });
+    if (!response.ok) {
+      throw new Error(`getPendingExperiences failed with status ${response.status}`);
+    }
+    const body = await response.json();
+    return body.experiences;
+  }
+  /** Confirms a delivery was surfaced via `experience.received`, so it stops appearing in future polls. */
+  async acknowledgeExperienceDelivery(deliveryId) {
+    const response = await fetchOrThrow("acknowledgeExperienceDelivery", `${this.baseUrl}/${SDK_ENDPOINTS.ACKNOWLEDGE_EXPERIENCE_DELIVERY}`, {
+      method: "POST",
+      headers: { [SDK_KEY_HEADER]: this.sdkKey, "Content-Type": "application/json" },
+      body: JSON.stringify({ deliveryId })
+    });
+    if (!response.ok) {
+      throw new Error(`acknowledgeExperienceDelivery failed with status ${response.status}`);
+    }
+  }
+};
+
+// src/events/factory.ts
+function createEventPayload(params) {
+  return {
+    id: generateEventId(),
+    type: params.type,
+    projectId: params.projectId,
+    applicationId: params.applicationId,
+    geofenceId: params.geofence.id,
+    locationId: params.geofence.locationId,
+    deviceId: params.deviceId,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    latitude: params.location.latitude,
+    longitude: params.location.longitude,
+    metadata: params.metadata ?? {},
+    sdkVersion: SDK_VERSION,
+    // First-try attempt count; SyncManager overwrites this with the real
+    // count if the event ends up going through the retry queue (see
+    // sync/sync-manager.ts#retryPending) — that's what makes the
+    // "Attempts" column in the admin's Event Explorer meaningful.
+    attempts: 1
+  };
+}
+
+// src/geofencing/state-machine.ts
+var GeofenceStateMachine = class {
+  membershipByGeofenceId = /* @__PURE__ */ new Map();
+  evaluate(location, geofences) {
+    const transitions = [];
+    const activeIds = /* @__PURE__ */ new Set();
+    for (const geofence of geofences) {
+      activeIds.add(geofence.id);
+      const distance = calculateDistanceMeters(location, geofence.center);
+      const nextMembership = distance <= geofence.radiusMeters ? "INSIDE" : "OUTSIDE";
+      const previousMembership = this.membershipByGeofenceId.get(geofence.id) ?? "OUTSIDE";
+      if (previousMembership !== nextMembership) {
+        transitions.push({
+          geofence,
+          type: nextMembership === "INSIDE" ? "geofence.enter" : "geofence.exit"
+        });
+      }
+      this.membershipByGeofenceId.set(geofence.id, nextMembership);
+    }
+    for (const id of this.membershipByGeofenceId.keys()) {
+      if (!activeIds.has(id)) {
+        this.membershipByGeofenceId.delete(id);
+      }
+    }
+    return transitions;
+  }
+  getMembership(geofenceId) {
+    return this.membershipByGeofenceId.get(geofenceId) ?? "OUTSIDE";
+  }
+  reset() {
+    this.membershipByGeofenceId.clear();
+  }
+};
+
+// src/location/simulated-location-provider.ts
+var SimulatedLocationProvider = class {
+  onUpdate = null;
+  currentLocation = null;
+  start(onUpdate) {
+    this.onUpdate = onUpdate;
+    if (this.currentLocation) {
+      onUpdate(this.currentLocation);
+    }
+  }
+  stop() {
+    this.onUpdate = null;
+  }
+  setLocation(coords) {
+    const location = { ...coords, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+    this.currentLocation = location;
+    this.onUpdate?.(location);
+  }
+  getCurrentLocation() {
+    return this.currentLocation;
+  }
+};
+
+// src/permissions/simulated-permission-provider.ts
+var SimulatedPermissionProvider = class {
+  async getStatus() {
+    return "granted";
+  }
+  async request() {
+    return "granted";
+  }
+};
+
+// src/sync/retry-policy.ts
+var RETRY_POLICY = {
+  /** Attempts beyond this stop increasing the delay — it plateaus at MAX_RETRY_DELAY_MS, but retrying never stops entirely (the SDK must never give up on an event; see storage/queue.ts). */
+  MAX_RETRIES: 6,
+  BASE_RETRY_DELAY_MS: 5e3,
+  MAX_RETRY_DELAY_MS: 5 * 6e4
+};
+function computeRetryDelayMs(attempts) {
+  const cappedAttempts = Math.min(attempts, RETRY_POLICY.MAX_RETRIES);
+  const exponential = RETRY_POLICY.BASE_RETRY_DELAY_MS * 2 ** Math.max(0, cappedAttempts - 1);
+  const delay = Math.min(exponential, RETRY_POLICY.MAX_RETRY_DELAY_MS);
+  const jitter = delay * 0.2 * (Math.random() * 2 - 1);
+  return Math.round(delay + jitter);
+}
+
+// src/storage/memory-store.ts
+var InMemoryEventQueueStore = class {
+  eventsById = /* @__PURE__ */ new Map();
+  async getAll() {
+    return [...this.eventsById.values()];
+  }
+  async save(event) {
+    this.eventsById.set(event.eventId, event);
+  }
+  async remove(eventId) {
+    this.eventsById.delete(eventId);
+  }
+};
+
+// src/storage/queue.ts
+var PendingEventQueue = class {
+  constructor(store = new InMemoryEventQueueStore()) {
+    this.store = store;
+  }
+  store;
+  async enqueue(payload) {
+    await this.store.save({
+      eventId: payload.id,
+      type: payload.type,
+      applicationId: payload.applicationId,
+      deviceId: payload.deviceId,
+      locationId: payload.locationId,
+      geofenceId: payload.geofenceId,
+      timestamp: payload.timestamp,
+      payload,
+      attempts: 0,
+      status: "pending",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      lastAttemptAt: null,
+      nextAttemptAt: null
+    });
+  }
+  /** Every queued event, regardless of retry timing — used for diagnostics/pending counts. */
+  async listPending() {
+    return this.store.getAll();
+  }
+  /** Only events whose backoff window has elapsed (or that have never been attempted) — used by SyncManager.retryPending(). */
+  async listReadyForRetry(now = /* @__PURE__ */ new Date()) {
+    const all = await this.store.getAll();
+    return all.filter(
+      (event) => event.status !== "sending" && (!event.nextAttemptAt || new Date(event.nextAttemptAt) <= now)
+    );
+  }
+  /** Marks an event as in-flight so a concurrent retry pass won't also pick it up. */
+  async markSending(eventId) {
+    const existing = await this.get(eventId);
+    if (!existing) return;
+    await this.store.save({ ...existing, status: "sending" });
+  }
+  async markAttemptFailed(eventId) {
+    const existing = await this.get(eventId);
+    if (!existing) return;
+    const attempts = existing.attempts + 1;
+    const now = /* @__PURE__ */ new Date();
+    await this.store.save({
+      ...existing,
+      status: "failed",
+      attempts,
+      lastAttemptAt: now.toISOString(),
+      nextAttemptAt: new Date(now.getTime() + computeRetryDelayMs(attempts)).toISOString()
+    });
+  }
+  async markSent(eventId) {
+    await this.store.remove(eventId);
+  }
+  async get(eventId) {
+    return (await this.store.getAll()).find((event) => event.eventId === eventId);
+  }
+};
+
+// src/sync/network-monitor.ts
+var ManualNetworkMonitor = class {
+  status = "online";
+  listeners = /* @__PURE__ */ new Set();
+  getStatus() {
+    return this.status;
+  }
+  setStatus(status) {
+    if (status === this.status) return;
+    this.status = status;
+    this.listeners.forEach((listener) => listener(status));
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+};
+
+// src/sync/sync-manager.ts
+var DEFAULT_RETRY_INTERVAL_MS = 3e4;
+var SyncManager = class {
+  constructor(apiClient, queue, retryIntervalMs = DEFAULT_RETRY_INTERVAL_MS, logger) {
+    this.apiClient = apiClient;
+    this.queue = queue;
+    this.retryIntervalMs = retryIntervalMs;
+    this.logger = logger;
+  }
+  apiClient;
+  queue;
+  retryIntervalMs;
+  logger;
+  retryTimer = null;
+  lastSyncAt = null;
+  lastUploadResult = null;
+  /**
+   * Write-ahead: the event is durably queued *before* any network attempt is
+   * made, so an app kill mid-request can never lose it (spec: "true
+   * write-ahead event persistence" — a prior version of this method tried
+   * the network first and only queued on failure, which meant an event in
+   * flight when the process died was gone for good). `attemptDelivery` then
+   * runs the exact same success/failure bookkeeping a queued retry uses, so
+   * there is only one code path for "what happens when an upload settles."
+   */
+  async sendOrQueue(payload) {
+    await this.queue.enqueue(payload);
+    await this.attemptDelivery(payload.id, payload);
+  }
+  /**
+   * Attempts queued events. By default only ones whose backoff window has
+   * elapsed (the timer-driven path, `startAutoRetry` — the whole point of
+   * backoff is to not hammer the backend on a fixed sweep). Pass
+   * `{ force: true }` to ignore that window and attempt every non-in-flight
+   * queued event regardless — connectivity just being confirmed restored
+   * (see `GeoPulseSdk.start`'s network-monitor subscription) is a stronger
+   * signal than "some fixed delay has passed," and a device that was
+   * offline for a while shouldn't have to wait out a stale backoff timer
+   * once it's actually back online.
+   */
+  async retryPending(options = {}) {
+    const ready = options.force ? (await this.queue.listPending()).filter((event) => event.status !== "sending") : await this.queue.listReadyForRetry();
+    const result = { attempted: ready.length, delivered: 0, failed: 0 };
+    for (const event of ready) {
+      const attemptNumber = event.attempts + 1;
+      const delivered = await this.attemptDelivery(event.eventId, { ...event.payload, attempts: attemptNumber });
+      if (delivered) {
+        result.delivered++;
+      } else {
+        result.failed++;
+      }
+    }
+    return result;
+  }
+  /**
+   * The single place that actually talks to the backend: marks the queued
+   * record "sending" (so a concurrent retry pass skips it), attempts the
+   * upload, and resolves it to either removed-from-queue (success — a
+   * `deduplicated: true` response still counts, since it means the backend
+   * already has this event id, which is exactly the outcome a retry is
+   * supposed to produce) or a scheduled retry (failure). Returns whether it
+   * was delivered, purely so `retryPending` can tally its `SyncResult`.
+   */
+  async attemptDelivery(eventId, payload) {
+    await this.queue.markSending(eventId);
+    this.logger?.log("Event upload started", { eventId, attempt: payload.attempts });
+    try {
+      await this.apiClient.ingestEvent(payload);
+      await this.queue.markSent(eventId);
+      this.lastSyncAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.lastUploadResult = "success";
+      this.logger?.log("Event upload succeeded", { eventId });
+      return true;
+    } catch (error) {
+      await this.queue.markAttemptFailed(eventId);
+      this.lastUploadResult = "failure";
+      this.logger?.warn("Event upload failed \u2014 retry scheduled", { eventId, error: String(error) });
+      return false;
+    }
+  }
+  startAutoRetry() {
+    if (this.retryTimer) return;
+    this.retryTimer = setInterval(() => {
+      void this.retryPending();
+    }, this.retryIntervalMs);
+  }
+  stopAutoRetry() {
+    if (this.retryTimer) {
+      clearInterval(this.retryTimer);
+      this.retryTimer = null;
+    }
+  }
+  getLastSyncAt() {
+    return this.lastSyncAt;
+  }
+  getLastUploadResult() {
+    return this.lastUploadResult;
+  }
+};
+
+// src/core/logger.ts
+var Logger = class {
+  constructor(enabled) {
+    this.enabled = enabled;
+  }
+  enabled;
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  log(message, details) {
+    if (!this.enabled) return;
+    if (details) {
+      console.log(`[GeoPulse] ${message}`, details);
+    } else {
+      console.log(`[GeoPulse] ${message}`);
+    }
+  }
+  warn(message, details) {
+    if (!this.enabled) return;
+    if (details) {
+      console.warn(`[GeoPulse] ${message}`, details);
+    } else {
+      console.warn(`[GeoPulse] ${message}`);
+    }
+  }
+};
+
+// src/core/geo-pulse-sdk.ts
+var DEFAULT_EXPERIENCE_POLL_INTERVAL_MS = 3e4;
+var MIN_TIMER_INTERVAL_MS = 1e3;
+function clampIntervalMs(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Number.isFinite(value) || value < MIN_TIMER_INTERVAL_MS) {
+    return MIN_TIMER_INTERVAL_MS;
+  }
+  return value;
+}
+var GeoPulseSdk = class {
+  status = "idle";
+  config = null;
+  apiClient = null;
+  syncManager = null;
+  resolvedProjectId = null;
+  resolvedApplicationId = null;
+  applicationEnabled = true;
+  configVersion = null;
+  configurationStatus = "unsynced";
+  geofences = [];
+  lastKnownLocation = null;
+  lastEvent = null;
+  deviceId = null;
+  locationError = null;
+  unsubscribeNetwork = null;
+  stateMachine = new GeofenceStateMachine();
+  listeners = /* @__PURE__ */ new Map();
+  experienceListeners = /* @__PURE__ */ new Set();
+  /** 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. */
+  seenExperienceDeliveryIds = /* @__PURE__ */ new Set();
+  experiencePollTimer = null;
+  experiencesReceivedCount = 0;
+  logger;
+  locationProvider;
+  permissionProvider;
+  queue;
+  buildApiClient;
+  deviceIdStore;
+  configCache;
+  networkMonitor;
+  getPlatform;
+  experiencePollIntervalMs = DEFAULT_EXPERIENCE_POLL_INTERVAL_MS;
+  constructor(dependencies = {}) {
+    this.locationProvider = dependencies.locationProvider ?? new SimulatedLocationProvider();
+    this.permissionProvider = dependencies.permissionProvider ?? new SimulatedPermissionProvider();
+    this.queue = dependencies.queue ?? new PendingEventQueue();
+    this.buildApiClient = dependencies.createApiClient ?? ((config) => new ApiClient(config.functionsBaseUrl ?? "", config.apiKey));
+    this.deviceIdStore = dependencies.deviceIdStore ?? new InMemoryKeyValueStore();
+    this.configCache = new ConfigCache(dependencies.configCacheStore ?? new InMemoryKeyValueStore());
+    this.networkMonitor = dependencies.networkMonitor ?? new ManualNetworkMonitor();
+    this.getPlatform = dependencies.getPlatform ?? (() => "unknown");
+    this.logger = new Logger(dependencies.debug ?? false);
+  }
+  /**
+   * 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".
+   */
+  async initialize(config) {
+    if (this.status === "running") {
+      throw new Error("GeoPulse.initialize() cannot be called while already running \u2014 call GeoPulse.stop() first");
+    }
+    if (this.status === "initializing") {
+      throw new Error("GeoPulse.initialize() is already in progress \u2014 wait for the first call to resolve");
+    }
+    if (!config.apiKey || !config.applicationId) {
+      throw new Error("GeoPulse.initialize requires both apiKey and applicationId");
+    }
+    if (!config.functionsBaseUrl) {
+      throw new Error(
+        "GeoPulse.initialize requires functionsBaseUrl (the deployed Cloud Functions base URL, or the local emulator's URL in development)"
+      );
+    }
+    if (config.debug !== void 0) {
+      this.logger.setEnabled(config.debug);
+    }
+    this.logger.log("GeoPulse.initialize()", { applicationId: config.applicationId });
+    this.status = "initializing";
+    this.config = config;
+    this.experiencePollIntervalMs = clampIntervalMs(config.experiencePollIntervalMs) ?? DEFAULT_EXPERIENCE_POLL_INTERVAL_MS;
+    this.apiClient = this.buildApiClient(config);
+    this.syncManager = new SyncManager(this.apiClient, this.queue, clampIntervalMs(config.retryIntervalMs), this.logger);
+    this.deviceId = await getOrCreateDeviceId(this.deviceIdStore);
+    try {
+      const projectConfig = await this.apiClient.getProjectConfig({
+        deviceId: this.deviceId,
+        platform: this.getPlatform(),
+        sdkVersion: SDK_VERSION
+      });
+      this.applyProjectConfig(projectConfig);
+      this.configurationStatus = "synced";
+      await this.configCache.save(projectConfig);
+      this.status = "initialized";
+      this.logger.log("Configuration synced", { geofenceCount: projectConfig.geofences.length, configVersion: projectConfig.configVersion });
+    } catch (error) {
+      const cached = await this.configCache.load();
+      if (cached) {
+        this.applyProjectConfig(cached.config);
+        this.configurationStatus = "cached";
+        this.status = "initialized";
+        this.logger.warn("getProjectConfig failed \u2014 using cached configuration", { fetchedAt: cached.fetchedAt });
+        return;
+      }
+      this.configurationStatus = "unavailable";
+      this.status = "error";
+      throw error;
+    }
+  }
+  async start() {
+    if (this.status === "running") {
+      throw new Error("GeoPulse.start() called while already running \u2014 call GeoPulse.stop() first if you want to restart");
+    }
+    if (this.status !== "initialized" && this.status !== "stopped") {
+      throw new Error("GeoPulse.start called before GeoPulse.initialize succeeded");
+    }
+    if (!this.applicationEnabled) {
+      this.status = "error";
+      throw new Error("This application has been disabled in the GeoPulse admin portal");
+    }
+    const permission = await this.permissionProvider.request();
+    if (permission !== "granted") {
+      this.status = "error";
+      throw new Error(`Location permission not granted (status: ${permission})`);
+    }
+    this.locationError = null;
+    await this.locationProvider.start(
+      (location) => {
+        void this.handleLocationUpdate(location);
+      },
+      (error) => {
+        this.locationError = error.message;
+        this.logger.warn("Location provider failed to start", { error: error.message });
+      }
+    );
+    if (this.locationError) {
+      this.status = "error";
+      throw new Error(`GeoPulse failed to start location tracking: ${this.locationError}`);
+    }
+    this.unsubscribeNetwork = this.networkMonitor.subscribe((networkStatus) => {
+      if (networkStatus === "online") {
+        this.logger.log("Network available \u2014 retrying queued events");
+        void this.syncManager?.retryPending({ force: true });
+      }
+    });
+    this.syncManager?.startAutoRetry();
+    this.startExperiencePolling();
+    this.status = "running";
+    this.logger.log("GeoPulse.start()");
+  }
+  stop() {
+    this.locationProvider.stop();
+    this.syncManager?.stopAutoRetry();
+    this.stopExperiencePolling();
+    this.unsubscribeNetwork?.();
+    this.unsubscribeNetwork = null;
+    this.status = "stopped";
+    this.logger.log("GeoPulse.stop()");
+  }
+  getStatus() {
+    return this.status;
+  }
+  async getPermissionStatus() {
+    return this.permissionProvider.getStatus();
+  }
+  on(eventName, callback) {
+    if (eventName === "experience.received") {
+      this.experienceListeners.add(callback);
+      return;
+    }
+    if (!this.listeners.has(eventName)) {
+      this.listeners.set(eventName, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(eventName)?.add(callback);
+  }
+  off(eventName, callback) {
+    if (eventName === "experience.received") {
+      this.experienceListeners.delete(callback);
+      return;
+    }
+    this.listeners.get(eventName)?.delete(callback);
+  }
+  // --- Small read-only accessors beyond the core 7-method API, so a host
+  // app (see apps/playground) can build a status UI around the SDK without
+  // it needing to duplicate state the SDK already tracks internally. ---
+  getConfiguredGeofences() {
+    return this.geofences;
+  }
+  /** The server-resolved application id (from `getProjectConfig`), or null before `initialize()` completes. */
+  getApplicationId() {
+    return this.resolvedApplicationId;
+  }
+  getLastKnownLocation() {
+    return this.lastKnownLocation;
+  }
+  async getPendingEventCount() {
+    return (await this.queue.listPending()).length;
+  }
+  /** Null until `initialize()` resolves it — persisted across app restarts (see config/device-id.ts). */
+  getDeviceId() {
+    return this.deviceId;
+  }
+  /**
+   * 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).
+   */
+  async getDiagnostics() {
+    const pending = await this.queue.listPending();
+    const permissionStatus = this.status === "idle" || this.status === "initializing" ? "unknown" : await this.permissionProvider.getStatus();
+    return {
+      initialized: this.status !== "idle" && this.status !== "initializing",
+      running: this.status === "running",
+      locationAvailable: this.lastKnownLocation !== null,
+      permissionStatus,
+      networkStatus: this.networkMonitor.getStatus(),
+      configurationStatus: this.configurationStatus,
+      configVersion: this.configVersion,
+      pendingEvents: pending.length,
+      totalRetryAttempts: pending.reduce((sum, event) => sum + event.attempts, 0),
+      locationError: this.locationError,
+      lastEventAt: this.lastEvent?.timestamp ?? null,
+      lastEventType: this.lastEvent?.type ?? null,
+      lastSyncAt: this.syncManager?.getLastSyncAt() ?? null,
+      lastUploadResult: this.syncManager?.getLastUploadResult() ?? null,
+      deviceId: this.deviceId,
+      sdkVersion: SDK_VERSION,
+      experiencesReceivedCount: this.experiencesReceivedCount
+    };
+  }
+  /**
+   * 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) {
+    const isDev2 = typeof __DEV__ === "undefined" ? true : __DEV__;
+    if (!isDev2) {
+      console.warn("GeoPulse.simulator is unavailable in production builds.");
+      return;
+    }
+    if (!(this.locationProvider instanceof SimulatedLocationProvider)) {
+      console.warn(
+        "GeoPulse.simulator.setLocation has no effect: the SDK is not running the simulated location provider."
+      );
+      return;
+    }
+    this.locationProvider.setLocation(coords);
+  }
+  /**
+   * 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.
+   */
+  startExperiencePolling() {
+    void this.pollForExperiences();
+    this.experiencePollTimer = setInterval(() => {
+      void this.pollForExperiences();
+    }, this.experiencePollIntervalMs);
+  }
+  stopExperiencePolling() {
+    if (this.experiencePollTimer) {
+      clearInterval(this.experiencePollTimer);
+      this.experiencePollTimer = null;
+    }
+  }
+  async pollForExperiences() {
+    if (!this.apiClient || !this.deviceId) {
+      return;
+    }
+    try {
+      const experiences = await this.apiClient.getPendingExperiences(this.deviceId);
+      for (const experience of experiences) {
+        if (this.seenExperienceDeliveryIds.has(experience.deliveryId)) {
+          continue;
+        }
+        this.seenExperienceDeliveryIds.add(experience.deliveryId);
+        this.experiencesReceivedCount += 1;
+        this.logger.log("Experience received", { deliveryId: experience.deliveryId, campaignId: experience.campaignId });
+        this.experienceListeners.forEach((listener) => listener(experience));
+        await this.apiClient.acknowledgeExperienceDelivery(experience.deliveryId).catch((error) => {
+          this.logger.warn("Failed to acknowledge experience delivery", {
+            deliveryId: experience.deliveryId,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        });
+      }
+    } catch (error) {
+      this.logger.warn("Polling for experiences failed", { error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  applyProjectConfig(projectConfig) {
+    this.resolvedProjectId = projectConfig.projectId;
+    this.resolvedApplicationId = projectConfig.applicationId;
+    this.applicationEnabled = projectConfig.applicationEnabled;
+    this.configVersion = projectConfig.configVersion;
+    this.geofences = projectConfig.geofences;
+  }
+  async handleLocationUpdate(location) {
+    this.lastKnownLocation = location;
+    if (!this.resolvedProjectId || !this.resolvedApplicationId || !this.syncManager || !this.deviceId) {
+      return;
+    }
+    const transitions = this.stateMachine.evaluate(location, this.geofences);
+    for (const transition of transitions) {
+      this.logger.log("Geofence state changed", { geofenceId: transition.geofence.id, type: transition.type });
+      const event = createEventPayload({
+        type: transition.type,
+        projectId: this.resolvedProjectId,
+        applicationId: this.resolvedApplicationId,
+        geofence: transition.geofence,
+        location,
+        deviceId: this.deviceId
+      });
+      this.lastEvent = event;
+      this.logger.log("Event generated", { eventId: event.id, type: event.type });
+      this.listeners.get(transition.type)?.forEach((listener) => listener(event));
+      await this.syncManager.sendOrQueue(event);
+    }
+  }
+};
+
+// src/location/device-location-provider.ts
+var Location = __toESM(require("expo-location"));
+var DeviceLocationProvider = class {
+  subscription = null;
+  /**
+   * `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.
+   */
+  async start(onUpdate, onError) {
+    try {
+      this.subscription = await Location.watchPositionAsync(
+        { accuracy: Location.Accuracy.Balanced, timeInterval: 5e3, distanceInterval: 10 },
+        (position) => {
+          onUpdate({
+            latitude: position.coords.latitude,
+            longitude: position.coords.longitude,
+            timestamp: new Date(position.timestamp).toISOString()
+          });
+        }
+      );
+    } catch (error) {
+      onError?.(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  stop() {
+    this.subscription?.remove();
+    this.subscription = null;
+  }
+};
+
+// src/permissions/expo-permission-provider.ts
+var Location2 = __toESM(require("expo-location"));
+function mapExpoStatus(status) {
+  switch (status) {
+    case Location2.PermissionStatus.GRANTED:
+      return "granted";
+    case Location2.PermissionStatus.DENIED:
+      return "denied";
+    default:
+      return "undetermined";
+  }
+}
+var ExpoPermissionProvider = class {
+  async getStatus() {
+    const { status } = await Location2.getForegroundPermissionsAsync();
+    return mapExpoStatus(status);
+  }
+  async request() {
+    const { status } = await Location2.requestForegroundPermissionsAsync();
+    return mapExpoStatus(status);
+  }
+};
+
+// src/storage/async-storage-store.ts
+var import_async_storage2 = __toESM(require("@react-native-async-storage/async-storage"));
+var STORAGE_KEY = "@geopulse/pending-events";
+var AsyncStorageEventQueueStore = class {
+  async getAll() {
+    const raw = await import_async_storage2.default.getItem(STORAGE_KEY);
+    if (!raw) return [];
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return [];
+    }
+  }
+  async save(event) {
+    const all = await this.getAll();
+    const next = [...all.filter((existing) => existing.eventId !== event.eventId), event];
+    await import_async_storage2.default.setItem(STORAGE_KEY, JSON.stringify(next));
+  }
+  async remove(eventId) {
+    const all = await this.getAll();
+    await import_async_storage2.default.setItem(STORAGE_KEY, JSON.stringify(all.filter((existing) => existing.eventId !== eventId)));
+  }
+};
+
+// src/sync/netinfo-network-monitor.ts
+var import_netinfo = __toESM(require("@react-native-community/netinfo"));
+function toStatus(isConnected) {
+  if (isConnected === null) return "unknown";
+  return isConnected ? "online" : "offline";
+}
+var NetInfoNetworkMonitor = class {
+  status = "unknown";
+  constructor() {
+    import_netinfo.default.fetch().then((state) => {
+      this.status = toStatus(state.isConnected);
+    });
+  }
+  getStatus() {
+    return this.status;
+  }
+  subscribe(listener) {
+    return import_netinfo.default.addEventListener((state) => {
+      this.status = toStatus(state.isConnected);
+      listener(this.status);
+    });
+  }
+};
+
+// src/index.ts
+var isDev = typeof __DEV__ === "undefined" ? true : __DEV__;
+var useRealLocationInDev = process.env.EXPO_PUBLIC_GEOPULSE_USE_REAL_LOCATION === "true";
+var useSimulatedProviders = isDev && !useRealLocationInDev;
+function getPlatform() {
+  switch (import_react_native.Platform.OS) {
+    case "ios":
+    case "android":
+    case "web":
+      return import_react_native.Platform.OS;
+    default:
+      return "unknown";
+  }
+}
+var persistentKeyValueStore = new AsyncStorageKeyValueStore();
+var sdk = new GeoPulseSdk({
+  locationProvider: useSimulatedProviders ? new SimulatedLocationProvider() : new DeviceLocationProvider(),
+  permissionProvider: useSimulatedProviders ? new SimulatedPermissionProvider() : new ExpoPermissionProvider(),
+  queue: new PendingEventQueue(new AsyncStorageEventQueueStore()),
+  deviceIdStore: persistentKeyValueStore,
+  configCacheStore: persistentKeyValueStore,
+  networkMonitor: new NetInfoNetworkMonitor(),
+  getPlatform,
+  debug: isDev
+});
+var GeoPulse = {
+  initialize: (config) => sdk.initialize(config),
+  start: () => sdk.start(),
+  stop: () => sdk.stop(),
+  getStatus: () => sdk.getStatus(),
+  getPermissionStatus: () => sdk.getPermissionStatus(),
+  on: sdk.on.bind(sdk),
+  off: sdk.off.bind(sdk),
+  // Small additions beyond the core 7-method API, for building a status UI
+  // around the SDK (see apps/playground) — not part of the minimal public
+  // surface the spec calls out, but plain read-only accessors for state the
+  // SDK already tracks internally.
+  getConfiguredGeofences: () => sdk.getConfiguredGeofences(),
+  getApplicationId: () => sdk.getApplicationId(),
+  getLastKnownLocation: () => sdk.getLastKnownLocation(),
+  getPendingEventCount: () => sdk.getPendingEventCount(),
+  getDeviceId: () => sdk.getDeviceId(),
+  /** Rich developer-diagnostics snapshot — see core/types.ts's DiagnosticsSnapshot doc. */
+  getDiagnostics: () => sdk.getDiagnostics(),
+  /** Development-only. No-ops (with a console warning) in a production build — see GeoPulseSdk.simulateLocation. */
+  simulator: {
+    setLocation: (coords) => sdk.simulateLocation(coords)
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DeviceLocationProvider,
+  ExpoPermissionProvider,
+  GeoPulse,
+  GeoPulseSdk,
+  ManualNetworkMonitor,
+  NetInfoNetworkMonitor,
+  SimulatedLocationProvider,
+  SimulatedPermissionProvider
+});
+//# sourceMappingURL=index.js.map