@cimplify/sdk 0.37.0 → 0.38.1

package/dist/dispatcher.mjs

@@ -4,6 +4,7 @@ var HELP = `cimplify \u2014 Cimplify SDK CLI
 
 Usage:
   bunx @cimplify/sdk                         Boot the local mock (alias for \`mock\`)
+  bunx @cimplify/sdk init [dir]              Scaffold a working storefront (uses SDK components)
   bunx @cimplify/sdk mock [flags]            Boot the local Cimplify API mock
   bunx @cimplify/sdk add <component>         Install a UI component from the registry
   bunx @cimplify/sdk list                    List available registry components
@@ -41,9 +42,11 @@ async function main() {
       await import(join(here, "mock", "cli.mjs"));
       return;
     }
+    case "init":
+      await runInit(args);
+      return;
     case "add":
-    case "list":
-    case "init": {
+    case "list": {
       process.argv = [process.argv[0], process.argv[1], sub, ...args];
       const { fileURLToPath } = await import('url');
       const { dirname, join } = await import('path');
@@ -57,6 +60,73 @@ async function main() {
       process.exit(1);
   }
 }
+async function runInit(args) {
+  const { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, copyFileSync } = await import('fs');
+  const { fileURLToPath } = await import('url');
+  const { dirname, join, resolve } = await import('path');
+  const { spawnSync } = await import('child_process');
+  const dir = args.find((a) => !a.startsWith("-")) ?? "my-storefront";
+  const target = resolve(process.cwd(), dir);
+  if (existsSync(target) && readdirSync(target).length > 0) {
+    console.error(`cimplify init: directory ${target} is not empty`);
+    process.exit(1);
+  }
+  mkdirSync(target, { recursive: true });
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve(here, "..", "templates", "storefront"),
+    resolve(here, "..", "..", "templates", "storefront"),
+    resolve(here, "templates", "storefront")
+  ];
+  const source = candidates.find((p) => existsSync(p));
+  if (!source) {
+    console.error("cimplify init: template not found in any of:");
+    for (const c of candidates) console.error("  " + c);
+    process.exit(1);
+  }
+  const placeholderName = dir.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+  const SUBSTITUTABLE = /* @__PURE__ */ new Set([".json", ".tsx", ".ts", ".html", ".md", ".css", ".env.example"]);
+  function copyTree(srcDir, dstDir) {
+    mkdirSync(dstDir, { recursive: true });
+    for (const entry of readdirSync(srcDir)) {
+      const s = join(srcDir, entry);
+      const d = join(dstDir, entry);
+      const stat = statSync(s);
+      if (stat.isDirectory()) {
+        copyTree(s, d);
+      } else {
+        const ext = entry.includes(".env") ? ".env.example" : entry.slice(entry.lastIndexOf("."));
+        if (SUBSTITUTABLE.has(ext)) {
+          const content = readFileSync(s, "utf8").replaceAll("__STOREFRONT_NAME__", placeholderName);
+          writeFileSync(d, content);
+        } else {
+          copyFileSync(s, d);
+        }
+      }
+    }
+  }
+  copyTree(source, target);
+  const envExample = join(target, ".env.example");
+  if (existsSync(envExample)) {
+    copyFileSync(envExample, join(target, ".env.local"));
+  }
+  console.log(`\u2713 Scaffolded ${placeholderName} in ${target}`);
+  console.log("");
+  console.log("Installing dependencies...");
+  const installer = spawnSync(process.env.npm_execpath ? "bun" : "bun", ["install"], {
+    cwd: target,
+    stdio: "inherit"
+  });
+  if (installer.status !== 0) {
+    console.warn("(bun install failed; run it manually)");
+  }
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${dir}`);
+  console.log("  bun dev          # boots both the mock API and the storefront");
+  console.log("");
+  console.log("Then open http://localhost:5173");
+}
 async function runDispatcherFlag(flag) {
   if (flag === "-h" || flag === "--help" || flag === "help") {
     console.log(HELP);

package/dist/mock/cli.mjs

@@ -7839,11 +7839,19 @@ function createMockApp(options = {}) {
     app.use("*", async (c, next) => {
       const origin = c.req.header("origin") ?? "";
       const allow = corsOrigins === "*" ? "*" : corsOrigins.includes(origin) ? origin : corsOrigins[0] ?? "*";
-      c.header("Access-Control-Allow-Origin", allow);
-      c.header("Access-Control-Allow-Headers", "content-type,authorization,x-session-token,idempotency-key");
-      c.header("Access-Control-Allow-Methods", "GET,POST,PATCH,DELETE,OPTIONS");
-      c.header("Access-Control-Expose-Headers", "x-session-token");
-      if (c.req.method === "OPTIONS") return new Response(null, { status: 204 });
+      const headers = {
+        "Access-Control-Allow-Origin": allow,
+        "Access-Control-Allow-Credentials": "true",
+        "Access-Control-Allow-Headers": c.req.header("access-control-request-headers") ?? "content-type,authorization,x-session-token,idempotency-key",
+        "Access-Control-Allow-Methods": "GET,POST,PATCH,DELETE,OPTIONS",
+        "Access-Control-Expose-Headers": "x-session-token",
+        "Access-Control-Max-Age": "86400",
+        Vary: "Origin"
+      };
+      if (c.req.method === "OPTIONS") {
+        return new Response(null, { status: 204, headers });
+      }
+      for (const [k, v] of Object.entries(headers)) c.header(k, v);
       await next();
     });
   }

package/dist/mock/library.js

@@ -7207,11 +7207,19 @@ function createMockApp(options = {}) {
     app.use("*", async (c, next) => {
       const origin = c.req.header("origin") ?? "";
       const allow = corsOrigins === "*" ? "*" : corsOrigins.includes(origin) ? origin : corsOrigins[0] ?? "*";
-      c.header("Access-Control-Allow-Origin", allow);
-      c.header("Access-Control-Allow-Headers", "content-type,authorization,x-session-token,idempotency-key");
-      c.header("Access-Control-Allow-Methods", "GET,POST,PATCH,DELETE,OPTIONS");
-      c.header("Access-Control-Expose-Headers", "x-session-token");
-      if (c.req.method === "OPTIONS") return new Response(null, { status: 204 });
+      const headers = {
+        "Access-Control-Allow-Origin": allow,
+        "Access-Control-Allow-Credentials": "true",
+        "Access-Control-Allow-Headers": c.req.header("access-control-request-headers") ?? "content-type,authorization,x-session-token,idempotency-key",
+        "Access-Control-Allow-Methods": "GET,POST,PATCH,DELETE,OPTIONS",
+        "Access-Control-Expose-Headers": "x-session-token",
+        "Access-Control-Max-Age": "86400",
+        Vary: "Origin"
+      };
+      if (c.req.method === "OPTIONS") {
+        return new Response(null, { status: 204, headers });
+      }
+      for (const [k, v] of Object.entries(headers)) c.header(k, v);
       await next();
     });
   }

package/dist/mock/library.mjs

@@ -7205,11 +7205,19 @@ function createMockApp(options = {}) {
     app.use("*", async (c, next) => {
       const origin = c.req.header("origin") ?? "";
       const allow = corsOrigins === "*" ? "*" : corsOrigins.includes(origin) ? origin : corsOrigins[0] ?? "*";
-      c.header("Access-Control-Allow-Origin", allow);
-      c.header("Access-Control-Allow-Headers", "content-type,authorization,x-session-token,idempotency-key");
-      c.header("Access-Control-Allow-Methods", "GET,POST,PATCH,DELETE,OPTIONS");
-      c.header("Access-Control-Expose-Headers", "x-session-token");
-      if (c.req.method === "OPTIONS") return new Response(null, { status: 204 });
+      const headers = {
+        "Access-Control-Allow-Origin": allow,
+        "Access-Control-Allow-Credentials": "true",
+        "Access-Control-Allow-Headers": c.req.header("access-control-request-headers") ?? "content-type,authorization,x-session-token,idempotency-key",
+        "Access-Control-Allow-Methods": "GET,POST,PATCH,DELETE,OPTIONS",
+        "Access-Control-Expose-Headers": "x-session-token",
+        "Access-Control-Max-Age": "86400",
+        Vary: "Origin"
+      };
+      if (c.req.method === "OPTIONS") {
+        return new Response(null, { status: 204, headers });
+      }
+      for (const [k, v] of Object.entries(headers)) c.header(k, v);
       await next();
     });
   }

package/dist/mock/msw.js

@@ -7205,11 +7205,19 @@ function createMockApp(options = {}) {
     app.use("*", async (c, next) => {
       const origin = c.req.header("origin") ?? "";
       const allow = corsOrigins === "*" ? "*" : corsOrigins.includes(origin) ? origin : corsOrigins[0] ?? "*";
-      c.header("Access-Control-Allow-Origin", allow);
-      c.header("Access-Control-Allow-Headers", "content-type,authorization,x-session-token,idempotency-key");
-      c.header("Access-Control-Allow-Methods", "GET,POST,PATCH,DELETE,OPTIONS");
-      c.header("Access-Control-Expose-Headers", "x-session-token");
-      if (c.req.method === "OPTIONS") return new Response(null, { status: 204 });
+      const headers = {
+        "Access-Control-Allow-Origin": allow,
+        "Access-Control-Allow-Credentials": "true",
+        "Access-Control-Allow-Headers": c.req.header("access-control-request-headers") ?? "content-type,authorization,x-session-token,idempotency-key",
+        "Access-Control-Allow-Methods": "GET,POST,PATCH,DELETE,OPTIONS",
+        "Access-Control-Expose-Headers": "x-session-token",
+        "Access-Control-Max-Age": "86400",
+        Vary: "Origin"
+      };
+      if (c.req.method === "OPTIONS") {
+        return new Response(null, { status: 204, headers });
+      }
+      for (const [k, v] of Object.entries(headers)) c.header(k, v);
       await next();
     });
   }

package/dist/mock/msw.mjs

@@ -7203,11 +7203,19 @@ function createMockApp(options = {}) {
     app.use("*", async (c, next) => {
       const origin = c.req.header("origin") ?? "";
       const allow = corsOrigins === "*" ? "*" : corsOrigins.includes(origin) ? origin : corsOrigins[0] ?? "*";
-      c.header("Access-Control-Allow-Origin", allow);
-      c.header("Access-Control-Allow-Headers", "content-type,authorization,x-session-token,idempotency-key");
-      c.header("Access-Control-Allow-Methods", "GET,POST,PATCH,DELETE,OPTIONS");
-      c.header("Access-Control-Expose-Headers", "x-session-token");
-      if (c.req.method === "OPTIONS") return new Response(null, { status: 204 });
+      const headers = {
+        "Access-Control-Allow-Origin": allow,
+        "Access-Control-Allow-Credentials": "true",
+        "Access-Control-Allow-Headers": c.req.header("access-control-request-headers") ?? "content-type,authorization,x-session-token,idempotency-key",
+        "Access-Control-Allow-Methods": "GET,POST,PATCH,DELETE,OPTIONS",
+        "Access-Control-Expose-Headers": "x-session-token",
+        "Access-Control-Max-Age": "86400",
+        Vary: "Origin"
+      };
+      if (c.req.method === "OPTIONS") {
+        return new Response(null, { status: 204, headers });
+      }
+      for (const [k, v] of Object.entries(headers)) c.header(k, v);
       await next();
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cimplify/sdk",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "description": "Cimplify Commerce SDK for storefronts",
   "keywords": [
     "cimplify",
@@ -18,7 +18,8 @@
   },
   "files": [
     "dist",
-    "registry"
+    "registry",
+    "templates"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/templates/storefront/.env.example

@@ -0,0 +1,2 @@
+VITE_CIMPLIFY_API_URL=http://127.0.0.1:8787
+VITE_CIMPLIFY_BUSINESS_ID=bus_default_akua_bakery

package/templates/storefront/README.md

@@ -0,0 +1,49 @@
+# __STOREFRONT_NAME__
+
+A Cimplify storefront scaffolded from the SDK template. Talks to the Cimplify mock API by default — swap one env var to point at production.
+
+## 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).
+- `vite` — this storefront on `http://localhost:5173`.
+
+Open the storefront in your browser. Edit `src/App.tsx` to start customising. The SDK ships full pages (`<CataloguePage>`, `<ProductPage>`, `<CartPage>`, `<CheckoutPage>`) and layouts (`<DefaultProductLayout>`, `<FoodProductLayout>`, etc.) that you can swap in.
+
+## 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 `VITE_CIMPLIFY_BUSINESS_ID` in `.env.local` to match the seeded business.
+
+## Go live
+
+```diff
+# .env.local
+- VITE_CIMPLIFY_API_URL=http://127.0.0.1:8787
++ VITE_CIMPLIFY_API_URL=https://api.cimplify.io
++ VITE_CIMPLIFY_API_KEY=<your tenant key>
+- VITE_CIMPLIFY_BUSINESS_ID=bus_default_akua_bakery
++ VITE_CIMPLIFY_BUSINESS_ID=<your business id>
+```
+
+## Add components
+
+```bash
+bunx @cimplify/sdk add product-card
+bunx @cimplify/sdk add cart-summary
+bunx @cimplify/sdk list
+```
+
+These copy component sources directly into `src/components/` — yours to edit.

package/templates/storefront/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__STOREFRONT_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/storefront/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "__STOREFRONT_NAME__",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "concurrently -k -n mock,vite -c blue,magenta \"bunx @cimplify/sdk --quiet\" \"vite\"",
+    "dev:storefront": "vite",
+    "dev:mock": "bunx @cimplify/sdk",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@cimplify/sdk": "^0.38.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-router-dom": "^7.9.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.2.4",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.0.0",
+    "concurrently": "^9.0.0",
+    "tailwindcss": "^4.2.4",
+    "typescript": "^5.9.3",
+    "vite": "^7.0.0"
+  }
+}

package/templates/storefront/src/App.tsx

@@ -0,0 +1,118 @@
+import { useEffect, useState } from "react";
+import { Routes, Route, NavLink, useNavigate } from "react-router-dom";
+import { CataloguePage, CartPage, CheckoutPage, useCimplifyClient } from "@cimplify/sdk/react";
+import type { Product, Category } from "@cimplify/sdk";
+
+function CartPill({ count }: { count: number }) {
+  return <span className="cimplify-storefront__cart-pill">Cart · {count}</span>;
+}
+
+function Catalogue() {
+  const navigate = useNavigate();
+  const { client } = useCimplifyClient();
+  const [products, setProducts] = useState<Product[] | undefined>(undefined);
+  const [categories, setCategories] = useState<Category[] | undefined>(undefined);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const [p, c] = await Promise.all([
+          client.catalogue.getProducts({ limit: 50 }),
+          client.catalogue.getCategories(),
+        ]);
+        if (cancelled) return;
+        if (p.ok) setProducts(p.value.items);
+        if (c.ok) setCategories(c.value);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [client]);
+
+  if (loading) return <p>Loading shop…</p>;
+  return (
+    <CataloguePage
+      title="Shop"
+      products={products}
+      categories={categories}
+      onProductClick={(p: Product) => navigate(`/products/${p.id}`)}
+    />
+  );
+}
+
+function ProductDetail() {
+  return (
+    <div>
+      <p>Product detail page — wire up your favourite ProductPage layout here.</p>
+      <p>The SDK ships <code>&lt;ProductPage&gt;</code>, <code>&lt;DefaultProductLayout&gt;</code>, <code>&lt;FoodProductLayout&gt;</code> etc. — pick one.</p>
+    </div>
+  );
+}
+
+function Cart() {
+  const navigate = useNavigate();
+  return <CartPage onCheckout={() => navigate("/checkout")} />;
+}
+
+function Checkout() {
+  const navigate = useNavigate();
+  return (
+    <CheckoutPage
+      onSuccess={(orderId: string) => navigate(`/orders/${orderId}`)}
+      onCancel={() => navigate("/cart")}
+    />
+  );
+}
+
+function OrderConfirmation() {
+  return (
+    <div>
+      <h2>Thanks — your order is confirmed.</h2>
+      <p>This is the page shoppers land on after checkout.</p>
+    </div>
+  );
+}
+
+export function App() {
+  const [cartCount, setCartCount] = useState(0);
+  const { client } = useCimplifyClient();
+
+  useEffect(() => {
+    void client.cart.getCount().then((r) => {
+      if (r.ok) setCartCount(r.value);
+    });
+  }, [client]);
+
+  return (
+    <div className="cimplify-storefront">
+      <header className="cimplify-storefront__nav">
+        <NavLink to="/"><h1>cimplify-store</h1></NavLink>
+        <nav>
+          <NavLink to="/" end>Shop</NavLink>
+          <NavLink to="/cart">Cart</NavLink>
+          <CartPill count={cartCount} />
+        </nav>
+      </header>
+
+      <main className="cimplify-storefront__main">
+        <Routes>
+          <Route path="/" element={<Catalogue />} />
+          <Route path="/products/:productId" element={<ProductDetail />} />
+          <Route path="/cart" element={<Cart />} />
+          <Route path="/checkout" element={<Checkout />} />
+          <Route path="/orders/:orderId" element={<OrderConfirmation />} />
+        </Routes>
+      </main>
+
+      <footer className="cimplify-storefront__footer">
+        Built with <a href="https://github.com/cimplify/cimplify">@cimplify/sdk</a> ·{" "}
+        Mock API at <code>{import.meta.env.VITE_CIMPLIFY_API_URL ?? "http://127.0.0.1:8787"}</code>
+      </footer>
+    </div>
+  );
+}

package/templates/storefront/src/main.tsx

@@ -0,0 +1,28 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import { createCimplifyClient } from "@cimplify/sdk";
+import { CimplifyProvider } from "@cimplify/sdk/react";
+import { App } from "./App";
+
+import "@cimplify/sdk/styles.css";
+import "./styles.css";
+
+const baseUrl = import.meta.env.VITE_CIMPLIFY_API_URL ?? "http://127.0.0.1:8787";
+const publicKey = import.meta.env.VITE_CIMPLIFY_PUBLIC_KEY ?? "mock-dev";
+
+const client = createCimplifyClient({
+  baseUrl,
+  publicKey,
+  suppressPublicKeyWarning: true,
+});
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <CimplifyProvider client={client}>
+        <App />
+      </CimplifyProvider>
+    </BrowserRouter>
+  </React.StrictMode>,
+);

package/templates/storefront/src/styles.css

@@ -0,0 +1,65 @@
+@import "tailwindcss";
+
+html, body {
+  margin: 0;
+  padding: 0;
+  font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto, sans-serif;
+  background: #fafaf9;
+  color: #0f172a;
+}
+
+* { box-sizing: border-box; }
+a { color: inherit; text-decoration: none; }
+
+.cimplify-storefront {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.cimplify-storefront__nav {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 24px;
+  background: white;
+  border-bottom: 1px solid #e2e8f0;
+  position: sticky;
+  top: 0;
+  z-index: 10;
+}
+
+.cimplify-storefront__nav h1 { font-size: 18px; margin: 0; }
+.cimplify-storefront__nav nav a { margin-left: 16px; font-size: 14px; }
+.cimplify-storefront__nav nav a.active { color: #2563eb; font-weight: 600; }
+.cimplify-storefront__cart-pill {
+  margin-left: 16px;
+  padding: 6px 12px;
+  border-radius: 999px;
+  background: #0f172a;
+  color: white;
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.cimplify-storefront__main {
+  flex: 1;
+  padding: 24px;
+  max-width: 1200px;
+  margin: 0 auto;
+  width: 100%;
+}
+
+.cimplify-storefront__footer {
+  padding: 24px;
+  text-align: center;
+  font-size: 12px;
+  color: #64748b;
+  border-top: 1px solid #e2e8f0;
+  background: white;
+}
+
+.cimplify-storefront__main svg {
+  max-width: 64px;
+  max-height: 64px;
+}

package/templates/storefront/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

package/templates/storefront/vite.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  server: { port: 5173, open: false, strictPort: false },
+});