@i4e/invest4edu-access-core 0.13.0 → 0.14.0

package/package.json

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

@@ -211,7 +211,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 };