@cliwant/mcp-sam-gov 1.2.0 → 1.4.0

package/dist/cms-utilization.js

@@ -0,0 +1,328 @@
+/**
+ * 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 { 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-utilization:data.cms.gov";
+// ★THE DATASET UUID — a SPECIFIC ANNUAL VINTAGE of "Medicare Physician & Other
+// Practitioners — by Provider and Service" (9,781,673 rows at build time, the most
+// recent published year). ★UPDATE YEARLY: CMS publishes a NEW uuid for each new
+// calendar year of utilization; this constant pins ONE vintage. The active vintage
+// is surfaced to the caller in a _meta note (VINTAGE_NOTE) so a consumer never
+// mistakes it for "current" or an unspecified year.
+const CMS_DATASET_UUID = "92396110-2aed-4d63-a6a2-5d6207d46a29";
+// ─── 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
+const HCPCS_RE = /^[A-Za-z0-9]{1,10}$/; // HCPCS/CPT code, e.g. "97110", "G0463"
+// providerType is a specialty label, e.g. "Physical Therapist in Private Practice".
+// It rides as a URLSearchParams VALUE (encoded), so this bound is a sanity guard,
+// not an SSRF necessity: letters/digits/space and common punctuation only.
+const PROVIDER_TYPE_RE = /^[A-Za-z0-9 &.,()/'-]{1,100}$/;
+const SIZE_MIN = 1;
+const SIZE_MAX = 100;
+const SIZE_DEFAULT = 25;
+// ─── Honesty notes (ADR-0061 required set) ────────────────────────
+const VINTAGE_NOTE = `Source dataset: CMS "Medicare Physician & Other Practitioners — by Provider and Service" (data.cms.gov dataset ${CMS_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 service counts are as-of that reference year. CMS publishes a new dataset id each year.`;
+const AGGREGATE_NOTE = "These are public PROVIDER-level AGGREGATE utilization figures (no patient identifiers). Averages (avgSubmittedCharge / avgMedicareAllowed / avgMedicarePayment) are per-service means for the provider+HCPCS row; totalBeneficiaries is CMS-rounded and suppressed below 11 in the source. This is a utilization snapshot, NOT a fraud, quality, or fitness determination.";
+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.";
+/**
+ * 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 function joinProviderName(lastOrg, first) {
+    const last = str(lastOrg);
+    const firstName = str(first);
+    if (last !== null && firstName !== null)
+        return `${last}, ${firstName}`;
+    return last ?? firstName ?? null;
+}
+/** Map ONE data-API row → the curated provider-service shape. */
+function mapService(row) {
+    const r = (row ?? {});
+    return {
+        npi: str(r.Rndrng_NPI),
+        providerName: joinProviderName(r.Rndrng_Prvdr_Last_Org_Name, r.Rndrng_Prvdr_First_Name),
+        credentials: str(r.Rndrng_Prvdr_Crdntls),
+        providerType: str(r.Rndrng_Prvdr_Type),
+        city: str(r.Rndrng_Prvdr_City),
+        state: str(r.Rndrng_Prvdr_State_Abrvtn),
+        zip: str(r.Rndrng_Prvdr_Zip5),
+        hcpcsCode: str(r.HCPCS_Cd),
+        hcpcsDescription: str(r.HCPCS_Desc),
+        totalBeneficiaries: num(r.Tot_Benes),
+        totalServices: num(r.Tot_Srvcs),
+        avgSubmittedCharge: num(r.Avg_Sbmtd_Chrg),
+        avgMedicareAllowed: num(r.Avg_Mdcr_Alowd_Amt),
+        avgMedicarePayment: num(r.Avg_Mdcr_Pymt_Amt),
+    };
+}
+// ─── 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" });
+}
+/**
+ * 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 async function providerServices(args) {
+    // ── [input guard] require npi OR state (never scan the whole 9.78M-row table).
+    //    providerType / hcpcsCode alone are NOT sufficient to scope. ──
+    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_medicare_provider_services requires at least `npi` (10-digit) OR `state` (2-letter) — an all-empty query would scan the entire 9.78M-row Medicare utilization table and is refused. providerType/hcpcsCode alone are not enough; add npi or state and retry.",
+            upstreamEndpoint: CMS_LABEL,
+        });
+    }
+    // ── Validate + build the filter params (SSRF: charclass + URLSearchParams value).
+    //    URLSearchParams encodes both the bracket key and the 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[Rndrng_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[Rndrng_Prvdr_State_Abrvtn]", state.toUpperCase());
+        filtersApplied.push(`state:${state.toUpperCase()}`);
+    }
+    if (args.providerType !== undefined && args.providerType !== "") {
+        const pt = args.providerType;
+        if (!PROVIDER_TYPE_RE.test(pt)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid providerType ${JSON.stringify(pt)} — allowed: letters, digits, space, & . , ( ) / ' - (≤100 chars).`,
+                upstreamEndpoint: CMS_LABEL,
+            });
+        }
+        filters.set("filter[Rndrng_Prvdr_Type]", pt);
+        filtersApplied.push(`providerType:${pt}`);
+    }
+    if (args.hcpcsCode !== undefined && args.hcpcsCode !== "") {
+        const hcpcs = args.hcpcsCode;
+        if (!HCPCS_RE.test(hcpcs)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid hcpcsCode ${JSON.stringify(hcpcs)} — expected an alphanumeric HCPCS/CPT code (^[A-Za-z0-9]{1,10}$), e.g. "97110" or "G0463".`,
+                upstreamEndpoint: CMS_LABEL,
+            });
+        }
+        filters.set("filter[HCPCS_Cd]", hcpcs.toUpperCase());
+        filtersApplied.push(`hcpcsCode:${hcpcs.toUpperCase()}`);
+    }
+    // ── 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);
+    }
+    const dataBase = `/data-api/v1/dataset/${CMS_DATASET_UUID}/data`;
+    const statsPath = `/data-api/v1/dataset/${CMS_DATASET_UUID}/data-viewer/stats`;
+    // ── (1) The COUNT sub-query FIRST (best-effort — the EXACT total, P1). The stats
+    //    body is `{ data: { found_rows, total_rows } }`. Any failure (network/5xx/
+    //    drift/missing field) degrades to totalAvailable:null + a disclosing 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 (epa-envirofacts / datagov-catalog 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 provider-service rows.");
+    }
+    const services = body.map(mapService);
+    const returned = services.length;
+    // ── [P1] pagination. total known ⇒ hasMore = offset+returned < total; total
+    //    unknown (count degraded) ⇒ a full page is the honest heuristic for "more". ──
+    const hasMore = totalAvailable !== null
+        ? offset + returned < totalAvailable
+        : returned === size;
+    const nextOffset = hasMore ? offset + returned : null;
+    const notes = [VINTAGE_NOTE, AGGREGATE_NOTE];
+    if (countFailed)
+        notes.push(COUNT_FALLBACK_NOTE);
+    const meta = {
+        source: `${CMS_HOST} CMS Medicare Physician & Other Practitioners — by Provider and Service (keyless)`,
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit: size, hasMore, nextOffset },
+        notes,
+    };
+    return withMeta({ services }, meta);
+}
+//# sourceMappingURL=cms-utilization.js.map

package/dist/cms-utilization.js.map

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

package/dist/courtlistener.d.ts

@@ -0,0 +1,115 @@
+/**
+ * courtlistener.ts — US FEDERAL COURT OPINIONS via CourtListener (ADR-0055) — the
+ * LITIGATION / case-law lane. Federal court decisions (opinions/clusters) — who
+ * sued whom in which court, the nature of suit, the disposition — the judicial
+ * signal no contract/spending/lobbying source carries (e.g. bid-protest and
+ * contract-claim opinions from the US Court of Federal Claims `uscfc` and the
+ * Federal Circuit `cafc`).
+ *
+ * ★ PROVENANCE — THIS IS NOT A .gov API (must be disclosed). The DATA is US federal
+ *   court PUBLIC RECORDS, but the API is **CourtListener**, operated by the **Free
+ *   Law Project** (a non-profit) which republishes those records KEYLESS. The .gov
+ *   primary source (PACER) is PAYWALLED. So every response's `_meta.source` AND a
+ *   note name CourtListener/Free Law Project and disclose the PACER-paywall — the
+ *   tool never presents itself as a government API.
+ *
+ * ★ THIS IS A KEYLESS TOOL WITH AN *OPTIONAL* RATE-LIMIT TOKEN (the lda.ts /
+ *   socrata app-token lineage, NOT the census/fred/bea key-REQUIRED lineage).
+ *   Anonymous GETs return HTTP 200 — it works with NO token. A free
+ *   COURTLISTENER_API_TOKEN only RAISES the shared rate limit; when set it rides
+ *   ONLY as the `Authorization: Token <value>` request header (never the
+ *   URL/label/_meta/notes/log — the K-test). When unset, NO auth header is sent
+ *   (genuine keyless). This mirrors lda.ts's optional-Authorization discipline.
+ *
+ *   GET https://www.courtlistener.com/api/rest/v4/search/
+ *       ?q=&court=&filed_after=&filed_before=&type=o&order_by=<order>[&cursor=]
+ *   → { count, next, previous, results:[{ caseName, court, court_id, dateFiled,
+ *        docketNumber, suitNature, status, judge, citation, absolute_url, … }] }
+ *
+ * ★ HONESTY (ADR-0055 P1–P5):
+ *   [P1]  totalAvailable = `count` (the API's REAL total for the filter, e.g. the
+ *         uscfc opinion corpus ~10595) — NEVER results.length. ★CURSOR pagination:
+ *         `next` is a FULL URL carrying an opaque `cursor=` param (NOT page/offset).
+ *         We EXTRACT the `cursor` value out of `next` and return it as `nextCursor`
+ *         (offset/nextOffset null — a numeric offset is meaningless); hasMore = next
+ *         is a non-null string. CourtListener v4 stops counting on deep cursor pages
+ *         (`count:null`) — that is DISCLOSED (totalAvailable:null + a note), never
+ *         fabricated as results.length.
+ *   [P2]  a genuine no-match (results:[]) ⇒ honest empty (returned:0). A 400 (bad
+ *         param) ⇒ invalid_input surfacing the API's message. A 429 (unauth
+ *         throttle) ⇒ rate_limited THROW (Retry-After honored, never routed around).
+ *         A 5xx/timeout ⇒ upstream_unavailable THROW. A 200 non-JSON ⇒ schema_drift.
+ *   [P3]  dates are strings; `citation` may be an array/object ⇒ flattened to a safe
+ *         string / string[] (never fabricated); judge / natureOfSuit / docketNumber
+ *         are null when absent (never empty-string); every scalar null-never-empty.
+ *   [P4]  `results` non-array, or `count` neither a number NOR null ⇒ driftError
+ *         (never a fabricated empty/total).
+ *   [K-test] OPTIONAL token: when COURTLISTENER_API_TOKEN is set it rides ONLY the
+ *         `Authorization: Token …` header — NEVER the URL/label/_meta/notes/log.
+ *         Unset ⇒ anonymous (no auth header at all).
+ *   [SSRF] fixed host `www.courtlistener.com`; a post-construction hostname/protocol
+ *         assert + `redirect:"error"`; `court` charclass `^[a-z0-9]+$`; the dates
+ *         charclass `^\d{4}-\d{2}-\d{2}$`; every VALUE rides URLSearchParams. The
+ *         `cursor` is opaque but charclass-guarded; and when we EXTRACT the cursor
+ *         from a `next` URL we RE-ASSERT that URL's host is courtlistener.com — an
+ *         off-host `next` is REFUSED (schema_drift), never followed.
+ */
+import { type MetaBundle } from "./meta.js";
+export declare const COURTLISTENER_HOST = "www.courtlistener.com";
+export declare const COURTLISTENER_CURSOR_RE: RegExp;
+/**
+ * The optional Authorization header (keyless-first, lda.ts/socrata app-token
+ * lineage). Present ONLY when COURTLISTENER_API_TOKEN is set (non-blank); the value
+ * is NEVER logged / never placed in the URL, label, `_meta`, or a note. When unset,
+ * `{}` (no header ⇒ genuine anonymous).
+ */
+export declare function courtlistenerAuthHeader(): Record<string, string>;
+/** true iff a CourtListener token is configured (for the `_meta` note — never the value). */
+export declare function courtlistenerTokenPresent(): boolean;
+export type CourtlistenerOpinion = {
+    caseName: string | null;
+    court: string | null;
+    courtId: string | null;
+    dateFiled: string | null;
+    docketNumber: string | null;
+    natureOfSuit: string | null;
+    status: string | null;
+    judge: string | null;
+    citation: string | string[] | null;
+    absoluteUrl: string | null;
+};
+/**
+ * Flatten CourtListener's `citation` (which may be a string, an array of strings,
+ * or an object) to a safe `string | string[] | null` — NEVER fabricated. An array
+ * ⇒ the non-null strings (or null when none); a string ⇒ that string; an object ⇒
+ * its non-null string VALUES (or null when none); absent ⇒ null. `[object Object]`
+ * can never leak (we never `String()` an object).
+ */
+export declare function flattenCitation(x: unknown): string | string[] | null;
+/**
+ * Extract the opaque `cursor` value from a CourtListener `next` URL. RE-ASSERTS the
+ * `next` URL's host is courtlistener.com — an OFF-HOST `next` is REFUSED (drift),
+ * never parsed/followed (SSRF: a poisoned `next` could otherwise steer the next
+ * page off-host). Returns the decoded cursor string, or null when `next` is null /
+ * carries no cursor. A non-string / unparseable `next` ⇒ null (treated as "no more").
+ */
+export declare function extractNextCursor(next: unknown, label: string): string | null;
+export type CourtlistenerSearchOpinionsArgs = {
+    query?: string;
+    court?: string;
+    dateFiledAfter?: string;
+    dateFiledBefore?: string;
+    natureOfSuit?: string;
+    cursor?: string;
+    order?: string;
+};
+/**
+ * Search US federal court opinions via CourtListener (`/api/rest/v4/search/`,
+ * type=o) → curated opinion rows + honest `_meta`. KEYLESS (an optional
+ * COURTLISTENER_API_TOKEN only raises the rate limit, sent as the Authorization
+ * header only). ★PROVENANCE: this is CourtListener/Free Law Project (a non-profit),
+ * NOT a .gov API — PACER (the .gov source) is paywalled. totalAvailable is the
+ * API's REAL `count`; CURSOR pagination (nextCursor extracted from `next`).
+ */
+export declare function searchOpinions(args: CourtlistenerSearchOpinionsArgs): Promise<MetaBundle>;
+//# sourceMappingURL=courtlistener.d.ts.map

package/dist/courtlistener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"courtlistener.d.ts","sourceRoot":"","sources":["../src/courtlistener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAKH,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAGzE,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAgB1D,eAAO,MAAM,uBAAuB,QAAmC,CAAC;AAiBxE;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIhE;AAED,6FAA6F;AAC7F,wBAAgB,yBAAyB,IAAI,OAAO,CAGnD;AAGD,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAcpE;AA4BD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqB7E;AAGD,MAAM,MAAM,+BAA+B,GAAG;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,+BAA+B,GACpC,OAAO,CAAC,UAAU,CAAC,CAiMrB"}