Data Bridge

Plugin iframe              Whatalo admin host (PluginFrame)       Database
      │                               │                               │
      │  whatalo:action { data }      │                               │
      │──────────────────────────►    │                               │
      │           Check granted_scopes + auth session                 │
      │                               │─────────────────────────────►│
      │                               │  Prisma query (read-only)    │
      │                               │◄─────────────────────────────│
      │  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();

  // Collection resources expose .list(params?) and .get(id)
  // Store is a singleton resource and exposes .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: "shirt",    // substring match on product name
});

// result.data    — array of Product objects
// result.pagination.total       — total matching products
// result.pagination.total_pages — total pages

// Fetch a single product by its public ID
const single = await products.get("472819365047");
// single.data — Product object

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

// Fetch a single order by its public ID
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
});

// Fetch a single customer by their public ID
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
});

// Fetch a single category by its 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" or 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;
  currency: string;
  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(`Store timezone: ${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 : "Failed to load data");
      } finally {
        setLoading(false);
      }
    }

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

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

  return (
    <div>
      <section>
        <h2>Recent Orders ({recentOrders.length})</h2>
        <ul>
          {recentOrders.map((order) => (
            <li key={order.id}>
              #{order.order_number} — {order.customer_name} — {order.status} —{" "}
              {new Intl.NumberFormat("es-DO", {
                style: "currency",
                currency: order.currency,
              }).format(order.total)}
            </li>
          ))}
        </ul>
      </section>

      <section>
        <h2>Low Stock Alert ({lowStock.length})</h2>
        <ul>
          {lowStock.map((product) => (
            <li key={product.id}>
              {product.name} — {product.stock_quantity} remaining
            </li>
          ))}
        </ul>
      </section>
    </div>
  );
}

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

const { data, pagination } = result;
// pagination.page         — current page number
// pagination.per_page     — items returned per page
// pagination.total        — total matching items across all pages
// pagination.total_pages  — total number of pages

// Check if there are more pages
const hasNextPage = pagination.page < pagination.total_pages;

try {
  const result = await products.list();
} catch (err) {
  // err.message === "Rate limit exceeded"
  // Wait before retrying — the window resets every 10 seconds
}

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

  // Common error messages:
  // "Missing scope: read:orders"   — scope not declared in manifest or not granted
  // "Plugin not installed"          — installation record not found
  // "Rate limit exceeded"           — 20 req/10s window exhausted
  // "Resource ID required for get operation" — called .get() without an ID on a non-singleton resource
  // "Order not found"               — ID does not exist in this store
  // "Unauthorized"                  — user session is invalid
}