@thejob/schema 2.0.4 → 2.0.6

package/src/job/job-taxonomy.util.ts

@@ -0,0 +1,111 @@
+import {
+  JOB_TAXONOMY,
+  type JobCategory,
+  type JobIndustry,
+  type JobSubCategory,
+} from "./job-taxonomy.constant.js";
+
+/**
+ * Taxonomy lookups + industry derivation.
+ *
+ * Hand-written (unlike job-taxonomy.constant.ts, which is generated) — the generator
+ * will not overwrite this file.
+ *
+ * WHY DERIVE INDUSTRY INSTEAD OF ASKING FOR IT
+ * `industry` is redundant: every subCategory name is globally unique and every industry
+ * belongs to exactly one category, so a subCategory already determines both. Asking an
+ * LLM to pick the industry *as well* asks it to re-derive what it just implied — and
+ * measured across ~57k enriched jobs it derived differently 15.9% of the time (e.g.
+ * "Data Science" filed under "Software & Web Development" rather than "Data, AI &
+ * Analytics"). 89.5% of those were a sibling industry under the SAME category: the right
+ * neighbourhood, the wrong box. Deriving in code removes that failure mode entirely
+ * rather than validating against it — a mismatch must never cost us the posting.
+ *
+ * WHY CATEGORY IS STILL ASKED FOR, NOT DERIVED
+ * The reverse (derive category from the subCategory too) measured 98.5% agreement, but
+ * the disagreements showed the MODEL was usually right and the tree wrong: a "Financial
+ * Analyst" tagged `business_intelligence` derives to Technology, while the model said
+ * Finance — and it is a finance job that uses BI tools. The category captures what the
+ * job IS; a subCategory's position in the tree does not. So the model keeps choosing it.
+ */
+
+/** subCategory -> the industry that owns it. */
+const INDUSTRY_OF_SUB = new Map<string, JobIndustry>(
+  JOB_TAXONOMY.flatMap((c) =>
+    c.industries.flatMap((i) => i.subCategories.map((s) => [s, i.industry] as const)),
+  ),
+);
+
+/** subCategory -> the category that owns it (via its industry). */
+const CATEGORY_OF_SUB = new Map<string, JobCategory>(
+  JOB_TAXONOMY.flatMap((c) =>
+    c.industries.flatMap((i) => i.subCategories.map((s) => [s, c.category] as const)),
+  ),
+);
+
+/** industry -> the category that owns it. */
+const CATEGORY_OF_INDUSTRY = new Map<string, JobCategory>(
+  JOB_TAXONOMY.flatMap((c) => c.industries.map((i) => [i.industry, c.category] as const)),
+);
+
+/** The industry a subCategory belongs to, or undefined if it is not a known subCategory. */
+export function industryOfSubCategory(sub: string): JobIndustry | undefined {
+  return INDUSTRY_OF_SUB.get(sub);
+}
+
+/** The category a subCategory belongs to, or undefined if unknown. */
+export function categoryOfSubCategory(sub: string): JobCategory | undefined {
+  return CATEGORY_OF_SUB.get(sub);
+}
+
+/** The category an industry belongs to, or undefined if unknown. */
+export function categoryOfIndustry(industry: string): JobCategory | undefined {
+  return CATEGORY_OF_INDUSTRY.get(industry);
+}
+
+/** The industries under a category (empty if the category is unknown). */
+export function industriesOfCategory(category: string): readonly JobIndustry[] {
+  return JOB_TAXONOMY.find((c) => c.category === category)?.industries.map((i) => i.industry) ?? [];
+}
+
+/** The subCategories under an industry (empty if the industry is unknown). */
+export function subCategoriesOfIndustry(industry: string): readonly JobSubCategory[] {
+  for (const c of JOB_TAXONOMY) {
+    for (const i of c.industries) if (i.industry === industry) return i.subCategories;
+  }
+  return [];
+}
+
+/**
+ * Derive a job's industry from its category + subCategories. This is the function that
+ * replaces asking the model for `industry`.
+ *
+ * Rule: the first subCategory that sits INSIDE the given category wins. Preferring the
+ * category keeps the model's judgement about what the job is (see the file header) while
+ * still deriving a structurally coherent industry; measured on ~57k jobs, 98.7% of those
+ * with a real category and real subCategories have at least one subCategory inside it.
+ *
+ * Falls back, in order:
+ *  1. no category given -> the first known subCategory's own industry;
+ *  2. no subCategory sits in the category -> undefined (caller keeps whatever it had,
+ *     or stores null; we never drop a posting over this).
+ *
+ * Order matters: `subCategories` is the model's own ranking, most relevant first.
+ */
+export function deriveIndustry(
+  category: string | null | undefined,
+  subCategories: readonly string[] | null | undefined,
+): JobIndustry | undefined {
+  const subs = (subCategories ?? []).filter((s) => INDUSTRY_OF_SUB.has(s));
+  if (subs.length === 0) return undefined;
+
+  if (category) {
+    const inCategory = subs.find((s) => CATEGORY_OF_SUB.get(s) === category);
+    if (inCategory) return INDUSTRY_OF_SUB.get(inCategory);
+    // The model's subCategories all sit outside its chosen category. Rather than force
+    // an industry that contradicts the category, leave it unset.
+    return undefined;
+  }
+
+  return INDUSTRY_OF_SUB.get(subs[0]);
+}

package/src/job/job.schema.ts

@@ -196,6 +196,24 @@ export const JobSchema = object({
 
   jdSummary: string().optional().label("JD Summary"),
 
+  /**
+   * Structured, model-extracted sections of the posting, re-organized into clean
+   * bullet points. This is our OWN unique presentation of the job (rendered as the
+   * primary, server-side page content) so the page adds value over the raw scraped
+   * description and is not penalized by Google as duplicate content. All sections
+   * optional: absent on jobs not yet (re-)enriched, and any section is `[]`/omitted
+   * when the posting genuinely has none.
+   */
+  jobHighlights: object({
+    responsibilities: array().of(string()).optional().label("Responsibilities"),
+    requirements: array().of(string()).optional().label("Requirements"),
+    benefits: array().of(string()).optional().label("Benefits"),
+    qualifications: array().of(string()).optional().label("Qualifications"),
+  })
+    .nullable()
+    .optional()
+    .label("Job Highlights"),
+
   canCreateAlert: boolean().optional().label("Can create alert"),
 
   canDirectApply: boolean().optional().label("Can direct apply"),
@@ -233,6 +251,18 @@ export const JobSchema = object({
 
   reports: array().of(UserIdAndCreatedAtSchema).optional().label("Reports"),
 
+  // Taxonomy fields are constants (see job-taxonomy.constant.ts), stored as slugs and
+  // translated for display. They are deliberately NOT `oneOf`-constrained here: a value
+  // outside the taxonomy must be DROPPED, never a reason to reject the posting. Yup
+  // `oneOf` fails the whole object, so one stale subCategory would cost a user their
+  // entire job on the create/edit form, and a single drifted LLM value would bin an
+  // otherwise-good enriched job.
+  //
+  // Callers sanitize instead: jobs-service's sanitizeTaxonomy() coerces unknown values
+  // to null / filters them out of the array before validation. Taxonomies change over
+  // time (values get renamed, retired, added), so stored jobs will always outlive the
+  // enum — being lenient here is what lets the taxonomy evolve without a migration
+  // gate on every write.
   category: string().nullable().optional().label("Category"),
 
   industry: string().nullable().optional().label("Industry"),

package/src/post/post.constant.ts

@@ -0,0 +1,7 @@
+export enum PostStatus {
+  Draft = "draft",
+  Published = "published",
+  Archived = "archived",
+}
+
+export const SupportedPostStatuses = Object.values(PostStatus);

package/src/post/post.schema.ts

@@ -0,0 +1,68 @@
+import { array, boolean, number, object, string } from "yup";
+import type { InferType } from "yup";
+import { DbDefaultSchema } from "../common/common.schema.js";
+import { PostStatus, SupportedPostStatuses } from "./post.constant.js";
+
+export const PostSchema = object({
+  /** Headline shown in listings and at the top of the post. */
+  title: string().required().min(5).max(200).label("Title"),
+
+  /** User-friendly, unique URL identifier. */
+  slug: string().required().max(250).label("Slug"),
+
+  /** Short summary used in listings and meta description fallback. */
+  excerpt: string().max(500).optional().label("Excerpt"),
+
+  /** Rendered HTML source of truth for the post body (sanitized on write/render).
+   *  Supports rich formatting markdown can't express (image size/alignment, etc). */
+  bodyHTML: string().required().min(1).label("Body (HTML)"),
+
+  /** Optional Markdown mirror of the body (portable text / search fallback).
+   *  Kept for back-compat and plain-text derivation; bodyHTML is authoritative. */
+  bodyMarkdown: string().optional().label("Body (Markdown)"),
+
+  /** Cover/hero image URL. Not `.url()`-validated: the value is either an
+   *  uploaded file URL served by this platform (which may be a bare host like
+   *  `http://localhost:3082/...` in dev, that yup's `.url()` wrongly rejects) or
+   *  an admin-pasted link. Kept as a plain string; empty ⇒ null. */
+  coverImage: string().nullable().optional().label("Cover image"),
+
+  /** Author (user id). */
+  authorId: string().required().label("Author ID"),
+
+  /** Free-form tags for filtering and related-posts. */
+  tags: array().of(string().trim().required()).default([]).label("Tags"),
+
+  /** Estimated reading time in minutes (server-derived from body length). */
+  readingTimeMinutes: number()
+    .min(0)
+    .optional()
+    .label("Reading time (minutes)"),
+
+  /** SEO overrides. */
+  seoTags: object({
+    description: string().optional().label("Description"),
+    keywords: array().of(string().required()).optional().label("Keywords"),
+  })
+    .nullable()
+    .optional()
+    .label("SEO Tags"),
+
+  /** When the post was first published (epoch ms). Server-owned. */
+  publishedAt: number().nullable().optional().label("Published at"),
+
+  /** Whether the post is featured in the blog listing. */
+  isFeatured: boolean().default(false).optional().label("Is featured"),
+
+  /** Publication state. */
+  status: string()
+    .oneOf(SupportedPostStatuses)
+    .default(PostStatus.Draft)
+    .required()
+    .label("Status"),
+})
+  .concat(DbDefaultSchema)
+  .noUnknown()
+  .label("Post");
+
+export type TPostSchema = InferType<typeof PostSchema>;