@cliwant/mcp-sam-gov 1.2.0 → 1.4.0

package/dist/cms-facility.js

@@ -0,0 +1,311 @@
+/**
+ * cms-facility.ts — CMS "facility directory" across FOUR provider-data datasets
+ * (`data.cms.gov`, the provider-data DKAN datastore-query API; ADR-0063). KEYLESS.
+ *
+ * WHAT IT ADDS: `cms_facility_directory` — a healthcare-facility directory / market
+ * lane that generalizes cms_hospital_compare (ADR-0062) BEYOND hospitals: a caller
+ * picks a `facilityType` (nursing_home | home_health | hospice | dialysis) and the
+ * tool routes to the RIGHT CMS provider-data dataset, returning each facility's
+ * name / address / city / state / zip / ownership. The facility-level complement to
+ * the utilization and hospital lanes — WHERE these Medicare-certified facilities are.
+ *
+ * ★THE facilityType → DATASET-ID CONSTANT MAP (the load-bearing SSRF guard): the
+ *   USER value never enters the URL path. `facilityType` is a Zod ENUM; it indexes a
+ *   MODULE-CONSTANT map to a VETTED dataset id (e.g. nursing_home → "4pq5-n9py") that
+ *   is spliced into the path. An unknown facilityType is blocked by the enum
+ *   (invalid_input) BEFORE any fetch — only one of four compile-time ids can ever
+ *   reach the path.
+ *
+ * ★THE ONE-REQUEST COUNT PATTERN (P1 honesty, inherited from cms-hospital): 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` (nursing_home ⇒ 14695), NEVER `results.length`.
+ *
+ * ★FIELD-NAME VARIANCE ACROSS DATASETS (the one genuinely-new complexity vs.
+ *   cms-hospital) — live-verified 2026-07-15. The facility NAME, ADDRESS, and
+ *   OWNERSHIP columns are NAMED DIFFERENTLY per dataset, so each is COALESCED over a
+ *   fixed candidate order (null if none present — NEVER an empty string, NEVER
+ *   fabricated):
+ *     name      : provider_name → facility_name → legal_business_name
+ *     address   : address → provider_address → address_line_1
+ *     ownership : ownership_type → type_of_ownership → profit_or_nonprofit
+ *   (city = citytown, state = state, zip = zip_code are uniform across all four.)
+ *   Per-dataset verified columns:
+ *     nursing_home 4pq5-n9py: provider_name / provider_address / ownership_type
+ *     home_health  6jpm-sxkc: provider_name / address          / type_of_ownership
+ *     hospice      yc9t-dgbk: facility_name / address_line_1    / ownership_type
+ *     dialysis     23ew-n7w9: facility_name / address_line_1    / profit_or_nonprofit
+ *   ★ADR-0063 said nursing_home's address is `address`; it is actually
+ *    `provider_address` (probed live) — the coalescing candidate list covers it.
+ *
+ * ★THE facilityName FILTER COLUMN also varies: the `contains` filter targets the
+ *   dataset's OWN primary-name column (provider_name for nursing_home/home_health,
+ *   facility_name for hospice/dialysis) — stored per-type in the constant map.
+ *
+ * The module writes ZERO fetch/coercion/error/meta code — it REUSES `getJson`
+ * (redirect:"error") / `driftError` (datasource.ts), `str` (coerce.ts,
+ * null-never-empty-string), and `withMeta`·`buildMeta` (meta.ts, offset pagination
+ * + totalAvailable). It MIRRORS cms-hospital.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 → 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: 383, results: [ { provider_name, provider_address, … }, … ], schema, query }
+ *
+ * ★ SSRF: the host is a compile-time literal (`CMS_HOST`); the dataset id is chosen
+ *   by a Zod-enum key from a MODULE-CONSTANT map (never the user string). Every USER
+ *   filter VALUE rides as a URLSearchParams VALUE (`conditions[i][value]=…`) — the
+ *   bracket key AND the value are encoded, so a value can never break out of the
+ *   path or inject a parameter. state is `^[A-Za-z]{2}$`; facilityName 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-0063 P1–P5, live-verified 2026-07-15 on data.cms.gov):
+ *   [P1] totalAvailable = the response's top-level `count` (EXACT per-filter total),
+ *        NOT the slice length. hasMore = offset+returned < count.
+ *   [P2] results:[] ⇒ honest empty (returned:0). An invalid facilityType is blocked
+ *        by the Zod enum (invalid_input). getJson maps a 4xx/5xx via
+ *        errorFromResponse and THROWS (503 ⇒ upstream_unavailable, 400 ⇒
+ *        invalid_input, 404 ⇒ not_found); a 200 non-JSON body OR a body missing
+ *        `count`/`results` ⇒ schema_drift (NEVER a fabricated empty).
+ *   [P3] name/address/ownership are COALESCED over the candidate order — null if none
+ *        (NEVER an empty string, NEVER fabricated). String fields via str().
+ *   [P4] results non-array OR count non-number ⇒ driftError.
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { str } from "./coerce.js";
+import { withMeta } from "./meta.js";
+// Re-export the shared honesty coercion (single audited copy in ./coerce.js) so a
+// regression fails together across sources. NO local str.
+export { str };
+// ─── SSRF core: the single fixed host + module-literal endpoint prefix ──
+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-facility:data.cms.gov";
+const CMS_PATH_PREFIX = "/provider-data/api/1/datastore/query";
+const CMS_PATH_SUFFIX = "/0";
+const FACILITY_DATASETS = {
+    nursing_home: {
+        id: "4pq5-n9py",
+        nameColumn: "provider_name",
+        label: 'CMS "Provider Information" (Nursing Home / Long-Term Care; ~14,695 Medicare/Medicaid-certified nursing homes)',
+    },
+    home_health: {
+        id: "6jpm-sxkc",
+        nameColumn: "provider_name",
+        label: 'CMS "Home Health Care Agencies" (~12,460 Medicare-certified home health agencies)',
+    },
+    hospice: {
+        id: "yc9t-dgbk",
+        nameColumn: "facility_name",
+        label: 'CMS "Hospice Provider Information" (~6,852 Medicare-certified hospices)',
+    },
+    dialysis: {
+        id: "23ew-n7w9",
+        nameColumn: "facility_name",
+        label: 'CMS "Dialysis Facility" (~7,490 Medicare-certified dialysis facilities)',
+    },
+};
+// The valid enum keys — a belt-and-suspenders re-guard behind the server Zod (a
+// DIRECT handler call bypasses Zod). An unknown key ⇒ invalid_input, 0 fetch.
+const FACILITY_TYPES = Object.keys(FACILITY_DATASETS);
+// ─── Coalescing candidate orders (the field-name variance across datasets) ──
+// Each output field probes these source columns IN ORDER; the first non-null (via
+// str(), which nulls ""/whitespace/"null") wins; null if NONE present. NEVER an
+// empty string, NEVER a fabricated value.
+const NAME_FIELDS = ["provider_name", "facility_name", "legal_business_name"];
+const ADDRESS_FIELDS = ["address", "provider_address", "address_line_1"];
+const OWNERSHIP_FIELDS = ["ownership_type", "type_of_ownership", "profit_or_nonprofit"];
+// ─── Validation charclasses (SSRF + "verify the input" honesty) ───
+const STATE_RE = /^[A-Za-z]{2}$/; // 2-letter state/territory abbreviation
+// facilityName rides as a URLSearchParams VALUE (encoded), so this bound is 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 SIZE_MIN = 1;
+const SIZE_MAX = 100;
+const SIZE_DEFAULT = 25;
+// DKAN condition operators (live-verified). state = exact; name = substring.
+const OP_EQUALS = "=";
+const OP_CONTAINS = "contains";
+// ─── Honesty notes (ADR-0063 required set) ────────────────────────
+const COALESCE_NOTE = "Field names vary across the four CMS provider-data datasets — `name`, `address`, and `ownership` are COALESCED over per-dataset candidate columns (name: provider_name/facility_name/legal_business_name; address: address/provider_address/address_line_1; ownership: ownership_type/type_of_ownership/profit_or_nonprofit). A field absent in the chosen dataset is null (unknown), NEVER an empty string and NEVER fabricated.";
+const FILTER_NOTE = "Filters are applied SERVER-SIDE via DKAN conditions (AND-combined): `state` is an EXACT match; `facilityName` is a case-insensitive SUBSTRING (contains) match against the dataset's primary-name column — so a facilityName fragment may match several facilities. totalAvailable is the upstream's EXACT count for this filter set, not the returned-row count.";
+/**
+ * Coalesce a row's value over a candidate column order → string | null.
+ * Returns the FIRST column whose str() is non-null (str nulls ""/whitespace/"null");
+ * null if NONE — NEVER an empty string, NEVER a fabricated value (P3).
+ */
+export function coalesceField(row, fields) {
+    for (const f of fields) {
+        const v = str(row[f]);
+        if (v !== null)
+            return v;
+    }
+    return null;
+}
+/** Map ONE datastore-query row → the curated facility shape for `facilityType`. */
+function mapFacility(row, facilityType) {
+    const r = (row ?? {});
+    return {
+        // [P3] name/address/ownership coalesced over candidate columns; null-never-empty.
+        name: coalesceField(r, NAME_FIELDS),
+        address: coalesceField(r, ADDRESS_FIELDS),
+        city: str(r.citytown),
+        state: str(r.state),
+        zip: str(r.zip_code),
+        // Echo the input facilityType (the caller's chosen lane).
+        facilityType,
+        ownership: coalesceField(r, OWNERSHIP_FIELDS),
+    };
+}
+// ─── 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 is a VETTED value from FACILITY_DATASETS (never the user string); the endpoint
+ * path is built from module 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(datasetId, query) {
+    const path = `${CMS_PATH_PREFIX}/${datasetId}${CMS_PATH_SUFFIX}`;
+    const url = `https://${CMS_HOST}${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 provider-data facility rows for a `facilityType` (+ optional state /
+ * facility-name fragment) → normalized facility rows + honest `_meta`. The
+ * facilityType (a Zod enum) indexes the FACILITY_DATASETS constant map to a vetted
+ * dataset id — the user value never enters the path. A SINGLE request: the response's
+ * top-level `count` is the EXACT per-filter total (P1 — never the slice length).
+ */
+export async function facilityDirectory(args) {
+    // ── [SSRF/input] resolve facilityType → the vetted dataset (belt-and-suspenders
+    //    behind the server Zod enum; a DIRECT handler call bypasses Zod). An unknown/
+    //    absent facilityType ⇒ invalid_input, 0 fetch. ──
+    const ft = args.facilityType;
+    if (ft === undefined || !Object.prototype.hasOwnProperty.call(FACILITY_DATASETS, ft)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid or missing facilityType ${JSON.stringify(ft)} — expected one of: ${FACILITY_TYPES.join(", ")}.`,
+            upstreamEndpoint: CMS_LABEL,
+        });
+    }
+    const facilityType = ft;
+    const dataset = FACILITY_DATASETS[facilityType];
+    // ── 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 = [`facilityType:${facilityType}`];
+    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 (args.state !== undefined && args.state !== "") {
+        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 (args.facilityName !== undefined && args.facilityName !== "") {
+        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,
+            });
+        }
+        // The name column varies per dataset (provider_name vs facility_name).
+        pushCondition(dataset.nameColumn, name, OP_CONTAINS);
+        filtersApplied.push(`facilityName~${name}`);
+    }
+    // ── 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-hospital 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(dataset.id, 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 facility rows.");
+    }
+    const totalAvailable = b.count;
+    const facilities = b.results.map((row) => mapFacility(row, facilityType));
+    const returned = facilities.length;
+    // ── [P1] pagination. hasMore = offset+returned < total (the EXACT count). ──
+    const hasMore = offset + returned < totalAvailable;
+    const nextOffset = hasMore ? offset + returned : null;
+    const DATASET_NOTE = `Source dataset: ${dataset.label} — data.cms.gov provider-data datastore "${dataset.id}". A CMS-published snapshot, not a live/real-time feed. Update the dataset id if CMS re-publishes it.`;
+    const meta = {
+        source: `${CMS_HOST} CMS provider-data facility directory — ${facilityType} (keyless)`,
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit: size, hasMore, nextOffset },
+        notes: [DATASET_NOTE, COALESCE_NOTE, FILTER_NOTE],
+    };
+    return withMeta({ facilities }, meta);
+}
+//# sourceMappingURL=cms-facility.js.map

package/dist/cms-facility.js.map

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

package/dist/cms-hospital.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 { str, num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num, str };
+export type Hospital = {
+    facilityId: string | null;
+    facilityName: string | null;
+    address: string | null;
+    city: string | null;
+    state: string | null;
+    zip: string | null;
+    county: string | null;
+    phone: string | null;
+    hospitalType: string | null;
+    ownership: string | null;
+    emergencyServices: boolean | null;
+    overallRating: number | null;
+};
+/**
+ * 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 declare function emergencyBool(x: unknown): boolean | null;
+export type CmsHospitalCompareArgs = {
+    state?: string;
+    facilityName?: string;
+    hospitalType?: string;
+    size?: number;
+    offset?: number;
+};
+/**
+ * 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 declare function hospitalCompare(args: CmsHospitalCompareArgs): Promise<MetaBundle>;
+//# sourceMappingURL=cms-hospital.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cms-hospital.d.ts","sourceRoot":"","sources":["../src/cms-hospital.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;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;AA0CpB,MAAM,MAAM,QAAQ,GAAG;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,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,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAOxD;AA8CD,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,UAAU,CAAC,CAyIrB"}