@cimplify/sdk 0.44.12 → 0.44.16

package/dist/{server-CUbuQxOV.d.ts → server-CnECAQDQ.d.mts}

@@ -575,6 +575,10 @@ interface AuthService {
     }): Session;
     status(token: string | null): {
         is_authenticated: boolean;
+        account_id?: string;
+        user_type: "customer" | "guest";
+        session_expires_at?: number;
+        /** @deprecated Kept for SDK back-compat; production lens does not return this. */
         session?: Session;
     };
 }
@@ -736,6 +740,7 @@ interface CheckoutResult {
     payment_status: string;
     payment_reference?: string;
     requires_authorization: boolean;
+    authorization_type?: "otp" | "pin" | "phone" | "birthday" | "address";
     next_action: {
         type: "none";
     } | {
@@ -749,6 +754,12 @@ interface CheckoutResult {
     provider?: string;
     authorization_url?: string;
     display_text?: string;
+    /** Bearer token used for guest order access (lookup `/orders/{id}?token=...`). */
+    bill_token?: string;
+    /** Stripe-style client secret for direct PaymentIntent confirmation. */
+    client_secret?: string;
+    /** Stripe publishable key (mock value in dev). */
+    public_key?: string;
 }
 
 interface OrderService {
@@ -811,22 +822,33 @@ interface SchedulingService {
 interface InventoryService {
     productStock(productId: string): {
         product_id: string;
-        quantity: number;
-        available: boolean;
+        location_id?: string;
+        stock_level: number;
+        in_stock: boolean;
     };
     variantStock(variantId: string): {
         variant_id: string;
-        quantity: number;
-        available: boolean;
+        location_id?: string;
+        stock_level: number;
+        in_stock: boolean;
     };
-    productAvailability(productId: string): {
+    productAvailability(productId: string, quantity?: number): {
         product_id: string;
+        quantity: number;
         is_available: boolean;
     };
-    variantAvailability(variantId: string): {
+    variantAvailability(variantId: string, quantity?: number): {
         variant_id: string;
+        quantity: number;
         is_available: boolean;
     };
+    /**
+     * Reserve stock for a cart item. No-op for product types that don't track
+     * inventory (services, digital). Throws on insufficient stock.
+     */
+    reserve(productId: string, variantId: string | undefined, quantity: number): void;
+    /** Release a previously-reserved quantity (e.g. when a line is removed). */
+    release(productId: string, variantId: string | undefined, quantity: number): void;
 }
 
 interface FxService {

package/dist/{server-CUbuQxOV.d.mts → server-CnECAQDQ.d.ts}

@@ -575,6 +575,10 @@ interface AuthService {
     }): Session;
     status(token: string | null): {
         is_authenticated: boolean;
+        account_id?: string;
+        user_type: "customer" | "guest";
+        session_expires_at?: number;
+        /** @deprecated Kept for SDK back-compat; production lens does not return this. */
         session?: Session;
     };
 }
@@ -736,6 +740,7 @@ interface CheckoutResult {
     payment_status: string;
     payment_reference?: string;
     requires_authorization: boolean;
+    authorization_type?: "otp" | "pin" | "phone" | "birthday" | "address";
     next_action: {
         type: "none";
     } | {
@@ -749,6 +754,12 @@ interface CheckoutResult {
     provider?: string;
     authorization_url?: string;
     display_text?: string;
+    /** Bearer token used for guest order access (lookup `/orders/{id}?token=...`). */
+    bill_token?: string;
+    /** Stripe-style client secret for direct PaymentIntent confirmation. */
+    client_secret?: string;
+    /** Stripe publishable key (mock value in dev). */
+    public_key?: string;
 }
 
 interface OrderService {
@@ -811,22 +822,33 @@ interface SchedulingService {
 interface InventoryService {
     productStock(productId: string): {
         product_id: string;
-        quantity: number;
-        available: boolean;
+        location_id?: string;
+        stock_level: number;
+        in_stock: boolean;
     };
     variantStock(variantId: string): {
         variant_id: string;
-        quantity: number;
-        available: boolean;
+        location_id?: string;
+        stock_level: number;
+        in_stock: boolean;
     };
-    productAvailability(productId: string): {
+    productAvailability(productId: string, quantity?: number): {
         product_id: string;
+        quantity: number;
         is_available: boolean;
     };
-    variantAvailability(variantId: string): {
+    variantAvailability(variantId: string, quantity?: number): {
         variant_id: string;
+        quantity: number;
         is_available: boolean;
     };
+    /**
+     * Reserve stock for a cart item. No-op for product types that don't track
+     * inventory (services, digital). Throws on insufficient stock.
+     */
+    reserve(productId: string, variantId: string | undefined, quantity: number): void;
+    /** Release a previously-reserved quantity (e.g. when a line is removed). */
+    release(productId: string, variantId: string | undefined, quantity: number): void;
 }
 
 interface FxService {

package/dist/server.d.mts

@@ -1,5 +1,5 @@
-import { C as CimplifyClient } from './client-CkGlXZRd.mjs';
-export { aN as Result } from './client-CkGlXZRd.mjs';
+import { C as CimplifyClient } from './client-Dh-bHyhU.mjs';
+export { aN as Result } from './client-Dh-bHyhU.mjs';
 export { am as Category, h as CimplifyError, ao as Collection, U as Product, a7 as ProductWithDetails } from './payment-DA1i5hhk.mjs';
 
 interface ServerClientOptions {

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { C as CimplifyClient } from './client-lvLvB1_K.js';
-export { aN as Result } from './client-lvLvB1_K.js';
+import { C as CimplifyClient } from './client-D6ZisKco.js';
+export { aN as Result } from './client-D6ZisKco.js';
 export { am as Category, h as CimplifyError, ao as Collection, U as Product, a7 as ProductWithDetails } from './payment-DA1i5hhk.js';
 
 interface ServerClientOptions {

package/dist/server.js

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunkOMAP327U_js = require('./chunk-OMAP327U.js');
-require('./chunk-BAWKQRIB.js');
-var chunkV2O5AO7I_js = require('./chunk-V2O5AO7I.js');
+var chunkMBGQP6FZ_js = require('./chunk-MBGQP6FZ.js');
+require('./chunk-CFD4J32N.js');
+var chunkMNIKXG7W_js = require('./chunk-MNIKXG7W.js');
 var react = require('react');
 
 var DEFAULT_DEV_URL = "http://127.0.0.1:8787";
@@ -18,7 +18,7 @@ function readEnv(...keys) {
 var getServerClient = react.cache((opts = {}) => {
   const baseUrl = opts.apiUrl ?? readEnv("CIMPLIFY_API_URL", "NEXT_PUBLIC_CIMPLIFY_API_URL") ?? DEFAULT_DEV_URL;
   const publicKey = opts.secretKey ?? readEnv("CIMPLIFY_SECRET_KEY", "NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY") ?? "mock-dev";
-  const client = chunkOMAP327U_js.createCimplifyClient({
+  const client = chunkMBGQP6FZ_js.createCimplifyClient({
     baseUrl,
     publicKey,
     suppressPublicKeyWarning: true
@@ -93,7 +93,7 @@ async function revalidateByTag(tag) {
 
 Object.defineProperty(exports, "CimplifyError", {
   enumerable: true,
-  get: function () { return chunkV2O5AO7I_js.CimplifyError; }
+  get: function () { return chunkMNIKXG7W_js.CimplifyError; }
 });
 exports.getServerClient = getServerClient;
 exports.revalidateBusiness = revalidateBusiness;

package/dist/server.mjs

@@ -1,6 +1,6 @@
-import { createCimplifyClient } from './chunk-3WD6U5RD.mjs';
-import './chunk-EZK2FXTM.mjs';
-export { CimplifyError } from './chunk-6TVQQYQ5.mjs';
+import { createCimplifyClient } from './chunk-UXLQ7WXI.mjs';
+import './chunk-7NML226B.mjs';
+export { CimplifyError } from './chunk-6AZZ6AOF.mjs';
 import { cache } from 'react';
 
 var DEFAULT_DEV_URL = "http://127.0.0.1:8787";

package/dist/testing/suite.d.mts

@@ -0,0 +1,60 @@
+import { C as CreateAppOptions } from '../server-CWpUlLOQ.mjs';
+import 'hono';
+
+/**
+ * Pre-baked test suites for scaffolded storefronts.
+ *
+ * Templates' `__tests__/*.test.ts` files are now ~5 lines each — they
+ * import their `brand` and call `createBrandSuite` / `createCartFlowSuite`
+ * / `createContractSuite`. One bug fix in this file → every template
+ * picks it up on `bun update @cimplify/sdk`.
+ *
+ *   // __tests__/brand.test.ts in any template:
+ *   import { createBrandSuite } from "@cimplify/sdk/testing/suite";
+ *   import { brand } from "../lib/brand";
+ *   createBrandSuite({ brand });
+ *
+ *   // __tests__/cart-flow.test.ts:
+ *   import { createCartFlowSuite } from "@cimplify/sdk/testing/suite";
+ *   import { brand } from "../lib/brand";
+ *   createCartFlowSuite({ seed: brand.mock.seed, businessId: brand.mock.businessId });
+ *
+ *   // __tests__/contract.test.ts:
+ *   import { createContractSuite } from "@cimplify/sdk/testing/suite";
+ *   import { brand } from "../lib/brand";
+ *   createContractSuite({ seed: brand.mock.seed });
+ */
+
+/**
+ * Brand sanity suite. Catches: missing required fields, placeholder
+ * strings shipped to prod, invalid email/url/locale/currency formats,
+ * mismatched seed/businessId pairing.
+ */
+declare function createBrandSuite(opts: {
+    brand: unknown;
+    label?: string;
+}): void;
+interface CartFlowOptions extends CreateAppOptions {
+    /** Expected business ID — asserts cart responses match the merchant. */
+    businessId?: string;
+    /** Override the describe() label. */
+    label?: string;
+}
+/**
+ * Cart flow suite. Boots the in-process mock, exercises add/dedupe/remove
+ * with shape assertions on every response. Catches: SDK ↔ mock contract
+ * drift, missing fields on cart items, add-to-cart not persisting,
+ * variant/payload silently dropped.
+ */
+declare function createCartFlowSuite(opts?: CartFlowOptions): void;
+interface ContractOptions extends CreateAppOptions {
+    label?: string;
+}
+/**
+ * Shape contract suite. Exercises the schemas against actual mock
+ * traffic. Catches: outbound payloads dropping required fields,
+ * inbound responses missing fields the storefront depends on.
+ */
+declare function createContractSuite(opts?: ContractOptions): void;
+
+export { createBrandSuite, createCartFlowSuite, createContractSuite };

package/dist/testing/suite.d.ts

@@ -0,0 +1,60 @@
+import { C as CreateAppOptions } from '../server-CWpUlLOQ.js';
+import 'hono';
+
+/**
+ * Pre-baked test suites for scaffolded storefronts.
+ *
+ * Templates' `__tests__/*.test.ts` files are now ~5 lines each — they
+ * import their `brand` and call `createBrandSuite` / `createCartFlowSuite`
+ * / `createContractSuite`. One bug fix in this file → every template
+ * picks it up on `bun update @cimplify/sdk`.
+ *
+ *   // __tests__/brand.test.ts in any template:
+ *   import { createBrandSuite } from "@cimplify/sdk/testing/suite";
+ *   import { brand } from "../lib/brand";
+ *   createBrandSuite({ brand });
+ *
+ *   // __tests__/cart-flow.test.ts:
+ *   import { createCartFlowSuite } from "@cimplify/sdk/testing/suite";
+ *   import { brand } from "../lib/brand";
+ *   createCartFlowSuite({ seed: brand.mock.seed, businessId: brand.mock.businessId });
+ *
+ *   // __tests__/contract.test.ts:
+ *   import { createContractSuite } from "@cimplify/sdk/testing/suite";
+ *   import { brand } from "../lib/brand";
+ *   createContractSuite({ seed: brand.mock.seed });
+ */
+
+/**
+ * Brand sanity suite. Catches: missing required fields, placeholder
+ * strings shipped to prod, invalid email/url/locale/currency formats,
+ * mismatched seed/businessId pairing.
+ */
+declare function createBrandSuite(opts: {
+    brand: unknown;
+    label?: string;
+}): void;
+interface CartFlowOptions extends CreateAppOptions {
+    /** Expected business ID — asserts cart responses match the merchant. */
+    businessId?: string;
+    /** Override the describe() label. */
+    label?: string;
+}
+/**
+ * Cart flow suite. Boots the in-process mock, exercises add/dedupe/remove
+ * with shape assertions on every response. Catches: SDK ↔ mock contract
+ * drift, missing fields on cart items, add-to-cart not persisting,
+ * variant/payload silently dropped.
+ */
+declare function createCartFlowSuite(opts?: CartFlowOptions): void;
+interface ContractOptions extends CreateAppOptions {
+    label?: string;
+}
+/**
+ * Shape contract suite. Exercises the schemas against actual mock
+ * traffic. Catches: outbound payloads dropping required fields,
+ * inbound responses missing fields the storefront depends on.
+ */
+declare function createContractSuite(opts?: ContractOptions): void;
+
+export { createBrandSuite, createCartFlowSuite, createContractSuite };

package/dist/testing/suite.js

@@ -0,0 +1,169 @@
+'use strict';
+
+var chunkXL4CX75J_js = require('../chunk-XL4CX75J.js');
+require('../chunk-MBGQP6FZ.js');
+require('../chunk-CFD4J32N.js');
+require('../chunk-MNIKXG7W.js');
+var vitest = require('vitest');
+
+var PLACEHOLDER_PHRASES = [
+  "lorem ipsum",
+  "todo",
+  "fixme",
+  "placeholder",
+  "your business name",
+  "your store"
+];
+function createBrandSuite(opts) {
+  vitest.describe(opts.label ?? "brand schema", () => {
+    vitest.it("conforms to the Cimplify brand contract", () => {
+      vitest.expect(() => chunkXL4CX75J_js.assertBrand(opts.brand)).not.toThrow();
+    });
+    vitest.it("declares a known mock seed", () => {
+      const b = opts.brand;
+      vitest.expect(chunkXL4CX75J_js.SeedNameSchema.safeParse(b.mock?.seed).success).toBe(true);
+    });
+    vitest.it("has no placeholder copy left in", () => {
+      const flat = JSON.stringify(opts.brand).toLowerCase();
+      for (const phrase of PLACEHOLDER_PHRASES) {
+        vitest.expect(flat, `brand contains placeholder phrase "${phrase}"`).not.toContain(phrase);
+      }
+    });
+    vitest.it("uses the bus_ businessId convention", () => {
+      const b = opts.brand;
+      vitest.expect(b.mock?.businessId).toMatch(/^bus_/);
+    });
+    vitest.it("zod-parses cleanly", () => {
+      const result = chunkXL4CX75J_js.BrandSchema.safeParse(opts.brand);
+      if (!result.success) {
+        throw new Error(
+          "Brand schema violations:\n" + result.error.issues.map((i) => `  \u2022 brand.${i.path.join(".")}: ${i.message}`).join("\n")
+        );
+      }
+      vitest.expect(result.success).toBe(true);
+    });
+  });
+}
+function createCartFlowSuite(opts = {}) {
+  vitest.describe(opts.label ?? "cart flow against in-process mock", () => {
+    let h;
+    vitest.beforeEach(() => {
+      h = chunkXL4CX75J_js.createTestClient(opts);
+    });
+    vitest.afterEach(() => h.dispose());
+    vitest.it("starts with an empty cart matching the canonical shape", async () => {
+      const res = await h.client.cart.get();
+      vitest.expect(res.ok).toBe(true);
+      if (!res.ok) return;
+      vitest.expect(() => chunkXL4CX75J_js.assertCart(res.value)).not.toThrow();
+      vitest.expect(res.value.items).toHaveLength(0);
+    });
+    vitest.it("adds the first product, persists it, and returns a shape-valid cart", async () => {
+      const { product, variantId } = await chunkXL4CX75J_js.fixtures.addFirstProduct(h.client);
+      vitest.expect(product.id).toBeTruthy();
+      const get = await h.client.cart.get();
+      vitest.expect(get.ok).toBe(true);
+      if (!get.ok) return;
+      vitest.expect(() => chunkXL4CX75J_js.assertCart(get.value)).not.toThrow();
+      vitest.expect(get.value.items).toHaveLength(1);
+      vitest.expect(get.value.items[0]?.item_id).toBe(product.id);
+      if (variantId) {
+        vitest.expect(get.value.items[0]?.variant_id).toBe(variantId);
+        const variantInfo = get.value.items[0]?.variant_info;
+        vitest.expect(variantInfo?.display_attributes).toBeDefined();
+      }
+      vitest.expect(parseFloat(String(get.value.pricing.subtotal))).toBeGreaterThan(0);
+    });
+    vitest.it("dedupes by line_key when adding the same product twice", async () => {
+      await chunkXL4CX75J_js.fixtures.addFirstProduct(h.client);
+      await chunkXL4CX75J_js.fixtures.addFirstProduct(h.client);
+      const res = await h.client.cart.get();
+      vitest.expect(res.ok).toBe(true);
+      if (!res.ok) return;
+      vitest.expect(res.value.items).toHaveLength(1);
+      vitest.expect(res.value.items[0]?.quantity).toBe(2);
+    });
+    vitest.it("removes items and zeroes the subtotal", async () => {
+      await chunkXL4CX75J_js.fixtures.addFirstProduct(h.client);
+      const before = await h.client.cart.get();
+      if (!before.ok) throw before.error;
+      const itemId = before.value.items[0]?.id;
+      vitest.expect(itemId).toBeTruthy();
+      const removed = await h.client.cart.removeItem(itemId);
+      vitest.expect(removed.ok).toBe(true);
+      const after = await h.client.cart.get();
+      if (!after.ok) throw after.error;
+      vitest.expect(after.value.items).toHaveLength(0);
+      vitest.expect(parseFloat(String(after.value.pricing.subtotal))).toBe(0);
+    });
+    if (opts.businessId) {
+      vitest.it("returns the brand's businessId on cart responses", async () => {
+        const res = await h.client.cart.get();
+        if (!res.ok) throw res.error;
+        vitest.expect(res.value.business_id).toBe(opts.businessId);
+      });
+    }
+  });
+}
+function createContractSuite(opts = {}) {
+  vitest.describe(opts.label ?? "SDK \u2194 mock contract", () => {
+    let h;
+    vitest.beforeEach(() => {
+      h = chunkXL4CX75J_js.createTestClient(opts);
+    });
+    vitest.afterEach(() => h.dispose());
+    vitest.it("AddItemPayload schema accepts a minimal valid body", () => {
+      const result = chunkXL4CX75J_js.AddItemPayloadSchema.safeParse({ item_id: "prod_x", quantity: 1 });
+      vitest.expect(result.success).toBe(true);
+    });
+    vitest.it("AddItemPayload schema rejects negative quantity", () => {
+      const result = chunkXL4CX75J_js.AddItemPayloadSchema.safeParse({ item_id: "prod_x", quantity: -1 });
+      vitest.expect(result.success).toBe(false);
+    });
+    vitest.it("AddItemPayload schema rejects empty item_id", () => {
+      const result = chunkXL4CX75J_js.AddItemPayloadSchema.safeParse({ item_id: "", quantity: 1 });
+      vitest.expect(result.success).toBe(false);
+    });
+    vitest.it("Cart line items returned by the mock match CartItemSchema", async () => {
+      const { product } = await chunkXL4CX75J_js.fixtures.addFirstProduct(h.client);
+      const get = await h.client.cart.get();
+      if (!get.ok) throw get.error;
+      vitest.expect(get.value.items.length).toBeGreaterThan(0);
+      for (const item of get.value.items) {
+        const result = chunkXL4CX75J_js.CartItemSchema.safeParse(item);
+        if (!result.success) {
+          const issues = result.error.issues.map((i) => `  \u2022 ${i.path.join(".")}: ${i.message}`).join("\n");
+          throw new Error(`Cart item shape mismatch for ${product.name}:
+${issues}`);
+        }
+        vitest.expect(result.success).toBe(true);
+      }
+    });
+    vitest.it("CheckoutResponse from the mock includes bill_token", async () => {
+      await chunkXL4CX75J_js.fixtures.addFirstProduct(h.client);
+      const cartRes = await h.client.cart.get();
+      if (!cartRes.ok) throw cartRes.error;
+      const checkout = await h.client.checkout.process({
+        cart_id: cartRes.value.id,
+        customer: chunkXL4CX75J_js.fixtures.customer(),
+        order_type: "delivery",
+        payment_method: "mobile_money",
+        mobile_money_details: { phone_number: "+233244000000", provider: "mtn" }
+      });
+      vitest.expect(checkout.ok).toBe(true);
+      if (!checkout.ok) return;
+      const result = chunkXL4CX75J_js.CheckoutResponseSchema.safeParse(checkout.value);
+      if (!result.success) {
+        const issues = result.error.issues.map((i) => `  \u2022 ${i.path.join(".")}: ${i.message}`).join("\n");
+        throw new Error(`CheckoutResponse shape mismatch:
+${issues}`);
+      }
+      vitest.expect(checkout.value.bill_token).toBeTruthy();
+      vitest.expect(checkout.value.order_id).toBeTruthy();
+    });
+  });
+}
+
+exports.createBrandSuite = createBrandSuite;
+exports.createCartFlowSuite = createCartFlowSuite;
+exports.createContractSuite = createContractSuite;

package/dist/testing/suite.mjs

@@ -0,0 +1,165 @@
+import { assertBrand, SeedNameSchema, BrandSchema, createTestClient, assertCart, fixtures, AddItemPayloadSchema, CartItemSchema, CheckoutResponseSchema } from '../chunk-ZLEFMQC6.mjs';
+import '../chunk-UXLQ7WXI.mjs';
+import '../chunk-7NML226B.mjs';
+import '../chunk-6AZZ6AOF.mjs';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+var PLACEHOLDER_PHRASES = [
+  "lorem ipsum",
+  "todo",
+  "fixme",
+  "placeholder",
+  "your business name",
+  "your store"
+];
+function createBrandSuite(opts) {
+  describe(opts.label ?? "brand schema", () => {
+    it("conforms to the Cimplify brand contract", () => {
+      expect(() => assertBrand(opts.brand)).not.toThrow();
+    });
+    it("declares a known mock seed", () => {
+      const b = opts.brand;
+      expect(SeedNameSchema.safeParse(b.mock?.seed).success).toBe(true);
+    });
+    it("has no placeholder copy left in", () => {
+      const flat = JSON.stringify(opts.brand).toLowerCase();
+      for (const phrase of PLACEHOLDER_PHRASES) {
+        expect(flat, `brand contains placeholder phrase "${phrase}"`).not.toContain(phrase);
+      }
+    });
+    it("uses the bus_ businessId convention", () => {
+      const b = opts.brand;
+      expect(b.mock?.businessId).toMatch(/^bus_/);
+    });
+    it("zod-parses cleanly", () => {
+      const result = BrandSchema.safeParse(opts.brand);
+      if (!result.success) {
+        throw new Error(
+          "Brand schema violations:\n" + result.error.issues.map((i) => `  \u2022 brand.${i.path.join(".")}: ${i.message}`).join("\n")
+        );
+      }
+      expect(result.success).toBe(true);
+    });
+  });
+}
+function createCartFlowSuite(opts = {}) {
+  describe(opts.label ?? "cart flow against in-process mock", () => {
+    let h;
+    beforeEach(() => {
+      h = createTestClient(opts);
+    });
+    afterEach(() => h.dispose());
+    it("starts with an empty cart matching the canonical shape", async () => {
+      const res = await h.client.cart.get();
+      expect(res.ok).toBe(true);
+      if (!res.ok) return;
+      expect(() => assertCart(res.value)).not.toThrow();
+      expect(res.value.items).toHaveLength(0);
+    });
+    it("adds the first product, persists it, and returns a shape-valid cart", async () => {
+      const { product, variantId } = await fixtures.addFirstProduct(h.client);
+      expect(product.id).toBeTruthy();
+      const get = await h.client.cart.get();
+      expect(get.ok).toBe(true);
+      if (!get.ok) return;
+      expect(() => assertCart(get.value)).not.toThrow();
+      expect(get.value.items).toHaveLength(1);
+      expect(get.value.items[0]?.item_id).toBe(product.id);
+      if (variantId) {
+        expect(get.value.items[0]?.variant_id).toBe(variantId);
+        const variantInfo = get.value.items[0]?.variant_info;
+        expect(variantInfo?.display_attributes).toBeDefined();
+      }
+      expect(parseFloat(String(get.value.pricing.subtotal))).toBeGreaterThan(0);
+    });
+    it("dedupes by line_key when adding the same product twice", async () => {
+      await fixtures.addFirstProduct(h.client);
+      await fixtures.addFirstProduct(h.client);
+      const res = await h.client.cart.get();
+      expect(res.ok).toBe(true);
+      if (!res.ok) return;
+      expect(res.value.items).toHaveLength(1);
+      expect(res.value.items[0]?.quantity).toBe(2);
+    });
+    it("removes items and zeroes the subtotal", async () => {
+      await fixtures.addFirstProduct(h.client);
+      const before = await h.client.cart.get();
+      if (!before.ok) throw before.error;
+      const itemId = before.value.items[0]?.id;
+      expect(itemId).toBeTruthy();
+      const removed = await h.client.cart.removeItem(itemId);
+      expect(removed.ok).toBe(true);
+      const after = await h.client.cart.get();
+      if (!after.ok) throw after.error;
+      expect(after.value.items).toHaveLength(0);
+      expect(parseFloat(String(after.value.pricing.subtotal))).toBe(0);
+    });
+    if (opts.businessId) {
+      it("returns the brand's businessId on cart responses", async () => {
+        const res = await h.client.cart.get();
+        if (!res.ok) throw res.error;
+        expect(res.value.business_id).toBe(opts.businessId);
+      });
+    }
+  });
+}
+function createContractSuite(opts = {}) {
+  describe(opts.label ?? "SDK \u2194 mock contract", () => {
+    let h;
+    beforeEach(() => {
+      h = createTestClient(opts);
+    });
+    afterEach(() => h.dispose());
+    it("AddItemPayload schema accepts a minimal valid body", () => {
+      const result = AddItemPayloadSchema.safeParse({ item_id: "prod_x", quantity: 1 });
+      expect(result.success).toBe(true);
+    });
+    it("AddItemPayload schema rejects negative quantity", () => {
+      const result = AddItemPayloadSchema.safeParse({ item_id: "prod_x", quantity: -1 });
+      expect(result.success).toBe(false);
+    });
+    it("AddItemPayload schema rejects empty item_id", () => {
+      const result = AddItemPayloadSchema.safeParse({ item_id: "", quantity: 1 });
+      expect(result.success).toBe(false);
+    });
+    it("Cart line items returned by the mock match CartItemSchema", async () => {
+      const { product } = await fixtures.addFirstProduct(h.client);
+      const get = await h.client.cart.get();
+      if (!get.ok) throw get.error;
+      expect(get.value.items.length).toBeGreaterThan(0);
+      for (const item of get.value.items) {
+        const result = CartItemSchema.safeParse(item);
+        if (!result.success) {
+          const issues = result.error.issues.map((i) => `  \u2022 ${i.path.join(".")}: ${i.message}`).join("\n");
+          throw new Error(`Cart item shape mismatch for ${product.name}:
+${issues}`);
+        }
+        expect(result.success).toBe(true);
+      }
+    });
+    it("CheckoutResponse from the mock includes bill_token", async () => {
+      await fixtures.addFirstProduct(h.client);
+      const cartRes = await h.client.cart.get();
+      if (!cartRes.ok) throw cartRes.error;
+      const checkout = await h.client.checkout.process({
+        cart_id: cartRes.value.id,
+        customer: fixtures.customer(),
+        order_type: "delivery",
+        payment_method: "mobile_money",
+        mobile_money_details: { phone_number: "+233244000000", provider: "mtn" }
+      });
+      expect(checkout.ok).toBe(true);
+      if (!checkout.ok) return;
+      const result = CheckoutResponseSchema.safeParse(checkout.value);
+      if (!result.success) {
+        const issues = result.error.issues.map((i) => `  \u2022 ${i.path.join(".")}: ${i.message}`).join("\n");
+        throw new Error(`CheckoutResponse shape mismatch:
+${issues}`);
+      }
+      expect(checkout.value.bill_token).toBeTruthy();
+      expect(checkout.value.order_id).toBeTruthy();
+    });
+  });
+}
+
+export { createBrandSuite, createCartFlowSuite, createContractSuite };