@cliwant/mcp-sam-gov 1.2.0 → 1.4.0

package/dist/cms-supplier.js

@@ -0,0 +1,414 @@
+/**
+ * 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 { 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-supplier:data.cms.gov";
+// ★THE DATASET UUIDs — SPECIFIC ANNUAL VINTAGES on data.cms.gov (live-verified,
+// keyless). ★UPDATE YEARLY for the DMEPOS set (CMS publishes a new uuid per
+// calendar year of supplier data); the revocation list is a rolling published
+// register. Each vintage is surfaced to the caller in a _meta note so a consumer
+// never mistakes it for "current" or an unspecified year.
+const DMEPOS_DATASET_UUID = "a2d56d3f-3531-4315-9d87-e29986516b41"; // DMEPOS by Supplier (annual vintage)
+const REVOKED_DATASET_UUID = "a6496a7d-4e19-479a-a9ad-d4c0a49e07c3"; // Revoked Medicare Providers & Suppliers (~7,059 rows)
+// ─── Validation charclasses (SSRF + "verify the input" honesty) ───
+const NPI_RE = /^\d{10}$/; // a 10-digit National Provider Identifier
+const STATE_RE = /^[A-Za-z]{2}$/; // 2-letter state/territory abbreviation
+// lastName rides as a URLSearchParams VALUE (encoded), so this bound is a sanity
+// guard, not an SSRF necessity: letters/digits/space and common name punctuation.
+const LAST_NAME_RE = /^[A-Za-z0-9 .,'-]{1,100}$/;
+const SIZE_MIN = 1;
+const SIZE_MAX = 100;
+const SIZE_DEFAULT = 25;
+// ─── Honesty notes (ADR-0064 required set) ────────────────────────
+const DMEPOS_VINTAGE_NOTE = `Source dataset: CMS "Medicare Durable Medical Equipment, Devices & Supplies — by Supplier" (data.cms.gov dataset ${DMEPOS_DATASET_UUID}) — a SPECIFIC ANNUAL VINTAGE (the most recent published year at build time), NOT a live/current or a multi-year figure. Amounts and counts are as-of that reference year. CMS publishes a new dataset id each year.`;
+const DMEPOS_AGGREGATE_NOTE = "These are public SUPPLIER-level AGGREGATE Medicare DMEPOS figures (no patient identifiers). totalBeneficiaries is CMS-rounded and suppressed below 11 in the source. This is a utilization snapshot, NOT a fraud, quality, or fitness determination.";
+const REVOKED_LIST_NOTE = `Source: CMS's PUBLIC "Revoked Medicare Providers & Suppliers" list (data.cms.gov dataset ${REVOKED_DATASET_UUID}) — a legally-published revocation/exclusion register (the same vetting class as the OFAC / SAM exclusion lists). A listing reflects a past Medicare enrollment revocation with its stated reason; it is a due-diligence signal, NOT a current-eligibility, guilt, or fitness determination. Verify against the primary source before acting.`;
+const COUNT_FALLBACK_NOTE = "The count sub-query (…/data-viewer/stats) failed or did not report found_rows, so totalAvailable is null (unknown) — it was NOT faked from the returned row count. hasMore is a heuristic (a full page ⇒ likely more); re-page with offset to confirm.";
+// ─── SSRF-guarded fetch (fixed host + hostname assertion + redirect:"error") ──
+/**
+ * GET one data.cms.gov JSON resource at a MODULE-BUILT URL (the dataset UUID + 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(path, query) {
+    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 data-API 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" });
+}
+/**
+ * The shared two-request slice: run the stats count sub-query FIRST (best-effort —
+ * the EXACT total, P1), then the authoritative data slice. A count failure degrades
+ * to totalAvailable:null + countFailed (never throws, never length-fakes). The data
+ * slice preserves the 4xx/5xx/timeout ToolErrorCarrier taxonomy, reclassifies a 200
+ * non-JSON SyntaxError to schema_drift, and asserts the body is an array (P4).
+ */
+async function fetchDatasetSlice(uuid, filters, size, offset) {
+    const dataBase = `/data-api/v1/dataset/${uuid}/data`;
+    const statsPath = `/data-api/v1/dataset/${uuid}/data-viewer/stats`;
+    // ── (1) The COUNT sub-query FIRST. Body is `{ data: { found_rows, total_rows } }`.
+    //    Any failure (network/5xx/drift/missing field) degrades to totalAvailable:null
+    //    + a note; it NEVER throws and NEVER fakes the total from the slice length. ──
+    let totalAvailable = null;
+    let countFailed = false;
+    try {
+        const statsBody = await getCms(statsPath, filters);
+        const dataObj = statsBody !== null &&
+            typeof statsBody === "object" &&
+            typeof statsBody.data === "object" &&
+            statsBody.data !== null
+            ? statsBody.data
+            : undefined;
+        if (dataObj !== undefined) {
+            const t = num(dataObj.found_rows);
+            if (t !== null && t >= 0) {
+                totalAvailable = t;
+            }
+            else {
+                countFailed = true; // present body but no usable found_rows (P4)
+            }
+        }
+        else {
+            countFailed = true; // stats body not the expected { data: {…} } shape
+        }
+    }
+    catch {
+        countFailed = true; // any count error ⇒ degrade, never propagate (P1)
+    }
+    // ── (2) The DATA slice — the authoritative request (a bare JSON array). ──
+    const dataQuery = new URLSearchParams(filters);
+    dataQuery.set("size", String(size));
+    dataQuery.set("offset", String(offset));
+    // 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(dataBase, dataQuery);
+    }
+    catch (e) {
+        if (e instanceof ToolErrorCarrier)
+            throw e;
+        if (e instanceof SyntaxError)
+            throw driftError(CMS_LABEL, "CMS data-API returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).");
+        throw e;
+    }
+    // [P4] the data body MUST be an array (a non-array 200 is drift, never a
+    // fabricated empty).
+    if (!Array.isArray(body)) {
+        throw driftError(CMS_LABEL, "CMS data-API shape drift — the /data response must be a JSON array of rows.");
+    }
+    return { rows: body, totalAvailable, countFailed };
+}
+/** Coerce args.size / args.offset to bounded integers (belt-and-suspenders behind
+ *  the server Zod; a DIRECT handler call bypasses Zod). */
+function boundSize(raw) {
+    let size = SIZE_DEFAULT;
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        size = Math.trunc(raw);
+        if (size < SIZE_MIN)
+            size = SIZE_MIN;
+        if (size > SIZE_MAX)
+            size = SIZE_MAX;
+    }
+    return size;
+}
+function boundOffset(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
+        return Math.trunc(raw);
+    }
+    return 0;
+}
+// ══════════════════════════════════════════════════════════════════
+// (1) cms_dmepos_suppliers
+// ══════════════════════════════════════════════════════════════════
+/**
+ * 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 function joinSupplierName(lastOrg, first) {
+    const last = str(lastOrg);
+    const firstName = str(first);
+    if (last !== null && firstName !== null)
+        return `${last}, ${firstName}`;
+    return last ?? firstName ?? null;
+}
+/** Map ONE DMEPOS data-API row → the curated supplier shape. */
+function mapSupplier(row) {
+    const r = (row ?? {});
+    return {
+        npi: str(r.Suplr_NPI),
+        supplierName: joinSupplierName(r.Suplr_Prvdr_Last_Name_Org, r.Suplr_Prvdr_First_Name),
+        credentials: str(r.Suplr_Prvdr_Crdntls),
+        entityType: str(r.Suplr_Prvdr_Ent_Cd),
+        city: str(r.Suplr_Prvdr_City),
+        state: str(r.Suplr_Prvdr_State_Abrvtn),
+        zip: str(r.Suplr_Prvdr_Zip5),
+        totalHcpcsCodes: num(r.Tot_Suplr_HCPCS_Cds),
+        totalBeneficiaries: num(r.Tot_Suplr_Benes),
+        totalClaims: num(r.Tot_Suplr_Clms),
+        totalServices: num(r.Tot_Suplr_Srvcs),
+        submittedCharges: num(r.Suplr_Sbmtd_Chrgs),
+        medicareAllowed: num(r.Suplr_Mdcr_Alowd_Amt),
+        medicarePayment: num(r.Suplr_Mdcr_Pymt_Amt),
+    };
+}
+/**
+ * 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 async function dmeposSuppliers(args) {
+    // ── [input guard] require npi OR state (never scan the whole supplier table). ──
+    const hasNpi = args.npi !== undefined && args.npi !== "";
+    const hasState = args.state !== undefined && args.state !== "";
+    if (!hasNpi && !hasState) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: "cms_dmepos_suppliers requires at least `npi` (10-digit) OR `state` (2-letter) — an all-empty query would scan the entire DMEPOS supplier table and is refused. Add npi or state and retry.",
+            upstreamEndpoint: CMS_LABEL,
+        });
+    }
+    // ── Validate + build the filter params (SSRF: charclass + URLSearchParams value). ──
+    const filters = new URLSearchParams();
+    const filtersApplied = [];
+    if (hasNpi) {
+        const npi = args.npi;
+        if (!NPI_RE.test(npi)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid npi ${JSON.stringify(npi)} — expected a 10-digit National Provider Identifier (^\\d{10}$).`,
+                upstreamEndpoint: CMS_LABEL,
+            });
+        }
+        filters.set("filter[Suplr_NPI]", npi);
+        filtersApplied.push(`npi:${npi}`);
+    }
+    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,
+            });
+        }
+        filters.set("filter[Suplr_Prvdr_State_Abrvtn]", state.toUpperCase());
+        filtersApplied.push(`state:${state.toUpperCase()}`);
+    }
+    const size = boundSize(args.size);
+    const offset = boundOffset(args.offset);
+    const { rows, totalAvailable, countFailed } = await fetchDatasetSlice(DMEPOS_DATASET_UUID, filters, size, offset);
+    const suppliers = rows.map(mapSupplier);
+    const returned = suppliers.length;
+    const hasMore = totalAvailable !== null
+        ? offset + returned < totalAvailable
+        : returned === size;
+    const nextOffset = hasMore ? offset + returned : null;
+    const notes = [DMEPOS_VINTAGE_NOTE, DMEPOS_AGGREGATE_NOTE];
+    if (countFailed)
+        notes.push(COUNT_FALLBACK_NOTE);
+    const meta = {
+        source: `${CMS_HOST} CMS Medicare DMEPOS — by Supplier (keyless)`,
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit: size, hasMore, nextOffset },
+        notes,
+    };
+    return withMeta({ suppliers }, meta);
+}
+// ══════════════════════════════════════════════════════════════════
+// (2) cms_revoked_providers
+// ══════════════════════════════════════════════════════════════════
+/**
+ * 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 function coalesceRevokedName(org, first, last) {
+    const o = str(org);
+    if (o !== null)
+        return o;
+    const f = str(first);
+    const l = str(last);
+    if (f !== null && l !== null)
+        return `${f} ${l}`;
+    return f ?? l ?? null;
+}
+/** Map ONE revocation data-API row → the curated revocation shape. */
+function mapRevocation(row) {
+    const r = (row ?? {});
+    return {
+        enrollmentId: str(r.ENRLMT_ID),
+        npi: str(r.NPI),
+        name: coalesceRevokedName(r.ORG_NAME, r.FIRST_NAME, r.LAST_NAME),
+        state: str(r.STATE_CD),
+        providerType: str(r.PROVIDER_TYPE_DESC),
+        revocationReason: str(r.REVOCATION_RSN),
+        revocationEffectiveDate: str(r.REVOCATION_EFCTV_DT),
+        reenrollmentBarExpiration: str(r.REENROLLMENT_BAR_EXPRTN_DT),
+    };
+}
+/**
+ * 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 async function revokedProviders(args) {
+    const filters = new URLSearchParams();
+    const filtersApplied = [];
+    if (args.npi !== undefined && args.npi !== "") {
+        const npi = args.npi;
+        if (!NPI_RE.test(npi)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid npi ${JSON.stringify(npi)} — expected a 10-digit National Provider Identifier (^\\d{10}$).`,
+                upstreamEndpoint: CMS_LABEL,
+            });
+        }
+        filters.set("filter[NPI]", npi);
+        filtersApplied.push(`npi:${npi}`);
+    }
+    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,
+            });
+        }
+        filters.set("filter[STATE_CD]", state.toUpperCase());
+        filtersApplied.push(`state:${state.toUpperCase()}`);
+    }
+    if (args.lastName !== undefined && args.lastName !== "") {
+        const lastName = args.lastName;
+        if (!LAST_NAME_RE.test(lastName)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid lastName ${JSON.stringify(lastName)} — allowed: letters, digits, space, . , ' - (≤100 chars).`,
+                upstreamEndpoint: CMS_LABEL,
+            });
+        }
+        filters.set("filter[LAST_NAME]", lastName);
+        filtersApplied.push(`lastName:${lastName}`);
+    }
+    const size = boundSize(args.size);
+    const offset = boundOffset(args.offset);
+    const { rows, totalAvailable, countFailed } = await fetchDatasetSlice(REVOKED_DATASET_UUID, filters, size, offset);
+    const revocations = rows.map(mapRevocation);
+    const returned = revocations.length;
+    const hasMore = totalAvailable !== null
+        ? offset + returned < totalAvailable
+        : returned === size;
+    const nextOffset = hasMore ? offset + returned : null;
+    const notes = [REVOKED_LIST_NOTE];
+    if (countFailed)
+        notes.push(COUNT_FALLBACK_NOTE);
+    const meta = {
+        source: `${CMS_HOST} CMS Revoked Medicare Providers & Suppliers (public revocation list, keyless)`,
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit: size, hasMore, nextOffset },
+        notes,
+    };
+    return withMeta({ revocations }, meta);
+}
+//# sourceMappingURL=cms-supplier.js.map

package/dist/cms-supplier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms-supplier.js","sourceRoot":"","sources":["../src/cms-supplier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;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,gFAAgF;AAChF,4EAA4E;AAC5E,8EAA8E;AAC9E,iFAAiF;AACjF,0DAA0D;AAC1D,MAAM,mBAAmB,GAAG,sCAAsC,CAAC,CAAC,sCAAsC;AAC1G,MAAM,oBAAoB,GAAG,sCAAsC,CAAC,CAAC,uDAAuD;AAE5H,qEAAqE;AACrE,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,0CAA0C;AACrE,MAAM,QAAQ,GAAG,eAAe,CAAC,CAAC,wCAAwC;AAC1E,iFAAiF;AACjF,kFAAkF;AAClF,MAAM,YAAY,GAAG,2BAA2B,CAAC;AAEjD,MAAM,QAAQ,GAAG,CAAC,CAAC;AACnB,MAAM,QAAQ,GAAG,GAAG,CAAC;AACrB,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,qEAAqE;AACrE,MAAM,mBAAmB,GACvB,oHAAoH,mBAAmB,sNAAsN,CAAC;AAChW,MAAM,qBAAqB,GACzB,sPAAsP,CAAC;AACzP,MAAM,iBAAiB,GACrB,4FAA4F,oBAAoB,+UAA+U,CAAC;AAClc,MAAM,mBAAmB,GACvB,wPAAwP,CAAC;AAE3P,iFAAiF;AACjF;;;;;;GAMG;AACH,KAAK,UAAU,MAAM,CAAC,IAAY,EAAE,KAAsB;IACxD,MAAM,GAAG,GAAG,WAAW,QAAQ,GAAG,IAAI,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;IAC7D,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,qCAAqC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,KAAK,CAAC,QAAQ,mCAAmC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,gDAAgD;YAC1M,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;AAED;;;;;;GAMG;AACH,KAAK,UAAU,iBAAiB,CAC9B,IAAY,EACZ,OAAwB,EACxB,IAAY,EACZ,MAAc;IAEd,MAAM,QAAQ,GAAG,wBAAwB,IAAI,OAAO,CAAC;IACrD,MAAM,SAAS,GAAG,wBAAwB,IAAI,oBAAoB,CAAC;IAEnE,oFAAoF;IACpF,mFAAmF;IACnF,mFAAmF;IACnF,IAAI,cAAc,GAAkB,IAAI,CAAC;IACzC,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,OAAO,GACX,SAAS,KAAK,IAAI;YAClB,OAAO,SAAS,KAAK,QAAQ;YAC7B,OAAQ,SAAqC,CAAC,IAAI,KAAK,QAAQ;YAC9D,SAAqC,CAAC,IAAI,KAAK,IAAI;YAClD,CAAC,CAAG,SAAqC,CAAC,IAAgC;YAC1E,CAAC,CAAC,SAAS,CAAC;QAChB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;YAClC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,cAAc,GAAG,CAAC,CAAC;YACrB,CAAC;iBAAM,CAAC;gBACN,WAAW,GAAG,IAAI,CAAC,CAAC,6CAA6C;YACnE,CAAC;QACH,CAAC;aAAM,CAAC;YACN,WAAW,GAAG,IAAI,CAAC,CAAC,kDAAkD;QACxE,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,WAAW,GAAG,IAAI,CAAC,CAAC,kDAAkD;IACxE,CAAC;IAED,4EAA4E;IAC5E,MAAM,SAAS,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC;IAC/C,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACpC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAExC,qEAAqE;IACrE,4EAA4E;IAC5E,0CAA0C;IAC1C,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC3C,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,mGAAmG,CACpG,CAAC;QACJ,MAAM,CAAC,CAAC;IACV,CAAC;IAED,yEAAyE;IACzE,qBAAqB;IACrB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,UAAU,CACd,SAAS,EACT,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC;AAClE,CAAC;AAED;2DAC2D;AAC3D,SAAS,SAAS,CAAC,GAAY;IAC7B,IAAI,IAAI,GAAG,YAAY,CAAC;IACxB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACpD,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,IAAI,GAAG,QAAQ;YAAE,IAAI,GAAG,QAAQ,CAAC;QACrC,IAAI,IAAI,GAAG,QAAQ;YAAE,IAAI,GAAG,QAAQ,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AACD,SAAS,WAAW,CAAC,GAAY;IAC/B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QAC/D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,qEAAqE;AACrE,2BAA2B;AAC3B,qEAAqE;AAErE;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,KAAc;IAC/D,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1B,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,IAAI,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,GAAG,IAAI,KAAK,SAAS,EAAE,CAAC;IACxE,OAAO,IAAI,IAAI,SAAS,IAAI,IAAI,CAAC;AACnC,CAAC;AAmBD,gEAAgE;AAChE,SAAS,WAAW,CAAC,GAAY;IAC/B,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAA4B,CAAC;IACjD,OAAO;QACL,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACrB,YAAY,EAAE,gBAAgB,CAC5B,CAAC,CAAC,yBAAyB,EAC3B,CAAC,CAAC,sBAAsB,CACzB;QACD,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC;QACvC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC;QACrC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC;QAC7B,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,wBAAwB,CAAC;QACtC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC;QAC5B,eAAe,EAAE,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC;QAC3C,kBAAkB,EAAE,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC;QAC1C,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC;QAClC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC;QACrC,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC;QAC1C,eAAe,EAAE,GAAG,CAAC,CAAC,CAAC,oBAAoB,CAAC;QAC5C,eAAe,EAAE,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC;KAC5C,CAAC;AACJ,CAAC;AASD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAA4B;IAE5B,kFAAkF;IAClF,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC;IACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;IAC/D,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACzB,MAAM,IAAI,gBAAgB,CAAC;YACzB,IAAI,EAAE,eAAe;YACrB,SAAS,EAAE,KAAK;YAChB,OAAO,EACL,4LAA4L;YAC9L,gBAAgB,EAAE,SAAS;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,sFAAsF;IACtF,MAAM,OAAO,GAAG,IAAI,eAAe,EAAE,CAAC;IACtC,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,GAAa,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,gBAAgB,CAAC;gBACzB,IAAI,EAAE,eAAe;gBACrB,SAAS,EAAE,KAAK;gBAChB,OAAO,EAAE,eAAe,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,kEAAkE;gBAC7G,gBAAgB,EAAE,SAAS;aAC5B,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;QACtC,cAAc,CAAC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,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,OAAO,CAAC,GAAG,CAAC,kCAAkC,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QACrE,cAAc,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAExC,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,GAAG,MAAM,iBAAiB,CACnE,mBAAmB,EACnB,OAAO,EACP,IAAI,EACJ,MAAM,CACP,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC;IAElC,MAAM,OAAO,GACX,cAAc,KAAK,IAAI;QACrB,CAAC,CAAC,MAAM,GAAG,QAAQ,GAAG,cAAc;QACpC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC;IACxB,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtD,MAAM,KAAK,GAAa,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;IACrE,IAAI,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAEjD,MAAM,IAAI,GAA0B;QAClC,MAAM,EAAE,GAAG,QAAQ,8CAA8C;QACjE,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;KACN,CAAC;IAEF,OAAO,QAAQ,CAAC,EAAE,SAAS,EAAE,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC;AAED,qEAAqE;AACrE,4BAA4B;AAC5B,qEAAqE;AAErE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAY,EACZ,KAAc,EACd,IAAa;IAEb,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,CAAC,CAAC;IACzB,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;IACrB,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACpB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACxB,CAAC;AAaD,sEAAsE;AACtE,SAAS,aAAa,CAAC,GAAY;IACjC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAA4B,CAAC;IACjD,OAAO;QACL,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9B,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QACf,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,SAAS,CAAC;QAChE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;QACtB,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC;QACvC,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC;QACvC,uBAAuB,EAAE,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC;QACnD,yBAAyB,EAAE,GAAG,CAAC,CAAC,CAAC,0BAA0B,CAAC;KAC7D,CAAC;AACJ,CAAC;AAUD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAA6B;IAE7B,MAAM,OAAO,GAAG,IAAI,eAAe,EAAE,CAAC;IACtC,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,EAAE,EAAE,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACrB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,gBAAgB,CAAC;gBACzB,IAAI,EAAE,eAAe;gBACrB,SAAS,EAAE,KAAK;gBAChB,OAAO,EAAE,eAAe,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,kEAAkE;gBAC7G,gBAAgB,EAAE,SAAS;aAC5B,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;QAChC,cAAc,CAAC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,EAAE,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,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,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QACrD,cAAc,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,gBAAgB,CAAC;gBACzB,IAAI,EAAE,eAAe;gBACrB,SAAS,EAAE,KAAK;gBAChB,OAAO,EAAE,oBAAoB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,2DAA2D;gBAChH,gBAAgB,EAAE,SAAS;aAC5B,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC;QAC3C,cAAc,CAAC,IAAI,CAAC,YAAY,QAAQ,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAExC,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,GAAG,MAAM,iBAAiB,CACnE,oBAAoB,EACpB,OAAO,EACP,IAAI,EACJ,MAAM,CACP,CAAC;IAEF,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC;IAEpC,MAAM,OAAO,GACX,cAAc,KAAK,IAAI;QACrB,CAAC,CAAC,MAAM,GAAG,QAAQ,GAAG,cAAc;QACpC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC;IACxB,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtD,MAAM,KAAK,GAAa,CAAC,iBAAiB,CAAC,CAAC;IAC5C,IAAI,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAEjD,MAAM,IAAI,GAA0B;QAClC,MAAM,EAAE,GAAG,QAAQ,+EAA+E;QAClG,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;KACN,CAAC;IAEF,OAAO,QAAQ,CAAC,EAAE,WAAW,EAAE,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC"}

package/dist/cms-utilization.d.ts

@@ -0,0 +1,113 @@
+/**
+ * cms-utilization.ts — CMS Medicare Physician & Other Practitioners "by Provider
+ * and Service" utilization (`data.cms.gov`, the data-API v1 dataset endpoint;
+ * ADR-0061). KEYLESS.
+ *
+ * WHAT IT ADDS: `cms_medicare_provider_services` — a healthcare-market /
+ * competitor-utilization lane: for a given provider (NPI) or state, what Medicare
+ * Part-B services (HCPCS) did providers render, to how many beneficiaries, at what
+ * submitted / Medicare-allowed / Medicare-paid amounts. The demand-side complement
+ * to NPPES (who the providers ARE) — this is what they actually BILL.
+ *
+ * ★THE TWO-REQUEST PATTERN (the load-bearing P1 honesty — MIRRORS epa-envirofacts):
+ *   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 } }`. This 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: the table is 9.78M rows. An all-empty query
+ *   (no npi, no state) is REFUSED with invalid_input (0 fetch) — providerType /
+ *   hcpcsCode alone are NOT enough to scope; a caller MUST pin npi OR state.
+ *
+ * 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 census-economic.ts's fixed-host
+ * SSRF idiom (a single host const + a post-construction hostname/protocol assertion
+ * + redirect:"error") and epa-envirofacts.ts's count-first two-request pattern +
+ * schema_drift catch-ladder (ToolErrorCarrier rethrow FIRST so a 5xx keeps its
+ * taxonomy → SyntaxError→driftError → bare rethrow).
+ *
+ *   GET https://data.cms.gov/data-api/v1/dataset/{uuid}/data-viewer/stats
+ *       ?filter[Rndrng_Prvdr_State_Abrvtn]=VA          (the COUNT sub-query)
+ *       → { "data": { "found_rows": 278254, "total_rows": 9781673 } }
+ *   GET https://data.cms.gov/data-api/v1/dataset/{uuid}/data
+ *       ?size=&offset=&filter[Rndrng_Prvdr_State_Abrvtn]=VA     (the DATA slice)
+ *       → [ { Rndrng_NPI, Rndrng_Prvdr_Last_Org_Name, …, Avg_Mdcr_Pymt_Amt }, … ]
+ *
+ * ★ SSRF: the host is a compile-time literal (`CMS_HOST`); the dataset UUID + 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}$`; hcpcsCode `^[A-Za-z0-9]{1,10}$`;
+ *   providerType 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.
+ *
+ * ★ PII NOTE: this is public PROVIDER-level AGGREGATE data — no patient identifiers.
+ *   Provider name / practice address / NPI is public professional information (the
+ *   same public surface as NPPES), so it is fine to surface.
+ *
+ * ★ HONESTY (ADR-0061 P1–P5, live-verified 2026-07-15 on data.cms.gov):
+ *   [input] require npi OR state — an all-empty query is REFUSED (0 fetch) so the
+ *           whole 9.78M-row table is never scanned.
+ *   [P1]    totalAvailable = the stats sub-query's found_rows (EXACT — e.g. VA =
+ *           278254), NOT the slice length. hasMore = offset+returned < total. Stats
+ *           fails/absent ⇒ totalAvailable:null + a disclosing note.
+ *   [P2]    an empty array ⇒ 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-array/non-JSON body ⇒
+ *           schema_drift (NEVER a fabricated empty).
+ *   [P3]    Tot_ / Avg_ fields via num() (numeric strings → numbers; a real 0 stays 0;
+ *           absent ⇒ null, never 0-faked); NPI/codes/HCPCS/names as strings
+ *           (null-never-empty-string).
+ *   [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 };
+export type ProviderService = {
+    npi: string | null;
+    providerName: string | null;
+    credentials: string | null;
+    providerType: string | null;
+    city: string | null;
+    state: string | null;
+    zip: string | null;
+    hcpcsCode: string | null;
+    hcpcsDescription: string | null;
+    totalBeneficiaries: number | null;
+    totalServices: number | null;
+    avgSubmittedCharge: number | null;
+    avgMedicareAllowed: number | null;
+    avgMedicarePayment: number | null;
+};
+/**
+ * Join the CMS Last_Org_Name + First_Name into one display name. An ORGANIZATION
+ * row (entity code "O") carries the org name in Last_Org_Name 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 joinProviderName(lastOrg: unknown, first: unknown): string | null;
+export type CmsMedicareProviderServicesArgs = {
+    npi?: string;
+    state?: string;
+    providerType?: string;
+    hcpcsCode?: string;
+    size?: number;
+    offset?: number;
+};
+/**
+ * Fetch Medicare Part-B provider-service utilization rows for an NPI / state (+
+ * optional providerType / hcpcsCode) → normalized service 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 providerServices(args: CmsMedicareProviderServicesArgs): Promise<MetaBundle>;
+//# sourceMappingURL=cms-utilization.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cms-utilization.d.ts","sourceRoot":"","sources":["../src/cms-utilization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;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;AAsCpB,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKhF;AAgDD,MAAM,MAAM,+BAA+B,GAAG;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,+BAA+B,GACpC,OAAO,CAAC,UAAU,CAAC,CAkLrB"}