@wireai/activation 0.3.0 → 0.7.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { k as WireOnboardingProps, l as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, n as OnboardingEvent, o as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, C as ClientEvent, e as EnvelopeSource } from './eventQueue-CrNB9gzH.js';
-export { A as AnalyticsEvent, b as ClientEventType, p as DeviceFormFactor, q as OnboardingProgress, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, s as collectDeviceContext, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from './eventQueue-CrNB9gzH.js';
+import { o as WireOnboardingProps, p as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, q as OnboardingEvent, u as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, C as ClientEvent, e as EnvelopeSource } from './currentSession-CxnP7gAa.js';
+export { A as AnalyticsEvent, b as ClientEventType, v as DeviceFormFactor, w as EXTRA_KEY_PREFIX, x as OnboardingProgress, R as RESERVED_USER_CONTEXT_KEYS, y as ResolveUserContextOptions, z as ResolvedUserContext, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, W as WireUserContext, B as collectDeviceContext, k as getCurrentSessionId, F as hashEmailFnv1a, G as isWireScalar, m as makeSessionId, H as namespaceExtra, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, I as resolveUserContext, s as setCurrentSessionId, t as toAnalyticsEvent } from './currentSession-CxnP7gAa.js';
 import { O as OnboardingTheme } from './types-BKfpdZzX.js';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.js';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-Cdgns6--.js';
@@ -186,8 +186,9 @@ declare const LoadingBlock: React__default.NamedExoticComponent<LoadingBlockProp
  * WHY a dedicated frame: those slots used to return a bare <LoadingBlock/>, whose flex:1 only
  * fills whatever the host happened to give it — with no safe area and, if the host didn't
  * bound it, no height at all (top-anchored). This wraps them in the same SafeAreaView the flow
- * uses, so the standalone loaders center exactly like the between-turns loader (which centers
- * in the full flow area via the scaffold's loaderChrome offset). One consistent centered look.
+ * uses, so the standalone loaders center exactly like the between-turns loader (both fill their
+ * parent flex:1 region and center in it — here the SafeAreaView, in the flow the scaffold body).
+ * One consistent centered look.
  */
 
 declare const LoadingScreen: React__default.NamedExoticComponent<LoadingBlockProps>;
@@ -825,6 +826,40 @@ declare const attributionMetadata: (a: OnboardingAttribution) => {
     attribution: Record<string, unknown>;
 };
 
+/**
+ * appVersion — best-effort, DEPENDENCY-FREE auto-detection of the host app's version string.
+ *
+ * WHY this exists: analytics segments the funnel `by_app_version`, but that breakdown is only
+ * populated when a `device.appVersion` rides the event. `config.appVersion` (see types.ts) has
+ * always been the way to supply it — but it is easy for a host to forget, and then the release
+ * breakdown is silently empty. This module fills that gap: when the host does NOT pass a version,
+ * the kit makes a best-effort read of the app version the host already ships in its Expo config,
+ * so the breakdown works out of the box. An explicit `config.appVersion` always WINS over this.
+ *
+ * WHY it adds NO dependency (the kit's hard rule): `expo-constants` / `expo-application` are read
+ * through a GUARDED, VARIABLE-specifier `require`. Passing a variable (not a string literal) keeps
+ * Metro/esbuild from statically resolving the module, so a host that does NOT have it installed
+ * (e.g. bare React Native) never fails to bundle — the require simply throws at runtime and is
+ * swallowed. Nothing is added to `package.json`; nothing is forced on the host.
+ *
+ * PRIVACY: an app version string is not PII and identifies no user or device, so surfacing it
+ * changes no App Privacy / Data Safety declaration (same guarantee as the rest of deviceContext).
+ *
+ * NEVER THROWS: every read is guarded; a missing/odd value yields `undefined`, never an exception.
+ * Analytics must never be able to break onboarding.
+ */
+/** A `require`-like resolver. Injectable in tests; production uses the guarded runtime require. */
+type OptionalRequire = (moduleName: string) => unknown;
+/**
+ * Detect the host app version, preferring `expo-constants` (`expoConfig.version`, then
+ * `nativeAppVersion`) and finally `expo-application` (`nativeApplicationVersion`). Returns the
+ * first real string, or `undefined` when none of those are available. Pure and never throws.
+ *
+ * `requireModule` is injectable so tests can exercise the "found" path without the native modules;
+ * production defaults to the guarded runtime require above.
+ */
+declare const detectAppVersion: (requireModule?: OptionalRequire) => string | undefined;
+
 /** Max accepted user-id length. Longer strings are truncated (never rejected). Keep in sync
  *  with the server's `USER_ID_MAX_LENGTH` (analytics/events.py). */
 declare const USER_ID_MAX_LENGTH = 128;
@@ -871,40 +906,6 @@ type IdentifyOnboardingOptions = {
  */
 declare const identifyOnboarding: (opts: IdentifyOnboardingOptions) => Promise<boolean>;
 
-/**
- * reportSessionStart — the ONE standard emitter for "the user opened the app again".
- *
- * Every app-open posts a single `app.session_started` event to the Wire analytics backend
- * (`POST {serverUrl}/v1/events`). That event does two jobs at once, with ZERO server changes:
- *
- *   1. SESSION MAPPING. It carries the host's opaque `userId` + a stable `deviceKey`, so the
- *      backend can group a user's (or a pre-auth device's) opens over time — "when did this
- *      user last use the app, and how many times". The device_key links the pre-auth opens to
- *      the user once `userId` arrives (here or via `identifyOnboarding`).
- *   2. QUESTIONNAIRE / RETENTION FIRING. It flows into the SAME event stream the server's
- *      decision engines read, so a questionnaire trigger `{event:"app.session_started", min_count:N}`
- *      (matched within a session) or a questionnaire `min_sessions:N` (distinct device sessions)
- *      fires on the user's Nth open with no new server endpoint.
- *
- * WIRE CONTRACT (server: analytics/events.py + routers/onboarding.py `POST /v1/events`):
- *   The event is stored as `event_type='app_event'`, `question_key='app.session_started'` — the
- *   generic app.* namespace the reviews wave shipped. The server's `_event_name(ev)` returns the
- *   `question_key` for an `app_event`, which is what a trigger's `event` string matches. We do NOT
- *   send `event_type:'app.session_started'` — that name is not in the server's EVENT_TYPES and
- *   would be rejected. `device_key` rides in the non-PII `user_context` bucket, where the server's
- *   `_event_device_key(ev)` reads it to group a device's sessions. `app_id` + `environment` are
- *   filled server-side from the resolving key (never sent here).
- *
- * SESSION ID DISTINCTION (important): the `session_id` on this event is a PER-OPEN id (a fresh
- * `makeSessionId()` each app-open) — it is NOT the onboarding A2A `contextId`. Onboarding runs
- * ONCE (first launch) and owns its own context id; session-start fires on EVERY open, so it needs
- * its own per-open id. Grouping over time is done by `device_key`/`user_id`, not by session_id.
- *
- * Fire-and-forget: like every analytics path in the kit, this never throws into the UI, never
- * awaits, and swallows a missing target / bad URL / missing fetch / network error. Analytics must
- * never be able to break the app.
- */
-
 /** The canonical event name for an app-open. A trigger keys off this exact string. */
 declare const SESSION_STARTED_EVENT: "app.session_started";
 /** Options for {@link reportSessionStart}. Everything except `target` is optional so a pre-auth
@@ -1131,4 +1132,4 @@ interface UseLifecycleEventsOptions {
  */
 declare const useLifecycleEvents: (config: LifecycleConfig | undefined, options?: UseLifecycleEventsOptions) => void;
 
-export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };
+export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, detectAppVersion, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };