create-cartbase 0.1.6 → 0.1.7

package/template/app/docs/variables.md

@@ -58,7 +58,7 @@ Every customer notification carries it. Money is formatted in the order's own cu
 | `{{ order.email }}` | The address the order was placed with. | email |  |
 | `{{ order.date }}` | When the order was placed. | date |  |
 | `{{ order.status }}` | Lifecycle state: pending, completed, canceled or archived. | text |  |
-| `{{ order.payment_status }}` | Paid, Awaiting payment, Refunded and so on, in the same words the admin uses. | text |  |
+| `{{ order.payment_status }}` | Paid, Unpaid, Partially paid, Refunded and so on, in the same words the admin uses. | text |  |
 | `{{ order.fulfillment_status }}` | Unfulfilled, Shipped, Delivered and so on, in the same words the admin uses. | text |  |
 | `{{ order.locale }}` | Language the customer shopped in, when the storefront sends one. | text |  |
 | `{{ order.cancelled_at }}` | When the order was cancelled, if it was. | datetime |  |
@@ -70,7 +70,7 @@ Every customer notification carries it. Money is formatted in the order's own cu
 | `{{ order.shipping }}` | What delivery cost the customer. | money |  |
 | `{{ order.discount }}` | Total discount applied to the order. | money |  |
 | `{{ order.payment_method_fee }}` | The fee of the payment method the customer chose (a COD courier fee, a handling fee on a manual method). | money |  |
-| `{{ order.paid }}` | How much has actually been captured so far. | money |  |
+| `{{ order.paid }}` | How much has actually been received so far. | money |  |
 | `{{ order.refunded }}` | How much has been refunded. | money |  |
 | `{{ order.balance_due }}` | What is still outstanding on the order. | money |  |
 
@@ -271,7 +271,7 @@ Staff operational alerts only.
 | Order Shipped | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
 | Order Delivered | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
 | Order Refunded | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
-| Order Cancelled | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Order Canceled | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
 | Admin: New Order | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
 | Welcome Email | Customer, Store, Brand |
 | Password Reset | Customer, Store, Brand |

package/template/app/next.config.ts

@@ -1,31 +1,27 @@
-import path from "node:path"
 import type { NextConfig } from "next"
 
 const nextConfig: NextConfig = {
-  // Monorepo: pin the workspace root (Next otherwise infers it from a
-  // stray lockfile OUTSIDE the repo and mis-roots the dev module graph).
-  outputFileTracingRoot: path.join(__dirname, "../.."),
-  // The smoke driver browses via 127.0.0.1; allow dev-resource access.
-  allowedDevOrigins: ["127.0.0.1"],
-  // @cartbase/storefront is source-shipped TypeScript (workspace package) —
-  // the app's Next build transpiles it.
+  // @cartbase/storefront is source-shipped TypeScript — the app's Next
+  // build transpiles it.
   transpilePackages: ["@cartbase/storefront"],
   images: {
-    // Reference app: seeded product images live on arbitrary demo hosts.
-    // A real store should allowlist its media domain via remotePatterns.
+    // Product images come from the Cartbase media CDN and, until you
+    // allowlist your own hosts under remotePatterns, from anywhere the
+    // catalog points. Tighten this when the media domain is known.
     unoptimized: true,
   },
   // The Cartbase store API ships NO CORS headers — browser-side SDK calls
   // must be same-origin. Proxy them through the app origin (the browser
   // client's baseUrl is window.location.origin); server-side SDK calls go
-  // straight to NEXT_PUBLIC_CARTBASE_URL and are unaffected.
+  // straight to the platform origin and are unaffected. The origin is the
+  // platform's constant; NEXT_PUBLIC_CARTBASE_URL only overrides it for a
+  // local or staging platform.
   async rewrites() {
-    const barterUrl = process.env.NEXT_PUBLIC_CARTBASE_URL
-    if (!barterUrl) return []
+    const cartbaseUrl = process.env.NEXT_PUBLIC_CARTBASE_URL || "https://admin.cartbase.ai"
     return [
       {
         source: "/api/store/:path*",
-        destination: `${barterUrl}/api/store/:path*`,
+        destination: `${cartbaseUrl}/api/store/:path*`,
       },
     ]
   },

package/template/app/package.json

@@ -2,13 +2,14 @@
   "name": "cartbase-storefront",
   "version": "0.1.0",
   "private": true,
-  "description": "Reference storefront built from docs/storefront/BUILD-A-STOREFRONT.md alone — the adoption proof for @cartbase/storefront.",
   "scripts": {
-    "dev": "next dev --webpack -p 4778",
+    "build": "next build",
+    "start": "next start",
+    "dev": "next dev",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cartbase/storefront": "^0.7.0",
+    "@cartbase/storefront": "^0.8.0",
     "next": "16.2.4",
     "react": "19.2.4",
     "react-dom": "19.2.4"

package/template/app/src/app/checkout/checkout-page-client.tsx

@@ -7,7 +7,6 @@ import type { StorePaymentEntry } from "@cartbase/storefront/api/checkout"
 import { CheckoutProvider } from "@cartbase/storefront/checkout/context"
 import { CheckoutClient } from "@cartbase/storefront/checkout/checkout-client"
 import { browserClient } from "@/lib/browser-client"
-import { MyposDemoTab } from "./mypos-demo-tab"
 
 /** sessionStorage key the confirmation page reads (guests have no order
  * read endpoint — the completeCart() response is the only order handle,
@@ -42,25 +41,6 @@ export function CheckoutPageClient({
         paymentMethodFilter={(methods) =>
           methods?.filter((m) => "payment_method_id" in m) ?? null
         }
-        // Provider-research demo (2026-08-04): the myPOS sandbox as a third
-        // radio card, so the embedded-provider seam can be judged inside
-        // the real checkout. Off unless NEXT_PUBLIC_MYPOS_DEMO=1.
-        extraPaymentTabs={
-          process.env.NEXT_PUBLIC_MYPOS_DEMO === "1"
-            ? [
-                {
-                  id: "mypos-demo",
-                  label: "Card via myPOS (demo)",
-                  content: (
-                    <MyposDemoTab
-                      amount={Number(cart.total) || 23.45}
-                      currency={cart.currency_code}
-                    />
-                  ),
-                },
-              ]
-            : undefined
-        }
         onOrderPlaced={(order) => {
           // Guest order handle = the completeCart() response (orders.md).
           // Stash it (+ the decorated cart lines for the items list) for

package/template/app/src/app/globals.css

@@ -17,7 +17,7 @@
  * to scan it to know which classes exist. Without this the components render
  * with no styles at all — the classes are in the markup but never generated.
  */
-@source "../../../../packages/storefront/src";
+@source "../../node_modules/@cartbase/storefront/src";
 
 /*
  * Dark mode is class-based: put `.dark` on <html> and every token swaps.

package/template/app/src/app/layout.tsx

@@ -17,10 +17,56 @@ import "./globals.css"
 // createStorefrontMetadata (platform-fingerprints card) stamps
 // `<meta name="generator" content="Cartbase" />` on every page — never
 // hand-write `generator` here.
-export const metadata: Metadata = createStorefrontMetadata({
-  title: "Barter Example Store",
-  description: "Reference storefront built on @cartbase/storefront",
-})
+export async function generateMetadata(): Promise<Metadata> {
+  const store = await fetchStore()
+  return createStorefrontMetadata({
+    title: store.name,
+    description: store.brand.slogan ?? undefined,
+  })
+}
+
+/**
+ * The store's own identity (store.md): name, slug, brand. Read once per
+ * request; a storefront never hardcodes its name. Until @cartbase/storefront
+ * 0.8.0 ships `api/store`, the call goes through the client's low-level
+ * request with the documented shape.
+ */
+type StoreIdentity = {
+  /** The store's public id: what PlatformInit mounts (one key: never an env input). */
+  id: string
+  name: string
+  slug: string
+  brand: {
+    logo_url: string | null
+    logo_square_url: string | null
+    color_primary: string | null
+    color_secondary: string | null
+    slogan: string | null
+  }
+}
+
+async function fetchStore(): Promise<StoreIdentity> {
+  const client = await getServerClient()
+  try {
+    const { store } = await client.request<{ store: StoreIdentity }>("/api/store/store")
+    return store
+  } catch {
+    // Never crash the layout on a transient API error; the name is
+    // decoration, the store still renders.
+    return {
+      id: BARTER_CLIENT_ID ?? "",
+      name: "Store",
+      slug: "",
+      brand: {
+        logo_url: null,
+        logo_square_url: null,
+        color_primary: null,
+        color_secondary: null,
+        slogan: null,
+      },
+    }
+  }
+}
 
 /**
  * Runbook steps 3–4: bootstrap store config at layout level, then mount
@@ -67,7 +113,8 @@ export default async function RootLayout({
   // the rename (platform-fingerprints card).
   const cartId = readCartCookie((name) => jar.get(name)?.value) ?? null
 
-  const [consentRes, mainMenu, footerMenu, cart] = await Promise.all([
+  const [store, consentRes, mainMenu, footerMenu, cart] = await Promise.all([
+    fetchStore(),
     getConsent(client),
     fetchMenu("main-menu"),
     fetchMenu("footer"),
@@ -94,12 +141,12 @@ export default async function RootLayout({
             wbraid) that exist ONLY on an ad's landing URL — miss them
             here and no platform can attribute the order to the click. */}
         <TrackInit />
-        <PlatformInit storeId={BARTER_CLIENT_ID} />
+        <PlatformInit storeId={store.id} />
         <Providers cart={cart} consent={consentRes.consent}>
           <header className="border-b border-border">
             <div className="max-w-7xl mx-auto px-4 h-16 flex items-center justify-between gap-6">
               <Link href="/" className="font-semibold text-lg">
-                Barter Example Store
+                {store.name}
               </Link>
               <div className="flex items-center gap-6">
                 <MenuNav menu={mainMenu} />
@@ -110,17 +157,11 @@ export default async function RootLayout({
                   Search
                 </Link>
                 {/*
-                  The workbench, reachable from the shop rather than by
-                  knowing the URL. This app is the reference store AND the
-                  place the library gets designed; the link is what makes the
-                  second half discoverable.
+                  The component workbench lives at /gallery in THIS app only
+                  (the seed excludes it, src/lib/storefront/seed.ts), so the
+                  shop's own nav never links to it: a merchant's store must
+                  not carry a dead link.
                 */}
-                <Link
-                  href="/gallery"
-                  className="text-sm text-muted-foreground hover:text-foreground"
-                >
-                  Library
-                </Link>
                 <CartButtonClient cart={cart} />
               </div>
             </div>
@@ -128,7 +169,7 @@ export default async function RootLayout({
           <main>{children}</main>
           <footer className="border-t border-border mt-12">
             <div className="max-w-7xl mx-auto px-4 py-8 text-sm text-muted-foreground flex items-center justify-between">
-              <span>Barter Example Store</span>
+              <span>{store.name}</span>
               <MenuNav menu={footerMenu} />
             </div>
           </footer>

package/template/app/src/lib/config.ts

@@ -1,21 +1,30 @@
-/** Shared storefront configuration (BUILD-A-STOREFRONT.md — inputs table). */
-
-export const BARTER_URL = process.env.NEXT_PUBLIC_CARTBASE_URL ?? ""
-export const BARTER_CLIENT_ID = process.env.NEXT_PUBLIC_CARTBASE_CLIENT_ID ?? ""
-export const BARTER_PUBLISHABLE_KEY =
-  process.env.NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY || undefined
-
-/**
- * Cart-id cookie — owned by the app (the SDK never persists the cart);
- * the NAME is owned by the library so every consumer emits the same wire
- * fingerprint (platform-fingerprints card). `readCartCookie` is the
- * backward-compat reader for the legacy `_barter_cart_id` name.
- */
-export { CART_COOKIE, readCartCookie } from "@cartbase/storefront/lib/cookie-names"
-export const CART_COOKIE_MAX_AGE = 60 * 60 * 24 * 30 // 30 days
-
-/** Locale cookie read by the clients' `getLocale`. */
-export const LOCALE_COOKIE = "_barter_locale"
-
-/** Pricing context for every catalog surface (runbook step 5). EUR only. */
-export const PRICING_CONTEXT = { currency_code: "eur" } as const
+/** Shared storefront configuration (BUILD-A-STOREFRONT.md — the one input). */
+
+import { cartbaseApiOrigin } from "@cartbase/storefront/lib/platform"
+
+/**
+ * The store's publishable key names the store and scopes its catalog: the
+ * ONE value a storefront needs (one key, 2026-09-07). The origin is the
+ * platform's, overridable for a local or staging platform; the client id is
+ * the platform's own door (hosted builds carry it) and never something to
+ * copy by hand.
+ */
+export const BARTER_PUBLISHABLE_KEY =
+  process.env.NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY || undefined
+export const BARTER_URL = cartbaseApiOrigin(process.env.NEXT_PUBLIC_CARTBASE_URL)
+export const BARTER_CLIENT_ID = process.env.NEXT_PUBLIC_CARTBASE_CLIENT_ID || undefined
+
+/**
+ * Cart-id cookie — owned by the app (the SDK never persists the cart);
+ * the NAME is owned by the library so every consumer emits the same wire
+ * fingerprint (platform-fingerprints card). `readCartCookie` is the
+ * backward-compat reader for the legacy `_barter_cart_id` name.
+ */
+export { CART_COOKIE, readCartCookie } from "@cartbase/storefront/lib/cookie-names"
+export const CART_COOKIE_MAX_AGE = 60 * 60 * 24 * 30 // 30 days
+
+/** Locale cookie read by the clients' `getLocale`. */
+export const LOCALE_COOKIE = "_barter_locale"
+
+/** Pricing context for every catalog surface (runbook step 5). EUR only. */
+export const PRICING_CONTEXT = { currency_code: "eur" } as const

package/template/app/next-env.d.ts

@@ -1,6 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/template/app/smoke.mjs

@@ -1,158 +0,0 @@
-/**
- * Adoption-proof smoke: drives the REAL example-storefront UI from home to
- * a completed pp_manual checkout against the barter backend.
- *
- * Prereqs: backend on :4777, example app on :4778 (see examples/storefront
- * package.json). Run: `node examples/storefront/smoke.mjs` from the repo
- * root (Playwright is a root devDependency). Exits 0 only when the
- * confirmation page shows an order number and totals.
- */
-import { chromium } from "@playwright/test"
-
-const BASE = process.env.SMOKE_BASE_URL ?? "http://127.0.0.1:4778"
-const trail = []
-const step = (msg) => {
-  trail.push(msg)
-  console.log(`[smoke] ${msg}`)
-}
-
-const browser = await chromium.launch()
-const page = await browser.newPage()
-page.setDefaultTimeout(30_000)
-
-try {
-  // ── Home ────────────────────────────────────────────────────────────
-  await page.goto(`${BASE}/`, { waitUntil: "domcontentloaded" })
-  step("home loaded")
-
-  // Consent banner (builtin modal is the server default) — accept.
-  const acceptButton = page.getByRole("button", { name: "Accept", exact: true })
-  try {
-    await acceptButton.waitFor({ state: "visible", timeout: 10_000 })
-    await acceptButton.click()
-    step("consent banner accepted")
-  } catch {
-    step("no consent banner rendered (disabled or external mode)")
-  }
-
-  await page.locator('a[href^="/products/"]').first().waitFor()
-  step("home renders product cards")
-
-  // ── PDP (seeded handle) ─────────────────────────────────────────────
-  await page.goto(`${BASE}/products/linen-shirt`, {
-    waitUntil: "domcontentloaded",
-  })
-  await page.getByTestId("product-container").waitFor()
-  step("PDP linen-shirt rendered")
-
-  // Pick the REAL Size option's "M" (the shared dev tenant accretes junk
-  // options; variant match needs exactly the Size choice). Dev-mode
-  // hydration can lag the SSR paint — retry until the selection sticks.
-  const sizeRow = page
-    .locator('div.flex.flex-col:has(> span:text-is("Select Size"))')
-    .first()
-  const mButton = sizeRow.getByRole("button", { name: "M", exact: true })
-  let selected = false
-  for (let i = 0; i < 30 && !selected; i++) {
-    await mButton.click()
-    await page.waitForTimeout(700)
-    selected = ((await mButton.getAttribute("class")) ?? "").includes(
-      "border-primary"
-    )
-  }
-  if (!selected) throw new Error("Size M never became selected")
-  step("selected Size M")
-
-  const addButton = page.getByTestId("add-product-button").first()
-  await addButton.click()
-  step("clicked Add to cart")
-
-  // ── Cart drawer → checkout ──────────────────────────────────────────
-  // The drawer auto-opens only on a rise from a nonzero base (first add
-  // never auto-opens — components.md); open it via the header cart
-  // button once the badge confirms the server-side add landed.
-  await page
-    .getByTestId("nav-cart-link")
-    .locator("span")
-    .filter({ hasText: /^\d+$/ })
-    .waitFor({ timeout: 20_000 })
-  step("header cart badge shows the added item")
-  await page.getByTestId("nav-cart-link").click()
-  const checkoutLink = page.getByRole("link", { name: "Checkout" })
-  await checkoutLink.click()
-  step("cart drawer opened via header cart button")
-  await page.waitForURL("**/checkout")
-  step("navigated to /checkout")
-
-  // ── Address form ────────────────────────────────────────────────────
-  const fill = async (name, value) => {
-    await page.locator(`[name="${name}"]`).fill(value)
-  }
-  await fill("email", "smoke-adoption@example.test")
-  await fill("shipping_address.first_name", "Ivan")
-  await fill("shipping_address.last_name", "Petrov")
-  await fill("shipping_address.address_1", "ul. Vitosha 15")
-  await fill("shipping_address.postal_code", "1000")
-  await fill("shipping_address.city", "Sofia")
-  await fill("shipping_address.phone", "+359888123456")
-  await page.locator('[name="shipping_address.phone"]').blur()
-  step("address form filled (BG address, EUR cart)")
-
-  // ── Shipping method ─────────────────────────────────────────────────
-  await page.getByText("Flat Rate (Bulgaria)", { exact: false }).first().click()
-  step('selected shipping "Flat Rate (Bulgaria)"')
-
-  // ── Payment: manual/offline tab (no Stripe env) ─────────────────────
-  const codTab = page.getByRole("button", { name: "Cash on delivery" })
-  await codTab.waitFor({ state: "visible" })
-  await codTab.click()
-  step("selected the merchant method (offline tab)")
-
-  // ── Place order ─────────────────────────────────────────────────────
-  const submit = page.getByTestId("submit-order-button")
-  await submit.waitFor({ state: "visible" })
-  // The Buy button enables once the debounced address autosave lands.
-  await page.waitForFunction(
-    () =>
-      !document.querySelector('[data-testid="submit-order-button"]')?.disabled,
-    undefined,
-    { timeout: 20_000 }
-  )
-  await submit.click()
-  step("clicked Place order")
-
-  // ── Confirmation ────────────────────────────────────────────────────
-  await page.waitForURL("**/order/**/confirmed", { timeout: 60_000 })
-  step(`confirmation URL: ${new URL(page.url()).pathname}`)
-
-  const orderNumberText = await page
-    .getByText(/#\d+/)
-    .first()
-    .innerText({ timeout: 30_000 })
-  const displayNumber = orderNumberText.match(/#(\d+)/)?.[1]
-  if (!displayNumber) throw new Error("no order display number rendered")
-  step(`order number rendered: #${displayNumber}`)
-
-  // Totals: the order family renders a Total row with a EUR amount.
-  const totalRow = page
-    .locator("div,li")
-    .filter({ hasText: /^Total/ })
-    .filter({ hasText: "€" })
-    .first()
-  const totalText = (await totalRow.innerText()).replace(/\s+/g, " ").trim()
-  if (!/€\s?\d/.test(totalText)) throw new Error("no EUR total rendered")
-  step(`totals rendered: ${totalText}`)
-
-  console.log("\n[smoke] PASS — completed checkout, order #" + displayNumber)
-  await browser.close()
-  process.exit(0)
-} catch (err) {
-  console.error("\n[smoke] FAIL after steps:\n - " + trail.join("\n - "))
-  console.error(err)
-  try {
-    await page.screenshot({ path: "examples/storefront/smoke-failure.png" })
-    console.error("[smoke] screenshot: examples/storefront/smoke-failure.png")
-  } catch {}
-  await browser.close()
-  process.exit(1)
-}

package/template/app/src/app/checkout/mypos-demo-tab.tsx

@@ -1,101 +0,0 @@
-"use client"
-
-import { useEffect, useRef, useState } from "react"
-
-/**
- * DEMO ONLY (2026-08-04, provider research): mounts the myPOS Embedded
- * sandbox (their public docs demo store) inside the real checkout's
- * payment section, so the visual seam of a third-party embedded provider
- * can be judged against our own tabs. Enabled by
- * NEXT_PUBLIC_MYPOS_DEMO=1; never ship this to a real store.
- */
-
-const SDK_SRC = "https://developers.mypos.com/repository/mypos-embedded-sdk.js"
-const CONTAINER_ID = "mypos-demo-container"
-
-declare global {
-  interface Window {
-    MyPOSEmbedded?: {
-      createPayment: (
-        containerId: string,
-        params: Record<string, unknown>,
-        callbacks: Record<string, unknown>
-      ) => void
-    }
-  }
-}
-
-export function MyposDemoTab({ amount, currency }: { amount: number; currency: string }) {
-  const mounted = useRef(false)
-  const [error, setError] = useState<string | null>(null)
-
-  useEffect(() => {
-    if (mounted.current) return
-    mounted.current = true
-
-    const mount = () => {
-      const sdk = window.MyPOSEmbedded
-      if (!sdk || typeof sdk.createPayment !== "function") {
-        setError("myPOS SDK loaded but its global was not found (check the console).")
-        return
-      }
-      sdk.createPayment(
-        CONTAINER_ID,
-        {
-          // Public sandbox store from the myPOS docs sample.
-          sid: "000000000000010",
-          ipcLanguage: "en",
-          walletNumber: "61938166610",
-          amount,
-          currency: currency.toUpperCase(),
-          orderID: `demo_${Math.random().toString(36).slice(2, 11)}`,
-          urlNotify: "https://example.com/payment-notify",
-          urlOk: window.location.href,
-          urlCancel: window.location.href,
-          keyIndex: 1,
-          cartItems: [{ article: "Cartbase demo order", quantity: 1, price: amount, currency: currency.toUpperCase() }],
-        },
-        {
-          isSandbox: true,
-          onSuccess: (data: unknown) => {
-            // Real integration: this is where complete-cart would run,
-            // AFTER server-side verification via urlNotify.
-            // eslint-disable-next-line no-console
-            console.log("[mypos-demo] sandbox success", data)
-            window.alert("myPOS sandbox reported success (demo only, no order is placed).")
-          },
-          onError: () => {
-            // eslint-disable-next-line no-console
-            console.log("[mypos-demo] sandbox payment failed")
-          },
-        }
-      )
-    }
-
-    const existing = document.querySelector(`script[src="${SDK_SRC}"]`)
-    if (existing && window.MyPOSEmbedded) {
-      mount()
-      return
-    }
-    const script = document.createElement("script")
-    script.src = SDK_SRC
-    script.async = true
-    script.onload = mount
-    script.onerror = () => setError("Could not load the myPOS SDK script.")
-    document.head.appendChild(script)
-  }, [amount, currency])
-
-  return (
-    <div>
-      {error ? (
-        <p className="text-sm text-red-600">{error}</p>
-      ) : (
-        <div id={CONTAINER_ID} className="min-h-[620px]" />
-      )}
-      <p className="mt-2 text-xs text-muted-foreground">
-        myPOS sandbox demo. The frame above is myPOS's embedded form with its
-        own pay button; everything around it is the Cartbase checkout.
-      </p>
-    </div>
-  )
-}