@i4e/invest4edu-access-core 0.16.0 → 0.17.0

package/package.json

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

@@ -17,13 +17,20 @@ export interface EntitlementResult {
   metered: boolean;
   quota: number | null;
   used: number;
+  /** Plan allowance left PLUS unspent à-la-carte credits. */
   remaining: number | null;
+  /** Unspent à-la-carte units bought for this subject and feature. */
+  credits?: number;
+  /** True when the plan allowance is gone and the next call spends a purchased credit. */
+  usingCredit?: boolean;
   overage_policy: string;
   reason?: string;
   period?: string | null;
   subject_key?: string | null;
   /** Carried so consume() counts against the exact bucket that was just checked. */
   carriedSubscriptionId?: unknown;
+  carriedSubjectType?: string;
+  carriedSubjectId?: string;
   carriedPeriodStart?: Date | string | null;
   carriedIdentity?: { accountId?: string | null; userId?: string | null };
   carriedRow?: Record<string, unknown> | null;
@@ -31,6 +38,8 @@ export interface EntitlementResult {
 
 export interface ConsumeResult {
   consumed: boolean;
+  /** The unit came out of a purchased credit rather than the plan's period counter. */
+  fromCredit?: boolean;
   /** "not_metered" | "quota_exceeded" | "error" */
   reason?: string;
 }

package/src/entitlement-store.js

@@ -106,6 +106,35 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
         ? trialRows
         : fetched.filter((r) => r.cycle === subscription.cycle);
 
+      /**
+       * À-la-carte credits — units bought singly. Summed across purchases that still have units
+       * left and have not expired. Read alongside usage because the resolver needs both to say
+       * whether the customer may proceed.
+       */
+      let credits = 0;
+      if (feature.is_meterable || feature.single_usage_purchasable) {
+        // Guarded separately: credits are a top-up, and failing to read them must not take the
+        // quota check down with it. Losing a purchased unit is bad; silently ceasing to meter
+        // everyone because one collection is unreachable is worse.
+        try {
+          const bal = await db.collection("feature_credits").aggregate([
+            {
+              $match: {
+                subject_type: subjectType,
+                subject_id: oid(subjectId),
+                feature_code: featureCode,
+                $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();
+          credits = bal[0]?.n || 0;
+        } catch (e) {
+          logger.warn(`[entitlement] credit balance unreadable for ${featureCode}: ${e.message}`);
+        }
+      }
+
       // Only read the counter when something could actually be metered — an unmetered feature
       // should not cost a query on every request.
       let used = 0;
@@ -123,13 +152,15 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       }
 
       const result = await resolveEntitlement({
-        subscription, entitlementRows: rows, featureCode, feature, used, identity, bypass, now,
+        subscription, entitlementRows: rows, featureCode, feature, used, credits, identity, bypass, now,
       });
 
       // Carry what consume() needs, so it cannot recompute the period key and count against a
       // different bucket than the one that was just checked.
       return {
         ...result,
+        carriedSubjectType: subjectType,
+        carriedSubjectId: subjectId,
         carriedSubscriptionId: subscription._id,
         carriedPeriodStart: subscription.period_start || null,
         carriedIdentity: identity,
@@ -170,6 +201,33 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       // 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;
+      /**
+       * Spending a purchased credit instead of the plan's allowance.
+       *
+       * `usingCredit` was decided by the same resolve that authorised this call, so the two cannot
+       * disagree about which bucket was checked and which is being drawn down. The guard
+       * `consumed < purchased` sits INSIDE the filter for the same reason the quota test does:
+       * Mongo decides atomically, so two concurrent calls cannot both spend the last unit.
+       *
+       * Oldest purchase first — a credit with an expiry should be used before one without.
+       */
+      if (entitlement?.usingCredit) {
+        const hit = await db.collection("feature_credits").findOneAndUpdate(
+          {
+            subject_type: entitlement.carriedSubjectType,
+            subject_id: oid(entitlement.carriedSubjectId),
+            feature_code: featureCode,
+            $expr: { $lt: ["$consumed", "$purchased"] },
+            $or: [{ expires_at: null }, { expires_at: { $exists: false } }, { expires_at: { $gt: now } }],
+          },
+          { $inc: { consumed: n } },
+          { sort: { expires_at: 1, createdAt: 1 } },
+        );
+        if (hit) 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.
+      }
+
       const period = periodKey(useRow.period_granularity || "month", { now, subscriptionId: subId, periodStart: start });
       const subjectKey = subjectKeyFor(useRow.quota_scope, ident) || "";
       const filter = {

package/src/entitlement.js

@@ -111,6 +111,7 @@ function withOverride(row, overrides = [], featureCode) {
  * @param {string} p.featureCode
  * @param {Object} p.feature                 registry row — `is_meterable` decides if quota applies
  * @param {number} p.used                    already consumed in this period (caller supplies)
+ * @param {number} [p.credits]               à-la-carte units bought and not yet spent
  * @param {Object} p.identity                { accountId, userId }
  * @param {boolean} [p.bypass]               D27 admin break-glass
  * @param {Date}   [p.now]
@@ -119,7 +120,7 @@ function withOverride(row, overrides = [], featureCode) {
  */
 export function resolveEntitlement({
   subscription, entitlementRows = [], featureCode, feature = {},
-  used = 0, identity = {}, bypass = false, now = new Date(),
+  used = 0, credits = 0, identity = {}, bypass = false, now = new Date(),
 } = {}) {
   const base = {
     quota: null, used, remaining: null, period: null, subject_key: null,
@@ -163,19 +164,36 @@ 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 remaining = Math.max(0, Number(row.quota) - Number(used || 0));
+  const planRemaining = Math.max(0, Number(row.quota) - Number(used || 0));
   const withinQuota = Number(used || 0) < Number(row.quota);
   const policy = row.overage_policy || "block";
 
+  /**
+   * À-la-carte credits — units bought one at a time rather than as part of a plan.
+   *
+   * They top up the plan's allowance rather than replacing it, and are spent ONLY once the plan
+   * allowance is gone. That ordering is the whole point: someone who bought ten extra analyses and
+   * then renews should not find their purchase quietly consumed by a month they had covered
+   * anyway. Plan first, purchase second.
+   *
+   * 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 remaining = planRemaining + creditBalance;
+
   return {
     unlocked: true,
     quota: Number(row.quota),
     used: Number(used || 0),
     remaining,
+    credits: creditBalance,
+    /** Tells consume() which bucket to draw from — the plan's counter, or a purchased credit. */
+    usingCredit,
     // Only `block` denies. single_usage/unlimited let the call through — billing catches up after.
-    allowed: withinQuota || policy !== "block",
+    allowed: withinQuota || usingCredit || policy !== "block",
     overage_policy: policy,
-    reason: withinQuota ? R.OK : R.QUOTA_EXCEEDED,
+    reason: withinQuota || usingCredit ? R.OK : R.QUOTA_EXCEEDED,
     period,
     subject_key,
     metered: true,