create-cartbase 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cartbase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,16 @@
 # create-cartbase
 
-Scaffold a new storefront on the **Cartbase** commerce platform:
+Scaffold a storefront on the [Cartbase](https://cartbase.net) commerce
+platform:
 
 ```bash
 npm create cartbase my-store
+# or, prefilled from your admin's Settings values:
+npm create cartbase my-store -- --url https://… --client-id … --key pk_…
 ```
 
-The official release is in development. This package name is held by
-Cartbase; do not depend on this version.
+You get a working Next.js storefront wired to your store through
+`@cartbase/storefront`, with the **complete platform docs included in
+`docs/`** and a `CLAUDE.md` brief — hand the folder to a coding agent
+and it has everything it needs offline. Deploy with the
+[`cartbase`](https://www.npmjs.com/package/cartbase) CLI.

package/dist/index.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function parseArgs(argv) {
+    const flags = new Map();
+    let dir;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const name = arg.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                flags.set(name, next);
+                i++;
+            }
+            else
+                flags.set(name, true);
+        }
+        else if (!dir)
+            dir = arg;
+    }
+    return { dir, flags };
+}
+function copyDir(from, to) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+        const src = path.join(from, entry.name);
+        const dest = path.join(to, entry.name);
+        if (entry.isDirectory())
+            copyDir(src, dest);
+        else if (entry.isFile())
+            fs.copyFileSync(src, dest);
+    }
+}
+function main() {
+    const { dir, flags } = parseArgs(process.argv.slice(2));
+    if (!dir || flags.get("help") === true) {
+        console.log(`create-cartbase — scaffold a Cartbase storefront
+
+Usage:
+  npm create cartbase <directory> [-- --url <api-origin> --client-id <uuid> --key <pk_…>]
+
+The three store inputs live in your Cartbase admin under Settings; given
+as flags they are written into .env.local, otherwise placeholders are.`);
+        process.exitCode = dir ? 0 : 1;
+        return;
+    }
+    const target = path.resolve(dir);
+    if (fs.existsSync(target) && fs.readdirSync(target).length > 0) {
+        console.error(`${target} already exists and is not empty.`);
+        process.exitCode = 1;
+        return;
+    }
+    const templateApp = path.join(path.dirname(path.dirname(fileURLToPath(import.meta.url))), "template", "app");
+    copyDir(templateApp, target);
+    // Name the app after its directory.
+    const pkgPath = path.join(target, "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    pkg.name = path
+        .basename(target)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "cartbase-storefront";
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    const url = typeof flags.get("url") === "string" ? flags.get("url") : "";
+    const clientId = typeof flags.get("client-id") === "string" ? flags.get("client-id") : "";
+    const key = typeof flags.get("key") === "string" ? flags.get("key") : "";
+    fs.writeFileSync(path.join(target, ".env.local"), [
+        "# Your store's inputs — Cartbase admin, Settings.",
+        `NEXT_PUBLIC_CARTBASE_URL=${url}`,
+        `NEXT_PUBLIC_CARTBASE_CLIENT_ID=${clientId}`,
+        `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY=${key}`,
+        "",
+    ].join("\n"));
+    const filled = url && clientId;
+    console.log(`
+Created ${path.basename(target)}/
+
+Next steps:
+  cd ${dir}
+  bun install        (or npm install)${filled
+        ? ""
+        : `
+  → open .env.local and fill in your store's URL, client id and
+    publishable key (Cartbase admin, Settings)`}
+  bun run dev
+
+The complete storefront reference is in docs/ — hand CLAUDE.md to your
+coding agent and it has everything. Deploy with the Cartbase CLI:
+cartbase login, then cartbase deploy.
+`);
+}
+main();

package/package.json

@@ -1,7 +1,21 @@
 {
   "name": "create-cartbase",
-  "version": "0.0.1",
-  "description": "Scaffold a Cartbase storefront — official release in development. This name is held by the Cartbase commerce platform.",
-  "license": "UNLICENSED",
-  "keywords": ["cartbase", "create", "storefront", "commerce"]
+  "version": "0.1.1",
+  "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-cartbase": "./dist/index.js"
+  },
+  "files": ["dist", "template"],
+  "scripts": {
+    "build": "node scripts/build-template.mjs && tsc -p tsconfig.json",
+    "prepack": "node scripts/build-template.mjs && tsc -p tsconfig.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  }
 }

package/template/app/CLAUDE.md

@@ -0,0 +1,18 @@
+# This is a Cartbase storefront
+
+A Next.js app wired to a Cartbase store through `@cartbase/storefront`
+(typed API client + UI components). Everything you need is local:
+
+- **docs/** — the complete storefront reference (also at the store's docs
+  site): endpoints, shapes, auth, checkout orchestration, components.
+  Start with docs/BUILD-A-STOREFRONT.md.
+- **.env.local** — the three store inputs (API origin, client id,
+  publishable key). Missing values: ask the merchant to copy them from
+  their Cartbase admin under Settings.
+- Deploy with the Cartbase CLI: `cartbase login` then `cartbase deploy`
+  — you get a permanent preview URL; the merchant publishes from their
+  admin. Never commit .env.local.
+
+House rules: totals and prices are SERVER truth (render them verbatim);
+always pass a pricing context; consent before tracking; the store API is
+proxied same-origin via next.config rewrites.

package/template/app/docs/BUILD-A-STOREFRONT.md

@@ -0,0 +1,216 @@
+# Build a storefront — the runbook
+
+**This runbook takes you from a blank Next.js app to a completed checkout
+against your Cartbase store.** It is written to be followed by a developer
+or handed to a coding agent as-is. Each step names the domain doc that
+carries the full contracts (shapes, curls, error codes, settings). Follow
+the steps in order — later steps assume earlier wiring exists. If anything
+here is unclear or wrong, it's a documentation bug — report it.
+
+What you need before starting (all three are in your Cartbase admin under
+**Settings**):
+
+| Input | Example | Where it goes |
+|---|---|---|
+| API origin | `https://admin.bitfar.co` | `NEXT_PUBLIC_CARTBASE_URL` |
+| Store client id | `1e7a4c02-9b31-4f7e-8d2a-5c6f90ab12cd` (uuid) | `NEXT_PUBLIC_CARTBASE_CLIENT_ID` |
+| Publishable API key | `pk_…` (optional, channel scope) | `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY` |
+
+Sanity-check the store before writing any code:
+
+```bash
+# The regions listing is the cheapest liveness + auth probe.
+curl -sf "$BASE/api/store/regions" -H "x-client-id: $CLIENT_ID" | grep -q '"regions"'
+```
+
+## Step 1 — Scaffold + package
+
+Create the Next.js app (App Router) and add the package:
+
+```bash
+# doc-noexec — scaffolding happens in YOUR repo, not against the API.
+bunx create-next-app@latest my-store --ts --app --tailwind
+cd my-store && bun add @cartbase/storefront
+```
+
+- The package is **source-shipped TypeScript** — add
+  `transpilePackages: ["@cartbase/storefront"]` to `next.config` or nothing
+  from it will compile.
+- The Tailwind preset is **Tailwind 3 format** (`tailwind-preset.cjs`).
+  `create-next-app --tailwind` scaffolds Tailwind 4 (CSS-first, no config
+  file) — either install `tailwindcss@3.4` + a `tailwind.config.cjs` with
+  `presets: [require("@cartbase/storefront/tailwind-preset")]` (include the
+  package source in `content`:
+  `"./node_modules/@cartbase/storefront/src/**/*.{ts,tsx}"`), or translate
+  the preset's tokens into Tailwind 4 `@theme` yourself. Then define the
+  shadcn-standard token variables (`--background`, `--primary`, … as raw
+  oklch channels) in your CSS — the working set is
+  `examples/storefront/src/app/globals.css`.
+- Pin the package version — storefronts never float `latest`.
+- Monorepo caveat: when the app lives in a workspace, set
+  `outputFileTracingRoot` in `next.config` — Next infers the root from
+  the nearest stray lockfile, and a wrong root silently breaks
+  page-segment hydration in dev (buttons render but nothing responds).
+
+## Step 2 — The client seam
+
+Construct ONE `StorefrontClient` per scope and pass it to every SDK call
+(all SDK functions take the client as first argument — see any domain doc's
+SDK line):
+
+- **Server** (RSC, server actions): construct per request; `getAuthToken`
+  reads the customer session cookie; `getLocale` reads the locale cookie.
+- **Browser**: construct once; token from your session store.
+
+Auth model (recap — full detail in [auth.md](auth.md)):
+`x-client-id` always; `x-publishable-api-key` when the store gave you one
+(it scopes the catalog and carts to the key's sales channels);
+`authorization: Bearer <jwt>` once a customer is logged in.
+
+**CORS (bites every browser client):** the store API sends NO CORS
+headers today, so browser-side SDK calls (cart drawer mutations, the
+whole checkout orchestration) only work same-origin. Unless your
+storefront is served from the Cartbase deployment origin itself, proxy the
+store surface through your own origin — in Next.js one rewrite does it —
+and give the BROWSER client `window.location.origin` as `baseUrl`
+(server-side calls hit `NEXT_PUBLIC_CARTBASE_URL` directly and are
+unaffected; see `examples/storefront/next.config.ts` for the working
+rewrite):
+
+```js
+// next.config.ts — proxy browser SDK traffic to the API origin
+async rewrites() {
+  return [{ source: "/api/store/:path*",
+            destination: `${process.env.NEXT_PUBLIC_CARTBASE_URL}/api/store/:path*` }]
+}
+```
+
+## Step 3 — Store configuration bootstrap
+
+Fetch once at layout level, cache per the docs' cache headers:
+
+1. [regions.md](regions.md) — regions (→ region_id for pricing + payment
+   providers), currencies, supported locales.
+2. [integrations.md](integrations.md) — `GET /api/store/integrations`: which
+   carriers are enabled (pickup points/lockers for checkout), COD fee
+   presence, and the **tracking block** (pixel/GA4/GTM/ads public ids).
+3. [consent.md](consent.md) — the CMP config for the consent banner.
+
+## Step 4 — Layout: consent, tracking, navigation
+
+Order inside `<body>` matters (contracts in [components.md](components.md)
+and [consent.md](consent.md)):
+
+1. `<ConsentInit>` FIRST child of body — static and synchronous, never
+   awaits a fetch (first-hit consent race otherwise).
+2. Tracking mounts (`<MetaPixel>`, `<GA4>`, GTM) — gated on the consent
+   state and fed by the integrations tracking block, never by env vars.
+3. Navigation from [menus.md](menus.md) — `main-menu` / `footer` handles;
+   an unknown handle 404s and must render as "no nav", never crash.
+
+## Step 5 — Catalog
+
+- [products.md](products.md) — listing + PDP. Always pass a pricing context
+  (`currency_code` or `region_id`) or prices come back undecorated; render
+  `variant.calculated_price`, fall back to base `prices[]`. **Never cache a
+  `calculated_price` response shared when a customer JWT was present** —
+  prices vary by customer group.
+- [collections.md](collections.md) — collection pages use the membership
+  endpoint (`/collections/:id/products`) which honors the admin's sort.
+- [categories.md](categories.md) — category tree, tags, types.
+- [search.md](search.md) — search page: `q` + facets from the response
+  (render buckets, apply via the documented query params), typo-tolerant,
+  synonym-aware. Related products on the PDP come from the same doc.
+- SEO: `seo_title`/`seo_description` fields with title/description
+  fallbacks; path conventions are `/products/<handle>`,
+  `/collections/<handle>`, `/categories/<handle>`.
+
+## Step 6 — Content
+
+- [content.md](content.md) — `/pages/<handle>` and `/blogs/<handle>` routes;
+  body HTML is server-sanitized, safe to render raw. Every store seeds
+  policy pages (`privacy-policy`, `terms-of-service`, `refund-policy`,
+  `shipping-policy`) — link them in the footer.
+- [metaobjects.md](metaobjects.md) — merchant-defined content (size charts
+  via the product→metafield→metaobject chain).
+- [redirects.md](redirects.md) — call ONLY from your `not-found` handler;
+  301 when `to_path` is non-null. Never on regular page loads.
+
+## Step 7 — Cart
+
+[carts.md](carts.md): create the cart lazily on first add-to-cart with the
+region + (optionally) sales channel; persist `cart.id` in a cookie; all cart
+mutations return the decorated cart — totals are SERVER truth, render them
+verbatim, never compute client-side. Line items, quantity updates, deletes,
+and the customer-attach call after login are all in that doc.
+[gift-cards.md](gift-cards.md): the apply/remove endpoints + the three
+decoration fields (`gift_cards[]`, `gift_card_total`,
+`gift_card_remainder`) your summary UI must render.
+
+## Step 8 — Checkout
+
+[checkout.md](checkout.md) is the authoritative sequence. In brief:
+
+1. List shipping options and payment providers **with `cart_id`** — the
+   server filters both through the merchant's checkout rules; your UI never
+   hides methods on its own.
+2. Carrier pickers (office/locker) come from the integrations config
+   ([integrations.md](integrations.md)); the chosen point goes into
+   `carrier_metadata`.
+3. Buy click = `prepare-checkout` (ONE call: address + shipping method +
+   payment session at the final amount) → for card: Stripe
+   `confirmPayment(client_secret)` → `complete`. For COD: `complete`
+   directly. Gift-card-covered carts skip the provider entirely.
+4. Handle the documented failure codes (`checkout_method_hidden`,
+   `account_required`, `gift_card_insufficient_balance`, cart-vs-order
+   union on complete) — each has a UI recovery path described in the doc.
+5. `sync-payment-amount` after any total-changing edit on the payment step;
+   `refresh-payment-if-terminal` only from Elements `loaderror` / aged-cart
+   mount.
+6. Order confirmation renders from [orders.md](orders.md)
+   (`/orders/display/:displayId` embeds items, fulfillments, tracking).
+
+## Step 9 — Customer accounts
+
+[auth.md](auth.md): passwordless email-code login (request → verify →
+Bearer session). [customers.md](customers.md): profile, addresses,
+order history, issued documents (invoices). Respect `accounts_mode`
+(store setting): `required` blocks guest checkout with `403
+account_required`; `disabled` means render no account UI at all. Gate B2B
+content on `customer.account_status === "approved"`.
+
+## Step 10 — Reviews
+
+[reviews.md](reviews.md): the PDP widget (`/reviews/widget` — aggregate +
+first page + display options in one call) and the token wizard route for
+email CTA links (`/review/<token>`): validate token → submit rating+body →
+optional photo step mints the reward code. Resume rules are in the doc.
+
+## Step 11 — Tracking events
+
+[components.md](components.md) tracking section: fire client events via the
+package helpers; **Purchase MUST use `eventID = "purchase_" +
+order.display_id`** so Meta dedupes browser Pixel against the server CAPI
+event; write the attribution keys (fbp/fbc/anon-id/ga session) into
+`cart.metadata` (consent-gated) so server events inherit them.
+
+## Step 12 — Go-live checklist
+
+- [ ] Pricing context passed on every catalog surface; no shared caching of
+      JWT-priced responses.
+- [ ] Consent banner renders for an unconfigured store (defaults are
+      server-applied); tags mount only behind consent.
+- [ ] Checkout completes: card (Stripe live), COD (fee renders from config),
+      gift card (partial + full cover).
+- [ ] Not-found handler consults redirects; policy pages linked.
+- [ ] Order confirmation + emails render totals identical to the cart.
+- [ ] Locale switching keeps cart + session; EUR everywhere.
+- [ ] The store's publishable key (if any) is set — B2B catalogs are
+      key-scoped and look "missing products" without it.
+
+## Step 13 — Ship it
+
+[deploy.md](deploy.md): send the app to Cartbase hosting — permanent
+preview URL on every deploy, **Publish** to go live, deploy history as
+rollback. Hosted storefronts get the three inputs above injected
+automatically, so there is nothing to configure.

package/template/app/docs/README.md

@@ -0,0 +1,77 @@
+# docs/storefront/ — the bulletproof storefront docs
+
+**Audience: an AGENT building a storefront from a blank Next.js app.** These
+docs are the entire knowledge transfer — every call shape, every curl, every
+setting, every component contract. If a storefront can't be built from these
+files alone, the fix is a doc fix, never tribal knowledge.
+
+Start at **[BUILD-A-STOREFRONT.md](BUILD-A-STOREFRONT.md)** — the runbook.
+Domain files below are its reference chapters.
+
+## Executable-docs contract (docs-truth CI)
+
+Docs that can lie aren't bulletproof, so every ```bash block in every file
+here is **extracted and executed** against the real test server by
+`tests/docs/storefront-curls.test.ts`. A drifted doc FAILS the build.
+
+Rules for doc authors (agents included):
+
+1. All ```bash blocks in one file form ONE script, executed top-to-bottom
+   with `bash -euo pipefail`. Later blocks may use variables exported by
+   earlier blocks (`CART_ID=$(curl … | grep -o …)`).
+2. The harness pre-exports: `BASE` (test-server origin), `CLIENT_ID` (dev
+   tenant id), `PUBLISHABLE_KEY` (the B2B-channel dev key — channel-scoped,
+   use only where the doc discusses key scoping).
+3. Every curl uses `-sf` (silent + fail-on-HTTP-error) unless the block
+   demonstrates an error case — then capture the status explicitly
+   (`-o /dev/null -w '%{http_code}'`) and assert it (`test "$STATUS" = 404`).
+4. Assert shape, not just liveness: pipe to `grep -q '"key"'` (or `node -e`
+   for anything structural). A block that checks nothing proves nothing.
+5. A block that must NOT run (illustrative only, external side effects)
+   starts with `# doc-noexec` on its first line. Use sparingly — every
+   noexec block is a hole in the truth gate.
+6. Blocks must be idempotent-safe on the shared dev tenant: create what you
+   read, suffix names with `$RUN` (pre-exported unique stamp), and clean up
+   in a final block when you created durable rows.
+
+## Per-domain file format
+
+One file per domain. For each endpoint, in order:
+
+- **Purpose** — one sentence, when a storefront calls it.
+- **Auth** — which headers (anon `x-client-id` / publishable key / Bearer).
+- **Request** — method, path, query/body shape (jsonc block).
+- **Response** — shape (jsonc block), with field notes.
+- **Working curl** — executable per the contract above.
+- **Errors** — status + `code` for every contract-listed failure.
+- **SDK** — the `@cartbase/storefront/api` function that wraps it.
+- **Components** — which `@cartbase/storefront` UI components consume it.
+- **Settings** — admin settings that change its behavior (checkout rules,
+  locales, consent, accounts mode…).
+
+## Files
+
+| File | Domain |
+|---|---|
+| [BUILD-A-STOREFRONT.md](BUILD-A-STOREFRONT.md) | The agent runbook — blank app → completed checkout |
+| [products.md](products.md) | Products, variants, pricing context |
+| [search.md](search.md) | Search, facets, related products |
+| [collections.md](collections.md) | Collections + membership listings |
+| [categories.md](categories.md) | Categories, tags, types |
+| [regions.md](regions.md) | Regions, currencies, locales |
+| [carts.md](carts.md) | Cart lifecycle + line items |
+| [gift-cards.md](gift-cards.md) | Gift-card tender on carts |
+| [checkout.md](checkout.md) | Shipping options, payment providers/collections, prepare-checkout orchestration, complete |
+| [orders.md](orders.md) | Order reads, display-id lookup, transfers |
+| [customers.md](customers.md) | Customer profile, addresses, documents |
+| [subscriptions.md](subscriptions.md) | Subscription portal: schedule control, contract edits, payment-method recovery |
+| [auth.md](auth.md) | Passwordless code login + session discipline |
+| [content.md](content.md) | Pages + blogs |
+| [menus.md](menus.md) | Navigation menus |
+| [metaobjects.md](metaobjects.md) | Merchant-defined content types |
+| [reviews.md](reviews.md) | Review widget, token wizard, photo rewards |
+| [integrations.md](integrations.md) | Store config: carriers, COD, tracking block, lockers |
+| [consent.md](consent.md) | Consent Mode v2 banner config |
+| [redirects.md](redirects.md) | 404-path URL redirects |
+| [components.md](components.md) | UI component families: contracts + required SDK calls |
+| [platform.md](platform.md) | Platform fingerprints: generator meta, window.Cartbase, x-cartbase-version header, cart cookie naming |

package/template/app/docs/auth.md

@@ -0,0 +1,105 @@
+# Auth — passwordless code login + session discipline
+
+Passwordless email-code login (customer-accounts card, Shopify Customer
+Account API direction). Two calls: **request** emails a 6-digit code,
+**verify** exchanges it for a session. Password login
+(`supabase.auth.signInWithPassword` client-side) stays available and yields
+an equivalent JWT — nothing here is needed for it.
+
+## The session discipline (one rule)
+
+`verify` mints a **real Supabase session**. Its `access_token` is the SAME
+`authorization: Bearer <jwt>` every `/api/store/*` route accepts — wire it
+into `StorefrontClient` once and every customer surface (customers/me,
+orders, documents, cart attach) is authenticated:
+
+```jsonc
+// new StorefrontClient({ baseUrl, clientId, getAuthToken: () => storedAccessToken })
+```
+
+Persist `access_token` + `refresh_token`; refresh client-side with the
+Supabase SDK (`setSession` → `refreshSession`) — the Cartbase API does not
+proxy token refresh. `expires_in` is seconds; `expires_at` epoch-seconds.
+
+## Server-enforced security posture (the SDK adds nothing)
+
+- Request NEVER reveals whether the email is registered — `{ok: true}`
+  always (no enumeration oracle). The code exists ONLY in the sent email.
+- Codes: hashed at rest, TTL **10 min**, single-use, one live code per
+  email (a new request supersedes prior codes), **5-wrong-attempt lockout**.
+- Rate limits per 15-min window: **5 requests per email**, **20 per IP** →
+  `429 rate_limited` — the only distinguishable request failure.
+- Every verify failure — wrong code, expired, consumed, locked out, unknown
+  email — is the SAME `401 invalid_code`.
+
+## POST /api/store/auth/code/request — step 1
+
+- **Purpose**: email a 6-digit one-time login code. First-time emails
+  register lazily at VERIFY, not here.
+- **Auth**: anon (`x-client-id` only).
+- **Request**: `{email: string}`.
+- **Response**: `{ok: true}` — always, by design.
+- **Errors**: `429 rate_limited` · `400 validation_failed` (malformed
+  email) · `400 missing_client_id`.
+- **SDK**: `auth.requestLoginCode(client, {email})`
+- **Components**: login form (account pages family).
+- **Settings**: the `auth-code` notification template carries the code.
+
+```bash
+# The request contract: {ok:true}, nothing else — no code echo, no
+# registered-or-not oracle. RUN-stamped email → no rate-limit collisions.
+curl -sf -X POST "$BASE/api/store/auth/code/request" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"email": "doc-auth-'$RUN'@doc.test"}' \
+  | grep -q '^{"ok":true}$'
+```
+
+## POST /api/store/auth/code/verify — step 2
+
+- **Purpose**: exchange (email, code) for a session. This is ALSO
+  passwordless **registration** — a first-time email lazy-creates the
+  customer (`account_status` per store policy) and triggers the welcome
+  email.
+- **Auth**: anon (`x-client-id` only).
+- **Request**: `{email: string, code: string}` — code is exactly 6 digits
+  (leading zeros count; any other shape → `400 validation_failed`).
+- **Response**:
+
+```jsonc
+{
+  "access_token": "eyJ…",        // the Bearer JWT for every store route
+  "refresh_token": "…",
+  "expires_in": 3600,             // seconds
+  "expires_at": 1789300000,       // epoch seconds (may be absent)
+  "token_type": "bearer",
+  "customer": { /* full customer + addresses — see customers.md */ }
+}
+```
+
+- **Errors**: `401 invalid_code` (every auth failure, generic) ·
+  `400 validation_failed` · `400 missing_client_id`.
+- **SDK**: `auth.verifyLoginCode(client, {email, code})`
+- **Components**: code-entry form (account pages family).
+- **Settings**: store approval policy (new-customer `account_status`);
+  `account-welcome` template.
+
+```bash
+# The 401 invalid_code contract — a well-formed but wrong code against the
+# RUN-stamped email (its real code lives only in the email we never read).
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  -X POST "$BASE/api/store/auth/code/verify" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"email": "doc-auth-'$RUN'@doc.test", "code": "000000"}')
+test "$STATUS" = 401
+curl -s -X POST "$BASE/api/store/auth/code/verify" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"email": "doc-auth-'$RUN'@doc.test", "code": "000000"}' \
+  | grep -q '"code":"invalid_code"'
+```
+
+> Cleanup note: the code rows this doc creates are single-per-run
+> (RUN-stamped email), superseded on any later request and dead after the
+> 10-minute TTL — there is no store-surface delete for them by design (they
+> are the auth trail). The happy-path session mint is exercised with a real
+> inbox-free code by `tests/store/customer-accounts-auth.test.ts` and the
+> SDK contract test (server-side code issue via the lib).