@cimplify/sdk 0.44.34 → 0.45.1

package/templates/storefront-bakery/AGENTS.md

@@ -1,120 +0,0 @@
-# AGENTS.md — Bakery storefront template
-
-If you are an AI agent (Claude, Cursor, Aider, devin, …) working on this storefront, **start here.**
-
-## TL;DR for rebranding
-
-To rebrand this storefront end-to-end as a different merchant:
-
-1. **Edit `lib/brand.ts`.** Every visible string reads from this file.
-2. **Edit `app/globals.css`** — the `@theme { … }` block holds the design tokens (palette, radius, font references).
-3. **Edit `.env.local`** — set `NEXT_PUBLIC_CIMPLIFY_API_URL`, `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`, `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID`, `NEXT_PUBLIC_SITE_URL`.
-
-That is the entire rebrand. Do not modify any `.tsx` file in `app/` or `components/` for content changes — they are design-only and read from `brand`.
-
-## Rules
-
-- ✅ All content edits → `lib/brand.ts`
-- ✅ All design-token edits → `app/globals.css` `@theme` block
-- ✅ Server Components stay cached via `'use cache'` + `cacheTag(tags.X())` + `cacheLife("hours")`
-- ✅ Client islands (header active link, cart pill, product modal) live behind `<Suspense>`
-- ❌ Don't hardcode strings. If a string isn't in `brand`, add a new field to the `Brand` interface.
-- ❌ Don't disable `cacheComponents: true` in `next.config.ts`.
-- ❌ Don't use `unstable_cache` — Next 16 uses the `'use cache'` directive.
-
-## Page surface
-
-```
-app/
-  page.tsx                       Home — hero, collection strips, category grid
-  shop/page.tsx                  Full catalogue (SDK <CataloguePage/>)
-  search/page.tsx                Search (SDK <SearchPage/>)
-  collections/[slug]/page.tsx    Collection landing
-  categories/[slug]/page.tsx     Category landing
-
-  cart/page.tsx                  SDK <CartPage/>
-  checkout/page.tsx              SDK <CheckoutPage/>
-  orders/[id]/page.tsx           Post-checkout confirmation (also target of /track-order)
-
-  account/page.tsx               <CimplifyAccount /> (iframe — handles sign-in, dashboard)
-  account/orders/page.tsx        <CimplifyAccount section="orders" />
-  account/addresses/page.tsx     <CimplifyAccount section="addresses" />
-  account/settings/page.tsx      <CimplifyAccount section="settings" />
-  login/page.tsx                 redirect → /account (iframe owns sign-in UI)
-  signup/page.tsx                redirect → /account (iframe owns sign-up UI)
-
-  contact/page.tsx               Contact form (Server Action wiring TODO; currently fakes submit)
-  track-order/page.tsx           Guest order lookup → /orders/[id]
-
-  about/page.tsx                 Brand story
-  faq/page.tsx                   FAQ
-  shipping/page.tsx              Standalone shipping policy
-  returns/page.tsx               Standalone returns policy
-  accessibility/page.tsx         Accessibility statement (WCAG 2.1 AA)
-  terms/page.tsx                 Terms of Service
-  privacy/page.tsx               Privacy Policy
-
-  sitemap-page/page.tsx          Human-readable HTML sitemap
-  sitemap.ts                     XML sitemap (search engines)
-  robots.ts                      robots.txt
-  llms.txt/route.ts              LLM-friendly Markdown index
-  opensearch.xml/route.ts        Browser address-bar search description
-  error.tsx, not-found.tsx       Global boundaries
-```
-
-## File ↔ brand-field map
-
-| File | Reads from `brand` |
-|---|---|
-| `app/layout.tsx` | identity, contact, socials, schemaType (Organization JSON-LD), `metadataBase` |
-| `app/page.tsx` | `brand.hero` (Hero badge / title / subtitle) |
-| `app/about/page.tsx` | `brand.about` |
-| `app/faq/page.tsx` | `brand.faq` |
-| `app/terms/page.tsx` | `brand.terms` |
-| `app/privacy/page.tsx` | `brand.privacy` |
-| `app/shipping/page.tsx` | `brand.shipping` |
-| `app/returns/page.tsx` | `brand.returns` |
-| `app/accessibility/page.tsx` | `brand.accessibility` |
-| `app/contact/page.tsx` | `brand.contactPage`, `brand.contact` |
-| `app/track-order/page.tsx` | `brand.trackOrder` |
-| `app/account/*/page.tsx` | `brand.account` (eyebrows + titles only — Cimplify Link iframe owns the UI) |
-| `app/login/page.tsx`, `app/signup/page.tsx` | `brand.account` (metadata only — both redirect to `/account`) |
-| `app/llms.txt/route.ts` | `brand.llms`, contact, currency |
-| `app/opensearch.xml/route.ts` | `brand.shortName`, `brand.name` |
-| `app/sitemap.ts`, `robots.ts` | derives URLs from product/category data |
-| `app/not-found.tsx` | `brand.name` (page title) |
-| `components/header.tsx` | `brand.shortName`, `brand.microTag`, `brand.header.nav` |
-| `components/footer.tsx` | `brand.footer`, `brand.contact`, `brand.socials` |
-
-## Bakery-specific notes
-
-- Product detail uses a **URL-driven modal** (`?product=<slug>`), not a static `/products/[slug]` route. Fits impulse-purchase food UX.
-- Schema.org `@type` is `Bakery` — set in `brand.schemaType`.
-- Mock seed: `--seed default` (Akua's Bakery). To preview a different industry, edit `dev:mock` in `package.json` and update `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID`.
-
-## Known TODOs (not blocking, but worth knowing)
-
-- `app/contact/contact-form.tsx` fakes a successful submit. In production, wire a Server Action that calls `client.support.sendMessage(...)` from `@cimplify/sdk/server`.
-- `components/newsletter.tsx` (homepage strip) similarly fakes submit. Wire to a real list provider.
-- Hero / lookbook imagery is Unsplash placeholder — replace with merchant assets.
-
-## Customizing SDK components
-
-For anything beyond `lib/brand.ts` + `app/globals.css`, lean on the SDK's prebuilt components rather than reinvent. **Especially for product customization** (variants, add-ons, bundles, composites, services with scheduling) — the SDK already gets price math, axis matching, and cart payload contracts right. Default to ejecting and restyling:
-
-```bash
-bunx @cimplify/sdk add cart-drawer
-bunx @cimplify/sdk add variant-selector
-bunx @cimplify/sdk add product-page
-```
-
-Then edit the local copy. **Don't change the cart payload shape** unless you're also touching the SDK mock + backend lens. Full ejection rules and the customizer contract are in the SDK-level [`AGENTS.md`](../../AGENTS.md) → "Don't reinvent product customization".
-
-## Quick start
-
-```bash
-bun install
-bun dev                 # boots mock + Next dev server
-```
-
-Open <http://localhost:3000>.

package/templates/storefront-bakery/CLAUDE.md

@@ -1,22 +0,0 @@
-# CLAUDE.md
-
-This project was scaffolded from a Cimplify storefront template (`bunx @cimplify/sdk init`).
-
-## Read these first
-
-- **`AGENTS.md`** at the project root — the file ↔ `brand.X` field map for *this template's* industry, plus the architectural rules.
-- **`.claude/skills/cimplify-storefront/SKILL.md`** — the playbook for common tasks (rebrand, add a section, wire a Server Action, deploy, eject a component). Invoke it whenever you're asked to change content, palette, copy, or routing.
-
-## The two-line summary
-
-1. **Edit `lib/brand.ts`** for any visible string.
-2. **Edit `app/globals.css` `@theme` block** for any palette / radius / font change.
-
-That covers ~95% of what merchants ask for. For anything else, follow the `cimplify-storefront` skill.
-
-## Don't do
-
-- Hardcode strings in pages or components.
-- Disable `cacheComponents: true` in `next.config.ts`.
-- Use `unstable_cache` — Next 16's canonical primitive is `'use cache'`.
-- Run `bun test` (Bun's `vi` shim is incomplete) — use `bun run test:run`.

package/templates/storefront-bakery/README.md

@@ -1,73 +0,0 @@
-# __STOREFRONT_NAME__
-
-A Cimplify storefront scaffolded from the **bakery** template — Next.js 16 (App Router), React 19, Tailwind v4. Warm food-styled palette, Playfair Display + Inter typography, designed for bakeries, pâtisseries, and food businesses.
-
-For a different industry, scaffold with `--template`:
-
-```bash
-bunx @cimplify/sdk init my-store --template retail   # electronics / consumer goods
-bunx @cimplify/sdk init my-store --template bakery   # default — food / pâtisserie
-```
-
-## Run
-
-```bash
-bun install
-bun dev
-```
-
-Two things start in parallel:
-
-- `bunx @cimplify/sdk` — the Cimplify mock API on `http://127.0.0.1:8787` (Akua's Bakery seeded by default).
-- `next dev` — this storefront on `http://localhost:3000`.
-
-Open the storefront in your browser. Edit `app/page.tsx` to start customising. The SDK ships full pages (`<CataloguePage>`, `<ProductPage>`, `<CartPage>`, `<CheckoutPage>`) and layouts (`<DefaultProductLayout>`, `<FoodProductLayout>`, etc.) that you can swap in.
-
-## Structure
-
-```
-app/
-  layout.tsx              # root layout, fonts, providers, header/footer/modal
-  page.tsx                # home
-  shop/page.tsx           # full catalogue (SDK <CataloguePage/>)
-  collections/[slug]/     # collection landing
-  categories/[slug]/      # category landing
-  cart/page.tsx           # SDK <CartPage/>
-  checkout/page.tsx       # SDK <CheckoutPage/>
-  orders/[id]/page.tsx    # post-checkout thank-you
-  globals.css             # Tailwind import + theme tokens
-components/
-  providers.tsx           # CimplifyProvider client wrapper
-  header.tsx, footer.tsx, hero.tsx
-  store-product-card.tsx  # SDK <ProductCard/> wired to URL-driven modal
-  product-modal.tsx       # ?product=<slug> deep-linkable modal
-  collection-strip.tsx    # horizontal product strip
-  category-grid.tsx       # SDK <CategoryGrid/> with router navigation
-lib/
-  cart.ts                 # useCartCount() for the header pill
-```
-
-## Switch seed
-
-```bash
-bunx @cimplify/sdk --seed restaurant   # Mama's Kitchen
-bunx @cimplify/sdk --seed retail       # Currents Electronics
-bunx @cimplify/sdk --seed services     # Serene Spa
-bunx @cimplify/sdk --seed grocery      # FreshMart
-```
-
-Update `NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID` in `.env.local` to match the seeded business.
-
-## Go live
-
-```diff
-# .env.local
-- NEXT_PUBLIC_CIMPLIFY_API_URL=http://127.0.0.1:8787
-+ NEXT_PUBLIC_CIMPLIFY_API_URL=https://api.cimplify.io
-- NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=mock-dev
-+ NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=<your tenant key>
-- NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=bus_default_akua_bakery
-+ NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=<your business id>
-```
-
-Deploy to Vercel with one click — `next.config.ts` already whitelists the SDK image hosts under `images.remotePatterns`.

package/templates/storefront-bakery/__tests__/brand.test.ts

@@ -1,4 +0,0 @@
-import { createBrandSuite } from "@cimplify/sdk/testing/suite";
-import { brand } from "../lib/brand";
-
-createBrandSuite({ brand });

package/templates/storefront-bakery/__tests__/cart-flow.test.ts

@@ -1,4 +0,0 @@
-import { createCartFlowSuite } from "@cimplify/sdk/testing/suite";
-import { brand } from "../lib/brand";
-
-createCartFlowSuite({ seed: brand.mock.seed, businessId: brand.mock.businessId });

package/templates/storefront-bakery/__tests__/contract.test.ts

@@ -1,4 +0,0 @@
-import { createContractSuite } from "@cimplify/sdk/testing/suite";
-import { brand } from "../lib/brand";
-
-createContractSuite({ seed: brand.mock.seed });

package/templates/storefront-bakery/app/about/page.tsx

@@ -1,38 +0,0 @@
-import type { Metadata } from "next";
-import { brand } from "@/lib/brand";
-
-export const metadata: Metadata = {
-  title: `About — ${brand.name}`,
-  description: brand.description,
-};
-
-export default function AboutPage() {
-  const a = brand.about;
-  const titleParts = a.title.split("\n");
-  return (
-    <article className="max-w-3xl mx-auto px-8 py-16">
-      <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
-        {a.eyebrow}
-      </p>
-      <h1 className="font-serif text-[clamp(2.25rem,5vw,3.5rem)] font-semibold mb-6 -tracking-[0.02em]">
-        {titleParts.map((line, i) => (
-          <span key={i}>
-            {line}
-            {i < titleParts.length - 1 && <br />}
-          </span>
-        ))}
-      </h1>
-      <div className="prose prose-lg max-w-none space-y-5 text-foreground/90 leading-relaxed">
-        {a.paragraphs.map((p, i) => (
-          <p key={i}>{p}</p>
-        ))}
-        {a.sections.map((s) => (
-          <div key={s.heading}>
-            <h2 className="font-serif text-3xl font-semibold mt-10 mb-3">{s.heading}</h2>
-            <p>{s.body}</p>
-          </div>
-        ))}
-      </div>
-    </article>
-  );
-}

package/templates/storefront-bakery/app/accessibility/page.tsx

@@ -1,11 +0,0 @@
-import type { Metadata } from "next";
-import { brand } from "@/lib/brand";
-import { PolicyPage } from "@/components/policy-page";
-
-export const metadata: Metadata = {
-  title: `${brand.accessibility.title} — ${brand.name}`,
-};
-
-export default function AccessibilityPage() {
-  return <PolicyPage policy={brand.accessibility} />;
-}

package/templates/storefront-bakery/app/account/addresses/page.tsx

@@ -1,21 +0,0 @@
-import type { Metadata } from "next";
-import { AccountIframe } from "@/components/account-iframe";
-import { brand } from "@/lib/brand";
-
-export const metadata: Metadata = {
-  title: `Addresses — ${brand.name}`,
-};
-
-export default function AddressesPage() {
-  return (
-    <article className="max-w-5xl mx-auto px-6 sm:px-8 py-12">
-      <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
-        Account
-      </p>
-      <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-8 -tracking-[0.02em]">
-        Your addresses
-      </h1>
-      <AccountIframe section="addresses" />
-    </article>
-  );
-}

package/templates/storefront-bakery/app/account/orders/page.tsx

@@ -1,21 +0,0 @@
-import type { Metadata } from "next";
-import { AccountIframe } from "@/components/account-iframe";
-import { brand } from "@/lib/brand";
-
-export const metadata: Metadata = {
-  title: `Orders — ${brand.name}`,
-};
-
-export default function OrdersPage() {
-  return (
-    <article className="max-w-5xl mx-auto px-6 sm:px-8 py-12">
-      <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
-        Account
-      </p>
-      <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-8 -tracking-[0.02em]">
-        Your orders
-      </h1>
-      <AccountIframe section="orders" />
-    </article>
-  );
-}

package/templates/storefront-bakery/app/account/page.tsx

@@ -1,22 +0,0 @@
-import type { Metadata } from "next";
-import { AccountIframe } from "@/components/account-iframe";
-import { brand } from "@/lib/brand";
-
-export const metadata: Metadata = {
-  title: `Account — ${brand.name}`,
-  description: brand.account.signupSubtitle,
-};
-
-export default function AccountPage() {
-  return (
-    <article className="max-w-5xl mx-auto px-6 sm:px-8 py-12">
-      <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
-        {brand.account.accountEyebrow}
-      </p>
-      <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-8 -tracking-[0.02em]">
-        {brand.account.accountTitle}
-      </h1>
-      <AccountIframe />
-    </article>
-  );
-}

package/templates/storefront-bakery/app/account/settings/page.tsx

@@ -1,21 +0,0 @@
-import type { Metadata } from "next";
-import { AccountIframe } from "@/components/account-iframe";
-import { brand } from "@/lib/brand";
-
-export const metadata: Metadata = {
-  title: `Settings — ${brand.name}`,
-};
-
-export default function SettingsPage() {
-  return (
-    <article className="max-w-5xl mx-auto px-6 sm:px-8 py-12">
-      <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
-        Account
-      </p>
-      <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-8 -tracking-[0.02em]">
-        Settings
-      </h1>
-      <AccountIframe section="settings" />
-    </article>
-  );
-}

package/templates/storefront-bakery/app/cart/page.tsx

@@ -1,9 +0,0 @@
-"use client";
-
-import { useRouter } from "next/navigation";
-import { CartPage as SdkCartPage } from "@cimplify/sdk/react";
-
-export default function CartPage() {
-  const router = useRouter();
-  return <SdkCartPage onCheckout={() => router.push("/checkout")} />;
-}

package/templates/storefront-bakery/app/categories/[slug]/listing-client.tsx

@@ -1,19 +0,0 @@
-"use client";
-
-import { ProductGrid } from "@cimplify/sdk/react";
-import type { Product } from "@cimplify/sdk";
-import { StoreProductCard } from "@/components/store-product-card";
-
-/**
- * Client island for the category listing. Receives server-fetched products
- * as props (serializable) and owns the `renderCard` function.
- */
-export function ListingClient({ products }: { products: Product[] }) {
-  return (
-    <ProductGrid
-      products={products}
-      emptyMessage="No products in this category yet."
-      renderCard={(p) => <StoreProductCard product={p} />}
-    />
-  );
-}

package/templates/storefront-bakery/app/categories/[slug]/page.tsx

@@ -1,118 +0,0 @@
-import type { Metadata } from "next";
-import { Suspense } from "react";
-import Link from "next/link";
-import { notFound } from "next/navigation";
-import { cacheTag, cacheLife } from "next/cache";
-import {
-  getServerClient,
-  tags,
-  type Category,
-  type Product,
-} from "@cimplify/sdk/server";
-import { ListingClient } from "./listing-client";
-import { brand } from "@/lib/brand";
-
-interface CategoryData {
-  category: Category;
-  products: Product[];
-}
-
-async function getCategory(slug: string): Promise<CategoryData | null> {
-  "use cache";
-  cacheTag(tags.categories());
-  cacheLife("hours");
-
-  const client = getServerClient();
-  const catRes = await client.catalogue.getCategoryBySlug(slug);
-  if (!catRes.ok) return null;
-
-  cacheTag(tags.category(catRes.value.id), tags.categoryProducts(catRes.value.id));
-  const r = await client.catalogue.getCategoryProducts(catRes.value.id);
-  const products = r.ok
-    ? ((r.value as { items?: Product[] }).items ?? (r.value as Product[]))
-    : [];
-  return { category: catRes.value, products };
-}
-
-export async function generateMetadata({
-  params,
-}: {
-  params: Promise<{ slug: string }>;
-}): Promise<Metadata> {
-  const { slug } = await params;
-  const data = await getCategory(slug);
-  if (!data) return {};
-  return {
-    title: `${data.category.name} — ${brand.name}`,
-    description: data.category.description ?? undefined,
-  };
-}
-
-export default async function CategoryPage({
-  params,
-}: {
-  params: Promise<{ slug: string }>;
-}) {
-  return (
-    <Suspense fallback={<CategorySkeleton />}>
-      <CategoryContent params={params} />
-    </Suspense>
-  );
-}
-
-async function CategoryContent({
-  params,
-}: {
-  params: Promise<{ slug: string }>;
-}) {
-  const { slug } = await params;
-  const data = await getCategory(slug);
-  if (!data) notFound();
-
-  const { category, products } = data;
-  return (
-    <section className="max-w-7xl mx-auto px-8 pt-12">
-      <header className="mb-8 text-center">
-        <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-2">
-          Category
-        </p>
-        <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-2">
-          {category.name}
-        </h1>
-        {category.description && (
-          <p className="mx-auto mb-2 max-w-xl text-muted-foreground">
-            {category.description}
-          </p>
-        )}
-        <p className="text-sm text-muted-foreground">
-          {products.length} item{products.length === 1 ? "" : "s"}
-        </p>
-      </header>
-      <ListingClient products={products} />
-      {products.length === 0 && (
-        <p className="text-center mt-8">
-          <Link href="/" className="text-primary font-semibold">
-            ← Back home
-          </Link>
-        </p>
-      )}
-    </section>
-  );
-}
-
-function CategorySkeleton() {
-  return (
-    <section className="max-w-7xl mx-auto px-8 pt-12">
-      <header className="mb-8 text-center">
-        <div className="mx-auto h-3 w-20 bg-muted rounded mb-2 animate-pulse" />
-        <div className="mx-auto h-10 w-64 bg-muted rounded mb-2 animate-pulse" />
-        <div className="mx-auto h-4 w-80 bg-muted rounded animate-pulse" />
-      </header>
-      <div className="grid grid-cols-2 md:grid-cols-3 gap-4">
-        {Array.from({ length: 6 }).map((_, i) => (
-          <div key={i} className="aspect-square bg-muted rounded-2xl animate-pulse" />
-        ))}
-      </div>
-    </section>
-  );
-}

package/templates/storefront-bakery/app/checkout/page.tsx

@@ -1,17 +0,0 @@
-"use client";
-
-import { useRouter } from "next/navigation";
-import { CheckoutPage as SdkCheckoutPage } from "@cimplify/sdk/react";
-
-export default function CheckoutPage() {
-  const router = useRouter();
-  return (
-    <SdkCheckoutPage
-      onComplete={(result) => {
-        if (result.success && result.order) {
-          router.push(`/orders/${result.order.id}`);
-        }
-      }}
-    />
-  );
-}

package/templates/storefront-bakery/app/collections/[slug]/listing-client.tsx

@@ -1,20 +0,0 @@
-"use client";
-
-import { ProductGrid } from "@cimplify/sdk/react";
-import type { Product } from "@cimplify/sdk";
-import { StoreProductCard } from "@/components/store-product-card";
-
-/**
- * Client island for the collection listing. Receives server-fetched
- * products as props (serializable) and owns the `renderCard` function
- * (which can't cross the server/client boundary).
- */
-export function ListingClient({ products }: { products: Product[] }) {
-  return (
-    <ProductGrid
-      products={products}
-      emptyMessage="No products in this collection yet."
-      renderCard={(p) => <StoreProductCard product={p} />}
-    />
-  );
-}