@wireai/activation 0.1.0 → 0.1.1

package/llms.txt

@@ -1,4 +1,4 @@
-# wireai-onboarding
+# @wireai/activation
 
 > A drop-in AI onboarding kit for React Native / Expo. One component, `<WireOnboarding>`, runs an
 > entire backend-orchestrated, AI-driven onboarding flow (themed cards, progress bar, a mid-flow
@@ -8,12 +8,12 @@
 
 ## What an agent needs to know
 
-- **Install:** `npm install wireai-onboarding wireai-rn` (react + react-native are peers).
-- **Metro (required):** `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` from `wireai-onboarding/metro` — pins one copy of react/react-native/wireai-rn/zod (prevents the dual-React crash).
+- **Install:** `npm install @wireai/activation wireai-rn` (react + react-native are peers).
+- **Metro (required):** `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` from `@wireai/activation/metro`, which pins one copy of react/react-native/wireai-rn/zod (prevents the dual-React crash).
 - **Two secrets:** an app `apiKey` (a `wai_…` key that resolves the tenant server-side) and the backend `serverUrl`. Created in the getwireai console or via the backend's `register_<app>.py`. Nothing renders without both.
 - **Render:** drop `<WireOnboarding config={wireConfigFromEnv({ appId })} theme={...} onComplete={persist} fallbackFlow={<YourStaticOnboarding/>} />` into the signup flow.
-- **Capture is deterministic** — `onComplete` returns `{ answers, raw }`; no second LLM call. Persist all answers through the app's normal profile-update path.
-- **It can never break onboarding** — pass `fallbackFlow` (your existing static onboarding) so a backend error/timeout degrades instead of dead-ending.
+- **Capture is deterministic.** `onComplete` returns `{ answers, raw }`; no second LLM call. Persist all answers through the app's normal profile-update path.
+- **It can never break onboarding.** Pass `fallbackFlow` (your existing static onboarding) so a backend error/timeout degrades instead of dead-ending.
 
 ## Helpers (the reusable substrate)
 
@@ -21,7 +21,7 @@
 - `isOnboardingEnabled({ remote? })` → the standard gate (transport present: apiKey + serverUrl). No on/off env flag; `remote` is an optional kill-switch the app passes in.
 - `WIRE_ONBOARDING_EVENTS` + `toAnalyticsEvent(event)` → canonical `wire_onboarding_*` funnel names; log via the app's own analytics.
 - `attributionMetadata(a)` → shape install/ad attribution into `config.metadata` (forwarded to the agent).
-- `reportClientEvent` / `makeSessionId` → report device-only funnel events to `POST /v1/events`. `<WireOnboarding>` does this automatically: `dropped` on unmount-without-complete, `client_fallback` on degrade-to-static. Hosts must not double-report fallback.
+- `reportClientEvent(target, event)` / `reportClientEvents` / `makeSessionId` (ROOT-exported, not a subpath) → report device-only funnel events. Contract: `POST {serverUrl}/v1/events`, header `Authorization: Bearer {apiKey}`, body `{ "events": [ ... ] }`; `target = { serverUrl, apiKey }` from the config. `<WireOnboarding>` does this automatically: `dropped` on unmount-without-complete, `client_fallback` on degrade-to-static. Hosts must not double-report fallback.
 - `deriveAnswers(messages)`, `themeFromBrand({ primary })`, `defaultIllustrations`, `DemoOnboarding` (dev/QA, no account).
 
 ## Files
@@ -33,4 +33,4 @@
 
 ## Fastest path
 
-Run the `wire-rn-integration` Claude skill — it detects the app's conventions, wires Metro, derives a theme, scaffolds the screen, wires a fallback, and type-checks. Otherwise use INTEGRATION_PROMPT.md.
+Run the `wire-rn-integration` Claude skill. It detects the app's conventions, wires Metro, derives a theme, scaffolds the screen, wires a fallback, and type-checks. Otherwise use INTEGRATION_PROMPT.md.

package/metro/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Type declarations for the `wireai-onboarding/metro` helper. This module runs in
+ * Type declarations for the `@wireai/activation/metro` helper. This module runs in
  * Node inside metro.config.js, so the config is loosely typed (`any`-ish) to avoid
  * coupling to a specific Metro/Expo version.
  */
@@ -11,7 +11,7 @@ export interface WithWireOnboardingOptions {
    */
   appRoot?: string;
   /**
-   * Absolute path to the kit's `src/` dir. When set, the `wireai-onboarding`
+   * Absolute path to the kit's `src/` dir. When set, the `@wireai/activation`
    * specifier maps here (source consumption) and the dir is added to watchFolders.
    * When omitted, the kit resolves from the installed package.
    */
@@ -19,7 +19,7 @@ export interface WithWireOnboardingOptions {
 }
 
 /**
- * Non-destructively wire the wireai-onboarding kit into an existing Metro config:
+ * Non-destructively wire the @wireai/activation kit into an existing Metro config:
  * pins single-instance deps to the app's copy, optionally maps the kit specifier
  * to source + watches it. Mutates and returns the same config object.
  */

package/metro/index.js

@@ -1,5 +1,5 @@
 /**
- * withWireOnboarding — one-call Metro wiring for the wireai-onboarding kit.
+ * withWireOnboarding — one-call Metro wiring for the @wireai/activation kit.
  *
  * This file runs in Node inside your app's `metro.config.js` (it is NOT React
  * Native code), so it's plain CommonJS with zero RN imports.
@@ -10,13 +10,13 @@
  *
  *   // External app (kit installed from git/tarball):
  *   const { getDefaultConfig } = require('expo/metro-config');
- *   const { withWireOnboarding } = require('wireai-onboarding/metro');
+ *   const { withWireOnboarding } = require('@wireai/activation/metro');
  *   module.exports = withWireOnboarding(getDefaultConfig(__dirname));
  *
  *   // Source consumer (monorepo app, kit resolved from its src/):
  *   const path = require('path');
  *   module.exports = withWireOnboarding(getDefaultConfig(__dirname), {
- *     source: path.join(__dirname, '../../getwire_ai/wireai-onboarding/src'),
+ *     source: path.join(__dirname, '../../wire-activation/src'),
  *   });
  *
  * @param {object} config  An existing Metro config object (e.g. from getDefaultConfig).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",
@@ -46,6 +46,20 @@
         "default": "./dist/index.js"
       }
     },
+    "./analytics": {
+      "react-native": {
+        "types": "./dist/analytics/index.d.ts",
+        "default": "./src/analytics/index.ts"
+      },
+      "import": {
+        "types": "./dist/analytics/index.d.mts",
+        "default": "./dist/analytics/index.mjs"
+      },
+      "require": {
+        "types": "./dist/analytics/index.d.ts",
+        "default": "./dist/analytics/index.js"
+      }
+    },
     "./coachmarks": {
       "react-native": {
         "types": "./dist/coachmarks/index.d.ts",

package/src/analytics/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @wireai/activation/analytics — the coherent analytics entry.
+ *
+ * Subpath export kept OUT of the main barrel so an analytics-only consumer never pulls in the
+ * onboarding / showcase / review UI (the kit's tree-shaking guarantee). It bundles the OPT-IN
+ * automatic screen-tracking helper with the pre-existing analytics primitives so a host has one
+ * import for "report app + onboarding events":
+ *
+ *   import { createScreenTracker, screenTrackingHandler, reportAppEvent } from "@wireai/activation/analytics";
+ *
+ * The screen-tracking core imports NO navigation library and NO React (the React glue is the thin
+ * `useScreenTracking` hook); `reportAppEvent` is pulled from `../reviews/transport` directly, not
+ * the `../reviews` barrel, to keep the review UI out of an analytics-only bundle.
+ */
+
+// ─── Automatic screen tracking (dependency-free core) ─────────────────────────
+export { createScreenTracker, getActiveRouteName, screenTrackingHandler } from "./screenTracking";
+export type {
+  ScreenTracker,
+  ScreenTrackerOptions,
+  NavigationStateLike,
+  NavigationRouteLike,
+} from "./screenTracking";
+
+// ─── The thin optional React hook over the core ───────────────────────────────
+export { useScreenTracking } from "./useScreenTracking";
+export type { NavigationRefLike } from "./useScreenTracking";
+
+// ─── The app-event transport this helper feeds (pure fetch, no review UI) ─────
+export { reportAppEvent } from "../reviews/transport";
+export type { ReportAppEventOptions } from "../reviews/transport";
+
+// ─── Device-only onboarding event reporters + session id seed ─────────────────
+export { reportClientEvent, reportClientEvents, makeSessionId } from "./reportClientEvent";
+export type { ClientEvent, ClientEventType, ClientEventTarget } from "./reportClientEvent";
+
+// ─── Canonical onboarding funnel names + kit-event mapper ──────────────────────
+export { WIRE_ONBOARDING_EVENTS, toAnalyticsEvent } from "./analyticsEvent";
+export type { WireOnboardingEventName, AnalyticsEvent } from "./analyticsEvent";

package/src/analytics/screenTracking.ts

@@ -0,0 +1,122 @@
+/**
+ * screenTracking — an OPT-IN, dependency-free automatic screen-view helper.
+ *
+ * Given the host app's navigation STATE (or a nav ref, via the useScreenTracking hook), this
+ * emits exactly ONE `screen` app-event per REAL screen change through the kit's existing
+ * `reportAppEvent` transport (`POST {serverUrl}/v1/events`, `event_type='app_event'`,
+ * `question_key='screen'`, `meta={ screen }`). Param-only changes and re-renders are de-duped
+ * away because we resolve and compare the route NAME only — never the params.
+ *
+ * Dependency-free core: this file imports NO navigation library. React-Navigation / expo-router
+ * are host concerns; the host supplies plain state objects and refs, typed structurally here
+ * (`NavigationStateLike`). It is also React-free — the optional React glue lives in
+ * `useScreenTracking.ts`. `reportAppEvent` is imported from the pure `../reviews/transport`
+ * module (NOT the `../reviews` barrel, which would drag the review UI into an analytics-only
+ * bundle and defeat tree-shaking).
+ *
+ * Privacy: only the route NAME ever leaves the device. Route params, query strings, and any
+ * user data are never read into the event. Fire-and-forget — this never throws into the UI.
+ */
+import { reportAppEvent } from "../reviews/transport";
+
+/** A single route inside a React-Navigation-shaped state (structural — no `@react-navigation`). */
+export interface NavigationRouteLike {
+  name: string;
+  /** A nested navigator's own state, when this route hosts one. */
+  state?: NavigationStateLike;
+  /** Route params are intentionally left `unknown` — this helper never reads them. */
+  params?: unknown;
+}
+
+/** A React-Navigation-shaped navigator state (structural type; no library import). */
+export interface NavigationStateLike {
+  /** Index of the active route within `routes`. */
+  index?: number;
+  routes?: NavigationRouteLike[];
+}
+
+/** Options for {@link createScreenTracker}. */
+export interface ScreenTrackerOptions {
+  /**
+   * Where to POST. `{ serverUrl, apiKey }` — same shape the kit's review/analytics config
+   * exposes. When omitted, the tracker still de-dups and fires `onScreen`, but sends nothing.
+   */
+  target?: { serverUrl: string; apiKey: string };
+  /** The onboarding/session id to correlate screen views with, when known. */
+  sessionId?: string;
+  /** A stable, non-PII device id — groups a device's sessions server-side. */
+  deviceKey?: string;
+  /** Called on every REAL screen change (after de-dup), before the network emit. */
+  onScreen?: (screen: string) => void;
+  /**
+   * Per-screen filter. Return `false` to skip the NETWORK emit for a screen (last-screen memory
+   * is still advanced + `onScreen` still fires) — e.g. to keep a sensitive route out of analytics.
+   */
+  shouldTrack?: (screen: string) => boolean;
+}
+
+/** The screen tracker returned by {@link createScreenTracker}. */
+export interface ScreenTracker {
+  /** Report the active screen. Ignores `undefined`/empty and de-dups repeats of the last screen. */
+  track: (screen: string | undefined) => void;
+  /** Clear the last-screen memory (e.g. on logout) so the next `track` always emits. */
+  reset: () => void;
+}
+
+/**
+ * Walk a React-Navigation-shaped state to the DEEPEST active route and return its NAME (never
+ * its params). Recurses `routes[index]` while a nested `.state` exists. Returns `undefined` for
+ * a missing/empty/malformed state — the caller treats that as "nothing to report".
+ */
+export const getActiveRouteName = (
+  state: NavigationStateLike | undefined,
+): string | undefined => {
+  let current: NavigationStateLike | undefined = state;
+  let name: string | undefined;
+  // Bounded by the finite nesting depth of a real navigator tree.
+  while (current && Array.isArray(current.routes) && current.routes.length > 0) {
+    const index = typeof current.index === "number" ? current.index : 0;
+    const route = current.routes[index];
+    if (!route) break;
+    name = route.name;
+    current = route.state;
+  }
+  return name;
+};
+
+/**
+ * Build a stateful screen tracker. `track` de-dups against the last reported screen so only a
+ * REAL change emits; `reset` clears that memory. Fire-and-forget throughout — a missing `target`
+ * skips the network but keeps the de-dup + `onScreen` behaviour intact.
+ */
+export const createScreenTracker = (options: ScreenTrackerOptions = {}): ScreenTracker => {
+  let lastScreen: string | undefined;
+  return {
+    track: (screen: string | undefined): void => {
+      if (!screen || screen === lastScreen) return;
+      lastScreen = screen;
+      options.onScreen?.(screen);
+      if (options.shouldTrack && !options.shouldTrack(screen)) return;
+      reportAppEvent(options.target, "screen", {
+        sessionId: options.sessionId,
+        deviceKey: options.deviceKey,
+        meta: { screen },
+      });
+    },
+    reset: (): void => {
+      lastScreen = undefined;
+    },
+  };
+};
+
+/**
+ * Adapt a tracker into a React-Navigation `onStateChange` handler — the one-place wiring:
+ *
+ *   <NavigationContainer onStateChange={screenTrackingHandler(tracker)}>
+ *
+ * It resolves the deepest active route name and hands it to `tracker.track` (which de-dups).
+ */
+export const screenTrackingHandler =
+  (tracker: ScreenTracker) =>
+  (state: NavigationStateLike | undefined): void =>
+    tracker.track(getActiveRouteName(state));

package/src/analytics/useScreenTracking.ts

@@ -0,0 +1,48 @@
+/**
+ * useScreenTracking — a THIN optional React hook over the pure screen-tracking core.
+ *
+ * It builds one tracker for the component's lifetime and subscribes to the host's navigation
+ * ref: it reports the current route on mount and on every `state` event, and unsubscribes on
+ * unmount. React is a REQUIRED peer of the kit, so importing it here is allowed; the hook adds
+ * NO navigation-library dependency — the ref is typed structurally (`NavigationRefLike`).
+ *
+ *   const navigationRef = useNavigationContainerRef(); // host's @react-navigation ref
+ *   useScreenTracking(navigationRef, { target, sessionId });
+ *   // ...<NavigationContainer ref={navigationRef}>
+ */
+import { useEffect, useRef } from "react";
+
+import { createScreenTracker, type ScreenTracker, type ScreenTrackerOptions } from "./screenTracking";
+
+/**
+ * The structural slice of a React-Navigation container ref this hook needs — no
+ * `@react-navigation` import. `getCurrentRoute` yields the active route; `addListener("state", …)`
+ * fires on every navigation state change and returns its own unsubscribe.
+ */
+export interface NavigationRefLike {
+  getCurrentRoute?: () => { name?: string } | undefined;
+  addListener?: (type: "state", callback: () => void) => () => void;
+}
+
+/**
+ * Subscribe screen tracking to a host navigation ref. Safe to call with a not-yet-ready ref
+ * (the effect no-ops until `addListener` exists). Returns nothing — it wires side effects only.
+ */
+export const useScreenTracking = (
+  navigationRef: NavigationRefLike | undefined,
+  options: ScreenTrackerOptions = {},
+): void => {
+  // One tracker per mount; kept in a ref so re-renders never rebuild the de-dup memory.
+  const trackerRef = useRef<ScreenTracker | undefined>(undefined);
+  if (!trackerRef.current) trackerRef.current = createScreenTracker(options);
+
+  useEffect(() => {
+    const tracker = trackerRef.current;
+    if (!tracker || !navigationRef?.addListener) return;
+    const report = (): void => tracker.track(navigationRef.getCurrentRoute?.()?.name);
+    report(); // initial screen on mount
+    const unsubscribe = navigationRef.addListener("state", report);
+    return unsubscribe;
+    // Re-subscribe only when the ref identity changes; option changes are read live off the closure.
+  }, [navigationRef]);
+};

package/src/coachmarks/index.ts

@@ -1,5 +1,5 @@
 /**
- * wireai-onboarding/coachmarks — the performance-first guided-tour engine.
+ * @wireai/activation/coachmarks — the performance-first guided-tour engine.
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-
  * free: importing this pulls in the optional peers `react-native-reanimated` and
@@ -9,7 +9,7 @@
  *
  *   import {
  *     CoachmarkProvider, useCoachmarkAnchor, useCoachmarkTour,
- *   } from "wireai-onboarding/coachmarks";
+ *   } from "@wireai/activation/coachmarks";
  */
 
 // ─── Root provider (mount once, around the NavigationContainer) ───────────────

package/src/features/WireFeaturesProvider.tsx

@@ -9,7 +9,7 @@
  *
  * NOTE on the built npm subpaths: React context is shared across the kit's subpath entries in the
  * SOURCE-consumption path (the monorepo apps) and in this test suite — one module instance, one
- * context. If you consume the built `wireai-onboarding/*` subpaths as separate bundles, pass the
+ * context. If you consume the built `@wireai/activation/*` subpaths as separate bundles, pass the
  * resolved flags (or a `featuresConfig`) to each surface explicitly instead of relying on context.
  */
 import React, { createContext, useContext, useMemo } from "react";

package/src/features/index.ts

@@ -1,12 +1,12 @@
 /**
- * wireai-onboarding feature controls — the per-module dashboard kill switches, consumed by the
+ * @wireai/activation feature controls — the per-module dashboard kill switches, consumed by the
  * kit with a HARD fail-open contract (a control-plane outage can never dark your app).
  *
  * These live in the CORE barrel (dependency-free: types + fetch + a React hook/provider). The
  * GATING is wired into the three client surfaces (coachmarks / showcase / reviews); onboarding
  * mode is server-owned, so the kit needs no gating there.
  *
- *   import { WireFeaturesProvider, fetchWireFeatures } from "wireai-onboarding";
+ *   import { WireFeaturesProvider, fetchWireFeatures } from "@wireai/activation";
  */
 export { fetchWireFeatures } from "./fetchWireFeatures";
 export { useWireFeatures } from "./useWireFeatures";

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * wireai-onboarding — premium, themable drop-in onboarding kit on top of the
+ * @wireai/activation — premium, themable drop-in onboarding kit on top of the
  * open-source wireai-rn SDK. Public surface.
  */
 

package/src/questionnaire/index.ts

@@ -1,5 +1,5 @@
 /**
- * wireai-onboarding/questionnaire - the skippable pre-onboarding questionnaire popup.
+ * @wireai/activation/questionnaire - the skippable pre-onboarding questionnaire popup.
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-free. The gate
  * asks one mandatory question ("what do you think about the app") plus two optional boxes,
@@ -8,7 +8,7 @@
  * at most once per user per questionnaire id. It reuses the shared `CenteredModal` shell (never
  * importing reviews/ internals for UI).
  *
- *   import { QuestionnaireGate, useQuestionnaireGate } from "wireai-onboarding/questionnaire";
+ *   import { QuestionnaireGate, useQuestionnaireGate } from "@wireai/activation/questionnaire";
  */
 
 // ─── The popup UI ───────────────────────────────────────────────────────────────

package/src/reviews/index.ts

@@ -1,5 +1,5 @@
 /**
- * wireai-onboarding/reviews — the in-app review sentiment gate.
+ * @wireai/activation/reviews — the in-app review sentiment gate.
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-free:
  * importing this pulls in the OPTIONAL peer `expo-store-review` (loaded lazily and only on
@@ -7,7 +7,7 @@
  * review and 1-4 to a feather-light feedback form POSTed to the Wire server, and decides
  * WHEN to show via local rules OR a server-provided decision (the AI seam).
  *
- *   import { ReviewGate, useReviewGate } from "wireai-onboarding/reviews";
+ *   import { ReviewGate, useReviewGate } from "@wireai/activation/reviews";
  */
 
 // ─── The gate UI ──────────────────────────────────────────────────────────────

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";