@ecomiq/storefront 1.1.5 → 2.0.0

package/src/providers/cart.tsx

@@ -0,0 +1,275 @@
+/**
+ * Estado de carrito storefront: sesión en localStorage + mutaciones vía serverApi.
+ *
+ * ```tsx
+ * <CartProvider storeId={settings.store.id} currencyCode={settings.store.currency}>
+ *   <App />
+ * </CartProvider>
+ *
+ * const { cart, addItem } = useCart()
+ * ```
+ */
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react'
+import { type StorefrontCart } from '@ecomiq/core'
+import { z } from 'zod'
+import { serverApi } from '../server'
+
+const CartSessionSchema = z.object({
+  version: z.literal(1),
+  storeId: z.string().min(1),
+  cartId: z.string().uuid(),
+})
+
+export type CartLoadStatus = 'loading' | 'ready' | 'error'
+
+export type CartMutation = {
+  kind: 'adding' | 'updating' | 'removing'
+  itemId?: string
+}
+
+export interface CartContextValue {
+  cart: StorefrontCart | null
+  cartId: string | undefined
+  itemCount: number
+  loadStatus: CartLoadStatus
+  mutation: CartMutation | null
+  error: string | undefined
+  addItem: (input: { variantId: string; quantity: number }) => Promise<StorefrontCart>
+  setItemQuantity: (itemId: string, quantity: number) => Promise<void>
+  removeItem: (itemId: string) => Promise<void>
+  reload: () => Promise<void>
+  clearCart: () => void
+}
+
+const CartContext = createContext<CartContextValue | null>(null)
+
+function sessionKey(storeId: string) {
+  return `ecomiq:cart:v1:${storeId}`
+}
+
+function readCartSession(key: string) {
+  if (typeof localStorage === 'undefined') return undefined
+  const raw = localStorage.getItem(key)
+  if (!raw) return undefined
+  try {
+    const result = CartSessionSchema.safeParse(JSON.parse(raw))
+    return result.success ? result.data : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function CartProvider({
+  storeId,
+  currencyCode,
+  children,
+}: {
+  storeId: string
+  currencyCode: string
+  children: ReactNode
+}) {
+  const key = sessionKey(storeId)
+  const [cart, setCart] = useState<StorefrontCart | null>(null)
+  const [cartId, setCartId] = useState<string>()
+  const [loadStatus, setLoadStatus] = useState<CartLoadStatus>('loading')
+  const [mutation, setMutation] = useState<CartMutation | null>(null)
+  const [error, setError] = useState<string>()
+  const mutationInFlight = useRef(false)
+
+  const persist = (nextCartId: string) => {
+    setCartId(nextCartId)
+    localStorage.setItem(key, JSON.stringify({ version: 1, storeId, cartId: nextCartId }))
+  }
+
+  const clear = () => {
+    setCart(null)
+    setCartId(undefined)
+    localStorage.removeItem(key)
+  }
+
+  const reload = async () => {
+    setLoadStatus('loading')
+    setError(undefined)
+    const stored = readCartSession(key)
+    if (!stored || stored.storeId !== storeId) {
+      clear()
+      setLoadStatus('ready')
+      return
+    }
+
+    setCartId(stored.cartId)
+    try {
+      const result = await serverApi.loadCart({ cartId: stored.cartId })
+      if (!result.ok) {
+        setError(result.error.message)
+        setLoadStatus('error')
+        return
+      }
+      if (!result.value) {
+        clear()
+      } else {
+        setCart(result.value)
+      }
+      setLoadStatus('ready')
+    } catch {
+      setError('No pudimos cargar el carrito. Inténtalo nuevamente.')
+      setLoadStatus('error')
+    }
+  }
+
+  useEffect(() => {
+    void reload()
+    const sync = (event: StorageEvent) => {
+      if (event.key === key) void reload()
+    }
+    window.addEventListener('storage', sync)
+    return () => window.removeEventListener('storage', sync)
+  }, [key])
+
+  const addItem = async (input: { variantId: string; quantity: number }) => {
+    if (mutationInFlight.current) {
+      const message = 'El carrito se está actualizando. Inténtalo nuevamente.'
+      setError(message)
+      throw new Error(message)
+    }
+
+    mutationInFlight.current = true
+    setMutation({ kind: 'adding' })
+    setError(undefined)
+    try {
+      let result
+      try {
+        result = await serverApi.addProductToCart({
+          cartId,
+          currencyCode,
+          variantId: input.variantId,
+          quantity: input.quantity,
+        })
+      } catch {
+        const message = 'No pudimos actualizar el carrito. Inténtalo nuevamente.'
+        setError(message)
+        throw new Error(message)
+      }
+
+      if (!result.ok) {
+        setError(result.error.message)
+        throw new Error(result.error.message)
+      }
+
+      setError(undefined)
+      persist(result.value.cartId)
+      setCart(result.value.cart)
+      return result.value.cart
+    } finally {
+      mutationInFlight.current = false
+      setMutation(null)
+    }
+  }
+
+  const setItemQuantity = async (itemId: string, quantity: number) => {
+    if (!cartId) {
+      setError('No hay un carrito activo.')
+      return
+    }
+    if (mutationInFlight.current) {
+      setError('El carrito se está actualizando. Inténtalo nuevamente.')
+      return
+    }
+
+    mutationInFlight.current = true
+    setMutation({ kind: 'updating', itemId })
+    setError(undefined)
+    try {
+      let result
+      try {
+        result = await serverApi.setCartItemQuantity({
+          cartId,
+          cartItemId: itemId,
+          quantity,
+        })
+      } catch {
+        setError('No pudimos actualizar el carrito. Inténtalo nuevamente.')
+        return
+      }
+
+      if (!result.ok) {
+        if (result.error.kind === 'cart-unavailable') clear()
+        setError(result.error.message)
+        return
+      }
+
+      setCart(result.value)
+    } finally {
+      mutationInFlight.current = false
+      setMutation(null)
+    }
+  }
+
+  const removeItem = async (itemId: string) => {
+    if (!cartId) {
+      setError('No hay un carrito activo.')
+      return
+    }
+    if (mutationInFlight.current) {
+      setError('El carrito se está actualizando. Inténtalo nuevamente.')
+      return
+    }
+
+    mutationInFlight.current = true
+    setMutation({ kind: 'removing', itemId })
+    setError(undefined)
+    try {
+      let result
+      try {
+        result = await serverApi.removeCartItem({
+          cartId,
+          cartItemId: itemId,
+        })
+      } catch {
+        setError('No pudimos actualizar el carrito. Inténtalo nuevamente.')
+        return
+      }
+
+      if (!result.ok) {
+        if (result.error.kind === 'cart-unavailable') clear()
+        setError(result.error.message)
+        return
+      }
+
+      setCart(result.value)
+    } finally {
+      mutationInFlight.current = false
+      setMutation(null)
+    }
+  }
+
+  const value: CartContextValue = {
+    cart,
+    cartId,
+    itemCount: cart?.items.reduce((sum, item) => sum + item.quantity, 0) ?? 0,
+    loadStatus,
+    mutation,
+    error,
+    addItem,
+    setItemQuantity,
+    removeItem,
+    reload,
+    clearCart: clear,
+  }
+
+  return <CartContext.Provider value={value}>{children}</CartContext.Provider>
+}
+
+/** Acceso al carrito. Requiere `<CartProvider>` en el layout. */
+export function useCart() {
+  const value = useContext(CartContext)
+  if (!value) throw new Error('useCart debe usarse dentro de CartProvider')
+  return value
+}

package/src/providers/ecomiq.ts

@@ -0,0 +1,137 @@
+/**
+ * Provider + hooks públicos de Ecomiq (settings, config, queries).
+ */
+import {
+  createContext,
+  createElement,
+  useContext,
+  type ReactNode,
+} from 'react'
+import { hashKey, keepPreviousData, useQuery } from '@tanstack/react-query'
+import { useNavigate } from '@tanstack/react-router'
+import {
+  getMenuItems,
+  type StorefrontMenuItem,
+  type StorefrontSettings,
+} from '@ecomiq/core'
+import type { PublicEcomiqConfig } from '../public-config'
+
+export interface ApiQueryOptions<T> {
+  /** Datos iniciales (ej. los del loader SSR) para render inmediato. */
+  initialData?: T
+  /** Tiempo en ms que los datos se consideran frescos. Default 30s. */
+  freshForMs?: number
+  /** Habilita/deshabilita la consulta. */
+  enabled?: boolean
+  /** Reintentos ante error. Default 1. */
+  retry?: number
+  keepPreviousData?: boolean
+  seed?: { key: readonly unknown[]; data: T }
+}
+
+export interface ApiQueryResult<T> {
+  data: T | undefined
+  isLoading: boolean
+  isRefreshing: boolean
+  error: Error | null
+  refresh: () => void
+}
+
+/**
+ * Consulta datos en el cliente con caché y deduplicación automáticas.
+ *
+ * ```ts
+ * const { data, isLoading } = useApiQuery(['products'], () => api.get('/products', schema))
+ * ```
+ */
+export function useApiQuery<T>(
+  key: readonly unknown[],
+  fetcher: (context: { signal: AbortSignal }) => Promise<T>,
+  options: ApiQueryOptions<T> = {},
+): ApiQueryResult<T> {
+  let initialData = options.initialData
+  if (options.seed && hashKey(options.seed.key) === hashKey(key)) {
+    initialData = options.seed.data
+  }
+  const query = useQuery({
+    queryKey: key,
+    queryFn: ({ signal }) => fetcher({ signal }),
+    initialData,
+    placeholderData: options.keepPreviousData ? keepPreviousData : undefined,
+    staleTime: options.freshForMs ?? 30_000,
+    enabled: options.enabled,
+    retry: options.retry ?? 1,
+  })
+  return {
+    data: query.data,
+    isLoading: query.isPending,
+    isRefreshing: query.isFetching && !query.isPending,
+    error: query.error,
+    refresh: () => void query.refetch(),
+  }
+}
+
+/** Valor único del shell: config local + settings storefront. */
+export interface AppEcomiqValue {
+  config: PublicEcomiqConfig
+  settings: StorefrontSettings
+}
+
+/** Contexto único de la app Ecomiq (lo provee el root generado). */
+export const AppEcomiqContext = createContext<AppEcomiqValue | null>(null)
+
+/**
+ * Provider del shell storefront (config + settings).
+ *
+ * ```tsx
+ * <AppEcomiqProvider config={publicConfig} settings={settings}>
+ *   <App />
+ * </AppEcomiqProvider>
+ * ```
+ */
+export function AppEcomiqProvider({
+  config,
+  settings,
+  children,
+}: AppEcomiqValue & { children: ReactNode }) {
+  return createElement(
+    AppEcomiqContext.Provider,
+    { value: { config, settings } },
+    children,
+  )
+}
+
+function useAppEcomiq(): AppEcomiqValue {
+  const value = useContext(AppEcomiqContext)
+  if (!value) {
+    throw new Error('Hooks de Ecomiq deben usarse dentro de AppEcomiqProvider')
+  }
+  return value
+}
+
+/** Acceso al ecomiq.config.js resuelto. */
+export function useAppConfig(): PublicEcomiqConfig {
+  return useAppEcomiq().config
+}
+
+/** Acceso a /v1/settings (CMS, store, menus). */
+export function useSettings(): StorefrontSettings {
+  return useAppEcomiq().settings
+}
+
+/** Items de un menú CMS (`main`, `footer`, `account`, …). */
+export function useMenu(key: string): StorefrontMenuItem[] {
+  return getMenuItems(useSettings(), key)
+}
+
+/**
+ * Navegación cliente a una ruta con query params (sin full page reload).
+ *
+ * ```ts
+ * const go = useSearchNavigate()
+ * go('/products', { sort: 'price_asc', page: 1 })
+ * ```
+ */
+export function useSearchNavigate() {
+  return useNavigate()
+}

package/src/providers/index.ts

@@ -0,0 +1,26 @@
+export {
+  AppEcomiqContext,
+  AppEcomiqProvider,
+  useApiQuery,
+  useAppConfig,
+  useSettings,
+  useMenu,
+  useSearchNavigate,
+  type AppEcomiqValue,
+  type ApiQueryOptions,
+  type ApiQueryResult,
+} from './ecomiq'
+export {
+  CartProvider,
+  useCart,
+  type CartContextValue,
+  type CartLoadStatus,
+  type CartMutation,
+} from './cart'
+export {
+  AuthProvider,
+  createStorefrontAuthClient,
+  useAuth,
+  type StorefrontAuthClientInstance,
+  type StorefrontSession,
+} from './auth'

package/src/public-config.ts

@@ -0,0 +1,44 @@
+export interface EcomiqThemeConfig {
+  primary?: string
+  primaryForeground?: string
+  background?: string
+  foreground?: string
+  accent?: string
+  radius?: string
+}
+
+export interface EcomiqSeoConfig {
+  titleTemplate?: string
+  keywords?: string[]
+  favicon?: string
+  ogImage?: string
+  twitterCard?: 'summary' | 'summary_large_image'
+  meta?: Array<{ name?: string; property?: string; content: string }>
+  links?: Array<Record<string, string>>
+}
+
+export interface EcomiqAnalyticsConfig {
+  googleAnalytics?: string
+  metaPixel?: string
+  plausible?: string
+  scripts?: Array<{ src?: string; inline?: string; defer?: boolean; async?: boolean }>
+}
+
+export interface EcomiqLayoutConfig {
+  nav?: Array<{ label: string; to: string }>
+  footerText?: string
+  stickyHeader?: boolean
+}
+
+export interface PublicEcomiqConfig {
+  name: string
+  /** Identidad de tienda para x-Store-Domain (ej. 'marketplace'). */
+  slug: string
+  description?: string
+  theme?: EcomiqThemeConfig
+  seo?: EcomiqSeoConfig
+  analytics?: EcomiqAnalyticsConfig
+  layout?: EcomiqLayoutConfig
+}
+
+export type EcomiqConfig = PublicEcomiqConfig

package/src/review-submission.ts

@@ -0,0 +1,89 @@
+import type {
+  CreateProductReviewParams,
+  StorefrontReview,
+} from '@ecomiq/core'
+import { ApiError } from '@ecomiq/core'
+import { z } from 'zod'
+
+const ReviewProblemSchema = z.object({
+  code: z.string().max(120).regex(/^[A-Za-z0-9._-]+$/).optional(),
+})
+
+interface ProductReviewClient {
+  createProductReview(
+    params: CreateProductReviewParams,
+  ): Promise<StorefrontReview>
+}
+
+export interface ProductReviewSubmissionError {
+  status: 400 | 409 | 429 | 500
+  code?: string
+  message: string
+}
+
+export type ProductReviewSubmissionResult =
+  | {
+      ok: true
+      review: StorefrontReview
+    }
+  | {
+      ok: false
+      error: ProductReviewSubmissionError
+    }
+
+export async function submitProductReview(
+  client: ProductReviewClient,
+  input: CreateProductReviewParams,
+): Promise<ProductReviewSubmissionResult> {
+  try {
+    const review = await client.createProductReview(input)
+    return { ok: true, review }
+  } catch (error) {
+    if (!(error instanceof ApiError)) throw error
+
+    let code: string | undefined
+    const problem = ReviewProblemSchema.safeParse(error.body)
+    if (problem.success) code = problem.data.code
+
+    if (error.status === 400) {
+      let message = 'Revisa los datos de la reseña e inténtalo nuevamente.'
+      if (
+        code === 'ProductReview.OrderInvalid' ||
+        code === 'ProductReview.OrderOwnerMismatch' ||
+        code === 'ProductReview.ProductNotPurchased'
+      ) {
+        message = 'No pudimos verificar la compra con los datos ingresados.'
+      }
+      return { ok: false, error: { status: 400, code, message } }
+    }
+
+    if (error.status === 409) {
+      let message = 'No pudimos registrar esta reseña porque ya existe una similar.'
+      if (code === 'ProductReview.AlreadyExists') {
+        message = 'Ya enviaste una reseña para este producto.'
+      }
+      return { ok: false, error: { status: 409, code, message } }
+    }
+
+    if (error.status === 429) {
+      return {
+        ok: false,
+        error: {
+          status: 429,
+          code,
+          message:
+            'Enviaste varias reseñas en poco tiempo. Espera un momento e inténtalo nuevamente.',
+        },
+      }
+    }
+
+    return {
+      ok: false,
+      error: {
+        status: 500,
+        code,
+        message: 'No pudimos enviar la reseña. Inténtalo nuevamente.',
+      },
+    }
+  }
+}

package/src/runtime/context.ts

@@ -0,0 +1 @@
+export { AppEcomiqContext, AppEcomiqProvider, type AppEcomiqValue } from '../providers/ecomiq'

package/src/runtime/default-layout.tsx

@@ -0,0 +1,80 @@
+/**
+ * Layout por defecto de Ecomiq.
+ * Nav y footer salen de settings.cms.menus (main / footer).
+ * Fallback: bloque `layout` de ecomiq.config.js.
+ */
+import { Link } from '@tanstack/react-router'
+import { getMenuItems } from '@ecomiq/core'
+import type { LayoutProps } from '../index'
+
+export default function DefaultLayout({ children, config, settings }: LayoutProps) {
+  const layout = (config.layout ?? {}) as {
+    nav?: Array<{ label: string; to: string }>
+    footerText?: string
+    stickyHeader?: boolean
+  }
+
+  const mainItems = getMenuItems(settings, 'main')
+  const footerItems = getMenuItems(settings, 'footer')
+  const nav =
+    mainItems.length > 0
+      ? mainItems.map((item) => ({ label: item.label, to: item.url, target: item.target }))
+      : (layout.nav ?? [{ label: 'Productos', to: '/' }]).map((item) => ({
+          ...item,
+          target: null as string | null | undefined,
+        }))
+
+  const sticky = layout.stickyHeader !== false
+  const storeName = settings?.store.name ?? config.name
+
+  return (
+    <div className="flex min-h-dvh flex-col">
+      <header
+        className={
+          'border-b bg-background/90 backdrop-blur supports-[backdrop-filter]:bg-background/75 z-40' +
+          (sticky ? ' sticky top-0' : '')
+        }
+      >
+        <div className="mx-auto flex h-14 w-full max-w-6xl items-center justify-between px-4">
+          <Link to="/" className="font-semibold tracking-tight text-lg">
+            {storeName}
+          </Link>
+          <nav className="flex items-center gap-5 text-sm text-muted-foreground">
+            {nav.map((item) =>
+              item.target === '_blank' ? (
+                <a
+                  key={item.to}
+                  href={item.to}
+                  target="_blank"
+                  rel="noreferrer"
+                  className="transition-colors hover:text-foreground"
+                >
+                  {item.label}
+                </a>
+              ) : (
+                <Link key={item.to} to={item.to} className="transition-colors hover:text-foreground">
+                  {item.label}
+                </Link>
+              ),
+            )}
+          </nav>
+        </div>
+      </header>
+      <main className="mx-auto w-full max-w-6xl flex-1 px-4 py-8">{children}</main>
+      <footer className="border-t">
+        <div className="mx-auto flex w-full max-w-6xl flex-col gap-4 px-4 py-6 text-sm text-muted-foreground sm:flex-row sm:items-center sm:justify-between">
+          <p>{layout.footerText ?? `${storeName} — creado con Ecomiq`}</p>
+          {footerItems.length > 0 && (
+            <nav className="flex flex-wrap gap-4">
+              {footerItems.map((item) => (
+                <Link key={item.url} to={item.url} className="transition-colors hover:text-foreground">
+                  {item.label}
+                </Link>
+              ))}
+            </nav>
+          )}
+        </div>
+      </footer>
+    </div>
+  )
+}