Quickstart: your first plugin

npx -p @dunea/plugin-sdk dunea-plugin init order-alerts
cd order-alerts
npm install

{
  "schemaVersion": 1,
  "kind": "plugin",
  "id": "order-alerts",
  "version": "0.1.0",
  "name": "Order alerts for Slack",
  "tagline": "Get a Slack message the moment an order is paid.",
  "description": "Order alerts posts a short message to the Slack channel of your choice for every paid order in your Dunea shop: the order number, the total and the number of items. Paste a Slack incoming webhook URL when you install it and you are done.",
  "icon": "https://example.com/order-alerts/icon.png",
  "developer": {
    "name": "Your Company",
    "website": "https://example.com",
    "supportEmail": "support@example.com",
    "privacyUrl": "https://example.com/privacy"
  },
  "pricing": { "model": "free" },
  "categories": ["sales", "productivity"],
  "permissions": ["orders:read"],
  "subscribes": ["plugin.installed", "plugin.uninstalled", "plugin.settings.updated", "shop.order.paid"],
  "webhookUrl": "https://order-alerts.example.com/dunea/webhook",
  "settings": [
    {
      "key": "slackWebhookUrl",
      "label": "Slack incoming webhook URL",
      "type": "secret",
      "required": true,
      "help": "In Slack, create an incoming webhook for the channel and paste its URL here."
    }
  ]
}

import { createServer } from 'node:http';
import { createWebhookHandler, DuneaClient } from '@dunea/plugin-sdk';

interface Install {
  accessToken: string;
  slackWebhookUrl: string;
}

// Use a real database in production, and encrypt the access token.
// Maps keep this example short, and are lost when the server restarts.
const installs = new Map<string, Install>();
const processed = new Set<string>();

const handler = createWebhookHandler({
  clientSecret: process.env.DUNEA_CLIENT_SECRET!,
  onEvent: {
    // Sent once per install, with the only copy of the access token.
    'plugin.installed': async (env) => {
      installs.set(env.installId, {
        accessToken: env.data.accessToken,
        slackWebhookUrl: String(env.data.settings.slackWebhookUrl ?? ''),
      });
    },

    // The owner changed a setting: read the current values.
    'plugin.settings.updated': async (env) => {
      const install = installs.get(env.installId);
      if (!install) return;

      const settings = await new DuneaClient({ accessToken: install.accessToken }).settings();
      install.slackWebhookUrl = String(settings.slackWebhookUrl ?? '');
    },

    'plugin.uninstalled': async (env) => {
      installs.delete(env.installId);
    },

    'shop.order.paid': async (env) => {
      // Deliveries are at-least-once: skip events you have already handled.
      if (processed.has(env.id)) return;

      const install = installs.get(env.installId);
      const orderId = String(env.data.orderId ?? '');
      if (!install || !orderId) return;

      const dunea = new DuneaClient({ accessToken: install.accessToken });
      const order = await dunea.orders.get(orderId);

      const total = (order.total / 100).toFixed(2); // amounts are in minor units
      const prefix = env.mode === 'test' ? '[test] ' : '';
      const response = await fetch(install.slackWebhookUrl, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({
          text: `${prefix}Order #${order.number} paid: ${total} ${order.currency}, ${order.items.length} item(s)`,
        }),
      });

      // Throwing returns a 500, so Dunea retries the delivery later.
      if (!response.ok) throw new Error(`Slack returned ${response.status}`);

      processed.add(env.id);
    },
  },
  onError: (error, body) => console.error('Dunea webhook failed', body.id, error),
});

const server = createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/dunea/webhook') {
    res.writeHead(404).end();
    return;
  }

  // Read the raw body: the signature is over these exact bytes.
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk as Buffer);

  const result = await handler({ rawBody: Buffer.concat(chunks), headers: req.headers });
  res.writeHead(result.status, { 'content-type': 'application/json' }).end(JSON.stringify(result.body));
});

server.listen(Number(process.env.PORT ?? 3000));

npx dunea-plugin validate

OK dunea.plugin.json: plugin "order-alerts" v0.1.0
  permissions: orders:read
  events: plugin.installed, plugin.uninstalled, plugin.settings.updated, shop.order.paid
  agent tools: (none)

export DUNEA_DEV_TOKEN=...

npx dunea-plugin publish

DUNEA_CLIENT_SECRET=... npx tsx src/webhook.ts

npx dunea-plugin test-webhook order-alerts

npx dunea-plugin publish --submit

npx dunea-plugin status order-alerts