@cliwant/mcp-sam-gov 1.1.0 → 1.3.0

package/dist/gsa-perdiem.js

@@ -0,0 +1,296 @@
+/**
+ * gsa-perdiem.ts — GSA Federal Travel Per-Diem lookup (`api.gsa.gov`, base
+ * `/travel/perdiem/v2`) — ADR-0050. The lodging + M&IE rate ceilings the federal
+ * government reimburses for official travel, by city/state or ZIP for a given year.
+ *
+ * WHAT IT ADDS: a NEW travel-cost lane (the per-diem authority) on the SAME
+ * `api.gsa.gov` host as datagov-catalog.ts, so it REUSES the audited `datagovKey.ts`
+ * key seam VERBATIM (keyHeader / keyModeLabel / pushKeyNote) — keyless by default via
+ * the shared DEMO_KEY, upgraded by DATA_GOV_API_KEY. The key rides ONLY in the
+ * X-Api-Key header — NEVER the URL / label / _meta / a log (the K-test). This module
+ * writes ZERO fetch/coercion/error/meta code: it REUSES `getJson` (redirect:"error",
+ * the X-Api-Key header) / `driftError` / `num`·`str` (coerce.ts) / `withMeta`·
+ * `buildMeta`, and MIRRORS the datagov-catalog schema_drift catch-ladder verbatim.
+ *
+ * ★ SSRF: the host is a compile-time literal (`GSA_PERDIEM_HOST`). The two lookup
+ *   modes ride FIXED path templates; every caller value (city/state/zip/year) is
+ *   charclass-validated THEN `encodeURIComponent`-escaped into a single path segment
+ *   (no raw passthrough, no query steer). A post-construction hostname/protocol
+ *   assertion + `redirect:"error"` lock it (fail closed on any off-host 3xx — a 3xx
+ *   off api.gsa.gov could carry the X-Api-Key header away).
+ *
+ * ★ HONESTY (ADR-0050 P1–P5, live-verified 2026-07-15):
+ *   [INPUT] EITHER (city + state) OR zip — supplying BOTH, or NEITHER, ⇒ invalid_input
+ *           with 0 fetch (an ambiguous/empty lookup is a caller error, never a guess).
+ *   [P1]    the API returns the COMPLETE rate set for the lookup (no pagination) ⇒
+ *           totalAvailable = the flattened row count, complete:true. NEVER fabricated.
+ *   [P2]    `errors` non-null ⇒ invalid_input surfacing the message (never a fake
+ *           empty); a genuine no-match (rates:[] / rate:[]) ⇒ honest empty (returned:0,
+ *           complete:true); a 429 (DEMO_KEY ~10/hr) ⇒ rate_limited THROW honoring
+ *           Retry-After; a 5xx ⇒ upstream_unavailable THROW; a 200 non-JSON ⇒
+ *           schema_drift. A DOWN service is NEVER a returned:0.
+ *   [P3]    `value` (monthly max lodging $) / `meals` (M&IE cap $) via `num` (null-
+ *           never-0 — a genuine 0 stays 0). `standardRate` / `isOconus` are STRING
+ *           booleans "true"/"false" ⇒ coerced to a real boolean (an unrecognized value
+ *           ⇒ null, never a fabricated false). The months array is preserved AS-IS
+ *           (never padded/fabricated to 12).
+ *   [P4]    `rates` / a group's `rate` / `months.month` absent or non-array ⇒
+ *           driftError (never a fabricated empty).
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { withMeta } from "./meta.js";
+// The SHARED api.data.gov key seam (ADR-0010 §2). api.gsa.gov accepts the SAME
+// DATA_GOV_API_KEY / DEMO_KEY via the X-Api-Key header — this is another consumer
+// of the audited key discipline (a key-leak regression now fails this suite too).
+import { keyHeader, keyModeLabel, pushKeyNote } from "./datagovKey.js";
+// ─── Fixed endpoint (SSRF core — compile-time CONSTANTS) ──────────
+export const GSA_PERDIEM_HOST = "api.gsa.gov";
+const GSA_PERDIEM_BASE = "/travel/perdiem/v2";
+// HOST+path label — surfaces in ToolError.upstreamEndpoint; the key rides ONLY in
+// the X-Api-Key header, so no token can ever appear here.
+const GSA_PERDIEM_LABEL = "gsa-perdiem:/travel/perdiem/v2/rates";
+const GSA_PERDIEM_SOURCE = (mode) => `${GSA_PERDIEM_HOST} via GSA Federal Travel Per-Diem API (${mode})`;
+// The default per-diem fiscal year (ADR-0050 — the current confirmed vintage).
+export const DEFAULT_PERDIEM_YEAR = "2025";
+// ─── Validation charclasses (SSRF + "verify the input" honesty) ───
+// Each rides in a single PATH segment (encodeURIComponent-escaped), so these are
+// belt-and-suspenders against a Zod-bypassing direct handler call.
+const CITY_RE = /^[A-Za-z .'\-]{1,60}$/;
+const STATE_RE = /^[A-Za-z]{2}$/;
+const ZIP_RE = /^\d{5}$/;
+const YEAR_RE = /^\d{4}$/;
+// ─── Honesty notes (ADR-0050 required set) ────────────────────────
+const RATE_MEANING_NOTE = "lodgingUsd (from the API's monthly `value`) is the MAX nightly lodging reimbursement ceiling for that month — it VARIES SEASONALLY, hence a per-month array; mealsUsd (from `meals`) is the daily Meals & Incidental Expenses (M&IE) ceiling. Both are integer US dollars. A withheld/absent figure is null, NEVER 0 (a genuine 0 is preserved).";
+const STANDARD_RATE_NOTE = "standardRate:true means this location falls under the CONUS STANDARD rate (not an individually-set non-standard rate). standardRate/isOconus are booleans coerced from the API's string 'true'/'false'.";
+const NO_PAGINATION_NOTE = "The per-diem API returns the COMPLETE rate set for the lookup (no pagination); totalAvailable equals the number of rows returned.";
+// ─── STRING-boolean coercion (null-never-fabricate) ───────────────
+/** Coerce the API's string 'true'/'false' → a real boolean; anything else ⇒ null. */
+function strBool(v) {
+    if (typeof v === "boolean")
+        return v;
+    if (typeof v === "string") {
+        const s = v.trim().toLowerCase();
+        if (s === "true")
+            return true;
+        if (s === "false")
+            return false;
+    }
+    return null;
+}
+/**
+ * Map one `months.month[]` entry → the curated per-month shape. `value` and the
+ * month `number` via `num` (null-never-0); `long` (month name) via `str`.
+ */
+function mapMonth(m) {
+    const it = (m ?? {});
+    return {
+        month: num(it.number),
+        monthName: str(it.long),
+        lodgingUsd: num(it.value),
+    };
+}
+// ─── SSRF-guarded fetch (fixed host + hostname assertion + redirect) ──
+/**
+ * GET one GSA per-diem JSON resource. `path` is a fully-assembled, pre-escaped
+ * path (NO query params — the key rides in the X-Api-Key header only). Builds
+ * `https://${GSA_PERDIEM_HOST}${path}` on the FIXED host, asserts the CONSTRUCTED
+ * URL's hostname === the host over https (belt-and-suspenders), sets
+ * `redirect:"error"` (an off-host 3xx must NOT be followed — it could carry the
+ * X-Api-Key header to a foreign host), and attaches the key ONLY in the header.
+ */
+async function getGsaPerdiem(path) {
+    const url = `https://${GSA_PERDIEM_HOST}${path}`;
+    const built = new URL(url);
+    if (built.hostname !== GSA_PERDIEM_HOST || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Constructed GSA per-diem URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the fixed host ${JSON.stringify(GSA_PERDIEM_HOST)} over https — refusing to fetch (SSRF safety).`,
+            retryable: false,
+            upstreamEndpoint: GSA_PERDIEM_LABEL,
+        });
+    }
+    // The key rides in the X-Api-Key header ONLY (never the URL/label/_meta);
+    // redirect:"error" (fail closed on any off-host 3xx).
+    return getJson(url, {
+        label: GSA_PERDIEM_LABEL,
+        headers: keyHeader(),
+        redirect: "error",
+    });
+}
+/**
+ * Look up GSA Federal Travel per-diem rates by EITHER (city + state) OR zip, for a
+ * given `year` (default 2025). Returns flattened rate rows (each outer state/year
+ * group × inner city/rate) + honest `_meta`: totalAvailable = the row count (no
+ * pagination — P1), lodging/meals as null-never-0 dollars (P3), standardRate/isOconus
+ * as real booleans, the months array preserved as-is. The DEMO_KEY rate disclosure
+ * rides in the notes.
+ */
+export async function perdiemRates(args) {
+    const label = GSA_PERDIEM_LABEL;
+    const year = args.year ?? DEFAULT_PERDIEM_YEAR;
+    // ── [INPUT] EITHER (city + state) OR zip — never both, never neither. This is a
+    //    caller-shape check (0 fetch): an ambiguous or empty lookup is invalid_input,
+    //    never a silent guess. ──
+    const hasCityState = args.city !== undefined || args.state !== undefined;
+    const hasZip = args.zip !== undefined;
+    if (hasCityState && hasZip) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: "Provide EITHER (city + state) OR zip — not both. City/state and ZIP are two distinct lookup modes; supplying both is ambiguous.",
+            upstreamEndpoint: label,
+        });
+    }
+    if (!hasCityState && !hasZip) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: "Provide a lookup key: EITHER (city + state, e.g. city:'Washington', state:'DC') OR zip (e.g. zip:'20001').",
+            upstreamEndpoint: label,
+        });
+    }
+    // ── Validate + default the inputs (belt-and-suspenders behind the server Zod;
+    //    a DIRECT handler call bypasses Zod). year rides in the PATH regardless. ──
+    if (!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}$), e.g. "2025". (year rides in the request PATH; it is strictly validated.)`,
+            upstreamEndpoint: label,
+        });
+    }
+    let path;
+    const filtersApplied = [`year:${year}`];
+    let lookupMode;
+    if (hasZip) {
+        const zip = args.zip;
+        if (!ZIP_RE.test(zip)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid zip ${JSON.stringify(zip)} — expected a 5-digit ZIP code (^\\d{5}$), e.g. "20001".`,
+                upstreamEndpoint: label,
+            });
+        }
+        lookupMode = `zip:${zip}`;
+        filtersApplied.push(lookupMode);
+        // Fixed template; each segment encodeURIComponent-escaped (belt-and-suspenders
+        // behind the charclass — no path injection, no query steer).
+        path = `${GSA_PERDIEM_BASE}/rates/zip/${encodeURIComponent(zip)}/year/${encodeURIComponent(year)}`;
+    }
+    else {
+        // city + state — BOTH are required together for this mode.
+        if (args.city === undefined || args.state === undefined) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: "The city lookup mode requires BOTH city AND state (e.g. city:'Washington', state:'DC'). Provide both, or use zip instead.",
+                upstreamEndpoint: label,
+            });
+        }
+        const city = args.city;
+        const state = args.state;
+        if (!CITY_RE.test(city)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid city ${JSON.stringify(city)} — expected 1–60 letters/spaces/.'- (^[A-Za-z .'\\-]{1,60}$), e.g. "Washington".`,
+                upstreamEndpoint: label,
+            });
+        }
+        if (!STATE_RE.test(state)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid state ${JSON.stringify(state)} — expected a 2-letter state code (^[A-Za-z]{2}$), e.g. "DC", "CA".`,
+                upstreamEndpoint: label,
+            });
+        }
+        lookupMode = `city:${city}, state:${state}`;
+        filtersApplied.push(`city:${city}`, `state:${state}`);
+        path = `${GSA_PERDIEM_BASE}/rates/city/${encodeURIComponent(city)}/state/${encodeURIComponent(state)}/year/${encodeURIComponent(year)}`;
+    }
+    // ── The typed catch-ladder (datagov-catalog searchDatasets shape, VERBATIM).
+    //    Preserve the 429/404/5xx/400/timeout ToolErrorCarrier taxonomy FIRST
+    //    (LOAD-BEARING: the DEMO_KEY-~10/hr 429→rate_limited frontier would regress to
+    //    schema_drift under a broader catch); reclassify a 200 non-JSON `.json()`
+    //    SyntaxError to schema_drift SECOND; bare-rethrow LAST. The host-assert
+    //    ToolErrorCarrier is also rethrown first. ──
+    let body;
+    try {
+        body = await getGsaPerdiem(path);
+    }
+    catch (e) {
+        if (e instanceof ToolErrorCarrier)
+            throw e;
+        if (e instanceof SyntaxError)
+            throw driftError(label, "GSA per-diem returned a non-JSON body at HTTP 200 — schema drift.");
+        throw e;
+    }
+    const b = (body ?? {});
+    // ── [P2] `errors` non-null ⇒ a lookup problem ⇒ invalid_input surfacing the
+    //    message (NEVER a fake empty — swallowing this as empty ⇒ RED). ──
+    if (b.errors !== null && b.errors !== undefined) {
+        const msg = typeof b.errors === "string" ? b.errors : JSON.stringify(b.errors);
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `GSA per-diem reported a lookup error for ${lookupMode} (year ${year}): ${msg}`,
+            upstreamEndpoint: label,
+        });
+    }
+    // ── [P4] `rates` MUST be an array (a missing/object/null rates is drift, never a
+    //    fabricated empty — a TypeError must never mask drift as upstream_unavailable). ──
+    if (!Array.isArray(b.rates)) {
+        throw driftError(label, "GSA per-diem shape drift — response.rates must be an array.");
+    }
+    // ── Flatten: each outer state/year group × its inner rate[]. ──
+    const rows = [];
+    for (const group of b.rates) {
+        const g = (group ?? {});
+        // [P4] a group's `rate` MUST be an array (never a fabricated empty).
+        if (!Array.isArray(g.rate)) {
+            throw driftError(label, "GSA per-diem shape drift — a rates[].rate must be an array.");
+        }
+        const gState = str(g.state);
+        const gYear = num(g.year);
+        const gOconus = strBool(g.isOconus);
+        for (const rate of g.rate) {
+            const r = (rate ?? {});
+            const monthsObj = (r.months ?? {});
+            // [P4] months.month MUST be an array (never padded/fabricated to 12).
+            if (!Array.isArray(monthsObj.month)) {
+                throw driftError(label, "GSA per-diem shape drift — a rate's months.month must be an array.");
+            }
+            rows.push({
+                city: str(r.city),
+                county: str(r.county),
+                state: gState,
+                zip: str(r.zip),
+                year: gYear,
+                isOconus: gOconus,
+                standardRate: strBool(r.standardRate),
+                mealsUsd: num(r.meals),
+                monthlyLodgingUsd: monthsObj.month.map(mapMonth),
+            });
+        }
+    }
+    const returned = rows.length;
+    const notes = [RATE_MEANING_NOTE, STANDARD_RATE_NOTE, NO_PAGINATION_NOTE];
+    pushKeyNote(notes);
+    return withMeta({ rates: rows }, {
+        source: GSA_PERDIEM_SOURCE(keyModeLabel()),
+        keylessMode: false, // keyed via the api.data.gov X-Api-Key (DEMO_KEY default)
+        returned,
+        // [P1] the COMPLETE set for the lookup (no pagination) ⇒ totalAvailable = the
+        // row count; complete is DERIVED true by buildMeta (returned === total).
+        totalAvailable: returned,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        notes,
+    });
+}
+//# sourceMappingURL=gsa-perdiem.js.map

package/dist/gsa-perdiem.js.map

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

package/dist/keys.d.ts

@@ -4,8 +4,8 @@
  * Why this exists
  * ----------------
  * The server rides 31 federal sources. MOST are fully keyless. But the set of
- * *optional* keys (raise a rate limit, unlock one filter) plus the two *required*
- * keys (Census business-patterns, FRED) has grown to the point where a user — or
+ * *optional* keys (raise a rate limit, unlock one filter) plus the four *required*
+ * keys (Census business-patterns, FRED, BEA Regional, DOL data) has grown to the point where a user — or
  * the AI driving the server — cannot tell, without reading source code:
  *   - which env var each source reads,
  *   - whether a key is REQUIRED or merely OPTIONAL,
@@ -19,8 +19,9 @@
  * Grounding: every `envVar` below is the exact string the code reads via
  * `process.env.<NAME>` — DATA_GOV_API_KEY (datagovKey.ts), SAM_GOV_API_KEY
  * (server.ts), BLS_API_KEY (bls.ts), NVD_API_KEY (nvd.ts), SOCRATA_APP_TOKEN
- * (socrata.ts), CENSUS_API_KEY (census-economic.ts), FRED_API_KEY (fred.ts).
- * No invented keys, sources, or signup URLs.
+ * (socrata.ts), CENSUS_API_KEY (census-economic.ts), FRED_API_KEY (fred.ts),
+ * BEA_API_KEY (bea.ts), DOL_API_KEY (dol.ts), LDA_API_KEY (lda.ts). No invented
+ * keys, sources, or signup URLs.
  */
 /** One registry entry describing a single API key the server can use. */
 export type KeyRegistryEntry = {
@@ -38,11 +39,12 @@ export type KeyRegistryEntry = {
     note: string;
 };
 /**
- * The 7 keys the server reads — code-grounded, no inventions.
+ * The 10 keys the server reads — code-grounded, no inventions.
  *
- * REQUIRED (2): CENSUS_API_KEY, FRED_API_KEY — those sources have no keyless
- * tier, so the tool throws without them. OPTIONAL (5): everything else works
- * keyless; a key only raises a rate limit or unlocks a single filter.
+ * REQUIRED (4): CENSUS_API_KEY, FRED_API_KEY, BEA_API_KEY, DOL_API_KEY — those sources
+ * have no keyless tier, so the tool throws without them (DOL_API_KEY gates ONLY
+ * dol_get_dataset; the DOL catalog, dol_list_datasets, is keyless). OPTIONAL (6):
+ * everything else works keyless; a key only raises a rate limit or unlocks a single filter.
  */
 export declare const KEY_REGISTRY: readonly KeyRegistryEntry[];
 /** Per-key status: the registry entry + a `currentlySet` boolean. NEVER the value. */

package/dist/keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,gBAAgB,EAiE1C,CAAC;AAQX,sFAAsF;AACtF,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG;IAAE,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC;AAErE,yCAAyC;AACzC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,sFAAsF;IACtF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kDAAkD;IAClD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CAYjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CA4C/C"}
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,gBAAgB,EA8F1C,CAAC;AAQX,sFAAsF;AACtF,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG;IAAE,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC;AAErE,yCAAyC;AACzC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,sFAAsF;IACtF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kDAAkD;IAClD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CAYjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CA4C/C"}

package/dist/keys.js

@@ -4,8 +4,8 @@
  * Why this exists
  * ----------------
  * The server rides 31 federal sources. MOST are fully keyless. But the set of
- * *optional* keys (raise a rate limit, unlock one filter) plus the two *required*
- * keys (Census business-patterns, FRED) has grown to the point where a user — or
+ * *optional* keys (raise a rate limit, unlock one filter) plus the four *required*
+ * keys (Census business-patterns, FRED, BEA Regional, DOL data) has grown to the point where a user — or
  * the AI driving the server — cannot tell, without reading source code:
  *   - which env var each source reads,
  *   - whether a key is REQUIRED or merely OPTIONAL,
@@ -19,23 +19,25 @@
  * Grounding: every `envVar` below is the exact string the code reads via
  * `process.env.<NAME>` — DATA_GOV_API_KEY (datagovKey.ts), SAM_GOV_API_KEY
  * (server.ts), BLS_API_KEY (bls.ts), NVD_API_KEY (nvd.ts), SOCRATA_APP_TOKEN
- * (socrata.ts), CENSUS_API_KEY (census-economic.ts), FRED_API_KEY (fred.ts).
- * No invented keys, sources, or signup URLs.
+ * (socrata.ts), CENSUS_API_KEY (census-economic.ts), FRED_API_KEY (fred.ts),
+ * BEA_API_KEY (bea.ts), DOL_API_KEY (dol.ts), LDA_API_KEY (lda.ts). No invented
+ * keys, sources, or signup URLs.
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 /**
- * The 7 keys the server reads — code-grounded, no inventions.
+ * The 10 keys the server reads — code-grounded, no inventions.
  *
- * REQUIRED (2): CENSUS_API_KEY, FRED_API_KEY — those sources have no keyless
- * tier, so the tool throws without them. OPTIONAL (5): everything else works
- * keyless; a key only raises a rate limit or unlocks a single filter.
+ * REQUIRED (4): CENSUS_API_KEY, FRED_API_KEY, BEA_API_KEY, DOL_API_KEY — those sources
+ * have no keyless tier, so the tool throws without them (DOL_API_KEY gates ONLY
+ * dol_get_dataset; the DOL catalog, dol_list_datasets, is keyless). OPTIONAL (6):
+ * everything else works keyless; a key only raises a rate limit or unlocks a single filter.
  */
 export const KEY_REGISTRY = [
     {
         envVar: "DATA_GOV_API_KEY",
         sources: [
-            "api.data.gov keyed sources: Regulations.gov, Congress.gov, GovInfo, Federal Audit Clearinghouse (FAC), data.gov catalog",
+            "api.data.gov keyed sources: Regulations.gov, Congress.gov, GovInfo, Federal Audit Clearinghouse (FAC), data.gov catalog, GSA per-diem",
         ],
         required: false,
         signupUrl: "https://api.data.gov/signup/",
@@ -90,6 +92,32 @@ export const KEY_REGISTRY = [
         unlocks: "the 2 FRED tools (there is no keyless tier — they throw without a key)",
         note: "REQUIRED: the FRED API has no keyless access.",
     },
+    {
+        envVar: "BEA_API_KEY",
+        sources: ["BEA Regional Economic Accounts (bea_regional_data)"],
+        required: true,
+        signupUrl: "https://apps.bea.gov/API/signup/",
+        unlocks: "the bea_regional_data tool (there is no keyless tier — it throws without a key)",
+        note: "REQUIRED: the BEA Data API has no keyless access.",
+    },
+    {
+        envVar: "DOL_API_KEY",
+        sources: [
+            "US DOL enforcement data (dol_get_dataset; dol_list_datasets is keyless)",
+        ],
+        required: true,
+        signupUrl: "https://dol.gov/developer",
+        unlocks: "the dol_get_dataset tool (dataset records need a free key; dol_list_datasets works keyless)",
+        note: "The DOL data endpoint needs a free key; the dataset CATALOG (dol_list_datasets) and agency list are keyless.",
+    },
+    {
+        envVar: "LDA_API_KEY",
+        sources: ["US Senate LDA lobbying (lda_search_filings)"],
+        required: false,
+        signupUrl: "https://lda.senate.gov/api/register/",
+        unlocks: "higher LDA API rate limits (anonymous access already works without it)",
+        note: "Keyless by default (anonymous 200); a free token only raises the rate limit.",
+    },
 ];
 /** true iff the env var is set to a non-empty (after-trim) string. */
 function isSet(envVar) {

package/dist/keys.js.map

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

package/dist/lda.d.ts

@@ -0,0 +1,105 @@
+/**
+ * lda.ts — US Senate LDA (Lobbying Disclosure Act) filings — the LOBBYING / B2G
+ * influence lane (ADR-0052). Who is paid HOW MUCH to lobby WHICH federal agency
+ * on WHICH issue — the registrant→client→government-entity signal that no
+ * contract/spending/grant source carries.
+ *
+ * ★ THIS IS A KEYLESS SOURCE WITH AN OPTIONAL KEY (the socrata.ts app-token
+ *   lineage, NOT the census/fred/bea key-required lineage). The LDA REST API
+ *   (lda.senate.gov/api/v1) serves anonymous GETs at HTTP 200 — it works with NO
+ *   key. A free `LDA_API_KEY` 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 socrata's optional `X-App-Token` discipline.
+ *
+ * The module writes ZERO fetch/coercion/error/meta code of its own: it REUSES
+ * `getJson` (the shared fetch envelope, redirect:"error") / `driftError` /
+ * `num`·`str` (coerce.ts, null-never-0/empty) / `withMeta`·`buildMeta`.
+ *
+ *   GET https://lda.senate.gov/api/v1/filings/
+ *       ?filing_year=&filing_type=&registrant_name=&client_name=&lobbyist_name=
+ *        &filing_specific_lobbying_issues=&government_entity=&page=&page_size=
+ *   → { count, next, previous, results:[{ filing_uuid, filing_type,
+ *        filing_type_display, filing_year, filing_period, filing_period_display,
+ *        filing_document_url, income, expenses, dt_posted, termination_date,
+ *        registrant:{name,…}|string, client:{name,…}|string,
+ *        lobbying_activities:[{ general_issue_code, general_issue_code_display,
+ *          description, government_entities:[{ name }] }], … }] }
+ *
+ * ★ HONESTY (ADR-0052 P1–P5):
+ *   [P1]   `count` is the API's REAL total (~1.95M) ⇒ totalAvailable = num(count),
+ *          NEVER results.length. Page-based pagination (page/page_size, 1-based):
+ *          returned = results.length, hasMore = page*pageSize < count, and the next
+ *          page number is surfaced in a note. Reverting totalAvailable to
+ *          results.length must go RED.
+ *   [P2]   getJson → fetchWithRetry taxonomy: a 400 (bad filter/param) ⇒
+ *          invalid_input SURFACING the API's error body (re-read once on the error
+ *          path); a 5xx/timeout ⇒ upstream_unavailable THROW; a 429 ⇒ rate_limited
+ *          THROW honoring Retry-After (NEVER routed around); a genuine no-match
+ *          (results:[]) ⇒ honest empty (returned:0); a 200 non-JSON ⇒ schema_drift.
+ *   [P3]   `income`/`expenses` are null-or-decimal-string ⇒ num() (null ⇒ null — NOT
+ *          reported ≠ 0; a genuine "0" stays 0). A missing `lobbying_activities` /
+ *          `government_entities` ⇒ empty arrays (never fabricated).
+ *   [P4]   `results` non-array or `count` non-number ⇒ driftError (never a
+ *          fabricated empty/total).
+ *   [SSRF] fixed host `lda.senate.gov`; a post-construction hostname/protocol
+ *          assert + `redirect:"error"`; every filter VALUE rides URLSearchParams;
+ *          `filingYear` / `page` / `pageSize` are charclass/range-guarded pre-fetch.
+ */
+import { num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num };
+export declare const LDA_HOST = "lda.senate.gov";
+/**
+ * The optional Authorization header (keyless-first, socrata app-token lineage).
+ * Present ONLY when LDA_API_KEY is set (non-blank); the value is NEVER logged /
+ * never placed in the URL, label, `_meta`, or a note. When unset, `{}` (no header).
+ */
+export declare function ldaAuthHeader(): Record<string, string>;
+/** true iff an LDA API key is configured (for the `_meta` note — never the value). */
+export declare function ldaKeyPresent(): boolean;
+export type LdaLobbyingActivity = {
+    issueCode: string | null;
+    description: string | null;
+    governmentEntities: string[];
+};
+export type LdaFiling = {
+    filingUuid: string | null;
+    filingType: string | null;
+    filingYear: number | null;
+    filingPeriod: string | null;
+    incomeUsd: number | null;
+    expensesUsd: number | null;
+    registrant: string | null;
+    client: string | null;
+    lobbyingActivities: LdaLobbyingActivity[];
+    documentUrl: string | null;
+    postedDate: string | null;
+    terminationDate: string | null;
+};
+/**
+ * The registrant/client value may be an OBJECT carrying `name` (with address
+ * fields) OR a plain string. Defensively resolve either to the display name (or
+ * null when absent) — never fabricate, never surface the whole address object.
+ */
+export declare function nameOf(x: unknown): string | null;
+export type LdaSearchFilingsArgs = {
+    registrantName?: string;
+    clientName?: string;
+    lobbyistName?: string;
+    filingYear?: string;
+    filingType?: string;
+    agency?: string;
+    issue?: string;
+    page?: number;
+    pageSize?: number;
+};
+/**
+ * Search US Senate LDA lobbying filings (`/api/v1/filings/`) → curated filing rows
+ * + honest `_meta`. KEYLESS (an optional LDA_API_KEY only raises the rate limit,
+ * sent as the Authorization header only). ★totalAvailable is the API's REAL `count`
+ * (~1.95M corpus) — never results.length; page-based pagination. income/expenses
+ * null-or-decimal-string → null-never-0.
+ */
+export declare function searchFilings(args: LdaSearchFilingsArgs): Promise<MetaBundle>;
+//# sourceMappingURL=lda.d.ts.map

package/dist/lda.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lda.d.ts","sourceRoot":"","sources":["../src/lda.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;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,mBAAmB,CAAC;AAqBzC;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAItD;AAED,sFAAsF;AACtF,wBAAgB,aAAa,IAAI,OAAO,CAGvC;AAGD,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,kBAAkB,EAAE,mBAAmB,EAAE,CAAC;IAC1C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKhD;AAwCD,MAAM,MAAM,oBAAoB,GAAG;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,UAAU,CAAC,CAyIrB"}