@thejob/schema 2.1.8 → 2.2.0

package/src/geo/country.schema.ts

@@ -0,0 +1,148 @@
+import { array, number, object, string } from "yup";
+import type { InferType } from "yup";
+
+/**
+ * A country in the geo reference mirror, backing `GET /geo/countries`.
+ *
+ * Sourced from dr5hn/countries-states-cities-database and refreshed wholesale by
+ * common-service. The upstream record is kept WHOLE — `translations`, `timezones`,
+ * `gdp`, `emoji` and all — and callers narrow with `?fields=` instead. Storing a
+ * projection would mean a re-ingest of 150k+ records every time someone wanted a
+ * field we had decided in advance nobody needed.
+ *
+ * Two deliberate departures from the house style for record schemas:
+ *
+ *   • NOT `.noUnknown().strict()`. `SkillSchema` is strict because it validates
+ *     user INPUT; this types a STORED shape whose upstream fields we keep
+ *     wholesale, so strict mode would reject documents the ingest legitimately
+ *     writes the moment dr5hn adds a column.
+ *   • NOT `.concat(DbDefaultSchema)`. These records have no `shortId` or
+ *     `createdBy` — nobody authors them. They carry the upstream `id` (which is
+ *     also the upsert key) plus our own `syncedAt`.
+ *
+ * Almost everything is nullable because the dataset genuinely has holes:
+ * `capital`, `gdp` and `postalCodeRegex` are absent on many rows. Only the
+ * identity fields are required.
+ */
+export const CountrySchema = object({
+  /** The upstream dr5hn id. Stable, and the key every upsert matches on. */
+  id: number().integer().required().label("ID"),
+
+  name: string().trim().required().label("Name"),
+
+  /**
+   * ISO 3166-1 alpha-2, UPPERCASE (`IN`, `SE`).
+   *
+   * Uppercased on ingest, because every filter facet in this package
+   * uppercase-normalizes codes (`codeTokens`) and stored job/user documents are
+   * already clean uppercase alpha-2. A lowercase value here would compare
+   * unequal to all of them and silently match nothing.
+   */
+  countryCode: string().trim().uppercase().length(2).required().label("Country Code"),
+
+  iso3: string().trim().uppercase().length(3).optional().nullable().label("ISO3"),
+  numericCode: string().trim().optional().nullable().label("Numeric Code"),
+  phonecode: string().trim().optional().nullable().label("Phone Code"),
+  capital: string().trim().optional().nullable().label("Capital"),
+  currency: string().trim().optional().nullable().label("Currency"),
+  currencyName: string().trim().optional().nullable().label("Currency Name"),
+  currencySymbol: string().trim().optional().nullable().label("Currency Symbol"),
+  tld: string().trim().optional().nullable().label("TLD"),
+
+  /** The name in its own script, e.g. "भारत". Stored, but NOT searchable; see `searchByLocale`. */
+  native: string().trim().optional().nullable().label("Native Name"),
+
+  population: number().optional().nullable().label("Population"),
+  gdp: number().optional().nullable().label("GDP"),
+  region: string().trim().optional().nullable().label("Region"),
+  regionId: number().integer().optional().nullable().label("Region ID"),
+  subregion: string().trim().optional().nullable().label("Subregion"),
+  subregionId: number().integer().optional().nullable().label("Subregion ID"),
+  nationality: string().trim().optional().nullable().label("Nationality"),
+  areaSqKm: number().optional().nullable().label("Area (sq km)"),
+  postalCodeFormat: string().trim().optional().nullable().label("Postal Code Format"),
+  postalCodeRegex: string().optional().nullable().label("Postal Code Regex"),
+
+  timezones: array()
+    .of(
+      object({
+        zoneName: string().optional().nullable().label("Zone Name"),
+        gmtOffset: number().optional().nullable().label("GMT Offset"),
+        gmtOffsetName: string().optional().nullable().label("GMT Offset Name"),
+        abbreviation: string().optional().nullable().label("Abbreviation"),
+        tzName: string().optional().nullable().label("TZ Name"),
+      }),
+    )
+    .optional()
+    .nullable()
+    .label("Timezones"),
+
+  /**
+   * Localized names keyed by locale (`{ sv: "Indien", fr: "Inde", … }`), ~19 of
+   * them. Deliberately UNSHAPED: the key set is upstream's to change, and
+   * declaring it here would turn a new locale into a validation failure. The
+   * VALUES are split per-locale into `searchByLocale`.
+   */
+  translations: object().optional().nullable().label("Translations"),
+
+  /**
+   * Coordinates as NUMBERS.
+   *
+   * Upstream ships these as strings (`"33.00000000"`). They are coerced on
+   * ingest, because a range query against a string compares lexicographically:
+   * `"9" > "10"` is true, so a bounding-box filter would be quietly wrong rather
+   * than failing loudly.
+   */
+  latitude: number().optional().nullable().label("Latitude"),
+  longitude: number().optional().nullable().label("Longitude"),
+
+  emoji: string().optional().nullable().label("Emoji"),
+  emojiU: string().optional().nullable().label("Emoji Unicode"),
+
+  /**
+   * The name field searched for the DEFAULT (English) locale: the canonical
+   * `name`, and nothing else.
+   *
+   * Search is scoped to ONE locale, so the searchable names are split across
+   * this field and `searchByLocale` rather than pooled into one array. A pooled
+   * field would make every locale's search implicitly a search of all 19
+   * languages: a French UI searching "Inde" would also match German "Indien".
+   */
+  searchDefault: array().of(string().required()).optional().default([]).label("Search Default"),
+
+  /**
+   * Per-locale name fields, keyed by lowercased BCP-47 tag (`de`, `pt-br`).
+   * Each carries ONLY that locale's translation, which is what makes
+   * `?locale=de` German and not "German plus everything that looks similar".
+   *
+   * Unshaped for the same reason as `translations`: the key set is upstream's.
+   *
+   * `native` is deliberately NOT indexed here. It cannot be attributed to a
+   * language with this data — 84% of city native names equal SEVERAL locales'
+   * translations (Latin spellings coinciding across de/it/nl/hr/pl) while
+   * distinctive non-Latin names like `भारत` match none — so filing `कर्नाटक`
+   * under German would be worse than not indexing it at all.
+   *
+   * The 19 upstream locales are br, ko, pt-BR, pt, nl, hr, fa, de, es, fr, ja,
+   * it, zh-CN, tr, ru, uk, pl, hi, ar. **`sv` is absent**, so a Swedish search
+   * matches nothing. That is the accepted cost of strict scoping.
+   */
+  searchByLocale: object().optional().nullable().label("Search By Locale"),
+
+  /** Epoch ms of the run that last wrote this row. Drives the stale-row prune. */
+  syncedAt: number().optional().nullable().label("Synced At"),
+}).label("Country");
+
+export type Country = InferType<typeof CountrySchema>;
+
+/** A single entry of `CountrySchema.timezones`. */
+export type CountryTimezone = NonNullable<Country["timezones"]>[number];
+
+/**
+ * The localized-name map, keyed by locale.
+ *
+ * Declared as a type rather than a yup shape for the reason given on
+ * `translations` above: the key set belongs to upstream. Shared by all three
+ * geo record types.
+ */
+export type GeoTranslations = Record<string, string>;

package/src/geo/geo-sync.schema.ts

@@ -0,0 +1,116 @@
+import { boolean, mixed, number, object, string } from "yup";
+import type { InferType } from "yup";
+import {
+  GeoSyncPhase,
+  GeoSyncStatus,
+  GeoSyncTrigger,
+  SupportedGeoSyncPhases,
+  SupportedGeoSyncStatuses,
+  SupportedGeoSyncTriggers,
+} from "./geo.constant.js";
+
+/**
+ * Per-collection tally of one ingest pass.
+ *
+ * `upserted` vs `modified` is the assertion worth reading: a re-run over
+ * unchanged upstream data must be ALL `modified` and ZERO `upserted`. Any
+ * `upserted` on a second run means the `id`-keyed upsert is not matching, and
+ * the collection is quietly accumulating duplicates.
+ */
+const GeoSyncCountsSchema = object({
+  read: number().integer().min(0).default(0).label("Read"),
+  upserted: number().integer().min(0).default(0).label("Upserted"),
+  modified: number().integer().min(0).default(0).label("Modified"),
+  matched: number().integer().min(0).default(0).label("Matched"),
+  /** Rows removed because upstream dropped them. See `prunedSkipped`. */
+  pruned: number().integer().min(0).default(0).label("Pruned"),
+  /**
+   * True when the stale-row prune was REFUSED because it would have removed more
+   * than its safety threshold of the collection. A partial fetch that looked
+   * like a success must not be able to empty the table, so the run reports the
+   * refusal rather than acting on it.
+   */
+  prunedSkipped: boolean().default(false).label("Prune Skipped"),
+}).label("Sync Counts");
+
+/**
+ * One run of the geo refresh job, as stored in `geo_sync_runs` and returned by
+ * `GET /geo/refresh/status`.
+ *
+ * The run document is the ONLY shared state between the job and the status
+ * endpoint: the job writes phase and progress onto it, the dashboard polls it.
+ * Nothing reaches into the job's memory, which is what lets the job be a plain
+ * in-process async function rather than a queue.
+ */
+export const GeoSyncRunSchema = object({
+  jobId: string().required().label("Job ID"),
+
+  status: mixed<GeoSyncStatus>()
+    .oneOf(SupportedGeoSyncStatuses)
+    .required()
+    .label("Status"),
+
+  trigger: mixed<GeoSyncTrigger>()
+    .oneOf(SupportedGeoSyncTriggers)
+    .optional()
+    .label("Trigger"),
+
+  /** Whether the caller asked to run even though the release tag was unchanged. */
+  force: boolean().default(false).label("Force"),
+
+  /**
+   * The upstream release tag this run fetched, e.g. `v3.2-export.7`.
+   *
+   * Null only when the tag could not be read AND `force` was set — a run that
+   * cannot tell what version it is fetching is otherwise a failure, not a
+   * refresh, so it is not allowed to proceed unattended.
+   */
+  releaseTag: string().optional().nullable().label("Release Tag"),
+
+  /** The tag of the last successful run, i.e. what this one is replacing. */
+  previousReleaseTag: string().optional().nullable().label("Previous Release Tag"),
+
+  startedAt: number().required().label("Started At"),
+  finishedAt: number().optional().nullable().label("Finished At"),
+  durationMs: number().optional().nullable().label("Duration (ms)"),
+
+  phase: mixed<GeoSyncPhase>()
+    .oneOf(SupportedGeoSyncPhases)
+    .optional()
+    .nullable()
+    .label("Phase"),
+
+  /**
+   * Live progress for the dashboard bar.
+   *
+   * `total` is an ESTIMATE — the previous successful run's count for the same
+   * collection, or a hardcoded fallback on the very first run, since the true
+   * total is not known until the stream ends. The UI should render it as one.
+   */
+  progress: object({
+    collection: string().optional().nullable().label("Collection"),
+    processed: number().integer().min(0).default(0).label("Processed"),
+    total: number().integer().min(0).optional().nullable().label("Total"),
+  })
+    .optional()
+    .nullable()
+    .label("Progress"),
+
+  counts: object({
+    countries: GeoSyncCountsSchema.optional().nullable().label("Countries"),
+    states: GeoSyncCountsSchema.optional().nullable().label("States"),
+    cities: GeoSyncCountsSchema.optional().nullable().label("Cities"),
+  })
+    .optional()
+    .nullable()
+    .label("Counts"),
+
+  /** Why a `skipped` run was skipped, in words the dashboard can show verbatim. */
+  reason: string().optional().nullable().label("Reason"),
+
+  /** The failure message on a `failed` run. Surfaced verbatim to the admin. */
+  error: string().optional().nullable().label("Error"),
+}).label("Geo Sync Run");
+
+export type GeoSyncRun = InferType<typeof GeoSyncRunSchema>;
+export type GeoSyncCounts = InferType<typeof GeoSyncCountsSchema>;

package/src/geo/geo.constant.ts

@@ -0,0 +1,78 @@
+/**
+ * Constants for the geo reference data (countries / states / cities).
+ *
+ * The data is a MIRROR of the dr5hn/countries-states-cities-database, refreshed
+ * wholesale by common-service rather than authored here. That is why these are
+ * sync/administrative vocabularies: the records themselves have no lifecycle of
+ * their own, only the job that replaces them does.
+ */
+
+/** Which level of the hierarchy a combined `/geo/search` hit came from. */
+export enum GeoKind {
+  Country = "country",
+  State = "state",
+  City = "city",
+}
+
+export const SupportedGeoKinds = Object.values(GeoKind);
+
+/**
+ * The state machine of one geo refresh run.
+ *
+ * `Skipped` is a SUCCESS, not a failure: the upstream release tag had not
+ * changed, so there was nothing to fetch. Keeping it distinct from `Succeeded`
+ * is what lets the admin dashboard say "already up to date" instead of showing
+ * a progress bar that completes instantly and implies work happened.
+ */
+export enum GeoSyncStatus {
+  Pending = "pending",
+  Running = "running",
+  Succeeded = "succeeded",
+  Failed = "failed",
+  Skipped = "skipped",
+}
+
+export const SupportedGeoSyncStatuses = Object.values(GeoSyncStatus);
+
+/** Terminal states. A run in any other state is still in flight. */
+export const TerminalGeoSyncStatuses = [
+  GeoSyncStatus.Succeeded,
+  GeoSyncStatus.Failed,
+  GeoSyncStatus.Skipped,
+] as const;
+
+/** Which phase a running job is in, for the progress display. */
+export enum GeoSyncPhase {
+  Checking = "checking",
+  Countries = "countries",
+  States = "states",
+  Cities = "cities",
+  Indexing = "indexing",
+  Done = "done",
+}
+
+export const SupportedGeoSyncPhases = Object.values(GeoSyncPhase);
+
+/** What triggered a run. `Boot` is reserved; today every run is `Manual`. */
+export enum GeoSyncTrigger {
+  Manual = "manual",
+  Boot = "boot",
+}
+
+export const SupportedGeoSyncTriggers = Object.values(GeoSyncTrigger);
+
+/** Mongo collection names, so service and consumers cannot disagree on them. */
+export const GEO_COLLECTIONS = {
+  countries: "geo_countries",
+  states: "geo_states",
+  cities: "geo_cities",
+  syncRuns: "geo_sync_runs",
+} as const;
+
+/**
+ * Max length of a `?search=` term on any `/geo` endpoint.
+ *
+ * Bounded because the term reaches an Atlas `$search` autocomplete clause, and
+ * an unbounded one is a needlessly expensive query for input no human types.
+ */
+export const GEO_SEARCH_MAX = 64;

package/src/geo/state-filter.schema.ts

@@ -0,0 +1,57 @@
+/**
+ * The state filter: the closed vocabulary of facets the state endpoints read.
+ *
+ * Shared by BOTH shapes of the same query, which is why `countryCodes` is
+ * declared here rather than assumed:
+ *
+ *   • `GET /geo/countries/:countryCode/states` — the cascade. The country is a
+ *     PATH param, folded into this filter by the route.
+ *   • `GET /geo/states?search=kar&countryCode=IN` — the flat search, for a user
+ *     who knows "Karnataka" but not which country it is in. Here `countryCodes`
+ *     is an optional narrowing facet.
+ *
+ * One vocabulary for both means the two cannot drift into accepting different
+ * things. The route rejects a path code that DISAGREES with a facet code rather
+ * than silently letting one win.
+ *
+ * `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 { codeTokens, rejectUnknownKeys, tokens } from "../common/facet.schema.js";
+
+const StateFilterShape = object({
+  /** ISO 3166-1 alpha-2 of the parent country, e.g. `IN`. */
+  countryCodes: codeTokens("Country Codes"),
+
+  /**
+   * BARE subdivision codes, e.g. `KA`.
+   *
+   * `@todo STATE-CODE-ISO-PREFIX` — not globally unique, so this facet ALONE is
+   * an ambiguous question: `stateCodes[0]=BDS` matches Badakhshan in Afghanistan
+   * and every other `BDS` elsewhere. Pair it with `countryCodes` to mean one
+   * place. See `StateSchema.stateCode`.
+   */
+  stateCodes: codeTokens("State Codes"),
+
+  /** Display names, matched exactly. Free-text matching is `?search=`. */
+  names: tokens("Names"),
+
+  /**
+   * Upstream's own subdivision word: "province", "state", "district", …
+   *
+   * `tokens`, NOT `codeTokens`: these are lowercase display strings and
+   * uppercasing them would match nothing. An OPEN vocabulary rather than an
+   * `enumFacet`, because upstream ships 30-odd values and adding one should not
+   * require a schema release here.
+   */
+  types: tokens("Types"),
+}).label("State Filter");
+
+/**
+ * Wrapped so an unknown key is REJECTED rather than silently ignored. See
+ * `SkillFilterSchema` for why this is a `.test()` and not `.noUnknown()`.
+ */
+export const StateFilterSchema = rejectUnknownKeys(StateFilterShape, () =>
+  Object.keys(StateFilterShape.fields),
+);

package/src/geo/state.schema.ts

@@ -0,0 +1,101 @@
+import { array, number, object, string } from "yup";
+import type { InferType } from "yup";
+
+/**
+ * A state / province / subdivision in the geo reference mirror, backing
+ * `GET /geo/countries/:countryCode/states` and `GET /geo/states`.
+ *
+ * Sourced from dr5hn and refreshed wholesale; the upstream record is kept whole.
+ * See `CountrySchema` for why this is neither `.strict()` nor concatenated with
+ * `DbDefaultSchema`.
+ *
+ * The parent country's `countryCode` and `countryName` are stored DENORMALIZED,
+ * as upstream ships them. That is deliberate: a flat search hit ("Karnataka")
+ * has to be enough for a UI to back-fill the country dropdown to India without a
+ * second round trip, which is the whole point of searching states without first
+ * picking a country.
+ */
+export const StateSchema = object({
+  /** The upstream dr5hn id. Stable, and the key every upsert matches on. */
+  id: number().integer().required().label("ID"),
+
+  name: string().trim().required().label("Name"),
+
+  countryId: number().integer().optional().nullable().label("Country ID"),
+
+  /** ISO 3166-1 alpha-2 of the parent, UPPERCASE. See `CountrySchema.countryCode`. */
+  countryCode: string().trim().uppercase().length(2).required().label("Country Code"),
+
+  countryName: string().trim().optional().nullable().label("Country Name"),
+
+  /**
+   * The BARE subdivision code, e.g. `KA` (upstream `iso2`).
+   *
+   * `@todo STATE-CODE-ISO-PREFIX` — this is **not globally unique**: `BDS`, `CA`,
+   * `NL` and `SP` all recur across several countries, so it is only meaningful
+   * PAIRED with `countryCode`. That is why the cities route is nested under both
+   * codes rather than under a state code alone, which would silently serve
+   * another country's cities. `stateCodeIso` below is the migration target;
+   * both are stored so the migration has its destination present before any
+   * consumer moves.
+   */
+  stateCode: string().trim().uppercase().optional().nullable().label("State Code"),
+
+  /** Fully-qualified ISO 3166-2, e.g. `IN-KA` (upstream `iso3166_2`). */
+  stateCodeIso: string().trim().uppercase().optional().nullable().label("ISO 3166-2 Code"),
+
+  fipsCode: string().trim().optional().nullable().label("FIPS Code"),
+
+  /** Upstream's own word for the subdivision: "province", "state", "district", … */
+  type: string().trim().optional().nullable().label("Type"),
+
+  level: number().integer().optional().nullable().label("Level"),
+  parentId: number().integer().optional().nullable().label("Parent ID"),
+
+  /** The name in its own script. Stored, but NOT searchable; see `searchByLocale`. */
+  native: string().trim().optional().nullable().label("Native Name"),
+
+  /** Numbers, not the strings upstream ships. See `CountrySchema.latitude`. */
+  latitude: number().optional().nullable().label("Latitude"),
+  longitude: number().optional().nullable().label("Longitude"),
+
+  timezone: string().trim().optional().nullable().label("Timezone"),
+
+  /** Localized names keyed by locale. Unshaped; see `CountrySchema.translations`. */
+  translations: object().optional().nullable().label("Translations"),
+
+  /**
+   * The name field searched for the DEFAULT (English) locale: the canonical
+   * `name`, and nothing else.
+   *
+   * Search is scoped to ONE locale, so the searchable names are split across
+   * this field and `searchByLocale` rather than pooled into one array. A pooled
+   * field would make every locale's search implicitly a search of all 19
+   * languages: a French UI searching "Inde" would also match German "Indien".
+   */
+  searchDefault: array().of(string().required()).optional().default([]).label("Search Default"),
+
+  /**
+   * Per-locale name fields, keyed by lowercased BCP-47 tag (`de`, `pt-br`).
+   * Each carries ONLY that locale's translation, which is what makes
+   * `?locale=de` German and not "German plus everything that looks similar".
+   *
+   * Unshaped for the same reason as `translations`: the key set is upstream's.
+   *
+   * `native` is deliberately NOT indexed here. It cannot be attributed to a
+   * language with this data — 84% of city native names equal SEVERAL locales'
+   * translations (Latin spellings coinciding across de/it/nl/hr/pl) while
+   * distinctive non-Latin names like `भारत` match none — so filing `कर्नाटक`
+   * under German would be worse than not indexing it at all.
+   *
+   * The 19 upstream locales are br, ko, pt-BR, pt, nl, hr, fa, de, es, fr, ja,
+   * it, zh-CN, tr, ru, uk, pl, hi, ar. **`sv` is absent**, so a Swedish search
+   * matches nothing. That is the accepted cost of strict scoping.
+   */
+  searchByLocale: object().optional().nullable().label("Search By Locale"),
+
+  /** Epoch ms of the run that last wrote this row. Drives the stale-row prune. */
+  syncedAt: number().optional().nullable().label("Synced At"),
+}).label("State");
+
+export type State = InferType<typeof StateSchema>;

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

@@ -0,0 +1,81 @@
+/**
+ * The group filter: the closed vocabulary of facets a group query can filter on.
+ *
+ * The counterpart of `UserFilterSchema` and `JobFilterSchema`, and the single
+ * declaration that `thejob-group-service` and `@thejob/groups-client` both derive
+ * from — the client types its filter with `InferType`, and the service checks
+ * incoming keys against `Object.keys` of it.
+ *
+ * This one matters more than the others did. `parseFilter` in group-service
+ * accepts ANY `filter[x]` key, splits it on commas and hands it to Mongo, so
+ * before this schema existed a misspelled facet was not a narrower query — it
+ * was a query for a field no document has, which returns 200 OK with zero rows
+ * and no error anywhere. A marketing campaign configured that way looks correct
+ * and mails an empty digest.
+ *
+ * `search`, `page`, `limit`, `sortBy`, `sortDirection` and `fields` are
+ * deliberately absent: they are reserved query params, not facets.
+ *
+ * WHAT A FACET MEANS stays in the service. This declares only the NAMES and the
+ * SHAPES a caller may send.
+ */
+import { boolean, object } from "yup";
+import { enumFacet, rejectUnknownKeys, tokens } from "../common/facet.schema.js";
+import {
+  SupportedGroupManagedBy,
+  SupportedGroupStatuses,
+  SupportedGroupVisibilities,
+} from "./group.constant.js";
+
+const GroupFilterShape = object({
+  // ── Classification ──────────────────────────────────────────────────────────
+  // Closed vocabularies, matched exactly. Values are LOWERCASE (`active`,
+  // `public`, `system`) and that casing is data, not style: it is what is stored.
+  //
+  // All three are currently NON-SELECTIVE — every group in production is
+  // `active` / `public` / `system`. They are declared anyway because they are
+  // real vocabulary that gains meaning as the corpus grows, and a filter that
+  // silently ignores `status` would be worse than one that narrows to everything.
+  status: enumFacet(SupportedGroupStatuses, "Status"),
+  visibility: enumFacet(SupportedGroupVisibilities, "Visibility"),
+  managedBy: enumFacet(SupportedGroupManagedBy, "Managed By"),
+
+  // ── Flags ───────────────────────────────────────────────────────────────────
+  // No `.default(false)`: an unchecked box must mean "no constraint", not "only
+  // the non-featured ones", so absent simply omits the clause.
+  isFeatured: boolean().optional().label("Featured Only"),
+  isDiscoverable: boolean().optional().label("Discoverable Only"),
+
+  // ── Markets ─────────────────────────────────────────────────────────────────
+  /**
+   * `tokens`, NOT `codeTokens`. This is the trap in this file.
+   *
+   * Every other filter here uses `codeTokens` for country codes, because users
+   * and jobs store uppercase ISO alpha-2. Groups store them LOWERCASE (`in`,
+   * `se`, `ww` — verified against production). `codeTokens` uppercases its
+   * input, so `$in: ["IN"]` against a stored `"in"` matches nothing: no error,
+   * empty result, empty mail.
+   *
+   * If these are ever normalised to uppercase, this becomes `codeTokens` in the
+   * same change as the data migration, not before it.
+   */
+  countries: tokens("Countries"),
+  featuredMarkets: tokens("Featured Markets"),
+
+  /** Group SLUGS, for naming specific groups. A display name breaks on rename. */
+  slugs: tokens("Slugs"),
+}).label("Group Filter");
+
+const GROUP_FILTER_KEYS = Object.keys(GroupFilterShape.fields);
+
+/**
+ * THE group filter.
+ *
+ * Wrapped in `rejectUnknownKeys` following `UserFilterSchema` rather than
+ * `JobFilterSchema`: an unknown key here is silently dropped by yup and then
+ * matches nothing downstream, so it must fail loudly at the point it is written.
+ */
+export const GroupFilterSchema = rejectUnknownKeys(
+  GroupFilterShape,
+  () => GROUP_FILTER_KEYS,
+);

package/src/group/group.constant.ts

@@ -18,3 +18,18 @@ export enum GroupStatus {
   Active = "active",
   Archived = "archived",
 }
+
+/**
+ * The enum values as arrays, for schemas that need `.oneOf(...)`.
+ *
+ * The same `Object.values(...)` form `page.constant.ts` already exports
+ * (`SupportedPageTypes`, `SupportedPageStatuses`). Derived rather than written
+ * out, so a new enum member cannot be added to one list and forgotten in the
+ * other.
+ */
+export const SupportedGroupStatuses = Object.values(GroupStatus);
+export const SupportedGroupVisibilities = Object.values(GroupVisibility);
+export const SupportedGroupManagedBy = Object.values(GroupManagedBy);
+export const SupportedGroupMembershipStatuses = Object.values(
+  GroupMembershipStatus,
+);