ad2app-lib 1.40.0 → 1.42.0

package/dist/publish-limits/index.d.ts

@@ -2,8 +2,11 @@
  * Canonical publish-limits source of truth for ad2app (AD2-1140 Wave 1).
  *
  * Single source of truth for (a) the per-platform compose/publish limits
- * (character count, image/video counts, max video duration) and (b) the
- * universal media-upload byte cap ad2app itself enforces.
+ * (character count, image/video counts, max video duration), (b) the
+ * universal media-upload byte cap ad2app itself enforces, and (c) which
+ * platforms a PUBLISHED post can be deleted from through our vendor
+ * (UNPUBLISHABLE_PLATFORMS / canUnpublish, ad2app-backend#303), kept here
+ * because it is the same kind of per-platform publishing capability.
  *
  * Provenance:
  *  - Per-platform values are the CORRECTED figures from

package/dist/publish-limits/index.js

@@ -3,8 +3,11 @@
  * Canonical publish-limits source of truth for ad2app (AD2-1140 Wave 1).
  *
  * Single source of truth for (a) the per-platform compose/publish limits
- * (character count, image/video counts, max video duration) and (b) the
- * universal media-upload byte cap ad2app itself enforces.
+ * (character count, image/video counts, max video duration), (b) the
+ * universal media-upload byte cap ad2app itself enforces, and (c) which
+ * platforms a PUBLISHED post can be deleted from through our vendor
+ * (UNPUBLISHABLE_PLATFORMS / canUnpublish, ad2app-backend#303), kept here
+ * because it is the same kind of per-platform publishing capability.
  *
  * Provenance:
  *  - Per-platform values are the CORRECTED figures from

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/scheduling/I_SchedulingProUpgrade.d.ts

@@ -6,6 +6,17 @@
  */
 export type SchedulingSubscriptionTier = 'free' | 'starter' | 'pro';
 export type SchedulingSubscriptionStatus = 'active' | 'canceled' | 'expired';
+/**
+ * Constructor input. Takes `maxAccounts`, or the deprecated `maxPlatforms` so
+ * code written against 1.40.0 keeps compiling; either way both fields are set.
+ */
+export type SchedulingSubscriptionInfoInput = Pick<SchedulingSubscriptionInfoDTO, 'tier' | 'status' | 'expiresAt'> & ({
+    maxAccounts: number;
+    maxPlatforms?: number;
+} | {
+    /** @deprecated Pass `maxAccounts` (ad2app-backend#301). */
+    maxPlatforms: number;
+});
 /**
  * Current subscription state for the authenticated user.
  * Returned by GET /social/subscription.
@@ -14,8 +25,14 @@ export declare class SchedulingSubscriptionInfoDTO {
     tier: SchedulingSubscriptionTier;
     status: SchedulingSubscriptionStatus;
     expiresAt: string | null;
+    /** How many social accounts the plan lets the user connect (free 0, starter 4, pro 10). */
+    maxAccounts: number;
+    /**
+     * @deprecated The cap counts accounts, not platforms (ad2app-backend#301).
+     * Read `maxAccounts`. Always equal to it; removed in a later release.
+     */
     maxPlatforms: number;
-    constructor(data: SchedulingSubscriptionInfoDTO);
+    constructor(data: SchedulingSubscriptionInfoInput);
 }
 /**
  * Response DTO for POST /social/subscription/checkout.
@@ -38,6 +55,16 @@ export interface SchedulingPlanPriceDTO {
     amount: number;
     currency: string;
     interval: string;
+    /**
+     * How many social accounts the plan lets the user connect. Optional only so
+     * 1.40.0-era literals still compile and because a backend older than this
+     * release omits it; read `maxAccounts ?? maxPlatforms`.
+     */
+    maxAccounts?: number;
+    /**
+     * @deprecated The cap counts accounts, not platforms (ad2app-backend#301).
+     * Read `maxAccounts`. Always equal to it; removed in a later release.
+     */
     maxPlatforms: number;
 }
 export declare class SchedulingProductPricesDTO {

package/dist/types/scheduling/I_SchedulingProUpgrade.js

@@ -7,17 +7,18 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SchedulingProUpgradeDTO = exports.SchedulingProductPricesDTO = exports.SchedulingPortalSessionResultDTO = exports.SchedulingCheckoutSessionResultDTO = exports.SchedulingSubscriptionInfoDTO = void 0;
-// ── SchedulingSubscriptionInfoDTO ────────────────────────────────────────────
 /**
  * Current subscription state for the authenticated user.
  * Returned by GET /social/subscription.
  */
 class SchedulingSubscriptionInfoDTO {
     constructor(data) {
+        const maxAccounts = 'maxAccounts' in data ? data.maxAccounts : data.maxPlatforms;
         this.tier = data.tier;
         this.status = data.status;
         this.expiresAt = data.expiresAt;
-        this.maxPlatforms = data.maxPlatforms;
+        this.maxAccounts = maxAccounts;
+        this.maxPlatforms = maxAccounts;
     }
 }
 exports.SchedulingSubscriptionInfoDTO = SchedulingSubscriptionInfoDTO;

package/package.json

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

package/src/publish-limits/index.ts

@@ -2,8 +2,11 @@
  * Canonical publish-limits source of truth for ad2app (AD2-1140 Wave 1).
  *
  * Single source of truth for (a) the per-platform compose/publish limits
- * (character count, image/video counts, max video duration) and (b) the
- * universal media-upload byte cap ad2app itself enforces.
+ * (character count, image/video counts, max video duration), (b) the
+ * universal media-upload byte cap ad2app itself enforces, and (c) which
+ * platforms a PUBLISHED post can be deleted from through our vendor
+ * (UNPUBLISHABLE_PLATFORMS / canUnpublish, ad2app-backend#303), kept here
+ * because it is the same kind of per-platform publishing capability.
  *
  * Provenance:
  *  - Per-platform values are the CORRECTED figures from

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

package/src/types/scheduling/I_SchedulingProUpgrade.ts

@@ -15,6 +15,22 @@ export type SchedulingSubscriptionStatus = 'active' | 'canceled' | 'expired';
 
 // ── SchedulingSubscriptionInfoDTO ────────────────────────────────────────────
 
+/**
+ * Constructor input. Takes `maxAccounts`, or the deprecated `maxPlatforms` so
+ * code written against 1.40.0 keeps compiling; either way both fields are set.
+ */
+export type SchedulingSubscriptionInfoInput = Pick<
+  SchedulingSubscriptionInfoDTO,
+  'tier' | 'status' | 'expiresAt'
+> &
+  (
+    | { maxAccounts: number; maxPlatforms?: number }
+    | {
+        /** @deprecated Pass `maxAccounts` (ad2app-backend#301). */
+        maxPlatforms: number;
+      }
+  );
+
 /**
  * Current subscription state for the authenticated user.
  * Returned by GET /social/subscription.
@@ -23,13 +39,21 @@ export class SchedulingSubscriptionInfoDTO {
   tier: SchedulingSubscriptionTier;
   status: SchedulingSubscriptionStatus;
   expiresAt: string | null;
+  /** How many social accounts the plan lets the user connect (free 0, starter 4, pro 10). */
+  maxAccounts: number;
+  /**
+   * @deprecated The cap counts accounts, not platforms (ad2app-backend#301).
+   * Read `maxAccounts`. Always equal to it; removed in a later release.
+   */
   maxPlatforms: number;
 
-  constructor(data: SchedulingSubscriptionInfoDTO) {
+  constructor(data: SchedulingSubscriptionInfoInput) {
+    const maxAccounts = 'maxAccounts' in data ? data.maxAccounts : data.maxPlatforms;
     this.tier = data.tier;
     this.status = data.status;
     this.expiresAt = data.expiresAt;
-    this.maxPlatforms = data.maxPlatforms;
+    this.maxAccounts = maxAccounts;
+    this.maxPlatforms = maxAccounts;
   }
 }
 
@@ -68,6 +92,16 @@ export interface SchedulingPlanPriceDTO {
   amount: number;
   currency: string;
   interval: string;
+  /**
+   * How many social accounts the plan lets the user connect. Optional only so
+   * 1.40.0-era literals still compile and because a backend older than this
+   * release omits it; read `maxAccounts ?? maxPlatforms`.
+   */
+  maxAccounts?: number;
+  /**
+   * @deprecated The cap counts accounts, not platforms (ad2app-backend#301).
+   * Read `maxAccounts`. Always equal to it; removed in a later release.
+   */
   maxPlatforms: number;
 }
 

package/src/types/scheduling/subscription-allowance.test.ts

@@ -0,0 +1,75 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { SchedulingPlanPriceDTO, SchedulingSubscriptionInfoDTO } from './I_SchedulingProUpgrade';
+
+/**
+ * ad2app-backend#301 — the plan cap counts connected ACCOUNTS. `maxPlatforms`
+ * named the wrong unit on a public response, so `maxAccounts` replaces it and
+ * `maxPlatforms` stays, deprecated, with the identical value until readers
+ * (the MCP connector first) have moved.
+ */
+
+test('subscription info carries maxAccounts', () => {
+	const info = new SchedulingSubscriptionInfoDTO({
+		tier: 'starter',
+		status: 'active',
+		expiresAt: null,
+		maxAccounts: 4,
+	});
+
+	assert.equal(info.maxAccounts, 4);
+});
+
+test('the deprecated maxPlatforms always equals maxAccounts', () => {
+	const info = new SchedulingSubscriptionInfoDTO({
+		tier: 'pro',
+		status: 'active',
+		expiresAt: null,
+		maxAccounts: 10,
+	});
+
+	assert.equal(info.maxPlatforms, 10);
+});
+
+test('a plan price carries both fields', () => {
+	const price: SchedulingPlanPriceDTO = {
+		tier: 'starter',
+		amount: 1600,
+		currency: 'USD',
+		interval: 'month',
+		maxAccounts: 4,
+		maxPlatforms: 4,
+	};
+
+	assert.equal(price.maxAccounts, price.maxPlatforms);
+});
+
+/**
+ * 1.41.0 is a minor release. Code written against 1.40.0 still passes
+ * `maxPlatforms` and builds plan-price literals without `maxAccounts`; both
+ * must keep compiling (backend and frontend master do exactly this).
+ */
+test('the 1.40.0 constructor call still works and fills both fields', () => {
+	const info = new SchedulingSubscriptionInfoDTO({
+		tier: 'starter',
+		status: 'active',
+		expiresAt: null,
+		maxPlatforms: 4,
+	});
+
+	assert.equal(info.maxAccounts, 4);
+	assert.equal(info.maxPlatforms, 4);
+});
+
+test('a 1.40.0 plan-price literal without maxAccounts still type-checks', () => {
+	const price: SchedulingPlanPriceDTO = {
+		tier: 'pro',
+		amount: 3300,
+		currency: 'USD',
+		interval: 'month',
+		maxPlatforms: 10,
+	};
+
+	assert.equal(price.maxAccounts ?? price.maxPlatforms, 10);
+});