@thejob/schema 2.1.9 → 2.3.0

package/src/marketing/marketing.schema.ts

@@ -1,360 +1,51 @@
 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,
+  CampaignStatus,
   SupportedCampaignEndKinds,
+  SupportedCampaignStatuses,
   SupportedCampaignIntervalUnits,
   SupportedCampaignTriggerKinds,
+  SupportedTemplateVariableBindingKinds,
 } from "./marketing.constant.js";
-
-// ─── Audience filter ─────────────────────────────────────────────────────────
-// The saved query a mailing list resolves against the users collection. Every
-// clause is optional and AND-ed; empty groups match everyone.
-//
-// Two kinds of clause:
-//   • Enum facets (`.oneOf(...)`) — closed vocabularies rendered as chip pickers.
-//   • Free-text token facets — open vocabularies (skills, companies, institutes,
-//     …) matched case-insensitively against a nested array/field. Any token in
-//     the list matches (OR within a facet), facets AND together.
-
-const tokens = (label: string) =>
-  array().of(string().trim().required()).optional().default([]).label(label);
-
-const enumFacet = (values: readonly string[], label: string) =>
-  array()
-    .of(string().oneOf(values).required())
-    .optional()
-    .default([])
-    .label(label);
-
-// 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,
-        ),
-    });
+import { epoch } from "../common/facet.schema.js";
+import { UserFilterSchema } from "../user/user-filter.schema.js";
 
 /**
- * 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"),
-  // The user's own current seniority (UserSchema.experienceLevel).
-  experienceLevels: enumFacet(SupportedExperienceLevels, "Experience Levels"),
-  // Levels the user is *targeting* (distinct from their current experienceLevel).
-  targetExperienceLevels: enumFacet(
-    SupportedExperienceLevels,
-    "Target Experience Levels",
-  ),
-  jobSearchUrgencies: enumFacet(SupportedJobSearchUrgencies, "Job Search Urgency"),
-  referralSources: enumFacet(SupportedReferralSources, "Referral Source"),
-  statuses: enumFacet(SupportedUserStatuses, "Account Status"),
-  profileVisibilities: enumFacet(
-    SupportedUserProfileVisibilities,
-    "Profile Visibility",
-  ),
-  // Proficiency held on any skill entry (skills[].proficiencyLevel).
-  skillProficiencyLevels: enumFacet(
-    SupportedProficiencyLevels,
-    "Skill Proficiency",
-  ),
-  // Proficiency held on any language entry (languages[].proficiencyLevel).
-  languageProficiencyLevels: enumFacet(
-    SupportedProficiencyLevels,
-    "Language Proficiency",
-  ),
-  // Mode of any education entry (educations[].studyType).
-  studyTypes: enumFacet(SupportedStudyTypes, "Study Type"),
-  // Platforms the user linked a social account for (socialAccounts[].type).
-  socialAccountTypes: enumFacet(SupportedSocialAccounts, "Social Accounts"),
-  // Currency of the user's salary floor (minSalaryCurrency).
-  salaryCurrencies: enumFacet(SupportedSalaryCurrencies, "Salary Currency"),
-
-  // ── Free-text token facets (nested profile arrays) ──────────────────────────
-  skills: tokens("Skills"),
-  languages: tokens("Languages"),
-  interests: tokens("Interests"),
-  companies: tokens("Companies"),
-  designations: tokens("Job Titles / Designations"),
-  institutes: tokens("Institutes"),
-  courses: tokens("Courses"),
-  fieldsOfStudy: tokens("Fields of Study"),
-  certifications: tokens("Certifications"),
-  certificationAuthorities: tokens("Certification Authorities"),
-  projects: tokens("Projects"),
-  jobRoles: tokens("Target Roles"),
-  jobLocations: tokens("Preferred Job Locations"),
-  // Companies a recruiter is hiring for (recruiterProfile.hiringFor[].page.name).
-  hiringForCompanies: tokens("Hiring For (Companies)"),
-  // Institutes a coordinator works at (coordinatorProfile.coordinatesAt[].page.name).
-  coordinatesAtInstitutes: tokens("Coordinates At (Institutes)"),
-  // Case-insensitive keyword match against headline + aboutMe.
-  keywords: tokens("Profile Keywords"),
-
-  // ── Range / boolean facets ──────────────────────────────────────────────────
-  // 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()
-    .default(false)
-    .label("Has Remote Experience"),
-  hasResumeOnly: boolean().optional().default(false).label("Has Resume"),
-  onboardingCompletedOnly: boolean()
-    .optional()
-    .default(false)
-    .label("Onboarding Completed"),
-  emailVerifiedOnly: boolean().optional().default(false).label("Email Verified Only"),
-  mobileVerifiedOnly: boolean()
-    .optional()
-    .default(false)
-    .label("Mobile Verified Only"),
-
-  // ── 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 mailing list's saved audience query.
  *
- * 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.
+ * The SAME filter user-service validates, re-exported under the name it carries
+ * where it is stored. Not a separate vocabulary: a list resolves against
+ * user-service, so anything it can save must be something that service accepts.
+ * Defined in `user/user-filter.schema.ts` because it describes users.
  *
- * `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.
+ * @todo SVELTE-UI-SCHEMA-RENAME — this was `ListFilterSchema`, and
+ * `thejob-svelte-ui` still imports THAT name in
+ * `src/lib/services/admin.service.ts` (3 lines: the import, a doc reference and
+ * the `InferType` argument). It will not typecheck against this build until
+ * those are updated. Deliberately left unmigrated rather than fixed in passing:
+ * renaming an export here is a change to every consumer, and each one is its
+ * own decision. No back-compat alias, so the break is loud rather than silent.
  */
-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"],
-);
+export const MailingListFilterSchema = UserFilterSchema;
 
 // ─── Mailing list ────────────────────────────────────────────────────────────
 
 export const MailingListSchema = object({
   name: string().required().min(1).max(120).label("Name"),
   description: string().optional().max(500).label("Description"),
-  filter: ListFilterSchema.default(() => ListFilterSchema.getDefault()),
+  filter: MailingListFilterSchema.default(() =>
+    MailingListFilterSchema.getDefault(),
+  ),
 }).label("Mailing List");
 
 // ─── 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.
+ * required only for that kind, so one stored shape covers them all.
  */
 export const CampaignTriggerSchema = object({
   kind: string()
@@ -445,52 +136,71 @@ export const CampaignTriggerSchema = object({
     .optional()
     .default(() => ({ kind: CampaignEndKind.Never }))
     .label("End Condition"),
+}).label("Trigger");
 
-  // 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(),
-    }),
+/**
+ * ONE data source a campaign draws content from: which source, how it is
+ * configured, and whether it personalises.
+ *
+ * Extracted so `CampaignSchema.dataSources` can hold several. A campaign used
+ * to store exactly one, which meant a template could never combine (say) jobs
+ * and groups in one mail.
+ */
+export const CampaignDataSourceSchema = object({
+  id: string().required().label("Data Source"),
   /**
-   * 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.
+   * Derive this source's filter per recipient from their profile, instead of
+   * using the admin-entered `params` for everyone.
+   *
+   * A second AXIS on a datasource, not a datasource of its own: a
+   * personalisation filter is an ordinary filter for that source, the only
+   * difference being who wrote it. Jobs previously shipped the two modes as
+   * two registry entries (`recent-jobs` / `matched-jobs`), which let them drift
+   * apart down to their output names.
+   *
+   * Optional, and absent reads as false, so every existing campaign stays
+   * un-personalised. Whether a source can honour it at all is declared by the
+   * source itself (`supportsPersonalisation`), which this package cannot see.
    */
-  windowDays: number()
-    .integer()
-    .min(1)
-    .max(90)
-    .optional()
-    .default(2)
-    .label("Eligibility Window (days)"),
-}).label("Trigger");
+  personalised: boolean().optional().label("Personalised"),
+  /**
+   * 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");
+  }),
+}).label("Data Source");
 
 /**
- * Where one template variable's value comes from. `value` carries the literal for
- * `static`/`url`, and the field path for `recipient`/`source`.
+ * Where ONE template variable's value comes from.
+ *
+ * `value` carries the literal for `static`/`url`, and the field path for
+ * `recipient`/`source`. Named for what it binds: "binding" alone says nothing
+ * about what is being bound to what.
  */
-export const BindingSchema = object({
-  kind: string().oneOf(SupportedBindingKinds).required().label("Source"),
+export const TemplateVariableBindingSchema = object({
+  kind: string()
+    .oneOf(SupportedTemplateVariableBindingKinds)
+    .required()
+    .label("Source"),
   value: string().required().min(1).max(2000).label("Value"),
-}).label("Binding");
+}).label("Template Variable Binding");
 
 export const CampaignSchema = object({
   name: string().required().min(1).max(200).label("Campaign Name"),
@@ -507,8 +217,8 @@ export const CampaignSchema = object({
   /**
    * 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,
+   * required. Scheduled 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()
@@ -521,6 +231,20 @@ export const CampaignSchema = object({
   text: string().optional().label("Plain-text Body"),
   listId: string().required().label("Mailing List"),
 
+  /**
+   * Where the campaign is in its life. See `CampaignStatus` for the transitions.
+   *
+   * Declared here so the enum is ENFORCED on write. It was previously written
+   * straight onto the document by the service with no schema behind it, and a
+   * value the enum never contained (`scheduled`) reached production rows and
+   * rendered in the admin list as though it were real.
+   */
+  status: string()
+    .oneOf(SupportedCampaignStatuses)
+    .optional()
+    .default(CampaignStatus.Draft)
+    .label("Status"),
+
   /** Key from email-service's template registry. Mutually exclusive with `html`. */
   templateKey: string().optional().label("Email Template"),
   /**
@@ -540,50 +264,41 @@ export const CampaignSchema = object({
   bindings: lazy((value: unknown) => {
     const keys = value && typeof value === "object" ? Object.keys(value) : [];
     return object(
-      Object.fromEntries(keys.map((k) => [k, BindingSchema.required()])),
+      Object.fromEntries(keys.map((k) => [k, TemplateVariableBindingSchema.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");
-    }),
-  })
+  /**
+   * The data sources this campaign draws content from.
+   *
+   * SEVERAL, because one mail may combine them. Each source's outputs are
+   * NAMESPACED by its id in the rendered payload (`jobs.jobCount`,
+   * `groups.groupCount`), so two sources providing the same name cannot
+   * overwrite each other and a template says which one it means.
+   */
+  dataSources: array()
+    .of(CampaignDataSourceSchema)
     .optional()
     .default(undefined)
-    .label("Data Source"),
+    .label("Data Sources"),
 
   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"),
+  /**
+   * Still TWO deliberate acts before mail leaves, as before: a campaign must be
+   * activated (`status: running`) AND taken out of dry run.
+   *
+   * The first half used to be a separate `enabled` boolean living alongside the
+   * status, which meant two fields encoding one idea and able to disagree — an
+   * `enabled: false` campaign whose status said it was sending was
+   * representable, and the admin list showed exactly that. Activation is a
+   * state transition, so it belongs in the state.
+   */
   dryRun: boolean().optional().default(true).label("Dry Run"),
   maxRecipients: number()
     .integer()

package/src/page/page-filter.schema.ts

@@ -0,0 +1,67 @@
+/**
+ * The page filter: the closed vocabulary of facets a page query can filter on.
+ *
+ * The counterpart of `GroupFilterSchema`; see that file for why an open
+ * `parseFilter` makes this declaration load-bearing rather than decorative.
+ *
+ * Every facet below was checked against production data before being declared.
+ * Three candidates that look filterable from `PageSchema` are deliberately
+ * ABSENT, because each would validate, save, render a form input, and match
+ * nothing:
+ *
+ *   • `pageType` — the stored key is `type` (see below).
+ *   • `categories` — declared as `array of string` in `PageSchema`, but actually
+ *     stored as `{ id, name }` OBJECTS. A string comparison never matches. A
+ *     `categories.name` dotted facet would probably work, but "probably" is how
+ *     a dead facet ships. @todo verify against live data, then add it.
+ *   • `industries` — present on 1 of 1,449 documents. Filtering on it excludes
+ *     99.9% of the corpus, which is a footgun rendered as a form input.
+ *
+ * `search`, `page`, `limit`, `sortBy`, `sortDirection` and `fields` are reserved
+ * query params, not facets, and are absent for that reason instead.
+ */
+import { boolean, object } from "yup";
+import { enumFacet, rejectUnknownKeys, tokens } from "../common/facet.schema.js";
+import {
+  SupportedPageStatuses,
+  SupportedPageTypes,
+} from "./page.constant.js";
+
+const PageFilterShape = object({
+  /**
+   * `type`, NOT `pageType`.
+   *
+   * The enum constant is named `PageType`, which makes `pageType` the obvious
+   * guess, and it is wrong: the stored key is `type` (verified — `pageType`
+   * exists on 0 of 1,449 documents, while `type` splits 1,198 company / 251
+   * institute). The name of a constant is not the name of a field.
+   */
+  type: enumFacet(SupportedPageTypes, "Page Type"),
+
+  /**
+   * Publication state. Worth knowing when filtering: 69 documents carry NO
+   * `status` at all and some carry `null`, so `status: ['published']` is a real
+   * narrowing (1,379 of 1,449) and absent means "no constraint", not "published".
+   */
+  status: enumFacet(SupportedPageStatuses, "Status"),
+
+  // ── Flags ───────────────────────────────────────────────────────────────────
+  // No `.default(false)`: absent means no constraint. Note `isFeatured` is
+  // present on only 55 documents, so combining it with `status: ['published']`
+  // leaves 11 pages — a legitimate filter that returns almost nothing.
+  isFeatured: boolean().optional().label("Featured Only"),
+
+  /** Lowercase (`in`, `se`, `ww`), like groups. See `GroupFilterSchema`. */
+  featuredMarkets: tokens("Featured Markets"),
+
+  /** Page SLUGS. A company is matched by slug: a display name breaks on rename. */
+  slugs: tokens("Slugs"),
+}).label("Page Filter");
+
+const PAGE_FILTER_KEYS = Object.keys(PageFilterShape.fields);
+
+/** THE page filter. See `GroupFilterSchema` for why unknown keys must fail loudly. */
+export const PageFilterSchema = rejectUnknownKeys(
+  PageFilterShape,
+  () => PAGE_FILTER_KEYS,
+);