ad2app-lib 1.27.1 → 1.29.0

package/brand/brand.d.ts

@@ -47,9 +47,18 @@ export interface ColorTokens {
 }
 export const color: ColorTokens;
 
+export interface DisplayFontTokens {
+	/** Direction-5 display face (spec 099 US5, OFL). Display roles only. */
+	family: string;
+	weights: readonly number[];
+	/** Below this size the face is illegible by design — fall back to `family`. */
+	minSizePx: number;
+	role: string;
+}
 export interface FontTokens {
 	family: string;
 	fallback: string;
+	display: DisplayFontTokens;
 }
 export const font: FontTokens;
 

package/brand/brand.mjs

@@ -47,6 +47,20 @@ export const color = {
 export const font = {
   family: 'Funnel Sans',
   fallback: '-apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif',
+  // The Direction-5 DISPLAY face (spec 099 US5; Jan-picked from a five-font exploration; OFL).
+  // It lived only in the landing (SiteShell.tsx wires it through next/font, globals.css exposes it
+  // as --font-display) until 2026-08-12, when a rendered story card was judged against the live
+  // landing and read as another company's: every headline in the motion lane was being set in the
+  // BODY face, because this token had no home here. Display roles ONLY — H1/H2 and big numerals.
+  // Below ~24px Unbounded is illegible by design, so body and UI stay Funnel Sans.
+  // A non-Next consumer (the Remotion lane) must self-host the same family; there is no CDN at
+  // render time.
+  display: {
+    family: 'Unbounded',
+    weights: [500, 700],
+    minSizePx: 24,
+    role: 'display only: h1, h2, big numerals — never body or UI',
+  },
 };
 
 // Social canvas sizes (px), the canonical ad set.

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/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.27.1",
+  "version": "1.29.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",

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