@i4e/invest4edu-access-core 0.30.0 → 0.32.0

package/src/user-entity-link.js

@@ -0,0 +1,58 @@
+/**
+ * Which hats may coexist on one person — @i4e/invest4edu-access-core.
+ *
+ * Historically every entity flow minted its own `users` row, so the same person signing
+ * up as a partner after already being a client was refused outright. One person is now
+ * one row carrying a link per entity, which makes "may this person also be X" a real
+ * question with a real answer — and it has to be the SAME answer in every flow, or the
+ * employee path enforces something the partner path does not.
+ *
+ * Only the rule table lives here. Resolving which hats a person currently wears is each
+ * backend's job: v1 reads `users` columns plus `userentitymappings`, v2 reads its own
+ * narrower projection, and neither shape belongs in a pure package. What must not differ
+ * is the verdict, so the verdict is what is shared.
+ */
+import { ENTITY } from './entity-status.js';
+
+/**
+ * Entities that may not coexist on one person.
+ *
+ * Deliberately minimal: it states the one prohibition the business asked for rather than
+ * enumerating every pair. Employee and partner are mutually exclusive; everything else
+ * that already happens keeps happening — a client links onto an employee today, and
+ * refusing that here would break a live flow.
+ *
+ * Extending this is a line in the table, not a new check somewhere else.
+ */
+export const CONFLICTING_ENTITIES = {
+  [ENTITY.DISTRIBUTOR]: [ENTITY.EMPLOYEE],
+  [ENTITY.EMPLOYEE]: [ENTITY.DISTRIBUTOR],
+  [ENTITY.CLIENT]: [],
+  [ENTITY.MANUFACTURER]: [],
+};
+
+/**
+ * Which already-worn hat, if any, forbids adding this one.
+ *
+ * Takes a plain set of entity types so it stays independent of how they were discovered —
+ * the mapping collection, the legacy columns, or a mix of both all reach the same table.
+ *
+ * @param {string} targetEntity        the hat being added, one of ENTITY
+ * @param {Set<string>|Array} existing the hats already worn
+ * @returns {string|null} the conflicting entity type, or null when the pairing is allowed
+ */
+export function conflictingEntityFor(targetEntity, existing) {
+  const worn = existing instanceof Set ? existing : new Set(existing || []);
+  return (CONFLICTING_ENTITIES[targetEntity] || []).find((e) => worn.has(e)) || null;
+}
+
+/** The refusal message for a pairing the table forbids. Shared so both backends say the same thing. */
+export function entityConflictMessage(targetEntity, conflictingEntity) {
+  if (targetEntity === ENTITY.DISTRIBUTOR && conflictingEntity === ENTITY.EMPLOYEE) {
+    return 'These contact details belong to an employee. An employee cannot also be registered as a partner.';
+  }
+  if (targetEntity === ENTITY.EMPLOYEE && conflictingEntity === ENTITY.DISTRIBUTOR) {
+    return 'These contact details belong to a partner. A partner cannot also be registered as an employee.';
+  }
+  return `These contact details are already registered as a ${conflictingEntity}, which cannot be combined with a ${targetEntity}.`;
+}

package/src/visible-when.js

@@ -1,108 +1,108 @@
-/**
- * `visibleWhen` — ONE predicate language, ONE evaluator.
- * @i4e/invest4edu-access-core (unified access framework, P1)
- *
- * The same function gates nav items, screen actions, grid columns, filters, row/bulk actions,
- * exports and summary metrics. That is what makes "driven by product and roles" true across the
- * whole app instead of per-screen — and it means a rule is written once, in data, not in 139
- * hardcoded predicates.
- *
- * Client-side evaluation is UX ONLY. Servers MUST re-evaluate before returning data, projecting
- * columns, or building an export/summary — never trust a client-supplied column list.
- *
- * Design: TDD-unified-access-and-subscription.md §8.3
- */
-
-import { hasFeature, isUsable } from "./access-resolver.js";
-
-/**
- * Shape (every key optional; all present keys must pass — AND):
- * {
- *   features:         ["ORDERS.LIST"]          // caller must hold all of these
- *   actions:          ["ORDERS.LIST.CANCEL"]   // alias of features, reads better on actions
- *   entitled:         "TOOLS.AI_REPORT"        // must be allowed AND entitlement-unlocked
- *   products:         ["IVP003"]               // caller's product scope must intersect
- *   distributorLevel: ["D1","D2"]
- *   screenType:       "openorders" | ["a","b"]
- *   roles:            ["BROKER_ADMIN"]         // LEGACY escape hatch — lint-flagged, being removed
- *   anyOf:            [ {...}, {...} ]         // OR of nested predicates
- *   not:              { ... }                  // negation
- * }
- *
- * @param {Object|null|undefined} rule   absent/empty ⇒ visible (opt-in gating, not opt-out)
- * @param {Object} ctx { snapshot, productScope?, distributorLevel?, screenType?, roles? }
- */
-export function evaluateVisibleWhen(rule, ctx = {}) {
-  if (!rule || typeof rule !== "object") return true;
-
-  const snapshot = ctx.snapshot || null;
-  // A system admin (D27) resolves a fully-open snapshot, so feature/entitlement checks below
-  // pass naturally. Product/level predicates still evaluate — an admin seeing a D1-only column
-  // labelled for D1 would be misleading, not permissive.
-  const productScope = new Set(
-    (ctx.productScope || snapshot?.productScope || []).map(String),
-  );
-
-  const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
-
-  if (rule.features && !asArray(rule.features).every((c) => hasFeature(snapshot, c))) return false;
-  if (rule.actions && !asArray(rule.actions).every((c) => hasFeature(snapshot, c))) return false;
-  if (rule.entitled && !asArray(rule.entitled).every((c) => isUsable(snapshot, c))) return false;
-
-  if (rule.products) {
-    const want = asArray(rule.products).map(String);
-    if (want.length && !want.some((p) => productScope.has(p))) return false;
-  }
-
-  if (rule.distributorLevel) {
-    const lvl = ctx.distributorLevel ? String(ctx.distributorLevel) : null;
-    if (!lvl || !asArray(rule.distributorLevel).map(String).includes(lvl)) return false;
-  }
-
-  if (rule.screenType) {
-    const st = ctx.screenType ? String(ctx.screenType) : null;
-    if (!st || !asArray(rule.screenType).map(String).includes(st)) return false;
-  }
-
-  // LEGACY: kept only so migration can proceed screen-by-screen. New configs must not use it.
-  if (rule.roles) {
-    const held = new Set(asArray(ctx.roles || snapshot?.resolved_for?.roles).map(String));
-    if (!asArray(rule.roles).map(String).some((r) => held.has(r))) return false;
-  }
-
-  if (rule.anyOf) {
-    const branches = asArray(rule.anyOf);
-    if (branches.length && !branches.some((b) => evaluateVisibleWhen(b, ctx))) return false;
-  }
-
-  if (rule.not && evaluateVisibleWhen(rule.not, ctx)) return false;
-
-  return true;
-}
-
-/** Filter a list of `{visibleWhen}`-bearing config items (columns, metrics, actions, filters). */
-export function filterVisible(items = [], ctx = {}) {
-  return items.filter((i) => evaluateVisibleWhen(i?.visibleWhen, ctx));
-}
-
-/**
- * Apply `relabelWhen` overrides to a grid column — absorbs the imperative relabelling in
- * order-constants (e.g. d1/d2/d3_payout → "Net Income" for the matching distributor level).
- * First matching rule wins; the column is returned unchanged when nothing matches.
- */
-export function applyRelabel(column, ctx = {}) {
-  if (!column?.relabelWhen?.length) return column;
-  for (const r of column.relabelWhen) {
-    if (evaluateVisibleWhen(r?.when, ctx)) {
-      return { ...column, header: r.header ?? column.header, label: r.label ?? column.label };
-    }
-  }
-  return column;
-}
-
-/** Resolve a full column list: drop hidden ones, apply relabelling, preserve order. */
-export function resolveColumns(columns = [], ctx = {}) {
-  return filterVisible(columns, ctx).map((c) => applyRelabel(c, ctx));
-}
-
-export default { evaluateVisibleWhen, filterVisible, applyRelabel, resolveColumns };
+/**
+ * `visibleWhen` — ONE predicate language, ONE evaluator.
+ * @i4e/invest4edu-access-core (unified access framework, P1)
+ *
+ * The same function gates nav items, screen actions, grid columns, filters, row/bulk actions,
+ * exports and summary metrics. That is what makes "driven by product and roles" true across the
+ * whole app instead of per-screen — and it means a rule is written once, in data, not in 139
+ * hardcoded predicates.
+ *
+ * Client-side evaluation is UX ONLY. Servers MUST re-evaluate before returning data, projecting
+ * columns, or building an export/summary — never trust a client-supplied column list.
+ *
+ * Design: TDD-unified-access-and-subscription.md §8.3
+ */
+
+import { hasFeature, isUsable } from "./access-resolver.js";
+
+/**
+ * Shape (every key optional; all present keys must pass — AND):
+ * {
+ *   features:         ["ORDERS.LIST"]          // caller must hold all of these
+ *   actions:          ["ORDERS.LIST.CANCEL"]   // alias of features, reads better on actions
+ *   entitled:         "TOOLS.AI_REPORT"        // must be allowed AND entitlement-unlocked
+ *   products:         ["IVP003"]               // caller's product scope must intersect
+ *   distributorLevel: ["D1","D2"]
+ *   screenType:       "openorders" | ["a","b"]
+ *   roles:            ["BROKER_ADMIN"]         // LEGACY escape hatch — lint-flagged, being removed
+ *   anyOf:            [ {...}, {...} ]         // OR of nested predicates
+ *   not:              { ... }                  // negation
+ * }
+ *
+ * @param {Object|null|undefined} rule   absent/empty ⇒ visible (opt-in gating, not opt-out)
+ * @param {Object} ctx { snapshot, productScope?, distributorLevel?, screenType?, roles? }
+ */
+export function evaluateVisibleWhen(rule, ctx = {}) {
+  if (!rule || typeof rule !== "object") return true;
+
+  const snapshot = ctx.snapshot || null;
+  // A system admin (D27) resolves a fully-open snapshot, so feature/entitlement checks below
+  // pass naturally. Product/level predicates still evaluate — an admin seeing a D1-only column
+  // labelled for D1 would be misleading, not permissive.
+  const productScope = new Set(
+    (ctx.productScope || snapshot?.productScope || []).map(String),
+  );
+
+  const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+
+  if (rule.features && !asArray(rule.features).every((c) => hasFeature(snapshot, c))) return false;
+  if (rule.actions && !asArray(rule.actions).every((c) => hasFeature(snapshot, c))) return false;
+  if (rule.entitled && !asArray(rule.entitled).every((c) => isUsable(snapshot, c))) return false;
+
+  if (rule.products) {
+    const want = asArray(rule.products).map(String);
+    if (want.length && !want.some((p) => productScope.has(p))) return false;
+  }
+
+  if (rule.distributorLevel) {
+    const lvl = ctx.distributorLevel ? String(ctx.distributorLevel) : null;
+    if (!lvl || !asArray(rule.distributorLevel).map(String).includes(lvl)) return false;
+  }
+
+  if (rule.screenType) {
+    const st = ctx.screenType ? String(ctx.screenType) : null;
+    if (!st || !asArray(rule.screenType).map(String).includes(st)) return false;
+  }
+
+  // LEGACY: kept only so migration can proceed screen-by-screen. New configs must not use it.
+  if (rule.roles) {
+    const held = new Set(asArray(ctx.roles || snapshot?.resolved_for?.roles).map(String));
+    if (!asArray(rule.roles).map(String).some((r) => held.has(r))) return false;
+  }
+
+  if (rule.anyOf) {
+    const branches = asArray(rule.anyOf);
+    if (branches.length && !branches.some((b) => evaluateVisibleWhen(b, ctx))) return false;
+  }
+
+  if (rule.not && evaluateVisibleWhen(rule.not, ctx)) return false;
+
+  return true;
+}
+
+/** Filter a list of `{visibleWhen}`-bearing config items (columns, metrics, actions, filters). */
+export function filterVisible(items = [], ctx = {}) {
+  return items.filter((i) => evaluateVisibleWhen(i?.visibleWhen, ctx));
+}
+
+/**
+ * Apply `relabelWhen` overrides to a grid column — absorbs the imperative relabelling in
+ * order-constants (e.g. d1/d2/d3_payout → "Net Income" for the matching distributor level).
+ * First matching rule wins; the column is returned unchanged when nothing matches.
+ */
+export function applyRelabel(column, ctx = {}) {
+  if (!column?.relabelWhen?.length) return column;
+  for (const r of column.relabelWhen) {
+    if (evaluateVisibleWhen(r?.when, ctx)) {
+      return { ...column, header: r.header ?? column.header, label: r.label ?? column.label };
+    }
+  }
+  return column;
+}
+
+/** Resolve a full column list: drop hidden ones, apply relabelling, preserve order. */
+export function resolveColumns(columns = [], ctx = {}) {
+  return filterVisible(columns, ctx).map((c) => applyRelabel(c, ctx));
+}
+
+export default { evaluateVisibleWhen, filterVisible, applyRelabel, resolveColumns };