@i4e/invest4edu-access-core 0.36.0 → 0.38.0

package/src/client-profile/sides.js

@@ -0,0 +1,204 @@
+/**
+ * Sides, profiles and tagging — who a client's business belongs to.
+ *
+ * ── Vocabulary ───────────────────────────────────────────────────────────────────────────────
+ *   profile   — one `distributorclients` record. A person has at most one `main` and one
+ *               `corporate` profile.
+ *   mapping   — one entry of `profile.distributor_mappings[]`: a distributor (or direct, when
+ *               `distributor_id` is null) that does business with this profile. Exactly one is
+ *               `is_primary`.
+ *   side key  — a stable string naming a side: the distributor id as a string, or `DIRECT_SIDE`.
+ *               House distributors (InvestValue's own) collapse to `DIRECT_SIDE`.
+ *
+ * ── Why a side KEY rather than the raw id ────────────────────────────────────────────────────
+ * Records carry `distributor_id` as an ObjectId, a string, null, or a house distributor's id,
+ * depending on which path wrote them. Comparing those directly is how the same side gets counted
+ * twice. Every comparison in this module goes through `sideKeyOf`.
+ *
+ * Pure: no I/O. House distributor ids are resolved by the caller (from the configured codes) and
+ * passed in, because only the backend can look codes up.
+ */
+import { PROFILE_TYPES, isEvaluated } from "./settings.js";
+
+export const DIRECT_SIDE = "direct";
+
+/** Why a record was tagged to the side it was. Logged, and stored on the record in audit mode. */
+export const TAG_REASONS = Object.freeze({
+  PLACER: "placer",
+  MF_EXCLUSIVE: "mf_exclusive",
+  CLIENT_APP: "client_app",
+});
+
+/**
+ * @param {*} distributorId   ObjectId | string | null | undefined
+ * @param {{ houseDistributorIds?: Iterable<string> }} ctx
+ */
+export function sideKeyOf(distributorId, { houseDistributorIds } = {}) {
+  if (distributorId === null || distributorId === undefined || distributorId === "") return DIRECT_SIDE;
+  const key = String(distributorId);
+  if (houseDistributorIds && new Set([...houseDistributorIds].map(String)).has(key)) return DIRECT_SIDE;
+  return key;
+}
+
+/** The profile type a distributor's client gets. No distributor → main. */
+export function profileTypeFor(distributor, settings) {
+  const types = settings?.corporate_distributor_types ?? [];
+  return distributor && types.includes(distributor.distributor_type) ? PROFILE_TYPES.CORPORATE : PROFILE_TYPES.MAIN;
+}
+
+/** The primary mapping, or a synthetic one from `distributor_id` for records not yet backfilled. */
+export function primaryMappingOf(profile) {
+  const mappings = Array.isArray(profile?.distributor_mappings) ? profile.distributor_mappings : [];
+  const primary = mappings.find((m) => m && m.is_primary);
+  if (primary) return primary;
+  return { distributor_id: profile?.distributor_id ?? null, is_primary: true, primary_locked: false, synthetic: true };
+}
+
+/** The primary side key of a profile. */
+export function primarySideOf(profile, ctx) {
+  return sideKeyOf(primaryMappingOf(profile).distributor_id, ctx);
+}
+
+/** Every side a profile does business with, primary first, de-duplicated. */
+export function sidesOf(profile, ctx) {
+  const keys = [primarySideOf(profile, ctx)];
+  for (const m of profile?.distributor_mappings ?? []) {
+    if (!m || m.status === "inactive") continue;
+    const key = sideKeyOf(m.distributor_id, ctx);
+    if (!keys.includes(key)) keys.push(key);
+  }
+  return keys;
+}
+
+/** The mapping for a side, if the profile has one. */
+export function mappingForSide(profile, sideKey, ctx) {
+  if (primarySideOf(profile, ctx) === sideKey) return primaryMappingOf(profile);
+  return (profile?.distributor_mappings ?? []).find((m) => m && sideKeyOf(m.distributor_id, ctx) === sideKey) ?? null;
+}
+
+/** True when the product code is configured as a mutual fund. */
+export function isMfProduct(productCode, settings) {
+  return Boolean(productCode) && (settings?.mf?.product_codes ?? []).includes(productCode);
+}
+
+/**
+ * Which side a new order is tagged to.
+ *
+ * Order of precedence, each behind its own mode:
+ *   1. MF exclusivity — MF always belongs to the primary (`mf_primary_stamp`).
+ *   2. Client app     — the client never picks; the primary gets it (`app_orders_primary`).
+ *   3. Otherwise      — the side of whoever placed it.
+ *
+ * Returns the decision for audit logging AND the side to apply. In audit mode `applied` is the
+ * placer's side (today's behaviour) while `decided` carries what enforce would do.
+ *
+ * @param {{ profile: object, placerSide: string, productCode?: string, isClientApp?: boolean,
+ *           settings: object, ctx?: object }} input
+ * @returns {{ decided: string, reason: string, applied: string, changed: boolean }}
+ */
+export function orderSideFor({ profile, placerSide, productCode, isClientApp = false, settings, ctx }) {
+  const primary = primarySideOf(profile, ctx);
+  const placer = placerSide ?? primary;
+  let decided = placer;
+  let reason = TAG_REASONS.PLACER;
+  let mode = null;
+
+  if (isMfProduct(productCode, settings) && settings?.mf?.exclusive_to_primary && isEvaluated(settings, "mf_primary_stamp")) {
+    decided = primary;
+    reason = TAG_REASONS.MF_EXCLUSIVE;
+    mode = "mf_primary_stamp";
+  } else if (isClientApp && settings?.app_orders?.tag_to_primary && isEvaluated(settings, "app_orders_primary")) {
+    decided = primary;
+    reason = TAG_REASONS.CLIENT_APP;
+    mode = "app_orders_primary";
+  }
+
+  const enforce = mode ? settings.modes[mode] === "enforce" : true;
+  const applied = enforce ? decided : placer;
+  return { decided, reason, applied, changed: decided !== placer };
+}
+
+/**
+ * Should the first qualifying order lock (or move) the primary?
+ *
+ * The primary is provisional until the first order. That order locks it:
+ *   - to the order's side for ordinary products,
+ *   - in place for MF (MF is tagged to the primary, so it can never move it).
+ * A locked primary never moves here; a referral (below) or an ops correction are the only other
+ * ways it changes.
+ *
+ * @returns {{ lock: boolean, newPrimarySide: string|null, moves: boolean }}
+ */
+export function primaryLockFor({ profile, orderSide, orderStatus, productCode, settings, ctx }) {
+  const none = { lock: false, newPrimarySide: null, moves: false };
+  if (!settings?.primary?.lock_on_first_order || !isEvaluated(settings, "primary_lock")) return none;
+  if ((settings.primary.ignore_order_statuses ?? []).includes(String(orderStatus))) return none;
+  const primary = primaryMappingOf(profile);
+  if (primary.primary_locked) return none;
+  const current = sideKeyOf(primary.distributor_id, ctx);
+  const target = isMfProduct(productCode, settings) && settings.mf?.exclusive_to_primary ? current : orderSide;
+  return { lock: true, newPrimarySide: target, moves: target !== current };
+}
+
+/**
+ * The primary a converting lead should get. A distributor referral wins and is locked; anything
+ * else keeps the lead's own distributor as a provisional primary.
+ *
+ * @returns {{ primarySide: string, locked: boolean, secondarySide: string|null, reason: string }}
+ */
+export function primaryFromLead({ lead, settings, ctx }) {
+  const leadSide = sideKeyOf(lead?.distributor_id, ctx);
+  const referralTypes = settings?.primary?.referral_types ?? [];
+  const referred = settings?.primary?.referral_sets_primary
+    && lead?.referred_by_id
+    && referralTypes.includes(lead?.referred_by_type);
+  if (!referred) return { primarySide: leadSide, locked: false, secondarySide: null, reason: "lead_distributor" };
+  const referrerSide = sideKeyOf(lead.referred_by_id, ctx);
+  return {
+    primarySide: referrerSide,
+    locked: true,
+    secondarySide: referrerSide !== leadSide ? leadSide : null,
+    reason: "referral",
+  };
+}
+
+/**
+ * The profile's new `distributor_id` and `distributor_mappings` after the primary is locked on a
+ * side (and moved there if it is not already the primary). Pure — the caller writes it.
+ * A side that is not yet mapped is added as the new primary; the old primary stays as a
+ * secondary mapping, so nobody loses the client.
+ *
+ * @returns {{ distributor_id: *, distributor_mappings: object[] }}
+ */
+export function withPrimaryLocked(profile, { newPrimarySide, newPrimaryDistributorId = null, at = new Date(), via = "order", ctx } = {}) {
+  const mappings = Array.isArray(profile?.distributor_mappings) && profile.distributor_mappings.length
+    ? profile.distributor_mappings.map((m) => ({ ...m }))
+    : [{ ...primaryMappingOf(profile), synthetic: undefined }];
+  let target = mappings.find((m) => sideKeyOf(m.distributor_id, ctx) === newPrimarySide);
+  if (!target) {
+    target = {
+      distributor_id: newPrimaryDistributorId,
+      is_primary: false,
+      primary_locked: false,
+      via,
+      mapped_at: at,
+      mapped_by: null,
+      first_business_at: at,
+      rm_id: null,
+      dist_emp_rm_id: null,
+      department_id: null,
+      merged_from_client_id: null,
+      status: "active",
+    };
+    mappings.push(target);
+  }
+  for (const m of mappings) {
+    m.is_primary = m === target;
+    if (m === target) {
+      m.primary_locked = true;
+      m.first_business_at = m.first_business_at ?? at;
+    }
+    delete m.synthetic;
+  }
+  return { distributor_id: target.distributor_id ?? null, distributor_mappings: mappings };
+}

package/src/index.js

@@ -35,6 +35,13 @@ export {
   ROLE_TYPE_PRIORITY,
   pickPortalRoleName,
 } from "./portal-roles.js";
+export {
+  MOBILE_LOGIN_SOURCES,
+  CLIENT_APP_LOGIN_SOURCES,
+  PARTNER_APP_HATS,
+  APP_BUNDLE_ID_PATTERN,
+  appBundleIdOf,
+} from "./mobile-app-identity.js";
 export {
   DEFAULT_ACCESS_FLAGS,
   ACCESS_FLAG_ENV_NAMES,
@@ -82,3 +89,7 @@ export {
   applyRelabel,
   resolveColumns,
 } from "./visible-when.js";
+
+// ── Client-profile model (two profiles per person, sides, access level, field policy) ─────────
+// Namespaced: its vocabulary (MODES, PROFILE_TYPES, …) is too generic to flatten into the root.
+export * as clientProfile from "./client-profile/index.js";

package/src/mobile-app-identity.js

@@ -0,0 +1,52 @@
+/**
+ * Which mobile app a login came from, and what it may record — @i4e/invest4edu-access-core.
+ *
+ * Two apps sign in to the same backends: the partner app (NeoFinDesk) and the client app
+ * (InvestValue AI). A person's hat names the app: a client hat is the client app, every other
+ * hat the partner app. Both backends read these to decide which hat a mobile login flags and
+ * what bundle id its session row keeps.
+ *
+ * ── Why this lives in the package rather than in each backend ─────────────────────────
+ * nfd-api-node declared these in src/api/common/mobileAppIdentity.js and nfd-api-node-v2 in
+ * services/user/user.js, held together by tests pinning each copy's literals (BRI-1263). The
+ * sets are fixed by the domain — the mobile platforms and the entity kinds — so they are
+ * constants, not reference data; but two copies of a constant are still two definitions.
+ */
+import { ENTITY } from './entity-status.js';
+
+/**
+ * Login / creation `source` values that mean "a mobile app" without naming which one. The
+ * partner app sends these, and so did the client app before it had its own values.
+ */
+export const MOBILE_LOGIN_SOURCES = new Set(['MOBILE_ANDROID', 'MOBILE_IOS', 'MOBILE_APP']);
+
+/** Sources only the client app (InvestValue AI) sends: they name the app, not just "mobile". */
+export const CLIENT_APP_LOGIN_SOURCES = new Set(['IV_CLIENT_APP_IOS', 'IV_CLIENT_APP_ANDROID']);
+
+/** Hats the partner app (NeoFinDesk) signs in as — every hat except the client one. */
+export const PARTNER_APP_HATS = Object.values(ENTITY).filter((t) => t !== ENTITY.CLIENT);
+
+/**
+ * A bundle id / package name: iOS reverse-DNS (letters, digits, `.`, `-`) and Android
+ * (letters, digits, `.`, `_`), at most 255 characters. Anything else — markup, a newline, a
+ * spreadsheet formula — is not an app identifier and is not stored.
+ */
+export const APP_BUNDLE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,254}$/;
+
+/**
+ * The calling app's bundle id for a session row, or null.
+ *
+ * A login whose source names a non-mobile channel (WEB, PARTNER_API, …) stores null whatever
+ * it sends. A login with NO source keeps it: the client app sends none on its OTP, MPIN and
+ * biometric logins, and those are exactly the logins the bundle id is for. Checked for shape
+ * only, not against an allowlist — a stale app build must still be able to log in.
+ *
+ * @param {object} body  the login request body; reads `source` (or `creation_source`) and `appBundleId`
+ * @returns {string|null}
+ */
+export function appBundleIdOf(body) {
+  const source = String(body?.source || body?.creation_source || '').trim().toUpperCase();
+  if (source && !MOBILE_LOGIN_SOURCES.has(source) && !CLIENT_APP_LOGIN_SOURCES.has(source)) return null;
+  const value = typeof body?.appBundleId === 'string' ? body.appBundleId.trim() : '';
+  return APP_BUNDLE_ID_PATTERN.test(value) ? value : null;
+}