@ecomiq/storefront 0.1.0

package/README.md

@@ -0,0 +1,177 @@
+# @ecomiq/storefront
+
+SDK oficial para construir tiendas online con **Next.js** y **React** sobre la plataforma 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.
+
+## Requisitos
+
+- Node.js 20+
+- Next.js 15+ (App Router)
+- React 19+
+- Tailwind CSS 4+
+
+## Instalación
+
+```bash
+npm install @ecomiq/storefront
+# o
+pnpm add @ecomiq/storefront
+```
+
+En `next.config.js` (o `.mjs`), transpila el SDK:
+
+```js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ["@ecomiq/storefront"],
+};
+
+export default nextConfig;
+```
+
+## Inicio rápido
+
+### 1. Estilos
+
+En `app/globals.css`:
+
+```css
+@import "tailwindcss";
+@import "@ecomiq/storefront/nextjs/css";
+```
+
+### 2. Proxy de la API de tienda
+
+Crea la ruta que reenvía las peticiones al backend de Ecomiq:
+
+```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!,
+});
+```
+
+### 3. Layout y provider
+
+```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();
+
+  return (
+    <EcomiqProvider store={data} authClient={yourAuthClient}>
+      <ThemeComponentLoader themeName="default" componentName="header" props={{ /* logo, etc. */ }} />
+      {children}
+      <ThemeComponentLoader themeName="default" componentName="footer" props={{ /* … */ }} />
+    </EcomiqProvider>
+  );
+}
+```
+
+### 4. Rutas de la tienda
+
+Usa el enrutador incluido para catálogo, producto, carrito, checkout y cuenta:
+
+```tsx
+// app/(shop)/[[...route]]/page.tsx
+import {
+  ShellRouter,
+  generateMetadata as generateStoreMetadata,
+} from "@ecomiq/storefront/nextjs";
+
+export default function StorePage(props: {
+  params: Promise<{ route?: string[] }>;
+  searchParams: Record<string, string | string[] | undefined>;
+}) {
+  return <ShellRouter {...props} getServerSession={yourGetSession} />;
+}
+
+export function generateMetadata(props: { params: Promise<{ route?: string[] }> }) {
+  return generateStoreMetadata({ params: props.params });
+}
+```
+
+Con esto tienes una tienda funcional: home, listados, ficha de producto, carrito, checkout y área de cliente.
+
+## Puntos de entrada
+
+Elige el subpath según lo que necesites en tu proyecto:
+
+| 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) |
+
+En la mayoría de storefronts nuevos basta con **`/nextjs`** para el armazón y **`/react`** cuando añadas pantallas o bloques propios.
+
+## Variables de entorno
+
+| Variable | Descripción |
+|----------|-------------|
+| `STOREFRONT_API_URL` | URL base de la API de tienda Ecomiq (usada en el proxy) |
+
+Configura también en tu app el identificador de tienda y auth según tu despliegue (subdominio, `X-Store-Id`, Better Auth, etc.).
+
+## Personalización
+
+### Temas
+
+Los bloques visuales (header, footer, tarjeta de producto, etc.) se cargan por nombre de tema:
+
+```tsx
+import { ThemeComponentLoader } from "@ecomiq/storefront/nextjs";
+
+<ThemeComponentLoader
+  themeName="default"
+  componentName="productCard"
+  props={{ product }}
+/>
+```
+
+Puedes registrar un tema propio y referenciarlo con `themeName`.
+
+### UI y datos en componentes propios
+
+```tsx
+import { useProducts, ProductsSection, type StorefrontProduct } from "@ecomiq/storefront/react";
+```
+
+```ts
+import { setClientStoreId, getStorefrontProducts } from "@ecomiq/storefront/client";
+
+setClientStoreId("tu-store-id");
+const page = await getStorefrontProducts({ page: 1, pageSize: 24 });
+```
+
+### Páginas preconstruidas
+
+Importa páginas listas desde `@ecomiq/storefront/nextjs/export-pages/*` si prefieres componer rutas manualmente en lugar de `ShellRouter`.
+
+## Ejemplo de dependencias
+
+```json
+{
+  "dependencies": {
+    "@ecomiq/storefront": "^0.1.0",
+    "next": "^15.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.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.