openings 0.1.2 → 0.1.4

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "openings",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "A free, candidate-safe job-search substrate for AI agents",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/abhay-avagama/hiring-agent.git" },
   "homepage": "https://github.com/abhay-avagama/hiring-agent#readme",
   "bugs": { "url": "https://github.com/abhay-avagama/hiring-agent/issues" },
-  "keywords": ["jobs", "resume", "matching", "mcp", "greenhouse", "lever", "ashby", "workday", "recruitee"],
+  "keywords": ["jobs", "resume", "matching", "mcp", "greenhouse", "lever", "ashby", "workday", "recruitee", "smartrecruiters", "workable", "breezy"],
   "type": "module",
   "bin": { "openings-mcp": "./src/package-mcp.ts" },
   "exports": "./src/index.ts",

package/src/board-verification.ts

@@ -0,0 +1,182 @@
+import { atomicJson } from "./atomic-file.ts";
+import { readEnrichmentRegistry, mergeEnrichmentLeads, type EnrichmentLead, type LeadAttempt } from "./enrichment-registry.ts";
+import { withFileLock } from "./file-lock.ts";
+import { providerSpec } from "./providers.ts";
+import { resolveSource } from "./source-verification.ts";
+import type { Ats, Company, SourceVerification } from "./types.ts";
+
+type Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+
+/** Providers whose public board is accepted as identity on its own. Workday stays on the company-identity path because its crawls are expensive. */
+export const BOARD_TIER_PROVIDERS: ReadonlySet<Ats> = new Set(["greenhouse", "lever", "ashby", "recruitee", "smartrecruiters", "workable", "breezy"]);
+
+export interface BoardVerificationOptions {
+  fetch?: Fetch;
+  now?: () => Date;
+  limit?: number;
+  concurrency?: number;
+  timeoutMs?: number;
+  /** Days before a board that permanently failed is probed again. */
+  cooldownDays?: number;
+}
+
+export interface BoardVerificationReport {
+  generatedAt: string;
+  considered: number;
+  selected: number;
+  skipped: { inCatalog: number; coolingDown: number; unsupported: number; deferred: number };
+  verified: number;
+  added: string[];
+  rejected: Array<{ sourceKey: string; reason: "unreachable" | "invalid_payload" | "empty_board" | "duplicate_slug"; detail: string }>;
+  catalogSize: number;
+}
+
+type CatalogEntry = Omit<Company, "slug"> & { verification: SourceVerification };
+
+/**
+ * Board-verified tier: a public ATS board is admitted on the provider's own identity (board name or tenant) without proof of
+ * the company website. Entries carry `identityEvidence: "provider_board"` and no `companyDomain`, so every consumer can tell
+ * them apart from company-verified sources.
+ */
+export async function verifyBoards(registryPath: string, catalogPath: string, options: BoardVerificationOptions = {}): Promise<BoardVerificationReport> {
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const now = options.now ?? (() => new Date());
+  const limit = Math.max(1, Math.trunc(options.limit ?? 200));
+  const concurrency = Math.max(1, Math.trunc(options.concurrency ?? 8));
+  const timeoutMs = Math.max(1, Math.trunc(options.timeoutMs ?? 30_000));
+  const cooldownMs = Math.max(0, options.cooldownDays ?? 30) * 86_400_000;
+
+  return withFileLock(catalogPath, async () => {
+    const catalog = await readCatalog(catalogPath);
+    const registry = await readEnrichmentRegistry(registryPath);
+    const knownSources = new Set(Object.values(catalog).map((entry) => `${entry.ats}:${entry.token.toLowerCase()}`));
+    const skipped = { inCatalog: 0, coolingDown: 0, unsupported: 0, deferred: 0 };
+    const eligible: EnrichmentLead[] = [];
+    for (const lead of registry.leads) {
+      if (!BOARD_TIER_PROVIDERS.has(lead.ats) || !resolveSource(lead.sourceUrl)) { skipped.unsupported += 1; continue; }
+      if (knownSources.has(`${lead.ats}:${lead.token.toLowerCase()}`)) { skipped.inCatalog += 1; continue; }
+      if (looksLikeTestBoard(lead.token)) { skipped.unsupported += 1; continue; }
+      if (coolingDown(lead, now(), cooldownMs)) { skipped.coolingDown += 1; continue; }
+      eligible.push(lead);
+    }
+    const selected = eligible.slice(0, limit);
+    skipped.deferred = eligible.length - selected.length;
+
+    const usedSlugs = new Set(Object.keys(catalog));
+    const added: string[] = [];
+    const rejected: BoardVerificationReport["rejected"] = [];
+    const updatedLeads: EnrichmentLead[] = [];
+    let cursor = 0;
+    async function worker() {
+      while (cursor < selected.length) {
+        const lead = selected[cursor++]!;
+        const attemptedAt = now().toISOString();
+        try {
+          const probe = await probeBoard(lead, fetcher, timeoutMs);
+          const name = probe.providerName || lead.companyMatches[0]?.companyName || humanize(lead.token);
+          const source = resolveSource(lead.sourceUrl)!;
+          const slug = uniqueSlug(lead, usedSlugs);
+          if (!slug) {
+            rejected.push({ sourceKey: lead.sourceKey, reason: "duplicate_slug", detail: `Catalog slug already used for ${lead.token}` });
+            updatedLeads.push(withAttempt(lead, { attemptedAt, outcome: "permanent_failure", category: "duplicate_slug", detail: "slug collision" }));
+            continue;
+          }
+          usedSlugs.add(slug);
+          catalog[slug] = {
+            name, ats: lead.ats, token: source.token, sourceUrl: source.canonicalSourceUrl,
+            discoveredFrom: lead.discoveredFrom[0] ?? { channel: "dataset", reference: registryPath },
+            verification: { observedCompanyName: name, identityEvidence: "provider_board", contentType: probe.contentType, payloadVersion: probe.payloadVersion, jobCount: probe.jobCount, checkedAt: attemptedAt, canonicalSourceUrl: source.canonicalSourceUrl },
+          };
+          added.push(slug);
+          updatedLeads.push({ ...withAttempt(lead, { attemptedAt, outcome: "success", category: "provider_board", detail: `${probe.jobCount} jobs` }), promotedAt: attemptedAt });
+        } catch (error) {
+          const reason = error instanceof BoardError ? error.reason : "unreachable";
+          const detail = error instanceof Error ? error.message : String(error);
+          const outcome = error instanceof BoardError && error.reason !== "unreachable" ? "permanent_failure" : "transient_failure";
+          rejected.push({ sourceKey: lead.sourceKey, reason, detail });
+          updatedLeads.push(withAttempt(lead, { attemptedAt, outcome, category: reason, detail }));
+        }
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, selected.length) }, worker));
+
+    if (added.length) await atomicJson(catalogPath, Object.fromEntries(Object.entries(catalog).sort(([a], [b]) => a.localeCompare(b))));
+    if (updatedLeads.length) await mergeEnrichmentLeads(registryPath, updatedLeads, now());
+    return {
+      generatedAt: now().toISOString(), considered: registry.leads.length, selected: selected.length, skipped,
+      verified: added.length, added: added.sort(), rejected: rejected.sort((a, b) => a.sourceKey.localeCompare(b.sourceKey)), catalogSize: Object.keys(catalog).length,
+    };
+  }, { operation: "verify boards" });
+}
+
+/** Random-looking tokens are almost always someone's test board: a long digit run mixed with letters, or a long consonant string. Short brand tokens like 2k or bvnk pass. */
+export function looksLikeTestBoard(token: string): boolean {
+  const value = token.toLowerCase();
+  return /[a-z]/.test(value) && (/\d{5,}/.test(value) || (value.length >= 8 && !/[aeiouy]/.test(value)));
+}
+
+class BoardError extends Error {
+  constructor(readonly reason: "unreachable" | "invalid_payload" | "empty_board", message: string) { super(message); }
+}
+
+async function probeBoard(lead: EnrichmentLead, fetcher: Fetch, timeoutMs: number): Promise<{ providerName: string; contentType: string; payloadVersion: string; jobCount: number }> {
+  const source = resolveSource(lead.sourceUrl)!;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
+  try {
+    const response = await fetcher(source.structuredEndpoint, { signal: controller.signal });
+    if (!response.ok) { await response.body?.cancel().catch(() => undefined); throw new BoardError(response.status === 404 || response.status === 410 ? "invalid_payload" : "unreachable", `HTTP ${response.status}`); }
+    let body: unknown;
+    try { body = await response.json(); } catch { throw new BoardError("invalid_payload", "Endpoint did not return JSON"); }
+    const spec = providerSpec(source.ats);
+    const jobs = spec ? spec.jobsFromBody(body) : source.ats === "lever" ? asArray(body) : asArray(isRecord(body) ? body[source.ats === "recruitee" ? "offers" : "jobs"] : undefined);
+    if (!jobs) throw new BoardError("invalid_payload", "Payload does not contain the expected jobs array");
+    if (jobs.length === 0) throw new BoardError("empty_board", "Board has no jobs");
+    const providerName = spec ? spec.providerName(jobs, body) : source.ats === "greenhouse" ? majority(jobs.map((job) => typeof job.company_name === "string" ? job.company_name.trim() : "").filter(Boolean)) : "";
+    const payloadVersion = spec ? spec.payloadVersion(body) : source.ats === "greenhouse" ? "greenhouse-job-board:v1" : source.ats === "lever" ? "lever-postings:v0" : source.ats === "recruitee" ? "recruitee-careers:v1" : `ashby-job-board:${isRecord(body) && typeof body.apiVersion === "string" ? body.apiVersion : "unknown"}`;
+    return { providerName, contentType: response.headers.get("content-type") ?? "unknown", payloadVersion, jobCount: jobs.length };
+  } finally { clearTimeout(timer); }
+}
+
+function coolingDown(lead: EnrichmentLead, now: Date, cooldownMs: number): boolean {
+  const last = lead.attempts[lead.attempts.length - 1];
+  if (!last) return false;
+  const age = now.getTime() - Date.parse(last.attemptedAt);
+  if (last.outcome === "permanent_failure") return age < cooldownMs;
+  if (last.outcome === "transient_failure") return age < 86_400_000;
+  return false;
+}
+
+function withAttempt(lead: EnrichmentLead, attempt: LeadAttempt): EnrichmentLead {
+  return { ...lead, attempts: [...lead.attempts, attempt] };
+}
+
+function uniqueSlug(lead: EnrichmentLead, used: Set<string>): string | null {
+  const base = lead.token.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || lead.ats;
+  for (const candidate of [base, `${lead.ats}-${base}`]) if (!used.has(candidate)) return candidate;
+  return null;
+}
+
+/** "acme-corp" -> "Acme Corp". Used only when the provider exposes no company name. */
+export function humanize(token: string): string {
+  return token.split(/[-_.]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+
+async function readCatalog(path: string): Promise<Record<string, CatalogEntry>> {
+  try {
+    const parsed = JSON.parse(await Bun.file(path).text()) as unknown;
+    if (!isRecord(parsed)) throw new Error(`Catalog is not an object: ${path}`);
+    return parsed as Record<string, CatalogEntry>;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+function majority(values: string[]): string {
+  const counts = new Map<string, number>();
+  for (const value of values) counts.set(value, (counts.get(value) ?? 0) + 1);
+  return [...counts].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "";
+}
+function asArray(value: unknown): Record<string, unknown>[] | null { return Array.isArray(value) && value.every(isRecord) ? value : null; }
+function isRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }

package/src/catalog.ts

@@ -1,4 +1,5 @@
 import type { Company, Job, JobSummary, SearchQuery } from "./types.ts";
+import { providerSpec, type JsonGet } from "./providers.ts";
 import { classifyJob, isEligibleForCountry, normalizeLocation } from "./locations.ts";
 
 type Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
@@ -100,6 +101,8 @@ export function createCatalog(options: CatalogOptions): Catalog {
         const description = await fetchWorkdayDescription(company, job.url, fetcher);
         job = { ...job, description };
       }
+      const spec = job && !job.description.trim() ? providerSpec(company.ats) : undefined;
+      if (job && spec?.detail) job = { ...job, description: await spec.detail(company, job, jsonGetter(fetcher, company.name)) };
       if (job && !job.description.trim()) throw new Error(`Full description unavailable for job: ${id}`);
       return job;
     },
@@ -118,6 +121,13 @@ export interface FetchJobsObserver {
 }
 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 spec = providerSpec(company.ats);
+  if (spec) {
+    const get = jsonGetter(fetcher, company.name, signal, observer);
+    const records = spec.fetchAll ? await spec.fetchAll(company.token, get) : spec.jobsFromBody(await get(spec.endpoint(company.token)));
+    if (!records) throw new Error(`${company.name} job board returned an invalid payload`);
+    return records.map((record) => spec.normalize(company, record));
+  }
   const url = company.ats === "greenhouse"
     ? `https://boards-api.greenhouse.io/v1/boards/${encodeURIComponent(company.token)}/jobs?content=true`
     : company.ats === "lever"
@@ -196,6 +206,15 @@ async function fetchWorkdayJobs(company: Company, fetcher: Fetch, signal?: Abort
   return jobs.map((job) => normalizeWorkday(company, source, job));
 }
 
+/** JSON fetch with the catalog's retry and backoff, shaped for the table-driven providers. */
+function jsonGetter(fetcher: Fetch, companyName: string, signal?: AbortSignal, observer?: FetchJobsObserver): JsonGet {
+  return async (url) => {
+    const response = await fetchWithRetry(fetcher, url, signal ? { signal } : undefined, companyName, observer);
+    if (!response.ok) { await response.body?.cancel().catch(() => undefined); throw new Error(`${companyName} job board returned HTTP ${response.status}`); }
+    return response.json();
+  };
+}
+
 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);

package/src/cli.ts

@@ -1,7 +1,11 @@
 #!/usr/bin/env bun
+import { ALL_PROVIDERS, type Ats } from "./types.ts";
 import { readFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
 import { createRuntime } from "./runtime.ts";
+import { atomicJson } from "./atomic-file.ts";
+import { verifyBoards } from "./board-verification.ts";
+import { discoverCareerSubdomains } from "./subdomain-discovery.ts";
 import { runSourceVerification } from "./source-pipeline.ts";
 import { runSourceDiscovery, runYcSourceDiscovery } from "./source-discovery.ts";
 import { discoverAndPromote } from "./source-discovery-pipeline.ts";
@@ -21,11 +25,13 @@ Usage:
   openings crawl [--country CODE | --companies FILE] [--concurrency N] [--source-cache-hours N] [--source-limit N] [--delay-ms N] [--workday-page-delay-ms N] [--data-dir PATH]
   openings snapshot export [--input FILE] [--output-dir PATH]
   openings coverage report --country CODE [--snapshot FILE] [--catalog FILE] [--candidates FILE] [--registry FILE] [--output FILE] [--as-of ISO]
+  openings sources discover-subdomains SEEDS.json [--output FILE] [--limit N] [--delay-ms N] [--report FILE]
+  openings sources verify-boards REGISTRY.json [--output FILE] [--limit N] [--concurrency N] [--report FILE]
   openings sources verify CANDIDATES.json [--output FILE] [--state-file FILE] [--concurrency N] [--workday-concurrency N] [--limit N] [--require-country CODE] [--registry FILE] [--retry-deferred]
   openings sources discover FEED.json [--country CODE] [--registry FILE] [--output FILE] [--catalog FILE] [--report FILE]
   openings sources discover-yc --country CODE [--registry FILE] [--output FILE] [--catalog FILE] [--report FILE]
   openings sources seed-companies-yc --country CODE [--output FILE]
-  openings sources discover-common-crawl [--country CODE] [--provider recruitee] [--index-record-limit N] [--sample-token-limit N] [--exclude-token TOKEN] [--report-only] [--registry FILE] [--output FILE] [--report FILE] [--index-url URL]
+  openings sources discover-common-crawl [--country CODE] [--provider NAME] [--index-record-limit N] [--sample-token-limit N] [--exclude-token TOKEN] [--report-only] [--registry FILE] [--output FILE] [--report FILE] [--index-url URL]
   openings sources enrich COMPANIES.json [--companies FILE]... [--evidence-kind authoritative_dataset|company_registry] [--registry FILE] [--output FILE] [--report FILE]
   openings sources trace-careers COMPANIES.json [--country CODE] [--registry FILE] [--common-crawl-report FILE] [--search-key-env NAME] [--output FILE] [--catalog FILE] [--report FILE]
   openings sources probe-jobposting COMPANIES.md [--catalog FILE] [--report FILE] [--company-limit 10|20]
@@ -156,6 +162,22 @@ export async function run(args: string[]): Promise<number> {
       )), null, 2));
       return 0;
     }
+    if (rest[0] === "discover-subdomains") {
+      const parsed = parseDiscoverSubdomains(rest.slice(1));
+      if (typeof parsed === "string") return fail(parsed);
+      const report = await discoverCareerSubdomains(parsed.seeds, parsed.output, { limit: parsed.limit, delayMs: parsed.delayMs });
+      if (parsed.report) await atomicJson(parsed.report, report);
+      console.log(JSON.stringify({ ...report, seeds: report.seeds.length }, null, 2));
+      return 0;
+    }
+    if (rest[0] === "verify-boards") {
+      const parsed = parseVerifyBoards(rest.slice(1));
+      if (typeof parsed === "string") return fail(parsed);
+      const report = await verifyBoards(parsed.registry, parsed.output, { limit: parsed.limit, concurrency: parsed.concurrency });
+      if (parsed.report) await atomicJson(parsed.report, report);
+      console.log(JSON.stringify(report, null, 2));
+      return 0;
+    }
     if (rest[0] !== "verify") return fail("sources requires a discovery, tracing, or `verify` subcommand");
     const parsed = parseSourceVerification(rest.slice(1));
     if (typeof parsed === "string") return fail(parsed);
@@ -307,7 +329,7 @@ function parseCommonCrawlDiscovery(args: string[]) {
   let country: string | undefined;
   let indexUrl: string | undefined;
   let registryPath: string | undefined = "data/enrichment-leads.json";
-  let provider: "recruitee" | undefined;
+  let provider: Ats | undefined;
   let indexRecordLimit: number | undefined;
   let sampleTokenLimit: number | undefined;
   const excludeTokens: string[] = [];
@@ -320,7 +342,7 @@ function parseCommonCrawlDiscovery(args: string[]) {
     else if (arg === "--index-url") { indexUrl = args[++index]; if (!indexUrl) return "--index-url requires a URL"; try { new URL(indexUrl); } catch { return "--index-url requires a valid URL"; } }
     else if (arg === "--registry") { if (reportOnly) return "Use either --registry or --report-only, not both"; registryPath = args[++index] ?? ""; if (!registryPath) return "--registry requires a file"; }
     else if (arg === "--report-only") { if (registryPath !== "data/enrichment-leads.json") return "Use either --registry or --report-only, not both"; reportOnly = true; registryPath = undefined; }
-    else if (arg === "--provider") { const value = args[++index]; if (value !== "recruitee") return "--provider currently supports only recruitee"; provider = value; }
+    else if (arg === "--provider") { const value = args[++index]; if (!value || !(ALL_PROVIDERS as readonly string[]).includes(value)) return `--provider must be one of ${ALL_PROVIDERS.join(", ")}`; provider = value as Ats; }
     else if (arg === "--index-record-limit") { indexRecordLimit = Number(args[++index]); if (!Number.isInteger(indexRecordLimit) || indexRecordLimit < 1 || indexRecordLimit > 2_000) return "--index-record-limit must be an integer from 1 to 2000"; }
     else if (arg === "--sample-token-limit") { sampleTokenLimit = Number(args[++index]); if (!Number.isInteger(sampleTokenLimit) || sampleTokenLimit < 1 || sampleTokenLimit > 60) return "--sample-token-limit must be an integer from 1 to 60"; }
     else if (arg === "--exclude-token") { const value = args[++index]?.trim(); if (!value || !/^[a-z0-9-]+$/i.test(value)) return "--exclude-token requires an ATS token"; excludeTokens.push(value.toLowerCase()); }
@@ -533,6 +555,42 @@ async function readCompanyFile(path: string): Promise<string[]> {
   return (await readFile(path, "utf8")).split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
 }
 
+function parseDiscoverSubdomains(args: string[]): { seeds: string; output: string; limit?: number; delayMs?: number; report?: string } | string {
+  const seeds = args[0];
+  if (!seeds || seeds.startsWith("--")) return "sources discover-subdomains requires a seed JSON file of { companyName, companyDomain }";
+  let output = ".openings/career-seeds-subdomains.json";
+  let limit: number | undefined;
+  let delayMs: number | undefined;
+  let report: string | undefined;
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--output") output = args[++index] ?? output;
+    else if (arg === "--report") report = args[++index];
+    else if (arg === "--limit") { limit = Number(args[++index]); if (!Number.isInteger(limit) || limit < 1) return "--limit must be a positive integer"; }
+    else if (arg === "--delay-ms") { delayMs = Number(args[++index]); if (!Number.isInteger(delayMs) || delayMs < 0) return "--delay-ms must be a non-negative integer"; }
+    else return `Unknown option: ${arg}`;
+  }
+  return { seeds, output, limit, delayMs, report };
+}
+
+function parseVerifyBoards(args: string[]): { registry: string; output: string; limit?: number; concurrency?: number; report?: string } | string {
+  const registry = args[0];
+  if (!registry || registry.startsWith("--")) return "sources verify-boards requires a registry JSON file";
+  let output = "data/companies.json";
+  let limit: number | undefined;
+  let concurrency: number | undefined;
+  let report: string | undefined;
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--output") output = args[++index] ?? output;
+    else if (arg === "--report") report = args[++index];
+    else if (arg === "--limit") { limit = Number(args[++index]); if (!Number.isInteger(limit) || limit < 1) return "--limit must be a positive integer"; }
+    else if (arg === "--concurrency") { concurrency = Number(args[++index]); if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 50) return "--concurrency must be an integer from 1 to 50"; }
+    else return `Unknown option: ${arg}`;
+  }
+  return { registry, output, limit, concurrency, report };
+}
+
 function parseSourceVerification(args: string[]) {
   const candidatesPath = args[0];
   if (!candidatesPath || candidatesPath.startsWith("--")) return "sources verify requires a candidate JSON file";

package/src/common-crawl-discovery.ts

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { atomicJson } from "./atomic-file.ts";
 import { stampReport, type ReportMeta } from "./report-meta.ts";
 import { mergeEnrichmentLeads, type EnrichmentLead } from "./enrichment-registry.ts";
+import { PROVIDERS } from "./providers.ts";
 import { resolveSource } from "./source-verification.ts";
 import type { Ats } from "./types.ts";
 import { assertArtifactFile } from "./artifact-path.ts";
@@ -36,11 +37,12 @@ export interface CommonCrawlDiscoveryReport extends ReportMeta {
   rejections: Array<{ value: string; reason: string }>;
 }
 
-const patterns = ["job-boards.greenhouse.io/*", "boards.greenhouse.io/*", "jobs.lever.co/*", "jobs.ashbyhq.com/*", "*.myworkdayjobs.com/*", "*.recruitee.com/*"];
-const recordsPerPattern = 10_000;
 const providerPatterns: Record<Ats, string[]> = {
-  greenhouse: patterns.slice(0, 2), lever: [patterns[2]!], ashby: [patterns[3]!], workday: [patterns[4]!], recruitee: [patterns[5]!],
+  greenhouse: ["job-boards.greenhouse.io/*", "boards.greenhouse.io/*"], lever: ["jobs.lever.co/*"], ashby: ["jobs.ashbyhq.com/*"], workday: ["*.myworkdayjobs.com/*"], recruitee: ["*.recruitee.com/*"],
+  ...Object.fromEntries(PROVIDERS.map((spec) => [spec.ats, spec.crawlPatterns])) as Record<"smartrecruiters" | "workable" | "breezy", string[]>,
 };
+const patterns = Object.values(providerPatterns).flat();
+const recordsPerPattern = 10_000;
 
 export async function discoverCommonCrawlSources(candidatesPath: string, reportPath: string, options: Options = {}): Promise<CommonCrawlDiscoveryReport> {
   if (options.provider === "recruitee") await assertArtifactFile(reportPath);

package/src/country-coverage.ts

@@ -4,6 +4,7 @@ import { deriveLeadState, readEnrichmentRegistry, type EnrichmentState } from ".
 import { isEligibleForCountry } from "./locations.ts";
 import { stampReport, type ReportMeta } from "./report-meta.ts";
 import { resolveSource } from "./source-verification.ts";
+import { ALL_PROVIDERS } from "./types.ts";
 import type { Ats, EligibilityConfidence, JobSnapshot, SourceCandidate, VerifiedCompany } from "./types.ts";
 import { projectJobCoverage } from "./job-coverage.ts";
 
@@ -110,8 +111,8 @@ async function readCatalog(path: string): Promise<Record<string, Omit<VerifiedCo
   const value: unknown = JSON.parse(await readFile(path, "utf8"));
   if (!isRecord(value)) throw new Error(`Invalid verified catalog: ${path}`);
   for (const [slug, company] of Object.entries(value)) {
-    if (!isRecord(company) || !["greenhouse", "lever", "ashby", "workday", "recruitee"].includes(String(company.ats)) || typeof company.token !== "string"
-      || typeof company.companyDomain !== "string" || typeof company.sourceUrl !== "string"
+    if (!isRecord(company) || !(ALL_PROVIDERS as readonly string[]).includes(String(company.ats)) || typeof company.token !== "string"
+      || (typeof company.companyDomain !== "string" && !(isRecord(company.verification) && company.verification.identityEvidence === "provider_board")) || typeof company.sourceUrl !== "string"
       || company.cohorts !== undefined && (!Array.isArray(company.cohorts) || !company.cohorts.every(validCountryCode))
       || !validVerification(company.verification)) throw new Error(`Invalid verified catalog source: ${slug}`);
   }

package/src/enrichment-registry.ts

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { atomicJson } from "./atomic-file.ts";
 import { withFileLock } from "./file-lock.ts";
+import { ALL_PROVIDERS } from "./types.ts";
 import type { Ats, DiscoveryProvenance, DomainEvidence } from "./types.ts";
 import { resolveSource } from "./source-verification.ts";
 
@@ -110,9 +111,9 @@ function consecutiveTransientFailures(attempts: LeadAttempt[]): number { let cou
 function isRegistry(value: unknown): value is EnrichmentRegistry {
   if (!isRecord(value) || value.version !== 1 || typeof value.updatedAt !== "string" || !Array.isArray(value.leads)) return false;
   return value.leads.every((lead) => isRecord(lead)
-    && typeof lead.sourceKey === "string" && /^(greenhouse|lever|ashby|workday|recruitee):.+/.test(lead.sourceKey)
+    && typeof lead.sourceKey === "string" && new RegExp(`^(${ALL_PROVIDERS.join("|")}):.+`).test(lead.sourceKey)
     && typeof lead.sourceUrl === "string" && typeof lead.token === "string"
-    && ["greenhouse", "lever", "ashby", "workday", "recruitee"].includes(String(lead.ats))
+    && (ALL_PROVIDERS as readonly string[]).includes(String(lead.ats))
     && Array.isArray(lead.discoveredFrom) && lead.discoveredFrom.every(validProvenance)
     && Array.isArray(lead.companyMatches) && lead.companyMatches.every(validMatch)
     && Array.isArray(lead.identityEvidence) && lead.identityEvidence.every(validEvidence)

package/src/job-coverage.ts

@@ -40,7 +40,7 @@ export function projectJobCoverage(sources: Company[], snapshot: JobSnapshot, co
         country,
         indexedSourcesWithEligibleJobs: eligibleSources.length,
         eligibleJobs: eligibleSources.reduce((total, { jobs }) => total + jobs.filter((job) => isEligibleForCountry(job, country)).length, 0),
-        distinctEligibleEmployers: new Set(eligibleSources.flatMap(({ source }) => source.companyDomain ? [normalizeDomain(source.companyDomain)] : [])).size,
+        distinctEligibleEmployers: new Set(eligibleSources.flatMap(({ source }) => source.companyDomain ? [normalizeDomain(source.companyDomain)] : source.verification?.identityEvidence === "provider_board" ? [`board:${source.ats}:${source.token.toLowerCase()}`] : [])).size,
       };
     }),
   };

package/src/mcp.ts

@@ -22,7 +22,7 @@ export function createMcpHandler(tools: ToolHandler) {
     const base = { jsonrpc: "2.0" as const, id: request.id ?? null };
     try {
       if (request.method === "initialize") {
-        return { ...base, result: { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "openings", version: "0.1.2" } } };
+        return { ...base, result: { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "openings", version: "0.1.4" } } };
       }
       if (request.method === "ping") return { ...base, result: {} };
       if (request.method === "tools/list") return { ...base, result: { tools: tools.list() } };

package/src/providers.ts

@@ -0,0 +1,183 @@
+import { classifyJob } from "./locations.ts";
+import type { Ats, Company, Job } from "./types.ts";
+
+/**
+ * Table-driven adapters for providers added after the original five. Each entry knows how to recognise a board URL,
+ * where its public structured endpoint lives, how to read the payload, and how to turn one record into a Job.
+ * The original providers keep their hand-written paths; new ones only need a row here.
+ */
+
+type Rec = Record<string, unknown>;
+/** Fetches a URL and returns its parsed JSON body; the caller supplies retry and pacing. */
+export type JsonGet = (url: string) => Promise<unknown>;
+
+export interface ProviderSpec {
+  ats: Ats;
+  label: string;
+  /** Registrable host suffixes on which this provider serves boards and job pages. */
+  hosts: string[];
+  /** Common Crawl URL patterns that surface this provider's boards. */
+  crawlPatterns: string[];
+  resolve(url: URL): string | null;
+  canonicalUrl(token: string): string;
+  endpoint(token: string): string;
+  jobsFromBody(body: unknown): Rec[] | null;
+  providerName(jobs: Rec[], body: unknown): string;
+  payloadVersion(body: unknown): string;
+  normalize(company: Company, job: Rec): Job;
+  /** Fetches every record when the endpoint paginates. Defaults to one request to `endpoint`. */
+  fetchAll?(token: string, get: JsonGet): Promise<Rec[]>;
+  /** Fetches the full description for one job when the listing omits it. */
+  detail?(company: Company, job: Job, get: JsonGet): Promise<string>;
+}
+
+const PAGE = 100;
+const MAX_RECORDS = 2000;
+
+const smartrecruiters: ProviderSpec = {
+  ats: "smartrecruiters",
+  label: "SmartRecruiters",
+  hosts: ["smartrecruiters.com"],
+  crawlPatterns: ["jobs.smartrecruiters.com/*", "careers.smartrecruiters.com/*"],
+  resolve(url) {
+    const parts = url.pathname.split("/").filter(Boolean);
+    if (url.hostname === "jobs.smartrecruiters.com" || url.hostname === "careers.smartrecruiters.com") return validToken(parts[0]);
+    if (url.hostname === "api.smartrecruiters.com" && parts[0] === "v1" && parts[1] === "companies") return validToken(parts[2]);
+    return null;
+  },
+  canonicalUrl: (token) => `https://jobs.smartrecruiters.com/${token}`,
+  endpoint: (token) => `https://api.smartrecruiters.com/v1/companies/${encodeURIComponent(token)}/postings?limit=${PAGE}&offset=0`,
+  jobsFromBody: (body) => (isRecord(body) ? asRecords(body.content) : null),
+  providerName: (jobs) => majority(jobs.map((job) => (isRecord(job.company) ? str(job.company.name) : ""))),
+  payloadVersion: () => "smartrecruiters-postings:v1",
+  async fetchAll(token, get) {
+    const records: Rec[] = [];
+    for (let offset = 0; offset < MAX_RECORDS; offset += PAGE) {
+      const body = await get(`https://api.smartrecruiters.com/v1/companies/${encodeURIComponent(token)}/postings?limit=${PAGE}&offset=${offset}`);
+      const page = smartrecruiters.jobsFromBody(body);
+      if (!page) throw new Error("SmartRecruiters returned an invalid postings payload");
+      records.push(...page);
+      const total = isRecord(body) && typeof body.totalFound === "number" ? body.totalFound : records.length;
+      if (page.length < PAGE || records.length >= total) break;
+    }
+    return records;
+  },
+  normalize(company, job) {
+    const loc = isRecord(job.location) ? job.location : {};
+    const country = str(loc.country);
+    const location = str(loc.fullLocation) || [str(loc.city), str(loc.region), country.length === 2 ? country.toUpperCase() : country].filter(Boolean).join(", ") || "Unspecified";
+    const remote = loc.remote === true;
+    return classifyJob({
+      id: `smartrecruiters:${company.slug}:${str(job.id)}`, company: company.name, title: str(job.name), location,
+      remote, workMode: remote ? "remote" : loc.hybrid === true ? "hybrid" : "unknown",
+      eligibleCountries: [], excludedCountries: [], eligibleRegions: [], eligibilityConfidence: "unknown",
+      url: `https://jobs.smartrecruiters.com/${company.token}/${encodeURIComponent(str(job.id))}`, updatedAt: str(job.releasedDate) || undefined, description: "",
+    });
+  },
+  async detail(company, job, get) {
+    const id = job.id.split(":")[2] ?? "";
+    const body = await get(`https://api.smartrecruiters.com/v1/companies/${encodeURIComponent(company.token)}/postings/${encodeURIComponent(id)}`);
+    const sections = isRecord(body) && isRecord(body.jobAd) && isRecord(body.jobAd.sections) ? body.jobAd.sections : {};
+    return ["jobDescription", "qualifications", "additionalInformation"].map((key) => { const section = sections[key]; return isRecord(section) ? plainText(str(section.text)) : ""; }).filter(Boolean).join("\n\n");
+  },
+};
+
+const workable: ProviderSpec = {
+  ats: "workable",
+  label: "Workable",
+  hosts: ["workable.com"],
+  crawlPatterns: ["apply.workable.com/*"],
+  resolve(url) {
+    const parts = url.pathname.split("/").filter(Boolean);
+    if (url.hostname === "apply.workable.com") return parts[0] && !["j", "api", "jobs", "embed", "assets"].includes(parts[0]) ? validToken(parts[0]) : null;
+    const match = /^([a-z0-9-]+)\.workable\.com$/i.exec(url.hostname);
+    if (match && !["www", "apply", "help", "resources", "jobs", "careers", "api", "app", "assets", "cdn", "status", "developers", "blog", "partners"].includes(match[1]!.toLowerCase())) return match[1]!.toLowerCase();
+    return null;
+  },
+  canonicalUrl: (token) => `https://apply.workable.com/${token}/`,
+  endpoint: (token) => `https://apply.workable.com/api/v1/widget/accounts/${encodeURIComponent(token)}`,
+  jobsFromBody: (body) => (isRecord(body) ? asRecords(body.jobs) : null),
+  providerName: (_jobs, body) => (isRecord(body) ? str(body.name) : ""),
+  payloadVersion: () => "workable-widget:v1",
+  normalize(company, job) {
+    const first = asRecords(job.locations)?.[0];
+    const location = [str(job.city), str(job.state), str(job.country) || (first ? str(first.country) : "")].filter(Boolean).join(", ") || "Unspecified";
+    const remote = job.telecommuting === true;
+    return classifyJob({
+      id: `workable:${company.slug}:${str(job.shortcode)}`, company: company.name, title: str(job.title), location,
+      remote, workMode: remote ? "remote" : "unknown",
+      eligibleCountries: [], excludedCountries: [], eligibleRegions: [], eligibilityConfidence: "unknown",
+      url: str(job.url) || `https://apply.workable.com/j/${encodeURIComponent(str(job.shortcode))}`, updatedAt: str(job.published_on) || undefined, description: "",
+    });
+  },
+  async detail(company, job, get) {
+    const shortcode = job.id.split(":")[2] ?? "";
+    const body = await get(`https://apply.workable.com/api/v2/accounts/${encodeURIComponent(company.token)}/jobs/${encodeURIComponent(shortcode)}`);
+    if (!isRecord(body)) return "";
+    return ["description", "requirements", "benefits"].map((key) => plainText(str(body[key]))).filter(Boolean).join("\n\n");
+  },
+};
+
+const breezy: ProviderSpec = {
+  ats: "breezy",
+  label: "Breezy",
+  hosts: ["breezy.hr"],
+  crawlPatterns: ["*.breezy.hr/*"],
+  resolve(url) {
+    const match = /^([a-z0-9-]+)\.breezy\.hr$/i.exec(url.hostname);
+    return match && !["www", "app", "api", "help", "blog"].includes(match[1]!.toLowerCase()) ? match[1]!.toLowerCase() : null;
+  },
+  canonicalUrl: (token) => `https://${token}.breezy.hr`,
+  endpoint: (token) => `https://${token}.breezy.hr/json?verbose=true`,
+  jobsFromBody: (body) => asRecords(body),
+  providerName: (jobs) => majority(jobs.map((job) => (isRecord(job.company) ? str(job.company.name) : ""))),
+  payloadVersion: () => "breezy-positions:v1",
+  normalize(company, job) {
+    const loc = isRecord(job.location) ? job.location : {};
+    const location = str(loc.name) || [str(loc.city), isRecord(loc.state) ? str(loc.state.name) : "", isRecord(loc.country) ? str(loc.country.name) : ""].filter(Boolean).join(", ") || "Unspecified";
+    const remote = loc.is_remote === true;
+    return classifyJob({
+      id: `breezy:${company.slug}:${str(job.id)}`, company: company.name, title: str(job.name), location,
+      remote, workMode: remote ? "remote" : "unknown",
+      eligibleCountries: [], excludedCountries: [], eligibleRegions: [], eligibilityConfidence: "unknown",
+      url: str(job.url) || `https://${company.token}.breezy.hr/p/${encodeURIComponent(str(job.friendly_id) || str(job.id))}`, updatedAt: str(job.published_date) || undefined, description: plainText(str(job.description)),
+    });
+  },
+};
+
+export const PROVIDERS: ReadonlyArray<ProviderSpec> = [smartrecruiters, workable, breezy];
+
+export function providerSpec(ats: string): ProviderSpec | undefined {
+  return PROVIDERS.find((spec) => spec.ats === ats);
+}
+
+/** Resolves a URL against the table-driven providers; returns null when none claims it. */
+export function resolveProviderSource(value: string): { ats: Ats; token: string; canonicalSourceUrl: string; structuredEndpoint: string } | null {
+  let url: URL;
+  try { url = new URL(value); } catch { return null; }
+  for (const spec of PROVIDERS) {
+    const token = spec.resolve(url);
+    if (token) return { ats: spec.ats, token, canonicalSourceUrl: spec.canonicalUrl(token), structuredEndpoint: spec.endpoint(token) };
+  }
+  return null;
+}
+
+function validToken(value: string | undefined): string | null {
+  return value && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) ? value : null;
+}
+
+export function plainText(value: string): string {
+  return value
+    .replace(/<br\s*\/?\s*>/gi, "\n").replace(/<\/(p|li|div|h[1-6])>/gi, "\n").replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+    .replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+function majority(values: string[]): string {
+  const counts = new Map<string, number>();
+  for (const value of values) if (value) counts.set(value, (counts.get(value) ?? 0) + 1);
+  return [...counts].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "";
+}
+function str(value: unknown): string { return typeof value === "string" ? value.trim() : typeof value === "number" ? String(value) : ""; }
+function asRecords(value: unknown): Rec[] | null { return Array.isArray(value) && value.every(isRecord) ? value : null; }
+function isRecord(value: unknown): value is Rec { return typeof value === "object" && value !== null && !Array.isArray(value); }