A04 — Creator financial API corrections

Status: blocked. Updated: 2026-09-06. Assigned agent: unassigned. Implementation PR: none.

Issues and acceptance covered

#51. The acceptance boundary is the implementation scope and completion checks below; see the issue acceptance matrix for parent coverage. Shared definitions: financial contract; proof anchors: evidence index.

Dependencies and blockers

A03 and payout-owned eligibility read contract. Coordinate GET-only hunks in payouts.ts with A05 and the payout writer owner. No new private campaign exposure before #50 contract.

Repository and expected files

Backend: src/api/routes/stats.ts overview/campaigns/leaderboard, src/api/routes/submissions.ts GET list/detail, src/api/routes/payouts.ts GET balance; proposed dedicated creator analytics router if cleaner; DTO/auth tests.

Existing behavior and verified gap

Overview still splits by paidOut; campaigns adds once but uses current RPM and lacks selected overrides; submissions estimate current earnings. Leaderboard adds external imports; balance has separate clipper/referral meanings. These routes lack canonical full-filter financial summaries (E01/E03/E04/E08).

Proposed implementation boundary

Use A03 for own creator/campaign/submission financial values and full-filter summary; retain recorded legacy history independently of current moderation. Expose payout-owned eligibility without recalculating it. Give leaderboards an explicit earned versus paid basis and keep external imports separate. Do not edit request/approval/send/preflight logic.

Expected API / data contract

Add analyticsV2 own positions and exact amount/coverage fields; full-filter summary separate from page rows, explicit creator/campaign/platform/time filters and bounded pagination. Preserve old numeric values until frontend migration, documenting estimate basis. No implicit number-to-string replacement.

Required tests

Own versus other creator; verified legacy identity/unmapped record; more than one page; status filter versus historical paid entries; cross-campaign totals; content/referral split; cache key/authorization order; legacy client payload; current rate edit cannot change v2 history.

Suggested agent tier

Smart owner reviews attribution/ownership and endpoint scope. Lower-cost agent handles bounded DTO and endpoint wiring from A03.

Expected PR boundary and reason

One creator GET-only API PR stacked on A03. Unlocks A11/A12. Keep payouts.ts balance hunk separate from A05 history and payout mutations. Keep compatibility additive, avoid unrelated cleanup, and list exact stacked commits and later units unlocked in the PR. If observed scope grows beyond this boundary, update the plan before splitting or adding work.

RBAC requirements / TODOs

Preserve requireAuth, ownership predicates and existing rate limits. TODO(RBAC): Own financial reads remain authenticated-creator scoped; staff/cross-creator access must use the separately approved staff financial boundary, never a query parameter bypass.

Completion and reconciliation checks

Creator overview = own campaign sum = own submission sum for equal basis/cutoff. Page changes cannot alter summary. Existing client shapes still parse. No known actual payment is erased by a later denial.

Record actual tests, source schema/contract versions, PR/merge SHA, manual evidence and residual coverage before changing status to review/complete. Any unexpected migration must first satisfy the migration gates; never bundle upstream financial writer work into this analytics unit.