create-cartbase 0.0.1 → 0.1.1

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

@@ -0,0 +1,51 @@
+import { cookies } from "next/headers"
+import { redirect } from "next/navigation"
+import { retrieveCart } from "@cartbase/storefront/api/carts"
+import {
+  listPaymentProviders,
+  listShippingOptions,
+} from "@cartbase/storefront/api/checkout"
+import { getIntegrationsConfig } from "@cartbase/storefront/api/integrations"
+import { readCartCookie } from "@/lib/config"
+import { getServerClient } from "@/lib/server-client"
+import { CheckoutPageClient } from "./checkout-page-client"
+
+/**
+ * Checkout (runbook step 8 / checkout.md): list shipping options and
+ * payment providers WITH `cart_id` (server-side rule filtering), fetch the
+ * integrations `cod` block, and hand everything to the orchestrated
+ * client layout. Redirect completed/missing carts server-side
+ * (checkout-client mount rule).
+ */
+export default async function CheckoutPage() {
+  const jar = await cookies()
+  // Back-compat: prefer `_cartbase_cart`, fall back to the legacy
+  // `_barter_cart_id` name (platform-fingerprints card).
+  const cartId = readCartCookie((name) => jar.get(name)?.value)
+  if (!cartId) redirect("/")
+
+  const client = await getServerClient()
+  const cart = await retrieveCart(client, cartId)
+    .then((res) => res.cart)
+    .catch(() => null)
+  if (!cart || (cart.items ?? []).length === 0) redirect("/")
+  if (cart.completed_at) redirect("/")
+
+  const [shippingOptions, paymentProviders, integrations] = await Promise.all([
+    listShippingOptions(client, { cart_id: cart.id }),
+    listPaymentProviders(client, {
+      cart_id: cart.id,
+      region_id: cart.region_id ?? undefined,
+    }),
+    getIntegrationsConfig(client),
+  ])
+
+  return (
+    <CheckoutPageClient
+      cart={cart}
+      shippingOptions={shippingOptions.shipping_options}
+      paymentProviders={paymentProviders.payment_providers}
+      codConfig={integrations.cod}
+    />
+  )
+}

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

@@ -0,0 +1,42 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/*
+ * Storefront theme tokens — shadcn-standard names, raw oklch channels
+ * (the @cartbase/storefront tailwind-preset wraps them in oklch(...)).
+ * Neutral light theme for the reference app.
+ */
+:root {
+  --background: 1 0 0;
+  --foreground: 0.145 0 0;
+  --card: 1 0 0;
+  --card-foreground: 0.145 0 0;
+  --popover: 1 0 0;
+  --popover-foreground: 0.145 0 0;
+  --primary: 0.205 0 0;
+  --primary-foreground: 0.985 0 0;
+  --secondary: 0.97 0 0;
+  --secondary-foreground: 0.205 0 0;
+  --muted: 0.97 0 0;
+  --muted-foreground: 0.556 0 0;
+  --accent: 0.97 0 0;
+  --accent-foreground: 0.205 0 0;
+  --destructive: 0.577 0.245 27.325;
+  --destructive-foreground: 0.985 0 0;
+  --border: 0.922 0 0;
+  --input: 0.922 0 0;
+  --ring: 0.708 0 0;
+  --success: 0.648 0.15 160;
+  --success-foreground: 0.985 0 0;
+  --warning: 0.828 0.189 84.429;
+  --warning-foreground: 0.279 0.077 45.635;
+  --radius: 0.5rem;
+  --font-display: ui-serif;
+  --font-body: system-ui;
+  --font-mono: ui-monospace;
+}
+
+body {
+  @apply bg-background text-foreground font-body;
+}

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

@@ -0,0 +1,113 @@
+import type { Metadata } from "next"
+import Link from "next/link"
+import { cookies } from "next/headers"
+import { retrieveCart, type Cart } from "@cartbase/storefront/api/carts"
+import { getConsent } from "@cartbase/storefront/api/consent"
+import { getMenu, type Menu } from "@cartbase/storefront/api/menus"
+import { ConsentInit } from "@cartbase/storefront/tracking/consent-init"
+import { CartButtonClient } from "@cartbase/storefront/common/cart-button-client"
+import { createStorefrontMetadata, PlatformInit } from "@cartbase/storefront/platform"
+import { BARTER_CLIENT_ID, readCartCookie } from "@/lib/config"
+import { getServerClient } from "@/lib/server-client"
+import { Providers } from "./providers"
+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",
+})
+
+/**
+ * Runbook steps 3–4: bootstrap store config at layout level, then mount
+ * order inside <body>: ConsentInit FIRST (static, synchronous), then the
+ * consent-gated UI, then navigation. A store with no menus 404s every
+ * handle — render no nav, never crash (menus.md).
+ */
+async function fetchMenu(handle: string): Promise<Menu | null> {
+  const client = await getServerClient()
+  try {
+    const { menu } = await getMenu(client, handle)
+    return menu
+  } catch {
+    return null // unknown/deleted handle (404) → graceful "no nav"
+  }
+}
+
+function MenuNav({ menu }: { menu: Menu | null }) {
+  if (!menu || menu.items.length === 0) return null
+  return (
+    <nav className="flex items-center gap-4">
+      {menu.items.map((item) => (
+        <Link
+          key={`${item.title}-${item.url}`}
+          href={item.url}
+          className="text-sm text-muted-foreground hover:text-foreground"
+        >
+          {item.title}
+        </Link>
+      ))}
+    </nav>
+  )
+}
+
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const client = await getServerClient()
+  const jar = await cookies()
+  // Back-compat: prefer the new `_cartbase_cart` cookie, fall back to the
+  // legacy `_barter_cart_id` name so an existing visitor's cart survives
+  // the rename (platform-fingerprints card).
+  const cartId = readCartCookie((name) => jar.get(name)?.value) ?? null
+
+  const [consentRes, mainMenu, footerMenu, cart] = await Promise.all([
+    getConsent(client),
+    fetchMenu("main-menu"),
+    fetchMenu("footer"),
+    cartId
+      ? retrieveCart(client, cartId)
+          .then((res): Cart | null => res.cart)
+          .catch(() => null) // stale cookie → empty cart state
+      : Promise.resolve(null),
+  ])
+
+  return (
+    <html lang="en">
+      <body>
+        <ConsentInit />
+        <PlatformInit storeId={BARTER_CLIENT_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
+              </Link>
+              <div className="flex items-center gap-6">
+                <MenuNav menu={mainMenu} />
+                <Link
+                  href="/search"
+                  className="text-sm text-muted-foreground hover:text-foreground"
+                >
+                  Search
+                </Link>
+                <CartButtonClient cart={cart} />
+              </div>
+            </div>
+          </header>
+          <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>
+              <MenuNav menu={footerMenu} />
+            </div>
+          </footer>
+        </Providers>
+      </body>
+    </html>
+  )
+}

package/template/app/src/app/order/[id]/confirmed/page.tsx

@@ -0,0 +1,77 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import Link from "next/link"
+import type { CompletedOrder, CartLineItem } from "@cartbase/storefront/api/carts"
+import {
+  OrderCompletedTemplate,
+} from "@cartbase/storefront/order/order-completed-template"
+import {
+  displayItemFromCartLine,
+} from "@cartbase/storefront/order/order-item"
+import {
+  orderTotalsFromSummary,
+} from "@cartbase/storefront/order/order-totals"
+import { LAST_ORDER_STORAGE_KEY } from "../../../checkout/checkout-page-client"
+
+/**
+ * Order confirmation (runbook step 8.6 + orders.md): guests have NO
+ * anonymous order read — the `completeCart()` response is the only order
+ * handle, so the checkout page stashes it in sessionStorage and this page
+ * renders it through the order family. Totals come from the order's
+ * summary snapshot (`orderTotalsFromSummary`); items keep the decorated
+ * cart lines' server-computed totals (`displayItemFromCartLine`).
+ */
+type Stash = { order: CompletedOrder; cartItems: CartLineItem[] }
+
+export default function OrderConfirmedPage() {
+  const [stash, setStash] = useState<Stash | null | "missing">(null)
+
+  useEffect(() => {
+    try {
+      const raw = sessionStorage.getItem(LAST_ORDER_STORAGE_KEY)
+      setStash(raw ? (JSON.parse(raw) as Stash) : "missing")
+    } catch {
+      setStash("missing")
+    }
+  }, [])
+
+  if (stash === null) return null // first paint before sessionStorage read
+
+  if (stash === "missing") {
+    return (
+      <div className="max-w-xl mx-auto px-4 py-16 text-center">
+        <h1 className="text-xl font-semibold mb-2">Order placed</h1>
+        <p className="text-muted-foreground mb-6">
+          Your order was placed successfully. A confirmation email is on its
+          way.
+        </p>
+        <Link href="/" className="underline">
+          Continue shopping
+        </Link>
+      </div>
+    )
+  }
+
+  const { order, cartItems } = stash
+  const totals = orderTotalsFromSummary(order.summary) ?? {
+    total: null,
+  }
+  // The completeCart() order carries FLATTENED items (checkout.md), not the
+  // order-detail pivot shape the template's default converter expects —
+  // pass the normalized cart-line items instead and drop `order.items`.
+  const orderForTemplate = { ...order, items: undefined }
+
+  return (
+    <OrderCompletedTemplate
+      order={orderForTemplate}
+      totals={totals}
+      items={cartItems.map(displayItemFromCartLine)}
+      // This reference store enables exactly one provider (pp_manual); a
+      // multi-provider store should stash the chosen provider id from its
+      // checkout state alongside the order.
+      paymentProviderId={"pp_manual"}
+      storeHref="/"
+    />
+  )
+}

package/template/app/src/app/page.tsx

@@ -0,0 +1,25 @@
+import { StoreTemplate } from "@cartbase/storefront/store/store-template"
+import type { SortOptions } from "@cartbase/storefront/lib/sort-products"
+import { PRICING_CONTEXT } from "@/lib/config"
+import { getServerClient } from "@/lib/server-client"
+
+/**
+ * Home = the all-products listing (runbook step 5: always pass a pricing
+ * context or prices come back undecorated).
+ */
+export default async function HomePage({
+  searchParams,
+}: {
+  searchParams: Promise<{ sortBy?: string; page?: string }>
+}) {
+  const { sortBy, page } = await searchParams
+  const client = await getServerClient()
+  return (
+    <StoreTemplate
+      client={client}
+      sortBy={sortBy as SortOptions | undefined}
+      page={page}
+      pricingContext={PRICING_CONTEXT}
+    />
+  )
+}

package/template/app/src/app/products/[handle]/page.tsx

@@ -0,0 +1,58 @@
+import { notFound } from "next/navigation"
+import { retrieveProduct } from "@cartbase/storefront/api/products"
+import { StoreApiError } from "@cartbase/storefront/api/types"
+import { ProductTemplate } from "@cartbase/storefront/products/product-template"
+import { addToCartAction } from "@/lib/cart-actions"
+import { PRICING_CONTEXT } from "@/lib/config"
+import { getServerClient } from "@/lib/server-client"
+
+/**
+ * PDP (runbook step 5): fetch by handle WITH the pricing context, render
+ * the full product template. `addToCart` is the app-owned seam — a server
+ * action that owns the cart cookie (products family contract).
+ */
+export default async function ProductPage({
+  params,
+}: {
+  params: Promise<{ handle: string }>
+}) {
+  const { handle } = await params
+  const client = await getServerClient()
+
+  let product
+  try {
+    const res = await retrieveProduct(client, handle, PRICING_CONTEXT)
+    product = res.product
+  } catch (e) {
+    if (e instanceof StoreApiError && e.status === 404) notFound()
+    throw e
+  }
+
+  return (
+    <ProductTemplate
+      client={client}
+      product={product}
+      pricingContext={PRICING_CONTEXT}
+      addToCart={addToCartAction}
+    />
+  )
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ handle: string }>
+}) {
+  const { handle } = await params
+  const client = await getServerClient()
+  try {
+    const { product } = await retrieveProduct(client, handle)
+    // SEO fields with title/description fallbacks (runbook step 5).
+    return {
+      title: product.seo_title ?? product.title,
+      description: product.seo_description ?? product.description ?? undefined,
+    }
+  } catch {
+    return {}
+  }
+}

package/template/app/src/app/providers.tsx

@@ -0,0 +1,54 @@
+"use client"
+
+import type { Cart } from "@cartbase/storefront/api/carts"
+import { CartDrawerProvider } from "@cartbase/storefront/cart-drawer/context"
+import { CartDrawerTemplate } from "@cartbase/storefront/cart-drawer/template"
+import { ConsentBanner } from "@cartbase/storefront/tracking/consent-banner"
+import {
+  pickConsentCopy,
+  shouldRenderBanner,
+  type ConsentSettings,
+} from "@cartbase/storefront/tracking/consent"
+import { CART_COOKIE, CART_COOKIE_MAX_AGE } from "@/lib/config"
+import { browserClient } from "@/lib/browser-client"
+
+/**
+ * Client-side shell: ONE CartDrawerProvider per app (cart-drawer family
+ * mount rule) + the consent banner (consent.md: render the builtin banner
+ * only when `enabled && mode === "builtin"`; ConsentInit stays in the
+ * server layout as the first child of <body>).
+ */
+export function Providers({
+  cart,
+  consent,
+  children,
+}: {
+  cart: Cart | null
+  consent: ConsentSettings
+  children: React.ReactNode
+}) {
+  const copy = pickConsentCopy(consent.copy, "en")
+  return (
+    <CartDrawerProvider
+      cart={cart}
+      client={browserClient}
+      onCartChange={(next) => {
+        // Persist the cart id (carts.md: the app owns the cart cookie).
+        document.cookie = `${CART_COOKIE}=${encodeURIComponent(
+          next.id
+        )};path=/;max-age=${CART_COOKIE_MAX_AGE};samesite=lax`
+      }}
+    >
+      {children}
+      <CartDrawerTemplate />
+      {shouldRenderBanner(consent) && copy && (
+        <ConsentBanner
+          copy={copy}
+          layout={consent.layout}
+          privacyHref={consent.privacy_href}
+          rejectOnFirstLayer={consent.reject_on_first_layer}
+        />
+      )}
+    </CartDrawerProvider>
+  )
+}

package/template/app/src/app/search/page.tsx

@@ -0,0 +1,20 @@
+import { SearchTemplate } from "@cartbase/storefront/store/search-template"
+import { PRICING_CONTEXT } from "@/lib/config"
+import { getServerClient } from "@/lib/server-client"
+
+/** Search page (runbook step 5) — fully URL-state driven search-template. */
+export default async function SearchPage({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}) {
+  const params = await searchParams
+  const client = await getServerClient()
+  return (
+    <SearchTemplate
+      client={client}
+      searchParams={params}
+      pricingContext={PRICING_CONTEXT}
+    />
+  )
+}

package/template/app/src/lib/browser-client.ts

@@ -0,0 +1,35 @@
+"use client"
+
+import { StorefrontClient } from "@cartbase/storefront/api/http"
+import {
+  BARTER_CLIENT_ID,
+  BARTER_PUBLISHABLE_KEY,
+  BARTER_URL,
+  LOCALE_COOKIE,
+} from "./config"
+
+function readCookie(name: string): string | null {
+  if (typeof document === "undefined") return null
+  const match = document.cookie
+    .split("; ")
+    .find((row) => row.startsWith(`${name}=`))
+  return match ? decodeURIComponent(match.slice(name.length + 1)) : null
+}
+
+/**
+ * Browser-scope StorefrontClient (runbook step 2): constructed once per
+ * app. Guest-only reference app — no auth token store.
+ *
+ * baseUrl is the APP origin, not the API origin: the store API ships no
+ * CORS headers, so browser calls ride the same-origin `/api/store/*`
+ * rewrite (next.config.ts). During SSR of client components no fetches
+ * run — the API origin stands in only to satisfy the constructor.
+ */
+export const browserClient = new StorefrontClient({
+  baseUrl:
+    typeof window !== "undefined" ? window.location.origin : BARTER_URL,
+  clientId: BARTER_CLIENT_ID,
+  publishableKey: BARTER_PUBLISHABLE_KEY,
+  getAuthToken: () => null,
+  getLocale: () => readCookie(LOCALE_COOKIE),
+})

package/template/app/src/lib/cart-actions.ts

@@ -0,0 +1,47 @@
+"use server"
+
+import { revalidatePath } from "next/cache"
+import { cookies } from "next/headers"
+import { addLineItem, createCart } from "@cartbase/storefront/api/carts"
+import { CART_COOKIE, CART_COOKIE_MAX_AGE, readCartCookie } from "./config"
+import { getServerClient } from "./server-client"
+
+/**
+ * PDP add-to-cart server action (carts.md: create the cart lazily on the
+ * first add — region falls back to the store default; persist `cart.id`
+ * in a cookie). Passed into `ProductTemplate`'s `addToCart` seam.
+ *
+ * Reads via `readCartCookie` (new `_cartbase_cart` name, falls back to the
+ * legacy `_barter_cart_id` — platform-fingerprints card); every WRITE uses
+ * the new name only, so a visitor's cart survives the rename.
+ */
+export async function addToCartAction(input: {
+  variantId: string
+  quantity: number
+}): Promise<void> {
+  const client = await getServerClient()
+  const jar = await cookies()
+  const cartId = readCartCookie((name) => jar.get(name)?.value)
+
+  if (cartId) {
+    await addLineItem(client, cartId, {
+      variant_id: input.variantId,
+      quantity: input.quantity,
+    })
+  } else {
+    const { cart } = await createCart(client, {
+      currency_code: "eur",
+      items: [{ variant_id: input.variantId, quantity: input.quantity }],
+    })
+    jar.set(CART_COOKIE, cart.id, {
+      path: "/",
+      sameSite: "lax",
+      httpOnly: false, // the browser-side drawer persists the same cookie
+      maxAge: CART_COOKIE_MAX_AGE,
+    })
+  }
+
+  // Layout refetches the cart snapshot → CartDrawerProvider sees the new
+  // product-line count and auto-opens the drawer.
+  revalidatePath("/", "layout")
+}

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

@@ -0,0 +1,21 @@
+/** 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

package/template/app/src/lib/server-client.ts

@@ -0,0 +1,25 @@
+import { cookies } from "next/headers"
+import { StorefrontClient } from "@cartbase/storefront/api/http"
+import {
+  BARTER_CLIENT_ID,
+  BARTER_PUBLISHABLE_KEY,
+  BARTER_URL,
+  LOCALE_COOKIE,
+} from "./config"
+
+/**
+ * Server-scope StorefrontClient (runbook step 2): construct per request;
+ * `getLocale` reads the locale cookie. No customer accounts in this
+ * reference app, so `getAuthToken` always answers null (guest).
+ */
+export async function getServerClient(): Promise<StorefrontClient> {
+  const jar = await cookies()
+  const locale = jar.get(LOCALE_COOKIE)?.value ?? null
+  return new StorefrontClient({
+    baseUrl: BARTER_URL,
+    clientId: BARTER_CLIENT_ID,
+    publishableKey: BARTER_PUBLISHABLE_KEY,
+    getAuthToken: () => null,
+    getLocale: () => locale,
+  })
+}

package/template/app/tailwind.config.cjs

@@ -0,0 +1,9 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  presets: [require("@cartbase/storefront/tailwind-preset")],
+  content: [
+    "./src/**/*.{ts,tsx}",
+    // The component library ships source — scan it so its classes exist.
+    "../../packages/storefront/src/**/*.{ts,tsx}",
+  ],
+}

package/template/app/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}