@wireai/activation 0.1.0 → 0.2.0

package/src/session-analytics/useLifecycleEvents.ts

@@ -0,0 +1,184 @@
+/**
+ * useLifecycleEvents — the batteries-included React hook that wires the TOP-OF-FUNNEL lifecycle
+ * events in ONE place: `app.first_open` (once ever) on mount, and `app.session_started` on every
+ * real app-open, both offline-buffered through the Brief-01 event queue.
+ *
+ * ONE emitter, one guard, no double-emit: session-start goes through the EXISTING
+ * {@link reportSessionStart} emitter (routed via a `sink`), NOT a second session emitter — so a
+ * host must use EITHER this hook OR `useSessionStart`, never both (both would fire an app-open).
+ * The once-per-open guard dedupes re-renders within this hook.
+ *
+ * Firing moments mirror {@link useSessionStart} exactly:
+ *   • ON MOUNT — the app opened (cold start / provider first render). `app.first_open` fires here
+ *     too (once ever, gated by the persisted flag in `reportFirstOpen`).
+ *   • ON FOREGROUND after a real background of at least {@link BACKGROUND_SESSION_MS} (30 min) — a
+ *     new app-open, so a fresh `app.session_started` fires. A quick app-switch does NOT count.
+ *
+ * OFFLINE-FIRST by default: pass your shared {@link EventQueue}'s `enqueue` as `options.sink` to
+ * route both events through your one queue. If you pass no sink, the hook lazily creates its OWN
+ * offline queue (dedicated storage key, so it never collides with your main queue) from the config
+ * + storage. Either way lifecycle events are buffered + persisted + retried, never lost offline.
+ *
+ * Dependency policy: `AppState` + `Platform` are RN built-ins (no new dep); the device snapshot is
+ * the kit's own dependency-free `collectDeviceContext()`; the queue is the dependency-free Brief-01
+ * `createEventQueue`. The pure `reportFirstOpen` / `wireLifecycleEvents` (in lifecycle.ts) import no
+ * React — this hook is the only React surface.
+ */
+import { useEffect, useRef } from "react";
+import { AppState, Platform, type AppStateStatus } from "react-native";
+
+import { createEventQueue, type EnvelopeSource, type EventQueue } from "../analytics/eventQueue";
+import type { ClientEvent, ClientEventTarget } from "../analytics/reportClientEvent";
+import { collectDeviceContext } from "../device/deviceContext";
+import type { WireOnboardingStorage } from "../session/persistedSession";
+import { reportFirstOpen } from "./lifecycle";
+import { reportSessionStart } from "./reportSessionStart";
+import { BACKGROUND_SESSION_MS } from "./useSessionStart";
+
+/** Tenant transport + host persistence for the lifecycle wiring. Same creds as `WireOnboardingConfig`. */
+export interface LifecycleConfig {
+  /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+  serverUrl?: string;
+  /** Tenant API key; sent as `Authorization: Bearer`. */
+  apiKey?: string;
+  /** Host app version (e.g. "1.4.2"), forwarded for release segmentation. Optional. */
+  appVersion?: string;
+  /** Tenant/app id — namespaces the first-open flag AND the hook's internal queue storage key. */
+  appId?: string;
+  /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag AND the
+   *  offline durability of the hook's internal queue. Omit it and both degrade to in-memory. */
+  storage?: WireOnboardingStorage;
+}
+
+/** Per-open identity + wiring the host supplies. All optional: a pre-auth open is device-only. */
+export interface UseLifecycleEventsOptions {
+  /** The host's opaque pseudonymous user id (NOT PII). Omitted before the user authenticates. */
+  userId?: string;
+  /** The host's local open-counter value for this open. Drives `returning` + "Nth session". */
+  sessionCount?: number;
+  /** A stable, non-PII device id the host owns. Groups this device's sessions server-side. */
+  deviceKey?: string;
+  /** Small non-PII extras forwarded on the event `meta`. */
+  meta?: Record<string, unknown>;
+  /** Set `false` to disable firing (e.g. behind a consent gate). Default enabled. */
+  enabled?: boolean;
+  /**
+   * Explicit transport sink (e.g. an existing shared `EventQueue.enqueue`). When provided, BOTH
+   * lifecycle events route here and the hook does NOT create its own queue — pass this to share ONE
+   * offline queue across the kit's analytics (screen tracking + lifecycle).
+   */
+  sink?: (event: ClientEvent) => void;
+  /**
+   * Context envelope (or provider) for the hook's internally-created queue. Ignored when `sink` is
+   * supplied (the host's queue owns envelope stamping).
+   */
+  envelope?: EnvelopeSource;
+}
+
+/**
+ * Fire `app.first_open` (once ever) + `app.session_started` (per open), offline-buffered. Returns
+ * nothing — a side-effecting hook. Safe to call with inline options (read through a ref, so
+ * changing `userId`/`sessionCount` never re-fires a session).
+ */
+export const useLifecycleEvents = (
+  config: LifecycleConfig | undefined,
+  options: UseLifecycleEventsOptions = {},
+): void => {
+  // Latest options/config through a ref so the mount/resume fires read fresh values without listing
+  // them as effect deps (which would re-fire a session on every prop change).
+  const latest = useRef({ config, options });
+  latest.current = { config, options };
+
+  // The resolved sink is created at most once and reused for every fire this mount.
+  const queueRef = useRef<EventQueue | undefined>(undefined);
+
+  useEffect(() => {
+    const resolveSink = (): ((event: ClientEvent) => void) | undefined => {
+      const { config: cfg, options: opts } = latest.current;
+      // Host-owned shared queue wins — one queue across the whole kit.
+      if (opts.sink) return opts.sink;
+      // No transport → no sink (events no-op rather than buffer forever against a dead target).
+      if (!cfg?.serverUrl) return undefined;
+      if (!queueRef.current) {
+        queueRef.current = createEventQueue({
+          target: { serverUrl: cfg.serverUrl, apiKey: cfg.apiKey ?? "" },
+          storage: cfg.storage,
+          // Dedicated key so the hook's internal queue never collides with a host's main queue.
+          storageKey: `wireai:evtq:lifecycle:${cfg.appId ?? "default"}`,
+          envelope: opts.envelope,
+        });
+      }
+      return queueRef.current.enqueue;
+    };
+
+    const targetOf = (cfg: LifecycleConfig | undefined): ClientEventTarget | undefined =>
+      cfg?.serverUrl ? { serverUrl: cfg.serverUrl, apiKey: cfg.apiKey ?? "" } : undefined;
+
+    // 1) first_open — once ever (persisted flag + in-memory latch inside reportFirstOpen).
+    {
+      const { config: cfg, options: opts } = latest.current;
+      if (opts.enabled !== false) {
+        const device = collectDeviceContext();
+        if (cfg?.appVersion && !device.appVersion) device.appVersion = cfg.appVersion;
+        reportFirstOpen({
+          target: targetOf(cfg),
+          sink: resolveSink(),
+          storage: cfg?.storage,
+          appId: cfg?.appId,
+          userId: opts.userId,
+          deviceKey: opts.deviceKey,
+          sessionCount: opts.sessionCount,
+          appVersion: cfg?.appVersion ?? device.appVersion,
+          platform: Platform.OS,
+          device,
+          meta: opts.meta,
+        });
+      }
+    }
+
+    // 2) session_start — the EXISTING emitter routed through the sink (offline-buffered, one guard).
+    const fireSession = () => {
+      const { config: cfg, options: opts } = latest.current;
+      if (opts.enabled === false) return;
+      if (!cfg?.serverUrl && !opts.sink) return;
+      const device = collectDeviceContext();
+      if (cfg?.appVersion && !device.appVersion) device.appVersion = cfg.appVersion;
+      reportSessionStart({
+        target: targetOf(cfg),
+        sink: resolveSink(),
+        // A fresh per-open id each fire; the emitter's once-guard dedupes within the open.
+        userId: opts.userId,
+        deviceKey: opts.deviceKey,
+        sessionCount: opts.sessionCount,
+        appVersion: cfg?.appVersion ?? device.appVersion,
+        platform: Platform.OS,
+        device,
+        meta: opts.meta,
+      });
+    };
+
+    // Mount = an app-open.
+    fireSession();
+
+    // Foreground after a real background = a new app-open.
+    let backgroundedAt: number | null = null;
+    const onChange = (state: AppStateStatus) => {
+      if (state === "background" || state === "inactive") {
+        if (backgroundedAt == null) backgroundedAt = Date.now();
+        return;
+      }
+      if (state === "active") {
+        const since = backgroundedAt;
+        backgroundedAt = null;
+        if (since != null && Date.now() - since >= BACKGROUND_SESSION_MS) fireSession();
+      }
+    };
+    const sub = AppState.addEventListener("change", onChange);
+    return () => {
+      // RN >= 0.65 returns a subscription with remove(); guard for older shims.
+      if (sub && typeof (sub as { remove?: () => void }).remove === "function") sub.remove();
+    };
+    // Mount-only effect: firing reads fresh values via `latest`, so no reactive deps.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+};

package/src/showcase/index.ts

@@ -1,5 +1,5 @@
 /**
- * wireai-onboarding/showcase — the pre-onboarding feature showcase ("app intro").
+ * @wireai/activation/showcase — the pre-onboarding feature showcase ("app intro").
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-
  * free: importing this pulls in the optional peer
@@ -7,7 +7,7 @@
  * `react-native-reanimated`). The app supplies a declarative ShowcaseConfig; the
  * kit bakes in the Wire theme + optional per-slide gesture hand and gates once.
  *
- *   import { FeatureShowcase, selectShowcaseSlides } from "wireai-onboarding/showcase";
+ *   import { FeatureShowcase, selectShowcaseSlides } from "@wireai/activation/showcase";
  */
 export { FeatureShowcase } from "./FeatureShowcase";
 export { selectShowcaseSlides } from "./selectShowcaseSlides";

package/src/types.ts

@@ -1,5 +1,5 @@
 /**
- * Public types for the wireai-onboarding kit.
+ * Public types for the @wireai/activation kit.
  */
 import type { Message } from "wireai-rn";
 import type { OnboardingTheme } from "./theme/types";