@cliwant/mcp-sam-gov 1.2.0 → 1.4.0

package/dist/courtlistener.js

@@ -0,0 +1,398 @@
+/**
+ * courtlistener.ts — US FEDERAL COURT OPINIONS via CourtListener (ADR-0055) — the
+ * LITIGATION / case-law lane. Federal court decisions (opinions/clusters) — who
+ * sued whom in which court, the nature of suit, the disposition — the judicial
+ * signal no contract/spending/lobbying source carries (e.g. bid-protest and
+ * contract-claim opinions from the US Court of Federal Claims `uscfc` and the
+ * Federal Circuit `cafc`).
+ *
+ * ★ PROVENANCE — THIS IS NOT A .gov API (must be disclosed). The DATA is US federal
+ *   court PUBLIC RECORDS, but the API is **CourtListener**, operated by the **Free
+ *   Law Project** (a non-profit) which republishes those records KEYLESS. The .gov
+ *   primary source (PACER) is PAYWALLED. So every response's `_meta.source` AND a
+ *   note name CourtListener/Free Law Project and disclose the PACER-paywall — the
+ *   tool never presents itself as a government API.
+ *
+ * ★ THIS IS A KEYLESS TOOL WITH AN *OPTIONAL* RATE-LIMIT TOKEN (the lda.ts /
+ *   socrata app-token lineage, NOT the census/fred/bea key-REQUIRED lineage).
+ *   Anonymous GETs return HTTP 200 — it works with NO token. A free
+ *   COURTLISTENER_API_TOKEN only RAISES the shared rate limit; when set it rides
+ *   ONLY as the `Authorization: Token <value>` request header (never the
+ *   URL/label/_meta/notes/log — the K-test). When unset, NO auth header is sent
+ *   (genuine keyless). This mirrors lda.ts's optional-Authorization discipline.
+ *
+ *   GET https://www.courtlistener.com/api/rest/v4/search/
+ *       ?q=&court=&filed_after=&filed_before=&type=o&order_by=<order>[&cursor=]
+ *   → { count, next, previous, results:[{ caseName, court, court_id, dateFiled,
+ *        docketNumber, suitNature, status, judge, citation, absolute_url, … }] }
+ *
+ * ★ HONESTY (ADR-0055 P1–P5):
+ *   [P1]  totalAvailable = `count` (the API's REAL total for the filter, e.g. the
+ *         uscfc opinion corpus ~10595) — NEVER results.length. ★CURSOR pagination:
+ *         `next` is a FULL URL carrying an opaque `cursor=` param (NOT page/offset).
+ *         We EXTRACT the `cursor` value out of `next` and return it as `nextCursor`
+ *         (offset/nextOffset null — a numeric offset is meaningless); hasMore = next
+ *         is a non-null string. CourtListener v4 stops counting on deep cursor pages
+ *         (`count:null`) — that is DISCLOSED (totalAvailable:null + a note), never
+ *         fabricated as results.length.
+ *   [P2]  a genuine no-match (results:[]) ⇒ honest empty (returned:0). A 400 (bad
+ *         param) ⇒ invalid_input surfacing the API's message. A 429 (unauth
+ *         throttle) ⇒ rate_limited THROW (Retry-After honored, never routed around).
+ *         A 5xx/timeout ⇒ upstream_unavailable THROW. A 200 non-JSON ⇒ schema_drift.
+ *   [P3]  dates are strings; `citation` may be an array/object ⇒ flattened to a safe
+ *         string / string[] (never fabricated); judge / natureOfSuit / docketNumber
+ *         are null when absent (never empty-string); every scalar null-never-empty.
+ *   [P4]  `results` non-array, or `count` neither a number NOR null ⇒ driftError
+ *         (never a fabricated empty/total).
+ *   [K-test] OPTIONAL token: when COURTLISTENER_API_TOKEN is set it rides ONLY the
+ *         `Authorization: Token …` header — NEVER the URL/label/_meta/notes/log.
+ *         Unset ⇒ anonymous (no auth header at all).
+ *   [SSRF] fixed host `www.courtlistener.com`; a post-construction hostname/protocol
+ *         assert + `redirect:"error"`; `court` charclass `^[a-z0-9]+$`; the dates
+ *         charclass `^\d{4}-\d{2}-\d{2}$`; every VALUE rides URLSearchParams. The
+ *         `cursor` is opaque but charclass-guarded; and when we EXTRACT the cursor
+ *         from a `next` URL we RE-ASSERT that URL's host is courtlistener.com — an
+ *         off-host `next` is REFUSED (schema_drift), never followed.
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { str } from "./coerce.js";
+import { withMeta } from "./meta.js";
+// ─── SSRF core: the single fixed host + base path ─────────────────
+export const COURTLISTENER_HOST = "www.courtlistener.com";
+const COURTLISTENER_SEARCH_PATH = "/api/rest/v4/search/";
+// HOST+path label — surfaces in ToolError.upstreamEndpoint; the optional token rides
+// ONLY in the Authorization header, so no token can ever appear here.
+const COURTLISTENER_SEARCH_LABEL = "courtlistener:/api/rest/v4/search";
+// ─── Validation (SSRF + "verify the input" honesty) ───────────────
+// A CourtListener court id — lowercase alphanumerics only (e.g. uscfc, cafc, scotus).
+const COURT_RE = /^[a-z0-9]+$/;
+// An ISO calendar date (→ filed_after / filed_before).
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+// The opaque cursor grammar (SSRF + injection guard). CourtListener's v4 cursor is a
+// URL-safe token; we return the DECODED value (extracted via URLSearchParams), so it
+// carries NO `%`. Reject spaces / `&` / `#` / `?` / quotes / angle-brackets / `\`
+// BEFORE it rides `cursor=` (defense-in-depth — the value can never steer the
+// fixed-host authority, but a malformed cursor must never reach the query).
+export const COURTLISTENER_CURSOR_RE = /^[A-Za-z0-9\-._~=+/:]{1,8192}$/;
+const DEFAULT_ORDER = "dateFiled desc";
+// ─── Honesty notes (ADR-0055 required set) ────────────────────────
+const PROVENANCE_NOTE = "Data = US FEDERAL COURT PUBLIC RECORDS served by CourtListener (Free Law Project, a non-profit) — NOT a .gov API. CourtListener republishes these records keyless; the .gov primary source (PACER) is PAYWALLED. Treat opinions as of CourtListener's last ingest.";
+const KEYLESS_NOTE = "Keyless by default (anonymous CourtListener access returns HTTP 200). An optional free COURTLISTENER_API_TOKEN only RAISES the rate limit; when set it is sent ONLY as the `Authorization: Token …` request header and is NEVER logged, echoed, or placed in this response.";
+const COUNT_TOTAL_NOTE = "totalAvailable is CourtListener's real `count` — the total match count for the filter (NOT the rows on this page). Pagination is an OPAQUE cursor: pass _meta.nextCursor back as the `cursor` argument (offset/nextOffset are meaningless/null). nextCursor:null / hasMore:false means this is the last page.";
+const DEEP_PAGE_NO_COUNT_NOTE = "CourtListener did not report a `count` on this cursor page (v4 stops counting on deep pages to save cost) — totalAvailable is unknown (null), NOT results.length. Use nextCursor to continue.";
+const NATURE_OF_SUIT_QUERY_NOTE = "natureOfSuit was applied as a full-text query term (the v4 opinions search has no verified dedicated nature-of-suit filter), so it matches that text anywhere in the document rather than an exact suitNature-field equality.";
+// ─── The optional-token seam (value NEVER leaked past the Authorization header) ──
+/**
+ * The optional Authorization header (keyless-first, lda.ts/socrata app-token
+ * lineage). Present ONLY when COURTLISTENER_API_TOKEN is set (non-blank); the value
+ * is NEVER logged / never placed in the URL, label, `_meta`, or a note. When unset,
+ * `{}` (no header ⇒ genuine anonymous).
+ */
+export function courtlistenerAuthHeader() {
+    const raw = process.env.COURTLISTENER_API_TOKEN;
+    const trimmed = typeof raw === "string" ? raw.trim() : "";
+    return trimmed ? { Authorization: `Token ${trimmed}` } : {};
+}
+/** true iff a CourtListener token is configured (for the `_meta` note — never the value). */
+export function courtlistenerTokenPresent() {
+    const raw = process.env.COURTLISTENER_API_TOKEN;
+    return typeof raw === "string" && raw.trim().length > 0;
+}
+/**
+ * Flatten CourtListener's `citation` (which may be a string, an array of strings,
+ * or an object) to a safe `string | string[] | null` — NEVER fabricated. An array
+ * ⇒ the non-null strings (or null when none); a string ⇒ that string; an object ⇒
+ * its non-null string VALUES (or null when none); absent ⇒ null. `[object Object]`
+ * can never leak (we never `String()` an object).
+ */
+export function flattenCitation(x) {
+    if (x === null || x === undefined)
+        return null;
+    if (typeof x === "string")
+        return str(x);
+    if (Array.isArray(x)) {
+        const parts = x.map((v) => str(v)).filter((v) => v !== null);
+        return parts.length === 0 ? null : parts;
+    }
+    if (typeof x === "object") {
+        const parts = Object.values(x)
+            .map((v) => str(v))
+            .filter((v) => v !== null);
+        return parts.length === 0 ? null : parts;
+    }
+    return null;
+}
+/** Prefix a relative absolute_url with the fixed host; pass an already-absolute URL through. */
+function resolveAbsoluteUrl(raw) {
+    const path = str(raw);
+    if (path === null)
+        return null;
+    if (/^https?:\/\//i.test(path))
+        return path;
+    return `https://${COURTLISTENER_HOST}${path.startsWith("/") ? path : `/${path}`}`;
+}
+/** Map ONE `results[]` opinion row → the curated shape. Every scalar via `str`. */
+function mapOpinion(raw) {
+    const o = (raw ?? {});
+    return {
+        caseName: str(o.caseName) ?? str(o.caseNameFull),
+        // court_citation_string is the short display name; fall back to the full `court`.
+        court: str(o.court_citation_string) ?? str(o.court),
+        courtId: str(o.court_id),
+        dateFiled: str(o.dateFiled),
+        docketNumber: str(o.docketNumber),
+        natureOfSuit: str(o.suitNature),
+        status: str(o.status),
+        judge: str(o.judge),
+        citation: flattenCitation(o.citation),
+        absoluteUrl: resolveAbsoluteUrl(o.absolute_url),
+    };
+}
+/**
+ * Extract the opaque `cursor` value from a CourtListener `next` URL. RE-ASSERTS the
+ * `next` URL's host is courtlistener.com — an OFF-HOST `next` is REFUSED (drift),
+ * never parsed/followed (SSRF: a poisoned `next` could otherwise steer the next
+ * page off-host). Returns the decoded cursor string, or null when `next` is null /
+ * carries no cursor. A non-string / unparseable `next` ⇒ null (treated as "no more").
+ */
+export function extractNextCursor(next, label) {
+    if (next === null || next === undefined)
+        return null;
+    if (typeof next !== "string" || next === "")
+        return null;
+    let u;
+    try {
+        u = new URL(next);
+    }
+    catch {
+        // A malformed `next` is drift — never fabricate a continuation from it.
+        throw driftError(label, `CourtListener returned a malformed \`next\` URL (${JSON.stringify(next).slice(0, 120)}) — refusing to derive a cursor from it.`);
+    }
+    if (u.hostname !== COURTLISTENER_HOST || u.protocol !== "https:") {
+        // An OFF-HOST next must be refused, not followed (SSRF safety).
+        throw driftError(label, `CourtListener \`next\` points off-host (${JSON.stringify(u.hostname)} ${u.protocol}) — refusing to follow it (SSRF safety).`);
+    }
+    return u.searchParams.get("cursor");
+}
+/**
+ * Search US federal court opinions via CourtListener (`/api/rest/v4/search/`,
+ * type=o) → curated opinion rows + honest `_meta`. KEYLESS (an optional
+ * COURTLISTENER_API_TOKEN only raises the rate limit, sent as the Authorization
+ * header only). ★PROVENANCE: this is CourtListener/Free Law Project (a non-profit),
+ * NOT a .gov API — PACER (the .gov source) is paywalled. totalAvailable is the
+ * API's REAL `count`; CURSOR pagination (nextCursor extracted from `next`).
+ */
+export async function searchOpinions(args) {
+    const label = COURTLISTENER_SEARCH_LABEL;
+    // ── Validate + default (belt-and-suspenders behind the server Zod; a DIRECT
+    //    handler call bypasses Zod). court / dates are charclass-guarded; the cursor
+    //    grammar-guarded; the free-text values ride URLSearchParams (encoded). ──
+    if (args.court !== undefined && !COURT_RE.test(args.court)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid court ${JSON.stringify(args.court)} — expected a CourtListener court id (lowercase alphanumerics, ^[a-z0-9]+$), e.g. "uscfc", "cafc", "scotus".`,
+            upstreamEndpoint: label,
+        });
+    }
+    if (args.dateFiledAfter !== undefined &&
+        !DATE_RE.test(args.dateFiledAfter)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid dateFiledAfter ${JSON.stringify(args.dateFiledAfter)} — expected an ISO date (^\\d{4}-\\d{2}-\\d{2}$), e.g. "2020-01-01".`,
+            upstreamEndpoint: label,
+        });
+    }
+    if (args.dateFiledBefore !== undefined &&
+        !DATE_RE.test(args.dateFiledBefore)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid dateFiledBefore ${JSON.stringify(args.dateFiledBefore)} — expected an ISO date (^\\d{4}-\\d{2}-\\d{2}$), e.g. "2024-12-31".`,
+            upstreamEndpoint: label,
+        });
+    }
+    if (args.cursor !== undefined &&
+        !COURTLISTENER_CURSOR_RE.test(args.cursor)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid cursor (opaque continuation token) — must be a ≤8192-char URL-safe token (no spaces, '%', or steering characters). Pass back the _meta.nextCursor from the previous page.`,
+            upstreamEndpoint: label,
+        });
+    }
+    // ── Build the query from VALIDATED typed args, key-by-key (SSRF: no raw
+    //    passthrough; every VALUE is URLSearchParams-encoded). type=o is FIXED. ──
+    const params = new URLSearchParams();
+    const filtersApplied = [];
+    // natureOfSuit has no verified dedicated filter on the v4 opinions search, so it
+    // is folded into the `q` full-text query (disclosed via NATURE_OF_SUIT_QUERY_NOTE).
+    const qParts = [];
+    if (args.query !== undefined && args.query !== "") {
+        qParts.push(args.query);
+        filtersApplied.push("query");
+    }
+    let natureOfSuitApplied = false;
+    if (args.natureOfSuit !== undefined && args.natureOfSuit !== "") {
+        qParts.push(args.natureOfSuit);
+        filtersApplied.push("natureOfSuit");
+        natureOfSuitApplied = true;
+    }
+    if (qParts.length > 0)
+        params.set("q", qParts.join(" "));
+    if (args.court !== undefined) {
+        params.set("court", args.court);
+        filtersApplied.push("court");
+    }
+    if (args.dateFiledAfter !== undefined) {
+        params.set("filed_after", args.dateFiledAfter);
+        filtersApplied.push("dateFiledAfter");
+    }
+    if (args.dateFiledBefore !== undefined) {
+        params.set("filed_before", args.dateFiledBefore);
+        filtersApplied.push("dateFiledBefore");
+    }
+    params.set("type", "o"); // FIXED — opinions only
+    params.set("order_by", args.order && args.order !== "" ? args.order : DEFAULT_ORDER);
+    if (args.cursor !== undefined) {
+        params.set("cursor", args.cursor);
+        filtersApplied.push("cursor");
+    }
+    const url = `https://${COURTLISTENER_HOST}${COURTLISTENER_SEARCH_PATH}?${params.toString()}`;
+    // Belt-and-suspenders: the fixed host + strictly-built query leave nothing to
+    // steer the authority; assert the built URL cannot have been moved off-host.
+    const built = new URL(url);
+    if (built.hostname !== COURTLISTENER_HOST || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Constructed CourtListener URL host ${JSON.stringify(built.hostname)} (${built.protocol}) is not ${COURTLISTENER_HOST} over https — refusing to fetch (SSRF safety).`,
+            upstreamEndpoint: label,
+        });
+    }
+    // ── Fetch through the shared envelope. The optional token rides the Authorization
+    //    header ONLY (never the URL/label/_meta); redirect:"error" fails closed on any
+    //    off-host 3xx. A 429 ⇒ rate_limited THROW (Retry-After honored by the shared
+    //    taxonomy, never routed around); a 5xx/timeout ⇒ upstream_unavailable THROW; a
+    //    400 ⇒ invalid_input (re-read below to surface the API message); a 200 non-JSON
+    //    ⇒ getJson's r.json() throws a SyntaxError ⇒ schema_drift. ──
+    const headers = courtlistenerAuthHeader();
+    let body;
+    try {
+        body = await getJson(url, {
+            label,
+            headers,
+            redirect: "error",
+        });
+    }
+    catch (e) {
+        if (e instanceof SyntaxError) {
+            throw driftError(label, "CourtListener /api/rest/v4/search returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).");
+        }
+        // [P2] A 400 (bad param) carries a DRF error body; fetchWithRetry discarded it.
+        // Re-read once on the error path ONLY so the caller learns the REAL reason (never
+        // a fake-empty). 5xx/429/404/timeout keep their taxonomy.
+        if (e instanceof ToolErrorCarrier && e.toolError.upstreamStatus === 400) {
+            const apiMsg = await readCourtlistenerErrorMessage(url, headers);
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: apiMsg
+                    ? `CourtListener rejected the request (HTTP 400): ${apiMsg}. Check the filter parameters (court, dateFiledAfter/Before, order, cursor).`
+                    : "CourtListener rejected the request (HTTP 400) — check the filter parameters (court, dateFiledAfter/Before, order, cursor).",
+                upstreamStatus: 400,
+                upstreamEndpoint: label,
+            });
+        }
+        throw e; // 5xx → upstream_unavailable, 404 → not_found, 429 → rate_limited …
+    }
+    // ── [P4] `results` MUST be an array; `count` MUST be a number OR null (v4 returns
+    //    count:null on deep cursor pages — a documented behavior, NOT drift). A
+    //    non-array results, or a count that is neither a number nor null (e.g. a
+    //    string/object), is drift — never a fabricated empty/total. ──
+    const b = (body ?? {});
+    if (!Array.isArray(b.results)) {
+        throw driftError(label, "CourtListener /api/rest/v4/search shape drift — `results` must be an array.");
+    }
+    const rawCount = b.count;
+    const countIsNumber = typeof rawCount === "number" && Number.isFinite(rawCount);
+    if (!countIsNumber && rawCount !== null && rawCount !== undefined) {
+        throw driftError(label, "CourtListener /api/rest/v4/search shape drift — `count` must be the total match count (a number) or null (deep cursor page).");
+    }
+    const opinions = b.results.map(mapOpinion);
+    const returned = opinions.length;
+    // ── [P1] totalAvailable is the API's REAL count, NEVER results.length. count:null
+    //    (deep cursor page) ⇒ totalAvailable:null + a disclosure note. ★CURSOR
+    //    pagination: hasMore from `next` presence; nextCursor EXTRACTED from the `next`
+    //    URL (host re-asserted). ──
+    const totalAvailable = countIsNumber ? rawCount : null;
+    const nextCursor = extractNextCursor(b.next, label);
+    const hasMore = nextCursor !== null;
+    const notes = [PROVENANCE_NOTE, COUNT_TOTAL_NOTE];
+    if (!countIsNumber)
+        notes.push(DEEP_PAGE_NO_COUNT_NOTE);
+    if (natureOfSuitApplied)
+        notes.push(NATURE_OF_SUIT_QUERY_NOTE);
+    notes.push(KEYLESS_NOTE);
+    notes.push(`CourtListener token: ${courtlistenerTokenPresent() ? "present (Authorization: Token … sent; value never logged)" : "absent (keyless; a free COURTLISTENER_API_TOKEN lifts the rate limit)"}.`);
+    return withMeta({ opinions }, {
+        source: `${COURTLISTENER_HOST} /api/rest/v4/search (CourtListener (Free Law Project) — US federal court records; PACER (.gov) is paywalled; keyless)`,
+        keylessMode: true, // ★KEYLESS — the optional token only raises the rate limit
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        // Cursor page: offset/nextOffset null (no numeric offset); continuation is
+        // nextCursor (the opaque token extracted from `next`, passed back as `cursor`).
+        pagination: { offset: null, limit: returned, hasMore, nextOffset: null },
+        nextCursor,
+        notes,
+    });
+}
+/**
+ * Single bare GET to read a CourtListener 400's DRF error body (error path ONLY).
+ * Returns a compact human-readable message, or null on any failure. Sends the SAME
+ * headers (so a keyed re-read honors the token) + redirect:"error"; the token stays
+ * header-only.
+ */
+async function readCourtlistenerErrorMessage(url, headers) {
+    try {
+        const r = await fetch(url, {
+            signal: AbortSignal.timeout(15_000),
+            headers,
+            redirect: "error",
+        });
+        const body = (await r.json());
+        return summarizeDrfError(body);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Summarize a Django-REST-Framework 400 error body into a compact string. DRF emits
+ * `{ detail: "…" }` OR `{ field: ["message", …], … }`. Returns null for a shape we
+ * can't read (⇒ the caller falls back to the generic 400 message).
+ */
+function summarizeDrfError(body) {
+    if (typeof body === "string")
+        return str(body);
+    if (body === null || typeof body !== "object")
+        return null;
+    const obj = body;
+    if (typeof obj.detail === "string")
+        return str(obj.detail);
+    const parts = [];
+    for (const [k, v] of Object.entries(obj)) {
+        const msg = Array.isArray(v)
+            ? v.map((x) => str(x)).filter((x) => x !== null).join("; ")
+            : str(v);
+        if (msg)
+            parts.push(`${k}: ${msg}`);
+    }
+    return parts.length > 0 ? parts.join(" | ") : null;
+}
+//# sourceMappingURL=courtlistener.js.map

package/dist/courtlistener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"courtlistener.js","sourceRoot":"","sources":["../src/courtlistener.ts"],"names":[],"mappings":"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"}

package/dist/cpsc.d.ts

@@ -0,0 +1,81 @@
+/**
+ * cpsc.ts — CPSC CONSUMER-PRODUCT RECALLS (www.saferproducts.gov) — the consumer
+ * goods / import product-safety vetting lane (ADR-0058). ONE keyless tool:
+ *   • cpsc_recalls — /RestWebServices/Recall?format=json + date/product/manufacturer/
+ *     recallNumber filters.
+ * The third leg of the cross-agency product-safety family alongside NHTSA (vehicles)
+ * and openFDA (medical/food): a manufacturer / product / hazard recall history for
+ * B2G supplier and import 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 `str`
+ *   coercion (null-never-empty-string), and `withMeta`/`buildMeta` — and mirrors
+ *   nhtsa.ts / datagov-catalog.ts's fixed-host SSRF idiom + schema_drift
+ *   catch-ladder verbatim.
+ *
+ * ★ THE HONESTY PILLARS (P1-P5, live-verified 2026-07-15):
+ *   P1: the /Recall response is a BARE JSON ARRAY with NO count field and NO server
+ *       pagination — it returns the COMPLETE set matching the filter. So
+ *       totalAvailable = results.length and complete:true, WITH a disclosing note
+ *       that CPSC reports no total-count field / no pagination. A total is NEVER
+ *       fabricated (there is no upstream total to trust; the honest total is the
+ *       length of the complete set).
+ *   P2: an empty array `[]` ⇒ an HONEST EMPTY (returned:0, complete:true) — a filter
+ *       that matches nothing 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 OR a non-array body ⇒ schema_drift (never a fabricated empty).
+ *   P3: dates stay STRINGS (via `str`); NumberOfUnits is free text ("About 6,500")
+ *       kept as a STRING; nested arrays (Products/Manufacturers/Retailers/Hazards/
+ *       Remedies/Injuries/ManufacturerCountries) are flattened to string arrays by
+ *       extracting each object's `.Name` (★ManufacturerCountries uses `.Country`,
+ *       NOT `.Name`), SKIPPING an empty `{}` object (never a fabricated entry); a
+ *       genuinely-absent nested array ⇒ []; null-never-empty-string throughout.
+ *   P4: the top-level body MUST be an array — a non-array (object/string/null) ⇒
+ *       driftError (a broken response contract, never a fabricated empty).
+ *   DEFAULT-WINDOW: with NO filter given, the unfiltered result is huge, so the tool
+ *       defaults RecallDateStart to ~90 days ago and DISCLOSES the default in a note
+ *       — it NEVER silently fetches the whole dataset.
+ *   SSRF: fixed host `www.saferproducts.gov` (compile-time literal) + post-construction
+ *       hostname/protocol assertion + redirect:"error"; every filter rides a
+ *       module-built URLSearchParams (no raw passthrough); dates are ^\d{4}-\d{2}-\d{2}$;
+ *       recallNumber is charclass-validated (letters/digits/hyphen only), so a
+ *       `../` or `%` can never reach the fixed path.
+ */
+import { type MetaBundle } from "./meta.js";
+export declare const CPSC_HOST = "www.saferproducts.gov";
+export declare const CPSC_DATE_RE: RegExp;
+export declare const CPSC_RECALL_NUMBER_RE: RegExp;
+export type CpscRecall = {
+    recallNumber: string | null;
+    recallDate: string | null;
+    title: string | null;
+    description: string | null;
+    url: string | null;
+    products: string[];
+    numberOfUnits: string | null;
+    manufacturers: string[];
+    retailers: string[];
+    hazards: string[];
+    remedies: string[];
+    injuries: string[];
+    manufacturerCountries: string[];
+};
+export type CpscRecallsArgs = {
+    dateStart?: string;
+    dateEnd?: string;
+    productName?: string;
+    manufacturer?: string;
+    recallNumber?: string;
+};
+/**
+ * Fetch CPSC consumer-product RECALLS → curated recall rows + honest `_meta`.
+ * KEYLESS. All filters are optional; with NO filter given, RecallDateStart defaults
+ * to ~90 days ago (disclosed in a note) so the whole dataset is never silently
+ * fetched. The response is a bare array with no total-count field / no pagination
+ * ⇒ totalAvailable = the number of returned recalls, complete:true. An empty array
+ * ⇒ an honest empty; a 4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROW; a 200 non-JSON
+ * OR a non-array body ⇒ schema_drift.
+ */
+export declare function recalls(args: CpscRecallsArgs): Promise<MetaBundle>;
+//# sourceMappingURL=cpsc.d.ts.map

package/dist/cpsc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpsc.d.ts","sourceRoot":"","sources":["../src/cpsc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAKH,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAGzE,eAAO,MAAM,SAAS,0BAA0B,CAAC;AAUjD,eAAO,MAAM,YAAY,QAAwB,CAAC;AAClD,eAAO,MAAM,qBAAqB,QAAoB,CAAC;AAgDvD,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC,CAAC;AA4BF,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AA8EF;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAuFxE"}