// @ts-check
/**
 * liveness-api.mjs — zero-token liveness check for ATS-hosted job postings.
 *
 * Many postings live on ATS platforms (Greenhouse, Lever, Ashby, Workday, ...) that
 * expose a public JSON endpoint. We can confirm whether a posting is still live by
 * hitting that endpoint directly — no browser, no LLM tokens — and only fall back to
 * the Playwright check (liveness-browser.mjs) for non-ATS pages or when the API is
 * inconclusive. This is the cheap first rung of the liveness ladder.
 *
 * CONSERVATIVE BY DESIGN: a false "expired" is worse than the status quo (the user
 * misses a real job). So we return `expired` only on a definitive signal — a
 * 404/410, or a closed marker the provider's `interpret` step recognises — and for
 * anything ambiguous (unknown ATS, redirect, 429/5xx, network/timeout) we return
 * `null` (→ caller falls back to Playwright).
 *
 * Three endpoint shapes:
 *   - Per-job (Greenhouse, Lever, Workday): the URL maps to a single-job endpoint,
 *     so a 200 is itself proof the posting is live. Workday also reads its 403
 *     body, whose error code tells a withdrawn posting apart from a blocked
 *     request.
 *   - Org-level (Ashby): the URL maps to the org's whole job board. A 200 only
 *     proves the board exists, so the provider's `interpret` step parses the board
 *     and confirms THIS posting is still listed before returning active/expired.
 *     (Ashby pages are JS-rendered, so the browser/static rung sees only nav/footer
 *     and false-reports live postings as expired — this API rung is authoritative.)
 *   - Per-job HTML (LinkedIn): the guest endpoint returns the rendered posting as
 *     HTML and answers 200 for closed postings too, so `interpret` reads two
 *     independent signals out of the body and only concludes when they agree.
 *     Zoho Recruit and UltiPro are the same shape: their posting pages embed
 *     the record and answer 200 for a removed posting too, so `interpret` reads
 *     the body.
 *
 * SSRF-safe by construction: the request URL is built from a FIXED, hard-coded API
 * host plus path segments extracted from the posting URL with a strict charset
 * (no slashes / traversal), and server-side redirects are refused.
 */

import { DEFAULT_USER_AGENT } from './user-agent.mjs';
import { parseWwrFeed } from './providers/weworkremotely.mjs';
import { hireHiveTenantOf } from './providers/hirehive.mjs';
import { ZOHO_HOST_RE, isZohoRecordClosed, parseZohoDetailPage } from './providers/zoho-recruit.mjs';
import { HOST_RE as ULTIPRO_HOST_RE, extractCandidateOpportunityDetail } from './providers/ultipro.mjs';
import { VEJ_KEY_MONITOR } from './providers/vdab.mjs';
import { PATH_BREAKING_CHAR, PATH_BREAKING_CHAR_ENCODED_ONCE } from './providers/arbeitsagentur.mjs';
import { resolveHibobTenant } from './providers/hibob.mjs';
import { atsVendorOf } from './ats-vendor.mjs';
import { linkedInJobId, linkedInGuestUrl } from './lib/linkedin-url.mjs';

const TIMEOUT_MS = 8_000;
// Arbeitsagentur: the hexadecimal digits of an encoded character can be in either case.
const PATH_BREAKING_CHAR_ENCODED_ONCE_RE = new RegExp(PATH_BREAKING_CHAR_ENCODED_ONCE, 'gi');
// Strict path-segment charset. Anything with a slash, dot-dot, or other char is
// rejected before it can reach the fixed-host API URL template. The one escape
// allowed is %20, because some Ashby org slugs contain a space (#5018). A space
// cannot end a segment or form a traversal; %2F and every other escape still fail.
const SAFE_SEGMENT = /^(?:[A-Za-z0-9._-]|%20)+$/;

// Most providers extract single path segments (SAFE_SEGMENT covers those directly).
// Workday's job path is genuinely multi-segment (a location slug + a title slug,
// e.g. "Toronto-ON-CAN/Agentic-AI-Engineer_R260010125"), so a `parts` value may
// itself contain slashes. This still validates every individual segment against
// the same strict charset (and rejects ".." in any of them) — it only relaxes
// "no slash at all" to "no *unsafe* content between slashes", so the traversal/
// injection guarantee is unchanged.
function isSafeValue(v) {
  if (typeof v !== 'string' || v.length === 0) return false;
  // SAFE_SEGMENT's charset includes "." (some real segments use dots), so ".."
  // alone passes that regex — same as the single-segment guard in
  // resolveAtsApi below, the explicit `!includes('..')` check per segment is
  // load-bearing, not redundant with the regex test.
  return v.split('/').every((seg) => seg.length > 0 && SAFE_SEGMENT.test(seg) && !seg.includes('..'));
}

// Each ATS: detect its posting URL, then map to a public JSON API URL.
// `match` returns the extracted path params (or null); `api` builds the FIXED-host URL.
// Optional per-provider fields:
//   `timeoutMs`  — override the default fetch timeout (slow/rate-limited APIs).
//   `throttleMs` — minimum interval between our requests to this provider.
//   `accept`     — override the Accept header (providers that answer in HTML).
//   `headers`    — extra request headers, or a function of the extracted
//                  params that returns them (see the `hibob` entry).
//   `method`     — HTTP method of the API request; defaults to GET.
//   `body`       — builds the request body from the extracted params, for an
//                  endpoint that only answers a POST (see the `meituan` entry).
//   `interpret`  — read the response body to decide liveness (org-level APIs
//                  where a 200 alone doesn't prove THIS posting is live, and
//                  per-job APIs that answer 200 for a closed posting). The third
//                  argument is the request's abort signal, for a provider that
//                  needs a second request to decide (see the `hibob` entry).
//   `interpretStatuses` — the statuses whose body `interpret` reads; defaults
//                  to [200]. A provider that answers a closed posting with an
//                  error status carrying a recognisable body lists that status
//                  here instead (see the `workday` entry); a 200 it leaves out
//                  takes the default per-job reading, proof the posting is live.
//                  A 404 or 410 listed here is read the same way, in place of
//                  the 404 rule below (see the `nofluffjobs` entry).
//   `api404Authoritative` — defaults to true (a 404/410 means gone). Set to
//                  false when the provider's public API can 404 a posting that
//                  is still genuinely live elsewhere (see the `lever` entry).
const ATS_PROVIDERS = [
  {
    id: 'greenhouse-embedded',
    // Company careers pages can expose only gh_jid, with no Greenhouse board.
    // The embed redirect supplies the board; a second per-job API request is
    // still required because even closed jobs can have an embed redirect.
    // Scanners often record these pages as plain http (http://block.xyz/careers/
    // jobs/N?gh_jid=N); only the gh_jid matters and both API hosts are fixed, so
    // the page's scheme is accepted. Without this the posting fell to the browser,
    // which timed out or saw the id dropped by a redirect and answered uncertain.
    acceptsHttp: true,
    match(u) {
      if (/(^|\.)greenhouse\.io$/.test(u.hostname)) return null;
      const id = u.searchParams.get('gh_jid');
      return id && /^\d+$/.test(id) ? { id } : null;
    },
    api: ({ id }) => `https://boards.greenhouse.io/embed/job_app?token=${id}`,
    async followEmbed(res, { id }) {
      if (res.status !== 301 && res.status !== 302) return null;
      let target;
      try { target = new URL(res.headers.get('location'), 'https://boards.greenhouse.io'); }
      catch { return null; }
      if (target.protocol !== 'https:' || !/(^|\.)greenhouse\.io$/.test(target.hostname)) return null;
      const board = target.searchParams.get('for');
      // The board is one URL path segment. isSafeValue also accepts Workday's
      // multi-segment paths, so reject a decoded slash here explicitly.
      if (!isSafeValue(board) || board.includes('/') || target.searchParams.get('token') !== id) return null;
      return `https://boards-api.greenhouse.io/v1/boards/${board}/jobs/${id}`;
    },
  },
  {
    id: 'greenhouse',
    // boards.greenhouse.io/{board}/jobs/{id} · job-boards[.eu].greenhouse.io/{board}/jobs/{id}
    match(u) {
      if (atsVendorOf(u.href) !== 'greenhouse') return null;
      const m = u.pathname.match(/^\/([^/]+)\/jobs\/(\d+)\/?$/);
      return m ? { board: m[1], id: m[2] } : null;
    },
    api: ({ board, id }) => `https://boards-api.greenhouse.io/v1/boards/${board}/jobs/${id}`,
  },
  {
    id: 'lever',
    // jobs.(eu.)?lever.co/{slug}/{id}
    match(u) {
      if (atsVendorOf(u.href) !== 'lever') return null;
      const host = u.hostname.match(/^jobs\.((?:eu\.)?lever\.co)$/);
      if (!host) return null;
      const m = u.pathname.match(/^\/([^/]+)\/([^/?#]+)\/?$/);
      return m ? { apiHost: `api.${host[1]}`, slug: m[1], id: m[2] } : null;
    },
    api: ({ apiHost, slug, id }) => `https://${apiHost}/v0/postings/${slug}/${id}`,
    // Lever's Confidential/Internal Postings feature explicitly excludes some
    // live postings from the public v0/postings API while the direct
    // jobs.lever.co page keeps serving them normally. Real-world repro
    // (2026-08-09): api.lever.co 404s two postings whose jobs.lever.co pages
    // return 200 with the real job title and a working Apply control. A 404
    // here is NOT proof of removal — fall through to Playwright instead.
    api404Authoritative: false,
  },
  {
    id: 'workable',
    // apply.workable.com/{account}/j/{shortcode}
    match(u) {
      if (u.hostname !== 'apply.workable.com') return null;
      const m = u.pathname.match(/^\/([^/]+)\/j\/([A-Za-z0-9_-]+)\/?$/);
      return m ? { account: m[1], shortcode: m[2] } : null;
    },
    api: ({ account, shortcode }) => `https://apply.workable.com/api/v2/accounts/${account}/jobs/${shortcode}`,
    // Workable's posting pages render client-side, so the browser rung reads a
    // not-yet-painted live posting as nav/footer only (insufficient_content),
    // which used to read as expired, the costly direction: scan --verify wrote
    // that to scan-history as skipped. The v2 JSON endpoint is per-job and needs no
    // browser. Measured live (#5000): 200 with state "published" is the live
    // shape and 404 ("Job not found") is the removed shape, so a 404 is
    // authoritative here and any other readable state stays uncertain.
    async interpret(res) {
      let posting;
      try { posting = await res.json(); } catch { return null; }
      return classifyWorkablePosting(posting);
    },
  },
  {
    id: 'workable-short',
    // apply.workable.com/j/{shortcode} is the share link, and it carries no
    // account. Following its own redirect yields /{account}/j/{shortcode},
    // which names the account the v2 endpoint needs (#5000).
    match(u) {
      if (u.hostname !== 'apply.workable.com') return null;
      const m = u.pathname.match(/^\/j\/([A-Za-z0-9_-]+)\/?$/);
      return m ? { shortcode: m[1] } : null;
    },
    api: ({ shortcode }) => `https://apply.workable.com/j/${shortcode}`,
    async followEmbed(res, { shortcode }) {
      if (res.status !== 301 && res.status !== 302) return null;
      let target;
      try { target = new URL(res.headers.get('location'), 'https://apply.workable.com'); }
      catch { return null; }
      if (target.protocol !== 'https:' || target.hostname !== 'apply.workable.com') return null;
      const m = target.pathname.match(/^\/([^/]+)\/j\/([A-Za-z0-9_-]+)\/?$/);
      if (!m || m[2] !== shortcode || !isSafeValue(m[1])) return null;
      return `https://apply.workable.com/api/v2/accounts/${m[1]}/jobs/${m[2]}`;
    },
    async interpret(res) {
      let posting;
      try { posting = await res.json(); } catch { return null; }
      return classifyWorkablePosting(posting);
    },
  },
  {
    id: 'ashby',
    // jobs.ashbyhq.com/{org}/{jobId}[/application]. Ashby's public posting API is
    // ORG-level (the whole job board), not per-job — so `api` maps to the board and
    // `interpret` confirms this {jobId} is still listed. Only {org} reaches the
    // fixed-host URL; {jobId} is used solely to filter the parsed board (SAFE_SEGMENT
    // still validates both).
    match(u) {
      if (atsVendorOf(u.href) !== 'ashby' || u.hostname !== 'jobs.ashbyhq.com') return null;
      const m = u.pathname.match(/^\/([^/]+)\/([^/]+)(?:\/application)?\/?$/);
      return m ? { org: m[1], jobId: m[2] } : null;
    },
    api: ({ org }) => `https://api.ashbyhq.com/posting-api/job-board/${org}`,
    // Ashby's posting-api has a server-side latency floor and rate-limits repeated
    // unauthenticated hits (see providers/ashby.mjs). Give it more room than the ATS
    // default so a slow-but-live board doesn't time out into a Playwright fallback.
    timeoutMs: 20_000,
    // The API is board-level, so a 404 means the board API is off for this org
    // (embed-only boards such as Whatnot, providers/ashby.mjs `ashby.embed`) or
    // the slug is wrong. Neither says THIS posting is gone: removal shows as a
    // 200 board that no longer lists the id (`ashby_api_unlisted`).
    api404Authoritative: false,
    // One board answers for every posting under the org, so a caller checking
    // several postings can pass checkLivenessViaApi a `boardCache` and fetch it
    // once (check-liveness.mjs does, per run).
    interpretBoard: (json, { jobId }) => classifyAshbyBoard(json, jobId),
    async interpret(res, { jobId }) {
      let json;
      try {
        json = await res.json();
      } catch {
        return null; // unparseable body → inconclusive, let the browser decide
      }
      return classifyAshbyBoard(json, jobId);
    },
  },
  {
    id: 'workday',
    // {tenant}.{shard}.myworkdayjobs.com[/{xx-XX}]/{site}/job/{jobPath...}
    // Mirrors the tenant/shard/site detection in providers/workday.mjs, but for a
    // single posting rather than the board-wide CXS search endpoint. Workday's
    // per-job CXS endpoint (`/wday/cxs/{tenant}/{site}/job/{jobPath}`) is a
    // genuinely PER-JOB API like Greenhouse/Lever: a live posting returns 200, a
    // missing one returns 404, and a withdrawn posting returns a structured 403,
    // whose body classifyWorkday403 reads.
    //
    // jobPath is intentionally multi-segment (Workday encodes a location slug and
    // a title slug as separate path parts, e.g.
    // "Toronto-ON-CAN/Agentic-AI-Engineer_R260010125") — isSafeValue (not the
    // single-segment SAFE_SEGMENT check other providers use directly) validates
    // it component-by-component.
    match(u) {
      if (atsVendorOf(u.href) !== 'workday') return null;
      const m = `${u.hostname}${u.pathname}`.match(
        /^([\w-]+)\.(wd[\w-]*)\.myworkdayjobs\.com\/(?:[a-z]{2}-[A-Z]{2}\/)?([^/?#]+)\/job\/(.+?)\/?$/
      );
      if (!m) return null;
      const [, tenant, shard, site, jobPath] = m;
      return { tenant, shard, site, jobPath };
    },
    api: ({ tenant, shard, site, jobPath }) =>
      `https://${tenant}.${shard}.myworkdayjobs.com/wday/cxs/${tenant}/${site}/job/${jobPath}`,
    interpretStatuses: [403],
    async interpret(res) {
      let json;
      try {
        json = await res.json();
      } catch {
        return null; // unparseable body (e.g. a WAF HTML interstitial) → inconclusive
      }
      return classifyWorkday403(json);
    },
  },
  {
    id: 'smartrecruiters',
    match(u) {
      if (u.hostname !== 'jobs.smartrecruiters.com') return null;
      const m = u.pathname.match(/^\/([^/]+)\/([A-Za-z0-9]+)(?:-[^/]*)?\/?$/);
      return m ? { company: m[1], id: m[2] } : null;
    },
    api: ({ company, id }) => `https://api.smartrecruiters.com/v1/companies/${company}/postings/${id}`,
    api404Authoritative: false, // the API also uses 400 for unknown IDs
    async interpret(res, { id }) {
      let posting;
      try { posting = await res.json(); } catch { return null; }
      if (String(posting?.id) !== id || typeof posting.active !== 'boolean') return null;
      return posting.active
        ? { result: 'active', code: 'smartrecruiters_api_active', reason: 'SmartRecruiters marks the posting active' }
        : { result: 'expired', code: 'smartrecruiters_api_inactive', reason: 'SmartRecruiters marks the posting inactive' };
    },
  },
  {
    id: 'zoho-recruit',
    // {tenant}.zohorecruit.<regional tld>/jobs/{portal}/{id}[/{slug}]. Zoho Recruit has no
    // JSON endpoint; the posting page itself embeds the record (see
    // providers/zoho-recruit.mjs), so `api` is that page and `interpret` reads
    // it. Zoho answers 200 for a removed posting too, so liveness comes from
    // the body, never from the status.
    match(u) {
      const host = u.hostname.match(ZOHO_HOST_RE);
      if (!host) return null;
      const m = u.pathname.match(/^\/jobs\/([^/]+)\/(\d+)(?:\/[^/]*)?\/?$/);
      return m ? { tenant: host[1], host: u.hostname, portal: m[1], id: m[2] } : null;
    },
    api: ({ host, portal, id }) => `https://${host}/jobs/${portal}/${id}`,
    accept: 'text/html',
    async interpret(res, { id }) {
      let html;
      try { html = await res.text(); } catch { return null; }
      return classifyZohoPostingPage(html, id);
    },
  },
  {
    id: 'hirehive',
    // <tenant>.hirehive.com/<title-slug>-<shortid> reads the tenant's per-posting
    // v2 API (`job_<shortid>`); /job/<number>[/<title-slug>] reads the v1 API by
    // that number. Both answer 200 with the posting and 404 with a JSON
    // `message`. The posting page says "This job is no longer available." for
    // an unpublished posting, which is the API's "Job is not published"; the
    // other messages ("Job not found", "Company not found", "Job does not match
    // company") do not prove a posting closed, so they stay inconclusive.
    match(u) {
      const tenant = hireHiveTenantOf(u.hostname);
      if (!tenant) return null;
      const host = `${tenant}.hirehive.com`;
      const byNumber = u.pathname.match(/^\/job\/(\d+)(?:\/[^/]*)?\/?$/);
      if (byNumber) return { host, version: 'v1', id: byNumber[1] };
      const bySlug = u.pathname.match(/^\/[^/]*-([A-Za-z0-9]+)\/?$/);
      return bySlug ? { host, version: 'v2', id: `job_${bySlug[1]}` } : null;
    },
    api: ({ host, version, id }) => `https://${host}/api/${version}/jobs/${id}`,
    interpretStatuses: [200, 404],
    api404Authoritative: false,
    async interpret(res, { id }) {
      let json;
      try { json = await res.json(); } catch { return null; }
      return classifyHireHivePosting(json, id, res.status);
    },
  },
  {
    id: 'ultipro',
    // {host}/{tenant}/JobBoard/{boardId}/OpportunityDetail?opportunityId={id}, the
    // URL providers/ultipro.mjs writes. Like Zoho Recruit, UKG has no per-posting
    // JSON endpoint: the detail page embeds the record (see providers/ultipro.mjs)
    // and answers 200 for a closed posting too, so `interpret` reads the body.
    //
    // The browser reads a closed posting here as uncertain: it either keeps its
    // page without an Apply control or gets the board's near-empty page, and on
    // 2026-10-28 all 57 closed postings read uncertain. Measured that day on 156
    // postings across 24 tenants, against each board's own listing: 99 listed
    // postings carried an open record, 14 unlisted ones a closed record and 42
    // the empty page's notice; the last, an internal-only posting, stays with
    // the browser.
    match(u) {
      if (!ULTIPRO_HOST_RE.test(u.hostname)) return null;
      const m = u.pathname.match(/^\/([^/]+)\/JobBoard\/([^/]+)\/OpportunityDetail\/?$/);
      const id = u.searchParams.get('opportunityId');
      if (!m || !id || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) return null;
      // UKG reads the id in any case and answers with the record's own lower-case id.
      return { host: u.hostname, tenant: m[1], boardId: m[2], id: id.toLowerCase() };
    },
    api: ({ host, tenant, boardId, id }) => `https://${host}/${tenant}/JobBoard/${boardId}/OpportunityDetail?opportunityId=${id}`,
    accept: 'text/html',
    async interpret(res, { id }) {
      let html;
      try { html = await res.text(); } catch { return null; }
      return classifyUltiproDetailPage(html, id);
    },
  },
  {
    id: 'hibob',
    // {tenant}.careers.hibob.com/jobs/{uuid}[/apply], the URL providers/hibob.mjs
    // writes. The posting page reads only this per-posting endpoint and, when
    // it answers 404, shows "No job openings match this URL" in place of the
    // posting, and a 200 is a live posting. A label with no careers site answers
    // 404 with the same body on its board endpoint too, so a 404 closes the
    // posting only when the tenant's board answers 200; otherwise it stays
    // inconclusive. The `companyidentifier` header names the tenant; without it,
    // or for a label that is not a tenant, the answer is 401, also inconclusive.
    match(u) {
      const tenant = resolveHibobTenant(u.href);
      if (!tenant) return null;
      const m = u.pathname.match(/^\/jobs\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:\/apply)?\/?$/i);
      return m ? { tenant, jobId: m[1] } : null;
    },
    api: ({ tenant, jobId }) => `https://${tenant}.careers.hibob.com/api/job-ad/${jobId}/application-form`,
    headers: ({ tenant }) => ({ companyidentifier: tenant }),
    interpretStatuses: [404],
    api404Authoritative: false,
    async interpret(res, { tenant }, signal) {
      await res.body?.cancel().catch(() => {});
      const board = await fetch(`https://${tenant}.careers.hibob.com/api/job-ad`, {
        headers: { 'user-agent': DEFAULT_USER_AGENT, accept: 'application/json', companyidentifier: tenant },
        redirect: 'error',
        signal,
      });
      await board.body?.cancel().catch(() => {});
      return board.status === 200
        ? { result: 'expired', code: 'hibob_api_gone', reason: 'HiBob answers 404 for the posting while the tenant board answers 200' }
        : null;
    },
  },
  {
    id: 'arbeitsagentur',
    match(u) {
      if (u.hostname !== 'www.arbeitsagentur.de') return null;
      const m = u.pathname.match(/^\/jobsuche\/jobdetail\/([^/]+)\/?$/);
      if (!m) return null;
      // The path holds the reference number encoded once, except a slash, which
      // is encoded once or twice (%2F or %252F). Decoding once keeps a literal
      // percent sign, and leaves only a twice-encoded slash still encoded.
      // The API takes the base64url of the real number. Only that form is passed
      // on: the real number can hold characters the safe-value check refuses.
      try {
        const refnr = decodeURIComponent(m[1]).replace(PATH_BREAKING_CHAR_ENCODED_ONCE_RE, PATH_BREAKING_CHAR);
        return { refnrBase64: Buffer.from(refnr).toString('base64url') };
      } catch {
        return null;
      }
    },
    api: ({ refnrBase64 }) => `https://rest.arbeitsagentur.de/jobboerse/jobsuche-service/pc/v4/jobdetails/${refnrBase64}`,
    headers: { 'X-API-Key': 'jobboerse-jobsuche' },
    api404Authoritative: false, // no expired real-job control; absence stays unknown
    async interpret(res, { refnrBase64 }) {
      let posting;
      try { posting = await res.json(); } catch { return null; }
      return posting?.referenznummer === Buffer.from(refnrBase64, 'base64url').toString() && posting?.stellenangebotsTitel
        ? { result: 'active', code: 'arbeitsagentur_api_active', reason: 'Arbeitsagentur returns the matching job detail' }
        : null;
    },
  },
  {
    id: 'weworkremotely',
    match(u) {
      if (u.hostname !== 'weworkremotely.com' || !/^\/remote-jobs\/[^/]+\/?$/.test(u.pathname)) return null;
      return { slug: u.pathname.split('/')[2] };
    },
    api: () => 'https://weworkremotely.com/remote-jobs.rss',
    accept: 'application/rss+xml',
    api404Authoritative: false,
    async interpret(res, { slug }) {
      let feed;
      try { feed = await res.text(); } catch { return null; }
      if (!/<rss\b/i.test(feed)) return null;
      const listed = parseWwrFeed(feed).some((job) => new URL(job.url).pathname.replace(/\/$/, '') === `/remote-jobs/${slug}`);
      return listed
        ? { result: 'active', code: 'weworkremotely_feed_listed', reason: 'Posting is listed in the current RSS feed' }
        : null; // feed is bounded; absence cannot prove expiry
    },
  },
  {
    id: 'linkedin',
    // linkedin.com/jobs/view/{id} · .../jobs/view/{title-slug}-{id} · any page that
    // carries the posting in ?currentJobId= (search and collection views).
    //
    // LinkedIn had no rung here, so every LinkedIn URL fell through to Playwright —
    // where /jobs/view/{id} redirects to a generic search page and no verdict can be
    // trusted. The guest endpoint below returns the rendered posting as HTML with no
    // auth and no browser, and it answers 200 for closed postings as well as live
    // ones, so liveness has to come from the body (`interpret`), never from the
    // status code alone.
    match(u) {
      const id = linkedInJobId(u);
      return id ? { id } : null;
    },
    api: ({ id }) => linkedInGuestUrl(id),
    // The endpoint is unauthenticated and rate-limited. Space our calls; the
    // interval sits on the provider so it holds for every caller rather than only
    // the loop in check-liveness.mjs.
    throttleMs: 3_500,
    // We parse HTML here, so ask for it. The endpoint also serves HTML under an
    // application/json Accept, but a request that misdescribes what it wants is one
    // content-negotiation change away from breaking silently.
    accept: 'text/html',
    async interpret(res) {
      let html;
      try {
        html = await res.text();
      } catch {
        return null; // unreadable body → inconclusive, let the browser decide
      }
      return classifyLinkedInPosting(html);
    },
  },
  {
    id: 'nofluffjobs',
    // nofluffjobs.com/pl/job/{slug}, the URL providers/nofluffjobs.mjs writes, and
    // the same posting under /job/{slug} or another language prefix.
    //
    // The browser reads this board backwards (#4832). A live posting puts "Aplikuj"
    // inside a <header> (the posting's own apply block), which the control walk
    // skips as page chrome: 40 of 40 live postings read no_apply_control on
    // 2026-10-18. A closed posting answers 200 and then moves to a search page
    // (/pl/?criteria=...), where an "APLIKUJ ›" promo link reads as an Apply
    // control: 42 of 59 closed postings read active. The board's public
    // per-posting API needs no browser and says which it is.
    match(u) {
      if (u.hostname !== 'nofluffjobs.com' && u.hostname !== 'www.nofluffjobs.com') return null;
      const m = u.pathname.match(/^\/(?:[a-z]{2}\/)?job\/([A-Za-z0-9-]+)\/?$/);
      return m ? { slug: m[1] } : null;
    },
    api: ({ slug }) => `https://nofluffjobs.com/api/posting/${slug}`,
    // Measured 2026-10-18: a live posting answers 200 with status "PUBLISHED", a
    // closed one 200 with status "EXPIRED" (and expiredBeforeDays), and a slug the
    // board does not have 404 {"status":"DOES_NOT_EXIST"}. The 404 body is read
    // too, so only that answer closes a posting, which scan --verify records for
    // good: a 404 saying anything else falls back to the browser.
    interpretStatuses: [200, 404],
    async interpret(res) {
      let posting;
      try { posting = await res.json(); } catch { return null; }
      return classifyNoFluffJobsPosting(posting, res.status);
    },
  },
  {
    id: 'tencent',
    // careers.tencent.com/jobdesc.html?postId={id}, the URL providers/tencent.mjs
    // writes. It usually copies the API's own PostURL, which is plain http (1,920
    // of 2,250 postings on 2026-10-18). The API host is fixed, so the page's
    // scheme is accepted, as for greenhouse-embedded.
    //
    // The browser reads this board wrong both ways (#4832): a live posting's
    // 申请岗位 is not an Apply label it knows (no_apply_control, dropped by
    // scan --verify), and a closed posting moves to /404.html served with a 200
    // (uncertain, kept by scan --verify). The per-posting endpoint the page
    // itself calls tells the two apart.
    acceptsHttp: true,
    match(u) {
      if (u.hostname !== 'careers.tencent.com' || u.pathname !== '/jobdesc.html') return null;
      const id = u.searchParams.get('postId');
      return id && /^\d+$/.test(id) ? { id } : null;
    },
    api: ({ id }) => `https://careers.tencent.com/tencentcareer/api/post/ByPostId?postId=${id}&language=zh-cn`,
    // Measured 2026-10-18: a live posting answers 200 {"Code":200,"Data":{…}},
    // a closed one HTTP 500 {"Code":500,"Data":"E1005"}.
    interpretStatuses: [200, 500],
    api404Authoritative: false, // a closed posting has its own answer
    throttleMs: 1_000,
    async interpret(res, { id }) {
      let json;
      try { json = await res.json(); } catch { return null; }
      return classifyTencentPost(json, id);
    },
  },
  {
    id: 'meituan',
    // zhaopin.meituan.com/web/position/detail?jobUnionId={id}, the URL
    // providers/meituan.mjs writes. The browser misses a live posting's 立即申请
    // (no_apply_control, dropped by scan --verify), and a closed posting's page
    // keeps the same button (#4832), so no Apply label can tell the two apart.
    // The getJobDetail endpoint the page calls can, and it only answers a POST
    // (a GET gets status 0 "请求方式不正确！").
    match(u) {
      if (u.hostname !== 'zhaopin.meituan.com' || u.pathname !== '/web/position/detail') return null;
      const id = u.searchParams.get('jobUnionId');
      return id && /^\d+$/.test(id) ? { id } : null;
    },
    api: () => 'https://zhaopin.meituan.com/api/official/job/getJobDetail',
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: ({ id }) => JSON.stringify({ jobUnionId: id, jobShareType: '1' }),
    api404Authoritative: false, // a closed posting has its own answer, a 200
    throttleMs: 1_000,
    async interpret(res, { id }) {
      let json;
      try { json = await res.json(); } catch { return null; }
      return classifyMeituanJob(json, id);
    },
  },
  {
    id: 'alibaba',
    // talent.alibaba.com/off-campus/position-detail?positionId={id}, the URL
    // providers/alibaba.mjs writes. The site does not deep-link (#2055): that
    // page lands on the home page for any posting, so the browser rung cannot
    // tell a live posting from a closed one and only this rung can.
    match(u) {
      if (u.hostname !== 'talent.alibaba.com' || u.pathname !== '/off-campus/position-detail') return null;
      const id = u.searchParams.get('positionId');
      // The id goes out as a JSON number, as the site sends it; up to 15
      // digits it converts exactly.
      return id && /^\d{1,15}$/.test(id) ? { id } : null;
    },
    api: () => 'https://talent.alibaba.com/position/detail',
    method: 'POST',
    // The stateless double-submit check providers/alibaba.mjs passes with a
    // fresh UUID per run: any matching cookie and header are accepted (this
    // constant measured 2026-10-18), so it needs no pre-request. Without the
    // pair the endpoint answers 403, and a GET 405.
    headers: { 'content-type': 'application/json', cookie: 'XSRF-TOKEN=career-ops', 'x-xsrf-token': 'career-ops' },
    body: ({ id }) => JSON.stringify({ id: Number(id), channel: 'group_official_site' }),
    api404Authoritative: false, // a closed posting has its own answer, a 200
    throttleMs: 1_000,
    async interpret(res, { id }) {
      let json;
      try { json = await res.json(); } catch { return null; }
      return classifyAlibabaPosition(json, id);
    },
  },
  {
    id: 'vdab',
    // www.vdab.be/vindeenjob/vacatures/{id}, the URL providers/vdab.mjs writes;
    // older links add a title slug after the id.
    //
    // A closed vacancy keeps its page and its "Solliciteer nu" button, and only
    // a banner says it is closed, "Deze vacature is niet meer gepubliceerd"
    // (#5244). The browser reads the page while it renders: on 2026-10-22 it
    // read 13 of 87 loads of unpublished vacancies active (the button rendered
    // before the banner) and 5 no_apply_control, as it did 2 of 40 loads of
    // published ones. The detail endpoint the page itself calls has no render
    // to wait for.
    match(u) {
      if (u.hostname !== 'www.vdab.be' && u.hostname !== 'vdab.be') return null;
      const m = u.pathname.match(/^\/vindeenjob\/vacatures\/(\d+)(?:\/[^/]+)?\/?$/);
      return m ? { id: m[1] } : null;
    },
    api: ({ id }) => `https://www.vdab.be/rest/vindeenjob/v4/vacatures/${id}?preview=false`,
    // Without the key the endpoint answers 403, which falls back to the browser,
    // so a rotated key costs this rung, not the check.
    headers: { 'vej-key-monitor': VEJ_KEY_MONITOR },
    // Measured 2026-10-22: a published vacancy answers 200 with gepubliceerd
    // true, an unpublished one 200 with gepubliceerd false and a status, and an
    // id VDAB never had 404 {"code":"NOT_FOUND"}. The 404 body is read too, so
    // a 404 saying anything else falls back to the browser instead of closing
    // the vacancy for good, and so does a 410, which VDAB never answered.
    interpretStatuses: [200, 404],
    api404Authoritative: false,
    async interpret(res, { id }) {
      let json;
      try { json = await res.json(); } catch { return null; }
      return classifyVdabVacancy(json, id, res.status);
    },
  },
];

// LinkedIn renders a closed posting with an explicit banner
// (`<figcaption class="closed-job__flavor--closed">No longer accepting
// applications</figcaption>`) and drops the apply control. A live posting shows one
// of two apply controls: the on-site button, or the off-site sign-in modal.
const LINKEDIN_CLOSED_MARKER = /No longer accepting applications/i;
const LINKEDIN_APPLY_CONTROL = /public_jobs_apply-link-onsite|job-details-topcard-apply-modal/;

/**
 * Decide liveness for one LinkedIn posting from its guest-endpoint HTML.
 * Pure + deterministic (no I/O), mirroring classifyLiveness in liveness-core.mjs.
 *
 * The two signals are read independently and must agree before this concludes
 * anything. A body carrying the closed banner AND an apply control, or neither, is
 * a page we do not recognise — a layout change, a partial render, an interstitial —
 * and it returns `uncertain` rather than picking the likelier answer.
 *
 * The asymmetry is deliberate and is the whole reason for the two-signal rule, and
 * it is this module's CONSERVATIVE BY DESIGN rule applied to a body read rather than
 * a status code: a wrong `expired` costs the user a real job they never see again,
 * while a wrong `uncertain` costs one re-check on the next sweep.
 *
 * @param {any} html - the guest endpoint's response body
 * @returns {{ result: 'active' | 'expired' | 'uncertain', code: string, reason: string } | null}
 *   null = nothing to read (empty or non-string body) → caller falls back.
 */
export function classifyLinkedInPosting(html) {
  if (typeof html !== 'string' || html.length === 0) return null;
  const closed = LINKEDIN_CLOSED_MARKER.test(html);
  const apply = LINKEDIN_APPLY_CONTROL.test(html);
  if (closed && !apply) {
    return {
      result: 'expired',
      code: 'linkedin_closed_marker',
      reason: 'LinkedIn shows "No longer accepting applications" and no apply control',
    };
  }
  if (apply && !closed) {
    return {
      result: 'active',
      code: 'linkedin_apply_control',
      reason: 'LinkedIn shows an apply control and no closure banner (live)',
    };
  }
  return {
    result: 'uncertain',
    code: 'linkedin_signals_disagree',
    reason: closed
      ? 'LinkedIn shows both a closure banner and an apply control — unrecognised page'
      : 'LinkedIn shows neither a closure banner nor an apply control — unrecognised page',
  };
}

// Reserved send times per provider, so back-to-back callers queue behind each
// other instead of all reading the same "last request" timestamp and firing
// together.
const nextRequestAt = new Map();

/**
 * Wait until this provider's next request slot, then reserve the one after it.
 *
 * @param {string} providerId
 * @param {number} [intervalMs] - minimum spacing; falsy means no throttling
 * @returns {Promise<number>} milliseconds actually waited
 */
export async function throttleProviderRequest(providerId, intervalMs) {
  if (!intervalMs) return 0;
  const now = Date.now();
  const earliest = Math.max(now, nextRequestAt.get(providerId) ?? 0);
  nextRequestAt.set(providerId, earliest + intervalMs);
  const wait = earliest - now;
  if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
  return wait;
}

/**
 * Decide liveness for one Ashby posting from its org's job-board API payload.
 * Pure + deterministic (no I/O), mirroring classifyLiveness in liveness-core.mjs.
 *
 * The public board lists only currently-published postings, so a posting that is
 * absent (or explicitly `isListed: false`) has been removed/unlisted → expired.
 * A present, listed posting → active. An unexpected shape → null (inconclusive),
 * so a future API change degrades to a Playwright fallback rather than a false
 * "expired".
 *
 * @param {any} json - parsed job-board response, expected shape `{ jobs: [...] }`
 * @param {string} jobId - the {jobId} from jobs.ashbyhq.com/{org}/{jobId}
 * @returns {{ result: 'active' | 'expired', code: string, reason: string } | null}
 */
export function classifyAshbyBoard(json, jobId) {
  if (!json || !Array.isArray(json.jobs)) return null; // unexpected shape → fall back
  const target = String(jobId).toLowerCase();
  const job = json.jobs.find((j) => typeof j?.id === 'string' && j.id.toLowerCase() === target);
  if (job && job.isListed !== false) {
    return { result: 'active', code: 'ashby_api_ok', reason: 'Ashby posting is listed on the board (live)' };
  }
  return { result: 'expired', code: 'ashby_api_unlisted', reason: 'Ashby posting not listed on the board — removed/unlisted' };
}

/**
 * Decide liveness for one Workable posting from its v2 endpoint JSON.
 * Pure + deterministic (no I/O), mirroring classifyLiveness in liveness-core.mjs.
 *
 * The live shape measured against a real posting is `state: "published"` (#5000);
 * every other readable state stays `uncertain` rather than expired, because the
 * endpoint is authoritative in the removed direction through its 404 alone, and a
 * state this rung does not recognise is exactly the case the browser rung cannot
 * improve on: Workable pages render client-side, so the fallback would call a live
 * posting expired. An unreadable body returns null so a future API change degrades
 * to the browser rung rather than to a verdict.
 *
 * @param {any} posting - the parsed v2 endpoint response
 * @returns {{ result: 'active' | 'uncertain', code: string, reason: string } | null}
 */
export function classifyWorkablePosting(posting) {
  if (!posting || typeof posting !== 'object') return null;
  if (posting.state === 'published') {
    return { result: 'active', code: 'workable_api_published', reason: 'Workable reports the posting published (live)' };
  }
  return {
    result: 'uncertain',
    code: 'workable_state_unrecognised',
    reason: `Workable reports state ${String(posting.state)}; not a verdict this rung can make`,
  };
}

/**
 * Decide liveness for one No Fluff Jobs posting from its /api/posting/{slug} answer.
 * Pure + deterministic (no I/O), mirroring classifyWorkablePosting.
 *
 * "PUBLISHED" is live and "EXPIRED" is the board's own word for closed; on a 404,
 * only "DOES_NOT_EXIST" says the posting is gone. Any other status on a 200 is one
 * this rung has not seen, so it stays uncertain rather than falling to the
 * browser, which reads most closed postings on this board as active. A body with
 * no status, and a 404 saying anything else, return null so a future API change
 * degrades to the browser rung rather than to a verdict.
 *
 * @param {any} posting - the parsed per-posting API response
 * @param {number} [httpStatus=200] - the response's HTTP status (200 or 404)
 * @returns {{ result: 'active' | 'expired' | 'uncertain', code: string, reason: string } | null}
 */
export function classifyNoFluffJobsPosting(posting, httpStatus = 200) {
  if (!posting || typeof posting !== 'object' || typeof posting.status !== 'string' || !posting.status) return null;
  if (httpStatus === 404) {
    return posting.status === 'DOES_NOT_EXIST'
      ? { result: 'expired', code: 'nofluffjobs_api_gone', reason: 'No Fluff Jobs has no posting under this slug (404 DOES_NOT_EXIST)' }
      : null;
  }
  if (posting.status === 'PUBLISHED') {
    return { result: 'active', code: 'nofluffjobs_api_published', reason: 'No Fluff Jobs reports the posting published (live)' };
  }
  if (posting.status === 'EXPIRED') {
    const days = Number.isFinite(posting.expiredBeforeDays) ? ` ${posting.expiredBeforeDays} day(s) ago` : '';
    return { result: 'expired', code: 'nofluffjobs_api_expired', reason: `No Fluff Jobs reports the posting expired${days}` };
  }
  return {
    result: 'uncertain',
    code: 'nofluffjobs_status_unrecognised',
    reason: `No Fluff Jobs reports status ${String(posting.status)}; not a verdict this rung can make`,
  };
}

// True when an id read from a board's answer is THIS posting's id: the same
// string, or a safe integer that prints as it. An array, an object, or a number
// too large to be exact (a 19-digit Tencent id parsed as a number) never matches.
function isSameId(value, id) {
  if (typeof value === 'string') return value === id;
  return Number.isSafeInteger(value) && String(value) === id;
}

/**
 * Decide liveness for one Tencent posting from its ByPostId answer (HTTP 200 or
 * 500). Pure + deterministic (no I/O), mirroring classifyNoFluffJobsPosting.
 *
 * `Code 200` carrying THIS PostId is live. `Code 500` with `Data: "E1005"` is
 * the board's answer for a posting it no longer has; an id that never existed
 * gets it too, and neither belongs in the pipeline. Any other readable answer,
 * a Code 200 for another PostId included, stays uncertain rather than falling
 * to the browser, which misreads this board both ways (#4832). An unreadable
 * body returns null so the browser rung decides.
 *
 * @param {any} json - parsed ByPostId body
 * @param {string} postId - the postId query parameter of the posting URL
 * @returns {{ result: 'active' | 'expired' | 'uncertain', code: string, reason: string } | null}
 */
export function classifyTencentPost(json, postId) {
  if (!json || typeof json !== 'object') return null;
  if (json.Code === 200 && isSameId(json.Data?.PostId, postId)) {
    return { result: 'active', code: 'tencent_api_active', reason: 'Tencent returns the posting (live)' };
  }
  if (json.Code === 500 && json.Data === 'E1005') {
    return { result: 'expired', code: 'tencent_api_e1005', reason: 'Tencent answers E1005: posting closed or removed' };
  }
  // Data is a string on every non-200 answer seen; name anything else by its type.
  const data = typeof json.Data === 'string' ? json.Data.slice(0, 80) : json.Data === null ? 'null' : typeof json.Data;
  return {
    result: 'uncertain',
    code: 'tencent_answer_unrecognised',
    reason: json.Code === 200
      ? 'Tencent answers Code 200 without this PostId; not a verdict this rung can make'
      : `Tencent answers Code ${String(json.Code)}, Data ${data}; not a verdict this rung can make`,
  };
}

/**
 * Decide liveness for one Meituan posting from its getJobDetail answer.
 * Pure + deterministic (no I/O), mirroring classifyTencentPost.
 *
 * A closed posting keeps `status: 1` and its whole record; only `jobStatus`
 * changes, from "000" (live) to "001" (closed). Any other readable answer
 * (another jobStatus, a record for another id, or `status: 0` "职位已下线或不存在！",
 * seen only for ids that never existed and for a wrong request method) stays
 * uncertain rather than falling to the browser, which cannot tell live from
 * closed on this board (#4832). An unreadable body returns null so the browser
 * rung decides.
 *
 * @param {any} json - parsed getJobDetail body
 * @param {string} jobUnionId - the jobUnionId query parameter of the posting URL
 * @returns {{ result: 'active' | 'expired' | 'uncertain', code: string, reason: string } | null}
 */
export function classifyMeituanJob(json, jobUnionId) {
  if (!json || typeof json !== 'object') return null;
  if (json.status !== 1 || !isSameId(json.data?.jobUnionId, jobUnionId)) {
    return {
      result: 'uncertain',
      code: 'meituan_answer_unrecognised',
      reason: json.status === 1
        ? 'Meituan answers status 1 without this jobUnionId; not a verdict this rung can make'
        : `Meituan answers status ${String(json.status)}; not a verdict this rung can make`,
    };
  }
  if (json.data.jobStatus === '000') {
    return { result: 'active', code: 'meituan_api_open', reason: 'Meituan reports jobStatus "000" (live)' };
  }
  if (json.data.jobStatus === '001') {
    return { result: 'expired', code: 'meituan_api_closed', reason: 'Meituan reports jobStatus "001" (closed)' };
  }
  return {
    result: 'uncertain',
    code: 'meituan_answer_unrecognised',
    reason: `Meituan reports jobStatus ${String(json.data.jobStatus)}; not a verdict this rung can make`,
  };
}

/**
 * Decide liveness for one Alibaba posting from its position/detail answer.
 * Pure + deterministic (no I/O), mirroring classifyTencentPost.
 *
 * Every measured answer was a 200 with `success: true`. A `content` carrying
 * THIS id is live, and `content: null` is the answer for a posting the board
 * no longer has (or never had). Any other readable answer, a failed call
 * (`success` not true, the in-band error providers/alibaba.mjs also checks) or
 * a record for another id, stays uncertain rather than falling to the browser,
 * which cannot tell live from closed on this board (#2055). An unreadable body
 * returns null so the browser rung decides.
 *
 * @param {any} json - parsed position/detail body
 * @param {string} id - the positionId query parameter of the posting URL
 * @returns {{ result: 'active' | 'expired' | 'uncertain', code: string, reason: string } | null}
 */
export function classifyAlibabaPosition(json, id) {
  if (!json || typeof json !== 'object') return null;
  if (json.success === true && json.content === null) {
    return { result: 'expired', code: 'alibaba_api_no_content', reason: 'Alibaba returns no position for the id: closed or removed' };
  }
  if (json.success === true && isSameId(json.content?.id, id)) {
    return { result: 'active', code: 'alibaba_api_active', reason: 'Alibaba returns the position (live)' };
  }
  return {
    result: 'uncertain',
    code: 'alibaba_answer_unrecognised',
    reason: json.success === true
      ? 'Alibaba answers success true without this position id; not a verdict this rung can make'
      : `Alibaba answers success ${String(json.success)}, errorCode ${String(json.errorCode)}; not a verdict this rung can make`,
  };
}

/**
 * Decide liveness for one VDAB vacancy from its detail answer (HTTP 200 or 404).
 * Pure + deterministic (no I/O), mirroring classifyNoFluffJobsPosting.
 *
 * `gepubliceerd` is what the page's closed banner reports ("Deze vacature is
 * niet meer gepubliceerd"): true is live. An unpublished vacancy's `status`
 * says why. PASSIEF is closed. HANGEND (pending) also covers vacancies VDAB has
 * not published yet, so it stays uncertain: an expired verdict is one
 * scan --verify records for good. An unpublished status this rung has not seen
 * stays uncertain too. On a 404, only NOT_FOUND says the id is gone. A record
 * for another vacancy, or one without the flag, returns null so the browser
 * rung decides.
 *
 * @param {any} json - the parsed detail response
 * @param {string} id - the vacancy id from the posting URL
 * @param {number} [httpStatus=200] - the response's HTTP status (200 or 404)
 * @returns {{ result: 'active' | 'expired' | 'uncertain', code: string, reason: string } | null}
 */
export function classifyVdabVacancy(json, id, httpStatus = 200) {
  if (!json || typeof json !== 'object') return null;
  if (httpStatus === 404) {
    return json.code === 'NOT_FOUND'
      ? { result: 'expired', code: 'vdab_api_gone', reason: 'VDAB has no vacancy under this id (404 NOT_FOUND)' }
      : null;
  }
  if (!isSameId(json.referentie?.id, id) || typeof json.gepubliceerd !== 'boolean') return null;
  if (json.gepubliceerd) {
    return { result: 'active', code: 'vdab_api_published', reason: 'VDAB reports the vacancy published (live)' };
  }
  if (json.status === 'PASSIEF') {
    return { result: 'expired', code: 'vdab_api_closed', reason: 'VDAB reports the vacancy no longer published (PASSIEF)' };
  }
  if (json.status === 'HANGEND') {
    return { result: 'uncertain', code: 'vdab_api_pending', reason: 'VDAB reports the vacancy pending (HANGEND): not published, and not closed' };
  }
  return {
    result: 'uncertain',
    code: 'vdab_status_unrecognised',
    reason: `VDAB reports the vacancy unpublished with status ${String(json.status)}; not a verdict this rung can make`,
  };
}

/**
 * Classify one HireHive per-posting API answer (see the `hirehive` entry).
 * A 200 counts only when the body is the posting the URL names.
 * @param {any} json
 * @param {string} id - `job_<shortid>` (v2) or the posting number (v1)
 * @param {number} httpStatus
 */
export function classifyHireHivePosting(json, id, httpStatus = 200) {
  if (httpStatus === 404) {
    return json?.message === 'Job is not published'
      ? { result: 'expired', code: 'hirehive_unpublished', reason: 'HireHive API: "Job is not published" (the posting page says the job is no longer available)' }
      : null;
  }
  if (httpStatus !== 200 || !json || String(json.id) !== String(id) || typeof json.title !== 'string' || !json.title.trim()) return null;
  return { result: 'active', code: 'hirehive_api_ok', reason: 'HireHive API returns the published posting (live)' };
}

/**
 * Decide liveness for one Zoho Recruit posting from its own page.
 * Pure + deterministic (no I/O), mirroring classifyAshbyBoard.
 *
 * A live posting page embeds its record; a record for THIS id marked
 * `Is_Locked` or unpublished is a posting the career site shows as filled
 * (expired), any other record for it is live. A removed posting is a 200 page
 * with no record and Zoho's "This job posting is no longer available." notice.
 * Anything else (a record for another id, an error page, a markup change)
 * returns null so the browser rung decides.
 *
 * @param {any} html - the posting page's body
 * @param {string} id - the {id} path segment from the posting URL
 * @returns {{ result: 'active' | 'expired', code: string, reason: string } | null}
 */
export function classifyZohoPostingPage(html, id) {
  if (typeof html !== 'string' || !html) return null;
  const record = parseZohoDetailPage(html);
  if (record) {
    if (String(record.id) !== String(id)) return null;
    return isZohoRecordClosed(record)
      ? { result: 'expired', code: 'zoho_recruit_filled', reason: 'Zoho Recruit marks the posting locked or unpublished (filled)' }
      : { result: 'active', code: 'zoho_recruit_page_ok', reason: 'Zoho Recruit posting page carries the open posting (live)' };
  }
  return /This job posting is no longer available/i.test(html)
    ? { result: 'expired', code: 'zoho_recruit_unavailable', reason: 'Zoho Recruit shows "This job posting is no longer available."' }
    : null;
}

// The notice on UKG's empty detail page, the one the browser shows as "This
// opportunity is currently not available." An internal-only posting's page has
// no record either, but carries a sign-in notice instead, so it does not match.
const ULTIPRO_UNAVAILABLE_NOTICE = 'data-i18n="Opportunity.OpportunityError.OpportunityUnavailableMessage"';

/**
 * Decide liveness for one UltiPro (UKG Pro Recruiting) posting from its own
 * detail page. Pure + deterministic (no I/O), mirroring classifyZohoPostingPage.
 *
 * A posting's page embeds its record, and the record for THIS id says whether
 * it is closed: `OpportunityIsClosed` false is live, true is closed (a closed
 * posting can keep its whole page, only without an Apply control). A posting
 * UKG no longer shows gets the board's empty page: no record, and the
 * "opportunity unavailable" notice. Anything else (a record for another id or
 * without the flag, an internal-only notice, an error page, a markup change)
 * returns null so the browser rung decides.
 *
 * @param {any} html - the detail page's body
 * @param {string} id - the opportunityId from the posting URL
 * @returns {{ result: 'active' | 'expired', code: string, reason: string } | null}
 */
export function classifyUltiproDetailPage(html, id) {
  if (typeof html !== 'string' || !html) return null;
  let page;
  try {
    page = extractCandidateOpportunityDetail(html, id);
  } catch {
    return null; // a record for another id, or one that no longer parses
  }
  if (page.status === 'ok') {
    const closed = page.detail.OpportunityIsClosed;
    if (typeof closed !== 'boolean') return null;
    return closed
      ? { result: 'expired', code: 'ultipro_api_closed', reason: 'UKG marks the opportunity closed (OpportunityIsClosed)' }
      : { result: 'active', code: 'ultipro_api_open', reason: 'UKG marks the opportunity open (live)' };
  }
  return html.includes(ULTIPRO_UNAVAILABLE_NOTICE)
    ? { result: 'expired', code: 'ultipro_api_unavailable', reason: 'UKG shows "This opportunity is currently not available."' }
    : null;
}

/**
 * Decide liveness for one Workday posting from the body of a 403 on its per-job
 * CXS endpoint. Pure + deterministic (no I/O), mirroring classifyAshbyBoard.
 *
 * On this endpoint a live posting is a 200 and a missing one is a 404, both
 * concluded from the status alone by the generic path. A withdrawn posting is a
 * 403 whose JSON body carries `errorCode: "S22"`, "permission denied" — the
 * only case where the body decides. Only that exact S22 shape reads as expired;
 * any other 403 body — a WAF or bot-wall page, or a Workday error with a
 * different code — stays inconclusive.
 *
 * @param {any} json - parsed body of a 403 from the CXS per-job endpoint
 * @returns {{ result: 'expired', code: string, reason: string } | null}
 */
export function classifyWorkday403(json) {
  return json?.httpStatus === 403 && json?.errorCode === 'S22'
    ? { result: 'expired', code: 'workday_api_withdrawn', reason: 'Workday CXS answers 403 S22 — posting withdrawn' }
    : null;
}

/**
 * Map a posting URL to its ATS API URL, or null if it isn't a known ATS posting
 * (or any extracted segment fails the strict charset). Pure + deterministic.
 * @param {string} rawUrl
 * @returns {{ ats: string, apiUrl: string, method: string, body?: string, parts: Record<string, string>, timeoutMs?: number, throttleMs?: number, accept?: string, interpret?: (res: Response, parts: Record<string, string>, signal: AbortSignal) => Promise<{ result: 'active' | 'expired' | 'uncertain', code: string, reason: string } | null>, interpretStatuses?: number[], api404Authoritative: boolean } | null}
 */
export function resolveAtsApi(rawUrl) {
  let u;
  try {
    u = new URL(rawUrl);
  } catch {
    return null;
  }
  if (u.protocol !== 'https:' && u.protocol !== 'http:') return null;
  const plainHttp = u.protocol === 'http:';
  for (const provider of ATS_PROVIDERS) {
    // Plain http resolves only for a provider that opts in: one whose API host is
    // fixed and never derived from the page URL, so the page's scheme is irrelevant.
    if (plainHttp && !provider.acceptsHttp) continue;
    const parts = provider.match(u);
    if (!parts) continue;
    // SSRF guard: every derived value must be safe — a single path segment for
    // most providers, or (Workday) a slash-separated sequence of safe segments.
    // isSafeValue enforces the same charset + no-".." rule either way.
    if (!Object.values(parts).every(isSafeValue)) return null;
    return {
      ats: provider.id,
      apiUrl: provider.api(parts),
      method: provider.method || 'GET',
      body: provider.body?.(parts),
      parts,
      timeoutMs: provider.timeoutMs,
      throttleMs: provider.throttleMs,
      accept: provider.accept,
      headers: typeof provider.headers === 'function' ? provider.headers(parts) : provider.headers,
      followEmbed: provider.followEmbed,
      interpret: provider.interpret,
      interpretStatuses: provider.interpretStatuses,
      api404Authoritative: provider.api404Authoritative !== false,
      interpretBoard: provider.interpretBoard,
    };
  }
  return null;
}

/** True if `url` is an ATS posting we can check via API (lets callers stay lazy about the browser). */
export function isAtsPosting(url) {
  return resolveAtsApi(url) !== null;
}

// ATS ids whose public API returns the actual JD body (not just a liveness
// signal). Greenhouse (`content`), Lever (`descriptionPlain`), Ashby
// (`descriptionPlain` on the org board), Workday (`jobPostingInfo.jobDescription`
// on the per-job CXS endpoint) and SmartRecruiters (`jobAd.sections`) all ship
// full text for free in the same payload resolveAtsApi() already points at.
// greenhouse-embedded (a company careers page carrying only `?gh_jid=`) reaches
// the same per-job Greenhouse endpoint once its embed redirect names the board.
// Zoho Recruit has no JSON API; the posting page resolveAtsApi() points at
// embeds the record with its HTML `Job_Description`. UltiPro is the same: its
// detail page embeds the `CandidateOpportunityDetail` record with its HTML
// `Description`. HiBob's per-posting endpoint carries the posting's HTML
// description, responsibilities, requirements and benefits.
// Workable canonical and share links expose description, requirements and benefits
// on the per-posting v2 API, after the existing guarded account-resolution hop.
// HireHive's per-posting API carries the description HTML.
// Microsoft and LinkedIn are on ATS_PROVIDERS
// for liveness only — their public endpoints answer search/status, never body
// text — so they are deliberately excluded here; see fetch-jd.mjs / the
// fetch*Jd() family in browser-extract.mjs for the per-provider fetchers.
//
// One ATS per line, in alphabetical order: PRs that add different ATSes then
// touch different lines, which reduces merge conflicts.
export const JD_TEXT_API_ATS = new Set([
  'ashby',
  'greenhouse',
  'greenhouse-embedded',
  'hibob',
  'hirehive',
  'lever',
  'smartrecruiters',
  'ultipro',
  'workable',
  'workable-short',
  'workday',
  'zoho-recruit',
]);

/**
 * Zero-token liveness check via the posting's ATS API.
 * @param {string} url
 * @param {{ boardCache?: Map<string, unknown> }} [options]
 *   boardCache: for a provider whose API is the whole board (Ashby), the parsed
 *   board is kept here under its API URL and reused for the next posting on the
 *   same board. Only a 200 that parsed into a board is kept; anything else is
 *   retried next time.
 *   Without it, every posting fetches its board, as before.
 * @returns {Promise<{ result: 'active' | 'expired' | 'uncertain', code: string, reason: string } | null>}
 *   null = not a known ATS posting, or inconclusive → caller should fall back to Playwright.
 *   `uncertain` is a conclusion in its own right: the provider reached the posting
 *   and could not read it, and no other rung would do better.
 */
export async function checkLivenessViaApi(url, { boardCache } = {}) {
  const resolved = resolveAtsApi(url);
  if (!resolved) return null;
  const { ats, apiUrl, method, body, parts, interpret, interpretStatuses, timeoutMs, throttleMs, accept, headers, followEmbed, api404Authoritative, interpretBoard } = resolved;
  const cacheBoard = Boolean(boardCache && interpretBoard);
  // Checked before the throttle: a board already in hand costs no request.
  if (cacheBoard && boardCache.has(apiUrl)) return interpretBoard(boardCache.get(apiUrl), parts);

  // Wait out any provider rate limit BEFORE arming the timeout, so the spacing
  // does not eat the budget the request itself needs.
  await throttleProviderRequest(ats, throttleMs);

  // The timeout guards the whole classification (fetch + any `interpret` body read),
  // since aborting the shared signal also tears down an in-flight res.json().
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs || TIMEOUT_MS);
  try {
    let res;
    try {
      res = await fetch(apiUrl, {
        method,
        headers: { 'user-agent': DEFAULT_USER_AGENT, accept: accept || 'application/json', ...headers },
        body,
        redirect: followEmbed ? 'manual' : 'error',
        signal: controller.signal,
      });
      if (followEmbed) {
        const jobApiUrl = await followEmbed(res, parts);
        if (!jobApiUrl) return null;
        res = await fetch(jobApiUrl, {
          method: 'GET',
          headers: { 'user-agent': DEFAULT_USER_AGENT, accept: 'application/json' },
          redirect: 'error',
          signal: controller.signal,
        });
      }
    } catch {
      return null; // network / timeout / redirect → inconclusive, let Playwright decide
    }

    if ((res.status === 404 || res.status === 410) && !interpretStatuses?.includes(res.status)) {
      if (!api404Authoritative) return null; // inconclusive → let Playwright check the real page
      return { result: 'expired', code: `${ats}_api_gone`, reason: `ATS API ${res.status} — posting removed` };
    }
    // Providers with an `interpret` step read the body of the statuses they
    // list (by default the 200: org-level Ashby, and per-job APIs whose 200 can
    // still describe a closed posting); any other 200 is proof the posting is live.
    if (cacheBoard && res.status === 200) {
      let json;
      try {
        json = await res.json();
      } catch {
        return null; // unparseable body → inconclusive, and not cached
      }
      // Kept only when it classifies: a 200 whose body is not a board (no
      // `jobs` array) stays uncached, so the next posting retries the API.
      const verdict = interpretBoard(json, parts);
      if (verdict) boardCache.set(apiUrl, json);
      return verdict;
    }
    if (interpret && (interpretStatuses || [200]).includes(res.status)) return await interpret(res, parts, controller.signal);
    if (res.status === 200) {
      return { result: 'active', code: `${ats}_api_ok`, reason: 'ATS API returns the posting (live)' };
    }
    return null; // 429/5xx/other → inconclusive, fall back to the browser check
  } catch {
    return null; // interpret abort / unexpected error → inconclusive
  } finally {
    clearTimeout(timer);
  }
}