@cliwant/mcp-sam-gov 1.3.0 → 1.5.0

package/src/treasury.ts

@@ -83,6 +83,13 @@ export const TREASURY_DATASETS = {
   mts_table_1: "/v1/accounting/mts/mts_table_1",
   rates_of_exchange: "/v1/accounting/od/rates_of_exchange",
   debt_outstanding: "/v2/accounting/od/debt_outstanding",
+  // interest_expense = ACTUAL interest PAID on the debt (debt-service cost by
+  // security type), distinct from avg_interest_rates (rates only). LIVE-VERIFIED
+  // 2026-07-16 (total-count 7245, truthful pagination). tror = the Treasury Report
+  // on Receivables — federal receivables + delinquent-debt collections BY AGENCY
+  // (debt-collection contracting / agency financial-management signal; total 3953).
+  interest_expense: "/v2/accounting/od/interest_expense",
+  tror: "/v2/debt/tror",
 } as const;
 
 export type TreasuryDatasetKey = keyof typeof TREASURY_DATASETS;

package/src/usaspending.ts

@@ -39,6 +39,31 @@ const USAS = "https://api.usaspending.gov/api/v2";
 
 export type UsasFilters = Record<string, unknown>;
 
+/**
+ * Build the awarding-agency filter for spending_by_category / spending_by_award —
+ * ALWAYS a canonical NAME match. A purely-numeric value is a toptier CODE (e.g.
+ * "036"), which the sibling code-based tools (usas_get_agency_profile /
+ * usas_get_agency_budget_function) take but which silently matches NOTHING here —
+ * returning a confidently-wrong empty (e.g. "VA had $0 subagency spending" when VA
+ * actually has $66.87B). Fail loud instead of faking a zero (dogfooding 2026-07-16;
+ * same confidently-wrong-empty class as the subaward drift). No real agency NAME is
+ * purely numeric, so the /^\d+$/ test never rejects a legitimate name.
+ */
+function awardingAgencyFilter(
+  agency: string,
+): { type: string; tier: string; name: string }[] {
+  if (/^\d+$/.test(agency.trim())) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `agency ${JSON.stringify(
+        agency,
+      )} looks like a toptier CODE, but this filter matches the canonical agency NAME (e.g. "Department of Veterans Affairs") — a code silently matches nothing here and would return a false empty. Resolve the name via usas_lookup_agency or usas_list_toptier_agencies, or use a code-based tool (usas_get_agency_profile / usas_get_agency_budget_function) that takes a toptierCode.`,
+    });
+  }
+  return [{ type: "awarding", tier: "toptier", name: agency }];
+}
+
 function buildFilters(args: {
   agency?: string;
   naics?: string;
@@ -48,9 +73,7 @@ function buildFilters(args: {
 }): UsasFilters {
   const filters: UsasFilters = { award_type_codes: ["A", "B", "C", "D"] };
   if (args.agency) {
-    filters.agencies = [
-      { type: "awarding", tier: "toptier", name: args.agency },
-    ];
+    filters.agencies = awardingAgencyFilter(args.agency);
   }
   if (args.naics) filters.naics_codes = [args.naics];
   if (args.fiscalYear) {
@@ -180,6 +203,20 @@ function categoryAggregateMeta(opts: {
       `Capped at the top ${opts.limit} categories by amount; more categories may exist. This endpoint reports no grand total, so the true number of categories is unknown (totalAvailable is null, NOT the returned count). These extra categories are NOT page-reachable — all six callers post page:1 with NO offset/page input (nextOffset is null). Raise limit (up to 50) or narrow filters to see the rest.`,
     );
   }
+  // Confidently-wrong-empty guard (dogfooding 2026-07-16): a SET agency filter that
+  // yields ZERO rows is ambiguous — a genuine zero OR a NAME that didn't match the
+  // exact canonical toptier name (an abbreviation / mis-case / partial / typo
+  // silently matches nothing on this NAME filter, so "$0" reads as authoritative
+  // when the name simply missed). Disclose the ambiguity. (A numeric CODE is already
+  // loud-failed by awardingAgencyFilter; this catches the wrong-NAME residual.)
+  const agencyFilterSet =
+    Array.isArray((opts.filters as { agencies?: unknown[] } | undefined)?.agencies) &&
+    (((opts.filters as { agencies?: unknown[] }).agencies?.length ?? 0) > 0);
+  if (agencyFilterSet && opts.returned === 0) {
+    notes.push(
+      `The agency filter matched NO records. This filter requires the EXACT canonical toptier agency NAME (e.g. "Department of Veterans Affairs"): an abbreviation, mis-cased, partial, or mistyped name silently matches nothing here. Verify the exact name via usas_list_toptier_agencies or usas_lookup_agency. If the name is correct, this is a genuine zero for this slice.`,
+    );
+  }
   if (opts.extraNotes) notes.push(...opts.extraNotes);
   return {
     source: opts.source,
@@ -672,20 +709,24 @@ export async function searchAwardsByRecipient(args: {
 // ─── Subaward enumeration ─────────────────────────────────────────
 
 export async function searchSubawards(args: {
-  primeRecipientName?: string;
+  subRecipientName?: string;
   agency?: string;
   naics?: string;
   fiscalYear?: number;
   limit?: number;
 }) {
   const filters = buildFilters(args);
-  if (args.primeRecipientName) {
-    filters.recipient_search_text = [args.primeRecipientName];
+  // recipient_search_text on a subawards spending_by_award search matches the
+  // SUBAWARDEE name (live-verified 2026-07-16), so this param is subRecipientName —
+  // NOT a prime filter (the old `primeRecipientName` name was inverted).
+  if (args.subRecipientName) {
+    filters.recipient_search_text = [args.subRecipientName];
   }
   type Resp = {
     results?: {
       "Sub-Award ID"?: string;
       "Sub-Award Recipient"?: string;
+      "Sub-Awardee Name"?: string;
       "Sub-Award Amount"?: number;
       "Sub-Award Date"?: string;
       NAICS?: { code?: string; description?: string };
@@ -705,6 +746,13 @@ export async function searchSubawards(args: {
       filters,
       fields: [
         "Sub-Award ID",
+        // DRIFT FIX (dogfooding 2026-07-15): USAspending's spending_by_award now
+        // returns the subawardee under "Sub-Awardee Name"; the legacy
+        // "Sub-Award Recipient" field is still echoed but is ALWAYS null. Request
+        // BOTH and prefer the live one (the endpoint echoes an unknown field as
+        // null, so requesting both is safe). Without this, every subRecipient was
+        // silently null — the supply-chain/teaming lane could not name any sub.
+        "Sub-Awardee Name",
         "Sub-Award Recipient",
         "Sub-Award Amount",
         "Sub-Award Date",
@@ -720,13 +768,13 @@ export async function searchSubawards(args: {
   const data = {
     subawards: results.map((r) => ({
       subAwardId: r["Sub-Award ID"] ?? "",
-      // minor m2 (W3-1 honesty): an ABSENT Sub-Award Recipient → null, NOT a
-      // fabricated "(name redacted)". The old sentinel asserted a specific PRIVACY
-      // reason on ANY nullish value (schema gap / null echo / genuine redaction
-      // alike) — internally inconsistent with the null-never-fabricate discipline
-      // this same function applies to `amount` below. Honest null; the caller
-      // reads absence, not an invented redaction cause.
-      subRecipient: r["Sub-Award Recipient"] ?? null,
+      // The subawardee name — read from the CURRENT field "Sub-Awardee Name",
+      // falling back to the legacy "Sub-Award Recipient" (now always null upstream).
+      // A genuinely absent name in BOTH ⇒ null (honest absence, never a fabricated
+      // "(name redacted)" — consistent with the null-never-fabricate discipline
+      // `amount` uses below).
+      subRecipient:
+        r["Sub-Awardee Name"] ?? r["Sub-Award Recipient"] ?? null,
       // F2 (P3 null-never-0): an ABSENT Sub-Award Amount → null, NEVER a
       // fabricated $0. A genuine 0 still survives (`??` fires only on null).
       amount: r["Sub-Award Amount"] ?? null,
@@ -1364,7 +1412,7 @@ export async function searchRecompetes(args: {
   const filtersApplied: string[] = ["awardType(contracts A/B/C/D)"];
   const filtersDropped: string[] = [];
   if (args.agency) {
-    filters.agencies = [{ type: "awarding", tier: "toptier", name: args.agency }];
+    filters.agencies = awardingAgencyFilter(args.agency);
     filtersApplied.push("agency");
   }
   if (args.naics) {
@@ -1730,6 +1778,20 @@ export async function spendingOverTime(args: {
       `Completeness for group='${group}': this endpoint returns no pagination envelope, and no-truncation is verified only for fiscal_year granularity — a very long ${group} series could in principle be capped server-side without a signal. Confirm the span (${spanStart ?? "?"} … ${spanEnd ?? "?"}) covers your expected range.`,
     );
   }
+  // Confidently-wrong-empty guard (dogfooding 2026-07-16): a SET agency filter that
+  // yields an ALL-ZERO timeline is ambiguous — a genuine zero OR a NAME that missed
+  // the exact canonical toptier name (an abbreviation / mis-case / typo silently
+  // matches nothing, producing a false "$0 every period" that reads as authoritative
+  // "this agency never spent on X"). Disclose it. (A numeric CODE is already
+  // loud-failed by awardingAgencyFilter; this catches the wrong-NAME residual.)
+  if (
+    args.agency &&
+    (timeline.length === 0 || timeline.every((t) => t.total === 0))
+  ) {
+    notes.push(
+      `The agency filter produced an ALL-ZERO timeline. This filter requires the EXACT canonical toptier agency NAME (e.g. "Department of Veterans Affairs"): an abbreviation, mis-cased, partial, or mistyped name silently matches nothing, yielding a false "$0 in every period". Verify the exact name via usas_list_toptier_agencies or usas_lookup_agency. If the name is correct, the agency genuinely had no CONTRACT obligations in this span.`,
+    );
+  }
 
   return withMeta(
     { group: json.group ?? group, timeline },
@@ -1842,9 +1904,7 @@ export async function searchCfdaSpending(args: {
     award_type_codes: ["02", "03", "04", "05"], // grants
   };
   if (args.agency) {
-    filters.agencies = [
-      { type: "awarding", tier: "toptier", name: args.agency },
-    ];
+    filters.agencies = awardingAgencyFilter(args.agency);
   }
   if (args.fiscalYear) {
     filters.time_period = [
@@ -2625,6 +2685,118 @@ export async function glossary(args: { limit?: number; search?: string }) {
   });
 }
 
+// ─── Disaster / emergency-fund spending (DEFC axis) ───────────────
+/**
+ * List the Disaster Emergency Fund Codes (DEFC) — the supplemental-appropriation
+ * tags (COVID-19 relief, IIJA/infrastructure, and other emergency laws) that
+ * usas_disaster_spending filters on. GET references/def_codes/ (keyless). Returns the
+ * COMPLETE code set (no pagination), each with `group` ('covid_19' | 'infrastructure'
+ * | null), title, and public law. Discovery front-door for usas_disaster_spending.
+ */
+export async function listDisasterCodes() {
+  return memoize("usas:def_codes", async () => {
+    type Resp = {
+      codes?: {
+        code?: string;
+        disaster?: string | null;
+        title?: string;
+        public_law?: string;
+      }[];
+    };
+    const json = await getUsas<Resp>("references/def_codes/");
+    const results = json.codes ?? [];
+    const codes = results.map((c) => ({
+      code: c.code ?? "",
+      // The supplemental-law GROUP: 'covid_19' (COVID relief), 'infrastructure'
+      // (IIJA), or null (other emergency appropriations). NOT fabricated when absent.
+      group: c.disaster ?? null,
+      title: c.title ?? "",
+      publicLaw: typeof c.public_law === "string" ? c.public_law : null,
+    }));
+    return withMeta(
+      { codes },
+      referenceMeta({
+        source: "usaspending.gov/api/v2 references/def_codes",
+        returned: codes.length,
+        limit: codes.length,
+        totalAvailable: codes.length,
+        // The endpoint takes no `limit` and returns the COMPLETE DEFC set → complete.
+        limitHonored: false,
+        extraNotes: [
+          "Complete list of Disaster Emergency Fund Codes (DEFC). group 'covid_19' = COVID-19 relief appropriations; 'infrastructure' = IIJA (Infrastructure Investment and Jobs Act); null = other supplemental/emergency appropriations. Pass one or more `code` values to usas_disaster_spending's `defCodes` to see spending tagged to those funds.",
+        ],
+      }),
+    );
+  });
+}
+
+/**
+ * Disaster / emergency-fund spending BY GEOGRAPHY — obligations or outlays tagged to
+ * one or more Disaster Emergency Fund Codes (DEFC: COVID-19, IIJA, etc.), broken out
+ * per state / county / congressional district. POST disaster/spending_by_geography/
+ * (keyless). Answers "which geographies captured COVID/IIJA relief money" — a
+ * distinct axis the standard award search does not expose. `defCodes` REQUIRED
+ * (discover them via usas_list_disaster_codes). The geography endpoint returns the
+ * COMPLETE set of geo units (no pagination) ⇒ totalAvailable = returned, complete.
+ * amount/perCapita are number|null (a real 0 stays 0 — some DEFCs report $0
+ * obligations with a nonzero awardCount; absent → null, never a fabricated 0).
+ */
+export async function disasterSpending(args: {
+  defCodes: string[];
+  spendingType?: "obligation" | "outlay";
+  geoLayer?: "state" | "county" | "district";
+}): Promise<MetaBundle> {
+  const spendingType = args.spendingType ?? "obligation";
+  const geoLayer = args.geoLayer ?? "state";
+  type Resp = {
+    geo_layer?: string;
+    results?: {
+      amount?: number;
+      display_name?: string;
+      shape_code?: string;
+      population?: number | null;
+      per_capita?: number;
+      award_count?: number;
+    }[];
+  };
+  const json = await postUsas<Resp>("disaster/spending_by_geography/", {
+    filter: { def_codes: args.defCodes },
+    spending_type: spendingType,
+    geo_layer: geoLayer,
+  });
+  const results = json.results ?? [];
+  // null-never-0: a real 0 (a DEFC that obligated nothing in that geo) stays 0; an
+  // absent/non-number amount is null (never a fabricated 0).
+  const nn = (v: unknown): number | null => (typeof v === "number" ? v : null);
+  const geographies = results.map((r) => ({
+    name: r.display_name ?? "",
+    code: r.shape_code ?? null,
+    amount: nn(r.amount),
+    awardCount: nn(r.award_count),
+    population: nn(r.population),
+    perCapita: nn(r.per_capita),
+  }));
+  return withMeta(
+    { spendingType, geoLayer, defCodes: args.defCodes, geographies },
+    {
+      source: "usaspending.gov/api/v2 disaster/spending_by_geography",
+      keylessMode: true,
+      returned: geographies.length,
+      // The endpoint returns EVERY geo unit for the layer (no cursor/paging) → the
+      // returned set IS complete; totalAvailable = returned, never a fabricated cap.
+      totalAvailable: geographies.length,
+      truncated: false,
+      filtersApplied: ["defCodes", "spendingType", "geoLayer"],
+      filtersDropped: [],
+      notes: [
+        "Spending tagged to the given Disaster Emergency Fund Codes (DEFC), per geography. amount/perCapita are number|null (a real 0 stays 0; absent → null).",
+        "obligation vs outlay differ: some DEFCs (e.g. IIJA/infrastructure) report $0 OBLIGATIONS by geography while awardCount is nonzero — a $0 with awards is NOT 'no activity'; try spendingType:'outlay' and read awardCount alongside the amount.",
+        "This returns the COMPLETE set of geo units for the layer (no pagination) — totalAvailable is the returned count, not a fabricated total.",
+      ],
+    } satisfies Partial<ResponseMeta>,
+  );
+}
+
 export async function listToptierAgencies(args: { limit?: number }) {
   const limit = args.limit ?? 50;
   return memoize(`usas:toptier:${limit}`, async () => {