SRV-29 — V2 API contract — loyalty, packs, credit, returns
Extend packages/contracts with the V2 endpoints first so the mobile V2 work starts against the mock server in parallel.
| Field | Details |
|---|---|
| Task code | SRV-29 |
| Phase | P4 — V2 evolutions |
| Product scope | V2 |
| Status | Planned |
| Start | Thu 21 Jan 2027 |
| Due | Sun 24 Jan 2027 |
| Responsible | Anis — Full-stack developer |
| Co-responsible | Imad |
| Effort | 1 person-day(s) planned · 3 from scratch · size S |
| Area · app | Server · server |
| Depends on | LCH-05 |
| Unblocks | SRV-30, MRA-20 |
| Milestones | — |
Summary
Extend packages/contracts with the V2 endpoints first so the mobile V2 work starts against the mock server in parallel.
Description
As in V1, the V2 mobile work starts from the contract (cahier §14.2): this task extends packages/contracts with the V2 endpoints first — loyalty (loyalty.*, admin.loyalty.*, rewards and redemptions), packs (packs.*, cart.packs.add, admin.packs.crud), detailed credit (due dates, reminders, overdue and accounting export) — and publishes them on the mock server so Imad builds the V2 mobile screens in parallel. Returns are no longer part of V2: since the 17 Oct decisions returns.create|list|get and the admin return operations are V1 (SRV-03, SRV-20); V2 only adds the loyalty effects on returns (points reversal shown in return and order responses). All changes are additive so V1 apps keep working. Out of scope: implementation (SRV-30 to SRV-32).
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | Loyalty contracts: summary, transactions, rewards, redeem, redemptions; admin settings, adjustments, rewards, redemptions | Anis |
| 2 | Packs contracts: packs.list/get, cart.packs.add, admin.packs.crud; pack lines in cart and order schemas | Anis |
| 3 | Detailed credit contracts: due dates and reminders in finance.summary and invoices, admin.finance.overdue, admin.finance.export | Anis |
| 4 | Additive fields on V1 schemas (points reversal on returns and orders, voucher on checkout) without breaking changes | Anis |
| 5 | OpenAPI regeneration, oasdiff check showing no breaking change, CHANGELOG minor version | Anis |
| 6 | Mock server examples for every V2 operation | Anis |
| 7 | V2 contract review and Dart client regeneration | Imad |
Deliverables
- packages/contracts/src/{loyalty.ts,packs.ts,admin/loyalty.ts,admin/finance-v2.ts}
- openapi.json v1.x (minor) published with CHANGELOG entry
- Updated mock-api-staging
Acceptance criteria
- Every V2 operation of endpoints.json for loyalty, packs and detailed credit exists with its method and path (LOY-04, PRM-06, FIN-06)
- oasdiff reports no breaking change against the V1 contract
- The mock server answers every V2 operation with valid examples
- Imad regenerates the Dart client and signs off the review
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| LOY-04 | Rewards catalogue (voucher, free delivery, discount, gift, early access) and redemption | V2 |
| PRM-06 | Profitable packs: bundles of references at a pack price, added to cart as a unit | V2 |
| FIN-06 | Detailed credit: payment terms, due dates, automatic blocking or approval when exceeded | V2 |
API surface
| Endpoint group | Operations |
|---|---|
| Loyalty (V2) | 5 |
| Promotions, banners & packs | 5 |
| Reseller finance | 6 |
| Reseller orders | 11 |
Test measures
- Contract diff test against endpoints.json
- Spectral lint and oasdiff in CI
Risks
- V2 scope changes after HOCO's generalisation feedback — version the V2 contract as minor releases and keep unbuilt operations flagged V2 in the docs
KPI
- Delivered by Sun 24 Jan 2027 within 1 person-day(s).
- Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
- Zero open critical defects, permission gaps or data-integrity regressions at sign-off.
Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.
LCH-05 — Generalisation roll-out — waves by zone, public store release
Progressive opening zone by zone after the pilot, remaining delegates trained, apps promoted to the public Play track, maintenance and support procedures handed over.
SRV-30 — V2 — Loyalty engine (points, levels, rewards, vouchers)
Points ledger, earning on delivery/payment, expiry job, reversals, level computation over a period, rewards catalogue, redemptions and vouchers usable at checkout.