Repository navigation
Publish unified invoice API contract for FE and BE (#446) - #571
woahwhattheheck wants to merge 10 commits into
Conversation
Closes Quittance-Labs#446. Share create/get/list/cancel/verify/stats request and response shapes plus the error envelope in shared/invoice-contract.ts, with runtime parsers and an OpenAPI 3.0.3 document. Express re-exports the envelopes; the Next.js client validates responses through the same parsers so invalid creates fail consistently on both sides and list/detail/verify/stats stay aligned.
Require complete numeric statistics and preserve explicit zero counts. Reject malformed success envelopes, unsafe or negative counts, non-finite or nonnumeric revenue, and missing or ambiguous storage rows. Keep raw object and canonical one-row responses compatible; publish their numeric bounds and wire shapes in OpenAPI. Validation: 66 focused backend checks, 21 shared checks, and 15 frontend checks pass. Backend typecheck and TypeScript 5.9.3 scoped frontend API-client check pass. The same contract file on exact parent reports 16 pass / 19 fail. Actual invoiceApi.getStats with locked Axios 1.12.2 completes 18 local HTTP cases: parent has 13 mismatches, candidate none; real Express/memory empty, pending, and paid controls pass both. Boundary: no full frontend build/typecheck, browser, wallet, external Horizon, or PostgreSQL runtime rerun. No dependency or storage behavior changes.
|
I reviewed this locally. The shared contract is a good direction, but six frontend tests fail on this branch as submitted, before any merge with
The cause is in
|
Merge current main without rewriting the submitted branch. Keep shared contract validation strict in tests, retain typed tolerant client responses, preserve existing seller-statistics row normalization, and carry pay-link copyValue/networkPassphrase through types, parsers and OpenAPI. Preserve current-main request correlation, search, canonical proof delivery and payment-session types. Add artifact-contract and partial-stats coverage.
Reject malformed pagination objects and require nonnegative safe-integer limit, offset, and total values in the strict shared parser. Reflect that contract in the OpenAPI schema. Continue normalizing legacy responses that omit pagination, and preserve the frontend client's tolerant runtime behavior. Two focused contract cases pass; the parent source reproduces acceptance of malformed supplied metadata.
Use one shared discriminant guard for create, get, list, payment-info, cancel and verify responses. A supplied success value must be literal true; supported legacy payloads without the flag retain their existing normalization. Preserve the stats and pagination repairs, OpenAPI document and all payment/identity logic. Two focused regression tests execute against the complete production contract and its real invoice-validation dependency, transpiled with TypeScript 5.8.3 and run with Node 22.16.0. Original: 1 passed, 1 failed. Patched: 2 passed, 0 failed. This is not a full backend/frontend typecheck, HTTP integration or database run.
Make the existing bare-array normalization reachable while retaining the strict supplied-success discriminant and pagination validation. Empty and populated lists use the same envelope parser; invalid invoice items remain rejected. Extend the existing compatibility case with the list exception, preserving empty-array rejection for all other response parsers. No new test file, transport gate or workflow enters the product branch. Preserve the documentation-only successor 9577eeb as parent. Run https://github.com/woahwhattheheck/Quittance0/actions/runs/37207722383 executed both existing response-contract tests against the complete production contract and real validation dependency using native type stripping and temporary ESM import-path adaptation: 2 passed, 0 failed. Paired legacy-list cases improved 0/2 to 2/2, with five pagination/error/item controls retained. This is not a project typecheck, HTTP/database check or full repository suite. Checked source blob fc9ac68; test blob 9474aa1.
|
@CemAyyildiz Your October 3 findings have been addressed in this original branch, now at
The committed review-resolution record retains the implementation revision's passing project commands and later focused results. It separately records the failed clean-worktree wrappers; those workflows are not being represented as green CI. No checks were rerun for this follow-up. Please re-review this head and identify any concrete remaining requirement. I maintain my original #446 contribution claim and request payment; please confirm acceptance, the compensation amount and settlement route. |
Summary
Closes #446.
Publishes a complete invoice API contract (create, get, list, cancel, verify, stats) as shared schemas with TypeScript types used by Express handlers and the Next.js client. Invalid create payloads fail consistently on both sides; list, detail, and verify share response types while the runtime client tolerates response-shape drift; strict shared parsers are exercised by contract tests.
Done when
Changes
shared/invoice-contract.ts— request/response shapes, shared error envelope (ApiSuccess/ApiFailure/ValidationFailureBody), runtime parsers for create/get/list/payment-info/cancel/verify/stats, andINVOICE_OPENAPI_SPECshared/invoice.ts— settlement fields and typed late-payment / settlement enums onInvoiceDto/PublicInvoiceDtobackend/src/types/api.ts— re-exports envelopes from the shared contract; Express send helpers stay backend-onlyfrontend/lib/api.ts—invoiceApimethods use shared response types and tolerate runtime response-shape drift; strict shared parsers remain in contract testsInvoiceCard/pay-page.types/export/payment-page-state— drop parallel invoice interfaces in favor ofInvoiceDtobackend/tests/invoice-contract.test.ts+tests/invoice-contract.test.mjs— fail when required fields diverge; exercise the in-memory MVP routerTest plan
cd backend && node --import tsx --test tests/invoice-contract.test.ts tests/create-invoice-validation.test.ts tests/shared-verification-contract.test.ts— passnode --test tests/invoice-contract.test.mjs— passcd frontend && node --test tests/invoice-form-validation.test.js tests/api-runtime.test.js— passnpm run typecheck(backend + frontend) — cleanOriginal-contributor compensation claim
/claim #446
I am the original author of this existing PR implementing issue #446. I request sponsor review, acceptance and consideration for any eligible GrantFox OSS reward under its current campaign terms. If accepted and eligible, please confirm the approved amount (if any), allocation, payment mechanism and payment date. This is an affirmative contributor claim, not a representation that a
Maybe Rewardedlisting guarantees payment.