Skip to content

feat: checkout and payment, the storefront's admin and order lookup, a starter and a second theme - #12

Merged
JasonYv merged 26 commits into
mainfrom
feature/phase2-checkout
Nov 2, 2026
Merged

JasonYv merged 26 commits into
mainfrom
feature/phase2-checkout

Conversation

@JasonYv

@JasonYv JasonYv commented Nov 1, 2026

Copy link
Copy Markdown
Contributor

Phases 2 and 3 of the rebuild on Mallok (design §9), built locally on mallok@0.1.0-rc.11. Nothing has been deployed, and no figure was taken on a Cloudflare account: the owner said the CPU use of the pages was not to be measured again now.

Phase 2 — checkout and payment (design §20)

  • Shipping zones: countries, a fixed rate per currency, and an amount from which it ships free. They are edited in the admin.
  • Checkout, with no script:
    • the buyer chooses a country, then sees shipping and the total;
    • they give a company and an address;
    • they pay on Stripe's hosted page by card or Link, at the shop's own prices, with Stripe's currency conversion off.
    • The Stripe API version is pinned to 2026-10-28.endive.
  • An order's page opens only with a signed link (an HMAC of the order's id).
  • The webhook route:
    • it answers 503 until the signing secret is set;
    • a payment is held to its order's currency and total;
    • one payment takes stock once;
    • an unpaid order is cancelled an hour after its payment page lapses.
  • Follow-ups (the buyer's four emails, the seller's three notices, cache purges) are owed from outbox rows written in the same batch as each change. Mallok jobs carry them out, with the cron behind them.
  • Orders in the admin:
    • mark shipped (tracking number and carrier) or delivered;
    • cancel one that was not paid;
    • refund in full: at Stripe first, then the books, with the stock put back unless the goods have shipped;
    • fulfil an oversold order once restocked.
    • Payments the shop could not keep are listed to refund.
  • The owner's nineteen decisions (D1–D19) and how each was built are in §20.

Phase 3 — the storefront (design §21)

  • Customers and sales panels: read-only views over orders, inquiries and the outbox.
  • Finding an order again by email: there are no buyer accounts.
    • The link is good for a day and lists the address's paid orders.
    • The answer is the same, and takes the same time, whether or not the address has bought.
    • Requests are limited per visitor and per address.
  • The sample as a starter for Mallok's first-run wizard: the catalogue in four languages, variants, prices and shipping zones, without pictures.
  • A second theme (src/theme-editorial/, entry src/worker/editorial.ts):
    • It reads the same content model, options, language packs and plugin views as the commerce theme, and draws them as an engineering bulletin.
    • It has no script and no file of its own; Mallok stages the assets of src/theme only (M46).
    • npm run preview -- --theme editorial shows it, and CI brings it up.
  • Parity with the old Next.js README, item by item: every commerce item is met. What is open is Mallok's (handoff M47).

Reviews

Each phase was given to two independent reviewers, one for correctness and one for security. Each finding was checked before it was acted on and fixed with a test seen failing first:

  • phase 2: fourteen findings (§20);
  • phase 3: eight findings, and one found before the review (§21).

One commit in the history, b87aff5, left the schema test's list of migrations one short. The next commit, 2f5a5ca, completes it.

Migrations

0004_checkout, 0005_storefront and 0006_review are additive. 0006 drops and recreates two of 0005's views rather than editing a migration that may have run.

Verification

  • lint, typecheck, npm test (1,100 tests in workerd across the site and editorial projects, 54 project tests), npm run build, npm run smoke, npm run smoke:shop, and npm run preview -- --check for both themes all pass locally.
  • Guards were broken one at a time and the tests went red: forty-one in phase 2, and thirty-nine in phase 3. The race tests went red on every run.
  • The editorial theme was looked at in a browser. All 131 pages of the sample were measured at 320, 375, 768 and 1280 px: none scrolls sideways.

Not verified

  • No payment was made at Stripe, in test mode or otherwise. That needs the owner's test keys and is the next step. Stripe was tested against a stand-in built from its documentation.
  • No email was delivered; emails were seen handed to Mallok's queue.
  • Nothing was deployed or measured on a Cloudflare account.
  • The index on lower(email) and the query plans were seen in workerd's SQLite, not on D1 itself.
  • The editorial theme was seen in Chrome on macOS only. Its DIN faces come from the visitor's system (Bahnschrift on Windows, with fallbacks elsewhere).
  • The first-run wizard was driven through its endpoint, not clicked through in the admin.

Mallok

The gaps met on the way are in the handoff list, M41–M47. None blocks this work.

Checkout needs to know whether an address can be shipped to and what it
costs before Stripe is asked for anything. A seller now groups countries into
zones in the admin, each with a rate per currency and an optional amount from
which it ships free; a country in no zone cannot be ordered to.

The migration also adds what an order records at checkout (its cart, company,
tax number, zone, tax mode, the digest of the buyer's link, the carrier, when
its payment page lapses) and the settings and secrets checkout reads. The
export carries the zones, and leaves an order's cart and link digest behind.
… orders

A payment is now checked against the order's currency and total before it
is taken; one that does not fit is refused and owed a refund, as a payment
for a cancelled order already was. With Stripe calculating tax, the tax is
what the payment came to beyond the goods and the shipping.

A lapsed Checkout session cancels the order it was for, so a pending order
does not hold its prices for ever. An oversold order is refunded, or
restocked and fulfilled; it can no longer simply be cancelled, which left a
payment taken and nobody owing it back. A refund may leave the stock alone
when the goods stay with the buyer, shipping records the carrier, and a
cancellation says why on what it owes.
…checked against

A Checkout session now carries the order line by line at its own prices and
shipping as one option named after its zone, lapses after an hour, offers
only methods that settle at once, and has Stripe's own currency conversion
switched off, so the buyer pays what the shop's page said. With Stripe
calculating tax it is worked out from a customer holding the address the
order ships to. A session can be expired before its order is cancelled.
Every request names API version 2026-10-28.endive.
The buyer is told an order is confirmed, shipped, refunded, or cancelled by
the seller, in the order's language, with a link to the order; the seller is
told of a new order, of one paid for after its stock had gone, and of a
payment that has to be refunded, with the reason. Everything a person typed
is escaped on its way into the HTML.
…fterwards

The checkout page asks where the order goes, shows shipping for that country
from the seller's zones and the total, and places a pending order before
sending the buyer to Stripe; one cart has one payment open at a time. The
order's page opens with a signed link, never by its number alone. Stripe's
deliveries pay an order, empty what was ordered from its cart in the same
batch, and close an order whose payment page lapsed.

What each change still owes is carried out by a job, with the cron behind
it: emails and purges, claimed so two runners never send one twice. The
admin lists orders and refused payments, and ships, delivers, cancels,
refunds, and fulfils an oversold order once restocked, always moving the
money at Stripe before the books here.
…ke run

The sample shop needs somewhere to ship to for its checkout to quote
anything. The smoke run now goes from the cart to the checkout page in
German, sees shipping to Germany quoted, and sees that with no Stripe keys
the shop offers no payment, places no order and turns Stripe's deliveries
away for Stripe to deliver again.
… against itself

Two independent reviews of checkout found fourteen things; this answers them.

A second payment for an oversold order was taken, or failed the webhook for
three days: only a pending order takes a payment now. A session that will
not expire may be paid, so Stripe is asked, and an order it has complete is
never cancelled by a new checkout, the admin or the cron. An order is placed
only when no other from its cart is waiting and the visitor is under ten an
hour, both counted in its own write; a session opened for an order closed
meanwhile is closed again. An oversold order keeps Stripe's tax. A refund is
held to the status its stock was decided on. Each email an outbox row owes is
marked as it is handed over, and a row another runner holds holds its
order's later rows back. Refunds and expiries carry no idempotency key,
which held a failure for a day. Links use the site's own domain when it has
one, and the order page sends no referrer.
…eviews found

The design's §20 lists the nineteen decisions as taken and what was built
for each, what building it found, the fourteen things two reviews found and
how each was answered, how it was verified, and what is not: no purchase has
been made at Stripe yet, and nothing has been deployed. The README says how
to take payments; the security notes describe the payment controls as they
are and the risks that remain; CLAUDE.md describes checkout for the next
person to change it.
Customers are the addresses that ordered or asked, gathered without regard
to case from the orders and inquiries the shop already holds, with what each
has spent per currency and their orders and inquiries beside them. Sales are
counted by the month a payment was confirmed and a refund made, per
currency, and by SKU over orders paid and kept. All three are read-only
views, as the order panels are.
A buyer gives the address they ordered with and is emailed a link that lists
every paid order placed with it for a day, each opening its own page. The
page answers the same whether or not the address has orders, so the form
tells nobody who has bought here; the link's secret is kept only as its
digest and the address is never in a link or a log. One visitor may ask a
few times an hour and an address be sent a few links an hour, both counted
in the write; links that open nothing any more are cleared with the carts.
The cart and order pages lead to it, in four languages.
A site deployed from this repository can now be filled with the sample from
the wizard, with no command to run: the catalogue in four languages from
content/, site.json's settings, and the seed's variants, prices and shipping
zones as records the shop's own panels save. A starter carries no files, so
covers, galleries and pictures in a body are left out, and every page is
whole without them. The list of documents is generated from content/ and a
test fails when it is stale; another holds the records to the seed, and a
third runs the starter through Mallok's own wizard step.
A contract with one theme behind it is a guess. The editorial theme reads
the same content model, options, language packs and plugin views as the
commerce theme and draws every page with no script and no file of its own:
its stylesheet is in the page, since Mallok stages assets from src/theme
only. Its tests import the real sample through a starter and hold every
page and every shop page whole; npm run preview -- --theme editorial, and
CI, bring it up on a real Worker.
An order whose payment page lapsed is cancelled unpaid, and its address is
whatever was typed into checkout. The lookup listed such orders and emailed
the address a link because of them, so a stranger could have the shop write
to someone who never bought anything. Only the statuses a payment leads to
count now, as the buyer's own emails already do.
…e two themes

The customer and sales panels, finding an order again by email, the
starter and the second theme are described where a reader looks for them,
with what each holds of a buyer's data. The design measures phase 3 against
the Next.js README item by item: every commerce item is met, and what is
open is Mallok's.
An oversold order is paid as oversold, never as paid, so the sales view
counted its refund and not the payment it gave back: a month with one such
order showed a negative net. Restocked and fulfilled, the order became
paid a month later and was counted then, for money taken earlier. Money is
counted when a payment is confirmed, either way. 0005 is unreleased but
may have run on a local database, so 0006 replaces the view.
The previous commit added 0006 and left this list at five.
The address typed was lower-cased by JavaScript, which folds all of
Unicode, and compared with SQLite's lower(), which folds ASCII only. An
address with a capital beyond ASCII found none of its orders, and one with
U+212A KELVIN SIGN, which JavaScript turns into an ASCII k, was sent a
link to the orders of the address it folded to. SQLite folds both sides
now, as the customers view does.
For an address with paid orders the route waited on two more writes — the
key that signs the orders' links and the email queued — before it
answered, so the time the answer took told a stranger whether the address
had bought here, which the page's words are careful not to. Both now run
after the answer.
The count of an address's paid orders compared lower(email), which no
index covered, so each request read every paid order through the status
index, refused requests included. The form is public and D1's allowance is
counted in rows read: enough requests could spend a day's allowance and
stop the shop. An index on the expression bounds a request to its
address's orders, and a refused request now reads none. The customers view
gets the same index on inquiries.
The cron cleared expired requests with the carts' limit of fifty a run, a
run an hour: past about fifty requests an hour the table grew without end,
and the addresses typed into the form were kept long after the day the
shop says it keeps them. One statement deletes them all now.
A review found what its tests could not, as they rendered only the full
sample with payments on: an empty sizes cell for a product that names no
sizes, an empty SKU for a cart line whose size was deleted, an empty
paragraph for a cart with no catalogue and no checkout to link to, and,
found by the new test for a bare site, an empty footer column for a site
that gave no contact. Each is left out or given a dash now. Its order page
is drawn in every status, as the commerce theme's now is.
Only a pending order's page was drawn, though the guide says both pages
are held whole in every state: paid, shipped with its carrier and number,
delivered, refunded, cancelled, oversold, and with tax and no company.
…arter to the seed

The limits are counted inside the statement that records a request; two
requests held at that write now show it, every run. The lookup lists every
status a payment leads to, not only paid. The starter is held to which
product each of the seed's variants belongs to, to every shipping rate and
its free-over amount, and to a product page in all four languages.
… last asked from

The customers panel took the newest contact's country, and an order's is
the country it ships to while an inquiry's is where the request came from,
as the edge reported it: one inquiry sent while travelling moved a buyer
abroad. The shipping country comes first; an inquiry's counts only for an
address that never ordered.
…s and keeps

Eight findings, each fixed with a test seen failing first, and the one
kept: a lookup's list hands out order links that do not expire. The guide
says how a view is changed once its migration has run, how an address is
folded, and why the lookup answers before it emails.
…ures

The first look — serif on warm paper, one narrow column, not one picture —
was turned down as ugly. The theme now sets its headings and figures in DIN,
the face of the standards these parts are made to, on titanium grey, leads
with a picture of a part beside the headline, shows every industry, case
study and product with its own picture, and puts a product's attributes and
a case's results in a drawing's title block. It still loads no file and runs
no script: the faces are the ones systems have.
@JasonYv
JasonYv merged commit 07463e1 into main Nov 2, 2026
1 check passed
@JasonYv
JasonYv deleted the feature/phase2-checkout branch November 2, 2026 15:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant