[makegov-hal]

What

Adds Tango's financial-assistance award endpoints (Tango API 5.12.0) to the Node SDK: USAspending's grant, loan, direct-payment and other assistance awards under /api/assistance/.

Per group (Grant(s), Loan(s), DirectPayment(s), Other):

Route	Method
GET /api/assistance/{group}/	listAssistanceGrants(options) — cursor-paginated, shaped, every filter typed
GET /api/assistance/{group}/{key}/	getAssistanceGrant(key, options) — shaped
GET /api/assistance/{group}/{key}/transactions/	listAssistanceGrantTransactions(key, options) — page-numbered, 100 default / 500 max
GET /api/assistance/{group}/{key}/listings/	listAssistanceGrantListings(key, options) — page-numbered, 100 max
(iterator)	iterateAssistanceGrants(options)

• ListAssistanceAwardsOptions types all 30 of the API's filters under the API's own names: the contract filters assistance inherits (key, uei, recipient, awarding_agency, funding_agency, the award_date / fiscal_year / pop_start_date / pop_end_date ranges) plus fain, uri, cfda_number, assistance_type, record_type, business_funds_indicator, disaster_emergency_fund_code, funding_opportunity_number, pop_state, pop_country, pop_zip, obligated_gte / obligated_lte, search and ordering. No SDK-side aliases (no keyword / recipient_uei / sort+order remaps like the legacy contract options carry).
• One AssistanceAward model interface (plus AssistanceRecipient, AssistanceTransaction, AssistanceAwardListing, etc.) and one registered shape schema serve all four groups, since the API gives them one shape. It covers every field and expand in the contract.
• ShapeConfig.ASSISTANCE_AWARDS_MINIMAL is the API's own default shape, character for character.
• Re-vendors contracts/filter_shape_contract.json from 5.11.0 to 5.12.1 (tango main, matching prod). The four assistance resources are the only difference.
• Naming follows the SDK's majority convention for paginated sub-resources (list*, like listIdvTransactions / listEntityContracts), not the older getContractTransactions.

Why

The assistance API is live in prod at 5.12.1 and the SDK had no way to reach it.

Testing

• npx vitest run: 621 passed across 56 files, including 43 new unit tests (tests/unit/client.assistance.test.ts) and 4 new cassette-replayed integration tests (tests/integration/assistance.test.ts, cassettes recorded against prod).
• npm run lint, npm run typecheck, npm run build: clean.
• npm run check-conformance: 0 errors, and no assistance warnings (every filter is a typed member, so none fall back to the index signature). npm run check-shape-coverage: 0 new gaps, no baseline growth. Mutation-checked: a fake field injected into the assistance shape trees is reported as a new gap.
• npm run generate-shape-overlay: regenerates with no diff.
• A throwaway live smoke against prod exercised all 16 methods plus a filtered/flat list and an iterator across pages: 22/22 pass, including a full every-field-and-expand shape on each group's detail route.

Risks

• Additive only; no existing method or type changes.
• 🚨 The API is inconsistent on transactions[].action_date_fiscal_year: a number on the /transactions/ sub-route, a string ("2027") inside the transactions(...) expand. OpenAPI says integer. The SDK types it number | string and passes it through as served.
• 🚨 disaster_emergency_fund_code=L matched an award whose disaster_emergency_fund_codes is "AAK: Emergency P.L. 118-158": the API's whole-code regex treats the L in P.L. as a code. That's an API-side filter bug, not an SDK one; the field itself is free text, not a list, and the SDK types it as a string.

Next steps

• Sibling SDKs (tango-python, tango-go, tango-rust) are being done in parallel; this PR's method names were shared with the Python agent for parity.

🤖 Generated with Claude Code