fix: one /v1, owned by the base URL

[0xdevcollins]

Follow-up to #199. That PR fixed 20 call sites; this one removes the reason they kept appearing.

The root cause

NEXT_PUBLIC_API_URL meant two different things:

	reads the env var as	appends
dashboard	origin	/v1
checkout	origin including /v1	nothing

Both were self-consistent, which is why neither looked wrong in isolation. But the variable is set once per deployment, so no value could satisfy both — and ci.yml builds both apps with NEXT_PUBLIC_API_URL: https://api.useroutr.com, meaning production checkout was built with no version segment at all.

Separately, four checkout call sites wrote /v1/payments/… on top of a base that already ended in /v1, requesting /v1/v1/payments/…. Those are the card and bank rails: bank-session, bank-session/regenerate, bank-sent, card-session.

The fix

@useroutr/types now owns the contract — both apps already depend on it:

resolveApiBaseUrl(origin, fallback)  // always exactly one /v1, accepts either
                                     // spelling, collapses an already-doubled one
assertVersionlessPath(path)          // throws outside production if a caller
                                     // re-adds the version

One rule, stated once: the base URL owns the version, call sites never write it. All three clients (dashboard api.ts, dashboard auth.ts, checkout api.ts) now go through it, so a future /v2 is a one-line change rather than a sweep.

The guard matters more than the resolver. A doubled prefix produces no type error and no lint error — it 404s at runtime and nowhere else, and the mocked hook tests assert the wrong string right alongside it. That is precisely how twenty call sites accumulated without anyone noticing.

Server side

Already correct and unchanged: one setGlobalPrefix('v1'), and no controller repeats it (the one that did, notifications, was fixed in #199).

Verified

undefined                     -> http://localhost:3333/v1
http://localhost:3333         -> http://localhost:3333/v1
http://localhost:3333/v1      -> http://localhost:3333/v1
https://api.useroutr.com      -> https://api.useroutr.com/v1
https://api.useroutr.com/v1   -> https://api.useroutr.com/v1

Guard: /v1/payouts and /v1/invoices/abc throw with the corrected path named in the message; /payouts and /v1beta/experiments pass (it does not false-positive on a resource whose name merely starts with the version string).

In the browser, checkout now requests GET /v1/checkout/<id> — single prefix.

Tests

• 12 new in packages/types, including the case where someone who has already been bitten pastes the doubled URL into the env var
• New Test Packages CI job — nothing outside apps/api and the contracts was ever run there, which is why the stale assertions survived
• 287 API unit + 15 API e2e still green; dashboard and checkout typecheck and lint clean (0 errors)
• Fixed 4 stale usePayouts assertions still pinning /v1/payouts. Dashboard suite goes from 14 failed / 6 passed to 10 failed / 10 passed — the remaining 10 fail on clean main too, for unrelated reasons (see below)

Deliberately not fixed here

• apps/dashboard's vitest suite is red independently of this change: @useroutr/ui doesn't resolve under vitest (the package ships raw TSX with no build, handled in Next by transpilePackages but not configured for vitest), plus a jsdom container issue. Needs its own change before it can join CI.
• apps/checkout/__tests__/crypto-payment.test.tsx exists but the app has no test script, no test deps and no config — it has never run once.
• The five dashboard files that bypass the api client with bare fetch() and no auth header, already tracked separately.

One carried-in change worth naming: useInvoiceCheckout.ts had already been corrected in the working tree by someone else. I included it because the new guard would now throw on those paths rather than let them 404 quietly.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
useroutr-www	Ready	Preview	Aug 9, 2026 2:35pm