Tango Rust SDK

Official, async-first Rust SDK for the Tango API — federal contracts, IDVs, entities, opportunities, grants, vehicles, and more, with dynamic response shaping so you fetch only the fields you need.

Pre-1.0 — v0.3.1. The resource surface now tracks the sibling SDKs endpoint for endpoint, but the public API may still shift before v1.0.0. Pin to a specific version if you depend on this in production.

The sibling SDKs are tango-python, tango-node and tango-go. This Rust port ships the full transport, error model, retry / rate-limit handling, webhook signing (in the separate tango-webhooks crate), and the resource-method surface. Same 0.x → 1.0 graduation logic as Go: the transport and types are stable; the surface stabilizes once it has been verified against the live API alongside the siblings.

Features

• Async-first — built on tokio + reqwest. One runtime, clean futures::Stream-based pagination.
• Dynamic response shaping — request exactly the fields you need via 34 built-in SHAPE_* presets or a custom comma-separated field list.
• Typed errors — single Error enum with rich payload variants (Auth, NotFound, Validation, RateLimit, Timeout, Api, Transport, Decode, Build). Programmatic dispatch via err.status() and err.is_retryable().
• Smart retries — automatic backoff on 5xx / 408 / 429 / transport errors, honoring the server's Retry-After header.
• Compile-time-checked client builder — via bon. Missing api_key? Won't compile.
• Async pagination — PageStream<T> implements futures::Stream. Yields one item at a time, fetches successive pages automatically.
• Forward-compatible models — every typed model carries #[serde(flatten)] extra: HashMap<String, Value> so a server-side schema addition surfaces in record.extra["new_field"] rather than being silently dropped.
• Webhook signing — in the separate makegov-tango-webhooks crate: zero transport deps, HMAC-SHA256 verification, constant-time via subtle.

Installation

[dependencies]
makegov-tango = "0.3"

# Optional: webhook signing for receivers
makegov-tango-webhooks = "0.3"

Crates publish under the makegov- prefix on crates.io; Rust imports stay short — use tango::Client; and use tango_webhooks::verify; — thanks to a [lib] name shim in each crate (same pattern as the aws-sdk-* family).

Requires Rust 1.80 or later.

Quick start

use tango::Client;
use futures::TryStreamExt;

#[tokio::main]
async fn main() -> tango::Result<()> {
    let client = Client::builder().api_key("your-api-key").build()?;

    // Single page
    let page = client.list_contracts(
        tango::ListContractsOptions::builder()
            .awarding_agency("9700")
            .shape(tango::SHAPE_CONTRACTS_MINIMAL)
            .limit(25u32)
            .build(),
    ).await?;
    for record in page.results {
        println!("{:?}", record.get("piid"));
    }

    // Walk every page as a stream
    let mut stream = client.iterate_contracts(
        tango::ListContractsOptions::builder()
            .awarding_agency("9700")
            .fiscal_year("2025")
            .build(),
    );
    while let Some(record) = stream.try_next().await? {
        println!("{:?}", record.get("piid"));
    }

    Ok(())
}

Get a typed agency

get_agency returns the typed AgencyRecord; forward-compatible fields land in agency.extra.

# use tango::Client;
# async fn run() -> tango::Result<()> {
# let client = Client::builder().api_key("x").build()?;
let agency = client.get_agency("9700", None).await?;
println!("{}", agency.name.unwrap_or_default());
# Ok(()) }

Get a fully-shaped entity

# use tango::{Client, GetEntityOptions, SHAPE_ENTITIES_COMPREHENSIVE};
# async fn run() -> tango::Result<()> {
# let client = Client::builder().api_key("x").build()?;
let entity = client.get_entity(
    "ABC123DEF456",
    Some(GetEntityOptions::builder().shape(SHAPE_ENTITIES_COMPREHENSIVE).build()),
).await?;
# Ok(()) }

Authentication

Pass an API key via Client::builder().api_key(...), or set TANGO_API_KEY in the environment and call Client::from_env(). You can also override the base URL via TANGO_BASE_URL for staging environments, or via the builder:

# use tango::Client;
# async fn run() -> tango::Result<()> {
let client = Client::builder()
    .api_key("your-key")
    .base_url("https://staging.tango.makegov.com".to_string())
    .build()?;
# Ok(()) }

Core concepts

Dynamic response shaping

Every list and get endpoint accepts a shape parameter selecting which fields the API returns. The SDK ships 34 presets matching the Node, Python, and Go SDKs:

# use tango::{Client, ListContractsOptions, SHAPE_CONTRACTS_MINIMAL};
# async fn run() -> tango::Result<()> {
# let client = Client::builder().api_key("x").build()?;
// Preset:
let page = client.list_contracts(
    ListContractsOptions::builder().shape(SHAPE_CONTRACTS_MINIMAL).build(),
).await?;

// Custom:
let page = client.list_contracts(
    ListContractsOptions::builder()
        .shape("key,piid,recipient(uei,display_name)")
        .build(),
).await?;
# Ok(()) }

See docs/SHAPES.md for the full grammar and the available presets.

Pagination

List endpoints support both page-based and cursor-based pagination. Page<T> exposes the next URL plus the extracted cursor for keyset endpoints:

# use tango::{Client, ListIDVsOptions};
# async fn run() -> tango::Result<()> {
# let client = Client::builder().api_key("x").build()?;
let page = client.list_idvs(ListIDVsOptions::builder().limit(50u32).build()).await?;
// Fetch the next page:
let next_page = client.list_idvs(
    ListIDVsOptions::builder().limit(50u32).cursor(page.cursor.unwrap_or_default()).build()
).await?;
# Ok(()) }

page.count is the total across every page. Past 1,000 matches the contract, IDV, opportunity and notice lists may report a query-planner estimate there instead of an exact count, and page.count_type says which you got: Some("exact"), Some("approximate"), or None when the endpoint does not say. It is read from that page's own response, so concurrent calls on one client never see each other's value.

page.meta is the response's meta object as the API sends it. On a list filtered by agency it carries the filter diagnostics: each entry of meta["resolved_filters"][<filter name>] that resolved says how its token matched in matched_by (Tango API 5.9.0+): key, code, name, alias or fuzzy. A fuzzy match is worth checking against the resolved name.

# use tango::{Client, ListContractsOptions};
# async fn run() -> tango::Result<()> {
# let client = Client::builder().api_key("x").build()?;
let page = client
    .list_contracts(ListContractsOptions::builder().awarding_agency("Navy").build())
    .await?;
if page.count_type.as_deref() == Some("approximate") {
    println!("about {} matches", page.count);
}
if let Some(entries) = page
    .meta
    .as_ref()
    .and_then(|m| m["resolved_filters"]["awarding_agency"].as_array())
{
    for entry in entries {
        if entry["matched_by"] == "fuzzy" {
            println!("check this match: {entry}");
        }
    }
}
# Ok(()) }

Or just iterate via PageStream<T>:

# use tango::{Client, ListIDVsOptions};
# use futures::TryStreamExt;
# async fn run() -> tango::Result<()> {
# let client = Client::builder().api_key("x").build()?;
let mut stream = client.iterate_idvs(ListIDVsOptions::builder().build());
while let Some(idv) = stream.try_next().await? {
    // process one IDV at a time
    let _ = idv;
}
# Ok(()) }

Or drain the whole thing:

# use tango::{Client, ListIDVsOptions};
# async fn run() -> tango::Result<()> {
# let client = Client::builder().api_key("x").build()?;
let all = client.iterate_idvs(ListIDVsOptions::builder().build()).collect_all().await?;
# Ok(()) }

Rate limits

After each request, client.rate_limit_info() returns a snapshot of the rate-limit headers:

# use tango::Client;
# async fn run() -> tango::Result<()> {
# let client = Client::builder().api_key("x").build()?;
if let Some(info) = client.rate_limit_info() {
    println!(
        "remaining={:?} limit={:?} reset_in={:?}",
        info.remaining, info.limit, info.reset_in
    );
}
# Ok(()) }

The client also automatically retries 429s, honoring Retry-After. See docs/CLIENT.md for the full retry semantics.

Webhook verification

Webhook signing lives in the separate makegov-tango-webhooks crate so a receiver service doesn't have to pull in the full SDK:

use tango_webhooks::{verify, SIGNATURE_HEADER};

fn check(raw_body: &[u8], header_value: &str, secret: &str) -> bool {
    verify(raw_body, header_value, secret)
}

The CRUD methods for managing webhook endpoints and alerts live on tango::Client: list_webhook_endpoints, create_webhook_endpoint, update_webhook_endpoint, delete_webhook_endpoint, test_webhook_endpoint, list_webhook_alerts, create_webhook_alert, etc.

See docs/WEBHOOKS.md for the full surface, signature format, and middleware patterns.

Error handling

Every fallible call returns Result<T, tango::Error>. The Error enum carries rich payloads — match the variant to dispatch on the failure mode:

use tango::{Client, Error};

# async fn run() -> tango::Result<()> {
# let client = Client::builder().api_key("x").build()?;
match client.get_agency("9700", None).await {
    Ok(agency) => println!("{}", agency.name.unwrap_or_default()),
    Err(Error::NotFound { .. }) => println!("not found"),
    Err(Error::RateLimit { retry_after, limit_type, .. }) => {
        println!("rate limited; retry in {retry_after}s (bucket: {limit_type:?})");
    }
    Err(Error::Validation { message, .. }) => eprintln!("bad input: {message}"),
    Err(Error::Api { status, message, .. }) => eprintln!("status={status}: {message}"),
    Err(e) => return Err(e),
}
# Ok(()) }

err.is_retryable() reports the SDK's retry decision (it already retries internally; this is for callers building their own retry policies on top). err.status() returns the HTTP status when one is associated with the error.

API methods

The SDK exposes a method on Client for every public endpoint the sibling SDKs cover. The main resources are listed here; the full method-by-method reference lives in docs/API_REFERENCE.md.

Sub-resources and lookups: list_contract_subawards / _transactions, list_entity_contracts / _idvs / _otas / _otidvs / _subawards / _lcats / get_entity_metrics / get_entity_budget_flows, get_budget_account_quarters / _recipients, list_sled_opportunity_revisions / get_sled_coverage, get_ebuy_attachment_url / get_ebuy_access, list_idv_awards / _child_idvs / _transactions / _lcats, list_agency_awarding_contracts / _funding_contracts, list_vehicle_awardees / _orders, list_otidv_awards, list_gsa_elibrary_contracts, list_business_types, list_offices, list_departments, list_mas_sins, list_assistance_listings, list_lcats (dispatcher). Meta: resolve, validate, get_version, list_api_keys. list_opportunities with search also matches attachment text. Metrics dispatcher: list_metrics.

See docs/API_REFERENCE.md for full signatures, filter fields, and quirks.

Workspace layout

This is a Cargo workspace with two published crates:

.
├── crates/
│   ├── tango/             # main SDK
│   └── tango-webhooks/    # HMAC-SHA256 signing/verification (no transport deps)
├── docs/                  # in-repo guides
├── justfile               # task runner (test / fmt / lint / cover / release-check)
├── Cargo.toml             # workspace manifest
└── README.md

Documentation

In-repo guides:

• docs/ARCHITECTURE.md — crate layout, request lifecycle, design rationale
• docs/CLIENT.md — builder options, env vars, retry semantics, error model, rate-limit observability
• docs/API_REFERENCE.md — method-by-method reference for every public method
• docs/SHAPES.md — shape grammar, the 34 presets, flat / flat_lists, trade-offs
• docs/WEBHOOKS.md — receiving deliveries, CRUD methods, troubleshooting

External:

• API docs (Rust): https://docs.rs/makegov-tango · https://docs.rs/makegov-tango-webhooks
• API reference: https://docs.makegov.com
• Sibling SDKs: @makegov/tango-node · tango-python · tango-go

Development

just test         # cargo test --workspace
just fmt          # cargo fmt --all
just lint         # cargo clippy --workspace --all-features -- -D warnings
just cover        # cargo llvm-cov --workspace --lcov --output-path lcov.info
just ci           # fmt-check + lint + test (run before opening a PR)
just release-check  # cargo publish --dry-run for both crates

Requirements

• Rust 1.80 or later.

License

MIT — see LICENSE.

Support

Open an issue at https://github.com/makegov/tango-rust/issues or email support@makegov.com.

Contributing

PRs welcome. See CONTRIBUTING.md. Run just ci before opening — fmt, clippy, and the full test suite must pass.