@ecomiq/storefront 1.1.5 → 2.0.0

package/src/index.ts

@@ -0,0 +1,274 @@
+/**
+ * API pública de @ecomiq/storefront.
+ * Todo lo que el usuario importa sale de aquí o de '@ecomiq/storefront/ui'.
+ * Las herramientas internas (router, bundler, SSR) no se exponen.
+ */
+import type { ReactNode } from 'react'
+import type { StorefrontSettings } from '@ecomiq/core'
+import type { PublicEcomiqConfig } from './public-config'
+
+export type {
+  EcomiqAnalyticsConfig,
+  EcomiqConfig,
+  EcomiqLayoutConfig,
+  EcomiqSeoConfig,
+  EcomiqThemeConfig,
+  PublicEcomiqConfig,
+} from './public-config'
+
+export {
+  createApi,
+  createStorefrontClient,
+  ApiError,
+  DEFAULT_API_BASE_URL,
+  DEFAULT_API_VERSION,
+} from '@ecomiq/core'
+export type { Api, CreateApiOptions, StorefrontClient } from '@ecomiq/core'
+export type { CreateApiOptions as CreateClientOptions } from '@ecomiq/core'
+export {
+  CollectionSchema,
+  CollectionsSchema,
+  CountrySchema,
+  CountriesSchema,
+  DepartmentSchema,
+  DepartmentsSchema,
+  DistrictSchema,
+  DistrictsSchema,
+  GeoDivisionSchema,
+  GeoDivisionTypeSchema,
+  GetDepartmentsParamsSchema,
+  GetDistrictsParamsSchema,
+  GetProvincesParamsSchema,
+  ProvinceSchema,
+  ProvincesSchema,
+  StorefrontSettingsSchema,
+  StorefrontMenuSchema,
+  StorefrontMenuItemSchema,
+  getMenuItems,
+} from '@ecomiq/core'
+export { getCountries, getDepartments, getDistricts, getProvinces } from '@ecomiq/core'
+export {
+  AddCartItemParamsSchema,
+  CreateCartParamsSchema,
+  CreateProductReviewParamsSchema,
+  GetCartParamsSchema,
+  ListProductReviewsParamsSchema,
+  ProductDetailParamsSchema,
+  ProductDetailSchema,
+  ProductAutocompleteParamsSchema,
+  ProductSuggestionSchema,
+  ProductSuggestionsSchema,
+  ProductSummarySchema,
+  ProductsParamsSchema,
+  ProductsResponseSchema,
+  RelatedProductsParamsSchema,
+  RemoveCartItemParamsSchema,
+  StorefrontCartSchema,
+  StorefrontReviewSchema,
+  StorefrontReviewsSchema,
+  CartCheckoutReadParamsSchema,
+  CartCheckoutParamsSchema,
+  GetShippingOptionsParamsSchema,
+  PutShippingMethodParamsSchema,
+  CartBuyerParamsSchema,
+  CartAddressesParamsSchema,
+  CartPromotionCodeParamsSchema,
+  UpdateCartItemQuantityParamsSchema,
+  cartVariantIdFromProduct,
+  sanitizeHtml,
+  stripHtml,
+} from '@ecomiq/core'
+export type {
+  Collection,
+  Collections,
+  Countries,
+  Country,
+  Department,
+  Departments,
+  District,
+  Districts,
+  GeoDivision,
+  GeoDivisionType,
+  GetDepartmentsParams,
+  GetDistrictsParams,
+  GetProvincesParams,
+  Province,
+  Provinces,
+  StorefrontSettings,
+  StorefrontMenu,
+  StorefrontMenuItem,
+  AddCartItemParams,
+  BundleItem,
+  CreateCartParams,
+  CreateProductReviewParams,
+  GetCartParams,
+  ListProductReviewsParams,
+  ProductDetail,
+  ProductDetailParams,
+  Product,
+  ProductAutocompleteParams,
+  ProductImage,
+  ProductPriceTier,
+  ProductSuggestion,
+  ProductSummary,
+  ProductsParams,
+  ProductsParamsInput,
+  ProductsResponse,
+  RelatedProductsParams,
+  RemoveCartItemParams,
+  SearchFilter,
+  SizeGuide,
+  SpecItem,
+  StorefrontCart,
+  StorefrontCartItem,
+  CartCheckoutReadParams,
+  CartCheckoutParams,
+  CartCheckoutResponse,
+  CartPaymentMethod,
+  GetShippingOptionsParams,
+  PutShippingMethodParams,
+  CartBuyerParams,
+  CartAddressesParams,
+  CartPromotionCodeParams,
+  ShippingRate,
+  ShippingOptionGroup,
+  ShippingOptionsResponse,
+  StorefrontOrderBump,
+  StorefrontReview,
+  StorefrontReviews,
+  UpdateCartItemQuantityParams,
+  VariantItem,
+} from '@ecomiq/core'
+export { createClient, getStorefrontClient } from './client'
+export type {
+  AddProductToCartInput,
+  AddProductToCartResult,
+  ProductCartMutationResult,
+} from './cart-session'
+export type {
+  ProductReviewSubmissionError,
+  ProductReviewSubmissionResult,
+} from './review-submission'
+export { serverApi } from './server'
+export { proxyStorefrontRequest } from './api-proxy'
+export {
+  AppEcomiqProvider,
+  useApiQuery,
+  useAppConfig,
+  useSettings,
+  useMenu,
+  useSearchNavigate,
+  CartProvider,
+  useCart,
+  AuthProvider,
+  createStorefrontAuthClient,
+  useAuth,
+  type CartContextValue,
+  type CartLoadStatus,
+  type CartMutation,
+  type StorefrontAuthClientInstance,
+  type StorefrontSession,
+} from './providers'
+export { createStorefrontAuth } from './auth/create-storefront-auth'
+export { ecomiqOAuthPassword } from './auth/ecomiq-oauth-password-plugin'
+export { ecomiqOAuthPasswordClient } from './auth/ecomiq-oauth-password-client'
+export { signInWithEcomiqCredentials } from './auth/ecomiq-storefront-sign-in'
+export type { EcomiqSignInCredentials } from './auth/ecomiq-storefront-sign-in'
+export * from './utils'
+export { Link } from './link'
+export { Await } from '@tanstack/react-router'
+export { Hero, findHeroSection, type HeroProps, type HeroSlide } from './components/hero'
+export { z } from 'zod'
+
+/**
+ * Contexto del loader. Por defecto el loader es isomorfo (SSR + cliente).
+ * Preferí `serverApi` para que el fetch a storefront solo corra en el servidor.
+ */
+export interface LoaderContext<
+  TParams = Record<string, string>,
+  TSearch extends Record<string, unknown> = Record<string, unknown>,
+> {
+  params: TParams
+  search: TSearch
+  config: PublicEcomiqConfig
+}
+
+/** Props que recibe el componente de una página. */
+export interface PageProps<
+  TData = unknown,
+  TParams = Record<string, string>,
+  TSearch extends Record<string, unknown> = Record<string, unknown>,
+> {
+  data: TData
+  params: TParams
+  search: TSearch
+}
+
+export interface PageMeta {
+  title?: string
+  description?: string
+  /** Imagen OG específica de esta página (sobreescribe seo.ogImage). */
+  ogImage?: string
+  /** Marca la página como noindex,nofollow. */
+  noIndex?: boolean
+  /** Metas extra solo para esta página. */
+  meta?: Array<{ name?: string; property?: string; content: string }>
+  /** Datos estructurados (schema.org); se serializa como JSON-LD. */
+  jsonLd?: Record<string, unknown>
+}
+
+/** Props que recibe un layout personalizado (layout.tsx en la raíz del proyecto). */
+export interface LayoutProps {
+  children: ReactNode
+  config: PublicEcomiqConfig
+  /** Settings storefront (CMS, store, menus). Cargado en el root para todas las páginas. */
+  settings: StorefrontSettings
+}
+
+/**
+ * Define el layout global de la tienda (opcional).
+ * Crea `layout.tsx` en la raíz del proyecto y el framework lo usa en lugar
+ * del layout por defecto. Recibe `children` (la página) y `config`.
+ */
+export function defineLayout(layout: (props: LayoutProps) => ReactNode) {
+  return layout
+}
+
+export interface EcomiqPage<
+  TData = unknown,
+  TParams = Record<string, string>,
+  TSearch extends Record<string, unknown> = Record<string, unknown>,
+> {
+  preload?: boolean
+  reloadOnSearch?: boolean
+  validateSearch?: (raw: Record<string, unknown>) => TSearch
+  /**
+   * Carga de datos. Corre en SSR y en navegaciones cliente.
+   * Usa `serverApi` (no `createClient`) para que el HTTP a storefront
+   * solo ocurra en el servidor.
+   */
+  loader?: (ctx: LoaderContext<TParams, TSearch>) => Promise<TData> | TData
+  /** Metadatos del documento; recibe los datos ya cargados. */
+  meta?: (ctx: {
+    data: TData
+    params: TParams
+    search: TSearch
+    config: PublicEcomiqConfig
+  }) => PageMeta
+  /** UI de la página. */
+  component: (props: PageProps<TData, TParams, TSearch>) => ReactNode
+  /** UI mientras el loader está en curso (navegación cliente). */
+  loading?: () => ReactNode
+  /** UI cuando el loader falla. */
+  error?: (props: { error: Error; reset: () => void }) => ReactNode
+}
+
+export function definePage<
+  TData = unknown,
+  TParams = Record<string, string>,
+  TSearch extends Record<string, unknown> = Record<string, unknown>,
+>(
+  page: EcomiqPage<TData, TParams, TSearch>,
+): EcomiqPage<TData, TParams, TSearch> {
+  return page
+}

package/src/link.tsx

@@ -0,0 +1,2 @@
+export { Link } from '@tanstack/react-router'
+export type { LinkProps } from '@tanstack/react-router'

package/src/pages/checkout.$checkoutId.tsx

@@ -0,0 +1,60 @@
+/**
+ * Checkout cerrado de Ecomiq (`/checkout/$checkoutId`).
+ * Los templates heredan la ruta vía codegen; no se puede overridear desde `pages/`.
+ * `/checkout` sin ID redirige a `/cart` (ver `checkout.tsx`).
+ */
+import { useEffect } from 'react'
+import { CheckoutSessionView } from '../components/checkout'
+import { definePage } from '../index'
+import { useAuth, useSearchNavigate, useSettings } from '../providers'
+
+export default definePage<undefined, { checkoutId: string }>({
+  meta: () => ({
+    title: 'Checkout',
+    description: 'Confirma tu pedido y completa la compra',
+    noIndex: true,
+  }),
+  component: CheckoutPage,
+})
+
+function CheckoutPage({ params }: { params: { checkoutId: string } }) {
+  const checkoutId = params.checkoutId?.trim() ?? ''
+  const { store } = useSettings()
+  const allowGuest = store.checkoutSettings.general.allowGuestCheckout
+  const { session, isPending: authPending } = useAuth()
+  const navigate = useSearchNavigate()
+  const isAuthenticated = Boolean(session?.user)
+  const needsAuth = !allowGuest && !authPending && !isAuthenticated && Boolean(checkoutId)
+
+  useEffect(() => {
+    if (checkoutId) return
+    void navigate({ to: '/cart', replace: true })
+  }, [checkoutId, navigate])
+
+  useEffect(() => {
+    if (!needsAuth || !checkoutId) return
+    void navigate({
+      to: '/account/login',
+      search: { redirect: `/checkout/${checkoutId}` },
+      replace: true,
+    })
+  }, [needsAuth, navigate, checkoutId])
+
+  if (!checkoutId) {
+    return (
+      <div className="mx-auto w-full max-w-6xl px-4 py-16 text-center text-sm text-muted-foreground">
+        Redirigiendo al carrito…
+      </div>
+    )
+  }
+
+  if (authPending || needsAuth) {
+    return (
+      <div className="mx-auto w-full max-w-6xl px-4 py-16 text-center text-sm text-muted-foreground">
+        {needsAuth ? 'Redirigiendo para iniciar sesión…' : 'Cargando…'}
+      </div>
+    )
+  }
+
+  return <CheckoutSessionView cartId={checkoutId} />
+}

package/src/pages/checkout.tsx

@@ -0,0 +1,31 @@
+/**
+ * Checkout cerrado de Ecomiq (`/checkout` / `/checkout/`).
+ * Sin ID → redirige al carrito. El flujo vive en `/checkout/$checkoutId`
+ * (ruta hermana, no hija: codegen usa `checkout.index.tsx`).
+ */
+import { useEffect } from 'react'
+import { definePage } from '../index'
+import { useSearchNavigate } from '../providers'
+
+export default definePage({
+  meta: () => ({
+    title: 'Checkout',
+    description: 'Confirma tu pedido y completa la compra',
+    noIndex: true,
+  }),
+  component: CheckoutRedirectPage,
+})
+
+function CheckoutRedirectPage() {
+  const navigate = useSearchNavigate()
+
+  useEffect(() => {
+    void navigate({ to: '/cart', replace: true })
+  }, [navigate])
+
+  return (
+    <div className="mx-auto w-full max-w-6xl px-4 py-16 text-center text-sm text-muted-foreground">
+      Redirigiendo al carrito…
+    </div>
+  )
+}

package/src/pages/thank-you.tsx

@@ -0,0 +1,53 @@
+/**
+ * Página de agradecimiento cerrada (`/thank-you`).
+ * Tras un checkout exitoso (sin redirect del provider).
+ */
+import { CheckCircle2 } from 'lucide-react'
+import { z } from 'zod'
+import { definePage, Link } from '../index'
+import { buttonVariants, cn } from '../ui'
+
+const ThankYouSearchSchema = z.object({
+  cartId: z.string().optional(),
+  transactionId: z.string().optional(),
+})
+
+type ThankYouSearch = z.infer<typeof ThankYouSearchSchema>
+
+export default definePage<undefined, Record<string, never>, ThankYouSearch>({
+  meta: () => ({
+    title: 'Gracias por tu compra',
+    description: 'Tu pedido fue recibido correctamente',
+    noIndex: true,
+  }),
+  validateSearch: (raw) => ThankYouSearchSchema.parse(raw),
+  component: ThankYouPage,
+})
+
+function ThankYouPage({ search }: { search: ThankYouSearch }) {
+  return (
+    <section className="mx-auto flex min-h-[55vh] w-full max-w-lg flex-col items-center justify-center px-4 py-16 text-center">
+      <div className="mb-5 flex size-14 items-center justify-center rounded-full bg-emerald-500/10 text-emerald-600">
+        <CheckCircle2 className="size-7" aria-hidden="true" />
+      </div>
+      <h1 className="text-3xl font-semibold tracking-tight">¡Gracias por tu compra!</h1>
+      <p className="mt-3 text-sm leading-6 text-muted-foreground">
+        Recibimos tu pedido y lo estamos procesando. Te enviaremos una confirmación por
+        correo cuando esté listo.
+      </p>
+      {search.transactionId ? (
+        <p className="mt-4 rounded-md bg-muted px-3 py-2 font-mono text-xs text-muted-foreground">
+          Ref. {search.transactionId}
+        </p>
+      ) : null}
+      <div className="mt-8 flex flex-wrap justify-center gap-3">
+        <Link to="/" className={cn(buttonVariants({ size: 'lg' }))}>
+          Volver a la tienda
+        </Link>
+        <Link to="/products" className={cn(buttonVariants({ size: 'lg', variant: 'outline' }))}>
+          Seguir comprando
+        </Link>
+      </div>
+    </section>
+  )
+}

package/src/providers/auth.tsx

@@ -0,0 +1,69 @@
+/**
+ * Auth storefront: Better Auth client + sesión via context.
+ *
+ * ```tsx
+ * const client = createStorefrontAuthClient()
+ * <AuthProvider client={client}>
+ *   <App />
+ * </AuthProvider>
+ *
+ * const { session, signIn, signOut } = useAuth()
+ * ```
+ */
+import { createContext, useContext, type ReactNode } from 'react'
+import { createAuthClient } from 'better-auth/react'
+import { ecomiqOAuthPasswordClient } from '../auth/ecomiq-oauth-password-client'
+import {
+  signInWithEcomiqCredentials,
+  type EcomiqSignInCredentials,
+} from '../auth/ecomiq-storefront-sign-in'
+import { useSettings } from './ecomiq'
+
+export type CreateStorefrontAuthClientOptions = {
+  baseURL?: string
+  basePath?: string
+}
+
+export function createStorefrontAuthClient(
+  options: CreateStorefrontAuthClientOptions = {},
+) {
+  return createAuthClient({
+    ...options,
+    plugins: [ecomiqOAuthPasswordClient()],
+  })
+}
+
+export type StorefrontAuthClientInstance = ReturnType<typeof createStorefrontAuthClient>
+/** Sesión tipada de Better Auth (`{ user, session }`). */
+export type StorefrontSession = StorefrontAuthClientInstance['$Infer']['Session']
+
+const AuthContext = createContext<StorefrontAuthClientInstance | null>(null)
+
+export function AuthProvider({
+  client,
+  children,
+}: {
+  client: StorefrontAuthClientInstance
+  children: ReactNode
+}) {
+  return <AuthContext.Provider value={client}>{children}</AuthContext.Provider>
+}
+
+/** Acceso a sesión y acciones de auth. Requiere `<AuthProvider>` + `<AppEcomiqProvider>`. */
+export function useAuth() {
+  const client = useContext(AuthContext)
+  if (!client) throw new Error('useAuth debe usarse dentro de AuthProvider')
+
+  const sessionQuery = client.useSession()
+  const settings = useSettings()
+
+  return {
+    client,
+    session: sessionQuery.data,
+    isPending: sessionQuery.isPending,
+    error: sessionQuery.error,
+    signIn: (credentials: EcomiqSignInCredentials) =>
+      signInWithEcomiqCredentials(client, settings, credentials),
+    signOut: () => client.signOut(),
+  }
+}