DEV Community: Daniel Pertu

Nine indexes on one queue table, five of them partial, three of them on a jsonb path

Daniel Pertu — Thu, 22 Oct 2026 10:19:50 +0000

Nakodo's background work is one Postgres table called jobs, drained by a cron every five minutes. The whole pipeline it runs is described in plain English on how it works: research a brand's site, look for creators, check them, write and send email, read the replies. Every step of that is rows in this table.

The schema has 25 tables and 55 indexes. Nine of them are on jobs, which is more than any other table has, and five of the six partial indexes in the whole database are here. That distribution is not an accident, and it is the most useful thing I have learned about queue tables in Postgres.

A queue table is mostly history

export const jobs = pgTable("jobs", {
  id: uuid().primaryKey().defaultRandom(),
  type: text({ enum: JOB_TYPES }).notNull(),
  campaignId: uuid().references(() => campaigns.id, { onDelete: "cascade" }),
  payload: jsonb().$type<JobPayload>().notNull(),
  dedupeKey: text(), // e.g. "enrich:UC123"; only one open job per key
  status: text({ enum: ["pending", "running", "done", "failed"] }).notNull().default("pending"),
  attempts: integer().notNull().default(0),
  runAfter: timestamp({ withTimezone: true }).notNull().defaultNow(),
  lockedAt: timestamp({ withTimezone: true }),
  lastError: text(),
  runId: uuid().references(() => runs.id, { onDelete: "set null" }),
  createdAt: createdAt(),
  finishedAt: timestamp({ withTimezone: true }),
});

At any moment a handful of these rows are pending or running and the rest are done or failed. Almost every question the app asks is about the handful: what can I claim now, does this key already have open work, what is this campaign still waiting for. Almost every row in the table is irrelevant to all of those questions.

An ordinary index does not know that. It indexes the finished rows too, gets bigger every day, and makes the planner walk entries that can never match. A partial index does know it:

index("jobs_open_campaign_idx")
  .on(t.campaignId)
  .where(sql`${t.status} in ('pending', 'running')`),

which drizzle-kit turns into exactly what you would have written by hand:

CREATE INDEX "jobs_open_campaign_idx" ON "jobs" USING btree ("campaign_id")
  WHERE "jobs"."status" in ('pending', 'running');

The index now holds tens of rows rather than hundreds of thousands, it stays that size for ever (finished jobs are deleted after 14 days by the nightly maintenance run), and it costs nothing to maintain on the 99% of writes that are status changes into done.

The catch, and it is a sharp one: the planner will only use a partial index if it can prove your query implies the index predicate. The predicate here is a literal status in ('pending', 'running'), so a query that asks for status <> 'done' and status <> 'failed' describes the same rows and gets a sequential scan. Partial indexes make the exact phrasing of a WHERE clause load-bearing, which means the predicate has to be written once in the application and reused. Ours is, in both the TypeScript and the SQL that reads it.

The dedupe index does something a constraint cannot

uniqueIndex("jobs_open_dedupe_uq")
  .on(t.dedupeKey)
  .where(sql`${t.status} in ('pending', 'running')`),

CREATE UNIQUE INDEX "jobs_open_dedupe_uq" ON "jobs" USING btree ("dedupe_key")
  WHERE "jobs"."status" in ('pending', 'running');

The rule is "only one open job per dedupe key". Not one job ever: the same creator is read again weeks later, the same campaign searches again tomorrow. A UNIQUE table constraint cannot express that, because constraints cannot be partial in Postgres. Only a unique index can, which is the reason to reach for uniqueIndex rather than unique even when you are not writing an expression.

Two things follow from it that are easy to get wrong.

dedupeKey is nullable, and in a unique index nulls do not conflict with each other, so any number of jobs with no dedupe key can be open at once. That is the behaviour we want (one-off work has no key) and it is worth saying out loud, because "unique" and "at most one" are not the same statement when nulls are allowed.

And the insert that relies on it is a bare conflict clause:

const rows = await db.insert(jobs).values(newJobs.map(...)).onConflictDoNothing().returning({ id: jobs.id });
return rows.length;

ON CONFLICT DO NOTHING with no conflict target handles a violation of any unique index, partial ones included, so enqueueing twenty jobs of which three already have open work inserts seventeen and returns seventeen ids. The moment you want DO UPDATE instead, you have to name an inference target, and for a partial index that means repeating the index predicate in the statement (ON CONFLICT (dedupe_key) WHERE status in (...) DO UPDATE), because Postgres has to pick the index out by its definition. That asymmetry between DO NOTHING and DO UPDATE is the single most surprising thing about partial unique indexes. The related trap is self-conflict inside one statement: two jobs with the same key in the same VALUES list are fine under DO NOTHING (the second one sees the first and is skipped), but the same batch under DO UPDATE raises "ON CONFLICT DO UPDATE command cannot affect row a second time". If you ever move from one to the other, dedupe the batch in application code first.

Three indexes on expressions, two of them into the jsonb

Some job types name their campaign in the column, and some only name it in the payload, because a job about a creator can serve several campaigns. Both have to be findable:

index("jobs_open_payload_campaign_idx")
  .on(sql`(${t.payload}->>'campaignId')`)
  .where(sql`${t.status} in ('pending', 'running')`),
index("jobs_open_payload_channel_idx")
  .on(sql`(${t.payload}->>'channelId')`)
  .where(sql`${t.status} in ('pending', 'running')`),

CREATE INDEX "jobs_open_payload_campaign_idx" ON "jobs" USING btree (("payload"->>'campaignId'))
  WHERE "jobs"."status" in ('pending', 'running');

The double parentheses in the generated SQL are not style. An index on an expression needs the expression in its own parentheses, and getting that wrong is a syntax error rather than a silent problem, which is the one merciful thing here. What is not merciful is the matching: the query has to use the same expression, character for character in spirit. payload->>'campaignId' matches, payload->'campaignId' (returning jsonb rather than text) does not, and neither does a cast bolted onto one side. Our reader writes the same thing the index does:

sql`${jobs.payload}->>'campaignId' = ${campaignId}`

An alternative was a GIN index on the whole payload, which would have answered every possible payload question. It would also have been far larger, and we only ever ask two. Two small btree indexes on two known paths beat one general index you cannot predict the cost of.

The third expression index is the one that pays for fairness between campaigns:

index("jobs_served_idx")
  .on(t.type, sql`coalesce(${t.finishedAt}, ${t.lockedAt})`, t.campaignId)
  .where(sql`${t.status} in ('done', 'running')`),

The question it answers is "when was each campaign last served work of this type", and the answer has two sources: a finished job has a finished_at, a job still running was last served when it was locked. Without the index that is a CASE or a coalesce in the query, evaluated per row over the whole history. With it, the coalesce is materialised in index order, and the predicate restricts it to done and running so failed and pending rows do not clutter it. Note that this index's predicate is a different pair of statuses from the other four, which is the clearest possible demonstration that the predicate belongs to the question, not to the table.

What Drizzle gives you, and what to watch

The whole vocabulary is index(), uniqueIndex(), .on() with either columns or sql fragments, .where(sql\...) and .using("gin", ...). The schema's two GIN indexes (one on a text array, one on a to_tsvector expression) use the same builder.

What to watch is how changes are migrated. In our history, one index was dropped and recreated three times across migrations, because an edit to an index's columns or predicate is not an alteration in Postgres; it is a DROP INDEX plus a CREATE INDEX. drizzle-kit generate writes exactly that, which is correct and also a lock on a table big enough to matter. Read the generated SQL, and if the table is large, replace the pair with CREATE INDEX CONCURRENTLY by hand and keep the migration honest about what it is doing.

The last thing worth saying is the cost. Nine indexes on a write-heavy table is not free: every insert and every status change maintains all nine. The reason it is affordable here is that the table never grows, because finished rows are deleted on a 14-day window. A queue table with no retention policy and nine indexes is a different and much worse story, and the retention is the decision that makes the indexing strategy work at all.

Our design system is a markdown table of nineteen motifs, and the useful column is the one that says no

Daniel Pertu — Thu, 22 Oct 2026 10:17:33 +0000

Most design systems I have worked in document what a component is and what props it takes. The part that decides whether an interface looks made or assembled is the part they usually leave out: where each thing is allowed to appear, and what it is never allowed to mean.

Nakodo is a field guide for finding creators, and its visual language is lifted from naturalists' plates and ledgers. docs/brand.md section 5.5 is a table of nineteen motifs with four columns: the motif, what it is, where it is used, and a rule. Some of those rules:

Catalogue numbers: "Always 4 digits for creators, 2 for guides. Sequence follows first sighted order, so numbers never change."
Pointer arrows: "Marketing and explanatory views only; never inside tables."
Hatching: "Always means not yet observed or locked. Never decorative in UI. Always paired with text."
Double rule: "Max one per screen."
Stamps: "Ink or cyano only, rotated at most -2 degrees. Never ochre, never red."
Live dot: "The only pill shape in the app."
Attention mark: "Max one kind of mark per row. Never used for status."
Tally marks: "Above 25, switch to a plain bar meter with numbers."

src/components/brand/marks.tsx is 228 lines and is that table turned into components. This post is about which of those rules the code can enforce and which ones it can only make easy.

Rules a type can hold

export function Stamp({ label, date, tone = "ink", className }: { label: string; date?: string; tone?: "ink" | "cyano"; className?: string }) {
  return (
    <span className={cn("inline-flex -rotate-2 items-center gap-1.5 rounded-sm border-[3px] border-double px-1.5 py-px",
      tone === "cyano" ? "border-cyano-700 text-cyano-700 dark:border-cyano-300 dark:text-cyano-300" : "border-foreground/70 text-foreground/80", className)}>
      <span className="label-caps">{label}</span>
      {date && <span className="catalogue">{date}</span>}
    </span>
  );
}

"Never ochre, never red" is a union of two strings, so breaking it is a type error. The rotation is not a prop at all: -rotate-2 is baked in, because "at most -2 degrees" with a prop would have meant someone eventually passing -6. The double border is a real CSS double 3px border rather than two elements, which is the same trick the app uses for its horizontal double rules.

Same with the catalogue numbers:

export function CatalogueNo({ n, kind = "creator" }: { n: number; kind?: "creator" | "guide" }) {
  const label = kind === "creator" ? `No. ${String(n).padStart(4, "0")}` : `Guide ${String(n).padStart(2, "0")}`;
  ...

Four digits or two, decided by the kind, not by the caller. The homepage carries seven of them; you can count the string No. 0 in the HTML.

Rules only CSS can hold

The specimen tag is "a small label with a notched left edge and a punched hole". It is one utility and one absolutely positioned dot:

@utility specimen-tag {
  position: relative;
  clip-path: polygon(7px 0, 100% 0, 100% 100%, 7px 100%, 0 50%);
  padding-left: 14px;
}

<span className="absolute top-1/2 left-[6px] size-1 -translate-y-1/2 rounded-full bg-background" aria-hidden="true" />

The hole is bg-background, not transparent, so it reads as punched through the tag to the page behind it. That is a cheat that only works because the tag never sits on anything but the page colour, which is itself a rule nobody wrote down. Two of these are in the homepage's HTML and two more on the pricing page, where they are the plan kickers: Notebook, Field kit, Expedition.

The plate marks ("small registration crosses at the corners of a framed area", marketing and ceremony only) are an array of four position class strings mapped over one SVG:

{(["-top-1.5 -left-1.5", "-top-1.5 -right-1.5", "-bottom-1.5 -left-1.5", "-right-1.5 -bottom-1.5"] as const).map((pos) => (
  <svg key={pos} viewBox="0 0 12 12" className={cn("absolute size-3 text-foreground/50", pos)} aria-hidden="true">
    <path d="M6 0v12M0 6h12" stroke="currentColor" strokeWidth="1" />
    <circle cx="6" cy="6" r="2.5" fill="none" stroke="currentColor" strokeWidth="1" />
  </svg>
))}

Four crosses per plate, so the count in the live HTML divides by four: M6 0v12 appears twelve times on the homepage, which is three plates. The pricing page has none, because plates are for the landing and for ceremony, and nothing on the pricing page is a ceremony.

Hatching is the one motif with a forced-colours fallback, because a repeating gradient that means "locked" disappears in Windows high contrast mode and would take the meaning with it:

@media (forced-colors: active) {
  .hatch { background-image: none; border: 1px dashed CanvasText; }
}

The tally meter, which is the rule table at its best

"Usage meters for small allowances (up to 25). Above 25, switch to a plain bar meter with numbers."

{limit <= 25 ? <Tally used={shown} limit={limit} /> : (
  <div className="h-1.5 overflow-hidden rounded-sm bg-paper-150 dark:bg-muted" role="presentation">
    <div className="grow-x h-full bg-cyano-700 dark:bg-cyano-400" style={{ width: `${(shown / limit) * 100}%` }} />
  </div>
)}

That threshold is a product decision disguised as a design one. A paid plan on Nakodo contacts 25 new creators or businesses each weekday, which is exactly on the line, so a Pro account sees five groups of five strokes rather than a bar. Tally marks are countable; a bar at 72% is not. Above 25 the strokes would be unreadable and the bar wins.

Each group of five is one SVG with four uprights and a diagonal:

{Array.from({ length: Math.min(size, 4) }, (_, i) => (
  <Stroke key={i} d={`M${3 + i * 5} 1.5V12.5`} n={start + i} used={used} />
))}
{size === 5 && <Stroke d="M1 11.5L22 2.5" n={start + 4} used={used} />}

and every stroke is drawn twice, once as a faint guide and once as the mark:

<path d={d} strokeWidth="1.5" className="stroke-paper-300 dark:stroke-ink-700" />
{n < used && <path d={d} pathLength={1} strokeWidth="1.5" className="draw-in stroke-foreground" style={{ "--i": n }} />}

Rendering the unused strokes means the meter has a fixed width and shows the allowance, not just the usage. pathLength={1} normalises every stroke to one unit so one dash rule covers both the uprights and the longer diagonal:

@keyframes draw-in { from { stroke-dashoffset: 1; } }
/* A gap longer than the dash, so no round cap shows at the far end while
   a stroke waits to be drawn. */
.draw-in { stroke-dasharray: 1 2; }
[data-reveal="go"] .draw-in { animation: draw-in 0.16s ease-out calc(0.15s + var(--i, 0) * 45ms) both; }

The comment above stroke-dasharray: 1 2 is the sort of thing you only write after seeing it: with 1 1, the round line cap of the waiting dash pokes out at the end of the path, and every tally shows a row of faint dots before it is drawn. The --i on each stroke is its index in the whole allowance, so twenty-five strokes are drawn in counting order at 45ms apart rather than all at once, and Reveal holds a meter below the fold until it is scrolled to.

Rules the code cannot hold

"Max one per screen" is three of the nineteen rules (double rule, margin annotation, and effectively the help button). Nothing enforces them. A component cannot know what else is on the page, and a lint rule would need to understand routing and layouts.

What the table does instead is make the limit cheap to check, because each motif has exactly one meaning, so counting them is counting a string. The homepage has three plates, seven catalogue numbers, two specimen tags and six field-mark bullets (M0 5H9), and the pricing page has two pointer arrows (M6 5H48) and no plates. Every one of those numbers came out of curl and grep on the live pages while writing this post, which is the whole argument for a vocabulary of fixed shapes: you can audit it from outside the app.

Two things I found doing that. Kicker is in this file and has three call sites, all of them in the campaigns list rather than above a marketing section heading, which matches the house rule that section names are a nav and page thing. And choiceCardClass, over in the forms module, is exported with no consumers at all, which is what happens to a shared constant when the thing that was going to use it got written differently.

The point of writing the rule column down is not governance. It is that a motif with one meaning can be used anywhere without thinking, and a motif with two meanings is just decoration with extra steps.

Eighteen useState calls in one help panel, and the key prop that throws them all away

Daniel Pertu — Thu, 22 Oct 2026 10:15:38 +0000

The help button at the bottom left of every signed-in page in Nakodo opens a panel that does three jobs in one surface: it walks the written manual, it offers an assistant when the manual did not have it, and it opens a conversation with a person when that did not either.

src/components/support/panel.tsx is 818 lines, the fourth largest client component in the app (the results table, the proposal editor and the brief editor are bigger; its own code comment claiming second place is out of date). It holds eighteen useState calls and two refs. I want to defend that, and then show the four pieces of it that are not obvious.

Nine steps, and a back stack that is not the browser's

type Step = "home" | "topics" | "answer" | "ask" | "form" | "opened" | "solved" | "list" | "thread";

const go = (next: Step) => {
  setStack((s) => [...s, step]);
  setError(null);
  setStep(next);
};
const back = () => {
  setError(null);
  setStep(stack[stack.length - 1] ?? "home");
  setStack((s) => s.slice(0, -1));
};

A panel with history in it is tempting to wire into the router, so that the back button works. Do not. The reader did not navigate anywhere: they are still on their campaign, with a panel over it. Pushing history entries means the back button out of the panel is also the back button out of the page they were working on, and the first time someone presses it twice they lose their place in the app to leave a help panel.

So the stack is an array of steps in component state. The back arrow in the header renders only when stack.length > 0, which is the same condition that decides whether the header shows the subtitle "Answered by a person, by email", because that line belongs to the panel's front door and not to a step inside it. Escape closes the whole panel, with stopPropagation so the dialog under it (if the panel was opened from inside one) does not also close.

Eighteen states, grouped, and why they are not reducers or a machine

They fall into five groups, in the order the panel uses them: where in the manual you are, the assistant's turns, the conversation form, the list of your conversations, and the thread you opened. Every group is small, none of them has a transition that depends on another group's internals, and the panel's steps are decided by the step union rather than by combinations of booleans.

A reducer would turn eighteen useState into one object plus eighteen action types and a switch, which is more code for the same transitions. A state machine library would describe the nine steps precisely and then still need all of the data above as context. The honest reason this is a pile of hooks is that each piece is read in exactly one place and written in one or two, and the file's structure (manual, assistant, person, conversations, drawing it, each under its own banner comment) carries the organisation that a reducer would otherwise have to.

One of those states is worth more than its line count: message, the text someone has written to a person. It lives here rather than in the form step, so closing the panel mid-sentence and opening it again does not lose it. The widget keeps the panel mounted once it has ever been wanted, which is what makes that work.

The chunk arrives on hover, and the panel is never server rendered

const SupportPanel = dynamic(() => import("./panel").then((m) => m.SupportPanel), { ssr: false });

const want = () => setWanted(true);
...
<button type="button" onPointerEnter={want} onFocus={want} onClick={() => { want(); setOpen((o) => !o); }} aria-expanded={open} ...>

Nobody is waiting on a help panel while a page paints, so it is a separate chunk and it is not server rendered. But a chunk that starts downloading on click gives you a button that does nothing for 200ms. onPointerEnter and onFocus set wanted, which mounts the panel closed, so by the time the click lands the component is usually already there. Keyboard users get the same head start from onFocus, and a touch user gets the pointer enter that precedes the tap.

The panel renders null while closed, so keeping it mounted costs one render and buys the half-written message.

A window event, caught by the thing that is always mounted

Other parts of the app link into the panel: a campaign header can offer help about limits, a settings page can open the part of the manual about emails. That is a custom window event, and the listener is in the 89-line widget rather than in the panel:

useEffect(() => {
  function asked(event: Event) {
    setRequest((last) => ({ n: (last?.n ?? 0) + 1, of: (event as CustomEvent<SupportOpenRequest>).detail ?? {} }));
    setWanted(true);
    setOpen(true);
  }
  window.addEventListener(SUPPORT_OPEN_EVENT, asked);
  return () => window.removeEventListener(SUPPORT_OPEN_EVENT, asked);
}, []);

The panel is a lazy chunk that may not exist yet when a page asks for it, so the listener has to live in the component that is always mounted. That is the whole reason the widget and the panel are two files.

Then the counter:

<SupportPanel key={request?.n ?? 0} ... />

n increments on every request, so the key changes, so React throws the old panel away and mounts a new one. This is the entire mechanism for "asking for the same part of the manual twice starts afresh rather than leaving you where you were". The alternative, an effect inside the panel that watches the request prop and calls eight setters to sync it, is the thing React's own docs call out as a smell, and it would have had to decide what to do about the half-written message, the assistant turns and the back stack one by one. A key is one line and gets all eighteen right.

That is also why the initial state is computed by a pure function rather than patched in afterwards:

const start = startingPoint(request);
const [step, setStep] = useState<Step>(start.step);
const [stack, setStack] = useState<Step[]>(start.stack);

startingPoint opens the panel on the assistant with the named section chosen and the line that page sent already in the transcript, seeds the stack with ["home"] so the back arrow leads somewhere instead of trapping the reader, and ignores a topic that does not belong to the named section, so an out-of-date deep link cannot file a conversation under the wrong heading. With no request it returns the front door.

The one rule: the gate must never be a dead end

A conversation with a person opens only after the assistant has had a go. That is deliberate and it is also the riskiest thing in the panel, because a gate with a broken gatekeeper is a wall.

const exhausted = turns.length >= SUPPORT_LIMITS.assistantTurns; // 2
const assistantFailed = turns.length === 0 && error !== null && step === "ask";
const leadWithPerson = exhausted || answered === false || assistantFailed;

A failed question counts as a go. If the assistant cannot be reached at all, the panel leads with the person instead of insisting on a step that cannot be completed. The three ways to reach a human are therefore: the assistant answered and said it did not get there, the assistant has used both of its turns, or the assistant could not be asked.

The failure path in ask() is the other half of that care:

const result = await askSupportAction({ question: asked, topic: topic?.id ?? null, history: turns });
setAsking(false);
if (!result.ok) {
  setError(result.error);
  setTranscript((t) => t.slice(0, -1));
  setQuestion(asked);
  return;
}

The question was appended to the transcript optimistically before the call, so a failure pops it off again and puts the text back in the box. Without the pop, the transcript that later travels with the conversation to a person would contain a question with no answer, and the reader would have to retype what they had just written.

Small things that make it feel like a panel and not a page

The scroller is aria-live="polite", and one effect pins it to the bottom on changes to [step, transcript, asking, thread, loading]. Whatever just arrived is what you see.
role="dialog", tabIndex={-1}, and focus taken inside a requestAnimationFrame on open, with cancelAnimationFrame in the cleanup so a panel closed in the same frame does not steal focus afterwards.
On a phone it is inset-0 with a backdrop and the launcher hides itself (max-sm:hidden); on a desktop it is a 23rem by 34rem card at bottom-18 left-4, capped with max-h-[calc(100svh-7rem)]. The header and footer pad with env(safe-area-inset-top) and env(safe-area-inset-bottom).
Bottom left, because toasts live bottom right, and a help button underneath the thing telling you what just happened is no use.
There are no illustrations in the panel, on purpose. It opens over whatever page you were on, that page may already have its one illustration, and the panel cannot know whether adding one would make it two.

The panel is behind sign-in, so there is nothing to click on from here, but the writing it serves is public: the same plain-answer style is what how it works and the guides are written in, and the limits it explains are the ones on the pricing page. Eighteen useState calls is not elegant. Losing someone's half-written message because a prop changed would be worse.

Four form components hold every form in our app, and writing this post found the one bug in them

Daniel Pertu — Thu, 22 Oct 2026 10:13:46 +0000

Nakodo has no form library. No React Hook Form, no Formik, no resolver. Forms are Server Actions with useActionState, inputs are plain inputs, and everything the forms share lives in src/components/forms.tsx, which is 162 lines and exports four components and two class name strings. Fifteen files import from it.

That is the whole abstraction, and it is worth writing down because the interesting decisions in a form system are not validation. They are what happens after submit, what a hint is, and where the Save button goes.

FormResult: 19 banners, two ARIA roles, one of them deliberate

Every form in the app ends with the same component, 19 times across 11 files:

export function FormResult({ state, card = false, className }: { state: Result; card?: boolean; className?: string }) {
  if (state?.error) {
    return (
      <p role="alert" className={cn("text-sm text-danger", className)}>
        {state.error}
        {state.upgrade && (
          <> <Link href={planHref("limit_form")}>See plans</Link></>
        )}
      </p>
    );
  }
  if (!state?.message) return null;
  return card ? (
    <p role="status" className={cn("flex gap-2 rounded-md border bg-card p-4 text-sm", className)}>
      <CheckIcon className="mt-0.5 size-4 shrink-0 text-cyano-700 dark:text-cyano-300" aria-hidden="true" />
      {state.message}
    </p>
  ) : (
    <p role="status" className={cn("text-sm text-muted-foreground", className)}>{state.message}</p>
  );
}

role="alert" for the failure and role="status" for the success is not symmetry for its own sake. alert maps to an assertive live region: a screen reader interrupts whatever it was reading, which is right for "we did not save your work". status is polite: it waits for a pause, which is right for "saved". Getting those the other way round produces a form that shouts about success and whispers about failure.

The upgrade boolean is the other load-bearing part. A plan limit is not a validation error and not a server error; it is a product state with an answer. One LimitError thrown anywhere in an action becomes { ok: false, error: e.message, upgrade: true } at the boundary, and the banner that renders it grows a link to the plans. No form has to know that a limit exists, and no second component renders limit messages differently from other errors.

card exists for the two places where the confirmation is the entire outcome of the page rather than feedback beside fields: the sign-in and sign-up forms, where the result is "we sent a confirmation link to that address" and there is nothing else left on screen to look at.

Field: 43 call sites, and the bug

export function Field({ id, label, optional, hint, className, children }) {
  return (
    <div className={cn("space-y-1.5", className)}>
      <Label htmlFor={id}>
        {label} {optional && <span className="font-normal text-muted-foreground">(optional)</span>}
      </Label>
      {children}
      {hint && <p className="text-[13px] text-muted-foreground">{hint}</p>}
    </div>
  );
}

43 uses across 9 files, 18 of them passing a hint. The label is wired to the control through htmlFor, which is the part people remember. The hint is not wired to anything, which is the part people forget, and I am one of them: a <p> after an input is read by a screen reader only if the user happens to keep walking the document, and the field's accessible description stays empty. Someone tabbing through the form hears "Views, edit text" and never hears "Use the median views of the creator's recent videos".

I noticed because the sign-up form does not use this component. Its fields are hand-rolled to fit the password hint onto the label row, and in doing so they did it properly. You can check both live, without an account:

The sign-up form renders <span id="password-hint" class="text-[13px] ...">At least 8 characters</span> and the input beside it carries aria-describedby="password-hint".
The sponsorship cost calculator renders seven text-[13px] hints through Field, and the page contains zero occurrences of aria-describedby.

The fix is to default the id (${id}-hint), put it on the paragraph, and pass it down to the control, which the component cannot do today because it renders children rather than owning the input. That last part is the actual design flaw: a field wrapper that takes an arbitrary child cannot add attributes to it, so the wiring has to be the caller's job, which means it will be forgotten. Either Field takes the input's props and renders it, or the hint id has to be returned to the caller. I have left it as it is for now and written it down rather than quietly shipping a redesign in the middle of a post, but it is a real gap in an app whose public pages are otherwise checked for this sort of thing.

ChoiceCards: the selected state never reaches React

Four uses, and not one of them tracks which card looks selected:

export const choiceCardClass =
  "cursor-pointer rounded-lg border bg-card transition-colors hover:border-ink-400 has-checked:border-primary has-checked:bg-selected has-focus-visible:outline-2 has-focus-visible:outline-offset-2 has-focus-visible:outline-ring";

The radio stays a real radio inside a real <label>, so arrow key navigation, the form's own value, required validation and screen reader semantics all come free. Tailwind 4's has-checked: and has-focus-visible: variants compile to :has(:checked) and :has(:focus-visible) on the card, so the card paints itself from the input's state. In the grid layout the radio is sr-only and the whole card is the control; in the list layout it stays visible with accent-primary, because a narrow panel reads better with the dot showing.

The one React subtlety is supporting controlled and uncontrolled use from one component:

checked={value === undefined ? undefined : value === o.value}
defaultChecked={defaultValue === undefined ? undefined : defaultValue === o.value}

Passing checked={false} instead of undefined would make it a controlled input with no onChange in the uncontrolled case, which React warns about and which freezes the radio. Passing undefined leaves the attribute off entirely, so the same JSX is either controlled by a parent's state or left to the form's own FormData. Two of the four call sites are controlled by a parent's state (the brief and proposal editors, which compare the choice against what is saved) and two are left to the form.

PanelForm: Save stays in view

<form action={action} className="flex min-h-0 flex-1 flex-col">
  {top}
  <div className={cn("min-h-0 flex-1 overflow-y-auto px-4", bodyClassName)}>{children}</div>
  <div className="flex items-center justify-end gap-2 border-t px-4 py-3">...</div>
</form>

Editors in the app open in a side sheet, and a long brief scrolls. The footer is not sticky, it is a flex sibling that is not allowed to shrink, which means no position: sticky, no z-index, and no gap under the last field. The two min-h-0 are the trick: a flex child defaults to min-height: auto, so the scrolling body would otherwise refuse to be smaller than its content and push the footer off the bottom of the sheet. The exported panelContentClass sets the sheet's width in six places, including the data-[side=right]: variants Radix needs, so one string decides how wide every editor panel is.

While counting call sites for this post I also found that choiceCardClass is exported and used only inside its own module. eslint-config-next does not flag unused exports, so a public-looking name with no consumers can sit there indefinitely. It is two lines of cleanup, but it is also a good argument for counting your own call sites occasionally.

Why not a form library

Because none of the four components above is about forms. They are about this product's answers to four questions: what does a failed save look like, what is a hint, what does a choice look like, and where does Save live. A library would have given me validation I do not need (the actions validate with Zod, server side, where it counts) and would not have given me a single opinion about any of those four. 162 lines, four components, one real bug found by writing them up in public.

Our welcome card prints a five digit permit number that cannot tell you how many users we have

Daniel Pertu — Thu, 22 Oct 2026 10:10:35 +0000

Nakodo is dressed as a field guide. Plans are called Notebook, Field kit and Expedition on the pricing page, creators are catalogued with numbers, and contacted ones get a rubber stamp. So when someone finishes setting up their first campaign, what they get is a permit: a framed plate with their name, their plan, the date, and a stamp that lands on it a beat later.

Field permit No. 04182
Holder   you@example.com
Plan     Field kit, Pro
Issued   22 Oct 2026

Permit issued. Nakodo is out surveying now, and what it finds shows up below.

It is 68 lines of component and it is the kind of thing that looks like pure decoration until you try to ship it. Three things in it are not decoration at all.

A sequential number would publish our user count

The obvious implementation of "No. 04182" is a counter. Do that and the first screen a new customer sees tells them exactly how many people signed up before them, which for an app in its first months is the one number you would rather not hand out. Worse, two customers comparing notes a week apart can measure the growth rate.

So the number is derived, not counted:

// A stable five-digit number from the user ID, so it doesn't reveal how many users there are.
function permitNumber(userId: string): string {
  return String(parseInt(userId.replace(/-/g, "").slice(0, 8), 16) % 100000).padStart(5, "0");
}

The account's UUID is random, the first eight hex digits are 32 bits of it, and the modulo flattens that into 00000 to 99999. The same account always gets the same permit, with no column to store and no sequence to keep.

It collides, and that is fine. With a space of 100,000 and random inputs, the chance that two accounts share a number passes a half at a few hundred accounts, by the usual birthday arithmetic. Nothing looks this number up. Nothing joins on it. It appears once, in one card, for fifteen minutes. The thing to be deliberate about is not the collision rate; it is making sure nobody later decides that a number printed to users must obviously be unique and adds a column for it.

Two gates, and they answer different questions

The card is rendered from the signed-in layout:

{profile?.onboardedAt && justOnboarded(profile.onboardedAt) && (
  <Suspense>
    <FieldPermit permit={{ no: permitNumber(user.id), name: profile.fullName ?? user.email, plan: `${plan.kicker}, ${plan.name}`, issued: profile.onboardedAt.toISOString() }} />
  </Suspense>
)}

const justOnboarded = (at: Date) => Date.now() - at.getTime() < 15 * 60 * 1000;

and then the client component decides again:

const ENDINGS: Record<string, string> = {
  launched: "Permit issued. Nakodo is out surveying now, and what it finds shows up below.",
  claimed: "Permit issued. Your campaign and its results are below.",
};

const ending = ENDINGS[params.get("welcome") ?? ""];
if (!ending) return null;

The server gate answers "is this account newly set up", from a column, so no amount of URL fiddling brings the card back next week. The client gate answers "is this the page view that setup redirected to", and it does it through a lookup rather than a boolean, because the sentence depends on how setup ended: the first campaign was launched, or a campaign Nakodo had already built for the customer's website was taken over while running.

The Record lookup is also the validation. ?welcome=, ?welcome=yes and a copied link with a stale value all read as "no ending", and the component returns null rather than rendering a card with a blank sentence in it.

The boolean that puts the parameter there exists once

Setup can be double submitted like anything else, so the fact that onboarding finished is written with a conditional update:

const [row] = await db
  .update(profiles)
  .set({ onboardedAt: new Date() })
  .where(and(eq(profiles.id, userId), isNull(profiles.onboardedAt)))
  .returning({ id: profiles.id });
if (row) await audit({ action: "onboarding.completed", userId, entityType: "user", entityId: userId, metadata });
return Boolean(row);

The isNull in the WHERE makes it idempotent, returning turns it into a compare and set, and the boolean that falls out is what the action appends to its redirect:

router.push(`/campaigns/${campaignId}${r.welcome ? "?welcome=launched" : ""}`);

One request wins, one audit row is written, and only the winner gets the ceremony. The second click lands on the same campaign with no parameter and therefore no card, which is the correct outcome: you did not finish onboarding twice.

Dismissing it edits the URL rather than any state

const dismiss = () => {
  const next = new URLSearchParams(params);
  next.delete("welcome");
  router.replace(next.size ? `${path}?${next}` : path, { scroll: false });
};

There is no dismissed state. The URL already is the state, so the close button removes the one parameter that makes the card render, copies the rest (the results table keeps its filters and sort in the query string, and losing them on a welcome card dismissal would be a real bug), uses replace so the back button does not bring the card back, and passes scroll: false so the page does not jump to the top as the card leaves.

The <Suspense> in the layout is not decoration either. useSearchParams in a client component makes everything above it dynamic unless it sits behind a boundary, and this layout wraps every signed-in page in the app.

The stamp is CSS, and it waits for the plate

The reward reads as paperwork being done in order: the plate fades in and slides down from above (motion-safe:animate-in fade-in-0 slide-in-from-top-2, 500ms), then the stamp hits it.

@keyframes stamp-land {
  from { opacity: 0; transform: scale(1.4) rotate(-6deg); }
  55% { opacity: 1; transform: scale(0.94) rotate(1deg); }
  75% { transform: scale(1.02) rotate(0deg); }
  to { transform: scale(1) rotate(0deg); }
}
@media (prefers-reduced-motion: no-preference) {
  .stamp-land {
    animation: stamp-land 0.45s cubic-bezier(0.3, 0, 0.3, 1) var(--stamp-delay, 0s) both;
  }
}

The overshoot is the whole effect: 1.4 down past the resting size to 0.94, back up to 1.02, then 1. Real rubber stamps squash and rebound, and a stamp that eases politely into place looks like a sticker. The card passes [--stamp-delay:0.7s] as a Tailwind arbitrary property, so the delay lives at the call site while the animation stays in one keyframe block. The whole rule sits inside prefers-reduced-motion: no-preference, so a reader who has asked for less motion gets the stamp already landed, with no animation to opt out of.

Why bother

Because the end of setup is the one moment in a tool like this where nothing has happened yet. The campaign is launched, the first results are minutes away, and the screen would otherwise be an empty table. A card that says "permit issued" fills that gap with something that belongs to the product rather than a spinner, and it costs one derived number, two gates, one conditional update and twelve lines of CSS.

You can see the vocabulary it is built from without an account: the plan kickers on the pricing page, and the surveying metaphor it refers to on how it works. The permit itself only exists for fifteen minutes, once, which is the point.

Our terms notice has no Agree button, because carrying on is the acceptance

Daniel Pertu — Thu, 22 Oct 2026 10:08:38 +0000

Terms change. The question nobody enjoys answering is what should happen to the accounts that are already signed in.

The common answers are all a bit wrong. A blocking modal with an Agree button interrupts someone in the middle of their work to collect a click that proves nothing, and if they do not click it you have to decide whether to lock them out of a product they are paying for. An email nobody opens is not notice. Silence is not notice either.

What Nakodo does is show a small notice under the header, say what changed and when, link the documents, and record the acceptance as the notice appears. There is nothing to click, because the thing being recorded is not a click. It is the fact that the person read a notice saying "by continuing to use Nakodo, you accept them" and then continued to use Nakodo.

This post is about the plumbing that makes that honest rather than hand-wavy.

Two constants, and three places the version is written

src/lib/legal.ts is 43 lines and holds every fact about who runs the app:

export const LEGAL = {
  company: PUBLISHER.name,
  registeredIn: PUBLISHER.registeredIn,
  // A company's website must show its registered number, registered office
  // and the part of the UK it's registered in (gov.uk, "Running a limited
  // company: signs, stationery and promotional material"). The terms and the
  // privacy notice show them.
  companyNumber: PUBLISHER.companyNumber as string | null,
  // The registered office, also the address for legal notices. Until it's
  // set, the pages leave it out.
  address: null as string | null,
  tradingName: BRAND.name,
  email: "hello@nakodo.app",
  law: "England and Wales",
  regulator: { name: "the Information Commissioner's Office (ICO)", url: "https://ico.org.uk/make-a-complaint/" },
} as const;

export const TERMS_VERSION = "2026-10-17";
export const UPDATED = "17 October 2026";

export const LEGAL_DOCS = [
  { href: "/terms", label: "terms of service" },
  { href: "/privacy", label: "privacy notice" },
] as const;

Those string | null types are load-bearing. The registered office is not set yet, so the terms page renders the office sentence only when there is one (LEGAL.address && ...) and simply says less, rather than printing an empty sentence or the word "null". The company number is set, which is why the terms page opens with "Nakodo is run by CogniPrep Ltd, a company registered in England and Wales (company number 17407266)" and the privacy notice says the same thing in its own voice. One COMPANY template literal builds that clause; nothing in the app spells the company out by hand.

At sign-up the accepted version goes to three places, on purpose:

const acceptedAt = new Date();
const accepted = { termsVersion: TERMS_VERSION, termsAcceptedAt: acceptedAt.toISOString() };
const { data, error } = await supabase.auth.signUp({
  ...parsed.data,
  options: { emailRedirectTo: await confirmUrl(next), data: { terms_version: ..., terms_accepted_at: ... } },
});

then a profiles row with the same two values, then an audit row (user.signed_up) carrying them as metadata. The auth user's metadata is the copy that survives anything we do to our own tables, the profile is the copy a page can read in one query, and the audit log is the copy with a timestamp we never update. Three copies of two values is not duplication worth deleting; it is the difference between believing your own records and hoping.

The whole decision is one strict inequality

{profile?.termsVersion !== TERMS_VERSION && <TermsNotice />}

That is the entire gate, in src/app/(app)/layout.tsx, which already loads the profile for the user menu, so the notice costs no extra query.

The optional chaining is the interesting half. An account created before we kept this column has null, so it sees the notice once, which is the correct outcome for someone who agreed to an older document. And if the profile itself were missing, undefined !== "2026-10-17" is also true, so the notice shows. Both unknown states fail towards telling the user something rather than towards silence.

The acceptance is written on arrival, not on interaction

export function TermsNotice() {
  const [open, setOpen] = useState(true);
  useEffect(() => {
    startTransition(() => acceptTermsAction());
  }, []);
  if (!open) return null;
  ...

An effect that fires a Server Action and ignores the result looks like something a reviewer should object to. It is deliberate. The notice has no success state to render and nothing to wait for, so startTransition keeps it out of the render path entirely: the write happens, the component does not re-render, and the panel is interactive the whole time.

The cross in the corner is onClick={() => setOpen(false)} and nothing else. It hides the notice for this page view. It does not accept, refuse, or postpone anything, because by the time it is clickable the acceptance has already been recorded. That is also why the notice does not come back tomorrow, and why there is no "remind me later" to reason about.

The sentence it shows is built from LEGAL_DOCS, so adding a third document means adding one array entry rather than editing prose:

{LEGAL_DOCS.map((doc, i) => (
  <Fragment key={doc.href}>
    {i > 0 && (i === LEGAL_DOCS.length - 1 ? " and " : ", ")}
    <Link href={doc.href} target="_blank">{doc.label}</Link>
  </Fragment>
))}{" "}
changed on {UPDATED}. By continuing to use {BRAND.name}, you accept them.

The UPDATE is a compare and set, and the audit row depends on it

const [accepted] = await db
  .update(profiles)
  .set({ termsVersion: TERMS_VERSION, termsAcceptedAt: new Date() })
  .where(and(eq(profiles.id, user.id), sql`${profiles.termsVersion} is distinct from ${TERMS_VERSION}`))
  .returning({ id: profiles.id });
if (accepted) {
  await audit({ action: "terms.accepted", userId: user.id, entityType: "user", entityId: user.id, metadata: { termsVersion: TERMS_VERSION } });
}

Two details carry this.

is distinct from rather than <>: the column is nullable, and null <> '2026-10-17' is null, which a WHERE clause treats as false. With <> the one group of accounts that most needs recording, the ones who accepted an older document and have nothing stored, would silently never be updated. is distinct from is the null-safe comparison, and it is one of the few places where SQL's three-valued logic quietly changes behaviour rather than throwing.

returning turns the UPDATE into a compare and set. React in development mounts effects twice; a double-submitted action, a second tab, or a fast reload can all call this more than once. The second call matches zero rows, accepted is undefined, and no audit row is written. The log therefore holds exactly one terms.accepted row per account per version, which is the property that makes it worth keeping at all. Writing the audit row first and the update second would have produced a log that counts tabs.

What it deliberately does not do

It does not prove anyone read anything. Nothing can. It does not block the app, because the people most likely to be mid-task are the ones with conversations running, and locking them out to collect a click would cost them real work for no legal gain. And it is separate from marketing consent, which lives on a different table keyed by email address, because "you accepted the current terms" and "you asked for product news" are not the same fact and should never be stored as one.

The version string is also a date, which means two constants have to move together when the documents change. That pairing is checked by a human and nothing else, so it is the honest weak point of the whole design: the gate is exact, the prose beside it is not.

You can see the output of all of this without an account. The terms and the privacy notice both print "Last updated 17 October 2026" and the company's registered details, from the same constants the notice reads. Change them and the notice fires for every signed-in account on the next page view, with no migration and no backfill.

A feature shipped as 21 files of prose, and the word "five" had to survive in five other sentences

Daniel Pertu — Thu, 22 Oct 2026 09:51:28 +0000

Our app ships with built-in question packs so a venue can run a quiz night without writing a question first. We increased how many, from five to thirteen. The interesting part is not the feature.

The code was dull in the way additive changes are dull: the seed became a directory of one module per pack with a shared types file and an index that exports the list, and the seed script itself shrank from 504 lines to 105 now that it contains logic rather than data. A test asserts every pack has enough questions for a full night, that no two packs ask the same question, and that nothing a player sees contains an em dash. That is the whole engineering story.

Then there was a second commit, with no logic in it at all: 21 files, every one of them prose, titled "Update site copy from five to thirteen question packs".

Where a number actually lives

Here is the diff by file, and it is a decent map of how a count spreads through a marketing site:

app/features/question-packs/page.tsx         37 +   5 -
lib/content/registry.ts                      21 +  21 -
app/features/page.tsx                         5 +   5 -
app/compare/ahaslides-alternative/page.tsx    3 +   3 -
app/compare/speedquizzing-alternative/...     3 +   3 -
app/compare/best-pub-quiz-apps/page.tsx       1 +   1 -
app/compare/kahoot-for-pub-quiz/page.tsx      1 +   1 -
app/compare/sporcle-live-alternative/...      1 +   1 -
app/faq/page.tsx                              2 +   2 -
app/pricing/page.tsx                          2 +   2 -
app/quiz-questions/page.tsx                   2 +   2 -
app/quiz-questions/{christmas,halloween,hard,true-or-false,food-and-drink}  1 + 1 - each
app/solutions/pubs/page.tsx                   2 +   2 -
app/solutions/charity-fundraisers/page.tsx    1 +   1 -
components/FeaturesGrid.tsx                   1 +   1 -
docs/seo-plan.md                              2 +   2 -

Five of those are competitor comparison pages, where the count is part of an argument rather than a description, so leaving them stale would have left us arguing a weaker case than the product supports. One is a planning document, which nobody reads but which future-me will believe. One is a component, where the number sits in a feature grid.

The registry line is the one worth expanding. Our content pages are built from a registry of nodes carrying the title, the heading, the meta description and a related list for each path, so a number that appears in a page's <title>, its search snippet and its <h1> is edited there rather than in the page:

-        heading: 'Five question packs, included on every plan',
+        heading: 'Thirteen question packs, included on every plan',
         description:
-            'General Knowledge, Pop Culture, Music & Audio, Sports and Food & Drink come with every plan. How to spread them across a season and build a mixed night.',
+            'Thirteen packs and over 800 questions on every plan, from General Knowledge to a hard pack and seasonal specials. How to build a mixed night from them.',

That old description had been a list of all five names, which only works while there are five of them. Thirteen names do not fit in a meta description, so the description had to change shape and not just change a word: the count replaced the enumeration. That is the kind of edit a find-and-replace cannot do, and the reason this commit is 21 files of hand editing rather than one sed.

Thirteen live URLs now contain the word "thirteen". You can see the top of the chain on the question packs page, whose heading and search snippet both come from that registry node.

The find-and-replace that would have been a disaster

The first thing anybody wants to do here is replace "five" with "thirteen". Our copy still contains "five" in at least five other places, all of them unrelated facts about different parts of the product:

lib/pricing/plans.ts      /** Ultimate: up to five host accounts, £100/month. */
registry.ts (plans)       'Ultimate adds five host accounts on one subscription and five sessions at once.'
registry.ts (builder)     'Pro includes five; Ultimate unlimited.'
registry.ts (timer)       'then five to fifteen seconds on the clock'
quiz-builder/page.tsx     'A 500-point closer really is worth five times a 100-point opener'

A global replace turns a five seat plan into a thirteen seat plan, a five second question timer into a thirteen second one, and a sentence about relative scoring into arithmetic that is simply wrong. Three of those are claims a customer could hold us to, and one of them is a number the billing code enforces, so the copy and the code would disagree about what a plan is.

This is not an argument for being careful with sed. It is the thing I actually took away: a number in prose carries no type and no name. PRO_PRICE_PENCE can only ever mean one thing, and the compiler knows where it is used. The string "five" in a sentence means whatever the sentence means, and the only tool that can tell two of them apart is a person reading both.

Why we spell it out, and why that defeats the test

Our house style spells small numbers as words in prose, which is right for reading and awkward for everything else. grep -r 13 finds nothing. The count appears in three grammatical shapes in the same release: as a heading noun phrase ("Thirteen question packs, included on every plan"), as a bare count inside a sentence ("a venue running one night a week gets months out of the thirteen before anything repeats"), and as a determiner in a call to action ("All thirteen packs are on the free session too").

The test that would catch the drift is easy to describe and annoying to write:

it('says in the copy how many packs actually ship', () => {
  expect(pageText('/features/question-packs')).toContain(numberToWord(seedPacks.length))
})

The pack modules are pure data with no database or network import, exactly like our price module, so seedPacks.length is readable from a test or even from a page. We do exactly that for money: prices are imported, formatted and rendered, never typed into a component, and there is a test that fails if any price surface describes our own price as an estimate.

We did not do it here, for two reasons that I think hold up.

First, a price is a token. It sits alone in a component and reads correctly as a numeral in every language of copy around it. A count is a word inside a sentence, with grammar on both sides of it, and interpolating one turns readable prose into a template: "13 packs are included" is not what a person would write, and rendering it from the data would mean writing every sentence around it to survive substitution.

Second, counting an array means importing it. The pack modules are a couple of hundred kilobytes of question data on disk whose only purpose is to be inserted into a database once per account. Pulling all of it into the render path of a marketing page to learn the length of a list is a bad trade for a number that changes once a quarter.

So the duplication is accepted, and the mitigation is in how the claims are written.

Claims that stay true in one direction

Look again at the new description: "Thirteen packs and over 800 questions". The seed contains comfortably more than 800. The number was rounded down, and down is the only safe direction: the sentence survives a question being pulled for being wrong, or a whole pack being rewritten, and it only becomes false if the product shrinks a lot. "Over 800" is a claim with slack in it; an exact total is a claim that goes wrong the first time somebody fixes an answer by deleting the question.

That is the cheapest available form of this discipline. Where a count must be exact, like the number of packs, it is a word in thirteen pages and a human's job. Where it can be approximate, it is written as a bound rather than a figure, and bounds do not drift.

The copy edit was also a crawl signal

One more coupling, which caught me out pleasantly. Each registry node carries an updated date, and our sitemap.xml reads lastModified from it rather than from the build clock, so the date in the sitemap is the date the page's content actually changed. That makes this copy commit eighteen date edits as well as a prose edit, and you can count the result in the live file:

$ curl -s https://pub-trivia.app/sitemap.xml | grep -c '2026-10-15'
17

Seventeen URLs claiming the same lastmod, which is honest, because they were genuinely all edited in the same sitting for the same reason. The only pages falling back to the build date are the three legal documents, which have no registry node.

A copy change that moves a crawl signal is a copy change worth doing in one commit rather than drizzling across a week, which is an argument for the shape of this commit that I did not have when I started writing it.

Check it yourself

pub-trivia.app/features/question-packs: the heading and the meta description both come from the registry node above, and the body explains how to build a night from the packs.
curl -s https://pub-trivia.app/features/question-packs | grep -o '<title>[^<]*' to see the registry's title rendered.
pub-trivia.app/faq and pub-trivia.app/pricing both repeat the count in their own words, which is the duplication this whole post is about, visible in two tabs.
The free tier at pub-trivia.app/signup needs no card, and every built-in pack is on it, which is the claim all thirteen of those pages are making.

I wrote that the fix was not a deletion. Eight days later it was, and the old URL now answers 200

Daniel Pertu — Thu, 22 Oct 2026 09:49:02 +0000

Two weeks ago I wrote about our Stripe webhook answering at two URLs, /webhook/stripe and /api/webhook/stripe, with the legacy one kept alive as a re-export of the real handler. One of that post's section headings was "The fix is not a deletion", and the reasoning was that the only thing pointing at a webhook URL is a setting in a vendor's dashboard, which you cannot grep, so you keep the old path alive until you are certain nothing is using it.

Eight days later it was a deletion. The post opened with two curls the reader could compare:

curl -s -X POST https://pub-trivia.app/webhook/stripe     -d '{}'
curl -s -X POST https://pub-trivia.app/api/webhook/stripe -d '{}'

Here is what those two print today:

Redirecting...
{"error":"Missing stripe-signature header"}

The second is the live webhook refusing an unsigned request, exactly as before. The first is more interesting than a 404, and it is the part of a URL removal I had not thought about.

Six edits in four files

The route handler was 25 lines, a re-export with its own segment config. Deleting the file was the small part. The path was also spelled out in five other places:

API_ROUTES, the list the proxy uses to decide what it must not touch: ['/api', '/webhook'] became ['/api'].
The proxy matcher's negative lookahead, which is one long literal regex: ...|webhook|api|monitoring).*) lost one alternative.
A second matcher entry, '/webhook/:path*', which existed only so maintenance mode could answer those paths with a 503. A matcher has to be a literal, so it cannot follow a runtime flag, which is why the paths it excludes are also listed explicitly.
CRAWLER_DISALLOW, the prefix list our robots.txt is generated from.
A test, which looped over four paths asserting each answered 503 while maintenance was on, and now loops over three.

Four files, six edits, for one path. None of them are hard, and that is the point: they are the sort of edit that a grep for the string finds in a second and that a careful reviewer would not question, which makes the forgettable one the one nobody notices is missing.

The one with a visible consequence is the robots list, because robots.txt is a generated public document:

$ curl -s https://pub-trivia.app/robots.txt | grep -c Disallow
7

It was eight. If you have an old copy of our robots.txt in a tab from a fortnight ago, Disallow: /webhook is in it. Removing the route removed the only reason to ask crawlers to stay out of it, and the file shrank by a line. That is a small thing, except that the inverse is the common bug: a path is removed from the app, left in the crawler policy, and three years later nobody knows whether that line protects something or not.

The deleted URL does not 404, it redirects

Removing /webhook from the proxy's API list did not make the path disappear. It moved it from one namespace into another.

Paths under /api are handed straight through by the proxy: no rate limiter, no session refresh, no auth gate, because they do their own authentication. Everything else goes to the gate, and the gate works from a prefix allowlist of public routes. It cannot know the route table, so it cannot tell the difference between a path that was never a route and a path whose route file I deleted eight days ago. Both are "not public", so both get a redirect to the login form:

$ curl -s -X POST -o /dev/null -w '%{http_code} %{redirect_url}\n' \
    https://pub-trivia.app/webhook/stripe -d '{}'
307 https://pub-trivia.app/login?next=%2Fwebhook%2Fstripe

And because the login page is a real page:

$ curl -s -L -X POST -o /dev/null -w '%{http_code} %{num_redirects}\n' \
    https://pub-trivia.app/webhook/stripe -d '{}'
200 1

A POST to a URL that no longer exists, followed one redirect, now answers 200 OK with a sign-in form in the body. For a human that is a mild annoyance. For a webhook sender it is the worst available answer, because any client that follows redirects and checks only the status code will mark that delivery as accepted and never retry it. The payload went into an HTML page and nothing read it.

Stripe is not such a client. It treats a 3xx on a webhook endpoint as a failed delivery and keeps retrying, so a misconfigured endpoint shows up as failures in its dashboard rather than as silence. That is the only reason this removal is safe rather than a quiet data loss, and it is luck of a kind, in that it is a property of somebody else's client rather than of our code. If you are deleting a webhook path, the order that makes it safe is unglamorous: point the vendor's dashboard at the new URL, watch the deliveries succeed there for longer than feels necessary, and only then delete the route. The intermediate state, where both URLs work, is the whole value of the re-export I defended in the earlier post.

Which claim from the earlier post survived

Two of them did, and one did not.

Still true: config that lives in a vendor's dashboard is config you cannot grep. That is why the deletion needed the dashboard change to come first, and why it is the only step in this that has no artefact in the repository.

Still true: re-exporting a route handler does not carry its route segment config across. The old file had to restate dynamic = 'force-dynamic' and maxDuration itself, because those are read from the module that defines the route, not from the module it borrowed its handler from. Deleting the file deleted that duplication too, which is the cleanest kind of fix.

No longer true: "the fix is not a deletion". It was the right call for a fortnight and the wrong call permanently, which is roughly the lifespan a compatibility shim is supposed to have. The failure mode of these shims is not that they are wrong, it is that nobody ever comes back to them, and a re-export that works has no symptoms at all.

What you can check

curl -s -X POST https://pub-trivia.app/api/webhook/stripe -d '{}' still answers {"error":"Missing stripe-signature header"}, which is the handler refusing an unsigned request before it looks at anything else.
curl -s https://pub-trivia.app/robots.txt lists seven disallowed prefixes, and /webhook is not one of them.
curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' https://pub-trivia.app/webhook/stripe shows the 307 to the login form with the original path preserved in ?next=, which nothing in our app reads, but that is a different post.

The pages this all exists to protect are public and dull by design: the pricing page, where a plan is bought, and the terms, which say what happens to a subscription afterwards. Everything above is plumbing in service of a venue being able to pay for a quiz night without anybody at either end thinking about URLs.

I told readers to curl our pricing endpoint, and seventeen days later it answers 404

Daniel Pertu — Thu, 22 Oct 2026 09:47:29 +0000

On 5 October I published a post about our app having two copies of every price: the figures in a TypeScript module that the marketing pages render, and the Stripe Price objects that actually took the money. It ended with a section inviting readers to watch the second copy for themselves:

curl -s https://pub-trivia.app/api/pricing
curl -sI https://pub-trivia.app/api/pricing | grep -iE 'cache|age'

Run either of those today:

$ curl -s -o /dev/null -w '%{http_code}\n' https://pub-trivia.app/api/pricing
404

The endpoint was deleted on 15 October. Since the whole point of writing these posts against a live site is that a reader can check the claim, a dead demo deserves its own post rather than a quiet edit, so here is what that URL was, why it is gone, and what to curl instead.

What it was

Thirty-four lines, and every one of them earning its place at the time:

const getCachedPricing = unstable_cache(
  () => getStripePricing(),
  ['stripe-pricing'],
  { revalidate: 300 } // re-fetch from Stripe at most once every 5 minutes
)

export async function GET(request: NextRequest) {
  const ip = getRequestIp(request.headers)
  const { success } = await ratelimit.pricing.limit(ip)
  if (!success) {
    return NextResponse.json({ error: 'Too many requests. Please slow down.' },
      { status: 429, headers: { 'Retry-After': '60' } })
  }

  try {
    const plans = await getCachedPricing()
    return NextResponse.json(plans, {
      headers: { 'Cache-Control': 'public, s-maxage=300, stale-while-revalidate=60' },
    })
  } catch (error) {
    console.error('Pricing API error:', error)
    return NextResponse.json({ error: 'Failed to fetch pricing' }, { status: 500 })
  }
}

A cached read of the live product list from Stripe, rate limited at 20 requests per minute per IP so it could not be used as a free proxy to our payment provider, and cached again at the CDN. It made a decent demo precisely because it was so ordinary: curl it twice and you could watch x-vercel-cache go from MISS to HIT while age climbed, and see that the s-maxage directive never reached the client because the CDN had consumed it.

It existed for one reason. The authoritative prices lived in Stripe, the dashboard plan screen needed them in the browser to put a figure on a button, and a React component cannot call the Stripe SDK. So there was an endpoint.

Why it went

The refactor that followed removed the authority, not the endpoint. Checkout now builds every line item inline from the same price module the marketing pages read, in the visitor's own currency, so there are no Stripe Price objects left to be authoritative about anything. There is no second copy of a price to go and fetch.

The deletion shows up in three other files, and the shapes of those changes are the interesting part:

The component lost a prop and a failure state. The plan cards used to take initialPlans: PricingPlan[], find the entry whose planType matched, and read plan.priceId to start a checkout. They now take the plan type and nothing else, and post that to the checkout route. The interface describing a plan's shape, eleven fields of it, went with them.

More telling, this branch went too:

) : (
  <Button size="lg" className="rounded-full w-full" disabled>
    Unavailable
  </Button>
)

That was the fallback for "Stripe did not answer, so we do not know what this plan costs". A disabled button on the only screen in the app whose job is to sell you something. It is not that we got better at handling the error: the request it was handling no longer exists, so the state is unreachable, and the honest thing was to delete the branch rather than keep a button nobody can ever see.

A rate limit bucket disappeared. Our limiter config is a single object of named sliding windows, so removing an endpoint means removing its entry:

-    /**
-     * /api/pricing — 20 per minute per IP.
-     * Public endpoint that proxies Stripe API calls. 20/min stops scraping
-     * while allowing normal page refreshes and plan-page loads.
-     */
-    pricing: sliding(20, 60),

Worth saying out loud because it is a cost people forget when they count the cost of an endpoint. That URL was not 34 lines. It was 34 lines, a limiter bucket, a Redis key namespace, a cache tag, an error branch in a component, a prop threaded down two levels, and an interface. Deleting it paid all of that back at once.

One comment is now half true. The plans screen still says, of its currency resolution, that "Checkout still prices from Stripe itself" in the fallback case. It does not any more: Checkout prices from the module. The code around it is correct, the sentence is a fossil, and I am leaving it in this post rather than quietly fixing it first, because it is the standard way documentation rots. The comment described a dependency, the dependency was removed, and the comment was not where anybody was looking.

What to curl instead

The replacement demo is better, because it shows the thing the old one only described. The pricing page itself now carries the only copy of the price:

$ curl -s https://pub-trivia.app/pricing | grep -o "Prices in [A-Z]\{3\}[^<]*"
Prices in EUR, including VAT where it applies. You pay the price shown.

That comes back in your own currency, resolved on the server from the request, which you can confirm by running it through a VPN exit in another country. The figures on the page itself are the figures Checkout charges.

The caching story moved with it, in the opposite direction:

$ curl -sI https://pub-trivia.app/pricing | grep -i cache-control
cache-control: private, no-cache, no-store, max-age=0, must-revalidate

The old endpoint was five minutes of shared CDN cache. The page that replaced it cannot be shared at all, because its content depends on where the request came from, so it renders per request and tells every cache to keep out. The old post's "watch it cache" paragraph is not merely dead, it is inverted, and that trade is deliberate: a page that renders fast and shows the wrong number is worse than one that renders correctly.

Two claims from that October post do still hold, and you can check both in the same response. There is still exactly one price for a plan rather than two, and the structured data still quotes the plans in pounds, which keeps one fixed figure in search results whatever currency the page itself is rendered in:

$ curl -s https://pub-trivia.app/pricing | grep -o 'priceCurrency":"[A-Z]*' | head -2
priceCurrency":"GBP"
priceCurrency":"GBP"

The thing I would actually keep

A published post is a dependency on a URL, and nothing in your repository knows about it. We have a test that regexes export const metadata out of a hundred route files, a test that holds the sitemap and the auth allowlist to the same list of public paths, and a test that fails if any price surface calls our own price an estimate. None of them know that a blog post from 5 October tells strangers to make a GET request to a path that no longer has a route file.

I am not going to build that, and I do not think anybody should. The practical version is cheaper: when a refactor deletes a public URL, grep your own writing for it before you ship, and if you find it, write the correction rather than editing the past quietly. The second option costs one post and buys back the only thing that makes "check it yourself" worth saying.

Our plan change cancelled your old subscription first, so closing the Checkout tab left you on nothing

Daniel Pertu — Thu, 22 Oct 2026 09:38:36 +0000

A plan change in our app goes through Stripe Checkout, because that is also how a first purchase works and one flow is better than two. The old version of it had five lines that read perfectly sensibly:

// Cancel any existing active/trialing subscriptions in parallel
await Promise.all(
  live
    .filter(sub => sub.status === 'active' || sub.status === 'trialing')
    .map(sub => stripe.subscriptions.cancel(sub.id)),
)

Cancel what the customer has, then send them to Checkout for what they want. Clean, and wrong, because the second half of that sentence is not guaranteed to happen. A customer who clicked Change plan, read the Stripe page, thought better of it and closed the tab had just lost the plan they were already paying for. Nobody declined anything. Nobody asked for a cancellation. The only thing that happened was a page being closed, and by then the money side of their account was already in the past tense.

The fix inverts the order: cancel nothing up front, and let the new subscription carry a note of what it supersedes.

The whole mechanism is one metadata key

/** Metadata key on a new subscription: the comma-separated IDs it replaces. */
export const REPLACES_KEY = 'replaces_subscriptions'

export function replacementMetadata(live: Pick<Stripe.Subscription, 'id'>[]): Record<string, string> {
  return live.length > 0 ? { [REPLACES_KEY]: live.map((sub) => sub.id).join(',') } : {}
}

Checkout stamps that on the subscription it creates. Every subscription still live on the customer goes on the list, paid up or not, so a past-due one stops retrying as well. If there is nothing to replace, the key is absent rather than empty, so a first purchase carries no trace of the mechanism at all.

The webhook does the cancelling, once the new subscription is actually paying. Abandoning Checkout now changes precisely nothing: no new subscription exists, so no list of replacements exists, so nothing gets cancelled, and the customer still has the plan they walked in with.

Two live subscriptions, briefly

The cost of that ordering is a window where the customer has two live subscriptions: the new paid one, and the old one that has not been cancelled yet. Stripe will happily tell you about both, in events that can arrive in either order, more than once each.

So the webhook stopped trusting the event it was handed. It asks what is true now:

async function syncCustomer(customerId: string, ended: Stripe.Subscription | null): Promise<void> {
  const live = await liveSubscriptions(customerId)
  const current = currentSubscription(live)

  if (current) {
    await handleSubscriptionActive(current)
    for (const old of supersededBy(current, live)) await cancelReplaced(old)
  } else if (ended) {
    await handleSubscriptionDeleted(ended)
  }
}

Every subscription event now routes through that, and the event's own payload is used for one thing only: the customer ID, plus the subscription object in the case where nothing is paying any more and we need to know what stopped.

The interesting function is the one that decides which of two live subscriptions the account follows:

export function currentSubscription(live) {
  const paying = live.filter(isPaying)
  const replaced = new Set(paying.flatMap(replacedIds))
  const candidates = paying.filter((sub) => !replaced.has(sub.id))
  candidates.sort((a, b) => b.created - a.created)
  return candidates[0] ?? null
}

Read it as a rule rather than as code: the account follows a paying subscription that no other paying subscription claims to replace. Newest wins if somehow there are several, which there should not be.

That single rule covers the cases I would otherwise have written four separate branches for:

The new subscription is paid, the old one is still live. The old one is named in the new one's metadata, so it is excluded, and the account is on the new plan immediately.
An event for the old subscription arrives late, after the change. It is still replaced, so it is still excluded, and the late event cannot drag the account back to the previous plan.
The new subscription exists but is unpaid. It is not paying, so it is not a candidate at all, and the customer keeps the plan they had. Charging has not succeeded, so nothing is granted.
The last subscription ends. Nothing is paying, nothing is current, and the account falls back to the trial.

The tests for the webhook read almost as a list of those:

✓ moves the venue to the new plan and only then cancels the old one
✓ keeps the new plan when the old one is deleted, rather than dropping to the trial
✓ ignores a late event for the old subscription once the new one pays
✓ leaves the old plan in place while the new subscription is unpaid
✓ drops to the trial when the last subscription ends

Cancelling something twice

supersededBy returns only the subscriptions that are still live and are named by the current one, so a webhook delivered twice finds the second time that there is nothing left to cancel. That handles the common case by construction, but not the race where two deliveries overlap, and Stripe's own retry behaviour makes overlapping deliveries normal rather than exotic.

async function cancelReplaced(sub: Stripe.Subscription): Promise<void> {
  try {
    await stripe.subscriptions.cancel(sub.id)
  } catch (error) {
    const now = await stripe.subscriptions.retrieve(sub.id).catch(() => null)
    if (now?.status === 'canceled') return
    throw error
  }
}

A failed cancel is re-read rather than assumed. If the subscription is already cancelled, the error was somebody else doing our job and it is swallowed. Anything else rethrows, which the route turns into a 500, which makes Stripe retry the event later. Two tests cover exactly that pair: one takes a second delivery in its stride, and one insists we retry when the cancel genuinely failed.

Deciding that from the error's shape rather than from a fresh read would have been shorter, and it would have meant classifying Stripe error codes correctly forever. A single extra API call is a better deal.

Reading the plan off metadata, not the price

One thing holds the whole arrangement together. The plan is stamped on the subscription's metadata, not derived from its price:

export function planTypeOf(sub: Pick<Stripe.Subscription, 'metadata'>): PaidPlanType {
  return parsePaidPlanType(sub.metadata?.plan_type) ?? 'pro'
}

We build Checkout line items from inline price_data in the visitor's own currency, so there are no Stripe Products or Prices to map back from. A subscription might be 36.99 euros or several thousand yen, and no lookup table can turn an amount into a plan without becoming wrong the next time a rate changes. The metadata reads identically in every currency, and the webhook's currency tests exist to prove it:

✓ provisions a euro Ultimate subscription as Ultimate
✓ provisions a yen Pro subscription as Pro, whatever its amount
✓ follows a plan change on a forint subscription
✓ downgrades a canceled krona subscription to the trial

The fallback to pro is deliberate: a paid subscription with no readable plan should grant the cheaper paid plan, never the dearer one and never nothing.

Two refusals in the route

Removing the up-front cancel left the checkout route with less to do and two things it now has to refuse.

The plan you already pay for. With the cancel gone, buying your current plan again would just create a second subscription at the same price, so the route answers 409 "You're already on this plan." A past-due subscriber is explicitly allowed through, because for them buying again is the repair, and there is a test with that in its name: "lets a past-due subscriber buy their plan again, to replace the one that isn't paid".

A currency we cannot quote. Stripe holds a customer to one currency while a subscription lives, so a plan change has to be priced in the live subscription's currency. If that currency is not one we price in, which can only happen if somebody made a subscription by hand in the Stripe dashboard, the route stops with a 409 and an email address rather than guessing. It used to decide this before cancelling anything, and the comment explaining why no longer needs to exist, because nothing is cancelled anywhere in the route.

Seeing it from outside

Plan changes live behind a login, so there is no URL I can hand you for this one. What is public is the pricing it is built on: pub-trivia.app/pricing renders in your own currency, and the note under the cards tells you which one, which is the figure a plan change would be quoted in afterwards. The terms say the rule in prose, including that a plan stays in the currency it started in.

If you want to watch the mechanism, the free tier at pub-trivia.app/signup needs no card, and the plans screen will offer you a Checkout session you are welcome to close. That used to be the destructive path. Now it is the no-op it always looked like.

Two features both wanted to pick the currency, so one of them is switched off in code

Daniel Pertu — Thu, 22 Oct 2026 09:37:19 +0000

We price visitors in their own currency from a table of rates, and the figures on our pricing page are the figures Checkout charges. That claim survives only if nothing between the page and the card is allowed to change the number.

Stripe has a feature whose whole job is to change the number. Adaptive Pricing re-prices a Checkout session into the customer's local currency at Stripe's own rate, which is a genuinely good feature if your prices are in one currency and your customers are not. For us it meant the customer would read one price on our page and then see Stripe's conversion of it on the next, which is the exact arrangement we had just spent a release deleting.

So every session we create carries one of two shapes, and which one it gets is decided by something else entirely: whether the sale is routed through Stripe as merchant of record.

Off, or absent, never left alone

function withoutAdaptivePricing(params) {
  return { ...params, adaptive_pricing: { enabled: false } }
}

function withAdaptivePricingUnset(params) {
  const { adaptive_pricing: _adaptivePricing, ...rest } = params
  return rest
}

Two functions that look like the same function. The difference matters because Managed Payments, Stripe's merchant-of-record mode, rejects the adaptive_pricing field outright and turns Adaptive Pricing on regardless. You cannot send it enabled: false. You cannot send it at all.

Which leaves the obvious question: if Adaptive Pricing is forced on for every merchant-of-record session, how is that safe when we have just said it must never be allowed to re-price anything?

It is safe only because of an invariant kept in a completely different file. Our merchant-of-record allowlist is the EU-27, and every EU-27 country is priced in its own currency by our own table, so a Dutch customer's session is already in euros and there is nothing for Stripe to convert. Adaptive Pricing is on and has no work to do.

That is a fragile kind of safety, so it is held down by a test rather than by a comment:

✓ prices every Managed Payments country in its own currency
✓ has exactly 21 euro members and six with their own currency
✓ covers exactly the EU-27, and never GB

Add a country to the merchant-of-record allowlist without adding its currency to the pricing table, and that first test goes red before the mismatch can reach a customer.

Why merchant of record at all, and why only there

When Managed Payments is on for a session, Stripe becomes the legal seller: it calculates, collects, files and remits the VAT, and carries the liability. In exchange Stripe takes its published merchant-of-record fee on top of normal card processing, and the tax is withheld from the payout, so the money that arrives is net.

That is worth paying for where foreign tax is genuinely due from the first sale, and not worth paying anywhere else, so the routing is an allowlist rather than a global setting:

EU-27: on. VAT is due in the customer's country from the first sale of an automated digital service by a UK seller.
UK: off. We are under the £90,000 VAT registration threshold. Switching merchant of record on for UK sales would have Stripe charge 20% VAT immediately, which throws the threshold away for nothing.
US: off. No sales tax nexus at this volume.
Everything not on the list: off.

The country comes from the visitor's IP at session creation, which is a coarse signal and is openly treated as one in the code. It is the same header that chose the currency the customer was shown, which is the real reason to read it once: the price and the tax routing cannot disagree about where the customer is, because they are reading the same byte. Once merchant of record is on, the authoritative tax country is the billing address the customer types on Stripe's own page, and Stripe computes the tax from that.

Every line item carries tax_behavior: 'inclusive', merchant of record or not, because that is a property of the price we quote rather than of the routing: whatever tax applies sits inside the figure on the page. A test says it in those words, "keeps tax inside the price, so the price shown is the price charged".

The failure mode that would have taken EU checkout down

Managed Payments has to be activated on the Stripe account, with the merchant-of-record terms accepted and an eligible tax code. If any of that is not true, Stripe rejects every session that sets managed_payments. Not some. Every one.

Since the field is set from the customer's country, a misconfiguration would not fail loudly in one place. It would fail as "checkout is broken in the EU" while the UK and the US sold normally, which is the kind of outage you find out about from a support email.

So the session creation helper retries once, without merchant of record, and only when Stripe's rejection was specifically about that field:

try {
  return await stripe.checkout.sessions.create(
    context.managedPayments ? withAdaptivePricingUnset(params) : withoutAdaptivePricing(params)
  )
} catch (error) {
  if (context.managedPayments && isManagedPaymentsRejection(error)) {
    console.error('[checkout] Managed Payments session rejected by Stripe, retrying without MoR', {
      country: context.country ?? null,
      stripe: describeStripeError(error),
    })
    return await stripe.checkout.sessions.create(
      withoutAdaptivePricing(stripManagedPayments(params))
    )
  }
  throw error
}

Two parts of that deserve the attention.

The detector has to be narrow. A retry that swallowed a card decline, a rate limit or a bad amount would be worse than the outage, because the sale would silently complete under the wrong tax treatment or fail twice for a reason nobody logged. isManagedPaymentsRejection only returns true for Stripe's request-validation error type, and then only when the param is managed_payments (or something nested under it), or the message mentions managed payments. It is duck typed rather than using instanceof, which keeps it testable without the SDK's error classes, and the tests spell out each refusal:

✓ recognises an explicit managed_payments param rejection
✓ recognises a nested managed_payments param
✓ recognises the phrase in an invalid-request message
✓ does NOT match a card decline, so a real failure is never retried away
✓ does NOT match transient network or API errors
✓ does NOT match an unrelated invalid-request error
✓ does NOT match an arbitrary Error that happens to mention the phrase

The strip has to be exact. Removing merchant of record from a session means removing precisely the fields that merchant of record added, which is the top level managed_payments and the tax_code on each line item's product_data. tax_behavior stays, because it belongs to the price. A line item built from a Price id carries none of those fields and passes through untouched. The input is cloned rather than mutated, and there is a test for that alone, because a mutating strip would quietly change the params the caller still holds a reference to.

The result is a sale that completes with no tax collected where tax was due, which is not nothing. It is a flagged sale instead of a lost customer, and the comment says so out loud: a flagged sale we can fix is better than a customer we lost.

The flag, after the fact

Flagging happens in the Stripe webhook, on checkout.session.completed, and it is the only thing that event does. Provisioning is driven entirely by subscription events, so a tax routing miss can never delay anybody's plan.

const country = session.customer_details?.address?.country ?? null
const taxAmount = session.total_details?.amount_tax ?? null
if (!isPossibleMoRMisroute(country, taxAmount)) return
console.error('[stripe-webhook] EU sale completed with no tax collected, possible Managed Payments misroute', { ... })

It compares the billing country Stripe actually captured against the tax Stripe actually collected. An EU billing country with zero tax is the signal, which catches both the misconfiguration retry above and the ordinary case of a customer whose IP exits in another country and who then types a French address on Stripe's page.

A genuine EU business-to-business sale with a valid VAT number also shows zero tax under reverse charge. That is a false positive, it is accepted in writing, and the handler is review-only, so the cost of being wrong is a log line rather than a refused sale. The log carries the session's own currency and amount alongside the GBP list price that checkout stamped on the session metadata, so the sale can be reconciled in pounds whatever it was charged in.

What a reader can check

Not much of this is visible from outside, which is the nature of billing code. Two things are:

curl -s https://pub-trivia.app/pricing | grep -o "Prices in [A-Z]\{3\}[^<]*" returns the currency your IP is priced in, and the note ends "including VAT where it applies. You pay the price shown." There is no second number later in the flow, which is what all of the above exists to protect.
Our terms state the billing currency rule, including that a plan stays in the currency it started in. A test asserts those sentences are still in the page, because the prose is now part of the contract the code implements.

The suites behind this are 27 tests on the merchant-of-record module and 22 on the session helper, including the four that say "does NOT retry" in various ways. Those four are the ones I would keep if I could only keep four.

There are no Prices in our Stripe Dashboard, only 24 rates in a table

Daniel Pertu — Thu, 22 Oct 2026 09:35:57 +0000

Our pricing page used to be a claim and our Stripe Dashboard used to be the fact. The doc comment on top of lib/pricing/plans.ts admitted it in as many words: the prices in the file and the prices on the Stripe Price objects were two copies of one fact and could drift, the file was what the site advertised, the Stripe Price was what was charged, and when you changed a price you had to change it in both places in the same sitting.

That comment is gone, and so are the Price objects. There is nothing to set up in our Stripe Dashboard now: no Products, no Prices, no currency variants. Checkout builds every line item inline from one table, in the visitor's own currency, at the figure the page printed.

You can see the output before reading any of the mechanism:

curl -s https://pub-trivia.app/pricing | grep -o "Prices in [A-Z]\{3\}[^<]*"

From a London IP that prints Prices in GBP, including VAT where it applies. You pay the price shown. From where I am sitting it prints Prices in EUR, and the page body contains no pound sign anywhere. Switch a VPN exit to Tokyo and the yen prices come back with no decimal places at all. The page is at pub-trivia.app/pricing if you would rather just look at it.

One table, two consumers

The currency table has 24 entries. Each is a lowercase id (which is also the code Stripe takes), an ISO code, a locale to format with, and a mid-market rate expressed as units per one pound:

export const CURRENCIES = {
  gbp: { code: 'GBP', locale: 'en-GB', rate: 1 },
  eur: { code: 'EUR', locale: 'en-IE', rate: 1.1696 },
  sek: { code: 'SEK', locale: 'sv-SE', rate: 12.8667 },
  // ... 21 more
} as const satisfies Record<string, CurrencyDefinition>

The rates are fixed, not live, and that is the whole design rather than laziness. A live feed would move a customer's price between two page loads, put a network call in the render path of the one number they came to read, and make the figure shown at 10:59 differ from the figure charged at 11:00. They were sourced from the ECB reference rates on a dated afternoon, and the note in the file says to refresh one when it has moved more than about three per cent.

A second map takes a two letter country code to one of those currencies, with anything unlisted falling back to pounds. It leans towards Europe because that is where the venues are. Every EU-27 member is priced in its own currency on purpose, which matters later.

One detail in the lookup that is easy to get wrong: the country comes from a request header, so it is attacker influenced even if only through a spoofed IP, and reading the map directly would let a country code of constructor or __proto__ return a function. The lookup goes through Object.prototype.hasOwnProperty.call for that reason and returns pounds for anything it does not own.

What a local price actually is

A plan is an integer number of GBP pence. Pro is 3000. The local price is that, converted, plus a margin, rounded up to a retail figure:

const major = (pence / 100) * CURRENCIES[currency].rate * LOCAL_PRICE_MARGIN
return Math.round(ceilToRetail(major, digits) * Math.pow(10, digits))

LOCAL_PRICE_MARGIN is 1.04. It is not a markup for its own sake: Stripe charges us to convert a payout in another currency back into pounds, and the fixed rates drift between refreshes, so without it a sale in krona can net less than the same sale in pounds. Four per cent covers both.

ceilToRetail rounds up to the next .99, or to the next whole unit in a currency written without decimals. Pro is £30, so euros come out as 30 x 1.1696 x 1.04 = 36.49, which becomes €36.99. Ultimate is £100, which lands on 121.63 and becomes €121.99. Those are the two figures on the live page right now from an EU address, and they are the two figures Checkout charges, which is the point of the exercise.

The rounding has an epsilon in it, because a value sitting exactly on a boundary would otherwise be nudged up by a whole unit by binary float error.

The free plan cost 99 cents

Here is the bug that came out of the rounding rule, and it is my favourite kind, because every individual step is correct.

The free trial is a plan like any other, with a price of 0 pence. Convert zero and you get zero. Round zero up to the next .99 and you get 0.99. So the one plan whose entire proposition is that it costs nothing displayed as €0.99 everywhere outside the United Kingdom, while still saying "no card needed" next to it.

The fix is three lines and a comment longer than the code:

// Free is free in every currency. Without this guard the retail round-up turns
// the trial's £0 into "€0.99", because the next `.99` above zero is 0.99.
if (pence === 0) return 0

Formatting is part of the charge now

When the price shown is also the price taken, the formatter stops being cosmetic.

Two currencies in our table are written without decimal places where Stripe still counts them in hundredths, and one is written and counted in whole units. Those are two different lists in the file, not one, because conflating them would be wrong by two orders of magnitude in whichever direction you picked. The forint is the interesting one: JavaScript engines disagree about it, V8 writing it without decimals while engines following ISO 4217 strictly give it two. Our page renders once on the server and again in the browser on hydration, so a price that depends on the engine is a price that can disagree with itself inside one page view. The list is hardcoded and a test checks it against the server's own Intl data so a new zero decimal currency cannot slip past.

Every Intl.NumberFormat call passes its fraction digits explicitly, so the engine's idea of a currency never changes the figure. Whole amounts drop the decimals, because .00 on every list price reads as more precision than a round number has.

The number that goes to Stripe gets its own function, because Stripe's units are not always the units the currency is written in:

export function stripeUnitAmount(pence: number, currency: DisplayCurrency): number {
  return Math.round(
    localPrice(pence, currency) * Math.pow(10, stripeDigits(currency) - minorUnitDigits(currency))
  )
}

The line item

With all of that in one module, the Checkout call is dull, which is the goal:

line_items: [{ price_data: planPriceData(planType, currency, mp.productData), quantity: 1 }]

and planPriceData is nine lines: the currency, stripeUnitAmount of the plan's pence, a monthly recurring, a product name for the invoice, and a tax behaviour of inclusive so any VAT sits inside the figure rather than appearing on top of it at the last step.

The plan rides on the subscription's metadata rather than being inferred from the price, so a subscription in any currency reads back the same, and the GBP list price rides along too so that a sale in forint can still be accounted for in pounds.

One more rule falls out of Stripe's own behaviour rather than ours: a subscription keeps the currency it started in for as long as it lives, because Stripe will not bill one customer in two currencies. So a signed in customer with a live subscription is priced in that subscription's currency, not in their country's, and a plan change has to be quoted in it. Our terms say this out loud, and a test asserts the sentence is still there: "billed in the currency it started in".

What the tests hold

The pricing and billing suites are 159 tests across six files, 43 of them on the currency module alone. The ones I would not want to lose:

A local price never nets less than the pound price, and never strays an unreasonable distance above the true conversion.
Prices are monotonic, so the cheaper plan can never round up past the dearer one.
The Stripe amount reads back as exactly the displayed price, in every currency.
Zero renders as a figure containing no non-zero digit, whatever the currency.
The hardcoded zero decimal list agrees with the runtime's Intl data.
The rendered pricing cards carry the exact displayed price in six currencies, and the purchase button says "Purchase €36.99/mo" rather than a pound figure.
No price surface describes our own price as a conversion, an estimate, or a guide to a pound figure. That one is a regex over the rendered text and over the source of eleven customer facing files, built from the words a weaselly price note tends to use: approx, convert, estimat, exchange, rounded up.

The last one is the test I like most, because it is the test that stops the design quietly rotting back into the old one. The moment a page says "approximately €36.99" we are back to advertising one number and charging another, and the suite goes red for a prose change.

Have a look at pub-trivia.app/pricing in whatever country you are in. If the note at the bottom of the cards names your currency and the figures end in .99, that is this table, and if you took a plan the figure on your statement would be the one you read.