@cimplify/sdk 0.36.0 → 0.38.0

package/dist/dispatcher.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// src/dispatcher.ts
+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
+  bunx @cimplify/sdk --help, -h              Show this help
+  bunx @cimplify/sdk --version, -v           Show SDK version
+
+Mock flags:
+  --port <num>             Port (default 8787)
+  --host <host>            Host (default 127.0.0.1)
+  --seed <name>            default | restaurant | retail | services | grocery | reesa-storefront | empty
+  --auth-mode <mode>       permissive (default) | strict
+  --otp <code>             Default OTP code (default 123456)
+  --persist <file>         Persist state to JSON file
+  --cors <origins>         CORS origins (comma-separated, or '*')
+  --webhook-url <url>      Send mock events to this URL
+  --webhook-secret <key>   HMAC secret for webhook signatures
+  --frozen-at <iso>        Freeze clock at given ISO timestamp
+  --quiet                  Suppress request logs
+`;
+async function main() {
+  const [, , maybeSub, ...rest] = process.argv;
+  const TOP_LEVEL_FLAGS = /* @__PURE__ */ new Set(["--help", "-h", "help", "--version", "-v", "version"]);
+  if (maybeSub && TOP_LEVEL_FLAGS.has(maybeSub)) {
+    return await runDispatcherFlag(maybeSub);
+  }
+  const isFlag = (s) => s?.startsWith("-");
+  const sub = !maybeSub || isFlag(maybeSub) ? "mock" : maybeSub;
+  const args = !maybeSub || isFlag(maybeSub) ? process.argv.slice(2) : rest;
+  switch (sub) {
+    case "mock": {
+      process.argv = [process.argv[0], process.argv[1], ...args];
+      const { fileURLToPath } = await import('url');
+      const { dirname, join } = await import('path');
+      const here = dirname(fileURLToPath(import.meta.url));
+      await import(join(here, "mock", "cli.mjs"));
+      return;
+    }
+    case "init":
+      await runInit(args);
+      return;
+    case "add":
+    case "list": {
+      process.argv = [process.argv[0], process.argv[1], sub, ...args];
+      const { fileURLToPath } = await import('url');
+      const { dirname, join } = await import('path');
+      const here = dirname(fileURLToPath(import.meta.url));
+      await import(join(here, "cli.js"));
+      return;
+    }
+    default:
+      console.error(`cimplify: unknown command "${sub}"`);
+      console.error(`Run \`bunx @cimplify/sdk --help\` for usage.`);
+      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);
+    return;
+  }
+  const { readFileSync } = await import('fs');
+  const { fileURLToPath } = await import('url');
+  const { dirname, join, resolve } = await import('path');
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [join(here, "..", "package.json"), join(here, "..", "..", "package.json"), resolve(here, "package.json")];
+  for (const path of candidates) {
+    try {
+      const pkg = JSON.parse(readFileSync(path, "utf8"));
+      if (pkg.name === "@cimplify/sdk" && pkg.version) {
+        console.log(pkg.version);
+        return;
+      }
+    } catch {
+    }
+  }
+  console.log("unknown");
+}
+main().catch((err) => {
+  console.error("cimplify:", err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cimplify/sdk",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Cimplify Commerce SDK for storefronts",
   "keywords": [
     "cimplify",
@@ -11,12 +11,15 @@
   ],
   "license": "MIT",
   "bin": {
+    "sdk": "dist/dispatcher.mjs",
+    "cimplify": "dist/dispatcher.mjs",
     "cimplify-sdk": "dist/cli.js",
-    "cimplify-mock": "dist/mock/cli.js"
+    "cimplify-mock": "dist/mock/cli.mjs"
   },
   "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,27 @@
+{
+  "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.37.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-router-dom": "^7.9.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.0.0",
+    "concurrently": "^9.0.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.0.0"
+  }
+}

package/templates/storefront/src/App.tsx

@@ -0,0 +1,82 @@
+import { Routes, Route, NavLink, useNavigate } from "react-router-dom";
+import { CataloguePage, CartPage, CheckoutPage, useCimplify } from "@cimplify/sdk/react";
+import type { Product } from "@cimplify/sdk";
+
+function CartPill() {
+  const cim = useCimplify();
+  const total = cim?.cart?.totalItems ?? 0;
+  return <span className="cimplify-storefront__cart-pill">Cart · {total}</span>;
+}
+
+function Catalogue() {
+  const navigate = useNavigate();
+  return (
+    <CataloguePage
+      title="Shop"
+      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() {
+  return (
+    <div className="cimplify-storefront">
+      <header className="cimplify-storefront__nav">
+        <NavLink to="/"><h1>__STOREFRONT_NAME__</h1></NavLink>
+        <nav>
+          <NavLink to="/" end>Shop</NavLink>
+          <NavLink to="/cart">Cart</NavLink>
+          <CartPill />
+        </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,21 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+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 businessId = import.meta.env.VITE_CIMPLIFY_BUSINESS_ID ?? "bus_default_akua_bakery";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <CimplifyProvider config={{ baseUrl, apiKey: "mock-dev", businessId }}>
+        <App />
+      </CimplifyProvider>
+    </BrowserRouter>
+  </React.StrictMode>,
+);

package/templates/storefront/src/styles.css

@@ -0,0 +1,59 @@
+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;
+}

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,10 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    open: true,
+  },
+});