@cliwant/mcp-sam-gov 1.2.0 → 1.3.0

package/dist/bea.js

@@ -0,0 +1,303 @@
+/**
+ * bea.ts — BEA (Bureau of Economic Analysis) Regional Economic Accounts — the
+ * REGIONAL / SUB-NATIONAL economic lane (ADR-0051). County / state / MSA GDP by
+ * industry (CAGDP2 / SAGDP2N) and personal income (CAINC1 / SAINC1) — the
+ * place-of-performance market context that neither the national FRED macro series
+ * nor the Census establishment counts carry.
+ *
+ * ★ THIS IS THE SERVER'S THIRD KEY-REQUIRED SOURCE (Census CBP #1, FRED #2). The
+ *   BEA Data API has NO keyless tier: every request needs `UserID=`. So, honestly:
+ *   with NO `BEA_API_KEY` this tool THROWS an `invalid_input` config error BEFORE
+ *   any fetch (never a fake-empty, never a keyless-pretend). The other 116 tools
+ *   stay keyless — this key is scoped to this one source. (Contrast the OPTIONAL
+ *   keys of datagov/bls/nvd, which lift a tier but are not required.)
+ *
+ * This module MIRRORS the census-economic.ts / fred.ts key-required precedent: a
+ * `beaApiKey()` env seam, a pre-fetch `invalid_input` THROW when unset, the
+ * fixed-host SSRF assert + `redirect:"error"`, and a data-absence-sentinel→null
+ * idiom (Census's negative floor / FRED's `"."` — here BEA's string suppression
+ * codes `(NA) (D) (NM) (L) *`). It REUSES `getJson` (the shared fetch envelope) /
+ * `driftError` / `num`·`str` (coerce.ts, null-never-0/empty) / `withMeta`·`buildMeta`.
+ * The key rides ONLY in the `UserID=` query param, NOWHERE else (never the label,
+ * `_meta.source`, notes, or a log — the K-test).
+ *
+ *   GET https://apps.bea.gov/api/data
+ *       ?UserID=<BEA_API_KEY>        (REQUIRED)
+ *       &method=GetData&datasetname=Regional&ResultFormat=json  (fixed)
+ *       &TableName=<tableName>       (e.g. CAGDP2, SAGDP2N, CAINC1)
+ *       &GeoFips=<geoFips>           (STATE | county FIPS | MSA)
+ *       &LineCode=<lineCode>         (industry line, or ALL)
+ *       &Year=<year>                 (YYYY | LAST5 | ALL)
+ *       &Frequency=<frequency>       (A | Q)
+ *   → { BEAAPI:{ Results:{ Statistic, UnitOfMeasure, Dimensions:[…],
+ *        Data:[{ Code, GeoFips, GeoName, TimePeriod, CL_UNIT, UNIT_MULT,
+ *                DataValue, NoteRef }], Notes:[{ NoteRef, NoteText }] } } }
+ *
+ * ★ HONESTY (ADR-0051 P1–P5):
+ *   [KEY]  no key ⇒ invalid_input THROW pre-fetch (0 fetch); the message names
+ *          BEA_API_KEY + the free-signup URL.
+ *   [P1]   BEA GetData returns the COMPLETE set for the filter (no server
+ *          pagination) ⇒ totalAvailable = the row count, complete:true. NEVER
+ *          fabricated.
+ *   [★P2]  ★the crux: a missing/invalid key (and any bad-parameter request) returns
+ *          HTTP **200** carrying `BEAAPI.Results.Error` — NOT an HTTP error status.
+ *          The catch-ladder checks `Results.Error` FIRST (BEFORE the Data-array
+ *          drift check) and throws invalid_input SURFACING `APIErrorDescription`
+ *          (+ code) — NEVER read as an empty result. `Data:[]` (a genuine empty
+ *          array) ⇒ honest empty (returned:0, complete:true). A 5xx/timeout ⇒
+ *          upstream_unavailable THROW. A 200 non-JSON ⇒ schema_drift.
+ *   [★P3]  `DataValue` is a STRING WITH COMMAS ("1,234,567") — strip commas then
+ *          `num()`. The suppression/not-available sentinels `(NA) (D) (NM) (L) *`
+ *          (and any non-numeric after the comma-strip) map to **null** (withheld),
+ *          NEVER 0 — a real "0" stays 0. `UNIT_MULT` (power-of-10 multiplier) is
+ *          reported as `unitMult` and `CL_UNIT` as `unitOfMeasure`; the raw value is
+ *          surfaced WITH the multiplier — it is NEVER multiplied in (that would lose
+ *          precision and double-count against the disclosed multiplier).
+ *   [P4]   `BEAAPI` / `Results` / `Data` absent or non-array ⇒ driftError — BUT
+ *          ONLY after the Results.Error check (an Error response is P2, not drift).
+ *   [SSRF] fixed host `apps.bea.gov`; `tableName` ^[A-Za-z0-9]{2,20}$; `geoFips`
+ *          ^[A-Za-z0-9]{2,10}$; `lineCode` ^([0-9]{1,4}|ALL)$; `year`
+ *          ^\d{4}$|LAST5|ALL; `frequency` {A,Q}. All VALUES ride URLSearchParams;
+ *          the key rides `UserID=` ONLY.
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { withMeta } from "./meta.js";
+// Re-export the shared honesty coercion (single audited copy in ./coerce.js —
+// ADR-0005 v2 FIX-C) so a `num` regression fails together across sources. NO local
+// num/str; the sentinel/comma-strip map is a WRAPPER around num, not a fork.
+export { num };
+// ─── SSRF core: the single fixed host + base path ─────────────────
+export const BEA_HOST = "apps.bea.gov";
+const BEA_PATH = "/api/data";
+// HOST+path label — surfaces in ToolError.upstreamEndpoint; the key rides ONLY in
+// the UserID= query param, so no token can ever appear here.
+const BEA_LABEL = "bea:/api/data";
+// ─── Validation charclasses (SSRF + "verify the input" honesty) ───
+const TABLE_RE = /^[A-Za-z0-9]{2,20}$/; // e.g. CAGDP2, SAGDP2N, CAINC1
+const GEOFIPS_RE = /^[A-Za-z0-9]{2,10}$/; // STATE | county FIPS | MSA code
+const LINECODE_RE = /^([0-9]{1,4}|ALL)$/; // industry line, or ALL
+const YEAR_RE = /^\d{4}$/; // a single 4-digit year
+const YEAR_KEYWORDS = new Set(["LAST5", "ALL"]);
+const FREQUENCIES = new Set(["A", "Q"]);
+const DEFAULT_YEAR = "LAST5";
+const DEFAULT_FREQUENCY = "A";
+// BEA encodes a suppressed / not-available cell as one of these string codes in
+// DataValue: (NA)=not available, (D)=disclosure-suppressed, (NM)=not meaningful,
+// (L)=less than half the unit, *=statistically insignificant. Any of these — and
+// any non-numeric value after the comma-strip — is a data-absence marker, NEVER a
+// number and NEVER 0.
+const BEA_SUPPRESSION = new Set(["(NA)", "(D)", "(NM)", "(L)", "*"]);
+// ─── Honesty notes (ADR-0051 required set) ────────────────────────
+const KEY_REQUIRED_NOTE = "This source REQUIRES a free BEA_API_KEY (the BEA Data API has no keyless tier). The key is sent ONLY as the UserID= query parameter to apps.bea.gov and is NEVER logged, echoed, or placed in this response.";
+const DATAVALUE_NOTE = "dataValue is parsed from BEA's comma-formatted DataValue string ('1,234,567' → 1234567). BEA suppression/not-available codes ((NA)/(D)/(NM)/(L)/*) map to null (withheld) — NEVER 0 (a genuine 0 is preserved as 0).";
+const UNIT_MULT_NOTE = "unitMult is BEA's UNIT_MULT (a power-of-10 multiplier) and unitOfMeasure is CL_UNIT (the unit label). The raw dataValue is surfaced ALONGSIDE unitMult and is NOT multiplied by it — apply unitMult yourself if a scaled figure is needed (multiplying here would lose precision and double-count).";
+const NO_PAGINATION_NOTE = "BEA GetData returns the COMPLETE set of rows matching the filter (no server-side pagination); totalAvailable equals the number of rows returned. Narrow with geoFips / lineCode / year to reduce the row count.";
+// ─── The key seam (REQUIRED; value NEVER leaked past the UserID= param) ──
+/** Read BEA_API_KEY from env; trim; return the value or undefined (unset/blank). */
+export function beaApiKey() {
+    const raw = process.env.BEA_API_KEY;
+    const trimmed = typeof raw === "string" ? raw.trim() : "";
+    return trimmed ? trimmed : undefined;
+}
+/**
+ * num(), but for BEA's comma-formatted DataValue string. Strips a suppression code
+ * ((NA)/(D)/(NM)/(L)/*) → null, otherwise removes thousands commas and defers to
+ * num (so "1,234,567" ⇒ 1234567, a genuine "0" ⇒ 0, and any residual non-numeric
+ * ⇒ null — NEVER a fabricated 0).
+ */
+export function beaDataValue(v) {
+    if (typeof v === "string") {
+        const s = v.trim();
+        if (s === "" || BEA_SUPPRESSION.has(s))
+            return null;
+        return num(s.replace(/,/g, ""));
+    }
+    return num(v);
+}
+/**
+ * Fetch BEA Regional Economic Accounts rows for a table × geography × line filter
+ * → normalized rows + summarized BEA Notes + honest `_meta`. REQUIRES BEA_API_KEY
+ * (throws invalid_input pre-fetch when unset). ★A missing/invalid key (and any bad
+ * parameter) surfaces as an HTTP-200 `BEAAPI.Results.Error` carrier which is
+ * detected and thrown as invalid_input BEFORE the Data-array shape check.
+ */
+export async function regionalData(args) {
+    // ── [KEY] REQUIRED key — throw an honest config error BEFORE any fetch. ──
+    const key = beaApiKey();
+    if (key === undefined) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: "BEA Regional Economic Accounts requires a free API key. Get one at https://apps.bea.gov/API/signup/ and set BEA_API_KEY.",
+            upstreamEndpoint: BEA_LABEL,
+        });
+    }
+    // ── Validate + default the inputs (belt-and-suspenders behind the server Zod;
+    //    a DIRECT handler call bypasses Zod). All ride in the query string. ──
+    const tableName = args.tableName ?? "";
+    if (!TABLE_RE.test(tableName)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid tableName ${JSON.stringify(tableName)} — expected a BEA Regional table code (^[A-Za-z0-9]{2,20}$), e.g. "CAGDP2" (county GDP by industry), "SAGDP2N" (state GDP), "CAINC1" (personal income).`,
+            upstreamEndpoint: BEA_LABEL,
+        });
+    }
+    const geoFips = args.geoFips ?? "";
+    if (!GEOFIPS_RE.test(geoFips)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid geoFips ${JSON.stringify(geoFips)} — expected a BEA GeoFips selector (^[A-Za-z0-9]{2,10}$), e.g. "STATE" (all states), a county FIPS like "06075", or an MSA code.`,
+            upstreamEndpoint: BEA_LABEL,
+        });
+    }
+    const lineCode = args.lineCode ?? "";
+    if (!LINECODE_RE.test(lineCode)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid lineCode ${JSON.stringify(lineCode)} — expected an integer industry line (^[0-9]{1,4}$), e.g. "1", or "ALL" for every line.`,
+            upstreamEndpoint: BEA_LABEL,
+        });
+    }
+    const year = args.year ?? DEFAULT_YEAR;
+    if (!YEAR_KEYWORDS.has(year) && !YEAR_RE.test(year)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid year ${JSON.stringify(year)} — expected a 4-digit year (^\\d{4}$), "LAST5", or "ALL".`,
+            upstreamEndpoint: BEA_LABEL,
+        });
+    }
+    const frequency = args.frequency ?? DEFAULT_FREQUENCY;
+    if (!FREQUENCIES.has(frequency)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid frequency ${JSON.stringify(frequency)} — expected one of A (annual), Q (quarterly).`,
+            upstreamEndpoint: BEA_LABEL,
+        });
+    }
+    // ── Build the query (all VALUES via URLSearchParams — no host/path steer; the
+    //    REQUIRED key rides ONLY here in UserID=). ──
+    const params = new URLSearchParams();
+    params.set("UserID", key);
+    params.set("method", "GetData");
+    params.set("datasetname", "Regional");
+    params.set("ResultFormat", "json");
+    params.set("TableName", tableName);
+    params.set("GeoFips", geoFips);
+    params.set("LineCode", lineCode);
+    params.set("Year", year);
+    params.set("Frequency", frequency);
+    const url = `https://${BEA_HOST}${BEA_PATH}?${params.toString()}`;
+    // Belt-and-suspenders: the fixed host + strictly-validated query leave nothing to
+    // steer the authority; assert the built URL cannot have been moved off-host.
+    const built = new URL(url);
+    if (built.hostname !== BEA_HOST || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Constructed BEA URL host ${JSON.stringify(built.hostname)} (${built.protocol}) is not ${BEA_HOST} over https — refusing to fetch (SSRF safety).`,
+            upstreamEndpoint: BEA_LABEL,
+        });
+    }
+    // ── Fetch through the shared envelope. The key rides UserID= ONLY (never the
+    //    label/_meta); redirect:"error" fails closed on any off-host 3xx (it could
+    //    carry the key away). A 5xx/timeout ⇒ upstream_unavailable THROW; a 200
+    //    non-JSON body ⇒ getJson's r.json() throws a SyntaxError ⇒ we reclassify to
+    //    schema_drift. ★A missing/invalid key returns HTTP 200 with an Error carrier,
+    //    so it does NOT surface here — it is detected in the parse ladder below. ──
+    let body;
+    try {
+        body = await getJson(url, { label: BEA_LABEL, redirect: "error" });
+    }
+    catch (e) {
+        if (e instanceof SyntaxError) {
+            throw driftError(BEA_LABEL, "BEA /api/data returned a non-JSON body at HTTP 200 — treating as schema drift (never read as an empty result).");
+        }
+        throw e; // 5xx → upstream_unavailable, 404 → not_found, 429 → rate_limited …
+    }
+    // ── [P4] Navigate BEAAPI.Results. An absent BEAAPI/Results is drift — BUT the
+    //    Results.Error check (P2) comes FIRST below, since an error RESPONSE also
+    //    carries BEAAPI.Results (with an Error member, not a Data array). ──
+    const beaapi = body?.BEAAPI;
+    if (beaapi === null || typeof beaapi !== "object") {
+        throw driftError(BEA_LABEL, "BEA response is missing the `BEAAPI` envelope — treating as schema drift (never a fabricated empty).");
+    }
+    const results = beaapi.Results;
+    if (results === null || typeof results !== "object") {
+        throw driftError(BEA_LABEL, "BEA response is missing `BEAAPI.Results` — treating as schema drift (never a fabricated empty).");
+    }
+    // ── [★P2] The CRUX: a missing/invalid key (or any bad parameter) returns HTTP
+    //    200 carrying `BEAAPI.Results.Error` — checked HERE, BEFORE the Data-array
+    //    drift check, so an error response is surfaced as invalid_input CARRYING the
+    //    APIErrorDescription (+ code), NEVER read as an empty result. ──
+    const errNode = results.Error;
+    if (errNode !== undefined && errNode !== null) {
+        const errObj = (Array.isArray(errNode) ? errNode[0] : errNode);
+        const code = str(errObj?.APIErrorCode);
+        const desc = str(errObj?.APIErrorDescription);
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: desc
+                ? `BEA rejected the request${code ? ` (APIErrorCode ${code})` : ""}: ${desc}. Check BEA_API_KEY and the tableName / geoFips / lineCode / year parameters.`
+                : `BEA rejected the request${code ? ` (APIErrorCode ${code})` : ""} — check BEA_API_KEY and the tableName / geoFips / lineCode / year parameters.`,
+            upstreamEndpoint: BEA_LABEL,
+        });
+    }
+    // ── [P4] `Data` MUST be an array (a missing/non-array is drift, never a
+    //    fabricated empty). An EMPTY array is a genuine honest-empty (below). ──
+    const data = results.Data;
+    if (!Array.isArray(data)) {
+        throw driftError(BEA_LABEL, "BEA `BEAAPI.Results.Data` is missing or not an array — treating as schema drift (never a fabricated empty).");
+    }
+    // ── [P3] Map each Data row (comma-stripped/​sentinel→null DataValue; UNIT_MULT /
+    //    CL_UNIT reported, NOT applied). ──
+    const rows = data.map((raw) => {
+        const row = (raw ?? {});
+        return {
+            geoFips: str(row.GeoFips),
+            geoName: str(row.GeoName),
+            timePeriod: str(row.TimePeriod),
+            lineCode: str(row.Code),
+            dataValue: beaDataValue(row.DataValue),
+            unitOfMeasure: str(row.CL_UNIT),
+            unitMult: num(row.UNIT_MULT),
+            noteRef: str(row.NoteRef),
+        };
+    });
+    // ── Summarize the BEA Notes (footnotes). A missing/non-array Notes ⇒ []. ──
+    const notesNode = results.Notes;
+    const notes = Array.isArray(notesNode)
+        ? notesNode.map((raw) => {
+            const n = (raw ?? {});
+            return { noteRef: str(n.NoteRef), noteText: str(n.NoteText) };
+        })
+        : [];
+    // ── [P1] The COMPLETE set for the filter (no server pagination). ──
+    const totalAvailable = rows.length;
+    const meta = {
+        // MODE only — never the key value (K-test).
+        source: "apps.bea.gov /api/data (BEA Regional Economic Accounts; BEA_API_KEY)",
+        keylessMode: false, // ★KEYED — the third key-required source
+        returned: rows.length,
+        totalAvailable,
+        filtersApplied: [
+            `tableName:${tableName}`,
+            `geoFips:${geoFips}`,
+            `lineCode:${lineCode}`,
+            `year:${year}`,
+            `frequency:${frequency}`,
+        ],
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        notes: [KEY_REQUIRED_NOTE, DATAVALUE_NOTE, UNIT_MULT_NOTE, NO_PAGINATION_NOTE],
+    };
+    return withMeta({ rows, notes }, meta);
+}
+//# sourceMappingURL=bea.js.map

package/dist/bea.js.map

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

package/dist/dol.d.ts

@@ -0,0 +1,118 @@
+/**
+ * dol.ts — US Department of Labor Data API v4 (apiprod.dol.gov) — the LABOR
+ * ENFORCEMENT lane (ADR-0053). WHD wage/hour violations, OSHA inspections, ILAB
+ * child/forced-labor reports, MSHA mine safety … — the compliance/enforcement
+ * signal no contract/spending/market source carries.
+ *
+ * TWO tools with a DELIBERATE key split (the honest reflection of the live API):
+ *   • `dol_list_datasets` (KEYLESS) — GET /v4/datasets. The dataset CATALOG (and
+ *     /v4/agencies) is keyless; this tool needs NO key. It returns the machine
+ *     inventory (name / tablename / api_url / agency / …) you page + filter to find
+ *     an endpoint, then feed its `apiUrl` into dol_get_dataset.
+ *   • `dol_get_dataset` (KEY-REQUIRED, DOL_API_KEY) — GET
+ *     /v4/get/{agency}/{endpoint}/json?… . The DATA endpoint has NO keyless tier, so
+ *     with NO `DOL_API_KEY` this tool THROWS an invalid_input config error BEFORE any
+ *     fetch (0 network call; the message names DOL_API_KEY + dol.gov/developer).
+ *   So DOL is the 4th REQUIRED key — but ONLY for the data tool; the catalog tool
+ *   (and every other tool on the server) stays keyless.
+ *
+ * ★LIVE-VERIFIED WIRE FACTS (2026-07-15):
+ *   - Host `apiprod.dol.gov` (AWS API Gateway) + base `/v4`.
+ *   - /v4/datasets is KEYLESS 200 → `{ datasets:[…], meta:{ current_page, next_page,
+ *     prev_page, total_pages, total_count } }`. `limit` is the PER-PAGE size (limit=1000
+ *     returns the whole 42-row catalog in one page, total_pages:1); server-side agency
+ *     filtering is NOT honored (verified: ?agency=ILAB still returned the full 42) — so
+ *     agency/query filtering is CLIENT-SIDE over the fetched catalog.
+ *   - The DATA route is the QUERY-STYLE form `/v4/get/{agency}/{endpoint}/{format}?…`
+ *     (NOT the path-style `/…/limit/N/offset/O/format/json`): the query-style URL
+ *     reached the DOL app and returned a proper `401 {"…key…missing…"}` on a bad key,
+ *     whereas the path-style URL only ever hit the AWS gateway's generic
+ *     `403 {"message":"Missing Authentication Token"}` (an unmatched route). The DOL
+ *     API User Guide (dataportal.dol.gov/pdf/dol-api-user-guide.pdf) confirms the
+ *     `/get/<agency>/<api_url>/<format>?limit=&offset=&filter_object=&…` template and
+ *     that `<endpoint>` is the dataset's **api_url** (NOT its tablename).
+ *
+ * ★UNVERIFIED (key-gated — coded DEFENSIVELY, honestly disclosed): the DATA response
+ *   body shape could not be observed live (every /v4/get call is 401 without a real
+ *   key, and the User Guide shows no body example). So `dol_get_dataset` accepts EITHER
+ *   a bare row array `[…]` OR `{ data:[…] }` OR `{ results:[…] }`; a top-level count
+ *   (`total_count`/`total`/`count`, or `meta.total_count`) is used for totalAvailable
+ *   ONLY if actually present, else `totalAvailable = null` (an HONEST unknown — never
+ *   `returned` passed off as the total). Records are surfaced VERBATIM (each dataset
+ *   has its own enforcement schema; blind coercion would distort compliance data — a
+ *   JSON `0` stays `0`, a JSON `null` stays `null`, field names are preserved as-is).
+ *
+ * ★HONESTY (ADR-0053 P1–P4 + KEY + SSRF):
+ *   [KEY]  dol_get_dataset with NO DOL_API_KEY ⇒ invalid_input THROW pre-fetch (0
+ *          fetch); the message names DOL_API_KEY + dol.gov/developer. The key rides the
+ *          `X-API-KEY` HEADER ONLY — NEVER the URL / label / _meta / notes / a log (the
+ *          K-test). dol_list_datasets is keyless (no key read, no header).
+ *   [P1]   catalog: totalAvailable = meta.total_count (the API's real catalog total)
+ *          for an unfiltered scan; when a CLIENT-SIDE filter is applied it is the
+ *          filtered-set size (exact — the whole catalog is fetched in one page). data:
+ *          totalAvailable = a real count field when present, else null; offset/limit
+ *          pagination in both.
+ *   [P2]   data: 401/403 (missing/invalid key) ⇒ invalid_input reclassified with the
+ *          DOL_API_KEY guidance (the AWS "Missing Authentication Token" is a key problem
+ *          here) — never empty. 400 ⇒ invalid_input. empty rows ⇒ honest empty
+ *          (returned:0). 429 ⇒ rate_limited THROW (Retry-After honored). 5xx/timeout ⇒
+ *          upstream_unavailable THROW. 200 non-JSON ⇒ schema_drift.
+ *   [P3]   records verbatim (null-never-0 comes for free — JSON preserves 0/null and
+ *          every original field name; the tool never introduces a fabricated 0).
+ *   [P4]   the expected array (catalog `datasets`; data's row array) absent/non-array
+ *          ⇒ driftError. A ToolErrorCarrier (401/5xx/…) is a P2 outcome, rethrown
+ *          BEFORE the drift check.
+ *   [SSRF] fixed host `apiprod.dol.gov` + a post-construction hostname/https assert +
+ *          `redirect:"error"`; agency/endpoint charclass `^[A-Za-z0-9_]+$` (they ride
+ *          in the PATH); limit/offset integers; filterValue/fields ride URLSearchParams;
+ *          the key rides the X-API-KEY header only.
+ */
+import { num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num };
+export declare const DOL_HOST = "apiprod.dol.gov";
+/** Read DOL_API_KEY from env; trim; return the value or undefined (unset/blank). */
+export declare function dolApiKey(): string | undefined;
+export type DolListDatasetsArgs = {
+    agency?: string;
+    query?: string;
+    limit?: number;
+    offset?: number;
+};
+export type DolDataset = {
+    name: string | null;
+    tablename: string | null;
+    apiUrl: string | null;
+    agency: string | null;
+    agencyAbbr: string | null;
+    description: string | null;
+    frequency: string | null;
+    datasetType: number | null;
+    category: string | null;
+};
+/**
+ * List the DOL Data API v4 dataset catalog (KEYLESS). Fetches the WHOLE catalog in
+ * one page, applies optional CLIENT-SIDE `agency` (abbr/name) + `query` (substring over
+ * name/description/tags) filters, then offset/limit-slices the filtered set. Honest
+ * `_meta`: totalAvailable = the catalog's real total (unfiltered) or the filtered-set
+ * size (exact — the whole catalog is in hand); offset pagination over the filtered set.
+ */
+export declare function listDatasets(args: DolListDatasetsArgs): Promise<MetaBundle>;
+export type DolGetDatasetArgs = {
+    agency?: string;
+    table?: string;
+    limit?: number;
+    offset?: number;
+    filterField?: string;
+    filterValue?: string;
+    fields?: string[];
+};
+/**
+ * Fetch records from one DOL dataset (KEY-REQUIRED). `agency` (abbr) + `table` (the
+ * dataset's api_url endpoint) ride the request PATH; limit/offset/filter ride the query;
+ * the DOL_API_KEY rides the X-API-KEY header ONLY. Records are surfaced VERBATIM. Honest
+ * `_meta`: totalAvailable is a real count field when present, else null (offset
+ * pagination). Unset key ⇒ invalid_input THROW pre-fetch (0 fetch).
+ */
+export declare function getDataset(args: DolGetDatasetArgs): Promise<MetaBundle>;
+//# sourceMappingURL=dol.d.ts.map

package/dist/dol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dol.d.ts","sourceRoot":"","sources":["../src/dol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAIzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAGf,eAAO,MAAM,QAAQ,oBAAoB,CAAC;AAkC1C,oFAAoF;AACpF,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAI9C;AAyBD,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAoBF;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiGjF;AAGD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAyK7E"}