@thejob/schema 2.1.9 → 2.2.0

package/src/user/user.constant.ts

@@ -118,16 +118,28 @@ 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.
+ * KINDS of notification, by subject matter — what a message is ABOUT, not how
+ * it reaches the user. A notification of a given kind may be delivered over any
+ * transport (email, web push, and later whatsapp or in-app); this enum is the
+ * user's per-subject mute switch and applies across all of them.
  *
- * Deliberately coarse: four channels a user will actually reason about, rather
+ * Named `NotificationType` rather than `...Channel` precisely because "channel"
+ * reads as a delivery route. Muting `groupActivity` mutes group activity
+ * everywhere, not merely in the mail.
+ *
+ * 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 kinds a user will actually reason about, rather
  * than one toggle per email template.
+ *
+ * The VALUES are stored in Mongo as the keys of `notificationPrefs`, so they
+ * are data, not style. Renaming the enum is a type-level change; renaming a
+ * value would be a data migration.
  */
-export enum NotificationChannel {
+export enum NotificationType {
   /** Group invites, join requests, membership approved/rejected. */
   GroupActivity = "groupActivity",
   /** Activity on jobs the user posted, e.g. a listing expiring. */
@@ -138,7 +150,7 @@ export enum NotificationChannel {
   ProductUpdates = "productUpdates",
 }
 
-export const SupportedNotificationChannels = Object.values(NotificationChannel);
+export const SupportedNotificationTypes = Object.values(NotificationType);
 
 /** ISO-4217 currency codes accepted for the salary preference (extend as needed). */
 export const SupportedSalaryCurrencies = ["USD", "EUR", "GBP", "SEK", "INR"] as const;

package/src/user/user.schema.ts

@@ -168,6 +168,36 @@ export const UserSchema = object({
     })
     .label("Notification Preferences"),
 
+  /**
+   * Consent to receive WEB PUSH notifications.
+   *
+   * Push is a TRANSPORT, not a category: it carries the same notifications
+   * `notificationPrefs` already governs, delivered to a device instead of an
+   * inbox. That is why no push value is added to `NotificationType` — the user
+   * chooses whether push is used at all, and WHICH kinds are worth pushing
+   * stays a product decision.
+   *
+   * Opt-IN, and it must not be folded into `notificationPrefs`: those are
+   * opt-OUT and read `!== false`, so an absent value means ENABLED. Applied to
+   * push, every user who predates this field would read as having granted
+   * permission they were never asked for. This mirrors `marketingConsent`
+   * instead, which is the opt-in shape in this file, down to the provenance
+   * fields.
+   *
+   * Consent alone never delivers anything: a push send also needs a live
+   * subscription (see `PushSubscriptionSchema`). This flag is the user's
+   * intent, the subscription is the browser grant, and both are required.
+   */
+  pushConsent: object({
+    subscribed: boolean().default(false).label("Subscribed to push notifications"),
+    /** Epoch ms of the last consent change (opt-in or opt-out). */
+    updatedAt: number().optional().label("Push consent updated at"),
+    /** Where the change originated, e.g. `onboarding`, `settings`, `prompt`. */
+    source: string().optional().label("Push consent source"),
+  })
+    .default({ subscribed: false })
+    .label("Push Consent"),
+
   /**
    * Vector embedding of the user's profile for semantic/hybrid search.
    * Generated from a structured summary of skills, experience, education, etc.
@@ -180,6 +210,21 @@ export const UserSchema = object({
     .nullable()
     .optional()
     .label("Embedding"),
+
+  /**
+   * Epoch ms the account was created, assigned by the storing service.
+   *
+   * Declared here, matching `GroupSchema`, because it is not merely stored: all
+   * 103,608 user documents carry it, `UserFilterSchema` filters on it
+   * (`createdAtWithinDays` / `createdAtOlderThanDays`), and the admin grid sorts
+   * and displays it. It was absent, so a consumer deriving its row type from
+   * this schema could not name the column it renders, and this object is
+   * `.noUnknown().strict()` — an undeclared key is stripped on validation.
+   *
+   * `updatedAt` is deliberately NOT added alongside it: nothing derives from it
+   * yet, and an optional field is only safe to add when something needs it.
+   */
+  createdAt: number().optional().label("Created At"),
 })
   .concat(UserGeneralDetailSchema)
   .concat(UserJobPreferencesSchema)

package/src/user/user.types.ts

@@ -4,6 +4,41 @@ import type { LocationSchema } from "../location/location.schema.js";
 import type { EducationSchema } from "./education.schema.js";
 import type { UserGeneralDetailSchema } from "./general-detail.schema.js";
 import type { WorkExperienceSchema } from "./work-experience.schema.js";
+import type { PushSubscriptionSchema } from "./push-subscription.schema.js";
+import type { UserSchema } from "./user.schema.js";
+
+/**
+ * A user, as this package defines one.
+ *
+ * DERIVED from `UserSchema`, never hand-written, so it cannot drift from the
+ * shape the schema validates. Consumers project subsets of it (a listing
+ * returns a handful of fields, a profile read returns more), which is why
+ * every field a projection may omit is optional at the schema level.
+ *
+ * `shortId` and `slug` are assigned by the STORING service and are not part of
+ * the validated input shape, so they are added here rather than in the schema.
+ * `shortId` is the identifier to use everywhere; `authAccountId` is Better
+ * Auth's id and belongs only in auth-related paths.
+ */
+export type User = InferType<typeof UserSchema> & {
+  /** Public identifier, server-assigned. The id to key on. */
+  shortId?: string;
+  /** Public profile handle, server-assigned. */
+  slug?: string;
+};
+
+/**
+ * A stored push subscription, with the identifier the storing service assigns.
+ *
+ * Same split as `User`: `shortId` is server-assigned and so is not part of the
+ * validated input shape. Note that the identifier consumers actually key on
+ * here is `endpoint`, not `shortId` — it is what the browser re-sends on
+ * re-subscribe and what a dead-subscription response names.
+ */
+export type PushSubscriptionRecord = InferType<typeof PushSubscriptionSchema> & {
+  /** Public identifier, server-assigned. */
+  shortId?: string;
+};
 
 export type UserProfileOverview = {
   name: InferType<typeof UserGeneralDetailSchema>["name"];