ad2app-lib 1.28.0 → 1.30.0

package/dist/analytics/index.d.ts

@@ -8,6 +8,7 @@
  * Naming convention: snake_case, object_verb_past_tense.
  * Do NOT rename events after they ship — historical data does not migrate.
  */
+import type { AccessDenialCode } from "../types/I_AccessDenial";
 /** Canonical PostHog event names. */
 export declare const EVENTS: {
     readonly LANDING_CTA_CLICKED: "landing_cta_clicked";
@@ -270,7 +271,12 @@ export interface EventProperties {
         app_locale: AppLocale;
     };
     [EVENTS.ACCESS_DENIED]: {
-        reason: 'beta-required' | 'subscription-required';
+        /**
+         * The backend's own machine-readable code, not a client guess — one union
+         * shared by the API body and this event (types/I_AccessDenial.ts), so a
+         * new wall cannot be counted under a reason that does not exist.
+         */
+        reason: AccessDenialCode;
         path?: string;
         app_locale: AppLocale;
     };

package/dist/types/I_AccessDenial.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Why a 403 happened, as a value a client can branch on.
+ *
+ * The frontend used to recognise these walls by comparing the backend's
+ * English message text, and that broke silently the first time a guard's
+ * wording changed: expected entitlement 403s were captured as $exception at a
+ * rate of ten in two minutes of ordinary tapping, burying real errors in the
+ * telemetry that exists to surface them (AD2-1320, 2026-08-19). Prose is copy
+ * and copy changes; this code is contract.
+ *
+ * Every 403 the product EXPECTS carries one of these as `code` in its response
+ * body, alongside the human-readable `message`, which is unchanged.
+ */
+export declare const ACCESS_DENIAL_CODES: {
+    /** No plan and no beta slot — nothing of their own to look at yet. */
+    readonly BETA_REQUIRED: "beta-required";
+    /** A churned payer attempting a write; they can still read their own data. */
+    readonly SUBSCRIPTION_REQUIRED: "subscription-required";
+    /**
+     * Needs a paid plan AND a connected Late profile. Deliberately distinct from
+     * SUBSCRIPTION_REQUIRED, because it names two preconditions at once: a
+     * paying user who has simply not connected an account yet must never be sent
+     * to buy a plan they already own. Clients show the surface's own empty state
+     * for this one and do NOT redirect.
+     */
+    readonly ENTITLEMENT_PRECONDITION: "entitlement-precondition";
+};
+export type AccessDenialCode = (typeof ACCESS_DENIAL_CODES)[keyof typeof ACCESS_DENIAL_CODES];
+/**
+ * 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.
+ */
+export interface I_AccessDenialBody {
+    statusCode: number;
+    error: string;
+    message: string;
+    code: AccessDenialCode;
+}

package/dist/types/I_AccessDenial.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACCESS_DENIAL_CODES = void 0;
+/**
+ * Why a 403 happened, as a value a client can branch on.
+ *
+ * The frontend used to recognise these walls by comparing the backend's
+ * English message text, and that broke silently the first time a guard's
+ * wording changed: expected entitlement 403s were captured as $exception at a
+ * rate of ten in two minutes of ordinary tapping, burying real errors in the
+ * telemetry that exists to surface them (AD2-1320, 2026-08-19). Prose is copy
+ * and copy changes; this code is contract.
+ *
+ * Every 403 the product EXPECTS carries one of these as `code` in its response
+ * body, alongside the human-readable `message`, which is unchanged.
+ */
+exports.ACCESS_DENIAL_CODES = {
+    /** No plan and no beta slot — nothing of their own to look at yet. */
+    BETA_REQUIRED: "beta-required",
+    /** A churned payer attempting a write; they can still read their own data. */
+    SUBSCRIPTION_REQUIRED: "subscription-required",
+    /**
+     * Needs a paid plan AND a connected Late profile. Deliberately distinct from
+     * SUBSCRIPTION_REQUIRED, because it names two preconditions at once: a
+     * paying user who has simply not connected an account yet must never be sent
+     * to buy a plan they already own. Clients show the surface's own empty state
+     * for this one and do NOT redirect.
+     */
+    ENTITLEMENT_PRECONDITION: "entitlement-precondition",
+};

package/dist/types/I_User.d.ts

@@ -10,8 +10,39 @@ export declare class I_User {
     has_connected_platforms?: boolean;
     influencer?: I_Influencer;
 }
+/**
+ * The answer an account has recorded about the onboarding tour.
+ *
+ * Three values, and the difference between the last two is the whole point:
+ *   'skipped' | 'completed' — a recorded answer. Never re-teach this user.
+ *   null                    — no record yet. A genuinely new user; show it.
+ *   ABSENT (the field is missing entirely) — the server could not read the
+ *                             column. Decide NOTHING.
+ *
+ * Absent is deliberately not `null`. Collapsing them shows the tour to every
+ * existing user in the window between a deploy and its manual migration
+ * (migrations here are run by hand, never on deploy).
+ */
+export type OnboardingState = 'skipped' | 'completed';
 export declare class I_SignedUser extends I_User {
     accessToken: string;
+    /**
+     * AD2-1331 AC3 (Maciej's review, 2026-08-25). Every response that hands back
+     * a session carries this, not just `authenticate` — the client replaces its
+     * authed slice wholesale with whichever payload arrives, so a path that omits
+     * it leaves the answer unknown for the rest of the session (AD2-1329 AC4).
+     *
+     * It lives HERE because AC3 chose an echoing PATCH over a failing one
+     * specifically to remove the forward-only rule from the client, and that only
+     * works if both sides agree on the shape. Until this shipped, the field was
+     * written by the backend, read by the frontend, and declared by neither: the
+     * frontend had to cast through `unknown` to see it, and a rename on either
+     * side would have type-checked clean while the onboarding funnel silently
+     * went dark.
+     *
+     * Optional on purpose — see OnboardingState: absent means "could not read".
+     */
+    onboardingState?: OnboardingState | null;
 }
 export declare enum UserRoles {
     ADMIN = "ADMIN",

package/dist/types/index.d.ts

@@ -35,3 +35,4 @@ export * from "./I_Collaboration";
 export * from "./I_Publish";
 export * from "./I_SM_Platform";
 export * from "./scheduling";
+export * from "./I_AccessDenial";

package/dist/types/index.js

@@ -52,3 +52,5 @@ __exportStar(require("./I_Publish"), exports);
 __exportStar(require("./I_SM_Platform"), exports);
 // ── Scheduling domain ─────────────────────────────────────────────────────────
 __exportStar(require("./scheduling"), exports);
+// ── Access control ────────────────────────────────────────────────────────────
+__exportStar(require("./I_AccessDenial"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -47,7 +47,7 @@
     "prepare": "npm run build"
   },
   "keywords": [],
-  "author": "Maciej Górski@ad2.app",
+  "author": "Maciej G\u00f3rski@ad2.app",
   "license": "ISC",
   "description": "Package to share types and utils across the ad2app projects",
   "dependencies": {

package/src/analytics/index.ts

@@ -9,6 +9,8 @@
  * Do NOT rename events after they ship — historical data does not migrate.
  */
 
+import type { AccessDenialCode } from "../types/I_AccessDenial";
+
 /** Canonical PostHog event names. */
 export const EVENTS = {
   // Acquisition (landing)
@@ -325,7 +327,12 @@ export interface EventProperties {
   // different 403s the backend sends. `path` is the request path, never a URL
   // with query params (no PII in analytics).
   [EVENTS.ACCESS_DENIED]: {
-    reason: 'beta-required' | 'subscription-required';
+    /**
+     * The backend's own machine-readable code, not a client guess — one union
+     * shared by the API body and this event (types/I_AccessDenial.ts), so a
+     * new wall cannot be counted under a reason that does not exist.
+     */
+    reason: AccessDenialCode;
     path?: string;
     app_locale: AppLocale;
   };

package/src/types/I_AccessDenial.ts

@@ -0,0 +1,42 @@
+/**
+ * Why a 403 happened, as a value a client can branch on.
+ *
+ * The frontend used to recognise these walls by comparing the backend's
+ * English message text, and that broke silently the first time a guard's
+ * wording changed: expected entitlement 403s were captured as $exception at a
+ * rate of ten in two minutes of ordinary tapping, burying real errors in the
+ * telemetry that exists to surface them (AD2-1320, 2026-08-19). Prose is copy
+ * and copy changes; this code is contract.
+ *
+ * Every 403 the product EXPECTS carries one of these as `code` in its response
+ * body, alongside the human-readable `message`, which is unchanged.
+ */
+export const ACCESS_DENIAL_CODES = {
+  /** No plan and no beta slot — nothing of their own to look at yet. */
+  BETA_REQUIRED: "beta-required",
+  /** A churned payer attempting a write; they can still read their own data. */
+  SUBSCRIPTION_REQUIRED: "subscription-required",
+  /**
+   * Needs a paid plan AND a connected Late profile. Deliberately distinct from
+   * SUBSCRIPTION_REQUIRED, because it names two preconditions at once: a
+   * paying user who has simply not connected an account yet must never be sent
+   * to buy a plan they already own. Clients show the surface's own empty state
+   * for this one and do NOT redirect.
+   */
+  ENTITLEMENT_PRECONDITION: "entitlement-precondition",
+} as const;
+
+export type AccessDenialCode =
+  (typeof ACCESS_DENIAL_CODES)[keyof typeof ACCESS_DENIAL_CODES];
+
+/**
+ * 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.
+ */
+export interface I_AccessDenialBody {
+  statusCode: number;
+  error: string;
+  message: string;
+  code: AccessDenialCode;
+}

package/src/types/I_User.ts

@@ -13,8 +13,41 @@ export class I_User {
   influencer?: I_Influencer;
 }
 
+/**
+ * The answer an account has recorded about the onboarding tour.
+ *
+ * Three values, and the difference between the last two is the whole point:
+ *   'skipped' | 'completed' — a recorded answer. Never re-teach this user.
+ *   null                    — no record yet. A genuinely new user; show it.
+ *   ABSENT (the field is missing entirely) — the server could not read the
+ *                             column. Decide NOTHING.
+ *
+ * Absent is deliberately not `null`. Collapsing them shows the tour to every
+ * existing user in the window between a deploy and its manual migration
+ * (migrations here are run by hand, never on deploy).
+ */
+export type OnboardingState = 'skipped' | 'completed';
+
 export class I_SignedUser extends I_User {
   accessToken: string;
+
+  /**
+   * AD2-1331 AC3 (Maciej's review, 2026-08-25). Every response that hands back
+   * a session carries this, not just `authenticate` — the client replaces its
+   * authed slice wholesale with whichever payload arrives, so a path that omits
+   * it leaves the answer unknown for the rest of the session (AD2-1329 AC4).
+   *
+   * It lives HERE because AC3 chose an echoing PATCH over a failing one
+   * specifically to remove the forward-only rule from the client, and that only
+   * works if both sides agree on the shape. Until this shipped, the field was
+   * written by the backend, read by the frontend, and declared by neither: the
+   * frontend had to cast through `unknown` to see it, and a rename on either
+   * side would have type-checked clean while the onboarding funnel silently
+   * went dark.
+   *
+   * Optional on purpose — see OnboardingState: absent means "could not read".
+   */
+  onboardingState?: OnboardingState | null;
 }
 
 export enum UserRoles {

package/src/types/index.ts

@@ -36,3 +36,6 @@ export * from "./I_Publish";
 export * from "./I_SM_Platform";
 // ── Scheduling domain ─────────────────────────────────────────────────────────
 export * from "./scheduling";
+
+// ── Access control ────────────────────────────────────────────────────────────
+export * from "./I_AccessDenial";

package/src/types/onboarding-state.test.ts

@@ -0,0 +1,66 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { I_SignedUser, OnboardingState, UserRoles } from './I_User';
+
+/**
+ * AD2-1331 AC3 — the shared shape, pinned.
+ *
+ * These are mostly COMPILE-time assertions: the value of this file is that
+ * `tsc` fails if `onboardingState` is renamed, narrowed, or made required on
+ * one side of the wire. Before it existed the field was written by the backend,
+ * read by the frontend, and declared by neither, so either side could rename it
+ * and every type-check would still pass while the onboarding funnel went dark.
+ *
+ * The runtime assertions below exist so the file is also a real test rather
+ * than a silent type-only artefact that a test runner skips over.
+ */
+
+test('a signed user may carry a recorded answer', () => {
+	const user: I_SignedUser = {
+		id: 'u-1',
+		role: UserRoles.INFLUENCER,
+		accessToken: 'tok',
+		onboardingState: 'completed',
+	};
+
+	assert.equal(user.onboardingState, 'completed');
+});
+
+test('null is a value, and means "no record yet" — a new user', () => {
+	const user: I_SignedUser = {
+		id: 'u-1',
+		role: UserRoles.INFLUENCER,
+		accessToken: 'tok',
+		onboardingState: null,
+	};
+
+	// null must survive as null: the client tells it apart from absent, and
+	// only null means "show the tour".
+	assert.equal(user.onboardingState, null);
+	assert.ok('onboardingState' in user);
+});
+
+test('ABSENT is distinct from null — the field may be omitted entirely', () => {
+	// The migration-pending case. If this ever stops compiling because the
+	// field was made required, the deploy window that follows would show the
+	// onboarding tour to the entire existing user base.
+	const user: I_SignedUser = {
+		id: 'u-1',
+		role: UserRoles.INFLUENCER,
+		accessToken: 'tok',
+	};
+
+	assert.equal('onboardingState' in user, false);
+	assert.equal(user.onboardingState, undefined);
+});
+
+test('the state union is exactly the two recorded answers', () => {
+	const every: OnboardingState[] = ['skipped', 'completed'];
+
+	assert.deepEqual(every, ['skipped', 'completed']);
+	// @ts-expect-error 'pending' is not a recorded answer; null/absent cover
+	// "no answer", and a third string would be a state nobody handles.
+	const invalid: OnboardingState = 'pending';
+	assert.equal(invalid, 'pending');
+});