@fayz-ai/storefront 0.7.0 → 0.8.2

package/src/stores/cart.store.ts

@@ -3,6 +3,7 @@ import { persist } from 'zustand/middleware'
 import type { Product } from '@fayz-ai/shop/types'
 import { roundCents } from '../format'
 import type { ResolvedStorefrontConfig } from '../config'
+import { useDeliveryStore, selectQuotedShipping } from './delivery.store'
 import {
   formatProductOptionSelection,
   normalizeProductOptionSelection,
@@ -40,11 +41,16 @@ export interface CartState {
   clear(): void
   openDrawer(): void
   closeDrawer(): void
+  /** Drop persisted lines the active backend can no longer resolve (e.g. a cart
+   *  built in an earlier mock-mode session, whose ids don't exist live). The
+   *  resolver returns false only for a definitive "not found"; on error it must
+   *  return true so a transient failure never discards a legit line. */
+  reconcile(resolve: (line: CartLine) => Promise<boolean>): Promise<void>
 }
 
 export const useCartStore = create<CartState>()(
   persist(
-    (set) => ({
+    (set, get) => ({
       lines: [],
       discountCode: null,
       discountPercent: 0,
@@ -106,6 +112,16 @@ export const useCartStore = create<CartState>()(
       clear: () => set({ lines: [], discountCode: null, discountPercent: 0 }),
       openDrawer: () => set({ isOpen: true }),
       closeDrawer: () => set({ isOpen: false, justAddedLineId: null }),
+
+      reconcile: async (resolve) => {
+        const lines = get().lines
+        if (lines.length === 0) return
+        const keep = await Promise.all(
+          lines.map((line) => resolve(line).catch(() => true)),
+        )
+        const kept = lines.filter((_, i) => keep[i])
+        if (kept.length !== lines.length) set({ lines: kept })
+      },
     }),
     {
       name: 'fayz.storefront.cart.v1',
@@ -132,12 +148,32 @@ export const selectSubtotal = (s: Pick<CartState, 'lines'>): number =>
 export const selectDiscountTotal = (s: Pick<CartState, 'lines' | 'discountPercent'>): number =>
   roundCents(selectSubtotal(s) * (s.discountPercent / 100))
 
+/**
+ * Freight to display.
+ *
+ * When the shopper has given a CEP and the store quoted it, that quote wins —
+ * it came from the same shipping_zones rows shop_place_order will charge from.
+ * Otherwise this falls back to the store-wide rate in config, which is what
+ * every storefront did before zones existed.
+ *
+ * The subtotal is PRE-discount on both sides of this. That is 0017's rule, and
+ * the quote is requested against the same number, so a coupon can never make
+ * the cart and the order disagree.
+ *
+ * Read through getState() rather than a hook because this is a plain selector
+ * called from several screens; components that render the value subscribe to
+ * useDeliveryStore themselves so a fresh quote re-renders them.
+ */
 export const selectShipping = (
   s: Pick<CartState, 'lines'>,
   cfg: ResolvedStorefrontConfig,
 ): number => {
   if (s.lines.length === 0) return 0
   const subtotal = selectSubtotal(s)
+
+  const quoted = selectQuotedShipping(useDeliveryStore.getState(), subtotal)
+  if (quoted != null) return quoted
+
   if (cfg.shipping.freeAbove != null && subtotal >= cfg.shipping.freeAbove) return 0
   return cfg.shipping.flatRate
 }

package/src/stores/delivery.store.ts

@@ -0,0 +1,152 @@
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+import { lookupPostalCode, normalizePostalCode, type PostalAddress } from '@fayz-ai/core'
+import { getShopProvider } from '@fayz-ai/shop/runtime'
+import type { ShippingQuoteOption } from '@fayz-ai/shop/types'
+
+/**
+ * Where the shopper wants it delivered, decided before the cart exists.
+ *
+ * Two different things live here and they are persisted differently on purpose:
+ *
+ *   the ADDRESS is durable — a CEP maps to the same street for years, and
+ *   carrying it to checkout is the whole point (the buyer types the number and
+ *   nothing else);
+ *
+ *   the QUOTE is not persisted at all. It is a price, and a price restored from
+ *   localStorage is a price the shopper can edit with devtools. It is re-asked
+ *   on demand, and resolved for the current cart through resolveOptionRate —
+ *   the same rule shop_shipping_for applies — so it can never go stale. The
+ *   order is charged from shop_place_order, which recomputes from the same
+ *   zones and ignores anything the client sends.
+ */
+
+export type DeliveryStatus = 'idle' | 'loading' | 'served' | 'unserved' | 'error'
+
+export interface DeliveryState {
+  postalCode: string
+  address: PostalAddress | null
+  options: ShippingQuoteOption[]
+  selectedZoneId: string | null
+  status: DeliveryStatus
+  error: string | null
+
+  /** Look the CEP up and quote it. `subtotal` decides free-above thresholds. */
+  resolve: (postalCode: string, subtotal: number) => Promise<void>
+  selectZone: (zoneId: string) => void
+  clear: () => void
+}
+
+const EMPTY = {
+  postalCode: '',
+  address: null,
+  options: [] as ShippingQuoteOption[],
+  selectedZoneId: null,
+  status: 'idle' as DeliveryStatus,
+  error: null,
+}
+
+export const useDeliveryStore = create<DeliveryState>()(
+  persist(
+    (set, get) => ({
+      ...EMPTY,
+
+      async resolve(postalCode: string, subtotal: number) {
+        const code = normalizePostalCode(postalCode)
+        if (code.length !== 8) {
+          set({ ...EMPTY, postalCode, status: 'error', error: 'Digite os 8 dígitos do CEP.' })
+          return
+        }
+
+        set({ postalCode: code, status: 'loading', error: null })
+
+        // The QUOTE comes first and is the answer that matters. Whether we
+        // deliver to a postcode, and for how much, is decided entirely by our
+        // own zones against eight digits — it does not need to know the street.
+        //
+        // Doing it the other way round made the delivery answer depend on a
+        // third party: with ViaCEP slow or rate-limited, a perfectly serviceable
+        // address reported an error instead of a price.
+        let options: ShippingQuoteOption[] = []
+        try {
+          options = (await getShopProvider().quoteShipping?.(code, subtotal)) ?? []
+        } catch {
+          set({ ...EMPTY, postalCode: code, status: 'error',
+                error: 'Não foi possível calcular o frete agora. Tente de novo.' })
+          return
+        }
+
+        // The ADDRESS is the convenience layer: it saves the buyer typing, and
+        // losing it costs typing, not the sale. Failures here never change the
+        // delivery verdict already decided above.
+        let address: PostalAddress | null = null
+        let notFound = false
+        try {
+          address = await lookupPostalCode(code)
+          notFound = address === null
+        } catch {
+          address = null
+        }
+
+        set({
+          postalCode: code,
+          address,
+          options,
+          selectedZoneId: options[0]?.zoneId ?? null,
+          // A store with no zones configured quotes nothing, and that must NOT
+          // read as "we don't deliver here" — it falls back to the store-wide
+          // flat rate, which the cart already knows how to show.
+          status: options.length > 0 ? 'served' : 'unserved',
+          // Reported alongside the price, not instead of it: the CEP may be
+          // mistyped even though its range is covered.
+          error: notFound ? 'CEP não encontrado. Confira os números.' : null,
+        })
+      },
+
+      selectZone(zoneId: string) {
+        if (get().options.some((option) => option.zoneId === zoneId)) set({ selectedZoneId: zoneId })
+      },
+
+      clear() {
+        set({ ...EMPTY })
+      },
+    }),
+    {
+      name: 'fayz.storefront.delivery.v1',
+      // Deliberately NOT persisting `options`: a rehydrated
+      // price would be shown as current without anything having quoted it. The
+      // address survives, the money is asked for again.
+      partialize: (state) => ({ postalCode: state.postalCode, address: state.address }),
+      onRehydrateStorage: () => (state) => {
+        if (state?.address) state.status = 'idle'
+      },
+    },
+  ),
+)
+
+/**
+ * The freight for the chosen zone at THIS subtotal, or null when there is no
+ * zone in play (no CEP yet, or a store that configured none) and the caller
+ * should use the store-wide rate. Null never means free.
+ *
+ * The free-above rule is applied here rather than trusting the `rate` the
+ * server resolved, because that one was resolved for whatever the cart held at
+ * quote time. Re-deriving from `baseRate`/`freeAbove` — the same CASE
+ * shop_shipping_for runs — means adding an item can never leave a stale price
+ * on screen. An earlier version fell back to the config flat rate when the
+ * quote went stale, which showed R$ 8 (the flat rate) for an address in an
+ * R$ 18 zone: shown one number, charged another.
+ */
+export function resolveOptionRate(option: ShippingQuoteOption, subtotal: number): number {
+  if (option.freeAbove != null && subtotal >= option.freeAbove) return 0
+  return option.baseRate
+}
+
+export const selectQuotedShipping = (
+  state: Pick<DeliveryState, 'options' | 'selectedZoneId' | 'status'>,
+  subtotal: number,
+): number | null => {
+  if (state.status !== 'served') return null
+  const option = state.options.find((o) => o.zoneId === state.selectedZoneId) ?? state.options[0]
+  return option ? resolveOptionRate(option, subtotal) : null
+}

package/src/testids.ts

@@ -3,6 +3,7 @@
 export const TID = {
   // header
   headerSearch: 'header-search',
+  headerSearchToggle: 'header-search-toggle',
   cartButton: 'cart-button',
   cartCount: 'cart-count',
   accountLink: 'account-link',
@@ -58,6 +59,9 @@ export const TID = {
   pdpAddToCart: 'pdp-add-to-cart',
   pdpRoot: 'pdp-root',
   pdpGallery: 'pdp-gallery',
+  pdpGalleryImage: 'pdp-gallery-image',
+  pdpGalleryThumbs: 'pdp-gallery-thumbs',
+  pdpGalleryThumb: 'pdp-gallery-thumb',
   pdpActions: 'pdp-actions',
   pdpEnquiryButton: 'pdp-enquiry-button',
   enquiryForm: 'enquiry-form',
@@ -86,6 +90,15 @@ export const TID = {
   cartTotal: 'cart-total',
   goCheckout: 'go-checkout',
   cartEmpty: 'cart-empty',
+  // delivery estimate (product page + cart)
+  deliveryEstimator: 'delivery-estimator',
+  deliveryCepInput: 'delivery-cep-input',
+  deliveryCepSubmit: 'delivery-cep-submit',
+  deliveryOption: 'delivery-option',
+  deliveryUnserved: 'delivery-unserved',
+  deliveryError: 'delivery-error',
+  deliveryAddress: 'delivery-address',
+  deliveryClear: 'delivery-clear',
   // checkout
   checkoutEmail: 'checkout-email',
   checkoutName: 'checkout-name',

package/src/theme.ts

@@ -33,6 +33,10 @@ export interface StorefrontThemeColors {
   /** Announcement bar */
   announcementBackground?: string
   announcementForeground?: string
+  /** Secondary brand accent (e.g. a gourmet gold beside the primary). Emitted
+   *  as `--sf-accent` / `--sf-accent-foreground` and the `accent` tailwind token. */
+  accent?: string
+  accentForeground?: string
 }
 
 export interface StorefrontThemeFont {
@@ -40,7 +44,11 @@ export interface StorefrontThemeFont {
   heading: string
   /** Body font, e.g. 'Rubik' */
   body: string
-  /** Google Fonts families to load (defaults to heading+body) */
+  /** Optional oversized display face for hero words (emitted as `--sf-font-display`). */
+  display?: string
+  /** Optional serif accent for quotes/editorial (emitted as `--sf-font-serif`). */
+  serif?: string
+  /** Google Fonts families to load (defaults to heading+body+display+serif) */
   googleFonts?: string[]
   /** Fallback stack — default sans-serif; use 'serif' for editorial themes */
   fallback?: 'sans-serif' | 'serif'
@@ -58,8 +66,11 @@ export interface StorefrontTheme {
     uppercaseNav?: boolean
     /** Show category shortcuts after primary nav links. Default true. */
     showCategories?: boolean
-    /** Show the storefront search input in the header. Default true. */
+    /** Show the storefront search in the header. Default true. */
     showSearch?: boolean
+    /** Header search presentation: a full input ('full', default) or a compact
+     *  icon button that expands into an input on click ('icon'). */
+    searchStyle?: 'full' | 'icon'
   }
   productCard?: {
     style?: CardStyle
@@ -67,6 +78,11 @@ export interface StorefrontTheme {
   }
   /** Uppercase CTA buttons with letter-spacing (Uyuni/Flex tone) */
   uppercaseButtons?: boolean
+  /** Brand-token passthrough. Each entry is emitted verbatim as a `--<key>` CSS
+   *  custom property, so a store can add gradients, glows, extra colors, or
+   *  letter-spacing the fixed schema doesn't enumerate — without editing the SDK.
+   *  e.g. { 'grad-ember': 'linear-gradient(...)', 'glow-ember': '0 0 0 1px ...' }. */
+  tokens?: Record<string, string>
 }
 
 const RADIUS_MAP: Record<StorefrontRadius, { button: string; card: string; input: string }> = {
@@ -90,6 +106,8 @@ const COLOR_VAR_MAP: Record<keyof StorefrontThemeColors, string> = {
   headerForeground: '--sf-header-fg',
   announcementBackground: '--sf-announcement-bg',
   announcementForeground: '--sf-announcement-fg',
+  accent: '--sf-accent',
+  accentForeground: '--sf-accent-foreground',
 }
 
 export function themeToCss(theme: StorefrontTheme): string {
@@ -111,6 +129,14 @@ export function themeToCss(theme: StorefrontTheme): string {
     const fallback = theme.font.fallback ?? 'sans-serif'
     lines.push(`--font-family: '${theme.font.body}', ${fallback};`)
     lines.push(`--sf-font-heading: '${theme.font.heading}', ${fallback};`)
+    if (theme.font.display) lines.push(`--sf-font-display: '${theme.font.display}', ${fallback};`)
+    if (theme.font.serif) lines.push(`--sf-font-serif: '${theme.font.serif}', serif;`)
+  }
+
+  // Brand-token passthrough — emit each entry as a raw CSS custom property.
+  for (const [key, value] of Object.entries(theme.tokens ?? {})) {
+    const name = key.startsWith('--') ? key : `--${key}`
+    lines.push(`${name}: ${value};`)
   }
 
   const radius = RADIUS_MAP[theme.radius ?? 'soft']
@@ -135,7 +161,11 @@ export function themeToCss(theme: StorefrontTheme): string {
 
 function googleFontsHref(theme: StorefrontTheme): string | null {
   if (!theme.font) return null
-  const families = theme.font.googleFonts ?? [theme.font.heading, theme.font.body]
+  const families =
+    theme.font.googleFonts ??
+    [theme.font.heading, theme.font.body, theme.font.display, theme.font.serif].filter(
+      (f): f is string => Boolean(f),
+    )
   const unique = [...new Set(families)]
   const params = unique
     .map((f) => `family=${encodeURIComponent(f).replace(/%20/g, '+')}:wght@300;400;500;600;700`)

package/src/workflows/checkout.ts

@@ -1,5 +1,5 @@
 import { getShopProvider } from '@fayz-ai/shop/runtime'
-import type { Order } from '@fayz-ai/shop/types'
+import type { Order, ShippingAddressInput, PaymentMethodKind } from '@fayz-ai/shop/types'
 import { establishCustomerSession } from '../auth'
 import type { ResolvedStorefrontConfig } from '../config'
 import type { CartState } from '../stores/cart.store'
@@ -24,6 +24,9 @@ export interface PlaceStorefrontOrderInput {
   session?: Pick<SessionState, 'customerId' | 'email'>
   customer: StorefrontCheckoutCustomer
   address?: StorefrontCheckoutAddress
+  /** Structured address; without it the order keeps only the free-text note. */
+  shippingAddress?: ShippingAddressInput
+  paymentMethod?: PaymentMethodKind
   markPaid?: boolean
 }
 
@@ -32,10 +35,25 @@ export interface PlaceStorefrontOrderResult {
   customerId: string
 }
 
-function formatDeliveryNotes(address: StorefrontCheckoutAddress | undefined): string | undefined {
-  if (!address) return undefined
-  if (address.notes?.trim()) return address.notes.trim()
+/**
+ * `notes` is the buyer's free-text message to the store — nothing else.
+ *
+ * It used to double as the delivery address, from back when the order had
+ * nowhere structured to put one. Now that the address is a real snapshot plus a
+ * row in the address book, repeating it here only creates a second copy that
+ * can disagree with the first (it did: it dropped number and district). When a
+ * structured address is present, notes carries only what the customer wrote.
+ */
+function formatDeliveryNotes(
+  address: StorefrontCheckoutAddress | undefined,
+  shippingAddress?: ShippingAddressInput,
+): string | undefined {
+  if (address?.notes?.trim()) return address.notes.trim()
 
+  // Structured address present → the order already knows where to deliver.
+  if (shippingAddress) return undefined
+
+  if (!address) return undefined
   const parts = [address.street, address.city, address.zip]
     .map((part) => part?.trim())
     .filter(Boolean)
@@ -54,6 +72,8 @@ export async function placeStorefrontOrder({
   session,
   customer,
   address,
+  shippingAddress,
+  paymentMethod,
   markPaid = false,
 }: PlaceStorefrontOrderInput): Promise<PlaceStorefrontOrderResult> {
   const email = customer.email.trim().toLowerCase()
@@ -73,9 +93,14 @@ export async function placeStorefrontOrder({
     customerId: customerId ?? undefined,
     customer: { name, email },
     currency: config.currency,
-    notes: formatDeliveryNotes(address),
+    notes: formatDeliveryNotes(address, shippingAddress),
     discountCode: cart.discountCode ?? undefined,
     shippingTotal: selectShipping(cart, config),
+    // Structured address + method are what populate public.addresses and the
+    // transactions ledger. `notes` stays for backwards compatibility with
+    // checkouts that have not been updated yet.
+    shippingAddress,
+    paymentMethod,
     items: cart.lines.map((line) => ({
       productId: line.productId,
       quantity: line.quantity,
@@ -84,7 +109,10 @@ export async function placeStorefrontOrder({
   })
 
   if (markPaid) {
-    await provider.updateOrder(order.id, { financialStatus: 'paid' })
+    // Prefer the RPC seam — anon storefronts have no UPDATE grant on the
+    // orders table, so a direct updateOrder 401s on pool backends.
+    if (provider.confirmPayment) await provider.confirmPayment(order.id)
+    else await provider.updateOrder(order.id, { financialStatus: 'paid' })
   }
 
   return { order, customerId: customerId ?? order.customerId ?? '' }