SRV-03 — API contract v1 — oRPC contract package, OpenAPI export & mock server

SummaryCopy Anchor Link

Every V1 endpoint as a typed contract (Zod request/response, errors, pagination) in packages/contracts; OpenAPI 3.1 generated and published; Prism mock server so Imad builds against it the same day.

DescriptionCopy Anchor Link

Step 3 and the hand-off that unblocks the mobile track (milestone API contract v1 published): every V1 endpoint the reseller and delegate apps use is declared contract-first in packages/contracts with oRPC — Zod 4 request/response schemas, .route({ method, path }), declared error codes and the pagination conventions of AUTHORING §3 — and the OpenAPI 3.1 document is generated, published and served by a Prism mock server so Imad can build against it the same day (NFR-09, SYN-05). The schemas carry the 17 Oct decisions: catalog operations are auth: optional and return price: null with priceLocked: true for guests, availability is IN_STOCK/OUT_OF_STOCK only (no quantity fields), catalog.facets, events.stream, support.whatsapp and returns.create|list|get exist, assisted orders and after-sales tickets have their own shapes. Out of scope: admin groups beyond the shared primitives (each SRV module task adds its admin procedures) and implementation. Imad reviews it as the first consumer and generates the Dart client from it.

SubtasksCopy Anchor Link

DeliverablesCopy Anchor Link

• packages/contracts/src/{common,errors,auth,me,files,catalog,cart,orders,returns,finance,promotions,profile,support,notifications,invitations,delegate,sync}.ts
• packages/contracts/scripts/openapi.ts producing openapi.json (CI artefact, served at /openapi.json)
• Mock server Dokploy app mock-api-staging (Prism) and docker compose service for local use
• packages/contracts/CHANGELOG.md (v1.0.0)

Acceptance criteriaCopy Anchor Link

• Every V1 operation of the groups listed on the task exists with the method and path of endpoints.json (script diff = 0)
• Catalog responses declare price as nullable with priceLocked; no reseller- or delegate-facing schema contains a stock quantity field (STK-07, AUTH-10)
• Idempotency-Key is a required header on every operation flagged idem and on cart.checkout and sync.batch
• Error responses use the envelope with codes from the registry (e.g. ORDER_MIN_AMOUNT_NOT_MET, STOCK_INSUFFICIENT, IDEMPOTENCY_KEY_REUSED)
• The mock server answers every operation with a schema-valid example
• Imad generates the Dart client from openapi.json and signs off the review

Requirements coveredCopy Anchor Link

API surfaceCopy Anchor Link

Test measuresCopy Anchor Link

• Contract test: every route in the contract router is unique by method + path and matches endpoints.json
• Spectral lint of openapi.json in CI
• Schema round-trip test: each example validates against its Zod schema
• Dart client generation job (smoke) run by Imad against the published document

RisksCopy Anchor Link

• Contract churn after Imad starts — semantic versioning, oasdiff breaking-change gate and a changelog entry for every change
• OpenAPI generation gaps for oRPC features (SSE, file streams) — describe events.stream as text/event-stream with documented event schemas

KPICopy Anchor Link

• Delivered by Sun 18 Oct 2026 within 2.5 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.