Contexto y Sesión

Cuando el handshake del App Bridge se completa, el admin envía un payload whatalo:context que contiene todo lo que tu plugin necesita saber sobre la sesión actual: la tienda donde está instalado, el usuario con sesión activa, el tema de UI activo y qué página se muestra.

WhataloContext es intencionalmente liviano. Ayuda a que tu iframe entienda la sesión actual y el shell del admin, pero no es la fuente de verdad para metadatos de tienda ni recursos de negocio.

Usa estas reglas:

• ¿Necesitas storeId, storeName, locale, theme o la página actual? Usa useAppBridge() / useWhataloContext()
• ¿Necesitas acceso de lectura en el frontend a datos como orders, products o store.timezone? Usa useWhataloData()
• ¿Necesitas lecturas backend, escrituras o lógica confiable del servidor? Usa WhataloClient

Tipo WhataloContext

interface WhataloContext {
  storeId: string;        // Identificador público de la tienda
  storeName: string;      // Nombre visible de la tienda
  locale: string;         // ej., "es", "en"
  theme: "light" | "dark";
  user: WhataloUser;
  appId: string;          // ID de tu plugin según el manifiesto
  currentPage: string;    // Ruta de la página activa — ej., "dashboard", "settings"
  initialHeight: number;  // Altura sugerida del iframe en píxeles
}

interface WhataloUser {
  id: string;
  name: string;
  email: string;
  role: "owner" | "admin" | "editor" | "staff" | "viewer";
}

user.name es solo una etiqueta visual. No lo trates como un nombre de perfil verificado. Para UI sensible a identidad, prefiere user.email y user.role.

Acceder al Contexto

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

function MyComponent() {
  const { storeId, storeName, user, locale, theme, isReady } = useAppBridge();

  if (!isReady) return <Spinner />;

  return (
    <div>
      <p>
        Tienda: {storeName} ({storeId})
      </p>
      <p>
        Usuario: {user.email} — Rol: {user.role}
      </p>
      <p>
        Idioma: {locale} — Tema: {theme}
      </p>
    </div>
  );
}

Valores por Defecto Antes de isReady

El hook devuelve valores seguros mientras el handshake está en progreso. Esto previene errores de null-check en tu lógica de renderizado.

Siempre verifica isReady antes de usar valores de contexto en lógica que depende de ellos (llamadas a API, renderizado condicional basado en user.role, etc.).

Acceso Basado en Rol

Usa user.role para exponer condicionalmente funcionalidades. Los roles son configurados por el dueño de la tienda y no pueden ser modificados por plugins.

const { user } = useAppBridge();

return (
  <div>
    {user.role === "owner" && <ZonaDePeligro />}
    {(user.role === "owner" || user.role === "admin") && <AccionesEnMasa />}
    <VistaDeConsulta />
  </div>
);

currentPage y Plugins Multi-página

currentPage refleja qué página del plugin está viendo actualmente el usuario. Coincide con el campo path que definiste en adminUI.pages dentro del manifiesto. Úsalo para renderizar la vista correcta:

const { currentPage } = useAppBridge();

switch (currentPage) {
  case "settings":
    return <PaginaDeConfiguracion />;
  case "dashboard":
  default:
    return <PaginaDeDashboard />;
}

Consulta Navegación para el patrón de enrutamiento completo.

Actualizaciones de Contexto

El admin envía contexto actualizado automáticamente cuando:

• El usuario navega a una página diferente en tu plugin
• El tema del admin cambia (claro ↔ oscuro)

Tu componente se re-renderiza con los nuevos valores porque useAppBridge() está respaldado por un contexto React que se actualiza en cada mensaje whatalo:context entrante.