ad2app-lib 1.35.0 → 1.37.0

package/dist/analytics/index.d.ts

@@ -75,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. */
@@ -251,7 +254,7 @@ export interface EventProperties {
         role: string;
     };
     [EVENTS.LOGGED_IN]: {
-        method?: 'email' | 'google';
+        method?: 'email' | 'google' | 'apple';
     };
     [EVENTS.SOCIAL_ACCOUNT_CONNECTED]: {
         platform: string;
@@ -472,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: {
@@ -482,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)
@@ -110,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
@@ -157,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.35.0",
+  "version": "1.37.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,
@@ -86,7 +86,9 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [EVENTS.PLAYBOOK_DOWNLOADED]: {},
   [EVENTS.SIGNED_UP]: { method: "email", role: "creator" },
   [EVENTS.PROFILE_COMPLETED]: { role: "creator" },
-  [EVENTS.LOGGED_IN]: {},
+  // Spec 161 T010: proves 'apple' type-checks alongside the pre-existing
+  // 'email' | 'google' union (compile-time, enforced by `tsc --noEmit`).
+  [EVENTS.LOGGED_IN]: { method: "apple" },
   [EVENTS.SOCIAL_ACCOUNT_CONNECTED]: { platform: "instagram" },
   [EVENTS.COMPOSE_STARTED]: {},
   [EVENTS.COMPOSE_STEP_VIEWED]: { step: "content" },
@@ -133,6 +135,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)", () => {
@@ -455,3 +461,47 @@ 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("161 logged_in.method accepts all three sign-in methods, and stays optional", () => {
+  const email: EventProperties[typeof EVENTS.LOGGED_IN] = { method: "email" };
+  const google: EventProperties[typeof EVENTS.LOGGED_IN] = { method: "google" };
+  const apple: EventProperties[typeof EVENTS.LOGGED_IN] = { method: "apple" };
+  const unset: EventProperties[typeof EVENTS.LOGGED_IN] = {};
+  assert.equal(email.method, "email");
+  assert.equal(google.method, "google");
+  assert.equal(apple.method, "apple");
+  assert.deepEqual(unset, {});
+});
+
+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

@@ -121,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];
@@ -334,7 +341,11 @@ export interface EventProperties {
   [EVENTS.PLAYBOOK_DOWNLOADED]: { edition_version?: string; format?: string };
   [EVENTS.SIGNED_UP]: { method: 'email' | 'google'; role: string };
   [EVENTS.PROFILE_COMPLETED]: { role: string };
-  [EVENTS.LOGGED_IN]: { method?: 'email' | 'google' };
+  // Spec 161: widened to include 'apple' — the value was already missing from
+  // this union (Google/email only) even though native Apple sign-in has
+  // existed since spec 136; this closes that gap rather than inventing a new
+  // property.
+  [EVENTS.LOGGED_IN]: { method?: 'email' | 'google' | 'apple' };
   [EVENTS.SOCIAL_ACCOUNT_CONNECTED]: {
     platform: string;
     account_count?: number;
@@ -500,6 +511,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). */
@@ -516,6 +537,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