Build self-hosted bots for Verdant.

Install

The SDK is published as @verdant/bot. Use it from a small process that you own: local Node, Bun, a VPS, a worker, or any host that can make HTTPS requests.

npm install @verdant/bot
# or
bun add @verdant/bot
# or
pnpm add @verdant/bot

Create a bot inside Verdant, mint a bot token, scope it to the server/feed/channel it needs, then pass the token through an environment variable.

Quickstart

This posts one feed announcement. The card uses format() so dynamic values are escaped, while selected variables can still be styled.

import { VerdantBot, card, channel, format, span } from "@verdant/bot";

const bot = new VerdantBot({
  token: process.env.VERDANT_BOT_TOKEN!,
});

const release = {
  version: "0.0.252",
  title: "Desktop updater polish",
};

await bot.feeds.postAnnouncement(
  process.env.VERDANT_FEED_ID!,
  card()
    .title(format("Client {version} released", release, {
      version: { color: "success", weight: "bold" },
    }))
    .description(format("{title} is live.", release, {
      title: { color: "info" },
    }))
    .accent("success")
    .richText(
      "Launch status: ",
      span("healthy", { color: "success", weight: "bold", italic: true }),
      ".",
    )
    .chart({
      title: "Release smoke metrics",
      kind: "bar",
      points: [
        { label: "Build", value: 1 },
        { label: "Upload", value: 1 },
        { label: "Announcement", value: 1 },
      ],
    })
    .youtube("https://www.youtube.com/watch?v=k1_ODDevbY8", "Release walkthrough")
    .button("Discuss release", channel(process.env.VERDANT_CHANNEL_ID!)),
  { idempotencyKey: `release-${release.version}` },
);

Examples

Webhook variables

Webhook payloads are just data. Pull out the fields you want, then map them into the builder. Keep static copy readable and pass dynamic values through format().

import { card, format } from "@verdant/bot";

export function releaseCard(payload: GitHubReleasePayload) {
  const values = {
    version: payload.release.tag_name,
    name: payload.release.name,
    author: payload.release.author.login,
    sha: payload.release.target_commitish.slice(0, 8),
  };

  return card()
    .title(format("Client {version} released", values, {
      version: { color: "success", weight: "bold" },
    }))
    .description(format("{name} by {author}", values, {
      name: { color: "info" },
      author: { color: "muted" },
    }))
    .accent("success")
    .table({
      columns: ["Field", "Value"],
      rows: [
        ["Version", format("{version}", values, { version: { color: "success", weight: "bold" } })],
        ["Commit", format("{sha}", values, { sha: { color: "info" } })],
        ["Author", format("{author}", values, { author: { color: "muted" } })],
      ],
    });

Channel cards

Feed announcements are good for long-lived posts. Text-channel cards are better for discussion, rankings, status updates, and short automation notices.

await bot.channels.postCard(
  process.env.VERDANT_CHANNEL_ID!,
  card()
    .title("Weekly ranking", { color: "purple", weight: "bold" })
    .accent("purple")
    .ranking("Top contributors", [
      { label: "Josh", value: 1280, detail: "12 commits" },
      { label: "Release Bot", value: 940, detail: "6 automations" },
    ]),
  { idempotencyKey: "rankings-week-2026-18" },
);

Flutter feed blocks

The feed builder sends structured JSON that Flutter renders natively. Bots never send raw HTML. Use .richText() for one editable text block with styled spans, .chart() for bounded analytics cards, and .youtube() for reviewed YouTube player references.

import { card, invite, span } from "@verdant/bot";

card()
  .title("Programmatic feed card", { fontSize: 20, weight: "semibold" })
  .summary("Posted through the bot REST API.", { fontSize: 14 })
  .accent("#1ee3b6")
  .heading("Highlights")
  .richText("Status: ", span("healthy", { color: "success", weight: "bold" }))
  .bullets(["Scoped token", "Backend validated", "Flutter-native preview"])
  .numbered(["Build payload", "POST to feed", "Verify in client"])
  .code("await bot.feeds.postAnnouncement(feedId, card);", "ts")
  .chart({
    title: "Audience split",
    kind: "donut",
    points: [
      { label: "Desktop", value: 58 },
      { label: "Mobile", value: 24 },
      { label: "Web", value: 18 },
    ],
  })
  .youtube("https://www.youtube.com/watch?v=k1_ODDevbY8", "Walkthrough")
  .button("Join server", invite(process.env.VERDANT_INVITE_CODE!))
  .footer("Generated by a bot", { fontSize: 12 });

Images

Upload images through Verdant first, then place the returned CDN URL in the card.

const image = await bot.uploads.image(
  await Bun.file("release-badge.png").arrayBuffer(),
  { filename: "release-badge.png", contentType: "image/png" },
);

await bot.feeds.postAnnouncement(
  process.env.VERDANT_FEED_ID!,
  card()
    .title("Release badge")
    .image(image.url, "Release badge")
    .text("The image is served from Verdant's CDN."),
);

Gateway

Simple scheduled bots can use REST only. Connect to the bot gateway when your bot needs to appear online or react to events it is allowed to receive.

const ws = new WebSocket("wss://api.verdant.chat/bot-gateway");

ws.onopen = () => {
  ws.send(JSON.stringify({
    op: "IDENTIFY",
    d: {
      token: process.env.VERDANT_BOT_TOKEN,
      intents: ["FEEDS", "MESSAGES"],
      serverIds: [process.env.VERDANT_SERVER_ID],
    },
  }));
};

ws.onmessage = (event) => {
  const frame = JSON.parse(event.data);
  if (frame.op === "READY") console.log("bot online");
  if (frame.op === "DISPATCH") console.log(frame.t, frame.d);
};

setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ op: "PING", d: {} }));
  }
}, 25_000);

Component Reference

Helpers

Styles

card()
  .accent("success")
  .title("Release passed", { color: "success" })
  .text("Custom brand color", { color: "#7c3aed" });

Publishing your bot

1. Create a bot in Verdant and keep its token in a secret store.
2. Assign the bot a server access role, then add that role to each feed's publish roles.
3. Mint a token with announcements:write and the target feed in allowedFeedIds.
4. Run your bot process anywhere that can reach https://api.verdant.chat.
5. Use REST for posting cards and the gateway only when your bot needs live events.
6. Use idempotency keys for webhooks, scheduled posts, and retryable jobs.

VERDANT_BOT_TOKEN=... \
VERDANT_BOT_FEED_ID=... \
VERDANT_API_URL=https://api.verdant.chat \
bun run --filter @verdant/bot smoke:feed

Optional env vars are VERDANT_INVITE_CODE, VERDANT_YOUTUBE_URL, and VERDANT_BOT_IDEMPOTENCY_KEY. The smoke script prints published IDs only, never the token.

If token auth succeeds but the bot role is missing from the feed publish roles, the API returns FEED_NO_PUBLISH_PERMISSION. If a channel button points outside the feed's server, validation rejects the card before publishing.