@i4e/invest4edu-access-core 0.36.0 → 0.38.0

package/src/client-profile/profiles.js

@@ -0,0 +1,126 @@
+/**
+ * Profiles — finding a person's existing profile, stamping a new one, and deciding what a saved
+ * action attaches.
+ *
+ * ── Finding a person ─────────────────────────────────────────────────────────────────────────
+ * A person is a PAN. Stored PANs vary in case and stray whitespace depending on the path that
+ * wrote them, so lookups match the normalised value case-insensitively and anchored — an exact
+ * match, never a prefix, so a lookup can never be used to enumerate clients.
+ *
+ * ── Attaching ────────────────────────────────────────────────────────────────────────────────
+ * The first saved action by someone who does not own a client records them on it (D4):
+ *   partner / partner staff → a secondary distributor mapping for their firm
+ *   internal employee       → a linked_users entry, unless they already see the client
+ *   client (app)            → nothing
+ * Searching alone attaches nothing; only a saved action does.
+ */
+import { ATTACH_TRIGGERS, PROFILE_TYPES, isEvaluated } from "./settings.js";
+import { CALLER_CLASSES } from "./access.js";
+import { DIRECT_SIDE, profileTypeFor, sideKeyOf } from "./sides.js";
+
+/** Uppercase and strip every whitespace character. Empty → null. */
+export function normalisePan(pan) {
+  if (pan === null || pan === undefined) return null;
+  const value = String(pan).replace(/\s+/g, "").toUpperCase();
+  return value || null;
+}
+
+/**
+ * A Mongo filter matching this PAN exactly, whatever the stored case or padding.
+ * Returns null for an empty PAN (never match "every client without a PAN").
+ */
+export function panMatchFilter(pan, field = "pan_card_no") {
+  const normal = normalisePan(pan);
+  if (!normal) return null;
+  const escaped = normal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return { [field]: { $regex: `^\\s*${escaped}\\s*$`, $options: "i" } };
+}
+
+/**
+ * The two-profile fields a brand-new client is created with: its type and a provisional primary
+ * mapping for the creator's side. Always additive — safe with every mode off.
+ */
+export function newProfileFields({ distributor, distributorId = null, at = new Date(), by = null, rmId = null, distEmpRmId = null, departmentId = null, via = ATTACH_TRIGGERS.CREATE, primaryLocked = false, settings }) {
+  return {
+    profile_type: profileTypeFor(distributor, settings),
+    distributor_mappings: [{
+      distributor_id: distributorId ?? null,
+      is_primary: true,
+      primary_locked: Boolean(primaryLocked),
+      via,
+      mapped_at: at,
+      mapped_by: by,
+      first_business_at: null,
+      rm_id: rmId,
+      dist_emp_rm_id: distEmpRmId,
+      department_id: departmentId,
+      merged_from_client_id: null,
+      status: "active",
+    }],
+  };
+}
+
+/** The profile type a caller's new client would get — the key for "does this person exist?". */
+export function profileTypeForCaller(callerDistributor, settings) {
+  return profileTypeFor(callerDistributor, settings);
+}
+
+/** Of a person's active profiles, the one of this type (oldest first if the data has duplicates). */
+export function pickProfileOfType(profiles = [], profileType) {
+  const ofType = profiles.filter((p) => (p.profile_type ?? PROFILE_TYPES.MAIN) === profileType);
+  ofType.sort((a, b) => new Date(a.created_date ?? 0) - new Date(b.created_date ?? 0));
+  return ofType[0] ?? null;
+}
+
+/**
+ * What a saved action should attach.
+ *
+ * @param {{ profile: object, actor: { callerClass: string, distributorId?: *, userId?: *,
+ *           employeeId?: *, alreadyVisible?: boolean }, via: string, at?: Date,
+ *           settings: object, ctx?: object, stamps?: { rmId?, distEmpRmId?, departmentId? } }} input
+ * @returns {{ kind: "none"|"mapping"|"linked_user", reason: string, entry?: object }}
+ */
+export function attachDecision({ profile, actor = {}, via, at = new Date(), settings, ctx, stamps = {} }) {
+  if (!isEvaluated(settings, "attach")) return { kind: "none", reason: "mode_off" };
+  if (!(settings.attach?.triggers ?? []).includes(via)) return { kind: "none", reason: "trigger_not_configured" };
+  if (!profile) return { kind: "none", reason: "no_profile" };
+
+  if (actor.callerClass === CALLER_CLASSES.CLIENT) return { kind: "none", reason: "client" };
+
+  if (actor.callerClass === CALLER_CLASSES.PARTNER) {
+    const side = sideKeyOf(actor.distributorId, ctx);
+    if (side === DIRECT_SIDE) return { kind: "none", reason: "partner_without_firm" };
+    const primarySide = sideKeyOf((profile.distributor_mappings ?? []).find((m) => m?.is_primary)?.distributor_id ?? profile.distributor_id, ctx);
+    const mapped = side === primarySide || (profile.distributor_mappings ?? []).some((m) => m && m.status !== "inactive" && sideKeyOf(m.distributor_id, ctx) === side);
+    if (mapped) return { kind: "none", reason: "already_mapped" };
+    return {
+      kind: "mapping",
+      reason: "new_side",
+      entry: {
+        distributor_id: actor.distributorId,
+        is_primary: false,
+        primary_locked: false,
+        via,
+        mapped_at: at,
+        mapped_by: actor.userId ?? null,
+        first_business_at: at,
+        rm_id: stamps.rmId ?? null,
+        dist_emp_rm_id: stamps.distEmpRmId ?? null,
+        department_id: stamps.departmentId ?? null,
+        merged_from_client_id: null,
+        status: "active",
+      },
+    };
+  }
+
+  // Internal employee (ops or sales).
+  if (!actor.userId) return { kind: "none", reason: "no_user" };
+  if (actor.alreadyVisible && settings.attach?.skip_if_already_visible) return { kind: "none", reason: "already_visible" };
+  const linked = (profile.linked_users ?? []).some((l) => l && String(l.user_id) === String(actor.userId));
+  if (linked) return { kind: "none", reason: "already_linked" };
+  return {
+    kind: "linked_user",
+    reason: "new_user",
+    entry: { user_id: actor.userId, employee_id: actor.employeeId ?? null, via, first_business_at: at },
+  };
+}

package/src/client-profile/settings.js

@@ -0,0 +1,377 @@
+/**
+ * Client-profile settings — the ONE place every behaviour of the two-profile model is configured.
+ *
+ * ── How configuration flows ──────────────────────────────────────────────────────────────────
+ * Defaults live here. Each environment keeps one document in the `clientprofilesettings`
+ * collection that overrides any subset of them. Both backends load that document through their
+ * config refresher and call `resolveClientProfileSettings(doc)`; neither re-states a default.
+ *
+ * ── What is NOT a default ────────────────────────────────────────────────────────────────────
+ * Business identifiers — distributor codes, role names, product codes, distributor-type labels —
+ * are data about one environment, so their defaults here are EMPTY. They are supplied by the
+ * environment's settings document (seeded per environment by the backends). An empty list simply
+ * means "nothing matches", and every feature that depends on one is also behind a mode that
+ * defaults to `off`.
+ *
+ * ── Modes ────────────────────────────────────────────────────────────────────────────────────
+ * Every behaviour that changes a request's outcome has a mode:
+ *   off      — behave exactly as before this module existed
+ *   audit    — compute the decision, log it, change nothing
+ *   enforce  — apply the decision
+ * All modes default to `off`, so shipping the code changes nothing until an environment opts in.
+ *
+ * ── Validation ───────────────────────────────────────────────────────────────────────────────
+ * The defaults double as the schema: a supplied value is accepted only when it has the same shape
+ * as the default it replaces (a string list for a list, a mode for a mode, …). Anything else keeps
+ * the default and is reported in `problems`, never thrown — a bad config document must not take a
+ * request path down.
+ */
+import { CLIENT_PROFILE_ERRORS } from "./errors.js";
+
+/** Collections the backends read and write for this feature. Named once, here. */
+export const CLIENT_PROFILE_COLLECTIONS = Object.freeze({
+  SETTINGS: "clientprofilesettings",
+  FIELD_POLICIES: "clientfieldpolicies",
+  CHANGE_REQUESTS: "client_profile_change_requests",
+});
+
+/** The id of the settings document inside `clientprofilesettings`. */
+export const CLIENT_PROFILE_SETTINGS_DOC_ID = "default";
+
+export const MODES = Object.freeze({ OFF: "off", AUDIT: "audit", ENFORCE: "enforce" });
+const MODE_VALUES = Object.freeze(Object.values(MODES));
+
+export const PROFILE_TYPES = Object.freeze({ CORPORATE: "corporate", MAIN: "main" });
+
+/** What caused a relationship to be recorded on a client. */
+export const ATTACH_TRIGGERS = Object.freeze({
+  CREATE: "create",
+  ORDER: "order",
+  PROPOSAL: "proposal",
+  PFA: "pfa",
+  GOAL: "goal",
+  ACTIVITY: "activity",
+  REFERRAL: "referral",
+  LEAD_CONVERSION: "lead_conversion",
+  MERGE: "merge",
+});
+
+/**
+ * The defaults, which are also the schema. Frozen deeply so no caller can mutate the shared copy.
+ */
+export const DEFAULT_CLIENT_PROFILE_SETTINGS = deepFreeze({
+  modes: {
+    attach: MODES.OFF,
+    side_filter: MODES.OFF,
+    field_lock: MODES.OFF,
+    primary_lock: MODES.OFF,
+    mf_primary_stamp: MODES.OFF,
+    app_orders_primary: MODES.OFF,
+    goal_approval: MODES.OFF,
+    resolve_by_pan: MODES.OFF,
+    linked_visibility: MODES.OFF,
+    mf_one_investor: MODES.OFF,
+  },
+  corporate_distributor_types: [],
+  house_distributor_codes: [],
+  primary: {
+    lock_on_first_order: true,
+    ignore_order_statuses: [],
+    referral_sets_primary: true,
+    referral_types: [],
+  },
+  mf: {
+    product_codes: [],
+    exclusive_to_primary: true,
+    one_investor_per_person: true,
+  },
+  app_orders: {
+    tag_to_primary: true,
+  },
+  attach: {
+    triggers: [
+      ATTACH_TRIGGERS.ORDER,
+      ATTACH_TRIGGERS.PROPOSAL,
+      ATTACH_TRIGGERS.PFA,
+      ATTACH_TRIGGERS.GOAL,
+      ATTACH_TRIGGERS.ACTIVITY,
+      ATTACH_TRIGGERS.LEAD_CONVERSION,
+    ],
+    skip_if_already_visible: true,
+  },
+  access: {
+    owner_user_fields: ["e1", "rm_id", "dist_emp_rm_id", "created_by"],
+    linked_user_field: "linked_users.user_id",
+    mapping_distributor_field: "distributor_mappings.distributor_id",
+  },
+  side_filter: {
+    distributor_fields: ["distributor_id", "ma1_id", "ma2_id"],
+    placer_fields: ["created_by", "e1"],
+  },
+  linked_view: {
+    fields: ["_id", "client_code", "client_name", "first_name", "middle_name", "last_name", "pan_card_no", "phone_list", "status"],
+    masked_fields: ["pan_card_no", "phone_list"],
+    masked_contact_keys: ["mobile", "phone", "phone_no", "number", "email"],
+  },
+  field_lock: {
+    ops_roles: [],
+    require_reason_for_ops: true,
+    unclassified_field_action: "lock",
+    lock_requires_kyc_verified: true,
+    lock_requires_ucc: true,
+  },
+  change_request: {
+    ttl_minutes: 10,
+  },
+  goals: {
+    partner_goal_requires_approval: true,
+    corporate_goals_stay_with_corporate: true,
+  },
+  events: {
+    profile_change_requested: "client.profile_change.requested",
+    profile_change_applied: "client.profile_change.applied",
+    profile_change_rejected: "client.profile_change.rejected",
+    profile_change_expired: "client.profile_change.expired",
+    goal_approval_requested: "client.goal.approval_requested",
+    goal_approved: "client.goal.approved",
+    goal_rejected: "client.goal.rejected",
+    goal_share_requested: "client.goal.share_requested",
+    goal_shared: "client.goal.shared",
+    goal_share_revoked: "client.goal.revoked",
+    relationship_attached: "client.relationship.attached",
+  },
+  event_subject: {
+    // The Events Framework entity type a client event is filed under. It decides what the
+    // engine loads as `client` and which related parties (distributor, RM) and derived fields
+    // (the app user for nudges) a template can use. `client` there means a LEAD — not this.
+    client_entity_type: "distributorclient",
+  },
+  messages: {
+    [CLIENT_PROFILE_ERRORS.PERSONAL_FIELD_LOCKED]: "These details are updated by the client in the InvestValue app: {fields}.",
+    [CLIENT_PROFILE_ERRORS.CONFIRMATION_REQUIRED]: "{count} change(s) were sent to the client for confirmation.",
+    [CLIENT_PROFILE_ERRORS.MF_INVESTOR_EXISTS]: "This client already has a mutual fund account. Place orders on it.",
+    [CLIENT_PROFILE_ERRORS.CLIENT_NOT_IN_SCOPE]: "You can't act on this client.",
+    [CLIENT_PROFILE_ERRORS.PROFILE_TYPE_EXISTS]: "This person already has a {profile_type} profile. Use the existing one.",
+    [CLIENT_PROFILE_ERRORS.EXISTING_CLIENT_FOUND]: "This client already exists. You can place an order, create a proposal or run a portfolio analysis for them.",
+    [CLIENT_PROFILE_ERRORS.SETTINGS_INVALID]: "Client-profile settings were invalid; defaults were used for: {keys}.",
+  },
+});
+
+/**
+ * One line per setting, for documentation and the tracker's configuration registry. Kept next to
+ * the defaults so a new setting cannot ship undescribed — `describeClientProfileSettings` throws
+ * in tests when a leaf has no description.
+ */
+export const CLIENT_PROFILE_SETTING_DESCRIPTIONS = Object.freeze({
+  "modes.attach": "Record a distributor or employee on a client at their first saved action.",
+  "modes.side_filter": "Narrow client-keyed reads to the caller's own side.",
+  "modes.field_lock": "Enforce the personal-details field policy.",
+  "modes.primary_lock": "Lock the primary distributor on the first order.",
+  "modes.mf_primary_stamp": "Tag every MF order to the primary distributor.",
+  "modes.app_orders_primary": "Tag every client-app order to the primary distributor, without asking.",
+  "modes.goal_approval": "Hold partner-added goals until the client approves them.",
+  "modes.resolve_by_pan": "Show an existing client instead of a duplicate error when a PAN is found.",
+  "modes.mf_one_investor": "Refuse a second MF investor for a person who already has one (D9).",
+  "modes.linked_visibility": "Clients reached only through a secondary mapping or a linked user appear in lists, as the limited card.",
+  corporate_distributor_types: "distributors.distributor_type values whose clients get a corporate profile.",
+  house_distributor_codes: "Distributor codes treated as direct (InvestValue's own house distributors).",
+  "primary.lock_on_first_order": "The first non-ignored order locks the primary distributor.",
+  "primary.ignore_order_statuses": "Order statuses that do not count as first business (e.g. cancelled).",
+  "primary.referral_sets_primary": "A lead referred by a distributor makes that distributor primary at conversion.",
+  "primary.referral_types": "clientleads.referred_by_type values that count as a distributor referral.",
+  "mf.product_codes": "Product codes treated as mutual funds for exclusivity.",
+  "mf.exclusive_to_primary": "MF orders are always tagged to the primary distributor.",
+  "mf.one_investor_per_person": "Never create a second MF investor for a person.",
+  "app_orders.tag_to_primary": "Client-app orders land on the main profile's primary.",
+  "attach.triggers": "Which saved actions link the actor to the client.",
+  "attach.skip_if_already_visible": "Write no link when the actor can already see the client.",
+  "access.owner_user_fields": "Client fields naming an owning person; matching one gives full access.",
+  "access.linked_user_field": "Client field holding linked users (the linked-visibility arm).",
+  "access.mapping_distributor_field": "Client field holding mapped distributors (the secondary-distributor arm).",
+  "side_filter.distributor_fields": "Record fields that name a record's distributor side.",
+  "side_filter.placer_fields": "Record fields that name the person who created a record.",
+  "linked_view.fields": "Client fields returned to a caller with linked access.",
+  "linked_view.masked_fields": "Linked-view fields that are masked before returning.",
+  "linked_view.masked_contact_keys": "Keys masked inside contact entries of a masked list field.",
+  "field_lock.ops_roles": "Roles allowed to correct personal details (audited).",
+  "field_lock.require_reason_for_ops": "Ops corrections must carry a reason.",
+  "field_lock.unclassified_field_action": "What happens to a field with no policy row (edit, verify or lock).",
+  "field_lock.lock_requires_kyc_verified": "The personal lock starts only once KYC is verified.",
+  "field_lock.lock_requires_ucc": "The personal lock starts only once a UCC exists.",
+  "change_request.ttl_minutes": "Minutes a corporate change request waits for the client's OTP.",
+  "goals.partner_goal_requires_approval": "Goals added by partners or employees wait for the client's approval.",
+  "goals.corporate_goals_stay_with_corporate": "Corporate-profile goals are never shown to main-profile partners.",
+  "events.profile_change_requested": "Event name: a corporate change was sent to the client.",
+  "events.profile_change_applied": "Event name: the client confirmed a change.",
+  "events.profile_change_rejected": "Event name: the client rejected a change.",
+  "events.profile_change_expired": "Event name: a change request expired.",
+  "events.goal_approval_requested": "Event name: a goal waits for the client's approval.",
+  "events.goal_approved": "Event name: the client approved a goal.",
+  "events.goal_rejected": "Event name: the client rejected a goal.",
+  "events.goal_share_requested": "Event name: a partner asked to see a goal.",
+  "events.goal_shared": "Event name: the client shared a goal with a partner.",
+  "events.goal_share_revoked": "Event name: the client stopped sharing a goal.",
+  "events.relationship_attached": "Event name: a new distributor or employee was linked to a client.",
+  "event_subject.client_entity_type": "Events Framework entity type client events are filed under (distributorclients).",
+  messages: "Human text for each error code; {placeholders} are filled by the caller.",
+});
+
+/** The allowed values for leaves that are enums rather than free strings. */
+const ENUM_LEAVES = Object.freeze({
+  "field_lock.unclassified_field_action": ["edit", "verify", "lock"],
+});
+
+/**
+ * Merge an environment's settings document over the defaults, validating as it goes.
+ *
+ * @param {object|null|undefined} doc  the `clientprofilesettings` document (its `_id` and audit
+ *                                     fields are ignored)
+ * @returns {{ settings: object, problems: string[] }}  `settings` is deeply frozen
+ */
+export function resolveClientProfileSettings(doc) {
+  const problems = [];
+  const source = isPlainObject(doc) ? stripMeta(doc) : {};
+  const settings = mergeLevel(DEFAULT_CLIENT_PROFILE_SETTINGS, source, "", problems);
+  return { settings: deepFreeze(settings), problems };
+}
+
+/** Read a mode with a safe answer for anything unexpected (`off`). */
+export function modeOf(settings, name) {
+  const value = settings?.modes?.[name];
+  return MODE_VALUES.includes(value) ? value : MODES.OFF;
+}
+
+/** True when the mode means "compute the decision" (audit or enforce). */
+export function isEvaluated(settings, name) {
+  return modeOf(settings, name) !== MODES.OFF;
+}
+
+/** True only when the decision should be applied. */
+export function isEnforced(settings, name) {
+  return modeOf(settings, name) === MODES.ENFORCE;
+}
+
+/**
+ * Fill a message template from settings. Unknown placeholders are left as-is so a missing value
+ * is visible rather than silently blank.
+ */
+export function messageFor(settings, code, values = {}) {
+  const template = settings?.messages?.[code] ?? DEFAULT_CLIENT_PROFILE_SETTINGS.messages[code] ?? code;
+  return String(template).replace(/\{(\w+)\}/g, (whole, key) => (key in values ? String(values[key]) : whole));
+}
+
+/**
+ * Flatten the defaults into registry rows: `{ key, default, description }`. Every leaf must be
+ * described; an undescribed leaf throws so it is caught in tests, not in production docs.
+ */
+/**
+ * The Events Framework subject for an event about a client. One place, so every emitter files
+ * client events under the same entity type.
+ */
+export function clientEventSubject(settings, clientId, extra = {}) {
+  return { entityType: settings.event_subject.client_entity_type, entityId: String(clientId), ...extra };
+}
+
+export function describeClientProfileSettings() {
+  const rows = [];
+  walkLeaves(DEFAULT_CLIENT_PROFILE_SETTINGS, "", (key, value) => {
+    const describedKey = key.startsWith("messages.") ? "messages" : key;
+    if (describedKey === "messages" && rows.some((r) => r.key === "messages")) return;
+    const description = CLIENT_PROFILE_SETTING_DESCRIPTIONS[describedKey];
+    if (!description) throw new Error(`client-profile setting "${key}" has no description`);
+    rows.push({
+      key: describedKey,
+      default: describedKey === "messages" ? DEFAULT_CLIENT_PROFILE_SETTINGS.messages : value,
+      description,
+    });
+  });
+  return rows;
+}
+
+// ── internals ─────────────────────────────────────────────────────────────────────────────────
+
+const META_KEYS = new Set(["_id", "created_at", "updated_at", "created_by", "updated_by", "__v"]);
+
+function stripMeta(doc) {
+  const out = {};
+  for (const [k, v] of Object.entries(doc)) if (!META_KEYS.has(k)) out[k] = v;
+  return out;
+}
+
+function mergeLevel(defaults, source, prefix, problems) {
+  const out = {};
+  for (const key of Object.keys(source)) {
+    if (!(key in defaults) && prefix !== "messages.") problems.push(`${prefix}${key}: unknown setting, ignored`);
+  }
+  for (const [key, def] of Object.entries(defaults)) {
+    const path = `${prefix}${key}`;
+    const has = Object.prototype.hasOwnProperty.call(source, key);
+    const value = has ? source[key] : undefined;
+    if (isPlainObject(def)) {
+      if (has && !isPlainObject(value)) {
+        problems.push(`${path}: expected an object, kept the default`);
+        out[key] = clone(def);
+      } else {
+        out[key] = mergeLevel(def, has ? value : {}, `${path}.`, problems);
+      }
+      continue;
+    }
+    if (!has) {
+      out[key] = clone(def);
+      continue;
+    }
+    if (acceptsValue(path, def, value)) out[key] = clone(value);
+    else {
+      problems.push(`${path}: ${describeExpected(path, def)}, kept the default`);
+      out[key] = clone(def);
+    }
+  }
+  // Messages may carry codes the defaults do not know yet (a newer backend); keep them.
+  if (prefix === "messages.") {
+    for (const [key, value] of Object.entries(source)) {
+      if (!(key in out) && typeof value === "string") out[key] = value;
+    }
+  }
+  return out;
+}
+
+function acceptsValue(path, def, value) {
+  if (path.startsWith("modes.")) return MODE_VALUES.includes(value);
+  if (ENUM_LEAVES[path]) return ENUM_LEAVES[path].includes(value);
+  if (Array.isArray(def)) return Array.isArray(value) && value.every((v) => typeof v === "string");
+  if (typeof def === "boolean") return typeof value === "boolean";
+  if (typeof def === "number") return typeof value === "number" && Number.isFinite(value) && value >= 0;
+  if (typeof def === "string") return typeof value === "string" && value.length > 0;
+  return false;
+}
+
+function describeExpected(path, def) {
+  if (path.startsWith("modes.")) return `expected one of ${MODE_VALUES.join("|")}`;
+  if (ENUM_LEAVES[path]) return `expected one of ${ENUM_LEAVES[path].join("|")}`;
+  if (Array.isArray(def)) return "expected a list of strings";
+  if (typeof def === "number") return "expected a non-negative number";
+  return `expected a ${typeof def}`;
+}
+
+function walkLeaves(obj, prefix, visit) {
+  for (const [key, value] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isPlainObject(value)) walkLeaves(value, path, visit);
+    else visit(path, value);
+  }
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+}
+
+function clone(v) {
+  if (Array.isArray(v)) return v.map(clone);
+  if (isPlainObject(v)) return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, clone(x)]));
+  return v;
+}
+
+function deepFreeze(obj) {
+  for (const value of Object.values(obj)) if (value && typeof value === "object") deepFreeze(value);
+  return Object.freeze(obj);
+}

package/src/client-profile/side-filter.js

@@ -0,0 +1,96 @@
+/**
+ * The side filter — what a caller may see of records filed on a client they can see.
+ *
+ * A client can now carry business from several sides. Every read keyed by `client_id` (orders,
+ * proposals, PFA uploads, goals, activities, MF batches) is narrowed with this filter, ANDed next
+ * to the `client_id` match. It only ever narrows: the tenant and record scopes still apply.
+ *
+ *   client (app)             → everything          ({})
+ *   full internal / ops      → everything          ({})
+ *   partner, full or linked  → their firm's side   (distributor fields ∈ firm)
+ *   linked internal employee → what they placed    (placer fields ∈ self + reportees)
+ *   linked partner staff     → firm side AND what they placed
+ *   none                     → nothing             (an impossible match)
+ *
+ * The field names come from settings (`side_filter.*`) because records name their distributor
+ * and creator differently across collections; the backend passes per-collection overrides when a
+ * collection differs (e.g. proposals use `distributorId` / `createdBy`).
+ *
+ * Returns a plain Mongo filter fragment. Ids are passed through untouched — the backend decides
+ * whether its collection stores ObjectIds or strings and passes values of that type.
+ */
+import { ACCESS_LEVELS, CALLER_CLASSES } from "./access.js";
+import { isEnforced, isEvaluated } from "./settings.js";
+
+/** A filter that matches nothing, for callers with no access. Stable so it can be asserted on. */
+export const MATCH_NOTHING = Object.freeze({ _id: { $exists: false } });
+
+/**
+ * @param {{ callerClass: string, accessLevel: string, firmDistributorIds?: Array,
+ *           userIds?: Array, fields?: { distributor?: string[], placer?: string[] },
+ *           settings: object }} input
+ * @returns {{ filter: object, applied: boolean, decided: object }}
+ *   `decided` is what enforce would apply; `filter` is what to apply now (`{}` unless enforced).
+ */
+export function buildSideFilter({ callerClass, accessLevel, firmDistributorIds = [], userIds = [], fields = {}, settings }) {
+  const decided = decideSideFilter({ callerClass, accessLevel, firmDistributorIds, userIds, fields, settings });
+  if (!isEvaluated(settings, "side_filter")) return { filter: {}, applied: false, decided: {} };
+  const enforce = isEnforced(settings, "side_filter");
+  return { filter: enforce ? decided : {}, applied: enforce, decided };
+}
+
+function decideSideFilter({ callerClass, accessLevel, firmDistributorIds, userIds, fields, settings }) {
+  if (callerClass === CALLER_CLASSES.CLIENT) return {};
+  if (accessLevel === ACCESS_LEVELS.NONE) return MATCH_NOTHING;
+
+  const distributorFields = fields.distributor ?? settings?.side_filter?.distributor_fields ?? [];
+  const placerFields = fields.placer ?? settings?.side_filter?.placer_fields ?? [];
+
+  if (callerClass === CALLER_CLASSES.PARTNER) {
+    const firm = anyOf(distributorFields, firmDistributorIds);
+    if (accessLevel === ACCESS_LEVELS.LINKED) return and(firm, anyOf(placerFields, userIds));
+    return firm;
+  }
+
+  // Internal callers (ops, employees).
+  if (accessLevel === ACCESS_LEVELS.FULL) return {};
+  return anyOf(placerFields, userIds);
+}
+
+function anyOf(fieldNames, values) {
+  if (!fieldNames.length || !values.length) return MATCH_NOTHING;
+  const arms = fieldNames.map((f) => ({ [f]: { $in: [...values] } }));
+  return arms.length === 1 ? arms[0] : { $or: arms };
+}
+
+function and(a, b) {
+  if (a === MATCH_NOTHING || b === MATCH_NOTHING) return MATCH_NOTHING;
+  return { $and: [a, b] };
+}
+
+/**
+ * Evaluate a side filter against an already-fetched record — for reads that filter in memory or
+ * aggregate in ways a query fragment cannot be spliced into. Supports exactly the shapes
+ * `buildSideFilter` produces: `{}`, MATCH_NOTHING, `$or`, `$and`, and `{ field: { $in: [...] } }`
+ * (dotted paths; array values match when any element matches). Ids compare by string.
+ */
+export function recordMatchesFilter(record, filter) {
+  if (!filter || Object.keys(filter).length === 0) return true;
+  if (filter === MATCH_NOTHING || (filter._id && filter._id.$exists === false)) return false;
+  return Object.entries(filter).every(([key, cond]) => {
+    if (key === "$or") return cond.some((f) => recordMatchesFilter(record, f));
+    if (key === "$and") return cond.every((f) => recordMatchesFilter(record, f));
+    const wanted = new Set((cond?.$in ?? []).map(String));
+    const value = valueAt(record, key);
+    const values = Array.isArray(value) ? value : [value];
+    return values.some((v) => v !== null && v !== undefined && wanted.has(String(v?._id ?? v)));
+  });
+}
+
+function valueAt(record, path) {
+  return path.split(".").reduce((acc, part) => {
+    if (acc === null || acc === undefined) return undefined;
+    if (Array.isArray(acc)) return acc.map((x) => x?.[part]);
+    return acc[part];
+  }, record);
+}