ad2app-lib 1.41.0 → 1.42.0

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/package.json

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

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/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',
+	});
+});