@wireai/activation 0.2.0 → 0.4.0

package/dist/analytics/index.d.mts

@@ -1,5 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-BeO_Brcu.mjs';
-export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, E as EnvelopeSource, e as EventQueue, f as EventQueueOptions, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, h as buildContextEnvelope, i as createEventQueue, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from '../eventQueue-CxKi7Qd5.mjs';
+import { E as EventQueueOptions } from '../eventQueue-CA1d8Fmn.mjs';
+export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, h as buildContextEnvelope, i as createEventQueue, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from '../eventQueue-CA1d8Fmn.mjs';
 import '../types-A6pTxIZV.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-GL_hQ0TN.mjs';
@@ -89,4 +90,70 @@ interface NavigationRefLike {
  */
 declare const useScreenTracking: (navigationRef: NavigationRefLike | undefined, options?: ScreenTrackerOptions) => void;
 
-export { type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, createScreenTracker, getActiveRouteName, screenTrackingHandler, useScreenTracking };
+/** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
+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.
+ */
+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}. */
+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.
+ */
+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`).
+ */
+declare const createAnalytics: (config: CreateAnalyticsConfig, options?: AnalyticsOptions) => Analytics;
+
+/**
+ * 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.
+ */
+declare const useAnalytics: (config: CreateAnalyticsConfig, options?: AnalyticsOptions) => Analytics;
+
+export { type Analytics, type AnalyticsOptions, type AnalyticsProps, type CreateAnalyticsConfig, EventQueueOptions, type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, createAnalytics, createScreenTracker, getActiveRouteName, screenTrackingHandler, useAnalytics, useScreenTracking };

package/dist/analytics/index.d.ts

@@ -1,5 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DLpd1v5_.js';
-export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, E as EnvelopeSource, e as EventQueue, f as EventQueueOptions, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, h as buildContextEnvelope, i as createEventQueue, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from '../eventQueue-rV1dtJJR.js';
+import { E as EventQueueOptions } from '../eventQueue-CrNB9gzH.js';
+export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, h as buildContextEnvelope, i as createEventQueue, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from '../eventQueue-CrNB9gzH.js';
 import '../types-BhpXJGlg.js';
 import '../types-BKfpdZzX.js';
 import '../types-GL_hQ0TN.js';
@@ -89,4 +90,70 @@ interface NavigationRefLike {
  */
 declare const useScreenTracking: (navigationRef: NavigationRefLike | undefined, options?: ScreenTrackerOptions) => void;
 
-export { type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, createScreenTracker, getActiveRouteName, screenTrackingHandler, useScreenTracking };
+/** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
+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.
+ */
+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}. */
+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.
+ */
+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`).
+ */
+declare const createAnalytics: (config: CreateAnalyticsConfig, options?: AnalyticsOptions) => Analytics;
+
+/**
+ * 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.
+ */
+declare const useAnalytics: (config: CreateAnalyticsConfig, options?: AnalyticsOptions) => Analytics;
+
+export { type Analytics, type AnalyticsOptions, type AnalyticsProps, type CreateAnalyticsConfig, EventQueueOptions, type NavigationRefLike, type NavigationRouteLike, type NavigationStateLike, type ScreenTracker, type ScreenTrackerOptions, createAnalytics, createScreenTracker, getActiveRouteName, screenTrackingHandler, useAnalytics, useScreenTracking };

package/dist/analytics/index.js

@@ -64,8 +64,29 @@ var createScreenTracker = (options = {}) => {
 };
 var screenTrackingHandler = (tracker) => (state) => tracker.track(getActiveRouteName(state));
 var useScreenTracking = (navigationRef, options = {}) => {
+  const optionsRef = react.useRef(options);
+  optionsRef.current = options;
   const trackerRef = react.useRef(void 0);
-  if (!trackerRef.current) trackerRef.current = createScreenTracker(options);
+  if (!trackerRef.current) {
+    const dynamicOptions = {
+      get target() {
+        return optionsRef.current.target;
+      },
+      get sessionId() {
+        return optionsRef.current.sessionId;
+      },
+      get deviceKey() {
+        return optionsRef.current.deviceKey;
+      },
+      get onScreen() {
+        return optionsRef.current.onScreen;
+      },
+      get shouldTrack() {
+        return optionsRef.current.shouldTrack;
+      }
+    };
+    trackerRef.current = createScreenTracker(dynamicOptions);
+  }
   react.useEffect(() => {
     const tracker = trackerRef.current;
     if (!tracker || !(navigationRef == null ? void 0 : navigationRef.addListener)) return;
@@ -338,6 +359,8 @@ var createEventQueue = (options) => {
   })();
   const postBatch = async (events) => {
     if (!(target == null ? void 0 : target.serverUrl) || events.length === 0) return false;
+    const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
+    const timer = setTimeout(() => controller == null ? void 0 : controller.abort(), 15e3);
     try {
       const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
       const headers = { "Content-Type": "application/json" };
@@ -345,11 +368,14 @@ var createEventQueue = (options) => {
       const res = await fetch(url, {
         method: "POST",
         headers,
-        body: JSON.stringify({ events })
+        body: JSON.stringify({ events }),
+        signal: controller == null ? void 0 : controller.signal
       });
       return !!(res && res.ok);
     } catch {
       return false;
+    } finally {
+      clearTimeout(timer);
     }
   };
   const clearRetry = () => {
@@ -423,8 +449,102 @@ var createEventQueue = (options) => {
   return { enqueue, flush, notifyOnline, size };
 };
 
+// src/identity/userIdentity.ts
+var USER_ID_MAX_LENGTH = 128;
+var sanitizeUserId = (raw) => {
+  if (typeof raw !== "string") return void 0;
+  const trimmed = raw.trim();
+  if (!trimmed) return void 0;
+  return trimmed.length > USER_ID_MAX_LENGTH ? trimmed.slice(0, USER_ID_MAX_LENGTH) : trimmed;
+};
+
+// src/analytics/analyticsFacade.ts
+var createAnalytics = (config, options = {}) => {
+  var _a, _b;
+  const sessionId = (_a = config.sessionId) != null ? _a : makeSessionId();
+  const envelope = () => buildContextEnvelope({
+    sessionId,
+    appVersion: config.appVersion,
+    appBuild: config.appBuild,
+    networkType: config.networkType
+  });
+  const queue = createEventQueue({
+    target: { serverUrl: config.serverUrl, apiKey: config.apiKey },
+    storage: config.storage,
+    appId: config.appId,
+    envelope,
+    ...options
+  });
+  let boundUserId;
+  const storageKey = `wireai:analytics:userId:${(_b = config.appId) != null ? _b : "default"}`;
+  if (config.storage) {
+    void config.storage.getItem(storageKey).then((saved) => {
+      if (saved) boundUserId = saved;
+    }).catch(() => {
+    });
+  }
+  const track = (event, props) => {
+    if (!event) return;
+    const 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, props) => {
+    if (!name) return;
+    const meta = { screen: name, ...props != null ? props : {} };
+    const 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, traits) => {
+    const clean = sanitizeUserId(userId);
+    if (!clean) return;
+    boundUserId = clean;
+    if (config.storage) {
+      void config.storage.setItem(storageKey, clean).catch(() => {
+      });
+    }
+    const 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
+  };
+};
+var useAnalytics = (config, options = {}) => {
+  const ref = react.useRef(void 0);
+  const prevKeys = react.useRef("");
+  const currentKeys = `${config.serverUrl}|${config.apiKey}|${config.appId}`;
+  if (!ref.current || prevKeys.current !== currentKeys) {
+    prevKeys.current = currentKeys;
+    ref.current = createAnalytics(config, options);
+  }
+  return ref.current;
+};
+
 exports.WIRE_ONBOARDING_EVENTS = WIRE_ONBOARDING_EVENTS;
 exports.buildContextEnvelope = buildContextEnvelope;
+exports.createAnalytics = createAnalytics;
 exports.createEventQueue = createEventQueue;
 exports.createScreenTracker = createScreenTracker;
 exports.getActiveRouteName = getActiveRouteName;
@@ -434,6 +554,7 @@ exports.reportClientEvent = reportClientEvent;
 exports.reportClientEvents = reportClientEvents;
 exports.screenTrackingHandler = screenTrackingHandler;
 exports.toAnalyticsEvent = toAnalyticsEvent;
+exports.useAnalytics = useAnalytics;
 exports.useScreenTracking = useScreenTracking;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map