npm - create-cartbase - Versions diffs - 0.0.1 → 0.1.1 - Mend

create-cartbase 0.0.1 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (49) hide show

package/LICENSE +21 -0
package/README.md +9 -3
package/dist/index.js +94 -0
package/package.json +18 -4
package/template/app/CLAUDE.md +18 -0
package/template/app/docs/BUILD-A-STOREFRONT.md +216 -0
package/template/app/docs/README.md +77 -0
package/template/app/docs/auth.md +105 -0
package/template/app/docs/carts.md +376 -0
package/template/app/docs/categories.md +194 -0
package/template/app/docs/checkout.md +611 -0
package/template/app/docs/collections.md +167 -0
package/template/app/docs/components.md +1090 -0
package/template/app/docs/consent.md +81 -0
package/template/app/docs/content.md +126 -0
package/template/app/docs/customers.md +269 -0
package/template/app/docs/deploy.md +192 -0
package/template/app/docs/gift-cards.md +153 -0
package/template/app/docs/integrations.md +137 -0
package/template/app/docs/menus.md +73 -0
package/template/app/docs/metaobjects.md +126 -0
package/template/app/docs/orders.md +221 -0
package/template/app/docs/platform.md +126 -0
package/template/app/docs/products.md +300 -0
package/template/app/docs/redirects.md +50 -0
package/template/app/docs/regions.md +206 -0
package/template/app/docs/reviews.md +223 -0
package/template/app/docs/search.md +218 -0
package/template/app/docs/subscriptions.md +148 -0
package/template/app/next.config.ts +34 -0
package/template/app/package.json +25 -0
package/template/app/postcss.config.cjs +6 -0
package/template/app/smoke.mjs +158 -0
package/template/app/src/app/checkout/checkout-page-client.tsx +66 -0
package/template/app/src/app/checkout/page.tsx +51 -0
package/template/app/src/app/globals.css +42 -0
package/template/app/src/app/layout.tsx +113 -0
package/template/app/src/app/order/[id]/confirmed/page.tsx +77 -0
package/template/app/src/app/page.tsx +25 -0
package/template/app/src/app/products/[handle]/page.tsx +58 -0
package/template/app/src/app/providers.tsx +54 -0
package/template/app/src/app/search/page.tsx +20 -0
package/template/app/src/lib/browser-client.ts +35 -0
package/template/app/src/lib/cart-actions.ts +47 -0
package/template/app/src/lib/config.ts +21 -0
package/template/app/src/lib/server-client.ts +25 -0
package/template/app/tailwind.config.cjs +9 -0
package/template/app/tsconfig.json +41 -0
package/template/app/tsconfig.tsbuildinfo +1 -0

package/template/app/docs/consent.md ADDED Viewed

@@ -0,0 +1,81 @@
+# Consent — Consent Mode v2 banner config
+The store's CMP configuration for the built-in Consent Mode v2 banner
+(consent-management card). Defaults are **always applied server-side**, so
+the payload is complete and renderable even for an unconfigured store
+(compliant built-in modal, BG + EN copy shipped).
+## Storefront wiring (the trap that matters)
+- Mount `<ConsentInit>` as the **first child of `<body>`** — it sets the
+  synchronous Consent Mode v2 DEFAULT and must **never wait on this fetch**
+  (async default = first-hit consent race). Resolve this config server-side
+  (RSC) and inline it into the document.
+- Render the built-in banner only when `enabled && mode === "builtin"`.
+- `mode: "external"` = the merchant's CMP owns the UI and must write the
+  same `_1c_consent` cookie (or call `setConsent()`) — all Cartbase-side tag
+  gating works off that one seam.
+- Choices persist 12 months in the cookie. Rybbit (platform analytics)
+  stays outside consent by design.
+- Pair with [integrations.md](integrations.md): `tracking.consent_required`
+  mirrors `enabled` here — tags mount only through the consent gate when
+  true.
+## GET /api/store/consent — the CMP config
+- **Purpose**: everything the banner needs to render, per locale.
+- **Auth**: anon (`x-client-id`).
+- **Request**: no params.
+- **Response** — the EXACT allowlist (nothing else will ever appear here):
+```jsonc
+{
+  "consent": {
+    "enabled": true,
+    "mode": "builtin",              // "builtin" | "external"
+    "layout": "modal",              // "modal" (blocking) | "banner-bottom" (non-blocking)
+    "privacy_href": "/cookies",
+    "reject_on_first_layer": false,
+    "copy": {
+      "bg": {
+        "title": "Преди да продължиш",
+        "body": "…",
+        "privacy_link_label": "…",
+        "accept_label": "…", "settings_label": "…", "reject_label": "…",
+        "settings_title": "…",
+        "accept_all_label": "…", "save_label": "…", "reject_all_label": "…",
+        "necessary_label": "…", "necessary_description": "…",
+        "analytics_label": "…", "analytics_description": "…",
+        "ads_label": "…", "ads_description": "…"
+      },
+      "en": { /* same 16 keys — every field always present per locale */ }
+    }
+  }
+}
+```
+- **Errors**: `400 missing_client_id` only — the payload itself always
+  succeeds (a corrupt/missing stored config degrades to defaults, never to
+  a broken banner).
+- **SDK**: `consent.getConsent(client)`
+- **Components**: `<ConsentInit>` + `<ConsentBanner copy={copy[locale]}
+  layout privacyHref rejectOnFirstLayer>` (consent family; reference impl
+  `src/components/storefront/consent/`).
+- **Settings**: admin → Settings → Consent (enabled/mode/layout/
+  privacy_href/copy per locale).
+```bash
+# Complete, renderable config — even on an unconfigured store the defaults
+# make every documented key present.
+BODY=$(curl -sf "$BASE/api/store/consent" -H "x-client-id: $CLIENT_ID")
+echo "$BODY" | grep -q '"consent"'
+echo "$BODY" | grep -q '"mode"'
+echo "$BODY" | grep -q '"layout"'
+echo "$BODY" | grep -q '"privacy_href"'
+echo "$BODY" | grep -q '"reject_on_first_layer"'
+echo "$BODY" | grep -q '"analytics_label"'
+echo "$BODY" | grep -q '"ads_description"'
+# Missing tenant header → the standard 400.
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/consent")
+test "$STATUS" = 400
+```

package/template/app/docs/content.md ADDED Viewed

@@ -0,0 +1,126 @@
+# Content — pages + blogs
+Shopify Storefront `Page` / `Article` shapes **verbatim** so storefront code
+ports 1:1. **PUBLISHED only** — drafts and deleted rows 404 (lib status
+filter AND the anon RLS policy). Stored HTML is server-sanitized on write —
+safe to render raw (`dangerouslySetInnerHTML`).
+Path convention (`src/lib/content/paths.ts`, shared with menus + redirects):
+`/pages/<handle>`, `/blogs/<handle>`, `/blogs/<blog>/<post>`. Handle renames
+create URL redirects automatically — wire [redirects.md](redirects.md) into
+your 404 handler and old content URLs keep working.
+Policy pages every store carries (`privacy-policy`, `terms-of-service`,
+`refund-policy`, `shipping-policy`) are seeded as **drafts** — they 404 here
+until the merchant publishes them.
+> Content is admin-authored; the shared dev tenant seeds no published
+> pages/blogs, so the executable blocks prove the 404 contract and the
+> happy-path shapes are pinned by `tests/store/content-store.test.ts` and
+> `tests/contract/sdk-content.contract.test.ts` (which create fixtures with
+> admin auth).
+## GET /api/store/pages/:handle — one page
+- **Purpose**: render a static page (`/pages/<handle>`).
+- **Auth**: anon (`x-client-id`).
+- **Request**: path handle only.
+- **Response**:
+```jsonc
+{
+  "page": {
+    "id": "cpage_<hex>",
+    "handle": "about-us",
+    "title": "About us",
+    "body": "<h2>…</h2>",              // sanitized HTML — render raw
+    "bodySummary": "…",                 // stripped, ~160-char word-boundary cut
+    "seo": {
+      "title": "About us",              // fallback: title
+      "description": "…"                // fallback: bodySummary
+    },
+    "publishedAt": "ISO-8601",
+    "createdAt": "ISO-8601",
+    "updatedAt": "ISO-8601"
+  }
+}
+```
+- **Errors**: `404 not_found` — unknown handle, draft, or deleted.
+- **SDK**: `content.getPage(client, handle)`
+- **Components**: static page template; footer policy links.
+- **Settings**: page status (draft/published) in admin → Content → Pages.
+```bash
+# Unknown handle → the clean 404 contract (drafts behave identically).
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/pages/doc-no-such-page-$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+curl -s "$BASE/api/store/pages/doc-no-such-page-$RUN" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"code":"not_found"'
+```
+## GET /api/store/blogs/:handle/posts — blog listing
+- **Purpose**: the blog index (`/blogs/<handle>`), paginated.
+- **Auth**: anon (`x-client-id`).
+- **Request**: query `{limit? (≤100, default 20), offset?}`. Published
+  only, `published_at` desc.
+- **Response**:
+```jsonc
+{
+  "blog": { "handle": "news", "title": "News" },
+  "articles": [ /* Article[] — the exact shape below */ ],
+  "count": 12,
+  "offset": 0,
+  "limit": 20
+}
+```
+- **Errors**: `404 not_found` (unknown blog handle) ·
+  `400 validation_failed` (limit/offset out of range).
+- **SDK**: `content.listBlogPosts(client, blogHandle, query?)`
+- **Components**: blog index template.
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/blogs/doc-no-such-blog-$RUN/posts" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+## GET /api/store/blogs/:handle/posts/:postHandle — one article
+- **Purpose**: render one post (`/blogs/<blog>/<post>`).
+- **Auth**: anon (`x-client-id`).
+- **Response** — Shopify `Article` verbatim:
+```jsonc
+{
+  "article": {
+    "id": "bpost_<hex>",
+    "handle": "hello-world",
+    "title": "Hello world",
+    "contentHtml": "<p>…</p>",         // sanitized HTML — render raw
+    "content": "…",                     // plain-text version
+    "excerpt": "…",                     // author-provided; falls back to truncated content
+    "image": { "url": "https://…", "altText": null },  // null when no hero image
+    "tags": ["news"],
+    "author": { "name": "Maria" },     // null when unset
+    "publishedAt": "ISO-8601",
+    "seo": { "title": "…", "description": "…" },  // fallbacks: title / excerpt
+    "blog": { "handle": "news", "title": "News" }
+  }
+}
+```
+- **Errors**: `404 not_found` — unknown blog OR unknown/draft post.
+- **SDK**: `content.getBlogPost(client, blogHandle, postHandle)`
+- **Components**: article template; article cards reuse the listing shape.
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/blogs/doc-no-such-blog-$RUN/posts/doc-no-post-$RUN" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```

package/template/app/docs/customers.md ADDED Viewed

@@ -0,0 +1,269 @@
+# Customers — profile, addresses, documents
+The signed-in customer surface. Every endpoint here requires a **customer
+session**: `authorization: Bearer <supabase jwt>` (minted by the
+passwordless flow — see [auth.md](auth.md) — or a client-side supabase
+password sign-in) **plus** the `x-client-id` tenant header the storefront
+always sends. Missing/invalid JWT → `401 {code: "unauthenticated"}` on every
+route below.
+Lazy registration: `/customers/me` resolves the customer by
+(client_id, JWT email) and **creates the row on first authenticated call**
+(has_account=true, `account_status` per the store's approval policy) — a
+fresh login never 404s on "me".
+`customer.account_status` (`pending` | `approved`) is on every customer
+payload; when the store's B2B approval policy is on, hide B2B content until
+`approved`.
+> The executable blocks below prove the **auth boundary** (401 contract) —
+> the docs harness is anonymous, so happy paths are shown as `jsonc` shapes
+> and are pinned by `tests/contract/customers.contract.test.ts` and
+> `tests/store/customer-accounts-*.test.ts` with real sessions.
+## POST /api/store/customers — guest-to-registered conversion
+- **Purpose**: bind a password sign-up to a customer row. Flow:
+  `supabase.auth.signUp({email, password})` client-side → this call with the
+  same email. NOT needed for the passwordless code flow (verify already
+  lazy-creates the customer).
+- **Auth**: Bearer JWT (+ `x-client-id`). Body email MUST equal the JWT
+  email.
+- **Request**:
+```jsonc
+// POST /api/store/customers
+{
+  "email": "maria@example.com",   // must match the session email
+  "first_name": "Maria",           // optional
+  "last_name": "Petrova",          // optional
+  "phone": "+359888123456",        // optional
+  "company_name": "Acme OOD"       // optional
+}
+```
+- **Response**: `{customer}` — the full customer with `addresses` embedded
+  (empty on first create). See the shape under `/customers/me` below.
+- **Errors**: `401 unauthenticated` · `403 email_mismatch` (body email ≠
+  session email) · `400 validation_failed`.
+- **SDK**: `customers.createCustomer(client, input)`
+- **Components**: account registration form (account pages family).
+- **Settings**: store approval policy decides `account_status` of a NEW row
+  (`pending` when B2B approval is required, else `approved`).
+```bash
+# No session → the documented 401 contract (the auth boundary, executable).
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST "$BASE/api/store/customers" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"email": "doc-'$RUN'@doc.test"}')
+test "$STATUS" = 401
+```
+## GET /api/store/customers/me — the signed-in customer
+- **Purpose**: hydrate account state after login / on account pages.
+  Lazy-creates the customer row on first call for this (tenant, email).
+- **Auth**: Bearer JWT (+ `x-client-id`).
+- **Request**: no params.
+- **Response**:
+```jsonc
+{
+  "customer": {
+    "id": "uuid",
+    "client_id": "uuid",
+    "email": "maria@example.com",
+    "first_name": "Maria",
+    "last_name": "Petrova",
+    "phone": "+359888123456",
+    "company_name": null,
+    "company_eik": null,            // Bulgarian company id (ЕИК) — invoice checkout
+    "vat_number": null,
+    "has_account": true,
+    "account_status": "approved",   // "pending" | "approved" — B2B gating
+    "tags": [],                      // admin-only labels; read-only here
+    "metadata": null,
+    "created_by": null,
+    "created_at": "ISO-8601",
+    "updated_at": "ISO-8601",
+    "deleted_at": null,
+    "addresses": [ /* CustomerAddress[], created_at asc — shape below */ ]
+  }
+}
+```
+- **Errors**: `401 unauthenticated` · `400 missing_client_id`.
+- **SDK**: `customers.getMe(client)`
+- **Components**: account dashboard / header account state.
+- **Settings**: approval policy (`account_status` on lazy create).
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/customers/me" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 401
+# The error envelope carries the stable code:
+curl -s "$BASE/api/store/customers/me" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"code":"unauthenticated"'
+```
+## POST /api/store/customers/me — update own profile
+- **Purpose**: profile edit (names, phone, company/VAT master data).
+- **Auth**: Bearer JWT (+ `x-client-id`).
+- **Request** (all optional; nullable fields clear with `null`):
+```jsonc
+{
+  "first_name": "Maria",
+  "last_name": "Petrova",
+  "phone": "+359888123456",
+  "company_name": "Acme OOD",
+  "company_eik": "123456789",   // loose format — foreign B2B customers exist
+  "vat_number": "BG123456789",
+  "metadata": {}
+  // "tags" are admin-only — the server STRIPS them from this body.
+}
+```
+- **Response**: `{customer}` — the refreshed customer (shape above).
+- **Errors**: `401 unauthenticated` · `400 validation_failed`.
+- **SDK**: `customers.updateMe(client, input)`
+- **Components**: account profile form; invoice-details step in checkout.
+- **Settings**: `company_eik`/`vat_number` feed invoice-required checkout
+  (order-documents).
+## GET /api/store/customers/me/addresses — list addresses
+- **Purpose**: the address book. Returns **every** address (created_at asc)
+  — the envelope is nominal: `offset` is always 0 and `limit` equals
+  `count`; no query params are read.
+- **Auth**: Bearer JWT (+ `x-client-id`).
+- **Response**:
+```jsonc
+{
+  "addresses": [
+    {
+      "id": "uuid",
+      "client_id": "uuid",
+      "customer_id": "uuid",
+      "address_name": "Home",
+      "first_name": "Maria",
+      "last_name": "Petrova",
+      "company": null,
+      "address_1": "ul. Ivan Vazov 1",
+      "address_2": null,
+      "city": "Sofia",
+      "country_code": "bg",          // stored lower-case
+      "province": null,
+      "postal_code": "1000",
+      "phone": "+359888123456",
+      "is_default_billing": false,
+      "is_default_shipping": true,
+      "metadata": null,
+      "created_at": "ISO-8601",
+      "updated_at": "ISO-8601",
+      "deleted_at": null
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 1
+}
+```
+- **Errors**: `401 unauthenticated`.
+- **SDK**: `customers.listAddresses(client)`
+- **Components**: address book; checkout address picker.
+## POST /api/store/customers/me/addresses — create address
+- **Purpose**: add to the address book. `is_default_billing` /
+  `is_default_shipping: true` clears the flag on every sibling first (one
+  default per kind).
+- **Auth**: Bearer JWT (+ `x-client-id`).
+- **Request**: all fields optional — same keys as the address shape above
+  (minus id/customer_id/timestamps). `country_code` is lower-cased.
+- **Response**: `{customer}` — the **full refreshed customer** (addresses
+  embedded), NOT the created address alone; find it in
+  `customer.addresses`.
+- **Errors**: `401 unauthenticated` · `400 validation_failed`.
+- **SDK**: `customers.createAddress(client, input)`
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
+  "$BASE/api/store/customers/me/addresses" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"city": "Sofia"}')
+test "$STATUS" = 401
+```
+## GET /api/store/customers/me/addresses/:id — one address
+- **Purpose**: read one owned address (edit-form hydrate).
+- **Auth**: Bearer JWT (+ `x-client-id`).
+- **Response**: `{address}` — ONE address object (the only address
+  endpoint that returns `{address}` instead of `{customer}`).
+- **Errors**: `401 unauthenticated` · `404 not_found` — unknown OR another
+  customer's address; ownership violations 404, they never 403.
+- **SDK**: `customers.getAddress(client, addressId)`
+## POST /api/store/customers/me/addresses/:id — update address
+- **Purpose**: partial update; default flags clear siblings.
+- **Auth**: Bearer JWT (+ `x-client-id`).
+- **Request**: same keys as create, nullable to clear.
+- **Response**: `{customer}` — full refreshed customer.
+- **Errors**: `401 unauthenticated` · `404 not_found` ·
+  `400 validation_failed`.
+- **SDK**: `customers.updateAddress(client, addressId, input)`
+## DELETE /api/store/customers/me/addresses/:id — delete address
+- **Purpose**: soft-delete an owned address.
+- **Auth**: Bearer JWT (+ `x-client-id`).
+- **Response**: `{customer}` — full refreshed customer (address gone).
+- **Errors**: `401 unauthenticated` · `404 not_found`.
+- **SDK**: `customers.deleteAddress(client, addressId)`
+## GET /api/store/customers/me/documents — my documents (invoices)
+- **Purpose**: the account "Invoices" page — the customer's issued
+  (non-void) order documents, `issued_at` desc. Ownership is INNER-join
+  enforced (session customer id AND client_id) — cross-customer reads are
+  impossible (adversarial-tested).
+- **Auth**: Bearer JWT (+ `x-client-id`).
+- **Request**: query `{limit? (≤200, default 20), offset?, doc_type?}`.
+- **Response**:
+```jsonc
+{
+  "documents": [
+    {
+      "id": "uuid",
+      "order_id": "order_…",
+      "order_display_id": 1042,
+      "doc_type": "invoice",
+      "number": "0000000042",
+      "issued_at": "ISO-8601",
+      "pdf_url": "https://…/invoice.pdf",
+      "due_date": null,
+      "paid_at": "ISO-8601"
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 20
+}
+```
+- **Errors**: `401 unauthenticated` · `400 validation_failed`.
+- **SDK**: `customers.listMyDocuments(client, query?)`
+- **Components**: account documents/invoices list.
+- **Settings**: order-documents issuing config (doc types, numbering).
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/customers/me/documents" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 401
+```

package/template/app/docs/deploy.md ADDED Viewed

@@ -0,0 +1,192 @@
+# Deploy & hosting
+Cartbase builds and hosts your storefront. You send the app's source files
+— one snapshot of the whole project — and Cartbase turns it into a
+running site: first on a **permanent preview URL**, then, when you press
+**Publish** (or call the publish endpoint), on the store's live domain.
+You never touch build servers, DNS, or hosting configuration; the platform
+provisions all of it on your first deploy.
+Two URLs exist per store, both created automatically:
+| Surface | URL | What serves there |
+|---|---|---|
+| Preview | `https://preview--{store-slug}.cartbase.net` | The newest deploy, always — the link never changes |
+| Live | `https://{store-slug}.cartbase.net` | The last **published** deploy, and nothing else |
+A failed build never replaces what's live or what's on preview — the
+previous successful deploy keeps serving. Custom domains for the live site
+attach in the admin (Settings → Domains) and don't change anything on this
+page.
+**These are Admin API endpoints** — they operate the store, so they
+authenticate with an admin session (sign-in cookie), not the storefront
+headers the rest of this corpus uses. In practice you'll deploy through
+the admin UI (**Storefront** in the sidebar), the Cartbase CLI, or an
+agent connection — all three are wrappers over exactly these calls.
+Users who belong to several stores name the target store with an
+`x-cartbase-store: <client-id>` header.
+## What a deploy is
+A deploy is a **full snapshot**: the complete file tree of your storefront
+app, uploaded in one request. Snapshot semantics cut both ways — a file
+you stop sending is removed from the deployed site. There is no
+partial-update mode; your working directory is the truth, every time.
+Bundle rules (enforced server-side; a violation fails the whole deploy
+with a readable `400` before anything is built):
+- ≤ 1500 files, ≤ 3 MB per file, ≤ 25 MB total (base64-decoded sizes)
+- `package.json` must exist at the bundle root — the app must be a
+  buildable Next.js project (`next build`)
+- File content travels base64-encoded (`content_base64`), so binary
+  assets — images, fonts — work
+- Never include: `node_modules/` (dependencies install at build time),
+  `.next/` (build output is generated), `.git/`, any `.env*` file
+- Not allowed in storefront bundles: `middleware.*`, `app/api/` or
+  `pages/api/` routes, `vercel.json` — a storefront is pages plus the
+  `@cartbase/storefront` package; server seams and hosting config are
+  platform territory. The CORS proxy from the runbook is a
+  `next.config` rewrite, which is fine.
+Error codes you can hit: `empty_bundle`, `bundle_too_large`,
+`invalid_bundle_file`, `invalid_path`, `blocked_path`, `duplicate_path`,
+`invalid_encoding`, `file_too_large`, `missing_package_json`.
+## Environment — provided, not configured
+Hosted storefronts receive the three runbook inputs automatically at
+build time; do **not** put them in the bundle (`.env*` files are blocked
+anyway):
+| Variable | Value |
+|---|---|
+| `NEXT_PUBLIC_CARTBASE_URL` | The store's API origin |
+| `NEXT_PUBLIC_CARTBASE_CLIENT_ID` | The store's client id |
+| `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY` | The store's publishable key, when one exists |
+Only these public values ever reach a storefront build — secret keys are
+never injected, so code that expects one is a design error.
+## Deploy to preview
+`POST /api/admin/storefront/deploys` — the one ingestion door. The first
+call on a store also provisions its hosting (takes a few extra seconds);
+every later call is just a deploy.
+```bash
+# doc-noexec — admin-session auth; run from an authenticated context.
+curl -s -X POST "$BASE/api/admin/storefront/deploys" \
+  -H "content-type: application/json" \
+  -d '{
+    "files": [
+      { "path": "package.json",  "content_base64": "<base64>" },
+      { "path": "app/layout.js", "content_base64": "<base64>" },
+      { "path": "app/page.js",   "content_base64": "<base64>" }
+    ],
+    "message": "homepage copy update"
+  }'
+```
+Response `201`:
+```json
+{
+  "deploy": {
+    "id": "sfd_01J…",
+    "target": "preview",
+    "status": "building",
+    "url": "https://preview--my-store.cartbase.net",
+    "message": "homepage copy update",
+    "file_count": 3,
+    "created_at": "2026-08-03T22:41:00.000Z"
+  }
+}
+```
+`message` (≤ 500 chars) is your label in the deploy history — write what
+changed. `source` (`api` | `cli` | `mcp` | `admin` | `agent`) tags where
+the deploy came from; omit it unless you're building tooling.
+Statuses move `queued → building → ready` (or `failed` / `canceled`).
+Poll the overview endpoint until the deploy you created is `ready`, then
+open the preview URL. Builds of a small app land in roughly a minute;
+`failed` rows carry a readable `error_message`.
+## Overview — hosting status + deploy history
+`GET /api/admin/storefront` returns the hosting record and the deploy
+ledger, newest first:
+```bash
+# doc-noexec — admin-session auth.
+curl -s "$BASE/api/admin/storefront"
+```
+```json
+{
+  "storefront": {
+    "id": "sfp_01J…",
+    "status": "ready",
+    "production_url": "https://my-store.cartbase.net",
+    "preview_url": "https://preview--my-store.cartbase.net",
+    "last_error": null,
+    "created_at": "…"
+  },
+  "deploys": [
+    {
+      "id": "sfd_01J…",
+      "target": "preview",
+      "status": "ready",
+      "message": "homepage copy update",
+      "url": "https://preview--my-store.cartbase.net",
+      "source": "cli",
+      "file_count": 3,
+      "total_bytes": 1930,
+      "error_message": null,
+      "promoted_deploy_id": null,
+      "created_at": "…",
+      "updated_at": "…"
+    }
+  ]
+}
+```
+`storefront` is `null` until the store's first deploy. `status:
+"provisioning"` / `"failed"` (with `last_error`) describe hosting setup,
+not builds; a failed provisioning resumes automatically on the next
+deploy attempt.
+## Publish — and rollback
+`POST /api/admin/storefront/publish` promotes a **ready preview deploy**
+to the live domain. This is the only path to production — nothing
+deploys straight to live, no matter who's asking.
+```bash
+# doc-noexec — admin-session auth.
+# Bare POST publishes the newest ready preview:
+curl -s -X POST "$BASE/api/admin/storefront/publish"
+# Naming an older deploy id IS the rollback mechanism:
+curl -s -X POST "$BASE/api/admin/storefront/publish" \
+  -H "content-type: application/json" \
+  -d '{ "deploy_id": "sfd_01H…older…" }'
+```
+Response `201` is a new ledger row with `target: "production"` and
+`promoted_deploy_id` pointing at the preview it promoted. Publishing is
+near-instant — the snapshot was already built; the live domain switches
+to it without a rebuild.
+Rollback is not a separate feature: publish any earlier `ready` deploy
+from the history and the live site is that snapshot again. Roll forward
+the same way.
+## Workflow summary
+1. Build locally against your store (the [runbook](BUILD-A-STOREFRONT.md)).
+2. Deploy → check the permanent preview URL.
+3. Iterate — every deploy replaces preview, live is untouched.
+4. Publish when it's right; the deploy history is your undo button.