@i4e/invest4edu-access-core 0.24.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
   "type": "module",
   "exports": {

package/src/entitlement-store.js

@@ -53,9 +53,34 @@ const noopLogger = { warn() {}, info() {} };
  *                                    would silently look unsubscribed.
  * @param {Object}   [opts.logger]   anything with `warn`
  */
-export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger = noopLogger } = {}) {
+export function createEntitlementStore({
+  getDb,
+  toObjectId = (v) => v,
+  logger = noopLogger,
+  /**
+   * THE subscription master switch.
+   *
+   * One place that makes the whole domain inert: no entitlement decides anything, no counter
+   * moves, no subject is auto-provisioned. Per-feature `rollout_mode` still governs which gates
+   * are live once this is on — this is the switch above all of them, for shipping the code long
+   * before the product.
+   *
+   * OFF by default, deliberately. A release must be able to carry every line of this and change
+   * nothing for a single user; a default of "on" would make that depend on remembering to set a
+   * flag, and the failure mode is customers being charged and refused.
+   *
+   * Resolved by the CALLER — env, a config document, whatever each service already uses — so this
+   * package keeps no opinion about where configuration lives.
+   */
+  isEnabled = () => String(process.env.SUBSCRIPTION_ENABLED || "").toLowerCase() === "true",
+} = {}) {
   if (typeof getDb !== "function") throw new Error("createEntitlementStore requires getDb()");
 
+  /** Resolved per call, never cached, so flipping the switch takes effect without a restart. */
+  const enabled = async () => {
+    try { return (await isEnabled()) === true; } catch { return false; }
+  };
+
   const oid = (v) => {
     try { return toObjectId(String(v)); } catch { return v; }
   };
@@ -82,6 +107,9 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
     bypass = false, now = new Date(),
   } = {}) {
     try {
+      // Master switch off ⇒ the same OPEN answer as "no subscription": allowed, unshaped,
+      // unmetered. Every caller already handles this, because it is the fail-open path.
+      if (!(await enabled())) return OPEN("subscription_disabled");
       const db = getDb();
       if (!db || !subjectType || !subjectId) return OPEN("no_subject");
 
@@ -324,6 +352,14 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       const useRow = row || entitlement?.carriedRow;
       const ident = identity || entitlement?.carriedIdentity || {};
       // An unmetered feature has nothing to count; saying so is not a failure.
+      /**
+       * Checked before anything else, including the not-metered short-circuits: "the domain is
+       * off" is a truer answer than "this feature is not metered", and it has to hold even when
+       * the caller passed nothing useful. Returning `consumed: false` rather than throwing keeps
+       * callers on the path they already have for "the counter did not move".
+       */
+      if (!(await enabled())) return { consumed: false, reason: "subscription_disabled" };
+
       if (entitlement && !entitlement.metered) return { consumed: false, reason: "not_metered" };
       if (!db || !subId || !useRow) return { consumed: false, reason: "not_metered" };
 
@@ -466,6 +502,10 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
    */
   async function provisionDefault({ subjectType, subjectId, accountId = null, now = new Date() } = {}) {
     try {
+      // No auto-provisioning while the domain is off, whatever the catalogue says. This is the
+      // one that would otherwise write rows into production on the first distributor created.
+      if (!(await enabled())) return null;
+
       const db = getDb();
       if (!db || !subjectType || !subjectId) return null;
 

package/src/entitlement.js

@@ -144,6 +144,12 @@ export function resolveEntitlement({
   const base = {
     quota: null, used, remaining: null, period: null, subject_key: null,
     overage_policy: "unlimited", metered: false,
+    /**
+     * A CEILING that shapes a response — top-N picks, tips per answer — as opposed to `quota`,
+     * which is a budget that decrements. Null when the plan sets none. Present on every result so
+     * a caller never has to tell "no ceiling" from "this resolver is too old to send one".
+     */
+    limit: null,
   };
   const open = (reason) => ({ ...base, unlocked: true, allowed: true, reason });
 
@@ -211,8 +217,28 @@ export function resolveEntitlement({
   }
 
   // Unlocked but not metered → nothing to count.
+  /**
+   * Unlocked but not counted.
+   *
+   * `limit` is carried through even though nothing is metered, because a number on an unmetered
+   * row is a CEILING rather than a budget: "your top-picks list shows 5" is read on every request
+   * and never decrements. Returning it lets a caller shape its response from the plan instead of
+   * hard-coding the shape, which is the difference between a config edit and a deploy.
+   *
+   * `quota` deliberately stays null here — it means "how much is left", and nothing is being
+   * spent. Reusing it for a ceiling would make `remaining` a lie and invite a consume() call that
+   * should never happen.
+   */
   if (!feature.is_meterable || row.quota === null || row.quota === undefined) {
-    return { ...open(feature.is_meterable ? R.OK : R.NOT_METERED), overage_policy: row.overage_policy || "unlimited" };
+    // null/undefined is UNSET, and Number() turns both into 0 — which would read as "show
+    // nothing", the exact opposite. Only a real number is a ceiling.
+    const raw = row.quota;
+    const ceiling = raw === null || raw === undefined || raw === "" ? null : Number(raw);
+    return {
+      ...open(feature.is_meterable ? R.OK : R.NOT_METERED),
+      overage_policy: row.overage_policy || "unlimited",
+      limit: ceiling !== null && Number.isFinite(ceiling) && ceiling >= 0 ? ceiling : null,
+    };
   }
 
   const granularity = row.period_granularity || "month";
@@ -252,6 +278,8 @@ export function resolveEntitlement({
 
   return {
     unlocked: true,
+    // Declared even on a metered result: absence must never be mistaken for "no ceiling".
+    limit: null,
     quota: Number(row.quota),
     used: Number(used || 0),
     remaining,