@i4e/invest4edu-access-core 0.17.3 → 0.20.0

package/package.json

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

package/src/entitlement-schema.js

@@ -33,6 +33,16 @@ export const SUBSCRIPTION_STATUSES = Object.freeze([
  */
 export const QUOTA_TIMEZONE = "Asia/Kolkata";
 
+/**
+ * The synthetic feature that carries a credits-mode plan's allowance.
+ *
+ * Credits mode needed no new machinery precisely because the allowance is an ordinary
+ * entitlement row on this code: it inherits cycle columns, effective-date versioning, trial
+ * precedence, as-of resolution and the race-free counter. A plan IS credits-mode when a row for
+ * this code resolves — there is no separate flag to drift out of step with the data.
+ */
+export const CREDITS_FEATURE_CODE = "SUBSCRIPTION.CREDITS";
+
 /** Reasons an entitlement decision can carry. Stable strings — they surface in APIs and logs. */
 export const ENTITLEMENT_REASONS = Object.freeze({
   OK: "ok",
@@ -169,6 +179,7 @@ export const METER_CLIENT_DEF = Object.freeze({
 
 export default {
   PERIOD_GRANULARITIES,
+  CREDITS_FEATURE_CODE,
   QUOTA_SCOPES,
   OVERAGE_POLICIES,
   SUBSCRIPTION_STATUSES,

package/src/entitlement-store.js

@@ -23,7 +23,8 @@
  * outage into a customer-visible one. Absence is far more likely to be our gap than a customer
  * genuinely owning nothing.
  */
-import { resolveEntitlement, periodKey, subjectKeyFor } from "./entitlement.js";
+import { resolveEntitlement, resolveEntitlementRow, periodKey, subjectKeyFor } from "./entitlement.js";
+import { CREDITS_FEATURE_CODE } from "./entitlement-schema.js";
 import { LIVE_STATUSES } from "./subscription-lifecycle.js";
 
 /** Every failure path returns this, so callers never have to branch on "did the lookup work". */
@@ -96,15 +97,105 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       const cycles = subscription.status === "trialing"
         ? ["trial", subscription.cycle]
         : [subscription.cycle];
+      /**
+       * Fetched together: the feature's own rows AND the plan's credit-allowance rows. A plan IS
+       * credits-mode when a SUBSCRIPTION.CREDITS row resolves — the mode is the data, so there is
+       * no flag to drift out of step with it.
+       */
       const fetched = await db.collection("plan_entitlements").find({
         plan_code: subscription.plan_code,
         cycle: { $in: cycles },
-        feature_code: featureCode,
+        feature_code: featureCode === CREDITS_FEATURE_CODE
+          ? featureCode
+          : { $in: [featureCode, CREDITS_FEATURE_CODE] },
       }).toArray();
-      const trialRows = fetched.filter((r) => r.cycle === "trial");
-      const rows = subscription.status === "trialing" && trialRows.length
-        ? trialRows
-        : fetched.filter((r) => r.cycle === subscription.cycle);
+      const pick = (code) => {
+        const mine = fetched.filter((r) => r.feature_code === code);
+        const trial = mine.filter((r) => r.cycle === "trial");
+        return subscription.status === "trialing" && trial.length
+          ? trial
+          : mine.filter((r) => r.cycle === subscription.cycle);
+      };
+      const rows = pick(featureCode);
+      const creditRows = featureCode === CREDITS_FEATURE_CODE ? [] : pick(CREDITS_FEATURE_CODE);
+      const creditsMode = creditRows.length > 0 && feature.is_meterable;
+
+      /**
+       * CREDITS MODE — the feature's own row says whether it is INCLUDED (and may override the
+       * cost); the guard runs against the shared credit allowance, priced per use.
+       *
+       *   cost = plan row's credit_cost  >  service's registry credit_cost  >  1
+       *
+       * The per-plan override is your "premium plans give more usage" lever: eCAS can cost 2 on
+       * Discover and 1 on Grow without any per-feature matrix returning through the back door.
+       */
+      if (creditsMode) {
+        const svcRow = resolveEntitlementRow(rows, featureCode, now);
+        // 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);
+
+          let packBalance = 0;
+          try {
+            const bal = await db.collection("feature_credits").aggregate([
+              { $match: {
+                subject_type: subjectType,
+                subject_id: oid(subjectId),
+                feature_code: CREDITS_FEATURE_CODE,
+                $expr: { $lt: ["$consumed", "$purchased"] },
+                $or: [{ expires_at: null }, { expires_at: { $exists: false } }, { expires_at: { $gt: now } }],
+              } },
+              { $group: { _id: null, n: { $sum: { $subtract: ["$purchased", "$consumed"] } } } },
+            ]).toArray();
+            packBalance = bal[0]?.n || 0;
+          } catch (e) {
+            logger.warn(`[entitlement] credit-pack balance unreadable: ${e.message}`);
+          }
+
+          const creditRow = creditRows[0];
+          const period = periodKey(creditRow.period_granularity || "month", {
+            now, subscriptionId: subscription._id, periodStart: subscription.period_start,
+          });
+          const subjectKey = subjectKeyFor(creditRow.quota_scope, identity) || "";
+          const usage = await db.collection("subscription_usage").findOne({
+            subscription_id: subscription._id,
+            feature_code: CREDITS_FEATURE_CODE,
+            period,
+            subject_key: subjectKey,
+          });
+
+          const result = await resolveEntitlement({
+            subscription,
+            entitlementRows: creditRows,
+            featureCode: CREDITS_FEATURE_CODE,
+            feature: { is_meterable: true },
+            used: usage?.used || 0,
+            credits: packBalance,
+            identity, bypass, now, cost,
+          });
+
+          const effectiveCreditRow = creditRows[0]
+            ? { ...creditRows[0], quota: result.quota, overage_policy: result.overage_policy || creditRows[0].overage_policy }
+            : null;
+
+          return {
+            ...result,
+            mode: "credits",
+            carriedSubjectType: subjectType,
+            carriedSubjectId: subjectId,
+            carriedSubscriptionId: subscription._id,
+            carriedPeriodStart: subscription.period_start || null,
+            carriedIdentity: identity,
+            carriedRow: effectiveCreditRow,
+            // consume() counts against THIS bucket, at THIS price — never recomputed.
+            carriedFeatureCode: CREDITS_FEATURE_CODE,
+            carriedCost: cost,
+          };
+        }
+      }
 
       /**
        * À-la-carte credits — units bought singly. Summed across purchases that still have units
@@ -184,6 +275,31 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
     }
   }
 
+  /**
+   * Per-service breakdown when a shared bucket pays — "where did my 500 credits go".
+   *
+   * Fire-and-forget and unguarded: it is reporting, not enforcement, and a failed attribution
+   * row must never undo a consumption the guard already allowed. Only written when the bucket
+   * differs from the feature (credits mode) — in count mode the guarded row IS the attribution.
+   */
+  function recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now }) {
+    if (!db || bucketCode === featureCode) return;
+    try {
+      const row = entitlement?.carriedRow || {};
+      const period = periodKey(row.period_granularity || "month", {
+        now, subscriptionId: subId, periodStart: entitlement?.carriedPeriodStart,
+      });
+      const subjectKey = subjectKeyFor(row.quota_scope, ident) || "";
+      db.collection("subscription_usage").updateOne(
+        { subscription_id: subId, feature_code: featureCode, period, subject_key: subjectKey },
+        { $inc: { used: n, credits_spent: units }, $setOnInsert: { attribution: true } },
+        { upsert: true },
+      ).catch((e) => logger.warn(`[entitlement] attribution write failed: ${e.message}`));
+    } catch (e) {
+      logger.warn(`[entitlement] attribution skipped: ${e.message}`);
+    }
+  }
+
   /**
    * Consume one unit — race-free by construction.
    *
@@ -210,6 +326,14 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       if (entitlement && !entitlement.metered) return { consumed: false, reason: "not_metered" };
       if (!db || !subId || !useRow) return { consumed: false, reason: "not_metered" };
 
+      /**
+       * Credits mode: the BUCKET is the plan's credit allowance, and one action costs `cost`
+       * units. Both were decided by the resolve that authorised this call — recomputing either
+       * 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);
+
       // The SAME bucket that entitlementFor just checked — recomputing it from different inputs
       // would count against a period nobody validated.
       const start = periodStart !== undefined ? periodStart : entitlement?.carriedPeriodStart;
@@ -228,14 +352,24 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
           {
             subject_type: entitlement.carriedSubjectType,
             subject_id: oid(entitlement.carriedSubjectId),
-            feature_code: featureCode,
-            $expr: { $lt: ["$consumed", "$purchased"] },
+            feature_code: bucketCode,
+            /**
+             * The WHOLE cost must fit in one pack row, decided atomically. A 2-credit action
+             * against a pack with 1 left is refused rather than split across purchases —
+             * splitting would need a transaction across rows, and the boundary case (the last
+             * unit of one pack) is not worth that machinery. The refusal falls through to the
+             * plan counter, which answers honestly.
+             */
+            $expr: { $lte: [{ $add: ["$consumed", units] }, "$purchased"] },
             $or: [{ expires_at: null }, { expires_at: { $exists: false } }, { expires_at: { $gt: now } }],
           },
-          { $inc: { consumed: n } },
+          { $inc: { consumed: units } },
           { sort: { expires_at: 1, createdAt: 1 } },
         );
-        if (hit) return { consumed: true, fromCredit: true };
+        if (hit) {
+          recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
+          return { consumed: true, fromCredit: true };
+        }
         // No credit left after all — fall through and let the plan counter answer, which may well
         // refuse. Better than silently succeeding on a balance that just went to zero.
       }
@@ -244,7 +378,7 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       const subjectKey = subjectKeyFor(useRow.quota_scope, ident) || "";
       const filter = {
         subscription_id: subId,
-        feature_code: featureCode,
+        feature_code: bucketCode,
         period,
         subject_key: subjectKey,
       };
@@ -255,15 +389,21 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       // that record is the evidence for whether a quota is set correctly before anyone is refused.
       if (!capped) {
         await db.collection("subscription_usage").updateOne(
-          filter, { $inc: { used: n }, $setOnInsert: { ...filter } }, { upsert: true },
+          filter, { $inc: { used: units }, $setOnInsert: { ...filter } }, { upsert: true },
         );
+        recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
         return { consumed: true };
       }
 
-      // Capped: try the GUARDED update first, without upsert.
-      const guarded = { ...filter, used: { $lt: Number(useRow.quota) } };
-      const hit = await db.collection("subscription_usage").updateOne(guarded, { $inc: { used: n } });
-      if (hit.matchedCount > 0) return { consumed: true };
+      // Capped: try the GUARDED update first, without upsert. Cost-aware — the whole cost must
+      // fit ($lte quota - units is exactly $lt quota when units is 1), and a balance never goes
+      // negative on an in-flight action.
+      const guarded = { ...filter, used: { $lte: Number(useRow.quota) - units } };
+      const hit = await db.collection("subscription_usage").updateOne(guarded, { $inc: { used: units } });
+      if (hit.matchedCount > 0) {
+        recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
+        return { consumed: true };
+      }
 
       // No match means either "no row yet" (first use this period) or "quota reached". Distinguish
       // by INSERTING — the unique index makes that safe under concurrency: exactly one racer wins
@@ -272,7 +412,11 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       // Doing this as an upsert on the guarded filter instead would rely on a duplicate-key
       // EXCEPTION to mean "quota exceeded" — correct by accident, and unreadable.
       try {
-        await db.collection("subscription_usage").insertOne({ ...filter, used: n, createdAt: new Date() });
+        // First use this period must ALSO fit — an allowance smaller than one action's cost is
+        // refused on action one, not discovered at minus-something.
+        if (Number(useRow.quota) - units < 0) return { consumed: false, reason: "quota_exceeded" };
+        await db.collection("subscription_usage").insertOne({ ...filter, used: units, createdAt: new Date() });
+        recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
         return { consumed: true };
       } catch (e) {
         if (e?.code === 11000) return { consumed: false, reason: "quota_exceeded" };

package/src/entitlement.js

@@ -134,6 +134,12 @@ function withOverride(row, overrides = [], featureCode) {
 export function resolveEntitlement({
   subscription, entitlementRows = [], featureCode, feature = {},
   used = 0, credits = 0, identity = {}, bypass = false, now = new Date(),
+  /**
+   * Units this ONE action costs. 1 for count-mode (used + 1 ≤ quota is exactly the old
+   * used < quota), the service's credit cost when a credits-mode plan is paying. Threading it
+   * through here is what lets one resolver serve both modes instead of a parallel copy.
+   */
+  cost = 1,
 } = {}) {
   const base = {
     quota: null, used, remaining: null, period: null, subject_key: null,
@@ -177,8 +183,11 @@ 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;
   const planRemaining = Math.max(0, Number(row.quota) - Number(used || 0));
-  const withinQuota = Number(used || 0) < Number(row.quota);
+  // 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.
+  const withinQuota = Number(used || 0) + unitCost <= Number(row.quota);
   const policy = row.overage_policy || "block";
 
   /**
@@ -192,7 +201,7 @@ export function resolveEntitlement({
    * Credits do not reset with the period — they were paid for, so they last until used.
    */
   const creditBalance = Math.max(0, Number(credits || 0));
-  const usingCredit = !withinQuota && creditBalance > 0;
+  const usingCredit = !withinQuota && creditBalance >= unitCost;
   const remaining = planRemaining + creditBalance;
 
   return {
@@ -210,6 +219,7 @@ export function resolveEntitlement({
     period,
     subject_key,
     metered: true,
+    cost: unitCost,
   };
 }
 

package/src/proration.js

@@ -0,0 +1,155 @@
+/**
+ * Proration — what the unused part of a running term is worth when someone upgrades.
+ *
+ * Without it, an upgrade STACKS: the new term is appended to the current end date, so the days
+ * already paid for on the smaller plan sit behind the new one, unusable at the new tier. The
+ * customer quietly loses that value and nothing on screen says so.
+ *
+ * The POLICY is configuration, not code — mode, basis, rounding, cap and scope all arrive from
+ * the caller (platform default < plan < service), so changing how proration works is an edit
+ * rather than a deploy. This module is only the arithmetic, kept pure so it can be tested
+ * without a database, a clock or a subscription.
+ *
+ * ── The rules that are NOT configurable, because getting them wrong invents money ────────────
+ *   · credit can never exceed what was actually paid for the current term
+ *   · credit can never exceed the new plan's price (a purchase must not become negative)
+ *   · rounding is toward the CUSTOMER paying more, never less — we do not credit value that was
+ *     not paid for
+ *   · a term that has not started, or has already ended, is worth nothing
+ */
+
+/** Every knob, with the conservative answer as the default. */
+export const PRORATION_DEFAULTS = {
+  /**
+   *   none    — today's behaviour: no credit, the new term stacks on the old end date
+   *   daily   — unused days ÷ total days
+   *   monthly — whole unused months only; a part-month counts for nothing
+   *   points  — no cash credit; the unused value is returned as reward points instead
+   */
+  mode: "none",
+  /** Ceiling on the credit as a percentage of the new plan's price. 100 = up to the full price. */
+  cap_percent: 100,
+  /** Apply when the PLAN changes, and/or when only the billing cycle changes. */
+  on_plan_change: true,
+  on_cycle_change: false,
+};
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/** Whole days between two instants, never negative. */
+function daysBetween(from, to) {
+  const ms = new Date(to).getTime() - new Date(from).getTime();
+  return ms <= 0 ? 0 : Math.floor(ms / MS_PER_DAY);
+}
+
+/** Whole months remaining — a part-month is worth nothing under `monthly`. */
+function wholeMonthsBetween(from, to) {
+  const a = new Date(from);
+  const b = new Date(to);
+  if (b <= a) return 0;
+  let months = (b.getFullYear() - a.getFullYear()) * 12 + (b.getMonth() - a.getMonth());
+  if (b.getDate() < a.getDate()) months -= 1;
+  return months > 0 ? months : 0;
+}
+
+/**
+ * Merge policy layers. Later wins, and only for keys it actually specifies — a plan that sets
+ * only `mode` must not silently reset the cap someone configured globally.
+ */
+export function resolveProrationPolicy(...layers) {
+  const out = { ...PRORATION_DEFAULTS };
+  for (const layer of layers) {
+    if (!layer || typeof layer !== "object") continue;
+    for (const k of Object.keys(PRORATION_DEFAULTS)) {
+      if (layer[k] !== undefined && layer[k] !== null) out[k] = layer[k];
+    }
+  }
+  return out;
+}
+
+/**
+ * What the unused remainder of the current term is worth, in PAISE.
+ *
+ * @param {object}  a
+ * @param {number}  a.paidAmount    what was paid for the CURRENT term (paise, ex-tax)
+ * @param {Date}    a.periodStart   when the current term began
+ * @param {Date}    a.periodEnd     when it ends (null/absent ⇒ open-ended ⇒ nothing to prorate)
+ * @param {Date}    a.now           the moment of the change
+ * @param {number}  a.newPlanPrice  price of what they are moving to (paise, ex-tax) — the cap
+ * @param {boolean} a.isCycleChange true when the plan is unchanged and only the cycle differs
+ * @param {object}  a.policy        resolved policy (see resolveProrationPolicy)
+ * @returns {{credit:number, as_points:boolean, reason:string, days_remaining:number,
+ *            days_total:number, mode:string}}
+ */
+export function prorate({
+  paidAmount = 0,
+  periodStart,
+  periodEnd,
+  now = new Date(),
+  newPlanPrice = 0,
+  isCycleChange = false,
+  policy = PRORATION_DEFAULTS,
+} = {}) {
+  const p = resolveProrationPolicy(policy);
+  const nil = (reason) => ({
+    credit: 0, as_points: false, reason, mode: p.mode, days_remaining: 0, days_total: 0,
+  });
+
+  if (p.mode === "none") return nil("proration is off");
+  if (isCycleChange && !p.on_cycle_change) return nil("cycle changes are not prorated");
+  if (!isCycleChange && !p.on_plan_change) return nil("plan changes are not prorated");
+
+  // An open-ended term (the provisioned default) has no remainder to value: nothing was paid for
+  // a period that does not end.
+  if (!periodEnd) return nil("term has no end date");
+  if (!(paidAmount > 0)) return nil("nothing was paid for the current term");
+
+  const daysTotal = daysBetween(periodStart, periodEnd);
+  const daysRemaining = daysBetween(now, periodEnd);
+  if (daysTotal <= 0) return nil("term length is zero");
+  if (daysRemaining <= 0) return nil("term has already ended");
+
+  let credit;
+  if (p.mode === "monthly") {
+    const monthsRemaining = wholeMonthsBetween(now, periodEnd);
+    const monthsTotal = wholeMonthsBetween(periodStart, periodEnd);
+    if (monthsTotal <= 0 || monthsRemaining <= 0) {
+      return { ...nil("less than a whole month remains"), days_remaining: daysRemaining, days_total: daysTotal };
+    }
+    credit = Math.floor((paidAmount * monthsRemaining) / monthsTotal);
+  } else {
+    // daily, and the basis for `points` too — the difference is only in how it is returned.
+    credit = Math.floor((paidAmount * daysRemaining) / daysTotal);
+  }
+
+  // Never more than was paid. Floating-point and clock skew both make this reachable.
+  credit = Math.min(credit, paidAmount);
+
+  /**
+   * The cap. Without it, a long unused term can exceed the new plan's price and the purchase
+   * goes to zero or negative — the customer upgrades for free, or we owe them money for taking
+   * a bigger plan. Applies to the cash credit only; points are a separate liability that does
+   * not have to fit inside this purchase.
+   */
+  if (p.mode !== "points") {
+    const ceiling = Math.floor((newPlanPrice * Math.max(0, Math.min(100, p.cap_percent))) / 100);
+    if (credit > ceiling) {
+      credit = ceiling;
+    }
+  }
+
+  if (credit <= 0) return { ...nil("nothing to credit"), days_remaining: daysRemaining, days_total: daysTotal };
+
+  return {
+    credit,
+    as_points: p.mode === "points",
+    reason: p.mode === "points"
+      ? `${daysRemaining} unused day(s) returned as points`
+      : `${daysRemaining} of ${daysTotal} day(s) unused`,
+    mode: p.mode,
+    days_remaining: daysRemaining,
+    days_total: daysTotal,
+  };
+}
+
+export default { prorate, resolveProrationPolicy, PRORATION_DEFAULTS };

package/src/subscription-lifecycle.js

@@ -70,6 +70,14 @@ export const SUBSCRIPTION_EVENT_TYPES = Object.freeze([
   // Consumption that happened outside the software — a webinar attended, a VPD session held.
   // There is no request behind it, so this event is the only record of who said it happened.
   "usage_recorded",
+  /**
+   * The refund conversation, recorded as it happens rather than reconstructed afterwards.
+   *
+   * A refund is the one flow where WHO ASKED and WHO AGREED both matter later — a credit note
+   * shows money went back but not that anyone approved it. `refund_requested` is the customer's
+   * ask, `refund_rejected` closes it with a reason, and `refunded` is the money actually moving.
+   */
+  "refund_requested", "refund_approved", "refund_rejected", "refunded",
 ]);
 
 export default { SUBSCRIPTION_STATUSES, LIVE_STATUSES, TRANSITIONS, canTransition, SUBSCRIPTION_EVENT_TYPES };