@ecomiq/storefront 0.1.1 → 1.0.0

package/README.md

@@ -1,15 +1,15 @@
 # @ecomiq/storefront
 
-SDK **headless** para construir tu propia tienda con **Next.js** y **React** sobre Ecomiq.
+SDK **headless** para construir tu tienda con **Next.js** o **TanStack Start** y **React** sobre la API de Ecomiq.
 
-Incluye capa de **datos y API**: tipos, schemas Zod, cliente BFF (`/api/store`), hooks y utilidades server. **No** incluye UI precargada (checkout, CMS renderer, temas, `ShellRouter`, etc.): diseñas e implementas la interfaz 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+
+- **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,16 +40,77 @@ const nextConfig = {
 export default nextConfig;
 ```
 
+## `ecomiq.config.js`
+
+En la **raíz de tu app** (`ecomiq.config.js`, `.cjs` o `.mjs`):
+
+```js
+// @ts-check
+
+/** @type {import('@ecomiq/storefront').EcomiqConfig} */
+const ecomiqConfig = {
+  slugStore: "mi-tienda",
+};
+
+module.exports = ecomiqConfig;
+```
+
+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
+
+| 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 (cookie / header 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 SDK **no** llama al upstream desde el browser; todas las peticiones van al proxy que tú montas 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
 
@@ -50,12 +123,11 @@ export const { GET, POST, PUT, PATCH, DELETE } = toNextJsStoreApiHandler({
 });
 ```
 
-### 2. Resolver la tienda (server)
+### 2. Layout y tienda
 
 ```tsx
 // app/layout.tsx (Server Component)
 import { getPublicStore, EcomiqProvider } from "@ecomiq/storefront/nextjs";
-import { authClient } from "./auth-client";
 
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
   const { data: store, error } = await getPublicStore();
@@ -63,14 +135,14 @@ export default async function RootLayout({ children }: { children: React.ReactNo
     // tu página de error / tienda no encontrada
   }
   return (
-    <EcomiqProvider store={store} authClient={authClient}>
+    <EcomiqProvider store={store}>
       {children}
     </EcomiqProvider>
   );
 }
 ```
 
-`EcomiqProvider` es un Client Component: puedes importarlo desde un layout servidor como en el ejemplo. Hidrata la tienda (`useStore`, `setClientStoreId`), React Query y la sesión (`authClient` de Better Auth).
+`EcomiqProvider` hidrata `useStore`, configura React Query y el `storeId` del cliente BFF.
 
 ### 3. Catálogo con hooks
 
@@ -105,67 +177,183 @@ export default async function CatalogPage() {
 }
 ```
 
-### 5. Estilos (opcional)
+---
+
+## Inicio rápido — TanStack Start
 
-```css
-@import "tailwindcss";
-@import "@ecomiq/storefront/nextjs/css";
+### 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 },
+});
 ```
 
-El CSS publicado es **mínimo**. Tu design system y componentes viven en la app.
+### 2. Tienda en root route
 
-## Puntos de entrada (npm)
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Outlet } from "@tanstack/react-router";
+import { getPublicStore, EcomiqProvider } from "@ecomiq/storefront/tanstack";
 
-| Import | Uso |
-|--------|-----|
-| `@ecomiq/storefront/core` | Tipos, Zod, utilidades, servicios axios legacy |
-| `@ecomiq/storefront/react` | `EcomiqProvider`, hooks, stores, auth OAuth, `findStorefrontCmsPageBySlug`, selector de variantes |
-| `@ecomiq/storefront/nextjs` | `getPublicStore`, `EcomiqProvider`, cliente BFF, hooks `useStore*` |
-| `@ecomiq/storefront/nextjs/api` | Handler del proxy `/api/store/*` |
-| `@ecomiq/storefront/nextjs/css` | Tailwind base opcional |
-| `@ecomiq/storefront/nextjs/postcss` | PostCSS de referencia |
+export const Route = createRootRoute({
+  loader: async () => getPublicStore(),
+  component: RootComponent,
+});
 
-No hay subpath `./client` en npm: las funciones del cliente BFF se importan desde **`/nextjs`**.
+function RootComponent() {
+  const { data: store } = Route.useLoaderData();
+  return (
+    <EcomiqProvider store={store}>
+      <Outlet />
+    </EcomiqProvider>
+  );
+}
+```
 
-## Auth (Better Auth)
+### 3. Hooks (idénticos a Next)
 
-Plugins para OAuth password grant de Ecomiq:
+```tsx
+import { useStoreProducts, useStoreCart } from "@ecomiq/storefront/tanstack";
+```
+
+---
+
+## Autenticación (Better Auth + SDK)
+
+Instala [Better Auth](https://www.better-auth.com/).
+
+**Servidor:**
 
 ```ts
-import {
-  ecomiqOAuthPassword,
-  ecomiqOAuthPasswordClient,
-} from "@ecomiq/storefront/react";
+// lib/auth.ts
+import { betterAuth } from "better-auth";
+import { ecomiqOAuthPassword } from "@ecomiq/storefront/nextjs";
+// TanStack: import { ecomiqOAuthPassword } from "@ecomiq/storefront/tanstack";
+
+export const auth = betterAuth({
+  plugins: [ecomiqOAuthPassword()],
+});
 ```
 
-## Variables de entorno
+**Ruta API (Next.js):**
 
-| Variable | Descripción |
-|----------|-------------|
-| `STOREFRONT_API_URL` | URL base de la API de tienda (proxy) |
-| `PUBLIC_STORE_SETTINGS_SOURCE` | `api` (default) o `kv` (OpenNext / Cloudflare) |
+```ts
+// app/api/auth/[...all]/route.ts
+import { toNextJsHandler } from "better-auth/next-js";
+import { auth } from "@/lib/auth";
 
-Tras `getPublicStore`, el SDK fija `X-Store-Id` en el servidor para las llamadas al proxy.
+export const { GET, POST } = toNextJsHandler(auth);
+```
 
-## Qué no viene en el paquete npm
+**Cliente:**
 
-Pensado para que **tú** construyas la UI:
+```ts
+// lib/auth-client.ts
+"use client";
 
-- `ShellRouter`, páginas exportadas
-- Checkout, carrito drawer, cuenta, formularios precargados
-- `CmsSectionsRenderer`, `DefaultCmsSectionsRenderer`, `SafeThemeInjector`
-- `ThemeComponentLoader` y temas `default` / `ana` / `sony`
-- Dependencia de `@ecomiq/ui`
+import { createAuthClient } from "better-auth/react";
+import { ecomiqOAuthPasswordClient } from "@ecomiq/storefront/nextjs";
 
-Esa capa completa existe en el **monorepo Ecomiq** (`workspace:*` sobre `src/`), no en el tarball npm.
+export const authClient = createAuthClient({
+  plugins: [ecomiqOAuthPasswordClient()],
+});
+```
 
-## Desarrollo en el monorepo Ecomiq
+**Layout** — pasa `authClient` al provider:
 
-Si trabajas dentro del repo `ecomiq`, el paquete se consume por fuente con exports amplios (`./react/components/*`, `./nextjs/export-pages/*`, etc.) y UI con `@ecomiq/ui`.
+```tsx
+<EcomiqProvider store={store} authClient={authClient}>
+  {children}
+</EcomiqProvider>
+```
 
-Para empaquetar o publicar en npm: ver [PUBLISHING.md](./PUBLISHING.md).
+### Login, registro y logout
+
+```tsx
+"use client";
+
+import {
+  useStore,
+  useStorefrontAuthClient,
+  useStorefrontSession,
+  registerCustomer,
+  signInWithEcomiqCredentials,
+} from "@ecomiq/storefront/nextjs";
+
+export function AccountActions() {
+  const { data: store } = useStore();
+  const authClient = useStorefrontAuthClient();
+  const { isAuthenticated, user, signOut, refetch } = useStorefrontSession();
+
+  async function handleLogin(email: string, password: string) {
+    await signInWithEcomiqCredentials(authClient, store, { email, password });
+    await refetch();
+  }
+
+  async function handleRegister(input: {
+    email: string;
+    password: string;
+    firstName: string;
+    lastName: string;
+    countryIsoCode: string;
+    phone: string;
+  }) {
+    await registerCustomer(input);
+    await handleLogin(input.email, input.password);
+  }
+
+  if (isAuthenticated) {
+    return (
+      <div>
+        <p>Hola, {user?.firstName ?? user?.email}</p>
+        <button type="button" onClick={() => signOut()}>Cerrar sesión</button>
+      </div>
+    );
+  }
+
+  return <div>{/* Tu UI */}</div>;
+}
+```
 
-## Dependencias recomendadas en tu app
+En TanStack, cambia el import a `@ecomiq/storefront/tanstack`.
+
+---
+
+## Qué incluye cada adapter
+
+Desde `/nextjs` o `/tanstack` obtienes:
+
+- **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` (Cloudflare KV vía `@opennextjs/cloudflare`) |
+
+**Identificador de tienda:** `slugStore` en `ecomiq.config.*` si existe; si no, header `Host`.
+
+## Dependencias recomendadas
+
+**Next.js:**
 
 ```json
 {
@@ -180,6 +368,21 @@ Para empaquetar o publicar en npm: ver [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).

package/dist/..d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+declare const EcomiqConfigSchema: z.ZodObject<{
+    /**
+     * Slug de tienda en Ecomiq (p. ej. `mi-tienda` para `mi-tienda.ecomiq.app`).
+     * Si está definido, tiene prioridad sobre el `Host` de la request (útil en `localhost`).
+     */
+    slugStore: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    slugStore?: string | undefined;
+}, {
+    slugStore?: string | undefined;
+}>;
+type EcomiqConfig = z.infer<typeof EcomiqConfigSchema>;
+/**
+ * Carga `ecomiq.config.js` (o `.cjs` / `.mjs`) desde la raíz del proyecto (`process.cwd()`).
+ * Resultado en caché por proceso.
+ */
+declare function loadEcomiqConfig(cwd?: string): EcomiqConfig | null;
+/** Limpia la caché (tests o recarga en dev). */
+declare function clearEcomiqConfigCache(): void;
+/**
+ * Identificador de tienda para settings (API / KV).
+ * 1. `slugStore` en `ecomiq.config.*` si existe.
+ * 2. Si no, deriva del header `Host` (`resolveStorefrontSettingsHost`).
+ */
+declare function resolvePublicStoreKey(hostHeader: string | null | undefined, cwd?: string): string;
+declare function hasEcomiqSlugStoreConfig(cwd?: string): boolean;
+
+export { type EcomiqConfig, EcomiqConfigSchema, clearEcomiqConfigCache, hasEcomiqSlugStoreConfig, loadEcomiqConfig, resolvePublicStoreKey };