@cliwant/mcp-sam-gov 1.2.0 → 1.4.0

package/dist/cms-hospital.js

@@ -0,0 +1,290 @@
+/**
+ * cms-hospital.ts — CMS Hospital Compare "Hospital General Information"
+ * (`data.cms.gov`, the provider-data DKAN datastore-query API; ADR-0062). KEYLESS.
+ *
+ * WHAT IT ADDS: `cms_hospital_compare` — a healthcare-facility directory / market
+ * lane: for a US state (and/or a facility-name fragment) list Medicare-certified
+ * hospitals with their location, type, ownership, emergency-services flag, and CMS
+ * star rating. The facility-level complement to the utilization lane
+ * (cms_medicare_provider_services, who BILLS) — this is WHERE the hospitals ARE and
+ * HOW CMS rates them.
+ *
+ * ★THE ONE-REQUEST COUNT PATTERN (the load-bearing P1 honesty — SIMPLER than
+ *   cms-utilization's two-request stats-count): the DKAN datastore-query response
+ *   is `{ count, results, schema, query }` — `count` is the EXACT per-filter total
+ *   in the SAME body as the rows. So totalAvailable = the response's top-level
+ *   `count` (VA ⇒ 96), NEVER `results.length`. A single request; no separate count
+ *   sub-query is needed (or possible — the endpoint reports the total inline).
+ *
+ * ★THE FILTER-REQUIRED INPUT GUARD: the dataset is 5432 hospitals. An all-empty
+ *   query (no state, no facilityName) is REFUSED with invalid_input (0 fetch) —
+ *   hospitalType alone is NOT enough to scope; a caller MUST pin state OR
+ *   facilityName.
+ *
+ * ★THE DKAN CONDITIONS FILTER (live-verified 2026-07-15): filters ride as
+ *   `conditions[i][property]` / `conditions[i][value]` / `conditions[i][operator]`
+ *   query triples, AND-combined server-side. `state` uses the exact operator `=`
+ *   (VA ⇒ 96); `facilityName` + `hospitalType` use the `contains` operator (a
+ *   case-insensitive substring match, live-verified — "CHILDREN" ⇒ 95). ALL
+ *   filtering is server-side; NOTHING is silently dropped or client-faked.
+ *
+ * The module writes ZERO fetch/coercion/error/meta code — it REUSES `getJson`
+ * (redirect:"error") / `driftError` (datasource.ts), `str`/`num` (coerce.ts,
+ * null-never-empty-string / null-never-0), and `withMeta`·`buildMeta` (meta.ts,
+ * offset pagination + totalAvailable). It MIRRORS cms-utilization.ts's fixed-host
+ * SSRF idiom (a single host const + a post-construction hostname/protocol assertion
+ * + redirect:"error" + `conditions[i][…]` bracket keys and values carried via
+ * URLSearchParams) and its schema_drift catch-ladder (ToolErrorCarrier rethrow
+ * FIRST so a 5xx keeps its taxonomy → SyntaxError→driftError → bare rethrow).
+ *
+ *   GET https://data.cms.gov/provider-data/api/1/datastore/query/{datasetId}/0
+ *       ?limit=&offset=&conditions[0][property]=state&conditions[0][value]=VA&conditions[0][operator]==
+ *       → { count: 96, results: [ { facility_id, facility_name, … }, … ], schema, query }
+ *
+ * ★ SSRF: the host is a compile-time literal (`CMS_HOST`); the dataset id + the
+ *   endpoint path are MODULE literals. Every USER filter VALUE rides as a
+ *   URLSearchParams VALUE (`conditions[i][value]=…`) — URLSearchParams encodes the
+ *   bracket key AND the value, so a value can never break out into the path or
+ *   inject a parameter. state is `^[A-Za-z]{2}$`; facilityName/hospitalType are a
+ *   bounded free-text charclass; size/offset are coerced to integers. A
+ *   post-construction hostname/protocol assertion + `redirect:"error"` fail closed
+ *   on any off-host 3xx.
+ *
+ * ★ HONESTY (ADR-0062 P1–P5, live-verified 2026-07-15 on data.cms.gov):
+ *   [input] require state OR facilityName — an all-empty query is REFUSED (0 fetch).
+ *   [P1]    totalAvailable = the response's top-level `count` (EXACT — VA = 96), NOT
+ *           the slice length. hasMore = offset+returned < count.
+ *   [P2]    results:[] ⇒ honest empty (returned:0). getJson maps a 4xx/5xx via
+ *           errorFromResponse and THROWS (503 ⇒ upstream_unavailable, 400 ⇒
+ *           invalid_input, 404 ⇒ not_found); a 200 non-JSON/non-array body OR a body
+ *           missing `count`/`results` ⇒ schema_drift (NEVER a fabricated empty).
+ *   [P3]    hospital_overall_rating "1"–"5" via num(); "Not Available"/""/non-numeric
+ *           ⇒ null (NEVER 0 — a data-absence-as-zero masquerade is the forbidden
+ *           class). emergency_services "Yes"⇒true / "No"⇒false / else null. String
+ *           fields via str() (null-never-empty-string).
+ *   [P4]    results non-array OR count non-number ⇒ driftError.
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { str, num } from "./coerce.js";
+import { withMeta } from "./meta.js";
+// Re-export the shared honesty coercions (single audited copy in ./coerce.js) so a
+// regression fails together across sources. NO local num/str.
+export { num, str };
+// ─── SSRF core: the single fixed host + module-literal path pieces ──
+const CMS_HOST = "data.cms.gov";
+// HOST-only label — surfaces in ToolError.upstreamEndpoint; keyless, so no token
+// can ever appear here.
+const CMS_LABEL = "cms-hospital:data.cms.gov";
+// ★THE DATASET ID — CMS Hospital Compare "Hospital General Information" (5432
+// Medicare-certified hospitals at build time). ★UPDATE IF CMS RE-IDs IT: the
+// provider-data datastore keys this dataset by a short slug; CMS has historically
+// kept it stable, but a re-publish could change it. The active dataset is surfaced
+// to the caller in a _meta note (DATASET_NOTE) so a consumer never mistakes the
+// vintage.
+const CMS_HOSPITAL_DATASET_ID = "xubh-q36u";
+const CMS_HOSPITAL_PATH = `/provider-data/api/1/datastore/query/${CMS_HOSPITAL_DATASET_ID}/0`;
+// ─── Validation charclasses (SSRF + "verify the input" honesty) ───
+const STATE_RE = /^[A-Za-z]{2}$/; // 2-letter state/territory abbreviation
+// facilityName / hospitalType ride as URLSearchParams VALUES (encoded), so these
+// bounds are a sanity guard, not an SSRF necessity: letters/digits/space and common
+// punctuation only (facility names carry apostrophes, &, /, -, .).
+const FACILITY_NAME_RE = /^[A-Za-z0-9 &.,()/'-]{1,100}$/;
+const HOSPITAL_TYPE_RE = /^[A-Za-z0-9 &.,()/'-]{1,100}$/;
+const SIZE_MIN = 1;
+const SIZE_MAX = 100;
+const SIZE_DEFAULT = 25;
+// DKAN condition operators (live-verified). state = exact; name/type = substring.
+const OP_EQUALS = "=";
+const OP_CONTAINS = "contains";
+// ─── Honesty notes (ADR-0062 required set) ────────────────────────
+const DATASET_NOTE = `Source dataset: CMS Hospital Compare "Hospital General Information" (data.cms.gov provider-data datastore "${CMS_HOSPITAL_DATASET_ID}", ~5,432 Medicare-certified hospitals) — a CMS-published snapshot, not a live/real-time feed. Update the dataset id if CMS re-publishes it.`;
+const FILTER_NOTE = "Filters are applied SERVER-SIDE via DKAN conditions (AND-combined): `state` is an EXACT match; `facilityName` and `hospitalType` are case-insensitive SUBSTRING (contains) matches — so a facilityName fragment may match several hospitals. totalAvailable is the upstream's EXACT count for this filter set, not the returned-row count.";
+const RATING_NOTE = "hospital_overall_rating is CMS's 1–5 star summary rating; \"Not Available\" (and any non-numeric) maps to overallRating:null (unknown), NEVER 0. This is a summary rating, NOT a clinical-quality or fitness determination.";
+/**
+ * Normalize the CMS `emergency_services` "Yes"/"No" flag → boolean | null.
+ * "Yes"⇒true, "No"⇒false (case-insensitive); anything else (absent/""/unrecognized)
+ * ⇒ null — NEVER a fabricated false (a data-absence-as-false masquerade).
+ */
+export function emergencyBool(x) {
+    const s = str(x);
+    if (s === null)
+        return null;
+    const low = s.toLowerCase();
+    if (low === "yes")
+        return true;
+    if (low === "no")
+        return false;
+    return null;
+}
+/** Map ONE datastore-query row → the curated hospital shape. */
+function mapHospital(row) {
+    const r = (row ?? {});
+    return {
+        facilityId: str(r.facility_id),
+        facilityName: str(r.facility_name),
+        address: str(r.address),
+        city: str(r.citytown),
+        state: str(r.state),
+        zip: str(r.zip_code),
+        county: str(r.countyparish),
+        phone: str(r.telephone_number),
+        hospitalType: str(r.hospital_type),
+        ownership: str(r.hospital_ownership),
+        emergencyServices: emergencyBool(r.emergency_services),
+        // [P3] "1"–"5" → number; "Not Available"/""/non-numeric → null (NEVER 0).
+        // num() returns null for a non-numeric string (Number("Not Available")=NaN) and
+        // for "" — exactly the P3 contract.
+        overallRating: num(r.hospital_overall_rating),
+    };
+}
+// ─── SSRF-guarded fetch (fixed host + hostname assertion + redirect:"error") ──
+/**
+ * GET one data.cms.gov provider-data JSON resource at a MODULE-BUILT URL (the
+ * dataset id + the endpoint path are literals; all user filter VALUES are already
+ * carried in the URLSearchParams `query`). Asserts the CONSTRUCTED URL's hostname
+ * === the fixed host over https, and sets `redirect:"error"` (an off-host 3xx must
+ * NOT be followed). Keyless — no headers.
+ */
+async function getCms(query) {
+    const url = `https://${CMS_HOST}${CMS_HOSPITAL_PATH}?${query.toString()}`;
+    const built = new URL(url);
+    if (built.hostname !== CMS_HOST || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Constructed CMS provider-data URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the fixed host ${JSON.stringify(CMS_HOST)} over https — refusing to fetch (SSRF safety).`,
+            retryable: false,
+            upstreamEndpoint: CMS_LABEL,
+        });
+    }
+    return getJson(built.toString(), { label: CMS_LABEL, redirect: "error" });
+}
+/**
+ * Fetch CMS Hospital Compare "Hospital General Information" rows for a state and/or
+ * facility-name fragment (+ optional hospitalType) → normalized hospital rows +
+ * honest `_meta`. REQUIRES state OR facilityName (an all-empty query is refused). A
+ * SINGLE request: the response's top-level `count` is the EXACT per-filter total
+ * (P1 — never the slice length).
+ */
+export async function hospitalCompare(args) {
+    // ── [input guard] require state OR facilityName (never scan the whole dataset).
+    //    hospitalType alone is NOT sufficient to scope. ──
+    const hasState = args.state !== undefined && args.state !== "";
+    const hasFacilityName = args.facilityName !== undefined && args.facilityName !== "";
+    if (!hasState && !hasFacilityName) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: "cms_hospital_compare requires at least `state` (2-letter) OR `facilityName` — an all-empty query would scan the entire ~5,432-hospital table and is refused. hospitalType alone is not enough; add state or facilityName and retry.",
+            upstreamEndpoint: CMS_LABEL,
+        });
+    }
+    // ── Validate + build the DKAN conditions (SSRF: charclass + URLSearchParams
+    //    value). URLSearchParams encodes both the bracket key and the value. Each
+    //    condition is an (property, value, operator) triple indexed by position. ──
+    const query = new URLSearchParams();
+    const filtersApplied = [];
+    let ci = 0;
+    const pushCondition = (property, value, operator) => {
+        query.set(`conditions[${ci}][property]`, property);
+        query.set(`conditions[${ci}][value]`, value);
+        query.set(`conditions[${ci}][operator]`, operator);
+        ci += 1;
+    };
+    if (hasState) {
+        const state = args.state;
+        if (!STATE_RE.test(state)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid state ${JSON.stringify(state)} — expected a 2-letter state/territory code (^[A-Za-z]{2}$), e.g. "VA".`,
+                upstreamEndpoint: CMS_LABEL,
+            });
+        }
+        pushCondition("state", state.toUpperCase(), OP_EQUALS);
+        filtersApplied.push(`state:${state.toUpperCase()}`);
+    }
+    if (hasFacilityName) {
+        const name = args.facilityName;
+        if (!FACILITY_NAME_RE.test(name)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid facilityName ${JSON.stringify(name)} — allowed: letters, digits, space, & . , ( ) / ' - (≤100 chars). It is a case-insensitive substring match.`,
+                upstreamEndpoint: CMS_LABEL,
+            });
+        }
+        pushCondition("facility_name", name, OP_CONTAINS);
+        filtersApplied.push(`facilityName~${name}`);
+    }
+    if (args.hospitalType !== undefined && args.hospitalType !== "") {
+        const ht = args.hospitalType;
+        if (!HOSPITAL_TYPE_RE.test(ht)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid hospitalType ${JSON.stringify(ht)} — allowed: letters, digits, space, & . , ( ) / ' - (≤100 chars). It is a case-insensitive substring match, e.g. "Acute".`,
+                upstreamEndpoint: CMS_LABEL,
+            });
+        }
+        pushCondition("hospital_type", ht, OP_CONTAINS);
+        filtersApplied.push(`hospitalType~${ht}`);
+    }
+    // ── Coerce size / offset to bounded integers (belt-and-suspenders behind the
+    //    server Zod; a DIRECT handler call bypasses Zod). ──
+    let size = SIZE_DEFAULT;
+    if (typeof args.size === "number" && Number.isFinite(args.size)) {
+        size = Math.trunc(args.size);
+        if (size < SIZE_MIN)
+            size = SIZE_MIN;
+        if (size > SIZE_MAX)
+            size = SIZE_MAX;
+    }
+    let offset = 0;
+    if (typeof args.offset === "number" &&
+        Number.isFinite(args.offset) &&
+        args.offset > 0) {
+        offset = Math.trunc(args.offset);
+    }
+    query.set("limit", String(size));
+    query.set("offset", String(offset));
+    // ── The single request. Catch-ladder (cms-utilization shape): preserve the
+    //    4xx/5xx/timeout ToolErrorCarrier taxonomy FIRST; reclassify a 200 non-JSON
+    //    SyntaxError to schema_drift SECOND; bare-rethrow LAST. ──
+    let body;
+    try {
+        body = await getCms(query);
+    }
+    catch (e) {
+        if (e instanceof ToolErrorCarrier)
+            throw e;
+        if (e instanceof SyntaxError)
+            throw driftError(CMS_LABEL, "CMS provider-data API returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).");
+        throw e;
+    }
+    // [P4] the body MUST be an object with a numeric `count` and an array `results`
+    // (a non-array results OR a non-number count is drift, never a fabricated empty).
+    const b = (body ?? {});
+    if (typeof b.count !== "number" || !Number.isFinite(b.count) || !Array.isArray(b.results)) {
+        throw driftError(CMS_LABEL, "CMS provider-data shape drift — the response must carry a numeric `count` and an array `results` of hospital rows.");
+    }
+    const totalAvailable = b.count;
+    const hospitals = b.results.map(mapHospital);
+    const returned = hospitals.length;
+    // ── [P1] pagination. hasMore = offset+returned < total (the EXACT count). ──
+    const hasMore = offset + returned < totalAvailable;
+    const nextOffset = hasMore ? offset + returned : null;
+    const meta = {
+        source: `${CMS_HOST} CMS Hospital Compare — Hospital General Information (keyless)`,
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit: size, hasMore, nextOffset },
+        notes: [DATASET_NOTE, FILTER_NOTE, RATING_NOTE],
+    };
+    return withMeta({ hospitals }, meta);
+}
+//# sourceMappingURL=cms-hospital.js.map

package/dist/cms-hospital.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms-hospital.js","sourceRoot":"","sources":["../src/cms-hospital.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;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,mFAAmF;AACnF,8DAA8D;AAC9D,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAEpB,uEAAuE;AACvE,MAAM,QAAQ,GAAG,cAAc,CAAC;AAChC,iFAAiF;AACjF,wBAAwB;AACxB,MAAM,SAAS,GAAG,2BAA2B,CAAC;AAE9C,8EAA8E;AAC9E,6EAA6E;AAC7E,kFAAkF;AAClF,mFAAmF;AACnF,gFAAgF;AAChF,WAAW;AACX,MAAM,uBAAuB,GAAG,WAAW,CAAC;AAC5C,MAAM,iBAAiB,GAAG,wCAAwC,uBAAuB,IAAI,CAAC;AAE9F,qEAAqE;AACrE,MAAM,QAAQ,GAAG,eAAe,CAAC,CAAC,wCAAwC;AAC1E,iFAAiF;AACjF,oFAAoF;AACpF,mEAAmE;AACnE,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AACzD,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AAEzD,MAAM,QAAQ,GAAG,CAAC,CAAC;AACnB,MAAM,QAAQ,GAAG,GAAG,CAAC;AACrB,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,kFAAkF;AAClF,MAAM,SAAS,GAAG,GAAG,CAAC;AACtB,MAAM,WAAW,GAAG,UAAU,CAAC;AAE/B,qEAAqE;AACrE,MAAM,YAAY,GAChB,8GAA8G,uBAAuB,8IAA8I,CAAC;AACtR,MAAM,WAAW,GACf,4UAA4U,CAAC;AAC/U,MAAM,WAAW,GACf,6NAA6N,CAAC;AAkBhO;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACjB,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC5B,MAAM,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5B,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC/B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,gEAAgE;AAChE,SAAS,WAAW,CAAC,GAAY;IAC/B,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAA4B,CAAC;IACjD,OAAO;QACL,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC;QAC9B,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC;QAClC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QACvB,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;QACrB,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;QACnB,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;QACpB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QAC3B,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC;QAC9B,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC;QAClC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC;QACpC,iBAAiB,EAAE,aAAa,CAAC,CAAC,CAAC,kBAAkB,CAAC;QACtD,0EAA0E;QAC1E,gFAAgF;QAChF,oCAAoC;QACpC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC,uBAAuB,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF;;;;;;GAMG;AACH,KAAK,UAAU,MAAM,CAAC,KAAsB;IAC1C,MAAM,GAAG,GAAG,WAAW,QAAQ,GAAG,iBAAiB,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;IAC1E,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC/D,MAAM,IAAI,gBAAgB,CAAC;YACzB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,0CAA0C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,KAAK,CAAC,QAAQ,mCAAmC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,gDAAgD;YAC/M,SAAS,EAAE,KAAK;YAChB,gBAAgB,EAAE,SAAS;SAC5B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;AAC5E,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAA4B;IAE5B,iFAAiF;IACjF,uDAAuD;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;IAC/D,MAAM,eAAe,GACnB,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;IAC9D,IAAI,CAAC,QAAQ,IAAI,CAAC,eAAe,EAAE,CAAC;QAClC,MAAM,IAAI,gBAAgB,CAAC;YACzB,IAAI,EAAE,eAAe;YACrB,SAAS,EAAE,KAAK;YAChB,OAAO,EACL,qOAAqO;YACvO,gBAAgB,EAAE,SAAS;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAC7E,8EAA8E;IAC9E,gFAAgF;IAChF,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,MAAM,aAAa,GAAG,CAAC,QAAgB,EAAE,KAAa,EAAE,QAAgB,EAAE,EAAE;QAC1E,KAAK,CAAC,GAAG,CAAC,cAAc,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;QACnD,KAAK,CAAC,GAAG,CAAC,cAAc,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;QAC7C,KAAK,CAAC,GAAG,CAAC,cAAc,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;QACnD,EAAE,IAAI,CAAC,CAAC;IACV,CAAC,CAAC;IAEF,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAe,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,gBAAgB,CAAC;gBACzB,IAAI,EAAE,eAAe;gBACrB,SAAS,EAAE,KAAK;gBAChB,OAAO,EAAE,iBAAiB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,yEAAyE;gBACxH,gBAAgB,EAAE,SAAS;aAC5B,CAAC,CAAC;QACL,CAAC;QACD,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,EAAE,SAAS,CAAC,CAAC;QACvD,cAAc,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,eAAe,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,YAAsB,CAAC;QACzC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,gBAAgB,CAAC;gBACzB,IAAI,EAAE,eAAe;gBACrB,SAAS,EAAE,KAAK;gBAChB,OAAO,EAAE,wBAAwB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,6GAA6G;gBAClK,gBAAgB,EAAE,SAAS;aAC5B,CAAC,CAAC;QACL,CAAC;QACD,aAAa,CAAC,eAAe,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;QAClD,cAAc,CAAC,IAAI,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,KAAK,EAAE,EAAE,CAAC;QAChE,MAAM,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC;QAC7B,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,gBAAgB,CAAC;gBACzB,IAAI,EAAE,eAAe;gBACrB,SAAS,EAAE,KAAK;gBAChB,OAAO,EAAE,wBAAwB,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,2HAA2H;gBAC9K,gBAAgB,EAAE,SAAS;aAC5B,CAAC,CAAC;QACL,CAAC;QACD,aAAa,CAAC,eAAe,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QAChD,cAAc,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,8EAA8E;IAC9E,yDAAyD;IACzD,IAAI,IAAI,GAAG,YAAY,CAAC;IACxB,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAChE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,IAAI,GAAG,QAAQ;YAAE,IAAI,GAAG,QAAQ,CAAC;QACrC,IAAI,IAAI,GAAG,QAAQ;YAAE,IAAI,GAAG,QAAQ,CAAC;IACvC,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IACE,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;QAC/B,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,CAAC,EACf,CAAC;QACD,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACjC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAEpC,4EAA4E;IAC5E,gFAAgF;IAChF,+DAA+D;IAC/D,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,gBAAgB;YAAE,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,YAAY,WAAW;YAC1B,MAAM,UAAU,CACd,SAAS,EACT,4GAA4G,CAC7G,CAAC;QACJ,MAAM,CAAC,CAAC;IACV,CAAC;IAED,gFAAgF;IAChF,kFAAkF;IAClF,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAA2C,CAAC;IACjE,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1F,MAAM,UAAU,CACd,SAAS,EACT,oHAAoH,CACrH,CAAC;IACJ,CAAC;IAED,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC;IAC/B,MAAM,SAAS,GAAI,CAAC,CAAC,OAAqB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC;IAElC,8EAA8E;IAC9E,MAAM,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,cAAc,CAAC;IACnD,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtD,MAAM,IAAI,GAA0B;QAClC,MAAM,EAAE,GAAG,QAAQ,gEAAgE;QACnF,WAAW,EAAE,IAAI;QACjB,QAAQ;QACR,cAAc;QACd,cAAc;QACd,cAAc,EAAE,EAAE;QAClB,iBAAiB,EAAE,EAAE;QACrB,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE;QACxD,KAAK,EAAE,CAAC,YAAY,EAAE,WAAW,EAAE,WAAW,CAAC;KAChD,CAAC;IAEF,OAAO,QAAQ,CAAC,EAAE,SAAS,EAAE,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC"}

package/dist/cms-supplier.d.ts

@@ -0,0 +1,133 @@
+/**
+ * cms-supplier.ts — two CMS supplier/vetting lanes on `data.cms.gov` (the SAME
+ * data-API v1 dataset endpoint + the SAME two-request stats-count pattern as
+ * cms-utilization.ts / ADR-0061; ADR-0064). KEYLESS.
+ *
+ * WHAT IT ADDS
+ *   1. `cms_dmepos_suppliers` — CMS "Medicare Durable Medical Equipment,
+ *      Devices & Supplies by Supplier": for a given supplier (NPI) or state, the
+ *      DMEPOS supplier's identity + aggregate Medicare figures (HCPCS codes,
+ *      beneficiaries, claims, services, submitted / Medicare-allowed / -paid
+ *      amounts). A supplier-market / competitor-utilization lane on the SUPPLY
+ *      side (who bills Medicare for equipment).
+ *   2. `cms_revoked_providers` — CMS "Revoked Medicare Providers & Suppliers":
+ *      the legally-published debarment / revocation list (7,059 rows), with the
+ *      revoked provider's identity, provider type, revocation reason, effective
+ *      date, and re-enrollment-bar expiration. A vetting / due-diligence lane in
+ *      the SAME class as the OFAC / SAM-exclusions lists already shipped —
+ *      surfacing the names IS the point (this is a public exclusion list).
+ *
+ * ★THE TWO-REQUEST PATTERN (the load-bearing P1 honesty — MIRRORS cms-utilization):
+ *   the data-API's `/data` slice is a bare JSON array that reports NO total. So the
+ *   EXACT total for a filter comes from a SEPARATE count sub-query — the identical
+ *   `filter[...]` on the `/data-viewer/stats` endpoint returns
+ *   `{ "data": { "found_rows": N, "total_rows": M } }`. Each tool runs the stats
+ *   count FIRST (best-effort) then the data slice: totalAvailable = found_rows (P1,
+ *   the per-filter EXACT total), NEVER the returned rows' length. If the stats
+ *   sub-query fails or is absent, totalAvailable falls to null + a disclosing note
+ *   (never a length-faked total) and the data slice still returns.
+ *
+ * ★THE FILTER-REQUIRED INPUT GUARD (dmepos only): the supplier table is large; an
+ *   all-empty query (no npi, no state) is REFUSED with invalid_input (0 fetch) — a
+ *   caller MUST pin npi OR state. The revocation list is only ~7K rows, so it is
+ *   safe to page unfiltered (all its filters are optional).
+ *
+ * The module writes ZERO fetch/coercion/error/meta code — it REUSES `getJson`
+ * (redirect:"error") / `driftError` (datasource.ts), `str`/`num` (coerce.ts,
+ * null-never-empty-string / null-never-0), and `withMeta`·`buildMeta` (meta.ts).
+ * It MIRRORS cms-utilization.ts's fixed-host SSRF idiom (a single host const + a
+ * post-construction hostname/protocol assertion + redirect:"error") and its
+ * count-first two-request pattern + schema_drift catch-ladder.
+ *
+ * ★ SSRF: the host is a compile-time literal (`CMS_HOST`); the dataset UUIDs + the
+ *   endpoint paths are MODULE literals. Every USER filter value rides as a
+ *   URLSearchParams VALUE (`filter[Col]=Val`) — URLSearchParams encodes the bracket
+ *   key AND the value, so a value can never break out into the path or inject a
+ *   parameter. npi is `^\d{10}$`; state `^[A-Za-z]{2}$`; lastName is a bounded
+ *   free-text charclass; size/offset are coerced to integers. A post-construction
+ *   hostname/protocol assertion + `redirect:"error"` fail closed on any off-host 3xx.
+ *
+ * ★ HONESTY (ADR-0064 P1–P5, live-verified 2026-07-15 on data.cms.gov):
+ *   [P1] totalAvailable = the stats sub-query's found_rows (EXACT), NOT the slice
+ *        length. hasMore = offset+returned < total. Stats fails/absent ⇒
+ *        totalAvailable:null + a disclosing note (never length-faked).
+ *   [P2] empty array ⇒ honest empty (returned:0). dmepos all-empty input ⇒
+ *        invalid_input (0 fetch). getJson maps a 4xx (⇒ invalid_input / not_found)
+ *        / 5xx (⇒ upstream_unavailable) and THROWS; a 200 non-array/non-JSON body ⇒
+ *        schema_drift (NEVER a fabricated empty).
+ *   [P3] aggregates via num() (numeric strings → numbers; a real 0 stays 0; absent
+ *        ⇒ null, never 0-faked); NPI / codes / reasons / dates as strings
+ *        (null-never-empty-string); a coalesced name ⇒ null if none.
+ *   [P4] a data body that is not an array ⇒ driftError; a stats body missing
+ *        found_rows ⇒ totalAvailable:null (handled, not a crash).
+ */
+import { str, num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num, str };
+/**
+ * Join the CMS Last_Name_Org + First_Name into one display name. An ORGANIZATION
+ * supplier (entity code "O") carries the org name in Last_Name_Org with an empty
+ * First_Name ⇒ just the org name. An INDIVIDUAL carries both ⇒ "Last, First".
+ * Either absent ⇒ the present one; both absent ⇒ null (never a fabricated "").
+ */
+export declare function joinSupplierName(lastOrg: unknown, first: unknown): string | null;
+export type DmeposSupplier = {
+    npi: string | null;
+    supplierName: string | null;
+    credentials: string | null;
+    entityType: string | null;
+    city: string | null;
+    state: string | null;
+    zip: string | null;
+    totalHcpcsCodes: number | null;
+    totalBeneficiaries: number | null;
+    totalClaims: number | null;
+    totalServices: number | null;
+    submittedCharges: number | null;
+    medicareAllowed: number | null;
+    medicarePayment: number | null;
+};
+export type CmsDmeposSuppliersArgs = {
+    npi?: string;
+    state?: string;
+    size?: number;
+    offset?: number;
+};
+/**
+ * Fetch DMEPOS supplier rows for an NPI / state → normalized supplier rows +
+ * honest `_meta`. REQUIRES npi OR state (an all-empty query is refused). Runs a
+ * stats count sub-query FIRST for the EXACT total (P1), then the data slice; a count
+ * failure degrades to totalAvailable:null + a note (never a length-faked total).
+ */
+export declare function dmeposSuppliers(args: CmsDmeposSuppliersArgs): Promise<MetaBundle>;
+/**
+ * Coalesce the revoked-provider display name: an ORGANIZATION carries ORG_NAME ⇒
+ * use it. An INDIVIDUAL carries FIRST_NAME + LAST_NAME ⇒ "First Last" (either
+ * present alone ⇒ that one). None present ⇒ null (never a fabricated "").
+ */
+export declare function coalesceRevokedName(org: unknown, first: unknown, last: unknown): string | null;
+export type RevokedProvider = {
+    enrollmentId: string | null;
+    npi: string | null;
+    name: string | null;
+    state: string | null;
+    providerType: string | null;
+    revocationReason: string | null;
+    revocationEffectiveDate: string | null;
+    reenrollmentBarExpiration: string | null;
+};
+export type CmsRevokedProvidersArgs = {
+    npi?: string;
+    state?: string;
+    lastName?: string;
+    size?: number;
+    offset?: number;
+};
+/**
+ * Fetch CMS revocation-list rows (all filters optional — the ~7K-row list is safe
+ * to page unfiltered) → normalized revocation rows + honest `_meta`. Runs a stats
+ * count sub-query FIRST for the EXACT total (P1), then the data slice; a count
+ * failure degrades to totalAvailable:null + a note (never a length-faked total).
+ */
+export declare function revokedProviders(args: CmsRevokedProvidersArgs): Promise<MetaBundle>;
+//# sourceMappingURL=cms-supplier.d.ts.map

package/dist/cms-supplier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms-supplier.d.ts","sourceRoot":"","sources":["../src/cms-supplier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAIH,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAIzE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AA8JpB;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKhF;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AA0BF,MAAM,MAAM,sBAAsB,GAAG;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,UAAU,CAAC,CAiFrB;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,OAAO,GACZ,MAAM,GAAG,IAAI,CAOf;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C,CAAC;AAiBF,MAAM,MAAM,uBAAuB,GAAG;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAiFrB"}