openings 0.1.0

package/src/career-tracing.ts

@@ -0,0 +1,181 @@
+import { readFile } from "node:fs/promises";
+import { atomicJson } from "./atomic-file.ts";
+import { assertCompatibleReport, stampReport, type ReportMeta } from "./report-meta.ts";
+import { mergeSourceCandidates } from "./source-discovery.ts";
+import { resolveSource } from "./source-verification.ts";
+import { fetchSafeHead, type HeadTransport, type ResolveHost } from "./safe-head.ts";
+import type { SourceCandidate } from "./types.ts";
+import { deriveLeadState, mergeEnrichmentLeads, type EnrichmentLead, type IdentityEvidence } from "./enrichment-registry.ts";
+
+type Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+
+interface CompanySeed { companyName: string; companyDomain: string; careerUrl?: string }
+interface TraceIssue { companyName?: string; companyDomain?: string; careerUrls?: string[]; reason: string; detail: string }
+interface TraceOptions { country?: string; fetch?: Fetch; concurrency?: number; timeoutMs?: number; searchKey?: string; commonCrawlReportPath?: string; resolveHost?: ResolveHost; headTransport?: HeadTransport; registryPath?: string }
+
+export interface CareerTraceReport extends ReportMeta {
+  companiesChecked: number;
+  ready: number;
+  alreadyKnown: number;
+  unresolved: number;
+  rejected: number;
+  failures: number;
+  candidatesPath: string;
+  reportPath: string;
+  unresolvedCompanies: TraceIssue[];
+  rejections: TraceIssue[];
+  failureDetails: TraceIssue[];
+  matched: number;
+  registryPath?: string;
+  registryAdded: number;
+}
+
+export async function traceCareerSources(inputPath: string, candidatesPath: string, reportPath: string, options: TraceOptions = {}): Promise<CareerTraceReport> {
+  const seeds = await readSeeds(inputPath);
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const concurrency = Math.max(1, Math.trunc(options.concurrency ?? 10));
+  const timeoutMs = Math.max(1, Math.trunc(options.timeoutMs ?? 15_000));
+  const country = options.country?.toUpperCase();
+  if (country && !/^[A-Z]{2}$/.test(country)) throw new Error("country must be a two-letter code");
+  const candidates: Array<{ index: number; candidate: SourceCandidate }> = [];
+  const commonCrawlLeads = options.commonCrawlReportPath ? await readCommonCrawlLeads(options.commonCrawlReportPath) : [];
+  const unresolved: Array<{ index: number; issue: TraceIssue }> = [];
+  const rejected: Array<{ index: number; issue: TraceIssue }> = [];
+  const failures: Array<{ index: number; issue: TraceIssue }> = [];
+  const registryRows: EnrichmentLead[] = [];
+  let matched = 0;
+  let cursor = 0;
+
+  async function worker() {
+    while (cursor < seeds.length) {
+      const index = cursor++;
+      const seed = seeds[index]!;
+      const invalid = validateSeed(seed);
+      if (invalid) { rejected.push({ index, issue: { ...identity(seed), reason: "invalid_company", detail: invalid } }); continue; }
+      const careerUrls = seed.careerUrl ? [seed.careerUrl] : ["careers", "career", "jobs"].map((path) => `https://${seed.companyDomain}/${path}`);
+      let found: ReturnType<typeof resolveSource> = null;
+      let reference = careerUrls[0]!;
+      let channel: "career_page" | "search" | "dataset" = "career_page";
+      if (options.searchKey) {
+        try {
+          const result = await searchForSource(seed, options.searchKey, fetcher, country);
+          if (result) { found = result.source; reference = result.reference; channel = "search"; }
+        } catch (error) {
+          failures.push({ index, issue: { ...identity(seed), reason: "search_failed", detail: error instanceof Error ? error.message : String(error) } });
+        }
+      }
+      if (!found) {
+        for (const careerUrl of careerUrls) {
+          try {
+            const result = await fetchSafeHead(careerUrl, { resolveHost: options.resolveHost, transport: options.headTransport, timeoutMs });
+            if (!result.response.ok) continue;
+            const source = resolveSource(result.finalUrl);
+            if (source) { found = source; reference = careerUrl; break; }
+          } catch (error) {
+            failures.push({ index, issue: { ...identity(seed), careerUrls: [careerUrl], reason: "career_request_failed", detail: error instanceof Error ? error.message : String(error) } });
+          }
+        }
+      }
+      if (!found) {
+        const lead = commonCrawlLeads.find((item) => sourceMatchesCompany(item.source.token, seed));
+        if (lead) { found = lead.source; reference = lead.reference; channel = "dataset"; }
+      }
+      if (!found) {
+        unresolved.push({ index, issue: { ...identity(seed), careerUrls, reason: "ats_not_resolved", detail: "Career URLs did not redirect to a supported structured job source" } });
+        continue;
+      }
+      const companyName = seed.companyName.trim();
+      const companyDomain = normalizeDomain(seed.companyDomain);
+      const companyMatch = { companyName, companyDomain, method: "normalized_token" as const, reference };
+      const identityEvidence: IdentityEvidence[] = channel === "career_page" ? [{ companyName, companyDomain, kind: "company_redirect", reference, observedAt: new Date().toISOString() }] : [];
+      const lead: EnrichmentLead = { sourceKey: `${found.ats}:${found.token.toLowerCase()}`, sourceUrl: found.canonicalSourceUrl, ats: found.ats, token: found.token,
+        discoveredFrom: [{ channel, reference }], companyMatches: [companyMatch], identityEvidence, attempts: [] };
+      registryRows.push(lead);
+      if (deriveLeadState(lead) !== "evidence_ready") { matched += 1; continue; }
+      candidates.push({ index, candidate: {
+        companyName, companyDomain, sourceUrl: found.canonicalSourceUrl,
+        cohorts: country ? [country] : undefined,
+        discoveredFrom: { channel, reference },
+        domainEvidence: channel === "career_page" ? { kind: "company_redirect", reference } : undefined,
+      } });
+    }
+  }
+
+  await Promise.all(Array.from({ length: Math.min(concurrency, seeds.length) }, worker));
+  const registry = options.registryPath ? await mergeEnrichmentLeads(options.registryPath, registryRows) : { added: 0 };
+  const additions = candidates.sort((a, b) => a.index - b.index).map((row) => row.candidate);
+  const appended = await mergeSourceCandidates(candidatesPath, additions);
+  const report: CareerTraceReport = stampReport("career-tracing:1", 1, {
+    companiesChecked: seeds.length, ready: appended, alreadyKnown: additions.length - appended,
+    unresolved: unresolved.length, rejected: rejected.length, failures: failures.length, matched, candidatesPath, reportPath, registryPath: options.registryPath, registryAdded: registry.added,
+    unresolvedCompanies: unresolved.sort((a, b) => a.index - b.index).map((row) => row.issue),
+    rejections: rejected.sort((a, b) => a.index - b.index).map((row) => row.issue),
+    failureDetails: failures.sort((a, b) => a.index - b.index).map((row) => row.issue),
+  });
+  await atomicJson(reportPath, report);
+  return report;
+}
+
+async function readCommonCrawlLeads(path: string) {
+  const value: unknown = JSON.parse(await readFile(path, "utf8"));
+  assertCompatibleReport(value, "common-crawl-discovery:1", 1);
+  if (!isRecord(value) || !Array.isArray(value.leads)) throw new Error("Common Crawl report must contain a leads array");
+  return value.leads.flatMap((lead) => {
+    if (!isRecord(lead) || typeof lead.sourceUrl !== "string") return [];
+    const source = resolveSource(lead.sourceUrl);
+    if (!source) return [];
+    const reference = isRecord(lead.discoveredFrom) && typeof lead.discoveredFrom.reference === "string" ? lead.discoveredFrom.reference : path;
+    return [{ source, reference }];
+  });
+}
+
+async function searchForSource(seed: CompanySeed, key: string, fetcher: Fetch, country?: string) {
+  const url = new URL("https://api.search.brave.com/res/v1/web/search");
+  url.searchParams.set("q", `\"${seed.companyName}\" (site:job-boards.greenhouse.io OR site:jobs.lever.co OR site:jobs.ashbyhq.com OR site:myworkdayjobs.com OR site:recruitee.com)`);
+  url.searchParams.set("count", "20");
+  if (country) url.searchParams.set("country", country);
+  const response = await fetcher(url, { headers: { Accept: "application/json", "X-Subscription-Token": key } });
+  if (!response.ok) throw new Error(`Brave Search returned HTTP ${response.status}`);
+  const value: unknown = await response.json();
+  const results = isRecord(value) && isRecord(value.web) && Array.isArray(value.web.results) ? value.web.results : [];
+  for (const result of results) {
+    if (!isRecord(result) || typeof result.url !== "string") continue;
+    const source = resolveSource(result.url);
+    if (source && sourceMatchesCompany(source.token, seed)) return { source, reference: result.url };
+  }
+  return null;
+}
+
+async function readSeeds(path: string): Promise<CompanySeed[]> {
+  const value: unknown = JSON.parse(await readFile(path, "utf8"));
+  if (!Array.isArray(value) || !value.every(isRecord)) throw new Error("Company input must be a JSON array of objects");
+  return value as unknown as CompanySeed[];
+}
+
+function validateSeed(seed: CompanySeed): string | null {
+  if (typeof seed.companyName !== "string" || !seed.companyName.trim()) return "companyName is required";
+  if (typeof seed.companyDomain !== "string" || !/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(seed.companyDomain)) return "companyDomain must be a hostname";
+  if (seed.careerUrl !== undefined) {
+    try {
+      const url = new URL(seed.careerUrl);
+      if (url.protocol !== "https:") return "careerUrl must use HTTPS";
+      const domain = normalizeDomain(seed.companyDomain);
+      const host = normalizeDomain(url.hostname);
+      if (host !== domain && !host.endsWith(`.${domain}`)) return "careerUrl must belong to companyDomain";
+    }
+    catch { return "careerUrl must be a valid URL"; }
+  }
+  return null;
+}
+
+function normalizeDomain(value: string): string { return value.toLowerCase().replace(/^www\./, ""); }
+function sourceMatchesCompany(token: string, seed: CompanySeed): boolean {
+  const normalize = (value: string) => value.toLowerCase().replace(/\b(inc|llc|ltd|limited|corp|corporation|company)\b/g, "").replace(/[^a-z0-9]/g, "");
+  const workdayTenant = token.includes("myworkdayjobs.com/") ? token.split("/")[1] : undefined;
+  const source = normalize(workdayTenant ?? token);
+  const name = normalize(seed.companyName);
+  const domain = normalize(normalizeDomain(seed.companyDomain).split(".")[0] ?? "");
+  return source.length >= 3 && (source === name || source === domain);
+}
+function identity(seed: Partial<CompanySeed>) { return { companyName: seed.companyName, companyDomain: seed.companyDomain }; }
+function isRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }

package/src/catalog.ts

@@ -0,0 +1,382 @@
+import type { Company, Job, JobSummary, SearchQuery } from "./types.ts";
+import { classifyJob, isEligibleForCountry, normalizeLocation } from "./locations.ts";
+
+type Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+
+export interface Catalog {
+  search(query: SearchQuery): Promise<JobSummary[]>;
+  get(id: string): Promise<Job | null>;
+}
+
+interface CatalogOptions {
+  companies: Company[];
+  fetch?: Fetch;
+  cacheTtlMs?: number;
+}
+
+interface GreenhouseJob {
+  id: number;
+  title: string;
+  location: { name: string };
+  absolute_url: string;
+  updated_at?: string;
+  content?: string;
+}
+
+interface LeverJob {
+  id: string;
+  text: string;
+  hostedUrl: string;
+  categories?: { location?: string };
+  descriptionPlain?: string;
+  workplaceType?: string;
+  createdAt?: number;
+}
+
+interface AshbyJob {
+  id: string;
+  title: string;
+  location?: string;
+  isRemote?: boolean;
+  jobUrl: string;
+  descriptionPlain?: string;
+  publishedAt?: string;
+}
+
+interface WorkdayJob {
+  title: string;
+  externalPath: string;
+  locationsText?: string;
+  postedOn?: string;
+  bulletFields?: string[];
+}
+
+interface RecruiteeJob {
+  guid: string;
+  title: string;
+  city?: string;
+  state_name?: string;
+  country_code?: string;
+  remote?: boolean;
+  hybrid?: boolean;
+  on_site?: boolean;
+  careers_url: string;
+  updated_at?: string;
+  published_at?: string;
+  description?: string;
+  requirements?: string;
+  translations?: Record<string, { description?: string; requirements?: string; title?: string }>;
+}
+
+export function createCatalog(options: CatalogOptions): Catalog {
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const cache = new Map<string, { expiresAt: number; jobs: Promise<Job[]> }>();
+
+  async function fetchJobs(company: Company): Promise<Job[]> {
+    const cached = cache.get(company.slug);
+    if (cached && cached.expiresAt > Date.now()) return cached.jobs;
+    const jobs = fetchSourceJobs(company, fetcher);
+    cache.set(company.slug, { expiresAt: Date.now() + (options.cacheTtlMs ?? 5 * 60_000), jobs });
+    try {
+      return await jobs;
+    } catch (error) {
+      cache.delete(company.slug);
+      throw error;
+    }
+  }
+
+  return {
+    async search(query) {
+      const jobs = (await Promise.all(options.companies.map((company) => fetchJobs(company).catch(() => [])))).flat();
+
+      return searchJobs(jobs, query);
+    },
+    async get(id) {
+      const [ats, slug] = id.split(":", 3);
+      const company = options.companies.find((candidate) => candidate.ats === ats && candidate.slug === slug);
+      if (!company) return null;
+      let job = (await fetchJobs(company)).find((candidate) => candidate.id === id) ?? null;
+      if (job && company.ats === "workday" && !job.description.trim()) {
+        const description = await fetchWorkdayDescription(company, job.url, fetcher);
+        job = { ...job, description };
+      }
+      if (job && !job.description.trim()) throw new Error(`Full description unavailable for job: ${id}`);
+      return job;
+    },
+  };
+}
+
+export function searchJobs(jobs: Job[], query: SearchQuery): JobSummary[] {
+  return jobs.filter((job) => matches(job, query)).slice(0, query.limit ?? 50).map(toSummary);
+}
+
+export interface FetchJobsObserver {
+  onBackoff?(event: { status: number; delayMs: number }): void;
+  workdayPageDelayMs?: number;
+  pacingNow?: () => number;
+  pacingSleep?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+}
+export async function fetchSourceJobs(company: Company, fetcher: Fetch = globalThis.fetch, signal?: AbortSignal, observer?: FetchJobsObserver): Promise<Job[]> {
+  if (company.ats === "workday") return fetchWorkdayJobs(company, fetcher, signal, observer);
+  const url = company.ats === "greenhouse"
+    ? `https://boards-api.greenhouse.io/v1/boards/${encodeURIComponent(company.token)}/jobs?content=true`
+    : company.ats === "lever"
+      ? `https://api.lever.co/v0/postings/${encodeURIComponent(company.token)}?mode=json`
+      : company.ats === "ashby"
+        ? `https://api.ashbyhq.com/posting-api/job-board/${encodeURIComponent(company.token)}`
+        : `https://${encodeURIComponent(company.token)}.recruitee.com/api/offers`;
+  const response = await fetchWithRetry(fetcher, url, signal ? { signal } : undefined, company.name, observer);
+  if (!response.ok) { await response.body?.cancel().catch(() => undefined); throw new Error(`${company.name} job board returned HTTP ${response.status}`); }
+  const body = await response.json();
+  return company.ats === "greenhouse"
+    ? (body as { jobs: GreenhouseJob[] }).jobs.map((job) => normalizeGreenhouse(company, job))
+    : company.ats === "lever"
+      ? (body as LeverJob[]).map((job) => normalizeLever(company, job))
+      : company.ats === "ashby"
+        ? (body as { jobs: AshbyJob[] }).jobs.map((job) => normalizeAshby(company, job))
+        : (body as { offers: RecruiteeJob[] }).offers.map((job) => normalizeRecruitee(company, job));
+}
+
+async function fetchWorkdayJobs(company: Company, fetcher: Fetch, signal?: AbortSignal, observer?: FetchJobsObserver): Promise<Job[]> {
+  const source = parseWorkdayToken(company.token);
+  const endpoint = `https://${source.host}/wday/cxs/${encodeURIComponent(source.tenant)}/${encodeURIComponent(source.site)}/jobs`;
+  const limit = 20;
+  const pageDelayMs = Math.max(0, Math.trunc(observer?.workdayPageDelayMs ?? 0));
+  const pacingNow = observer?.pacingNow ?? Date.now;
+  const pacingSleep = observer?.pacingSleep ?? abortableDelay;
+  let previousPageStart: number | undefined;
+  let pageGate = Promise.resolve();
+  async function pacePageStart() {
+    if (!pageDelayMs) return;
+    let release!: () => void;
+    const previous = pageGate;
+    pageGate = new Promise<void>((resolve) => { release = resolve; });
+    await previous;
+    try {
+      const remaining = previousPageStart === undefined ? 0 : previousPageStart + pageDelayMs - pacingNow();
+      if (remaining > 0) await pacingSleep(remaining, signal);
+      previousPageStart = pacingNow();
+    } finally { release(); }
+  }
+  async function page(offset: number): Promise<{ total: number; jobs: WorkdayJob[] }> {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      await pacePageStart();
+      const response = await fetcher(endpoint, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ appliedFacets: {}, limit, offset, searchText: "" }), signal });
+      if (response.ok) {
+        const body = await response.json() as { total?: unknown; jobPostings?: unknown };
+        if (!Number.isInteger(body.total) || !Array.isArray(body.jobPostings)) throw new Error(`${company.name} Workday source returned an invalid payload`);
+        return { total: body.total as number, jobs: body.jobPostings as WorkdayJob[] };
+      }
+      if (!isTransientStatus(response.status) || attempt === 2) { await response.body?.cancel().catch(() => undefined); throw new Error(`${company.name} job board returned HTTP ${response.status}`); }
+      const delayMs = retryDelayMs(response, attempt);
+      observer?.onBackoff?.({ status: response.status, delayMs });
+      await response.body?.cancel().catch(() => undefined);
+      await abortableDelay(delayMs, signal);
+    }
+    throw new Error(`${company.name} Workday source exhausted retries`);
+  }
+  const first = await page(0);
+  if (first.total < first.jobs.length || first.total > 100_000) throw new Error(`${company.name} Workday source reported an invalid total`);
+  const offsets = Array.from({ length: Math.ceil(first.total / limit) - 1 }, (_, index) => (index + 1) * limit);
+  const pages = new Array<WorkdayJob[]>(offsets.length);
+  let cursor = 0;
+  async function worker() {
+    while (cursor < offsets.length) {
+      const index = cursor++;
+      const offset = offsets[index]!;
+      const result = await page(offset);
+      if (result.jobs.length === 0 && offset < first.total) throw new Error(`${company.name} Workday source truncated at offset ${offset} of ${first.total}`);
+      pages[index] = result.jobs;
+    }
+  }
+  const workerCount = pageDelayMs > 0 ? 1 : Math.min(4, offsets.length);
+  await Promise.all(Array.from({ length: workerCount }, worker));
+  const jobs = [first.jobs, ...pages].flat().slice(0, first.total);
+  if (jobs.length !== first.total) throw new Error(`${company.name} Workday source returned ${jobs.length} of ${first.total} jobs`);
+  return jobs.map((job) => normalizeWorkday(company, source, job));
+}
+
+async function fetchWithRetry(fetcher: Fetch, input: string | URL, init: RequestInit | undefined, companyName: string, observer?: FetchJobsObserver): Promise<Response> {
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const response = await fetcher(input, init);
+    if (response.ok || !isTransientStatus(response.status)) return response;
+    if (attempt === 2) {
+      await response.body?.cancel().catch(() => undefined);
+      throw new Error(`${companyName} job board returned HTTP ${response.status}`);
+    }
+    const delayMs = retryDelayMs(response, attempt);
+    observer?.onBackoff?.({ status: response.status, delayMs });
+    await response.body?.cancel().catch(() => undefined);
+    await abortableDelay(delayMs, init?.signal ?? undefined);
+  }
+  throw new Error(`${companyName} job source exhausted retries`);
+}
+
+export function isTransientStatus(status: number): boolean {
+  return status === 429 || status === 502 || status === 503 || status === 504 || status === 520;
+}
+
+export function retryDelayMs(response: Response, attempt: number): number {
+  const value = response.headers.get("retry-after");
+  if (value !== null) {
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.min(30_000, seconds * 1_000);
+    const date = Date.parse(value);
+    if (Number.isFinite(date)) return Math.min(30_000, Math.max(0, date - Date.now()));
+  }
+  return 500 * 2 ** attempt;
+}
+
+export function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  if (!ms) return Promise.resolve();
+  if (signal?.aborted) return Promise.reject(signal.reason ?? new Error("Aborted"));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("Aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function normalizeWorkday(company: Company, source: ReturnType<typeof parseWorkdayToken>, job: WorkdayJob): Job {
+  const location = job.locationsText ?? "Unspecified";
+  const requisition = job.bulletFields?.[0] ?? job.externalPath.split("_").at(-1) ?? job.externalPath;
+  return classifyJob({
+    id: `workday:${company.slug}:${requisition}`,
+    company: company.name,
+    title: job.title,
+    location,
+    remote: /remote/i.test(location),
+    workMode: /remote/i.test(location) ? "remote" : "unknown",
+    eligibleCountries: [], excludedCountries: [], eligibleRegions: [], eligibilityConfidence: "unknown",
+    url: `https://${source.host}/en-US/${source.site}${job.externalPath}`,
+    description: "",
+  });
+}
+
+async function fetchWorkdayDescription(company: Company, jobUrl: string, fetcher: Fetch): Promise<string> {
+  const source = parseWorkdayToken(company.token);
+  const path = new URL(jobUrl).pathname.replace(new RegExp(`^/en-US/${escapeRegExp(source.site)}`), "");
+  const response = await fetcher(`https://${source.host}/wday/cxs/${encodeURIComponent(source.tenant)}/${encodeURIComponent(source.site)}${path}`);
+  if (!response.ok) throw new Error(`${company.name} job detail returned HTTP ${response.status}`);
+  const body = await response.json() as { jobPostingInfo?: { jobDescription?: unknown } };
+  if (typeof body.jobPostingInfo?.jobDescription !== "string") throw new Error(`${company.name} job detail returned an invalid payload`);
+  return stripHtml(body.jobPostingInfo.jobDescription);
+}
+
+function parseWorkdayToken(token: string): { host: string; tenant: string; site: string } {
+  const [host, tenant, site, ...rest] = token.split("/");
+  if (!host || !tenant || !site || rest.length) throw new Error(`Invalid Workday source token: ${token}`);
+  return { host, tenant, site };
+}
+
+function escapeRegExp(value: string): string { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
+
+function normalizeAshby(company: Company, job: AshbyJob): Job {
+  const location = job.location ?? "Unspecified";
+  return classifyJob({
+    id: `ashby:${company.slug}:${job.id}`,
+    company: company.name,
+    title: job.title,
+    location,
+    remote: job.isRemote ?? /remote/i.test(location),
+    workMode: job.isRemote ? "remote" : "unknown",
+    eligibleCountries: [],
+    excludedCountries: [],
+    eligibleRegions: [],
+    eligibilityConfidence: "unknown",
+    url: job.jobUrl,
+    updatedAt: job.publishedAt,
+    description: job.descriptionPlain ?? "",
+  });
+}
+
+function normalizeLever(company: Company, job: LeverJob): Job {
+  const location = job.categories?.location ?? "Unspecified";
+  return classifyJob({
+    id: `lever:${company.slug}:${job.id}`,
+    company: company.name,
+    title: job.text,
+    location,
+    remote: job.workplaceType === "remote" || /remote/i.test(location),
+    workMode: job.workplaceType === "remote" ? "remote" : job.workplaceType === "hybrid" ? "hybrid" : job.workplaceType === "onsite" ? "onsite" : "unknown",
+    eligibleCountries: [],
+    excludedCountries: [],
+    eligibleRegions: [],
+    eligibilityConfidence: "unknown",
+    url: job.hostedUrl,
+    updatedAt: job.createdAt ? new Date(job.createdAt).toISOString() : undefined,
+    description: job.descriptionPlain ?? "",
+  });
+}
+
+function normalizeGreenhouse(company: Company, job: GreenhouseJob): Job {
+  const location = job.location?.name ?? "Unspecified";
+  return classifyJob({
+    id: `greenhouse:${company.slug}:${job.id}`,
+    company: company.name,
+    title: job.title,
+    location,
+    remote: /remote/i.test(location),
+    workMode: "unknown",
+    eligibleCountries: [],
+    excludedCountries: [],
+    eligibleRegions: [],
+    eligibilityConfidence: "unknown",
+    url: job.absolute_url,
+    updatedAt: job.updated_at,
+    description: stripHtml(job.content ?? ""),
+  });
+}
+
+function normalizeRecruitee(company: Company, job: RecruiteeJob): Job {
+  const location = [job.city, job.state_name, job.country_code?.toUpperCase()].filter(Boolean).join(", ") || "Unspecified";
+  const translation = job.translations?.en ?? Object.values(job.translations ?? {})[0];
+  const description = [translation?.description ?? job.description, translation?.requirements ?? job.requirements].filter(Boolean).map((value) => stripHtml(value!)).join("\n\n");
+  const updatedAt = job.updated_at ?? job.published_at;
+  return classifyJob({
+    id: `recruitee:${company.slug}:${job.guid}`,
+    company: company.name,
+    title: translation?.title ?? job.title,
+    location,
+    remote: job.remote === true,
+    workMode: job.remote ? "remote" : job.hybrid ? "hybrid" : job.on_site ? "onsite" : "unknown",
+    eligibleCountries: [], excludedCountries: [], eligibleRegions: [], eligibilityConfidence: "unknown",
+    url: job.careers_url,
+    ...(updatedAt ? { updatedAt: new Date(updatedAt).toISOString() } : {}),
+    description,
+  });
+}
+
+function matches(job: Job, query: SearchQuery): boolean {
+  const terms = query.query?.trim().toLocaleLowerCase().split(/\s+/).filter(Boolean) ?? [];
+  const location = query.location ? normalizeLocation(query.location) : undefined;
+  const searchable = `${job.title} ${job.company}`.toLocaleLowerCase();
+  return (terms.length === 0 || terms.every((term) => searchable.includes(term)))
+    && (!location || normalizeLocation(job.location).includes(location))
+    && (!query.country || isEligibleForCountry(job, query.country))
+    && (query.remote === undefined || job.remote === query.remote);
+}
+
+function toSummary(job: Job): JobSummary {
+  const { description: _description, ...summary } = job;
+  return summary;
+}
+
+function stripHtml(value: string): string {
+  return value
+    .replace(/<br\s*\/?\s*>/gi, "\n")
+    .replace(/<\/p>/gi, "\n\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}