feat(node): full API + Python-SDK parity (84 methods, retries, signing, iterators)

[makegov-hal]

Summary

Brings @makegov/tango-node to full feature parity with both the Tango API and tango-python. Every method on tango_python.TangoClient now has an idiomatic camelCase counterpart on TangoClient. Adds retry-with-backoff, async iterator pagination, webhook signing helpers, and TANGO_BASE_URL env fallback along the way. Branch is 16 commits ahead of main.

• 84 public methods on TangoClient (up from ~30 on main)
• 111 unit tests pass (up from 56 on main); 82% line coverage
• Live smoke against a running Tango: every new method exercised end-to-end (scripts/smoke-*.ts), zero leaked resources
• No breaking changes — every signature change is additive

What's new

API parity — read methods

The Node SDK was missing list/get methods for ~half the Tango API surface. Now covered:

• Lookups: listNaics/getNaics, listPsc/getPsc, listMasSins/getMasSin, listAssistanceListings/getAssistanceListing, listOrganizations/getOrganization, listOffices/getOffice, listDepartments/getDepartment, getBusinessType
• Awards completeness: listOtas/getOta, listOtidvs/getOtidv/listOtidvAwards, listSubawards, listGsaElibraryContracts, listLcats (accepts { uei } or { idvKey })
• Other: listProtests/getProtest, listItDashboard/getItDashboard, listMetrics, resolve, validate

API parity — typed metrics wrappers

tango-python exposes typed metric methods scoped to each owner type; Node now matches:

• getEntityMetrics(uei, months, periodGrouping)
• getNaicsMetrics(code, months, periodGrouping)
• getPscMetrics(code, months, periodGrouping)

(The generic listMetrics({ ownerType, ownerId, months, periodGrouping }) from the reads branch is preserved for low-level use.)

API parity — entity, IDV, agency sub-resources

• Entity: listEntityContracts, listEntityIdvs, listEntityOtas, listEntityOtidvs, listEntitySubawards, listEntityLcats
• IDV: listIdvLcats (typed sibling of the generic listLcats({ idvKey }))
• Agency: listAgencyAwardingContracts, listAgencyFundingContracts

Webhook write API

• Subscriptions: createWebhookSubscription, updateWebhookSubscription, deleteWebhookSubscription. Accepts the canonical Tango payload shape (subscription_name, subscription_type, endpoint, query_type, filter_definition, …) and a legacy { subscriptionName, payload } camelCase shape for backward compatibility.
• Endpoints: createWebhookEndpoint (name is first-class — defaults to URL host if omitted), updateWebhookEndpoint, deleteWebhookEndpoint. testWebhookEndpoint(endpointId) is the canonical method (the API's body key is endpoint_id — see makegov/tango#2252); testWebhookDelivery kept as a legacy alias.
• Alerts (filter-subscription convenience): listWebhookAlerts, getWebhookAlert, createWebhookAlert, updateWebhookAlert, deleteWebhookAlert. Note: multi-endpoint accounts hit a 400 from the backend on createWebhookAlert — tracked at makegov/tango#2256.

New typed input interfaces exported from the package root: WebhookSubscriptionCreateInput, WebhookSubscriptionUpdateInput, WebhookEndpointCreateInput, WebhookEndpointUpdateInput, WebhookAlertCreateInput, WebhookAlert, plus options types for the new sub-resources.

Webhook signing helpers

Three standalone functions, exported from the package root (no TangoClient required):

• verifySignature(body, header, secret) — constant-time HMAC-SHA256 verification. Accepts "sha256=<hex>" and bare-hex forms. Returns boolean, never throws.
• generateSignature(body, secret) — emits "sha256=<hex>" matching the dispatcher format.
• parseSignatureHeader(header) — returns { algorithm, signature } | null for clean branching in receivers.

Mirrors tango_python.webhooks.signing byte-for-byte; the unit tests are ported from there.

Async iterator pagination

For convenience, list methods now have async-iterator wrappers that handle next / cursor for you:

for await (const contract of client.iterateContracts({ awarding_agency: "9700" })) {
  console.log(contract.piid, contract.total_contract_value);
}

Typed iterators: iterateContracts, iterateEntities, iterateOpportunities, iterateNotices, iterateGrants, iterateForecasts, iterateIdvs, iterateVehicles. Sequential (no concurrent requests) to respect rate limits.

Retry with exponential backoff

HttpClient now retries failed requests automatically:

• Retries on 5xx, 408, 429, network errors, client-side timeouts
• Does not retry on other 4xx — surfaces as the appropriate Tango* error
• Exponential backoff: base retryBackoffMs (default 250ms), doubled per attempt, capped at 10s
• Honors Retry-After headers (delta-seconds and HTTP-date) on 429/503

Constructor surface

new TangoClient({
  apiKey: process.env.TANGO_API_KEY,   // optional if TANGO_API_KEY env is set
  baseUrl: "https://tango.makegov.com", // optional if TANGO_BASE_URL env is set
  timeoutMs: 30_000,                    // existing
  timeout: 30_000,                      // NEW — shorthand alias; timeoutMs wins if both
  retries: 3,                           // NEW
  retryBackoffMs: 250,                  // NEW
  fetchImpl: customFetch,               // existing
});

TANGO_BASE_URL env fallback

When baseUrl is not passed and process.env.TANGO_BASE_URL is set, the client uses that — parity with TANGO_API_KEY. Useful for .env-driven local/staging configs.

Misc

• searchOpportunityAttachments, getVersion, listApiKeys round out parity with the Python SDK's introspection / search surface.

Fixed

• ShapeConfig.IDVS_COMPREHENSIVE no longer includes base_and_exercised_options_value, which is not a valid IDV shape field — the API was returning 400 Invalid shape on this preset. Now aligned with tango_python.IDVS_COMPREHENSIVE. Also reconciled recipient.cage_code → recipient.cage to match the Python preset exactly.

Testing

• npm test (vitest): 111/111 pass, 16 test files (up from 51 / 9 files on main). New test files: tests/unit/{client.parity,client.iterate,client.baseurl,webhooks.signing,config.shapes}.test.ts.
• npm run coverage: 82.04% lines / 74.08% branches / 73.79% functions.
• npm run build: clean tsc compile.
• Smoke harnesses at scripts/smoke-{reads,writes,extras,parity}.ts. Each requires TANGO_API_KEY in env (hard-fails if unset — no fallback). Latest runs against http://localhost:8000: smoke-reads 27/27, smoke-writes 8/8, smoke-extras 8/8, smoke-parity 19/21 (2 environmental: searchOpportunityAttachments 404 locally; createWebhookAlert hit by the multi-endpoint tango#2256 issue).

Decisions worth flagging

• parseSignatureHeader returns { algorithm, signature } instead of a bare string — small ergonomic upgrade over Python's bare-string return. algorithm defaults to "sha256" when callers pass a legacy bare-hex value.
• verifySignature arg order is (body, header, secret) (header before secret) to match TS conventions. Different from Python's (body, secret, signature_header).
• Async iteration is sequential, not concurrent — Tango rate limits would punish concurrent pagination anyway.
• Iterator parses ?cursor= from next before ?page=; cursor wins if both are present.

Known issues tracked on tango (not blockers)

• makegov/tango#2252 — endpoint vs endpoint_id field-name inconsistency.
• makegov/tango#2254 — OpenAPI advertises ordering on /notices/, /protests/, /subawards/ but viewsets reject most values.
• makegov/tango#2256 — /api/webhooks/alerts/ should accept an explicit endpoint field so multi-endpoint accounts can use the convenience wrapper.

Risks

• No public API removed. Existing methods unchanged. Existing options preserved. Behaviorally additive.
• Retry default is 3 — a small risk that previously-loud transient failures now retry silently. Set retries: 0 to opt out.
• Hardcoded API key strings in smoke scripts were scrubbed via git filter-branch before push — branch history is clean.

Sibling work

Companion PR in tango-python covers the same parity work for the Python SDK. Docs in makegov/docs#9 are updated for both SDKs' new surfaces.

– Hal 🤖

[Copilot]

Pull request overview

This PR expands @makegov/tango-node to near-complete Tango API and tango-python parity by adding a large set of new TangoClient methods, plus SDK “quality-of-life” features (retries, async iterators, webhook signing helpers) and supporting tests/smoke scripts.

Changes:

• Added many missing read APIs, sub-resource APIs, typed metrics helpers, and webhook alert/subscription/endpoint write APIs to TangoClient.
• Introduced HttpClient retry-with-exponential-backoff (with Retry-After support), async-iterator pagination helpers, and TANGO_BASE_URL constructor fallback.
• Added webhook HMAC signing utilities and significantly expanded unit + smoke coverage, plus a ShapeConfig fix for IDVS_COMPREHENSIVE.

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/unit/webhooks.signing.test.ts	Adds unit tests for new webhook signing helpers.
tests/unit/utils.http.test.ts	Updates/extends HttpClient tests to cover retries/backoff behavior.
tests/unit/config.shapes.test.ts	Adds regression tests for ShapeConfig.IDVS_COMPREHENSIVE.
tests/unit/client.parity.test.ts	Adds unit tests for newly added Python-parity client methods.
tests/unit/client.iterate.test.ts	Adds tests for async iterator pagination (page/cursor/break handling).
tests/unit/client.baseurl.test.ts	Adds tests for TANGO_BASE_URL constructor fallback precedence.
src/webhooks/signing.ts	Implements generateSignature, verifySignature, parseSignatureHeader, and related constants.
src/utils/http.ts	Adds retry/backoff logic and Retry-After parsing to the HTTP client.
src/types.ts	Extends TangoClientOptions with timeout alias and retry settings.
src/models/Webhooks.ts	Adds/extends webhook-related models and new typed create/update inputs.
src/models/index.ts	Re-exports newly added webhook model/input types.
src/index.ts	Re-exports new client option types and webhook signing helpers from package root.
src/config.ts	Fixes ShapeConfig.IDVS_COMPREHENSIVE fields to match API/Python preset.
src/client.ts	Major expansion: new parity methods, webhook CRUD, iterators, base URL fallback, retry options wiring.
scripts/smoke-writes.ts	Adds live smoke harness for webhook write APIs.
scripts/smoke-reads.ts	Adds live smoke harness for newly added read-only parity methods.
scripts/smoke-parity.ts	Adds live smoke harness for parity methods (incl. webhook alerts CRUD).
scripts/smoke-extras.ts	Adds live smoke harness for signing helpers, iteration, and base URL env fallback.
CHANGELOG.md	Documents the new parity surface, retries, iterators, signing helpers, and fixes.
.gitignore	Ignores .worktrees/.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated 8 comments.