@userflow-tech/react-native 0.1.0

package/lib/module/lifecycle.js

@@ -0,0 +1,195 @@
+"use strict";
+
+/**
+ * Mobile connection lifecycle policy.
+ *
+ * - Background / inactive → arm a short grace timer, then suspend the socket.
+ *   Returning to active before grace elapses avoids suspend/resume churn: resume
+ *   if already idle-suspended, otherwise probe liveness (`ensureAlive`) so a
+ *   silently-dead socket recovers without waiting for the next heartbeat.
+ * - Foreground after grace but < {@link SESSION_STALE_AFTER_BACKGROUND_MS}
+ *   (5 min) → resume and keep the mid-flow session (short-background “resume”).
+ * - Foreground after ≥ 5 min → clear local flow session, then resume
+ *   (long-background reconnect without stale mid-flow UI).
+ * - Foreground idle for 5 min → suspend (skip while any flow session is active).
+ * - Activity while foreground → reset idle timer and resume if idle-suspended.
+ *
+ * This 5-minute policy is the ticket meaning of FLOW_RENDERING_SPEC “resume”:
+ * short backgrounds continue the active flow; long backgrounds clear then reconnect.
+ */
+
+import { AppState } from 'react-native';
+/** Match web `INACTIVITY_TIMEOUT` — disconnect after this much idle time in foreground. */
+export const INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000;
+
+/** Away this long → drop local mid-flow session before reconnecting. */
+export const SESSION_STALE_AFTER_BACKGROUND_MS = 5 * 60 * 1000;
+
+/**
+ * Delay before suspending on leave. Covers transient iOS `inactive` (Control
+ * Center, biometric prompts, app-switcher peek) and quick app-switches.
+ */
+export const SUSPEND_GRACE_MS = 3_000;
+const defaultScheduler = {
+  setTimeout: (handler, ms) => setTimeout(handler, ms),
+  clearTimeout: handle => clearTimeout(handle)
+};
+function defaultSubscribeAppState(handler) {
+  const subscription = AppState.addEventListener('change', handler);
+  return () => subscription.remove();
+}
+
+/**
+ * Owns AppState subscription, background duration tracking, and the foreground
+ * idle timer. Call {@link start} from `Userflow.init` and {@link stop} from
+ * `Userflow.teardown`.
+ */
+export class LifecycleController {
+  unsubscribeAppState = null;
+  idleTimer = null;
+  graceTimer = null;
+  backgroundedAt = null;
+  appIsActive = true;
+  started = false;
+  /** True once the grace timer has fired (or we suspended on long-away resume). */
+  suspended = false;
+  constructor(deps) {
+    this.suspend = deps.suspend;
+    this.resume = deps.resume;
+    this.clearLocalSession = deps.clearLocalSession;
+    this.ensureAlive = deps.ensureAlive;
+    this.hasActiveSession = deps.hasActiveSession;
+    this.scheduler = deps.scheduler ?? defaultScheduler;
+    this.now = deps.now ?? (() => Date.now());
+    this.suspendGraceMs = deps.suspendGraceMs ?? SUSPEND_GRACE_MS;
+    this.getCurrentAppState = deps.getCurrentAppState ?? (() => AppState.currentState);
+    this.subscribeAppState = deps.subscribeAppState ?? defaultSubscribeAppState;
+  }
+  start() {
+    if (this.started) return;
+    this.started = true;
+    this.appIsActive = this.getCurrentAppState() === 'active';
+    this.unsubscribeAppState = this.subscribeAppState(status => {
+      this.handleAppStateChange(status);
+    });
+    if (this.appIsActive) {
+      this.scheduleIdleTimer();
+    }
+  }
+  stop() {
+    if (!this.started) return;
+    this.started = false;
+    this.clearIdleTimer();
+    this.clearGraceTimer();
+    this.unsubscribeAppState?.();
+    this.unsubscribeAppState = null;
+    this.backgroundedAt = null;
+    this.suspended = false;
+  }
+
+  /**
+   * Signal user/SDK activity while the app is foregrounded. Resets the idle
+   * timer and reconnects if the socket was idle-suspended.
+   */
+  reportActivity() {
+    if (!this.started || !this.appIsActive) return;
+    this.resume();
+    this.suspended = false;
+    this.scheduleIdleTimer();
+  }
+
+  /** Visible for tests. */
+  handleAppStateChange(status) {
+    if (!this.started) return;
+    if (status === 'active') {
+      this.onForeground();
+      return;
+    }
+    if (status === 'background' || status === 'inactive') {
+      this.onBackground();
+    }
+  }
+  onBackground() {
+    // Already leaving (e.g. inactive → background): keep first timestamp; do not
+    // re-arm the grace timer.
+    if (!this.appIsActive && this.backgroundedAt != null) {
+      return;
+    }
+    if (this.appIsActive) {
+      this.backgroundedAt = this.now();
+    } else if (this.backgroundedAt == null) {
+      this.backgroundedAt = this.now();
+    }
+    this.appIsActive = false;
+    this.clearIdleTimer();
+    this.scheduleGraceTimer();
+  }
+  onForeground() {
+    const awayMs = this.backgroundedAt != null ? this.now() - this.backgroundedAt : 0;
+    this.backgroundedAt = null;
+    this.appIsActive = true;
+    this.clearGraceTimer();
+    if (awayMs < this.suspendGraceMs) {
+      // Transient blur / quick switch. If already idle-suspended, resume —
+      // ensureAlive is a no-op while the transport is lifecycle-suspended.
+      // Otherwise probe liveness so a silently-dead socket recovers fast.
+      if (this.suspended) {
+        this.resume();
+        this.suspended = false;
+      } else {
+        this.ensureAlive();
+      }
+      this.scheduleIdleTimer();
+      return;
+    }
+
+    // Away past grace: ensure a clean suspend (covers iOS freezing JS before
+    // the grace timer fired) then resume. Clear mid-flow session if stale.
+    if (!this.suspended) {
+      this.suspend();
+      this.suspended = true;
+    }
+    if (awayMs >= SESSION_STALE_AFTER_BACKGROUND_MS) {
+      this.clearLocalSession();
+    }
+    this.resume();
+    this.suspended = false;
+    this.scheduleIdleTimer();
+  }
+  scheduleGraceTimer() {
+    this.clearGraceTimer();
+    this.graceTimer = this.scheduler.setTimeout(() => {
+      this.graceTimer = null;
+      if (this.appIsActive) return;
+      if (this.suspended) return;
+      this.suspend();
+      this.suspended = true;
+    }, this.suspendGraceMs);
+  }
+  clearGraceTimer() {
+    if (this.graceTimer != null) {
+      this.scheduler.clearTimeout(this.graceTimer);
+      this.graceTimer = null;
+    }
+  }
+  scheduleIdleTimer() {
+    this.clearIdleTimer();
+    this.idleTimer = this.scheduler.setTimeout(() => {
+      this.idleTimer = null;
+      if (!this.appIsActive) return;
+      if (this.hasActiveSession()) {
+        this.scheduleIdleTimer();
+        return;
+      }
+      this.suspend();
+      this.suspended = true;
+    }, INACTIVITY_TIMEOUT_MS);
+  }
+  clearIdleTimer() {
+    if (this.idleTimer != null) {
+      this.scheduler.clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+  }
+}
+//# sourceMappingURL=lifecycle.js.map

package/lib/module/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["AppState","INACTIVITY_TIMEOUT_MS","SESSION_STALE_AFTER_BACKGROUND_MS","SUSPEND_GRACE_MS","defaultScheduler","setTimeout","handler","ms","clearTimeout","handle","defaultSubscribeAppState","subscription","addEventListener","remove","LifecycleController","unsubscribeAppState","idleTimer","graceTimer","backgroundedAt","appIsActive","started","suspended","constructor","deps","suspend","resume","clearLocalSession","ensureAlive","hasActiveSession","scheduler","now","Date","suspendGraceMs","getCurrentAppState","currentState","subscribeAppState","start","status","handleAppStateChange","scheduleIdleTimer","stop","clearIdleTimer","clearGraceTimer","reportActivity","onForeground","onBackground","scheduleGraceTimer","awayMs"],"sourceRoot":"../../src","sources":["lifecycle.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/navigation/WithUserflowReactNavigation.js

@@ -0,0 +1,65 @@
+"use strict";
+
+import { useNavigationContainerRef } from '@react-navigation/native';
+import { cloneElement, isValidElement, useCallback, useEffect } from 'react';
+import { handleScreenChange } from "../screenTracker.js";
+import { chainCallbacks } from "./chainCallbacks.js";
+import { getActiveRouteName } from "./getActiveRouteName.js";
+import { setReactNavigationRef } from "./openFlowNavigateUrl.js";
+function assignRef(ref, value) {
+  if (typeof ref === 'function') {
+    ref(value);
+  } else if (ref != null && typeof ref === 'object' && 'current' in ref) {
+    ref.current = value;
+  }
+}
+function mergeRefs(...refs) {
+  return value => {
+    for (const ref of refs) {
+      assignRef(ref, value);
+    }
+  };
+}
+
+/**
+ * Wraps a React Navigation `NavigationContainer` to report screen changes to
+ * Userflow after {@link Userflow.init} has completed.
+ *
+ * Also registers the container ref for in-app NAVIGATE actions (path-like URLs).
+ * Screen tracking ≠ action routing — without this wrapper, NAVIGATE falls back to
+ * Linking / host `onNavigate`.
+ */
+export function WithUserflowReactNavigation({
+  children
+}) {
+  const navigationRef = useNavigationContainerRef();
+  useEffect(() => {
+    setReactNavigationRef(navigationRef);
+    return () => {
+      setReactNavigationRef(null);
+    };
+  }, [navigationRef]);
+  const handleReady = useCallback(() => {
+    setReactNavigationRef(navigationRef);
+    const name = getActiveRouteName(navigationRef.getRootState());
+    handleScreenChange(name ? {
+      screen: name
+    } : undefined);
+  }, [navigationRef]);
+  const handleStateChange = useCallback(state => {
+    const name = getActiveRouteName(state ?? navigationRef.getRootState());
+    handleScreenChange(name ? {
+      screen: name
+    } : undefined);
+  }, [navigationRef]);
+  if (! /*#__PURE__*/isValidElement(children)) {
+    throw new Error('WithUserflowReactNavigation expects a single React element child.');
+  }
+  const childProps = children.props;
+  return /*#__PURE__*/cloneElement(children, {
+    ref: mergeRefs(childProps.ref, navigationRef),
+    onReady: chainCallbacks(childProps.onReady, handleReady) ?? handleReady,
+    onStateChange: chainCallbacks(childProps.onStateChange, handleStateChange) ?? handleStateChange
+  });
+}
+//# sourceMappingURL=WithUserflowReactNavigation.js.map

package/lib/module/navigation/WithUserflowReactNavigation.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useNavigationContainerRef","cloneElement","isValidElement","useCallback","useEffect","handleScreenChange","chainCallbacks","getActiveRouteName","setReactNavigationRef","assignRef","ref","value","current","mergeRefs","refs","WithUserflowReactNavigation","children","navigationRef","handleReady","name","getRootState","screen","undefined","handleStateChange","state","Error","childProps","props","onReady","onStateChange"],"sourceRoot":"../../../src","sources":["navigation/WithUserflowReactNavigation.tsx"],"mappings":";;AAAA,SAASA,yBAAyB,QAAQ,0BAA0B;AAMpE,SAASC,YAAY,EAAEC,cAAc,EAAEC,WAAW,EAAEC,SAAS,QAAQ,OAAO;AAG5E,SAASC,kBAAkB,QAAQ,qBAAkB;AAErD,SAASC,cAAc,QAAQ,qBAAkB;AACjD,SAASC,kBAAkB,QAAQ,yBAAsB;AACzD,SAASC,qBAAqB,QAAQ,0BAAuB;AAY7D,SAASC,SAASA,CAAIC,GAA6B,EAAEC,KAAe,EAAQ;EAC1E,IAAI,OAAOD,GAAG,KAAK,UAAU,EAAE;IAC7BA,GAAG,CAACC,KAAK,CAAC;EACZ,CAAC,MAAM,IAAID,GAAG,IAAI,IAAI,IAAI,OAAOA,GAAG,KAAK,QAAQ,IAAI,SAAS,IAAIA,GAAG,EAAE;IACpEA,GAAG,CAAsCE,OAAO,GAAGD,KAAK;EAC3D;AACF;AAEA,SAASE,SAASA,CAAI,GAAGC,IAAqC,EAAwB;EACpF,OAAQH,KAAK,IAAK;IAChB,KAAK,MAAMD,GAAG,IAAII,IAAI,EAAE;MACtBL,SAAS,CAACC,GAAG,EAAEC,KAAK,CAAC;IACvB;EACF,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASI,2BAA2BA,CAAC;EAC1CC;AACgC,CAAC,EAAsB;EACvD,MAAMC,aAAa,GAAGjB,yBAAyB,CAAgB,CAAC;EAEhEI,SAAS,CAAC,MAAM;IACdI,qBAAqB,CAACS,aAAa,CAAC;IACpC,OAAO,MAAM;MACXT,qBAAqB,CAAC,IAAI,CAAC;IAC7B,CAAC;EACH,CAAC,EAAE,CAACS,aAAa,CAAC,CAAC;EAEnB,MAAMC,WAAW,GAAGf,WAAW,CAAC,MAAM;IACpCK,qBAAqB,CAACS,aAAa,CAAC;IACpC,MAAME,IAAI,GAAGZ,kBAAkB,CAACU,aAAa,CAACG,YAAY,CAAC,CAAC,CAAC;IAC7Df,kBAAkB,CAACc,IAAI,GAAG;MAAEE,MAAM,EAAEF;IAAK,CAAC,GAAGG,SAAS,CAAC;EACzD,CAAC,EAAE,CAACL,aAAa,CAAC,CAAC;EAEnB,MAAMM,iBAAiB,GAAGpB,WAAW,CAClCqB,KAAuB,IAAK;IAC3B,MAAML,IAAI,GAAGZ,kBAAkB,CAACiB,KAAK,IAAIP,aAAa,CAACG,YAAY,CAAC,CAAC,CAAC;IACtEf,kBAAkB,CAACc,IAAI,GAAG;MAAEE,MAAM,EAAEF;IAAK,CAAC,GAAGG,SAAS,CAAC;EACzD,CAAC,EACD,CAACL,aAAa,CAChB,CAAC;EAED,IAAI,eAACf,cAAc,CAACc,QAAQ,CAAC,EAAE;IAC7B,MAAM,IAAIS,KAAK,CAAC,mEAAmE,CAAC;EACtF;EAEA,MAAMC,UAAU,GAAGV,QAAQ,CAACW,KAAK;EAEjC,oBAAO1B,YAAY,CAACe,QAAQ,EAAE;IAC5BN,GAAG,EAAEG,SAAS,CAACa,UAAU,CAAChB,GAAG,EAAEO,aAAa,CAAC;IAC7CW,OAAO,EAAEtB,cAAc,CAACoB,UAAU,CAACE,OAAO,EAAEV,WAAW,CAAC,IAAIA,WAAW;IACvEW,aAAa,EAAEvB,cAAc,CAACoB,UAAU,CAACG,aAAa,EAAEN,iBAAiB,CAAC,IAAIA;EAChF,CAAC,CAAC;AACJ","ignoreList":[]}

package/lib/module/navigation/chainCallbacks.js

@@ -0,0 +1,12 @@
+"use strict";
+
+/** Runs two optional callbacks in sequence, forwarding the same arguments. */
+export function chainCallbacks(first, second) {
+  if (!first) return second;
+  if (!second) return first;
+  return (...args) => {
+    first(...args);
+    second(...args);
+  };
+}
+//# sourceMappingURL=chainCallbacks.js.map

package/lib/module/navigation/chainCallbacks.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["chainCallbacks","first","second","args"],"sourceRoot":"../../../src","sources":["navigation/chainCallbacks.ts"],"mappings":";;AAAA;AACA,OAAO,SAASA,cAAcA,CAC5BC,KAAyC,EACzCC,MAA0C,EACN;EACpC,IAAI,CAACD,KAAK,EAAE,OAAOC,MAAM;EACzB,IAAI,CAACA,MAAM,EAAE,OAAOD,KAAK;EACzB,OAAO,CAAC,GAAGE,IAAO,KAAK;IACrBF,KAAK,CAAC,GAAGE,IAAI,CAAC;IACdD,MAAM,CAAC,GAAGC,IAAI,CAAC;EACjB,CAAC;AACH","ignoreList":[]}

package/lib/module/navigation/getActiveRouteName.js

@@ -0,0 +1,14 @@
+"use strict";
+
+/** Returns the deepest active route name from a React Navigation state tree. */
+export function getActiveRouteName(state) {
+  if (!state) return undefined;
+  const index = state.index ?? 0;
+  const route = state.routes[index];
+  if (!route) return undefined;
+  if (route.state) {
+    return getActiveRouteName(route.state);
+  }
+  return route.name;
+}
+//# sourceMappingURL=getActiveRouteName.js.map

package/lib/module/navigation/getActiveRouteName.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["getActiveRouteName","state","undefined","index","route","routes","name"],"sourceRoot":"../../../src","sources":["navigation/getActiveRouteName.ts"],"mappings":";;AAIA;AACA,OAAO,SAASA,kBAAkBA,CAACC,KAAgC,EAAsB;EACvF,IAAI,CAACA,KAAK,EAAE,OAAOC,SAAS;EAE5B,MAAMC,KAAK,GAAGF,KAAK,CAACE,KAAK,IAAI,CAAC;EAC9B,MAAMC,KAAK,GAAGH,KAAK,CAACI,MAAM,CAACF,KAAK,CAAC;EACjC,IAAI,CAACC,KAAK,EAAE,OAAOF,SAAS;EAE5B,IAAIE,KAAK,CAACH,KAAK,EAAE;IACf,OAAOD,kBAAkB,CAACI,KAAK,CAACH,KAAK,CAAC;EACxC;EAEA,OAAOG,KAAK,CAACE,IAAI;AACnB","ignoreList":[]}

package/lib/module/navigation/index.js

@@ -0,0 +1,5 @@
+"use strict";
+
+export { WithUserflowReactNavigation } from "./WithUserflowReactNavigation.js";
+export { openFlowNavigateUrl, setHostOnNavigate, setReactNavigationRef, setExpoRouterNavigator, isExternalNavigateUrl, isInAppNavigateUrl } from "./openFlowNavigateUrl.js";
+//# sourceMappingURL=index.js.map

package/lib/module/navigation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["WithUserflowReactNavigation","openFlowNavigateUrl","setHostOnNavigate","setReactNavigationRef","setExpoRouterNavigator","isExternalNavigateUrl","isInAppNavigateUrl"],"sourceRoot":"../../../src","sources":["navigation/index.ts"],"mappings":";;AAAA,SAASA,2BAA2B,QAAQ,kCAA+B;AAE3E,SACEC,mBAAmB,EACnBC,iBAAiB,EACjBC,qBAAqB,EACrBC,sBAAsB,EACtBC,qBAAqB,EACrBC,kBAAkB,QACb,0BAAuB","ignoreList":[]}

package/lib/module/navigation/openFlowNavigateUrl.js

@@ -0,0 +1,100 @@
+"use strict";
+
+import { Linking } from 'react-native';
+import { isSafeUrl, openSafeUrl } from "../content/openSafeUrl.js";
+let hostOnNavigate = null;
+let navigationRef = null;
+let expoRouter = null;
+
+/** Optional host escape hatch — wins over router / Linking when set. */
+export function setHostOnNavigate(handler) {
+  hostOnNavigate = handler ?? null;
+}
+
+/** Register the React Navigation container used by {@link WithUserflowReactNavigation}. */
+export function setReactNavigationRef(ref) {
+  navigationRef = ref ?? null;
+}
+
+/** Register Expo Router push for path-like NAVIGATE actions. */
+export function setExpoRouterNavigator(router) {
+  expoRouter = router ?? null;
+}
+
+/** True for http(s) / mailto / tel (external). */
+export function isExternalNavigateUrl(url) {
+  return isSafeUrl(url);
+}
+
+/** Path-like in-app URL: leading slash, or no scheme. */
+export function isInAppNavigateUrl(url) {
+  const trimmed = url.trim();
+  if (!trimmed) return false;
+  if (isExternalNavigateUrl(trimmed)) return false;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return false;
+  return true;
+}
+function normalizeInAppPath(url) {
+  const trimmed = url.trim();
+  if (trimmed.startsWith('/')) return trimmed;
+  return `/${trimmed}`;
+}
+function routeNameFromPath(path) {
+  const normalized = normalizeInAppPath(path).replace(/^\//, '');
+  const [first] = normalized.split(/[/?#]/);
+  return first || normalized;
+}
+
+/**
+ * Open a flow NAVIGATE url.
+ *
+ * Priority:
+ * 1. Host `onNavigate` (custom schemes / exotic routing)
+ * 2. External allowlisted schemes → Linking / `openSafeUrl`
+ * 3. Path-like → Expo Router `push` or React Navigation `navigate`
+ * 4. Fallback → Linking (best-effort)
+ *
+ * Note: screen tracking ≠ action routing. React Navigation hosts must wrap with
+ * `WithUserflowReactNavigation` for in-app NAVIGATE; Expo Router apps get a
+ * navigator handle when the host mounts `UserflowExpoRouterScreenTracker` from
+ * `@userflow-tech/react-native/expo-router` under `UserflowProvider`.
+ */
+export async function openFlowNavigateUrl(url) {
+  const trimmed = url.trim();
+  if (!trimmed) return;
+  if (hostOnNavigate) {
+    await hostOnNavigate(trimmed);
+    return;
+  }
+  if (isExternalNavigateUrl(trimmed)) {
+    await openSafeUrl(trimmed);
+    return;
+  }
+  if (isInAppNavigateUrl(trimmed)) {
+    if (expoRouter) {
+      expoRouter.push(normalizeInAppPath(trimmed));
+      return;
+    }
+    if (navigationRef?.isReady()) {
+      const name = routeNameFromPath(trimmed);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- route names are host-defined
+      navigationRef.navigate(name);
+      return;
+    }
+  }
+
+  // Last resort — may fail for custom schemes; hosts should set onNavigate.
+  try {
+    await Linking.openURL(trimmed);
+  } catch {
+    // Best-effort.
+  }
+}
+
+/** @internal */
+export function resetFlowNavigateRegistryForTests() {
+  hostOnNavigate = null;
+  navigationRef = null;
+  expoRouter = null;
+}
+//# sourceMappingURL=openFlowNavigateUrl.js.map

package/lib/module/navigation/openFlowNavigateUrl.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Linking","isSafeUrl","openSafeUrl","hostOnNavigate","navigationRef","expoRouter","setHostOnNavigate","handler","setReactNavigationRef","ref","setExpoRouterNavigator","router","isExternalNavigateUrl","url","isInAppNavigateUrl","trimmed","trim","test","normalizeInAppPath","startsWith","routeNameFromPath","path","normalized","replace","first","split","openFlowNavigateUrl","push","isReady","name","navigate","openURL","resetFlowNavigateRegistryForTests"],"sourceRoot":"../../../src","sources":["navigation/openFlowNavigateUrl.ts"],"mappings":";;AACA,SAASA,OAAO,QAAQ,cAAc;AAEtC,SAASC,SAAS,EAAEC,WAAW,QAAQ,2BAAwB;AAQ/D,IAAIC,cAA0C,GAAG,IAAI;AACrD,IAAIC,aAA2D,GAAG,IAAI;AACtE,IAAIC,UAAiC,GAAG,IAAI;;AAE5C;AACA,OAAO,SAASC,iBAAiBA,CAACC,OAA+C,EAAQ;EACvFJ,cAAc,GAAGI,OAAO,IAAI,IAAI;AAClC;;AAEA;AACA,OAAO,SAASC,qBAAqBA,CACnCC,GAA6D,EACvD;EACNL,aAAa,GAAGK,GAAG,IAAI,IAAI;AAC7B;;AAEA;AACA,OAAO,SAASC,sBAAsBA,CAACC,MAAyC,EAAQ;EACtFN,UAAU,GAAGM,MAAM,IAAI,IAAI;AAC7B;;AAEA;AACA,OAAO,SAASC,qBAAqBA,CAACC,GAAW,EAAW;EAC1D,OAAOZ,SAAS,CAACY,GAAG,CAAC;AACvB;;AAEA;AACA,OAAO,SAASC,kBAAkBA,CAACD,GAAW,EAAW;EACvD,MAAME,OAAO,GAAGF,GAAG,CAACG,IAAI,CAAC,CAAC;EAC1B,IAAI,CAACD,OAAO,EAAE,OAAO,KAAK;EAC1B,IAAIH,qBAAqB,CAACG,OAAO,CAAC,EAAE,OAAO,KAAK;EAChD,IAAI,sBAAsB,CAACE,IAAI,CAACF,OAAO,CAAC,EAAE,OAAO,KAAK;EACtD,OAAO,IAAI;AACb;AAEA,SAASG,kBAAkBA,CAACL,GAAW,EAAU;EAC/C,MAAME,OAAO,GAAGF,GAAG,CAACG,IAAI,CAAC,CAAC;EAC1B,IAAID,OAAO,CAACI,UAAU,CAAC,GAAG,CAAC,EAAE,OAAOJ,OAAO;EAC3C,OAAO,IAAIA,OAAO,EAAE;AACtB;AAEA,SAASK,iBAAiBA,CAACC,IAAY,EAAU;EAC/C,MAAMC,UAAU,GAAGJ,kBAAkB,CAACG,IAAI,CAAC,CAACE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;EAC9D,MAAM,CAACC,KAAK,CAAC,GAAGF,UAAU,CAACG,KAAK,CAAC,OAAO,CAAC;EACzC,OAAOD,KAAK,IAAIF,UAAU;AAC5B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,eAAeI,mBAAmBA,CAACb,GAAW,EAAiB;EACpE,MAAME,OAAO,GAAGF,GAAG,CAACG,IAAI,CAAC,CAAC;EAC1B,IAAI,CAACD,OAAO,EAAE;EAEd,IAAIZ,cAAc,EAAE;IAClB,MAAMA,cAAc,CAACY,OAAO,CAAC;IAC7B;EACF;EAEA,IAAIH,qBAAqB,CAACG,OAAO,CAAC,EAAE;IAClC,MAAMb,WAAW,CAACa,OAAO,CAAC;IAC1B;EACF;EAEA,IAAID,kBAAkB,CAACC,OAAO,CAAC,EAAE;IAC/B,IAAIV,UAAU,EAAE;MACdA,UAAU,CAACsB,IAAI,CAACT,kBAAkB,CAACH,OAAO,CAAC,CAAC;MAC5C;IACF;IACA,IAAIX,aAAa,EAAEwB,OAAO,CAAC,CAAC,EAAE;MAC5B,MAAMC,IAAI,GAAGT,iBAAiB,CAACL,OAAO,CAAC;MACvC;MACCX,aAAa,CAA2C0B,QAAQ,CAACD,IAAW,CAAC;MAC9E;IACF;EACF;;EAEA;EACA,IAAI;IACF,MAAM7B,OAAO,CAAC+B,OAAO,CAAChB,OAAO,CAAC;EAChC,CAAC,CAAC,MAAM;IACN;EAAA;AAEJ;;AAEA;AACA,OAAO,SAASiB,iCAAiCA,CAAA,EAAS;EACxD7B,cAAc,GAAG,IAAI;EACrBC,aAAa,GAAG,IAAI;EACpBC,UAAU,GAAG,IAAI;AACnB","ignoreList":[]}

package/lib/module/network.js

@@ -0,0 +1,85 @@
+"use strict";
+
+/**
+ * Network reachability → eager liveness check (optional enhancement).
+ *
+ * When connectivity returns while the app is foregrounded (and the transport is
+ * not suspended), call {@link NetworkControllerDeps.ensureAlive} so we do not
+ * wait for the adaptive heartbeat / foreground probe to notice the drop.
+ * `ensureAlive` probes a still-open (possibly half-dead) socket and reconnects
+ * eagerly when the transport is already dropped — covering both cases.
+ *
+ * This is layered on top of a complete zero-dependency recovery path (socket
+ * close → reconnect ladder, adaptive heartbeat, and the foreground liveness
+ * probe). `@react-native-community/netinfo` is therefore an *optional* peer: when
+ * present it makes offline→online recovery fast; when absent the baseline still
+ * recovers within a few seconds of the next beat / foreground return.
+ */
+
+function isOnline(status) {
+  return status.isConnected === true && status.isInternetReachable !== false;
+}
+function defaultSubscribe(handler) {
+  // Lazy require so the SDK works without the optional peer. When installed,
+  // NetInfo makes offline→online reconnect fast; when absent the transport's
+  // adaptive heartbeat + foreground probe still recover the connection.
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- optional peer at import time
+    const NetInfo = require('@react-native-community/netinfo');
+    return NetInfo.addEventListener(state => {
+      handler({
+        isConnected: state.isConnected,
+        isInternetReachable: state.isInternetReachable
+      });
+    });
+  } catch {
+    if (__DEV__) {
+      // eslint-disable-next-line no-console -- intentional missing-optional-peer diagnostic
+      console.warn('[Userflow] Optional peer @react-native-community/netinfo is not installed; ' + 'skipping instant network-aware reconnect. Connection recovery still works ' + 'via the adaptive heartbeat and foreground liveness probe.');
+    }
+    return () => {};
+  }
+}
+
+/**
+ * Owns the NetInfo subscription. Call {@link start} from `Userflow.init` and
+ * {@link stop} from `Userflow.teardown`.
+ */
+export class NetworkController {
+  unsubscribe = null;
+  started = false;
+  wasOnline = null;
+  constructor(deps) {
+    this.ensureAlive = deps.ensureAlive;
+    this.subscribe = deps.subscribe ?? defaultSubscribe;
+  }
+  start() {
+    if (this.started) return;
+    this.started = true;
+    this.unsubscribe = this.subscribe(status => {
+      this.handleStatus(status);
+    });
+  }
+  stop() {
+    if (!this.started) return;
+    this.started = false;
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    this.wasOnline = null;
+  }
+
+  /** Visible for tests. */
+  handleStatus(status) {
+    if (!this.started) return;
+    const online = isOnline(status);
+    const previous = this.wasOnline;
+    this.wasOnline = online;
+
+    // First sample only seeds state — do not reconnect on start.
+    if (previous === null) return;
+    if (!previous && online) {
+      this.ensureAlive();
+    }
+  }
+}
+//# sourceMappingURL=network.js.map

package/lib/module/network.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isOnline","status","isConnected","isInternetReachable","defaultSubscribe","handler","NetInfo","require","addEventListener","state","__DEV__","console","warn","NetworkController","unsubscribe","started","wasOnline","constructor","deps","ensureAlive","subscribe","start","handleStatus","stop","online","previous"],"sourceRoot":"../../src","sources":["network.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAcA,SAASA,QAAQA,CAACC,MAAqB,EAAW;EAChD,OAAOA,MAAM,CAACC,WAAW,KAAK,IAAI,IAAID,MAAM,CAACE,mBAAmB,KAAK,KAAK;AAC5E;AAEA,SAASC,gBAAgBA,CAACC,OAAwC,EAAc;EAC9E;EACA;EACA;EACA,IAAI;IACF;IACA,MAAMC,OAAO,GAAGC,OAAO,CAAC,iCAAiC,CAOxD;IACD,OAAOD,OAAO,CAACE,gBAAgB,CAAEC,KAAK,IAAK;MACzCJ,OAAO,CAAC;QACNH,WAAW,EAAEO,KAAK,CAACP,WAAW;QAC9BC,mBAAmB,EAAEM,KAAK,CAACN;MAC7B,CAAC,CAAC;IACJ,CAAC,CAAC;EACJ,CAAC,CAAC,MAAM;IACN,IAAIO,OAAO,EAAE;MACX;MACAC,OAAO,CAACC,IAAI,CACV,6EAA6E,GAC3E,4EAA4E,GAC5E,2DACJ,CAAC;IACH;IACA,OAAO,MAAM,CAAC,CAAC;EACjB;AACF;;AAEA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,CAAC;EAIrBC,WAAW,GAAwB,IAAI;EACvCC,OAAO,GAAG,KAAK;EACfC,SAAS,GAAmB,IAAI;EAExCC,WAAWA,CAACC,IAA2B,EAAE;IACvC,IAAI,CAACC,WAAW,GAAGD,IAAI,CAACC,WAAW;IACnC,IAAI,CAACC,SAAS,GAAGF,IAAI,CAACE,SAAS,IAAIhB,gBAAgB;EACrD;EAEAiB,KAAKA,CAAA,EAAS;IACZ,IAAI,IAAI,CAACN,OAAO,EAAE;IAClB,IAAI,CAACA,OAAO,GAAG,IAAI;IACnB,IAAI,CAACD,WAAW,GAAG,IAAI,CAACM,SAAS,CAAEnB,MAAM,IAAK;MAC5C,IAAI,CAACqB,YAAY,CAACrB,MAAM,CAAC;IAC3B,CAAC,CAAC;EACJ;EAEAsB,IAAIA,CAAA,EAAS;IACX,IAAI,CAAC,IAAI,CAACR,OAAO,EAAE;IACnB,IAAI,CAACA,OAAO,GAAG,KAAK;IACpB,IAAI,CAACD,WAAW,GAAG,CAAC;IACpB,IAAI,CAACA,WAAW,GAAG,IAAI;IACvB,IAAI,CAACE,SAAS,GAAG,IAAI;EACvB;;EAEA;EACAM,YAAYA,CAACrB,MAAqB,EAAQ;IACxC,IAAI,CAAC,IAAI,CAACc,OAAO,EAAE;IAEnB,MAAMS,MAAM,GAAGxB,QAAQ,CAACC,MAAM,CAAC;IAC/B,MAAMwB,QAAQ,GAAG,IAAI,CAACT,SAAS;IAC/B,IAAI,CAACA,SAAS,GAAGQ,MAAM;;IAEvB;IACA,IAAIC,QAAQ,KAAK,IAAI,EAAE;IACvB,IAAI,CAACA,QAAQ,IAAID,MAAM,EAAE;MACvB,IAAI,CAACL,WAAW,CAAC,CAAC;IACpB;EACF;AACF","ignoreList":[]}