@thejob/schema 2.1.4 → 2.1.6

package/CLAUDE.md

@@ -50,8 +50,31 @@ Practical consequences:
 
 Enum string values are consumed as literals across services and stored in Mongo, so
 their casing is data, not style. Group `managedBy` / `visibility` / `status` are
-**lowercase** (`system`, `private`, `archived`). Changing a case is a data migration,
-not a refactor — existing documents will silently stop matching.
+**lowercase** (`system`, `private`, `archived`), as are `SavedSearchStatus` and
+`JobAlertFrequency`. Changing a case is a data migration, not a refactor —
+existing documents will silently stop matching.
+
+## The consent fields are a compliance surface
+
+Three shapes here decide whether the platform may mail someone, and each behaves
+differently on purpose:
+
+- **`notificationPrefs`** (`user.schema.ts`) — per-channel, opt-**out**. The
+  consumer reads `!== false`, so a user whose document predates the field must
+  read as *enabled*. That is why adding it needed no backfill migration, and why
+  a "tidy-up" that made the fields required would silently mute every legacy user.
+- **`marketingConsent.subscribed`** — opt-**in**, read as `=== true`. The exact
+  inverse. Do not collapse the two into one shape; they have different legal
+  footing, which email-service's footer rules already encode.
+- **`marketingConsent.jobAlertFrequency`** — a *second* gate on job-alert mail
+  only, so a user can stop alerts while staying subscribed generally.
+
+`NotificationChannel` values are duplicated as a string union in `@thejob/notify`
+(so that package stays dependency-free). This package remains the source of
+truth; adding a channel means editing the enum, the `notificationPrefs` object
+keys, its `.default()`, and that union.
+
+Full picture: `thejob-notification-service/NOTIFICATIONS.md`.
 
 ## Conventions
 

package/dist/index.cjs

@@ -102,6 +102,7 @@ __export(index_exports, {
   SYSTEM_DATE_FORMAT: () => SYSTEM_DATE_FORMAT,
   SavedSearchSchema: () => SavedSearchSchema,
   SavedSearchStatus: () => SavedSearchStatus,
+  SignupContextSource: () => SignupContextSource,
   SkillSchema: () => SkillSchema,
   SocialAccount: () => SocialAccount,
   SocialAccountSchema: () => SocialAccountSchema,
@@ -135,6 +136,7 @@ __export(index_exports, {
   SupportedResourceTypes: () => SupportedResourceTypes,
   SupportedSalaryCurrencies: () => SupportedSalaryCurrencies,
   SupportedSavedSearchStatuses: () => SupportedSavedSearchStatuses,
+  SupportedSignupContextSources: () => SupportedSignupContextSources,
   SupportedSocialAccounts: () => SupportedSocialAccounts,
   SupportedStudyTypes: () => SupportedStudyTypes,
   SupportedUserProfileVisibilities: () => SupportedUserProfileVisibilities,
@@ -592,6 +594,26 @@ var PageSchema = (0, import_yup12.object)().shape({
 var import_yup13 = require("yup");
 var SkillSchema = (0, import_yup13.object)({
   name: (0, import_yup13.string)().trim().required().label("Skill Name"),
+  /**
+   * The taxonomy concept this skill resolved to, assigned by thejob-taxonomy-service
+   * via `POST /normalize/batch`. Stable slug, e.g. "power-bi".
+   *
+   * Normalization is ADDITIVE and never authoritative over `name`: the raw string a
+   * job was posted with is always preserved, and these two fields are written
+   * alongside it. That is what makes a wrong match, a taxonomy re-run, or a service
+   * outage recoverable rather than a data loss.
+   *
+   * Optional and nullable because they genuinely are absent in two normal cases,
+   * neither of which is an error:
+   *   - the term did not resolve (~22% of mentions are a long tail the taxonomy has
+   *     no concept for yet), and the raw `name` stands alone;
+   *   - the document predates normalization and has not been re-processed.
+   *
+   * Consumers must therefore read `conceptName ?? name`, never `conceptName` alone.
+   */
+  conceptId: (0, import_yup13.string)().optional().nullable().label("Concept ID"),
+  /** Canonical display name for `conceptId`, e.g. "Power BI". See `conceptId`. */
+  conceptName: (0, import_yup13.string)().optional().nullable().label("Concept Name"),
   logo: (0, import_yup13.object)({
     light: (0, import_yup13.string)().required().label("Light Logo"),
     dark: (0, import_yup13.string)().optional().nullable().label("Dark Logo")
@@ -797,7 +819,15 @@ var JobSchema = (0, import_yup18.object)({
   designation: (0, import_yup18.string)().optional().nullable().label("Designation"),
   employmentType: (0, import_yup18.string)().required().label("Employment type"),
   workMode: (0, import_yup18.string)().required().label("Work mode"),
-  skills: (0, import_yup18.array)().of(SkillSchema.pick(["name", "logo"]).required().label("Skill")).nullable().optional().label("Skills"),
+  /**
+   * `conceptId`/`conceptName` carry the taxonomy-service normalization. They are
+   * picked here (not just `name`/`logo`) because SkillSchema is `.noUnknown()`:
+   * an unpicked field that is actually PRESENT fails validation, so omitting them
+   * would reject every normalized job.
+   */
+  skills: (0, import_yup18.array)().of(
+    SkillSchema.pick(["name", "logo", "conceptId", "conceptName"]).required().label("Skill")
+  ).nullable().optional().label("Skills"),
   bookmarks: (0, import_yup18.array)().of(UserIdAndCreatedAtSchema).optional().label("Bookmarks"),
   embedding: (0, import_yup18.object)({
     vector: (0, import_yup18.array)((0, import_yup18.number)().required()).optional().label("Embedding vector"),
@@ -2110,6 +2140,13 @@ var UserProfileVisibility = /* @__PURE__ */ ((UserProfileVisibility2) => {
 var SupportedUserProfileVisibilities = Object.values(
   UserProfileVisibility
 );
+var SignupContextSource = /* @__PURE__ */ ((SignupContextSource2) => {
+  SignupContextSource2["CfHeader"] = "cf-header";
+  SignupContextSource2["Location"] = "location";
+  SignupContextSource2["Default"] = "default";
+  return SignupContextSource2;
+})(SignupContextSource || {});
+var SupportedSignupContextSources = Object.values(SignupContextSource);
 var UserDetailType = /* @__PURE__ */ ((UserDetailType2) => {
   UserDetailType2["Overview"] = "overview";
   UserDetailType2["AdditionalInfo"] = "additionalInfo";
@@ -2533,10 +2570,28 @@ var UserGeneralDetailSchema = (0, import_yup33.object)({
   mobileVerified: (0, import_yup33.string)().nullable().optional().label("Mobile Verified"),
   experienceLevel: (0, import_yup33.string)().oneOf(SupportedExperienceLevels).required().label("Experience level"),
   location: LocationSchema.required().label("Location"),
-  region: (0, import_yup33.object)().shape({
-    country: (0, import_yup33.string)().trim().required().label("Region Country"),
-    lang: (0, import_yup33.string)().trim().required().label("Region Language")
-  }).optional().default(void 0).label("Region"),
+  /**
+   * 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: (0, import_yup33.object)().shape({
+    // ISO 3166-1 alpha-2, uppercase — the shape `cf-ipcountry` returns, so
+    // measured and inferred values are directly comparable.
+    country: (0, import_yup33.string)().trim().uppercase().length(2).required().label("Signup Country"),
+    locale: (0, import_yup33.string)().trim().required().label("Signup Locale"),
+    source: (0, import_yup33.string)().oneOf(SupportedSignupContextSources).required().label("Signup Context Source"),
+    at: (0, import_yup33.number)().required().label("Signup Context At")
+  }).optional().default(void 0).label("Signup Context"),
   profileVisibility: (0, import_yup33.string)().oneOf(SupportedUserProfileVisibilities).default("public" /* Public */).label("Profile Visibility")
 }).noUnknown().strict().label("General Detail");
 
@@ -2886,6 +2941,7 @@ var StudentCompletenessSchema = UserCompletenessSchema.omit([
   SYSTEM_DATE_FORMAT,
   SavedSearchSchema,
   SavedSearchStatus,
+  SignupContextSource,
   SkillSchema,
   SocialAccount,
   SocialAccountSchema,
@@ -2919,6 +2975,7 @@ var StudentCompletenessSchema = UserCompletenessSchema.omit([
   SupportedResourceTypes,
   SupportedSalaryCurrencies,
   SupportedSavedSearchStatuses,
+  SupportedSignupContextSources,
   SupportedSocialAccounts,
   SupportedStudyTypes,
   SupportedUserProfileVisibilities,

package/dist/index.d.cts

@@ -437,6 +437,8 @@ declare const JobSchema: ObjectSchema<{
     employmentType: string;
     workMode: string;
     skills: {
+        conceptId?: string | null | undefined;
+        conceptName?: string | null | undefined;
         name: string;
         logo: {
             dark?: string | null | undefined;
@@ -1500,6 +1502,24 @@ declare enum UserProfileVisibility {
     Hidden = "hidden"
 }
 declare const SupportedUserProfileVisibilities: 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.
+ */
+declare 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"
+}
+declare const SupportedSignupContextSources: SignupContextSource[];
 declare enum UserDetailType {
     Overview = "overview",
     AdditionalInfo = "additionalInfo",
@@ -1718,6 +1738,8 @@ declare const FeedbackSchema: yup.ObjectSchema<{
 
 declare const SkillSchema: yup.ObjectSchema<{
     name: string;
+    conceptId: string | null | undefined;
+    conceptName: string | null | undefined;
     logo: {
         dark?: string | null | undefined;
         light: string;
@@ -1731,6 +1753,8 @@ declare const SkillSchema: yup.ObjectSchema<{
     updatedAt: number | undefined;
 }, yup.AnyObject, {
     name: undefined;
+    conceptId: undefined;
+    conceptName: undefined;
     logo: null;
     tags: "";
     shortId: undefined;
@@ -1932,9 +1956,11 @@ declare const UserSchema: yup.ObjectSchema<{
             coordinates: number[];
         };
     };
-    region: {
+    signupContext: {
         country: string;
-        lang: string;
+        at: number;
+        locale: string;
+        source: NonNullable<SignupContextSource | undefined>;
     } | undefined;
     profileVisibility: UserProfileVisibility;
     openToWork: boolean;
@@ -2137,7 +2163,7 @@ declare const UserSchema: yup.ObjectSchema<{
             coordinates: "";
         };
     };
-    region: undefined;
+    signupContext: undefined;
     profileVisibility: UserProfileVisibility.Public;
     openToWork: false;
     jobSearchUrgency: undefined;
@@ -2189,9 +2215,11 @@ declare const UserGeneralDetailSchema: yup.ObjectSchema<{
             coordinates: number[];
         };
     };
-    region: {
+    signupContext: {
         country: string;
-        lang: string;
+        at: number;
+        locale: string;
+        source: NonNullable<SignupContextSource | undefined>;
     } | undefined;
     profileVisibility: UserProfileVisibility;
 }, yup.AnyObject, {
@@ -2221,7 +2249,7 @@ declare const UserGeneralDetailSchema: yup.ObjectSchema<{
             coordinates: "";
         };
     };
-    region: undefined;
+    signupContext: undefined;
     profileVisibility: UserProfileVisibility.Public;
 }, "">;
 
@@ -2995,4 +3023,4 @@ declare const StudentCompletenessSchema: yup.ObjectSchema<{
     };
 }, "">;
 
-export { AnswerChoiceType, ApplicationReceivePreference, CampaignSchema, CampaignStatus, ChoiceQuestionSchema, Common, CompensationType, CompletenessScoreSchema, ContactTypes, CoordinatorPageLinkSchema, DISPLAY_DATE_FORMAT, DISPLAY_DATE_FORMAT_SHORT, DateStringSchema, DbDefaultSchema, DefaultPaginatedResponse, DefaultPaginationOptions, DefaultUserRoles, DurationSchema, EMPTY_STRING, EducationLevel, EducationSchema, EmployeeCount, EmploymentType, ExperienceLevel, FEEDBACK_MESSAGE_MAX, FeedbackSchema, FeedbackStatus, FeedbackType, GeneraDetailFields, GroupManagedBy, GroupMembershipSchema, GroupMembershipStatus, GroupSchema, GroupStatus, GroupTranslationSchema, GroupVisibility, InputQuestionSchema, JOB_TAXONOMY, JobAlertFrequency, JobCategory, JobIndustry, JobSchema, JobSearchUrgency, JobStatus, JobSubCategory, ListFilterSchema, LocationSchema, MIN_SALARY_LOWER_BOUND, MIN_SALARY_UPPER_BOUND, MailingListSchema, NotificationChannel, PREFILL_MIRRORED_KEYS, PRIVATE_PROFILE_FIELDS, PageSchema, PageStatus, PageType, type PaginatedResponse, PaginationSchema, PostSchema, PostStatus, type PrefillMirroredKey, type PrivateProfileField, ProficiencyLevel, QuestionSchema, QuestionType, ReadAndAcknowledgeQuestionSchema, RecruiterPageLinkSchema, ReferralSource, ReportReason, ReportSchema, ResourceType, SITEMAP_FORMAT, SYSTEM_DATE_FORMAT, SavedSearchSchema, SavedSearchStatus, SkillSchema, SocialAccount, SocialAccountSchema, StudentCompletenessSchema, StudyType, SupportedAnswerChoiceTypes, SupportedApplicationReceivePreferences, SupportedCampaignStatuses, SupportedCompensationTypes, SupportedContactTypes, SupportedEducationLevels, SupportedEmployeeCounts, SupportedEmploymentTypes, SupportedExperienceLevels, SupportedFeedbackStatuses, SupportedFeedbackTypes, SupportedJobAlertFrequencies, SupportedJobCategories, SupportedJobIndustries, SupportedJobSearchUrgencies, SupportedJobStatuses, SupportedJobSubCategories, SupportedNotificationChannels, SupportedPageStatuses, SupportedPageTypes, SupportedPostStatuses, SupportedProficiencyLevels, SupportedQuestionTypes, SupportedReferralSources, SupportedReportReasons, SupportedResourceTypes, SupportedSalaryCurrencies, type SupportedSalaryCurrency, SupportedSavedSearchStatuses, SupportedSocialAccounts, SupportedStudyTypes, SupportedUserProfileVisibilities, SupportedUserRoles, SupportedUserStatuses, SupportedWorkModes, TAXONOMY_LABELS, type TChoiceQuestionSchema, type TDurationSchema, type TInputQuestionSchema, type TJobSchema, type TPostSchema, type TQuestionSchema, type TReadAndAcknowledgeQuestionSchema, type TUserIdAndCreatedAtSchema, TermsAcceptedSchema, UserAdditionalInfoSchema, UserCertificationSchema, UserCompletenessSchema, UserCoordinatorProfileSchema, UserDetailType, UserGeneralDetailSchema, UserIdAndCreatedAtSchema, UserInterestSchema, UserJobPreferencesSchema, UserLanguageSchema, type UserProfileOverview, UserProfileVisibility, UserProjectSchema, UserRecruiterProfileSchema, UserRole, UserSchema, UserSkillSchema, UserStatus, WorkExperienceSchema, WorkMode, categoryOfIndustry, categoryOfSubCategory, dateString, deriveIndustry, getSchemaByQuestion, industriesOfCategory, industryOfSubCategory, subCategoriesOfIndustry };
+export { AnswerChoiceType, ApplicationReceivePreference, CampaignSchema, CampaignStatus, ChoiceQuestionSchema, Common, CompensationType, CompletenessScoreSchema, ContactTypes, CoordinatorPageLinkSchema, DISPLAY_DATE_FORMAT, DISPLAY_DATE_FORMAT_SHORT, DateStringSchema, DbDefaultSchema, DefaultPaginatedResponse, DefaultPaginationOptions, DefaultUserRoles, DurationSchema, EMPTY_STRING, EducationLevel, EducationSchema, EmployeeCount, EmploymentType, ExperienceLevel, FEEDBACK_MESSAGE_MAX, FeedbackSchema, FeedbackStatus, FeedbackType, GeneraDetailFields, GroupManagedBy, GroupMembershipSchema, GroupMembershipStatus, GroupSchema, GroupStatus, GroupTranslationSchema, GroupVisibility, InputQuestionSchema, JOB_TAXONOMY, JobAlertFrequency, JobCategory, JobIndustry, JobSchema, JobSearchUrgency, JobStatus, JobSubCategory, ListFilterSchema, LocationSchema, MIN_SALARY_LOWER_BOUND, MIN_SALARY_UPPER_BOUND, MailingListSchema, NotificationChannel, PREFILL_MIRRORED_KEYS, PRIVATE_PROFILE_FIELDS, PageSchema, PageStatus, PageType, type PaginatedResponse, PaginationSchema, PostSchema, PostStatus, type PrefillMirroredKey, type PrivateProfileField, ProficiencyLevel, QuestionSchema, QuestionType, ReadAndAcknowledgeQuestionSchema, RecruiterPageLinkSchema, ReferralSource, ReportReason, ReportSchema, ResourceType, SITEMAP_FORMAT, SYSTEM_DATE_FORMAT, SavedSearchSchema, SavedSearchStatus, SignupContextSource, SkillSchema, SocialAccount, SocialAccountSchema, StudentCompletenessSchema, StudyType, SupportedAnswerChoiceTypes, SupportedApplicationReceivePreferences, SupportedCampaignStatuses, SupportedCompensationTypes, SupportedContactTypes, SupportedEducationLevels, SupportedEmployeeCounts, SupportedEmploymentTypes, SupportedExperienceLevels, SupportedFeedbackStatuses, SupportedFeedbackTypes, SupportedJobAlertFrequencies, SupportedJobCategories, SupportedJobIndustries, SupportedJobSearchUrgencies, SupportedJobStatuses, SupportedJobSubCategories, SupportedNotificationChannels, SupportedPageStatuses, SupportedPageTypes, SupportedPostStatuses, SupportedProficiencyLevels, SupportedQuestionTypes, SupportedReferralSources, SupportedReportReasons, SupportedResourceTypes, SupportedSalaryCurrencies, type SupportedSalaryCurrency, SupportedSavedSearchStatuses, SupportedSignupContextSources, SupportedSocialAccounts, SupportedStudyTypes, SupportedUserProfileVisibilities, SupportedUserRoles, SupportedUserStatuses, SupportedWorkModes, TAXONOMY_LABELS, type TChoiceQuestionSchema, type TDurationSchema, type TInputQuestionSchema, type TJobSchema, type TPostSchema, type TQuestionSchema, type TReadAndAcknowledgeQuestionSchema, type TUserIdAndCreatedAtSchema, TermsAcceptedSchema, UserAdditionalInfoSchema, UserCertificationSchema, UserCompletenessSchema, UserCoordinatorProfileSchema, UserDetailType, UserGeneralDetailSchema, UserIdAndCreatedAtSchema, UserInterestSchema, UserJobPreferencesSchema, UserLanguageSchema, type UserProfileOverview, UserProfileVisibility, UserProjectSchema, UserRecruiterProfileSchema, UserRole, UserSchema, UserSkillSchema, UserStatus, WorkExperienceSchema, WorkMode, categoryOfIndustry, categoryOfSubCategory, dateString, deriveIndustry, getSchemaByQuestion, industriesOfCategory, industryOfSubCategory, subCategoriesOfIndustry };

package/dist/index.d.ts

@@ -437,6 +437,8 @@ declare const JobSchema: ObjectSchema<{
     employmentType: string;
     workMode: string;
     skills: {
+        conceptId?: string | null | undefined;
+        conceptName?: string | null | undefined;
         name: string;
         logo: {
             dark?: string | null | undefined;
@@ -1500,6 +1502,24 @@ declare enum UserProfileVisibility {
     Hidden = "hidden"
 }
 declare const SupportedUserProfileVisibilities: 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.
+ */
+declare 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"
+}
+declare const SupportedSignupContextSources: SignupContextSource[];
 declare enum UserDetailType {
     Overview = "overview",
     AdditionalInfo = "additionalInfo",
@@ -1718,6 +1738,8 @@ declare const FeedbackSchema: yup.ObjectSchema<{
 
 declare const SkillSchema: yup.ObjectSchema<{
     name: string;
+    conceptId: string | null | undefined;
+    conceptName: string | null | undefined;
     logo: {
         dark?: string | null | undefined;
         light: string;
@@ -1731,6 +1753,8 @@ declare const SkillSchema: yup.ObjectSchema<{
     updatedAt: number | undefined;
 }, yup.AnyObject, {
     name: undefined;
+    conceptId: undefined;
+    conceptName: undefined;
     logo: null;
     tags: "";
     shortId: undefined;
@@ -1932,9 +1956,11 @@ declare const UserSchema: yup.ObjectSchema<{
             coordinates: number[];
         };
     };
-    region: {
+    signupContext: {
         country: string;
-        lang: string;
+        at: number;
+        locale: string;
+        source: NonNullable<SignupContextSource | undefined>;
     } | undefined;
     profileVisibility: UserProfileVisibility;
     openToWork: boolean;
@@ -2137,7 +2163,7 @@ declare const UserSchema: yup.ObjectSchema<{
             coordinates: "";
         };
     };
-    region: undefined;
+    signupContext: undefined;
     profileVisibility: UserProfileVisibility.Public;
     openToWork: false;
     jobSearchUrgency: undefined;
@@ -2189,9 +2215,11 @@ declare const UserGeneralDetailSchema: yup.ObjectSchema<{
             coordinates: number[];
         };
     };
-    region: {
+    signupContext: {
         country: string;
-        lang: string;
+        at: number;
+        locale: string;
+        source: NonNullable<SignupContextSource | undefined>;
     } | undefined;
     profileVisibility: UserProfileVisibility;
 }, yup.AnyObject, {
@@ -2221,7 +2249,7 @@ declare const UserGeneralDetailSchema: yup.ObjectSchema<{
             coordinates: "";
         };
     };
-    region: undefined;
+    signupContext: undefined;
     profileVisibility: UserProfileVisibility.Public;
 }, "">;
 
@@ -2995,4 +3023,4 @@ declare const StudentCompletenessSchema: yup.ObjectSchema<{
     };
 }, "">;
 
-export { AnswerChoiceType, ApplicationReceivePreference, CampaignSchema, CampaignStatus, ChoiceQuestionSchema, Common, CompensationType, CompletenessScoreSchema, ContactTypes, CoordinatorPageLinkSchema, DISPLAY_DATE_FORMAT, DISPLAY_DATE_FORMAT_SHORT, DateStringSchema, DbDefaultSchema, DefaultPaginatedResponse, DefaultPaginationOptions, DefaultUserRoles, DurationSchema, EMPTY_STRING, EducationLevel, EducationSchema, EmployeeCount, EmploymentType, ExperienceLevel, FEEDBACK_MESSAGE_MAX, FeedbackSchema, FeedbackStatus, FeedbackType, GeneraDetailFields, GroupManagedBy, GroupMembershipSchema, GroupMembershipStatus, GroupSchema, GroupStatus, GroupTranslationSchema, GroupVisibility, InputQuestionSchema, JOB_TAXONOMY, JobAlertFrequency, JobCategory, JobIndustry, JobSchema, JobSearchUrgency, JobStatus, JobSubCategory, ListFilterSchema, LocationSchema, MIN_SALARY_LOWER_BOUND, MIN_SALARY_UPPER_BOUND, MailingListSchema, NotificationChannel, PREFILL_MIRRORED_KEYS, PRIVATE_PROFILE_FIELDS, PageSchema, PageStatus, PageType, type PaginatedResponse, PaginationSchema, PostSchema, PostStatus, type PrefillMirroredKey, type PrivateProfileField, ProficiencyLevel, QuestionSchema, QuestionType, ReadAndAcknowledgeQuestionSchema, RecruiterPageLinkSchema, ReferralSource, ReportReason, ReportSchema, ResourceType, SITEMAP_FORMAT, SYSTEM_DATE_FORMAT, SavedSearchSchema, SavedSearchStatus, SkillSchema, SocialAccount, SocialAccountSchema, StudentCompletenessSchema, StudyType, SupportedAnswerChoiceTypes, SupportedApplicationReceivePreferences, SupportedCampaignStatuses, SupportedCompensationTypes, SupportedContactTypes, SupportedEducationLevels, SupportedEmployeeCounts, SupportedEmploymentTypes, SupportedExperienceLevels, SupportedFeedbackStatuses, SupportedFeedbackTypes, SupportedJobAlertFrequencies, SupportedJobCategories, SupportedJobIndustries, SupportedJobSearchUrgencies, SupportedJobStatuses, SupportedJobSubCategories, SupportedNotificationChannels, SupportedPageStatuses, SupportedPageTypes, SupportedPostStatuses, SupportedProficiencyLevels, SupportedQuestionTypes, SupportedReferralSources, SupportedReportReasons, SupportedResourceTypes, SupportedSalaryCurrencies, type SupportedSalaryCurrency, SupportedSavedSearchStatuses, SupportedSocialAccounts, SupportedStudyTypes, SupportedUserProfileVisibilities, SupportedUserRoles, SupportedUserStatuses, SupportedWorkModes, TAXONOMY_LABELS, type TChoiceQuestionSchema, type TDurationSchema, type TInputQuestionSchema, type TJobSchema, type TPostSchema, type TQuestionSchema, type TReadAndAcknowledgeQuestionSchema, type TUserIdAndCreatedAtSchema, TermsAcceptedSchema, UserAdditionalInfoSchema, UserCertificationSchema, UserCompletenessSchema, UserCoordinatorProfileSchema, UserDetailType, UserGeneralDetailSchema, UserIdAndCreatedAtSchema, UserInterestSchema, UserJobPreferencesSchema, UserLanguageSchema, type UserProfileOverview, UserProfileVisibility, UserProjectSchema, UserRecruiterProfileSchema, UserRole, UserSchema, UserSkillSchema, UserStatus, WorkExperienceSchema, WorkMode, categoryOfIndustry, categoryOfSubCategory, dateString, deriveIndustry, getSchemaByQuestion, industriesOfCategory, industryOfSubCategory, subCategoriesOfIndustry };
+export { AnswerChoiceType, ApplicationReceivePreference, CampaignSchema, CampaignStatus, ChoiceQuestionSchema, Common, CompensationType, CompletenessScoreSchema, ContactTypes, CoordinatorPageLinkSchema, DISPLAY_DATE_FORMAT, DISPLAY_DATE_FORMAT_SHORT, DateStringSchema, DbDefaultSchema, DefaultPaginatedResponse, DefaultPaginationOptions, DefaultUserRoles, DurationSchema, EMPTY_STRING, EducationLevel, EducationSchema, EmployeeCount, EmploymentType, ExperienceLevel, FEEDBACK_MESSAGE_MAX, FeedbackSchema, FeedbackStatus, FeedbackType, GeneraDetailFields, GroupManagedBy, GroupMembershipSchema, GroupMembershipStatus, GroupSchema, GroupStatus, GroupTranslationSchema, GroupVisibility, InputQuestionSchema, JOB_TAXONOMY, JobAlertFrequency, JobCategory, JobIndustry, JobSchema, JobSearchUrgency, JobStatus, JobSubCategory, ListFilterSchema, LocationSchema, MIN_SALARY_LOWER_BOUND, MIN_SALARY_UPPER_BOUND, MailingListSchema, NotificationChannel, PREFILL_MIRRORED_KEYS, PRIVATE_PROFILE_FIELDS, PageSchema, PageStatus, PageType, type PaginatedResponse, PaginationSchema, PostSchema, PostStatus, type PrefillMirroredKey, type PrivateProfileField, ProficiencyLevel, QuestionSchema, QuestionType, ReadAndAcknowledgeQuestionSchema, RecruiterPageLinkSchema, ReferralSource, ReportReason, ReportSchema, ResourceType, SITEMAP_FORMAT, SYSTEM_DATE_FORMAT, SavedSearchSchema, SavedSearchStatus, SignupContextSource, SkillSchema, SocialAccount, SocialAccountSchema, StudentCompletenessSchema, StudyType, SupportedAnswerChoiceTypes, SupportedApplicationReceivePreferences, SupportedCampaignStatuses, SupportedCompensationTypes, SupportedContactTypes, SupportedEducationLevels, SupportedEmployeeCounts, SupportedEmploymentTypes, SupportedExperienceLevels, SupportedFeedbackStatuses, SupportedFeedbackTypes, SupportedJobAlertFrequencies, SupportedJobCategories, SupportedJobIndustries, SupportedJobSearchUrgencies, SupportedJobStatuses, SupportedJobSubCategories, SupportedNotificationChannels, SupportedPageStatuses, SupportedPageTypes, SupportedPostStatuses, SupportedProficiencyLevels, SupportedQuestionTypes, SupportedReferralSources, SupportedReportReasons, SupportedResourceTypes, SupportedSalaryCurrencies, type SupportedSalaryCurrency, SupportedSavedSearchStatuses, SupportedSignupContextSources, SupportedSocialAccounts, SupportedStudyTypes, SupportedUserProfileVisibilities, SupportedUserRoles, SupportedUserStatuses, SupportedWorkModes, TAXONOMY_LABELS, type TChoiceQuestionSchema, type TDurationSchema, type TInputQuestionSchema, type TJobSchema, type TPostSchema, type TQuestionSchema, type TReadAndAcknowledgeQuestionSchema, type TUserIdAndCreatedAtSchema, TermsAcceptedSchema, UserAdditionalInfoSchema, UserCertificationSchema, UserCompletenessSchema, UserCoordinatorProfileSchema, UserDetailType, UserGeneralDetailSchema, UserIdAndCreatedAtSchema, UserInterestSchema, UserJobPreferencesSchema, UserLanguageSchema, type UserProfileOverview, UserProfileVisibility, UserProjectSchema, UserRecruiterProfileSchema, UserRole, UserSchema, UserSkillSchema, UserStatus, WorkExperienceSchema, WorkMode, categoryOfIndustry, categoryOfSubCategory, dateString, deriveIndustry, getSchemaByQuestion, industriesOfCategory, industryOfSubCategory, subCategoriesOfIndustry };

package/dist/index.js

@@ -417,6 +417,26 @@ var PageSchema = object10().shape({
 import { array as array6, object as object11, string as string8 } from "yup";
 var SkillSchema = object11({
   name: string8().trim().required().label("Skill Name"),
+  /**
+   * The taxonomy concept this skill resolved to, assigned by thejob-taxonomy-service
+   * via `POST /normalize/batch`. Stable slug, e.g. "power-bi".
+   *
+   * Normalization is ADDITIVE and never authoritative over `name`: the raw string a
+   * job was posted with is always preserved, and these two fields are written
+   * alongside it. That is what makes a wrong match, a taxonomy re-run, or a service
+   * outage recoverable rather than a data loss.
+   *
+   * Optional and nullable because they genuinely are absent in two normal cases,
+   * neither of which is an error:
+   *   - the term did not resolve (~22% of mentions are a long tail the taxonomy has
+   *     no concept for yet), and the raw `name` stands alone;
+   *   - the document predates normalization and has not been re-processed.
+   *
+   * Consumers must therefore read `conceptName ?? name`, never `conceptName` alone.
+   */
+  conceptId: string8().optional().nullable().label("Concept ID"),
+  /** Canonical display name for `conceptId`, e.g. "Power BI". See `conceptId`. */
+  conceptName: string8().optional().nullable().label("Concept Name"),
   logo: object11({
     light: string8().required().label("Light Logo"),
     dark: string8().optional().nullable().label("Dark Logo")
@@ -622,7 +642,15 @@ var JobSchema = object16({
   designation: string13().optional().nullable().label("Designation"),
   employmentType: string13().required().label("Employment type"),
   workMode: string13().required().label("Work mode"),
-  skills: array8().of(SkillSchema.pick(["name", "logo"]).required().label("Skill")).nullable().optional().label("Skills"),
+  /**
+   * `conceptId`/`conceptName` carry the taxonomy-service normalization. They are
+   * picked here (not just `name`/`logo`) because SkillSchema is `.noUnknown()`:
+   * an unpicked field that is actually PRESENT fails validation, so omitting them
+   * would reject every normalized job.
+   */
+  skills: array8().of(
+    SkillSchema.pick(["name", "logo", "conceptId", "conceptName"]).required().label("Skill")
+  ).nullable().optional().label("Skills"),
   bookmarks: array8().of(UserIdAndCreatedAtSchema).optional().label("Bookmarks"),
   embedding: object16({
     vector: array8(number5().required()).optional().label("Embedding vector"),
@@ -1935,6 +1963,13 @@ var UserProfileVisibility = /* @__PURE__ */ ((UserProfileVisibility2) => {
 var SupportedUserProfileVisibilities = Object.values(
   UserProfileVisibility
 );
+var SignupContextSource = /* @__PURE__ */ ((SignupContextSource2) => {
+  SignupContextSource2["CfHeader"] = "cf-header";
+  SignupContextSource2["Location"] = "location";
+  SignupContextSource2["Default"] = "default";
+  return SignupContextSource2;
+})(SignupContextSource || {});
+var SupportedSignupContextSources = Object.values(SignupContextSource);
 var UserDetailType = /* @__PURE__ */ ((UserDetailType2) => {
   UserDetailType2["Overview"] = "overview";
   UserDetailType2["AdditionalInfo"] = "additionalInfo";
@@ -2253,7 +2288,7 @@ var FeedbackSchema = object22({
 }).label("Feedback Schema");
 
 // src/user/user.schema.ts
-import { array as array14, boolean as boolean15, number as number11, object as object34, string as string32 } from "yup";
+import { array as array14, boolean as boolean15, number as number12, object as object34, string as string32 } from "yup";
 
 // src/user/work-experience.schema.ts
 import { boolean as boolean12, object as object23, string as string20 } from "yup";
@@ -2342,7 +2377,7 @@ var UserAdditionalInfoSchema = object29({
 }).noUnknown().strict().label("User Additional Info");
 
 // src/user/general-detail.schema.ts
-import { object as object30, string as string28 } from "yup";
+import { number as number10, object as object30, string as string28 } from "yup";
 var UserGeneralDetailSchema = object30({
   id: string28().optional().label("ID"),
   name: object30().shape({
@@ -2358,15 +2393,33 @@ var UserGeneralDetailSchema = object30({
   mobileVerified: string28().nullable().optional().label("Mobile Verified"),
   experienceLevel: string28().oneOf(SupportedExperienceLevels).required().label("Experience level"),
   location: LocationSchema.required().label("Location"),
-  region: object30().shape({
-    country: string28().trim().required().label("Region Country"),
-    lang: string28().trim().required().label("Region Language")
-  }).optional().default(void 0).label("Region"),
+  /**
+   * 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: object30().shape({
+    // ISO 3166-1 alpha-2, uppercase — the shape `cf-ipcountry` returns, so
+    // measured and inferred values are directly comparable.
+    country: string28().trim().uppercase().length(2).required().label("Signup Country"),
+    locale: string28().trim().required().label("Signup Locale"),
+    source: string28().oneOf(SupportedSignupContextSources).required().label("Signup Context Source"),
+    at: number10().required().label("Signup Context At")
+  }).optional().default(void 0).label("Signup Context"),
   profileVisibility: string28().oneOf(SupportedUserProfileVisibilities).default("public" /* Public */).label("Profile Visibility")
 }).noUnknown().strict().label("General Detail");
 
 // src/user/user-job-preferences.schema.ts
-import { array as array11, boolean as boolean14, date as date2, number as number10, object as object31, string as string29 } from "yup";
+import { array as array11, boolean as boolean14, date as date2, number as number11, object as object31, string as string29 } from "yup";
 var UserJobPreferencesSchema = object31({
   /**
    * Whether the job seeker is openly signalling availability. Surfaces the
@@ -2412,7 +2465,7 @@ var UserJobPreferencesSchema = object31({
    * Defaults to 0 ("any salary") rather than being optional - every job-seeker
    * has a floor, even if it's zero.
    */
-  minSalary: number10().integer().min(MIN_SALARY_LOWER_BOUND).max(MIN_SALARY_UPPER_BOUND).default(0).required().label("Minimum Salary"),
+  minSalary: number11().integer().min(MIN_SALARY_LOWER_BOUND).max(MIN_SALARY_UPPER_BOUND).default(0).required().label("Minimum Salary"),
   minSalaryCurrency: string29().oneOf(SupportedSalaryCurrencies).default("USD").required().label("Minimum Salary Currency"),
   /**
    * Marketing-attribution capture from the final onboarding step.
@@ -2439,7 +2492,7 @@ var UserJobPreferencesSchema = object31({
       id: string29().required().label("ID"),
       url: string29().required().label("Resume URL"),
       filename: string29().trim().max(255).optional().label("Filename"),
-      sizeBytes: number10().integer().min(0).optional().label("Size (bytes)"),
+      sizeBytes: number11().integer().min(0).optional().label("Size (bytes)"),
       mimeType: string29().trim().max(120).optional().label("MIME Type"),
       uploadedAt: date2().required().label("Uploaded At"),
       isPrimary: boolean14().default(false).label("Is Primary")
@@ -2569,7 +2622,7 @@ var UserSchema = object34({
   marketingConsent: object34({
     subscribed: boolean15().default(false).label("Subscribed to marketing email"),
     /** Epoch ms of the last consent change (opt-in or opt-out). */
-    updatedAt: number11().optional().label("Consent updated at"),
+    updatedAt: number12().optional().label("Consent updated at"),
     /** Where the consent change originated, e.g. `onboarding`, `unsubscribe`, `settings`. */
     source: string32().optional().label("Consent source"),
     /**
@@ -2609,7 +2662,7 @@ var UserSchema = object34({
    * Only generated for public profiles with sufficient completeness (≥60%).
    */
   embedding: object34({
-    vector: array14(number11().required()).optional().label("Embedding vector"),
+    vector: array14(number12().required()).optional().label("Embedding vector"),
     model: string32().optional().label("Embedding model")
   }).nullable().optional().label("Embedding")
 }).concat(UserGeneralDetailSchema).concat(UserJobPreferencesSchema).concat(UserRecruiterProfileSchema).concat(UserCoordinatorProfileSchema).noUnknown().strict().label("User Schema");
@@ -2710,6 +2763,7 @@ export {
   SYSTEM_DATE_FORMAT,
   SavedSearchSchema,
   SavedSearchStatus,
+  SignupContextSource,
   SkillSchema,
   SocialAccount,
   SocialAccountSchema,
@@ -2743,6 +2797,7 @@ export {
   SupportedResourceTypes,
   SupportedSalaryCurrencies,
   SupportedSavedSearchStatuses,
+  SupportedSignupContextSources,
   SupportedSocialAccounts,
   SupportedStudyTypes,
   SupportedUserProfileVisibilities,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thejob/schema",
-  "version": "2.1.4",
+  "version": "2.1.6",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/job/job.schema.ts

@@ -69,8 +69,18 @@ export const JobSchema = object({
 
   workMode: string().required().label("Work mode"),
 
+  /**
+   * `conceptId`/`conceptName` carry the taxonomy-service normalization. They are
+   * picked here (not just `name`/`logo`) because SkillSchema is `.noUnknown()`:
+   * an unpicked field that is actually PRESENT fails validation, so omitting them
+   * would reject every normalized job.
+   */
   skills: array()
-    .of(SkillSchema.pick(["name", "logo"]).required().label("Skill"))
+    .of(
+      SkillSchema.pick(["name", "logo", "conceptId", "conceptName"])
+        .required()
+        .label("Skill"),
+    )
     .nullable()
     .optional()
     .label("Skills"),

package/src/skill/skill.schema.ts

@@ -3,6 +3,29 @@ import { DbDefaultSchema } from "../common/common.schema.js";
 
 export const SkillSchema = object({
   name: string().trim().required().label("Skill Name"),
+
+  /**
+   * The taxonomy concept this skill resolved to, assigned by thejob-taxonomy-service
+   * via `POST /normalize/batch`. Stable slug, e.g. "power-bi".
+   *
+   * Normalization is ADDITIVE and never authoritative over `name`: the raw string a
+   * job was posted with is always preserved, and these two fields are written
+   * alongside it. That is what makes a wrong match, a taxonomy re-run, or a service
+   * outage recoverable rather than a data loss.
+   *
+   * Optional and nullable because they genuinely are absent in two normal cases,
+   * neither of which is an error:
+   *   - the term did not resolve (~22% of mentions are a long tail the taxonomy has
+   *     no concept for yet), and the raw `name` stands alone;
+   *   - the document predates normalization and has not been re-processed.
+   *
+   * Consumers must therefore read `conceptName ?? name`, never `conceptName` alone.
+   */
+  conceptId: string().optional().nullable().label("Concept ID"),
+
+  /** Canonical display name for `conceptId`, e.g. "Power BI". See `conceptId`. */
+  conceptName: string().optional().nullable().label("Concept Name"),
+
   logo: object({
     light: string().required().label("Light Logo"),
     dark: string().optional().nullable().label("Dark Logo"),

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",