@sharib/geopulse-react-native 0.3.4 → 0.4.0

package/dist/index.js

@@ -60,7 +60,7 @@ var AsyncStorageKeyValueStore = class {
 
 // src/config/types.ts
 var DEFAULT_BACKEND_URL = "https://geofends.onrender.com";
-var SDK_VERSION = "0.3.4";
+var SDK_VERSION = "0.4.0";
 
 // src/config/key-value-store.ts
 var InMemoryKeyValueStore = class {
@@ -281,6 +281,24 @@ function resolveExperienceStyle(type, custom) {
 }
 
 // src/firebase/api-client.ts
+var MAX_RETRY_AFTER_MS = 15 * 6e4;
+var ApiError = class extends Error {
+  constructor(message, status, retryAfterMs = null) {
+    super(message);
+    this.status = status;
+    this.retryAfterMs = retryAfterMs;
+    this.name = "ApiError";
+  }
+  status;
+  retryAfterMs;
+};
+function retryAfterMsFrom(response) {
+  const seconds = Number(response.headers?.get?.("retry-after"));
+  return Number.isFinite(seconds) && seconds > 0 ? Math.min(seconds * 1e3, MAX_RETRY_AFTER_MS) : null;
+}
+function failure(callName, response) {
+  return new ApiError(`${callName} failed with status ${response.status}`, response.status, response.status === 429 ? retryAfterMsFrom(response) : null);
+}
 var REQUEST_TIMEOUT_MS = 15e3;
 async function fetchWithTimeout(url, init) {
   const controller = new AbortController();
@@ -331,7 +349,7 @@ var ApiClient = class {
       headers: this.headers()
     });
     if (!response.ok) {
-      throw new Error(`getProjectConfig failed with status ${response.status}`);
+      throw failure("getProjectConfig", response);
     }
     return await response.json();
   }
@@ -342,7 +360,7 @@ var ApiClient = class {
       body: JSON.stringify(payload)
     });
     if (!response.ok) {
-      throw new Error(`ingestLocationEvent failed with status ${response.status}`);
+      throw failure("ingestLocationEvent", response);
     }
     return await response.json();
   }
@@ -354,10 +372,10 @@ var ApiClient = class {
       headers: this.headers()
     });
     if (!response.ok) {
-      throw new Error(`getPendingExperiences failed with status ${response.status}`);
+      throw failure("getPendingExperiences", response);
     }
     const body = await response.json();
-    return body.experiences;
+    return { experiences: body.experiences ?? [], revoked: body.revoked ?? [] };
   }
   /** Confirms a delivery was surfaced via `experience.received`, so it stops appearing in future polls. */
   async acknowledgeExperienceDelivery(deliveryId) {
@@ -367,7 +385,7 @@ var ApiClient = class {
       body: JSON.stringify({ deliveryId })
     });
     if (!response.ok) {
-      throw new Error(`acknowledgeExperienceDelivery failed with status ${response.status}`);
+      throw failure("acknowledgeExperienceDelivery", response);
     }
   }
 };
@@ -396,27 +414,52 @@ function createEventPayload(params) {
 }
 
 // src/geofencing/state-machine.ts
+var DEFAULT_EXIT_BUFFER_METERS = 20;
+var DEFAULT_MAX_ACCURACY_METERS = 100;
+var DEFAULT_TRANSITION_COOLDOWN_MS = 2 * 6e4;
 var GeofenceStateMachine = class {
   membershipByGeofenceId = /* @__PURE__ */ new Map();
+  lastTransitionAtByGeofenceId = /* @__PURE__ */ new Map();
+  exitBufferMeters;
+  maxAccuracyMeters;
+  cooldownMs;
+  now;
+  constructor(options = {}) {
+    this.exitBufferMeters = options.exitBufferMeters ?? DEFAULT_EXIT_BUFFER_METERS;
+    this.maxAccuracyMeters = options.maxAccuracyMeters ?? DEFAULT_MAX_ACCURACY_METERS;
+    this.cooldownMs = options.cooldownMs ?? DEFAULT_TRANSITION_COOLDOWN_MS;
+    this.now = options.now ?? Date.now;
+  }
   evaluate(location, geofences) {
+    if (location.accuracy !== void 0 && location.accuracy > this.maxAccuracyMeters) {
+      return [];
+    }
     const transitions = [];
     const activeIds = /* @__PURE__ */ new Set();
+    const exitBuffer = Math.max(this.exitBufferMeters, location.accuracy ?? 0);
+    const now = this.now();
     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"
-        });
+      const nextMembership = previousMembership === "INSIDE" ? distance > geofence.radiusMeters + exitBuffer ? "OUTSIDE" : "INSIDE" : distance <= geofence.radiusMeters ? "INSIDE" : "OUTSIDE";
+      if (previousMembership === nextMembership) {
+        this.membershipByGeofenceId.set(geofence.id, nextMembership);
+        continue;
+      }
+      const lastTransitionAt = this.lastTransitionAtByGeofenceId.get(geofence.id);
+      if (lastTransitionAt !== void 0 && now - lastTransitionAt < this.cooldownMs) {
+        this.membershipByGeofenceId.set(geofence.id, previousMembership);
+        continue;
       }
       this.membershipByGeofenceId.set(geofence.id, nextMembership);
+      this.lastTransitionAtByGeofenceId.set(geofence.id, now);
+      transitions.push({ geofence, type: nextMembership === "INSIDE" ? "geofence.enter" : "geofence.exit" });
     }
-    for (const id of this.membershipByGeofenceId.keys()) {
+    for (const id of [...this.membershipByGeofenceId.keys()]) {
       if (!activeIds.has(id)) {
         this.membershipByGeofenceId.delete(id);
+        this.lastTransitionAtByGeofenceId.delete(id);
       }
     }
     return transitions;
@@ -424,8 +467,62 @@ var GeofenceStateMachine = class {
   getMembership(geofenceId) {
     return this.membershipByGeofenceId.get(geofenceId) ?? "OUTSIDE";
   }
+  isInsideAny() {
+    for (const membership of this.membershipByGeofenceId.values()) {
+      if (membership === "INSIDE") return true;
+    }
+    return false;
+  }
+  exportState() {
+    return {
+      membership: Object.fromEntries(this.membershipByGeofenceId),
+      lastTransitionAt: Object.fromEntries(this.lastTransitionAtByGeofenceId)
+    };
+  }
+  /** Only for a machine that has not evaluated anything yet. */
+  restoreState(state) {
+    this.membershipByGeofenceId.clear();
+    this.lastTransitionAtByGeofenceId.clear();
+    for (const [id, membership] of Object.entries(state.membership)) {
+      if (membership === "INSIDE" || membership === "OUTSIDE") this.membershipByGeofenceId.set(id, membership);
+    }
+    for (const [id, at] of Object.entries(state.lastTransitionAt)) {
+      if (typeof at === "number" && Number.isFinite(at)) this.lastTransitionAtByGeofenceId.set(id, at);
+    }
+  }
   reset() {
     this.membershipByGeofenceId.clear();
+    this.lastTransitionAtByGeofenceId.clear();
+  }
+};
+
+// src/geofencing/state-store.ts
+var STORAGE_KEY = "@geopulse/geofence-state";
+var GEOFENCE_STATE_MAX_AGE_MS = 12 * 60 * 60 * 1e3;
+var GeofenceStateStore = class {
+  constructor(store, now = Date.now) {
+    this.store = store;
+    this.now = now;
+  }
+  store;
+  now;
+  async load() {
+    try {
+      const raw = await this.store.getItem(STORAGE_KEY);
+      if (!raw) return null;
+      const saved = JSON.parse(raw);
+      if (typeof saved.savedAt !== "number" || this.now() - saved.savedAt > GEOFENCE_STATE_MAX_AGE_MS) return null;
+      if (typeof saved.membership !== "object" || saved.membership === null) return null;
+      return { membership: saved.membership, lastTransitionAt: saved.lastTransitionAt ?? {} };
+    } catch {
+      return null;
+    }
+  }
+  async save(state) {
+    try {
+      await this.store.setItem(STORAGE_KEY, JSON.stringify({ ...state, savedAt: this.now() }));
+    } catch {
+    }
   }
 };
 
@@ -492,65 +589,98 @@ var InMemoryEventQueueStore = class {
 };
 
 // src/storage/queue.ts
+var MAX_QUEUE_SIZE = 100;
+var MAX_QUEUED_EVENT_AGE_MS = 24 * 60 * 60 * 1e3;
 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
+  chain = Promise.resolve();
+  serialized(operation) {
+    const result = this.chain.then(operation, operation);
+    this.chain = result.catch(() => void 0);
+    return result;
+  }
+  enqueue(payload) {
+    return this.serialized(async () => {
+      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
+      });
+      await this.trim();
     });
   }
   /** 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)
-    );
+  listPending() {
+    return this.serialized(() => this.store.getAll());
+  }
+  /** 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 = /* @__PURE__ */ new Date()) {
+    return this.serialized(async () => {
+      let all = await this.store.getAll();
+      for (const event of all.filter((candidate) => isTooOld(candidate, now.getTime()))) {
+        await this.store.remove(event.eventId);
+      }
+      all = all.filter((event) => !isTooOld(event, now.getTime()));
+      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()
+  markSending(eventId) {
+    return this.serialized(async () => {
+      const existing = await this.get(eventId);
+      if (!existing) return;
+      await this.store.save({ ...existing, status: "sending" });
     });
   }
-  async markSent(eventId) {
-    await this.store.remove(eventId);
+  /** `minDelayMs` lets a 429's Retry-After push the next attempt later than the normal backoff. */
+  markAttemptFailed(eventId, minDelayMs = 0) {
+    return this.serialized(async () => {
+      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() + Math.max(computeRetryDelayMs(attempts), minDelayMs)).toISOString()
+      });
+    });
+  }
+  markSent(eventId) {
+    return this.serialized(() => this.store.remove(eventId));
   }
   async get(eventId) {
     return (await this.store.getAll()).find((event) => event.eventId === eventId);
   }
+  /** Keeps the queue within MAX_QUEUE_SIZE by dropping the oldest events that are not being sent right now. */
+  async trim() {
+    const all = await this.store.getAll();
+    if (all.length <= MAX_QUEUE_SIZE) return;
+    const droppable = all.filter((event) => event.status !== "sending").sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
+    for (const event of droppable.slice(0, all.length - MAX_QUEUE_SIZE)) {
+      await this.store.remove(event.eventId);
+    }
+  }
 };
+function isTooOld(event, nowMs) {
+  const eventTime = Date.parse(event.timestamp);
+  return !Number.isNaN(eventTime) && nowMs - eventTime > MAX_QUEUED_EVENT_AGE_MS;
+}
 
 // src/sync/network-monitor.ts
 var ManualNetworkMonitor = class {
@@ -572,20 +702,29 @@ var ManualNetworkMonitor = class {
 
 // src/sync/sync-manager.ts
 var DEFAULT_RETRY_INTERVAL_MS = 3e4;
+var MAX_UPLOADS_PER_MINUTE = 3;
+var FORCED_RETRY_MIN_GAP_MS = 1e4;
+var FORBIDDEN_PAUSE_MS = MAX_RETRY_AFTER_MS;
+var DEFAULT_RATE_LIMIT_PAUSE_MS = 6e4;
 var SyncManager = class {
-  constructor(apiClient, queue, retryIntervalMs = DEFAULT_RETRY_INTERVAL_MS, logger) {
+  constructor(apiClient, queue, retryIntervalMs = DEFAULT_RETRY_INTERVAL_MS, logger, onDelivered) {
     this.apiClient = apiClient;
     this.queue = queue;
     this.retryIntervalMs = retryIntervalMs;
     this.logger = logger;
+    this.onDelivered = onDelivered;
   }
   apiClient;
   queue;
   retryIntervalMs;
   logger;
+  onDelivered;
   retryTimer = null;
   lastSyncAt = null;
   lastUploadResult = null;
+  uploadTimes = [];
+  pausedUntil = 0;
+  lastForcedRetryAt = 0;
   /**
    * 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
@@ -597,8 +736,18 @@ var SyncManager = class {
    */
   async sendOrQueue(payload) {
     await this.queue.enqueue(payload);
+    if (!this.canUploadNow()) {
+      this.logger?.log("Upload deferred (rate cap or server asked to wait)", { eventId: payload.id });
+      return;
+    }
     await this.attemptDelivery(payload.id, payload);
   }
+  canUploadNow() {
+    const now = Date.now();
+    if (now < this.pausedUntil) return false;
+    this.uploadTimes = this.uploadTimes.filter((at) => now - at < 6e4);
+    return this.uploadTimes.length < MAX_UPLOADS_PER_MINUTE;
+  }
   /**
    * Attempts queued events. By default only ones whose backoff window has
    * elapsed (the timer-driven path, `startAutoRetry` — the whole point of
@@ -611,9 +760,17 @@ var SyncManager = class {
    * 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 };
+    let force = options.force === true;
+    if (force) {
+      const now = Date.now();
+      if (now - this.lastForcedRetryAt < FORCED_RETRY_MIN_GAP_MS) force = false;
+      else this.lastForcedRetryAt = now;
+    }
+    const ready = force ? (await this.queue.listPending()).filter((event) => event.status !== "sending") : await this.queue.listReadyForRetry();
+    const result = { attempted: 0, delivered: 0, failed: 0 };
     for (const event of ready) {
+      if (!this.canUploadNow()) break;
+      result.attempted++;
       const attemptNumber = event.attempts + 1;
       const delivered = await this.attemptDelivery(event.eventId, { ...event.payload, attempts: attemptNumber });
       if (delivered) {
@@ -634,21 +791,39 @@ var SyncManager = class {
    * was delivered, purely so `retryPending` can tally its `SyncResult`.
    */
   async attemptDelivery(eventId, payload) {
+    this.uploadTimes.push(Date.now());
     await this.queue.markSending(eventId);
     this.logger?.log("Event upload started", { eventId, attempt: payload.attempts });
+    let result;
     try {
-      await this.apiClient.ingestEvent(payload);
+      result = 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) });
+      if (error instanceof ApiError && error.status === 429) {
+        const waitMs = error.retryAfterMs ?? DEFAULT_RATE_LIMIT_PAUSE_MS;
+        this.pausedUntil = Date.now() + waitMs;
+        await this.queue.markAttemptFailed(eventId, waitMs);
+        this.logger?.warn("Server rate limit \u2014 pausing uploads", { eventId, waitMs });
+      } else if (error instanceof ApiError && isPermanentRejection(error.status)) {
+        await this.queue.markSent(eventId);
+        if (error.status === 403) this.pausedUntil = Date.now() + FORBIDDEN_PAUSE_MS;
+        this.logger?.warn("Event rejected permanently \u2014 dropped", { eventId, status: error.status });
+      } else {
+        await this.queue.markAttemptFailed(eventId);
+        this.logger?.warn("Event upload failed \u2014 retry scheduled", { eventId, error: String(error) });
+      }
       return false;
     }
+    try {
+      this.onDelivered?.(result);
+    } catch (error) {
+      this.logger?.warn("onDelivered handler threw", { eventId, error: String(error) });
+    }
+    return true;
   }
   startAutoRetry() {
     if (this.retryTimer) return;
@@ -669,6 +844,9 @@ var SyncManager = class {
     return this.lastUploadResult;
   }
 };
+function isPermanentRejection(status) {
+  return status >= 400 && status < 500 && status !== 408 && status !== 429;
+}
 
 // src/core/logger.ts
 var Logger = class {
@@ -704,7 +882,8 @@ var ApplicationMismatchError = class extends Error {
     this.name = "ApplicationMismatchError";
   }
 };
-var DEFAULT_EXPERIENCE_POLL_INTERVAL_MS = 3e4;
+var DEFAULT_EXPERIENCE_POLL_INTERVAL_MS = 15 * 6e4;
+var CONFIG_REFRESH_INTERVAL_MS = 60 * 6e4;
 var MIN_TIMER_INTERVAL_MS = 1e3;
 function clampIntervalMs(value) {
   if (value === void 0) {
@@ -731,12 +910,25 @@ var GeoPulseSdk = class {
   deviceId = null;
   locationError = null;
   unsubscribeNetwork = null;
-  stateMachine = new GeofenceStateMachine();
+  stateMachine;
+  geofenceStateStore;
+  geofenceStateRestored = false;
+  realtime = null;
+  createRealtime;
+  lastConfigFetchAt = 0;
+  configRefreshInFlight = false;
   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();
+  seenExperienceRevisions = /* @__PURE__ */ new Map();
+  experienceRemovedListeners = /* @__PURE__ */ new Set();
+  removedDeliveryIds = /* @__PURE__ */ new Set();
   experiencePollTimer = null;
+  experiencePollInFlight = false;
+  /** Set while a poll that was refused with "too many requests" waits to be tried again. */
+  pollRetryTimer = null;
+  /** Set when a poll was asked for while one was already running; that one may have queried before the new delivery existed. */
+  experiencePollRequested = false;
   experiencesReceivedCount = 0;
   logger;
   locationProvider;
@@ -758,6 +950,9 @@ var GeoPulseSdk = class {
     this.networkMonitor = dependencies.networkMonitor ?? new ManualNetworkMonitor();
     this.getPlatform = dependencies.getPlatform ?? (() => "unknown");
     this.logger = new Logger(dependencies.debug ?? false);
+    this.stateMachine = new GeofenceStateMachine(dependencies.stateMachineOptions);
+    this.geofenceStateStore = new GeofenceStateStore(dependencies.stateStore ?? new InMemoryKeyValueStore());
+    this.createRealtime = dependencies.createRealtimeClient;
   }
   /**
    * Resolves this device's persistent id, then fetches (or falls back to
@@ -783,8 +978,25 @@ var GeoPulseSdk = class {
     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.syncManager = new SyncManager(
+      this.apiClient,
+      this.queue,
+      clampIntervalMs(config.retryIntervalMs),
+      this.logger,
+      (result) => this.handleEventDelivered(result)
+    );
     this.deviceId = await getOrCreateDeviceId(this.deviceIdStore);
+    this.realtime?.disconnect();
+    this.realtime = this.createRealtime ? this.createRealtime({
+      baseUrl: config.functionsBaseUrl || DEFAULT_BACKEND_URL,
+      sdkKey: config.apiKey,
+      applicationId: config.applicationId,
+      deviceId: this.deviceId,
+      onChanged: () => void this.pollForExperiences(),
+      // Whatever changed while the socket was down is picked up now.
+      onConnected: () => void this.pollForExperiences(),
+      logger: this.logger
+    }) : null;
     try {
       const projectConfig = await this.apiClient.getProjectConfig({
         deviceId: this.deviceId,
@@ -796,6 +1008,7 @@ var GeoPulseSdk = class {
       }
       this.applyProjectConfig(projectConfig);
       this.configurationStatus = "synced";
+      this.lastConfigFetchAt = Date.now();
       await this.configCache.save(projectConfig);
       this.status = "initialized";
       this.logger.log("Configuration synced", { geofenceCount: projectConfig.geofences.length, configVersion: projectConfig.configVersion });
@@ -834,6 +1047,11 @@ var GeoPulseSdk = class {
       this.status = "error";
       throw new Error(`Location permission not granted (status: ${permission})`);
     }
+    if (!this.geofenceStateRestored) {
+      this.geofenceStateRestored = true;
+      const saved = await this.geofenceStateStore.load();
+      if (saved) this.stateMachine.restoreState(saved);
+    }
     this.locationError = null;
     await this.locationProvider.start(
       (location) => {
@@ -857,12 +1075,14 @@ var GeoPulseSdk = class {
     this.syncManager?.startAutoRetry();
     this.startExperiencePolling();
     this.status = "running";
+    this.syncRealtime();
     this.logger.log("GeoPulse.start()");
   }
   stop() {
     this.locationProvider.stop();
     this.syncManager?.stopAutoRetry();
     this.stopExperiencePolling();
+    this.realtime?.disconnect();
     this.unsubscribeNetwork?.();
     this.unsubscribeNetwork = null;
     this.status = "stopped";
@@ -879,6 +1099,10 @@ var GeoPulseSdk = class {
       this.experienceListeners.add(callback);
       return;
     }
+    if (eventName === "experience.removed") {
+      this.experienceRemovedListeners.add(callback);
+      return;
+    }
     if (!this.listeners.has(eventName)) {
       this.listeners.set(eventName, /* @__PURE__ */ new Set());
     }
@@ -889,6 +1113,10 @@ var GeoPulseSdk = class {
       this.experienceListeners.delete(callback);
       return;
     }
+    if (eventName === "experience.removed") {
+      this.experienceRemovedListeners.delete(callback);
+      return;
+    }
     this.listeners.get(eventName)?.delete(callback);
   }
   // --- Small read-only accessors beyond the core 7-method API, so a host
@@ -970,28 +1198,64 @@ var GeoPulseSdk = class {
     void this.pollForExperiences();
     this.experiencePollTimer = setInterval(() => {
       void this.pollForExperiences();
+      void this.refreshConfigIfStale();
     }, this.experiencePollIntervalMs);
   }
   stopExperiencePolling() {
+    if (this.pollRetryTimer) {
+      clearTimeout(this.pollRetryTimer);
+      this.pollRetryTimer = null;
+    }
     if (this.experiencePollTimer) {
       clearInterval(this.experiencePollTimer);
       this.experiencePollTimer = null;
     }
   }
+  /**
+   * 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.
+   */
+  handleEventDelivered(result) {
+    if (this.experiencePollTimer === null || result?.experiencesPending === false) {
+      return;
+    }
+    void this.pollForExperiences();
+  }
+  /** One poll at a time: a second request while one is running makes it run once more afterwards, rather than overlapping. */
   async pollForExperiences() {
+    if (this.experiencePollInFlight) {
+      this.experiencePollRequested = true;
+      return;
+    }
+    this.experiencePollInFlight = true;
+    try {
+      do {
+        this.experiencePollRequested = false;
+        await this.pollForExperiencesOnce();
+      } while (this.experiencePollRequested);
+    } finally {
+      this.experiencePollInFlight = false;
+    }
+  }
+  async pollForExperiencesOnce() {
     if (!this.apiClient || !this.deviceId) {
       return;
     }
     try {
-      const experiences = await this.apiClient.getPendingExperiences(this.deviceId);
+      const { experiences, revoked } = await this.apiClient.getPendingExperiences(this.deviceId);
       for (const experience of experiences) {
-        if (this.seenExperienceDeliveryIds.has(experience.deliveryId)) {
+        const revision = experience.revision ?? 0;
+        const seenRevision = this.seenExperienceRevisions.get(experience.deliveryId);
+        if (seenRevision === revision) {
           continue;
         }
-        this.seenExperienceDeliveryIds.add(experience.deliveryId);
+        const isUpdate = seenRevision !== void 0;
+        this.seenExperienceRevisions.set(experience.deliveryId, revision);
+        this.removedDeliveryIds.delete(experience.deliveryId);
         this.experiencesReceivedCount += 1;
-        this.logger.log("Experience received", { deliveryId: experience.deliveryId, campaignId: experience.campaignId });
-        this.experienceListeners.forEach((listener) => listener(experience));
+        this.logger.log("Experience received", { deliveryId: experience.deliveryId, campaignId: experience.campaignId, isUpdate });
+        this.experienceListeners.forEach((listener) => listener({ ...experience, isUpdate }));
         await this.apiClient.acknowledgeExperienceDelivery(experience.deliveryId).catch((error) => {
           this.logger.warn("Failed to acknowledge experience delivery", {
             deliveryId: experience.deliveryId,
@@ -999,10 +1263,84 @@ var GeoPulseSdk = class {
           });
         });
       }
+      for (const removed of revoked) {
+        if (!this.removedDeliveryIds.has(removed.deliveryId)) {
+          this.removedDeliveryIds.add(removed.deliveryId);
+          this.seenExperienceRevisions.delete(removed.deliveryId);
+          this.logger.log("Experience removed", { deliveryId: removed.deliveryId, campaignId: removed.campaignId });
+          this.experienceRemovedListeners.forEach((listener) => listener(removed));
+        }
+        await this.apiClient.acknowledgeExperienceDelivery(removed.deliveryId).catch((error) => {
+          this.logger.warn("Failed to acknowledge experience removal", {
+            deliveryId: removed.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) });
+      if (error instanceof ApiError && error.status === 429) {
+        this.schedulePollRetry(error.retryAfterMs ?? 3e4);
+      }
     }
   }
+  schedulePollRetry(waitMs) {
+    if (this.pollRetryTimer !== null || this.experiencePollTimer === null) {
+      return;
+    }
+    this.pollRetryTimer = setTimeout(() => {
+      this.pollRetryTimer = null;
+      void this.pollForExperiences();
+    }, waitMs + Math.random() * 5e3);
+  }
+  /**
+   * 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.
+   */
+  async refreshConfigIfStale() {
+    if (!this.apiClient || !this.deviceId || !this.config || this.configRefreshInFlight) {
+      return;
+    }
+    if (Date.now() - this.lastConfigFetchAt < CONFIG_REFRESH_INTERVAL_MS) {
+      return;
+    }
+    this.configRefreshInFlight = true;
+    try {
+      const projectConfig = await this.apiClient.getProjectConfig({ deviceId: this.deviceId, platform: this.getPlatform(), sdkVersion: SDK_VERSION });
+      if (projectConfig.applicationId !== this.config.applicationId) {
+        return;
+      }
+      this.lastConfigFetchAt = Date.now();
+      this.applyProjectConfig(projectConfig);
+      this.configurationStatus = "synced";
+      await this.configCache.save(projectConfig);
+      this.logger.log("Configuration refreshed", { geofenceCount: projectConfig.geofences.length, configVersion: projectConfig.configVersion });
+      if (!projectConfig.applicationEnabled) {
+        this.logger.warn("Application disabled \u2014 stopping");
+        this.stop();
+        this.status = "error";
+      }
+    } catch (error) {
+      this.logger.warn("Configuration refresh failed \u2014 keeping the current geofences", { error: error instanceof Error ? error.message : String(error) });
+    } finally {
+      this.configRefreshInFlight = false;
+    }
+  }
+  /** Keeps the push connection open exactly while the user is inside a geofence. */
+  syncRealtime() {
+    if (!this.realtime || this.status === "stopped") {
+      return;
+    }
+    if (this.stateMachine.isInsideAny()) {
+      this.realtime.connect();
+    } else {
+      this.realtime.disconnect();
+    }
+  }
+  async persistGeofenceState() {
+    await this.geofenceStateStore.save(this.stateMachine.exportState());
+  }
   applyProjectConfig(projectConfig) {
     this.resolvedProjectId = projectConfig.projectId;
     this.resolvedApplicationId = projectConfig.applicationId;
@@ -1016,6 +1354,10 @@ var GeoPulseSdk = class {
       return;
     }
     const transitions = this.stateMachine.evaluate(location, this.geofences);
+    if (transitions.length > 0) {
+      void this.persistGeofenceState();
+    }
+    this.syncRealtime();
     for (const transition of transitions) {
       this.logger.log("Geofence state changed", { geofenceId: transition.geofence.id, type: transition.type });
       const event = createEventPayload({
@@ -1054,7 +1396,8 @@ var DeviceLocationProvider = class {
           onUpdate({
             latitude: position.coords.latitude,
             longitude: position.coords.longitude,
-            timestamp: new Date(position.timestamp).toISOString()
+            timestamp: new Date(position.timestamp).toISOString(),
+            ...typeof position.coords.accuracy === "number" ? { accuracy: position.coords.accuracy } : {}
           });
         }
       );
@@ -1093,10 +1436,10 @@ var ExpoPermissionProvider = class {
 
 // 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 STORAGE_KEY2 = "@geopulse/pending-events";
 var AsyncStorageEventQueueStore = class {
   async getAll() {
-    const raw = await import_async_storage2.default.getItem(STORAGE_KEY);
+    const raw = await import_async_storage2.default.getItem(STORAGE_KEY2);
     if (!raw) return [];
     try {
       return JSON.parse(raw);
@@ -1107,14 +1450,112 @@ var AsyncStorageEventQueueStore = class {
   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));
+    await import_async_storage2.default.setItem(STORAGE_KEY2, 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)));
+    await import_async_storage2.default.setItem(STORAGE_KEY2, JSON.stringify(all.filter((existing) => existing.eventId !== eventId)));
   }
 };
 
+// src/realtime/realtime-client.ts
+var RECONNECT_BASE_MS = 5e3;
+var RECONNECT_MAX_MS = 5 * 6e4;
+var NO_RETRY_CODES = /* @__PURE__ */ new Set([4400, 4401, 4403]);
+function toRealtimeUrl(baseUrl) {
+  return `${baseUrl.replace(/\/+$/, "").replace(/^http/, "ws")}/realtime`;
+}
+var RealtimeClient = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  socket = null;
+  connected = false;
+  wanted = false;
+  failures = 0;
+  reconnectTimer = null;
+  isConnected() {
+    return this.connected;
+  }
+  connect() {
+    this.wanted = true;
+    if (this.socket || this.reconnectTimer) return;
+    this.open();
+  }
+  disconnect() {
+    this.wanted = false;
+    this.failures = 0;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    const socket = this.socket;
+    this.socket = null;
+    this.connected = false;
+    if (socket) {
+      socket.onclose = null;
+      socket.onmessage = null;
+      socket.onerror = null;
+      try {
+        socket.close(1e3, "done");
+      } catch {
+      }
+    }
+  }
+  open() {
+    const create = this.options.createSocket ?? defaultCreateSocket;
+    let socket;
+    try {
+      socket = create(toRealtimeUrl(this.options.baseUrl));
+    } catch (error) {
+      this.options.logger?.warn("Realtime unavailable", { error: String(error) });
+      return;
+    }
+    if (!socket) return;
+    this.socket = socket;
+    socket.onopen = () => {
+      socket.send(JSON.stringify({ type: "hello", sdkKey: this.options.sdkKey, applicationId: this.options.applicationId, deviceId: this.options.deviceId }));
+    };
+    socket.onmessage = (event) => {
+      let message = null;
+      try {
+        message = JSON.parse(String(event.data));
+      } catch {
+        return;
+      }
+      if (message?.type === "ready") {
+        this.connected = true;
+        this.failures = 0;
+        this.options.onConnected();
+      } else if (message?.type === "changed") {
+        this.options.onChanged();
+      }
+    };
+    socket.onerror = () => {
+    };
+    socket.onclose = (event) => {
+      this.socket = null;
+      this.connected = false;
+      if (!this.wanted) return;
+      if (NO_RETRY_CODES.has(event.code)) {
+        this.options.logger?.warn("Realtime rejected by the server; not retrying", { code: event.code });
+        return;
+      }
+      this.failures += 1;
+      const delay = Math.min(RECONNECT_BASE_MS * 2 ** (this.failures - 1), RECONNECT_MAX_MS);
+      this.reconnectTimer = setTimeout(() => {
+        this.reconnectTimer = null;
+        if (this.wanted) this.open();
+      }, Math.round(delay * (0.8 + Math.random() * 0.4)));
+    };
+  }
+};
+function defaultCreateSocket(url) {
+  const Ctor = globalThis.WebSocket;
+  return Ctor ? new Ctor(url) : null;
+}
+
 // src/sync/netinfo-network-monitor.ts
 var import_netinfo = __toESM(require("@react-native-community/netinfo"));
 function toStatus(isConnected) {
@@ -1252,6 +1693,11 @@ var sdk = new GeoPulseSdk({
   queue: new PendingEventQueue(new AsyncStorageEventQueueStore()),
   deviceIdStore: persistentKeyValueStore,
   configCacheStore: persistentKeyValueStore,
+  // The simulator is for trying things out: no 2-minute cooldown, and no saved "inside" state surviving a reload
+  // (otherwise "enter" would not fire again after Fast Refresh while the saved state says you are still inside).
+  stateStore: useSimulatedProviders ? void 0 : persistentKeyValueStore,
+  stateMachineOptions: useSimulatedProviders ? { cooldownMs: 0 } : void 0,
+  createRealtimeClient: (options) => new RealtimeClient(options),
   networkMonitor: new NetInfoNetworkMonitor(),
   getPlatform,
   debug: isDev