@cimplify/sdk 0.40.1 → 0.41.0

package/templates/storefront-services/README.md

@@ -0,0 +1,73 @@
+# __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-services/app/about/page.tsx

@@ -0,0 +1,38 @@
+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-services/app/cart/page.tsx

@@ -0,0 +1,9 @@
+"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-services/app/categories/[slug]/listing-client.tsx

@@ -0,0 +1,19 @@
+"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-services/app/categories/[slug]/page.tsx

@@ -0,0 +1,118 @@
+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-services/app/checkout/page.tsx

@@ -0,0 +1,17 @@
+"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-services/app/collections/[slug]/listing-client.tsx

@@ -0,0 +1,20 @@
+"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} />}
+    />
+  );
+}

package/templates/storefront-services/app/collections/[slug]/page.tsx

@@ -0,0 +1,118 @@
+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 Collection,
+  type Product,
+} from "@cimplify/sdk/server";
+import { ListingClient } from "./listing-client";
+import { brand } from "@/lib/brand";
+
+interface CollectionData {
+  collection: Collection;
+  products: Product[];
+}
+
+async function getCollection(slug: string): Promise<CollectionData | null> {
+  "use cache";
+  cacheTag(tags.collections());
+  cacheLife("hours");
+
+  const client = getServerClient();
+  const colRes = await client.catalogue.getCollectionBySlug(slug);
+  if (!colRes.ok) return null;
+
+  cacheTag(tags.collection(colRes.value.id), tags.collectionProducts(colRes.value.id));
+  const r = await client.catalogue.getCollectionProducts(colRes.value.id);
+  const products = r.ok
+    ? ((r.value as { items?: Product[] }).items ?? (r.value as Product[]))
+    : [];
+  return { collection: colRes.value, products };
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}): Promise<Metadata> {
+  const { slug } = await params;
+  const data = await getCollection(slug);
+  if (!data) return {};
+  return {
+    title: `${data.collection.name} — ${brand.name}`,
+    description: data.collection.description ?? undefined,
+  };
+}
+
+export default async function CollectionPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  return (
+    <Suspense fallback={<CollectionSkeleton />}>
+      <CollectionContent params={params} />
+    </Suspense>
+  );
+}
+
+async function CollectionContent({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const data = await getCollection(slug);
+  if (!data) notFound();
+
+  const { collection, 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">
+          Collection
+        </p>
+        <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-2">
+          {collection.name}
+        </h1>
+        {collection.description && (
+          <p className="mx-auto mb-2 max-w-xl text-muted-foreground">
+            {collection.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 CollectionSkeleton() {
+  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-services/app/error.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { useEffect } from "react";
+import Link from "next/link";
+
+/**
+ * Root error boundary. Next.js calls this whenever a thrown error escapes
+ * a Server Component without being caught by a closer `error.tsx`.
+ *
+ * Wire `reportError` (Sentry, Datadog, etc.) here so production failures
+ * surface — silently recovering hides real bugs.
+ */
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    // TODO: replace with your error reporter
+    // eslint-disable-next-line no-console
+    console.error("Storefront error:", error);
+  }, [error]);
+
+  return (
+    <section className="max-w-2xl mx-auto px-8 py-20 text-center">
+      <p className="text-[11px] font-semibold uppercase tracking-[0.16em] text-primary mb-3">
+        Something broke
+      </p>
+      <h1 className="font-serif text-[clamp(2rem,4vw,2.75rem)] font-semibold mb-4">
+        That wasn&apos;t supposed to happen.
+      </h1>
+      <p className="text-muted-foreground leading-relaxed mb-8">
+        We&apos;ve been notified. Refresh the page, or head back home —
+        most of the time the second try just works.
+      </p>
+      {error.digest && (
+        <p className="text-xs font-mono text-muted-foreground mb-6">
+          Reference: <code className="text-foreground">{error.digest}</code>
+        </p>
+      )}
+      <div className="flex flex-wrap items-center justify-center gap-3">
+        <button
+          type="button"
+          onClick={reset}
+          className="inline-block px-6 py-3 rounded-full bg-primary text-primary-foreground font-semibold text-sm transition-colors hover:bg-primary/90"
+        >
+          Try again
+        </button>
+        <Link
+          href="/"
+          className="inline-block px-6 py-3 rounded-full border border-border hover:bg-muted transition-colors text-sm font-medium"
+        >
+          Back home
+        </Link>
+      </div>
+    </section>
+  );
+}

package/templates/storefront-services/app/faq/page.tsx

@@ -0,0 +1,46 @@
+import type { Metadata } from "next";
+import { brand } from "@/lib/brand";
+
+export const metadata: Metadata = {
+  title: `FAQ — ${brand.name}`,
+  description: "Delivery, pickup, custom cakes, allergens, payment — answers to the questions we hear most often.",
+};
+
+export default function FaqPage() {
+  const f = brand.faq;
+  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">
+        {f.eyebrow}
+      </p>
+      <h1 className="font-serif text-[clamp(2.25rem,5vw,3.5rem)] font-semibold mb-10 -tracking-[0.02em]">
+        {f.title}
+      </h1>
+      <div className="space-y-12">
+        {f.sections.map((section) => (
+          <section key={section.title}>
+            <h2 className="font-serif text-2xl font-semibold mb-5">{section.title}</h2>
+            <dl className="space-y-6">
+              {section.items.map((item) => (
+                <div key={item.q}>
+                  <dt className="font-medium text-foreground mb-1.5">{item.q}</dt>
+                  <dd className="text-muted-foreground leading-relaxed">{item.a}</dd>
+                </div>
+              ))}
+            </dl>
+          </section>
+        ))}
+      </div>
+      <p className="mt-12 pt-8 border-t border-border text-sm text-muted-foreground">
+        {f.contactPrompt}{" "}
+        <a
+          href={`mailto:${f.contactEmail}`}
+          className="text-primary font-semibold hover:underline"
+        >
+          {f.contactEmail}
+        </a>{" "}
+        and a real human will reply within 24 hours.
+      </p>
+    </article>
+  );
+}

package/templates/storefront-services/app/globals.css

@@ -0,0 +1,45 @@
+@import "tailwindcss";
+
+@source "../node_modules/@cimplify/sdk/dist";
+
+/* Serene Spa — calm sand + sage palette, soft contrast.
+   Tweak primary to retheme everything. */
+@theme {
+  --color-background: oklch(0.98 0.012 90);
+  --color-foreground: oklch(0.22 0.02 140);
+  --color-card: oklch(1 0 0);
+  --color-card-foreground: oklch(0.22 0.02 140);
+  --color-popover: oklch(1 0 0);
+  --color-popover-foreground: oklch(0.22 0.02 140);
+  --color-primary: oklch(0.46 0.06 150);
+  --color-primary-foreground: oklch(0.99 0.01 90);
+  --color-secondary: oklch(0.93 0.025 90);
+  --color-secondary-foreground: oklch(0.3 0.04 140);
+  --color-muted: oklch(0.95 0.018 90);
+  --color-muted-foreground: oklch(0.5 0.02 140);
+  --color-accent: oklch(0.9 0.035 90);
+  --color-accent-foreground: oklch(0.3 0.04 140);
+  --color-destructive: oklch(0.58 0.24 27);
+  --color-destructive-foreground: oklch(0.99 0 0);
+  --color-border: oklch(0.91 0.018 90);
+  --color-input: oklch(0.93 0.018 90);
+  --color-ring: oklch(0.46 0.06 150);
+  --radius: 1rem;
+}
+
+@layer base {
+  html, body {
+    margin: 0;
+    padding: 0;
+    background: var(--color-background);
+    color: var(--color-foreground);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+  a { color: inherit; text-decoration: none; }
+  h1, h2, h3, h4 {
+    font-family: var(--font-serif);
+    letter-spacing: -0.015em;
+    font-weight: 500;
+  }
+}

package/templates/storefront-services/app/layout.tsx

@@ -0,0 +1,80 @@
+import type { Metadata } from "next";
+import { Inter, Fraunces } from "next/font/google";
+import "./globals.css";
+import { Providers } from "@/components/providers";
+import { Header } from "@/components/header";
+import { Footer } from "@/components/footer";
+import { ProductModal } from "@/components/product-modal";
+import { Suspense } from "react";
+import { brand } from "@/lib/brand";
+
+const inter = Inter({
+  subsets: ["latin"],
+  variable: "--font-sans",
+  display: "swap",
+});
+
+const fraunces = Fraunces({
+  subsets: ["latin"],
+  variable: "--font-serif",
+  display: "swap",
+});
+
+const SITE_URL =
+  process.env.NEXT_PUBLIC_SITE_URL?.trim() || "https://example.com";
+
+export const metadata: Metadata = {
+  metadataBase: new URL(SITE_URL),
+  title: {
+    default: brand.name,
+    template: `%s — ${brand.name}`,
+  },
+  description: brand.description,
+  openGraph: {
+    type: "website",
+    siteName: brand.name,
+    locale: brand.locale,
+  },
+  twitter: { card: "summary_large_image" },
+};
+
+const ORGANIZATION_LD = {
+  "@context": "https://schema.org",
+  "@type": brand.schemaType,
+  name: brand.name,
+  url: SITE_URL,
+  description: brand.description,
+  email: brand.contact.email,
+  telephone: brand.contact.phoneTel,
+  address: {
+    "@type": "PostalAddress",
+    streetAddress: brand.contact.streetAddress,
+    addressLocality: brand.contact.city,
+    addressCountry: brand.contact.countryCode,
+  },
+  sameAs: brand.socials.map((s) => s.href),
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${fraunces.variable}`}>
+      <body
+        suppressHydrationWarning
+        className="min-h-screen flex flex-col bg-background text-foreground font-sans"
+      >
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(ORGANIZATION_LD) }}
+        />
+        <Providers>
+          <Header />
+          <main className="flex-1 pb-12 w-full">{children}</main>
+          <Footer />
+          <Suspense fallback={null}>
+            <ProductModal />
+          </Suspense>
+        </Providers>
+      </body>
+    </html>
+  );
+}