Visión General del App Bridge

La capa de comunicación entre el iframe de tu plugin y el admin de Whatalo — construida sobre postMessage con validación estricta de origen.

El App Bridge es la biblioteca JavaScript que conecta tu plugin (ejecutándose dentro de un iframe) con el shell de administración de Whatalo. Proporciona una API tipada y basada en promesas para leer el contexto de la tienda, disparar acciones de UI y mantenerse sincronizado con el estado del admin — todo sin acceso directo al DOM a través del límite del iframe.

Internamente usa la API postMessage del navegador con validación estricta de origen en ambos lados.

Instalación

@whatalo/plugin-sdk ya está incluido cuando creas el proyecto con whatalo init. Para proyectos existentes:

pnpm add @whatalo/plugin-sdk

Inicio Rápido

import { useAppBridge } from "@whatalo/plugin-sdk/bridge";

function MyPlugin() {
  const bridge = useAppBridge();

  // Wait for the handshake to complete before rendering
  if (!bridge.isReady) return <div>Cargando...</div>;

  return (
    <div>
      <h1>Hola, {bridge.storeName}!</h1>
      <p>
        {bridge.user.email} — {bridge.user.role}
      </p>
      <button
        onClick={() =>
          bridge.toast.show("Funciona!", { variant: "success" })
        }
      >
        Probar Toast
      </button>
    </div>
  );
}

Hooks Disponibles

Hook	Caso de uso
`useAppBridge()`	Recomendado. Acceso todo en uno a contexto, acciones y facturación.
`useWhataloContext()`	Solo datos de contexto (tienda, usuario, tema, página actual).
`useWhataloAction()`	Solo acciones (toast, navegar, modal, resize, facturación).

Usa useAppBridge() a menos que tengas una razón específica para separar el contexto de las acciones.

Para identidad de usuario en la UI del plugin, prefiere bridge.user.email y bridge.user.role. Trata bridge.user.name solo como una etiqueta visual.

Protocolo de Mensajes

El bridge usa cuatro tipos de mensajes mediante postMessage:

Tipo	Dirección	Propósito
`whatalo:init`	Host → Plugin	Envía el origen del padre para comunicación segura
`whatalo:context`	Host → Plugin	Envía datos de tienda, usuario, tema y página actual
`whatalo:action`	Plugin → Host	El plugin solicita una acción (toast, navegar, modal, etc.)
`whatalo:ack`	Host → Plugin	El host confirma éxito o error de la acción

Secuencia de Handshake

Admin carga el iframe → tu appUrl se renderiza
         │
         ▼
Host envía whatalo:init  (contiene parentOrigin)
         │
         ▼
Plugin guarda parentOrigin, envía acción "ready"
         │
         ▼
Host responde con whatalo:context  (payload de contexto completo)
         │
         ▼
Plugin establece isReady = true  →  tu UI se renderiza

Hasta que isReady sea true, todas las acciones salientes se encolan y se envían una vez que el handshake se completa.

Modelo de Seguridad

Fijación de origen — El plugin envía cada acción exclusivamente al parentOrigin recibido durante whatalo:init. Nunca envía a "*".
Validación del host — El admin valida el origen de cada mensaje entrante contra el appUrl registrado del plugin. Los mensajes de otros orígenes se descartan silenciosamente.
Bloqueo de mismo origen — Las URLs de plugin que comparten origen con el admin son rechazadas.
Timeout de acción — Todas las acciones tienen un timeout de 5 segundos. Si no se recibe ningún whatalo:ack, la promesa devuelta resuelve con { success: false, error: "timeout" }.

Límites de Tasa

Los límites de tasa se aplican por tipo de acción usando una ventana deslizante de 10 segundos:

Acción	Máximo por 10 segundos
`toast`	3
`navigate`	5
`modal`	3
`resize`	30
`billing`	10

Las solicitudes que exceden el límite se rechazan con { success: false, error: "rate_limited" }.