API for Report Flow

[SakshiKekre]

Summary

Implemented report API functionality with corrected ID handling and proper alignment between frontend types and backend API endpoints.

TODO: API for calculation endpoint

Key Changes

Type Alignment Fixes

• Fixed ID handling: Updated ReportMetadata to use id instead of report_id (matches backend auto-increment pattern)
• Made Report fields optional: reportId, createdAt, updatedAt now optional like Policy type (populated after creation)
• Simplified creation payload: ReportCreationPayload now only includes simulation_1_id and simulation_2_id (backend generates ID/timestamps)
• Streamlined update payload: Removed redundant fields from ReportSetOutputPayload (report ID passed in URL path)

New API Functions

• fetchReportById(countryId, reportId) - GET report by ID
• createReport(countryId, payload) - POST new report (creates with 'pending' status)
• updateReport(countryId, reportId, payload) - PATCH report status/output

Updated Adapters

• ReportAdapter.fromMetadata() - Fixed ID mapping (id → reportId)
• ReportAdapter.toCreationPayload() - Simplified to only send simulation IDs
• ReportAdapter.toCompletedReportPayload() - Streamlined for status updates
• ReportAdapter.toErrorReportPayload() - Added error state handling

Testing

• Updated all existing report adapter tests (12 passing)
• Added comprehensive report API tests (6 passing)
• Fixed mock data to match corrected types
• Total: 18 tests passing

[anth-volk]

Thanks for your work on this @SakshiKekre! There are a few points where I'd recommend changes (basically only around using conversion adapters) and a couple questions, otherwise we'll be good to go.

[anth-volk]

Had a few requested changes, plus I believe a couple comments remain incomplete.

[SakshiKekre]

issue: I should've paid more attention previously, but here, too, passing reportId as a URL param instead of in the body is pretty uncommon. Would recommend moving to body.

Thanks for pointing this out in all spots where ID is used. It’s helpful because I don’t have to dig through each line myself. Mentioning my thoughts here for all comments relevant to ID in the URL:

While I agree that URLs for PATCH shouldn’t include path parameters where possible, in this case, the reportId is an identifier, not part of the patch data itself to go in the body. The path identifies which resource is being updated, while the body describes what is updated.

This aligns with common REST conventions:

• GET /report/{id} fetches a report
• PATCH /report/{id} updates a report
• DELETE /report/{id} deletes a report

Removing the ID from the path would make the PATCH act on the collection (/report), which is less canonical and inconsistent with the rest of the CRUD model.

Given that, I’d prefer to keep the reportId in the path across these occurrences.

BTW, this also makes me want to rename the endpoints from report -> reports and simulation -> simulations to better reflect collections.

[anth-volk]

Note: DO NOT MERGE until API update (https://github.com/PolicyEngine/policyengine-api/actions/runs/17701223907/attempts/1) is fully deployed