@i4e/invest4edu-access-core 0.31.0 → 0.32.0

package/src/index.js

@@ -1,57 +1,74 @@
-/**
- * @i4e/invest4edu-access-core — shared access-control primitives for the NFD backends.
- * Tenant isolation (D1 keystone) + role capabilities (G7).
- */
-export { default as als, runWithTenant, runAsSystem, getTenantStore } from "./tenant-context.js";
-export {
-  default as tenantPlugin,
-  setTenantMode,
-  getTenantMode,
-  setTenantWriteMode,
-  getTenantWriteMode,
-  TENANT_MODES,
-} from "./tenant-plugin.js";
-export {
-  CAPABILITY_FLAGS,
-  DEFAULT_ROLE_CAPABILITIES,
-  buildCapabilityMap,
-  resolveCapabilities,
-} from "./role-capabilities.js";
-export { resolveReporteeUserIds } from "./reportee-tree.js";
-export {
-  DEFAULT_ACCESS_FLAGS,
-  ACCESS_FLAG_ENV_NAMES,
-  flagEnvName,
-  readEnvFlags,
-  resolveFlags,
-} from "./access-config.js";
-
-// ── Unified access framework (P1) ─────────────────────────────────────────────────────────────
-export {
-  FEATURE_TYPES,
-  REGISTRY_STATUSES,
-  ROLLOUT_MODES,
-  GRANT_EFFECTS,
-  GRANT_SUBJECTS,
-  FEATURE_CODE_PATTERN,
-  isValidFeatureCode,
-  parentCodeOf,
-  moduleCodeOf,
-  ACCESS_MODULE_DEF,
-  ACCESS_FEATURE_DEF,
-  ACCESS_GRANT_DEF,
-} from "./access-schema.js";
-export {
-  resolveAccessSnapshot,
-  mergeGrants,
-  buildNav,
-  hasFeature,
-  isUsable,
-  ENTITLEMENT_REASONS,
-} from "./access-resolver.js";
-export {
-  evaluateVisibleWhen,
-  filterVisible,
-  applyRelabel,
-  resolveColumns,
-} from "./visible-when.js";
+/**
+ * @i4e/invest4edu-access-core — shared access-control primitives for the NFD backends.
+ * Tenant isolation (D1 keystone) + role capabilities (G7).
+ */
+export { default as als, runWithTenant, runAsSystem, getTenantStore } from "./tenant-context.js";
+export {
+  default as tenantPlugin,
+  setTenantMode,
+  getTenantMode,
+  setTenantWriteMode,
+  getTenantWriteMode,
+  TENANT_MODES,
+} from "./tenant-plugin.js";
+export {
+  CAPABILITY_FLAGS,
+  DEFAULT_ROLE_CAPABILITIES,
+  buildCapabilityMap,
+  resolveCapabilities,
+} from "./role-capabilities.js";
+export { resolveReporteeUserIds } from "./reportee-tree.js";
+export {
+  ENTITY,
+  ENTITY_STATUS,
+  isEntityLoginAllowed,
+  entityInactiveMessage,
+  checkPortalEntityAccess,
+} from "./entity-status.js";
+export {
+  CONFLICTING_ENTITIES,
+  conflictingEntityFor,
+  entityConflictMessage,
+} from "./user-entity-link.js";
+export {
+  CLIENT_APP_ROLE_NAMES,
+  ROLE_TYPE_PRIORITY,
+  pickPortalRoleName,
+} from "./portal-roles.js";
+export {
+  DEFAULT_ACCESS_FLAGS,
+  ACCESS_FLAG_ENV_NAMES,
+  flagEnvName,
+  readEnvFlags,
+  resolveFlags,
+} from "./access-config.js";
+
+// ── Unified access framework (P1) ─────────────────────────────────────────────────────────────
+export {
+  FEATURE_TYPES,
+  REGISTRY_STATUSES,
+  ROLLOUT_MODES,
+  GRANT_EFFECTS,
+  GRANT_SUBJECTS,
+  FEATURE_CODE_PATTERN,
+  isValidFeatureCode,
+  parentCodeOf,
+  moduleCodeOf,
+  ACCESS_MODULE_DEF,
+  ACCESS_FEATURE_DEF,
+  ACCESS_GRANT_DEF,
+} from "./access-schema.js";
+export {
+  resolveAccessSnapshot,
+  mergeGrants,
+  buildNav,
+  hasFeature,
+  isUsable,
+  ENTITLEMENT_REASONS,
+} from "./access-resolver.js";
+export {
+  evaluateVisibleWhen,
+  filterVisible,
+  applyRelabel,
+  resolveColumns,
+} from "./visible-when.js";

package/src/portal-roles.js

@@ -0,0 +1,66 @@
+/**
+ * Which roles belong to which surface, and which one names a portal session.
+ *
+ * One person is one `users` row that may hold a partner role and a client role at the
+ * same time. Permissions resolve as a union across roles, and the frontend collapses the
+ * array to a single `role_type` string — so both "which roles apply here" and "which one
+ * wins" have to be answered deliberately rather than by array order.
+ *
+ * Lives here because it was written three times: nfd-api-node, nfd-api-node-v2 and the
+ * frontend each held the same sixteen names in the same order. The frontend's copy was the
+ * one nothing pinned, and it is also the one where drift is quietest — a wrong `role_type`
+ * renders as missing screens, not as an error.
+ */
+
+/** Roles that exist only for the client app. A portal session never carries these. */
+export const CLIENT_APP_ROLE_NAMES = ['CLIENT_USER'];
+
+/**
+ * Priority order for resolving the single `role_type` a portal session reports.
+ *
+ * Most-privileged first, so a person wearing several hats is described by the strongest.
+ * Partner roles sit ahead of CLIENT_ADMIN deliberately: on the portal, someone who is
+ * both a partner and a client-facing admin is there as the partner.
+ *
+ * Adding a role here is what makes it visible to the frontend's role predicates — a role
+ * missing from this list resolves to an empty `role_type`.
+ */
+export const ROLE_TYPE_PRIORITY = [
+  'SUPER_ADMIN',
+  'BROKER_ADMIN',
+  'MANUFACTURER_ADMIN',
+  'DISTRIBUTOR_ADMIN',
+  'PARTNER_ADMIN',
+  'BASIC_PLAN_PARTNERS',
+  // The default role of every self-signed-up partner. Its absence from the old list is
+  // why they resolved to an empty role_type and the client had to guess positionally.
+  'DRAFT_DISTRIBUTOR_USER',
+  'INTERN_USER',
+  'DISTRIBUTOR_TRIAL',
+  'BROKER_PRODUCT_ADMINS',
+  'BACKOFFICE_USER',
+  'HR_USER',
+  'HR',
+  'PAT_SALES',
+  'SALES_USER',
+  'CLIENT_ADMIN',
+];
+
+/**
+ * The role that names a session, out of every role name held.
+ *
+ * Client-app roles are dropped first: they match no portal predicate, so landing on one
+ * reads as "neither partner nor client" and hides every partner screen. A role outside
+ * the priority list is still better than nothing — it simply cannot be ranked, so the
+ * first remaining one wins.
+ *
+ * @param {string[]} roleNames
+ * @returns {string} the winning role name, or '' when none applies to a portal session
+ */
+export function pickPortalRoleName(roleNames) {
+  const portalNames = (roleNames || [])
+    .filter(Boolean)
+    .filter((name) => !CLIENT_APP_ROLE_NAMES.includes(name));
+
+  return ROLE_TYPE_PRIORITY.find((r) => portalNames.includes(r)) || portalNames[0] || '';
+}

package/src/proration.js

@@ -1,155 +1,155 @@
-/**
- * Proration — what the unused part of a running term is worth when someone upgrades.
- *
- * Without it, an upgrade STACKS: the new term is appended to the current end date, so the days
- * already paid for on the smaller plan sit behind the new one, unusable at the new tier. The
- * customer quietly loses that value and nothing on screen says so.
- *
- * The POLICY is configuration, not code — mode, basis, rounding, cap and scope all arrive from
- * the caller (platform default < plan < service), so changing how proration works is an edit
- * rather than a deploy. This module is only the arithmetic, kept pure so it can be tested
- * without a database, a clock or a subscription.
- *
- * ── The rules that are NOT configurable, because getting them wrong invents money ────────────
- *   · credit can never exceed what was actually paid for the current term
- *   · credit can never exceed the new plan's price (a purchase must not become negative)
- *   · rounding is toward the CUSTOMER paying more, never less — we do not credit value that was
- *     not paid for
- *   · a term that has not started, or has already ended, is worth nothing
- */
-
-/** Every knob, with the conservative answer as the default. */
-export const PRORATION_DEFAULTS = {
-  /**
-   *   none    — today's behaviour: no credit, the new term stacks on the old end date
-   *   daily   — unused days ÷ total days
-   *   monthly — whole unused months only; a part-month counts for nothing
-   *   points  — no cash credit; the unused value is returned as reward points instead
-   */
-  mode: "none",
-  /** Ceiling on the credit as a percentage of the new plan's price. 100 = up to the full price. */
-  cap_percent: 100,
-  /** Apply when the PLAN changes, and/or when only the billing cycle changes. */
-  on_plan_change: true,
-  on_cycle_change: false,
-};
-
-const MS_PER_DAY = 24 * 60 * 60 * 1000;
-
-/** Whole days between two instants, never negative. */
-function daysBetween(from, to) {
-  const ms = new Date(to).getTime() - new Date(from).getTime();
-  return ms <= 0 ? 0 : Math.floor(ms / MS_PER_DAY);
-}
-
-/** Whole months remaining — a part-month is worth nothing under `monthly`. */
-function wholeMonthsBetween(from, to) {
-  const a = new Date(from);
-  const b = new Date(to);
-  if (b <= a) return 0;
-  let months = (b.getFullYear() - a.getFullYear()) * 12 + (b.getMonth() - a.getMonth());
-  if (b.getDate() < a.getDate()) months -= 1;
-  return months > 0 ? months : 0;
-}
-
-/**
- * Merge policy layers. Later wins, and only for keys it actually specifies — a plan that sets
- * only `mode` must not silently reset the cap someone configured globally.
- */
-export function resolveProrationPolicy(...layers) {
-  const out = { ...PRORATION_DEFAULTS };
-  for (const layer of layers) {
-    if (!layer || typeof layer !== "object") continue;
-    for (const k of Object.keys(PRORATION_DEFAULTS)) {
-      if (layer[k] !== undefined && layer[k] !== null) out[k] = layer[k];
-    }
-  }
-  return out;
-}
-
-/**
- * What the unused remainder of the current term is worth, in PAISE.
- *
- * @param {object}  a
- * @param {number}  a.paidAmount    what was paid for the CURRENT term (paise, ex-tax)
- * @param {Date}    a.periodStart   when the current term began
- * @param {Date}    a.periodEnd     when it ends (null/absent ⇒ open-ended ⇒ nothing to prorate)
- * @param {Date}    a.now           the moment of the change
- * @param {number}  a.newPlanPrice  price of what they are moving to (paise, ex-tax) — the cap
- * @param {boolean} a.isCycleChange true when the plan is unchanged and only the cycle differs
- * @param {object}  a.policy        resolved policy (see resolveProrationPolicy)
- * @returns {{credit:number, as_points:boolean, reason:string, days_remaining:number,
- *            days_total:number, mode:string}}
- */
-export function prorate({
-  paidAmount = 0,
-  periodStart,
-  periodEnd,
-  now = new Date(),
-  newPlanPrice = 0,
-  isCycleChange = false,
-  policy = PRORATION_DEFAULTS,
-} = {}) {
-  const p = resolveProrationPolicy(policy);
-  const nil = (reason) => ({
-    credit: 0, as_points: false, reason, mode: p.mode, days_remaining: 0, days_total: 0,
-  });
-
-  if (p.mode === "none") return nil("proration is off");
-  if (isCycleChange && !p.on_cycle_change) return nil("cycle changes are not prorated");
-  if (!isCycleChange && !p.on_plan_change) return nil("plan changes are not prorated");
-
-  // An open-ended term (the provisioned default) has no remainder to value: nothing was paid for
-  // a period that does not end.
-  if (!periodEnd) return nil("term has no end date");
-  if (!(paidAmount > 0)) return nil("nothing was paid for the current term");
-
-  const daysTotal = daysBetween(periodStart, periodEnd);
-  const daysRemaining = daysBetween(now, periodEnd);
-  if (daysTotal <= 0) return nil("term length is zero");
-  if (daysRemaining <= 0) return nil("term has already ended");
-
-  let credit;
-  if (p.mode === "monthly") {
-    const monthsRemaining = wholeMonthsBetween(now, periodEnd);
-    const monthsTotal = wholeMonthsBetween(periodStart, periodEnd);
-    if (monthsTotal <= 0 || monthsRemaining <= 0) {
-      return { ...nil("less than a whole month remains"), days_remaining: daysRemaining, days_total: daysTotal };
-    }
-    credit = Math.floor((paidAmount * monthsRemaining) / monthsTotal);
-  } else {
-    // daily, and the basis for `points` too — the difference is only in how it is returned.
-    credit = Math.floor((paidAmount * daysRemaining) / daysTotal);
-  }
-
-  // Never more than was paid. Floating-point and clock skew both make this reachable.
-  credit = Math.min(credit, paidAmount);
-
-  /**
-   * The cap. Without it, a long unused term can exceed the new plan's price and the purchase
-   * goes to zero or negative — the customer upgrades for free, or we owe them money for taking
-   * a bigger plan. Applies to the cash credit only; points are a separate liability that does
-   * not have to fit inside this purchase.
-   */
-  if (p.mode !== "points") {
-    const ceiling = Math.floor((newPlanPrice * Math.max(0, Math.min(100, p.cap_percent))) / 100);
-    if (credit > ceiling) {
-      credit = ceiling;
-    }
-  }
-
-  if (credit <= 0) return { ...nil("nothing to credit"), days_remaining: daysRemaining, days_total: daysTotal };
-
-  return {
-    credit,
-    as_points: p.mode === "points",
-    reason: p.mode === "points"
-      ? `${daysRemaining} unused day(s) returned as points`
-      : `${daysRemaining} of ${daysTotal} day(s) unused`,
-    mode: p.mode,
-    days_remaining: daysRemaining,
-    days_total: daysTotal,
-  };
-}
-
-export default { prorate, resolveProrationPolicy, PRORATION_DEFAULTS };
+/**
+ * Proration — what the unused part of a running term is worth when someone upgrades.
+ *
+ * Without it, an upgrade STACKS: the new term is appended to the current end date, so the days
+ * already paid for on the smaller plan sit behind the new one, unusable at the new tier. The
+ * customer quietly loses that value and nothing on screen says so.
+ *
+ * The POLICY is configuration, not code — mode, basis, rounding, cap and scope all arrive from
+ * the caller (platform default < plan < service), so changing how proration works is an edit
+ * rather than a deploy. This module is only the arithmetic, kept pure so it can be tested
+ * without a database, a clock or a subscription.
+ *
+ * ── The rules that are NOT configurable, because getting them wrong invents money ────────────
+ *   · credit can never exceed what was actually paid for the current term
+ *   · credit can never exceed the new plan's price (a purchase must not become negative)
+ *   · rounding is toward the CUSTOMER paying more, never less — we do not credit value that was
+ *     not paid for
+ *   · a term that has not started, or has already ended, is worth nothing
+ */
+
+/** Every knob, with the conservative answer as the default. */
+export const PRORATION_DEFAULTS = {
+  /**
+   *   none    — today's behaviour: no credit, the new term stacks on the old end date
+   *   daily   — unused days ÷ total days
+   *   monthly — whole unused months only; a part-month counts for nothing
+   *   points  — no cash credit; the unused value is returned as reward points instead
+   */
+  mode: "none",
+  /** Ceiling on the credit as a percentage of the new plan's price. 100 = up to the full price. */
+  cap_percent: 100,
+  /** Apply when the PLAN changes, and/or when only the billing cycle changes. */
+  on_plan_change: true,
+  on_cycle_change: false,
+};
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/** Whole days between two instants, never negative. */
+function daysBetween(from, to) {
+  const ms = new Date(to).getTime() - new Date(from).getTime();
+  return ms <= 0 ? 0 : Math.floor(ms / MS_PER_DAY);
+}
+
+/** Whole months remaining — a part-month is worth nothing under `monthly`. */
+function wholeMonthsBetween(from, to) {
+  const a = new Date(from);
+  const b = new Date(to);
+  if (b <= a) return 0;
+  let months = (b.getFullYear() - a.getFullYear()) * 12 + (b.getMonth() - a.getMonth());
+  if (b.getDate() < a.getDate()) months -= 1;
+  return months > 0 ? months : 0;
+}
+
+/**
+ * Merge policy layers. Later wins, and only for keys it actually specifies — a plan that sets
+ * only `mode` must not silently reset the cap someone configured globally.
+ */
+export function resolveProrationPolicy(...layers) {
+  const out = { ...PRORATION_DEFAULTS };
+  for (const layer of layers) {
+    if (!layer || typeof layer !== "object") continue;
+    for (const k of Object.keys(PRORATION_DEFAULTS)) {
+      if (layer[k] !== undefined && layer[k] !== null) out[k] = layer[k];
+    }
+  }
+  return out;
+}
+
+/**
+ * What the unused remainder of the current term is worth, in PAISE.
+ *
+ * @param {object}  a
+ * @param {number}  a.paidAmount    what was paid for the CURRENT term (paise, ex-tax)
+ * @param {Date}    a.periodStart   when the current term began
+ * @param {Date}    a.periodEnd     when it ends (null/absent ⇒ open-ended ⇒ nothing to prorate)
+ * @param {Date}    a.now           the moment of the change
+ * @param {number}  a.newPlanPrice  price of what they are moving to (paise, ex-tax) — the cap
+ * @param {boolean} a.isCycleChange true when the plan is unchanged and only the cycle differs
+ * @param {object}  a.policy        resolved policy (see resolveProrationPolicy)
+ * @returns {{credit:number, as_points:boolean, reason:string, days_remaining:number,
+ *            days_total:number, mode:string}}
+ */
+export function prorate({
+  paidAmount = 0,
+  periodStart,
+  periodEnd,
+  now = new Date(),
+  newPlanPrice = 0,
+  isCycleChange = false,
+  policy = PRORATION_DEFAULTS,
+} = {}) {
+  const p = resolveProrationPolicy(policy);
+  const nil = (reason) => ({
+    credit: 0, as_points: false, reason, mode: p.mode, days_remaining: 0, days_total: 0,
+  });
+
+  if (p.mode === "none") return nil("proration is off");
+  if (isCycleChange && !p.on_cycle_change) return nil("cycle changes are not prorated");
+  if (!isCycleChange && !p.on_plan_change) return nil("plan changes are not prorated");
+
+  // An open-ended term (the provisioned default) has no remainder to value: nothing was paid for
+  // a period that does not end.
+  if (!periodEnd) return nil("term has no end date");
+  if (!(paidAmount > 0)) return nil("nothing was paid for the current term");
+
+  const daysTotal = daysBetween(periodStart, periodEnd);
+  const daysRemaining = daysBetween(now, periodEnd);
+  if (daysTotal <= 0) return nil("term length is zero");
+  if (daysRemaining <= 0) return nil("term has already ended");
+
+  let credit;
+  if (p.mode === "monthly") {
+    const monthsRemaining = wholeMonthsBetween(now, periodEnd);
+    const monthsTotal = wholeMonthsBetween(periodStart, periodEnd);
+    if (monthsTotal <= 0 || monthsRemaining <= 0) {
+      return { ...nil("less than a whole month remains"), days_remaining: daysRemaining, days_total: daysTotal };
+    }
+    credit = Math.floor((paidAmount * monthsRemaining) / monthsTotal);
+  } else {
+    // daily, and the basis for `points` too — the difference is only in how it is returned.
+    credit = Math.floor((paidAmount * daysRemaining) / daysTotal);
+  }
+
+  // Never more than was paid. Floating-point and clock skew both make this reachable.
+  credit = Math.min(credit, paidAmount);
+
+  /**
+   * The cap. Without it, a long unused term can exceed the new plan's price and the purchase
+   * goes to zero or negative — the customer upgrades for free, or we owe them money for taking
+   * a bigger plan. Applies to the cash credit only; points are a separate liability that does
+   * not have to fit inside this purchase.
+   */
+  if (p.mode !== "points") {
+    const ceiling = Math.floor((newPlanPrice * Math.max(0, Math.min(100, p.cap_percent))) / 100);
+    if (credit > ceiling) {
+      credit = ceiling;
+    }
+  }
+
+  if (credit <= 0) return { ...nil("nothing to credit"), days_remaining: daysRemaining, days_total: daysTotal };
+
+  return {
+    credit,
+    as_points: p.mode === "points",
+    reason: p.mode === "points"
+      ? `${daysRemaining} unused day(s) returned as points`
+      : `${daysRemaining} of ${daysTotal} day(s) unused`,
+    mode: p.mode,
+    days_remaining: daysRemaining,
+    days_total: daysTotal,
+  };
+}
+
+export default { prorate, resolveProrationPolicy, PRORATION_DEFAULTS };