@ecomiq/storefront 0.1.1 → 0.1.2

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** 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 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
 
@@ -28,14 +28,33 @@ const nextConfig = {
 export default nextConfig;
 ```
 
+## `ecomiq.config.js` (opcional)
+
+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`:
+
+```js
+// @ts-check
+
+/** @type {import('@ecomiq/storefront').EcomiqConfig} */
+const ecomiqConfig = {
+  slugStore: "mi-tienda",
+};
+
+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).
+
+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 (cookie / header tras getPublicStore)
+              ↑ 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 `toNextJsStoreApiHandler`.
 
 ## Inicio rápido
 
@@ -50,12 +69,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 +81,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 el estado de la tienda (`useStore`, `setClientStoreId`) y React Query. La autenticación es opcional (pasos 5 y 6).
 
 ### 3. Catálogo con hooks
 
@@ -105,67 +123,146 @@ export default async function CatalogPage() {
 }
 ```
 
-### 5. Estilos (opcional)
+### 5. Autenticación (Better Auth + SDK)
 
-```css
-@import "tailwindcss";
-@import "@ecomiq/storefront/nextjs/css";
-```
+Instala [Better Auth](https://www.better-auth.com/) y los plugins del SDK (OAuth password grant con credenciales Ecomiq).
 
-El CSS publicado es **mínimo**. Tu design system y componentes viven en la app.
+**Servidor:**
 
-## Puntos de entrada (npm)
+```ts
+// lib/auth.ts
+import { betterAuth } from "better-auth";
+import { ecomiqOAuthPassword } from "@ecomiq/storefront/react";
 
-| 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 auth = betterAuth({
+  plugins: [ecomiqOAuthPassword()],
+});
+```
 
-No hay subpath `./client` en npm: las funciones del cliente BFF se importan desde **`/nextjs`**.
+**Ruta API:**
 
-## Auth (Better Auth)
+```ts
+// app/api/auth/[...all]/route.ts
+import { toNextJsHandler } from "better-auth/next-js";
+import { auth } from "@/lib/auth";
 
-Plugins para OAuth password grant de Ecomiq:
+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/react";
+
+export const authClient = createAuthClient({
+  plugins: [ecomiqOAuthPasswordClient()],
+});
+```
+
+**Layout** — añade `authClient` al provider del paso 2:
+
+```tsx
+import { authClient } from "@/lib/auth-client";
+
+<EcomiqProvider store={store} authClient={authClient}>
+  {children}
+</EcomiqProvider>
+```
+
+### 6. Login, registro y logout
+
+Con el paso 5 configurado:
+
+```tsx
+"use client";
+
 import {
-  ecomiqOAuthPassword,
-  ecomiqOAuthPasswordClient,
+  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>
+    );
+  }
+
+  return (
+    <div>
+      {/* Tu UI: formularios que llaman handleLogin / handleRegister */}
+    </div>
+  );
+}
 ```
 
-## Variables de entorno
+- **Login:** `signInWithEcomiqCredentials` (headers de tienda los resuelve el SDK).
+- **Registro:** `registerCustomer`, luego login con las mismas credenciales.
+- **Logout:** `signOut()` de `useStorefrontSession`.
 
-| Variable | Descripción |
-|----------|-------------|
-| `STOREFRONT_API_URL` | URL base de la API de tienda (proxy) |
-| `PUBLIC_STORE_SETTINGS_SOURCE` | `api` (default) o `kv` (OpenNext / Cloudflare) |
+## Puntos de entrada (npm)
 
-Tras `getPublicStore`, el SDK fija `X-Store-Id` en el servidor para las llamadas al proxy.
+| 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é no viene en el paquete npm
+El cliente BFF se importa desde **`/nextjs`** (no hay subpath `./client` en npm).
 
-Pensado para que **tú** construyas la UI:
+## Variables de entorno
 
-- `ShellRouter`, páginas exportadas
-- Checkout, carrito drawer, cuenta, formularios precargados
-- `CmsSectionsRenderer`, `DefaultCmsSectionsRenderer`, `SafeThemeInjector`
-- `ThemeComponentLoader` y temas `default` / `ana` / `sony`
-- Dependencia de `@ecomiq/ui`
+| 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) |
 
-Esa capa completa existe en el **monorepo Ecomiq** (`workspace:*` sobre `src/`), no en el tarball npm.
+Tras `getPublicStore`, el SDK configura el contexto de tienda en el servidor para las llamadas al proxy.
 
-## Desarrollo en el monorepo Ecomiq
+**Identificador de tienda:** `slugStore` en `ecomiq.config.*` si existe; si no, header `Host`.
 
-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`.
+## Publicación del paquete
 
-Para empaquetar o publicar en npm: ver [PUBLISHING.md](./PUBLISHING.md).
+Mantenimiento del tarball npm: [PUBLISHING.md](./PUBLISHING.md).
 
-## Dependencias recomendadas en tu app
+## Dependencias recomendadas
 
 ```json
 {

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 };