Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Mallok decides the contracts on both sides. Its documentation is the reference:
- **Inquiries are read in the admin** in a `table` panel with their lines as a related table, and marked, exported and deleted by the actions in `lib/inquiry-admin.ts`. An amount is stored twice, as minor units and as the text the buyer saw, because a table panel lists a column as it is stored. `cart_id` and `ip_hash` are in the table and not in the panel.
- **An inquiry is the first personal data the shop holds.** It goes in no log and no address, and the plugin's own job carries an id only. Every value goes through `escapeHtml` on its way into an email; a name, a company and a phone number are made one line each (white space collapses; it is not refused, because a refused form comes back empty); an address is held to an allow-list (`EMAIL_PATTERN_SOURCE`), because the admin makes a `mailto:` link of it; a cell of the export that a spreadsheet would run as a formula is made text, and so is every piece a semicolon would make a cell of (`inert`). **What the plugin cannot keep to itself is the email**: `ctx.sendEmail` stores the whole message in Mallok's `job` table, where deleting the inquiry does not reach it. `SECURITY.md` says so; do not claim otherwise.
- **What the shop holds is in a site export** (`exportFiles`, `lib/export.ts`; design §19): variants with the slug of their product, prices, the stock ledger, orders and their lines, payment events, the outbox, inquiries and their lines — a JSON file each under `shop/`, a row an object, as stored, with a manifest and the shop's own settings, which Mallok's `site.json` does not carry. Tables are read with `*`, so a column a migration adds is exported without anyone remembering; `test/shop/export.test.ts` fails when a new `p_shop_` table is neither exported nor on its list of those left behind (carts, rates, the scheduler's state), and when an exported table has a column the test does not list — so that a new column is looked at before it is carried out of the shop. A column an export adds to a row has a name no table's column has (`variant_sku`, `product_slug`): of two columns of one name D1 keeps the last. An inquiry's `cart_id` and `ip_hash` stay behind. Nothing is rewritten for a spreadsheet: that is the admin's CSV, which is for reading; this is for carrying. A table over `EXPORT_ROW_LIMIT`, or files over `EXPORT_BYTE_LIMIT` together, fail the export rather than leave rows out, because Mallok then refuses to call it a backup — a file missing rows would pass for one. Both are guards against a Worker's memory and neither is a measurement. The reason is in the endpoint's answer and in the Worker's log (`shop_export_refused`); Mallok's command line and admin show only that the shop failed, and suggest switching the failing plugin off — which would give a backup with nothing of the shop's in it.
- **Checkout is two routes** (`routes/checkout.ts`, `lib/checkout.ts`; design §20). `GET checkout` is the page: the cart as it will be ordered, a form sent by GET that chooses the country (`?country=DE`), and once one is chosen the shipping, the total and the order form, which carries that country hidden — the page has no script. `POST checkout/place` places the order and answers 303 to Stripe's page, or back to the checkout page with a kind (`?checkout=invalid&field=city`); like the cart's forms it never renders, and nothing typed travels in an address. **`readCheckout` is the one reading of a checkout** — `readCartFacts`, then where the cart can go and what that costs — and `quoteOf` the one sum; the page and the order both use them, and `pricedCartOf` turns that same reading into the order's lines. A country counts only when it is in a zone with a rate in the cart's currency. `lib/checkout-view.ts`'s header is the contract with the theme's `shop/checkout` layout. The shop takes payments only when both Stripe secrets are set (`stripeKeys`); until then the cart offers no checkout and the page says payment is unavailable.
- **Checkout is two routes** (`routes/checkout.ts`, `lib/checkout.ts`; design §20). `GET checkout` is the page: the cart as it will be ordered, a form sent by GET that chooses the country (`?country=DE`), and once one is chosen the shipping, the total and the order form, which carries that country hidden — the page has no script. `POST checkout/place` places the order and answers 303 to Stripe's page, or back to the checkout page with a kind (`?checkout=invalid&field=city`); like the cart's forms it never renders, and nothing typed travels in an address. **`readCheckout` is the one reading of a checkout** — `readCartFacts`, then where the cart can go and what that costs — and `quoteOf` the one sum; the page and the order both use them, and `pricedCartOf` turns that same reading into the order's lines. A country counts only when it is in a zone with a rate in the cart's currency. `lib/checkout-view.ts`'s header is the contract with the theme's `shop/checkout` layout. The shop takes payments only when both Stripe secrets are set (`stripeKeys`); until then the cart offers no checkout and the page says payment is unavailable. Every reading of a Stripe secret goes through `stripeSecret` (`lib/stripe-secrets.ts`), which drops the white space it was pasted with — Mallok keeps a secret as typed, and a signing secret saved with a space before it refused every delivery (design §22); `test/shop/checkout.test.ts` fails when another file reads one.
- **The order is written before Stripe is asked for anything**, `pending`, with its cart, its company, its zone's name, its tax mode and the site's origin; then, in tax mode `stripe`, a Stripe customer holding the address it ships to; then the Checkout session, which lapses after `CHECKOUT_LIFETIME_MS`; then the session is recorded on the order. A Stripe failure closes the order (`cancelled`, reason `failed`) and sends the buyer back with `payments_unavailable`. **One cart has one payment open at a time**: placing an order first closes at Stripe the session of every order still waiting from the same cart, and cancels it (`replaced`); the order is written only if no other from the cart is waiting and the visitor has placed fewer than `MAX_CHECKOUTS_PER_HOUR` in the hour, both asked inside the write (`guard` of `createPendingOrder`, `OrderNotPlacedError`); and a placement whose order was closed by another while it opened its session closes that session again. **"Not open" is not "closed"**: a session Stripe will not expire may have just been paid, its word not here yet. `closeCheckoutSession` asks Stripe, and an order whose session is complete is never cancelled — by a new checkout (`paid_meanwhile`), the admin, or the cron. Links and Stripe's return use the site's own domain when it has one (`siteOriginOf`), not the request's host.
- **`lib/stripe-client.ts` is every call to Stripe**, over `fetch`, at `STRIPE_API_VERSION`, each with an idempotency key built from what it acts on. A session carries the order line by line at its snapshot prices and shipping as one fixed option named after the zone, with `adaptive_pricing` off and only `card` and `link` allowed. Its failures are described by Stripe's identifiers (`StripeRequestError`), never its free text. A refund and an expiry carry no idempotency key: Stripe keeps a key's first answer for a day, failures included, and Stripe's own state already stops a full refund being made twice. Check a parameter against Stripe's current API reference before adding one: names change between versions (design §20, finding 1).
- **An order's page** (`routes/order.ts`, `GET order/:orderNo?k=…`, sent with `Referrer-Policy: no-referrer`) opens only with the secret its link carries: an HMAC of the order's id (`lib/order-access.ts`) under a key the shop makes once and keeps in `p_shop_state`, which an export leaves behind. A wrong secret, none and an unknown order all answer the same 404. The page reads the key and never makes it: a GET writes nothing. Links are built by `orderLink` from the origin the order was placed on (`site_origin`), because the emails that carry them are written by a job, which has no request.
Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
[![CI](https://github.com/fobstack/Nundar/actions/workflows/ci.yml/badge.svg)](https://github.com/fobstack/Nundar/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](LICENSE)

> **Status: in development.** Nundar is being rebuilt on Mallok. The catalogue, the cart, requests for a quote, checkout with Stripe, the seller's orders, customers and sales, and a second theme work locally; a purchase at Stripe has not been run end to end yet, and nothing has been deployed — see [What works today](#what-works-today). It is not ready to run a real shop.
> **Status: in development.** Nundar is being rebuilt on Mallok. The catalogue, the cart, requests for a quote, checkout with Stripe, the seller's orders, customers and sales, and a second theme work locally; a purchase has been run end to end in Stripe's test mode against a local site, and nothing has been deployed — see [What works today](#what-works-today). It is not ready to run a real shop.

---

Expand Down Expand Up @@ -65,7 +65,7 @@ Nundar builds on `mallok@0.1.0-rc.11`, the first release with the plugin API the
| **Inquiries** | The cart sent as one request for a quote, from a form on the cart page: who to answer, and a message. A size with no price can go in the cart to be asked about. The buyer lands on the inquiry's number; the seller is told by email, answerable straight to the buyer, and finds every inquiry in the admin with its lines — to mark, export as CSV, or delete | A challenge in front of the form (it waits for Mallok), which is why the email confirming to the buyer is off unless switched on |
| **Taking your data with you** | What the shop holds is in the site's export (`mallok export`), beside the content: variants, prices, the stock ledger, orders, payment events, inquiries and the shop's settings, a JSON file each under `shop/`, as stored | An import of those files; an export of a table too large for one request (both wait for Mallok) |
| **Shipping** | Zones set in the admin: the countries each covers, a fixed rate in each currency, and an amount from which it ships free. A country in no zone is not offered at checkout | Rates by weight |
| **Checkout and payment** | A checkout page in the site's own design and language, with no script: the country the order goes to, shipping and the total for it, the buyer's company and address, then Stripe's hosted page to pay — by card, or Link, at the shop's own prices with Stripe's currency conversion off. Tax is not charged unless the shop switches Stripe Tax on. An order's own page, opened by the signed link Stripe returns the buyer to and every email carries. A payment takes stock exactly once however often Stripe reports it, is held to the order's total, and empties what was ordered from the cart; an unpaid order is cancelled an hour after its payment page lapses | A purchase made at Stripe in test mode has not been run yet (it needs a shop's own test keys); buyer accounts; invoices of the shop's own; partial refunds |
| **Checkout and payment** | A checkout page in the site's own design and language, with no script: the country the order goes to, shipping and the total for it, the buyer's company and address, then Stripe's hosted page to pay — by card, or Link, at the shop's own prices with Stripe's currency conversion off. Tax is not charged unless the shop switches Stripe Tax on. An order's own page, opened by the signed link Stripe returns the buyer to and every email carries. A payment takes stock exactly once however often Stripe reports it, is held to the order's total, and empties what was ordered from the cart; an unpaid order is cancelled an hour after its payment page lapses | Not yet tried at Stripe: Stripe Tax, Apple Pay and Google Pay, a card that asks for authentication, an order in EUR or GBP; buyer accounts; invoices of the shop's own; partial refunds |
| **Orders in the admin** | Every order with its lines, its address and its amounts: mark shipped (tracking number and carrier), delivered, cancel one that was not paid, refund in full — at Stripe first, then the books, with the stock back unless the goods have shipped — or fulfil one that was paid for after its stock had gone, once restocked. Payments the shop could not keep are listed to refund. The buyer is written to in their language when an order is confirmed, shipped, refunded or cancelled; the seller is told of every new order and every refund owed | |
| **Customers and sales** | Every address that ordered or asked for a quote, with its orders and inquiries beneath it and what it has spent in each currency; sales by month — paid, refunded, net and the average order — and by product, per currency | |
| **Finding an order again** | No account to make: a buyer types the address they ordered with and is emailed a link, good for a day, to every order they paid for. The page says the same whether or not there were any, and asking is limited per visitor and per address | |
Expand Down Expand Up @@ -174,7 +174,7 @@ The shop takes payments through Stripe's hosted checkout, on your own Stripe acc
4. **The notification address.** The shop's **Notification email** setting is where new orders, refunds owed and inquiries are announced. Email goes through the site's own email settings (Settings → Email).
5. **Optional.** **Tax** set to `stripe` has Stripe Tax add tax at payment, wherever your Stripe account is registered to collect it, for Stripe's fee; it is `none` by default, and prices are without tax. **Terms page** names a page a buyer ticks that they accept. **Order number prefix** is `ND` unless you set another.

To try it on a local site (`npm run dev`), Stripe's command-line tool can forward test events to it — `stripe listen --forward-to http://localhost:8787/_mallok/p/shop/stripe/webhook --events payment_intent.succeeded,checkout.session.expired --latest` — and prints the signing secret to enter. Without `--latest`, it sends events at your account's default API version. Pay on Stripe's page with one of Stripe's test cards.
To try it on a local site (`npm run dev`), Stripe's command-line tool can forward test events to it — `stripe listen --forward-to http://localhost:8787/_mallok/p/shop/stripe/webhook --events payment_intent.succeeded,checkout.session.expired --latest` — and prints the signing secret to enter. Without `--latest`, it sends events at your account's default API version. Pay on Stripe's page with one of Stripe's test cards. The listener's login lapses after a while: it may reconnect and stop forwarding, or stop with an expired OAuth token, and what Stripe sent meanwhile does not reach the shop — start it again and deliver a missed event with `stripe events resend <event id>`.

## Commands

Expand All @@ -192,7 +192,7 @@ To try it on a local site (`npm run dev`), Stripe's command-line tool can forwar

## Deploying

Not yet. The shop can take payments now, and a purchase in Stripe's test mode has still to be run end to end on a real Stripe account before anyone relies on it. Nothing here has been measured on a real Cloudflare account either. When Nundar is ready, deployment is Mallok's own: `npx mallok create . --slug <slug>`, which creates the Worker, the D1 database and the R2 bucket on your own Cloudflare account, after which Mallok's first-run wizard offers the sample shop to start from. That path has not been run for this repository.
Not yet. A purchase has been run end to end in Stripe's test mode against a local site — paid, delivered twice, refunded, and orders expired and cancelled (design §22) — but nothing here has been deployed or measured on a real Cloudflare account. When Nundar is ready, deployment is Mallok's own: `npx mallok create . --slug <slug>`, which creates the Worker, the D1 database and the R2 bucket on your own Cloudflare account, after which Mallok's first-run wizard offers the sample shop to start from. That path has not been run for this repository.

## Languages and currencies

Expand Down
Loading
Loading