cimplify mock

Boots an in-process Hono server that mirrors the production Cimplify API (~99% parity) with seeded data. The mock is the oracle for testing and local development; every scaffolded storefront wires `bun dev` to start it alongside Next.js.

Usage

The mock storefront API lives in @cimplify/sdk (not @cimplify/cli) because it's tightly coupled to the SDK's domain types and seed data. Boot it via the dedicated cimplify-mock bin after a one-time install, or via bunx with no install.

# Zero-install via bunx
bunx @cimplify/sdk mock                       # default seed, 127.0.0.1:8787
bunx @cimplify/sdk mock --seed retail
bunx @cimplify/sdk mock --seed restaurant

# Or install once
bun add -g @cimplify/sdk
cimplify-mock --seed retail

Seeds

Seed	Use case
`default`	A representative bakery; the default if you omit `--seed`.
`restaurant`	Menu-driven, with reservations + add-ons.
`retail`	Variant-aware retail with full PDPs.
`services`	Bookable services with calendar availability.
`grocery`	High-SKU grocery with quick-add.
`fashion`	Multi-drop fashion with a lookbook.
`reesa-storefront`	Reesa-specific seed for AI / agent demos.
`empty`	A bare business with no products. Useful for onboarding flows.

Flags

Flag	Default	Description
`--port <num>`	`8787`	Listen port.
`--host <host>`	`127.0.0.1`	Bind host. Use `0.0.0.0` to expose on a LAN.
`--seed <name>`	`default`	One of the seeds in the table above.
`--auth-mode <mode>`	`permissive`	`permissive` accepts any token; `strict` enforces real OTP / session checks.
`--otp <code>`	`123456`	Default OTP code accepted by `auth.verifyOtp`.
`--persist <file>`	none	Persist mock state to a JSON file across restarts.
`--cors <origins>`	none	Comma-separated allow-list, or `*` for any origin.
`--webhook-url <url>`	none	POST mock events to this URL.
`--webhook-secret <key>`	none	HMAC secret for webhook signatures.
`--frozen-at <iso>`	now	Freeze the mock's clock at a given ISO timestamp.
`--quiet`	off	Suppress per-request logs.

Examples

Frozen-clock testing

# All time-sensitive flows (slot availability, deal expiry, fx quote ttl) anchor to this point.
cimplify mock \
  --seed retail \
  --frozen-at "2026-06-01T10:00:00Z"

LAN-accessible mock with persistence

cimplify mock \
  --host 0.0.0.0 \
  --port 8787 \
  --seed grocery \
  --persist ./.mock-state.json

Webhook delivery during local development

cimplify mock \
  --seed restaurant \
  --webhook-url http://localhost:3000/api/webhooks \
  --webhook-secret whsec_local_dev

Strict auth + custom OTP

cimplify mock \
  --auth-mode strict \
  --otp 042042

In Next.js dev

Every storefront template wires bun dev to spawn the mock + next dev in parallel. next.config.ts proxies /v1/* to the mock to avoid CORS in the browser.

package.json (excerpt)

{
  "scripts": {
    "dev": "concurrently \"bun run dev:mock\" \"next dev\"",
    "dev:mock": "cimplify mock --seed retail --quiet"
  }
}

Programmatic mock

For unit / integration tests you don't need a separate process; the mock runs in-process via the SDK's first-class fetch injection, parallel-safe and globalThis-free.

A test using @cimplify/sdk/testing

import { createTestClient, fixtures, assertCart } from "@cimplify/sdk/testing";

const h = await createTestClient({ seed: "retail" });
await fixtures.addFirstProduct(h.client);
const cart = await h.client.cart.get();
assertCart(cart);

Where next

Testing harness createTestClient, fixtures, suites.
init Scaffold a storefront wired to the mock.
CLI overview Full subcommand index.