jd-intel 0.8.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jd-intel",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Fetch and normalize job descriptions across every major ATS (Greenhouse, Lever, Ashby, Workday, and more), for your AI assistant. No copy-paste.",
   "type": "module",
   "main": "src/index.js",

package/src/adapters/ashby.js

@@ -1,4 +1,5 @@
 import { normalize } from '../normalizer.js';
+import { atsErrorFromStatus } from '../errors.js';
 
 const API_URL = 'https://jobs.ashbyhq.com/api/non-user-graphql';
 const BOARD_URL = 'https://api.ashbyhq.com/posting-api/job-board';
@@ -28,7 +29,7 @@ async function fetchAshbyRest(slug) {
 
   if (!resp.ok) {
     if (resp.status === 404) return [];
-    throw new Error(`Ashby REST API error for ${slug}: ${resp.status}`);
+    throw atsErrorFromStatus(resp.status, `Ashby REST API error for ${slug}: ${resp.status}`);
   }
 
   const data = await resp.json();

package/src/adapters/greenhouse.js

@@ -1,4 +1,5 @@
 import { normalize, stripHtml } from '../normalizer.js';
+import { atsErrorFromStatus } from '../errors.js';
 
 const BASE_URL = 'https://boards-api.greenhouse.io/v1/boards';
 
@@ -16,7 +17,7 @@ export async function fetchGreenhouse(slug) {
 
   if (!resp.ok) {
     if (resp.status === 404) return []; // Company not found or no jobs
-    throw new Error(`Greenhouse API error for ${slug}: ${resp.status}`);
+    throw atsErrorFromStatus(resp.status, `Greenhouse API error for ${slug}: ${resp.status}`);
   }
 
   const data = await resp.json();

package/src/adapters/lever.js

@@ -1,4 +1,5 @@
 import { normalize, stripHtml } from '../normalizer.js';
+import { atsErrorFromStatus } from '../errors.js';
 
 const BASE_URL = 'https://api.lever.co/v0/postings';
 
@@ -15,7 +16,7 @@ export async function fetchLever(slug) {
 
   if (!resp.ok) {
     if (resp.status === 404) return [];
-    throw new Error(`Lever API error for ${slug}: ${resp.status}`);
+    throw atsErrorFromStatus(resp.status, `Lever API error for ${slug}: ${resp.status}`);
   }
 
   const jobs = await resp.json();

package/src/adapters/recruitee.js

@@ -1,4 +1,5 @@
 import { normalize, stripHtml } from '../normalizer.js';
+import { atsErrorFromStatus } from '../errors.js';
 
 /**
  * Fetch jobs from a Recruitee career site.
@@ -18,7 +19,7 @@ export async function fetchRecruitee(slug) {
 
   if (!resp.ok) {
     if (resp.status === 404) return []; // No Recruitee site for this slug
-    throw new Error(`Recruitee API error for ${slug}: ${resp.status}`);
+    throw atsErrorFromStatus(resp.status, `Recruitee API error for ${slug}: ${resp.status}`);
   }
 
   const data = await resp.json();

package/src/adapters/smartrecruiters.js

@@ -1,4 +1,5 @@
 import { normalize, stripHtml } from '../normalizer.js';
+import { atsErrorFromStatus } from '../errors.js';
 
 const BASE_URL = 'https://api.smartrecruiters.com/v1/companies';
 const PAGE_SIZE = 100;
@@ -30,7 +31,7 @@ export async function fetchSmartrecruiters(slug) {
 
     if (!resp.ok) {
       if (resp.status === 404) return []; // Company not found
-      throw new Error(`SmartRecruiters API error for ${slug}: ${resp.status}`);
+      throw atsErrorFromStatus(resp.status, `SmartRecruiters API error for ${slug}: ${resp.status}`);
     }
 
     const data = await resp.json();

package/src/adapters/teamtailor.js

@@ -1,4 +1,5 @@
 import { normalize, stripHtml } from '../normalizer.js';
+import { atsErrorFromStatus } from '../errors.js';
 
 /**
  * Fetch jobs from a TeamTailor career site via its public RSS feed.
@@ -43,7 +44,7 @@ async function resolveFeed(slug, method = 'GET') {
     });
     if (resp.ok) return resp;
     if (resp.status !== 404) {
-      throw new Error(`TeamTailor RSS error for ${slug}: ${resp.status}`);
+      throw atsErrorFromStatus(resp.status, `TeamTailor RSS error for ${slug}: ${resp.status}`);
     }
     // 404 on this host — try the next region.
   }

package/src/adapters/workday.js

@@ -1,4 +1,5 @@
 import { normalize, stripHtml } from '../normalizer.js';
+import { atsErrorFromStatus } from '../errors.js';
 
 const MAX_DETAIL_FETCHES = 100;
 const LIST_PAGE_SIZE = 20;
@@ -49,7 +50,7 @@ export async function fetchWorkday(slug, ctx = {}) {
     if (!resp.ok) {
       if (resp.status === 404) return []; // wrong site / no such board
       if (offset === 0) {
-        throw new Error(`Workday API error for ${slug} (${tenant}/${env}/${site}): ${resp.status}`);
+        throw atsErrorFromStatus(resp.status, `Workday API error for ${slug} (${tenant}/${env}/${site}): ${resp.status}`);
       }
       break; // mid-paging failure: keep what we have
     }

package/src/errors.js

@@ -0,0 +1,38 @@
+/**
+ * Error taxonomy + typed error for the jd-intel toolkit.
+ *
+ * Codes are short and stable; the MCP tool descriptions teach the AI what each
+ * one means. Adapters throw AtsError with a code so callers map failures by
+ * `err.code` instead of parsing the message.
+ */
+
+export const ERROR_CODES = {
+  COMPANY_NOT_FOUND: 'company_not_found',  // Slug not in registry and not detected
+  ATS_UNREACHABLE: 'ats_unreachable',      // Known ATS failed (500, timeout)
+  PARTIAL_FAILURE: 'partial_failure',      // Discovery mode; some adapters failed
+  INVALID_ARGS: 'invalid_args',            // Missing required, wrong type, bad pattern
+  NO_RESULTS: 'no_results',                // Query succeeded, filters returned nothing
+  RATE_LIMITED: 'rate_limited',            // Upstream returned 429
+};
+
+/**
+ * Thrown by adapters on an upstream HTTP failure. Carries a stable `code`
+ * (ats_unreachable / rate_limited) so the MCP layer maps it without parsing
+ * the message. Extends Error, so the message, stack, and `instanceof Error`
+ * all keep working for existing library consumers.
+ */
+export class AtsError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'AtsError';
+    this.code = code;
+  }
+}
+
+/**
+ * Helper for adapters: build an AtsError from an HTTP status (429 => rate
+ * limited, anything else => unreachable) with the given message.
+ */
+export function atsErrorFromStatus(status, message) {
+  return new AtsError(status === 429 ? ERROR_CODES.RATE_LIMITED : ERROR_CODES.ATS_UNREACHABLE, message);
+}

package/src/index.js

@@ -139,3 +139,8 @@ 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';