@usequeek/theme-kit 0.1.14 → 0.1.16

package/components/cart/cart-panel-controller.tsx

@@ -8,6 +8,7 @@ import { useStorefront } from '../../provider';
 import { useHref } from '../../hooks/use-href';
 import { useShopCart } from '../../hooks/use-shop-cart';
 import { useCartPanelStore } from '../../stores/cart-panel-store';
+import { normalizeCurrencyCode } from '../../utils/format';
 
 export interface CartPanelControllerRenderProps {
   isOpen: boolean;
@@ -57,7 +58,9 @@ export function CartPanelController({
     isOpen,
     items,
     total,
-    currency: vendor.currency ?? 'NGN',
+    // Store-wide display uses the vendor's currency; item rows carry their own.
+    // List-level meta.currency is never read (platform default, wrong per store).
+    currency: normalizeCurrencyCode(vendor.currency),
     onClose: closePanel,
     onCheckout: () => navigate('/checkout'),
     onViewCart: () => navigate('/cart'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",

package/stores/cart-store.ts

@@ -5,6 +5,7 @@ import { createJSONStorage, persist } from 'zustand/middleware';
 import type { CartAddon, CartItem } from '../types/cart';
 import type { Product, ProductVariant } from '../types/product';
 import { toast } from './toast-store';
+import { normalizeCurrencyCode, PLATFORM_DEFAULT_CURRENCY } from '../utils/format';
 import { pushAddToCart } from '../apps/analytics-events';
 import { getActivePlatform, platformScopedStorage } from '../sdk/platform';
 import { productRequiresVariant } from '../utils/match-variant';
@@ -13,8 +14,9 @@ interface CartState {
   items: CartItem[];
   /** Set once per vendor mount (see vendor-shell.tsx) — the store has no
    *  React context, so this is how it learns the active vendor's currency
-   *  for GA4 event values. Defaults to the same 'NGN' fallback used
-   *  everywhere else in the storefront (see checkout-controller.tsx). */
+   *  for GA4 event values. The initial value is the platform default as a
+   *  last resort only; vendor-shell overwrites it with the vendor's currency
+   *  on mount. List-level `meta.currency` is never a source. */
   currency: string;
   setCurrency: (currency: string) => void;
   addProduct: (product: Product, quantity?: number, variant?: ProductVariant | null) => void;
@@ -50,8 +52,8 @@ export const useCartStore = create<CartState>()(
   persist(
     (set, get) => ({
       items: [],
-      currency: 'NGN',
-      setCurrency: (currency) => set({ currency }),
+      currency: PLATFORM_DEFAULT_CURRENCY,
+      setCurrency: (currency) => set({ currency: normalizeCurrencyCode(currency) }),
       addProduct: (product, quantity = 1, variant = null) => {
         get().addItemWithAddons(product, quantity, [], variant);
       },

package/tests/currency-contract.test.ts

@@ -0,0 +1,86 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { formatMoney, normalizeCurrencyCode, PLATFORM_DEFAULT_CURRENCY } from '../utils/format';
+import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
+import { useCartStore } from '../stores/cart-store';
+
+/**
+ * Slice 2 of api-currency-contract-fix: client readers off `meta.currency`.
+ * List-level `meta.currency` stamps the PLATFORM default (NGN) even on
+ * non-NGN stores, so the item's own `currency` code is the source and the
+ * vendor's currency is the store-wide source. Missing codes fall back to the
+ * platform default as a LAST resort, in exactly one place.
+ */
+describe('currency contract (Slice 2)', () => {
+  it('exposes NGN as the platform default last resort', () => {
+    expect(PLATFORM_DEFAULT_CURRENCY).toBe('NGN');
+  });
+
+  it('normalizeCurrencyCode keeps valid item/vendor codes', () => {
+    expect(normalizeCurrencyCode('USD')).toBe('USD');
+    expect(normalizeCurrencyCode('ngn')).toBe('NGN');
+    expect(normalizeCurrencyCode('  eur  ')).toBe('EUR');
+  });
+
+  it('normalizeCurrencyCode falls back instead of passing garbage through', () => {
+    expect(normalizeCurrencyCode(undefined)).toBe('NGN');
+    expect(normalizeCurrencyCode(null)).toBe('NGN');
+    expect(normalizeCurrencyCode('')).toBe('NGN');
+    expect(normalizeCurrencyCode('US')).toBe('NGN');
+    expect(normalizeCurrencyCode('USDD')).toBe('NGN');
+    expect(normalizeCurrencyCode(42)).toBe('NGN');
+  });
+
+  it('normalizeCurrencyCode honors an explicit vendor fallback', () => {
+    expect(normalizeCurrencyCode(undefined, 'USD')).toBe('USD');
+    expect(normalizeCurrencyCode('', 'eur')).toBe('EUR');
+    expect(normalizeCurrencyCode(undefined, 'bogus')).toBe('NGN');
+  });
+
+  it('normalizeProduct keeps the item currency, ignoring list-level meta', () => {
+    const envelope = {
+      data: [{ id: 'p1', title: 'Tote', price: 5000, currency: 'usd' }],
+      meta: { currency: { code: 'NGN', symbol: '₦' } },
+    };
+    const [raw] = extractProducts(envelope);
+    expect(normalizeProduct(raw).currency).toBe('USD');
+  });
+
+  it('normalizeProduct falls back to the platform default when the item has none', () => {
+    const [raw] = extractProducts({ data: [{ id: 'p2', title: 'Cap', price: 1000 }] });
+    expect(normalizeProduct(raw).currency).toBe('NGN');
+  });
+
+  it('formatMoney formats through the item code, not a wired symbol', () => {
+    expect(formatMoney(12500)).toBe('₦12,500');
+    const usd = formatMoney(5000, 'USD');
+    expect(usd).toContain('5,000');
+    expect(usd).not.toContain('₦');
+  });
+
+  it('cart-store currency starts at the platform default and normalizes vendor init', () => {
+    expect(useCartStore.getState().currency).toBe('NGN');
+    useCartStore.getState().setCurrency('usd');
+    expect(useCartStore.getState().currency).toBe('USD');
+    useCartStore.getState().setCurrency('');
+    expect(useCartStore.getState().currency).toBe('NGN');
+  });
+
+  it('no kit source reads list-level meta.currency', () => {
+    const ROOT = resolve(__dirname, '..');
+    const walk = (dir: string): string[] => readdirSync(dir).flatMap((entry) => {
+      const path = join(dir, entry);
+      if (entry === 'node_modules' || entry === 'tests' || entry.startsWith('.')) return [];
+      if (statSync(path).isDirectory()) return walk(path);
+      return /\.(ts|tsx)$/.test(entry) ? [path] : [];
+    });
+    const offenders = walk(ROOT).flatMap((file) => {
+      const source = readFileSync(file, 'utf8');
+      // Real reads use `?.` or a `.meta` access (`payload?.meta?.currency`,
+      // `data.meta.currency`); prose comments naming the contract don't count.
+      return /meta\?\.\s*currency|\.meta\.currency/.test(source) ? [relative(ROOT, file)] : [];
+    });
+    expect(offenders).toEqual([]);
+  });
+});

package/tests/orders-walk.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { fetchOrders } from '../api/orders';
+
+/**
+ * `GET store/orders` answers the ONE storefront list envelope (pagination
+ * Slice 4b, founder 28/9/26): `has_more` + `next_cursor` top-level, no
+ * `links`, no paginator `meta`. The kit reads the page it asked for.
+ */
+describe('fetchOrders walk state', () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it('asks /client/store/orders by page and returns the top-level walk state', async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        status: 'success',
+        message: 'Orders retrieved',
+        data: [{ id: 'o1', order_no: 'Q-1' }],
+        meta: { currency: { code: 'NGN' } },
+        has_more: true,
+        next_cursor: 'eyJ2IjoxfQ',
+      }),
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const page = await fetchOrders('kili-foods', 2, 'ongoing');
+
+    const url = String((fetchMock.mock.calls[0] as unknown[])[0]);
+    expect(url).toContain('/client/store/orders');
+    expect(url).toContain('page=2');
+    expect(url).toContain('status=ongoing');
+    expect(page.has_more).toBe(true);
+    expect(page.next_cursor).toBe('eyJ2IjoxfQ');
+    expect(page).not.toHaveProperty('links');
+    expect(page.data).toHaveLength(1);
+  });
+
+  it('never sends status=all (the unfiltered list)', async () => {
+    const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ data: [], has_more: false, next_cursor: null }) }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const page = await fetchOrders('kili-foods', 1, 'all');
+
+    expect(String((fetchMock.mock.calls[0] as unknown[])[0])).not.toContain('status=');
+    expect(page.has_more).toBe(false);
+    expect(page.next_cursor).toBeNull();
+  });
+});

package/types/order.ts

@@ -85,16 +85,18 @@ export interface OrderDetail {
   table?: { id: string; name: string; section?: string | null } | null;
 }
 
-export interface OrderPageMeta {
-  current_page: number;
-  last_page: number;
-  per_page: number;
-  total: number;
-}
-
+/**
+ * `GET store/orders` — the ONE storefront list envelope: the walk state rides
+ * top-level. A page-mode reader (`?page=N`) labels the page it asked for and
+ * loads the next while `has_more` is true; a cursor reader passes
+ * `next_cursor` back as `starting_after`. No totals, page counts or page URLs
+ * are sent; `meta` is context only (e.g. `currency`).
+ */
 export interface OrderListResponse {
   data: OrderListItem[];
-  meta: OrderPageMeta;
+  has_more: boolean;
+  next_cursor: string | null;
+  meta?: Record<string, unknown>;
 }
 
 export interface CheckoutPayload {

package/utils/format.ts

@@ -42,7 +42,29 @@ export function formatCount(value: number): string {
   return value.toLocaleString(DISPLAY_LOCALE);
 }
 
-export function formatMoney(amount: number, currency = 'NGN'): string {
+/**
+ * Platform default — the LAST resort only. Item rows carry their own
+ * `currency` code (see normalizeProduct) and store-wide display uses the
+ * vendor's currency (cart-store, set from vendor-shell on mount). A missing
+ * or malformed code must resolve through this function, never a bare
+ * `?? 'NGN'` at a call site, so the fallback stays in exactly one place.
+ */
+export const PLATFORM_DEFAULT_CURRENCY = 'NGN';
+
+/**
+ * The ONE currency-code resolver: trims/uppercases the item or vendor code,
+ * accepts it when it is a 3-letter code, and returns the platform default
+ * otherwise. List-level `meta.currency` is never consulted — it stamps the
+ * platform default even on non-NGN stores (api-currency-contract-fix).
+ */
+export function normalizeCurrencyCode(value: unknown, fallback: string = PLATFORM_DEFAULT_CURRENCY): string {
+  const code = typeof value === 'string' ? value.trim().toUpperCase() : '';
+  if (/^[A-Z]{3}$/.test(code)) return code;
+  const cleanFallback = typeof fallback === 'string' ? fallback.trim().toUpperCase() : '';
+  return /^[A-Z]{3}$/.test(cleanFallback) ? cleanFallback : PLATFORM_DEFAULT_CURRENCY;
+}
+
+export function formatMoney(amount: number, currency = PLATFORM_DEFAULT_CURRENCY): string {
   try {
     return new Intl.NumberFormat('en-NG', {
       style: 'currency',

package/utils/product-normalizer.ts

@@ -8,6 +8,7 @@ import type {
   ProductPricing,
   ProductVariantOptionValue,
 } from '../types/product';
+import { normalizeCurrencyCode } from './format';
 
 const KIND_SET = new Set(['physical', 'service', 'digital']);
 const STATUS_SET = new Set(['active', 'inactive']);
@@ -267,7 +268,10 @@ export function normalizeProduct(raw: LegacyProductLike): Product {
         ? (raw.status as Product['status'])
         : 'active',
     barcode: typeof raw.barcode === 'string' && raw.barcode !== '' ? raw.barcode : null,
-    currency: String(raw.currency ?? 'NGN'),
+    // Item-level code is the source — list-level meta.currency is never read
+    // (it stamps the platform default even on non-NGN stores). Missing or
+    // malformed codes fall back to the platform default as a last resort.
+    currency: normalizeCurrencyCode(raw.currency),
     pricing: normalizePricing(raw),
     shop: {
       id: String(raw.shop?.id ?? raw.vendor?.id ?? shopId),