@thejob/schema 2.1.7 → 2.1.8

package/src/marketing/marketing.schema.ts

@@ -1,18 +1,33 @@
-import { array, boolean, number, object, string } from "yup";
+import { array, boolean, lazy, mixed, number, object, string } from "yup";
 import {
+  SupportedEducationLevels,
   SupportedExperienceLevels,
   SupportedStudyTypes,
 } from "../common/common.constant.js";
+import { SupportedPageTypes } from "../page/page.constant.js";
 import { SupportedSocialAccounts } from "../social-account/social-account.constant.js";
 import {
+  SupportedJobAlertFrequencies,
   SupportedJobSearchUrgencies,
+  SupportedNotificationChannels,
   SupportedProficiencyLevels,
   SupportedReferralSources,
   SupportedSalaryCurrencies,
+  SupportedSignupContextSources,
   SupportedUserProfileVisibilities,
   SupportedUserRoles,
   SupportedUserStatuses,
 } from "../user/user.constant.js";
+import {
+  CAMPAIGN_MAX_RECIPIENTS_CEILING,
+  CampaignEndKind,
+  CampaignTriggerKind,
+  SupportedBindingKinds,
+  SupportedCampaignAnchorFields,
+  SupportedCampaignEndKinds,
+  SupportedCampaignIntervalUnits,
+  SupportedCampaignTriggerKinds,
+} from "./marketing.constant.js";
 
 // ─── Audience filter ─────────────────────────────────────────────────────────
 // The saved query a mailing list resolves against the users collection. Every
@@ -34,7 +49,50 @@ const enumFacet = (values: readonly string[], label: string) =>
     .default([])
     .label(label);
 
-export const ListFilterSchema = object({
+// Relative windows are counted in whole days/months at resolution time. Bounded
+// so a typo cannot turn into an unbounded scan; `undefined` (not 0) is "unset",
+// because 0 days is a meaningful value.
+const days = (label: string) =>
+  number().integer().min(0).max(3650).optional().default(undefined).label(label);
+
+const months = (label: string) =>
+  number().integer().min(0).max(1200).optional().default(undefined).label(label);
+
+const percent = (label: string) =>
+  number().integer().min(0).max(100).optional().default(undefined).label(label);
+
+/** Absolute epoch milliseconds. */
+const epoch = (label: string) =>
+  number().integer().min(0).optional().default(undefined).label(label);
+
+/**
+ * A salary bound, valid only when the filter also pins exactly one currency.
+ * `minSalary` is stored as a bare integer, so comparing across USD/EUR/GBP/SEK/INR
+ * is not a comparison at all.
+ */
+const salaryBound = (label: string) =>
+  number()
+    .integer()
+    .min(0)
+    .optional()
+    .default(undefined)
+    .label(label)
+    .when("salaryCurrencies", {
+      is: (v: unknown) => !Array.isArray(v) || v.length !== 1,
+      then: (s) =>
+        s.test(
+          "requires-single-currency",
+          "Pick exactly one salary currency to filter by salary",
+          (value) => value === undefined || value === null,
+        ),
+    });
+
+/**
+ * Every clause except `or`. Declared separately so `ListFilterSchema` can embed
+ * it as its branch type without referring to itself: the union is deliberately
+ * one level deep, and a non-recursive definition is what enforces that.
+ */
+export const ListFilterBranchSchema = object({
   // ── Enum facets (closed vocabularies, chip pickers) ─────────────────────────
   countries: array().of(string().required()).optional().default([]).label("Countries"),
   roles: enumFacet(SupportedUserRoles, "Roles"),
@@ -91,8 +149,12 @@ export const ListFilterSchema = object({
   keywords: tokens("Profile Keywords"),
 
   // ── Range / boolean facets ──────────────────────────────────────────────────
-  minSalaryFloor: number().integer().min(0).optional().label("Min Salary ≥"),
-  minSalaryCeil: number().integer().min(0).optional().label("Min Salary ≤"),
+  // A salary bound is meaningless without a currency: `minSalary` is a raw
+  // integer and 50000 SEK is not 50000 USD, so an un-currencied range matches
+  // across currencies and quietly means nothing. Requiring exactly one currency
+  // alongside a bound is what makes the comparison sound.
+  minSalaryFloor: salaryBound("Min Salary ≥"),
+  minSalaryCeil: salaryBound("Min Salary ≤"),
   openToWorkOnly: boolean().optional().default(false).label("Open to Work Only"),
   remoteExperienceOnly: boolean()
     .optional()
@@ -108,7 +170,177 @@ export const ListFilterSchema = object({
     .optional()
     .default(false)
     .label("Mobile Verified Only"),
-}).label("Audience Filter");
+
+  // ── Lifecycle windows ───────────────────────────────────────────────────────
+  // Relative, because a saved list is resolved fresh on every send: a stored
+  // absolute epoch would freeze at authoring time and the audience would decay
+  // to nothing. The absolute forms below exist for one-shot sends; when both are
+  // present the relative form wins.
+  lastSeenBeforeDays: days("Inactive For (days) ≥"),
+  lastSeenAfterDays: days("Active Within (days)"),
+  createdAtWithinDays: days("Signed Up Within (days)"),
+  createdAtOlderThanDays: days("Signed Up Before (days ago)"),
+  completenessMin: percent("Profile Completeness ≥"),
+  completenessMax: percent("Profile Completeness ≤"),
+  // Absolute epoch-ms forms. Prefer the relative fields above for anything that
+  // repeats.
+  lastSeenBefore: epoch("Last Seen Before"),
+  lastSeenAfter: epoch("Last Seen After"),
+  createdAtFrom: epoch("Signed Up After"),
+  createdAtBefore: epoch("Signed Up Before"),
+
+  // ── Geography ───────────────────────────────────────────────────────────────
+  // `countries` above matches location.countryCode. These narrow within it.
+  // NOTE: stateCodes are stored bare (`KA`, not `IN-KA`) — see the pending
+  // @todo STATE-CODE-ISO-PREFIX migration. Match the stored form, do not prefix.
+  states: tokens("States"),
+  stateCodes: tokens("State Codes"),
+  cities: tokens("Cities"),
+  // Radius search around a point, against location.geo. All three required
+  // together; validated as a group rather than field-by-field so a half-filled
+  // radius cannot silently match everyone.
+  withinRadius: object({
+    lat: number().min(-90).max(90).required().label("Latitude"),
+    lng: number().min(-180).max(180).required().label("Longitude"),
+    km: number().moreThan(0).max(20_000).required().label("Radius (km)"),
+  })
+    .optional()
+    .default(undefined)
+    .label("Within Radius"),
+
+  // ── Signup context (immutable market / locale) ──────────────────────────────
+  signupCountries: tokens("Signup Countries"),
+  signupLocales: tokens("Signup Locales"),
+  signupSources: enumFacet(SupportedSignupContextSources, "Signup Source"),
+
+  // ── Attainment ──────────────────────────────────────────────────────────────
+  // Absent on users who predate the field. Absent means "unknown", never a
+  // match — filtering on this necessarily excludes them.
+  educationLevels: enumFacet(SupportedEducationLevels, "Education Level"),
+
+  // ── Consent metadata ────────────────────────────────────────────────────────
+  // `marketingConsent.subscribed` is NOT a facet: it is a hard opt-in gate
+  // applied unconditionally by user-service and is not relaxable from here.
+  jobAlertFrequencies: enumFacet(
+    SupportedJobAlertFrequencies,
+    "Job Alert Frequency",
+  ),
+  consentSources: tokens("Consent Source"),
+  consentUpdatedWithinDays: days("Consent Updated Within (days)"),
+
+  // ── Notification preferences ────────────────────────────────────────────────
+  // Read as opt-IN (`=== true`), matching marketingConsent and NOT the `!== false`
+  // reading used for transactional notification routing. A campaign is bulk mail,
+  // so a channel the user never affirmatively enabled does not count as consent.
+  // `productUpdates` defaults to false on the user document, so targeting it
+  // selects only people who deliberately turned it on.
+  notificationChannelsEnabled: enumFacet(
+    SupportedNotificationChannels,
+    "Notification Channels Enabled",
+  ),
+
+  // ── Tenure / recency ────────────────────────────────────────────────────────
+  // Against workExperiences[].duration and educations[].duration ("YYYY-MM").
+  currentlyEmployed: boolean()
+    .optional()
+    .default(false)
+    .label("Currently Employed"),
+  graduatedWithinMonths: months("Graduated Within (months)"),
+  skillUsedWithinMonths: months("Skill Used Within (months)"),
+
+  // ── Profile richness ────────────────────────────────────────────────────────
+  hasImage: boolean().optional().default(false).label("Has Photo"),
+  hasHeadline: boolean().optional().default(false).label("Has Headline"),
+  hasAboutMe: boolean().optional().default(false).label("Has About Me"),
+  hasMobile: boolean().optional().default(false).label("Has Mobile Number"),
+  // Segment by WHICH profile section is missing (profileCompleteness.missing[]),
+  // rather than only by the overall percentage.
+  missingSections: tokens("Missing Profile Sections"),
+
+  // ── Employer / institute taxonomy ───────────────────────────────────────────
+  companyTypes: enumFacet(SupportedPageTypes, "Company Type"),
+  instituteTypes: enumFacet(SupportedPageTypes, "Institute Type"),
+
+  // ── Activity ────────────────────────────────────────────────────────────────
+  // Backed by denormalised counters on the user document, because the source
+  // data lives in other services' collections. Tri-state: `false` is a real
+  // filter ("has NO job alert"), which is the audience an alert nudge wants, so
+  // these are `undefined` when unset rather than defaulting to false.
+  hasJobAlert: boolean()
+    .optional()
+    .default(undefined)
+    .label("Has a Job Alert"),
+  hasApplied: boolean().optional().default(undefined).label("Has Applied"),
+  appliedWithinDays: days("Applied Within (days)"),
+
+  // ── Free-text search (name / email) ─────────────────────────────────────────
+  search: string().trim().optional().label("Search"),
+
+})
+  .label("Audience Filter Branch");
+
+/**
+ * Rejects filter keys the query builder does not understand.
+ *
+ * A silently dropped filter key widens the audience with no error, which is how
+ * a "Has Resume" checkbox ends up mailing everyone. Yup's own `noUnknown` only
+ * errors under `.strict()`, which would additionally disable coercion and reject
+ * the "80" / "true" strings form payloads legitimately send, so this is done as
+ * a test instead: unknown keys fail, coercion stays on.
+ *
+ * `allowed` is passed in rather than read from the schema, so that the branch
+ * schema can forbid `or` while the top-level filter permits it.
+ */
+const rejectUnknownKeys = <T extends { test: (...a: never[]) => T }>(
+  schema: T,
+  allowed: () => readonly string[],
+): T =>
+  (schema.test as unknown as (
+    name: string,
+    msg: (p: { value: unknown; label: string }) => string,
+    fn: (v: unknown) => boolean,
+  ) => T)(
+    "no-unknown-filter-keys",
+    ({ value, label }) => {
+      const known = new Set(allowed());
+      const bad = Object.keys((value ?? {}) as Record<string, unknown>).filter(
+        (k) => !known.has(k),
+      );
+      return `${label} has unsupported keys: ${bad.join(", ")}`;
+    },
+    (value) => {
+      if (value == null) return true;
+      const known = new Set(allowed());
+      return Object.keys(value as Record<string, unknown>).every((k) =>
+        known.has(k),
+      );
+    },
+  );
+
+/**
+ * The saved audience query. Every clause AND-s together; `or` unions the whole
+ * filter with each branch, deduplicating by user, for audiences that are
+ * genuinely a union rather than an intersection ("signed up recently OR active
+ * recently"). One level only, branches do not nest.
+ */
+const BRANCH_KEYS = Object.keys(ListFilterBranchSchema.fields);
+
+/** A branch of `or`: every clause except `or` itself, so unions cannot nest. */
+export const ListFilterBranch = rejectUnknownKeys(
+  ListFilterBranchSchema,
+  () => BRANCH_KEYS,
+);
+
+export const ListFilterSchema = rejectUnknownKeys(
+  ListFilterBranchSchema.shape({
+    or: array()
+      .of(ListFilterBranch)
+      .optional()
+      .default([])
+      .label("Or Any Of"),
+  }).label("Audience Filter"),
+  () => [...BRANCH_KEYS, "or"],
+);
 
 // ─── Mailing list ────────────────────────────────────────────────────────────
 
@@ -120,11 +352,252 @@ export const MailingListSchema = object({
 
 // ─── Campaign ────────────────────────────────────────────────────────────────
 
+/**
+ * When a campaign sends. Discriminated by `kind`; the fields each kind needs are
+ * required only for that kind, so one stored shape covers all four.
+ */
+export const CampaignTriggerSchema = object({
+  kind: string()
+    .oneOf(SupportedCampaignTriggerKinds)
+    .required()
+    .default(CampaignTriggerKind.Manual)
+    .label("Trigger"),
+
+  // IANA zone, e.g. "Asia/Kolkata". Local wall-clock times are interpreted in it,
+  // so occurrences land at the intended hour across DST rather than drifting.
+  timezone: string()
+    .optional()
+    .default("UTC")
+    .label("Timezone")
+    .when("kind", {
+      is: (k: string) => k !== CampaignTriggerKind.Manual,
+      then: (s) => s.required(),
+    }),
+
+  // kind: once
+  runAt: epoch("Send At").when("kind", {
+    is: CampaignTriggerKind.Once,
+    then: (s) => s.required(),
+  }),
+
+  // kind: schedule
+  startAt: epoch("Starts").when("kind", {
+    is: CampaignTriggerKind.Schedule,
+    then: (s) => s.required(),
+  }),
+  interval: object({
+    every: number().integer().min(1).max(365).required().label("Every"),
+    unit: string()
+      .oneOf(SupportedCampaignIntervalUnits)
+      .required()
+      .label("Unit"),
+  })
+    .optional()
+    .default(undefined)
+    .label("Repeats")
+    .when("kind", {
+      is: CampaignTriggerKind.Schedule,
+      then: (s) => s.required(),
+    }),
+  /** Local wall-clock send time, "HH:mm" in `timezone`. */
+  timeOfDay: string()
+    .matches(/^([01]\d|2[0-3]):[0-5]\d$/, "Use HH:mm")
+    .optional()
+    .default("09:00")
+    .label("Time of Day"),
+  /** For weekly intervals: ISO weekdays, 1 = Monday .. 7 = Sunday. */
+  byWeekday: array()
+    .of(number().integer().min(1).max(7).required())
+    .optional()
+    .default([])
+    .label("On Days"),
+  /**
+   * For monthly intervals: 1-31, or -1 meaning "last day of the month". A month
+   * shorter than the chosen day is clamped to its last day, so 31 in February
+   * fires on the 28th/29th rather than being skipped.
+   */
+  byMonthday: number()
+    .integer()
+    .min(-1)
+    .max(31)
+    .notOneOf([0])
+    .optional()
+    .default(undefined)
+    .label("Day of Month"),
+  end: object({
+    kind: string().oneOf(SupportedCampaignEndKinds).required().label("Ends"),
+    occurrences: number()
+      .integer()
+      .min(1)
+      .max(10_000)
+      .optional()
+      .default(undefined)
+      .label("After N Sends")
+      .when("kind", {
+        is: CampaignEndKind.AfterOccurrences,
+        then: (s) => s.required(),
+      }),
+    date: epoch("End Date").when("kind", {
+      is: CampaignEndKind.OnDate,
+      then: (s) => s.required(),
+    }),
+  })
+    .optional()
+    .default(() => ({ kind: CampaignEndKind.Never }))
+    .label("End Condition"),
+
+  // kind: lifecycle
+  anchorField: string()
+    .oneOf(SupportedCampaignAnchorFields)
+    .optional()
+    .default(undefined)
+    .label("Anchor Date")
+    .when("kind", {
+      is: CampaignTriggerKind.Lifecycle,
+      then: (s) => s.required(),
+    }),
+  /** Days after the anchor at which this user becomes eligible. */
+  offsetDays: number()
+    .integer()
+    .min(0)
+    .max(3650)
+    .optional()
+    .default(undefined)
+    .label("Days After Anchor")
+    .when("kind", {
+      is: CampaignTriggerKind.Lifecycle,
+      then: (s) => s.required(),
+    }),
+  /**
+   * How long a user stays eligible after crossing the offset. Needed because the
+   * scheduler samples periodically and a zero-width window would miss anyone not
+   * observed on the exact day. A user inside the window on several ticks is still
+   * mailed once: the permanent idempotency key, not this value, guarantees that.
+   */
+  windowDays: number()
+    .integer()
+    .min(1)
+    .max(90)
+    .optional()
+    .default(2)
+    .label("Eligibility Window (days)"),
+}).label("Trigger");
+
+/**
+ * Where one template variable's value comes from. `value` carries the literal for
+ * `static`/`url`, and the field path for `recipient`/`source`.
+ */
+export const BindingSchema = object({
+  kind: string().oneOf(SupportedBindingKinds).required().label("Source"),
+  value: string().required().min(1).max(2000).label("Value"),
+}).label("Binding");
+
 export const CampaignSchema = object({
   name: string().required().min(1).max(200).label("Campaign Name"),
-  subject: string().required().min(1).max(255).label("Subject"),
-  // HTML body; may contain a {{unsubscribe_url}} placeholder.
-  html: string().required().min(1).label("HTML Body"),
+  // The template renders its own subject; an override is only needed for the
+  // inline-HTML path, hence not required when a template is chosen.
+  subject: string()
+    .optional()
+    .max(255)
+    .label("Subject")
+    .when("templateKey", {
+      is: (v: unknown) => !v,
+      then: (s) => s.required().min(1),
+    }),
+  /**
+   * Inline HTML body; may contain {{unsubscribe_url}}. Optional now that a
+   * campaign can instead name a registry template — exactly one of the two is
+   * required. Scheduled and lifecycle campaigns must use a template: the
+   * registry path is the one with a compliance-checked footer and a render test,
+   * and hand-pasted HTML that repeats forever is a mistake that repeats forever.
+   */
+  html: string()
+    .optional()
+    .label("HTML Body")
+    .when("templateKey", {
+      is: (v: unknown) => !v,
+      then: (s) => s.required().min(1),
+    }),
   text: string().optional().label("Plain-text Body"),
   listId: string().required().label("Mailing List"),
+
+  /** Key from email-service's template registry. Mutually exclusive with `html`. */
+  templateKey: string().optional().label("Email Template"),
+  /**
+   * One entry per variable the chosen template declares. Validated at save time
+   * against the template's own `variables`, so a missing required binding is a
+   * rejected save rather than a broken send.
+   */
+  /**
+   * A DICTIONARY keyed by template variable name, which Yup has no native type
+   * for. It must be built with `lazy` from the keys actually present: a bare
+   * `object()` has no known keys, so under `stripUnknown: true` (which the
+   * consumers' validate helper passes) every binding is "unknown" and the whole
+   * map arrives as `{}` — silently turning a fully-configured campaign into one
+   * whose required variables all appear unbound. Shaping each entry also means a
+   * malformed binding is rejected here rather than at send time.
+   */
+  bindings: lazy((value: unknown) => {
+    const keys = value && typeof value === "object" ? Object.keys(value) : [];
+    return object(
+      Object.fromEntries(keys.map((k) => [k, BindingSchema.required()])),
+    )
+      .optional()
+      .default(() => ({}))
+      .label("Template Data");
+  }),
+  /** Registered data source supplying per-recipient content, plus its params. */
+  dataSource: object({
+    id: string().required().label("Data Source"),
+    /**
+     * A free-form bag whose keys are defined by the chosen source's OWN
+     * `paramsSchema`, which this package cannot see. Same `lazy` treatment as
+     * `bindings` above, and for the same reason: a bare `object()` has no known
+     * keys, so under `stripUnknown: true` every param is "unknown" and the bag
+     * arrives as `{}` — a campaign configured to mail remote Python roles in
+     * Bangalore silently saves as an unfiltered platform-wide digest.
+     *
+     * Values stay unvalidated here on purpose; the marketing service validates
+     * them against the real source schema in `checkCampaignConfig`, which is the
+     * only place that knows what a given source accepts.
+     */
+    params: lazy((value: unknown) => {
+      const keys =
+        value && typeof value === "object" ? Object.keys(value) : [];
+      return object(
+        Object.fromEntries(keys.map((k) => [k, mixed().optional()])),
+      )
+        .optional()
+        .default(() => ({}))
+        .label("Parameters");
+    }),
+  })
+    .optional()
+    .default(undefined)
+    .label("Data Source"),
+
+  trigger: CampaignTriggerSchema.default(() =>
+    CampaignTriggerSchema.getDefault(),
+  ),
+
+  // ── Safety ──────────────────────────────────────────────────────────────────
+  // Both default to the safe position: a new campaign neither runs nor sends
+  // until someone deliberately says so, and says so twice.
+  enabled: boolean().optional().default(false).label("Enabled"),
+  dryRun: boolean().optional().default(true).label("Dry Run"),
+  maxRecipients: number()
+    .integer()
+    .min(1)
+    .max(CAMPAIGN_MAX_RECIPIENTS_CEILING)
+    .optional()
+    .default(undefined)
+    .label("Max Recipients"),
+
+  utm: object({
+    campaign: string().optional().max(120).label("utm_campaign"),
+    content: string().optional().max(120).label("utm_content"),
+  })
+    .optional()
+    .default(undefined)
+    .label("Link Tagging"),
 }).label("Campaign");