@wireai/activation 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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>",

package/src/analytics/analyticsFacade.ts

@@ -0,0 +1,171 @@
+/**
+ * analyticsFacade — a Segment/PostHog-shaped developer API (`track` / `screen` / `identify`)
+ * over the kit's OWN offline-first event queue. One package, one key, one line:
+ *
+ *   const analytics = createAnalytics({ serverUrl, apiKey, storage });
+ *   analytics.track("content_share", { source: "feed" });
+ *   analytics.screen("Home", { tab: "explore" });
+ *   analytics.identify("u_123", { plan: "pro" });
+ *
+ * WHY a façade: the primitives already exist (`createEventQueue` for durable offline-first
+ * transport, `buildContextEnvelope` for the non-PII device context, the `identify` client-event
+ * contract for user binding), but a host had to wire them together by hand. This composes them
+ * into the familiar analytics-SDK surface so a consumer gets the ergonomics with NO second
+ * install and NO second key — the same `{ serverUrl, apiKey }` creds as onboarding.
+ *
+ * ROUTING: every call builds a `ClientEvent` and `enqueue`s it. The queue stamps the context
+ * envelope (device + host scalars), persists offline, batches, retries, and dequeues on ack —
+ * so `track`/`screen`/`identify` inherit offline-first durability for free. `screen` routes
+ * through the SAME queue rather than the direct `reportAppEvent` POST (a deliberate upgrade:
+ * screen views survive being offline too).
+ *
+ * DEPENDENCY-FREE + TREE-SHAKEABLE: this module imports ONLY the queue, the envelope builder,
+ * the client-event types + session-id seed, and the identity sanitizer. It reaches NO
+ * onboarding / showcase / review UI, so an analytics-only consumer bundles none of it. React is
+ * absent here on purpose — the optional React glue is the thin `useAnalytics` hook.
+ *
+ * FIRE-AND-FORGET: no method throws into the UI or blocks — the queue already guarantees that.
+ */
+import { buildContextEnvelope, type ContextEnvelope } from "./contextEnvelope";
+import { createEventQueue, type EventQueue, type EventQueueOptions } from "./eventQueue";
+import { makeSessionId, type ClientEvent } from "./reportClientEvent";
+import { sanitizeUserId } from "../identity/userIdentity";
+
+/** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
+export type AnalyticsProps = Record<string, unknown>;
+
+/**
+ * Tenant transport + context inputs for {@link createAnalytics}. `serverUrl`/`apiKey` are the
+ * SAME creds as onboarding (never a second key). The rest feed the context envelope + the queue's
+ * offline persistence — all optional.
+ */
+export type CreateAnalyticsConfig = {
+  /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+  serverUrl: string;
+  /** Tenant API key; sent as `Authorization: Bearer`. */
+  apiKey: string;
+  /**
+   * Correlation id shared by every event from this instance (and the `identify` event). Defaults
+   * to a fresh `makeSessionId()` at creation so all events agree on one id per analytics instance.
+   */
+  sessionId?: string;
+  /** Tenant/app id used to namespace the queue's default storage key (`wireai:evtq:<appId>`). */
+  appId?: string;
+  /**
+   * Host persistence (AsyncStorage-compatible subset) for offline-first durability. When omitted,
+   * the queue runs in the documented in-memory mode (survives re-renders, not app kills).
+   */
+  storage?: EventQueueOptions["storage"];
+  /** Host app version, e.g. "1.4.2" (host-injected; stamped onto every event's context). */
+  appVersion?: string;
+  /** Host native build number, e.g. "412" (host-injected). */
+  appBuild?: string;
+  /** Host connectivity signal, e.g. "wifi" | "cellular" — read fresh per event via the provider. */
+  networkType?: string;
+};
+
+/** Optional queue tuning knobs, forwarded verbatim to {@link createEventQueue}. */
+export type AnalyticsOptions = Partial<
+  Pick<EventQueueOptions, "maxSize" | "batchSize" | "baseBackoffMs" | "maxBackoffMs" | "maxRetries">
+>;
+
+/**
+ * The developer-facing analytics surface. `track`/`screen`/`identify` are the Segment/PostHog-shaped
+ * API; `flush`/`notifyOnline`/`size` expose the underlying queue so a host can drive reconnect
+ * draining (load-bearing for offline-first) and inspect the pending buffer.
+ */
+export type Analytics = {
+  /** Record an in-app event: `event_type='app_event'`, `question_key=<event>`, `props`→`meta`. */
+  track(event: string, props?: AnalyticsProps): void;
+  /** Record a screen view: `event_type='app_event'`, `question_key='screen'`, `meta={ screen, ...props }`. */
+  screen(name: string, props?: AnalyticsProps): void;
+  /** Bind the host's opaque user id (per-session, in-memory) and emit an `identify` event. */
+  identify(userId: string, traits?: AnalyticsProps): void;
+  /** Attempt an immediate drain of the pending buffer. Fire-and-forget. */
+  flush(): void;
+  /** Host reconnect signal: reset backoff and drain now. Fire-and-forget. */
+  notifyOnline(): void;
+  /** Current pending (in-memory) count. */
+  size(): number;
+};
+
+/**
+ * Create a bound analytics instance. Seeds one correlation `sessionId`, builds an offline-first
+ * queue over the tenant transport, and passes a fresh-per-event context envelope PROVIDER so the
+ * connectivity type is read at enqueue time. The bound user id starts unset (see `identify`).
+ */
+export const createAnalytics = (
+  config: CreateAnalyticsConfig,
+  options: AnalyticsOptions = {},
+): Analytics => {
+  const sessionId = config.sessionId ?? makeSessionId();
+
+  // A provider (not a fixed value) so `networkType` is evaluated fresh on every enqueue.
+  const envelope = (): ContextEnvelope =>
+    buildContextEnvelope({
+      sessionId,
+      appVersion: config.appVersion,
+      appBuild: config.appBuild,
+      networkType: config.networkType,
+    });
+
+  const queue: EventQueue = createEventQueue({
+    target: { serverUrl: config.serverUrl, apiKey: config.apiKey },
+    storage: config.storage,
+    appId: config.appId,
+    envelope,
+    ...options,
+  });
+
+  // Per-session, in-memory user binding. Not persisted across launches (that is a follow-up).
+  let boundUserId: string | undefined;
+
+  const track = (event: string, props?: AnalyticsProps): void => {
+    if (!event) return;
+    const clientEvent: ClientEvent = {
+      event_type: "app_event",
+      session_id: sessionId,
+      question_key: event,
+    };
+    if (props && Object.keys(props).length > 0) clientEvent.meta = JSON.stringify(props);
+    if (boundUserId) clientEvent.user_id = boundUserId;
+    queue.enqueue(clientEvent);
+  };
+
+  const screen = (name: string, props?: AnalyticsProps): void => {
+    if (!name) return;
+    // Reuse the K6 screen event shape (question_key='screen'); route through the queue for offline-first.
+    const meta = { screen: name, ...(props ?? {}) };
+    const clientEvent: ClientEvent = {
+      event_type: "app_event",
+      session_id: sessionId,
+      question_key: "screen",
+      meta: JSON.stringify(meta),
+    };
+    if (boundUserId) clientEvent.user_id = boundUserId;
+    queue.enqueue(clientEvent);
+  };
+
+  const identify = (userId: string, traits?: AnalyticsProps): void => {
+    const clean = sanitizeUserId(userId);
+    // Blank / non-string → no binding, no event (sanitizeUserId returns undefined). >128 → truncated.
+    if (!clean) return;
+    boundUserId = clean;
+    const clientEvent: ClientEvent = {
+      event_type: "identify",
+      session_id: sessionId,
+      user_id: clean,
+    };
+    if (traits && Object.keys(traits).length > 0) clientEvent.meta = JSON.stringify(traits);
+    queue.enqueue(clientEvent);
+  };
+
+  return {
+    track,
+    screen,
+    identify,
+    flush: queue.flush,
+    notifyOnline: queue.notifyOnline,
+    size: queue.size,
+  };
+};

package/src/analytics/index.ts

@@ -45,3 +45,15 @@ export type { ContextEnvelope, ContextEnvelopeInput } from "./contextEnvelope";
 // ─── Offline-first, persistent, batched + retried event queue (dependency-free) ─
 export { createEventQueue } from "./eventQueue";
 export type { EventQueue, EventQueueOptions, EnvelopeSource } from "./eventQueue";
+
+// ─── Developer-facing analytics façade (track / screen / identify) over the queue ─
+export { createAnalytics } from "./analyticsFacade";
+export type {
+  Analytics,
+  AnalyticsOptions,
+  AnalyticsProps,
+  CreateAnalyticsConfig,
+} from "./analyticsFacade";
+
+// ─── The thin optional React hook over the façade ─────────────────────────────
+export { useAnalytics } from "./useAnalytics";

package/src/analytics/reportClientEvent.ts

@@ -35,8 +35,17 @@ import type { DeviceContext } from "../device/deviceContext";
  *  This is the SINGLE fallback signal — hosts must NOT also report their own.
  *  `identify` binds the host's opaque `user_id` to this `session_id` (late binding — the user
  *  registered during/after onboarding). It carries no funnel weight; the server maps the
- *  session to the user and back-fills a `session_started` if it never saw the session. */
-export type ClientEventType = "screen_skipped" | "dropped" | "client_fallback" | "identify";
+ *  session to the user and back-fills a `session_started` if it never saw the session.
+ *  `app_event` is the host's own in-app event (the `createAnalytics` façade's `track`/`screen`
+ *  route through the offline queue as first-class `ClientEvent`s). The server already ingests
+ *  it — `reportAppEvent` (reviews/transport) has fired `event_type='app_event'` all along; this
+ *  widening just lets the same shape flow through the durable queue instead of a blind POST. */
+export type ClientEventType =
+  | "screen_skipped"
+  | "dropped"
+  | "client_fallback"
+  | "identify"
+  | "app_event";
 
 /** One client-reported event. Mirrors the server's `OnboardingEvent` (client-settable fields). */
 export type ClientEvent = {

package/src/analytics/useAnalytics.ts

@@ -0,0 +1,36 @@
+/**
+ * useAnalytics — a THIN optional React hook over the pure {@link createAnalytics} factory.
+ *
+ * It builds ONE analytics instance for the component's lifetime and returns it, so re-renders
+ * never rebuild the queue or lose the in-memory user binding. React is a REQUIRED peer of the
+ * kit, so importing it here is allowed; the hook adds NO other dependency. Mirrors the existing
+ * `createScreenTracker` / `useScreenTracking` split — the factory stays React-free, this is the
+ * glue.
+ *
+ *   const analytics = useAnalytics({ serverUrl, apiKey, storage, appId });
+ *   analytics.track("content_share", { source: "feed" });
+ *   // ...on reconnect: analytics.notifyOnline();
+ */
+import { useRef } from "react";
+
+import {
+  createAnalytics,
+  type Analytics,
+  type AnalyticsOptions,
+  type CreateAnalyticsConfig,
+} from "./analyticsFacade";
+
+/**
+ * Build a per-mount analytics instance. `config`/`options` are read once at first render (the
+ * instance is stable for the component's lifetime, held in a ref). Returns the {@link Analytics}
+ * surface so the component can `track` / `screen` / `identify` and drive `notifyOnline` on reconnect.
+ */
+export const useAnalytics = (
+  config: CreateAnalyticsConfig,
+  options: AnalyticsOptions = {},
+): Analytics => {
+  // One instance per mount; kept in a ref so re-renders never rebuild the queue or drop the binding.
+  const ref = useRef<Analytics | undefined>(undefined);
+  if (!ref.current) ref.current = createAnalytics(config, options);
+  return ref.current;
+};