Discord Plugin

@theholocron/holocron-plugin-discord notifications

Install

pnpm add -D @theholocron/holocron-plugin-discord

Capabilities

Capability	Token
`notifications`	`HOLOCRON_DISCORD_WEBHOOK (discord)`

The “token” for Discord is the full webhook URL, not a separate API key.

Config

providers: {
  notifications: ["discord", {
    // Named aliases — map logical names to webhook URLs
    webhooks: {
      deploys: "https://discord.com/api/webhooks/111/abc",
      alerts:  "https://discord.com/api/webhooks/222/xyz",
    },
    // Default when send() is called without an explicit channel
    defaultChannel: "deploys",
  }],
}

Options

Option	Required	Description
`webhooks`	No	Named aliases mapping logical channel names to their webhook URLs
`defaultChannel`	No	Alias key or raw webhook URL used as the fallback when no channel is passed to `send()`

Authentication

The “token” for Discord is an incoming webhook URL — it contains the credential inline and requires no Authorization header.

1. Create a webhook

Open your Discord server and navigate to the channel you want to post to
Click the gear icon (Edit Channel) → Integrations → Webhooks
Click New Webhook, give it a name (e.g. “Holocron”), and click Copy Webhook URL

The URL looks like: https://discord.com/api/webhooks/{webhook.id}/{webhook.token}

2. Store the webhook URL

holocron auth set discord https://discord.com/api/webhooks/1234567890/abcdefghij...

Or via env var:

export HOLOCRON_DISCORD_WEBHOOK=https://discord.com/api/webhooks/...
# Also recognized:
export DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

What `notifications` provides

send(channel, message) — post a message to the given channel. channel can be:
- A key in webhooks (alias)
- A raw webhook URL (https://discord.com/api/webhooks/...)
- An empty string, which falls back to defaultChannel

Example

import { createPlugin } from "@theholocron/holocron-plugin-discord";

const plugin = createPlugin({
  cliToken: process.env.HOLOCRON_DISCORD_WEBHOOK,
  webhooks: {
    deploys: "https://discord.com/api/webhooks/111/abc",
  },
  defaultChannel: "deploys",
});
const notif = plugin.capabilities.notifications();

// Via alias
await notif.send("deploys", "Deploy complete");
// Via raw URL
await notif.send("https://discord.com/api/webhooks/111/abc", "Deploy complete");
// Via default
await notif.send("", "Deploy complete");