@cimplify/sdk 0.39.0 → 0.40.0

package/templates/storefront-retail/README.md

@@ -0,0 +1,77 @@
+# __STOREFRONT_NAME__
+
+A Cimplify storefront scaffolded from the **retail** template — Next.js 16 (App Router), React 19, Tailwind v4. Cool navy + electric blue palette, Inter + JetBrains Mono typography, modern electronics-store aesthetic.
+
+## Run
+
+```bash
+bun install
+bun dev
+```
+
+Two things start in parallel:
+
+- `bunx @cimplify/sdk --seed retail` — the Cimplify mock API on `http://127.0.0.1:8787`, seeded with Currents Electronics.
+- `next dev` — this storefront on `http://localhost:3000`.
+
+Open the storefront in your browser. Edit `app/page.tsx` to start customising.
+
+## 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
+  about, faq, terms, privacy
+  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 the seed
+
+This template is wired to the `retail` seed. To preview a different industry without re-scaffolding:
+
+```bash
+bunx @cimplify/sdk --seed restaurant   # Mama's Kitchen
+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.
+
+For a fresh scaffold with another design altogether:
+
+```bash
+bunx @cimplify/sdk init my-store --template bakery     # warm food/pastry
+bunx @cimplify/sdk init my-store --template restaurant # coming soon
+bunx @cimplify/sdk init my-store --template services   # coming soon
+bunx @cimplify/sdk init my-store --template grocery    # coming soon
+```
+
+## 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_currents_electronics
++ 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-retail/app/about/page.tsx

@@ -0,0 +1,71 @@
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "About — Currents Electronics",
+  description:
+    "Authorised dealer for Apple, Samsung, Sony, Bose. Serving Accra and West Africa with same-day delivery and a two-year warranty since 2017.",
+};
+
+export default function AboutPage() {
+  return (
+    <article className="max-w-3xl mx-auto px-8 py-16">
+      <p className="text-[11px] font-mono uppercase tracking-[0.16em] text-primary mb-2">
+        About Currents
+      </p>
+      <h1 className="text-[clamp(2.25rem,5vw,3.5rem)] font-bold mb-6 -tracking-[0.025em] leading-tight">
+        Tech that lasts.<br />Service that doesn&apos;t flake.
+      </h1>
+      <div className="prose prose-lg max-w-none space-y-5 text-foreground/90 leading-relaxed">
+        <p>
+          We started Currents in 2017 because the best phones, laptops, and
+          headphones were either three months out of stock in Accra, or
+          obviously fake. Either way, you ended up calling someone&apos;s
+          cousin in London. That&apos;s a bad way to buy a thousand-dollar
+          device.
+        </p>
+        <p>
+          Today we&apos;re an authorised dealer for Apple, Samsung, Sony, Bose,
+          Logitech, and Anker. Every product is sourced direct from the
+          manufacturer or their certified distributor — no parallel imports,
+          no refurbished-as-new, no &quot;dual SIM Asia spec&quot; on a US iPhone.
+          What you order is what we open in front of you on delivery.
+        </p>
+        <p>
+          We back everything with a two-year warranty (one year manufacturer +
+          one year Currents), free same-day Accra delivery, and a 14-day
+          no-questions-asked return on anything sealed.
+        </p>
+
+        <h2 className="text-2xl font-semibold mt-10 mb-3 -tracking-[0.02em]">
+          Trade-in
+        </h2>
+        <p>
+          Got an iPhone, Galaxy, or MacBook you no longer use? Bring it in or
+          ship it to us — we&apos;ll quote you within 48 hours and credit the
+          value toward your next purchase. We work with refurbishers across the
+          continent so your old kit stays in service for years more.
+        </p>
+
+        <h2 className="text-2xl font-semibold mt-10 mb-3 -tracking-[0.02em]">
+          Business sales
+        </h2>
+        <p>
+          Equipping a team or kitting out a co-working space? We do volume
+          quotes, delivery scheduling, asset tagging, and on-site setup. Email{" "}
+          <a
+            href="mailto:business@currentselectronics.test"
+            className="text-primary font-semibold hover:underline"
+          >
+            business@currentselectronics.test
+          </a>
+          .
+        </p>
+
+        <h2 className="text-2xl font-semibold mt-10 mb-3 -tracking-[0.02em]">
+          Visit
+        </h2>
+        <p>Atomic Junction, East Legon, Accra · Mon–Sat, 9am–8pm.</p>
+      </div>
+    </article>
+  );
+}

package/templates/storefront-retail/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-retail/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-retail/app/categories/[slug]/page.tsx

@@ -0,0 +1,117 @@
+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";
+
+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} — Akua's Bakery`,
+    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-retail/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-retail/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-retail/app/collections/[slug]/page.tsx

@@ -0,0 +1,117 @@
+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";
+
+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} — Akua's Bakery`,
+    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-retail/app/faq/page.tsx

@@ -0,0 +1,127 @@
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Support — Currents Electronics",
+  description:
+    "Shipping, warranty, repairs, returns, payment — answers to the questions we hear most often.",
+};
+
+interface QA {
+  q: string;
+  a: string;
+}
+
+const SECTIONS: { title: string; items: QA[] }[] = [
+  {
+    title: "Ordering & delivery",
+    items: [
+      {
+        q: "How fast is shipping?",
+        a: "Free same-day delivery within Greater Accra for orders placed before 4pm. Outside Accra, we use a partner courier — usually 1–3 business days, with tracking sent by SMS.",
+      },
+      {
+        q: "Can I pick up in store?",
+        a: "Yes. Choose 'Pickup' at checkout and we'll have your order boxed at our Atomic Junction store within 30 minutes. Bring a photo ID matching the order name.",
+      },
+      {
+        q: "Do you ship internationally?",
+        a: "We ship across West Africa via DHL — rates and ETAs are calculated at checkout once you enter your destination.",
+      },
+      {
+        q: "How do I track my order?",
+        a: "You'll get an SMS and email with a tracking link within 30 minutes of dispatch. Same-day Accra orders include the rider's phone number.",
+      },
+    ],
+  },
+  {
+    title: "Warranty & repairs",
+    items: [
+      {
+        q: "What does the two-year warranty cover?",
+        a: "Manufacturing defects, electrical failures, and battery degradation below 80% within the first 24 months. Accidental damage, water damage, and software issues caused by user installs are excluded.",
+      },
+      {
+        q: "Where do I send a faulty device?",
+        a: "Drop it at our Atomic Junction store, or request a free pickup from your address by emailing support@currentselectronics.test. Loaner devices are available for warranty claims while we diagnose.",
+      },
+      {
+        q: "Can you fix devices bought elsewhere?",
+        a: "We offer paid repairs on Apple and Samsung devices regardless of where they were purchased. Expect a quote within 48 hours of inspection.",
+      },
+    ],
+  },
+  {
+    title: "Trade-in & financing",
+    items: [
+      {
+        q: "How does trade-in work?",
+        a: "Tell us the model and condition of your device, get an instant estimate, and ship it free or drop it at our store. Once we verify, we credit your account or pay out via Mobile Money — your choice.",
+      },
+      {
+        q: "Do you offer instalment payments?",
+        a: "Yes. Pay in 3 (interest-free) or 6/12 monthly instalments via our partner Fidelity Bank. Available at checkout for orders over GH₵2,000.",
+      },
+      {
+        q: "Are there bulk discounts for businesses?",
+        a: "Yes. Email business@currentselectronics.test with your shopping list and team size — most orders over 5 units qualify for a discount, plus free on-site setup.",
+      },
+    ],
+  },
+  {
+    title: "Payment & returns",
+    items: [
+      {
+        q: "What payment methods do you accept?",
+        a: "Mobile Money (MTN, Telecel, AirtelTigo), Visa/Mastercard, instalments via Fidelity Bank, and cash on delivery for Accra orders.",
+      },
+      {
+        q: "What's your return policy?",
+        a: "14 days, no questions asked, on any sealed product. For opened items, returns are accepted within 7 days subject to a 10% restocking fee. We can't accept returns on activated SIM-bundled phones once the SIM is registered.",
+      },
+      {
+        q: "Are products genuine?",
+        a: "Yes. We're an authorised dealer for every brand we stock. Every product ships with the manufacturer's serial number registered to your name — verify it on the brand's official portal anytime.",
+      },
+    ],
+  },
+];
+
+export default function FaqPage() {
+  return (
+    <article className="max-w-3xl mx-auto px-8 py-16">
+      <p className="text-[11px] font-mono uppercase tracking-[0.16em] text-primary mb-2">
+        Support
+      </p>
+      <h1 className="text-[clamp(2.25rem,5vw,3.5rem)] font-bold mb-10 -tracking-[0.025em]">
+        Questions, answered.
+      </h1>
+      <div className="space-y-12">
+        {SECTIONS.map((section) => (
+          <section key={section.title}>
+            <h2 className="text-2xl font-semibold mb-5 -tracking-[0.02em]">
+              {section.title}
+            </h2>
+            <dl className="space-y-6">
+              {section.items.map((item) => (
+                <div key={item.q}>
+                  <dt className="font-semibold 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">
+        Still stuck? Email{" "}
+        <a
+          href="mailto:support@currentselectronics.test"
+          className="text-primary font-semibold hover:underline"
+        >
+          support@currentselectronics.test
+        </a>{" "}
+        and a real human will reply within 24 hours.
+      </p>
+    </article>
+  );
+}

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

@@ -0,0 +1,47 @@
+@import "tailwindcss";
+
+/* Scan the SDK's bundled JS so utility classes used inside its components
+   land in the compiled stylesheet alongside our own. */
+@source "../node_modules/@cimplify/sdk/dist";
+
+/* Currents Electronics palette — cool navy chrome, electric blue accent.
+   Modern retail aesthetic; tweak these tokens to retheme everything. */
+@theme {
+  --color-background: oklch(0.99 0.005 240);
+  --color-foreground: oklch(0.2 0.03 250);
+  --color-card: oklch(1 0 0);
+  --color-card-foreground: oklch(0.2 0.03 250);
+  --color-popover: oklch(1 0 0);
+  --color-popover-foreground: oklch(0.2 0.03 250);
+  --color-primary: oklch(0.55 0.22 255);
+  --color-primary-foreground: oklch(0.99 0 0);
+  --color-secondary: oklch(0.95 0.02 250);
+  --color-secondary-foreground: oklch(0.25 0.05 250);
+  --color-muted: oklch(0.96 0.01 250);
+  --color-muted-foreground: oklch(0.5 0.03 250);
+  --color-accent: oklch(0.92 0.07 240);
+  --color-accent-foreground: oklch(0.25 0.1 250);
+  --color-destructive: oklch(0.58 0.24 27);
+  --color-destructive-foreground: oklch(0.99 0 0);
+  --color-border: oklch(0.92 0.01 250);
+  --color-input: oklch(0.94 0.01 250);
+  --color-ring: oklch(0.55 0.22 255);
+  --radius: 0.5rem;
+}
+
+@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-sans);
+    letter-spacing: -0.02em;
+    font-weight: 600;
+  }
+}

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

@@ -0,0 +1,46 @@
+import type { Metadata } from "next";
+import { Inter, JetBrains_Mono } 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";
+
+const inter = Inter({
+  subsets: ["latin"],
+  variable: "--font-sans",
+  display: "swap",
+});
+
+const mono = JetBrains_Mono({
+  subsets: ["latin"],
+  variable: "--font-mono",
+  display: "swap",
+});
+
+export const metadata: Metadata = {
+  title: "Currents Electronics",
+  description:
+    "The latest laptops, phones, audio, and accessories — curated, in-stock, shipped from Accra to Africa.",
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${mono.variable}`}>
+      <body
+        suppressHydrationWarning
+        className="min-h-screen flex flex-col bg-background text-foreground font-sans"
+      >
+        <Providers>
+          <Header />
+          <main className="flex-1 pb-12 w-full">{children}</main>
+          <Footer />
+          <Suspense fallback={null}>
+            <ProductModal />
+          </Suspense>
+        </Providers>
+      </body>
+    </html>
+  );
+}