usas_spending_over_time

Instructions

Implementation Reference

• src/server.ts:127-134 (schema)

  Zod schema for usas_spending_over_time input validation: optional group (fiscal_year/quarter/month), agency, naics, setAside.

  const UsasSpendingOverTimeInput = z.object({
    group: z.enum(["fiscal_year", "quarter", "month"]).optional(),
    agency: z.string().optional(),
    naics: z.string().optional(),
    setAside: z
      .enum(["SBA", "8A", "HZS", "SDVOSBC", "WOSB", "EDWOSB", "VSA", "VSS"])
      .optional(),
  });

• src/server.ts:368-374 (registration)

  Tool registration entry in server.ts: name 'usas_spending_over_time', description, and inputSchema reference.

  // ━━━ USAspending — Aggregate Analysis (6) ━━━
  {
    name: "usas_spending_over_time",
    description:
      "Time-series aggregation of federal spending. Group by fiscal_year / quarter / month, filter by agency / NAICS / set-aside. Use for 'how has VA 541512 spending trended over the past 5 years' — returns yearly/quarterly/monthly $ rollups.",
    inputSchema: UsasSpendingOverTimeInput,
  },

• src/usaspending.ts:409-440 (handler)

  Handler function spendingOverTime that POSTs to USAspending search/spending_over_time/ and returns timeline data with timePeriod, total, contractObligations, grantObligations, idvObligations.

  export async function spendingOverTime(args: {
    group?: "fiscal_year" | "quarter" | "month";
    agency?: string;
    naics?: string;
    setAside?: string;
  }) {
    const filters = buildFilters(args);
    type Resp = {
      group?: string;
      results?: {
        time_period?: { fiscal_year?: string; quarter?: string; month?: string };
        aggregated_amount?: number;
        Contract_Obligations?: number;
        Grant_Obligations?: number;
        Idv_Obligations?: number;
      }[];
    };
    const json = await postUsas<Resp>("search/spending_over_time/", {
      group: args.group ?? "fiscal_year",
      filters,
    });
    return {
      group: json.group,
      timeline: (json.results ?? []).map((r) => ({
        timePeriod: r.time_period ?? {},
        total: r.aggregated_amount ?? 0,
        contractObligations: r.Contract_Obligations ?? 0,
        grantObligations: r.Grant_Obligations ?? 0,
        idvObligations: r.Idv_Obligations ?? 0,
      })),
    };
  }

• src/server.ts:709-712 (handler)

  Switch-case dispatch in server.ts that routes 'usas_spending_over_time' to usas.spendingOverTime() with parsed args.

  case "usas_spending_over_time":
    return await usas.spendingOverTime(
      UsasSpendingOverTimeInput.parse(args),
    );

• src/usaspending.ts:42-67 (helper)

  buildFilters helper used by spendingOverTime to construct USAspending API filter objects from args (agency, naics, setAside).

  function buildFilters(args: {
    agency?: string;
    naics?: string;
    fiscalYear?: number;
    setAside?: string;
    pscCodes?: string[];
  }): UsasFilters {
    const filters: UsasFilters = { award_type_codes: ["A", "B", "C", "D"] };
    if (args.agency) {
      filters.agencies = [
        { type: "awarding", tier: "toptier", name: args.agency },
      ];
    }
    if (args.naics) filters.naics_codes = [args.naics];
    if (args.fiscalYear) {
      filters.time_period = [
        {
          start_date: `${args.fiscalYear - 1}-10-01`,
          end_date: `${args.fiscalYear}-09-30`,
        },
      ];
    }
    if (args.setAside) filters.set_aside_type_codes = [args.setAside];
    if (args.pscCodes?.length) filters.psc_codes = args.pscCodes;
    return filters;
  }