@i4e/invest4edu-access-core 0.13.0 → 0.15.0

package/package.json

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

@@ -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,
@@ -211,7 +215,93 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
     }
   }
 
-  return { findSubscription, entitlementFor, consume };
+  /**
+   * Give a subject the default plan, if there is one and they have none.
+   *
+   * A distributor who has never bought anything currently resolves to "no subscription", which
+   * fails OPEN — so today every distributor silently has unlimited everything. A default plan is
+   * how that becomes deliberate: a real package with real limits, assigned automatically, so the
+   * system's answer to "what may this person do" stops being "we never decided".
+   *
+   * ── Idempotent, and safe to call from anywhere ───────────────────────────────────────────────
+   * Returns the existing subscription untouched if one is live. That matters because the natural
+   * call site is distributor creation, and distributors get created down several paths (self
+   * onboarding, admin, draft approval, bulk import) — a provisioner that could double-assign would
+   * have to be wired carefully into exactly one of them, which is how coverage gaps happen. This
+   * one can be called from all of them, or twice, or after the fact.
+   *
+   * ── Never fatal ──────────────────────────────────────────────────────────────────────────────
+   * Returns null on any failure rather than throwing. Callers create distributors; a subscription
+   * that could not be provisioned must never be the reason a distributor does not exist. The gap
+   * is recoverable by calling this again — a failed creation is not.
+   *
+   * @param {Object} p
+   * @param {string} p.subjectType   "distributor" | "client"
+   * @param {string} p.subjectId
+   * @param {string} [p.accountId]
+   * @param {Date}   [p.now]
+   * @returns {Promise<Object|null>} the subscription (existing or new), or null
+   */
+  async function provisionDefault({ subjectType, subjectId, accountId = null, now = new Date() } = {}) {
+    try {
+      const db = getDb();
+      if (!db || !subjectType || !subjectId) return null;
+
+      const existing = await findSubscription({ subjectType, subjectId });
+      if (existing) return existing;
+
+      // The default plan is a property of the CATALOGUE, not of this code — so which package new
+      // distributors get, and for how long, is changed by editing a plan rather than deploying.
+      const plan = await db.collection("plan_catalog").findOne({
+        default_for: subjectType,
+        status: "active",
+      });
+      if (!plan) return null;
+
+      const days = Number(plan.default_duration_days) || 0;
+      const start = new Date(now);
+      const end = new Date(now);
+      if (days > 0) end.setDate(end.getDate() + days);
+      // No duration means an open-ended default tier; period_end null reads as "does not lapse".
+      const periodEnd = days > 0 ? end : null;
+
+      /**
+       * Status is `active`, not `trialing`.
+       *
+       * This is a real package on real terms, not a taste of a bigger one — and `trialing` would
+       * make trial-cycle entitlement rows take precedence, quietly applying terms nobody wrote for
+       * this plan. The trial mechanism stays available for plans that actually want it.
+       */
+      const doc = {
+        account_id: accountId ? oid(accountId) : null,
+        subject_type: subjectType,
+        subject_id: oid(subjectId),
+        plan_code: plan.plan_code,
+        cycle: plan.default_cycle || "monthly",
+        status: "active",
+        period_start: start,
+        period_end: periodEnd,
+        provisioned_default: true,   // so a report can tell "given" from "bought"
+        createdAt: new Date(),
+      };
+
+      try {
+        await db.collection("account_subscriptions").insertOne(doc);
+      } catch (e) {
+        // Two creation paths racing on the same subject. The partial unique index on a live
+        // subscription is what makes this safe: one wins, and the loser reads the winner's row
+        // rather than creating a duplicate.
+        if (e?.code === 11000) return findSubscription({ subjectType, subjectId });
+        throw e;
+      }
+      return doc;
+    } catch (e) {
+      logger.warn(`[entitlement] default provisioning failed for ${subjectType} ${subjectId}: ${e.message}`);
+      return null;
+    }
+  }
+
+  return { findSubscription, entitlementFor, consume, provisionDefault };
 }
 
 export default { createEntitlementStore };

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);