@thejob/schema 2.1.2 → 2.1.4

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/user.constant.ts

@@ -97,6 +97,29 @@ export enum JobAlertFrequency {
 
 export const SupportedJobAlertFrequencies = Object.values(JobAlertFrequency);
 
+/**
+ * Channels of NOTIFICATION email — mail about activity on the user's own
+ * account (a group invite, a job of theirs expiring). Distinct from marketing:
+ * notifications are opt-OUT (default on, see `notificationPrefs`), marketing is
+ * opt-IN (`marketingConsent.subscribed`). Transactional mail (magic-link,
+ * verification) is governed by neither and always sends.
+ *
+ * Deliberately coarse: four channels a user will actually reason about, rather
+ * than one toggle per email template.
+ */
+export enum NotificationChannel {
+  /** Group invites, join requests, membership approved/rejected. */
+  GroupActivity = "groupActivity",
+  /** Activity on jobs the user posted, e.g. a listing expiring. */
+  JobActivity = "jobActivity",
+  /** Status changes on jobs the user applied to. */
+  ApplicationUpdates = "applicationUpdates",
+  /** Product announcements and feature news. */
+  ProductUpdates = "productUpdates",
+}
+
+export const SupportedNotificationChannels = Object.values(NotificationChannel);
+
 /** ISO-4217 currency codes accepted for the salary preference (extend as needed). */
 export const SupportedSalaryCurrencies = ["USD", "EUR", "GBP", "SEK", "INR"] as const;
 export type SupportedSalaryCurrency = (typeof SupportedSalaryCurrencies)[number];

package/src/user/user.schema.ts

@@ -141,6 +141,33 @@ export const UserSchema = object({
     .default({ subscribed: false })
     .label("Marketing Consent"),
 
+  /**
+   * Per-channel toggles for NOTIFICATION email — mail about activity on the
+   * user's own account (a group invite, a job of theirs expiring).
+   *
+   * Deliberately separate from `marketingConsent`, which they must NOT be
+   * collapsed into: the two have different legal footing, which the
+   * email-service footer rules already encode. Notifications are opt-OUT
+   * (default `true`) because a user who declined marketing still needs to hear
+   * that their group invite arrived; marketing stays opt-IN. `productUpdates`
+   * is the exception — it is promotional in character, so it defaults off.
+   *
+   * Transactional mail (magic-link, verification) ignores this object entirely.
+   */
+  notificationPrefs: object({
+    groupActivity: boolean().default(true).label("Group activity email"),
+    jobActivity: boolean().default(true).label("Job activity email"),
+    applicationUpdates: boolean().default(true).label("Application update email"),
+    productUpdates: boolean().default(false).label("Product update email"),
+  })
+    .default({
+      groupActivity: true,
+      jobActivity: true,
+      applicationUpdates: true,
+      productUpdates: false,
+    })
+    .label("Notification Preferences"),
+
   /**
    * Vector embedding of the user's profile for semantic/hybrid search.
    * Generated from a structured summary of skills, experience, education, etc.