@ecomiq/storefront 0.1.2 → 1.0.0

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` | Solo config: `EcomiqConfig`, `loadEcomiqConfig`, `resolvePublicStoreKey` |
+| `@ecomiq/storefront/nextjs` | Adapter Next + capa React (hooks, provider, BFF, auth, tipos) |
+| `@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` | Adapter TanStack + **misma** capa React que `/nextjs` |
+| `@ecomiq/storefront/tanstack/api` | Proxy `/api/store/*` (server routes) |
+
+Importa **todo desde el adapter de tu framework** (`/nextjs` o `/tanstack`). En npm no hay subpaths públicos `/core` ni `/react`.
+
+Los hooks (`useStoreProducts`, `useStoreCart`, `useStoreCollections`, etc.) tienen **una sola implementación** reexportada por ambos adapters; solo cambia el bootstrap server (`getPublicStore`, handler del proxy).
+
+### Peers
 
-Cuándo usarlo lo decides tú: en local, staging o producción. Plantilla: [ecomiq.config.example.cjs](./ecomiq.config.example.cjs).
+| 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
 
@@ -88,7 +142,7 @@ export default async function RootLayout({ children }: { children: React.ReactNo
 }
 ```
 
-`EcomiqProvider` hidrata el estado de la tienda (`useStore`, `setClientStoreId`) y React Query. La autenticación es opcional (pasos 5 y 6).
+`EcomiqProvider` hidrata `useStore`, configura React Query y el `storeId` del cliente BFF.
 
 ### 3. Catálogo con hooks
 
@@ -123,23 +177,76 @@ export default async function CatalogPage() {
 }
 ```
 
-### 5. Autenticación (Better Auth + SDK)
+---
+
+## Inicio rápido — TanStack Start
+
+### 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/routes/__root.tsx
+import { createRootRoute, Outlet } from "@tanstack/react-router";
+import { getPublicStore, EcomiqProvider } from "@ecomiq/storefront/tanstack";
+
+export const Route = createRootRoute({
+  loader: async () => getPublicStore(),
+  component: RootComponent,
+});
+
+function RootComponent() {
+  const { data: store } = Route.useLoaderData();
+  return (
+    <EcomiqProvider store={store}>
+      <Outlet />
+    </EcomiqProvider>
+  );
+}
+```
+
+### 3. Hooks (idénticos a Next)
+
+```tsx
+import { useStoreProducts, useStoreCart } from "@ecomiq/storefront/tanstack";
+```
+
+---
+
+## Autenticación (Better Auth + SDK)
 
-Instala [Better Auth](https://www.better-auth.com/) y los plugins del SDK (OAuth password grant con credenciales Ecomiq).
+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 +263,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 +287,6 @@ import {
   useStore,
   useStorefrontAuthClient,
   useStorefrontSession,
-} from "@ecomiq/storefront/react";
-import {
   registerCustomer,
   signInWithEcomiqCredentials,
 } from "@ecomiq/storefront/nextjs";
@@ -216,54 +317,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 +368,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).