Data Bridge

Plugin iframe              Host admin de Whatalo (PluginFrame)     Base de datos
      │                               │                               │
      │  whatalo:action { data }      │                               │
      │──────────────────────────►    │                               │
      │           Verificar granted_scopes + sesión auth              │
      │                               │─────────────────────────────►│
      │                               │  Consulta Prisma (solo lectura)│
      │                               │◄─────────────────────────────│
      │  whatalo:ack { success, data } │                               │
      │◄──────────────────────────    │                               │

// whatalo.app.ts
import { defineApp } from "@whatalo/plugin-sdk";

export default defineApp({
  id: "my-plugin",
  name: "My Plugin",
  scopes: [
    "read:products",   // required for products and categories
    "read:orders",     // required for orders
    "read:customers",  // required for customers
    "read:store",      // required for store metadata
  ],
  adminUI: {
    pages: [{ path: "dashboard", title: "Dashboard" }],
  },
});

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

export function Dashboard() {
  const { products, orders, customers, categories, store } = useWhataloData();

  // Los recursos de colección exponen .list(params?) y .get(id)
  // Store es un recurso singleton y expone .get()
}

// List products — all params are optional
const result = await products.list({
  page: 1,
  per_page: 20,
  status: "active",   // "active" | "inactive" — omit for all
  search: "camisa",   // substring match on product name
});

// result.data    — array de objetos Product
// result.pagination.total       — total de productos que coinciden
// result.pagination.total_pages — total de páginas

// Obtener un producto por su ID público
const single = await products.get("472819365047");
// single.data — objeto Product

// List orders — all params are optional
const result = await orders.list({
  page: 1,
  per_page: 20,
  status: "pending",  // order status string — omit for all
});

// Obtener un pedido por su ID público
const single = await orders.get("819365047283");

// List customers — all params are optional
const result = await customers.list({
  page: 1,
  per_page: 20,
  search: "maria",  // matches name, phone, or email
});

// Obtener un cliente por su ID público
const single = await customers.get("365047281936");

// List categories — all params are optional
const result = await categories.list({
  page: 1,
  per_page: 50,
  search: "ropa",  // substring match on category name
});

// Obtener una categoría por su slug
const single = await categories.get("camisetas");
// Note: categories use slug as their ID, not a public_id

const result = await store.get();

console.log(result.data.name);      // "Benita Store"
console.log(result.data.currency);  // "MXN"
console.log(result.data.timezone);  // "Europe/Madrid"
console.log(result.data.domain);    // "benita.example.com" o null

import { useEffect, useState } from "react";
import { useWhataloData } from "@whatalo/plugin-sdk/bridge";
import type { DataListResponse } from "@whatalo/plugin-sdk/bridge";

interface Order {
  id: string;
  order_number: number;
  status: string;
  total: number;
  customer_name: string;
}

interface Product {
  id: string;
  name: string;
  stock_quantity: number;
  is_purchasable: boolean;
}

export function StoreDashboard() {
  const { orders, products, store } = useWhataloData();

  const [recentOrders, setRecentOrders] = useState<Order[]>([]);
  const [lowStock, setLowStock] = useState<Product[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    async function loadDashboardData() {
      try {
        // Both requests run in parallel — no sequential waterfall
        const [ordersResult, productsResult, storeResult] = await Promise.all([
          orders.list({ page: 1, per_page: 10 }),
          products.list({ page: 1, per_page: 100, status: "active" }),
          store.get(),
        ]);

        setRecentOrders(ordersResult.data as Order[]);

        console.log(`Zona horaria de la tienda: ${storeResult.data.timezone}`);

        // Filter client-side for low-stock items
        const stockWarning = (productsResult.data as Product[]).filter(
          (p) => p.stock_quantity > 0 && p.stock_quantity <= 5
        );
        setLowStock(stockWarning);
      } catch (err) {
        setError(err instanceof Error ? err.message : "Error al cargar datos");
      } finally {
        setLoading(false);
      }
    }

    loadDashboardData();
  }, [orders, products, store]);

  if (loading) return <p>Cargando dashboard...</p>;
  if (error) return <p>Error: {error}</p>;

  return (
    <div>
      <section>
        <h2>Pedidos Recientes ({recentOrders.length})</h2>
        <ul>
          {recentOrders.map((order) => (
            <li key={order.id}>
              #{order.order_number} — {order.customer_name} — {order.status} —{" "}
              ${order.total.toFixed(2)}
            </li>
          ))}
        </ul>
      </section>

      <section>
        <h2>Alerta de Bajo Stock ({lowStock.length})</h2>
        <ul>
          {lowStock.map((product) => (
            <li key={product.id}>
              {product.name} — {product.stock_quantity} restantes
            </li>
          ))}
        </ul>
      </section>
    </div>
  );
}

const result = await products.list({ page: 1, per_page: 25 });

const { data, pagination } = result;
// pagination.page         — número de página actual
// pagination.per_page     — ítems retornados por página
// pagination.total        — total de ítems coincidentes en todas las páginas
// pagination.total_pages  — número total de páginas

// Verificar si hay más páginas
const hasNextPage = pagination.page < pagination.total_pages;

try {
  const result = await products.list();
} catch (err) {
  // err.message === "Rate limit exceeded"
  // Espera antes de reintentar — la ventana se reinicia cada 10 segundos
}

try {
  const result = await orders.list({ page: 1 });
  // Usa result.data
} catch (err) {
  const message = err instanceof Error ? err.message : "Error desconocido";

  // Mensajes de error comunes:
  // "Missing scope: read:orders"   — scope no declarado o no otorgado
  // "Plugin not installed"          — registro de instalación no encontrado
  // "Rate limit exceeded"           — ventana de 20 req/10s agotada
  // "Resource ID required for get operation" — .get() llamado sin ID en un recurso no singleton
  // "Order not found"               — ID no existe en esta tienda
  // "Unauthorized"                  — sesión del usuario inválida
}