Plugin SDK

my-plugin/
├── package.json        "build": "bun build … (see Publishing)"
├── src/
│   ├── index.ts        definePlugin()        — runs on the Beamvia server (sandboxed)
│   └── client.tsx      definePluginClient()  — React pages and dashboard slots (optional)
└── listing/            the public store page (optional, see Store page)
    ├── listing.json    TPluginListing: tagline, description, highlights, FAQ, setup, SEO (en + id)
    └── media/          cover (1200×630) and screenshots (1600×1000): PNG, JPEG, WebP or SVG

import { definePlugin } from "@beamvia/plugin-sdk";

type TConfig = { greeting: string };

export default definePlugin<TConfig>({
  manifest: { key: "@acme/greeter", name: "Greeter", description: "Greets new customers", icon: "Hand", version: "1.0.0", author: "Acme", network: ["api.acme.com"] },
  config: [{ key: "greeting", label: { en: "Greeting", id: "Sapaan" }, type: "TEXT", default: "Hi <%= contact.name.first %>!" }],
  permissions: [{ key: "plugin.greeter.manage", label: "Reset greeter stats" }],
  billing: { items: { greetings: { name: { en: "Greeting pack", id: "Paket sapaan" } } } },
  // contact: rows are deleted with the contact they belong to
  collections: { greeted: { indexes: [["contactId"]], unique: [["contactId"]], contact: ["contactId"] } },

  // ** Claim a conversation, answer, then give it back
  inbound: {
    priority: 50,
    onMessage: async (ctx, { contact, isFirstMessage, isOwner }) => {
      if (!isFirstMessage || isOwner) return;
      await ctx.storage.upsert("greeted", { contactId: contact.id }, { $inc: { count: 1 } });
      return { replies: [{ type: "TEXT", text: await ctx.template.render(ctx.config.greeting, { data: {} }) }] };
    },
  },

  // ** The only RPC: dashboard, other plugins, the AI (tool) and the API (api)
  actions: {
    stats: async (ctx) => ({ count: await ctx.storage.count("greeted") }),
    reset: { permission: "plugin.greeter.manage", run: async (ctx) => ({ removed: await ctx.storage.remove("greeted", {}) }) },
    greeted_count: {
      input: { type: "object", additionalProperties: false, required: [], properties: {} },
      tool: { description: "How many customers were greeted", risk: "LOW" },
      api: true,
      run: async (ctx) => ({ count: await ctx.storage.count("greeted") }),
    },
  },

  // ** One event bus: Beamvia's events, schedules and other plugins' events (background)
  on: {
    "inbox.message.created": async (ctx, { conversation, message }) => {
      if (message.direction === "INBOUND" && /refund/i.test(message.text)) await ctx.inbox.addTag(conversation.id, "refund");
    },
    "schedule.daily": async (ctx) => ctx.logger.info("Daily tick"),
  },
  schedules: { daily: "0 9 * * *" },
  emits: { greeted: { description: "A customer was greeted" } },

  // ** Public pages (blocks) and webhooks: /public/<workspace>/greeter/…
  routes: {
    "GET hello/:name": async (ctx, request) => ({ page: { title: "Hello", blocks: [{ type: "text", text: `Hi ${request.params.name}` }] } }),
    "POST webhook": async (ctx, request) => ({ status: 200, json: { received: request.body.length } }),
  },

  ai: { instructions: "Greet warmly; never promise refunds.", context: async (ctx, { contact }) => `Greeted before: ${!!(await ctx.storage.findOne("greeted", { contactId: contact.id }))}` },

  ui: {
    navigation: [{ group: { key: "greeter", label: "Greeter", icon: "Hand" }, items: [{ label: "Stats", path: "stats", icon: "BarChart3" }] }],
    pages: [{ path: "stats", title: "Greeter" }],                       // drawn by the client entry
    panels: { contact: async (ctx, { contact }) => [{ type: "text", text: `Contact ${contact.name}` }] },
  },
});

import { definePluginClient } from "@beamvia/plugin-sdk";
import { Button, Card, CardContent, CardHeader, CardTitle, Skeleton } from "@beamvia/plugin-sdk/ui";
import { useAction, useQuery, toast } from "@beamvia/plugin-sdk/client";

const Stats = () => {
  const { data, isLoading } = useQuery<{ count: number }>("stats");
  const reset = useAction("reset");
  if (isLoading) return <Skeleton className="h-24" />;
  return (
    <Card>
      <CardHeader><CardTitle>Greeted customers</CardTitle></CardHeader>
      <CardContent className="flex items-center justify-between">
        <span className="text-2xl font-semibold">{data?.count}</span>
        <Button variant="outline" disabled={reset.isRunning} onClick={() => reset.run().then(() => toast.success("Reset"))}>Reset</Button>
      </CardContent>
    </Card>
  );
};

export default definePluginClient({
  key: "@acme/greeter",
  pages: { stats: Stats },
  slots: {
    "inbox.composer.actions": ({ insertText }) => <Button size="sm" variant="ghost" onClick={() => insertText("Hello! 👋")}>Wave</Button>,
  },
});

// ** Metrics on every row, store views, a status count and a row command
ui: {
    metrics: {
        contact: {
            orders: { label: { en: "Orders", id: "Pesanan" }, format: "NUMBER", isPinned: true },
            spent: { label: { en: "Spent", id: "Belanja" }, format: "MONEY", currency: "IDR", isPinned: true },
        },
    },
    commands: [{ id: "ship", label: "Mark shipped", target: ["inbox.row", "inbox.selection"], action: "orderShip", when: { metric: "orders" } }],
    banner: async (ctx, { contact }) => ({ tone: "warning", text: "Unpaid order #1042", action: { label: "Remind", command: "remind" } }),
    commandCenter: {
        sources: {
            order: {
                collection: "orders",
                label: "Orders",
                item: { title: "number", subtitle: "customer.name", badge: "status", at: "updatedAt" },
                fields: [{ key: "status", label: "Status", type: "SELECT", isWritable: true, options: [{ value: "PAID", label: "Paid" }, { value: "SHIPPED", label: "Shipped" }] }],
                open: { window: "order" },
            },
        },
        views: [
            { id: "pending", name: "Pending shipment", source: "order", condition: [{ key: "status", op: "is", value: "PAID" }] },
            { id: "shipped", name: "Shipped", source: "order", condition: [{ key: "status", op: "is", value: "SHIPPED" }] },
        ],
        templates: [{ id: "ops", name: "Store ops", layout: { row: [{ view: "pending" }, { view: "shipped" }] } }],
        windows: { order: { title: "Order" } },
        status: { unpaid: { label: "Unpaid" } },
    },
},
collections: { orders: { indexes: [["status", "updatedAt"]] } },

// ** In a listener or schedule
await ctx.contacts.metric.set(contactId, { orders: 12, spent: 1250000 });
await ctx.ui.status("unpaid", 3);

// ** Client: the window the Command Center opens
definePluginClient({ commandCenter: { windows: { order: ({ params }) => <OrderDetail id={params.id} /> } } });

# package.json → "build": two CommonJS bundles with source maps
bun build src/index.ts   --outdir dist --entry-naming server.js --format cjs --target node    --sourcemap=external
bun build src/client.tsx --outdir dist --entry-naming client.js --format cjs --target browser --sourcemap=external \
  --external react --external react/jsx-runtime --external react/jsx-dev-runtime \
  --external @beamvia/plugin-sdk/ui --external @beamvia/plugin-sdk/client

# Development: Beamvia's PLUGIN_DEV_PATH=/path/to/your/plugins loads every <package>/dist/ bundle,
# lists it in the store and reloads it when you rebuild (no upload, no review; never in production)

# Publishing: upload dist/package.zip on /developer, or bun run publish (with listing/, the store page goes for review too)
#   manifest.key      must start with your developer scope, e.g. "@acme/greeter"
#   manifest.version  major.minor.patch, newer than the published one
# → an admin reviews the code (diff against the last version) → approves → publishes

{
  "description": {
    "short": { "en": "Ask every new customer one quick question", "id": "Tanya satu pertanyaan ke setiap pelanggan baru" },
    "long": { "en": "Markdown: what it does, who it is for, how it works", "id": "…" }
  },
  "highlights": { "en": ["Asks once, on the first message"], "id": ["Bertanya sekali, di pesan pertama"] },
  "media": {
    "cover": { "url": "cover.svg", "alt": { "en": "Poll: ask every new customer…", "id": "…" } },
    "gallery": [{ "type": "IMAGE", "url": "01.svg", "alt": { "en": "Poll asking a new customer…", "id": "…" } }]
  },
  "faq": [{ "question": { "en": "Can I change the question?", "id": "…" }, "answer": { "en": "Yes…", "id": "…" } }],
  "setup": [{ "en": "Install Poll in your workspace.", "id": "…" }],
  "categories": ["MARKETING", "ANALYTICS"],
  "tags": ["survey", "polling"],
  "languages": ["en", "id"],
  "support": { "email": "[email protected]", "url": "" },
  "links": { "docs": "", "privacy": "https://acme.com/privacy", "terms": "", "website": "https://acme.com", "demo": "" },
  "seo": { "title": { "en": "Poll: WhatsApp survey for new customers", "id": "…" }, "description": { "en": "…", "id": "…" }, "keywords": ["whatsapp survey"] }
}

# bun run build packs listing/ into dist/package.zip; bun run publish submits it for review with the build