ad2app-lib 1.34.0 → 1.36.0

package/dist/analytics/index.d.ts

@@ -48,6 +48,7 @@ export declare const EVENTS: {
     readonly PAYWALL_DISMISSED: "paywall_dismissed";
     readonly ACCESS_DENIED: "access_denied";
     readonly ONBOARDING_STEP_COMPLETED: "onboarding_step_completed";
+    readonly ONBOARDING_STEP_VIEWED: "onboarding_step_viewed";
     readonly EXIT_INTENT_SHOWN: "exit_intent_shown";
     readonly EXIT_INTENT_DISMISSED: "exit_intent_dismissed";
     readonly EXIT_INTENT_CAPTURED: "exit_intent_captured";
@@ -74,6 +75,9 @@ export declare const EVENTS: {
     readonly POST_RESCHEDULED: "post_rescheduled";
     readonly ACCOUNT_DISCONNECTED: "account_disconnected";
     readonly NOTIFICATION_PREFERENCES_UPDATED: "notification_preferences_updated";
+    readonly NATIVE_SESSION_LAUNCHED: "native_session_launched";
+    readonly NATIVE_SESSION_RENEWED: "native_session_renewed";
+    readonly NATIVE_SESSION_ENDED: "native_session_ended";
 };
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
 /** Which email program a send belongs to (spec 120). Wire values — do not rename. */
@@ -346,11 +350,16 @@ export interface EventProperties {
         app_locale: AppLocale;
     };
     [EVENTS.ONBOARDING_STEP_COMPLETED]: {
-        flow: 'complete_profile';
+        flow: 'complete_profile' | 'beta_consent';
         step: string;
         step_index: number;
         app_locale: AppLocale;
     };
+    [EVENTS.ONBOARDING_STEP_VIEWED]: {
+        flow: 'complete_profile' | 'beta_consent';
+        step: string;
+        app_locale?: AppLocale;
+    };
     [EVENTS.EXIT_INTENT_SHOWN]: {
         surface: 'connect_wall';
         dwell_ms?: number;
@@ -466,6 +475,13 @@ export interface EventProperties {
         enabled?: boolean;
         success: boolean;
     };
+    [EVENTS.NATIVE_SESSION_LAUNCHED]: {
+        outcome: 'restored' | 'none' | 'degraded';
+    };
+    [EVENTS.NATIVE_SESSION_RENEWED]: Record<string, never>;
+    [EVENTS.NATIVE_SESSION_ENDED]: {
+        cause: 'rejected' | 'sign_out';
+    };
 }
 /** Canonical person property keys (set via identify / $set). */
 export declare const PERSON_PROPS: {
@@ -476,3 +492,14 @@ export declare const PERSON_PROPS: {
     readonly PAYWALL_HITS: "paywall_hits";
 };
 export type PersonPropKey = (typeof PERSON_PROPS)[keyof typeof PERSON_PROPS];
+/**
+ * Canonical launch-context SUPER-property keys (159 US2). Registered once per
+ * session (like `is_pwa` / `display_mode` / `app_platform` in
+ * registerLaunchContext), so they ride every event without a per-event field.
+ * `APP_BUILD` is the only one governed here today — the value MUST come from
+ * the build itself (contract Rule 4), never a hand-maintained constant.
+ */
+export declare const LAUNCH_CONTEXT_PROPS: {
+    readonly APP_BUILD: "app_build";
+};
+export type LaunchContextPropKey = (typeof LAUNCH_CONTEXT_PROPS)[keyof typeof LAUNCH_CONTEXT_PROPS];

package/dist/analytics/index.js

@@ -10,7 +10,7 @@
  * Do NOT rename events after they ship — historical data does not migrate.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PERSON_PROPS = exports.CONNECT_BLOCK_REASONS = exports.ONBOARDING_COMPLETED_AT = exports.EMAIL_PROPS = exports.EVENTS = void 0;
+exports.LAUNCH_CONTEXT_PROPS = exports.PERSON_PROPS = exports.CONNECT_BLOCK_REASONS = exports.ONBOARDING_COMPLETED_AT = exports.EMAIL_PROPS = exports.EVENTS = void 0;
 /** Canonical PostHog event names. */
 exports.EVENTS = {
     // Acquisition (landing)
@@ -72,6 +72,12 @@ exports.EVENTS = {
     // trust — it is part of why a REAL retry defect sat unnoticed in the same list.
     ACCESS_DENIED: 'access_denied', // entitlement 403 at the API choke point (beta wall / subscription)
     ONBOARDING_STEP_COMPLETED: 'onboarding_step_completed', // one step of a multi-step flow (complete-profile)
+    // Promoted from a raw string literal at ad2app-frontend's
+    // OnboardingFlow.tsx:887 (spec 158, 2026-09-03) — it was already firing in
+    // production (15 events, 3 people) ungoverned since spec 095. `flow` is
+    // widened alongside ONBOARDING_STEP_COMPLETED below to cover the beta
+    // consent step, which is not part of the complete-profile flow.
+    ONBOARDING_STEP_VIEWED: 'onboarding_step_viewed', // a step was actually shown (drop-off, not just completion)
     EXIT_INTENT_SHOWN: 'exit_intent_shown', // exit-intent capture modal armed (065, verbatim wire values)
     EXIT_INTENT_DISMISSED: 'exit_intent_dismissed',
     EXIT_INTENT_CAPTURED: 'exit_intent_captured', // email captured into the beta list
@@ -104,6 +110,12 @@ exports.EVENTS = {
     ACCOUNT_DISCONNECTED: 'account_disconnected',
     // Settings.
     NOTIFICATION_PREFERENCES_UPDATED: 'notification_preferences_updated',
+    // Native session lifecycle (159) — the iOS wrapper's Keychain-backed session,
+    // reported so "does it survive" is a query instead of an inference from login
+    // counts. Native only; the web session's posture is unchanged (contract Rule 5).
+    NATIVE_SESSION_LAUNCHED: 'native_session_launched',
+    NATIVE_SESSION_RENEWED: 'native_session_renewed',
+    NATIVE_SESSION_ENDED: 'native_session_ended',
 };
 /**
  * Canonical email event property KEYS (spec 120 T001). Emitters and tests
@@ -151,3 +163,13 @@ exports.PERSON_PROPS = {
     // stored here would rewrite the value on every historical paywall_shown event.
     PAYWALL_HITS: 'paywall_hits',
 };
+/**
+ * Canonical launch-context SUPER-property keys (159 US2). Registered once per
+ * session (like `is_pwa` / `display_mode` / `app_platform` in
+ * registerLaunchContext), so they ride every event without a per-event field.
+ * `APP_BUILD` is the only one governed here today — the value MUST come from
+ * the build itself (contract Rule 4), never a hand-maintained constant.
+ */
+exports.LAUNCH_CONTEXT_PROPS = {
+    APP_BUILD: 'app_build',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",

package/src/analytics/index.test.ts

@@ -8,7 +8,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
-import { EVENTS, PERSON_PROPS, EMAIL_PROPS } from "./index";
+import { EVENTS, PERSON_PROPS, EMAIL_PROPS, LAUNCH_CONTEXT_PROPS } from "./index";
 import type {
   EventProperties,
   EmailEventProperties,
@@ -105,6 +105,7 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [EVENTS.PAYWALL_DISMISSED]: { surface: "upgrade_modal", trigger: "user_click", hit_number: 1, app_locale: "en" },
   [EVENTS.ACCESS_DENIED]: { reason: "subscription-required", app_locale: "en" },
   [EVENTS.ONBOARDING_STEP_COMPLETED]: { flow: "complete_profile", step: "role", step_index: 1, app_locale: "en" },
+  [EVENTS.ONBOARDING_STEP_VIEWED]: { flow: "beta_consent", step: "consent" },
   [EVENTS.EXIT_INTENT_SHOWN]: { surface: "connect_wall" },
   [EVENTS.EXIT_INTENT_DISMISSED]: { surface: "connect_wall" },
   [EVENTS.EXIT_INTENT_CAPTURED]: { surface: "connect_wall" },
@@ -132,6 +133,10 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [EVENTS.POST_RESCHEDULED]: { success: true },
   [EVENTS.ACCOUNT_DISCONNECTED]: { platform: "instagram", success: true },
   [EVENTS.NOTIFICATION_PREFERENCES_UPDATED]: { success: true },
+  // 159 native session lifecycle
+  [EVENTS.NATIVE_SESSION_LAUNCHED]: { outcome: "restored" },
+  [EVENTS.NATIVE_SESSION_RENEWED]: {},
+  [EVENTS.NATIVE_SESSION_ENDED]: { cause: "rejected" },
 };
 
 test("EVENTS values are 1:1 with EventProperties keys (no missing or typo'd event)", () => {
@@ -186,6 +191,10 @@ test("080 paywall / onboarding wire names are locked (rename breaks the baseline
   assert.equal(EVENTS.ONBOARDING_STEP_COMPLETED, "onboarding_step_completed");
 });
 
+test("158: onboarding_step_viewed wire name is locked — it was already live in production as a raw string before this promotion (rename breaks the existing 15 events)", () => {
+  assert.equal(EVENTS.ONBOARDING_STEP_VIEWED, "onboarding_step_viewed");
+});
+
 test("080 subscription-lifecycle wire names are locked (backend = source of truth)", () => {
   assert.deepEqual(
     [
@@ -450,3 +459,36 @@ test("120 playbook events carry the edition stamp", () => {
   assert.equal(opened.edition_version, "2026.08");
   assert.equal(downloaded.format, "pdf");
 });
+
+// 159: the native session lifecycle + build attribution.
+
+test("159 native session wire names are locked", () => {
+  assert.equal(EVENTS.NATIVE_SESSION_LAUNCHED, "native_session_launched");
+  assert.equal(EVENTS.NATIVE_SESSION_RENEWED, "native_session_renewed");
+  assert.equal(EVENTS.NATIVE_SESSION_ENDED, "native_session_ended");
+});
+
+test("159 native_session_launched carries a closed outcome — restored, none, or degraded", () => {
+  const restored: EventProperties[typeof EVENTS.NATIVE_SESSION_LAUNCHED] = { outcome: "restored" };
+  const none: EventProperties[typeof EVENTS.NATIVE_SESSION_LAUNCHED] = { outcome: "none" };
+  const degraded: EventProperties[typeof EVENTS.NATIVE_SESSION_LAUNCHED] = { outcome: "degraded" };
+  assert.equal(restored.outcome, "restored");
+  assert.equal(none.outcome, "none");
+  assert.equal(degraded.outcome, "degraded");
+});
+
+test("159 native_session_ended carries its cause — rejected or sign_out, never bare", () => {
+  const rejected: EventProperties[typeof EVENTS.NATIVE_SESSION_ENDED] = { cause: "rejected" };
+  const signOut: EventProperties[typeof EVENTS.NATIVE_SESSION_ENDED] = { cause: "sign_out" };
+  assert.equal(rejected.cause, "rejected");
+  assert.equal(signOut.cause, "sign_out");
+});
+
+test("159 native_session_renewed carries no properties (the fact of the renewal is the whole report)", () => {
+  const renewed: EventProperties[typeof EVENTS.NATIVE_SESSION_RENEWED] = {};
+  assert.deepEqual(renewed, {});
+});
+
+test("159 LAUNCH_CONTEXT_PROPS governs the build-attribution key (no raw 'app_build' string at the call site)", () => {
+  assert.equal(LAUNCH_CONTEXT_PROPS.APP_BUILD, "app_build");
+});

package/src/analytics/index.ts

@@ -78,6 +78,12 @@ export const EVENTS = {
   // trust — it is part of why a REAL retry defect sat unnoticed in the same list.
   ACCESS_DENIED: 'access_denied', // entitlement 403 at the API choke point (beta wall / subscription)
   ONBOARDING_STEP_COMPLETED: 'onboarding_step_completed', // one step of a multi-step flow (complete-profile)
+  // Promoted from a raw string literal at ad2app-frontend's
+  // OnboardingFlow.tsx:887 (spec 158, 2026-09-03) — it was already firing in
+  // production (15 events, 3 people) ungoverned since spec 095. `flow` is
+  // widened alongside ONBOARDING_STEP_COMPLETED below to cover the beta
+  // consent step, which is not part of the complete-profile flow.
+  ONBOARDING_STEP_VIEWED: 'onboarding_step_viewed', // a step was actually shown (drop-off, not just completion)
   EXIT_INTENT_SHOWN: 'exit_intent_shown', // exit-intent capture modal armed (065, verbatim wire values)
   EXIT_INTENT_DISMISSED: 'exit_intent_dismissed',
   EXIT_INTENT_CAPTURED: 'exit_intent_captured', // email captured into the beta list
@@ -115,6 +121,13 @@ export const EVENTS = {
 
   // Settings.
   NOTIFICATION_PREFERENCES_UPDATED: 'notification_preferences_updated',
+
+  // Native session lifecycle (159) — the iOS wrapper's Keychain-backed session,
+  // reported so "does it survive" is a query instead of an inference from login
+  // counts. Native only; the web session's posture is unchanged (contract Rule 5).
+  NATIVE_SESSION_LAUNCHED: 'native_session_launched',
+  NATIVE_SESSION_RENEWED: 'native_session_renewed',
+  NATIVE_SESSION_ENDED: 'native_session_ended',
 } as const;
 
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
@@ -436,11 +449,19 @@ export interface EventProperties {
     app_locale: AppLocale;
   };
   [EVENTS.ONBOARDING_STEP_COMPLETED]: {
-    flow: 'complete_profile'; // closed set, extensible when a new flow ships
+    flow: 'complete_profile' | 'beta_consent'; // widened 2026-09-03 (spec 158) for the beta consent step
     step: string; // stable slug derived from the real wizard, not guessed
     step_index: number; // 1-based
     app_locale: AppLocale;
   };
+  // Promoted from a raw string (spec 158) — same `flow`/`step` shape as
+  // ONBOARDING_STEP_COMPLETED, fired once per step actually SHOWN rather than
+  // finished, so drop-off is visible per step, not only per completion.
+  [EVENTS.ONBOARDING_STEP_VIEWED]: {
+    flow: 'complete_profile' | 'beta_consent';
+    step: string;
+    app_locale?: AppLocale; // optional: the pre-existing raw call site does not have it yet (T001a repairs the call site, not the type's honesty about what ships today)
+  };
   // Exit-intent (065). surface value is VERBATIM from the ExitIntentModal
   // component ('connect_wall'); dwell_ms / page_views / app_locale are optional
   // additions T003 wires (the component does not emit them yet — fidelity gate).
@@ -486,6 +507,16 @@ export interface EventProperties {
 
   // Settings — which preference toggled and its new state.
   [EVENTS.NOTIFICATION_PREFERENCES_UPDATED]: { preference?: string; enabled?: boolean; success: boolean };
+
+  // Native session lifecycle (159, contract session-reports.md). `outcome`
+  // covers all three launch reports in one event (restored / none / degraded)
+  // rather than three near-duplicate event names — the same pattern as
+  // ACCESS_DENIED's `reason`. `cause` on the ending is mandatory (contract
+  // Rule 1): an ending without a cause tells a reader nothing a bug and a
+  // person didn't already look identical.
+  [EVENTS.NATIVE_SESSION_LAUNCHED]: { outcome: 'restored' | 'none' | 'degraded' };
+  [EVENTS.NATIVE_SESSION_RENEWED]: Record<string, never>;
+  [EVENTS.NATIVE_SESSION_ENDED]: { cause: 'rejected' | 'sign_out' };
 }
 
 /** Canonical person property keys (set via identify / $set). */
@@ -502,6 +533,19 @@ export const PERSON_PROPS = {
 
 export type PersonPropKey = (typeof PERSON_PROPS)[keyof typeof PERSON_PROPS];
 
+/**
+ * Canonical launch-context SUPER-property keys (159 US2). Registered once per
+ * session (like `is_pwa` / `display_mode` / `app_platform` in
+ * registerLaunchContext), so they ride every event without a per-event field.
+ * `APP_BUILD` is the only one governed here today — the value MUST come from
+ * the build itself (contract Rule 4), never a hand-maintained constant.
+ */
+export const LAUNCH_CONTEXT_PROPS = {
+  APP_BUILD: 'app_build',
+} as const;
+
+export type LaunchContextPropKey = (typeof LAUNCH_CONTEXT_PROPS)[keyof typeof LAUNCH_CONTEXT_PROPS];
+
 /**
  * Compile-time taxonomy contract (AD2-952). These are pure type-level assertions:
  * if EVENTS and EventProperties ever drift, the `tsc --noEmit` CI gate fails the