makegov-tango 0.4.0

//! Shape presets for the Tango API's dynamic response-shaping feature.
//!
//! Every list/get endpoint accepts a `shape=` query parameter selecting which
//! fields the API returns. Use one of the [`shapes`](self) constants as a
//! sensible default, or pass a custom comma-separated field list of your own.
//!
//! These constants mirror the canonical defaults in `tango-node` and
//! `tango-python` so identical calls return identical bodies across SDKs.

/// The public Tango SaaS endpoint.
pub const DEFAULT_BASE_URL: &str = "https://tango.makegov.com";

/// Default shape for [`Client::list_contracts`](crate::Client::list_contracts).
pub const SHAPE_CONTRACTS_MINIMAL: &str =
    "key,piid,award_date,recipient(display_name),description,total_contract_value";

/// Default shape for [`Client::list_budget_accounts`](crate::Client::list_budget_accounts) and [`Client::get_budget_account`](crate::Client::get_budget_account).
///
/// Mirrors the API's own default budget-account shape, including `data_through_period`, `account_category` and `source_anomalies` (decode the latter with [`BudgetSourceAnomaly::from_record`](crate::models::BudgetSourceAnomaly::from_record)).
pub const SHAPE_BUDGET_ACCOUNTS_MINIMAL: &str = concat!(
    "id,federal_account_symbol,fiscal_year,data_through_period,agency_code,agency_name,",
    "bureau_name,",
    "account_title,bea_category,on_off_budget,subfunction_code,account_category,",
    "requested_ba,enacted_ba,apportioned,obligated_total,outlayed_total,",
    "unobligated_balance,contract_obligated,attribution_status,",
    "attribution_confidence,contract_obligated_estimated,",
    "contract_share_of_obligated_capped,",
    "assistance_obligated,obligated_to_apportioned_pct_capped,",
    "obligated_to_enacted_pct_capped,outlayed_to_obligated_pct_capped,",
    "ba_growth_next_year_pct,source_anomalies",
);

/// Default shape for [`Client::list_entities`](crate::Client::list_entities).
pub const SHAPE_ENTITIES_MINIMAL: &str = "uei,legal_business_name,cage_code,business_types";

/// Default shape for [`Client::get_entity`](crate::Client::get_entity).
pub const SHAPE_ENTITIES_COMPREHENSIVE: &str = concat!(
    "uei,legal_business_name,dba_name,cage_code,",
    "business_types,primary_naics,naics_codes,psc_codes,",
    "email_address,entity_url,description,capabilities,keywords,",
    "physical_address,mailing_address,",
    "federal_obligations(*),congressional_district",
);

/// Default shape for [`Client::list_forecasts`](crate::Client::list_forecasts).
pub const SHAPE_FORECASTS_MINIMAL: &str =
    "id,title,anticipated_award_date,fiscal_year,naics_code,status";

/// Default shape for [`Client::list_opportunities`](crate::Client::list_opportunities).
pub const SHAPE_OPPORTUNITIES_MINIMAL: &str =
    "opportunity_id,title,solicitation_number,response_deadline,active";

/// Default shape for [`Client::list_notices`](crate::Client::list_notices).
pub const SHAPE_NOTICES_MINIMAL: &str = "notice_id,title,solicitation_number,posted_date";

/// Default shape for [`Client::list_protests`](crate::Client::list_protests).
pub const SHAPE_PROTESTS_MINIMAL: &str =
    "case_id,case_number,title,source_system,outcome,filed_date";

/// Suggested list shape for
/// [`Client::list_contract_appeals`](crate::Client::list_contract_appeals).
///
/// Deliberately does not name `decision_text`. The decision body needs an Enterprise plan, so a suggested shape carrying it would make every list page pay for text most callers are not served.
/// Name it explicitly when you are entitled to it; `text_status` and `text_char_count` describe the text at every plan.
pub const SHAPE_CONTRACT_APPEALS_MINIMAL: &str = concat!(
    "uuid,board,docket_numbers,decision_date,appellant,judge,",
    "decision_type,url,listed",
);

/// Suggested list shape for [`Client::list_dibbs_rfqs`](crate::Client::list_dibbs_rfqs).
pub const SHAPE_DIBBS_RFQS_MINIMAL: &str = concat!(
    "uuid,solicitation,nsn,part_number,nomenclature,quantity,",
    "issue_date,return_by_date,is_open",
);

/// Suggested list shape for [`Client::list_dibbs_rfps`](crate::Client::list_dibbs_rfps).
pub const SHAPE_DIBBS_RFPS_MINIMAL: &str =
    "uuid,solicitation,nsn,part_number,nomenclature,issued_date,closes_date,is_open";

/// Suggested list shape for [`Client::list_dibbs_awards`](crate::Client::list_dibbs_awards).
///
/// `total_contract_price` is the order total repeated on every line item, so never sum it across rows.
pub const SHAPE_DIBBS_AWARDS_MINIMAL: &str = concat!(
    "uuid,award_number,solicitation,nsn,part_number,nomenclature,",
    "awardee_cage,award_date,total_contract_price",
);

/// Suggested list shape for [`Client::list_exclusions`](crate::Client::list_exclusions).
pub const SHAPE_EXCLUSIONS_MINIMAL: &str = concat!(
    "exclusion_key,display_name,entity_name,uei,classification_type,exclusion_type,",
    "excluding_agency_name,activate_date,termination_date,is_currently_excluded",
);

/// Default shape for [`Client::list_grants`](crate::Client::list_grants).
pub const SHAPE_GRANTS_MINIMAL: &str = "grant_id,opportunity_number,title,status(*),agency_code";

/// Default shape for [`Client::list_idvs`](crate::Client::list_idvs).
pub const SHAPE_IDVS_MINIMAL: &str = concat!(
    "key,piid,award_date,recipient(display_name,uei),description,",
    "total_contract_value,obligated,idv_type",
);

/// Default shape for [`Client::get_idv`](crate::Client::get_idv).
pub const SHAPE_IDVS_COMPREHENSIVE: &str = concat!(
    "key,piid,award_date,description,fiscal_year,total_contract_value,obligated,",
    "idv_type,multiple_or_single_award_idv,type_of_idc,period_of_performance(start_date,last_date_to_order),",
    "recipient(display_name,legal_business_name,uei,cage),",
    "awarding_office(*),funding_office(*),place_of_performance(*),parent_award(key,piid),",
    "competition(*),legislative_mandates(*),transactions(*),subawards_summary(*)",
);

/// Default shape for [`Client::list_vehicles`](crate::Client::list_vehicles).
pub const SHAPE_VEHICLES_MINIMAL: &str = concat!(
    "uuid,solicitation_identifier,is_synthetic_solicitation,program_acronym,",
    "organization_id,organization,vehicle_type,description,",
    "idv_count,awardee_count,holder_count,order_winner_count,order_count,total_obligated,",
    "vehicle_obligations,vehicle_contracts_value,latest_award_date,",
    "solicitation_title,solicitation_date",
);

/// Default shape for [`Client::get_vehicle`](crate::Client::get_vehicle).
pub const SHAPE_VEHICLES_COMPREHENSIVE: &str = concat!(
    "uuid,solicitation_identifier,is_synthetic_solicitation,agency_id,program_acronym,",
    "organization_id,organization(*),vehicle_type,who_can_use,",
    "solicitation_title,solicitation_description,solicitation_date,opportunity_id,",
    "naics_code,psc_code,set_aside,",
    "fiscal_year,award_date,latest_award_date,last_date_to_order,",
    "description,idv_count,awardee_count,holder_count,order_winner_count,order_count,total_obligated,",
    "vehicle_obligations,vehicle_contracts_value,",
    "type_of_idc,contract_type,metrics(*)",
);

/// Default shape for [`Client::list_vehicle_awardees`](crate::Client::list_vehicle_awardees).
pub const SHAPE_VEHICLE_AWARDEES_MINIMAL: &str = concat!(
    "uuid,key,piid,award_date,title,order_count,idv_obligations,",
    "idv_contracts_value,recipient(display_name,uei)",
);

/// Default shape for [`Client::list_vehicle_orders`](crate::Client::list_vehicle_orders).
pub const SHAPE_VEHICLE_ORDERS_MINIMAL: &str = concat!(
    "key,piid,award_date,obligated,total_contract_value,description,",
    "recipient(display_name,uei)",
);

/// Default shape for [`Client::list_organizations`](crate::Client::list_organizations).
pub const SHAPE_ORGANIZATIONS_MINIMAL: &str = "key,fh_key,name,level,type,short_name";

/// Default shape for [`Client::list_otas`](crate::Client::list_otas).
pub const SHAPE_OTAS_MINIMAL: &str = concat!(
    "key,piid,award_date,recipient(display_name,uei),description,",
    "total_contract_value,obligated",
);

/// Default shape for [`Client::list_otidvs`](crate::Client::list_otidvs).
pub const SHAPE_OTIDVS_MINIMAL: &str = concat!(
    "key,piid,award_date,recipient(display_name,uei),description,",
    "total_contract_value,obligated,idv_type",
);

/// Default shape for [`Client::list_subawards`](crate::Client::list_subawards).
///
/// The Tango API rejects `id` and `amount` in subaward shapes; stick to the
/// canonical fields below or roll your own subset.
pub const SHAPE_SUBAWARDS_MINIMAL: &str =
    "award_key,prime_recipient(uei,display_name),subaward_recipient(uei,display_name)";

/// Default shape for [`Client::list_gsa_elibrary_contracts`](crate::Client::list_gsa_elibrary_contracts).
pub const SHAPE_GSA_ELIBRARY_CONTRACTS_MINIMAL: &str = concat!(
    "uuid,contract_number,schedule,recipient(display_name,uei),",
    "idv(key,award_date)",
);

/// Default shape for [`Client::list_itdashboard`](crate::Client::list_itdashboard).
/// Mirrors the API's `INVESTMENT_LIST_DEFAULT_SHAPE`.
pub const SHAPE_ITDASHBOARD_INVESTMENTS_MINIMAL: &str = concat!(
    "uii,agency_name,bureau_name,investment_title,",
    "type_of_investment,part_of_it_portfolio,updated_time,url",
);

/// Default shape for [`Client::get_itdashboard`](crate::Client::get_itdashboard).
/// Mirrors the API's `INVESTMENT_RETRIEVE_DEFAULT_SHAPE`.
pub const SHAPE_ITDASHBOARD_INVESTMENTS_COMPREHENSIVE: &str = concat!(
    "uii,agency_code,agency_name,bureau_code,bureau_name,",
    "investment_title,type_of_investment,part_of_it_portfolio,",
    "updated_time,url",
);

/// Suggested list shape for
/// [`Client::list_sled_opportunities`](crate::Client::list_sled_opportunities).
///
/// `description` is detail-only on the API — its median is around 550
/// characters and its tail runs past 120,000 — so it is deliberately absent
/// here. Name it explicitly, or pass `verbose=true` via `extra`.
///
/// `delisted_at` is when the portal stopped listing the solicitation before its deadline; when set, `status` is `closed` and `status_reason` is `delisted`, unless the portal itself already called it closed, awarded or cancelled. It is null for a solicitation never delisted, or seen again since.
pub const SHAPE_SLED_OPPORTUNITIES_MINIMAL: &str = concat!(
    "opportunity_id,solicitation_number,solicitation_type,title,state,",
    "jurisdiction,agency,status,status_reason,delisted_at,posted_date,response_deadline,",
    "source_url,has_documents,first_seen_at,last_change_seen_at",
);

/// Suggested detail shape for
/// [`Client::get_sled_opportunity`](crate::Client::get_sled_opportunity).
///
/// Deliberately does not name `attachments(extracted_text)`. The document body
/// needs a Small plan and the API resolves it only for a caller who names the
/// leaf, so a default shape carrying it would make every detail fetch pay for a
/// document nobody asked to read. Ask for it explicitly instead:
///
/// ```text
/// opportunity_id,attachments(name,size_bytes,extracted_text)
/// ```
pub const SHAPE_SLED_OPPORTUNITIES_COMPREHENSIVE: &str = concat!(
    "opportunity_id,solicitation_number,solicitation_type,",
    "solicitation_type_source,title,description,state,jurisdiction,agency,",
    "status,status_reason,delisted_at,status_computed_at,source_status,source_url,",
    "posted_date,response_deadline,response_deadline_original,",
    "bid_opening_date,bid_opening_raw,category_codes,has_documents,",
    "first_seen_at,last_seen_at,last_change_seen_at,",
    "organization(*),contact(*),meta(*),attachments(*),revisions(*)",
);

/// Suggested shape for
/// [`Client::list_sled_opportunity_revisions`](crate::Client::list_sled_opportunity_revisions).
///
/// `changes` — the per-field before and after — is omitted on purpose: it needs
/// a Small plan, so naming it in a default shape would 403 a Free caller on a
/// field they never asked to gate. `changed_fields` names what moved at every
/// plan.
pub const SHAPE_SLED_REVISIONS_MINIMAL: &str =
    "observed_at,sequence,kind,changed_fields,source_declared";

/// Suggested list shape for
/// [`Client::list_sled_forecasts`](crate::Client::list_sled_forecasts).
pub const SHAPE_SLED_FORECASTS_MINIMAL: &str = concat!(
    "forecast_id,state,agency,title,estimated_advertisement_date,",
    "estimated_advertisement_raw,procurement_category,procurement_method,",
    "contract_number,incumbent_name,source_url,estimated_value(*)",
);

/// Suggested detail shape for
/// [`Client::get_sled_forecast`](crate::Client::get_sled_forecast).
pub const SHAPE_SLED_FORECASTS_COMPREHENSIVE: &str = concat!(
    "forecast_id,state,agency,title,description,",
    "estimated_advertisement_date,estimated_advertisement_raw,",
    "procurement_category,procurement_method,contract_term,contract_number,",
    "incumbent_name,mbe_dbe_goal,delivery_location,source_url,source_status,",
    "has_documents,first_seen_at,last_seen_at,",
    "organization(*),contact(*),estimated_value(*)",
);

/// Suggested list shape for [`Client::list_sbir_topics`](crate::Client::list_sbir_topics).
pub const SHAPE_SBIR_TOPICS_MINIMAL: &str = concat!(
    "topic_id,topic_number,title,agency,activity,year,",
    "solicitation_number,open_date,close_date,listed_open",
);

/// Suggested list shape for [`Client::list_sbir_solicitations`](crate::Client::list_sbir_solicitations).
pub const SHAPE_SBIR_SOLICITATIONS_MINIMAL: &str = concat!(
    "solicitation_id,solicitation_number,title,program,activity,",
    "cycle_name,solicitation_status,year,start_date,end_date",
);

/// Suggested list shape for [`Client::list_federal_register_documents`](crate::Client::list_federal_register_documents).
///
/// Mirrors the API's default list shape. `full_text` is never on the list.
pub const SHAPE_FEDERAL_REGISTER_MINIMAL: &str = concat!(
    "uuid,document_number,publication_date,type,subtype,title,abstract,action,",
    "agencies,cfr_references,citation,significant,comments_close_on,effective_on,",
    "html_url,pdf_url",
);

/// Suggested detail shape for [`Client::get_federal_register_document`](crate::Client::get_federal_register_document).
///
/// Mirrors the API's default detail shape. `full_text` is left out on purpose: it can run to several MB, so name it when you want it.
pub const SHAPE_FEDERAL_REGISTER_COMPREHENSIVE: &str = concat!(
    "uuid,document_number,publication_date,type,subtype,title,abstract,action,",
    "agencies,cfr_references,citation,significant,comments_close_on,effective_on,",
    "html_url,pdf_url,dates,signing_date,start_page,end_page,volume,docket_ids,",
    "dockets,regulation_id_numbers,topics,correction_of,corrections,",
    "executive_order_number,presidential_document_number,proclamation_number,",
    "comment_url,regulations_dot_gov_url,raw_text_url,body_html_url",
);

/// Suggested list shape for [`Client::list_ebuy_requests`](crate::Client::list_ebuy_requests).
///
/// Mirrors the API's default list shape. `description` is detail-only; `attachment_count` says whether a detail fetch is worth it.
pub const SHAPE_EBUY_REQUESTS_MINIMAL: &str = concat!(
    "rfq_id,request_type,title,schedule,sin,status,buyer_name,buyer_agency,",
    "buyer_agency_code,reference_number,issue_date,close_date,attachment_count,",
    "link_count,last_seen",
);

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn vehicle_shapes_carry_company_counts() {
        for (name, shape) in [
            ("SHAPE_VEHICLES_MINIMAL", SHAPE_VEHICLES_MINIMAL),
            ("SHAPE_VEHICLES_COMPREHENSIVE", SHAPE_VEHICLES_COMPREHENSIVE),
        ] {
            let fields: Vec<&str> = shape.split(',').collect();
            for want in ["awardee_count", "holder_count", "order_winner_count"] {
                assert!(
                    fields.contains(&want),
                    "{name} should carry {want:?}: {shape:?}"
                );
            }
        }
    }
}