@thejob/schema 2.1.3 → 2.1.5

package/src/saved-search/saved-search.schema.ts

@@ -0,0 +1,84 @@
+import { number, object, string } from "yup";
+import { JobAlertFrequency, SupportedJobAlertFrequencies } from "../user/user.constant.js";
+import { SavedSearchStatus, SupportedSavedSearchStatuses } from "./saved-search.constant.js";
+
+/**
+ * A search a user asked to be kept, and optionally to be alerted about.
+ *
+ * Two jobs in one document, deliberately: the query the user built, and the
+ * cadence at which they want it re-run for them. Splitting them would mean a
+ * user with three saved searches and one alert preference has no way to say
+ * which search the alert is for.
+ *
+ * The stored query mirrors what `GET /jobs/search-v3` accepts — a free-text
+ * `search` plus a `filter` map — so replaying a saved search is running the same
+ * search the user originally ran, not a second, subtly different implementation
+ * that drifts from it.
+ */
+export const SavedSearchSchema = object({
+  /** Public identifier. Server-assigned. */
+  shortId: string().trim().label("Short Id"),
+
+  /**
+   * Owner's Better Auth account id. Server-assigned from the verified token,
+   * never accepted from a request body.
+   */
+  ownerUserId: string().trim().label("Owner"),
+
+  /** What the user calls this search, e.g. "Remote React roles". */
+  label: string().trim().max(120).required().label("Label"),
+
+  /**
+   * The free-text query. Optional because a search can be filters-only ("all
+   * remote jobs in Sweden"), which is a legitimate alert to want.
+   */
+  search: string().trim().max(500).optional().label("Search Text"),
+
+  /**
+   * Field filters, in the same `{ field: values }` shape the search endpoint
+   * parses from `filter[field]=a,b`. Held as a free-form object rather than a
+   * closed schema because the job facets it addresses live in jobs-service and
+   * change independently; validating them here would put this package in the
+   * business of tracking that vocabulary.
+   */
+  filter: object().optional().default({}).label("Filters"),
+
+  /**
+   * How often to mail matches. `off` keeps the search saved but silent, which is
+   * the difference between "I don't want mail" and "delete my search".
+   *
+   * Reuses the cadence enum from `marketingConsent.jobAlertFrequency` rather
+   * than defining a second one: two vocabularies for the same concept is how
+   * they drift.
+   */
+  frequency: string()
+    .oneOf(SupportedJobAlertFrequencies)
+    .default(JobAlertFrequency.Off)
+    .label("Alert Frequency"),
+
+  status: string()
+    .oneOf(SupportedSavedSearchStatuses)
+    .default(SavedSearchStatus.Active)
+    .label("Status"),
+
+  /**
+   * Epoch ms of the last alert sent for this search. The matching sweep reads it
+   * to decide whether the cadence is due, and writes it only AFTER a successful
+   * publish, so a failed run retries next tick rather than silently skipping a
+   * period.
+   */
+  lastNotifiedAt: number().optional().label("Last Notified At"),
+
+  /**
+   * Epoch ms high-water mark: only jobs created after this are "new" for the
+   * next alert. Kept separate from `lastNotifiedAt` because a run that finds no
+   * matches should still advance what counts as new, without implying mail was
+   * sent.
+   */
+  lastMatchedAt: number().optional().label("Last Matched At"),
+})
+  // `createdAt`/`updatedAt` are deliberately absent, matching every other schema
+  // here: audit timestamps are the storing service's concern, not part of the
+  // shape a client sends or validates.
+  .noUnknown()
+  .strict();

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

@@ -1,7 +1,8 @@
-import { object, string } from "yup";
+import { number, object, string } from "yup";
 import { SupportedExperienceLevels } from "../common/common.constant.js";
 import { LocationSchema } from "../location/location.schema.js";
 import {
+  SupportedSignupContextSources,
   SupportedUserProfileVisibilities,
   UserProfileVisibility,
 } from "./user.constant.js";
@@ -30,14 +31,35 @@ export const UserGeneralDetailSchema = object({
     .required()
     .label("Experience level"),
   location: LocationSchema.required().label("Location"),
-  region: object()
+  /**
+   * Where the account was created, captured once and never rewritten.
+   *
+   * Server-owned: listed in user-service's SERVER_CONTROLLED_FIELDS and absent
+   * from every user-writable schema, so a client cannot set or amend it. That
+   * immutability is the point — this answers "which market/jurisdiction governed
+   * this user at sign-up?", which a field the user can PATCH could never do.
+   *
+   * `source` records HOW the value was obtained, because most of it is inferred
+   * rather than measured, and an audit has to be able to tell those apart:
+   *   - `cf-header`  measured from Cloudflare's `cf-ipcountry` at sign-up
+   *   - `location`   derived from the user's self-entered profile location
+   *   - `default`    assumed (no signal available); presumption, not evidence
+   */
+  signupContext: object()
     .shape({
-      country: string().trim().required().label("Region Country"),
-      lang: string().trim().required().label("Region Language"),
+      // ISO 3166-1 alpha-2, uppercase — the shape `cf-ipcountry` returns, so
+      // measured and inferred values are directly comparable.
+      country: string().trim().uppercase().length(2).required().label("Signup Country"),
+      locale: string().trim().required().label("Signup Locale"),
+      source: string()
+        .oneOf(SupportedSignupContextSources)
+        .required()
+        .label("Signup Context Source"),
+      at: number().required().label("Signup Context At"),
     })
     .optional()
     .default(undefined)
-    .label("Region"),
+    .label("Signup Context"),
   profileVisibility: string()
     .oneOf(SupportedUserProfileVisibilities)
     .default(UserProfileVisibility.Public)

package/src/user/user.constant.ts

@@ -34,6 +34,26 @@ export const SupportedUserProfileVisibilities = Object.values(
   UserProfileVisibility,
 );
 
+/**
+ * How a user's `signupContext` was obtained. Stored on the document, so these
+ * strings are data: lowercase, and a rename is a migration.
+ *
+ * The distinction is deliberate. Only `CfHeader` is measured; the other two are
+ * inferred, and `Default` is a bare presumption with no signal behind it at all.
+ * Collapsing them would make an assumed country indistinguishable from an
+ * observed one, which is precisely what a compliance record must not do.
+ */
+export enum SignupContextSource {
+  /** Measured from Cloudflare's `cf-ipcountry` header at sign-up. */
+  CfHeader = "cf-header",
+  /** Derived from the user's self-entered profile location (backfill). */
+  Location = "location",
+  /** Assumed; no signal was available. A presumption, not evidence. */
+  Default = "default",
+}
+
+export const SupportedSignupContextSources = Object.values(SignupContextSource);
+
 export enum UserDetailType {
   Overview = "overview",
   AdditionalInfo = "additionalInfo",