ad2app-lib 1.41.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_AccessDenial.d.ts

@@ -26,14 +26,63 @@ export declare const ACCESS_DENIAL_CODES: {
     readonly ENTITLEMENT_PRECONDITION: "entitlement-precondition";
 };
 export type AccessDenialCode = (typeof ACCESS_DENIAL_CODES)[keyof typeof ACCESS_DENIAL_CODES];
+/**
+ * WHICH precondition the entitlement wall refused on (backend#305, spec 170).
+ *
+ * `ENTITLEMENT_PRECONDITION` above is the CLIENT contract: every cause below
+ * wants the same behaviour from a client — render the surface's own empty
+ * state, do not redirect, never send a paying user to buy a plan they already
+ * own — so a fourth code would force every consumer to re-learn a wall it
+ * already handles correctly, to carry information no consumer acts on.
+ *
+ * This is for whoever is READING. There is one throw site in the backend and
+ * four ways to reach it, and until now all four answered with the same string:
+ * "has no beta place", "subscription lapsed", "has connected nothing yet" and
+ * "was left in a state we do not recognise" were indistinguishable outside a
+ * database session. One beta tester was refused across /dashboard, /inbox,
+ * /settings and a post page — 21 denials in 30 days — and the only way to find
+ * out why was to open the database by hand.
+ *
+ * NOTHING HERE MAY SAY ANYTHING ABOUT THE ACCOUNT beyond which condition
+ * failed. These names travel to the browser. `UNRECOGNISED_PLAN` deliberately
+ * does not carry WHICH plan value was unrecognised — that belongs in the
+ * server-side log.
+ */
+export declare const ENTITLEMENT_PRECONDITIONS: {
+    /** No such user row. Unentitled, not merely unconnected. */
+    readonly UNKNOWN_ACCOUNT: "unknown-account";
+    /**
+     * A plan value the allow-list deliberately refuses: 'TRIALING', 'PAST_DUE',
+     * a future tier, or a typo. Split out of NO_ENTITLEMENT on purpose — both
+     * stay refused, and the fail-closed property of the allow-list is not
+     * touched, but a plan value we do not recognise is a DEFECT and a plain free
+     * account is not. Reported separately because that distinction is most of
+     * what makes a locked-out account diagnosable.
+     */
+    readonly UNRECOGNISED_PLAN: "unrecognised-plan";
+    /** No paid plan and no live beta place; or a lapsed payer / lapsed place
+     *  holder, who keeps read-only access to content we hold but has no claim on
+     *  a live vendor read. */
+    readonly NO_ENTITLEMENT: "no-entitlement";
+    /** Entitled, and has connected nothing yet. They need an account, NOT a
+     *  purchase — the distinction spec 144 drew in prose and nothing recorded. */
+    readonly NO_CONNECTION: "no-connection";
+};
+export type EntitlementPrecondition = (typeof ENTITLEMENT_PRECONDITIONS)[keyof typeof ENTITLEMENT_PRECONDITIONS];
 /**
  * The body shape those 403s answer with. `statusCode`/`error` are carried
  * explicitly so the response stays byte-identical to Nest's default envelope
  * and `code` is purely additive — no existing consumer sees a change.
+ *
+ * `precondition` is additive in exactly the same way, and OPTIONAL, which is
+ * what makes two promises true by construction: a client that ignores it
+ * behaves as it does today, and a response from a backend that predates it is
+ * still a valid body rather than something a consumer has to special-case.
  */
 export interface I_AccessDenialBody {
     statusCode: number;
     error: string;
     message: string;
     code: AccessDenialCode;
+    precondition?: EntitlementPrecondition;
 }

package/dist/types/I_AccessDenial.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ACCESS_DENIAL_CODES = void 0;
+exports.ENTITLEMENT_PRECONDITIONS = exports.ACCESS_DENIAL_CODES = void 0;
 /**
  * Why a 403 happened, as a value a client can branch on.
  *
@@ -28,3 +28,45 @@ exports.ACCESS_DENIAL_CODES = {
      */
     ENTITLEMENT_PRECONDITION: "entitlement-precondition",
 };
+/**
+ * WHICH precondition the entitlement wall refused on (backend#305, spec 170).
+ *
+ * `ENTITLEMENT_PRECONDITION` above is the CLIENT contract: every cause below
+ * wants the same behaviour from a client — render the surface's own empty
+ * state, do not redirect, never send a paying user to buy a plan they already
+ * own — so a fourth code would force every consumer to re-learn a wall it
+ * already handles correctly, to carry information no consumer acts on.
+ *
+ * This is for whoever is READING. There is one throw site in the backend and
+ * four ways to reach it, and until now all four answered with the same string:
+ * "has no beta place", "subscription lapsed", "has connected nothing yet" and
+ * "was left in a state we do not recognise" were indistinguishable outside a
+ * database session. One beta tester was refused across /dashboard, /inbox,
+ * /settings and a post page — 21 denials in 30 days — and the only way to find
+ * out why was to open the database by hand.
+ *
+ * NOTHING HERE MAY SAY ANYTHING ABOUT THE ACCOUNT beyond which condition
+ * failed. These names travel to the browser. `UNRECOGNISED_PLAN` deliberately
+ * does not carry WHICH plan value was unrecognised — that belongs in the
+ * server-side log.
+ */
+exports.ENTITLEMENT_PRECONDITIONS = {
+    /** No such user row. Unentitled, not merely unconnected. */
+    UNKNOWN_ACCOUNT: "unknown-account",
+    /**
+     * A plan value the allow-list deliberately refuses: 'TRIALING', 'PAST_DUE',
+     * a future tier, or a typo. Split out of NO_ENTITLEMENT on purpose — both
+     * stay refused, and the fail-closed property of the allow-list is not
+     * touched, but a plan value we do not recognise is a DEFECT and a plain free
+     * account is not. Reported separately because that distinction is most of
+     * what makes a locked-out account diagnosable.
+     */
+    UNRECOGNISED_PLAN: "unrecognised-plan",
+    /** No paid plan and no live beta place; or a lapsed payer / lapsed place
+     *  holder, who keeps read-only access to content we hold but has no claim on
+     *  a live vendor read. */
+    NO_ENTITLEMENT: "no-entitlement",
+    /** Entitled, and has connected nothing yet. They need an account, NOT a
+     *  purchase — the distinction spec 144 drew in prose and nothing recorded. */
+    NO_CONNECTION: "no-connection",
+};

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.41.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_AccessDenial.ts

@@ -29,14 +29,66 @@ export const ACCESS_DENIAL_CODES = {
 export type AccessDenialCode =
   (typeof ACCESS_DENIAL_CODES)[keyof typeof ACCESS_DENIAL_CODES];
 
+/**
+ * WHICH precondition the entitlement wall refused on (backend#305, spec 170).
+ *
+ * `ENTITLEMENT_PRECONDITION` above is the CLIENT contract: every cause below
+ * wants the same behaviour from a client — render the surface's own empty
+ * state, do not redirect, never send a paying user to buy a plan they already
+ * own — so a fourth code would force every consumer to re-learn a wall it
+ * already handles correctly, to carry information no consumer acts on.
+ *
+ * This is for whoever is READING. There is one throw site in the backend and
+ * four ways to reach it, and until now all four answered with the same string:
+ * "has no beta place", "subscription lapsed", "has connected nothing yet" and
+ * "was left in a state we do not recognise" were indistinguishable outside a
+ * database session. One beta tester was refused across /dashboard, /inbox,
+ * /settings and a post page — 21 denials in 30 days — and the only way to find
+ * out why was to open the database by hand.
+ *
+ * NOTHING HERE MAY SAY ANYTHING ABOUT THE ACCOUNT beyond which condition
+ * failed. These names travel to the browser. `UNRECOGNISED_PLAN` deliberately
+ * does not carry WHICH plan value was unrecognised — that belongs in the
+ * server-side log.
+ */
+export const ENTITLEMENT_PRECONDITIONS = {
+  /** No such user row. Unentitled, not merely unconnected. */
+  UNKNOWN_ACCOUNT: "unknown-account",
+  /**
+   * A plan value the allow-list deliberately refuses: 'TRIALING', 'PAST_DUE',
+   * a future tier, or a typo. Split out of NO_ENTITLEMENT on purpose — both
+   * stay refused, and the fail-closed property of the allow-list is not
+   * touched, but a plan value we do not recognise is a DEFECT and a plain free
+   * account is not. Reported separately because that distinction is most of
+   * what makes a locked-out account diagnosable.
+   */
+  UNRECOGNISED_PLAN: "unrecognised-plan",
+  /** No paid plan and no live beta place; or a lapsed payer / lapsed place
+   *  holder, who keeps read-only access to content we hold but has no claim on
+   *  a live vendor read. */
+  NO_ENTITLEMENT: "no-entitlement",
+  /** Entitled, and has connected nothing yet. They need an account, NOT a
+   *  purchase — the distinction spec 144 drew in prose and nothing recorded. */
+  NO_CONNECTION: "no-connection",
+} as const;
+
+export type EntitlementPrecondition =
+  (typeof ENTITLEMENT_PRECONDITIONS)[keyof typeof ENTITLEMENT_PRECONDITIONS];
+
 /**
  * The body shape those 403s answer with. `statusCode`/`error` are carried
  * explicitly so the response stays byte-identical to Nest's default envelope
  * and `code` is purely additive — no existing consumer sees a change.
+ *
+ * `precondition` is additive in exactly the same way, and OPTIONAL, which is
+ * what makes two promises true by construction: a client that ignores it
+ * behaves as it does today, and a response from a backend that predates it is
+ * still a valid body rather than something a consumer has to special-case.
  */
 export interface I_AccessDenialBody {
   statusCode: number;
   error: string;
   message: string;
   code: AccessDenialCode;
+  precondition?: EntitlementPrecondition;
 }

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/access-denial.test.ts

@@ -0,0 +1,70 @@
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+
+import {
+	ACCESS_DENIAL_CODES,
+	ENTITLEMENT_PRECONDITIONS,
+	type EntitlementPrecondition,
+	type I_AccessDenialBody,
+} from './I_AccessDenial';
+
+/**
+ * Spec 170 T003. These four strings are a contract between three repos and a
+ * PostHog query someone will write against them: a rename is a silent break in
+ * whichever of the three does not get rebuilt, and the query just stops
+ * matching. Pinned here so a rename has to be a decision.
+ */
+test('the four precondition names are stable strings', () => {
+	assert.deepEqual(ENTITLEMENT_PRECONDITIONS, {
+		UNKNOWN_ACCOUNT: 'unknown-account',
+		UNRECOGNISED_PLAN: 'unrecognised-plan',
+		NO_ENTITLEMENT: 'no-entitlement',
+		NO_CONNECTION: 'no-connection',
+	});
+});
+
+test('the union covers every name and nothing else', () => {
+	const all: EntitlementPrecondition[] = Object.values(ENTITLEMENT_PRECONDITIONS);
+	assert.equal(new Set(all).size, 4);
+	// Exhaustiveness, checked by the compiler: adding a name without handling it
+	// here stops building.
+	for (const value of all) {
+		switch (value) {
+			case 'unknown-account':
+			case 'unrecognised-plan':
+			case 'no-entitlement':
+			case 'no-connection':
+				break;
+			default: {
+				const never: never = value;
+				throw new Error(`unhandled precondition ${String(never)}`);
+			}
+		}
+	}
+});
+
+test('precondition is optional, so an older backend still sends a valid body', () => {
+	// The whole point of the field being optional: this has to compile.
+	const withoutIt: I_AccessDenialBody = {
+		statusCode: 403,
+		error: 'Forbidden',
+		message: 'Analytics require a paid plan with a connected Late profile',
+		code: ACCESS_DENIAL_CODES.ENTITLEMENT_PRECONDITION,
+	};
+	assert.equal(withoutIt.precondition, undefined);
+
+	const withIt: I_AccessDenialBody = {
+		...withoutIt,
+		precondition: ENTITLEMENT_PRECONDITIONS.NO_CONNECTION,
+	};
+	assert.equal(withIt.precondition, 'no-connection');
+});
+
+test('the denial codes are untouched', () => {
+	// FR-003: this feature adds a field, it does not renegotiate `code`.
+	assert.deepEqual(ACCESS_DENIAL_CODES, {
+		BETA_REQUIRED: 'beta-required',
+		SUBSCRIPTION_REQUIRED: 'subscription-required',
+		ENTITLEMENT_PRECONDITION: 'entitlement-precondition',
+	});
+});

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";