@onlistify/storefront 0.1.0 → 0.1.1

package/README.md

@@ -1,41 +1,132 @@
 # ONlistify Storefront
 
-App y SDK para mostrar el storefront de un tenant (tema, bloques, listado de propiedades).
+SDK para integrar el listado y la ficha de propiedades de una inmobiliaria en cualquier web. Una sola llamada monta tema, filtros, paginación y bloques configurados.
 
-## SDK
+## Instalación
 
-Build de la librería: `pnpm run build:sdk`. Salida en `dist/` (ESM, CJS y `.d.ts`).
+```bash
+npm install @onlistify/storefront
+```
+
+El paquete incluye el **SDK** (navegador) y la **CLI**. Desde cualquier carpeta donde tengas un `.onlistify`:
+
+```bash
+npm install @onlistify/storefront
+npx onlistify pull --output-dir ./mi-sitio --env draft
+npx onlistify push
+npx onlistify promote
+npx onlistify preview --env draft
+npx onlistify dev
+```
+
+Sin instalar (npx descarga y ejecuta): `npx @onlistify/storefront pull --output-dir ./mi-sitio --env draft`
+
+Ejemplo mínimo de `.onlistify`: solo `apiUrl` y `apiKey`. El webhook se llama a `apiUrl/webhook`. Opcional: `storefrontUrl`, `tenantSlug` (para preview).
+
+## Integración (cualquier URL)
 
-### Uso rápido
+Indica el **slug** del tenant y la **base** de la API. La ruta de tu página puede ser la que quieras (`/`, `/propiedades`, dominio propio, etc.):
 
 ```ts
-import { bootSiteRuntime } from 'onlistify-storefront';
+import { bootSiteRuntime } from '@onlistify/storefront';
 
 const app = document.getElementById('app');
 if (app) {
-  await bootSiteRuntime(app);
+  await bootSiteRuntime(app, {
+    slug: 'mi-inmobiliaria',
+    baseUrl: 'https://api.onlistify.com',
+  });
 }
 ```
 
-La URL debe ser `/tienda/:slug` (ej. `/tienda/mi-inmobiliaria`). El SDK obtiene el slug del pathname.
+Con bundler (Vite, Webpack, etc.) o como módulo en el navegador. No hace falta usar una ruta tipo `/tienda/:slug`.
+
+## Opciones
+
+| Opción        | Descripción |
+|---------------|-------------|
+| `slug`        | Slug del tenant (recomendado). Sin esto, se puede usar `getSlugFromPath`. |
+| `baseUrl`     | Base de la API (ej. `https://api.onlistify.com`). |
+| `environment` | `'draft'` \| `'live'`. Por defecto `'live'` o `?environment=draft` en la URL. |
+| `getSlugFromPath` | Función `(pathname) => string` para obtener el slug desde la ruta. Se ignora si se pasa `slug`. |
+| `onError`     | Callback cuando falle la carga de configuración o el runtime. |
+
+## App de desarrollo
+
+En este repo, la app Vite usa variables de entorno para no depender de la ruta:
+
+- `VITE_PUBLIC_STOREFRONT_SLUG` — slug del tenant (ej. `richistate`).
+- `VITE_PUBLIC_API_URL` — base de la API.
+
+Crea `.env` con esos valores y arranca con `pnpm dev`. La app funciona en la raíz (ej. `http://localhost:5174/`).
+
+## Conectar a ONlistify para enviar cambios
+
+El **storefront solo lee** (config, propiedades, plugins). Para **enviar cambios** (editar tema, bloques, publicar) tienes dos opciones:
+
+**1. Dashboard (recomendado)**  
+- En el repo `onlistify-front` crea o edita `.env` con la URL de tu backend:
+  ```bash
+  NEXT_PUBLIC_API_URL=https://tu-backend.onlistify.com
+  ```
+  (En local: `http://localhost:8888` si el backend corre ahí.)
+- Arranca el dashboard (`pnpm dev`), inicia sesión y entra en **Configuración del sitio** o **API pública**. Los cambios se envían al backend desde la UI.
+
+**2. API con clave**  
+- En el dashboard ve a **API pública** y crea una API key del tenant.  
+- Desde scripts o integraciones:
+  ```bash
+  export ONLISTIFY_API_URL=https://tu-backend.onlistify.com
+  export ONLISTIFY_API_KEY=onl_tu_clave
+  ```
+  - `GET` config: `curl -H "X-API-Key: $ONLISTIFY_API_KEY" "$ONLISTIFY_API_URL/api/v1/public/site-config?environment=draft"`
+  - `PUT` para guardar borrador: body JSON con la config completa.
+  - `POST .../site-config/promote` para publicar borrador a vivo.
+
+El **storefront** solo necesita `baseUrl` (la misma URL del backend) y `slug` del tenant para mostrar datos; no envía cambios.
+
+## Build del SDK
+
+```bash
+pnpm run build:sdk
+```
+
+Salida en `dist/`: entrada principal (browser), entrada `node` (Node) y carpeta `dist/plugins/` con los plugins por defecto (hero, header).
+
+## SDK Node (descargar web, push, webhook)
+
+Para scripts o la CLI (descargar la web como código, subir cambios, disparar un webhook):
+
+```ts
+import {
+  pullSiteConfig,
+  pushSiteConfig,
+  promoteSiteConfig,
+  exportSiteProject,
+  triggerWebhook,
+  getDefaultPluginsDir,
+} from '@onlistify/storefront/node';
+```
 
-### Configuración
+- `pullSiteConfig({ apiUrl, apiKey }, 'draft' | 'live')` — devuelve la config normalizada.
+- `pushSiteConfig({ apiUrl, apiKey }, config)` — guarda borrador.
+- `promoteSiteConfig({ apiUrl, apiKey })` — publica a live.
+- `exportSiteProject({ apiUrl, apiKey }, { outputDir, environment?, includePlugins? })` — escribe en `outputDir` el `site-config.draft.json` y, si `includePlugins` es true, copia los plugins por defecto del SDK a `outputDir/plugins/`. Así los devs obtienen la config y el código físico de los bloques para editarlos.
+- `triggerWebhook(url, payload?)` — POST a la URL (útil tras push/promote para desplegar).
+- `getDefaultPluginsDir()` — ruta a `dist/plugins` del paquete.
 
-- **API base:** variable de entorno `VITE_PUBLIC_API_URL` o `bootSiteRuntime(app, { baseUrl: 'https://api.ejemplo.com' })`. También `setApiBase(url)` antes de cualquier `fetch*`.
-- **Entorno:** `bootSiteRuntime(app, { environment: 'draft' | 'live' })`. Por defecto usa `?environment=draft` en la URL o `live`.
-- **Slug custom:** `bootSiteRuntime(app, { getSlugFromPath: (pathname) => 'mi-tenant' })`.
-- **Errores:** `bootSiteRuntime(app, { onError: (err) => console.error(err) })`.
+La CLI incluida en el paquete (`npx onlistify`) usa este entry: `pull --output-dir ./mi-sitio` exporta el sitio completo; `push` / `promote` envían cambios y, si está definido `webhookUrl` en `.onlistify`, se llama al terminar.
 
-### API pública
+## API pública (browser)
 
-- `bootSiteRuntime(app, options?)` — monta la UI en el elemento.
+- `bootSiteRuntime(app, options?)` — monta el storefront en el elemento.
 - `fetchSiteConfig(slug, environment?)` — configuración del sitio.
 - `fetchProperties(slug, params?)` — listado de propiedades.
 - `fetchPlugins(slug)` — plugins/bloques.
 - `setApiBase(url)` — define la base de la API.
 - Tipos: `SiteConfig`, `BlockDef`, `PageDef`, `PublicPropertySummary`, `ListPropertiesParams`, `BootSiteRuntimeOptions`, `StorefrontConfigError`, `StorefrontNetworkError`, etc.
 
-### Errores
+## Errores
 
-- `StorefrontConfigError`: fallo HTTP de configuración o propiedades (`status` opcional).
-- `StorefrontNetworkError`: fallo de red (`cause` con el error original).
+- `StorefrontConfigError`: error HTTP de config o propiedades (`status` opcional).
+- `StorefrontNetworkError`: error de red (`cause` con el error original).

package/dist/cli.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function loadSdk() {
+  try {
+    return await import(path.join(__dirname, 'node.js'));
+  } catch {
+    return null;
+  }
+}
+
+function loadConfig() {
+  const cwd = process.cwd();
+  let apiUrl = process.env.ONLISTIFY_API_URL;
+  let apiKey = process.env.ONLISTIFY_API_KEY;
+  let tenantSlug = process.env.ONLISTIFY_TENANT_SLUG;
+  let storefrontUrl = process.env.ONLISTIFY_STOREFRONT_URL;
+  const configPath = path.join(cwd, '.onlistify');
+  if (fs.existsSync(configPath)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      apiUrl = apiUrl ?? data.apiUrl ?? data.ONLISTIFY_API_URL;
+      apiKey = apiKey ?? data.apiKey ?? data.ONLISTIFY_API_KEY;
+      tenantSlug = tenantSlug ?? data.tenantSlug ?? data.ONLISTIFY_TENANT_SLUG;
+      storefrontUrl = storefrontUrl ?? data.storefrontUrl ?? data.ONLISTIFY_STOREFRONT_URL;
+    } catch (_) {}
+  }
+  apiUrl = (apiUrl || 'http://localhost:8888').replace(/\/$/, '');
+  storefrontUrl = (storefrontUrl || 'http://localhost:5174').replace(/\/$/, '');
+  const webhookUrl = `${apiUrl}/webhook`;
+  return { apiUrl, apiKey, tenantSlug, storefrontUrl, webhookUrl };
+}
+
+function usage() {
+  console.log(`onlistify (@onlistify/storefront)
+  pull [--env draft|live] [--output FILE]        Descarga config a archivo
+  pull --output-dir DIR [--env draft]            Descarga sitio completo (config + plugins)
+  push [FILE]                                    Sube site-config.draft.json como borrador
+  promote                                        Publica borrador a live
+  preview [--env draft|live]                     Abre storefront en el navegador
+  dev [--config FILE]                            Watch y push al guardar
+
+  Config: .onlistify con apiUrl y apiKey (opcional: storefrontUrl, tenantSlug para preview). Webhook = apiUrl/webhook.
+`);
+}
+
+async function api(apiUrl, apiKey, method, pathname, body = null) {
+  const url = `${apiUrl}/api/v1/public${pathname}`;
+  const opts = { method, headers: { 'X-API-Key': apiKey } };
+  if (body) {
+    opts.headers['Content-Type'] = 'application/json';
+    opts.body = typeof body === 'string' ? body : JSON.stringify(body);
+  }
+  const res = await fetch(url, opts);
+  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
+  return res.json();
+}
+
+function parseArgs(args) {
+  const out = { env: 'draft', output: null, outputDir: null, file: null, config: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--env' && args[i + 1]) out.env = args[++i];
+    else if (args[i] === '--output' && args[i + 1]) out.output = args[++i];
+    else if (args[i] === '--output-dir' && args[i + 1]) out.outputDir = args[++i];
+    else if (args[i] === '--config' && args[i + 1]) out.config = args[++i];
+    else if (!args[i].startsWith('-')) { out.file = args[i]; break; }
+  }
+  return out;
+}
+
+async function cmdPull(config, args) {
+  const { apiUrl, apiKey } = config;
+  if (!apiKey) {
+    console.error('Falta ONLISTIFY_API_KEY o apiKey en .onlistify');
+    process.exit(1);
+  }
+  const { env, output, outputDir } = parseArgs(args);
+  const envParam = env === 'live' ? 'live' : 'draft';
+  const sdk = await loadSdk();
+
+  if (outputDir && sdk?.exportSiteProject) {
+    const { configPath, pluginsPath } = await sdk.exportSiteProject(
+      { apiUrl, apiKey },
+      { outputDir, environment: envParam, includePlugins: true }
+    );
+    console.log('Sitio exportado:', configPath, pluginsPath ? `plugins: ${pluginsPath}` : '');
+    return;
+  }
+
+  if (sdk?.pullSiteConfig) {
+    const siteConfig = await sdk.pullSiteConfig({ apiUrl, apiKey }, envParam);
+    const outPath = path.resolve(process.cwd(), output || (envParam === 'live' ? 'site-config.live.json' : 'site-config.draft.json'));
+    fs.writeFileSync(outPath, JSON.stringify(siteConfig, null, 2), 'utf8');
+    console.log('Config guardada en', outPath);
+    return;
+  }
+
+  const data = await api(apiUrl, apiKey, 'GET', `/site-config?environment=${envParam}`);
+  const json = JSON.stringify(data?.data ?? data ?? { pages: [] }, null, 2);
+  const outPath = path.resolve(process.cwd(), output || (envParam === 'live' ? 'site-config.live.json' : 'site-config.draft.json'));
+  fs.writeFileSync(outPath, json, 'utf8');
+  console.log('Config guardada en', outPath);
+}
+
+async function cmdPush(config, args) {
+  const { apiUrl, apiKey, webhookUrl } = config;
+  if (!apiKey) {
+    console.error('Falta ONLISTIFY_API_KEY o apiKey en .onlistify');
+    process.exit(1);
+  }
+  const { file } = parseArgs(args);
+  const configPath = path.resolve(process.cwd(), file || 'site-config.draft.json');
+  let body;
+  try {
+    body = fs.readFileSync(configPath, 'utf8');
+    JSON.parse(body);
+  } catch (e) {
+    if (e.code === 'ENOENT') console.error('Archivo no encontrado:', configPath);
+    else console.error('JSON inválido:', e.message);
+    process.exit(1);
+  }
+
+  const sdk = await loadSdk();
+  if (sdk?.pushSiteConfig) {
+    await sdk.pushSiteConfig({ apiUrl, apiKey }, JSON.parse(body));
+  } else {
+    await api(apiUrl, apiKey, 'PUT', '/site-config?environment=draft', body);
+  }
+  console.log('Borrador guardado');
+  if (webhookUrl && sdk?.triggerWebhook) {
+    try {
+      await sdk.triggerWebhook(webhookUrl, { event: 'onlistify.push' });
+      console.log('Webhook llamado');
+    } catch (e) {
+      console.warn('Webhook:', e.message);
+    }
+  }
+}
+
+async function cmdPromote(config) {
+  const { apiUrl, apiKey, webhookUrl } = config;
+  if (!apiKey) {
+    console.error('Falta ONLISTIFY_API_KEY o apiKey en .onlistify');
+    process.exit(1);
+  }
+  const sdk = await loadSdk();
+  if (sdk?.promoteSiteConfig) {
+    await sdk.promoteSiteConfig({ apiUrl, apiKey });
+  } else {
+    await api(apiUrl, apiKey, 'POST', '/site-config/promote');
+  }
+  console.log('Config publicada en vivo');
+  if (webhookUrl && sdk?.triggerWebhook) {
+    try {
+      await sdk.triggerWebhook(webhookUrl, { event: 'onlistify.promote' });
+      console.log('Webhook llamado');
+    } catch (e) {
+      console.warn('Webhook:', e.message);
+    }
+  }
+}
+
+function cmdPreview(config, args) {
+  const { storefrontUrl, tenantSlug } = config;
+  const { env } = parseArgs(args);
+  const slug = tenantSlug || 'mi-inmobiliaria';
+  const envParam = env === 'live' ? '' : '?environment=draft';
+  const url = `${storefrontUrl}/tienda/${encodeURIComponent(slug)}${envParam}`;
+  const start = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  spawn(start, [url], { stdio: 'ignore', detached: true });
+  console.log('Abriendo', url);
+}
+
+async function cmdDev(config, args) {
+  const { apiUrl, apiKey, webhookUrl } = config;
+  if (!apiKey) {
+    console.error('Falta ONLISTIFY_API_KEY o apiKey en .onlistify');
+    process.exit(1);
+  }
+  const { config: configFile } = parseArgs(args);
+  const configPath = path.resolve(process.cwd(), configFile || 'site-config.draft.json');
+  if (!fs.existsSync(configPath)) {
+    console.error('Archivo no encontrado:', configPath);
+    process.exit(1);
+  }
+  const sdk = await loadSdk();
+  const push = async () => {
+    try {
+      const body = fs.readFileSync(configPath, 'utf8');
+      const parsed = JSON.parse(body);
+      if (sdk?.pushSiteConfig) await sdk.pushSiteConfig({ apiUrl, apiKey }, parsed);
+      else await api(apiUrl, apiKey, 'PUT', '/site-config?environment=draft', body);
+      console.log('[%s] Borrador actualizado', new Date().toISOString());
+      if (webhookUrl && sdk?.triggerWebhook) {
+        try { await sdk.triggerWebhook(webhookUrl, { event: 'onlistify.push' }); } catch (_) {}
+      }
+    } catch (e) {
+      console.error('Error:', e.message);
+    }
+  };
+  fs.watch(configPath, (eventType) => {
+    if (eventType === 'change') push();
+  });
+  console.log('Observando', configPath, '- Recarga la pestaña de preview al cambiar.');
+  await push();
+}
+
+const commands = { pull: cmdPull, push: cmdPush, promote: cmdPromote, preview: cmdPreview, dev: cmdDev };
+const cmd = process.argv[2];
+const cmdArgs = process.argv.slice(3);
+
+if (!cmd || cmd === '-h' || cmd === '--help') {
+  usage();
+  process.exit(0);
+}
+
+const fn = commands[cmd];
+if (!fn) {
+  console.error('Comando desconocido:', cmd);
+  usage();
+  process.exit(1);
+}
+
+const config = loadConfig();
+Promise.resolve(fn(config, cmdArgs)).catch((e) => {
+  console.error(e.message);
+  process.exit(1);
+});

package/dist/index-CxOAQ9Nx.d.cts

@@ -0,0 +1,53 @@
+type SiteEnvironment = 'draft' | 'live';
+interface SiteConfigTheme {
+    primaryColor?: string;
+    accentColor?: string;
+    logoUrl?: string;
+    customCssVars?: Record<string, string>;
+}
+interface PropiedadCardBlockProps {
+    theme?: {
+        primaryColor?: string;
+        accentColor?: string;
+        badgeBackground?: string;
+        cardBorderRadius?: string;
+        imageAspectRatio?: '16/9' | '4/3' | '1/1';
+    };
+    showFields?: Record<string, boolean>;
+    badges?: {
+        featured?: {
+            enabled: boolean;
+            label?: string;
+        };
+        virtualTour?: {
+            enabled: boolean;
+            label?: string;
+        };
+        custom?: Array<{
+            key: string;
+            label: string;
+            when?: string;
+        }>;
+    };
+    layout?: 'compact' | 'default' | 'minimal';
+    linkTarget?: '_self' | '_blank';
+    openDetailIn?: 'same' | 'modal' | 'drawer';
+}
+interface BlockDef<TProps = Record<string, unknown>> {
+    id: string;
+    type: string;
+    props?: TProps;
+}
+interface PageDef {
+    id: string;
+    path: string;
+    blocks: BlockDef[];
+}
+interface SiteConfig {
+    version?: number;
+    theme?: SiteConfigTheme;
+    themeOverrides?: Record<string, unknown>;
+    pages?: PageDef[];
+}
+
+export type { BlockDef as B, PageDef as P, SiteEnvironment as S, SiteConfig as a, PropiedadCardBlockProps as b, SiteConfigTheme as c };

package/dist/index-CxOAQ9Nx.d.ts

@@ -0,0 +1,53 @@
+type SiteEnvironment = 'draft' | 'live';
+interface SiteConfigTheme {
+    primaryColor?: string;
+    accentColor?: string;
+    logoUrl?: string;
+    customCssVars?: Record<string, string>;
+}
+interface PropiedadCardBlockProps {
+    theme?: {
+        primaryColor?: string;
+        accentColor?: string;
+        badgeBackground?: string;
+        cardBorderRadius?: string;
+        imageAspectRatio?: '16/9' | '4/3' | '1/1';
+    };
+    showFields?: Record<string, boolean>;
+    badges?: {
+        featured?: {
+            enabled: boolean;
+            label?: string;
+        };
+        virtualTour?: {
+            enabled: boolean;
+            label?: string;
+        };
+        custom?: Array<{
+            key: string;
+            label: string;
+            when?: string;
+        }>;
+    };
+    layout?: 'compact' | 'default' | 'minimal';
+    linkTarget?: '_self' | '_blank';
+    openDetailIn?: 'same' | 'modal' | 'drawer';
+}
+interface BlockDef<TProps = Record<string, unknown>> {
+    id: string;
+    type: string;
+    props?: TProps;
+}
+interface PageDef {
+    id: string;
+    path: string;
+    blocks: BlockDef[];
+}
+interface SiteConfig {
+    version?: number;
+    theme?: SiteConfigTheme;
+    themeOverrides?: Record<string, unknown>;
+    pages?: PageDef[];
+}
+
+export type { BlockDef as B, PageDef as P, SiteEnvironment as S, SiteConfig as a, PropiedadCardBlockProps as b, SiteConfigTheme as c };

package/dist/index.cjs

@@ -526,7 +526,8 @@ PropiedadCard = __decorateClass([
 
 // src/sdk/site-runtime.ts
 var BUILTIN_PLUGIN_URLS = {
-  "onl-hero": { js: "/plugins/example/hero-plugin.js", css: "/plugins/example/hero-plugin.css" }
+  "onl-hero": { js: "/plugins/example/hero-plugin.js", css: "/plugins/example/hero-plugin.css" },
+  "onl-header": { js: "/plugins/example/header-plugin.js", css: "/plugins/example/header-plugin.css" }
 };
 var loadedPlugins = /* @__PURE__ */ new Set();
 function getSlugFromPath(pathname) {
@@ -700,10 +701,9 @@ async function bootSiteRuntime(app, options = {}) {
   } else {
     setApiBase(getApiBase());
   }
-  const getSlug = options.getSlugFromPath ?? getSlugFromPath;
-  const slug = getSlug(typeof window !== "undefined" ? window.location.pathname : "");
+  const slug = options.slug?.trim() || (options.getSlugFromPath ?? getSlugFromPath)(typeof window !== "undefined" ? window.location.pathname : "");
   if (!slug) {
-    app.innerHTML = "<p>URL debe ser /tienda/:slug (ej. /tienda/mi-inmobiliaria)</p>";
+    app.innerHTML = "<p>Indica el tenant con <code>slug</code> en opciones (recomendado) o con <code>getSlugFromPath</code>. Ej: bootSiteRuntime(app, { slug: 'mi-inmobiliaria', baseUrl: 'https://api.ejemplo.com' })</p>";
     return;
   }
   app.innerHTML = "<p>Cargando...</p>";