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

npm install @onlistify/storefront

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

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.):

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:

  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:

  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

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):

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