Skip to main content

sdac-fetch-costs

Purpose​

Syncs SDAC cost report data from the TherapyLog system into the database via the Ingestion Server, then returns a report_id that downstream tools can use. The sync is idempotent -- if recent data already exists for the district and period, it returns the existing report_id without re-fetching.

Tool type​

Deterministic (data sync)

Tool ID​

sdac-fetch-costs

Inputs​

  • district_id (string, required) -- District identifier from session context
  • year (number, optional) -- Filter by year (e.g. 2025)
  • quarter (number, optional) -- Filter by quarter (1-4)

Outputs​

  • success (boolean)
  • report_id (string | null) -- Report ID for use with downstream validation tools
  • status (string) -- Sync status: success, empty, duplicate, or failed
  • record_count (number) -- Number of records synced
  • synced (boolean) -- Whether new data was synced (false = cache hit or empty)
  • error (string, optional) -- Error message if sync failed

Example output​

{
  "success": true,
  "report_id": "SDAC-2024-Q2-001",
  "status": "success",
  "record_count": 84,
  "synced": true
}

Functional details​

  • POSTs to the Ingestion Server at POST /sdac/sync.
  • TherapyLog data is mapped to the same DB tables as Excel uploads, so all downstream validation tools work identically regardless of data source.
  • If year and quarter are omitted, the Ingestion Server defaults to the current reporting period.

Usage notes​

  • Call this tool at the start of a TherapyLog-sourced review session to get a report_id.
  • Pass the returned report_id to validation tools (e.g. sdac-validate-source-codes, sdac-get-report-info).
  • A synced: false result with a valid report_id means cached data was reused -- no action needed.

Implementation details​

  • Reads INGESTION_API_URL environment variable (defaults to http://localhost:8000).
  • Does not write directly to the database -- the Ingestion Server handles all DB writes.

Code Location: packages/domain-sdac/src/tools/fetch-sdac-costs.tool.ts