@i4e/invest4edu-access-core 0.11.0 → 0.12.0

package/package.json

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

package/src/subscription-lifecycle.js

@@ -0,0 +1,69 @@
+/**
+ * Subscription lifecycle — statuses, transitions and event types. SHARED, because code branches
+ * on these in both backends and a status list that drifts between them means one side treats a
+ * subscription as live while the other has cut access (invariant #11).
+ *
+ * The machine:
+ *
+ *   trialing → active | cancelled | expired
+ *   active   → past_due | blocked | cancelled
+ *   past_due → active | blocked | cancelled          (payment recovered | gave up | user quit)
+ *   blocked  → active | cancelled                    (recovered | closed)
+ *   cancelled / expired → (terminal — a new purchase creates a NEW subscription)
+ *
+ * Terminal states stay terminal on purpose: "reactivating" a cancelled row would resurrect its
+ * history, overrides and period as if nothing happened. A fresh subscription is honest about the
+ * gap and keeps the audit trail of the old one intact.
+ *
+ * Upgrade/downgrade are TRANSITIONS OF PLAN, not of status — a plan change happens on a live
+ * subscription and does not appear here.
+ */
+
+export const SUBSCRIPTION_STATUSES = Object.freeze([
+  "trialing", "active", "past_due", "blocked", "cancelled", "expired",
+]);
+
+/** States in which entitlements resolve. past_due keeps working — cutting access the moment a
+ *  payment is late loses more than it protects; `blocked` is the deliberate cut-off. */
+export const LIVE_STATUSES = Object.freeze(["trialing", "active", "past_due"]);
+
+export const TRANSITIONS = Object.freeze({
+  trialing: ["active", "cancelled", "expired"],
+  active: ["past_due", "blocked", "cancelled"],
+  past_due: ["active", "blocked", "cancelled"],
+  blocked: ["active", "cancelled"],
+  cancelled: [],
+  expired: [],
+});
+
+/** `{ ok }` or `{ ok: false, message }` naming the legal moves — the caller shows it verbatim. */
+export function canTransition(from, to) {
+  const allowed = TRANSITIONS[from];
+  if (!allowed) return { ok: false, message: `${from} is not a subscription status` };
+  if (from === to) return { ok: false, message: `already ${from}` };
+  if (!allowed.includes(to)) {
+    return {
+      ok: false,
+      message: allowed.length
+        ? `${from} can only move to: ${allowed.join(", ")}`
+        : `${from} is terminal — a new purchase creates a new subscription`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Event types — the audit spine AND what the Events Engine receives (`subscription.<type>`).
+ * Engagement and monitoring both hang off this list, so an unlisted type is an event nobody can
+ * subscribe to: recording one is refused rather than silently accepted.
+ */
+export const SUBSCRIPTION_EVENT_TYPES = Object.freeze([
+  "created", "trial_started", "activated", "renewed",
+  "plan_changed", "cycle_changed", "period_extended",
+  "override_set", "override_removed",
+  "status_changed", "cancelled", "blocked", "expired",
+  "payment_captured", "payment_failed",
+  "quota_exceeded",
+]);
+
+export default { SUBSCRIPTION_STATUSES, LIVE_STATUSES, TRANSITIONS, canTransition, SUBSCRIPTION_EVENT_TYPES };