← all branches

feat/api-dx2

safeviewing older commit
2ad6e01 · incrementalPR #262reviewed 2026-07-07 21:15 UTC0H · 1M · 1L · 1I
The branch
Purpose
Fix DX gaps in the public API surfaced by a real Tiendas Neto customer request — send the latest PDFs for 4 RPUs end-to-end.
Goal
Public-API DX round 2: refresh docs, fix zip filename collisions, add collection health to monitoring, add latest_only filter.
Sub-goals
  • SG-1: Document force_refresh + period_count on POST /v1/jobs
  • SG-2: Fix /v1/files/zip filename collisions (CFE period-based names → rpu_period.ext with numeric suffix)
  • SG-3: Add last_collection + latest_period_end to GET /v1/monitoring
  • SG-4: Add GET /v1/files?latest_only=true filter
The changes (whole branch)
What
This commit (2ad6e016) adds two edge-case tests to dedupeZipEntryNames (empty input, storagePath passthrough), expands the toCuratedErrorCode default-bucket anchor with 5 more real CfeErrorCode values, and hoists the lastIndexOf call outside the suffix loop (pure cleanup — identical output).
Why
Test hardening after the previous commit introduced the zip dedup and error curation functions. The storagePath invariant is load-bearing (wrong path → wrong S3 object in the zip); the anchored error codes prevent silent promotion of internal codes to the public surface.
Areas
apps/platform/src/api/utils+47−2apps/platform/src/api/utils/__tests__+201−0apps/platform/src/api/contracts/public-v1+9−1apps/platform/src/api/handlers/public-v1+24−3domains/utility/src/bill+19−1packages/api/src+39−9
Blast
13 files, +454/-49 across public-v1 API layer, utility domain bill queries, and api package schemas. All wire changes additive; no migrations.
no-migrations additive-only test-only-commit
➖CI· No CI checks found via gh pr checks➖CodeRabbit· No .coderabbit.yaml

Findings · 3

tests2

medium

storagePath passthrough test uses identical storagePaths — assertion is trivially true

apps/platform/src/api/utils/__tests__/public-v1-file-read.test.ts

mk('123','2026-05.pdf') called twice produces the same storagePath for both entries. The assertion `out.map(e=>e.storagePath).toEqual(files.map(f=>f.storagePath))` passes even if the implementation swapped storagePaths between entries, because both are identical strings. The test is meant to guard against the zip generator fetching the wrong S3 object under a renamed entry — that invariant requires *distinct* storagePaths. Fix: give the two entries different filenames (e.g. `mk('123','2026-05.pdf')` and `mk('123','2026-06.pdf')`) and assert each entry's storagePath separately after dedup.

low

Default-bucket anchor enumerates codes explicitly — won't catch new CfeErrorCode additions

apps/platform/src/api/utils/__tests__/public-v1-monitoring-read.test.ts

The it.each list now covers 9 codes, but the test must be manually updated whenever a new CfeErrorCode is added. If the enum grows without updating the list, the new code leaks through without a failing test. Consider deriving the expected-default set as `allCfeCodes.filter(c => !explicitlyCuratedCodes.includes(c))` so the test self-updates. Low priority since the fail-closed invariant test already catches any output outside the public set.

improvement1

info

No material improvement opportunities

The dedupeZipEntryNames refactor (hoist lastIndexOf, start n=2) is already clean. No simplification or reuse gaps.

History · 6 commits

  1. d2ff8e5needs attentionincremental1H · 2M · 4L2026-07-07 21:51
  2. 2ad6e01safeincremental0H · 1M · 1L2026-07-07 21:15current
  3. 4ea2976needs attentionincremental0H · 1M · 4L2026-07-07 20:20
  4. fe4cf9fneeds attentionincremental3H · 8M · 7L2026-07-07 14:53
  5. d82dbe8safeincremental0H · 0M · 0L2026-07-06 18:16
  6. 7113f2eneeds attentionfull5H · 6M · 7L2026-07-06 18:01