@cimplify/cli 0.15.2 → 0.16.0

package/dist/dev-V7JSUVOI.mjs

@@ -1,8 +0,0 @@
-#!/usr/bin/env node
-export { run as default, detectPackageManager, mergeEnvEntries } from './chunk-F2UI225N.mjs';
-import './chunk-I2UP7YTG.mjs';
-import './chunk-MXYUAJEW.mjs';
-import './chunk-5KYR6WJB.mjs';
-import './chunk-NYXA6X56.mjs';
-import './chunk-MLE4MVYC.mjs';
-import './chunk-3QUK5BPY.mjs';

package/dist/explain-O5AC73EE.mjs

@@ -1,251 +0,0 @@
-#!/usr/bin/env node
-import { package_default } from './chunk-GRR5U2M5.mjs';
-import { parseArgs } from './chunk-5KYR6WJB.mjs';
-import { bold, dim, info, result, CliError, CLI_ERROR_CODE } from './chunk-3QUK5BPY.mjs';
-
-// src/embedded-docs.ts
-var TOPICS = [
-  {
-    "name": "brand",
-    "title": "Brand schema",
-    "description": "Single source of truth for visible strings (lib/brand.ts)",
-    "source_url": "https://cimplify.dev/docs/templates/brand",
-    "body": '## Field reference\n\n      \n        \n\n| Field | Required | Purpose |\n| --- | --- | --- |\n| `name` | yes | Full brand name; used in metadata, header, schema.org Organization |\n| `shortName` | yes | Compact form for tight spots (header, OG, app icons) |\n| `microTag` | yes | Tiny industry label shown beside the wordmark |\n| `description` | yes | Default OG / SEO description (\u2265 20 chars) |\n| `schemaType` | yes | schema.org Organization subtype (`Store`, `Bakery`, \u2026) |\n| `currency` | yes | ISO 4217 (e.g. `GHS`); used by every `formatPrice` |\n| `locale` | yes | BCP-47-ish, e.g. `en_GH` |\n| `contact` | yes | Address, email, phone, hours, country code |\n| `socials[]` | yes | Footer / contact chips with built-in icon keys |\n| `header.nav` | yes | Top nav links (label + href) |\n| `hero` | yes | Home hero: badge, title, subtitle, CTAs |\n| `trustItems?` | no | Hero trust strip (free shipping, warranty, \u2026) |\n| `brandStrip?` | no | "Authorised dealer for\u2026" strip |\n| `promo?` | no | Time-limited banner |\n| `terms` / `privacy` | yes | Standalone policy pages (eyebrow, sections, last updated) |\n| `shipping` / `returns` / `accessibility` | yes | Same shape as terms/privacy |\n| `newsletter` | yes | Footer signup copy |\n| `about` | yes | Eyebrow, title, paragraphs, sections |\n| `faq` | yes | Sectioned Q/A list |\n| `account` | yes | Login, signup, and account page copy for SDK-rendered account routes |\n| `contactPage` | yes | Eyebrow, title, body for `/contact` |\n| `trackOrder` | yes | Copy for the guest order lookup page |\n| `footer` | yes | Sitemap sections, blurb, optional "Powered by" |\n| `llms.summary` | yes | \u2265 20-char blurb that opens the `/llms.txt` index |\n| `mock.seed` | yes | Mock seed name (must match `SeedNameSchema`) |\n| `mock.businessId` | yes | Must start with `bus_` |\n\n      \n\n      \n\n## A complete example\n\n      \n        \n\n```ts title="lib/brand.ts (excerpt: the retail template)"\n\nexport const brand: Brand = {\n  name: "Currents Electronics",\n  shortName: "Currents",\n  microTag: "ELECTRONICS",\n  description:\n    "Authorised dealer for Apple, Samsung, Sony, Bose. Same-day Accra delivery, two-year warranty.",\n  schemaType: "Store",\n  currency: "GHS",\n  locale: "en_GH",\n\n  contact: {\n    email: "hello@currentselectronics.test",\n    phone: "+233 244 000 000",\n    phoneTel: "+233244000000",\n    streetAddress: "Atomic Junction, East Legon",\n    city: "Accra",\n    countryCode: "GH",\n    hours: "Mon\u2013Sat \xB7 9am\u20138pm",\n  },\n\n  socials: [\n    { label: "Instagram", href: "https://instagram.com/currentselectronics", icon: "instagram" },\n    { label: "WhatsApp",  href: "https://wa.me/233244000000",                icon: "whatsapp"  },\n  ],\n\n  header: { nav: [\n    { label: "Shop",   href: "/shop" },\n    { label: "Deals",  href: "/categories/deals" },\n    { label: "Support",href: "/faq" },\n  ]},\n\n  hero: {\n    badge: "LAPTOPS \xB7 PHONES \xB7 AUDIO",\n    title: "The tech you want, in stock today.",\n    subtitle: "Same-day delivery in Accra. Two-year warranty on every product.",\n    primaryCtaLabel: "Shop now",\n    secondaryCtaLabel: "See deals",\n    secondaryCtaHref: "/categories/deals",\n  },\n\n  // \u2026terms, privacy, shipping, returns, accessibility, about, faq, \u2026\n\n  newsletter: {\n    title: "New drops, real prices, in your inbox.",\n    body: "One email a week. No newsletter chaff.",\n    eyebrow: "The shortlist",\n  },\n  account: {\n    loginEyebrow: "Welcome back", loginTitle: "Sign in to Currents",\n    signupEyebrow: "Welcome",     signupTitle: "Create your Currents account",\n    accountEyebrow: "Your account", accountTitle: "Welcome back",\n  },\n  contactPage: { title: "Talk to a real human.", body: "We reply within a business day.", eyebrow: "Contact" },\n  trackOrder:  { title: "Where\'s my order?",     body: "Enter your order number and email.", eyebrow: "Track an order" },\n  footer:      { sitemap: [/* \u2026 */], poweredBy: { label: "Cimplify", href: "https://app.cimplify.io" } },\n  llms:        { summary: "Authorised dealer for Apple, Samsung, Sony, Bose. Two-year warranty." },\n\n  mock: { seed: "retail", businessId: "bus_currents_electronics" },\n};\n```\n\n      \n\n      \n\n## Validation: `assertBrand`\n\n      \n\nTemplates run `assertBrand(brand)` in their `brand.test.ts`. Failures list every offending field with its dot-path; drift between the template and the schema is impossible to ship by accident.\n\n      \n        \n\n```ts title="__tests__/brand.test.ts"\n\ncreateBrandSuite({ brand });\n```\n\n      \n\n      \n\n## Industry-specific extensions\n\n      \n\nNeed fields the base schema doesn\'t have (fashion\'s `lookbook`, services\' `bookingPolicy`)? Extend, don\'t fork. The base shape stays canonical and your custom fields type-check alongside it.\n\n      \n        \n\n```ts title="Extending BrandSchema"\n\nexport const FashionBrandSchema = BrandSchema.extend({\n  lookbook: z.object({\n    eyebrow: z.string(),\n    title: z.string().min(1),\n    drops: z.array(z.object({\n      slug: z.string(),\n      title: z.string(),\n      heroImage: z.string().url(),\n    })),\n  }),\n});\n\nexport type FashionBrand = z.infer<typeof FashionBrandSchema>;\n```\n\n      \n\n      \n\n## Next\n\n      \n        \n- [**Templates overview**](/docs/templates)\n  Six industry templates and what they ship\n\n        \n- [**Customizing**](/docs/templates/customizing)\n  Beyond brand: ejection and schema extensions\n'
-  },
-  {
-    "name": "eject",
-    "title": "Customizing a template",
-    "description": "When and how to eject SDK components into your project",
-    "source_url": "https://cimplify.dev/docs/templates/customizing",
-    "body": '## The customisation tiers\n\n      \n        \n\n| Tier | When | Cost |\n| --- | --- | --- |\n| Edit `brand.ts` | Copy, links, contact, hero, FAQ, policies | Free updates from the SDK forever |\n| Edit `globals.css @theme` | Palette, radius, fonts | Free updates from the SDK forever |\n| `classNames` overrides | Restyle a slot inside an SDK component | Free updates; no fork |\n| Eject a component | Restructure JSX, change behaviour, add merchant logic | You own the file; no auto-updates |\n| Extend `BrandSchema` | Industry-specific fields (lookbook, booking policy) | Type-checked, validated, schema co-evolves |\n\n      \n\n      \n\n## Edit content via `brand.ts`\n\n      \n\nHardcoding a string in a page or component is the wrong move. Hoist it into the brand object first; everything that reads from `brand` stays consistent across pages, sitemap, and metadata.\n\n      \n        \n\n```tsx\n// \u274C wrong: hardcoded in a component\n<h1>Akua\'s Bakery</h1>\n\n// \u2705 right: sourced from the brand contract\n<h1>{brand.hero.title}</h1>\n```\n\n      \n\n      \n\n## Eject a component\n\n      \n\nThe SDK ships ~67 ejectable components in its registry (cards, selectors, full pages, primitives). Eject when a `classNames` override can\'t reach the part you need to change, or when you\'re restructuring beyond what the component\'s props support.\n\n      \n        \n\n```bash\n# Browse the registry\ncimplify list\n\n# Eject one\ncimplify add cart-summary\n# \u2192 writes ./components/cart-summary.tsx, owned by you\n\n# Replace the SDK import in your page\n# import { CartSummary } from "@cimplify/sdk/react"\n# import { CartSummary } from "@/components/cart-summary"\n```\n\n      \n      \n\nOnce ejected, the file is yours. SDK upgrades won\'t touch it; you trade off auto-bugfixes for full control.\n\n      \n        \n\n**Don\'t reinvent the customizer.** Variant selection, add-on math, bundle pricing, and composite mode-switching took many iterations to get right. Eject `variant-selector`, `composite-selector`, `bundle-selector`, or `add-on-selector` and re-style; don\'t rewrite the cart payload contract. See `AGENTS.md` for the full doctrine.\n\n      \n\n      \n\n## Extend the brand schema\n\n      \n\nIndustry-specific fields belong on the schema, not in scattered component props. Use `BrandSchema.extend` so your additions get the same boot-time validation as the canonical fields.\n\n      \n        \n\n```ts title="lib/schema.ts (services template)"\n\nexport const ServicesBrandSchema = BrandSchema.extend({\n  bookingPolicy: z.object({\n    cancellationWindowHours: z.number().int().positive(),\n    depositPercent: z.number().int().min(0).max(100),\n    rescheduleNoticeHours: z.number().int().positive(),\n  }),\n});\n\nexport type ServicesBrand = z.infer<typeof ServicesBrandSchema>;\n```\n\n      \n      \n        \n\n```ts title="lib/brand.ts"\n\nexport const brand: ServicesBrand = {\n  // \u2026all the standard Brand fields\u2026\n  bookingPolicy: {\n    cancellationWindowHours: 24,\n    depositPercent: 25,\n    rescheduleNoticeHours: 12,\n  },\n};\n```\n\n      \n      \n        \n\n```ts title="__tests__/brand.test.ts: assert against the extended schema"\n\ndescribe("brand", () => {\n  it("conforms to the services brand contract", () => {\n    expect(ServicesBrandSchema.safeParse(brand).success).toBe(true);\n  });\n});\n```\n\n      \n\n      \n\n## Add a new section\n\n      \n\n1. Build the section as a Server Component in `components/`.\n2. Read merchant-specific copy from `brand`; extend the schema if the field isn\'t there.\n3. Wrap any client interactivity in a `*-client.tsx` island behind `<Suspense>` to keep the chrome cached.\n4. Compose into the page (`app/page.tsx`, `app/products/[slug]/page.tsx`, \u2026).\n5. Run `bun run check`.\n\n      \n\n## Wire a Server Action\n\n      \n        \n\n```ts\n"use server";\n\nexport async function cancelMyOrder(orderId: string) {\n  const r = await getServerClient().orders.cancel(orderId, "customer requested");\n  if (!r.ok) return { ok: false as const, message: r.error.message };\n\n  await revalidateOrders();\n  return { ok: true as const };\n}\n```\n\n      \n\n      \n\n## Don\'ts\n\n      \n\n- Hardcode strings in pages or components.\n- Enable `cacheComponents: true` in `next.config.ts`. Cache Components (the `\'use cache\'` directive) is still experimental and its runtime constraints don\'t suit hosted storefronts. Stay on the ISR Previous Model the templates ship with.\n- Use `\'use cache\'` / `cacheTag` / `cacheLife` directives. Same reason: they require Cache Components, which we don\'t enable. Use `export const revalidate` per page + `cacheOptions: { revalidate, tags }` on SDK reads.\n- Bypass `getServerClient()` by instantiating `createCimplifyClient` directly in a Server Component; you\'ll lose per-request memoisation.\n\n      \n\n## Next\n\n      \n        \n- [**Brand schema**](/docs/templates/brand)\n  Field reference and a full example\n\n        \n- [**Testing**](/docs/testing)\n  Catch ejections that broke the contract\n'
-  },
-  {
-    "name": "products",
-    "title": "Catalogue \u2014 Single product",
-    "description": "Product shape, single-product fetch, by id or slug",
-    "source_url": "https://cimplify.dev/docs/sdk/catalogue#single-product",
-    "body": "## Single product\nBoth `getProductById` and `getProductBySlug` resolve to the same endpoint; the server accepts either a UUID or a slug.\n\n      \n        \n\n```ts\nconst byId = await client.catalogue.getProductById('prod_xxx')\nconst bySlug = await client.catalogue.getProductBySlug('studio-tee-natural')\n\nif (bySlug.ok) {\n  const product = bySlug.value          // ProductWithDetails\n  console.log(product.id, product.name)\n  console.log(product.variants)\n  console.log(product.add_ons)\n  console.log(product.images)\n}\n```\n"
-  },
-  {
-    "name": "variants",
-    "title": "Catalogue \u2014 Variants",
-    "description": "Variant axes, picking by axis selections",
-    "source_url": "https://cimplify.dev/docs/sdk/catalogue#variants",
-    "body": "## Variants\n```ts\nconst variants = await client.catalogue.getVariants('prod_xxx')\nconst single = await client.catalogue.getVariantById('prod_xxx', 'var_yyy')\n\n// Find a variant by axis selections (size: M, color: blue)\nconst found = await client.catalogue.getVariantByAxisSelections('prod_xxx', {\n  size: 'M',\n  color: 'blue',\n})\n\nif (found.ok && found.value) {\n  console.log(found.value.id, found.value.default_price)\n}\n```\n"
-  },
-  {
-    "name": "bundles",
-    "title": "Catalogue \u2014 Bundles and composites",
-    "description": "Fixed bundles AND configurable composites (same catalogue section)",
-    "source_url": "https://cimplify.dev/docs/sdk/catalogue#bundles-and-composites",
-    "body": "## Bundles and composites\n**Bundles** are fixed product groupings with a single combined price. **Composites** are build-your-own: the customer picks one option per component and the price is computed from those selections.\n\n      \n        \n\n```ts\n// Bundles\nconst bundles = await client.catalogue.getBundles()\nconst bundle = await client.catalogue.getBundleById('bun_xxx')\n\n// Composites\nconst composites = await client.catalogue.getComposites()\nconst composite = await client.catalogue.getCompositeById('comp_xxx')\n\n// Price a composite from a set of selections\nconst price = await client.catalogue.calculateCompositePrice(\n  'comp_xxx',\n  [\n    { component_id: 'comp_base', selected_option_id: 'opt_classic' },\n    { component_id: 'comp_milk', selected_option_id: 'opt_oat' },\n  ],\n  'loc_main',\n)\n```\n"
-  },
-  {
-    "name": "composites",
-    "title": "Catalogue \u2014 Bundles and composites",
-    "description": "Alias of `bundles` \u2014 customer-configurable bundles",
-    "source_url": "https://cimplify.dev/docs/sdk/catalogue#bundles-and-composites",
-    "body": "## Bundles and composites\n**Bundles** are fixed product groupings with a single combined price. **Composites** are build-your-own: the customer picks one option per component and the price is computed from those selections.\n\n      \n        \n\n```ts\n// Bundles\nconst bundles = await client.catalogue.getBundles()\nconst bundle = await client.catalogue.getBundleById('bun_xxx')\n\n// Composites\nconst composites = await client.catalogue.getComposites()\nconst composite = await client.catalogue.getCompositeById('comp_xxx')\n\n// Price a composite from a set of selections\nconst price = await client.catalogue.calculateCompositePrice(\n  'comp_xxx',\n  [\n    { component_id: 'comp_base', selected_option_id: 'opt_classic' },\n    { component_id: 'comp_milk', selected_option_id: 'opt_oat' },\n  ],\n  'loc_main',\n)\n```\n"
-  },
-  {
-    "name": "add-ons",
-    "title": "Catalogue \u2014 Add-ons",
-    "description": "Product add-ons / customizations (gift wrap, engraving, \u2026)",
-    "source_url": "https://cimplify.dev/docs/sdk/catalogue#add-ons",
-    "body": "## Add-ons\n```ts\nconst addOns = await client.catalogue.getAddOns('prod_xxx')\nif (addOns.ok) {\n  for (const group of addOns.value) {\n    console.log(group.name, group.options)\n  }\n}\n```\n"
-  },
-  {
-    "name": "quotes",
-    "title": "Catalogue \u2014 Price quotes",
-    "description": "Price quotes \u2014 quote-first pricing flow before add-to-cart",
-    "source_url": "https://cimplify.dev/docs/sdk/catalogue#price-quotes",
-    "body": "## Price quotes\nWhenever variants, add-ons, bundle picks, or composite picks affect price, fetch a quote first and pass `quote_id` to `cart.addItem`. Quotes have an `expires_at`; refresh if the user dwells.\n\n      \n        \n\n```ts\nconst quote = await client.catalogue.fetchQuote({\n  product_id: 'prod_xxx',\n  variant_id: 'var_yyy',\n  quantity: 2,\n  add_on_option_ids: ['addopt_oat_milk'],\n  location_id: 'loc_main',\n})\n\nif (!quote.ok) {\n  console.error(quote.error.code, quote.error.message)\n  return\n}\n\nawait client.cart.addItem({\n  item_id: 'prod_xxx',\n  quantity: 2,\n  variant_id: 'var_yyy',\n  add_on_options: ['addopt_oat_milk'],\n  quote_id: quote.value.quote_id,\n})\n\n// Refresh an aging quote\nconst refreshed = await client.catalogue.refreshQuote({\n  quote_id: quote.value.quote_id,\n  quantity: 3,\n})\nif (refreshed.ok) {\n  console.log(refreshed.value.quote.quote_id)\n}\n```\n"
-  },
-  {
-    "name": "discounts",
-    "title": "Catalogue \u2014 Discounts",
-    "description": "Deals and promotional pricing",
-    "source_url": "https://cimplify.dev/docs/sdk/catalogue#discounts",
-    "body": "## Discounts\nValidate a code at the line / subtotal level before applying it to the cart. Order subtotal is passed as a `Money` string.\n\n      \n        \n\n```ts\nconst r = await client.catalogue.validateDiscountCode('WELCOME10', '49.99', 'loc_main')\nif (r.ok) {\n  console.log(r.value.is_valid, r.value.discount_amount)\n}\n```\n"
-  },
-  {
-    "name": "cart",
-    "title": "Cart",
-    "description": "Flat add-to-cart payload + quote-then-add flow",
-    "source_url": "https://cimplify.dev/docs/sdk/cart",
-    "body": "## Add an item\n\n      \n\nThe add-to-cart payload is **flat**. There is no nested `configuration` wrapper and no `productId` field; everything sits at the top of the body.\n\n      \n        \n\n```ts\nconst added = await client.cart.addItem({\n  item_id: 'prod_studio-tee-natural',\n  quantity: 1,\n  variant_id: 'var_studio-tee-natural_size_s',\n  add_on_options: ['addopt_gift_wrap'],\n  special_instructions: 'Please ship without invoice.',\n})\n\nif (!added.ok) {\n  console.error(added.error.code, added.error.message)\n  return\n}\n\nconsole.log(added.value.cart.id)\n```\n\n      \n\n      \n\n## Read the cart\n\n      \n        \n\n```ts\n\nconst r = await client.cart.get()\nif (!r.ok) return\n\nconst cart = r.value\nconsole.log(cart.items.length)\nconsole.log(cart.pricing.currency)               // \"GHS\"\nconsole.log(cart.pricing.subtotal)               // Money (branded string)\nconsole.log(cart.pricing.total_price)            // Money\n\n// Money is a string. Always parse before math, format before display.\nconst subtotal = parsePrice(cart.pricing.subtotal)\nif (subtotal !== 0) {\n  console.log(formatPrice(subtotal, cart.pricing.currency)) // \"GH\u20B529.99\"\n}\n```\n\n      \n\n      \n\n## Update quantity / remove / clear\n\n      \n        \n\n```ts\n// You need the cart-item id from cart.items[i].id (NOT the product id)\nawait client.cart.updateQuantity('ci_xxx', 3)\nawait client.cart.removeItem('ci_xxx')\nawait client.cart.clear()\n```\n\n      \n\n      \n\n## Coupons\n\n      \n        \n\n```ts\nconst apply = await client.cart.applyCoupon('WELCOME10')\nif (!apply.ok) {\n  // Codes you'll see: COUPON_INVALID, COUPON_EXPIRED, COUPON_MIN_NOT_MET\n  console.error(apply.error.code)\n}\n\nawait client.cart.removeCoupon()\n\n// Custom idempotency key (otherwise the SDK auto-generates one)\nawait client.cart.applyCoupon('WELCOME10', { idempotencyKey: 'apply-welcome10-once' })\n```\n\n      \n\n      \n\n## Convenience reads\n\n      \n        \n\n```ts\nconst count = await client.cart.getCount()                      // Result<number>\nconst total = await client.cart.getTotal()                      // Result<string>\nconst items = await client.cart.getItems()                      // Result<CartItem[]>\nconst summary = await client.cart.getSummary()                  // Result<CartSummary>\nconst empty = await client.cart.isEmpty()                       // Result<boolean>\nconst has = await client.cart.hasItem('prod_xxx', 'var_yyy')    // Result<boolean>\nconst found = await client.cart.findItem('prod_xxx', 'var_yyy') // Result<CartItem | undefined>\n```\n\n      \n\n      \n\n## Reorder from a past order\n\n      \n\nWalks every line item on the order and adds it to the current cart. Returns added/failed lists; partial success is normal (e.g. a discontinued variant).\n\n      \n        \n\n```ts\nconst r = await client.cart.reorderFromOrder('ord_xxx')\nif (!r.ok) return\n\nconsole.log(r.value.added)   // [{ item_id }, ...]\nconsole.log(r.value.failed)  // [{ item_id, error: CimplifyError }, ...]\n```\n\n      \n\n      \n\n## addItem payload\n\n      \n        \n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `item_id` | `string` | Required. Product ID. |\n| `quantity` | `number` | Required. |\n| `variant_id` | `string` | Selected variant. |\n| `add_on_options` | `string[]` | Selected add-on option IDs. |\n| `special_instructions` | `string` | Free-form note. |\n| `bundle_selections` | `BundleSelection[]` | Required when item is a bundle. |\n| `composite_selections` | `CompositeSelection[]` | Required when item is a composite. |\n| `quote_id` | `string` | Pre-computed quote from `catalogue.fetchQuote`. Locks the price. |\n\n      \n\n      \n\n## Method reference\n\n      \n        \n\n| Method | Returns |\n| --- | --- |\n| `get()` | `Result<UICart>` |\n| `getItems()` | `Result<CartItem[]>` |\n| `getCount()` | `Result<number>` |\n| `getTotal()` | `Result<string>` |\n| `getSummary()` | `Result<CartSummary>` |\n| `addItem(input, opts?)` | `Result<CartMutationResult>` |\n| `updateQuantity(cartItemId, qty)` | `Result<CartMutationResult>` |\n| `removeItem(cartItemId)` | `Result<CartMutationResult>` |\n| `clear()` | `Result<CartMutationResult>` |\n| `applyCoupon(code, opts?)` | `Result<CartMutationResult>` |\n| `removeCoupon()` | `Result<CartMutationResult>` |\n| `reorderFromOrder(orderId)` | `Result<ReorderResult>` |\n| `isEmpty()` | `Result<boolean>` |\n| `hasItem(productId, variantId?)` | `Result<boolean>` |\n| `findItem(productId, variantId?)` | `Result<CartItem \\| undefined>` |\n\n      \n\n      \n\n## Related\n\n      \n        \n- [**Catalogue**](/docs/sdk/catalogue)\n  Fetch products and price quotes before adding\n\n        \n- [**Checkout**](/docs/sdk/checkout)\n  Convert the cart into a paid order\n\n        \n- [**Scheduling**](/docs/sdk/scheduling)\n  Pick a slot for service bookings before checkout\n\n        \n- [**Money type**](/docs/concepts/money)\n  parsePrice / formatPrice for cart totals\n"
-  },
-  {
-    "name": "checkout",
-    "title": "Checkout",
-    "description": "Flat ProcessArgs body for /checkout, payment methods",
-    "source_url": "https://cimplify.dev/docs/sdk/checkout",
-    "body": "`client.purchaseIntents` is the checkout authority. Minting creates a durable\nPurchaseIntent and immutable terms; it does **not** create an Order. Confirmation\ncreates the Order only after the server revalidates the accepted terms, source,\ninventory, funding allocation, and opaque payment option.\n\n## Mint Cart terms\n\n```ts\n  MOBILE_MONEY_TENDER_AUTHORITY_KIND,\n  ORDER_TYPE,\n  PURCHASE_INTENT_PAYMENT_METHOD,\n  PURCHASE_INTENT_MOBILE_MONEY_NETWORK,\n  PURCHASE_INTENT_SOURCE_KIND,\n} from '@cimplify/sdk'\n\nconst minted = await client.purchaseIntents.mint({\n  client_intent_key: crypto.randomUUID(),\n  source: {\n    kind: PURCHASE_INTENT_SOURCE_KIND.CART,\n    cart_id: cart.id,\n  },\n  checkout: {\n    customer: {\n      name: 'Jane Doe',\n      email: 'jane@example.com',\n      phone: '+233244000000',\n      save_details: false,\n    },\n    order_type: ORDER_TYPE.PICKUP,\n    address_info: { pickup_time: '2026-08-23T15:00:00Z' },\n    tender_preference: {\n      method_kind: PURCHASE_INTENT_PAYMENT_METHOD.MOBILE_MONEY,\n      authority: {\n        authority_kind: MOBILE_MONEY_TENDER_AUTHORITY_KIND.TRANSIENT,\n        phone_number: '+233244000000',\n        network: PURCHASE_INTENT_MOBILE_MONEY_NETWORK.MTN,\n      },\n    },\n  },\n})\n\nif (!minted.ok) throw minted.error\nif (!minted.value.current_terms) throw new Error('Checkout terms are not prepared')\n```\n\nThe server derives seller and owner authority from the authenticated client. Do not\nsend a business, account, staff-session, or hosted-session owner in the body.\n\nFor a saved Mobile Money authority, send only the opaque ID:\n\n```ts\nconst tenderPreference = {\n  method_kind: PURCHASE_INTENT_PAYMENT_METHOD.MOBILE_MONEY,\n  authority: {\n    authority_kind: MOBILE_MONEY_TENDER_AUTHORITY_KIND.SAVED_REFERENCE,\n    stored_instrument_id: savedMobileMoney.id,\n  },\n} as const\n```\n\nThe server independently verifies ownership and derives its network. Never pair a\nsaved reference with a phone number.\n\n## Review one exact option\n\n```ts\n\nconst terms = minted.value.current_terms\nconst option = selectPurchaseIntentPaymentOption(terms, {\n  method_kind: PURCHASE_INTENT_PAYMENT_METHOD.MOBILE_MONEY,\n})\n\nif (!option) throw new Error('The selected payment method is unavailable')\n\nrenderPaymentReview({\n  commercePrincipal: option.principal_amount,\n  collectionFee: option.fee_amount,\n  customerDebit: option.customer_debit_amount,\n  currency: option.currency,\n})\n```\n\nThe exact equations are:\n\n```text\nstore_credit_consumed + voucher_credit_consumed + rail_amount = due_now\nprincipal_amount + fee_amount = customer_debit_amount\n```\n\nFunding allocations belong to the accepted terms. Payment options collect only the\nresidual principal and their own provider/offline fee. Do not display one top-level\npayment fee: different options may have different fees.\n\n## Confirm reviewed terms\n\n```ts\n  PURCHASE_INTENT_CONFIRM_STATUS,\n  createPurchaseIntentConfirmation,\n} from '@cimplify/sdk'\n\nconst confirmation = createPurchaseIntentConfirmation(\n  terms,\n  option,\n  crypto.randomUUID(),\n)\nconst confirmed = await client.purchaseIntents.confirm(\n  minted.value.id,\n  confirmation,\n)\nif (!confirmed.ok) throw confirmed.error\n\nswitch (confirmed.value.status) {\n  case PURCHASE_INTENT_CONFIRM_STATUS.ORDER_CREATED:\n    showOrder(confirmed.value.order_id, confirmed.value.order_number)\n    break\n  case PURCHASE_INTENT_CONFIRM_STATUS.TERMS_CHANGED:\n    showTermsReview(confirmed.value.replacement, confirmed.value.deltas)\n    break\n  case PURCHASE_INTENT_CONFIRM_STATUS.SELECTION_UNAVAILABLE:\n    showUnavailableLines(confirmed.value.lines)\n    break\n  case PURCHASE_INTENT_CONFIRM_STATUS.PAYMENT_FAILED:\n    showDeclinedPayment()\n    break\n  default:\n    handleProviderOrRecoveryState(confirmed.value)\n}\n```\n\n`createPurchaseIntentConfirmation` binds the current intent revision, terms version,\ndue-now value, currency, selected option ID, and its exact\n`customer_debit_amount`. A true zero-rail purchase is the only case that can confirm\nwithout an option.\n\n## Resolve provider actions and replay\n\n`resolve` drives the canonical confirm/action/poll loop while keeping one durable\nattempt authority:\n\n```ts\n  CHECKOUT_NEXT_ACTION,\n  PAYMENT_AUTHORIZATION_OUTCOME_STATUS,\n  PURCHASE_INTENT_ACTION_DECISION,\n  PURCHASE_INTENT_CONFIRM_STATUS,\n} from '@cimplify/sdk'\n\nconst resolution = await client.purchaseIntents.resolve(minted.value.id, {\n  confirmation,\n  onActionRequired: async (action) => {\n    if (action.status === PURCHASE_INTENT_CONFIRM_STATUS.REDIRECT_REQUIRED) {\n      window.location.assign(action.authorization_url)\n      return PURCHASE_INTENT_ACTION_DECISION.STOP\n    }\n\n    if (action.status === PURCHASE_INTENT_CONFIRM_STATUS.CARD_POPUP_REQUIRED) {\n      const outcome = await client.checkout.authorizeCardPopup({\n        type: CHECKOUT_NEXT_ACTION.CARD_POPUP,\n        provider: action.provider,\n        client_secret: action.client_secret,\n        public_key: action.public_key,\n        provider_account_id: action.provider_account_id ?? undefined,\n      })\n      return outcome.status === PAYMENT_AUTHORIZATION_OUTCOME_STATUS.SUBMITTED\n        ? PURCHASE_INTENT_ACTION_DECISION.CONTINUE\n        : PURCHASE_INTENT_ACTION_DECISION.STOP\n    }\n\n    const authorization = await collectAuthorization(action.authorization_type)\n    return {\n      kind: PURCHASE_INTENT_ACTION_DECISION.SUBMIT,\n      request: { authorization },\n    }\n  },\n})\n```\n\nKeep the same confirmation idempotency key after an ambiguous response. A definitive\ndecline or an explicitly accepted replacement terms version starts a new attempt key.\nPersist only opaque intent, attempt, terms, option, and idempotency authorities for\nbrowser recovery\u2014never customer contact, address, voucher, note, or raw tender data,\nand never a hash of low-entropy PII.\n\n## Hosted checkout\n\nHosted PurchaseIntents belong to the CheckoutSession, not the storefront API session:\n\n```ts\nconst hosted = client.purchaseIntents.forHostedSession(sessionId)\nconst prepared = await hosted.prepare({\n  expected_intent_revision: 0,\n  idempotency_key: crypto.randomUUID(),\n  checkout,\n})\n\nif (!prepared.ok || !prepared.value.current_terms) {\n  throw prepared.ok ? new Error('Terms unavailable') : prepared.error\n}\n\nconst result = await hosted.resolve(prepared.value.id, {\n  confirmation: createPurchaseIntentConfirmation(\n    prepared.value.current_terms,\n    selectPurchaseIntentPaymentOption(prepared.value.current_terms, tender) ?? null,\n    crypto.randomUUID(),\n  ),\n})\n```\n\nUse the hosted service for prepare, confirm, replay, and action submission. An intent\nID is the durable resource ID, but it does not replace the hosted session's owner\nauthority.\n\n## Compatibility adapter\n\n`client.checkout.process()` remains a deprecated SDK adapter over purchase-intent\nroutes for one migration window. New integrations should use\n`client.purchaseIntents` so terms review, per-option fees, attempt replay, and hosted\nownership remain explicit. The backend `/api/v1/checkout` endpoint no longer exists,\nand new checkout responses do not issue legacy Order bill tokens.\n\nThe deprecated `client.checkout.submitAuthorization()` method is fail-closed. It\ncan submit an action only when the same in-memory `CheckoutService` instance has\njust received the matching `payment_id`, `intent_id`, and `attempt_id` from\n`process()`. The SDK sends the authorization to the owner-fenced purchase-intent\nattempt action route; it never falls back to the legacy payment-id authorization\nmutation. After a reload, use the durable purchase-intent replay/action API instead.\n\n- [**Checkout Elements**](/docs/checkout/elements)\n  Use the hosted UI and its `reviewing_terms` state.\n\n- [**Orders**](/docs/sdk/orders)\n  Read the committed Order after `order_created`.\n"
-  },
-  {
-    "name": "orders",
-    "title": "Orders",
-    "description": "Order shape and status flow",
-    "source_url": "https://cimplify.dev/docs/sdk/orders",
-    "body": "`client.orders.list()` returns different results depending on how the\nclient was constructed:\n\n- **Guest client** (`getServerClient()` with no `accessToken`, or the\n  browser `cimplify` client with no signed-in shopper): returns nothing\n  by default; the API has no customer to scope to. `client.orders.get()`\n  may still use a previously cached historical Order token for its original\n  pre-convergence order. New purchase-intent checkout does not issue one.\n- **Authenticated client** (`getAuthenticatedServerClient()` from the\n  templates, or `getServerClient({ accessToken })` from a custom integration):\n  returns *that customer's* orders at *this merchant*.\n\nSee [Sign in with Cimplify \u2192 Personalized server-side reads](/docs/sdk/auth#personalized-server-side-reads)\nfor the full setup.\n\n## Render orders for the signed-in shopper\n\n```tsx title=\"app/account/orders/page.tsx\"\n\nexport const revalidate = 0; // personalized; do not ISR-cache\n\nexport default async function OrdersPage() {\n  const client = await getAuthenticatedServerClient();\n  const r = await client.orders.list({ limit: 20 });\n  if (!r.ok) throw new Error(r.error.message);\n\n  if (r.value.length === 0) {\n    return <p>No orders yet.</p>;\n  }\n  return (\n    <ul>\n      {r.value.map((o) => (\n        <li key={o.id}>#{o.order_number} \xB7 {o.status} \xB7 {o.total_price}</li>\n      ))}\n    </ul>\n  );\n}\n```\n\nIf `cimplify_access` is missing (signed-out shopper), `client.orders.list()`\nreturns the empty guest view. Branch on `getSession()` from `lib/auth.ts`\nif you want to redirect to sign-in instead.\n\n## List orders\n\n      \n        \n\n```ts\nconst r = await client.orders.list({ limit: 20 })\nif (!r.ok) {\n  console.error(r.error.code, r.error.message)\n  return\n}\n\nconsole.log(r.value.length)\nfor (const order of r.value) {\n  console.log(order.id, order.order_number, order.status)\n}\n```\n\n      \n\n      \n\n## Filter by status\n\n      \n        \n\n```ts\nconst pending = await client.orders.list({ status: 'pending' })\nconst completed = await client.orders.list({ status: 'completed', limit: 50 })\n\n// Convenience wrappers\nconst recent = await client.orders.getRecent(5)             // last 5\nconst cancelled = await client.orders.getByStatus('cancelled')\n```\n\n      \n\n      \n\n## Get a single order\n\n      \n\nAuthenticated and recognised shoppers read the Order created by a confirmed purchase intent through their existing owner/session authority. The SDK still appends a cached historical Order token when one already exists, solely so old orders remain readable during the compatibility window.\n\n      \n        \n\n```ts\n\nconst r = await client.orders.get('ord_xxx')\nif (!r.ok) return\n\nconst order = r.value\nconsole.log(order.status)\nconsole.log(order.items.length)\nconsole.log(order.total_price)                       // Money string\nconsole.log(formatPrice(parsePrice(order.total_price), order.currency))\n```\n\n      \n\n      \n\n## Cancel an order\n\n      \n        \n\n```ts\nconst cancelled = await client.orders.cancel('ord_xxx', 'changed_mind')\nif (!cancelled.ok) {\n  // Codes you'll see: ORDER_NOT_CANCELLABLE, ORDER_ALREADY_FULFILLED\n  console.error(cancelled.error.code, cancelled.error.message)\n}\n\n// Idempotent retry: same key, same outcome on the server\nawait client.orders.cancel('ord_xxx', 'changed_mind', {\n  idempotencyKey: 'cancel-ord_xxx-once',\n})\n```\n\n      \n\n      \n\n## Order status values\n\n      \n        \n\n| Status | Meaning |\n| --- | --- |\n| `pending` | Created, awaiting payment confirmation |\n| `confirmed` | Accepted by the business |\n| `preparing` | Being assembled or fulfilled |\n| `ready` | Ready for pickup or delivery dispatch |\n| `completed` | Fulfilled; terminal state |\n| `cancelled` | Cancelled; terminal state |\n| `refunded` | Payment refunded |\n\n      \n\n      \n\n## Poll until terminal\n\n      \n        \n\n```ts\nasync function pollUntilTerminal(orderId: string, intervalMs = 5000) {\n  for (;;) {\n    const r = await client.orders.get(orderId)\n    if (!r.ok) return r\n\n    const status = r.value.status\n    if (status === 'completed' || status === 'cancelled' || status === 'refunded') {\n      return r\n    }\n\n    await new Promise((resolve) => setTimeout(resolve, intervalMs))\n  }\n}\n```\n\n      \n\n      \n\n## Method reference\n\n      \n        \n\n| Method | Returns |\n| --- | --- |\n| `list({ status?, limit?, offset? })` | `Result<Order[]>` |\n| `get(orderId)` | `Result<Order>` |\n| `cancel(orderId, reason?, opts?)` | `Result<Order>` |\n| `getRecent(limit?)` | `Result<Order[]>` |\n| `getByStatus(status)` | `Result<Order[]>` |\n\n      \n\n      \n\n## Related\n\n      \n        \n- [**Checkout**](/docs/sdk/checkout)\n  Create the orders that this page lists\n\n        \n- [**Subscriptions**](/docs/sdk/subscriptions)\n  For recurring orders, see the subscription surface\n\n        \n- [**Scheduling**](/docs/sdk/scheduling)\n  Reschedule or cancel a booking line item\n\n        \n- [**Error handling**](/docs/sdk/errors)\n  Cancellation guards and retryable errors\n"
-  },
-  {
-    "name": "subscriptions",
-    "title": "Subscriptions",
-    "description": "Recurring billing, plan changes, cancellation",
-    "source_url": "https://cimplify.dev/docs/sdk/subscriptions",
-    "body": "## List subscriptions\n\n      \n        \n\n```ts\nconst r = await client.subscriptions.list()\nif (!r.ok) {\n  console.error(r.error.code, r.error.message)\n  return\n}\n\nfor (const sub of r.value) {\n  console.log(sub.id, sub.status, sub.next_billing_at)\n}\n```\n\n      \n\n      \n\n## Get a single subscription\n\n      \n        \n\n```ts\nconst r = await client.subscriptions.get('sub_xxx')\nif (!r.ok) return\n\nconst sub = r.value // SubscriptionWithDetails\nconsole.log(sub.plan)\nconsole.log(sub.items)\nconsole.log(sub.recent_invoices)\n```\n\n      \n\n      \n\n## Pause / resume\n\n      \n\nPausing freezes future renewals indefinitely; resuming reactivates without re-running checkout.\n\n      \n        \n\n```ts\nawait client.subscriptions.pause('sub_xxx')\n// ...later\nawait client.subscriptions.resume('sub_xxx')\n```\n\n      \n\n      \n\n## Skip the next renewal\n\n      \n        \n\n```ts\nconst r = await client.subscriptions.skipNextRenewal('sub_xxx', {\n  idempotencyKey: 'skip-sub_xxx-2026-05', // optional\n})\n\nif (!r.ok) {\n  console.error(r.error.code, r.error.message)\n  return\n}\n\nconsole.log(r.value.success)\n```\n\n      \n\n      \n\n## Cancel\n\n      \n\nCancellation is terminal; the subscription cannot be resumed. Pass a reason for analytics.\n\n      \n        \n\n```ts\nconst r = await client.subscriptions.cancel('sub_xxx', 'too_expensive', {\n  idempotencyKey: 'cancel-sub_xxx-once', // optional\n})\n\nif (!r.ok) {\n  // Codes you'll see: SUBSCRIPTION_NOT_FOUND, ALREADY_CANCELLED\n  console.error(r.error.code, r.error.message)\n}\n```\n\n      \n\n      \n\n## Method reference\n\n      \n        \n\n| Method | Returns |\n| --- | --- |\n| `list()` | `Result<Subscription[]>` |\n| `get(id)` | `Result<SubscriptionWithDetails>` |\n| `pause(id)` | `Result<{ success: boolean }>` |\n| `resume(id)` | `Result<{ success: boolean }>` |\n| `skipNextRenewal(id, opts?)` | `Result<{ success: boolean }>` |\n| `cancel(id, reason?, opts?)` | `Result<{ success: boolean }>` |\n\n      \n\n      \n\n## Related\n\n      \n        \n- [**Checkout**](/docs/sdk/checkout)\n  Subscriptions are created at checkout time\n\n        \n- [**Orders**](/docs/sdk/orders)\n  Each renewal becomes a new order\n\n        \n- [**Auth**](/docs/sdk/auth)\n  Subscriptions require an authenticated customer\n\n        \n- [**Error handling**](/docs/sdk/errors)\n  ALREADY_CANCELLED, SUBSCRIPTION_NOT_FOUND\n"
-  },
-  {
-    "name": "services",
-    "title": "Scheduling \u2014 List services",
-    "description": "Bookable services + variant-aware availability",
-    "source_url": "https://cimplify.dev/docs/sdk/scheduling#list-services",
-    "body": "## List services\n```ts\nconst r = await client.scheduling.getServices()\nif (!r.ok) {\n  console.error(r.error.code, r.error.message)\n  return\n}\n\nfor (const service of r.value) {\n  console.log(service.id, service.name, service.duration_minutes)\n}\n\nconst single = await client.scheduling.getService('svc_xxx')\n```\n"
-  },
-  {
-    "name": "bookings",
-    "title": "Scheduling \u2014 Get available slots (variant-aware)",
-    "description": "Picking slots, creating bookings, reschedule and cancel",
-    "source_url": "https://cimplify.dev/docs/sdk/scheduling#get-available-slots-variant-aware",
-    "body": "## Get available slots (variant-aware)\nPass `variant_id` when the service has variants; slot times and capacities depend on which variant the customer is booking.\n\n      \n        \n\n```ts\nconst r = await client.scheduling.getAvailableSlots({\n  service_id: 'svc_haircut',\n  date: '2026-05-08',\n  variant_id: 'var_haircut_premium', // 60-minute variant\n  participant_count: 1,\n})\n\nif (!r.ok) return\n\nfor (const slot of r.value) {\n  console.log(slot.start_time, slot.end_time, slot.capacity_available)\n  console.log(slot.available_staff)\n}\n```\n"
-  },
-  {
-    "name": "errors",
-    "title": "Errors",
-    "description": "CimplifyError codes and remediation",
-    "source_url": "https://cimplify.dev/docs/sdk/errors",
-    "body": "## Result type\n\n      \n        \n\n```ts\ntype Result<T, E = CimplifyError> =\n  | { ok: true; value: T }\n  | { ok: false; error: E }\n```\n\n      \n\n      \n\n## CimplifyError\n\n      \n        \n\n```ts\n\nclass CimplifyError {\n  code: string                          // 'VALIDATION_ERROR', 'NOT_FOUND', 'RATE_LIMITED', ...\n  message: string                       // human-readable\n  retryable?: boolean                   // safe to retry?\n  context?: Record<string, unknown>     // structured details (field name, validation rule, ...)\n}\n```\n\n      \n\n      \n\n## Read errors\n\n      \n        \n\n```ts\nconst r = await client.catalogue.getProducts()\n\nif (!r.ok) {\n  console.error(r.error.code)        // machine-readable\n  console.error(r.error.message)     // human-readable\n  console.error(r.error.retryable)   // boolean\n  console.error(r.error.context)     // optional structured detail\n  return\n}\n\nconsole.log(r.value.items)\n```\n\n      \n\n      \n\n## Branch on code\n\n      \n        \n\n```ts\nconst r = await client.cart.addItem({ item_id: 'prod_xxx', quantity: 1 })\n\nif (!r.ok) {\n  switch (r.error.code) {\n    case 'OUT_OF_STOCK':\n      showToast('This item is out of stock')\n      break\n    case 'ITEM_UNAVAILABLE':\n      showToast('No longer available')\n      break\n    case 'VALIDATION_ERROR':\n      showToast(r.error.message)\n      break\n    case 'RATE_LIMITED':\n      showToast('Slow down; try again in a moment')\n      break\n    default:\n      showToast(r.error.message)\n  }\n}\n```\n\n      \n\n      \n\n## Retry helper\n\n      \n\nOnly retry when the server has marked the error `retryable`. Use exponential backoff and a small attempt cap.\n\n      \n        \n\n```ts\n\nasync function withRetry<T>(\n  fn: () => Promise<Result<T>>,\n  maxAttempts = 3,\n): Promise<Result<T>> {\n  let last!: Result<T>\n  for (let i = 0; i < maxAttempts; i++) {\n    last = await fn()\n    if (last.ok) return last\n    if (!last.error.retryable) return last\n    await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** i))\n  }\n  return last\n}\n\nconst r = await withRetry(() => client.catalogue.getProducts({ limit: 24 }))\n```\n\n      \n\n      \n\n## Common error codes\n\n      \n        \n\n| Code | Retryable | Meaning |\n| --- | --- | --- |\n| `VALIDATION_ERROR` | No | Bad input; fix the request |\n| `NOT_FOUND` | No | Resource missing or filtered out |\n| `UNAUTHORIZED` | No | Sign in / refresh the session |\n| `FORBIDDEN` | No | Authenticated but not allowed |\n| `RATE_LIMITED` | Yes | Back off and retry |\n| `NETWORK_ERROR` | Yes | Transport failed before response |\n| `TIMEOUT` | Yes | Server did not respond in time |\n| `SERVER_ERROR` | Yes | Generic 5xx |\n\n      \n\n      \n\n## Checkout-specific codes\n\n      \n        \n\n| Code | Recoverable | Meaning |\n| --- | --- | --- |\n| `INVALID_CART` | No | Cart is empty or no longer valid |\n| `ALREADY_PROCESSING` | No | A checkout for this cart is already in flight |\n| `PAYMENT_FAILED` | Yes | Provider declined; let the user retry |\n| `FX_QUOTE_FAILED` | Yes | Could not lock an FX quote for the pay currency |\n| `AUTH_INCOMPLETE` | Yes | Customer must finish OTP / PIN authorization |\n| `AUTH_LOST` | Yes | Session expired mid-checkout |\n| `CHECKOUT_FAILED` | Sometimes | Generic terminal failure; read message + retryable |\n\n      \n\n      \n\n## Schema-shape errors (testing only)\n\n      \n\nInside the testing harness, `assertX` helpers throw `SchemaViolationError` with structured `issues[]`. This is the only place the SDK throws.\n\n      \n        \n\n```ts\n\ntry {\n  assertCart(response)\n} catch (e) {\n  if (e instanceof SchemaViolationError) {\n    console.error(e.toJSON()) // RFC 7807 + structured issues[]\n  }\n}\n```\n\n      \n\n      \n\n## Related\n\n      \n        \n- [**Result&lt;T, E&gt;**](/docs/concepts/result)\n  Why methods never throw, how to narrow\n\n        \n- [**Idempotency**](/docs/concepts/idempotency)\n  Safe retries for write methods\n\n        \n- [**Checkout**](/docs/sdk/checkout)\n  Where most error codes show up\n\n        \n- [**Auth**](/docs/sdk/auth)\n  UNAUTHORIZED + AUTH_LOST recovery\n"
-  },
-  {
-    "name": "uploads",
-    "title": "Uploads",
-    "description": "Presigned upload flow: init \u2192 PUT \u2192 confirm",
-    "source_url": "https://cimplify.dev/docs/sdk/uploads",
-    "body": "## Upload a File (sugar)\n\n      \n        \n\n```ts\nasync function handleFile(file: File) {\n  const r = await client.uploads.upload(file)\n  if (!r.ok) {\n    console.error(r.error.code, r.error.message)\n    return\n  }\n\n  console.log(r.value.id, r.value.url)\n  console.log(r.value.filename, r.value.content_type, r.value.size_bytes)\n}\n```\n\n      \n\n      \n\n## Step-by-step (when you need control)\n\n      \n\nUse the explicit form when you want to show progress, retry the PUT independently, or upload bytes from a non-File source (Blob, stream, etc.).\n\n      \n        \n\n```ts\n// 1. Init: get a presigned URL\nconst init = await client.uploads.init(file.name, file.type, file.size, {\n  idempotencyKey: 'upload-' + file.name + '-' + file.size, // optional\n})\nif (!init.ok) {\n  console.error(init.error.code, init.error.message)\n  return\n}\n\nconst { upload_id, upload_url, expires_in_secs } = init.value\n\n// 2. PUT the bytes directly to storage\nconst put = await fetch(upload_url, {\n  method: 'PUT',\n  body: file,\n  headers: { 'Content-Type': file.type },\n})\n\nif (!put.ok) {\n  console.error('PUT failed', put.status)\n  return\n}\n\n// 3. Confirm: server validates and indexes\nconst confirmed = await client.uploads.confirm(upload_id)\nif (!confirmed.ok) return\n\nconsole.log(confirmed.value.id, confirmed.value.url)\n```\n\n      \n\n      \n\n## React: a drop zone\n\n      \n        \n\n```tsx\n'use client'\n\nexport function DropZone({ onUploaded }: { onUploaded: (result: UploadResult) => void }) {\n  const client = useCimplifyClient()\n  const [status, setStatus] = useState<'idle' | 'uploading' | 'error'>('idle')\n\n  async function pick(e: React.ChangeEvent<HTMLInputElement>) {\n    const file = e.target.files?.[0]\n    if (!file) return\n\n    setStatus('uploading')\n    const r = await client.uploads.upload(file)\n    if (!r.ok) {\n      setStatus('error')\n      return\n    }\n\n    setStatus('idle')\n    onUploaded(r.value)\n  }\n\n  return (\n    <label>\n      <input type=\"file\" onChange={pick} />\n      <span>{status === 'uploading' ? 'Uploading\u2026' : 'Choose a file'}</span>\n    </label>\n  )\n}\n```\n\n      \n\n      \n\n## UploadResult shape\n\n      \n        \n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `id` | `string` | Stable upload id |\n| `url` | `string` | Public, durable URL |\n| `filename` | `string` | Original filename |\n| `content_type` | `string` | MIME |\n| `size_bytes` | `number` |   |\n\n      \n\n      \n\n## Method reference\n\n      \n        \n\n| Method | Returns |\n| --- | --- |\n| `init(filename, contentType, sizeBytes, opts?)` | `Result<UploadInitResponse>` |\n| `confirm(uploadId)` | `Result<UploadResult>` |\n| `upload(file)` | `Result<UploadResult>` |\n\n      \n\n      \n\n## Related\n\n      \n        \n- [**Support**](/docs/sdk/support)\n  Attach uploads to chat messages\n\n        \n- [**Auth**](/docs/sdk/auth)\n  Profile photo via `updateProfile`\n\n        \n- [**Error handling**](/docs/sdk/errors)\n  UPLOAD_FAILED is retryable\n\n        \n- [**Idempotency**](/docs/concepts/idempotency)\n  Replay-safe upload init\n"
-  },
-  {
-    "name": "assets",
-    "title": "Assets",
-    "description": "Storefront brand assets \u2014 upload to CDN, build URLs, render through next/image",
-    "source_url": "https://cimplify.dev/docs/sdk/assets",
-    "body": 'The asset surface on the SDK is **read-side only**: building URLs for images you\'ve already uploaded via [`cimplify assets upload`](/docs/cli/assets). Customer-runtime uploads still go through `client.uploads.upload(file)`.\n\n## `assetUrl(path, opts?)`\n\nPure URL builder. Prepends the CDN base for relative paths, passes absolute URLs through with the transform query contract appended.\n\n```ts\n\nassetUrl("hero/main.jpg")\n// "https://storefrontassetscdn.cimplify.io/hero/main.jpg"\n\nassetUrl("hero/main.jpg", { w: 1200, format: "webp", quality: 80 })\n// "https://storefrontassetscdn.cimplify.io/hero/main.jpg?w=1200&format=webp&quality=80"\n\nassetUrl("hero/main.jpg", { base: "http://localhost:8787/storage" })\n// "http://localhost:8787/storage/hero/main.jpg"\n\nassetUrl("https://res.cloudinary.com/foo/bar.jpg")\n// "https://res.cloudinary.com/foo/bar.jpg"   (absolute \u2192 passthrough)\n```\n\n### Options\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `base` | `string` | Override the CDN base. Defaults to `DEFAULT_CDN_BASE_URL`. |\n| `w` / `h` | `number` | Width / height in pixels (on-the-fly resizing) |\n| `quality` | `number` | 0\u2013100 |\n| `format` | `"auto" \\| "webp" \\| "avif" \\| "jpeg"` | `"auto"` lets the CDN pick by `Accept` header |\n\nThe transform query is only meaningful when the URL terminates on the Cimplify storefront CDN (which supports on-the-fly resizing). For external hosts, unknown params are typically ignored; the image still loads at its original size.\n\n## `isCimplifyAsset(src, base?)`\n\nDecides whether `src` is hosted on a Cimplify CDN. Used by the storefront\'s `next/image` loader to skip transforms for external URLs.\n\n```ts\n\nisCimplifyAsset("hero/main.jpg")                                      // true (relative \u2192 ours)\nisCimplifyAsset("/img/seed/bakery/x.jpg")                             // true (dev mock passthrough)\nisCimplifyAsset("https://storefrontassetscdn.cimplify.io/x.jpg")     // true\nisCimplifyAsset("https://cdn.cimplify.io/x.jpg")                     // true\nisCimplifyAsset("https://static-tmp.cimplify.io/seed/x.jpg")         // true\nisCimplifyAsset("https://res.cloudinary.com/demo/upload/x.jpg")      // false\nisCimplifyAsset("https://images.unsplash.com/photo-xyz")             // false\n```\n\n## Built-in `next/image` loader\n\nEvery storefront template scaffolded by `cimplify init` ships `lib/cimplify-loader.ts` and points `images.loaderFile` at it. The loader:\n\n```ts\n\nconst cdnBase = process.env.NEXT_PUBLIC_CIMPLIFY_CDN_URL?.trim() || undefined;\n\nconst cimplifyImageLoader: ImageLoader = ({ src, width, quality }) => {\n  if (isCimplifyAsset(src, cdnBase)) {\n    return assetUrl(src, { base: cdnBase, w: width, quality, format: "auto" });\n  }\n  return src;\n};\n\nexport default cimplifyImageLoader;\n```\n\n**Cloudinary URLs from `client.catalogue.getProducts()` flow through untouched.** Cimplify-hosted URLs get the transform query. The result: every `<Image>` works regardless of where its asset lives, and Cimplify-hosted ones get edge-optimized.\n\nTo point the loader at a different CDN (for testing, multi-CDN setups, etc.) set `NEXT_PUBLIC_CIMPLIFY_CDN_URL` in your `.env.local`:\n\n```\nNEXT_PUBLIC_CIMPLIFY_CDN_URL=http://localhost:8787/storage\n```\n\n## `useImage(path, opts?)` (React)\n\nThin hook that returns `{ src, loader }` for `<Image>`:\n\n```tsx\n\nexport function Hero() {\n  const { src, loader } = useImage("hero/main.jpg", { format: "webp", quality: 85 });\n  return <Image src={src} loader={loader} alt="..." width={1200} height={800} />;\n}\n```\n\nIf `images.loaderFile` is already set globally in your `next.config.ts`, you typically don\'t need `useImage`; just `<Image src={assetUrl("hero/main.jpg")} />` works. `useImage` is useful when you want per-component transform overrides on a project that doesn\'t use a global loader.\n\n### Options\n\n| Field | Notes |\n| --- | --- |\n| `base` | Per-call CDN base override |\n| `w`, `h` | Default transform values; per-image `width` from `<Image>` still wins |\n| `format`, `quality` | Default transform values |\n\n`useImage` is `useMemo`-stable across renders when the path + opts don\'t change.\n\n## Constants\n\n```ts\n\nDEFAULT_CDN_BASE_URL // "https://storefrontassetscdn.cimplify.io"\nCIMPLIFY_CDN_HOSTS   // readonly ["storefrontassetscdn.cimplify.io", "cdn.cimplify.io", "static-tmp.cimplify.io"]\n```\n\n## What\'s not in v1\n\n- **`useUpload` hook**: runtime customer-facing uploads with progress + cancel. Deferred to v1.1. Customer uploads today go through `client.uploads.upload(file)` (no progress, no cancel; just `await`).\n- **`SEED_IDS` typed const tree**: demo-only convenience for referencing seed-image slugs in code. Generate-from-seed-source step deferred to v1.1; today demos use `seedImage(industry, slug)` from the SDK\'s mock module.\n- **Cloudinary / S3 path-transform support**: the loader passes external hosts through unchanged; Cloudinary\'s `c_fill,w_500/` path transforms aren\'t synthesized.\n- **`assets rm` server-side delete**: CLI removes manifest entries; the remote blob stays until v1.1\'s media-manager `DELETE` wiring.\n\n## Where it lives in the platform\n\n- Wire format: `POST /v1/businesses/{id}/assets/{init,confirm}`; see the management API reference\n- Backend service: `crate::uploads::service::UploadService::init_storefront_asset`\n- Served from the Cimplify asset CDN at `storefrontassetscdn.cimplify.io`\n- Storage key: `assets/{business_id}/{folder}/{upload_id}/{filename}`: immutable per upload; use the returned preview URL\n\n## Related\n\n- [`cimplify assets`](/docs/cli/assets): CLI surface for upload/ls/rm\n- [Uploads (customer-runtime)](/docs/sdk/uploads): `client.uploads.upload(file)` for private 7-day-presigned uploads\n'
-  },
-  {
-    "name": "exit-codes",
-    "title": "CLI \u2014 Exit codes",
-    "description": "CLI exit codes (NOT_LINKED=4, TIMEOUT=12, \u2026)",
-    "source_url": "https://cimplify.dev/docs/cli#exit-codes",
-    "body": "## Exit codes\nDistinct per error class so callers can branch on `$?` without parsing output:\n\n| Code | Name | Meaning |\n| --- | --- | --- |\n| `0` | OK | Success. For `deploy`, deployment is `active`. |\n| `1` | FAILED | Generic failure (build failed, deploy errored). |\n| `2` | SUPERSEDED | A newer push raced this deploy; usually fine. |\n| `3` | ABORTED | User canceled (Ctrl-C) or `cimplify_cancel_deployment`. |\n| `4` | NOT_LINKED | `.cimplify/project.json` missing. Run `cimplify link <id>`. |\n| `7` | INTERACTIVE_REQUIRED | A prompt was needed but `--yes` not passed and stdin is non-TTY. |\n| `9` | NOT_FOUND | Resource (project, domain, deploy) does not exist. |\n| `10` | NETWORK_ERROR | Could not reach `api.cimplify.io`. |\n| `12` | TIMEOUT | Long-poll exceeded its window; the underlying job may still be running. |\n| `20` | NOT_LOGGED_IN | No saved token. Run `cimplify login` or pass `--api-key`. |\n| `21` | AUTH_FAILED | Token expired or revoked. Re-login. |\n| `30` | INVALID_INPUT | Argument/flag validation failed. |\n\nFull list in `@cimplify/cli/errors`.\n"
-  },
-  {
-    "name": "inspect-json",
-    "title": 'Inspect \u2014 The JSON envelope (locked contract, `schema_version: "1"`)',
-    "description": "The locked JSON envelope cimplify inspect emits",
-    "source_url": "https://cimplify.dev/docs/cli/inspect#the-json-envelope-locked-contract-schema_version-1",
-    "body": '## The JSON envelope (locked contract, `schema_version: "1"`)\n```jsonc\n{\n  "ok": true,\n  "schema_version": "1",\n  "data": {\n    "business": {\n      "handle": "bakeryco",\n      "name": "Bakery & Co.",\n      "currencies": ["USD", "GHS"],\n      "locations": 2\n    },\n    "totals": {\n      "products": 142,\n      "collections": 8,\n      "categories": 12,\n      "distinct_tags": 24\n    },\n    "gaps": {\n      "no_image": 11,\n      "no_description": 7,\n      "no_price": 0,\n      "no_collection": 23,\n      "no_tags": 56,\n      "empty_collections": [{ "id": "col_seasonal", "name": "Seasonal" }],\n      "empty_categories":  [{ "id": "cat_specials", "name": "Specials" }]\n    },\n    "products": {\n      "sample": [\n        {\n          "id": "prod_abc1",\n          "name": "Croissant",\n          "slug": "croissant",\n          "price": { "amount": "3.50", "currency": "USD" },\n          "has_image": true,\n          "has_description": true,\n          "tags": ["vegan", "bestseller"],\n          "collection_ids": ["col_featured"],\n          "category_ids": ["cat_breakfast"],\n          "variant_count": 3\n        }\n      ],\n      "next_cursor": "eyJpZCI6IjE5In0",\n      "returned": 20\n    },\n    "collections": [\n      {\n        "id": "col_featured",\n        "name": "Featured",\n        "slug": "featured",\n        "product_count": 12,\n        "sample_product_ids": ["prod_abc1", "prod_abc2", "prod_abc3"]\n      }\n    ],\n    "categories": {\n      "tree": [\n        { "id": "cat_breakfast", "name": "Breakfast", "slug": "breakfast", "product_count": 24, "children": [] }\n      ]\n    },\n    "tags": {\n      "top": [{ "tag": "vegan", "count": 18 }, { "tag": "bestseller", "count": 12 }]\n    }\n  },\n  "meta": {\n    "fetched_at": "2026-05-23T10:15:32Z",\n    "source": "hosted",\n    "sampled": true,\n    "sample_size": 20,\n    "gaps_method": "sample",\n    "shape_hints": ["medium_catalogue", "uses_collections", "has_empty_collection", "untagged_majority", "has_image_gaps"],\n    "suggestions": [\n      { "kind": "fix_no_image", "count": 11 },\n      { "kind": "fix_no_collection", "count": 23 },\n      { "kind": "merchandise_empty_collection", "collection_id": "col_seasonal", "name": "Seasonal" }\n    ],\n    "suggested_commands": ["cimplify inspect catalogue --all"]\n  }\n}\n```\n\n### Error envelope\n\n```jsonc\n{\n  "ok": false,\n  "schema_version": "1",\n  "error": {\n    "code": "NO_PUBLIC_KEY",\n    "message": "Set NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY in .env or pass --public-key.",\n    "remediation": "Get one at desk.cimplify.io/settings/api."\n  }\n}\n```\n\n### Field rules\n\n- `ok` is always present.\n- `schema_version` is a contract over the whole document; bump on **removal**, **rename**, or **type change** of any field, `shape_hints` token, or `suggestions[].kind`. **Adding** is non-breaking.\n- `data.gaps.empty_collections` / `empty_categories` are always arrays (return `[]`, never omit).\n- `data.products.sample` is **always page-ordered** (never randomized).\n- `next_cursor` is `null` when the walk is exhausted.\n- `meta.source` is `"hosted"` or `"mock"`. Locked.\n- `meta.gaps_method` is `"sample"` or `"exact"`. Locked.\n- `meta.shape_hints` is **sorted alphabetically** (deterministic, diffable).\n- `meta.suggestions` is ordered by impact (most actionable first).\n- `meta.fetched_at` is the only timestamp; nothing in `data` carries time.\n'
-  },
-  {
-    "name": "shape-hints",
-    "title": "Inspect \u2014 `shape_hints` vocabulary",
-    "description": "The canonical shape_hints vocabulary for cimplify inspect",
-    "source_url": "https://cimplify.dev/docs/cli/inspect#shape_hints-vocabulary",
-    "body": "## `shape_hints` vocabulary\nFlat string tokens for agents to branch on. Adding tokens is non-breaking; removing/renaming bumps `schema_version`.\n\n### Catalogue size\n\n| Token | Meaning |\n| --- | --- |\n| `empty_catalogue` | 0 products. Whole storefront needs an empty-state. |\n| `tiny_catalogue` | 1\u20139 products. Skip search, deep filters. |\n| `small_catalogue` | 10\u201399 products. Default UX. |\n| `medium_catalogue` | 100\u2013999 products. Search nice-to-have. |\n| `large_catalogue` | 1000+ products. Search + facets required. |\n\n### Feature presence\n\n| Token | Meaning |\n| --- | --- |\n| `has_variants` | At least one product has variants \u2192 variant picker UI. |\n| `has_addons` | At least one product has add-on options \u2192 modifier UI. |\n| `has_subscriptions` | Billing plans exist \u2192 recurring pricing toggle. |\n| `has_composites` | Bundle / composite products exist. |\n| `has_recipes` | Products linked to `ProductComponent` (restaurant / manufacturing). |\n| `has_time_profiles` | Products have time-of-day windows \u2192 hours-aware UI. |\n| `has_input_fields` | Buyer-supplied inputs (engraving, message). |\n| `has_custom_attributes` | Custom attribute schemas defined. |\n| `per_location_pricing` | Prices vary by location. |\n| `multi_currency` | >1 currency configured. |\n| `multi_location` | >1 location configured. |\n\n### Merchandising state\n\n| Token | Meaning |\n| --- | --- |\n| `uses_collections` | \u22651 non-empty collection exists. |\n| `uses_categories` | \u22651 non-empty category. |\n| `has_empty_collection` | \u22651 collection has 0 products. |\n| `has_empty_category` | \u22651 category has 0 products. |\n| `untagged_majority` | >50% of products are untagged. |\n| `unmerchandised_majority` | >50% of products aren't in any collection. |\n\n### Data quality\n\n| Token | Meaning |\n| --- | --- |\n| `has_image_gaps` | \u22651 product missing image. |\n| `has_description_gaps` | \u22651 product missing description. |\n| `has_price_gaps` | \u22651 product missing price. |\n\n### Environment\n\n| Token | Meaning |\n| --- | --- |\n| `mock_data` | Reading from `cimplify-mock` (key isn't `cpk_live_*` / `cpk_test_*`). |\n"
-  },
-  {
-    "name": "revalidation-tags",
-    "title": "Revalidation",
-    "description": "Canonical cimplify:* cache-tag vocabulary + revalidate helpers",
-    "source_url": "https://cimplify.dev/docs/sdk/revalidation",
-    "body": "Cimplify storefronts cache catalogue reads with Next 16's ISR (`export const revalidate = N` + `next.tags` via the SDK's `cacheOptions`). When a merchant edits a product, collection, or brand asset, Cimplify invalidates the matching caches for your storefront automatically, with no `/api/revalidate` webhook round-trip required.\n\nThis page is the canonical contract between Cimplify and your storefront. Use the typed helpers (never hand-write tag strings) so the scheme stays in one place.\n\n## Why ISR, not Cache Components\n\nCimplify templates use Next 16's [Previous Model](https://nextjs.org/docs/app/guides/caching-without-cache-components): `export const revalidate` at the page level, `cacheOptions: { revalidate, tags }` on SDK reads (forwarded as `fetch().next.{revalidate,tags}`), and `revalidateTag` for invalidation. The `'use cache'` directive (Cache Components) is still experimental and its runtime constraints don't suit hosted storefronts. The Previous Model is stable, fully supported, and what every Cimplify template ships with. Keep `cacheComponents` **off** in `next.config.ts`.\n\n## Tags\n\nAll tags are namespaced under `cimplify:` so they can't collide with consumer tags. Build them via `tags` from `@cimplify/sdk/server`:\n\n```ts\n\nexport const revalidate = 3600;\n\nasync function getProducts() {\n  const r = await getServerClient().catalogue.getProducts(\n    { limit: 24 },\n    { cacheOptions: { revalidate: 3600, tags: [tags.products()] } },\n  );\n  return r.ok ? r.value.items : [];\n}\n```\n\n### Catalogue\n\n| Helper | Tag |\n| --- | --- |\n| `tags.products()` | `cimplify:products` |\n| `tags.product(id)` | `cimplify:product:{id}` |\n| `tags.categories()` | `cimplify:categories` |\n| `tags.category(id)` | `cimplify:category:{id}` |\n| `tags.categoryProducts(id)` | `cimplify:category:{id}:products` |\n| `tags.collections()` | `cimplify:collections` |\n| `tags.collection(id)` | `cimplify:collection:{id}` |\n| `tags.collectionProducts(id)` | `cimplify:collection:{id}:products` |\n| `tags.tag(name)` | `cimplify:tag:{name}` (product tag, e.g. \"vegan\") |\n| `tags.addons()` | `cimplify:addons` |\n| `tags.addon(id)` | `cimplify:addon:{id}` |\n| `tags.stock()` | `cimplify:stock` |\n| `tags.stockFor(productId)` | `cimplify:stock:{productId}` |\n\n### Brand / business\n\n| Helper | Tag |\n| --- | --- |\n| `tags.business()` | `cimplify:business` |\n| `tags.brand()` | `cimplify:brand` |\n| `tags.locations()` | `cimplify:locations` |\n| `tags.location(id)` | `cimplify:location:{id}` |\n| `tags.locale()` | `cimplify:locale` |\n\n### Pricing / subscriptions\n\n| Helper | Tag |\n| --- | --- |\n| `tags.pricing()` | `cimplify:pricing` |\n| `tags.subscriptions()` | `cimplify:subscriptions` |\n| `tags.subscription(id)` | `cimplify:subscription:{id}` |\n\n### Customer-scoped (Server Actions only)\n\n| Helper | Tag |\n| --- | --- |\n| `tags.orders(customerId)` | `cimplify:orders:{customerId}` |\n| `tags.order(id)` | `cimplify:order:{id}` |\n\n## Granularity\n\nTag with **both** a broad and a precise tag on every read so either-flavour invalidation works:\n\n```ts\ncacheOptions: { revalidate: 3600, tags: [tags.products(), tags.product(id)] }\n```\n\nThe broad tag (`products`) catches \"I changed something product-related, invalidate everything.\" The precise tag (`product:{id}`) catches \"I changed exactly this one product, invalidate only its entries.\"\n\n## Revalidating from a Server Action\n\n```ts\n\nexport async function saveProduct(id: string, data: ProductInput) {\n  await client.catalogue.updateProduct(id, data);\n  await revalidateProduct(id);\n}\n```\n\nHelpers:\n\n| Helper | Invalidates |\n| --- | --- |\n| `revalidateProducts()` | `products` |\n| `revalidateProduct(id)` | `product:{id}` + `products` |\n| `revalidateCategories()` | `categories` |\n| `revalidateCategory(id)` | `category:{id}` + `category:{id}:products` + `categories` |\n| `revalidateCollections()` | `collections` |\n| `revalidateCollection(id)` | `collection:{id}` + `collection:{id}:products` + `collections` |\n| `revalidateBusiness()` | `business` |\n| `revalidateBrand()` | `brand` |\n| `revalidateLocations()` | `locations` |\n| `revalidateLocation(id)` | `location:{id}` + `locations` |\n| `revalidatePricing()` | `pricing` + `products` |\n| `revalidateAddOns()` | `addons` |\n| `revalidateAddOn(id)` | `addon:{id}` + `addons` |\n| `revalidateSubscriptions()` | `subscriptions` |\n| `revalidateSubscription(id)` | `subscription:{id}` + `subscriptions` |\n| `revalidateStock(productId?)` | `stock:{productId}` + `stock` (or just `stock` if no id) |\n| `revalidateByTag(tag)` | escape hatch for a raw tag |\n\n## The Cimplify \u2192 storefront eviction contract\n\nWhen a merchant edits something in the dashboard, Cimplify automatically invalidates the matching caches for every storefront serving that business, **globally, in ~1\u20133 seconds**, with no webhook round-trip into your storefront. You don't wire anything up; tagging your reads correctly is the whole contract.\n\nThe tags Cimplify dispatches use the **exact strings** from the tables above, keyed by database ID. If you've tagged your `cacheOptions.tags` with the helpers above, your storefront stays in sync automatically.\n\n## Dynamic routes: tag by **ID**, never by slug\n\nCimplify dispatches revalidation tags **keyed by database ID**, not by URL slug. A `/products/[slug]` page that caches itself under `tags.product(slug)` will never be invalidated by an edit; the tag the storefront wrote doesn't match the tag Cimplify fires.\n\nResolve the slug to a record first, then tag with `record.id`:\n\n```ts title=\"app/products/[slug]/page.tsx (correct)\"\n\nexport const revalidate = 3600;\n\nexport async function generateStaticParams() {\n  const r = await getServerClient().catalogue.getProducts({ limit: 10_000 });\n  if (!r.ok || r.value.items.length === 0) return [{ slug: \"__placeholder__\" }];\n  return r.value.items.map((p) => ({ slug: p.slug ?? p.id }));\n}\n\nexport default async function Page({ params }: { params: Promise<{ slug: string }> }) {\n  const { slug } = await params;\n\n  // First resolve slug \u2192 product. Tag the resolution read with the\n  // collection-level tag so adds/removes invalidate it. This call hits the\n  // SDK with a fallback-broad tag.\n  const r = await getServerClient().catalogue.getProductBySlug(\n    slug,\n    { cacheOptions: { revalidate: 3600, tags: [tags.products()] } },\n  );\n  if (!r.ok) notFound();\n\n  // Now re-fetch with the resolved ID so the per-product tag is keyed on the\n  // stable identifier; revalidateProduct(id) from Cimplify will hit this\n  // entry on the next mutation.\n  const detailed = await getServerClient().catalogue.getProduct(\n    r.value.id,\n    { cacheOptions: { revalidate: 3600, tags: [tags.product(r.value.id), tags.products()] } },\n  );\n\n  if (!detailed.ok) notFound();\n  return <ProductDetail product={detailed.value} />;\n}\n```\n\nThe same pattern applies to `[slug]` routes for categories, collections, addons, locations, and so on: always tag with the resolved `record.id`, never with the URL slug.\n\n### Why this matters\n\n- **Renames don't orphan.** The cache key includes the slug (path-based), so a renamed product gets a fresh cache entry under the new slug. The old slug-keyed entry is invalidated via the `tags.products()` collection tag and will 404 naturally.\n- **IDs are stable.** Cimplify's bus emits `ProductUpdated { id }` events; the slug isn't on the event payload, and adding it would create races with concurrent rename. Keeping the tag scheme ID-only keeps the contract simple.\n- **You get instant freshness.** With Cimplify's automatic eviction, a 1-hour `revalidate` entry can sit cached and still flip fresh within ~3s of an edit, but only if the tag actually matches.\n\n## SDK timeout\n\nThe SDK's default per-call timeout is **5 seconds**. Picked so a single slow upstream call can't exhaust the page render budget; a hung `getCollections()` would otherwise take the entire page render with it. With the 5s default, a slow call fails fast, `Result.ok` becomes `false`, the page renders with empty data, and the result is cached so subsequent hits are instant.\n\nOverride only for genuinely-large bulk reads (admin tooling, batch jobs):\n\n```ts\n\nconst adminClient = createCimplifyClient({\n  secretKey: process.env.CIMPLIFY_SECRET_KEY,\n  timeout: 30_000, // 30s for a 10k-row export\n});\n```\n\n## Don't cache empty responses as if they were real\n\nIf a render produces empty results because of a transient backend hiccup, that empty render gets cached for the full `revalidate` window, and every visitor sees an empty storefront until someone manually invalidates.\n\nTwo defences:\n\n**1.** The SDK's 5s timeout above stops a slow call from hanging the whole render, but the result is still `Result.ok = false`. Branch on that and short-circuit to a not-found / soft state rather than committing the empty render to cache:\n\n```ts title=\"app/categories/[slug]/page.tsx\"\nasync function getCategory(slug: string) {\n  const r = await getServerClient().catalogue.getCategoryBySlug(\n    slug,\n    { cacheOptions: { revalidate: 3600, tags: [tags.categories()] } },\n  );\n  // Distinguish a real 404 from a transient SDK error. Only `notFound()` on\n  // the real 404; for transient errors, render a soft loading state so the\n  // cache doesn't lock in an incorrect \"page couldn't load\" for an hour.\n  if (!r.ok) {\n    if (r.error.code === \"NOT_FOUND\") notFound();\n    return { soft: true as const };\n  }\n  return { soft: false as const, category: r.value };\n}\n```\n\n**2.** Use the eviction-pipeline path for catalogue invalidation rather than relying on `revalidate` window expiry. A real edit in the dashboard purges the cache within seconds; the `revalidate` value is a backstop, not the primary refresh mechanism.\n\n## Tag taxonomy is locked\n\nThe vocabulary above is the v1 contract. Adding new tag helpers is non-breaking; removing or renaming any of them bumps the SDK major version. Agents that bake these strings into prompts can pin to v0.x of `@cimplify/sdk`.\n"
-  },
-  {
-    "name": "inspect-suggestions",
-    "title": "Inspect \u2014 `suggestions[].kind` vocabulary",
-    "description": "The canonical suggestions[].kind vocabulary for cimplify inspect",
-    "source_url": "https://cimplify.dev/docs/cli/inspect#suggestionskind-vocabulary",
-    "body": '## `suggestions[].kind` vocabulary\nEach entry is a stable `kind` + typed payload. Copy lives here (and in `cimplify explain inspect-suggestions`) so agents don\'t invent phrasing.\n\n| Kind | Payload | Implied prompt |\n| --- | --- | --- |\n| `add_first_product` | `{}` | Catalogue is empty; seed or add a product. |\n| `add_first_collection` | `{}` | Products exist but no collections; group some. |\n| `fix_no_image` | `{ count }` | N products without images; add placeholders. |\n| `fix_no_description` | `{ count }` | N products lack descriptions; generate copy. |\n| `fix_no_price` | `{ count }` | N products have no price; open the editor. |\n| `fix_no_collection` | `{ count }` | N products not in any collection; suggest "Featured". |\n| `fix_no_tags` | `{ count }` | N untagged products; suggest tags from name/category. |\n| `merchandise_empty_collection` | `{ collection_id, name }` | Collection "X" is empty; pick products to feature. |\n| `merchandise_empty_category` | `{ category_id, name }` | Category "X" has no products; fill or remove. |\n| `tag_uncategorized_products` | `{ count }` | Majority untagged; bulk-tag from category. |\n| `enable_search_ui` | `{ product_count }` | Large catalogue; add search + filters. |\n'
-  },
-  {
-    "name": "agent-prompts",
-    "title": "Agent prompts",
-    "description": "Copy-paste prompts for common Cimplify workflows",
-    "source_url": "https://cimplify.dev/docs/agent-prompts",
-    "body": 'These prompts are deliberately terse. Each one names the canonical doc the agent should read first, the exact commands or [MCP tools](/docs/mcp) to call, and the exit condition. Replace `<angle-bracket>` placeholders before running.\n\nEvery prompt assumes the agent has either:\n\n- the [Cimplify CLI](/docs/cli) installed and `cimplify login` complete, **or**\n- an MCP connection to `https://api.cimplify.io/mcp` ([setup](/docs/mcp#connect))\n\n## Ship a new storefront end-to-end\n\n```text title="Scaffold \u2192 deploy \u2192 custom domain"\nSet up a Cimplify <retail> storefront called <my-store> and deploy it to <shop.example.com>.\n\nSource of truth: https://cimplify.dev/docs/tldr\n- Use the MCP tools at api.cimplify.io/mcp when available; otherwise shell `cimplify <cmd> --json`.\n- After every command, echo the JSON envelope.\n- Stop on the first non-zero exit code and name it from https://cimplify.dev/docs/cli#exit-codes.\n- Poll deployment status with cimplify_get_deployment_status (or `cimplify status --json`); never `sleep`.\n- Idempotent: re-running any step is safe.\n```\n\n## Rebrand an existing storefront\n\n```text title="Apply a new brand to a scaffolded template"\nRebrand the storefront in <./my-store> to match these tokens:\n  name: <Acme Coffee>\n  primary: <#0F172A>\n  accent: <#F59E0B>\n  fontDisplay: <"Playfair Display">\n  fontBody: <"Inter">\n\nRules (https://cimplify.dev/docs/templates/brand):\n- Single source of truth is `lib/brand.ts`. Update it first.\n- Mirror color tokens into `app/globals.css` `@theme` block. Do not hard-code colors elsewhere.\n- Do not edit ejected SDK components; they pick up tokens automatically.\n- Run `bun run check:brand` after edits; fix any schema errors it reports.\n- Verify by opening `http://localhost:3000` (start `bun dev` if not running).\n- Commit with message `brand: <name>`. Do not deploy.\n```\n\n## Add a homepage section\n\n```text title="New Server Component section, cache-tagged"\nAdd a `<Stories>` section to the homepage of the storefront in <./my-store>.\n\nPattern (mirrors the Server Component sections under `app/_sections/` in the scaffolded template):\n- Create `app/_sections/stories.tsx` as an async Server Component. Pass `cacheOptions: { revalidate: 3600, tags: [tags.collections()] }` to the SDK read (from `@cimplify/sdk/server`). Do NOT use `\'use cache\'` / `cacheTag` / `cacheLife`. Cimplify storefronts run on CF Workers where Cache Components is broken; use the ISR Previous Model.\n- Source data from `client.catalogue.getCollection({ slug: "stories" })`.\n- Render with the existing `<SectionHeader>` and `<ProductCard>` SDK components (do not eject).\n- Insert into `app/page.tsx` between the hero and the featured collection.\n- Run `bun run check`. It must pass typecheck, lint, brand, cart-flow, contract.\n- Do not modify `lib/brand.ts` or any file under `components/ui/`.\n```\n\n## Migrate to a new SDK version\n\n```text title="SDK upgrade with breaking-change scan"\nUpgrade the storefront in <./my-store> from `@cimplify/sdk@<0.44.x>` to `@cimplify/sdk@<latest>`.\n\nProcess:\n- Read the release notes for the target range (`npm view @cimplify/sdk versions --json` to list, then `npm view @cimplify/sdk@<version>` per release).\n- Bump the pin in `package.json`, run `bun install`.\n- For each breaking change called out in the changelog, grep the project for the old symbol and apply the documented replacement.\n- Run `bun run check`. If `check:contract` fails, the SDK \u2194 mock contract drifted; stop and report.\n- Do not run `cimplify deploy`. End by printing a summary of every file you changed and every breaking change you applied.\n```\n\n## Add a custom checkout payment method\n\n```text title="Wire an additional payment option"\nAdd <mobile_money> as a checkout payment option in the storefront at <./my-store>.\n\nReference: https://cimplify.dev/docs/api-reference/checkout (purchase-intent mint, immutable terms review, then exact option confirmation).\n- Use the exported `PURCHASE_INTENT_*` constants and closed tender preference types.\n- Eject the existing `<PaymentMethodPicker>` component with `cimplify add payment-method-picker`.\n- Add the option in the ejected picker, preparing provider input into an opaque server-issued payment option.\n- Show `fee_amount` and `customer_debit_amount`, then confirm the reviewed option ID.\n- Validate mint and confirmation bodies against the purchase-intent schemas from `@cimplify/sdk/testing`.\n- Run `bun run check:cart`; the add\u2192checkout flow must still pass.\n```\n\n## Provision a CI deploy key\n\n```text title="One-time setup for headless deploys"\nCreate a CI-scoped API key for the Cimplify project linked at <./my-store>, and write the GitHub Actions snippet that uses it.\n\nSteps:\n- Confirm `.cimplify/project.json` exists; if not, fail with NOT_LINKED (exit 4).\n- Print the dashboard URL the human needs to visit to create the key (https://app.cimplify.io/settings/developer).\n- Once the user provides `dk_live_\u2026`, store it as a repo secret named `CIMPLIFY_API_KEY` (instruct, do not perform).\n- Write `.github/workflows/deploy.yml` that runs on push to main: install CLI via the curl one-liner, `cimplify deploy --prod --api-key "$CIMPLIFY_API_KEY" --yes --json`.\n- Print the exit-code legend from https://cimplify.dev/docs/cli#exit-codes so the workflow can map failures.\n```\n\n## Diagnose a deploy that didn\'t go live\n\n```text title="Triage a failed or stuck deployment"\nThe latest deploy of the project at <./my-store> isn\'t live. Find out why.\n\nTriage path:\n- `cimplify status --json`: what\'s the latest deployment_id and status?\n- If status is `failed`, `cimplify logs --deployment <id> --json | tail -200`. Quote the first error line you see.\n- If status is `queued` or `building` for >5 minutes, the build is stuck; try `cimplify rollback <previous-deploy-id>`.\n- If status is `superseded` (exit 2), a newer push raced it; usually fine, so confirm with `cimplify status` again.\n- If domains misroute, `cimplify domains ls --json`: confirm the verified+attached domain.\n- Report: deployment_id, status, the failing log line (if any), and the recommended next action. Do not auto-rollback without confirming.\n```\n\n## Add a hero image and reference it in the homepage\n\n```text title="Upload brand assets \u2192 use them in source"\nAdd the image at <./Downloads/hero.jpg> as the homepage hero for the storefront in <./my-store>.\n\nReference: https://cimplify.dev/docs/cli/assets\n- `cp <./Downloads/hero.jpg> public/hero/main.jpg`\n- `cimplify assets upload public/hero/ --folder hero --json`: captures the manifest entry for `hero/main.jpg`.\n- Edit `app/page.tsx`: replace the hero `<Image>` `src` with `assetUrl("hero/main.jpg")` from `@cimplify/sdk`.\n- Do NOT touch existing `<Image>` calls that point at Cloudinary or other external hosts; the loader passes them through unchanged.\n- Run `bun run check`. Open `http://localhost:3000`; verify the hero image renders.\n- Commit `cimplify-assets.json` along with the source change so the manifest is reviewable.\n```\n\n## Audit caching and asset delivery\n\n```text title="Find caching and asset regressions on a live storefront"\nAudit the live storefront at <https://my-store.mycimplify.com> for caching and asset-delivery regressions.\n\nSources of truth:\n- https://cimplify.dev/docs/sdk/optimization (page + asset caching)\n- https://cimplify.dev/docs/templates/seo-and-resource-hints (responsive images)\n\n- Page cache: curl /, /shop, and a PDP 2\u20133\xD7 each; `X-Cimplify-Edge-Cache` must warm to HIT and `Cache-Control` must carry `s-maxage`. A BYPASS or missing `s-maxage` means the page lost its `revalidate` or carries a Cookie.\n- Asset cache: pull a `/_next/static/*` chunk; it must be `public, max-age=31536000, immutable`.\n- Images: flag raw `<img>` from a third-party CDN, and Cloudinary URLs with no `/upload/<transform>/` segment (full-resolution originals).\n- Report a table (route/asset, observed header, expected, severity). Do not change source unless asked.\n```\n\n## Reset a sandbox storefront to a clean state\n\n```text title="Wipe and re-seed for repeatable demos"\nReset the local mock state for the storefront in <./my-store>.\n\n- Stop any running `bun dev` process.\n- `cimplify mock reset` (clears the in-process mock backing store).\n- `cimplify mock seed <retail>` (re-seeds with the chosen industry fixture).\n- `bun dev` to restart both servers.\n- Verify: `curl localhost:8787/v1/catalogue/products | jq \'.data | length\'` returns the expected seed count (~24 for retail).\n- Do not touch the linked cloud project; this is local-only.\n```\n\n## How these are built\n\nEvery prompt above is structured the same way so you can adapt them:\n\n1. **Goal**: one sentence, with `<angle-bracket>` placeholders for the moving parts.\n2. **Source of truth**: the canonical doc URL the agent reads first.\n3. **Rules**: operational guardrails for which tools to call, what to echo, and when to stop.\n4. **Exit condition**: what counts as success, what counts as a halt.\n\nIf you build a prompt that should live here, open a PR against `content/docs/agent-prompts.mdx`. Keep them under ~12 lines; if a workflow needs more, it belongs in a dedicated doc page and the prompt should link to it.\n'
-  },
-  {
-    "name": "seeds",
-    "title": "seeds",
-    "description": "Available mock seeds and how to switch between them",
-    "source_url": "https://cimplify.dev/docs/cli/mock",
-    "body": '## Mock seeds\n\nEvery Cimplify storefront ships with a local Hono mock backed by one of\nthese seeds. Switch with `cimplify mock seed <name>` (or hand-edit the\n`--seed` flag in your `package.json` `scripts.dev`).\n\n| Seed | Notes |\n| --- | --- |\n| `auto` | (no description) |\n| `context` | (no description) |\n| `default` | Generic small business \u2014 minimal fixtures |\n| `empty` | No data \u2014 for blank-slate testing |\n| `fashion` | Apparel with multi-axis variants (size, color) |\n| `grocery` | High-SKU produce + perishables |\n| `names` | (no description) |\n| `pharmacy` | Wellspring Apothecary \u2014 health products with regulated metadata |\n| `reesa-storefront` | Reesa-specific demo storefront |\n| `restaurant` | Menu-driven with reservations |\n| `retail` | Electronics-focused storefront with variants and add-ons |\n| `services` | Bookable services (e.g. salon, spa) |\n| `source` | (no description) |\n\n### Finding fixture IDs\n\nEach seed is a TypeScript file at `packages/sdk/src/mock/seeds/<name>.ts`\nin the cimplify monorepo. Product slugs, categories, and variant axes\nare defined inline. Grep that file when you need a real slug for a\nhard-coded demo:\n\n```bash\ngrep "slug:" node_modules/@cimplify/sdk/dist/mock/seeds/<name>.* | head\n```\n\nA future `cimplify mock products ls --json` will surface these IDs\ndirectly without grep.\n'
-  }
-];
-var TOPICS_BY_NAME = Object.fromEntries(
-  TOPICS.map((t) => [t.name, t])
-);
-
-// src/commands/explain.ts
-var CLI_VERSION = package_default.version ?? "unknown";
-var NAME_COL_WIDTH = 14;
-function listTopics(topics = TOPICS) {
-  const out = [];
-  out.push(bold("cimplify explain"));
-  out.push(dim(`\u2014 canonical guidance, bundled in cli-v${CLI_VERSION}`));
-  out.push("");
-  for (const t of topics) {
-    out.push(`  ${bold(t.name.padEnd(NAME_COL_WIDTH))}${t.description}`);
-  }
-  out.push("");
-  out.push(dim(`Run \`cimplify explain <topic>\` to print the guide.`));
-  out.push(dim(`Add --json for a machine-readable envelope.`));
-  return out;
-}
-function renderTopic(topic) {
-  const out = [];
-  out.push(bold(`cimplify explain ${topic.name}`));
-  out.push("");
-  out.push(topic.body.trimEnd());
-  out.push("");
-  out.push(dim(`Source: ${topic.source_url} (snapshot in cli-v${CLI_VERSION})`));
-  return out;
-}
-function getTopic(name) {
-  return TOPICS_BY_NAME[name] ?? null;
-}
-function knownTopicNames() {
-  return TOPICS.map((t) => t.name);
-}
-async function run(argv) {
-  const args = parseArgs(argv);
-  const name = args.positional[0];
-  if (!name) {
-    for (const line of listTopics()) info(line);
-    result({
-      topics: TOPICS.map((t) => ({
-        name: t.name,
-        description: t.description,
-        source_url: t.source_url
-      }))
-    });
-    return;
-  }
-  const topic = getTopic(name);
-  if (!topic) {
-    throw new CliError(
-      CLI_ERROR_CODE.NOT_FOUND,
-      `Unknown topic "${name}".`,
-      { remediation: `Run \`cimplify explain\` to see all topics (${knownTopicNames().length} available).` }
-    );
-  }
-  for (const line of renderTopic(topic)) info(line);
-  result({
-    topic: topic.name,
-    title: topic.title,
-    body: topic.body,
-    source_url: topic.source_url,
-    snapshot_version: CLI_VERSION
-  });
-}
-
-export { run as default, getTopic, listTopics, renderTopic };

package/dist/introspect-2NGESQZE.mjs

@@ -1,8 +0,0 @@
-#!/usr/bin/env node
-export { run as default, extractMockSeed, gatherIntrospection, renderIntrospection } from './chunk-WEAB6HHQ.mjs';
-import './chunk-I2UP7YTG.mjs';
-import './chunk-GRR5U2M5.mjs';
-import './chunk-KN2YSKXZ.mjs';
-import './chunk-5KYR6WJB.mjs';
-import './chunk-MLE4MVYC.mjs';
-import './chunk-3QUK5BPY.mjs';

package/dist/repo-X3KZ5R64.mjs

@@ -1,9 +0,0 @@
-#!/usr/bin/env node
-export { run as default, fetchCloneToken, fetchRepoRecord } from './chunk-A6WHBSXZ.mjs';
-import './chunk-TH4XENKH.mjs';
-import './chunk-MXYUAJEW.mjs';
-import './chunk-KN2YSKXZ.mjs';
-import './chunk-5KYR6WJB.mjs';
-import './chunk-NYXA6X56.mjs';
-import './chunk-MLE4MVYC.mjs';
-import './chunk-3QUK5BPY.mjs';