Demo: a static copy of one review, without the review service. Reviewed marks apply in this tab until it reloads, and view settings stay in this browser. Comments, decisions, and publication need an installed mcp-review. About mcp-review · Get early access

Move the storefront API to typed handlers

Every endpoint of the storefront API moves from an Express callback to a typed handler, so validation, access checks, errors and logging happen in one pipeline instead of in 224 copies.

What changes

  • A new pipeline in src/http/ matches the route, checks access, validates the path, query and body against a schema, runs the handler, and writes one JSON answer.
  • Each of the 32 resources gets its schemas in src/schemas/, and its 7 handlers move to the new form.
  • The handler tests move from Mocha and supertest to node:test against the handlers themselves.
  • The tax rate table moves into the repository, so checkout no longer calls the finance service for each order.
  • The scheduled jobs import the shared @storefront/logger package. That change is mechanical.
flowchart LR
  Request[request] --> Pipeline[http pipeline]
  Pipeline --> Schemas[schemas]
  Pipeline --> Handlers[typed handlers]
  Handlers --> DB[(database)]

How to review

Read Typed request pipeline first: every other section depends on it. The handler sections repeat one pattern per resource, so a few files of each show it; the tests and the API reference follow the handlers.

Coverage

Presentation
All 1051 selected changes are placed. 1050 in groups · 0 unbucketed · 1 generated · 0 without a text diff
Explanations
8 of 8 groups have an explanation.
Agent analysis
Reading the analysis status…
Human review
0 of 1051 hunks are marked reviewed.

Sections

Each section opens on its own page, so the browser loads only the changes of that section. Show all sections on one page

  1. 9 files · 9 hunks · +643 -464 · 0/9 files reviewed · 0 open discussions

    The pipeline is the reason for this change. A handler now declares its method, path, access and schemas, and runHandler does the rest in a fixed order.

    Order of the checks

    1. Access: a user or admin endpoint without a session answers 401, and a non-admin on an admin endpoint 403.
    2. Validation: the path, the query and the body each pass their schema, or the answer is 422 with the problems.
    3. The handler runs. An HttpError becomes its status and code; any other error becomes a 500 that quotes the request ID.

    What to check

    • readJson caps the body at 1 MiB and answers 413 above it.
    • A 204 answer writes no body.
    • app.ts keeps listen, so the deployment does not change.
    • src/handlers/index.ts replaces the Express route table and lists each literal path before the path with a parameter.
  2. 78 files · 394 hunks · +1499 -1753 · 0/78 files reviewed · 0 open discussions

    The handlers of products, categories, brands, prices, stock levels, reviews, collections and media move to the typed form.

    Each file keeps its toResponse shape, so the JSON of every answer stays the same. The behaviour changes in three ways:

    • A create with an existing key, such as a product SKU or a category slug, answers 409 instead of a database error.
    • Delete needs an admin. Before, any signed-in user could delete.
    • List and search take their limits from the schema, so a limit over 100 is a 422 instead of being cut silently.

    src/catalog/categoryMappings.ts keys every category by the external ID of the new catalog import instead of its legacy code. Each entry changes only that field.

  3. 71 files · 141 hunks · +2545 -1374 · 0/71 files reviewed · 0 open discussions

    The handlers of carts, orders, payments, refunds, shipments, invoices, coupons and returns move to the typed form, with the same three behaviour changes as the catalog.

    src/tax/rates.ts holds the tax rate of each region and category for each financial year. Checkout read it from the finance service for every order; now the table ships with the API and finance updates it once a year. Its rows are data: check the shape and taxRate, not each rate.

  4. 77 files · 154 hunks · +1244 -1509 · 0/77 files reviewed · 0 open discussions

    The handlers of customers, addresses, sessions, wishlists, notifications, subscriptions, loyalty accounts and consents move to the typed form.

    A customer email is now the key of a create, so a second account with the same email answers 409.

  5. 32 files · 32 hunks · +1069 -0 · 0/32 files reviewed · 0 open discussions

    One schema file for each resource. A create body is strict, so an unknown field is a 422; an update body needs at least one field.

  6. 224 files · 224 hunks · +5440 -5216 · 0/224 files reviewed · 0 open discussions

    Each handler test calls the handler through invoke instead of starting the Express app, and adds a request without a session.

  7. 32 files · 32 hunks · +524 -460 · 0/32 files reviewed · 0 open discussions

    Each reference page gets a table of its endpoints with their access and validation, and the new error shape.

  8. 64 files · 64 hunks · +352 -352 · 0/64 files reviewed · 0 open discussions

    Mechanical change · 2 example files · 62 remaining matching files

    The 64 scheduled jobs import the shared @storefront/logger package instead of the local log module. The two examples show the whole change; the other jobs repeat it exactly.

  9. 1 file · 1 hunk · +1352 -0 · 0/1 files reviewed · 0 open discussions

    Lockfiles, codegen, and vendored files. Diffs load on demand, no syntax highlighting until asked.

+14,668 -11,128 left