npm package: @onlistify/storefront
Description: 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.
Latest version: 0.1.3

# ONlistify Storefront

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.

## Instalación

```bash
npm install @onlistify/storefront
```

El paquete incluye el **SDK** (navegador) y la **CLI**. Desde cualquier carpeta donde tengas un `.onlistify`:

```bash
npx @onlistify/storefront pull --output-dir ./mi-sitio --env draft
npx @onlistify/storefront push
npx @onlistify/storefront promote
npx @onlistify/storefront preview --env draft
npx @onlistify/storefront dev
```

O instala y usa el comando `storefront`: `npm install @onlistify/storefront` y luego `npx storefront pull ...`

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)

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

const app = document.getElementById('app');
if (app) {
  await bootSiteRuntime(app, {
    slug: 'mi-inmobiliaria',
    baseUrl: 'https://api.onlistify.com',
  });
}
```

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';
```

- `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.

La CLI incluida en el paquete (`npx @onlistify/storefront` o `npx storefront`) 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 (browser)

- `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

- `StorefrontConfigError`: error HTTP de config o propiedades (`status` opcional).
- `StorefrontNetworkError`: error de red (`cause` con el error original).