@cliwant/mcp-sam-gov 1.2.0 → 1.4.0

package/dist/nhtsa.js

@@ -0,0 +1,263 @@
+/**
+ * nhtsa.ts — NHTSA VEHICLE SAFETY (api.nhtsa.gov) — the vehicle / parts /
+ * fleet supplier PRODUCT-SAFETY vetting lane (ADR-0057). Two keyless tools:
+ *   • nhtsa_recalls    — /recalls/recallsByVehicle?make=&model=&modelYear=
+ *   • nhtsa_complaints — /complaints/complaintsByVehicle?make=&model=&modelYear=
+ * The cross-agency product-safety family alongside openFDA (medical) / CPSC
+ * (consumer goods): a manufacturer/component/safety-signal history for B2G
+ * supplier vetting.
+ *
+ * ★ KEYLESS — there is NO API key at all (no parameter, no header). This module
+ *   touches NO key seam (no KEY_REGISTRY / keys.ts / API_KEYS.md). It REUSES the
+ *   shared `getJson` (redirect:"error") / `driftError` fetch envelope, the `num`/
+ *   `str` coercions (null-never-empty-string; a genuine 0 stays 0), and
+ *   `withMeta`/`buildMeta` — and mirrors datagov-catalog.ts's fixed-host SSRF
+ *   idiom + schema_drift catch-ladder verbatim.
+ *
+ * ★ PII — the complaints upstream response carries a `vin` field (an individual
+ *   vehicle identifier). It is DELIBERATELY OMITTED from the curated output
+ *   entirely — never surfaced, logged, or stored. The B2G value is the
+ *   manufacturer / component / safety signal, NOT the VIN.
+ *
+ * ★ THE HONESTY PILLARS (P1-P4, live-verified 2026-07-15):
+ *   P1: totalAvailable = `Count` (recalls) / `count` (complaints) — the REAL total.
+ *       NHTSA returns the COMPLETE filtered set (no pagination), so in the normal
+ *       case Count === results.length ⇒ complete:true. totalAvailable is NEVER
+ *       fabricated: a PRESENT numeric Count is trusted verbatim; a MISSING Count
+ *       falls back to results.length WITH an honest note (never invented).
+ *   P2: results:[] (Count 0) ⇒ an HONEST EMPTY (returned:0, complete:true) — a bad
+ *       make/model that returns 200+Count 0 is an honest no-match, NOT an error. A
+ *       4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROW (never a fake empty); a 200
+ *       non-JSON body ⇒ schema_drift.
+ *   P3: booleans (crash/fire/parkIt/parkOutSide/overTheAirUpdate) preserved AS
+ *       booleans (a non-boolean ⇒ null, never a fabricated false); counts
+ *       (numberOfInjuries/numberOfDeaths) via `num` (a genuine 0 stays 0, NEVER
+ *       null-for-0); dates as strings via `str`; Count/count via `num`.
+ *   P4: `results` non-array ⇒ driftError; a Count/count that is PRESENT but a
+ *       non-number ⇒ driftError (a broken total contract, never a fabricated empty).
+ *   SSRF: fixed host `api.nhtsa.gov` (compile-time literal) + post-construction
+ *       hostname/protocol assertion + redirect:"error"; make/model ride
+ *       URLSearchParams (module-built, no raw passthrough); modelYear is
+ *       ^\d{4}$; make/model are charclass-validated (letters/digits/space/hyphen,
+ *       so a `../` or `%` can never reach the fixed path).
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { withMeta } from "./meta.js";
+// ─── Fixed endpoint (SSRF core — compile-time CONSTANTS) ──────────
+export const NHTSA_HOST = "api.nhtsa.gov";
+const RECALLS_PATH = "/recalls/recallsByVehicle";
+const COMPLAINTS_PATH = "/complaints/complaintsByVehicle";
+// HOST+path-only labels (→ ToolError.upstreamEndpoint). Keyless ⇒ no token can
+// ever appear here regardless, but the labels stay host+path for consistency.
+const RECALLS_LABEL = "nhtsa:/recalls/recallsByVehicle";
+const COMPLAINTS_LABEL = "nhtsa:/complaints/complaintsByVehicle";
+// ─── Input validation grammar (SSRF + injection guard) ────────────
+// modelYear: exactly 4 digits. make/model: letters/digits/space/hyphen only —
+// rejects `../`, `%`, `/`, `.`, quotes, so a value can never break out of the
+// URLSearchParams-encoded query onto the fixed host/path.
+export const NHTSA_MODEL_YEAR_RE = /^\d{4}$/;
+export const NHTSA_MAKE_MODEL_RE = /^[A-Za-z0-9 -]+$/;
+const KEYLESS_NOTE = "NHTSA is a keyless public API (api.nhtsa.gov) — no API key is required or accepted.";
+const COMPLETE_SET_NOTE = "NHTSA returns the COMPLETE set of matching records for this make/model/modelYear (no pagination) — totalAvailable is the upstream Count, and returned should equal it.";
+// ─── Shared coercions ─────────────────────────────────────────────
+/** A genuine boolean preserved; anything else ⇒ null (never a fabricated false). */
+function bool(x) {
+    return typeof x === "boolean" ? x : null;
+}
+/**
+ * Validate the shared make/model/modelYear inputs (belt-and-suspenders behind the
+ * server Zod; a DIRECT handler call bypasses Zod). Rejects a bad value PRE-fetch
+ * (0 network call) so a `../`/`%` can never reach the fixed host/path.
+ */
+function validateVehicleArgs(args, label) {
+    const checks = [
+        ["make", args.make, NHTSA_MAKE_MODEL_RE],
+        ["model", args.model, NHTSA_MAKE_MODEL_RE],
+        ["modelYear", args.modelYear, NHTSA_MODEL_YEAR_RE],
+    ];
+    for (const [name, value, re] of checks) {
+        if (typeof value !== "string" || !re.test(value)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: name === "modelYear"
+                    ? `Invalid modelYear ${JSON.stringify(value)} — expected a 4-digit year (^\\d{4}$), e.g. "2020".`
+                    : `Invalid ${name} ${JSON.stringify(value)} — expected letters/digits/space/hyphen only (^[A-Za-z0-9 -]+$), e.g. "honda".`,
+                upstreamEndpoint: label,
+            });
+        }
+    }
+}
+// ─── SSRF-guarded fetch (fixed host + hostname assertion + redirect) ──
+/**
+ * GET one NHTSA JSON resource on the FIXED host. Builds
+ * `https://api.nhtsa.gov${path}?${params}`, asserts the CONSTRUCTED URL's
+ * hostname === the fixed host over https (belt-and-suspenders), and sets
+ * `redirect:"error"` (fail closed on any off-host 3xx). Keyless — no header/token.
+ */
+async function getNhtsa(path, label, params) {
+    const url = `https://${NHTSA_HOST}${path}?${params.toString()}`;
+    const built = new URL(url);
+    if (built.hostname !== NHTSA_HOST || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Constructed NHTSA URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the fixed host ${JSON.stringify(NHTSA_HOST)} over https — refusing to fetch (SSRF safety).`,
+            upstreamEndpoint: label,
+        });
+    }
+    return getJson(url, { label, redirect: "error" });
+}
+/** Build the shared make/model/modelYear query (module-built; no raw passthrough). */
+function vehicleParams(args) {
+    const params = new URLSearchParams();
+    params.set("make", args.make);
+    params.set("model", args.model);
+    params.set("modelYear", args.modelYear);
+    return params;
+}
+/**
+ * Fetch + parse a NHTSA resource, mirroring datagov-catalog's catch-ladder: a
+ * ToolErrorCarrier (host-assert / 4xx-5xx taxonomy) rethrows FIRST (preserving its
+ * kind); a 200 non-JSON `.json()` SyntaxError reclassifies to schema_drift; a bare
+ * error rethrows LAST.
+ */
+async function fetchNhtsa(path, label, args) {
+    try {
+        return await getNhtsa(path, label, vehicleParams(args));
+    }
+    catch (e) {
+        if (e instanceof ToolErrorCarrier)
+            throw e;
+        if (e instanceof SyntaxError)
+            throw driftError(label, `NHTSA ${label} returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).`);
+        throw e;
+    }
+}
+/**
+ * Resolve the total from a Count/count field (P1/P4). A PRESENT numeric value is
+ * trusted verbatim; a MISSING (undefined/null) value falls back to results.length
+ * WITH an honest note (never fabricated); a PRESENT non-number ⇒ driftError (a
+ * broken total contract). Returns the total + the fallback flag.
+ */
+function resolveTotal(rawCount, returned, label) {
+    if (rawCount === undefined || rawCount === null) {
+        // P1 fallback — missing Count ⇒ results.length + an honest note.
+        return { total: returned, fellBack: true };
+    }
+    const n = num(rawCount);
+    if (n === null) {
+        // P4 — a PRESENT non-number Count is a broken contract, never a fake empty.
+        throw driftError(label, `NHTSA ${label} shape drift — the total count field is present but non-numeric.`);
+    }
+    return { total: n, fellBack: false };
+}
+/** Map ONE /recallsByVehicle row → the curated recall shape. Booleans via `bool`. */
+function mapRecall(row) {
+    const r = (row ?? {});
+    return {
+        campaignNumber: str(r.NHTSACampaignNumber),
+        manufacturer: str(r.Manufacturer),
+        component: str(r.Component),
+        summary: str(r.Summary),
+        consequence: str(r.Consequence),
+        remedy: str(r.Remedy),
+        reportReceivedDate: str(r.ReportReceivedDate),
+        parkIt: bool(r.parkIt),
+        parkOutside: bool(r.parkOutSide),
+        overTheAirUpdate: bool(r.overTheAirUpdate),
+    };
+}
+/**
+ * Map ONE /complaintsByVehicle row → the curated complaint shape. ★The `vin` field
+ * is DELIBERATELY OMITTED (PII — never read into the output). Counts via `num` (a
+ * genuine 0 stays 0); booleans via `bool`.
+ */
+function mapComplaint(row) {
+    const r = (row ?? {});
+    return {
+        odiNumber: str(r.odiNumber),
+        manufacturer: str(r.manufacturer),
+        component: str(r.components),
+        summary: str(r.summary),
+        crash: bool(r.crash),
+        fire: bool(r.fire),
+        numberOfInjuries: num(r.numberOfInjuries),
+        numberOfDeaths: num(r.numberOfDeaths),
+        dateOfIncident: str(r.dateOfIncident),
+        dateComplaintFiled: str(r.dateComplaintFiled),
+        // ★ NO vin — the PII field is never surfaced, logged, or stored.
+    };
+}
+const FILTERS_APPLIED = ["make", "model", "modelYear"];
+// ─── Tool: nhtsa_recalls ──────────────────────────────────────────
+/**
+ * Fetch NHTSA safety RECALLS for a make/model/modelYear → curated recall rows +
+ * honest `_meta`. KEYLESS. totalAvailable = the upstream `Count` (the REAL total —
+ * NHTSA returns the complete set, no pagination). A no-match (Count 0) ⇒ an honest
+ * empty; a 4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROW; a 200 non-JSON ⇒ drift.
+ */
+export async function recalls(args) {
+    validateVehicleArgs(args, RECALLS_LABEL);
+    const body = await fetchNhtsa(RECALLS_PATH, RECALLS_LABEL, args);
+    const b = (body ?? {});
+    // P4 — results MUST be an array (a missing/string/null results is drift).
+    if (!Array.isArray(b.results)) {
+        throw driftError(RECALLS_LABEL, `NHTSA ${RECALLS_LABEL} shape drift — results must be an array.`);
+    }
+    const recalls = b.results.map(mapRecall);
+    const returned = recalls.length;
+    const { total, fellBack } = resolveTotal(b.Count, returned, RECALLS_LABEL);
+    const notes = [KEYLESS_NOTE, COMPLETE_SET_NOTE];
+    if (fellBack)
+        notes.push("NHTSA did not report a Count field — totalAvailable falls back to the number of returned rows (results.length); the true total may differ.");
+    return withMeta({ recalls }, {
+        source: `${NHTSA_HOST} /recalls/recallsByVehicle (NHTSA vehicle safety recalls; keyless)`,
+        keylessMode: true,
+        returned,
+        totalAvailable: total,
+        filtersApplied: FILTERS_APPLIED,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        notes,
+    });
+}
+// ─── Tool: nhtsa_complaints ───────────────────────────────────────
+/**
+ * Fetch NHTSA consumer COMPLAINTS for a make/model/modelYear → curated complaint
+ * rows (★NO vin — PII omitted) + honest `_meta`. KEYLESS. totalAvailable = the
+ * upstream `count` (the REAL total). A no-match ⇒ honest empty; a 4xx ⇒
+ * invalid_input; a 5xx/timeout ⇒ THROW; a 200 non-JSON ⇒ drift.
+ */
+export async function complaints(args) {
+    validateVehicleArgs(args, COMPLAINTS_LABEL);
+    const body = await fetchNhtsa(COMPLAINTS_PATH, COMPLAINTS_LABEL, args);
+    const b = (body ?? {});
+    // P4 — results MUST be an array (a missing/string/null results is drift).
+    if (!Array.isArray(b.results)) {
+        throw driftError(COMPLAINTS_LABEL, `NHTSA ${COMPLAINTS_LABEL} shape drift — results must be an array.`);
+    }
+    const complaints = b.results.map(mapComplaint);
+    const returned = complaints.length;
+    const { total, fellBack } = resolveTotal(b.count, returned, COMPLAINTS_LABEL);
+    const notes = [
+        KEYLESS_NOTE,
+        COMPLETE_SET_NOTE,
+        "The NHTSA complaint VIN (an individual vehicle identifier) is intentionally EXCLUDED from this output (PII). The B2G signal is the manufacturer/component/crash/fire/injury/death safety history.",
+    ];
+    if (fellBack)
+        notes.push("NHTSA did not report a count field — totalAvailable falls back to the number of returned rows (results.length); the true total may differ.");
+    return withMeta({ complaints }, {
+        source: `${NHTSA_HOST} /complaints/complaintsByVehicle (NHTSA vehicle safety complaints; keyless)`,
+        keylessMode: true,
+        returned,
+        totalAvailable: total,
+        filtersApplied: FILTERS_APPLIED,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        notes,
+    });
+}
+//# sourceMappingURL=nhtsa.js.map

package/dist/nhtsa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nhtsa.js","sourceRoot":"","sources":["../src/nhtsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAsC,MAAM,WAAW,CAAC;AAEzE,qEAAqE;AACrE,MAAM,CAAC,MAAM,UAAU,GAAG,eAAe,CAAC;AAC1C,MAAM,YAAY,GAAG,2BAA2B,CAAC;AACjD,MAAM,eAAe,GAAG,iCAAiC,CAAC;AAC1D,+EAA+E;AAC/E,8EAA8E;AAC9E,MAAM,aAAa,GAAG,iCAAiC,CAAC;AACxD,MAAM,gBAAgB,GAAG,uCAAuC,CAAC;AAEjE,qEAAqE;AACrE,8EAA8E;AAC9E,8EAA8E;AAC9E,0DAA0D;AAC1D,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAC7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAEtD,MAAM,YAAY,GAChB,qFAAqF,CAAC;AACxF,MAAM,iBAAiB,GACrB,wKAAwK,CAAC;AAE3K,qEAAqE;AACrE,oFAAoF;AACpF,SAAS,IAAI,CAAC,CAAU;IACtB,OAAO,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,CAAC;AASD;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,IAAsB,EAAE,KAAa;IAChE,MAAM,MAAM,GAAoC;QAC9C,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC;QACxC,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,mBAAmB,CAAC;QAC1C,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,EAAE,mBAAmB,CAAC;KACnD,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC;QACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,gBAAgB,CAAC;gBACzB,IAAI,EAAE,eAAe;gBACrB,SAAS,EAAE,KAAK;gBAChB,OAAO,EACL,IAAI,KAAK,WAAW;oBAClB,CAAC,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,qDAAqD;oBACjG,CAAC,CAAC,WAAW,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,gFAAgF;gBAC9H,gBAAgB,EAAE,KAAK;aACxB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE;;;;;GAKG;AACH,KAAK,UAAU,QAAQ,CACrB,IAAY,EACZ,KAAa,EACb,MAAuB;IAEvB,MAAM,GAAG,GAAG,WAAW,UAAU,GAAG,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;IAChE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,KAAK,CAAC,QAAQ,KAAK,UAAU,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjE,MAAM,IAAI,gBAAgB,CAAC;YACzB,IAAI,EAAE,eAAe;YACrB,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,8BAA8B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,KAAK,CAAC,QAAQ,mCAAmC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,gDAAgD;YACrM,gBAAgB,EAAE,KAAK;SACxB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;AACpD,CAAC;AAED,sFAAsF;AACtF,SAAS,aAAa,CAAC,IAAsB;IAC3C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,UAAU,CACvB,IAAY,EACZ,KAAa,EACb,IAAsB;IAEtB,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,gBAAgB;YAAE,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,YAAY,WAAW;YAC1B,MAAM,UAAU,CACd,KAAK,EACL,SAAS,KAAK,uFAAuF,CACtG,CAAC;QACJ,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CACnB,QAAiB,EACjB,QAAgB,EAChB,KAAa;IAEb,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAChD,iEAAiE;QACjE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC7C,CAAC;IACD,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxB,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;QACf,4EAA4E;QAC5E,MAAM,UAAU,CACd,KAAK,EACL,SAAS,KAAK,kEAAkE,CACjF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACvC,CAAC;AA6BD,qFAAqF;AACrF,SAAS,SAAS,CAAC,GAAY;IAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAA4B,CAAC;IACjD,OAAO;QACL,cAAc,EAAE,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC;QAC1C,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QACjC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3B,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QACvB,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC;QAC/B,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;QACrB,kBAAkB,EAAE,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC;QAC7C,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;QACtB,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC;QAChC,gBAAgB,EAAE,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC;KAC3C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,GAAY;IAChC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAA4B,CAAC;IACjD,OAAO;QACL,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3B,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QACjC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;QAC5B,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QACvB,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;QACpB,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAClB,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC;QACzC,cAAc,EAAE,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC;QACrC,cAAc,EAAE,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC;QACrC,kBAAkB,EAAE,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC;QAC7C,iEAAiE;KAClE,CAAC;AACJ,CAAC;AAED,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;AAEvD,qEAAqE;AACrE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAsB;IAClD,mBAAmB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,YAAY,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC;IAEjE,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAA2C,CAAC;IACjE,0EAA0E;IAC1E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,MAAM,UAAU,CACd,aAAa,EACb,SAAS,aAAa,0CAA0C,CACjE,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAI,CAAC,CAAC,OAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAChC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;IAE3E,MAAM,KAAK,GAAa,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;IAC1D,IAAI,QAAQ;QACV,KAAK,CAAC,IAAI,CACR,4IAA4I,CAC7I,CAAC;IAEJ,OAAO,QAAQ,CACb,EAAE,OAAO,EAAE,EACX;QACE,MAAM,EAAE,GAAG,UAAU,oEAAoE;QACzF,WAAW,EAAE,IAAI;QACjB,QAAQ;QACR,cAAc,EAAE,KAAK;QACrB,cAAc,EAAE,eAAe;QAC/B,cAAc,EAAE,EAAE;QAClB,iBAAiB,EAAE,EAAE;QACrB,KAAK;KAC0B,CAClC,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAsB;IACrD,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,eAAe,EAAE,gBAAgB,EAAE,IAAI,CAAC,CAAC;IAEvE,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAA2C,CAAC;IACjE,0EAA0E;IAC1E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,MAAM,UAAU,CACd,gBAAgB,EAChB,SAAS,gBAAgB,0CAA0C,CACpE,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAI,CAAC,CAAC,OAAqB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC;IACnC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IAE9E,MAAM,KAAK,GAAa;QACtB,YAAY;QACZ,iBAAiB;QACjB,mMAAmM;KACpM,CAAC;IACF,IAAI,QAAQ;QACV,KAAK,CAAC,IAAI,CACR,4IAA4I,CAC7I,CAAC;IAEJ,OAAO,QAAQ,CACb,EAAE,UAAU,EAAE,EACd;QACE,MAAM,EAAE,GAAG,UAAU,6EAA6E;QAClG,WAAW,EAAE,IAAI;QACjB,QAAQ;QACR,cAAc,EAAE,KAAK;QACrB,cAAc,EAAE,eAAe;QAC/B,cAAc,EAAE,EAAE;QAClB,iBAAiB,EAAE,EAAE;QACrB,KAAK;KAC0B,CAClC,CAAC;AACJ,CAAC"}

package/dist/nonprofit.d.ts

@@ -0,0 +1,116 @@
+/**
+ * nonprofit.ts — US TAX-EXEMPT NONPROFITS (IRS Form 990) — the nonprofit /
+ * grantee / subcontractor vetting lane (ADR-0060). Who a tax-exempt organization
+ * IS (EIN, NTEE code, subsection, ruling date, status) and what its Form 990
+ * FINANCIALS look like (revenue, expenses, assets, liabilities by tax year) —
+ * the 501(c) signal no contract/spending/grant/lobbying source carries.
+ *
+ * ★ PROVENANCE — THIS IS NOT A .gov API (must be disclosed). The DATA is IRS Form
+ *   990 filings — FEDERAL tax-exempt PUBLIC RECORDS — but the API is **ProPublica
+ *   Nonprofit Explorer**, operated by **ProPublica** (a non-profit newsroom) which
+ *   republishes those records KEYLESS. The IRS itself offers NO clean query API
+ *   (only bulk downloads / a web UI). So every response's `_meta.source` AND a note
+ *   name "IRS Form 990 data via ProPublica Nonprofit Explorer" — the tool NEVER
+ *   presents itself as a government API.
+ *
+ * ★ KEYLESS — no key of any kind. Anonymous GETs return HTTP 200. There is NO
+ *   KEY_REGISTRY / keys.ts / API_KEYS.md entry for this source.
+ *
+ * The module writes ZERO fetch/coercion/error/meta code of its own: it REUSES
+ * `getJson` (the shared fetch envelope, redirect:"error") / `driftError` /
+ * `num`·`str` (coerce.ts, null-never-0/empty) / `withMeta`·`buildMeta`.
+ *
+ *   SEARCH  GET https://projects.propublica.org/nonprofits/api/v2/search.json
+ *       ?q=&state[id]=&ntee[id]=&page=
+ *     → { total_results, organizations:[{ ein, name, sub_name, city, state,
+ *          ntee_code, subseccd, score }], num_pages, cur_page, per_page,
+ *          page_offset }
+ *   DETAIL  GET https://projects.propublica.org/nonprofits/api/v2/organizations/{ein}.json
+ *     → { organization:{ ein, name, address, city, state, zipcode, ntee_code,
+ *          subsection_code, ruling_date, exempt_organization_status_code,
+ *          foundation_code }, filings_with_data:[{ tax_prd_yr, formtype, pdf_url,
+ *          totrevenue, totfuncexpns, totassetsend, totliabend }] }
+ *
+ * ★ HONESTY (ADR-0060 P1–P5):
+ *   [P1]   SEARCH totalAvailable = `total_results` (the API's REAL total for the
+ *          query) — NEVER organizations.length. Page pagination (page is 0-based):
+ *          hasMore = (cur_page+1) < num_pages; the next page number is surfaced in
+ *          a note. DETAIL totalAvailable = filings.length (the COMPLETE filing set
+ *          from the one detail doc — no pagination). Reverting the search total to
+ *          organizations.length must go RED.
+ *   [P2]   SEARCH a genuine no-match (organizations:[]) ⇒ honest empty (returned:0,
+ *          complete:true). DETAIL an unknown EIN (HTTP 404) ⇒ not_found (NEVER a
+ *          fabricated empty org). A 4xx ⇒ invalid_input; a 5xx/timeout ⇒
+ *          upstream_unavailable THROW; a 200 non-JSON ⇒ schema_drift.
+ *   [P3]   The four Form 990 figures (totrevenue/totfuncexpns/totassetsend/
+ *          totliabend) ride `num()` — a genuine 0 STAYS 0, an absent figure ⇒ null
+ *          (NEVER 0-faked). EIN + the codes are strings; ruling_date is a string.
+ *   [P4]   SEARCH `organizations` non-array OR `total_results` non-number ⇒
+ *          driftError. DETAIL `organization` non-object OR `filings_with_data`
+ *          non-array ⇒ driftError (never a fabricated empty/total).
+ *   [SSRF] fixed host `projects.propublica.org`; a post-construction hostname/
+ *          protocol assert + `redirect:"error"`; the query VALUES ride
+ *          URLSearchParams (incl. the `state[id]`/`ntee[id]` bracket keys);
+ *          `ein` charclass `^\d{1,9}$` (path segment); `state` `^[A-Za-z]{2}$`;
+ *          `ntee` an integer 1..10.
+ */
+import { num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num };
+export declare const NONPROFIT_HOST = "projects.propublica.org";
+export type NonprofitOrgSummary = {
+    ein: string | null;
+    name: string | null;
+    city: string | null;
+    state: string | null;
+    nteeCode: string | null;
+    subsectionCode: string | null;
+};
+export type NonprofitOrganization = {
+    ein: string | null;
+    name: string | null;
+    address: string | null;
+    city: string | null;
+    state: string | null;
+    zip: string | null;
+    nteeCode: string | null;
+    subsectionCode: string | null;
+    rulingDate: string | null;
+    statusCode: string | null;
+};
+export type NonprofitFiling = {
+    taxYear: number | null;
+    formType: string | null;
+    revenueUsd: number | null;
+    expensesUsd: number | null;
+    assetsUsd: number | null;
+    liabilitiesUsd: number | null;
+    pdfUrl: string | null;
+};
+export type NonprofitSearchArgs = {
+    query?: string;
+    state?: string;
+    ntee?: number;
+    page?: number;
+};
+/**
+ * Search US tax-exempt nonprofits (IRS Form 990) via ProPublica Nonprofit Explorer
+ * (`/nonprofits/api/v2/search.json`) → curated org summaries + honest `_meta`.
+ * KEYLESS. ★PROVENANCE: this is ProPublica (a non-profit newsroom) republishing
+ * IRS Form 990 public records — NOT a .gov API. ★totalAvailable is the API's REAL
+ * `total_results` — never organizations.length; page-based (0-indexed) pagination.
+ */
+export declare function search(args: NonprofitSearchArgs): Promise<MetaBundle>;
+export type NonprofitFinancialsArgs = {
+    ein: string;
+};
+/**
+ * Fetch ONE nonprofit's IRS Form 990 profile + financials via ProPublica Nonprofit
+ * Explorer (`/nonprofits/api/v2/organizations/{ein}.json`) → curated organization +
+ * filings + honest `_meta`. KEYLESS. ★PROVENANCE: ProPublica (a non-profit newsroom)
+ * republishing IRS Form 990 public records — NOT a .gov API. An unknown EIN (HTTP
+ * 404) ⇒ not_found (never a fabricated empty org). The four Form 990 figures ride
+ * num() (null-never-0). totalAvailable = filings.length (the COMPLETE set).
+ */
+export declare function financials(args: NonprofitFinancialsArgs): Promise<MetaBundle>;
+//# sourceMappingURL=nonprofit.d.ts.map

package/dist/nonprofit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonprofit.d.ts","sourceRoot":"","sources":["../src/nonprofit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAIzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAGf,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAiCxD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAiBF,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAmCF,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CA4H3E;AAGD,MAAM,MAAM,uBAAuB,GAAG;IACpC,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAoGrB"}