@ecomiq/storefront 0.1.2 → 1.0.1

package/README.md

@@ -1,15 +1,15 @@
 # @ecomiq/storefront
 
-SDK **headless** para construir tu tienda con **Next.js** y **React** sobre la API de Ecomiq.
+SDK **headless** para construir tu tienda con **Next.js** o **TanStack Start** y **React** sobre la API de Ecomiq.
 
-Incluye tipos, schemas Zod, cliente BFF (`/api/store`), hooks, `EcomiqProvider` y utilidades server. La interfaz de la tienda la implementas en tu proyecto.
+Incluye tipos, schemas Zod, cliente BFF (`/api/store`), hooks, `EcomiqProvider` y bootstrap server por framework. **No incluye UI de tienda** (CMS, temas, checkout, etc.): la implementas en tu proyecto.
 
 ## Requisitos
 
 - Node.js 20+
-- Next.js 15+ (App Router)
 - React 19+
-- Tailwind CSS 4+ (opcional)
+- **Next.js 15+** (App Router) *o* **TanStack Start** (`@tanstack/react-start`)
+- Tailwind CSS 4+ (opcional; ver `/nextjs/css`)
 
 ## Instalación
 
@@ -19,6 +19,18 @@ npm install @ecomiq/storefront
 pnpm add @ecomiq/storefront
 ```
 
+Instala también el peer de tu stack:
+
+```bash
+# Next.js
+pnpm add next react react-dom @tanstack/react-query better-auth
+
+# TanStack Start
+pnpm add @tanstack/react-start react react-dom @tanstack/react-query better-auth
+```
+
+**Next.js** — en `next.config`:
+
 ```js
 /** @type {import('next').NextConfig} */
 const nextConfig = {
@@ -28,9 +40,9 @@ const nextConfig = {
 export default nextConfig;
 ```
 
-## `ecomiq.config.js` (opcional)
+## `ecomiq.config.js`
 
-Puedes añadir en la **raíz de tu app** (junto a `next.config.js`) un archivo `ecomiq.config.js`, `ecomiq.config.cjs` o `ecomiq.config.mjs`:
+En la **raíz de tu app** (`ecomiq.config.js`, `.cjs` o `.mjs`):
 
 ```js
 // @ts-check
@@ -43,20 +55,62 @@ const ecomiqConfig = {
 module.exports = ecomiqConfig;
 ```
 
-Si defines `slugStore`, `getPublicStore` usa ese slug como identificador de tienda y no lo infiere del header `Host`. Si no usas el archivo, la tienda se resuelve por el `Host` de la request (por ejemplo subdominio o dominio propio).
+Si defines `slugStore`, `getPublicStore` usa ese slug (útil en localhost). Si no, deriva del header `Host`. Plantilla: [ecomiq.config.example.cjs](./ecomiq.config.example.cjs).
+
+## Puntos de entrada (npm)
+
+| Import | Uso |
+|--------|-----|
+| `@ecomiq/storefront` | **Client:** `EcomiqProvider`, hooks (`useStoreProducts`, …). **Server** (`react-server`): config (`loadEcomiqConfig`, …) |
+| `@ecomiq/storefront/nextjs` | **Server** (`react-server`): `getPublicStore`, cliente BFF server, auth helpers. **Client:** `EcomiqProvider`, hooks |
+| `@ecomiq/storefront/nextjs/api` | Proxy `/api/store/*` (App Router) |
+| `@ecomiq/storefront/nextjs/css` | Tailwind mínimo (opcional) |
+| `@ecomiq/storefront/nextjs/postcss` | PostCSS de referencia |
+| `@ecomiq/storefront/tanstack` | TanStack server + reexport client (misma API client que `/nextjs`) |
+| `@ecomiq/storefront/tanstack/api` | Proxy `/api/store/*` (server routes) |
 
-Cuándo usarlo lo decides tú: en local, staging o producción. Plantilla: [ecomiq.config.example.cjs](./ecomiq.config.example.cjs).
+Importa hooks desde `@ecomiq/storefront` o desde `@ecomiq/storefront/nextjs`. El build npm separa internamente server y client para App Router — **no necesitas** subpaths `/server` ni `/client`.
+
+Los hooks (`useStoreProducts`, `useStoreCart`, …) tienen **una sola implementación** reexportada por ambos adapters; solo cambia el bootstrap server (`getPublicStore`, handler del proxy).
+
+### Peers
+
+| Paquete | Cuándo |
+|---------|--------|
+| `react`, `react-dom` | Siempre |
+| `next` | Solo si usas `/nextjs` |
+| `@tanstack/react-start` | Solo si usas `/tanstack` |
+| `@opennextjs/cloudflare` | Opcional (settings vía KV) |
 
 ## Arquitectura
 
 ```
-Navegador → /api/store/* (proxy en tu Next.js) → API Ecomiq
-              ↑ X-Store-Id (tras getPublicStore)
+                    ┌─────────────────────────────┐
+                    │  @ecomiq/storefront         │  ecomiq.config.js
+                    └──────────────┬──────────────┘
+                                   │
+         ┌─────────────────────────┴─────────────────────────┐
+         ▼                                                   ▼
+  /nextjs (+ /nextjs/api)                          /tanstack (+ /tanstack/api)
+  getPublicStore · toNextJsStoreApiHandler         getPublicStore · createTanStackStoreApiHandler
+         │                                                   │
+         └─────────────────────────┬─────────────────────────┘
+                                   ▼
+              Capa React compartida (hooks, EcomiqProvider, cliente BFF, auth)
+                                   │
+                                   ▼
+              core/server — fetchPublicStoreSettings · handleStoreProxyRequest
+                                   │
+                                   ▼
+Navegador → /api/store/* (proxy en tu app) → API Ecomiq
+              ↑ contexto X-Store-Id (tras getPublicStore)
 ```
 
-El browser no llama al upstream directo; montas el proxy con `toNextJsStoreApiHandler`.
+El browser **no** llama al upstream directo; montas el proxy con el adapter de tu framework.
 
-## Inicio rápido
+---
+
+## Inicio rápido — Next.js
 
 ### 1. Proxy BFF
 
@@ -69,11 +123,32 @@ export const { GET, POST, PUT, PATCH, DELETE } = toNextJsStoreApiHandler({
 });
 ```
 
+Los hooks y `EcomiqProvider` son **Client Components** (`"use client"`). En el layout (Server Component) solo importes funciones server; el provider va en un archivo client aparte.
+
 ### 2. Layout y tienda
 
 ```tsx
-// app/layout.tsx (Server Component)
-import { getPublicStore, EcomiqProvider } from "@ecomiq/storefront/nextjs";
+// app/ecomiq-provider.tsx
+"use client";
+
+import { EcomiqProvider } from "@ecomiq/storefront";
+import type { StorefrontSettings } from "@ecomiq/storefront/nextjs";
+
+export function EcomiqRootProvider({
+  store,
+  children,
+}: {
+  store: StorefrontSettings | null;
+  children: React.ReactNode;
+}) {
+  return <EcomiqProvider store={store}>{children}</EcomiqProvider>;
+}
+```
+
+```tsx
+// app/layout.tsx — Server Component
+import { getPublicStore } from "@ecomiq/storefront/nextjs";
+import { EcomiqRootProvider } from "./ecomiq-provider";
 
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
   const { data: store, error } = await getPublicStore();
@@ -81,21 +156,25 @@ export default async function RootLayout({ children }: { children: React.ReactNo
     // tu página de error / tienda no encontrada
   }
   return (
-    <EcomiqProvider store={store}>
-      {children}
-    </EcomiqProvider>
+    <html lang="es">
+      <body>
+        <EcomiqRootProvider store={store}>{children}</EcomiqRootProvider>
+      </body>
+    </html>
   );
 }
 ```
 
-`EcomiqProvider` hidrata el estado de la tienda (`useStore`, `setClientStoreId`) y React Query. La autenticación es opcional (pasos 5 y 6).
+`getPublicStore` corre en el servidor. `EcomiqProvider` hidrata `useStore`, configura React Query y el `storeId` del cliente BFF — debe vivir en un módulo con `"use client"`.
 
 ### 3. Catálogo con hooks
 
+Puedes importar hooks desde el paquete raíz o desde `/nextjs`:
+
 ```tsx
 "use client";
 
-import { useStoreProducts } from "@ecomiq/storefront/nextjs";
+import { useStoreProducts } from "@ecomiq/storefront";
 
 export function ProductList() {
   const { useStorefrontProductsList } = useStoreProducts();
@@ -123,23 +202,97 @@ export default async function CatalogPage() {
 }
 ```
 
-### 5. Autenticación (Better Auth + SDK)
+---
+
+## Inicio rápido — TanStack Start
 
-Instala [Better Auth](https://www.better-auth.com/) y los plugins del SDK (OAuth password grant con credenciales Ecomiq).
+### 1. Proxy BFF
+
+Ruta splat: `/api/store/*` → `routes/api/store/$.ts`
+
+```ts
+// src/routes/api/store/$.ts
+import { createFileRoute } from "@tanstack/react-router";
+import { createTanStackStoreApiHandler } from "@ecomiq/storefront/tanstack/api";
+
+const storeApi = createTanStackStoreApiHandler({
+  apiBaseUrl: process.env.STOREFRONT_API_URL,
+});
+
+export const Route = createFileRoute("/api/store/$")({
+  server: { handlers: storeApi },
+});
+```
+
+### 2. Tienda en root route
+
+```tsx
+// src/components/ecomiq-provider.tsx
+"use client";
+
+import { EcomiqProvider } from "@ecomiq/storefront";
+import type { StorefrontSettings } from "@ecomiq/storefront/tanstack";
+
+export function EcomiqRootProvider({
+  store,
+  children,
+}: {
+  store: StorefrontSettings | null;
+  children: React.ReactNode;
+}) {
+  return <EcomiqProvider store={store}>{children}</EcomiqProvider>;
+}
+```
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Outlet } from "@tanstack/react-router";
+import { getPublicStore } from "@ecomiq/storefront/tanstack";
+import { EcomiqRootProvider } from "../components/ecomiq-provider";
+
+export const Route = createRootRoute({
+  loader: async () => getPublicStore(),
+  component: RootComponent,
+});
+
+function RootComponent() {
+  const { data: store } = Route.useLoaderData();
+  return (
+    <EcomiqRootProvider store={store}>
+      <Outlet />
+    </EcomiqRootProvider>
+  );
+}
+```
+
+### 3. Hooks (Client Components)
+
+```tsx
+"use client";
+
+import { useStoreProducts, useStoreCart } from "@ecomiq/storefront";
+```
+
+---
+
+## Autenticación (Better Auth + SDK)
+
+Instala [Better Auth](https://www.better-auth.com/).
 
 **Servidor:**
 
 ```ts
 // lib/auth.ts
 import { betterAuth } from "better-auth";
-import { ecomiqOAuthPassword } from "@ecomiq/storefront/react";
+import { ecomiqOAuthPassword } from "@ecomiq/storefront/nextjs";
+// TanStack: import { ecomiqOAuthPassword } from "@ecomiq/storefront/tanstack";
 
 export const auth = betterAuth({
   plugins: [ecomiqOAuthPassword()],
 });
 ```
 
-**Ruta API:**
+**Ruta API (Next.js):**
 
 ```ts
 // app/api/auth/[...all]/route.ts
@@ -156,26 +309,22 @@ export const { GET, POST } = toNextJsHandler(auth);
 "use client";
 
 import { createAuthClient } from "better-auth/react";
-import { ecomiqOAuthPasswordClient } from "@ecomiq/storefront/react";
+import { ecomiqOAuthPasswordClient } from "@ecomiq/storefront/nextjs";
 
 export const authClient = createAuthClient({
   plugins: [ecomiqOAuthPasswordClient()],
 });
 ```
 
-**Layout** — añade `authClient` al provider del paso 2:
+**Layout** — pasa `authClient` al provider:
 
 ```tsx
-import { authClient } from "@/lib/auth-client";
-
 <EcomiqProvider store={store} authClient={authClient}>
   {children}
 </EcomiqProvider>
 ```
 
-### 6. Login, registro y logout
-
-Con el paso 5 configurado:
+### Login, registro y logout
 
 ```tsx
 "use client";
@@ -184,8 +333,6 @@ import {
   useStore,
   useStorefrontAuthClient,
   useStorefrontSession,
-} from "@ecomiq/storefront/react";
-import {
   registerCustomer,
   signInWithEcomiqCredentials,
 } from "@ecomiq/storefront/nextjs";
@@ -216,54 +363,44 @@ export function AccountActions() {
     return (
       <div>
         <p>Hola, {user?.firstName ?? user?.email}</p>
-        <button type="button" onClick={() => signOut()}>
-          Cerrar sesión
-        </button>
+        <button type="button" onClick={() => signOut()}>Cerrar sesión</button>
       </div>
     );
   }
 
-  return (
-    <div>
-      {/* Tu UI: formularios que llaman handleLogin / handleRegister */}
-    </div>
-  );
+  return <div>{/* Tu UI */}</div>;
 }
 ```
 
-- **Login:** `signInWithEcomiqCredentials` (headers de tienda los resuelve el SDK).
-- **Registro:** `registerCustomer`, luego login con las mismas credenciales.
-- **Logout:** `signOut()` de `useStorefrontSession`.
+En TanStack, cambia el import a `@ecomiq/storefront/tanstack`.
 
-## Puntos de entrada (npm)
+---
 
-| Import | Uso |
-|--------|-----|
-| `@ecomiq/storefront` | `EcomiqConfig`, `loadEcomiqConfig` (tipado de `ecomiq.config.js`) |
-| `@ecomiq/storefront/core` | Tipos, Zod, utilidades |
-| `@ecomiq/storefront/react` | `EcomiqProvider`, hooks, sesión (`useStorefrontSession`), plugins Better Auth |
-| `@ecomiq/storefront/nextjs` | `getPublicStore`, cliente BFF, `registerCustomer`, `signInWithEcomiqCredentials`, hooks `useStore*` |
-| `@ecomiq/storefront/nextjs/api` | Proxy `/api/store/*` |
+## Qué incluye cada adapter
+
+Desde `/nextjs` o `/tanstack` obtienes:
 
-El cliente BFF se importa desde **`/nextjs`** (no hay subpath `./client` en npm).
+- **Server:** `getPublicStore`, `getHostname`, `fetchPublicStoreSettings` (agnóstico)
+- **Provider:** `EcomiqProvider`, `useStore`, `usePublicStore`
+- **Hooks BFF:** `useStoreProducts`, `useStoreCollections`, `useStorePages`, `useStoreCart`
+- **Cliente:** `getStorefrontProducts`, `registerCustomer`, servicios de carrito/cuenta, etc.
+- **Auth:** `ecomiqOAuthPassword`, `ecomiqOAuthPasswordClient`, `signInWithEcomiqCredentials`, `useStorefrontSession`
+- **Tipos y Zod:** `StorefrontSettings`, `StorefrontProduct`, schemas, `formatCurrency`
+- **Utilidades:** `findStorefrontCmsPageBySlug`, selector de variantes de producto
 
 ## Variables de entorno
 
 | Variable | Descripción |
 |----------|-------------|
 | `STOREFRONT_API_URL` | URL base de la API de tienda (proxy) |
-| `PUBLIC_STORE_SETTINGS_SOURCE` | `api` (default) o `kv` (despliegues con KV) |
-
-Tras `getPublicStore`, el SDK configura el contexto de tienda en el servidor para las llamadas al proxy.
+| `PUBLIC_STORE_SETTINGS_SOURCE` | `api` (default) o `kv` (Cloudflare KV vía `@opennextjs/cloudflare`) |
 
 **Identificador de tienda:** `slugStore` en `ecomiq.config.*` si existe; si no, header `Host`.
 
-## Publicación del paquete
-
-Mantenimiento del tarball npm: [PUBLISHING.md](./PUBLISHING.md).
-
 ## Dependencias recomendadas
 
+**Next.js:**
+
 ```json
 {
   "dependencies": {
@@ -277,6 +414,21 @@ Mantenimiento del tarball npm: [PUBLISHING.md](./PUBLISHING.md).
 }
 ```
 
+**TanStack Start:**
+
+```json
+{
+  "dependencies": {
+    "@ecomiq/storefront": "^0.1.0",
+    "@tanstack/react-query": "^5.66.0",
+    "@tanstack/react-start": "^1.0.0",
+    "better-auth": "^1.6.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}
+```
+
 ## Soporte
 
 Documentación y credenciales: [ecomiq.pe](https://ecomiq.pe) (o el portal de tu organización).