jd-intel 0.7.0 → 0.8.1

package/src/index.js

@@ -1,136 +1,146 @@
-/**
- * jd-intel — JD intelligence toolkit: fetch, normalize, and search job descriptions across every major ATS.
- *
- * Fetches, normalizes, and enriches job data from public ATS APIs
- * (Greenhouse, Lever, Ashby, SmartRecruiters, Teamtailor, Recruitee,
- * Workday) into a unified schema.
- */
-
-import { ADAPTERS, ATS_NAMES } from './adapters/index.js';
-import { loadRegistry, searchRegistry, detectAts, findAtsBySlug, findEntryBySlug } from './registry.js';
-import { applyFilters } from './filters.js';
-
-/**
- * Fetch jobs from a company's ATS board.
- *
- * @param {Object} options
- * @param {string} options.company - Company slug or name
- * @param {string} [options.ats] - Specific ATS platform. If omitted, auto-detects.
- * @param {object} [options.config] - Adapter-specific config (e.g. Workday {tenant, env, site}). Bypasses the registry; the only way to reach a Workday company not in the registry.
- * @param {string} [options.titleFilter] - Regex matched against title only. Use for role identity ("product manager", "staff engineer").
- * @param {string} [options.filter] - Regex matched across title, department, description. Use for topic/scope.
- * @param {number} [options.postedWithinDays] - Only return jobs posted within N days.
- * @param {string[]} [options.locationIncludes] - Keep jobs whose location contains any of these (case-insensitive).
- * @param {string[]} [options.locationExcludes] - Drop jobs whose location contains any of these (case-insensitive).
- * @param {number} [options.limit=100] - Maximum jobs to return after filtering.
- * @returns {Promise<Array>} Normalized, filtered job objects
- */
-export async function fetchJobs({
-  company,
-  ats,
-  config,
-  titleFilter,
-  filter,
-  postedWithinDays,
-  locationIncludes,
-  locationExcludes,
-  limit = 100,
-} = {}) {
-  if (!company) throw new Error('Company slug required');
-
-  // Unified slug normalization: strip all non-alphanumeric (matches detectAts)
-  const slug = company.toLowerCase().replace(/[^a-z0-9]/g, '');
-
-  // Filter context is passed as an additive 2nd arg to adapters. Existing
-  // adapters declare fetch{Name}(slug) and ignore extra positional args
-  // (JS no-op), so this is backward-compatible. Filter-aware adapters
-  // (e.g. Workday) use it to avoid mass detail-fetching on huge tenants.
-  const filterContext = { titleFilter, filter, postedWithinDays, locationIncludes, locationExcludes, limit };
-
-  let jobs;
-  if (ats) {
-    const adapter = ADAPTERS[ats];
-    if (!adapter) throw new Error(`Unknown ATS: ${ats}. Supported: ${ATS_NAMES.join(', ')}`);
-    // Explicit ATS: an explicitly passed config wins (the only path that
-    // can reach a Workday company not in the registry). With no explicit
-    // config, fall back to the registry so config-keyed adapters
-    // (Workday) and canonically-cased registry slugs (SmartRecruiters
-    // "Visa") also work on the explicit path, not just under auto-detect.
-    let fetchSlug = slug;
-    let cfg = config;
-    let companyName;
-    if (!cfg) {
-      const hit = await findEntryBySlug(slug);
-      if (hit && hit.ats === ats) {
-        fetchSlug = hit.entry.slug;
-        cfg = hit.entry.config;
-        companyName = hit.entry.name;
-      }
-    }
-    jobs = await adapter.fetch(fetchSlug, { config: cfg, companyName, filterContext });
-  } else {
-    // Consult registry first — if we know which ATS this company uses,
-    // skip probing the others (saves API calls, clearer error semantics).
-    // The registry entry carries the canonical slug (so the adapter is
-    // called with the ATS's own casing, e.g. SmartRecruiters "Visa") and
-    // any adapter-specific config (the Workday {tenant,env,site} triple).
-    const hit = await findEntryBySlug(slug);
-    if (hit) {
-      jobs = await ADAPTERS[hit.ats].fetch(hit.entry.slug, {
-        config: config || hit.entry.config,
-        companyName: hit.entry.name,
-        filterContext,
-      });
-    } else {
-      // Discovery mode: company not in registry, probe all adapters.
-      // (Registry-only adapters like Workday bail here via their guard.)
-      const results = await Promise.allSettled(
-        Object.entries(ADAPTERS).map(async ([name, adapter]) => adapter.fetch(slug, { filterContext }))
-      );
-      jobs = results
-        .filter(r => r.status === 'fulfilled')
-        .flatMap(r => r.value);
-    }
-  }
-
-  return applyFilters(jobs, { titleFilter, filter, postedWithinDays, locationIncludes, locationExcludes, limit });
-}
-
-/**
- * Search for companies in the registry.
- */
-export async function search({ keyword, location, ats } = {}) {
-  // For now, search is registry-based. With SQLite store, this becomes a full-text search.
-  if (!keyword) throw new Error('Keyword required');
-  return searchRegistry(keyword);
-}
-
-/**
- * Detect which ATS platform a company uses (probes each adapter).
- */
-export { detectAts } from './registry.js';
-
-/**
- * Look up which ATS a slug belongs to in the registry (cached, no network).
- * Returns the ATS name (e.g. "greenhouse", "workday") or null if not in registry.
- */
-export { findAtsBySlug } from './registry.js';
-
-/**
- * Registry management.
- */
-export const registry = {
-  load: loadRegistry,
-  search: searchRegistry,
-  detect: detectAts,
-  findAtsBySlug,
-  findEntryBySlug,
-};
-
-// Re-export individual adapters for direct use
-export { fetchGreenhouse } from './adapters/greenhouse.js';
-export { fetchLever } from './adapters/lever.js';
-export { fetchAshby } from './adapters/ashby.js';
-
-// Re-export filter logic for reuse (e.g., by the MCP server)
-export { applyFilters } from './filters.js';
+/**
+ * jd-intel — JD intelligence toolkit: fetch, normalize, and search job descriptions across every major ATS.
+ *
+ * Fetches, normalizes, and enriches job data from public ATS APIs
+ * (Greenhouse, Lever, Ashby, SmartRecruiters, Teamtailor, Recruitee,
+ * Workday) into a unified schema.
+ */
+
+import { ADAPTERS, ATS_NAMES } from './adapters/index.js';
+import { loadRegistry, searchRegistry, detectAts, findAtsBySlug, findEntryBySlug, getRegistrySource } from './registry.js';
+import { applyFilters } from './filters.js';
+
+/**
+ * Fetch jobs from a company's ATS board.
+ *
+ * @param {Object} options
+ * @param {string} options.company - Company slug or name
+ * @param {string} [options.ats] - Specific ATS platform. If omitted, auto-detects.
+ * @param {object} [options.config] - Adapter-specific config (e.g. Workday {tenant, env, site}). Bypasses the registry; the only way to reach a Workday company not in the registry.
+ * @param {string} [options.titleFilter] - Regex matched against title only. Use for role identity ("product manager", "staff engineer").
+ * @param {string} [options.filter] - Regex matched across title, department, description. Use for topic/scope.
+ * @param {number} [options.postedWithinDays] - Only return jobs posted within N days.
+ * @param {string[]} [options.locationIncludes] - Keep jobs whose location contains any of these (case-insensitive).
+ * @param {string[]} [options.locationExcludes] - Drop jobs whose location contains any of these (case-insensitive).
+ * @param {number} [options.limit=100] - Maximum jobs to return after filtering.
+ * @returns {Promise<Array>} Normalized, filtered job objects
+ */
+export async function fetchJobs({
+  company,
+  ats,
+  config,
+  titleFilter,
+  filter,
+  postedWithinDays,
+  locationIncludes,
+  locationExcludes,
+  limit = 100,
+} = {}) {
+  if (!company) throw new Error('Company slug required');
+
+  // Unified slug normalization: strip all non-alphanumeric (matches detectAts)
+  const slug = company.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+  // Filter context is passed as an additive 2nd arg to adapters. Existing
+  // adapters declare fetch{Name}(slug) and ignore extra positional args
+  // (JS no-op), so this is backward-compatible. Filter-aware adapters
+  // (e.g. Workday) use it to avoid mass detail-fetching on huge tenants.
+  const filterContext = { titleFilter, filter, postedWithinDays, locationIncludes, locationExcludes, limit };
+
+  let jobs;
+  if (ats) {
+    const adapter = ADAPTERS[ats];
+    if (!adapter) throw new Error(`Unknown ATS: ${ats}. Supported: ${ATS_NAMES.join(', ')}`);
+    // Explicit ATS: an explicitly passed config wins (the only path that
+    // can reach a Workday company not in the registry). With no explicit
+    // config, fall back to the registry so config-keyed adapters
+    // (Workday) and canonically-cased registry slugs (SmartRecruiters
+    // "Visa") also work on the explicit path, not just under auto-detect.
+    let fetchSlug = slug;
+    let cfg = config;
+    let companyName;
+    if (!cfg) {
+      const hit = await findEntryBySlug(slug);
+      if (hit && hit.ats === ats) {
+        fetchSlug = hit.entry.slug;
+        cfg = hit.entry.config;
+        companyName = hit.entry.name;
+      }
+    }
+    jobs = await adapter.fetch(fetchSlug, { config: cfg, companyName, filterContext });
+  } else {
+    // Consult registry first — if we know which ATS this company uses,
+    // skip probing the others (saves API calls, clearer error semantics).
+    // The registry entry carries the canonical slug (so the adapter is
+    // called with the ATS's own casing, e.g. SmartRecruiters "Visa") and
+    // any adapter-specific config (the Workday {tenant,env,site} triple).
+    const hit = await findEntryBySlug(slug);
+    if (hit) {
+      jobs = await ADAPTERS[hit.ats].fetch(hit.entry.slug, {
+        config: config || hit.entry.config,
+        companyName: hit.entry.name,
+        filterContext,
+      });
+    } else {
+      // Discovery mode: company not in registry, probe all adapters.
+      // (Registry-only adapters like Workday bail here via their guard.)
+      const results = await Promise.allSettled(
+        Object.entries(ADAPTERS).map(async ([name, adapter]) => adapter.fetch(slug, { filterContext }))
+      );
+      jobs = results
+        .filter(r => r.status === 'fulfilled')
+        .flatMap(r => r.value);
+    }
+  }
+
+  return applyFilters(jobs, { titleFilter, filter, postedWithinDays, locationIncludes, locationExcludes, limit });
+}
+
+/**
+ * Search for companies in the registry.
+ */
+export async function search({ keyword, location, ats } = {}) {
+  // For now, search is registry-based. With SQLite store, this becomes a full-text search.
+  if (!keyword) throw new Error('Keyword required');
+  return searchRegistry(keyword);
+}
+
+/**
+ * Detect which ATS platform a company uses (probes each adapter).
+ */
+export { detectAts } from './registry.js';
+
+/**
+ * Look up which ATS a slug belongs to in the registry (cached, no network).
+ * Returns the ATS name (e.g. "greenhouse", "workday") or null if not in registry.
+ */
+export { findAtsBySlug } from './registry.js';
+
+/**
+ * Registry management.
+ */
+export const registry = {
+  load: loadRegistry,
+  search: searchRegistry,
+  detect: detectAts,
+  findAtsBySlug,
+  findEntryBySlug,
+  getSource: getRegistrySource,
+};
+
+// Re-export individual adapters for direct use
+export { fetchGreenhouse } from './adapters/greenhouse.js';
+export { fetchLever } from './adapters/lever.js';
+export { fetchAshby } from './adapters/ashby.js';
+
+// Re-export filter logic for reuse (e.g., by the MCP server)
+export { applyFilters } from './filters.js';
+
+// Re-export the list of supported ATS names (e.g. so the MCP layer can report
+// the full set detectAts probes, instead of hardcoding a stale subset).
+export { ATS_NAMES };
+
+// Error taxonomy + typed error. Adapters throw AtsError with a stable .code
+// (ats_unreachable / rate_limited) so the MCP layer maps failures without
+// parsing messages. ERROR_CODES is the single source of truth for both.
+export { ERROR_CODES, AtsError } from './errors.js';

package/src/registry.js

@@ -1,114 +1,164 @@
-import { readFile } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const REGISTRY_DIR = join(__dirname, '..', 'registry');
-
-let cache = {};
-
-/**
- * Load company registry for a specific ATS or all ATS platforms.
- */
-export async function loadRegistry(ats) {
-  if (ats && cache[ats]) return cache[ats];
-
-  if (ats) {
-    try {
-      const data = await readFile(join(REGISTRY_DIR, `${ats}.json`), 'utf-8');
-      cache[ats] = JSON.parse(data);
-      return cache[ats];
-    } catch {
-      return [];
-    }
-  }
-
-  // Load all
-  const all = {};
-  for (const platform of ['greenhouse', 'lever', 'ashby', 'smartrecruiters', 'teamtailor', 'recruitee', 'workday']) {
-    try {
-      const data = await readFile(join(REGISTRY_DIR, `${platform}.json`), 'utf-8');
-      all[platform] = JSON.parse(data);
-      cache[platform] = all[platform];
-    } catch {
-      all[platform] = [];
-    }
-  }
-  return all;
-}
-
-/**
- * Search registry for companies matching a query.
- */
-export async function searchRegistry(query) {
-  const all = await loadRegistry();
-  const lower = query.toLowerCase();
-  const results = [];
-
-  for (const [ats, companies] of Object.entries(all)) {
-    for (const company of companies) {
-      const name = (company.name || company.slug || '').toLowerCase();
-      const sector = (company.sector || '').toLowerCase();
-      if (name.includes(lower) || sector.includes(lower)) {
-        results.push({ ...company, ats });
-      }
-    }
-  }
-
-  return results;
-}
-
-// Slug match is case/punctuation-insensitive: registry slugs are stored
-// in each ATS's canonical form (SmartRecruiters uses PascalCase, e.g.
-// "Visa"), but callers pass a lowercased/alnum-stripped slug. Comparing
-// normalized forms keeps registry-first routing working for those.
-const normSlug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
-
-/**
- * Look up which ATS a slug belongs to in the registry.
- * Returns the ATS name (e.g., "greenhouse") or null if not in registry.
- */
-export async function findAtsBySlug(slug) {
-  const all = await loadRegistry();
-  const key = normSlug(slug);
-  for (const [ats, companies] of Object.entries(all)) {
-    if (companies.some(c => normSlug(c.slug) === key)) return ats;
-  }
-  return null;
-}
-
-/**
- * Look up the full registry entry for a slug, with its ATS.
- * Unlike findAtsBySlug (returns just the ats name), this returns the
- * whole entry so callers can read adapter-specific config (e.g. the
- * Workday {tenant, env, site} triple). Additive — does not change
- * findAtsBySlug, which has other callers.
- *
- * @returns {Promise<{ats: string, entry: object}|null>}
- */
-export async function findEntryBySlug(slug) {
-  const all = await loadRegistry();
-  const key = normSlug(slug);
-  for (const [ats, companies] of Object.entries(all)) {
-    const entry = companies.find(c => normSlug(c.slug) === key);
-    if (entry) return { ats, entry };
-  }
-  return null;
-}
-
-/**
- * Auto-detect which ATS a company uses.
- */
-export async function detectAts(companyName) {
-  const { ADAPTERS } = await import('./adapters/index.js');
-  const slug = companyName.toLowerCase().replace(/[^a-z0-9]/g, '');
-
-  const results = [];
-  const checks = Object.entries(ADAPTERS).map(async ([ats, adapter]) => {
-    const found = await adapter.has(slug);
-    if (found) results.push({ ats, slug });
-  });
-
-  await Promise.allSettled(checks);
-  return results;
-}
+import { readFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REGISTRY_DIR = join(__dirname, '..', 'registry');
+
+const PLATFORMS = ['greenhouse', 'lever', 'ashby', 'smartrecruiters', 'teamtailor', 'recruitee', 'workday'];
+
+// Network-first registry. A hosted copy lets installed bundles AND npx users
+// pick up newly-added companies without reinstalling; the on-disk copy that
+// ships with the package is the guaranteed offline fallback. The base URL is
+// resolved at call time so it stays overridable: point JD_INTEL_REGISTRY_URL
+// at a different host, or set it to '' to force disk-only (tests, air-gapped).
+const DEFAULT_REGISTRY_URL = 'https://prpmdev.github.io/jd-intel/registry';
+const FETCH_TIMEOUT_MS = 2500;
+
+function registryBaseUrl() {
+  return process.env.JD_INTEL_REGISTRY_URL !== undefined
+    ? process.env.JD_INTEL_REGISTRY_URL
+    : DEFAULT_REGISTRY_URL;
+}
+
+let cache = {};
+let sources = {}; // platform -> 'network' | 'disk-fallback'
+
+async function fetchPlatform(platform) {
+  const base = registryBaseUrl();
+  if (!base) throw new Error('registry network disabled');
+  const res = await fetch(`${base}/${platform}.json`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+  if (!res.ok) throw new Error(`registry fetch ${platform}: HTTP ${res.status}`);
+  const data = await res.json();
+  if (!Array.isArray(data)) throw new Error(`registry fetch ${platform}: not an array`);
+  return data;
+}
+
+async function readPlatform(platform) {
+  const data = await readFile(join(REGISTRY_DIR, `${platform}.json`), 'utf-8');
+  return JSON.parse(data);
+}
+
+// Load one platform: hosted copy first, on-disk fallback on ANY failure
+// (offline, non-200, timeout, malformed). Cached per process after first load.
+async function loadPlatform(platform) {
+  if (cache[platform]) return cache[platform];
+  try {
+    cache[platform] = await fetchPlatform(platform);
+    sources[platform] = 'network';
+  } catch {
+    try {
+      cache[platform] = await readPlatform(platform);
+    } catch {
+      cache[platform] = [];
+    }
+    sources[platform] = 'disk-fallback';
+  }
+  return cache[platform];
+}
+
+/**
+ * Load company registry for a specific ATS or all ATS platforms.
+ * Network-first with on-disk fallback (see registryBaseUrl).
+ */
+export async function loadRegistry(ats) {
+  if (ats) return loadPlatform(ats);
+  const all = {};
+  await Promise.all(PLATFORMS.map(async (platform) => {
+    all[platform] = await loadPlatform(platform);
+  }));
+  return all;
+}
+
+/**
+ * Where the registry data loaded this process came from:
+ *   'network'       every loaded platform came from the hosted copy
+ *   'disk-fallback' every loaded platform fell back to the bundled copy
+ *   'mixed'         some of each
+ *   'unknown'       nothing loaded yet
+ * Surfaced in MCP response metadata so the AI can tell the user whether the
+ * company list is live or the bundled snapshot.
+ */
+export function getRegistrySource() {
+  const vals = Object.values(sources);
+  if (vals.length === 0) return 'unknown';
+  if (vals.every((v) => v === 'network')) return 'network';
+  if (vals.every((v) => v === 'disk-fallback')) return 'disk-fallback';
+  return 'mixed';
+}
+
+/**
+ * Search registry for companies matching a query.
+ */
+export async function searchRegistry(query) {
+  const all = await loadRegistry();
+  const lower = query.toLowerCase();
+  const results = [];
+
+  for (const [ats, companies] of Object.entries(all)) {
+    for (const company of companies) {
+      const name = (company.name || company.slug || '').toLowerCase();
+      const sector = (company.sector || '').toLowerCase();
+      if (name.includes(lower) || sector.includes(lower)) {
+        results.push({ ...company, ats });
+      }
+    }
+  }
+
+  return results;
+}
+
+// Slug match is case/punctuation-insensitive: registry slugs are stored
+// in each ATS's canonical form (SmartRecruiters uses PascalCase, e.g.
+// "Visa"), but callers pass a lowercased/alnum-stripped slug. Comparing
+// normalized forms keeps registry-first routing working for those.
+const normSlug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/**
+ * Look up which ATS a slug belongs to in the registry.
+ * Returns the ATS name (e.g., "greenhouse") or null if not in registry.
+ */
+export async function findAtsBySlug(slug) {
+  const all = await loadRegistry();
+  const key = normSlug(slug);
+  for (const [ats, companies] of Object.entries(all)) {
+    if (companies.some(c => normSlug(c.slug) === key)) return ats;
+  }
+  return null;
+}
+
+/**
+ * Look up the full registry entry for a slug, with its ATS.
+ * Unlike findAtsBySlug (returns just the ats name), this returns the
+ * whole entry so callers can read adapter-specific config (e.g. the
+ * Workday {tenant, env, site} triple). Additive — does not change
+ * findAtsBySlug, which has other callers.
+ *
+ * @returns {Promise<{ats: string, entry: object}|null>}
+ */
+export async function findEntryBySlug(slug) {
+  const all = await loadRegistry();
+  const key = normSlug(slug);
+  for (const [ats, companies] of Object.entries(all)) {
+    const entry = companies.find(c => normSlug(c.slug) === key);
+    if (entry) return { ats, entry };
+  }
+  return null;
+}
+
+/**
+ * Auto-detect which ATS a company uses.
+ */
+export async function detectAts(companyName) {
+  const { ADAPTERS } = await import('./adapters/index.js');
+  const slug = companyName.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+  const results = [];
+  const checks = Object.entries(ADAPTERS).map(async ([ats, adapter]) => {
+    const found = await adapter.has(slug);
+    if (found) results.push({ ats, slug });
+  });
+
+  await Promise.allSettled(checks);
+  return results;
+}