@i4e/invest4edu-access-core 0.32.0 → 0.34.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 };

package/src/report-audience.js

@@ -0,0 +1,226 @@
+/**
+ * Portfolio report audience — who is a report FOR, and which sections may it show.
+ *
+ * A product review (Aditya, Manoj, Rozy) decided the portfolio report must show different things
+ * to different audiences: a partner's client and an employee-serviced client see a reduced,
+ * B2C-toned view (health score and storytelling, no recommendations), while an adviser working
+ * their own book keeps the full report.
+ *
+ * ── The audience is a property of the CLIENT, never the viewer ────────────────────────────────
+ * One RM opens a partner's client and a direct client in the same session, and the InvestValue
+ * mobile app is always a client viewer while its users are clients of BOTH types. So the answer
+ * is derived from the client record and obeyed identically by every renderer — NFD web, the
+ * native mobile screens, and anything that comes later.
+ *
+ * ── Why this lives in the package ─────────────────────────────────────────────────────────────
+ * The same rule is needed in v1 (which fronts the eCAS registry) and v2 (which mints the PFA
+ * subject token and answers PFA's callbacks). Two copies of a classification rule is how the two
+ * halves drift into disagreeing about what a partner's client may see — and a drift here is not a
+ * cosmetic bug: it decides what a client is shown about their own money.
+ *
+ * ── PURE, like the rest of this package ───────────────────────────────────────────────────────
+ * No Mongoose, no I/O. The two identity lookups are INJECTED, because they are the one part that
+ * genuinely differs: v1 has Mongoose models, v2 reads raw collections, and a script may have
+ * neither. Injecting them keeps the decision testable without a database and keeps the package
+ * free of every repo's model graph — the same contract `access-resolver` and `route-features`
+ * already follow.
+ *
+ * ── FAIL OPEN, ALWAYS ─────────────────────────────────────────────────────────────────────────
+ * An unknown audience, an unreadable registry, a thrown lookup — all resolve to the full report.
+ * A gating bug that blanks a working report is worse than one that shows too much, and this code
+ * sits in front of a screen clients already use.
+ *
+ * ── What this is NOT ──────────────────────────────────────────────────────────────────────────
+ * Presentation, not confidentiality. The sections withheld are the client's own portfolio data
+ * shown in less depth, and the map reaches the renderers through channels a caller can influence.
+ * It must never become the only thing standing between a viewer and data they may not see; if a
+ * genuinely must-not-see section is ever added, it needs enforcement at the data source instead.
+ * Decision recorded 10 Sep 2026.
+ *
+ * Spec: IV-CodingAgent/specs/access-management/SPEC-portfolio-report-audience.md
+ */
+
+/** Audiences. Surface-neutral: every renderer maps these to its own components. */
+export const AUDIENCE = Object.freeze({
+  PARTNER: "partner",
+  RM_E1: "rm_e1",
+  DIRECT: "direct",
+  FULL: "full",
+});
+
+/**
+ * Section keys. Deliberately named for WHAT they are, not for the component that renders them,
+ * because independent renderers consume this: nfd-ui gates React components, the mobile app
+ * filters its tab array. A key named after either one would read as foreign in the other.
+ *
+ * `healthScore` has no entry: the gauge is the one thing every audience keeps, so it is never
+ * gated. Making it configurable would invite a state where the report shows nothing at all.
+ */
+export const SECTION_KEYS = Object.freeze([
+  "actions", // the 3-step action plan / recommendations
+  "phc", // portfolio health-check detail body
+  "chat", // AI chat
+  "performance", // performance / gains
+  "keyInsights",
+  "fundAnalysis", // the fund analysis table
+  "scoreBreakdownFunds", // underlying funds inside the score breakdown
+  "advisorCta", // "call your advisor" prompt
+]);
+
+/** Everything on. The answer whenever we cannot prove a narrower one is correct. */
+export const ALL_VISIBLE = Object.freeze({
+  actions: true,
+  phc: true,
+  chat: true,
+  performance: true,
+  keyInsights: true,
+  fundAnalysis: true,
+  scoreBreakdownFunds: true,
+  advisorCta: false, // opt-in, not part of "everything"
+  fundDetail: "full",
+  tone: "adviser",
+});
+
+/** The reduced view. Partner and RM-E1 clients get exactly this; direct adds the CTA. */
+const REDUCED = Object.freeze({
+  actions: false,
+  phc: false,
+  chat: false,
+  performance: false,
+  keyInsights: false,
+  fundAnalysis: false,
+  scoreBreakdownFunds: false,
+  advisorCta: false,
+  fundDetail: "minimal",
+  tone: "b2c",
+});
+
+/**
+ * Defaults encode the review notes. They are the FALLBACK, not the source of truth — the registry
+ * overrides them per feature. They exist so the resolver still answers correctly before the
+ * registry rows are seeded, and when the registry cannot be read.
+ */
+export const AUDIENCE_DEFAULTS = Object.freeze({
+  [AUDIENCE.FULL]: ALL_VISIBLE,
+
+  // "Don't show for Partner clients & RM clients where RM is E1. Actions will not come.
+  //  Portfolio Health Score component — don't show; only show Health Score, no recommendations.
+  //  Hide the AI chatbot. Remove Key / Fund Analysis. Hide Performance. Less fund details.
+  //  Score breakdown — remove underlying fund. Language B2C / neutral."
+  [AUDIENCE.PARTNER]: REDUCED,
+
+  // Same treatment as a partner client — the review grouped them in one line.
+  [AUDIENCE.RM_E1]: REDUCED,
+
+  // "Direct Clients — call advisor to get details to know the plan. Same storytelling."
+  [AUDIENCE.DIRECT]: Object.freeze({ ...REDUCED, advisorCta: true }),
+});
+
+const E1_TYPE_DISTRIBUTOR = "distributor";
+
+/** A lookup that was not supplied, or threw, proves nothing. Never let it throw upward. */
+async function safeAsk(fn, id) {
+  if (typeof fn !== "function") return false;
+  try {
+    return !!(await fn(id));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Classify a client record into an audience.
+ *
+ * `e1_type` is a HINT and is treated as one — the same rule `shapePersonFilterOptions` follows,
+ * for the same reason: on devpoc 66 rows carry a type that disagrees with the collection the id is
+ * actually in (29 on dev), and those rows predate the field being declared. So both collections
+ * are consulted and the hint only decides which answer wins when both could be true. Trusting the
+ * enum bare would misclassify exactly those rows — and misclassifying is how a partner's client
+ * ends up seeing an adviser's report.
+ *
+ * @param {{ distributor_id?: *, e1?: *, e1_type?: string }} client
+ * @param {Object} [lookups]
+ * @param {(id: *) => Promise<boolean>} [lookups.isEmployee]     does this id name an employee-backed user?
+ * @param {(id: *) => Promise<boolean>} [lookups.isDistributor]  does this id name a real distributor?
+ * @returns {Promise<'partner'|'rm_e1'|'direct'>}
+ */
+export async function classifyAudience(client, lookups = {}) {
+  if (!client) return AUDIENCE.DIRECT;
+
+  // A client sitting in a partner's book is a partner client, whatever E1 says. This is the
+  // strongest signal we have and it is a plain field — house clients were moved to direct by
+  // nulling it (dedup, Aug 2026), so `null` genuinely means "not a partner's".
+  if (client.distributor_id) return AUDIENCE.PARTNER;
+
+  const { e1 } = client;
+  if (!e1) return AUDIENCE.DIRECT;
+
+  // Ask both, then let the hint break the tie — never the other way round.
+  const [employee, distributor] = await Promise.all([
+    safeAsk(lookups.isEmployee, e1),
+    safeAsk(lookups.isDistributor, e1),
+  ]);
+
+  if (employee && distributor) {
+    return client.e1_type === E1_TYPE_DISTRIBUTOR ? AUDIENCE.PARTNER : AUDIENCE.RM_E1;
+  }
+  if (employee) return AUDIENCE.RM_E1;
+  if (distributor) return AUDIENCE.PARTNER;
+
+  // An E1 resolving to nobody (deleted user, another account's distributor) is exactly the
+  // bad-data case above. Fall back to the reduced-but-safe audience rather than to `full`.
+  return AUDIENCE.DIRECT;
+}
+
+/**
+ * Merge registry overrides over the audience defaults.
+ *
+ * The registry is the source of truth for WHICH sections exist and whether each is on; the
+ * defaults answer while the rows are unseeded. `loadOverrides` is injected rather than imported so
+ * this module stays free of the access models — and so a caller with no registry at all (the
+ * mobile path has no access snapshot: no roles, no grants) can skip the read entirely without a
+ * second code path.
+ *
+ * @param {string} audience
+ * @param {(audience: string) => Promise<Object|null>} [loadOverrides]
+ */
+export async function resolveSections(audience, loadOverrides) {
+  const base = AUDIENCE_DEFAULTS[audience] || ALL_VISIBLE;
+  if (typeof loadOverrides !== "function") return { ...base };
+  try {
+    const overrides = await loadOverrides(audience);
+    return overrides && typeof overrides === "object" ? { ...base, ...overrides } : { ...base };
+  } catch {
+    return { ...base }; // registry unreadable → the audience default still applies
+  }
+}
+
+/**
+ * The one entry point callers use: classify, resolve, and never throw.
+ *
+ * @param {Object} client                                     client-ish record (distributor_id, e1, e1_type)
+ * @param {Object} [opts]
+ * @param {(id: *) => Promise<boolean>} [opts.isEmployee]
+ * @param {(id: *) => Promise<boolean>} [opts.isDistributor]
+ * @param {(audience: string) => Promise<Object|null>} [opts.loadOverrides]
+ * @returns {Promise<{ audience: string, sections: Object }>}
+ */
+export async function resolveReportAudience(client, opts = {}) {
+  try {
+    const audience = await classifyAudience(client, opts);
+    return { audience, sections: await resolveSections(audience, opts.loadOverrides) };
+  } catch {
+    // Fail open. Every caller renders a report from this; none of them should render nothing.
+    return { audience: AUDIENCE.FULL, sections: { ...ALL_VISIBLE } };
+  }
+}
+
+export default {
+  AUDIENCE,
+  SECTION_KEYS,
+  ALL_VISIBLE,
+  AUDIENCE_DEFAULTS,
+  classifyAudience,
+  resolveSections,
+  resolveReportAudience,
+};