create-cartbase 0.0.1 → 0.1.1

package/template/app/docs/redirects.md

@@ -0,0 +1,50 @@
+# URL redirects — 404-path lookup
+
+Exact-match redirect lookup (seo-listings card 21). **Hot-path rule: call
+this ONLY from the storefront's not-found handler** — never on regular page
+loads (index-covered exact match on `(client_id, from_path)`). When
+`to_path` is non-null, issue a **301** to it; when null, render the 404.
+
+Redirects are created in admin and **automatically on handle renames** of
+products/collections/pages/posts — wiring this once means renames never
+break old URLs (path convention shared with [content.md](content.md) and
+[menus.md](menus.md)).
+
+## GET /api/store/url-redirects?path=… — lookup
+
+- **Purpose**: resolve a missed pathname (e.g. `/products/old-handle`) to
+  its redirect target, if any.
+- **Auth**: anon (`x-client-id`).
+- **Request**: query `{path}` — the exact pathname that 404'd (leading
+  slash included), min length 1.
+- **Response**:
+
+```jsonc
+{
+  "path": "/products/old-handle",   // echoed
+  "to_path": "/products/new-handle" // or null — no redirect, render the 404
+}
+```
+
+- **Errors**: `400 validation_failed` (missing/empty `path`) ·
+  `400 missing_client_id`.
+- **SDK**: `redirects.lookupRedirect(client, path)`
+- **Components**: the storefront `not-found` handler (no visual component).
+- **Settings**: admin → Content → URL redirects; automatic rows on handle
+  renames.
+
+```bash
+# Miss → to_path null (the everyday 404 case), echo intact.
+BODY=$(curl -sf "$BASE/api/store/url-redirects?path=/doc-no-such-path-$RUN" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$BODY" | grep -q '"to_path":null'
+echo "$BODY" | grep -q "doc-no-such-path-$RUN"
+# Missing path param → 400.
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/url-redirects" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 400
+```
+
+> The hit case (`to_path` non-null) requires an admin-created redirect row;
+> it is pinned executably by `tests/store/url-redirects-lookup.test.ts` and
+> the SDK contract test `tests/contract/sdk-content.contract.test.ts`.

package/template/app/docs/regions.md

@@ -0,0 +1,206 @@
+# Regions, currencies, locales
+
+Catalog-context primitives a storefront resolves at boot: regions feed the
+pricing context (`region_id` → region currency), currencies tell you what the
+store has enabled, locales drive the language switcher and the client's
+`x-locale` header. All reads are anonymous. Money is EUR decimal major units
+everywhere.
+
+SDK module: `@cartbase/storefront/api/regions`.
+
+---
+
+## GET /api/store/regions
+
+- **Purpose** — list the store's regions; a storefront usually picks one at
+  boot (or by shopper choice) and passes its id/currency as the pricing
+  context on catalog reads.
+- **Auth** — anon: `x-client-id` required.
+- **Request** — `GET /api/store/regions`
+
+```jsonc
+// query (all optional)
+{
+  "q": "bulg",             // case-insensitive substring on name
+  "currency_code": "eur",  // exact match, lowercased server-side
+  "limit": 50,             // 1–200, default 50
+  "offset": 0
+}
+```
+
+- **Response** — ordered by name. NOTE: Cartbase regions carry NO embedded
+  `countries` array — country/tax scope lives server-side in
+  `tax_regions`.
+
+```jsonc
+{
+  "regions": [
+    {
+      "id": "reg_01tst000000000000000000001",
+      "name": "Bulgaria",
+      "currency_code": "eur",       // lowercase — feeds the pricing context
+      "automatic_taxes": true,
+      "metadata": null,
+      "created_at": "2026-07-01T00:00:00.000Z",
+      "updated_at": "2026-07-01T00:00:00.000Z"
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 50
+}
+```
+
+- **Working curl**
+
+```bash
+REGIONS=$(curl -sf "$BASE/api/store/regions" -H "x-client-id: $CLIENT_ID")
+echo "$REGIONS" | grep -q '"regions"'
+echo "$REGIONS" | grep -q '"count"'
+REGION_ID=$(echo "$REGIONS" | grep -o '"id":"reg_[^"]*"' | head -1 | cut -d'"' -f4)
+test -n "$REGION_ID"
+```
+
+- **Errors** — 400 `missing_client_id` (header absent/empty),
+  400 `validation_failed` (bad limit/offset).
+- **SDK** — `listRegions(client, query?)`.
+- **Components** — region/currency selector (see components.md).
+- **Settings** — Admin → Settings → Regions.
+
+```bash
+# Auth contract: no x-client-id → 400 missing_client_id
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/regions")
+test "$STATUS" = 400
+curl -s "$BASE/api/store/regions" | grep -q '"code":"missing_client_id"'
+```
+
+---
+
+## GET /api/store/regions/:id
+
+- **Purpose** — retrieve one region (e.g. re-hydrate the shopper's stored
+  choice).
+- **Auth** — anon: `x-client-id` required.
+- **Request** — `GET /api/store/regions/{region_id}` — no query.
+- **Response** — `{ "region": { ...same shape as the list rows... } }`
+- **Working curl**
+
+```bash
+REGION=$(curl -sf "$BASE/api/store/regions/$REGION_ID" -H "x-client-id: $CLIENT_ID")
+echo "$REGION" | grep -q '"region"'
+echo "$REGION" | grep -q '"currency_code"'
+```
+
+- **Errors** — 404 `not_found` (unknown id, soft-deleted, or another
+  tenant's region — invisible, not forbidden).
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/regions/reg_doesnotexist$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+curl -s "$BASE/api/store/regions/reg_doesnotexist$RUN" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"code":"not_found"'
+```
+
+- **SDK** — `retrieveRegion(client, regionId)`.
+- **Components** — region/currency selector.
+- **Settings** — Admin → Settings → Regions.
+
+---
+
+## GET /api/store/currencies
+
+- **Purpose** — list the currencies ENABLED on this store (the shared
+  currency catalog filtered by the store's `store_currencies` links). Use
+  for formatting metadata (symbol, decimal digits).
+- **Auth** — anon: `x-client-id` required.
+- **Request** — query `{ code?, limit?, offset? }` (`code` exact,
+  lowercased; `limit` 1–200, default 50).
+- **Response** — ordered by code; a store with no enabled currencies
+  returns an empty list.
+
+```jsonc
+{
+  "currencies": [
+    {
+      "code": "eur",
+      "name": "Euro",
+      "symbol": "€",
+      "symbol_native": "€",
+      "decimal_digits": 2,
+      "rounding": 0,
+      "created_at": "2026-07-01T00:00:00.000Z",
+      "updated_at": "2026-07-01T00:00:00.000Z"
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 50
+}
+```
+
+- **Working curl**
+
+```bash
+CURRENCIES=$(curl -sf "$BASE/api/store/currencies" -H "x-client-id: $CLIENT_ID")
+echo "$CURRENCIES" | grep -q '"currencies"'
+echo "$CURRENCIES" | grep -q '"code":"eur"'   # the dev store enables EUR
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`.
+- **SDK** — `listCurrencies(client, query?)`.
+- **Components** — price formatting helpers.
+- **Settings** — Admin → Settings → Store → currencies (enable/disable +
+  default).
+
+---
+
+## GET /api/store/currencies/:code
+
+- **Purpose** — retrieve one currency by code (case-insensitive).
+- **Auth** — anon: `x-client-id` required.
+- **Request** — `GET /api/store/currencies/{code}` — no query.
+- **Response** — `{ "currency": { ...same shape as the list rows... } }`
+- **Working curl**
+
+```bash
+CURRENCY=$(curl -sf "$BASE/api/store/currencies/eur" -H "x-client-id: $CLIENT_ID")
+echo "$CURRENCY" | grep -q '"currency"'
+echo "$CURRENCY" | grep -q '"symbol"'
+```
+
+- **Errors** — 404 `not_found`.
+- **CODE-TRUTH NOTE** — unlike the list, the single read is NOT filtered by
+  the store's enabled set: any currency in the shared catalog resolves.
+  Treat the LIST as the authority on what the store supports.
+- **SDK** — `retrieveCurrency(client, code)`.
+- **Components** — price formatting helpers.
+- **Settings** — Admin → Settings → Store → currencies.
+
+---
+
+## GET /api/store/locales
+
+- **Purpose** — the store's supported locale codes; drives the language
+  switcher and the value your client sends as `x-locale`.
+- **Auth** — anon: `x-client-id` required.
+- **Request** — no query.
+- **Response** — default locale FIRST, then alphabetical:
+
+```jsonc
+{ "locales": ["en", "bg"] }
+```
+
+- **Working curl**
+
+```bash
+LOCALES=$(curl -sf "$BASE/api/store/locales" -H "x-client-id: $CLIENT_ID")
+echo "$LOCALES" | grep -q '"locales"'
+echo "$LOCALES" | grep -q '"en"'
+```
+
+- **Errors** — 400 `missing_client_id`.
+- **SDK** — `listLocales(client)`.
+- **Components** — locale switcher; `StorefrontClient`'s `getLocale` hook.
+- **Settings** — Admin → Settings → Store → locales (each store manages
+  its own locale list in `store_locales`).

package/template/app/docs/reviews.md

@@ -0,0 +1,223 @@
+# Reviews — widget, token wizard, photo rewards
+
+Verified-purchase reviews. Reviews exist **only** via a
+single-use, order-scoped, expiring **token** minted by the request scanner
+and mailed as `<review_link_base>/<token>` — the token IS the auth for
+every write; no login. All public reads serve `status='visible'` rows only
+— hidden/pending/deleted never leak (RLS-enforced too).
+
+The wizard is two-step: **submit** (rating + body, consumes the token) →
+**photo** (attach media, mint the reward code). Resume rule: token consumed
++ `review.reward_code` null → resume at the photo step; `reward_code` set →
+fully done, show the code.
+
+> Public reads below run executably against the seeded `Linen Shirt`
+> product (`prod_01tst00000000000000000001`, scripts/seed-fixtures.ts) —
+> shape holds at any review count, including zero. Token-gated writes need
+> a server-minted token, so their happy paths are pinned by
+> `tests/store/reviews-store.test.ts` + `tests/contract/reviews-widget.contract.test.ts`;
+> here the error contracts run executably.
+
+## GET /api/store/reviews — list visible reviews
+
+- **Purpose**: the paginated review list under the PDP widget.
+- **Auth**: anon (`x-client-id`).
+- **Request**: query `{product_id (required), sort? default|rating|date,
+  order? asc|desc, limit? (≤50, default 10), offset?}`. `default` = with-
+  media first, newest within.
+- **Response**: `{reviews: [PublicReview…], count, has_more}`.
+  `PublicReview` is EXACTLY these keys (leak guard — no email/order/IP/
+  reward/status; media entries hidden by moderation are filtered out):
+
+```jsonc
+{
+  "reviews": [
+    {
+      "id": "uuid",
+      "customer_name": "Елена Г.",
+      "rating": 5,
+      "title": null,                  // always null — the form has no title
+      "body": "Страхотна риза!",
+      "media": [ { "type": "image", "url": "https://…", "thumb": "https://…", "w": 0, "h": 0, "bytes": 0 } ],
+      "admin_response": null,
+      "admin_response_at": null,
+      "created_at": "ISO-8601"
+    }
+  ],
+  "count": 1,
+  "has_more": false
+}
+```
+
+- **Errors**: `400 validation_failed` (missing product_id, bad sort/limit).
+- **SDK**: `reviews.listReviews(client, query)`
+- **Components**: review list / masonry grid (review widget family).
+
+```bash
+curl -sf "$BASE/api/store/reviews?product_id=prod_01tst00000000000000000001&sort=date" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"has_more"'
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/reviews" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 400
+```
+
+## GET /api/store/reviews/aggregate — star-badge stats
+
+- **Purpose**: the PDP star rating + histogram. Visible only. Edge-cached
+  60s (`Cache-Control: public, max-age=60, s-maxage=60`).
+- **Auth**: anon (`x-client-id`).
+- **Request**: query `{product_id}`.
+- **Response**: `{product_id, count, avg_rating, distribution: {"1"…"5"}}`
+  — `avg_rating` rounded to 1 decimal, 0 when no reviews.
+- **Errors**: `400 validation_failed`.
+- **SDK**: `reviews.getAggregate(client, productId)`
+- **Components**: star badge (PDP + product cards).
+
+```bash
+curl -sf "$BASE/api/store/reviews/aggregate?product_id=prod_01tst00000000000000000001" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"distribution"'
+```
+
+## GET /api/store/reviews/widget — one-call widget payload
+
+- **Purpose**: aggregate + first page (sized/sorted per the store's
+  Settings → Reviews display options) + display options in ONE call — what
+  the product widget + star badge mount from. Edge-cached 60s.
+- **Auth**: anon (`x-client-id`).
+- **Request**: query `{product_id}`.
+- **Response**:
+
+```jsonc
+{
+  "product_id": "prod_…",
+  "aggregate": { /* ReviewAggregate — shape above */ },
+  "reviews": [ /* PublicReview[] — first page */ ],
+  "count": 3,
+  "has_more": false,
+  "options": { "layout": "masonry", "page_size": 6, "photo_first": true }
+}
+```
+
+- **Errors**: `400 validation_failed`.
+- **SDK**: `reviews.getWidget(client, productId)`
+- **Components**: the review widget (masonry/list) + star badge.
+- **Settings**: `widget_layout`, `widget_page_size`, `widget_photo_first`
+  (admin → Settings → Reviews).
+
+```bash
+BODY=$(curl -sf "$BASE/api/store/reviews/widget?product_id=prod_01tst00000000000000000001" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$BODY" | grep -q '"aggregate"'
+echo "$BODY" | grep -q '"options"'
+echo "$BODY" | grep -q '"photo_first"'
+```
+
+## GET /api/store/reviews/token/:token — validate + form context
+
+- **Purpose**: bootstrap the review form from the emailed link: validity,
+  product card, greeting, and the RESUME state. **Never cached** — state
+  changes on submit.
+- **Auth**: anon (`x-client-id`); the token is the bearer secret.
+- **Response** — ALWAYS 200, `TokenValidation`:
+
+```jsonc
+// invalid
+{ "valid": false, "reason": "not_found" }   // or "expired" | "invalid" (malformed/too short)
+// valid
+{
+  "valid": true,
+  "already_submitted": false,
+  "review": null,                  // {id, reward_code} once submitted
+  "product": { "id": "prod_…", "handle": "linen-shirt", "title": "Linen Shirt", "thumbnail": "https://…" },
+  "customer_name": "Елена",
+  "expires_at": "ISO-8601"
+}
+```
+
+- **Errors**: none over HTTP — failures are in-band (`valid: false`).
+- **SDK**: `reviews.validateToken(client, token)`
+- **Components**: review wizard entry route.
+
+```bash
+# Unknown (but well-formed) token → in-band not_found, HTTP 200.
+curl -sf "$BASE/api/store/reviews/token/doc-not-a-real-token-$RUN" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"reason":"not_found"'
+# Malformed (too short) → "invalid".
+curl -sf "$BASE/api/store/reviews/token/short" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"reason":"invalid"'
+```
+
+## POST /api/store/reviews — submit (wizard step 1)
+
+- **Purpose**: create the review from a token. Consumes the token;
+  idempotent on the (order, product) unique — a race/retry returns the
+  existing review and still consumes the token.
+- **Auth**: anon (`x-client-id`); the token is the auth.
+- **Request**: `{token, rating: 1–5 int, body (REQUIRED — a rating alone is
+  not a review; HTML stripped, ≤2000 chars), media?}` — media ≤ 7 items
+  (≤6 images + ≤1 video), URLs must be on the store's file host (from
+  upload-url below). **No title field.**
+- **Response**: `{id, success: true}`.
+- **Errors**: `400 invalid_data` (shape / empty-after-sanitize body / media
+  rule) · `404 not_found` (unknown token) · `409 conflict` (token consumed
+  — replay) · `410 gone` (expired) · `429 rate_limited` (3/h per IP).
+- **SDK**: `reviews.submitReview(client, input)`
+- **Components**: review wizard, step 1.
+- **Settings**: `moderation_mode: "hold"` lands the review as `pending`
+  (not publicly visible until approved); `auto_publish` goes live at once.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST "$BASE/api/store/reviews" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"token": "doc-not-a-real-token-'$RUN'", "rating": 5, "body": "great"}')
+test "$STATUS" = 404
+```
+
+## POST /api/store/reviews/:id/photo — attach media + reward (step 2)
+
+- **Purpose**: attach media and mint the single-use reward code (a REAL
+  promotion, percentage-off-order — 10% default). The reward is for the
+  PHOTO, never the rating. Idempotent — retries return the same code; a
+  promo-mint failure never loses the media. A CONSUMED token is accepted
+  (step 1 consumed it).
+- **Auth**: anon (`x-client-id`); the token must match the review's
+  (order, product) pair.
+- **Request**: `{token, media (1–7 items, ≤6 images + ≤1 video, file-host
+  URLs only)}`.
+- **Response**: `{code}` (fresh mint — also emails the `review-reward`
+  template) | `{code, already_issued: true}` (retry) | `{code: null,
+  message}` (mint failed; media saved).
+- **Errors**: `400 invalid_data` · `403 forbidden` (token does not match
+  this review) · `404 not_found` (review or token unknown).
+- **SDK**: `reviews.attachReviewPhoto(client, reviewId, input)`
+- **Components**: review wizard, step 2 (photo + reward reveal).
+- **Settings**: `reward_enabled`, `reward_percentage`.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  -X POST "$BASE/api/store/reviews/00000000-0000-0000-0000-00000000dead/photo" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"token": "doc-not-a-real-token-'$RUN'", "media": [{"type": "image", "url": "https://example.com/x.jpg"}]}')
+test "$STATUS" = 400
+```
+
+## POST /api/store/reviews/upload-url — signed media upload
+
+- **Purpose**: get a signed R2 PUT for the photo step. Upload the raw file
+  to `uploadUrl`, then reference `publicUrl` in the media array. A consumed
+  token is accepted; expiry still applies.
+- **Auth**: anon (`x-client-id`); the token is the auth.
+- **Request**: `{token, name, type (image/jpeg|jpg|png|webp or
+  video/mp4|quicktime), size?}` — caps: image ≤ 8MB, video ≤ 50MB.
+- **Response**: `{uploadUrl, publicUrl, key, filename}`.
+- **Errors**: `400 invalid_data` (unsupported MIME, too large) ·
+  `404 not_found` (unknown token) · `410 gone` (expired token).
+- **SDK**: `reviews.createUploadUrl(client, input)`
+- **Components**: review wizard photo picker.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST "$BASE/api/store/reviews/upload-url" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"token": "doc-not-a-real-token-'$RUN'", "name": "x.jpg", "type": "image/jpeg"}')
+test "$STATUS" = 404
+```