@i4e/invest4edu-access-core 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.20.0",
+  "version": "0.22.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": {
@@ -19,7 +19,8 @@
     "./route-features": "./src/route-features.js",
     "./subscription-lifecycle": "./src/subscription-lifecycle.js",
     "./entitlement-store": "./src/entitlement-store.js",
-    "./proration": "./src/proration.js"
+    "./proration": "./src/proration.js",
+    "./credits": "./src/credits.js"
   },
   "scripts": {
     "test": "node --test test/"

package/src/credits.js

@@ -0,0 +1,128 @@
+/**
+ * Credits — what happens to an unused allowance when a term ends.
+ *
+ * A credits plan hands out an allowance per term (500 credits a month) and every service spends
+ * from it at its own price. At the term boundary the counter resets, and the question nobody can
+ * avoid answering is what the unspent remainder was worth. Silence is itself an answer — the
+ * default today is that it evaporates, which is fine as a policy and indefensible as an accident.
+ *
+ * ── Rollover is a POLICY, resolved in layers ─────────────────────────────────────────────────
+ * platform default < plan. Same shape and same merge rule as proration, because they are the
+ * same kind of decision: what unused value is worth when the ground moves under it.
+ *
+ * ── The rules that are NOT configurable, because getting them wrong invents credits ──────────
+ *   · you can never roll more than went unused — the cap trims, it never tops up
+ *   · an unlimited allowance rolls nothing: there was no scarcity to carry forward
+ *   · rounding is DOWN, so a rollover never hands out a credit that was not left over
+ *   · rolled credits expire; carrying them forever turns a monthly allowance into a savings
+ *     account and makes the liability unbounded. They lapse at the end of the term they land in
+ *
+ * Kept pure — no database, no clock, no subscription — so the arithmetic is testable on its own.
+ */
+
+/** Every knob, with the conservative answer as the default. */
+export const CREDITS_DEFAULTS = {
+  /**
+   *   none   — the remainder lapses at the term boundary (today's behaviour)
+   *   full   — everything unused carries into the next term
+   *   capped — carries, but no more than `cap_percent` of the allowance
+   */
+  rollover_mode: "none",
+  /** Ceiling on what may roll, as a percentage of the term's allowance. Only used by `capped`. */
+  rollover_cap_percent: 50,
+  /**
+   * How long rolled credits survive, in terms. 1 = they must be used in the term they land in.
+   * Rolled credits never roll again regardless — carrying a carry compounds into a balance that
+   * no one budgeted for.
+   */
+  rollover_expires_in_terms: 1,
+};
+
+/**
+ * Merge policy layers. Later wins, and only for keys it actually specifies — a plan that sets
+ * only the mode must not silently reset a cap someone configured globally.
+ */
+export function resolveCreditsPolicy(...layers) {
+  const out = { ...CREDITS_DEFAULTS };
+  for (const layer of layers) {
+    if (!layer || typeof layer !== "object") continue;
+    for (const k of Object.keys(CREDITS_DEFAULTS)) {
+      if (layer[k] !== undefined && layer[k] !== null) out[k] = layer[k];
+    }
+  }
+  return out;
+}
+
+/**
+ * How many credits carry into the next term.
+ *
+ * @param {object}  a
+ * @param {number|null} a.quota  the term's allowance. null = unlimited ⇒ nothing to carry
+ * @param {number}  a.used       credits spent this term
+ * @param {object}  a.policy     resolved policy (see resolveCreditsPolicy)
+ * @returns {{units:number, reason:string, unused:number, cap:number|null, mode:string}}
+ */
+export function computeRollover({ quota, used = 0, policy = CREDITS_DEFAULTS } = {}) {
+  const p = resolveCreditsPolicy(policy);
+  const mode = p.rollover_mode;
+  const nil = (reason) => ({ units: 0, reason, unused: 0, cap: null, mode });
+
+  if (mode === "none") return nil("rollover is off");
+  // Unlimited means the allowance never constrained anything, so there is no remainder to carry.
+  // Rolling "infinity minus what you used" is not a number, and any finite stand-in is invented.
+  if (quota == null) return nil("allowance is unlimited — nothing to carry");
+
+  const allowance = Number(quota);
+  if (!Number.isFinite(allowance) || allowance <= 0) return nil("no allowance this term");
+
+  const spent = Math.max(0, Number(used) || 0);
+  // Overage can push `used` past the quota under a warn policy; a negative remainder is not a debt.
+  const unused = Math.max(0, allowance - spent);
+  if (unused <= 0) return { units: 0, reason: "allowance fully used", unused: 0, cap: null, mode };
+
+  if (mode === "full") {
+    return { units: Math.floor(unused), reason: "carried in full", unused, cap: null, mode };
+  }
+
+  if (mode === "capped") {
+    const pct = Math.max(0, Math.min(100, Number(p.rollover_cap_percent) || 0));
+    const cap = Math.floor((allowance * pct) / 100);
+    const units = Math.min(Math.floor(unused), cap);
+    return {
+      units,
+      reason: units < unused ? `capped at ${pct}% of the allowance` : "carried in full (under the cap)",
+      unused,
+      cap,
+      mode,
+    };
+  }
+
+  // An unrecognised mode is a config error. Carrying nothing is the safe reading of it — the
+  // alternative invents a balance from a typo.
+  return nil(`unknown rollover mode "${mode}"`);
+}
+
+/**
+ * When rolled credits lapse: the end of the term they can be used in.
+ *
+ * Needs the length of the term they are landing in, which the caller knows and this module
+ * deliberately does not. A term with no end (open-ended subscription) yields null — nothing to
+ * expire against, and inventing a date would silently destroy paid-for value.
+ */
+export function rolloverExpiryDate({ nextPeriodStart, nextPeriodEnd, policy = CREDITS_DEFAULTS } = {}) {
+  const p = resolveCreditsPolicy(policy);
+  if (!nextPeriodEnd) return null;
+  const end = new Date(nextPeriodEnd);
+  if (Number.isNaN(end.getTime())) return null;
+
+  const terms = Math.max(1, Math.floor(Number(p.rollover_expires_in_terms) || 1));
+  if (terms === 1) return end;
+
+  // More than one term: extend by the length of the term they land in, which is the only measure
+  // of "a term" available here. Without a start we cannot know that length, so we keep the single
+  // term rather than guess — under-granting is recoverable, over-granting is not.
+  const start = nextPeriodStart ? new Date(nextPeriodStart) : null;
+  if (!start || Number.isNaN(start.getTime()) || start >= end) return end;
+  const termMs = end.getTime() - start.getTime();
+  return new Date(end.getTime() + termMs * (terms - 1));
+}

package/src/entitlement-store.js

@@ -134,9 +134,10 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
         // Not named in a credits plan → the same fail-open NOT_IN_PLAN as count mode. A plan
         // that forgot to include a feature is a config gap, not a paywall.
         if (svcRow && svcRow.unlocked !== false) {
-          const cost = Number(svcRow.credit_cost) > 0
-            ? Number(svcRow.credit_cost)
-            : (Number(feature.credit_cost) > 0 ? Number(feature.credit_cost) : 1);
+          // UNSET falls through to the next layer; 0 does not — it is the plan saying "free".
+          const priced = (v) => (v === null || v === undefined || v === "" || !Number.isFinite(Number(v)) || Number(v) < 0
+            ? null : Number(v));
+          const cost = priced(svcRow.credit_cost) ?? priced(feature.credit_cost) ?? 1;
 
           let packBalance = 0;
           try {
@@ -332,7 +333,14 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
        * here could draw from a bucket nobody checked, at a price nobody quoted.
        */
       const bucketCode = entitlement?.carriedFeatureCode || featureCode;
-      const units = n * (Number(entitlement?.carriedCost) > 0 ? Number(entitlement.carriedCost) : 1);
+      const carried = Number(entitlement?.carriedCost);
+      const units = n * (Number.isFinite(carried) && carried >= 0 ? carried : 1);
+
+      /**
+       * A free action inside a credits plan: authorised, but there is no balance to move. Writing
+       * a zero increment would still create the row and make it look like something was spent.
+       */
+      if (units === 0) return { consumed: true, free: true };
 
       // The SAME bucket that entitlementFor just checked — recomputing it from different inputs
       // would count against a period nobody validated.

package/src/entitlement.js

@@ -183,7 +183,18 @@ export function resolveEntitlement({
   const granularity = row.period_granularity || "month";
   const period = periodKey(granularity, { now, subscriptionId: subscription._id, periodStart: subscription.period_start });
   const subject_key = subjectKeyFor(row.quota_scope, identity);
-  const unitCost = Number(cost) > 0 ? Number(cost) : 1;
+  /**
+   * Zero is a PRICE, not a missing value.
+   *
+   * "Included, costs nothing" is a thing a credits plan has to be able to say, and the most
+   * important thing it says it about is placing an order: metered, unlimited on every plan today,
+   * and the last action that should ever be refused for an empty balance. Coercing 0 up to 1
+   * would quietly put revenue behind the credit meter.
+   */
+  // null and "" are UNSET, and Number() turns both into 0 — which would read as "free" and hand
+  // away exactly what this branch exists to protect. Only a real number counts as a price.
+  const raw = cost === null || cost === undefined || cost === "" ? 1 : Number(cost);
+  const unitCost = Number.isFinite(raw) && raw >= 0 ? raw : 1;
   const planRemaining = Math.max(0, Number(row.quota) - Number(used || 0));
   // Cost-aware: the action is allowed only if the WHOLE cost fits. Refusing at balance < cost is
   // the agreed rule — a balance never goes negative on an in-flight action.