@fayz-ai/storefront 0.2.0

package/src/components/sections/MiscSections.tsx

@@ -0,0 +1,157 @@
+import React, { useState } from 'react'
+import * as LucideIcons from 'lucide-react'
+import { bannerPlaceholder } from '../../sections'
+import { Reveal } from '../../motion'
+import { Link } from '../../router'
+import { TID } from '../../testids'
+
+function Icon({ name, className }: { name: string; className?: string }) {
+  const C = (LucideIcons as unknown as Record<string, React.ComponentType<{ className?: string }>>)[name]
+  return C ? <C className={className} /> : null
+}
+
+export function BenefitsRow({ items }: { items: Array<{ icon: string; title: string; text?: string }> }) {
+  return (
+    <section data-testid={TID.benefits} className="border-y bg-card">
+      <div className="mx-auto grid max-w-7xl grid-cols-1 gap-6 px-4 py-9 sm:grid-cols-3 sm:px-6">
+        {items.slice(0, 4).map((item, i) => (
+          <Reveal key={i} delay={i * 120} className="flex items-center justify-center gap-3 text-center sm:text-left">
+            <span className="flex h-12 w-12 shrink-0 items-center justify-center rounded-full bg-primary/10">
+              <Icon name={item.icon} className="h-6 w-6 text-primary" />
+            </span>
+            <div>
+              <p className="font-semibold">{item.title}</p>
+              {item.text && <p className="text-sm text-muted-foreground">{item.text}</p>}
+            </div>
+          </Reveal>
+        ))}
+      </div>
+    </section>
+  )
+}
+
+export function PromoBanner({
+  title,
+  subtitle,
+  eyebrow,
+  cta,
+  href,
+  image,
+  hue = 160,
+}: {
+  title: string
+  subtitle?: string
+  eyebrow?: string
+  cta?: string
+  href?: string
+  image?: string
+  hue?: number
+}) {
+  return (
+    <section data-testid={TID.promoBanner} className="group relative my-12 overflow-hidden">
+      <img
+        src={image ?? bannerPlaceholder(title, hue, hue + 50, 1600, 420)}
+        alt={title}
+        className="h-80 w-full object-cover transition-transform duration-700 ease-out group-hover:scale-105"
+      />
+      <div className="absolute inset-0 flex flex-col items-center justify-center bg-gradient-to-t from-black/65 via-black/35 to-black/20 p-6 text-center text-white">
+        <Reveal>
+          {eyebrow && (
+            <p className="mb-2 text-xs font-semibold uppercase tracking-[0.25em] text-white/80">{eyebrow}</p>
+          )}
+          <h2 className="sf-heading text-3xl font-bold drop-shadow sm:text-5xl">{title}</h2>
+          {subtitle && <p className="mt-3 max-w-lg text-white/90">{subtitle}</p>}
+          {cta && (
+            <Link
+              to={href ?? '/catalog'}
+              className="sf-cta mt-6 inline-block bg-white px-8 py-3 font-semibold text-gray-900 shadow-lg transition-all hover:-translate-y-0.5 hover:shadow-xl"
+              style={{ borderRadius: 'var(--sf-radius-button)' }}
+            >
+              {cta}
+            </Link>
+          )}
+        </Reveal>
+      </div>
+    </section>
+  )
+}
+
+export function ManifestoBlock({ title, text }: { title?: string; text: string }) {
+  return (
+    <section data-testid={TID.manifesto} className="mx-auto max-w-3xl px-4 py-14 text-center sm:px-6">
+      {title && <h2 className="sf-heading mb-5 text-2xl font-bold">{title}</h2>}
+      <p className="sf-heading text-xl leading-relaxed text-muted-foreground sm:text-2xl">{text}</p>
+    </section>
+  )
+}
+
+export function Testimonials({ title, items }: { title?: string; items: Array<{ quote: string; author: string }> }) {
+  return (
+    <section data-testid={TID.testimonials} className="bg-muted/50 py-14">
+      <div className="mx-auto max-w-7xl px-4 sm:px-6">
+        {title && (
+          <Reveal>
+            <h2 className="sf-heading mb-10 text-center text-3xl font-bold">{title}</h2>
+          </Reveal>
+        )}
+        <div className="grid gap-6 md:grid-cols-3">
+          {items.slice(0, 3).map((t, i) => (
+            <Reveal key={i} delay={i * 130}>
+              <figure
+                className="h-full bg-card p-7 shadow-sm transition-shadow hover:shadow-md"
+                style={{ borderRadius: 'var(--sf-radius-card)' }}
+              >
+                <div className="mb-3 text-primary" aria-hidden>★★★★★</div>
+                <blockquote className="leading-relaxed">“{t.quote}”</blockquote>
+                <figcaption className="mt-4 text-sm font-semibold text-muted-foreground">— {t.author}</figcaption>
+              </figure>
+            </Reveal>
+          ))}
+        </div>
+      </div>
+    </section>
+  )
+}
+
+export function NewsletterBand({ title, subtitle }: { title?: string; subtitle?: string }) {
+  const [email, setEmail] = useState('')
+  const [done, setDone] = useState(false)
+  return (
+    <section data-testid={TID.newsletter} className="bg-primary py-16 text-primary-foreground">
+      <Reveal className="mx-auto max-w-xl px-4 text-center sm:px-6">
+        <h2 className="sf-heading text-3xl font-bold">{title ?? 'Receba nossas novidades'}</h2>
+        {subtitle && <p className="mt-2 opacity-90">{subtitle}</p>}
+        {done ? (
+          <p data-testid={TID.newsletterDone} className="mt-6 font-medium">Inscrição confirmada! 🎉</p>
+        ) : (
+          <form
+            className="mt-6 flex gap-2"
+            onSubmit={(e) => {
+              e.preventDefault()
+              if (email.trim()) setDone(true)
+            }}
+          >
+            <input
+              data-testid={TID.newsletterEmail}
+              type="email"
+              required
+              placeholder="Seu e-mail"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              className="flex-1 border-0 bg-white/95 px-4 py-3 text-sm text-gray-900 outline-none"
+              style={{ borderRadius: 'var(--sf-radius-input)' }}
+            />
+            <button
+              type="submit"
+              data-testid={TID.newsletterSubmit}
+              className="sf-cta bg-foreground px-6 py-3 text-sm font-semibold text-background"
+              style={{ borderRadius: 'var(--sf-radius-button)' }}
+            >
+              Assinar
+            </button>
+          </form>
+        )}
+      </Reveal>
+    </section>
+  )
+}

package/src/components/sections/ProductRail.tsx

@@ -0,0 +1,73 @@
+import React, { useMemo } from 'react'
+import { useProducts } from '../../hooks/useProducts'
+import { useStorefrontConfig } from '../../config'
+import { ProductCard } from '../ProductCard'
+import { Reveal } from '../../motion'
+import { Link } from '../../router'
+import { TID } from '../../testids'
+
+export function ProductRail({
+  title,
+  subtitle,
+  eyebrow,
+  filter = 'all',
+  limit = 4,
+}: {
+  title: string
+  subtitle?: string
+  eyebrow?: string
+  filter?: 'sale' | 'new' | 'all'
+  limit?: number
+}) {
+  const config = useStorefrontConfig()
+  const ProductCardComponent = config.slots?.ProductCard ?? ProductCard
+  const { products, loading } = useProducts(
+    filter === 'new'
+      ? { status: 'active', orderBy: 'created_at', order: 'desc' }
+      : { status: 'active' },
+  )
+
+  const visible = useMemo(() => {
+    let list = products
+    if (filter === 'sale') list = list.filter((p) => p.compareAtPrice != null && p.compareAtPrice > p.price)
+    return list.slice(0, limit)
+  }, [products, filter, limit])
+
+  if (!loading && visible.length === 0) return null
+
+  return (
+    <section data-testid={TID.productRail} className="mx-auto max-w-7xl px-4 py-14 sm:px-6">
+      <Reveal className="mb-10 text-center">
+        {eyebrow && (
+          <p className="mb-2 text-xs font-semibold uppercase tracking-[0.2em] text-primary">{eyebrow}</p>
+        )}
+        <h2 className="sf-heading text-3xl font-bold tracking-tight">{title}</h2>
+        {subtitle && <p className="mt-2 text-muted-foreground">{subtitle}</p>}
+      </Reveal>
+      {loading ? (
+        <div className="grid grid-cols-2 gap-5 md:grid-cols-4">
+          {Array.from({ length: limit }, (_, i) => (
+            <div key={i} className="aspect-[3/4] animate-pulse bg-muted" style={{ borderRadius: 'var(--sf-radius-card)' }} />
+          ))}
+        </div>
+      ) : (
+        <div className="grid grid-cols-2 gap-5 md:grid-cols-4">
+          {visible.map((p, i) => (
+            <Reveal key={p.id} delay={i * 90}>
+              <ProductCardComponent product={p} />
+            </Reveal>
+          ))}
+        </div>
+      )}
+      <Reveal className="mt-10 text-center" delay={200}>
+        <Link
+          to={config.catalogPath}
+          className="sf-cta inline-block border border-foreground/30 px-7 py-2.5 text-sm font-semibold transition-all hover:-translate-y-0.5 hover:bg-foreground hover:text-background hover:shadow"
+          style={{ borderRadius: 'var(--sf-radius-button)' }}
+        >
+          Ver tudo
+        </Link>
+      </Reveal>
+    </section>
+  )
+}

package/src/config.ts

@@ -0,0 +1,176 @@
+import React, { createContext, useContext } from 'react'
+import type { Product } from '@fayz-ai/shop/types'
+import type { ShopProvider } from '@fayz-ai/shop/provider'
+import type { MockShopSeed } from '@fayz-ai/shop/mock'
+import type { StorefrontTheme } from './theme'
+import type { HomeConfig, NavLink, FooterConfig } from './sections'
+import type { StorefrontAuthAdapter } from './auth'
+
+export interface ProductCardSlotProps {
+  product: Product
+}
+
+export type StorefrontRouteKind =
+  | 'home'
+  | 'catalog'
+  | 'product'
+  | 'checkout'
+  | 'account'
+  | 'order'
+  | 'custom'
+
+export type StorefrontRouteParams = Record<string, string>
+
+export interface StorefrontRouteComponentProps {
+  path: string
+  params: StorefrontRouteParams
+  config: ResolvedStorefrontConfig
+}
+
+export type StorefrontRouteChrome = 'default' | 'focused'
+
+export interface StorefrontRouteDefinition {
+  /**
+   * Stable identifier for generated-code diffs, QA reports, and route ownership.
+   */
+  id: string
+  /**
+   * Hash route pattern. Supports the same params as matchPath, e.g. '/checkout'
+   * or '/collections/:slug'. Custom routes are matched before SDK defaults.
+   */
+  path: string
+  /**
+   * Intent label for agents and manifests. It does not change matching behavior.
+   */
+  kind?: StorefrontRouteKind
+  /**
+   * Shell chrome for the route. `focused` hides storefront nav/footer/cart
+   * around high-intent flows such as checkout.
+   */
+  chrome?: StorefrontRouteChrome
+  /**
+   * App-owned screen/workflow that can still use storefront/shop primitives.
+   */
+  component: React.ComponentType<StorefrontRouteComponentProps>
+}
+
+export interface StorefrontSlots {
+  /**
+   * Product card renderer used by catalog grids and product rails.
+   *
+   * Custom renderers must preserve `productCardSlotContract` selectors so
+   * checkout smoke tests, QA, and agents can still operate the storefront.
+   */
+  ProductCard?: React.ComponentType<ProductCardSlotProps>
+}
+
+export interface StorefrontDiscountConfig {
+  code: string
+  percent: number
+  title?: string
+}
+
+export interface StorefrontConfig {
+  /** Store display name (header, page title) */
+  name: string
+  /** Optional logo node; defaults to the store name */
+  logo?: React.ReactNode
+  /** ISO 4217 — default 'BRL' */
+  currency?: string
+  /** Intl locale for money/date formatting — default 'pt-BR' */
+  locale?: string
+  /** Visual identity: colors, fonts, radius, header/card personality */
+  theme?: StorefrontTheme
+  /** Promo message above the header (e.g. 'FRETE GRÁTIS ACIMA DE R$ 300') */
+  announcement?: string
+  /** Home page blueprint. When set, `/` renders it and the catalog moves to /catalog. */
+  home?: HomeConfig
+  /** Header nav links — defaults derived from home/catalog routing */
+  nav?: NavLink[]
+  /** Footer content (about text, contact, social) */
+  footer?: FooterConfig
+  /** Preferred backend descriptor for manifest/scaffold metadata. */
+  backend?: { provider?: 'mock' | 'fayz-api' | 'fayz-shop' | 'custom'; url?: string }
+  /** @deprecated Use backend/provider adapters. Storefront no longer creates Supabase clients. */
+  supabaseUrl?: string
+  /** @deprecated Use backend/provider adapters. Storefront no longer creates Supabase clients. */
+  supabaseAnonKey?: string
+  /** Explicit provider override (tests, custom backends) */
+  provider?: ShopProvider
+  /** Per-store mock catalog (products/categories/discounts) for mock mode */
+  catalog?: MockShopSeed
+  /** Store-level discount codes available regardless of provider backend. */
+  discounts?: StorefrontDiscountConfig[]
+  /**
+   * Institutional/legal page content (privacy, terms, returns). Plain text —
+   * blank lines separate paragraphs. Unset pages render a placeholder so the
+   * routes (and footer links) exist even before the store writes its policy.
+   */
+  legal?: { privacy?: string; terms?: string; returns?: string }
+  /** Customer auth — same AuthAdapter contract as createSaasApp. Default: mock. */
+  auth?: { adapter?: StorefrontAuthAdapter }
+  /** Shipping pricing — default { flatRate: 0 } */
+  shipping?: { flatRate?: number; freeAbove?: number }
+  /**
+   * Payment behavior. v1 default 'mock' instantly marks orders paid with NO
+   * real charge (demo). M4 sets 'pix-mercadopago' so orders stay pending until
+   * a real payment webhook confirms settlement.
+   */
+  payments?: { mode?: 'mock' | 'pix-mercadopago' }
+  /** Feature toggles — discounts default off; accounts default on */
+  features?: { discounts?: boolean; accounts?: boolean }
+  /** Code-level customization slots. Kept out of serialized manifests. */
+  slots?: StorefrontSlots
+  /** Code-level route overrides/custom routes. Kept out of serialized manifests. */
+  routes?: StorefrontRouteDefinition[]
+}
+
+export interface ResolvedStorefrontConfig extends StorefrontConfig {
+  currency: string
+  locale: string
+  shipping: { flatRate: number; freeAbove?: number }
+  payments: { mode: 'mock' | 'pix-mercadopago' }
+  features: { discounts: boolean; accounts: boolean }
+  /** Where the full product list lives ('/' without a home page, '/catalog' with one) */
+  catalogPath: string
+  nav: NavLink[]
+}
+
+export function resolveConfig(config: StorefrontConfig): ResolvedStorefrontConfig {
+  const catalogPath = config.home ? '/catalog' : '/'
+  return {
+    ...config,
+    currency: config.currency ?? 'BRL',
+    locale: config.locale ?? 'pt-BR',
+    shipping: { flatRate: config.shipping?.flatRate ?? 0, freeAbove: config.shipping?.freeAbove },
+    payments: { mode: config.payments?.mode ?? 'mock' },
+    features: {
+      // Auto-enable the coupon UI when the store actually ships discount codes
+      // (via config.discounts or a seeded catalog), unless explicitly overridden —
+      // otherwise a store can advertise a coupon with no field to enter it.
+      discounts:
+        config.features?.discounts ??
+        Boolean(config.discounts?.length || config.catalog?.discounts?.length),
+      accounts: config.features?.accounts ?? true,
+    },
+    catalogPath,
+    nav:
+      config.nav ??
+      (config.home
+        ? [
+            { label: 'Início', to: '/' },
+            { label: 'Loja', to: '/catalog' },
+          ]
+        : [{ label: 'Loja', to: '/' }]),
+  }
+}
+
+const StorefrontConfigContext = createContext<ResolvedStorefrontConfig | null>(null)
+
+export const StorefrontConfigProvider = StorefrontConfigContext.Provider
+
+export function useStorefrontConfig(): ResolvedStorefrontConfig {
+  const ctx = useContext(StorefrontConfigContext)
+  if (!ctx) throw new Error('useStorefrontConfig must be used inside createStorefrontApp')
+  return ctx
+}

package/src/createStorefrontApp.tsx

@@ -0,0 +1,171 @@
+import React from 'react'
+import { setShopProvider } from '@fayz-ai/shop/runtime'
+import { createMockShopProvider } from '@fayz-ai/shop/mock'
+import type { MockShopSeed } from '@fayz-ai/shop/mock'
+import type { Discount } from '@fayz-ai/shop/types'
+import { initCustomerAuth, resolveAuthAdapter } from './auth'
+import { StorefrontConfigProvider, resolveConfig, useStorefrontConfig } from './config'
+import type { StorefrontConfig, StorefrontDiscountConfig } from './config'
+import { useHashPath, matchPath } from './router'
+import { StorefrontThemeStyle } from './theme'
+import { StorefrontHeader } from './components/StorefrontHeader'
+import { StorefrontFooter } from './components/StorefrontFooter'
+import { CartDrawer } from './components/CartDrawer'
+import { CatalogPage } from './pages/CatalogPage'
+import { HomePage } from './pages/HomePage'
+import { ProductDetailPage } from './pages/ProductDetailPage'
+import { CheckoutPage } from './pages/CheckoutPage'
+import { OrderConfirmationPage } from './pages/OrderConfirmationPage'
+import { MyPurchasesPage } from './pages/MyPurchasesPage'
+import { NotFoundPage } from './pages/NotFoundPage'
+import { PolicyPage } from './pages/PolicyPage'
+import { StorefrontErrorBoundary } from './components/StorefrontErrorBoundary'
+import { Toaster } from './components/Toaster'
+
+function getCustomRouteMatch(config: ReturnType<typeof useStorefrontConfig>, path: string) {
+  for (const route of config.routes ?? []) {
+    const params = matchPath(route.path, path)
+    if (params) return { route, params }
+  }
+  return null
+}
+
+function isFocusedRoute(config: ReturnType<typeof useStorefrontConfig>, path: string): boolean {
+  const custom = getCustomRouteMatch(config, path)
+  if (custom) return custom.route.chrome === 'focused' || custom.route.kind === 'checkout'
+  return Boolean(matchPath('/checkout', path))
+}
+
+function RouteSwitch({ path }: { path: string }) {
+  const config = useStorefrontConfig()
+
+  const custom = getCustomRouteMatch(config, path)
+  if (custom) {
+    const CustomRoute = custom.route.component
+    return <CustomRoute path={path} params={custom.params} config={config} />
+  }
+
+  const product = matchPath('/product/:slug', path)
+  if (product?.slug) return <ProductDetailPage slug={product.slug} />
+
+  const order = matchPath('/order/:id', path)
+  if (order?.id) return <OrderConfirmationPage orderId={order.id} />
+
+  if (matchPath('/checkout', path)) return <CheckoutPage />
+  if (matchPath('/account', path)) return <MyPurchasesPage />
+  if (matchPath('/catalog', path)) return <CatalogPage />
+  if (matchPath('/privacy', path)) return <PolicyPage kind="privacy" />
+  if (matchPath('/terms', path)) return <PolicyPage kind="terms" />
+  if (matchPath('/refunds', path)) return <PolicyPage kind="returns" />
+
+  // Root renders home (or catalog when there's no home). Any other unmatched
+  // path is a genuine 404 — don't silently fall back to the storefront.
+  if (path === '/' || path === '') {
+    return config.home ? <HomePage sections={config.home.sections} /> : <CatalogPage />
+  }
+  return <NotFoundPage />
+}
+
+/**
+ * Side-effect runtime init shared by the factory and the manifest scaffold:
+ * wires customer auth and the shop provider. Idempotent and safe to call once
+ * before first render. Provider resolution: explicit > catalog mock > empty mock.
+ */
+/**
+ * config.discounts are simple {code, percent} entries the UI validator trusts
+ * (useDiscountValidator). They must ALSO be seeded into the provider, or
+ * placeOrder won't find the code server-side and will charge full price — the
+ * shopper sees a discounted total but is billed the undiscounted one.
+ */
+function storefrontDiscountToSeed(discount: StorefrontDiscountConfig): Discount {
+  const ts = new Date().toISOString()
+  return {
+    id: `cfg-discount-${discount.code.trim().toLowerCase()}`,
+    tenantId: 'mock',
+    title: discount.title ?? `${discount.percent}% off`,
+    code: discount.code.trim().toUpperCase(),
+    type: 'percentage',
+    method: 'code',
+    value: discount.percent,
+    usageLimit: null,
+    oncePerCustomer: false,
+    startsAt: ts,
+    endsAt: null,
+    status: 'active',
+    timesUsed: 0,
+    createdAt: ts,
+    updatedAt: ts,
+  }
+}
+
+function buildMockSeed(config: StorefrontConfig): MockShopSeed | undefined {
+  const configDiscounts = (config.discounts ?? []).map(storefrontDiscountToSeed)
+  if (!config.catalog && configDiscounts.length === 0) return undefined
+  // Config-level codes win over catalog seeds sharing the same code.
+  const catalogDiscounts = (config.catalog?.discounts ?? []).filter(
+    (cd) => !configDiscounts.some((cfg) => (cd.code ?? '').toUpperCase() === cfg.code),
+  )
+  return {
+    ...config.catalog,
+    discounts: [...catalogDiscounts, ...configDiscounts],
+  }
+}
+
+export function initStorefrontRuntime(config: StorefrontConfig): void {
+  initCustomerAuth(resolveAuthAdapter(config.auth?.adapter))
+
+  if (config.provider) {
+    setShopProvider(config.provider)
+  } else {
+    setShopProvider(createMockShopProvider(buildMockSeed(config)))
+  }
+
+  if (config.supabaseUrl || config.supabaseAnonKey) {
+    console.warn(
+      '@fayz-ai/shop: supabaseUrl/supabaseAnonKey are legacy fields. Pass an explicit provider/adapter or use the Fayz SDK broker path.',
+    )
+  }
+}
+
+/** The inner storefront UI. Reads everything from the config context, so it is
+ *  shared by createStorefrontApp and the manifest-driven StorefrontScaffold. */
+export function StorefrontShell() {
+  const config = useStorefrontConfig()
+  const path = useHashPath()
+  const focused = isFocusedRoute(config, path)
+  return (
+    <div className="min-h-screen bg-background text-foreground">
+      {config.theme && <StorefrontThemeStyle theme={config.theme} />}
+      {!focused && <StorefrontHeader />}
+      <StorefrontErrorBoundary key={path}>
+        <RouteSwitch path={path} />
+      </StorefrontErrorBoundary>
+      {!focused && <CartDrawer />}
+      {!focused && <StorefrontFooter />}
+      <Toaster />
+    </div>
+  )
+}
+
+/**
+ * Declarative storefront factory — the customer-facing counterpart of
+ * createSaasApp. Sugar over the manifest path: it is equivalent to
+ * renderApp(defineStorefront(config)), sharing initStorefrontRuntime +
+ * StorefrontShell with the scaffold.
+ *
+ *   const App = createStorefrontApp({ name: 'Aurora Goods', currency: 'BRL' })
+ */
+export function createStorefrontApp(config: StorefrontConfig): React.ComponentType {
+  const resolved = resolveConfig(config)
+  initStorefrontRuntime(config)
+
+  function StorefrontApp() {
+    return (
+      <StorefrontConfigProvider value={resolved}>
+        <StorefrontShell />
+      </StorefrontConfigProvider>
+    )
+  }
+  StorefrontApp.displayName = 'StorefrontApp'
+  return StorefrontApp
+}

package/src/format.ts

@@ -0,0 +1,7 @@
+export function formatMoney(value: number, currency = 'BRL', locale = 'pt-BR'): string {
+  return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(value)
+}
+
+export function roundCents(value: number): number {
+  return Math.round(value * 100) / 100
+}

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+export { useProducts } from './useProducts'
+export { useProduct } from './useProduct'
+export { useCategories } from './useCategories'
+export { useMyOrders } from './useMyOrders'
+export { useDiscountValidator } from './useDiscountValidator'

package/src/hooks/useCategories.ts

@@ -0,0 +1,26 @@
+import { useEffect, useState } from 'react'
+import { getShopProvider } from '@fayz-ai/shop/runtime'
+import type { Category } from '@fayz-ai/shop/types'
+
+export function useCategories(): { categories: Category[]; loading: boolean } {
+  const [categories, setCategories] = useState<Category[]>([])
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    let cancelled = false
+    getShopProvider()
+      .listCategories()
+      .then((data) => {
+        if (!cancelled) setCategories(data)
+      })
+      .catch(() => {})
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  return { categories, loading }
+}

package/src/hooks/useDiscountValidator.ts

@@ -0,0 +1,43 @@
+import { useCallback } from 'react'
+import { validateDiscount } from '@fayz-ai/shop'
+import { useStorefrontConfig } from '../config'
+
+export interface DiscountValidation {
+  valid: boolean
+  percent: number
+  message?: string
+}
+
+const REASON_MESSAGE: Record<string, string> = {
+  expired: 'Cupom expirado.',
+  not_started: 'Cupom ainda não está ativo.',
+  usage_limit: 'Cupom esgotado.',
+  not_found: 'Cupom inválido ou expirado.',
+}
+
+/**
+ * Storefront coupon validator. The store's own config.discounts (simple percent
+ * codes) are trusted directly; everything else goes through the provider-backed
+ * validateDiscount primitive, which enforces status/date-window/usage-limit.
+ * The storefront cart models discounts as a percentage, so non-percentage codes
+ * are rejected for client-side preview (the server still honors them at checkout).
+ */
+export function useDiscountValidator(): (code: string) => Promise<DiscountValidation> {
+  const config = useStorefrontConfig()
+  return useCallback(async (code: string) => {
+    const normalized = code.trim().toUpperCase()
+    if (!normalized) return { valid: false, percent: 0, message: 'Informe um cupom.' }
+
+    const configDiscount = config.discounts?.find((d) => d.code.trim().toUpperCase() === normalized)
+    if (configDiscount) return { valid: true, percent: configDiscount.percent }
+
+    const validation = await validateDiscount({ code: normalized })
+    if (!validation.valid) {
+      return { valid: false, percent: 0, message: REASON_MESSAGE[validation.reason ?? 'not_found'] ?? 'Cupom inválido ou expirado.' }
+    }
+    if (validation.type !== 'percentage') {
+      return { valid: false, percent: 0, message: 'Este cupom não é suportado na loja.' }
+    }
+    return { valid: true, percent: validation.value }
+  }, [config.discounts])
+}