@thejob/schema 2.1.8 → 2.2.0

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

@@ -0,0 +1,61 @@
+/**
+ * The skill filter: the closed vocabulary of facets a skill query can filter on.
+ *
+ * The counterpart of `PageFilterSchema` and `GroupFilterSchema`, for
+ * common-service's `GET /skills`. Same reason those exist: `parseFilter` there
+ * accepted ANY key and passed it straight to Mongo, so a misspelled or invented
+ * facet was not a narrower query — it was a query for a field no document has,
+ * returning 200 OK with zero rows and no error anywhere.
+ *
+ * Deliberately SMALL, and every facet below is a field `SkillSchema` actually
+ * declares rather than one that seemed plausible:
+ *
+ *   • `name`       — the display name, and the field the free-text search
+ *                    already matches on.
+ *   • `conceptIds` — the taxonomy concept a skill resolved to (stable slug,
+ *                    e.g. "power-bi"). The one facet with real query value:
+ *                    it groups every alias of a skill under one id.
+ *   • `tags`       — declared on `SkillSchema`, capped at 20 per document.
+ *
+ * ABSENT on purpose: `conceptName` (a display string for `conceptId`, so
+ * filtering on it is the same question asked less reliably) and `logo` (an
+ * object of URLs, not a value anyone filters by).
+ *
+ * The collection is EMPTY in both `thejob` and `thejob-dev` today, and the two
+ * live callers (`skill-field.svelte`, `language-field.svelte`) send only
+ * `search`, `fields` and `sortBy`. So this is not modelling observed queries —
+ * it exists so the service has a closed vocabulary like every other one, and so
+ * the first real facet is an addition to a declaration rather than a new
+ * mechanism. Add facets here when a caller needs one, against real data.
+ *
+ * `search`, `page`, `limit`, `sortBy`, `sortDirection` and `fields` are reserved
+ * query params, not facets, and are absent for that reason instead.
+ */
+import { object } from "yup";
+import { rejectUnknownKeys, tokens } from "../common/facet.schema.js";
+
+const SkillFilterShape = object({
+  /** Display names, matched exactly. Free-text matching is `?search=`. */
+  names: tokens("Names"),
+
+  /**
+   * Taxonomy concept ids, e.g. "power-bi".
+   *
+   * `tokens`, NOT `codeTokens`: a conceptId is a lowercase slug, and
+   * uppercasing it would match nothing.
+   */
+  conceptIds: tokens("Concept IDs"),
+
+  tags: tokens("Tags"),
+}).label("Skill Filter");
+
+/**
+ * Wrapped so an unknown key is REJECTED rather than silently ignored.
+ *
+ * Yup gives you unknown-key rejection or coercion, never both: `.noUnknown()`
+ * alone accepts `{bogus:1}`, and with `strict: true` it rejects but then throws
+ * on the string values every query param arrives as. Hence a `.test()`.
+ */
+export const SkillFilterSchema = rejectUnknownKeys(SkillFilterShape, () =>
+  Object.keys(SkillFilterShape.fields),
+);

package/src/user/general-detail.schema.ts

@@ -21,6 +21,13 @@ export const UserGeneralDetailSchema = object({
     .label("Name"),
   headline: string().trim().max(200).optional().label("Headline"),
   image: string().optional().label("Image"),
+  // The DISPLAYED avatar (`image`) is a flattened export with any status frame
+  // ("#OpenToWork", …) already burned into the pixels. `imageOriginal` keeps the
+  // un-framed source the user uploaded, so the image builder can reopen it and
+  // apply a DIFFERENT frame instead of stacking a second one on top of the first.
+  // Optional and absent on every pre-existing user: treat a missing value as
+  // "only the flattened image is available".
+  imageOriginal: string().optional().label("Original Image"),
   aboutMe: string().trim().max(3000).optional().label("About Me"),
   email: string()
     // .emailStrict() // TODO: Enable strict email validation.

package/src/user/push-subscription.schema.ts

@@ -0,0 +1,86 @@
+import { number, object, string } from "yup";
+
+/**
+ * A single browser's Web Push subscription.
+ *
+ * This is the DEVICE grant, distinct from `user.pushConsent`, which is the
+ * user's intent. Both are required to deliver: consent without a subscription
+ * has nowhere to send, and a subscription without consent must not be used.
+ *
+ * Shape dictated by the Push API, not by us. `endpoint` and `keys` come back
+ * verbatim from `PushSubscription.toJSON()` in the browser and are passed
+ * verbatim to the sender, so nothing here may be normalised or reformatted —
+ * `p256dh` and `auth` are base64url and case-sensitive.
+ *
+ * MANY per user, one per browser profile per device, which is why this is its
+ * own collection rather than a field on the user. The same person on a phone
+ * and a laptop is two rows, and both should receive.
+ */
+export const PushSubscriptionSchema = object({
+  /**
+   * The user this subscription belongs to, by the `shortId` every service
+   * keys a user on, matching `UserSchema.shortId`.
+   *
+   * NOT the Better Auth account id. That id is meaningful only inside the auth
+   * service, and owning these rows by one would force the service that sends
+   * push to translate an id it has no other use for. The signed-in browser
+   * gets its own shortId straight off the JWT claim.
+   *
+   * Named `userShortId` rather than `shortId` because a stored row has a
+   * `shortId` of its OWN (see `PushSubscriptionRecord`); one field cannot be
+   * both the row's id and its owner's.
+   */
+  userShortId: string().required().label("User Short ID"),
+
+  /**
+   * The push service URL the browser issued. Vendor-specific (FCM, Mozilla,
+   * Apple) and effectively unbounded in length, so it carries no length cap.
+   *
+   * This is the IDENTITY of a subscription: it is what a re-subscribing
+   * browser sends back unchanged, and what a 404/410 response identifies as
+   * dead. Upserts and deletes both key on it.
+   */
+  endpoint: string().required().label("Push Endpoint"),
+
+  /**
+   * Encryption material from the browser. Web Push payloads are encrypted to
+   * these keys, so a row missing either one cannot be delivered to at all.
+   */
+  keys: object({
+    /** Client public key, base64url. */
+    p256dh: string().required().label("P256DH Key"),
+    /** Client auth secret, base64url. */
+    auth: string().required().label("Auth Secret"),
+  })
+    .required()
+    .label("Push Keys"),
+
+  /**
+   * Epoch ms the push service says the subscription expires, when it says
+   * anything at all. Usually absent — most browsers return null — so this is
+   * informational and never the basis for pruning. A 404/410 on send is the
+   * only reliable death signal.
+   */
+  expirationTime: number().nullable().optional().label("Expiration Time"),
+
+  /**
+   * The subscribing browser's user agent, kept so a user can recognise their
+   * own devices in a "where you receive notifications" list. Display only:
+   * never parsed, and never used to decide delivery.
+   */
+  userAgent: string().optional().label("User Agent"),
+
+  /** Epoch ms the subscription was first registered. */
+  createdAt: number().optional().label("Created At"),
+
+  /**
+   * Epoch ms this subscription was last confirmed live, refreshed when the
+   * browser re-registers it. A subscription that stops being refreshed is a
+   * device that stopped visiting, which is useful for pruning rows that never
+   * fail loudly enough to be caught by a 410.
+   */
+  lastSeenAt: number().optional().label("Last Seen At"),
+})
+  .noUnknown()
+  .strict()
+  .label("Push Subscription Schema");

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

@@ -0,0 +1,438 @@
+/**
+ * The user filter: the closed vocabulary of facets a user query can filter on.
+ *
+ * Lives HERE, with the user module, because it describes USERS. It sat in
+ * `marketing/` for as long as marketing was its only caller, which made it look
+ * like a marketing concept; it is not. `thejob-user-service` derives the
+ * vocabulary it validates against from this schema, and `@thejob/users-client`
+ * derives its `UserFilter` type from it, so this is the single declaration all
+ * three agree on. A mailing list merely STORES one
+ * (`MailingListSchema.filter`).
+ *
+ * `search` is deliberately absent. It is free text over name/email: it names no
+ * field on a user document, it cannot be meaningfully unioned inside an `or`
+ * branch, and user-service treats it as a reserved param beside the filter. See
+ * `ListUsersOptions` in `@thejob/users-client`.
+ */
+import { array, boolean, number, object, string } from "yup";
+import {
+  conjunction,
+  currencyBound,
+  days,
+  enumFacet,
+  epoch,
+  months,
+  percent,
+  qualified,
+  rejectUnknownKeys,
+  tokens,
+} from "../common/facet.schema.js";
+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,
+  SupportedNotificationTypes,
+  SupportedProficiencyLevels,
+  SupportedReferralSources,
+  SupportedSalaryCurrencies,
+  SupportedSignupContextSources,
+  SupportedUserProfileVisibilities,
+  SupportedUserRoles,
+  SupportedUserStatuses,
+} from "./user.constant.js";
+
+// 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.
+
+
+/**
+ * Every clause except `or`. Declared separately so `UserFilterSchema` can embed
+ * it as its branch type without referring to itself: the union is deliberately
+ * one level deep, and a non-recursive definition enforces that.
+ *
+ * INTERNAL. Not exported: it is scaffolding for the two schemas below, and the
+ * only filter a consumer should reach for is `UserFilterSchema`.
+ */
+const UserFilterBranchShape = object({
+  /**
+   * Exact email addresses. An IDENTITY lookup, not a search.
+   *
+   * The admin `search` box already matches email, but as a case-insensitive
+   * unanchored regex over email + first + last, which no index can seek: it
+   * scans every key. Measured against 103,680 users, finding one person by
+   * their full address examined all 103,680 documents and took 552ms, where the
+   * same lookup as an exact match on the indexed `email` field is 0ms and
+   * examines 1.
+   *
+   * So this is for when the caller ALREADY KNOWS the address (previewing what
+   * one named recipient will receive, reconciling a bounce) and `search` is for
+   * when a human is typing a fragment.
+   *
+   * Values are LOWER-CASED before matching, not matched case-insensitively: all
+   * 103,680 stored addresses are already lower case (verified), so normalising
+   * the input keeps the match an indexed equality instead of a regex that would
+   * put the scan straight back.
+   */
+  emails: array().of(string().required()).optional().default([]).label("Email Addresses"),
+  /**
+   * Better Auth account ids. An IDENTITY lookup like `emails`, and for the same
+   * reason: the caller already knows the exact value.
+   *
+   * BACKEND-ONLY, despite living beside the human-facing facets. The consumer
+   * is hono-auth, which holds an account id and needs the profile's `shortId`
+   * to sign into the JWT it is minting. It cannot use `GET /me` (it is the one
+   * issuing the token) and cannot use `GET /users/:shortId` (the shortId is
+   * precisely what it lacks), so the list route with a facet is the lookup.
+   *
+   * Matched as an indexed equality on `authAccountId`, which is already indexed
+   * as the mirror's link key. No case normalisation, unlike `emails`: these are
+   * opaque generated ids, stored exactly as Better Auth issued them, so folding
+   * case could only ever turn a hit into a miss.
+   *
+   * The admin filter panel builds its controls explicitly rather than from this
+   * shape, so declaring it here does not put an account-id box in the UI.
+   */
+  authAccountIds: array().of(string().required()).optional().default([]).label("Auth Account IDs"),
+  // ── 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",
+  ),
+  // Mode of any education entry (educations[].studyType).
+  //
+  // Left as a STANDALONE enum, unlike skill/language proficiency above: it is a
+  // property of a person's education in general ("studied full time"), and the
+  // measured divergence against pairing it with `courses` was 1 user out of
+  // 3,465. Pairing is for qualifiers that are MEANINGLESS alone; this one is
+  // not, so it stays cheap to use.
+  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) ──────────────────────────
+  // Skill and language each carry their OWN proficiency, because a level is
+  // only meaningful attached to the thing it qualifies. See `qualified`:
+  // as two independent facets, "python + expert" returned 301 users where only
+  // 103 were actually expert at Python.
+  //
+  // `[{ name: 'python', proficiencyLevel: 'expert' }]` — the level is optional,
+  // so naming a skill without one still filters on the skill alone.
+  skills: qualified(SupportedProficiencyLevels, "proficiencyLevel", "Skills"),
+  languages: qualified(SupportedProficiencyLevels, "proficiencyLevel", "Languages"),
+  interests: tokens("Interests"),
+
+  // LOOSE forms, kept deliberately. Each of these is a real question on its own
+  // ("worked at Google", "was an engineer somewhere"), and asking for two of
+  // them usually does mean "has each of these somewhere in their history".
+  // They AND across the whole array, so different entries may satisfy each.
+  //
+  // `companyName` / `instituteName`, NOT the `company` widget the job filter
+  // uses. Both are PICKED from real pages — a profile stores the whole
+  // `PageSchema.pick(["name","slug","type","logo"])` object, not free text — but
+  // the facet matches `workExperiences.company.name`, so the value to store is
+  // the page's NAME. Storing its slug would be a picker that matches nothing.
+  companies: tokens("Companies").meta({ widget: "companyName" }),
+  designations: tokens("Job Titles / Designations"),
+  institutes: tokens("Institutes").meta({ widget: "instituteName" }),
+  courses: tokens("Courses"),
+  fieldsOfStudy: tokens("Fields of Study"),
+
+  // PRECISE forms: all parts must describe ONE entry.
+  //
+  // The narrower question the loose facets above cannot express. "Engineer AT
+  // Google" as `companies=Google & designations=engineer` also matches someone
+  // who was an engineer at Acme and a designer at Google, because Mongo
+  // satisfies each path from a different array entry. Measured on production:
+  // VIT + B.Tech returned 71 users where 64 had one education entry that was
+  // both, and Infosys + Test Engineer returned 7 where 6 actually matched.
+  //
+  // Additive rather than a replacement: both readings are legitimate, so the
+  // vocabulary carries both and the caller says which it means. 1,573 users
+  // have two or more work entries and 1,761 have two or more educations, so the
+  // distinction is real and grows as profiles fill in.
+  //
+  // The fields mirror what the profile form actually collects for one entry
+  // (`WorkExperienceSchema` / `EducationSchema`), minus the parts that cannot
+  // narrow an audience: `description` is prose, and a per-entry `location`
+  // duplicates the top-level geography facets against a much emptier path.
+  //
+  // `isCurrent` reads `duration.isActive`, which is what the profile form calls
+  // "I currently work here". It is the field that makes this facet worth having
+  // per entry: "engineer at Google" and "engineer at Google NOW" are different
+  // audiences, and only the second is reachable without it. Live counts:
+  // 2,190 users have a current job against 4,527 with a past one, 1,456 have a
+  // remote entry, 4,088 are still studying.
+  workHistory: conjunction(
+    [
+      "company",
+      "designation",
+      { name: "isCurrent", type: "boolean" },
+      { name: "isRemote", type: "boolean" },
+    ],
+    "Work History",
+  ),
+  educationHistory: conjunction(
+    [
+      "institute",
+      "course",
+      "fieldOfStudy",
+      { name: "studyType", type: "string", oneOf: SupportedStudyTypes },
+      { name: "isCurrent", type: "boolean" },
+      { name: "isDistanceLearning", type: "boolean" },
+    ],
+    "Education History",
+  ),
+  // The issuing body belongs to the certificate, not to the person: "AWS SA"
+  // plus "Microsoft" as two facets matches someone holding an AWS cert AND any
+  // unrelated Microsoft one. 38% of users with a certification hold two or more,
+  // so the entries are there to diverge.
+  //
+  // `authority` is free text rather than a closed vocabulary, hence `"open"`.
+  certifications: qualified("open", "authority", "Certifications"),
+  projects: tokens("Projects"),
+  jobRoles: tokens("Target Roles"),
+  jobLocations: tokens("Preferred Job Locations"),
+  // Companies a recruiter is hiring for (recruiterProfile.hiringFor[].page.name).
+  // A picked page (`recruiterProfile.hiringFor.page`), matched on `.name`.
+  //
+  // `pageName`, which searches BOTH page types: `RecruiterPageLinkSchema` picks
+  // `PageSchema` without constraining `type`, so a recruiter may be hiring for
+  // an institute as legitimately as for a company. Production carries exactly
+  // that on the coordinator side — a `coordinatesAt` entry holding a company —
+  // so scoping either of these to one type would hide real data.
+  hiringForCompanies: tokens("Hiring For").meta({ widget: "pageName" }),
+  // Institutes a coordinator works at (coordinatorProfile.coordinatesAt[].page.name).
+  // Same: a picked page (`coordinatorProfile.coordinatesAt.page`), on `.name`,
+  // and likewise unconstrained in `type`.
+  coordinatesAtInstitutes: tokens("Coordinates At").meta({ widget: "pageName" }),
+  // 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.
+  // The sibling currency facet is named explicitly: this bound is inert without
+  // it, so the dependency is stated rather than assumed.
+  minSalaryFloor: currencyBound("Min Salary ≥", "salaryCurrencies"),
+  minSalaryCeil: currencyBound("Min Salary ≤", "salaryCurrencies"),
+  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 ────────────────────────────────────────────────────────
+  // `marketingSubscribed` IS a facet, and deliberately so. It used to be a hard
+  // opt-in gate applied unconditionally by user-service; that gate was removed
+  // when user-service became a pure data source, so consent is now an ordinary
+  // filter that marketing-service defaults to `true` in `resolveAudience`.
+  //
+  // NO `.default()` HERE, unlike every other boolean facet. The send spreads its
+  // default first and lets a stored value win, so this must distinguish "the
+  // list said nothing" (absent -> default applies) from "the list said false"
+  // (override -> mails users who never opted in). A `.default(false)` would
+  // materialise the second case on every list that never chose it.
+  //
+  // @todo CONSENT-FILTER-ENFORCEMENT — nothing enforces consent anywhere now.
+  marketingSubscribed: boolean().optional().label("Marketing Subscribed"),
+  jobAlertFrequencies: enumFacet(
+    SupportedJobAlertFrequencies,
+    "Job Alert Frequency",
+  ),
+  consentSources: tokens("Consent Source"),
+  consentUpdatedWithinDays: days("Consent Updated Within (days)"),
+  /** The absolute bound `consentUpdatedWithinDays` resolves into (epoch ms). */
+  consentUpdatedAfter: epoch("Consent Updated After"),
+
+  // ── 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(
+    SupportedNotificationTypes,
+    "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)"),
+
+  // The ABSOLUTE bounds the three relative windows above resolve into
+  // (`graduatedWithinMonths` -> `graduatedAfter`, and so on). Both forms are
+  // accepted: a caller may send either, and user-service derives the bound when
+  // only the window is given.
+  //
+  // A UI should offer the WINDOW, not these. A saved list is re-resolved on
+  // every send, so a stored absolute date rots — "graduated after 2024-03" keeps
+  // meaning that forever, while "within 18 months" keeps meaning what the admin
+  // intended. They are declared because the vocabulary must be complete, not
+  // because a list should store one.
+  graduatedAfter: string().trim().optional().label("Graduated After"),
+  skillUsedAfter: string().trim().optional().label("Skill Used After"),
+
+  // ── 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)"),
+
+  // `search` is NOT here. It is free text over name/email, not a facet: it names
+  // no field on a user document, user-service treats it as a RESERVED PARAM
+  // beside the filter rather than a filter key, and it is meaningless inside an
+  // `or` branch (a union of "matches this text" with a facet clause). It travels
+  // as a sibling of the filter — see `PreviewFilterSchema` in marketing-service —
+  // so a saved audience cannot carry free text it would silently re-run later.
+})
+  .label("Audience Filter Branch");
+
+const BRANCH_KEYS = Object.keys(UserFilterBranchShape.fields);
+
+/**
+ * One branch of `or`: every clause except `or` itself, so unions cannot nest.
+ *
+ * INTERNAL, for the same reason as the shape above — a consumer validates a
+ * whole filter, never a lone branch.
+ */
+const UserFilterBranch = rejectUnknownKeys(UserFilterBranchShape, () => BRANCH_KEYS);
+
+/**
+ * THE user filter. One declaration, three derived uses:
+ *
+ * - `@thejob/users-client` derives its `UserFilter` type with `InferType`.
+ * - `thejob-user-service` derives `USER_FILTER_FACETS` with
+ *   `Object.keys(UserFilterSchema.fields)` — the closed vocabulary it 400s
+ *   against.
+ * - `MailingListSchema.filter` stores one, as does the audience preview.
+ *
+ * It was previously written out three times: a yup schema here, a hand-written
+ * TS interface in the client, and a hand-listed `Set` of ~74 strings in the
+ * service. Three lists of the same names drift, and the drift is invisible — a
+ * facet the schema accepts but the service does not is a 400 on a send that
+ * validated cleanly when it was saved.
+ *
+ * A FILTER, not an audience: it says which users match and nothing about what a
+ * caller intends to do with them. Marketing narrows it one way, an admin list
+ * another, and neither meaning belongs here.
+ *
+ * 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, which the non-recursive definition above enforces.
+ */
+export const UserFilterSchema = rejectUnknownKeys(
+  UserFilterBranchShape.shape({
+    or: array().of(UserFilterBranch).optional().default([]).label("Or Any Of"),
+  }).label("User Filter"),
+  () => [...BRANCH_KEYS, "or"],
+);

package/src/user/user-interest.schema.ts

@@ -1,3 +1,35 @@
-import { string } from "yup";
+import { object, string } from "yup";
 
-export const UserInterestSchema = string().trim().required().label("Interest");
+/**
+ * One interest on a user profile, as a REFERENCE to a taxonomy entry.
+ *
+ * This was declared as a bare `string()` and that was simply wrong about the
+ * data: a full census of the live users collection found 41,822 interest
+ * entries, 100% of them objects, with `id`, `name` and `logo` present on every
+ * single one. Not one string.
+ *
+ * The damage was silent and reached the UI. Because the schema said `string`,
+ * every type derived from it said `string[]`, so an admin panel rendering
+ * `{interest}` type-checked cleanly and printed `[object Object]` to the
+ * operator. The public profile page had already worked around it by declaring
+ * its own local `Interest` interface with the real shape, which is how a wrong
+ * declaration survives: each consumer patches around it privately instead of
+ * one fix at the source.
+ *
+ * `logo` is a material-symbols icon NAME (`cloud`, `code`, `psychology`), not a
+ * URL or a storage key, so it is rendered as an icon rather than fetched.
+ *
+ * Every field is required because the data says so: there is no partial entry
+ * among the 41,822, and these are written by picking an existing taxonomy
+ * entry rather than typed free-hand.
+ */
+export const UserInterestSchema = object({
+  /** The taxonomy entry's id. */
+  id: string().trim().required().label("Interest Id"),
+  /** Display name, e.g. "Cloud Computing". */
+  name: string().trim().required().label("Interest"),
+  /** Material-symbols icon name, e.g. "cloud". */
+  logo: string().trim().required().label("Interest Logo"),
+})
+  .required()
+  .label("Interest");