@i4e/invest4edu-access-core 0.14.0 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "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

@@ -111,7 +111,7 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       let used = 0;
       const row = rows[0] || null;
       if (feature.is_meterable && row) {
-        const period = periodKey(row.period_granularity || "month", { now, subscriptionId: subscription._id });
+        const period = periodKey(row.period_granularity || "month", { now, subscriptionId: subscription._id, periodStart: subscription.period_start });
         const subjectKey = subjectKeyFor(row.quota_scope, identity) || "";
         const usage = await db.collection("subscription_usage").findOne({
           subscription_id: subscription._id,
@@ -131,6 +131,7 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       return {
         ...result,
         carriedSubscriptionId: subscription._id,
+        carriedPeriodStart: subscription.period_start || null,
         carriedIdentity: identity,
         carriedRow: row,
       };
@@ -155,7 +156,7 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
    */
   async function consume({
     entitlement, featureCode, n = 1, now = new Date(),
-    subscriptionId, row, identity,
+    subscriptionId, row, identity, periodStart,
   } = {}) {
     try {
       const db = getDb();
@@ -166,7 +167,10 @@ 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" };
 
-      const period = periodKey(useRow.period_granularity || "month", { now, subscriptionId: subId });
+      // 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;
+      const period = periodKey(useRow.period_granularity || "month", { now, subscriptionId: subId, periodStart: start });
       const subjectKey = subjectKeyFor(useRow.quota_scope, ident) || "";
       const filter = {
         subscription_id: subId,

package/src/entitlement.js

@@ -40,13 +40,32 @@ function partsInZone(date, timeZone = QUOTA_TIMEZONE) {
  * @param {Object} [opts]
  * @param {Date}   [opts.now]
  * @param {string} [opts.subscriptionId]  required for `term`
+ * @param {Date|string} [opts.periodStart] the current term's start — rolls the `term` bucket
  * @param {string} [opts.timeZone]
  */
-export function periodKey(granularity, { now = new Date(), subscriptionId = null, timeZone } = {}) {
+export function periodKey(granularity, { now = new Date(), subscriptionId = null, periodStart = null, timeZone } = {}) {
   const g = PERIOD_GRANULARITIES.includes(granularity) ? granularity : "month";
   if (g === "lifetime") return "lifetime";
   // A term quota with no subscription would silently collapse every firm into one shared bucket.
-  if (g === "term") return subscriptionId ? `term:${String(subscriptionId)}` : "lifetime";
+  /**
+   * A term bucket is one BILLING TERM, not the subscription's whole life.
+   *
+   * Keying on the subscription alone looks right and is subtly wrong: a subscription document
+   * survives its own transitions — trial becomes paid, a plan is downgraded then upgraded, a year
+   * renews — all on the same `_id`. So an annual allowance consumed during a trial would come out
+   * of the year the customer then paid for. Including where the term STARTED rolls the bucket
+   * every time the term does.
+   *
+   * Without a start date it degrades to the old lifetime-of-subscription key rather than throwing,
+   * because a missing date must not silently move everyone into one shared bucket.
+   */
+  if (g === "term") {
+    if (!subscriptionId) return "lifetime";
+    if (!periodStart) return `term:${String(subscriptionId)}`;
+    const start = periodStart instanceof Date ? periodStart : new Date(periodStart);
+    if (Number.isNaN(start.getTime())) return `term:${String(subscriptionId)}`;
+    return `term:${String(subscriptionId)}:${start.toISOString().slice(0, 10)}`;
+  }
 
   const { y, m, d } = partsInZone(now, timeZone);
   if (g === "year") return y;
@@ -142,7 +161,7 @@ export function resolveEntitlement({
   }
 
   const granularity = row.period_granularity || "month";
-  const period = periodKey(granularity, { now, subscriptionId: subscription._id });
+  const period = periodKey(granularity, { now, subscriptionId: subscription._id, periodStart: subscription.period_start });
   const subject_key = subjectKeyFor(row.quota_scope, identity);
   const remaining = Math.max(0, Number(row.quota) - Number(used || 0));
   const withinQuota = Number(used || 0) < Number(row.quota);

package/src/subscription-lifecycle.js

@@ -29,7 +29,10 @@ export const LIVE_STATUSES = Object.freeze(["trialing", "active", "past_due"]);
 
 export const TRANSITIONS = Object.freeze({
   trialing: ["active", "cancelled", "expired"],
-  active: ["past_due", "blocked", "cancelled"],
+  // `expired` because a FIXED-TERM subscription that reaches its end has simply run out. Without
+  // it the only exits are `blocked`, which implies a deliberate cut-off, and `cancelled`, which
+  // implies the customer chose to leave — neither is true of a 90-day plan reaching day 91.
+  active: ["past_due", "blocked", "cancelled", "expired"],
   past_due: ["active", "blocked", "cancelled"],
   blocked: ["active", "cancelled"],
   cancelled: [],