@thejob/schema 1.0.106 → 2.0.0

package/src/pagination/pagination.constant.ts

@@ -0,0 +1,20 @@
+export type PaginatedResponse<T> = {
+  results: T[];
+  limit: number;
+  page: number;
+  total: number;
+  sortDirection?: "asc" | "desc";
+  sortBy?: string;
+};
+
+export const DefaultPaginatedResponse = {
+  results: [],
+  total: 0,
+  page: 1,
+  limit: 10,
+};
+
+export const DefaultPaginationOptions = {
+  page: 1,
+  limit: 10,
+};

package/src/pagination/pagination.schema.ts

@@ -0,0 +1,13 @@
+import { number, object, string } from "yup";
+
+export const PaginationSchema = object().shape({
+  page: number().required().min(1).label("Page").default(1),
+  limit: number().required().min(1).max(100).label("Limit").default(10),
+  sortBy: string().notOneOf([""]).optional().label("SortBy"),
+  nextPage: string().optional().label("Next Page Token"),
+  prevPage: string().optional().label("Previous Page Token"),
+  sortDirection: string()
+    .oneOf(["asc", "desc"])
+    .optional()
+    .label("Sort Direction"),
+});

package/src/skill/skill.schema.ts

@@ -0,0 +1,19 @@
+import { array, object, string } from "yup";
+import { DbDefaultSchema } from "../common/common.schema.js";
+
+export const SkillSchema = object({
+  name: string().trim().required().label("Skill Name"),
+  logo: object({
+    light: string().required().label("Light Logo"),
+    dark: string().optional().nullable().label("Dark Logo"),
+  })
+    .optional()
+    .nullable()
+    .default(null)
+    .label("Logo"),
+  tags: array().of(string().max(50)).max(20).optional().label("Tags"),
+})
+  .concat(DbDefaultSchema)
+  .noUnknown()
+  .strict()
+  .label("Skill");

package/src/social-account/social-account.constant.ts

@@ -0,0 +1,33 @@
+export enum SocialAccount {
+  Facebook = "facebook",
+  Twitter = "twitter",
+  LinkedIn = "linkedin",
+  Instagram = "instagram",
+  YouTube = "youtube",
+  Pinterest = "pinterest",
+  Snapchat = "snapchat",
+  TikTok = "tiktok",
+  WhatsApp = "whatsapp",
+  Telegram = "telegram",
+  Reddit = "reddit",
+  Tumblr = "tumblr",
+  Medium = "medium",
+  Quora = "quora",
+  GitHub = "github",
+  GitLab = "gitlab",
+  Bitbucket = "bitbucket",
+  StackOverflow = "stackoverflow",
+  Behance = "behance",
+  Dribbble = "dribbble",
+  Vimeo = "vimeo",
+  Flickr = "flickr",
+  SoundCloud = "soundcloud",
+  Spotify = "spotify",
+  Twitch = "twitch",
+  Discord = "discord",
+  Clubhouse = "clubhouse",
+  Website = "website",
+  Other = "other",
+}
+
+export const SupportedSocialAccounts = Object.values(SocialAccount);

package/src/social-account/social-account.schema.ts

@@ -0,0 +1,18 @@
+import { boolean, object, string } from "yup";
+import { SupportedSocialAccounts } from "./social-account.constant.js";
+export const SocialAccountSchema = object()
+  .shape({
+    // TODO: Remove isNew — it's unused. Backend (user-social-accounts.service.ts) just strips it before saving.
+    isNew: boolean().default(false).optional().label("Is New"),
+    type: string()
+      .oneOf(SupportedSocialAccounts)
+      .required()
+      .label("Account Type"),
+    url: string()
+      // .urlStrict()
+      .required()
+      .label("URL"),
+  })
+  .noUnknown()
+  .strict()
+  .label("Social Account");

package/src/user/education.schema.ts

@@ -0,0 +1,37 @@
+import { boolean, object, ObjectSchema, string } from "yup";
+import { PageSchema } from "../page/page.schema.js";
+import { SupportedStudyTypes } from "../common/common.constant.js";
+import { LocationSchema } from "../location/location.schema.js";
+import {
+  DurationSchema,
+  type TDurationSchema,
+} from "../duration/duration.schema.js";
+
+export const EducationSchema = object({
+  institute: PageSchema.pick(["name", "slug", "type", "logo"])
+    .deepPartial()
+    .concat(PageSchema.pick(["name", "type"]))
+    .required()
+    .label("Institute"),
+  course: string().trim().required().label("Course"),
+  fieldOfStudy: string().trim().required().label("Field of Study"),
+  duration: <ObjectSchema<TDurationSchema>>DurationSchema({
+    format: "YYYY-MM",
+    startLabel: "Start Date",
+    endLabel: "End Date",
+  })
+    .required()
+    .label("Duration"),
+  description: string().trim().max(3000).optional().label("Description"),
+  isDistanceLearning: boolean().default(false).label("Is Distance Learning"),
+  location: LocationSchema.required().label("Location"),
+  studyType: string()
+    .oneOf(SupportedStudyTypes)
+    .trim()
+    .max(50)
+    .required()
+    .label("Study Type"),
+})
+  .noUnknown()
+  .strict()
+  .label("Education");

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

@@ -0,0 +1,48 @@
+import { object, string } from "yup";
+import { SupportedExperienceLevels } from "../common/common.constant.js";
+import { LocationSchema } from "../location/location.schema.js";
+import {
+  SupportedUserProfileVisibilities,
+  UserProfileVisibility,
+} from "./user.constant.js";
+
+export const UserGeneralDetailSchema = object({
+  id: string().optional().label("ID"),
+  name: object()
+    .shape({
+      first: string().trim().max(50).required().label("First Name"),
+      last: string().trim().max(50).optional().label("Last Name"),
+    })
+    .required()
+    .label("Name"),
+  headline: string().trim().max(200).optional().label("Headline"),
+  image: string().optional().label("Image"),
+  aboutMe: string().trim().max(3000).optional().label("About Me"),
+  email: string()
+    // .emailStrict() // TODO: Enable strict email validation.
+    .required()
+    .label("Email"),
+  mobile: string().nullable().optional().label("Mobile"),
+  emailVerified: string().nullable().optional().label("Email Verified"),
+  mobileVerified: string().nullable().optional().label("Mobile Verified"),
+  experienceLevel: string()
+    .oneOf(SupportedExperienceLevels)
+    .required()
+    .label("Experience level"),
+  location: LocationSchema.required().label("Location"),
+  region: object()
+    .shape({
+      country: string().trim().required().label("Region Country"),
+      lang: string().trim().required().label("Region Language"),
+    })
+    .optional()
+    .default(undefined)
+    .label("Region"),
+  profileVisibility: string()
+    .oneOf(SupportedUserProfileVisibilities)
+    .default(UserProfileVisibility.Public)
+    .label("Profile Visibility"),
+})
+  .noUnknown()
+  .strict()
+  .label("General Detail");

package/src/user/project.schema.ts

@@ -0,0 +1,27 @@
+import { object, string } from "yup";
+import { DurationSchema } from "../duration/duration.schema.js";
+
+export const UserProjectSchema = object({
+  name: string().trim().max(50).required().label("Name"),
+  url: string()
+    // .urlStrict() // TODO: Enable strict URL validation.
+    .optional()
+    .label("URL"),
+  description: string()
+    .trim()
+    .min(100)
+    .max(3000)
+    .required()
+    .label("Description"),
+  duration: DurationSchema({
+    format: "YYYY-MM",
+    startLabel: "Start Date",
+    endLabel: "End Date",
+  })
+    .optional()
+    .nullable()
+    .label("Duration"),
+})
+  .noUnknown()
+  .strict()
+  .label("Project");

package/src/user/user-additional-info.schema.ts

@@ -0,0 +1,9 @@
+import { object, string } from "yup";
+
+export const UserAdditionalInfoSchema = object({
+  title: string().trim().max(60).required().label("Title"),
+  description: string().trim().max(1000).required().label("Description"),
+})
+  .noUnknown()
+  .strict()
+  .label("User Additional Info");

package/src/user/user-certification.schema.ts

@@ -0,0 +1,24 @@
+import { object, string } from "yup";
+import { DurationSchema } from "../duration/duration.schema.js";
+
+export const UserCertificationSchema = object({
+  name: string().trim().max(100).required().label("Name"),
+  // TODO: Add validation for authority
+  authority: string().trim().max(100).required().label("Authority"),
+  licenseNumber: string().trim().max(50).optional().label("License Number"),
+  duration: DurationSchema({
+    format: "YYYY-MM",
+    startLabel: "Start Date",
+    endLabel: "End Date",
+  })
+    .optional()
+    .nullable()
+    .label("Duration"),
+  url: string()
+    // .urlStrict() // TODO: Add url validation
+    .optional()
+    .label("URL"),
+})
+  .noUnknown()
+  .strict()
+  .label("Certification");

package/src/user/user-completeness.schema.ts

@@ -0,0 +1,21 @@
+import { object } from "yup";
+import { CompletenessScoreSchema } from "../common/common.schema.js";
+import { UserDetailType } from "./user.constant.js";
+
+export const UserCompletenessSchema = object({
+  additionalInfo: CompletenessScoreSchema(0).label("Additional Info"), // Optional
+  certifications: CompletenessScoreSchema(0).label("Certifications"), // Optional
+  educations: CompletenessScoreSchema().label("Educations"),
+  general: CompletenessScoreSchema().label("General"),
+  overview: CompletenessScoreSchema().label("Overview"),
+  interests: CompletenessScoreSchema(0).label("Interests"), // Optional
+  languages: CompletenessScoreSchema().label("Languages"),
+  projects: CompletenessScoreSchema(0).label("Projects"), // Optional
+  skills: CompletenessScoreSchema().label("Skills"),
+  socialAccounts: CompletenessScoreSchema(0).label("Social Accounts"), // Optional
+  workExperiences: CompletenessScoreSchema().label("Work Experience"),
+});
+
+export const StudentCompletenessSchema = UserCompletenessSchema.omit([
+  UserDetailType.WorkExperiences,
+]);

package/src/user/user-coordinator-profile.schema.ts

@@ -0,0 +1,45 @@
+import { array, object, string } from "yup";
+import { PageSchema } from "../page/page.schema.js";
+
+/**
+ * A link between a coordinator user and an Institute Page they coordinate
+ * at. A coordinator can be linked to multiple institutes (e.g. a placement
+ * officer across two campuses), and their `jobTitle` is per-link rather
+ * than global.
+ *
+ * The `page` field stores a denormalised snapshot (name/slug/type/logo) of
+ * the linked Page, mirroring the convention `RecruiterPageLinkSchema` and
+ * `WorkExperienceSchema.company` already use. The full Page document
+ * lives in the `pages` collection and is identified by `slug`.
+ */
+export const CoordinatorPageLinkSchema = object({
+  page: PageSchema.pick(["name", "slug", "type", "logo"])
+    .deepPartial()
+    .concat(PageSchema.pick(["name", "type"]))
+    .required()
+    .label("Institute Page"),
+  jobTitle: string().trim().max(100).optional().label("Job Title"),
+})
+  .noUnknown()
+  .strict()
+  .label("Coordinator Page Link");
+
+/**
+ * Coordinator-role-specific fields on UserSchema. All optional at the field
+ * level — presence is gated by `UserRole.Coordinator` in the user's
+ * `roles`, not by schema branching, so the user shape stays flat.
+ */
+export const UserCoordinatorProfileSchema = object({
+  coordinatorProfile: object({
+    coordinatesAt: array()
+      .of(CoordinatorPageLinkSchema)
+      .default([])
+      .label("Coordinates At"),
+  })
+    .optional()
+    .default(undefined)
+    .label("Coordinator Profile"),
+})
+  .noUnknown()
+  .strict()
+  .label("User Coordinator Profile");

package/src/user/user-interest.schema.ts

@@ -0,0 +1,3 @@
+import { string } from "yup";
+
+export const UserInterestSchema = string().trim().required().label("Interest");

package/src/user/user-job-preferences.schema.ts

@@ -0,0 +1,208 @@
+import { array, boolean, date, number, object, string } from "yup";
+
+import { SupportedExperienceLevels } from "../common/common.constant.js";
+import { LocationSchema } from "../location/location.schema.js";
+import { SocialAccountSchema } from "../social-account/social-account.schema.js";
+import { EducationSchema } from "./education.schema.js";
+import {
+  MIN_SALARY_LOWER_BOUND,
+  MIN_SALARY_UPPER_BOUND,
+  SupportedJobSearchUrgencies,
+  SupportedReferralSources,
+  SupportedSalaryCurrencies,
+} from "./user.constant.js";
+import { WorkExperienceSchema } from "./work-experience.schema.js";
+
+/**
+ * Onboarding-derived job-search preferences for a job-seeker.
+ *
+ * These fields live on the user document in the NestJS-managed `users`
+ * collection. Auth-server (Better Auth) only mirrors `roles`; everything in
+ * this sub-schema is owned by the API.
+ *
+ * The schema is `concat()`-ed into `UserSchema` so the fields are flat on the
+ * user (matches the wizard's PATCH payload shape).
+ */
+export const UserJobPreferencesSchema = object({
+  /**
+   * Whether the job seeker is openly signalling availability. Surfaces the
+   * "Open to work" badge on the public profile and boosts visibility in
+   * recruiter search. Defaults to `false` — users must opt in.
+   */
+  openToWork: boolean().default(false).label("Open to Work"),
+
+  /**
+   * How urgently the user is looking for their next job. Drives match scoring
+   * and can downgrade the visibility of expired or low-relevance postings for
+   * users in `passively_browsing` mode.
+   */
+  jobSearchUrgency: string()
+    .oneOf(SupportedJobSearchUrgencies)
+    .required()
+    .label("Job Search Urgency"),
+
+  /**
+   * Locations the user wants to work in. Stores the full `LocationSchema`
+   * shape (country, city, state, geo, etc.) as returned by the locations
+   * autocomplete API.
+   */
+  jobLocations: array()
+    .of(LocationSchema.required().label("Job Location"))
+    .min(1, "Pick at least one preferred location.")
+    .required()
+    .label("Job Locations"),
+
+  /**
+   * Seniority levels the user wants jobs to be matched against. Multi-select
+   * (up to 2) for borderline candidates.
+   *
+   * Distinct from the singular `experienceLevel` field on `UserSchema`
+   * (concat'd via `UserGeneralDetailSchema`) — that field captures the user's
+   * own current seniority, while these are the levels they want to *target*.
+   * Both reuse the same `ExperienceLevel` taxonomy from `common.constant.ts`
+   * so search/match logic doesn't have to translate between two vocabularies.
+   */
+  targetExperienceLevels: array()
+    .of(string().oneOf(SupportedExperienceLevels).required())
+    .min(1, "Pick at least one experience level.")
+    .max(2, "You can select at most 2 experience levels.")
+    .required()
+    .label("Target Experience Levels"),
+
+  /**
+   * Specializations the user is searching for — free-form titles.
+   *
+   * Job titles are an open vocabulary (think O*NET, ESCO, LinkedIn's title
+   * graph), so the schema only enforces length bounds per entry. The wizard
+   * surfaces a curated "Popular Roles" picker for discovery, but the user
+   * can ultimately add any title; matching/normalization happens downstream.
+   */
+  jobRoles: array()
+    .of(string().trim().max(120).required())
+    .min(1, "Pick at least one role.")
+    .required()
+    .label("Job Roles"),
+
+  /**
+   * Minimum acceptable annual base salary, in `minSalaryCurrency`.
+   * Stored as an integer in the currency's major unit (e.g. dollars, not cents).
+   * Defaults to 0 ("any salary") rather than being optional — every job-seeker
+   * has a floor, even if it's zero.
+   */
+  minSalary: number()
+    .integer()
+    .min(MIN_SALARY_LOWER_BOUND)
+    .max(MIN_SALARY_UPPER_BOUND)
+    .default(0)
+    .required()
+    .label("Minimum Salary"),
+
+  minSalaryCurrency: string()
+    .oneOf(SupportedSalaryCurrencies)
+    .default("USD")
+    .required()
+    .label("Minimum Salary Currency"),
+
+  /**
+   * Marketing-attribution capture from the final onboarding step.
+   */
+  referralSource: string()
+    .oneOf(SupportedReferralSources)
+    .required()
+    .label("Referral Source"),
+
+  /**
+   * Resumes the user has uploaded. Embedded directly on the user document
+   * (capped at 5) — they're cheap to denormalize, every wizard step that
+   * cares about them is already loading the user doc, and the cap keeps the
+   * subdoc bounded.
+   *
+   * The binary itself lives in object storage (GCS); only a stable URL/key
+   * the API can sign for download is kept here.
+   *
+   * Distinct from the `Resumes` collection used by the (currently unused)
+   * AI resume-builder flow — onboarding uploads land here, AI-built resumes
+   * live in their own collection.
+   */
+  resumes: array()
+    .of(
+      object({
+        // Stable id assigned on upload — used to address a specific entry
+        // for delete / set-primary operations without exposing the GCS URL
+        // as a route key.
+        id: string().required().label("ID"),
+        url: string().required().label("Resume URL"),
+        filename: string().trim().max(255).optional().label("Filename"),
+        sizeBytes: number().integer().min(0).optional().label("Size (bytes)"),
+        mimeType: string().trim().max(120).optional().label("MIME Type"),
+        uploadedAt: date().required().label("Uploaded At"),
+        isPrimary: boolean().default(false).label("Is Primary"),
+      })
+        .noUnknown()
+        .strict()
+        .label("Resume"),
+    )
+    .max(5, "You can keep at most 5 resumes on file.")
+    .default([])
+    .label("Resumes"),
+
+  /**
+   * Set when the user finishes the wizard's last step. Acts as the gate the
+   * onboarding hook checks to redirect users who haven't completed setup.
+   */
+  onboardingCompletedAt: date()
+    .nullable()
+    .optional()
+    .label("Onboarding Completed At"),
+
+  /**
+   * Parser-suggested values for wizard fields, written by the resume-upload
+   * flow. Every parser-derived field lands here — including profile-shaped
+   * fields (headline, aboutMe, mobile, location, experienceLevel,
+   * socialAccounts, workExperiences, educations) — so nothing reaches the
+   * top-level user document until the user confirms it on the matching
+   * wizard step. When a user clicks Next on a step, the API drops the
+   * matching key from this sub-doc so a re-uploaded resume can't overwrite
+   * confirmed answers.
+   *
+   * READ RULE — strict:
+   *   `pendingPrefill.<field>` is ONLY for seeding a wizard step's form
+   *   initial value (e.g. `prefer(user.<field>, user.pendingPrefill?.<field>)`
+   *   in a step's `load`). It is NOT the user's actual value — it's an
+   *   unconfirmed suggestion. Never substitute it as a fallback in profile
+   *   pages, search/match, recommendations, public profile, dashboards, or
+   *   APIs. If `user.<field>` is empty there, the correct behavior is empty,
+   *   because the user has not confirmed it yet.
+   */
+  pendingPrefill: object({
+    headline: string().trim().optional().label("Pending Headline"),
+    aboutMe: string().trim().optional().label("Pending About Me"),
+    mobile: string().trim().optional().label("Pending Mobile"),
+    location: LocationSchema.optional()
+      .default(undefined)
+      .label("Pending Location"),
+    experienceLevel: string()
+      .oneOf(SupportedExperienceLevels)
+      .optional()
+      .label("Pending Experience Level"),
+    socialAccounts: array()
+      .of(SocialAccountSchema.required())
+      .optional()
+      .label("Pending Social Accounts"),
+    workExperiences: array()
+      .of(WorkExperienceSchema.required())
+      .optional()
+      .label("Pending Work Experiences"),
+    educations: array()
+      .of(EducationSchema.required())
+      .optional()
+      .label("Pending Educations"),
+  })
+    .nullable()
+    .optional()
+    .default(undefined)
+    .label("Pending Prefill"),
+})
+  .noUnknown()
+  .strict()
+  .label("User Job Preferences Schema");

package/src/user/user-language.schema.ts

@@ -0,0 +1,15 @@
+import { object, string } from "yup";
+import { SupportedProficiencyLevels } from "./user.constant.js";
+
+export const UserLanguageSchema = object({
+  name: string().trim().required().label("Name"),
+  proficiencyLevel: string()
+    .oneOf(SupportedProficiencyLevels)
+    .trim()
+    .max(50)
+    .required()
+    .label("Proficiency Level"),
+})
+  .noUnknown()
+  .strict()
+  .label("Language");

package/src/user/user-recruiter-profile.schema.ts

@@ -0,0 +1,45 @@
+import { array, object, string } from "yup";
+import { PageSchema } from "../page/page.schema.js";
+
+/**
+ * A link between a recruiter user and a company Page they hire for.
+ * A single recruiter can be linked to multiple pages (e.g. a founder at one
+ * company who also recruits for an agency client), and their `jobTitle` is
+ * per-link rather than global.
+ *
+ * The `page` field stores a denormalised snapshot (name/slug/type/logo) of
+ * the linked Page, mirroring the convention `WorkExperienceSchema.company`
+ * already uses. The full Page document lives in the `pages` collection and
+ * is identified by `slug`.
+ */
+export const RecruiterPageLinkSchema = object({
+  page: PageSchema.pick(["name", "slug", "type", "logo"])
+    .deepPartial()
+    .concat(PageSchema.pick(["name", "type"]))
+    .required()
+    .label("Company Page"),
+  jobTitle: string().trim().max(100).optional().label("Job Title"),
+})
+  .noUnknown()
+  .strict()
+  .label("Recruiter Page Link");
+
+/**
+ * Recruiter-role-specific fields on UserSchema. All optional at the field
+ * level — presence is gated by `UserRole.Recruiter` in the user's `roles`,
+ * not by schema branching, so the user shape stays flat.
+ */
+export const UserRecruiterProfileSchema = object({
+  recruiterProfile: object({
+    hiringFor: array()
+      .of(RecruiterPageLinkSchema)
+      .default([])
+      .label("Hiring For"),
+  })
+    .optional()
+    .default(undefined)
+    .label("Recruiter Profile"),
+})
+  .noUnknown()
+  .strict()
+  .label("User Recruiter Profile");

package/src/user/user-skill.schema.ts

@@ -0,0 +1,19 @@
+import { object, string } from "yup";
+import { dateString } from "../extensions/date-string.extension.js";
+import { SupportedProficiencyLevels } from "./user.constant.js";
+
+export const UserSkillSchema = object({
+  name: string().required().label("Name"),
+  proficiencyLevel: string()
+    .oneOf(SupportedProficiencyLevels)
+    .required()
+    .label("Proficiency Level"),
+  lastUsed: dateString()
+    .format("YYYY-MM")
+    .nullable()
+    .optional()
+    .label("Last Used"),
+})
+  .noUnknown()
+  .strict()
+  .label("Skill");