ad2app-lib 1.42.0 → 1.43.0

package/dist/analytics/index.d.ts

@@ -29,6 +29,8 @@ export declare const EVENTS: {
     readonly PLAYBOOK_OPENED: "playbook_opened";
     readonly PLAYBOOK_DOWNLOADED: "playbook_downloaded";
     readonly SIGNED_UP: "signed_up";
+    readonly ANALYTICS_CONSENT_RECORDED: "analytics_consent_recorded";
+    readonly FIRST_AUTHENTICATED: "first_authenticated";
     readonly PROFILE_COMPLETED: "profile_completed";
     readonly LOGGED_IN: "logged_in";
     readonly SOCIAL_ACCOUNT_CONNECTED: "social_account_connected";
@@ -262,6 +264,10 @@ export interface EventProperties {
         method: 'email' | 'google';
         role: string;
     };
+    [EVENTS.ANALYTICS_CONSENT_RECORDED]: {
+        state: 'granted' | 'declined' | 'unset';
+    };
+    [EVENTS.FIRST_AUTHENTICATED]: Record<string, never>;
     [EVENTS.PROFILE_COMPLETED]: {
         role: string;
     };

package/dist/analytics/index.js

@@ -39,6 +39,15 @@ exports.EVENTS = {
     PLAYBOOK_DOWNLOADED: 'playbook_downloaded',
     // Activation (web app)
     SIGNED_UP: 'signed_up', // server-owned (backend, on user creation)
+    // 171 (backend#307): the analytics answer itself, emitted by the BACKEND so
+    // it arrives for the people who declined — a decline recorded only by the
+    // browser that declined is a fact nobody can read. Carries the answer and
+    // nothing else.
+    ANALYTICS_CONSENT_RECORDED: 'analytics_consent_recorded', // server-owned (backend)
+    // 171: the first authenticated request after signup. Server-owned and
+    // consent-independent, in the same spirit as T046/T054 — it is what tells
+    // "used the product, refused tracking" apart from "never came back".
+    FIRST_AUTHENTICATED: 'first_authenticated', // server-owned (backend)
     PROFILE_COMPLETED: 'profile_completed', // the /complete-profile step (influencers)
     LOGGED_IN: 'logged_in',
     SOCIAL_ACCOUNT_CONNECTED: 'social_account_connected',

package/dist/types/I_AnalyticsConsent.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A person's stated answer about analytics, as an ACCOUNT FACT (spec 171,
+ * backend#307).
+ *
+ * WHY THIS EXISTS. `posthog-js` runs `opt_out_capturing_by_default: true`, and
+ * a decline calls `opt_out_capturing()`. That is correct and it is the point:
+ * a decline collects nothing. It also means the fact of the decline is known
+ * only to that browser — so from the product's side, someone using the app
+ * every day with analytics off is indistinguishable from someone who signed up
+ * and never came back. Five of nineteen beta testers were in that state on
+ * 2026-09-14, and every percentage on the beta dashboard was silently computed
+ * over fourteen people while claiming nineteen.
+ *
+ * RECORDING A DECLINE IS NOT THE TRACKING THAT WAS DECLINED. This carries the
+ * answer and nothing else — no page, no behaviour, no session. It is the same
+ * instrument as `push_consent_state`, which has recorded "declined" as a
+ * separate legal control since spec 162 without anyone calling it surveillance,
+ * and it is precisely what lets the product HONOUR a decline while still
+ * counting that person as a user rather than as an absence.
+ */
+export declare const ANALYTICS_CONSENT_STATES: {
+    /** Never answered the banner. The default, and distinguishable from both
+     *  answers — an unanswered question is not a "no". */
+    readonly UNSET: "unset";
+    /** Accepted analytics. Recorded the same way as a decline, so neither answer
+     *  is ever inferred from the absence of the other. */
+    readonly GRANTED: "granted";
+    /** Declined analytics. The person is still using the product; they are
+     *  invisible by choice, which is a different thing from inactive. */
+    readonly DECLINED: "declined";
+};
+export type AnalyticsConsentState = (typeof ANALYTICS_CONSENT_STATES)[keyof typeof ANALYTICS_CONSENT_STATES];
+/**
+ * The body of `POST /users/analytics-consent`.
+ *
+ * `unset` IS sendable, and only from one place: the "Cookie settings" link
+ * that reopens the choice (review 2026-09-17 M2). The first draft forbade it
+ * on the reasoning that the absence of an answer is not an answer anyone
+ * gives — true of the banner, false of a RESET, which is a person actively
+ * withdrawing their previous answer. Without it the browser went back to
+ * `pending` while the column still said `declined`, so the dashboard counted
+ * someone as opted out while they were being asked again. A stale record is
+ * worse than an absent one.
+ */
+export interface I_AnalyticsConsentBody {
+    state: AnalyticsConsentState;
+}

package/dist/types/I_AnalyticsConsent.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANALYTICS_CONSENT_STATES = void 0;
+/**
+ * A person's stated answer about analytics, as an ACCOUNT FACT (spec 171,
+ * backend#307).
+ *
+ * WHY THIS EXISTS. `posthog-js` runs `opt_out_capturing_by_default: true`, and
+ * a decline calls `opt_out_capturing()`. That is correct and it is the point:
+ * a decline collects nothing. It also means the fact of the decline is known
+ * only to that browser — so from the product's side, someone using the app
+ * every day with analytics off is indistinguishable from someone who signed up
+ * and never came back. Five of nineteen beta testers were in that state on
+ * 2026-09-14, and every percentage on the beta dashboard was silently computed
+ * over fourteen people while claiming nineteen.
+ *
+ * RECORDING A DECLINE IS NOT THE TRACKING THAT WAS DECLINED. This carries the
+ * answer and nothing else — no page, no behaviour, no session. It is the same
+ * instrument as `push_consent_state`, which has recorded "declined" as a
+ * separate legal control since spec 162 without anyone calling it surveillance,
+ * and it is precisely what lets the product HONOUR a decline while still
+ * counting that person as a user rather than as an absence.
+ */
+exports.ANALYTICS_CONSENT_STATES = {
+    /** Never answered the banner. The default, and distinguishable from both
+     *  answers — an unanswered question is not a "no". */
+    UNSET: "unset",
+    /** Accepted analytics. Recorded the same way as a decline, so neither answer
+     *  is ever inferred from the absence of the other. */
+    GRANTED: "granted",
+    /** Declined analytics. The person is still using the product; they are
+     *  invisible by choice, which is a different thing from inactive. */
+    DECLINED: "declined",
+};

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export * from "./I_Influencer";
 export * from "./I_InfluencersLists";
 export * from "./I_InfluencersCategories";
 export * from "./I_InfluencersProperties";
+export * from "./I_AnalyticsConsent";
 export * from "./I_Item";
 export * from "./I_List";
 export * from "./I_PaginatedList";

package/dist/types/index.js

@@ -21,6 +21,7 @@ __exportStar(require("./I_Influencer"), exports);
 __exportStar(require("./I_InfluencersLists"), exports);
 __exportStar(require("./I_InfluencersCategories"), exports);
 __exportStar(require("./I_InfluencersProperties"), exports);
+__exportStar(require("./I_AnalyticsConsent"), exports);
 __exportStar(require("./I_Item"), exports);
 __exportStar(require("./I_List"), exports);
 __exportStar(require("./I_PaginatedList"), exports);

package/package.json

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

package/src/analytics/index.test.ts

@@ -154,6 +154,11 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   // 164 G012 — both behind default-OFF flags, fixed for completeness
   [EVENTS.COMMENT_GUARD_MODE_CHANGED]: { mode: "flag-only" },
   [EVENTS.AI_TOOLS_REVOKE_REQUESTED]: {},
+  // 171 (backend#307) — both server-owned, both emitted by the backend so they
+  // arrive for the people who declined analytics. A decline recorded only by
+  // the browser that declined is a fact nobody can read.
+  [EVENTS.ANALYTICS_CONSENT_RECORDED]: { state: "declined" },
+  [EVENTS.FIRST_AUTHENTICATED]: {},
 };
 
 test("EVENTS values are 1:1 with EventProperties keys (no missing or typo'd event)", () => {

package/src/analytics/index.ts

@@ -43,6 +43,15 @@ export const EVENTS = {
 
   // Activation (web app)
   SIGNED_UP: 'signed_up', // server-owned (backend, on user creation)
+  // 171 (backend#307): the analytics answer itself, emitted by the BACKEND so
+  // it arrives for the people who declined — a decline recorded only by the
+  // browser that declined is a fact nobody can read. Carries the answer and
+  // nothing else.
+  ANALYTICS_CONSENT_RECORDED: 'analytics_consent_recorded', // server-owned (backend)
+  // 171: the first authenticated request after signup. Server-owned and
+  // consent-independent, in the same spirit as T046/T054 — it is what tells
+  // "used the product, refused tracking" apart from "never came back".
+  FIRST_AUTHENTICATED: 'first_authenticated', // server-owned (backend)
   PROFILE_COMPLETED: 'profile_completed', // the /complete-profile step (influencers)
   LOGGED_IN: 'logged_in',
   SOCIAL_ACCOUNT_CONNECTED: 'social_account_connected',
@@ -405,6 +414,8 @@ export interface EventProperties {
   [EVENTS.PLAYBOOK_OPENED]: { edition_version?: string };
   [EVENTS.PLAYBOOK_DOWNLOADED]: { edition_version?: string; format?: string };
   [EVENTS.SIGNED_UP]: { method: 'email' | 'google'; role: string };
+  [EVENTS.ANALYTICS_CONSENT_RECORDED]: { state: 'granted' | 'declined' | 'unset' };
+  [EVENTS.FIRST_AUTHENTICATED]: Record<string, never>;
   [EVENTS.PROFILE_COMPLETED]: { role: string };
   // Spec 161: widened to include 'apple' — the value was already missing from
   // this union (Google/email only) even though native Apple sign-in has

package/src/types/I_AnalyticsConsent.ts

@@ -0,0 +1,50 @@
+/**
+ * A person's stated answer about analytics, as an ACCOUNT FACT (spec 171,
+ * backend#307).
+ *
+ * WHY THIS EXISTS. `posthog-js` runs `opt_out_capturing_by_default: true`, and
+ * a decline calls `opt_out_capturing()`. That is correct and it is the point:
+ * a decline collects nothing. It also means the fact of the decline is known
+ * only to that browser — so from the product's side, someone using the app
+ * every day with analytics off is indistinguishable from someone who signed up
+ * and never came back. Five of nineteen beta testers were in that state on
+ * 2026-09-14, and every percentage on the beta dashboard was silently computed
+ * over fourteen people while claiming nineteen.
+ *
+ * RECORDING A DECLINE IS NOT THE TRACKING THAT WAS DECLINED. This carries the
+ * answer and nothing else — no page, no behaviour, no session. It is the same
+ * instrument as `push_consent_state`, which has recorded "declined" as a
+ * separate legal control since spec 162 without anyone calling it surveillance,
+ * and it is precisely what lets the product HONOUR a decline while still
+ * counting that person as a user rather than as an absence.
+ */
+export const ANALYTICS_CONSENT_STATES = {
+  /** Never answered the banner. The default, and distinguishable from both
+   *  answers — an unanswered question is not a "no". */
+  UNSET: "unset",
+  /** Accepted analytics. Recorded the same way as a decline, so neither answer
+   *  is ever inferred from the absence of the other. */
+  GRANTED: "granted",
+  /** Declined analytics. The person is still using the product; they are
+   *  invisible by choice, which is a different thing from inactive. */
+  DECLINED: "declined",
+} as const;
+
+export type AnalyticsConsentState =
+  (typeof ANALYTICS_CONSENT_STATES)[keyof typeof ANALYTICS_CONSENT_STATES];
+
+/**
+ * The body of `POST /users/analytics-consent`.
+ *
+ * `unset` IS sendable, and only from one place: the "Cookie settings" link
+ * that reopens the choice (review 2026-09-17 M2). The first draft forbade it
+ * on the reasoning that the absence of an answer is not an answer anyone
+ * gives — true of the banner, false of a RESET, which is a person actively
+ * withdrawing their previous answer. Without it the browser went back to
+ * `pending` while the column still said `declined`, so the dashboard counted
+ * someone as opted out while they were being asked again. A stale record is
+ * worse than an absent one.
+ */
+export interface I_AnalyticsConsentBody {
+  state: AnalyticsConsentState;
+}

package/src/types/analytics-consent.test.ts

@@ -0,0 +1,52 @@
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+
+import {
+	ANALYTICS_CONSENT_STATES,
+	type AnalyticsConsentState,
+	type I_AnalyticsConsentBody,
+} from './I_AnalyticsConsent';
+
+/**
+ * Spec 171 T003. Three repos and a PostHog query depend on these exact
+ * strings; a rename is a silent break in whichever of them does not get
+ * rebuilt, and the query simply stops matching.
+ */
+test('the consent state names are stable strings', () => {
+	assert.deepEqual(ANALYTICS_CONSENT_STATES, {
+		UNSET: 'unset',
+		GRANTED: 'granted',
+		DECLINED: 'declined',
+	});
+});
+
+test('the union covers every state and nothing else', () => {
+	const all: AnalyticsConsentState[] = Object.values(ANALYTICS_CONSENT_STATES);
+	assert.equal(new Set(all).size, 3);
+	for (const value of all) {
+		switch (value) {
+			case 'unset':
+			case 'granted':
+			case 'declined':
+				break;
+			default: {
+				const never: never = value;
+				throw new Error(`unhandled state ${String(never)}`);
+			}
+		}
+	}
+});
+
+test('a client can send any of the three, including a withdrawal', () => {
+	// `unset` is sendable only from the "Cookie settings" reset (review M2): a
+	// person withdrawing a previous answer is an action, unlike never having
+	// answered. Without it the column kept the old answer while the browser
+	// went back to pending, and a stale record is worse than an absent one.
+	const granted: I_AnalyticsConsentBody = { state: 'granted' };
+	const declined: I_AnalyticsConsentBody = { state: 'declined' };
+	const withdrawn: I_AnalyticsConsentBody = { state: 'unset' };
+	assert.deepEqual(
+		[granted.state, declined.state, withdrawn.state],
+		['granted', 'declined', 'unset'],
+	);
+});

package/src/types/index.ts

@@ -5,6 +5,7 @@ export * from "./I_Influencer";
 export * from "./I_InfluencersLists";
 export * from "./I_InfluencersCategories";
 export * from "./I_InfluencersProperties";
+export * from "./I_AnalyticsConsent";
 export * from "./I_Item";
 export * from "./I_List";
 export * from "./I_PaginatedList";