@thejob/schema 2.0.1 → 2.0.3

package/package.json

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

package/src/common/common.constant.ts

@@ -1,3 +1,33 @@
+/**
+ * Common option keys shared across schemas. `Yes`/`No` are used by acknowledge
+ * questions; `Skill`/`EducationLevel`/`ExperienceLevel`/etc. tag where a choice
+ * question sources its options from. Migrated from schema v1.
+ */
+export enum Common {
+  Yes = "yes",
+  No = "no",
+  DateRangeOption = "date_range_option",
+  ExperienceLevel = "experience_level",
+  Company = "company",
+  EmploymentType = "employment_type",
+  WorkMode = "work_mode",
+  Location = "location",
+  CareerLevel = "career_level",
+  Category = "category",
+  Designation = "designation",
+  EducationLevel = "education_level",
+  Language = "language",
+  Skill = "skill",
+}
+
+// Common constants
+export const EMPTY_STRING = "eMpTyStRiNg";
+// DayJS formats: https://day.js.org/docs/en/display/format
+export const SYSTEM_DATE_FORMAT = "YYYY-MM-DD";
+export const DISPLAY_DATE_FORMAT = "LL";
+export const DISPLAY_DATE_FORMAT_SHORT = "MMMM, YYYY";
+export const SITEMAP_FORMAT = "YYYY-MM-DDThh:mm:ssZ";
+
 // Education-related enums
 export enum StudyType {
   FullTime = "full_time",

package/src/common/common.schema.ts

@@ -1,4 +1,5 @@
 import { boolean, number, object, string } from "yup";
+import type { InferType } from "yup";
 
 export const TermsAcceptedSchema = object({
   termsAccepted: boolean()
@@ -26,3 +27,16 @@ export const CompletenessScoreSchema = (minScore: number = 50) =>
     totalSteps: number().min(0).default(0).label("Total Steps"),
     completedSteps: number().min(0).default(0).label("Completed Steps"),
   });
+
+/**
+ * Tracks a user reference plus when the relation was created (bookmarks,
+ * applicants, reports on a job). The v1 `userId` used `.objectId()`; plain
+ * `string()` in v2.
+ */
+export const UserIdAndCreatedAtSchema = object().shape({
+  userId: string().required().label("User Id"),
+  createdAt: string().required().label("Created At"),
+});
+export type TUserIdAndCreatedAtSchema = InferType<
+  typeof UserIdAndCreatedAtSchema
+>;

package/src/index.ts

@@ -20,6 +20,17 @@ export * from "./extensions/date-string.extension.js";
 export * from "./group/group.schema.js";
 export * from "./group/group.constant.js";
 
+/**
+ * Job schemas and constants.
+ */
+export * from "./job/job.schema.js";
+export * from "./job/job.constant.js";
+
+/**
+ * Question schemas and constants (job questionnaire).
+ */
+export * from "./question/index.js";
+
 /**
  * Location schemas and constants.
  */

package/src/job/job.constant.ts

@@ -0,0 +1,66 @@
+export enum JobStatus {
+  Published = "published",
+  Draft = "draft",
+  Deleted = "deleted",
+  Closed = "closed",
+  Expired = "expired",
+}
+
+export const SupportedJobStatuses = Object.values(JobStatus);
+
+export enum EmploymentType {
+  Fulltime = "full_time",
+  PartTime = "part_time",
+  Temporary = "temporary",
+  Contract = "contract",
+  Internship = "internship",
+  Freelance = "freelance",
+  Volunteer = "volunteer",
+  PerDiem = "per_diem",
+}
+
+export const SupportedEmploymentTypes = Object.values(EmploymentType);
+
+export enum WorkMode {
+  OnSite = "on_site",
+  Hybrid = "hybrid",
+  Remote = "remote",
+}
+
+export const SupportedWorkModes = Object.values(WorkMode);
+
+export enum CompensationType {
+  Hourly = "hourly",
+  Weekly = "weekly",
+  Monthly = "monthly",
+  Yearly = "yearly",
+  OneTime = "one-time",
+  Other = "other",
+}
+
+export const SupportedCompensationTypes = Object.values(CompensationType);
+
+export enum EmployeeCount {
+  _1_2 = "1_2_employees",
+  _3_10 = "3_10_employees",
+  _11_100 = "11_100_employees",
+  _101_1000 = "101_1000_employees",
+  _1001_5000 = "1001_5000_employees",
+  _5001_10000 = "5001_10000_employees",
+  _10001_Plus = "10001_plus_employees",
+}
+
+export const SupportedEmployeeCounts = Object.values(EmployeeCount);
+
+export enum ApplicationReceivePreference {
+  Inbox = "inbox",
+  Email = "email",
+  ExternalWebsite = "external_website",
+}
+
+export const SupportedApplicationReceivePreferences = Object.values(
+  ApplicationReceivePreference,
+);
+
+// Note: ExperienceLevel lives in common.constant.ts (single source of truth);
+// it is intentionally not re-declared here.

package/src/job/job.schema.ts

@@ -0,0 +1,256 @@
+import { array, boolean, lazy, mixed, number, object, string } from "yup";
+import type { InferType, ObjectSchema } from "yup";
+import {
+  DbDefaultSchema,
+  UserIdAndCreatedAtSchema,
+} from "../common/common.schema.js";
+import {
+  SupportedEducationLevels,
+  SupportedExperienceLevels,
+  SYSTEM_DATE_FORMAT,
+} from "../common/common.constant.js";
+import { DurationSchema } from "../duration/duration.schema.js";
+import { LocationSchema } from "../location/location.schema.js";
+import { PageSchema } from "../page/page.schema.js";
+import { SkillSchema } from "../skill/skill.schema.js";
+import { QuestionType } from "../question/index.js";
+import type {
+  TChoiceQuestionSchema,
+  TInputQuestionSchema,
+  TQuestionSchema,
+  TReadAndAcknowledgeQuestionSchema,
+} from "../question/index.js";
+import { getSchemaByQuestion } from "../question/question.utils.js";
+import {
+  ApplicationReceivePreference,
+  JobStatus,
+  SupportedCompensationTypes,
+  SupportedJobStatuses,
+} from "./job.constant.js";
+
+export const JobSchema = object({
+  /** Unique id usable by external systems to reference the job. */
+  uniqueId: string().optional().label("Unique ID"),
+
+  /** Job title shown in listings and search. */
+  headline: string().required().min(5).max(150).label("Headline"),
+
+  /** User-friendly, unique URL identifier. */
+  slug: string().required().max(250).label("Slug"),
+
+  /** How applications are received (inbox vs external website). */
+  applicationReceivePreference: mixed<ApplicationReceivePreference>()
+    .oneOf([
+      ApplicationReceivePreference.Inbox,
+      ApplicationReceivePreference.ExternalWebsite,
+    ])
+    .required()
+    .label("Preference"),
+
+  /** Required when applicationReceivePreference is ExternalWebsite. */
+  externalApplyLink: string().when("applicationReceivePreference", {
+    is: (value: ApplicationReceivePreference) =>
+      value === ApplicationReceivePreference.ExternalWebsite,
+    then: (schema) => schema.url().required().label("Apply for Job link"),
+    otherwise: (schema) => schema.optional(),
+  }),
+
+  /** Company the job belongs to (subset of PageSchema). */
+  company: PageSchema.pick(["name", "slug", "type", "logo"])
+    .deepPartial()
+    .concat(PageSchema.pick(["name", "type"]))
+    .required()
+    .label("Company"),
+
+  /** @deprecated kept for backwards compatibility. */
+  designation: string().optional().nullable().label("Designation"),
+
+  employmentType: string().required().label("Employment type"),
+
+  workMode: string().required().label("Work mode"),
+
+  skills: array()
+    .of(SkillSchema.pick(["name", "logo"]).required().label("Skill"))
+    .nullable()
+    .optional()
+    .label("Skills"),
+
+  bookmarks: array().of(UserIdAndCreatedAtSchema).optional().label("Bookmarks"),
+
+  embedding: object({
+    vector: array(number().required()).optional().label("Embedding vector"),
+    model: string().optional().label("Embedding model"),
+  })
+    .nullable()
+    .optional()
+    .label("Embedding"),
+
+  applicants: array()
+    .of(UserIdAndCreatedAtSchema)
+    .optional()
+    .label("Applicants"),
+
+  applicantCount: number().optional().label("Applicant count"),
+
+  externalApplicationLinkClickCount: number()
+    .optional()
+    .label("External application link click count"),
+
+  description: string().required().min(100).max(50000).label("Description"),
+
+  descriptionMarkdown: string().required().label("Description Markdown"),
+
+  descriptionHTML: string().optional().label("Description HTML"),
+
+  /**
+   * Job locations. Required even for remote roles (compliance/legal). Defaults
+   * to an empty array; min(1) is intentionally not enforced yet.
+   */
+  locations: array().of(LocationSchema).default([]).label("Location"),
+
+  educationLevel: array(string().oneOf(SupportedEducationLevels))
+    .required()
+    .min(1)
+    .label("Educational level"),
+
+  /** Posting validity window (start/expiry). */
+  validity: DurationSchema({
+    format: SYSTEM_DATE_FORMAT,
+    startLabel: "Start Date",
+    endLabel: "Expiry Date",
+  }).label("Validity"),
+
+  /**
+   * When the auto-close system last re-checked this job's liveness (epoch ms).
+   * Server-owned operational field: set by the expiry re-crawl track when a job
+   * has no `validity.endDate` and must be verified by crawling its page. Guards
+   * re-check cadence so the same job is not re-crawled on every sweep.
+   */
+  lastExpiryCheckAt: number()
+    .optional()
+    .nullable()
+    .label("Last expiry check at"),
+
+  experienceLevel: string()
+    .oneOf(SupportedExperienceLevels)
+    .nullable()
+    .optional()
+    .label("Experience level"),
+
+  contactEmail: string().email().nullable().optional().label("Contact email"),
+
+  workingHoursPerWeek: number()
+    .nullable()
+    .optional()
+    .min(1)
+    .max(24 * 7)
+    .label("Working hours per week"),
+
+  tags: array().max(50).optional().label("Tags"),
+
+  /** Direct/Quick-apply questionnaire. Each item is validated against the
+   *  concrete question schema for its `type`, with the stored `answers` omitted. */
+  questionnaire: array()
+    .of(
+      lazy((question: TQuestionSchema) => {
+        const schema = getSchemaByQuestion(question.type);
+        if (question.type === QuestionType.Input) {
+          return (schema as ObjectSchema<TInputQuestionSchema>).omit([
+            "answers",
+          ]);
+        } else if (question.type === QuestionType.Choice) {
+          return (schema as ObjectSchema<TChoiceQuestionSchema>).omit([
+            "answers",
+          ]);
+        } else if (question.type === QuestionType.ReadAndAcknowledge) {
+          return (
+            schema as ObjectSchema<TReadAndAcknowledgeQuestionSchema>
+          ).omit(["answers"]);
+        }
+        return schema;
+      }),
+    )
+    .label("Questionnaire"),
+
+  status: string()
+    .oneOf(SupportedJobStatuses)
+    .default(JobStatus.Draft)
+    .required()
+    .label("Status"),
+
+  seoTags: object({
+    description: string().optional().label("Description"),
+    keywords: array().of(string()).optional().label("Keywords"),
+  })
+    .nullable()
+    .optional()
+    .label("SEO Tags"),
+
+  jdSummary: string().optional().label("JD Summary"),
+
+  canCreateAlert: boolean().optional().label("Can create alert"),
+
+  canDirectApply: boolean().optional().label("Can direct apply"),
+
+  hasApplied: boolean().optional().label("Has applied"),
+
+  isOwner: boolean().optional().label("Is owner"),
+
+  hasBookmarked: boolean().optional().label("Has bookmarked"),
+
+  hasReported: boolean().optional().label("Has reported"),
+
+  ratePerHour: number().optional().min(0).label("Rate per hour"),
+
+  isPromoted: boolean().optional().label("Is promoted"),
+
+  salaryRange: object({
+    currency: string().required().label("Currency").default("USD"),
+    min: number().nullable().optional().min(0).label("Minimum Salary"),
+    max: number().nullable().optional().min(0).label("Maximum Salary"),
+    compensationType: string()
+      .oneOf(SupportedCompensationTypes)
+      .nullable()
+      .optional()
+      .label("Compensation Type"),
+    isNegotiable: boolean()
+      .nullable()
+      .optional()
+      .default(true)
+      .label("Is Negotiable"),
+  })
+    .nullable()
+    .optional()
+    .label("Salary Range"),
+
+  reports: array().of(UserIdAndCreatedAtSchema).optional().label("Reports"),
+
+  category: string().nullable().optional().label("Category"),
+
+  industry: string().nullable().optional().label("Industry"),
+
+  subCategories: array()
+    .of(string().trim().required())
+    .nullable()
+    .optional()
+    .label("Sub Categories"),
+
+  termsAccepted: boolean()
+    .oneOf([true], "Accept terms before proceeding")
+    .required("Accept terms before proceeding")
+    .label("Terms accepted"),
+
+  isFeatured: boolean().optional().default(false).label("Is featured"),
+
+  /** Market country codes to feature this job in; empty = global. */
+  featuredMarkets: array()
+    .of(string().required())
+    .optional()
+    .default([])
+    .label("Featured markets"),
+})
+  .concat(DbDefaultSchema)
+  .noUnknown()
+  .label("Job");
+
+export type TJobSchema = InferType<typeof JobSchema>;

package/src/question/choice-question.schema.ts

@@ -0,0 +1,96 @@
+import { array, mixed, object, string } from "yup";
+import type { InferType } from "yup";
+import { Common } from "../common/common.constant.js";
+import {
+  AnswerChoiceType,
+  QuestionType,
+  SupportedAnswerChoiceTypes,
+} from "./question.constant.js";
+import { QuestionSchema } from "./question.schema.js";
+
+/**
+ * Validates that the selected answer(s) come from the question's own `options`.
+ * In v2 options and answers are plain strings (the v1 name/id/logo and "others"
+ * reference-object variants were dropped, matching the rest of the v2 schema).
+ */
+const ChoicePreferredAnswerSchema = (label: string = "Preferred answer") =>
+  mixed<string | string[]>().when("answerChoiceType", {
+    is: (value: AnswerChoiceType) => value === AnswerChoiceType.Multiple,
+    then: () =>
+      array(string())
+        .test(
+          "is-valid-option",
+          `${label} must be from the provided options`,
+          function (answer) {
+            const { options = [] } = this.parent;
+            if (answer && answer.length > 0) {
+              return answer.every((a) => options.includes(a));
+            }
+            return true;
+          },
+        )
+        .optional()
+        .label(label),
+    otherwise: () =>
+      string()
+        .test(
+          "is-valid-option",
+          `${label} must be from the provided options`,
+          function (answer) {
+            const { options = [] } = this.parent;
+            return !answer || options.includes(answer);
+          },
+        )
+        .optional()
+        .label(label),
+  });
+
+const getChoiceAnswerSchema = (
+  answerChoiceType: AnswerChoiceType,
+  isOptional: boolean,
+) => {
+  if (answerChoiceType === AnswerChoiceType.Multiple) {
+    const multiAnswerSchema = array(string().max(500));
+    return isOptional
+      ? multiAnswerSchema.optional().default([])
+      : multiAnswerSchema
+          .min(1, "Select at least one option.")
+          .required("Select at least one option.")
+          .default([]);
+  }
+  // Single choice
+  const singleAnswerSchema = string().max(500);
+  return isOptional
+    ? singleAnswerSchema.optional()
+    : singleAnswerSchema.required("Select an option.");
+};
+
+export const ChoiceQuestionSchema = QuestionSchema.concat(
+  object().shape({
+    type: string()
+      .oneOf([QuestionType.Choice])
+      .required()
+      .label("Question type"),
+    optionsFrom: string()
+      .oneOf([Common.Skill, Common.EducationLevel, Common.ExperienceLevel])
+      .optional()
+      .label("Option field"),
+    options: array(string().required())
+      .min(1)
+      .required()
+      .label("Options"),
+    answerChoiceType: string()
+      .oneOf(SupportedAnswerChoiceTypes)
+      .required()
+      .default(AnswerChoiceType.Single)
+      .label("Type"),
+    preferredAnswer: ChoicePreferredAnswerSchema("Preferred answer"),
+    answers: mixed<string | string[]>().when(
+      ["answerChoiceType", "isOptional"],
+      ([answerChoiceType, isOptional]) =>
+        getChoiceAnswerSchema(answerChoiceType, isOptional),
+    ),
+  }),
+);
+
+export type TChoiceQuestionSchema = InferType<typeof ChoiceQuestionSchema>;

package/src/question/index.ts

@@ -0,0 +1,6 @@
+export * from "./question.constant.js";
+export * from "./question.schema.js";
+export * from "./input-question.schema.js";
+export * from "./choice-question.schema.js";
+export * from "./read-and-acknowledge.schema.js";
+export * from "./question.utils.js";

package/src/question/input-question.schema.ts

@@ -0,0 +1,24 @@
+import { object, string } from "yup";
+import type { InferType } from "yup";
+import { QuestionType } from "./question.constant.js";
+import { QuestionSchema } from "./question.schema.js";
+
+export const InputQuestionSchema = QuestionSchema.concat(
+  object().shape({
+    type: string()
+      .oneOf([QuestionType.Input])
+      .required()
+      .label("Question type"),
+    preferredAnswer: string().max(100).optional().label("Preferred Answer"),
+    answers: string()
+      .max(500)
+      .when("isOptional", {
+        is: (isOptional: boolean) => Boolean(isOptional),
+        then: (schema) => schema.optional(),
+        otherwise: (schema) => schema.required(),
+      })
+      .label("Answer"),
+  }),
+);
+
+export type TInputQuestionSchema = InferType<typeof InputQuestionSchema>;

package/src/question/question.constant.ts

@@ -0,0 +1,14 @@
+export enum QuestionType {
+  Input = "input",
+  Choice = "choice",
+  ReadAndAcknowledge = "readAndAcknowledge",
+}
+
+export const SupportedQuestionTypes = Object.values(QuestionType);
+
+export enum AnswerChoiceType {
+  Single = "single",
+  Multiple = "multiple",
+}
+
+export const SupportedAnswerChoiceTypes = Object.values(AnswerChoiceType);

package/src/question/question.schema.ts

@@ -0,0 +1,22 @@
+import { boolean, object, string } from "yup";
+import { SupportedQuestionTypes } from "./question.constant.js";
+import type { TChoiceQuestionSchema } from "./choice-question.schema.js";
+import type { TInputQuestionSchema } from "./input-question.schema.js";
+import type { TReadAndAcknowledgeQuestionSchema } from "./read-and-acknowledge.schema.js";
+
+/** Base fields shared by every question variant. The concrete variants concat
+ *  their own `type`-narrowed fields onto this (see input/choice/acknowledge). */
+export const QuestionSchema = object().shape({
+  label: string().max(50).optional().label("Label"),
+  default: boolean().optional().default(false).label("Default"),
+  title: string().required().max(200).label("Title"),
+  type: string().oneOf(SupportedQuestionTypes).required().label("Type"),
+  isOptional: boolean().optional().label("Mark if the question is optional"),
+  readonly: boolean().optional().label("Readonly"),
+  isNew: boolean().optional().label("Is New"),
+});
+
+export type TQuestionSchema =
+  | TInputQuestionSchema
+  | TChoiceQuestionSchema
+  | TReadAndAcknowledgeQuestionSchema;

package/src/question/question.utils.ts

@@ -0,0 +1,23 @@
+import type { ObjectSchema } from "yup";
+import { ChoiceQuestionSchema } from "./choice-question.schema.js";
+import { InputQuestionSchema } from "./input-question.schema.js";
+import { QuestionType } from "./question.constant.js";
+import type { TQuestionSchema } from "./question.schema.js";
+import { ReadAndAcknowledgeQuestionSchema } from "./read-and-acknowledge.schema.js";
+
+/** Resolve the concrete question schema for a question's `type`. Drives the
+ *  `lazy` validation of the job questionnaire. */
+export const getSchemaByQuestion = (
+  type: QuestionType,
+): ObjectSchema<TQuestionSchema> => {
+  switch (type) {
+    case QuestionType.Input:
+      return InputQuestionSchema as unknown as ObjectSchema<TQuestionSchema>;
+    case QuestionType.Choice:
+      return ChoiceQuestionSchema as unknown as ObjectSchema<TQuestionSchema>;
+    case QuestionType.ReadAndAcknowledge:
+      return ReadAndAcknowledgeQuestionSchema as unknown as ObjectSchema<TQuestionSchema>;
+    default:
+      throw new Error("Unsupported schema: " + type);
+  }
+};

package/src/question/read-and-acknowledge.schema.ts

@@ -0,0 +1,25 @@
+import { object, string } from "yup";
+import type { InferType } from "yup";
+import { Common } from "../common/common.constant.js";
+import { QuestionType } from "./question.constant.js";
+import { QuestionSchema } from "./question.schema.js";
+
+const AcknowledgeAnswerSchema = string()
+  .oneOf([Common.Yes, Common.No])
+  .required("This question must be acknowledged.");
+
+export const ReadAndAcknowledgeQuestionSchema = QuestionSchema.concat(
+  object().shape({
+    type: string()
+      .oneOf([QuestionType.ReadAndAcknowledge])
+      .required()
+      .label("Question type"),
+    description: string().max(10000).required().label("Content"),
+    preferredAnswer: AcknowledgeAnswerSchema.label("Preferred Answer"),
+    answers: AcknowledgeAnswerSchema.label("Answer"),
+  }),
+);
+
+export type TReadAndAcknowledgeQuestionSchema = InferType<
+  typeof ReadAndAcknowledgeQuestionSchema
+>;