@mastra/discord 1.0.0 → 1.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,1110 @@
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes, randomUUID } from "crypto";
+import { AgentChannels, resolveWaitUntil } from "@mastra/core/channels";
+import { InMemoryChannelsStorage } from "@mastra/core/storage";
+import { DiscordAdapter, createDiscordAdapter, createDiscordAdapter as createDiscordAdapter$1 } from "@chat-adapter/discord";
+//#region src/types.ts
+/**
+* Default Discord REST base — **including** the `/api/v10` version segment. The
+* client concatenates this with the request path verbatim, so an override must
+* carry its own version segment (`https://example.test/api/v10`); passing a bare
+* origin produces unversioned request URLs.
+*/
+const DISCORD_API_BASE_URL = "https://discord.com/api/v10";
+/** Base for the OAuth2 authorize (bot-invite) URL. */
+const DISCORD_OAUTH_AUTHORIZE_URL = "https://discord.com/oauth2/authorize";
+/**
+* Named Discord permission bits (a subset). Discord permissions are a 53+ bit
+* field, so they are represented as `bigint` and serialized to a decimal string
+* in the invite URL.
+*
+* @see https://discord.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags
+*/
+const DISCORD_PERMISSIONS = {
+	ADD_REACTIONS: 1n << 6n,
+	VIEW_CHANNEL: 1n << 10n,
+	SEND_MESSAGES: 1n << 11n,
+	EMBED_LINKS: 1n << 14n,
+	ATTACH_FILES: 1n << 15n,
+	READ_MESSAGE_HISTORY: 1n << 16n,
+	USE_APPLICATION_COMMANDS: 1n << 31n,
+	SEND_MESSAGES_IN_THREADS: 1n << 38n
+};
+/**
+* Default permissions requested in the bot-invite URL: enough for a chat agent
+* to read and reply (in channels and threads), post embeds/files, add reactions,
+* and see recent history. Kept intentionally minimal — no moderation or manage
+* permissions. Callers can override via {@link DiscordConnectOptions.permissions}
+* or {@link DiscordProviderConfig.permissions}.
+*/
+const DEFAULT_INVITE_PERMISSIONS = DISCORD_PERMISSIONS.VIEW_CHANNEL | DISCORD_PERMISSIONS.SEND_MESSAGES | DISCORD_PERMISSIONS.SEND_MESSAGES_IN_THREADS | DISCORD_PERMISSIONS.EMBED_LINKS | DISCORD_PERMISSIONS.ATTACH_FILES | DISCORD_PERMISSIONS.READ_MESSAGE_HISTORY | DISCORD_PERMISSIONS.ADD_REACTIONS | DISCORD_PERMISSIONS.USE_APPLICATION_COMMANDS;
+/** OAuth2 scopes requested by the bot-invite URL. */
+const DEFAULT_INVITE_SCOPES = ["bot", "applications.commands"];
+//#endregion
+//#region src/discord-client.ts
+/** `CHAT_INPUT` (slash) application command type. */
+const APPLICATION_COMMAND_TYPE_CHAT_INPUT = 1;
+/** Per-request ceiling for control-plane calls, so a hung API can't stall the provider. */
+const REQUEST_TIMEOUT_MS = 1e4;
+/**
+* Discord snowflake pattern (17–20 digits). Every id Discord issues — application,
+* guild, channel, user — is a snowflake. Validate before interpolating any id
+* into a REST path so unverified callers can't smuggle path traversal (`..`) or
+* other non-snowflake values that resolve to a different endpoint (e.g., a
+* `guildId` of `..` on `/applications/{id}/guilds/{guildId}/commands` collapses
+* to the global-commands endpoint and would overwrite an app's global commands).
+*
+* @see https://discord.com/developers/docs/reference#snowflakes
+*/
+const DISCORD_SNOWFLAKE = /^\d{17,20}$/;
+function assertSnowflake(value, label) {
+	if (!DISCORD_SNOWFLAKE.test(value)) throw new Error(`Invalid Discord ${label}: ${JSON.stringify(value)}`);
+}
+/**
+* Call the Discord REST API with Bot-token auth. `method` is required; supplying
+* `body` adds the JSON `content-type` header and serializes the payload. Returns
+* the raw {@link Response} so callers can classify the status themselves rather
+* than having every non-2xx collapse into a thrown error.
+*
+* This is the **control plane only** — validating the app and reading guild
+* membership. Sending replies uses the interaction token inside the adapter,
+* never this bot-token path.
+*/
+async function discordRequest(botToken, method, path, apiBaseUrl = DISCORD_API_BASE_URL, body) {
+	const init = {
+		method,
+		headers: {
+			authorization: `Bot ${botToken}`,
+			...body !== void 0 ? { "content-type": "application/json" } : {}
+		},
+		...body !== void 0 ? { body: JSON.stringify(body) } : {}
+	};
+	try {
+		return await fetch(`${apiBaseUrl}${path}`, {
+			...init,
+			signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+		});
+	} catch (cause) {
+		throw new Error(`Discord ${method} ${path} request failed`, { cause });
+	}
+}
+/** Read a Discord error description from a non-2xx response, best-effort. */
+async function describeError(response) {
+	return (await response.json().catch(() => null))?.message ?? `HTTP ${response.status}`;
+}
+/**
+* Validate the app's bot token and resolve the application identity via
+* `GET /applications/@me` (Bot auth). Throws if the token is rejected.
+*
+* @see https://discord.com/developers/docs/resources/application#get-current-application
+*/
+async function validateApp(botToken, apiBaseUrl = DISCORD_API_BASE_URL) {
+	const response = await discordRequest(botToken, "GET", "/applications/@me", apiBaseUrl);
+	if (!response.ok) throw new Error(`Discord rejected the bot token: ${await describeError(response)}`);
+	const app = await response.json();
+	if (!app?.id) throw new Error("Discord /applications/@me returned no application id");
+	return app;
+}
+/**
+* Whether the bot is already a member of a guild. `GET /guilds/{id}` (Bot auth)
+* returns `200` only when the bot is in the guild. Absence is `404` (`10004
+* Unknown Guild`) — Discord standardized on 404 rather than 403 so the response
+* can't confirm a guild exists to a caller that lacks access — with legacy
+* deployments still answering `403` (`50001 Missing Access`).
+*
+* Any **other** failure (`401`, `429`, `5xx`) is a transient or auth problem,
+* not evidence of absence, and throws. Collapsing those into `false` would send
+* a caller whose bot *is* in the guild down the invite path on a rate limit.
+*
+* @see https://discord.com/developers/docs/resources/guild#get-guild
+*/
+async function guildHealthCheck(botToken, guildId, apiBaseUrl = DISCORD_API_BASE_URL) {
+	assertSnowflake(guildId, "guild id");
+	const response = await discordRequest(botToken, "GET", `/guilds/${guildId}`, apiBaseUrl);
+	if (response.ok) {
+		await response.body?.cancel().catch(() => {});
+		return true;
+	}
+	if (response.status === 404 || response.status === 403) {
+		await response.body?.cancel().catch(() => {});
+		return false;
+	}
+	throw new Error(`Discord guild lookup failed for "${guildId}": ${await describeError(response)}`);
+}
+/** Map normalized commands to the Discord bulk-overwrite `CHAT_INPUT` payload. */
+function toCommandPayload(commands) {
+	return commands.map((c) => ({
+		name: c.name,
+		description: c.description,
+		type: APPLICATION_COMMAND_TYPE_CHAT_INPUT
+	}));
+}
+/**
+* Longest `Retry-After` we will wait out inline before giving up. Registration
+* is best-effort at the call site, so a long bucket is better surfaced as an
+* error than held open.
+*/
+const MAX_RETRY_AFTER_MS = 5e3;
+/**
+* `PUT` a bulk command overwrite, retrying **once** if Discord rate-limits it.
+*
+* Discord returns the wait in the `retry_after` body field (seconds, may be
+* fractional) and the `Retry-After` header. The value is dynamic, so it is read
+* from the response rather than assumed.
+*
+* @see https://discord.com/developers/docs/topics/rate-limits
+*/
+async function bulkOverwriteCommands(botToken, path, commands, apiBaseUrl, scopeLabel) {
+	const payload = toCommandPayload(commands);
+	for (let attempt = 0; attempt < 2; attempt++) {
+		const response = await discordRequest(botToken, "PUT", path, apiBaseUrl, payload);
+		if (response.ok) {
+			await response.body?.cancel().catch(() => {});
+			return;
+		}
+		if (response.status === 429 && attempt === 0) {
+			const body = await response.json().catch(() => null);
+			const headerSeconds = Number(response.headers.get("retry-after"));
+			const seconds = body?.retry_after ?? (Number.isFinite(headerSeconds) ? headerSeconds : 0);
+			const waitMs = Math.ceil(seconds * 1e3);
+			if (waitMs > 0 && waitMs <= MAX_RETRY_AFTER_MS) {
+				await new Promise((resolve) => setTimeout(resolve, waitMs));
+				continue;
+			}
+			throw new Error(`Discord ${scopeLabel} command registration was rate-limited; retry after ${seconds}s: ${body?.message ?? `HTTP ${response.status}`}`);
+		}
+		throw new Error(`Discord ${scopeLabel} command registration failed: ${await describeError(response)}`);
+	}
+}
+/**
+* Bulk-overwrite a **guild's** slash commands (`PUT …/guilds/{guildId}/commands`).
+* Guild-scoped commands update **instantly**. Register on first-seen guild;
+* callers skip the call when the command hash is unchanged (200 creates/day/guild).
+*
+* @see https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-guild-application-commands
+*/
+async function registerGuildCommands(botToken, applicationId, guildId, commands, apiBaseUrl = DISCORD_API_BASE_URL) {
+	assertSnowflake(applicationId, "application id");
+	assertSnowflake(guildId, "guild id");
+	await bulkOverwriteCommands(botToken, `/applications/${applicationId}/guilds/${guildId}/commands`, commands, apiBaseUrl, "guild");
+}
+/**
+* Bulk-overwrite the app's **global** slash commands (`PUT …/commands`).
+* Eventually consistent (propagation is not instant — don't quote a fixed
+* number). Opt-in via `commandScope: 'global'`.
+*
+* @see https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-global-application-commands
+*/
+async function registerGlobalCommands(botToken, applicationId, commands, apiBaseUrl = DISCORD_API_BASE_URL) {
+	assertSnowflake(applicationId, "application id");
+	await bulkOverwriteCommands(botToken, `/applications/${applicationId}/commands`, commands, apiBaseUrl, "global");
+}
+/**
+* Build the OAuth2 bot-invite URL. This *is* the Discord "install" flow: the
+* operator opens it, picks a guild, and authorizes — there is no token exchange.
+* `scope=bot applications.commands` + a `permissions` bitfield.
+*
+* @see https://discord.com/developers/docs/topics/oauth2#bot-authorization-flow
+*/
+function buildInviteUrl(options) {
+	const permissions = (options.permissions ?? DEFAULT_INVITE_PERMISSIONS).toString();
+	const scopes = options.scopes ?? DEFAULT_INVITE_SCOPES;
+	const url = new URL(DISCORD_OAUTH_AUTHORIZE_URL);
+	url.searchParams.set("client_id", options.applicationId);
+	url.searchParams.set("scope", scopes.join(" "));
+	url.searchParams.set("permissions", permissions);
+	if (options.guildId) {
+		url.searchParams.set("guild_id", options.guildId);
+		url.searchParams.set("disable_guild_select", "true");
+	}
+	return url.toString();
+}
+//#endregion
+//#region src/commands.ts
+/**
+* Conventional command seed registered when a connect provides none. Discord
+* surfaces `/help` in the command picker; the built-in DM/mention handling
+* covers everything else, so the seed is intentionally tiny.
+* @see https://discord.com/developers/docs/interactions/application-commands
+*/
+const DEFAULT_COMMANDS = [{
+	name: "help",
+	description: "Show what this bot can do"
+}];
+/**
+* Map user-supplied commands to Discord `CHAT_INPUT` command shapes, enforcing
+* the API constraints: `name` is lowercased, stripped of a leading slash,
+* reduced to `[a-z0-9_-]`, and clamped to 1-32 chars; `description` defaults to
+* `Run /<name>` and is clamped to 1-100 chars. Empty or duplicate names are
+* dropped.
+*
+* @see https://discord.com/developers/docs/interactions/application-commands#application-command-object-application-command-naming
+*/
+function normalizeCommands(raw) {
+	if (!raw) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const commands = [];
+	for (const item of raw) {
+		const input = typeof item === "string" ? { name: item } : item;
+		const name = input.name.replace(/^\//, "").toLowerCase().replace(/[^a-z0-9_-]/g, "").slice(0, 32);
+		if (!name || seen.has(name)) continue;
+		seen.add(name);
+		const description = (input.description?.trim() || `Run /${name}`).slice(0, 100);
+		commands.push({
+			name,
+			description
+		});
+	}
+	return commands;
+}
+/**
+* Stable content hash of a normalized command list, used to skip re-`PUT`ting a
+* guild/global command set that hasn't changed (Discord allows only 200
+* application-command creates per day, per guild). Order-independent: commands
+* are sorted by name before hashing.
+*/
+function hashCommands(commands) {
+	const canonical = [...commands].sort((a, b) => a.name.localeCompare(b.name)).map((c) => ({
+		name: c.name,
+		description: c.description
+	}));
+	return createHash("sha256").update(JSON.stringify(canonical)).digest("hex").slice(0, 16);
+}
+//#endregion
+//#region src/crypto.ts
+/**
+* Opt-in AES-256-GCM encryption for the app's bot token at rest, with
+* HKDF-SHA256 key derivation (mirrors `@mastra/telegram` / `@mastra/slack`'s
+* `crypto.ts`). Each value gets a fresh random 16-byte salt + 12-byte IV; the
+* salt travels in the ciphertext, so the same passphrase never derives the same
+* key twice. The algorithm prefix lets plaintext and encrypted values coexist
+* during migration, so {@link decrypt} can no-op on plaintext.
+*
+* Format: `aes-256-gcm-hkdf:base64(salt):base64(iv):base64(authTag):base64(ciphertext)`
+*/
+const ALGO_PREFIX = "aes-256-gcm-hkdf";
+const HKDF_INFO = "mastra-discord-encryption";
+function deriveKey(passphrase, salt) {
+	return Buffer.from(hkdfSync("sha256", passphrase, salt, HKDF_INFO, 32));
+}
+/** Whether a stored value was produced by {@link encrypt}. */
+function isEncrypted(value) {
+	return value.startsWith(`${ALGO_PREFIX}:`);
+}
+/** Encrypt a UTF-8 string with a per-value random salt + IV. */
+function encrypt(plaintext, passphrase) {
+	const salt = randomBytes(16);
+	const iv = randomBytes(12);
+	const cipher = createCipheriv("aes-256-gcm", deriveKey(passphrase, salt), iv);
+	const enc = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+	const tag = cipher.getAuthTag();
+	return `${ALGO_PREFIX}:${salt.toString("base64")}:${iv.toString("base64")}:${tag.toString("base64")}:${enc.toString("base64")}`;
+}
+/** Decrypt a value from {@link encrypt}. Plaintext (unprefixed) is returned unchanged. */
+function decrypt(value, passphrase) {
+	if (!isEncrypted(value)) return value;
+	const [, saltB64, ivB64, tagB64, ctB64] = value.split(":");
+	if (!saltB64 || !ivB64 || !tagB64 || ctB64 === void 0) throw new Error("Invalid ciphertext payload");
+	try {
+		const decipher = createDecipheriv("aes-256-gcm", deriveKey(passphrase, Buffer.from(saltB64, "base64")), Buffer.from(ivB64, "base64"));
+		decipher.setAuthTag(Buffer.from(tagB64, "base64"));
+		return Buffer.concat([decipher.update(Buffer.from(ctB64, "base64")), decipher.final()]).toString("utf8");
+	} catch (cause) {
+		throw new Error("Failed to decrypt a stored Discord secret — either the configured encryption key does not match the one it was encrypted with, or the stored value is corrupt. Check `encryptionKey` on DiscordProvider or MASTRA_ENCRYPTION_KEY.", { cause });
+	}
+}
+//#endregion
+//#region src/install-store.ts
+/** Platform identifier used for every stored record, config, and route. */
+const PLATFORM = "discord";
+/**
+* Two-tier persistence for Discord, layered over the platform-agnostic
+* `ChannelsStorage` (the same store `@mastra/slack` / `@mastra/telegram` use).
+*
+* - **App tier** (`saveConfig`/`getConfig`) — the one application's
+*   `botToken` + `publicKey` + `applicationId`, stored **once** (one app, many
+*   guilds). `botToken` is AES-256-GCM encrypted at rest when an `encryptionKey`
+*   is supplied.
+* - **Install tier** (`getInstallationByAgent`/`…ByWebhookId`/`saveInstallation`)
+*   — one row per agent, keyed by agent, tracking the `guildIds` the bot is live
+*   in. Secrets are **not** duplicated per row.
+*/
+var DiscordInstallStore = class {
+	storage;
+	encryptionKey;
+	constructor(storage, encryptionKey) {
+		this.storage = storage;
+		this.encryptionKey = encryptionKey;
+	}
+	/** The stored app config, if any (bot token decrypted). */
+	async getAppConfig() {
+		const config = await this.storage.getConfig(PLATFORM);
+		if (!config) return null;
+		const data = config.data ?? {};
+		if (!data.botToken || !data.publicKey || !data.applicationId) return null;
+		return {
+			botToken: this.#dec(data.botToken),
+			publicKey: data.publicKey,
+			applicationId: data.applicationId
+		};
+	}
+	/** Persist the app config once (bot token encrypted at rest when keyed). */
+	async saveAppConfig(app) {
+		const data = {
+			botToken: this.#enc(app.botToken),
+			publicKey: app.publicKey,
+			applicationId: app.applicationId
+		};
+		await this.storage.saveConfig({
+			platform: PLATFORM,
+			data,
+			updatedAt: /* @__PURE__ */ new Date()
+		});
+	}
+	/** Remove the stored app config. */
+	async deleteAppConfig() {
+		await this.storage.deleteConfig(PLATFORM);
+	}
+	/** The installation for an agent, if any. */
+	async getByAgent(agentId) {
+		const record = await this.storage.getInstallationByAgent(PLATFORM, agentId);
+		return record ? this.#fromRecord(record) : null;
+	}
+	/** Look up an installation by the routing id in its interactions-route path. */
+	async getByWebhookId(webhookId) {
+		const record = await this.storage.getInstallationByWebhookId(webhookId);
+		return record && record.platform === "discord" ? this.#fromRecord(record) : null;
+	}
+	/**
+	* Find the installation that owns a guild (tenancy lookup by `guildId`). Used
+	* when the routing key is a guild rather than a webhook id.
+	*
+	* `guildIds` is per-agent and nothing enforces exclusivity, so two agents can
+	* legitimately be installed into the same guild. Returning the first match
+	* would make routing depend on storage row order — the same interaction could
+	* reach a different agent on the next lookup. Instead the **oldest** install
+	* wins (ties broken by id), which is stable across restarts and storage
+	* backends, and the ambiguity is logged once so an operator can see it.
+	*
+	* `ChannelsStorage` has no query-by-data-field, so this necessarily lists the
+	* platform's installations; it is not on the interactions hot path, which
+	* routes by `webhookId`.
+	*/
+	async getByGuildId(guildId) {
+		const matches = (await this.storage.listInstallations(PLATFORM)).filter((r) => (r.data?.guildIds ?? []).includes(guildId));
+		if (matches.length === 0) return null;
+		if (matches.length > 1) console.warn(`[Discord] Guild "${guildId}" is claimed by ${matches.length} installations (${matches.map((r) => r.agentId).join(", ")}). Routing to the oldest; disconnect the others to remove the ambiguity.`);
+		const winner = matches.reduce((oldest, r) => {
+			const a = r.createdAt?.getTime() ?? 0;
+			const b = oldest.createdAt?.getTime() ?? 0;
+			if (a !== b) return a < b ? r : oldest;
+			return r.id < oldest.id ? r : oldest;
+		});
+		return this.#fromRecord(winner);
+	}
+	/** Insert or replace an installation. */
+	async save(installation) {
+		await this.storage.saveInstallation(this.#toRecord(installation));
+	}
+	/** All Discord installations (active and pending). */
+	async list() {
+		return (await this.storage.listInstallations(PLATFORM)).map((r) => this.#fromRecord(r));
+	}
+	/** Remove an agent's installation, if present. */
+	async deleteByAgent(agentId) {
+		const record = await this.storage.getInstallationByAgent(PLATFORM, agentId);
+		if (record) await this.storage.deleteInstallation(record.id);
+	}
+	#enc(value) {
+		return value && this.encryptionKey ? encrypt(value, this.encryptionKey) : value;
+	}
+	#dec(value) {
+		if (!value) return value;
+		if (!this.encryptionKey) {
+			if (isEncrypted(value)) throw new Error("The stored Discord bot token is encrypted at rest, but no encryption key is configured. Set `encryptionKey` on DiscordProvider or MASTRA_ENCRYPTION_KEY.");
+			return value;
+		}
+		return decrypt(value, this.encryptionKey);
+	}
+	#toRecord(install) {
+		const data = {
+			guildIds: install.guildIds,
+			displayName: install.displayName,
+			commands: install.commands,
+			commandVersions: install.commandVersions
+		};
+		return {
+			id: install.id,
+			platform: PLATFORM,
+			agentId: install.agentId,
+			status: install.status,
+			webhookId: install.webhookId,
+			data,
+			createdAt: install.installedAt,
+			updatedAt: /* @__PURE__ */ new Date()
+		};
+	}
+	#fromRecord(record) {
+		const data = record.data ?? {};
+		return {
+			id: record.id,
+			agentId: record.agentId,
+			webhookId: record.webhookId ?? "",
+			status: record.status === "active" ? "active" : "pending",
+			guildIds: data.guildIds ?? [],
+			displayName: data.displayName,
+			commands: data.commands,
+			commandVersions: data.commandVersions,
+			installedAt: record.createdAt
+		};
+	}
+};
+/** Project an installation to its public, secret-free info for the editor UI. */
+function toInstallationInfo(install) {
+	return {
+		id: install.id,
+		platform: PLATFORM,
+		agentId: install.agentId,
+		status: install.status,
+		displayName: install.displayName,
+		installedAt: install.installedAt
+	};
+}
+//#endregion
+//#region src/discord-provider.ts
+/**
+* Resolve the per-adapter config the provider applies to the Discord entry in
+* `AgentChannels.adapters`. Discord has native embeds + action-row buttons, so
+* `toolDisplay` defaults to `'cards'` (unlike Telegram's `'text'`); `streaming`
+* post-and-edits the interaction followup; `gateway` (default `true`) makes core
+* own the DM/mention Gateway reconnection loop.
+*/
+function resolveDiscordAdapterConfig(config) {
+	return {
+		streaming: config.streaming ?? true,
+		typingStatus: config.typingStatus ?? true,
+		toolDisplay: config.toolDisplay ?? "cards",
+		gateway: config.gateway ?? true
+	};
+}
+/**
+* Discord channel provider for Mastra — a {@link ChannelProvider} over
+* `@chat-adapter/discord`. The adapter handles the protocol (Ed25519 request
+* verification, PING/PONG, deferrals, embeds/buttons, the Gateway bridge,
+* post-and-edit streaming); this provider adds the lifecycle layer.
+*
+* **One app, many guilds.** Discord has no programmatic app creation, so a
+* single application's credentials (bot token / public key / application id) are
+* stored **once** and reused across every guild. "Installing" is a bot invite —
+* an OAuth2 authorize URL — not a token exchange, so `connect()` returns the
+* `oauth` variant. A guild is confirmed either eagerly (the bot is already a
+* member) or lazily off the first inbound interaction's authoritative `guild_id`
+* (see {@link activateGuild}).
+*
+* **Gateway is core's job.** The mounted interactions route only ever receives
+* HTTP Interactions (PING, slash commands, buttons). DMs / @mentions / reactions
+* arrive over the Gateway WebSocket, whose reconnection loop core owns: setting
+* `gateway: true` (default) on the adapter entry is enough — the wrapper never
+* calls `startGatewayListener` or runs a reconnect loop.
+*
+* Implemented (issues `mastra-discord-13x.2` + `.3`): the app-config +
+* guild-keyed install store, `connect()`/`disconnect()`, OAuth2 invite-URL
+* generation, the interactions route (raw-body delegation), and adapter/Gateway
+* wiring. Command registration lands in `mastra-discord-13x.4`.
+*/
+var DiscordProvider = class {
+	id = PLATFORM;
+	#config;
+	#mastra;
+	#store;
+	/** Live adapters, keyed by installation id (one per agent; all share the app's bot token). */
+	#adapters = /* @__PURE__ */ new Map();
+	/** Cached sync view of whether the app is configured (for {@link getInfo}). */
+	#configured = false;
+	#initPromise = null;
+	/**
+	* Whether {@link #store} was built on the in-memory fallback rather than real
+	* storage — i.e. it was resolved before a `Mastra` instance was available.
+	*/
+	#storeIsFallback = false;
+	/**
+	* A fallback store dropped by {@link __attach}, held until the next store
+	* access so its contents can be carried into the real storage. See
+	* {@link #migrateFallback}.
+	*/
+	#pendingMigration;
+	/**
+	* The single in-flight store resolution. Concurrent callers share it rather
+	* than each running {@link #resolveStore}, so the fallback migration can't be
+	* raced: without this, a second caller reads the already-claimed
+	* {@link #pendingMigration} as absent, skips the migration, and caches a store
+	* over storage the first caller has not finished populating.
+	*/
+	#storeResolution;
+	/**
+	* Bumped by every {@link __attach}. A resolution that started before an attach
+	* was built against the previous storage target, so it must not cache its
+	* result; it reports itself superseded and the caller resolves again.
+	*/
+	#storeGeneration = 0;
+	constructor(config = {}) {
+		this.#config = config;
+		this.#configured = this.#suppliedAppConfig() != null;
+	}
+	/**
+	* Called by Mastra when this channel is registered.
+	* @internal
+	*/
+	__attach(mastra) {
+		const isNewInstance = this.#mastra != null && this.#mastra !== mastra;
+		this.#storeGeneration++;
+		if (isNewInstance || this.#storeIsFallback) {
+			if (this.#storeIsFallback) this.#pendingMigration = this.#store;
+			this.#initPromise = null;
+			this.#store = void 0;
+			this.#storeIsFallback = false;
+		}
+		if (isNewInstance) {
+			this.#adapters.clear();
+			this.#configured = this.#suppliedAppConfig() != null;
+		}
+		this.#mastra = mastra;
+	}
+	/**
+	* The interactions route: a single POST endpoint keyed by an opaque
+	* `webhookId`. The handler passes the **RAW** request bytes straight to
+	* `adapter.handleWebhook` — Ed25519 verification + PING/PONG live in the
+	* adapter, and any middleware that parsed/re-serialized the body would break
+	* every signature. `requiresAuth: false` (Discord authenticates via Ed25519,
+	* not a bearer token). Auto-initializes on first hit (mirrors `@mastra/slack`).
+	*/
+	getRoutes() {
+		const self = this;
+		const withInit = (handler) => {
+			return async ({ mastra }) => {
+				self.#mastra = mastra;
+				await self.#autoInitialize();
+				return handler.bind(self);
+			};
+		};
+		return [{
+			path: `/${PLATFORM}/events/:webhookId`,
+			method: "POST",
+			requiresAuth: false,
+			createHandler: withInit(this.#handleWebhook)
+		}];
+	}
+	/** Discovery metadata for the editor UI. */
+	getInfo() {
+		return {
+			id: this.id,
+			name: "Discord",
+			isConfigured: this.#configured,
+			connectOptionsSchema: {
+				type: "object",
+				properties: {
+					guildId: {
+						type: "string",
+						description: "Guild (server) to install into. If the bot is already a member, connect binds immediately; otherwise you receive an invite URL."
+					},
+					name: {
+						type: "string",
+						description: "Display name for the installation (defaults to the application's name)."
+					},
+					commands: {
+						type: "array",
+						items: { type: "string" },
+						description: "Slash command names to register for this agent."
+					}
+				}
+			}
+		};
+	}
+	/**
+	* Restore state from storage: mark the provider configured when an app config
+	* or any active installation exists, and rebuild an adapter + `AgentChannels`
+	* per active install so its Gateway loop (core-owned) starts. Idempotent.
+	*/
+	async initialize() {
+		if (this.#initPromise) return this.#initPromise;
+		this.#initPromise = this.#doInitialize();
+		try {
+			await this.#initPromise;
+		} catch (err) {
+			this.#initPromise = null;
+			throw err;
+		}
+	}
+	async #doInitialize() {
+		const store = await this.#getStore();
+		const active = (await store.list()).filter((i) => i.status === "active");
+		const hasApp = await store.getAppConfig() != null || this.#suppliedAppConfig() != null;
+		this.#configured = hasApp || active.length > 0;
+		for (const installation of active) try {
+			await this.#activateInstallation(installation);
+		} catch (err) {
+			console.error(`[Discord] Failed to restore installation "${installation.id}":`, err);
+		}
+	}
+	/**
+	* Provide or clear the app credentials at runtime. An object merges/overrides
+	* `botToken` / `publicKey` / `applicationId` (persisted on the next `connect`);
+	* `null` clears the stored app config.
+	*/
+	async configure(credentials) {
+		if (credentials === null) {
+			await (await this.#getStore()).deleteAppConfig();
+			this.#config = {
+				...this.#config,
+				app: void 0
+			};
+			this.#configured = false;
+			this.#adapters.clear();
+			this.#initPromise = null;
+			return;
+		}
+		const previous = this.#config.app;
+		this.#config = {
+			...this.#config,
+			app: {
+				...previous,
+				...credentials
+			}
+		};
+		this.#configured = this.#suppliedAppConfig() != null || this.#configured;
+		if (![
+			"botToken",
+			"publicKey",
+			"applicationId"
+		].some((k) => credentials[k] !== void 0 && credentials[k] !== previous?.[k])) return;
+		const store = await this.#getStore();
+		const stored = await store.getAppConfig();
+		if (stored) {
+			const merged = {
+				...stored,
+				...credentials
+			};
+			if (merged.botToken && merged.publicKey && merged.applicationId) await store.saveAppConfig(merged);
+		}
+		const wasInitialized = this.#initPromise !== null;
+		this.#adapters.clear();
+		this.#initPromise = null;
+		if (wasInitialized) await this.initialize();
+	}
+	/**
+	* Connect an agent to Discord.
+	*
+	* - Ensures the app config exists (stored, or supplied via provider config /
+	*   `DISCORD_*` env and persisted once, after validation). Throws if none —
+	*   Discord apps are created in the Developer Portal, not programmatically.
+	* - Validates the bot token via `GET /applications/@me`.
+	* - If `options.guildId` is given **and the bot is already in that guild**,
+	*   binds immediately (`{ type: 'immediate' }`).
+	* - Otherwise persists a pending install and returns the OAuth2 bot-invite URL
+	*   (`{ type: 'oauth', authorizationUrl }`); the guild activates lazily on the
+	*   first interaction.
+	*/
+	async connect(agentId, options = {}) {
+		const store = await this.#getStore();
+		const existing = await store.getByAgent(agentId);
+		if (existing?.status === "active") throw new Error(`Agent "${agentId}" is already connected to Discord. Disconnect first to reconnect. To add another server, invite the bot with the existing URL — new guilds activate on first use.`);
+		const { app, persisted } = await this.#resolveAppConfig(store);
+		const identity = await validateApp(app.botToken, this.#apiBaseUrl());
+		if (!persisted) await store.saveAppConfig(app);
+		const installationId = existing?.id ?? randomUUID();
+		const webhookId = existing?.webhookId ?? randomUUID();
+		const displayName = options.name ?? identity.name;
+		const installedAt = existing?.installedAt ?? /* @__PURE__ */ new Date();
+		const commands = normalizeCommands(options.commands ?? this.#config.commands ?? DEFAULT_COMMANDS);
+		if (options.guildId && await guildHealthCheck(app.botToken, options.guildId, this.#apiBaseUrl())) {
+			const installation = {
+				id: installationId,
+				agentId,
+				webhookId,
+				status: "active",
+				guildIds: [options.guildId],
+				displayName,
+				commands: commands.length ? commands : void 0,
+				commandVersions: existing?.commandVersions,
+				installedAt
+			};
+			await store.save(installation);
+			await this.#registerCommands(app, installation, options.guildId);
+			await this.#activateInstallation(installation);
+			this.#configured = true;
+			await this.#config.onInstall?.(installation);
+			return {
+				type: "immediate",
+				installationId
+			};
+		}
+		const pending = {
+			id: installationId,
+			agentId,
+			webhookId,
+			status: "pending",
+			guildIds: existing?.guildIds ?? [],
+			displayName,
+			commands: commands.length ? commands : void 0,
+			commandVersions: existing?.commandVersions,
+			installedAt
+		};
+		await store.save(pending);
+		await this.#registerCommands(app, pending);
+		this.#configured = true;
+		return {
+			type: "oauth",
+			authorizationUrl: buildInviteUrl({
+				applicationId: app.applicationId,
+				permissions: options.permissions ?? this.#config.permissions ?? DEFAULT_INVITE_PERMISSIONS,
+				scopes: DEFAULT_INVITE_SCOPES,
+				...options.guildId !== void 0 ? { guildId: options.guildId } : {}
+			}),
+			installationId
+		};
+	}
+	/**
+	* Confirm a guild off an inbound interaction's authoritative `guild_id` and
+	* mark the installation active (lazy activation). Called by the interactions
+	* route on first use. Returns the updated installation, or `null` if the
+	* `webhookId` is unknown.
+	*/
+	async activateGuild(webhookId, guildId) {
+		const next = (this.#activationChains.get(webhookId) ?? Promise.resolve()).catch(() => {}).then(() => this.#activateGuildNow(webhookId, guildId));
+		this.#activationChains.set(webhookId, next);
+		try {
+			return await next;
+		} finally {
+			if (this.#activationChains.get(webhookId) === next) this.#activationChains.delete(webhookId);
+		}
+	}
+	#activationChains = /* @__PURE__ */ new Map();
+	async #activateGuildNow(webhookId, guildId) {
+		const store = await this.#getStore();
+		const installation = await store.getByWebhookId(webhookId);
+		if (!installation) return null;
+		const wasActive = installation.status === "active";
+		const known = installation.guildIds.includes(guildId);
+		if (wasActive && known) return installation;
+		if (!known) installation.guildIds.push(guildId);
+		installation.status = "active";
+		await store.save(installation);
+		const app = await store.getAppConfig();
+		if (app) await this.#registerCommands(app, installation, guildId);
+		this.#configured = true;
+		if (!wasActive) await this.#config.onInstall?.(installation);
+		return installation;
+	}
+	/**
+	* Disconnect an agent from Discord: remove its installation row and drop the
+	* adapter entry.
+	*
+	* **Limitation:** the Gateway loop is owned by core (it calls
+	* `startGatewayListener` itself; there is no `stopGatewayListener`), so
+	* disconnect cannot kill an in-flight gateway window — it lapses at the next
+	* duration boundary. Contrast Telegram's clean `stopPolling()`.
+	*/
+	async disconnect(agentId) {
+		const store = await this.#getStore();
+		const existing = await store.getByAgent(agentId);
+		if (!existing) throw new Error(`No Discord installation found for agent "${agentId}"`);
+		this.#adapters.delete(existing.id);
+		await store.deleteByAgent(agentId);
+		this.#configured = await store.getAppConfig() != null || (await store.list()).some((i) => i.status === "active");
+	}
+	/** List installations (public info only — no secrets). */
+	async listInstallations() {
+		return (await (await this.#getStore()).list()).map(toInstallationInfo);
+	}
+	/** The full installation for an agent (no secrets live on it), or `null`. */
+	async getInstallation(agentId) {
+		return await (await this.#getStore()).getByAgent(agentId) ?? null;
+	}
+	/** Whether the Discord app is configured (credentials resolvable). */
+	isConfigured() {
+		return this.#configured;
+	}
+	/** The live `DiscordAdapter` for an installation id, if one is active. */
+	getAdapter(installationId) {
+		return this.#adapters.get(installationId);
+	}
+	async #handleWebhook(c) {
+		const webhookId = c.req.param("webhookId");
+		if (!webhookId) return c.json({ error: "Missing webhookId" }, 400);
+		const store = await this.#getStore();
+		const installation = await store.getByWebhookId(webhookId);
+		if (!installation) return c.json({ error: "Unknown webhook" }, 404);
+		const app = await store.getAppConfig();
+		if (!app) return c.json({ error: "Discord app is not configured" }, 503);
+		const adapter = this.#getOrCreateAdapter(installation, app);
+		const waitUntil = this.#config.waitUntil ?? resolveWaitUntil(c);
+		const activationBody = c.req.raw.clone();
+		const scheduleActivation = (response) => {
+			if (response.ok) {
+				const activation = this.#activateFromInteraction(webhookId, activationBody);
+				if (waitUntil) waitUntil(activation);
+				else activation.catch(() => {});
+			}
+			return response;
+		};
+		const agent = this.#resolveAgent(installation.agentId);
+		if (!agent || !this.#mastra) try {
+			return scheduleActivation(await adapter.handleWebhook(c.req.raw, waitUntil ? { waitUntil } : void 0));
+		} catch (err) {
+			console.error("[Discord] adapter.handleWebhook error:", err);
+			return c.json({ error: "Internal error" }, 500);
+		}
+		let channels = agent.getChannels();
+		if (!channels || channels.adapters["discord"] !== adapter) {
+			channels = this.#createAgentChannels(agent, adapter);
+			await channels.initialize(this.#mastra);
+		}
+		try {
+			return scheduleActivation(await channels.handleWebhookEvent(PLATFORM, c.req.raw, waitUntil ? { waitUntil } : void 0));
+		} catch (err) {
+			console.error("[Discord] Error delegating to AgentChannels:", err);
+			return c.json({ error: "Internal error" }, 500);
+		}
+	}
+	/** Extract the guild from an interaction body (a clone) and activate it. Best-effort. */
+	async #activateFromInteraction(webhookId, request) {
+		try {
+			const body = await request.json();
+			if (body?.guild_id) await this.activateGuild(webhookId, body.guild_id);
+		} catch {}
+	}
+	#apiBaseUrl() {
+		return this.#config.apiBaseUrl ?? "https://discord.com/api/v10";
+	}
+	/**
+	* Register an installation's slash commands (best-effort — a failure logs and
+	* doesn't block connect). Skips the `PUT` when the command hash is unchanged
+	* for the scope key, so re-activation of a known guild costs no API call
+	* (200 creates/day/guild). `guildId` is required for guild scope; global scope
+	* ignores it and registers once under the `'global'` key.
+	*/
+	async #registerCommands(app, installation, guildId) {
+		const commands = installation.commands ?? [];
+		if (!commands.length) return;
+		const scope = this.#config.commandScope ?? "guild";
+		const key = scope === "global" ? "global" : guildId;
+		if (!key) return;
+		const hash = hashCommands(commands);
+		const versions = installation.commandVersions ?? {};
+		if (versions[key] === hash) return;
+		try {
+			if (scope === "global") await registerGlobalCommands(app.botToken, app.applicationId, commands, this.#apiBaseUrl());
+			else await registerGuildCommands(app.botToken, app.applicationId, guildId, commands, this.#apiBaseUrl());
+			installation.commandVersions = {
+				...versions,
+				[key]: hash
+			};
+			await (await this.#getStore()).save(installation);
+		} catch (err) {
+			console.warn(`[Discord] command registration failed (${scope}${guildId ? `, guild ${guildId}` : ""}):`, err);
+		}
+	}
+	/** Build (once) the adapter for an installation from the shared app config. */
+	#getOrCreateAdapter(installation, app) {
+		const existing = this.#adapters.get(installation.id);
+		if (existing) return existing;
+		const adapter = createDiscordAdapter$1({
+			botToken: app.botToken,
+			publicKey: app.publicKey,
+			applicationId: app.applicationId,
+			apiUrl: this.#apiBaseUrl(),
+			userName: installation.displayName,
+			...this.#config.mentionRoleIds !== void 0 ? { mentionRoleIds: this.#config.mentionRoleIds } : {},
+			...this.#config.interactionFlags !== void 0 ? { interactionFlags: this.#config.interactionFlags } : {},
+			...this.#config.logger !== void 0 ? { logger: this.#config.logger } : {}
+		});
+		this.#adapters.set(installation.id, adapter);
+		return adapter;
+	}
+	/** Rebuild the adapter and inject AgentChannels for an active installation. */
+	async #activateInstallation(installation) {
+		const app = await (await this.#getStore()).getAppConfig();
+		if (!app) return;
+		const agent = this.#resolveAgent(installation.agentId);
+		const adapter = this.#getOrCreateAdapter(installation, app);
+		if (agent && this.#mastra) await this.#createAgentChannels(agent, adapter).initialize(this.#mastra);
+	}
+	/**
+	* Create AgentChannels for an agent with the Discord adapter, preserving any
+	* adapters/config the agent author already configured (mirrors `@mastra/slack`
+	* / `@mastra/telegram`). `gateway: true` (default) makes core start the Gateway
+	* reconnection loop for DMs/mentions.
+	*/
+	#createAgentChannels(agent, adapter) {
+		const existingConfig = agent.getChannels()?.channelConfig;
+		const cfg = this.#config;
+		const entry = {
+			adapter,
+			...resolveDiscordAdapterConfig(cfg),
+			...cfg.cors !== void 0 ? { cors: cfg.cors } : {},
+			...cfg.formatError !== void 0 ? { formatError: cfg.formatError } : {}
+		};
+		const channels = new AgentChannels({
+			...existingConfig,
+			adapters: {
+				...existingConfig?.adapters,
+				[PLATFORM]: entry
+			},
+			userName: agent.name,
+			handlers: cfg.handlers ?? existingConfig?.handlers,
+			inlineMedia: cfg.inlineMedia ?? existingConfig?.inlineMedia,
+			inlineLinks: cfg.inlineLinks ?? existingConfig?.inlineLinks,
+			state: cfg.state ?? existingConfig?.state,
+			threadContext: cfg.threadContext ?? existingConfig?.threadContext,
+			chatOptions: cfg.chatOptions ?? existingConfig?.chatOptions,
+			tools: cfg.tools ?? existingConfig?.tools,
+			resolveResourceId: cfg.resolveResourceId ?? existingConfig?.resolveResourceId,
+			waitUntil: cfg.waitUntil ?? existingConfig?.waitUntil,
+			resolveWaitUntil: cfg.resolveWaitUntil ?? existingConfig?.resolveWaitUntil
+		});
+		agent.setChannels(channels);
+		return channels;
+	}
+	async #autoInitialize() {
+		if (!this.#mastra) return;
+		await this.initialize();
+	}
+	#resolveAgent(agentId) {
+		try {
+			return this.#mastra?.getAgentById(agentId);
+		} catch {
+			return;
+		}
+	}
+	/** App credentials from provider config or `DISCORD_*` env, or `null` if incomplete. */
+	#suppliedAppConfig() {
+		const a = this.#config.app ?? {};
+		const botToken = a.botToken ?? process.env.DISCORD_BOT_TOKEN;
+		const publicKey = a.publicKey ?? process.env.DISCORD_PUBLIC_KEY;
+		const applicationId = a.applicationId ?? process.env.DISCORD_APPLICATION_ID;
+		if (botToken && publicKey && applicationId) return {
+			botToken,
+			publicKey,
+			applicationId
+		};
+		return null;
+	}
+	/**
+	* Resolve the app config: prefer the stored one, else the supplied credentials
+	* (config / `DISCORD_*` env). `persisted` says whether it's already in storage,
+	* so the caller can persist supplied credentials **once**, after validation.
+	* Throws if neither is available.
+	*/
+	async #resolveAppConfig(store) {
+		const stored = await store.getAppConfig();
+		if (stored) return {
+			app: stored,
+			persisted: true
+		};
+		const supplied = this.#suppliedAppConfig();
+		if (supplied) return {
+			app: supplied,
+			persisted: false
+		};
+		throw new Error("Discord app is not configured. Provide botToken, publicKey, and applicationId via the provider `app` option, the DISCORD_BOT_TOKEN / DISCORD_PUBLIC_KEY / DISCORD_APPLICATION_ID env vars, or configure() — Discord applications are created in the Developer Portal, not programmatically.");
+	}
+	/**
+	* The single entry point to the store. Every caller either gets the cached
+	* store or joins the one in-flight resolution — nobody resolves in parallel,
+	* so a caller that arrives mid-migration waits for it to finish instead of
+	* building a second store over storage that isn't populated yet.
+	*/
+	async #getStore() {
+		for (;;) {
+			if (this.#store) return this.#store;
+			const inFlight = this.#storeResolution ??= this.#resolveStore(this.#storeGeneration);
+			let resolved;
+			try {
+				resolved = await inFlight;
+			} finally {
+				if (this.#storeResolution === inFlight) this.#storeResolution = void 0;
+			}
+			if (resolved) return resolved;
+		}
+	}
+	/**
+	* One resolution attempt, run under {@link #getStore}'s in-flight guard — so
+	* the {@link #pendingMigration} claim below cannot be double-taken, and the
+	* migration completes before any caller sees the store.
+	*
+	* Returns `undefined` when `__attach` superseded this attempt while it ran:
+	* the storage target changed underneath it, so caching would pin the provider
+	* to a store built for the previous one.
+	*/
+	async #resolveStore(generation) {
+		const encryptionKey = this.#config.encryptionKey ?? process.env.MASTRA_ENCRYPTION_KEY;
+		const { storage, isFallback } = await this.#resolveStorage();
+		if (generation !== this.#storeGeneration) return void 0;
+		const pending = this.#pendingMigration;
+		this.#pendingMigration = void 0;
+		if (pending && isFallback) {
+			this.#storeIsFallback = true;
+			this.#store = pending;
+			return pending;
+		}
+		const store = new DiscordInstallStore(storage, encryptionKey);
+		if (pending) await this.#migrateFallback(pending, store);
+		if (generation !== this.#storeGeneration) {
+			if (pending && !this.#pendingMigration) this.#pendingMigration = pending;
+			return;
+		}
+		this.#storeIsFallback = isFallback;
+		this.#store = store;
+		return store;
+	}
+	/**
+	* Copy what a pre-registration store wrote into the real storage that has
+	* since become available. Anything already persisted wins — the real store is
+	* the durable record, and a stale in-memory row must not overwrite it. Both
+	* stores share an encryption key, so this round-trips through plaintext.
+	*
+	* Best-effort: a failure here must not take down `__attach`'s caller or the
+	* request that triggered the resolution. The provider still works against the
+	* real storage; only the pre-registration writes are missing, which is the
+	* behaviour before this migration existed.
+	*/
+	async #migrateFallback(from, to) {
+		try {
+			const app = await from.getAppConfig();
+			if (app && !await to.getAppConfig()) await to.saveAppConfig(app);
+			for (const install of await from.list()) {
+				if (await to.getByAgent(install.agentId)) continue;
+				await to.save(install);
+			}
+		} catch (error) {
+			console.warn("[Discord] Failed to carry pre-registration installations into Mastra storage; connect() again to re-create them.", error);
+		}
+	}
+	/**
+	* Resolve the backing storage, reporting whether it is the in-memory fallback
+	* so {@link __attach} can re-resolve a store that was built before Mastra was
+	* available, carrying its contents across.
+	*/
+	async #resolveStorage() {
+		if (this.#config.storage) return {
+			storage: this.#config.storage,
+			isFallback: false
+		};
+		const mastraStore = this.#mastra?.getStorage();
+		if (mastraStore) try {
+			await mastraStore.init();
+			const channels = await mastraStore.getStore("channels");
+			if (channels) return {
+				storage: channels,
+				isFallback: false
+			};
+		} catch {}
+		return {
+			storage: new InMemoryChannelsStorage(),
+			isFallback: true
+		};
+	}
+};
+//#endregion
+export { DEFAULT_COMMANDS, DEFAULT_INVITE_PERMISSIONS, DEFAULT_INVITE_SCOPES, DISCORD_API_BASE_URL, DISCORD_OAUTH_AUTHORIZE_URL, DISCORD_PERMISSIONS, DiscordAdapter, DiscordInstallStore, DiscordProvider, PLATFORM, buildInviteUrl, createDiscordAdapter, decrypt, discordRequest, encrypt, guildHealthCheck, hashCommands, isEncrypted, normalizeCommands, registerGlobalCommands, registerGuildCommands, resolveDiscordAdapterConfig, toInstallationInfo, validateApp };
+
+//# sourceMappingURL=index.js.map