jd-intel 0.9.0 → 0.11.0

package/src/adapters/smartrecruiters.js

@@ -1,11 +1,14 @@
-import { normalize } from '../normalizer.js';
+import { normalize, missingContent } from '../normalizer.js';
 import { atsErrorFromStatus } from '../errors.js';
+import { atsFetch, probeResult } from '../http.js';
+import { prefilterRows } from '../filters.js';
 
 const BASE_URL = 'https://api.smartrecruiters.com/v1/companies';
 const PAGE_SIZE = 100;
+const MAX_DETAIL_FETCHES = 100;
 
 /**
- * Fetch all postings from a SmartRecruiters company.
+ * Fetch postings from a SmartRecruiters company.
  * Public API, no auth required.
  * Docs: https://developers.smartrecruiters.com/reference/postingsget-1
  *
@@ -14,21 +17,29 @@ const PAGE_SIZE = 100;
  *     and the structured `compensation` block with it.
  *   - jd-intel's contract is "full JD text", so we must fetch each
  *     posting's DETAIL endpoint to get jobAd.sections.
- * Large enterprise tenants with hundreds of openings will therefore be
- * slow against SmartRecruiters specifically. This is the API's shape,
- * not a bug here.
+ *
+ * The list does carry name, location and releasedDate, so the same
+ * pre-filter and detail budget Workday applies run here: list-evaluable
+ * filters narrow the candidates, then at most MAX_DETAIL_FETCHES of them
+ * are hydrated (see prefilterRows). Without a filterContext the
+ * cap still holds, so a direct call on a 400-posting tenant reads 100.
  *
  * @param {string} slug - SmartRecruiters company identifier (e.g., 'Visa')
+ * @param {object} [ctx] - { filterContext, report }; report is called once
+ *   with { listed, prefiltered, hydrated, capped, org_name, org_url }
+ *   when given
  * @returns {Promise<Array>} Normalized job objects
  */
-export async function fetchSmartrecruiters(slug) {
+export async function fetchSmartrecruiters(slug, ctx = {}) {
+  const fc = ctx.filterContext || {};
+
   // 1. Page through the postings list.
   const postings = [];
   let offset = 0;
 
   while (true) {
     const listUrl = `${BASE_URL}/${slug}/postings?limit=${PAGE_SIZE}&offset=${offset}`;
-    const resp = await fetch(listUrl);
+    const resp = await atsFetch(listUrl);
 
     if (!resp.ok) {
       if (resp.status === 404) return []; // Company not found
@@ -43,22 +54,61 @@ export async function fetchSmartrecruiters(slug) {
     if (content.length === 0 || offset >= (data.totalFound || 0)) break;
   }
 
-  // 2. Fetch detail per posting for the description.
-  const jobs = await Promise.all(postings.map(async (p) => {
+  // 2. Filter-aware candidate selection BEFORE the N+1 detail cost, then
+  //    the detail budget (see prefilterRows). The list row carries name,
+  //    location and releasedDate. The detail adds no location (unlike
+  //    Workday's additionalLocations), so a row with none follows the
+  //    library's rule now: out under includes, kept under excludes.
+  //    postedAt comes from releasedDate alone, so a missing or unparseable
+  //    date is out, as it is in the library.
+  const { candidates, hydrate } = prefilterRows(postings, fc, {
+    title: p => p.name || '',
+    location: p => listLocation(p).location.toLowerCase(),
+    postedWithin: (p, days) => {
+      const released = new Date(p.releasedDate || '').getTime();
+      return Number.isFinite(released) && released >= Date.now() - days * 86400000;
+    },
+    max: MAX_DETAIL_FETCHES,
+  });
+
+  // Every list row carries company { identifier, name }. Neither the list
+  // nor the detail has a company website, and postingUrl is always on
+  // jobs.smartrecruiters.com, so org_url stays null (issue #58).
+  if (typeof ctx.report === 'function') {
+    ctx.report({
+      listed: postings.length,
+      prefiltered: candidates.length,
+      hydrated: hydrate.length,
+      capped: hydrate.length < candidates.length,
+      org_name: postings.find(p => p.company?.name)?.company.name || null,
+      org_url: null,
+    });
+  }
+
+  // 4. Fetch detail per candidate for the description. atsFetch's per-host
+  //    queue keeps this fan-out to 4 requests at a time (a 412-posting
+  //    tenant measured 53s unbounded), so the cap also holds the detail
+  //    step to roughly 13s.
+  const jobs = await Promise.all(hydrate.map(async (p) => {
     let sections = {};
     let postingUrl = '';
     let salary = null;
+    let content; // set only when the detail could not be read (issue #85)
 
     try {
-      const detailResp = await fetch(`${BASE_URL}/${slug}/postings/${p.id}`);
+      const detailResp = await atsFetch(`${BASE_URL}/${slug}/postings/${p.id}`);
       if (detailResp.ok) {
         const detail = await detailResp.json();
         sections = detail.jobAd?.sections || {};
         postingUrl = detail.postingUrl || detail.applyUrl || '';
         salary = parseCompensation(detail.compensation);
+      } else {
+        content = missingContent(detailResp);
       }
-    } catch {
-      // Detail fetch failed: fall back to list-only fields (no description).
+    } catch (err) {
+      // Detail fetch failed, retries included: list-only fields (no
+      // description, no url), marked missing.
+      content = missingContent(err);
     }
 
     const description = [
@@ -67,18 +117,7 @@ export async function fetchSmartrecruiters(slug) {
       sections.additionalInformation?.text,
     ].filter(Boolean).join('\n\n');
 
-    const loc = p.location || {};
-    const place = loc.fullLocation
-      || [loc.city, loc.region, loc.country].filter(Boolean).join(', ');
-    let location = place;
-    let workplace = null;
-    if (loc.remote) {
-      location = `Remote - ${place}`.replace(/ - $/, ' ');
-      workplace = 'remote';
-    } else if (loc.hybrid) {
-      location = `Hybrid - ${place}`.replace(/ - $/, ' ');
-      workplace = 'hybrid';
-    }
+    const { location, workplace } = listLocation(p);
 
     return normalize({
       companySlug: slug,
@@ -91,6 +130,7 @@ export async function fetchSmartrecruiters(slug) {
       url: postingUrl,
       postedAt: p.releasedDate || null,
       salary, // null when the detail has no compensation; normalize() then parses text
+      content,
       metadata: {
         smartRecruitersId: p.id,
         refNumber: p.refNumber || '',
@@ -104,6 +144,20 @@ export async function fetchSmartrecruiters(slug) {
   return jobs;
 }
 
+/**
+ * The location string and workplace type a list row yields. Built once
+ * here so the pre-filter matches exactly what the normalized job carries,
+ * "Remote - " and "Hybrid - " prefixes included.
+ */
+function listLocation(p) {
+  const loc = p.location || {};
+  const place = loc.fullLocation
+    || [loc.city, loc.region, loc.country].filter(Boolean).join(', ');
+  if (loc.remote) return { location: `Remote - ${place}`.replace(/ - $/, ' '), workplace: 'remote' };
+  if (loc.hybrid) return { location: `Hybrid - ${place}`.replace(/ - $/, ' '), workplace: 'hybrid' };
+  return { location: place, workplace: null };
+}
+
 const PERIODS = { YEARLY: 'year', MONTHLY: 'month', HOURLY: 'hour' };
 
 /**
@@ -130,20 +184,16 @@ function parseCompensation(comp) {
 }
 
 /**
- * Check if a company exists on SmartRecruiters.
- * (HEAD isn't reliably supported on the postings endpoint, so use a
- * minimal GET.)
+ * Check if a company exists on SmartRecruiters. See probeResult for the
+ * outcomes. (HEAD isn't reliably supported on the postings endpoint, so
+ * use a minimal GET.)
  */
 export async function hasSmartrecruiters(slug) {
-  try {
-    const resp = await fetch(`${BASE_URL}/${slug}/postings?limit=1`);
-    if (!resp.ok) return false;
-    // SmartRecruiters returns 200 with an empty page (not 404) for unknown
-    // companies, so resp.ok alone false-positives on any slug. Confirm at
-    // least one real posting exists before claiming a match.
-    const data = await resp.json();
-    return (data.totalFound || 0) > 0 || (data.content || []).length > 0;
-  } catch {
-    return false;
-  }
+  const resp = await atsFetch(`${BASE_URL}/${slug}/postings?limit=1`);
+  if (!probeResult(resp, `SmartRecruiters probe for ${slug}`)) return false;
+  // SmartRecruiters returns 200 with an empty page (not 404) for unknown
+  // companies, so resp.ok alone false-positives on any slug. Confirm at
+  // least one real posting exists before claiming a match.
+  const data = await resp.json();
+  return (data.totalFound || 0) > 0 || (data.content || []).length > 0;
 }

package/src/adapters/teamtailor.js

@@ -1,5 +1,7 @@
 import { normalize, decodeEntities } from '../normalizer.js';
 import { atsErrorFromStatus } from '../errors.js';
+import { atsFetch } from '../http.js';
+import { orgHost } from '../boards.js';
 
 /**
  * Fetch jobs from a TeamTailor career site via its public RSS feed.
@@ -23,26 +25,33 @@ import { atsErrorFromStatus } from '../errors.js';
  * collapse by one layer per pass.
  *
  * @param {string} slug - TeamTailor career-site slug (e.g., 'tibber')
+ * @param {object} [ctx] - { report }; report is called once with
+ *   { org_name, org_url } when given
  * @returns {Promise<Array>} Normalized job objects
  */
 // Most sites are {slug}.teamtailor.com, but some sit on a regional
-// segment, e.g. crunchbase.na.teamtailor.com. '' is the base host.
-const TT_REGIONS = ['', 'na', 'eu'];
+// segment, e.g. crunchbase.na.teamtailor.com. '' is the base host. There
+// is no reachable eu segment: {slug}.eu.teamtailor.com fails TLS for every
+// slug, known or not, because the wildcard certificate covers one label
+// only (live check 2026-09-27). Probing it was a guaranteed failure that
+// the has() contract would now report as an outage.
+const TT_REGIONS = ['', 'na'];
 
 // Feeds send `none`, `hybrid`, `fully` or `onsite`. `none` is no signal.
 const REMOTE_STATUS = { hybrid: 'hybrid', fully: 'remote', onsite: 'onsite' };
 
 /**
  * Resolve which TeamTailor host actually serves this slug's feed.
- * Returns the first 200 Response, throws on a non-404 error, or
- * returns null if no region has a feed.
+ * Returns the first 200 Response, throws on a non-404 error (atsFetch
+ * throws the 429, 5xx and network cases itself), or returns null if no
+ * region has a feed.
  */
 async function resolveFeed(slug, method = 'GET') {
   for (const region of TT_REGIONS) {
     const host = region
       ? `${slug}.${region}.teamtailor.com`
       : `${slug}.teamtailor.com`;
-    const resp = await fetch(`https://${host}/jobs.rss`, {
+    const resp = await atsFetch(`https://${host}/jobs.rss`, {
       method,
       redirect: 'follow',
     });
@@ -55,18 +64,32 @@ async function resolveFeed(slug, method = 'GET') {
   return null;
 }
 
-export async function fetchTeamtailor(slug) {
+export async function fetchTeamtailor(slug, ctx = {}) {
   const resp = await resolveFeed(slug, 'GET');
   if (!resp) return []; // No TeamTailor site in any known region
 
   const xml = await resp.text();
 
-  const company = (
-    xml.match(/<channel>[\s\S]*?<title>([\s\S]*?)<\/title>/)?.[1] || slug
-  ).trim();
+  const channelTitle = (xml.match(/<channel>[\s\S]*?<title>([\s\S]*?)<\/title>/)?.[1] || '').trim();
+  const company = channelTitle || slug;
 
   const items = [...xml.matchAll(/<item>([\s\S]*?)<\/item>/g)].map(m => m[1]);
 
+  // The channel title is the company as the site names itself. The channel
+  // <link> always sits on {slug}.teamtailor.com, but item links follow the
+  // site's custom domain when it has one (jobs.tibber.com on a feed served
+  // from tibber.teamtailor.com), so the first item's link is the host that
+  // can say something; the channel link is the fallback for an empty feed.
+  if (typeof ctx.report === 'function') {
+    const link = items[0]?.match(/<link>([\s\S]*?)<\/link>/)?.[1]
+      || xml.match(/<channel>[\s\S]*?<link>([\s\S]*?)<\/link>/)?.[1]
+      || '';
+    ctx.report({
+      org_name: decodeEntities(channelTitle) || null,
+      org_url: orgHost(link.trim()),
+    });
+  }
+
   return items.map(item => {
     const pick = (tag, src = item) => {
       const m = src.match(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`));
@@ -120,12 +143,10 @@ export async function fetchTeamtailor(slug) {
 }
 
 /**
- * Check if a company has a TeamTailor career site.
+ * Check if a company has a TeamTailor career site: true when a regional
+ * host serves the feed, false when every host answers 404, and the
+ * AtsError from resolveFeed for anything else.
  */
 export async function hasTeamtailor(slug) {
-  try {
-    return (await resolveFeed(slug, 'HEAD')) !== null;
-  } catch {
-    return false;
-  }
+  return (await resolveFeed(slug, 'HEAD')) !== null;
 }

package/src/adapters/workday.js

@@ -1,5 +1,8 @@
-import { normalize } from '../normalizer.js';
+import { normalize, missingContent } from '../normalizer.js';
 import { atsErrorFromStatus } from '../errors.js';
+import { prefilterRows } from '../filters.js';
+import { atsFetch } from '../http.js';
+import { orgHost } from '../boards.js';
 
 const MAX_DETAIL_FETCHES = 100;
 const LIST_PAGE_SIZE = 20;
@@ -30,7 +33,9 @@ const MULTI_LOCATION = /^\s*\d+\s+locations?\s*$/;
  * detail set.
  *
  * @param {string} slug - normalized company slug (registry routing key)
- * @param {object} [ctx] - { config:{tenant,env,site}, companyName, filterContext }
+ * @param {object} [ctx] - { config:{tenant,env,site}, companyName, filterContext, report };
+ *   report is called once, after hydration, with
+ *   { listed, prefiltered, hydrated, capped, org_name, org_url } when given
  * @returns {Promise<Array>} Normalized job objects
  */
 export async function fetchWorkday(slug, ctx = {}) {
@@ -46,12 +51,25 @@ export async function fetchWorkday(slug, ctx = {}) {
   let offset = 0;
   let pages = 0;
   let firstTotal = 0;
-  while (pages < LIST_PAGE_HARD_CAP) {
-    const resp = await fetch(`${base}/jobs`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ appliedFacets: {}, limit: LIST_PAGE_SIZE, offset, searchText: '' }),
-    });
+  let listCapped = false;
+  while (true) {
+    if (pages >= LIST_PAGE_HARD_CAP) {
+      listCapped = true;
+      break;
+    }
+    let resp;
+    try {
+      resp = await atsFetch(`${base}/jobs`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ appliedFacets: {}, limit: LIST_PAGE_SIZE, offset, searchText: '' }),
+      });
+    } catch (err) {
+      // A 429 or 5xx that outlasted the retries, or a network failure.
+      // After the first page, keep the postings already read.
+      if (offset === 0) throw err;
+      break;
+    }
 
     if (!resp.ok) {
       if (offset === 0) {
@@ -74,69 +92,53 @@ export async function fetchWorkday(slug, ctx = {}) {
     if (firstTotal > 0 && offset >= firstTotal) break;
   }
 
-  // 2. Filter-aware candidate selection BEFORE the N+1 detail cost.
-  //    The list carries title/locationsText/postedOn — enough to apply
-  //    titleFilter, location, and recency without descriptions.
-  let candidates = postings;
-
-  if (fc.titleFilter) {
-    const re = new RegExp(fc.titleFilter, 'i');
-    candidates = candidates.filter(p => re.test(p.title || ''));
-  }
-  if (Array.isArray(fc.locationIncludes) && fc.locationIncludes.length > 0) {
-    const inc = fc.locationIncludes.map(s => String(s).toLowerCase());
-    candidates = candidates.filter(p => {
+  // 2. Filter-aware candidate selection BEFORE the N+1 detail cost, then
+  //    the detail budget (see prefilterRows). The list carries
+  //    title/locationsText/postedOn, enough to apply titleFilter, location
+  //    and recency without descriptions. "2 Locations" says nothing about
+  //    where: the row stays a candidate through both location filters and
+  //    the library's pass after hydration decides on the detail's location
+  //    list (issue #61).
+  //    NOTE: huge-tenant coverage is intentionally capped for v1. Two caps
+  //    apply: the list scan above stops at LIST_PAGE_HARD_CAP pages (2000
+  //    postings, enough for Salesforce's ~1398), and the detail set is cut
+  //    to MAX_DETAIL_FETCHES here. Proper fix (smart pagination, surfaced
+  //    truncation) is tracked in #26.
+  const { candidates, hydrate } = prefilterRows(postings, fc, {
+    title: p => p.title || '',
+    location: p => {
       const loc = (p.locationsText || '').toLowerCase();
-      // "2 Locations" says nothing about where. The row stays a candidate
-      // and the pass after hydration decides on the detail's location list.
-      if (MULTI_LOCATION.test(loc)) return true;
-      return inc.some(s => loc.includes(s));
-    });
-  }
-  if (Array.isArray(fc.locationExcludes) && fc.locationExcludes.length > 0) {
-    const exc = fc.locationExcludes.map(s => String(s).toLowerCase());
-    candidates = candidates.filter(p => {
-      const loc = (p.locationsText || '').toLowerCase();
-      return !exc.some(s => loc.includes(s));
-    });
-  }
-  if (typeof fc.postedWithinDays === 'number') {
-    candidates = candidates.filter(p => withinDays(p.postedOn, fc.postedWithinDays));
-  }
-
-  // 3. Bound the detail-fetch set.
-  //    NOTE: huge-tenant coverage is intentionally capped for v1. Two
-  //    caps apply: the list scan above stops at LIST_PAGE_HARD_CAP pages
-  //    (2000 postings, enough for Salesforce's ~1398), and the detail set
-  //    is cut to MAX_DETAIL_FETCHES here. A description `filter` is
-  //    applied by the library AFTER this returns, so for that case we
-  //    keep the full backstop instead of truncating tightly to `limit`
-  //    (which could hydrate jobs that all fail the regex while better
-  //    matches go unscanned). The library pages with `offset` after this
-  //    returns, so the budget covers the page plus what precedes it.
-  //    Proper fix (smart pagination / rate-limited concurrency / surfaced
-  //    truncation) is tracked in #26, to be designed alongside
-  //    retry/rate-limit work (#7).
-  const limit = typeof fc.limit === 'number' && fc.limit > 0 ? fc.limit : 100;
-  const skip = typeof fc.offset === 'number' && fc.offset > 0 ? fc.offset : 0;
-  const cap = fc.filter ? MAX_DETAIL_FETCHES : Math.min(skip + limit, MAX_DETAIL_FETCHES);
-  candidates = candidates.slice(0, cap);
-
-  // 4. Hydrate descriptions via the per-posting detail endpoint.
-  const jobs = await Promise.all(candidates.map(async (p) => {
+      return MULTI_LOCATION.test(loc) ? null : loc;
+    },
+    postedWithin: (p, days) => withinDays(p.postedOn, days),
+    max: MAX_DETAIL_FETCHES,
+  });
+
+  // 4. Hydrate descriptions via the per-posting detail endpoint. The detail
+  //    also carries `hiringOrganization: { name, url }` next to
+  //    jobPostingInfo; the list does not. Kept per posting in list order so
+  //    the one reported is the first hydrated posting's, not whichever
+  //    detail answered first (a tenant can post under several entities).
+  const orgs = [];
+  const jobs = await Promise.all(hydrate.map(async (p, i) => {
     const externalPath = p.externalPath || ''; // already begins with '/job/...'
     let info = {};
+    let content; // set only when the detail could not be read (issue #85)
     try {
       // externalPath already carries the '/job/...' segment, so it is
       // concatenated directly onto the CXS base. Inserting another
       // '/job' here yields '/job/job/...' which Workday rejects (422).
-      const dResp = await fetch(`${base}${externalPath}`);
+      const dResp = await atsFetch(`${base}${externalPath}`);
       if (dResp.ok) {
         const detail = await dResp.json();
         info = detail.jobPostingInfo || {};
+        orgs[i] = detail.hiringOrganization || null;
+      } else {
+        content = missingContent(dResp);
       }
-    } catch {
-      // detail failed: fall back to list fields, empty description
+    } catch (err) {
+      // detail failed, retries included: list fields only, marked missing
+      content = missingContent(err);
     }
 
     return normalize({
@@ -151,6 +153,7 @@ export async function fetchWorkday(slug, ctx = {}) {
       url: `https://${tenant}.${env}.myworkdayjobs.com/${site}${externalPath}`,
       postedAt: parseWorkdayDate(info.startDate) || normalizePostedOn(p.postedOn),
       salary: null, // normalizer extracts from description text
+      content,
       metadata: {
         workdayTenant: tenant,
         workdayEnv: env,
@@ -160,6 +163,20 @@ export async function fetchWorkday(slug, ctx = {}) {
     }, 'workday');
   }));
 
+  // Nothing hydrated (a filter miss, an empty site) means no detail was
+  // read, so the org is unknown rather than absent: null, null.
+  if (typeof ctx.report === 'function') {
+    const org = orgs.find(Boolean) || {};
+    ctx.report({
+      listed: postings.length,
+      prefiltered: candidates.length,
+      hydrated: hydrate.length,
+      capped: listCapped || hydrate.length < candidates.length,
+      org_name: org.name || null,
+      org_url: orgHost(org.url),
+    });
+  }
+
   return jobs;
 }
 
@@ -179,19 +196,26 @@ function parseWorkdayRemoteType(remoteType) {
 
 /**
  * Workday list `postedOn` is a relative string ("Posted Today",
- * "Posted 5 Days Ago", "Posted 30+ Days Ago"). Decide membership in
- * the last N days WITHOUT a network call. Unparseable -> keep (true);
- * the library re-filters authoritatively on the real postedAt after
- * hydration, so a false-keep here is corrected downstream.
+ * "Posted 5 Days Ago", "Posted 30+ Days Ago"). The days it names, or null
+ * when it names none.
  */
-function withinDays(postedOn, days) {
-  if (!postedOn) return true;
-  const s = String(postedOn).toLowerCase();
-  if (/today/.test(s)) return days >= 0;
-  if (/yesterday/.test(s)) return days >= 1;
+function daysAgo(postedOn) {
+  const s = String(postedOn || '').toLowerCase();
+  if (/today/.test(s)) return 0;
+  if (/yesterday/.test(s)) return 1;
   const m = s.match(/(\d+)\+?\s*days?\s*ago/);
-  if (m) return parseInt(m[1], 10) <= days;
-  return true;
+  return m ? parseInt(m[1], 10) : null;
+}
+
+/**
+ * Decide membership in the last N days WITHOUT a network call.
+ * Unparseable -> keep (true); the library re-filters authoritatively on
+ * the real postedAt after hydration, so a false-keep here is corrected
+ * downstream.
+ */
+function withinDays(postedOn, days) {
+  const n = daysAgo(postedOn);
+  return n === null || n <= days;
 }
 
 /**
@@ -202,16 +226,8 @@ function normalizePostedOn(v) {
   if (!v) return null;
   const direct = new Date(v);
   if (Number.isFinite(direct.getTime())) return direct.toISOString();
-  const s = String(v).toLowerCase();
-  let daysAgo = null;
-  if (/today/.test(s)) daysAgo = 0;
-  else if (/yesterday/.test(s)) daysAgo = 1;
-  else {
-    const m = s.match(/(\d+)\+?\s*days?\s*ago/);
-    if (m) daysAgo = parseInt(m[1], 10);
-  }
-  if (daysAgo === null) return null;
-  return new Date(Date.now() - daysAgo * 86400000).toISOString();
+  const n = daysAgo(v);
+  return n === null ? null : new Date(Date.now() - n * 86400000).toISOString();
 }
 
 /**

package/src/boards.js

@@ -0,0 +1,80 @@
+/**
+ * The boards[] entry of a fetchJobsDetailed result (issues #58, #60, #87).
+ *
+ * A board is one (ats, slug) the library fetched, with what came back. The
+ * fields fall in three groups: what the registry or the caller said about
+ * it (`name`, `site`), what the fetch found (`jobs_found`, `matched`,
+ * `scan`), and what the board says about itself (`org_name`, `org_url`).
+ * Only the adapters can read the third group, and they hand it over through
+ * ctx.report. Both fields are null where the platform exposes nothing, and
+ * they are never filled from the slug or the registry name: a slug is an
+ * address, not a confirmed identity.
+ */
+
+const BOARD_URLS = {
+  greenhouse: (slug) => `https://boards.greenhouse.io/${slug}`,
+  lever: (slug) => `https://jobs.lever.co/${slug}`,
+  ashby: (slug) => `https://jobs.ashbyhq.com/${slug}`,
+  smartrecruiters: (slug) => `https://careers.smartrecruiters.com/${slug}`,
+  teamtailor: (slug) => `https://${slug}.teamtailor.com`,
+  recruitee: (slug) => `https://${slug}.recruitee.com`,
+  workday: (slug, config) => (config ? `https://${config.tenant}.${config.env}.myworkdayjobs.com/${config.site}` : null),
+};
+
+// Domains the platforms own. A link there (boards.greenhouse.io,
+// jobs.lever.co, testco.recruitee.com, cisco.wd5.myworkdayjobs.com) says
+// which ATS hosts the board, nothing about whose board it is.
+const ATS_DOMAINS = ['greenhouse.io', 'lever.co', 'ashbyhq.com', 'smartrecruiters.com', 'teamtailor.com', 'recruitee.com', 'myworkdayjobs.com'];
+
+/**
+ * The page a person opens to see the board, or null when the ATS is unknown
+ * or, for Workday, no {tenant, env, site} is at hand.
+ */
+export function boardUrl(ats, slug, config) {
+  const build = BOARD_URLS[ats];
+  return build ? build(slug, config) : null;
+}
+
+/**
+ * The bare hostname a board's link points at ("jobs.example.com"), for
+ * org_url. Null when the link is missing or malformed, and null when the
+ * host belongs to an ATS, since that carries no signal about the company.
+ */
+export function orgHost(link) {
+  let host;
+  try {
+    host = new URL(link).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+  if (!host || ATS_DOMAINS.some(d => host === d || host.endsWith(`.${d}`))) return null;
+  return host;
+}
+
+/**
+ * @param {object} board
+ * @param {string} board.ats
+ * @param {string} board.slug - The slug the adapter was called with (canonical casing on a registry hit)
+ * @param {string|null} board.name - Registry row name; null for a probe or an override
+ * @param {object} [board.config] - Workday {tenant, env, site}, when one was used
+ * @param {string|null} board.org_name - The organization name the ATS response states, else null
+ * @param {string|null} board.org_url - The careers or company host the board links to (see orgHost), else null
+ * @param {number} board.jobs_found - Rows the board listed before any filter: the list count an adapter reported through ctx.report when it filters before hydrating, else the rows it returned
+ * @param {number} board.matched - Rows left after filters, before offset and limit
+ * @param {object|null} board.scan - The { listed, prefiltered, hydrated, capped } counts the adapter reported through ctx.report, else null
+ */
+export function describeBoard({ ats, slug, name = null, config, org_name = null, org_url = null, jobs_found, matched = 0, scan = null }) {
+  return {
+    ats,
+    slug,
+    name,
+    site: ats === 'workday' && config ? config.site : null,
+    board_url: boardUrl(ats, slug, config),
+    org_name,
+    org_url,
+    jobs_found,
+    matched,
+    selected: true,
+    scan,
+  };
+}