@ecomiq/storefront 0.1.0 → 0.1.2

package/README.md

@@ -1,15 +1,15 @@
 # @ecomiq/storefront
 
-SDK oficial para construir tiendas online con **Next.js** y **React** sobre la plataforma Ecomiq.
+SDK **headless** para construir tu tienda con **Next.js** y **React** sobre la API de Ecomiq.
 
-Incluye componentes de catálogo, carrito, checkout, cuenta de cliente, CMS, temas y un proxy listo para conectar tu app con la API de tienda.
+Incluye tipos, schemas Zod, cliente BFF (`/api/store`), hooks, `EcomiqProvider` y utilidades server. La interfaz de la tienda la implementas en tu proyecto.
 
 ## Requisitos
 
 - Node.js 20+
 - Next.js 15+ (App Router)
 - React 19+
-- Tailwind CSS 4+
+- Tailwind CSS 4+ (opcional)
 
 ## Instalación
 
@@ -19,8 +19,6 @@ npm install @ecomiq/storefront
 pnpm add @ecomiq/storefront
 ```
 
-En `next.config.js` (o `.mjs`), transpila el SDK:
-
 ```js
 /** @type {import('next').NextConfig} */
 const nextConfig = {
@@ -30,20 +28,37 @@ const nextConfig = {
 export default nextConfig;
 ```
 
-## Inicio rápido
+## `ecomiq.config.js` (opcional)
 
-### 1. Estilos
+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 `app/globals.css`:
+```js
+// @ts-check
+
+/** @type {import('@ecomiq/storefront').EcomiqConfig} */
+const ecomiqConfig = {
+  slugStore: "mi-tienda",
+};
 
-```css
-@import "tailwindcss";
-@import "@ecomiq/storefront/nextjs/css";
+module.exports = ecomiqConfig;
 ```
 
-### 2. Proxy de la API de tienda
+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).
 
-Crea la ruta que reenvía las peticiones al backend de Ecomiq:
+Cuándo usarlo lo decides tú: en local, staging o producción. Plantilla: [ecomiq.config.example.cjs](./ecomiq.config.example.cjs).
+
+## Arquitectura
+
+```
+Navegador → /api/store/* (proxy en tu Next.js) → API Ecomiq
+              ↑ X-Store-Id (tras getPublicStore)
+```
+
+El browser no llama al upstream directo; montas el proxy con `toNextJsStoreApiHandler`.
+
+## Inicio rápido
+
+### 1. Proxy BFF
 
 ```ts
 // app/api/store/[...path]/route.ts
@@ -54,124 +69,214 @@ export const { GET, POST, PUT, PATCH, DELETE } = toNextJsStoreApiHandler({
 });
 ```
 
-### 3. Layout y provider
+### 2. Layout y tienda
 
 ```tsx
-// app/(shop)/layout.tsx
-import { EcomiqProvider, getPublicStore, ThemeComponentLoader } from "@ecomiq/storefront/nextjs";
-
-export default async function ShopLayout({ children }: { children: React.ReactNode }) {
-  const { data } = await getPublicStore();
+// app/layout.tsx (Server Component)
+import { getPublicStore, EcomiqProvider } from "@ecomiq/storefront/nextjs";
 
+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 (
-    <EcomiqProvider store={data} authClient={yourAuthClient}>
-      <ThemeComponentLoader themeName="default" componentName="header" props={{ /* logo, etc. */ }} />
+    <EcomiqProvider store={store}>
       {children}
-      <ThemeComponentLoader themeName="default" componentName="footer" props={{ /* … */ }} />
     </EcomiqProvider>
   );
 }
 ```
 
-### 4. Rutas de la tienda
+`EcomiqProvider` hidrata el estado de la tienda (`useStore`, `setClientStoreId`) y React Query. La autenticación es opcional (pasos 5 y 6).
 
-Usa el enrutador incluido para catálogo, producto, carrito, checkout y cuenta:
+### 3. Catálogo con hooks
 
 ```tsx
-// app/(shop)/[[...route]]/page.tsx
-import {
-  ShellRouter,
-  generateMetadata as generateStoreMetadata,
-} from "@ecomiq/storefront/nextjs";
+"use client";
 
-export default function StorePage(props: {
-  params: Promise<{ route?: string[] }>;
-  searchParams: Record<string, string | string[] | undefined>;
-}) {
-  return <ShellRouter {...props} getServerSession={yourGetSession} />;
+import { useStoreProducts } from "@ecomiq/storefront/nextjs";
+
+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>
+  );
 }
+```
+
+### 4. Datos en Server Components
+
+```tsx
+import { getStorefrontProducts } from "@ecomiq/storefront/nextjs";
 
-export function generateMetadata(props: { params: Promise<{ route?: string[] }> }) {
-  return generateStoreMetadata({ params: props.params });
+export default async function CatalogPage() {
+  const { products } = await getStorefrontProducts({ page: 1, pageSize: 24 });
+  return <YourGrid products={products} />;
 }
 ```
 
-Con esto tienes una tienda funcional: home, listados, ficha de producto, carrito, checkout y área de cliente.
+### 5. Autenticación (Better Auth + SDK)
 
-## Puntos de entrada
+Instala [Better Auth](https://www.better-auth.com/) y los plugins del SDK (OAuth password grant con credenciales Ecomiq).
 
-Elige el subpath según lo que necesites en tu proyecto:
+**Servidor:**
 
-| Import | Cuándo usarlo |
-|--------|----------------|
-| `@ecomiq/storefront/nextjs` | App Next.js completa: layout, router, provider, páginas exportables, temas |
-| `@ecomiq/storefront/nextjs/api` | Solo el handler del proxy `/api/store/*` |
-| `@ecomiq/storefront/nextjs/css` | Estilos base del shell |
-| `@ecomiq/storefront/react` | Componentes, hooks, tipos y utilidades para UI personalizada |
-| `@ecomiq/storefront/client` | Llamadas a la API de tienda (catálogo, carrito, pedidos, cliente) sin componentes |
-| `@ecomiq/storefront/core` | Tipos y schemas Zod (módulos sin React) |
+```ts
+// lib/auth.ts
+import { betterAuth } from "better-auth";
+import { ecomiqOAuthPassword } from "@ecomiq/storefront/react";
 
-En la mayoría de storefronts nuevos basta con **`/nextjs`** para el armazón y **`/react`** cuando añadas pantallas o bloques propios.
+export const auth = betterAuth({
+  plugins: [ecomiqOAuthPassword()],
+});
+```
 
-## Variables de entorno
+**Ruta API:**
 
-| Variable | Descripción |
-|----------|-------------|
-| `STOREFRONT_API_URL` | URL base de la API de tienda Ecomiq (usada en el proxy) |
+```ts
+// app/api/auth/[...all]/route.ts
+import { toNextJsHandler } from "better-auth/next-js";
+import { auth } from "@/lib/auth";
 
-Configura también en tu app el identificador de tienda y auth según tu despliegue (subdominio, `X-Store-Id`, Better Auth, etc.).
+export const { GET, POST } = toNextJsHandler(auth);
+```
 
-## Personalización
+**Cliente:**
 
-### Temas
+```ts
+// lib/auth-client.ts
+"use client";
+
+import { createAuthClient } from "better-auth/react";
+import { ecomiqOAuthPasswordClient } from "@ecomiq/storefront/react";
+
+export const authClient = createAuthClient({
+  plugins: [ecomiqOAuthPasswordClient()],
+});
+```
 
-Los bloques visuales (header, footer, tarjeta de producto, etc.) se cargan por nombre de tema:
+**Layout** — añade `authClient` al provider del paso 2:
 
 ```tsx
-import { ThemeComponentLoader } from "@ecomiq/storefront/nextjs";
+import { authClient } from "@/lib/auth-client";
 
-<ThemeComponentLoader
-  themeName="default"
-  componentName="productCard"
-  props={{ product }}
-/>
+<EcomiqProvider store={store} authClient={authClient}>
+  {children}
+</EcomiqProvider>
 ```
 
-Puedes registrar un tema propio y referenciarlo con `themeName`.
+### 6. Login, registro y logout
 
-### UI y datos en componentes propios
+Con el paso 5 configurado:
 
 ```tsx
-import { useProducts, ProductsSection, type StorefrontProduct } from "@ecomiq/storefront/react";
-```
+"use client";
 
-```ts
-import { setClientStoreId, getStorefrontProducts } from "@ecomiq/storefront/client";
+import {
+  useStore,
+  useStorefrontAuthClient,
+  useStorefrontSession,
+} from "@ecomiq/storefront/react";
+import {
+  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>
+    );
+  }
 
-setClientStoreId("tu-store-id");
-const page = await getStorefrontProducts({ page: 1, pageSize: 24 });
+  return (
+    <div>
+      {/* Tu UI: formularios que llaman handleLogin / handleRegister */}
+    </div>
+  );
+}
 ```
 
-### Páginas preconstruidas
+- **Login:** `signInWithEcomiqCredentials` (headers de tienda los resuelve el SDK).
+- **Registro:** `registerCustomer`, luego login con las mismas credenciales.
+- **Logout:** `signOut()` de `useStorefrontSession`.
+
+## 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/*` |
+
+El cliente BFF se importa desde **`/nextjs`** (no hay subpath `./client` en npm).
+
+## 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) |
 
-Importa páginas listas desde `@ecomiq/storefront/nextjs/export-pages/*` si prefieres componer rutas manualmente en lugar de `ShellRouter`.
+Tras `getPublicStore`, el SDK configura el contexto de tienda en el servidor para las llamadas al proxy.
 
-## Ejemplo de dependencias
+**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
 
 ```json
 {
   "dependencies": {
     "@ecomiq/storefront": "^0.1.0",
+    "@tanstack/react-query": "^5.66.0",
+    "better-auth": "^1.6.0",
     "next": "^15.3.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "tailwindcss": "^4.0.0"
+    "react-dom": "^19.0.0"
   }
 }
 ```
 
 ## Soporte
 
-Documentación de la plataforma y credenciales de API: [ecomiq.pe](https://ecomiq.pe) (o el portal que use tu organización).
-
-Para incidencias del SDK, abre un issue en el repositorio del paquete o contacta al equipo Ecomiq.
+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 };