@ecomiq/storefront 1.1.5 → 2.0.0

package/README.md

@@ -1,441 +1,50 @@
 # @ecomiq/storefront
 
-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 bootstrap server por framework. **No incluye UI de tienda** (CMS, temas, checkout, etc.): la implementas en tu proyecto.
-
-## Requisitos
-
-- Node.js 20+
-- React 19+
-- **Next.js 15+** (App Router) *o* **TanStack Start** (`@tanstack/react-start`)
-- Tailwind CSS 4+ (opcional; ver `/nextjs/css`)
+Micro framework SSR de Ecomiq para storefronts. Páginas, datos y deploy sin
+configurar TanStack Start, Vite ni Cloudflare a mano.
 
 ## Instalación
 
 ```bash
 npm install @ecomiq/storefront
 # o
+yarn add @ecomiq/storefront
+# o
 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 = {
-  transpilePackages: ["@ecomiq/storefront"],
-};
-
-export default nextConfig;
-```
-
-## `ecomiq.config.js`
+Peer deps: `react` y `react-dom` ^19.
 
-En la **raíz de tu app** (`ecomiq.config.js`, `.cjs` o `.mjs`):
+## Uso
 
 ```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` | Tipos, schemas Zod, utilidades vanilla (`formatCurrency`, …). **Server** (`react-server`): config (`loadEcomiqConfig`, …) |
-| `@ecomiq/storefront/react` | **Client** (`"use client"`): `EcomiqProvider`, hooks BFF, componentes reutilizables |
-| `@ecomiq/storefront/nextjs` | **Server** (`react-server`): `getPublicStore`, cliente BFF server, auth helpers. **Client:** reexport de `/react` |
-| `@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) |
-
-Importa hooks y `EcomiqProvider` desde `@ecomiq/storefront/react`. El build npm separa server (`react-server`), vanilla (raíz) y React (`/react`) para App Router.
-
-Los hooks (`useStoreProducts`, `useStoreCart`, …) viven en `/react`; `/nextjs` y `/tanstack` los reexportan en client por compatibilidad.
-
-### Peers
-
-| Paquete | Cuándo |
-|---------|--------|
-| `react`, `react-dom` | Siempre |
-| `next` | Solo si usas `/nextjs` |
-| `@tanstack/react-start` | Solo si usas `/tanstack` |
-
-**Cloudflare:** el SDK no incluye `@opennextjs/cloudflare`. Si despliegas en Cloudflare con settings vía KV (`PUBLIC_STORE_SETTINGS_SOURCE=kv`), instálalo y configura wrangler en **tu** proyecto.
-
-## Arquitectura
-
-```
-                    ┌─────────────────────────────┐
-                    │  @ecomiq/storefront         │  ecomiq.config.js
-                    └──────────────┬──────────────┘
-                                   │
-         ┌─────────────────────────┴─────────────────────────┐
-         ▼                                                   ▼
-  /nextjs (+ /nextjs/api)                          /tanstack (+ /tanstack/api)
-  getPublicStore · toNextJsStoreApiHandler         getPublicStore · createTanStackStoreApiHandler
-         │                                                   │
-         └─────────────────────────┬─────────────────────────┘
-                                   ▼
-              Capa React (`/react`) — hooks, EcomiqProvider, cliente BFF browser, 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 el adapter de tu framework.
-
----
-
-## Inicio rápido — Next.js
+// ecomiq.config.js
+import { defineConfig } from '@ecomiq/storefront/config'
 
-### 1. Proxy BFF
-
-```ts
-// app/api/store/[...path]/route.ts
-import { toNextJsStoreApiHandler } from "@ecomiq/storefront/nextjs/api";
-
-export const { GET, POST, PUT, PATCH, DELETE } = toNextJsStoreApiHandler({
-  apiBaseUrl: process.env.STOREFRONT_API_URL!,
-});
-```
-
-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/ecomiq-provider.tsx
-"use client";
-
-import { EcomiqProvider } from "@ecomiq/storefront/react";
-import type { StorefrontSettings } from "@ecomiq/storefront";
-
-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();
-  if (error) {
-    // tu página de error / tienda no encontrada
-  }
-  return (
-    <html lang="es">
-      <body>
-        <EcomiqRootProvider store={store}>{children}</EcomiqRootProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-`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
-
-Importa hooks desde `@ecomiq/storefront/react`:
-
-```tsx
-"use client";
-
-import { useStoreProducts } from "@ecomiq/storefront/react";
-
-export function ProductList() {
-  const { useStorefrontProductsList } = useStoreProducts();
-  const { data, isLoading } = useStorefrontProductsList({ page: 1, pageSize: 24 });
-
-  if (isLoading) return <p>Cargando…</p>;
-  return (
-    <ul>
-      {data?.products.map((p) => (
-        <li key={p.id}>{p.name}</li>
-      ))}
-    </ul>
-  );
-}
+export default defineConfig({
+  store: { slug: 'mi-tienda' },
+})
 ```
 
-### 4. Datos en Server Components
-
 ```tsx
-import { getStorefrontProducts } from "@ecomiq/storefront/nextjs";
-
-export default async function CatalogPage() {
-  const { products } = await getStorefrontProducts({ page: 1, pageSize: 24 });
-  return <YourGrid products={products} />;
-}
-```
-
----
-
-## Inicio rápido — TanStack Start
-
-### 1. Proxy BFF
+// pages/index.tsx
+import { definePage, serverApi } from '@ecomiq/storefront'
 
-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 },
-});
+export default definePage({
+  loader: async () => {
+    const products = await serverApi.products.list()
+    return { products }
+  },
+  component: ({ data }) => <pre>{JSON.stringify(data.products, null, 2)}</pre>,
+})
 ```
 
-### 2. Tienda en root route
+CLI:
 
-```tsx
-// src/components/ecomiq-provider.tsx
-"use client";
-
-import { EcomiqProvider } from "@ecomiq/storefront/react";
-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/react";
-```
-
----
-
-## 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/nextjs";
-// TanStack: import { ecomiqOAuthPassword } from "@ecomiq/storefront/tanstack";
-
-export const auth = betterAuth({
-  plugins: [ecomiqOAuthPassword()],
-});
-```
-
-**Ruta API (Next.js):**
-
-```ts
-// app/api/auth/[...all]/route.ts
-import { toNextJsHandler } from "better-auth/next-js";
-import { auth } from "@/lib/auth";
-
-export const { GET, POST } = toNextJsHandler(auth);
-```
-
-**Cliente:**
-
-```ts
-// lib/auth-client.ts
-"use client";
-
-import { createAuthClient } from "better-auth/react";
-import { ecomiqOAuthPasswordClient } from "@ecomiq/storefront/nextjs";
-
-export const authClient = createAuthClient({
-  plugins: [ecomiqOAuthPasswordClient()],
-});
-```
-
-**Layout** — pasa `authClient` al provider:
-
-```tsx
-<EcomiqProvider store={store} authClient={authClient}>
-  {children}
-</EcomiqProvider>
-```
-
-### 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>;
-}
-```
-
-En TanStack, cambia el import server a `@ecomiq/storefront/tanstack` y los hooks a `@ecomiq/storefront/react`.
-
----
-
-## Qué incluye cada entry
-
-Desde `/nextjs` o `/tanstack` (**server**, condición `react-server`):
-
-- `getPublicStore`, `getHostname`, `fetchPublicStoreSettings`
-- Cliente BFF server: `getStorefrontProducts`, `registerCustomer`, carrito/cuenta, etc.
-- Auth server: `ecomiqOAuthPassword`
-
-Desde `@ecomiq/storefront/react` (**client**, `"use client"`):
-
-- **Provider:** `EcomiqProvider`, `useStore`, `usePublicStore`
-- **Hooks BFF:** `useStoreProducts`, `useStoreCollections`, `useStorePages`, `useStoreCart`
-- **Auth client:** `ecomiqOAuthPasswordClient`, `signInWithEcomiqCredentials`, `useStorefrontSession`
-- **Componentes:** selector de variantes de producto (más en futuras versiones)
-
-Desde `@ecomiq/storefront` (raíz — vanilla, server o client):
-
-- **Tipos y Zod:** `StorefrontSettings`, `StorefrontProduct`, schemas
-- **Utilidades:** `formatCurrency`, `countryCurrency`, `sanitizeHtml`, `stripHtml`, labels de pedidos, `findStorefrontCmsPageBySlug`
-- **Config** (solo server): `loadEcomiqConfig`, `EcomiqConfigSchema`, …
-
-## 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; requiere `@opennextjs/cloudflare` en tu proyecto, no en el SDK) |
-
-**Identificador de tienda:** `slugStore` en `ecomiq.config.*` si existe; si no, header `Host`.
-
-## Dependencias recomendadas
-
-**Next.js:**
-
-```json
-{
-  "dependencies": {
-    "@ecomiq/storefront": "^0.1.0",
-    "next": "^15.3.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
-  }
-}
-```
-
-**TanStack Start:**
-
-```json
-{
-  "dependencies": {
-    "@ecomiq/storefront": "^0.1.0",
-    "@tanstack/react-start": "^1.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
-  }
-}
+```bash
+npx ecomiq dev
+npx ecomiq build
+npx ecomiq deploy
 ```
 
-## Soporte
-
-Documentación y credenciales: [ecomiq.pe](https://ecomiq.pe) (o el portal de tu organización).
+Ver el monorepo [ecomiq-storefront](https://github.com/ecomiq/ecomiq-storefront) para la app de referencia y más documentación.

package/bin/ecomiq.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * CLI de Ecomiq.
+ *
+ *   ecomiq dev      → servidor de desarrollo con SSR y HMR
+ *   ecomiq build    → build de producción (target Cloudflare Workers)
+ *   ecomiq deploy   → build + publicación en Cloudflare Workers
+ *   ecomiq clean    → elimina la carpeta interna .ecomiq
+ *
+ * El usuario nunca interactúa con las herramientas internas: la CLI
+ * genera una app interna en `.ecomiq/` y delega en ella.
+ */
+import { spawn } from 'node:child_process'
+import { rmSync, existsSync, realpathSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { generateApp, watchPages } from '../src/codegen.mjs'
+import { parseConfig } from '../src/config.mjs'
+import { createViteConfig } from '../src/vite-inline.mjs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const cwd = process.cwd()
+
+const c = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+}
+
+function banner(msg) {
+  console.log(`\n  ${c.bold('◈ ecomiq')} ${c.dim('·')} ${msg}\n`)
+}
+
+export async function loadUserConfig(projectDirectory = process.cwd()) {
+  const configPath = resolve(projectDirectory, 'ecomiq.config.js')
+  if (!existsSync(configPath)) {
+    throw new Error(
+      `No se encontró ${configPath}. Crea ecomiq.config.js en la raíz del proyecto.`,
+    )
+  }
+  const mod = await import(pathToFileURL(configPath).href)
+  return parseConfig(mod.default, { source: configPath })
+}
+
+function run(bin, args, opts = {}) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(bin, args, {
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+      ...opts,
+    })
+    child.on('exit', (code) => (code === 0 ? resolvePromise() : reject(new Error(`${bin} salió con código ${code}`))))
+  })
+}
+
+// Los binarios internos viven en las dependencias del framework.
+const frameworkRoot = resolve(__dirname, '..')
+function internalBin(name) {
+  return resolve(frameworkRoot, 'node_modules', '.bin', name)
+}
+function resolveBin(name) {
+  const local = internalBin(name)
+  if (existsSync(local)) return local
+  // fallback: hoisted en el node_modules del proyecto
+  const hoisted = resolve(cwd, 'node_modules', '.bin', name)
+  return existsSync(hoisted) ? hoisted : name
+}
+
+const appDir = resolve(cwd, '.ecomiq')
+
+async function prepare() {
+  const config = await loadUserConfig()
+  await generateApp({ cwd, appDir, frameworkRoot, config })
+  return config
+}
+
+export async function runCli(command = process.argv[2] ?? 'help') {
+  switch (command) {
+    case 'dev': {
+      const config = await prepare()
+      const port = config.dev?.port ?? 3000
+      banner(`dev · ${config.name ?? 'tienda'} ${c.dim('http://localhost:' + port)}`)
+      const { createServer } = await import('vite')
+      const server = await createServer({ ...createViteConfig({ appDir, config }), server: { port, fs: { allow: ['..'] } } })
+      await server.listen()
+      const pageWatcher = watchPages({
+        cwd,
+        appDir,
+        frameworkRoot,
+        config,
+        onGenerate() {
+          server.config.logger.info(c.dim('  ↻ rutas regeneradas'))
+        },
+        onError(error) {
+          server.config.logger.error(`No se pudieron regenerar las rutas: ${error.message}`)
+        },
+      })
+      server.httpServer?.once('close', () => pageWatcher.close())
+      server.printUrls()
+      break
+    }
+    case 'build': {
+      const config = await prepare()
+      banner(`build · Cloudflare Workers`)
+      const { createBuilder } = await import('vite')
+      const builder = await createBuilder(createViteConfig({ appDir, config }))
+      await builder.buildApp()
+      console.log(c.green('\n  ✔ Build listo en .ecomiq/dist\n'))
+      break
+    }
+    case 'deploy': {
+      const config = await prepare()
+      banner(`deploy · Cloudflare Workers`)
+      const { createBuilder } = await import('vite')
+      const builder = await createBuilder(createViteConfig({ appDir, config }))
+      await builder.buildApp()
+      // @cloudflare/vite-plugin emite la config final del Worker junto al build
+      const built = resolve(appDir, 'dist', 'server', 'wrangler.json')
+      const fallback = resolve(appDir, 'wrangler.jsonc')
+      await run(resolveBin('wrangler'), ['deploy', '--config', existsSync(built) ? built : fallback], { cwd: appDir })
+      console.log(c.green('\n  ✔ Publicado en Cloudflare Workers\n'))
+      break
+    }
+    case 'clean': {
+      rmSync(appDir, { recursive: true, force: true })
+      console.log(c.green('  ✔ .ecomiq eliminado'))
+      break
+    }
+    default: {
+      banner('framework de storefronts')
+      console.log(`  ${c.bold('ecomiq dev')}      servidor de desarrollo`)
+      console.log(`  ${c.bold('ecomiq build')}    build de producción`)
+      console.log(`  ${c.bold('ecomiq deploy')}   publicar en Cloudflare Workers`)
+      console.log(`  ${c.bold('ecomiq clean')}    limpiar archivos internos\n`)
+    }
+  }
+}
+
+const invokedPath = process.argv[1]
+let invokedDirectly = false
+if (invokedPath && existsSync(invokedPath)) {
+  invokedDirectly = realpathSync(invokedPath) === fileURLToPath(import.meta.url)
+}
+
+if (invokedDirectly) {
+  try {
+    await runCli()
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Error desconocido'
+    console.error(c.red(`\n  ✖ ${message}\n`))
+    process.exitCode = 1
+  }
+}