@mastra/discord 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,554 @@
+import { ChannelAdapterConfig, ChannelConfig, ChannelConnectResult, ChannelHandlers, ChannelInstallationInfo, ChannelPlatformInfo, ChannelProvider, StreamingConfig, WaitUntilFn } from "@mastra/core/channels";
+import { ChannelsStorage } from "@mastra/core/storage";
+import { DiscordAdapter, DiscordAdapter as DiscordAdapter$1, DiscordAdapterConfig, DiscordAdapterConfig as DiscordAdapterConfig$1, createDiscordAdapter } from "@chat-adapter/discord";
+import { Mastra } from "@mastra/core/mastra";
+import { ApiRoute } from "@mastra/core/server";
+//#region src/types.d.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.
+ */
+declare const DISCORD_API_BASE_URL = "https://discord.com/api/v10";
+/** Base for the OAuth2 authorize (bot-invite) URL. */
+declare 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
+ */
+declare const DISCORD_PERMISSIONS: {
+  readonly ADD_REACTIONS: bigint;
+  readonly VIEW_CHANNEL: bigint;
+  readonly SEND_MESSAGES: bigint;
+  readonly EMBED_LINKS: bigint;
+  readonly ATTACH_FILES: bigint;
+  readonly READ_MESSAGE_HISTORY: bigint;
+  readonly USE_APPLICATION_COMMANDS: bigint;
+  readonly SEND_MESSAGES_IN_THREADS: bigint;
+};
+/**
+ * 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}.
+ */
+declare const DEFAULT_INVITE_PERMISSIONS: bigint;
+/** OAuth2 scopes requested by the bot-invite URL. */
+declare const DEFAULT_INVITE_SCOPES: readonly ['bot', 'applications.commands'];
+/**
+ * A Discord application command as it goes over the wire (bulk-overwrite
+ * registration). Only the `CHAT_INPUT` (slash) shape is modeled here.
+ * @see https://discord.com/developers/docs/interactions/application-commands
+ */
+interface DiscordCommand {
+  /** 1-32 chars, lowercase `[a-z0-9_-]` (Discord also allows a leading `-`/`_`). */
+  name: string;
+  /** 1-100 chars. */
+  description: string;
+}
+/** Command input accepted by the provider — a bare name or `{ name, description }`. */
+type DiscordCommandInput = string | {
+  name: string;
+  description?: string;
+};
+/**
+ * App-level credentials for a single Discord application. Discord has **no
+ * programmatic app creation** — these come from the Developer Portal and are
+ * stored **once** (one app, many guilds). `botToken` is the only secret;
+ * `publicKey` and `applicationId` are public.
+ */
+interface DiscordAppConfig {
+  /** Bot token (`Authorization: Bot <token>`) — the control-plane credential. Secret. */
+  botToken: string;
+  /** Ed25519 public key used by the adapter to verify interaction signatures. */
+  publicKey: string;
+  /** The application (client) id — used as `client_id` in the invite URL. */
+  applicationId: string;
+}
+/**
+ * Configuration for {@link DiscordProvider}.
+ *
+ * Discord is **one app, many guilds**: a single application's credentials are
+ * reused across every guild the bot is invited to. There is no per-install
+ * token — "installing" is a bot invite (an OAuth2 authorize URL), and tenancy
+ * is keyed by `guildId` per interaction.
+ */
+interface DiscordProviderConfig {
+  /**
+   * App credentials (bot token / public key / application id). May be omitted
+   * here and provided via the `DISCORD_BOT_TOKEN` / `DISCORD_PUBLIC_KEY` /
+   * `DISCORD_APPLICATION_ID` env vars, or later via {@link DiscordProvider.configure}.
+   * Whichever source resolves first is persisted **once** to channels storage.
+   */
+  app?: Partial<DiscordAppConfig>;
+  /**
+   * Public HTTPS base URL for the interactions endpoint (the URL set once in the
+   * Developer Portal). May be omitted and auto-detected from the Mastra server.
+   */
+  baseUrl?: string;
+  /**
+   * Persistence for the app config + per-agent installs. Defaults to Mastra's
+   * channels storage when attached to a Mastra instance with storage, and falls
+   * back to an in-memory store otherwise (dev/test — not persisted across restarts).
+   */
+  storage?: ChannelsStorage;
+  /**
+   * Override the Discord REST origin (e.g. a test mock). Defaults to
+   * {@link DISCORD_API_BASE_URL}.
+   */
+  apiBaseUrl?: string;
+  /**
+   * Passphrase for encrypting the stored `botToken` at rest (AES-256-GCM).
+   * Defaults to the `MASTRA_ENCRYPTION_KEY` env var. When unset, the token is
+   * stored in plaintext (fine for the in-memory dev store; set a key for any
+   * persistent backend).
+   */
+  encryptionKey?: string;
+  /**
+   * Permissions bitfield requested in the invite URL. Overrides
+   * {@link DEFAULT_INVITE_PERMISSIONS}. Accepts a `bigint` or a decimal string.
+   */
+  permissions?: bigint | string;
+  /**
+   * Default slash commands registered for every connected agent (a per-agent
+   * list can override via {@link DiscordConnectOptions.commands}). Defaults to
+   * the conventional `/help` seed.
+   */
+  commands?: DiscordCommandInput[];
+  /**
+   * Where slash commands are registered:
+   * - `'guild'` (default) — per-guild (`PUT …/guilds/{id}/commands`), updates
+   *   instantly; registered on first-seen guild, keyed by a per-guild hash.
+   * - `'global'` — app-wide (`PUT …/commands`), eventually consistent; registered
+   *   once regardless of guild.
+   *
+   * @default 'guild'
+   */
+  commandScope?: 'guild' | 'global';
+  /**
+   * Keep the serverless invocation alive while the agent stream runs after the
+   * interaction is acked (Vercel/AWS Lambda). See `ChannelConfig.waitUntil`.
+   */
+  waitUntil?: WaitUntilFn;
+  /**
+   * Start the Gateway WebSocket (core-owned) so the bot receives DMs, @mentions,
+   * and reactions in addition to slash commands. Set `false` for interactions-
+   * only serverless deployments. Forwarded to the adapter entry as `gateway`.
+   *
+   * @default true
+   */
+  gateway?: boolean;
+  /**
+   * Role IDs (in addition to direct user mentions) that trigger mention
+   * handlers. Forwarded to the adapter (`DISCORD_MENTION_ROLE_IDS` env fallback).
+   */
+  mentionRoleIds?: string[];
+  /**
+   * Return interaction response flags (e.g. ephemeral, flag 64) for the initial
+   * deferred slash-command response. Flags are locked at defer time, so this
+   * fires on the deferred ACK, not the followup. Forwarded to the adapter.
+   */
+  interactionFlags?: DiscordAdapterConfig$1['interactionFlags'];
+  /** Logger forwarded to the underlying `DiscordAdapter` for internal error reporting. */
+  logger?: DiscordAdapterConfig$1['logger'];
+  /**
+   * Stream agent text to Discord as it generates, via the adapter's post-and-edit
+   * (`editMessage`) loop. Discord has no native token streaming, so this
+   * chunk-edits the interaction followup (throttle via `updateIntervalMs`).
+   *
+   * @default true
+   */
+  streaming?: StreamingConfig;
+  /**
+   * Keep a typing indicator alive during generation. Set `false` to disable.
+   *
+   * @default true
+   */
+  typingStatus?: boolean;
+  /** Override built-in event handlers. Forwarded to `AgentChannels`. */
+  handlers?: ChannelHandlers;
+  /** Which media types to send inline to the model. See `ChannelConfig.inlineMedia`. */
+  inlineMedia?: ChannelConfig['inlineMedia'];
+  /** Promote URLs in message text to file parts. See `ChannelConfig.inlineLinks`. */
+  inlineLinks?: ChannelConfig['inlineLinks'];
+  /** State adapter for deduplication, locking, and subscriptions. See `ChannelConfig.state`. */
+  state?: ChannelConfig['state'];
+  /** Fetch recent thread messages when the agent joins mid-conversation. See `ChannelConfig.threadContext`. */
+  threadContext?: ChannelConfig['threadContext'];
+  /** Additional options passed directly to the Chat SDK. See `ChannelConfig.chatOptions`. */
+  chatOptions?: ChannelConfig['chatOptions'];
+  /** Resolve the memory `resourceId` before a channel thread is created. See `ChannelConfig.resolveResourceId`. */
+  resolveResourceId?: ChannelConfig['resolveResourceId'];
+  /** Resolve `waitUntil` from the request's Hono `Context`. See `ChannelConfig.resolveWaitUntil`. */
+  resolveWaitUntil?: ChannelConfig['resolveWaitUntil'];
+  /** CORS configuration for the generated interactions route. */
+  cors?: ChannelAdapterConfig['cors'];
+  /** Override how errors are rendered in Discord messages. See `ChannelAdapterConfig.formatError`. */
+  formatError?: ChannelAdapterConfig['formatError'];
+  /**
+   * How tool calls are rendered in the reply. Discord has native embeds +
+   * action-row buttons, so this defaults to `'cards'` (unlike Telegram's
+   * `'text'`). See `ChannelAdapterConfig.toolDisplay`.
+   *
+   * @default 'cards'
+   */
+  toolDisplay?: ChannelAdapterConfig['toolDisplay'];
+  /**
+   * Whether to expose channel reaction tools (`add_reaction`/`remove_reaction`)
+   * to the agent. Set `false` for models without function calling. See `ChannelConfig.tools`.
+   *
+   * @default true
+   */
+  tools?: ChannelConfig['tools'];
+  /** Called after an agent successfully connects and the installation is persisted. */
+  onInstall?: (installation: DiscordInstallation) => void | Promise<void>;
+}
+/** Options accepted by {@link DiscordProvider.connect}. */
+interface DiscordConnectOptions {
+  /**
+   * The guild to install into. When the bot is **already** a member of this
+   * guild, connect binds immediately (`{ type: 'immediate' }`) and registers its
+   * commands; otherwise the operator is sent the invite URL and the guild is
+   * confirmed lazily off the first inbound interaction's authoritative `guild_id`.
+   */
+  guildId?: string;
+  /** Display name for this installation. Defaults to the application's name. */
+  name?: string;
+  /**
+   * Slash commands to register for this agent. Overrides
+   * {@link DiscordProviderConfig.commands}. Defaults to the `/help` seed.
+   */
+  commands?: DiscordCommandInput[];
+  /** Permissions bitfield override for this invite (bigint or decimal string). */
+  permissions?: bigint | string;
+}
+/**
+ * A per-agent Discord installation. Unlike Telegram (one token = one row),
+ * Discord installs are keyed by agent and track the set of `guildIds` the bot is
+ * live in. **No secrets live here** — the bot token lives once in the app config
+ * ({@link DiscordAppConfig}); this row only holds routing + per-guild command
+ * versions. Persisted through {@link DiscordInstallStore}.
+ */
+interface DiscordInstallation {
+  /** Stable installation id. */
+  id: string;
+  /** The agent this installation is bound to. */
+  agentId: string;
+  /**
+   * Opaque id embedded in the interactions route path
+   * (`/discord/events/:webhookId`). Used to resolve the install on inbound POSTs.
+   */
+  webhookId: string;
+  /**
+   * `pending` — invite issued, no guild confirmed yet.
+   * `active` — the bot is live in at least one guild (or bound to a known guild).
+   */
+  status: 'active' | 'pending';
+  /** Guilds this agent's bot is confirmed live in (tenancy keys). */
+  guildIds: string[];
+  /** Display name (application name or an operator-supplied override). */
+  displayName?: string;
+  /** Normalized slash commands to register for this agent (resolved at connect). */
+  commands?: DiscordCommand[];
+  /**
+   * Registered-command version hash, keyed by `guildId` (guild scope) or the
+   * literal `'global'` (global scope). Used to skip re-`PUT`ting commands when
+   * unchanged (200/day/guild rate limit).
+   */
+  commandVersions?: Record<string, string>;
+  /** When the installation was created. */
+  installedAt: Date;
+}
+//#endregion
+//#region src/discord-provider.d.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.
+ */
+declare function resolveDiscordAdapterConfig(config: Pick<DiscordProviderConfig, 'streaming' | 'typingStatus' | 'toolDisplay' | 'gateway'>): {
+  streaming: StreamingConfig;
+  typingStatus: boolean;
+  toolDisplay: ChannelAdapterConfig['toolDisplay'];
+  gateway: boolean;
+};
+/**
+ * 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`.
+ */
+declare class DiscordProvider implements ChannelProvider {
+  #private;
+  readonly id = "discord";
+  constructor(config?: DiscordProviderConfig);
+  /**
+   * Called by Mastra when this channel is registered.
+   * @internal
+   */
+  __attach(mastra: Mastra): void;
+  /**
+   * 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(): ApiRoute[];
+  /** Discovery metadata for the editor UI. */
+  getInfo(): ChannelPlatformInfo;
+  /**
+   * 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.
+   */
+  initialize(): Promise<void>;
+  /**
+   * 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.
+   */
+  configure(credentials: Partial<DiscordAppConfig> | null): Promise<void>;
+  /**
+   * 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.
+   */
+  connect(agentId: string, options?: DiscordConnectOptions): Promise<ChannelConnectResult>;
+  /**
+   * 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.
+   */
+  activateGuild(webhookId: string, guildId: string): Promise<DiscordInstallation | null>;
+  /**
+   * 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()`.
+   */
+  disconnect(agentId: string): Promise<void>;
+  /** List installations (public info only — no secrets). */
+  listInstallations(): Promise<ChannelInstallationInfo[]>;
+  /** The full installation for an agent (no secrets live on it), or `null`. */
+  getInstallation(agentId: string): Promise<DiscordInstallation | null>;
+  /** Whether the Discord app is configured (credentials resolvable). */
+  isConfigured(): boolean;
+  /** The live `DiscordAdapter` for an installation id, if one is active. */
+  getAdapter(installationId: string): DiscordAdapter$1 | undefined;
+}
+//#endregion
+//#region src/install-store.d.ts
+/** Platform identifier used for every stored record, config, and route. */
+declare 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.
+ */
+declare class DiscordInstallStore {
+  #private;
+  private readonly storage;
+  private readonly encryptionKey?;
+  constructor(storage: ChannelsStorage, encryptionKey?: string | undefined);
+  /** The stored app config, if any (bot token decrypted). */
+  getAppConfig(): Promise<DiscordAppConfig | null>;
+  /** Persist the app config once (bot token encrypted at rest when keyed). */
+  saveAppConfig(app: DiscordAppConfig): Promise<void>;
+  /** Remove the stored app config. */
+  deleteAppConfig(): Promise<void>;
+  /** The installation for an agent, if any. */
+  getByAgent(agentId: string): Promise<DiscordInstallation | null>;
+  /** Look up an installation by the routing id in its interactions-route path. */
+  getByWebhookId(webhookId: string): Promise<DiscordInstallation | 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`.
+   */
+  getByGuildId(guildId: string): Promise<DiscordInstallation | null>;
+  /** Insert or replace an installation. */
+  save(installation: DiscordInstallation): Promise<void>;
+  /** All Discord installations (active and pending). */
+  list(): Promise<DiscordInstallation[]>;
+  /** Remove an agent's installation, if present. */
+  deleteByAgent(agentId: string): Promise<void>;
+}
+/** Project an installation to its public, secret-free info for the editor UI. */
+declare function toInstallationInfo(install: DiscordInstallation): ChannelInstallationInfo;
+//#endregion
+//#region src/discord-client.d.ts
+/**
+ * The subset of Discord's application object the control plane reads back from
+ * `GET /applications/@me`.
+ * @see https://discord.com/developers/docs/resources/application#application-object
+ */
+interface DiscordApplication {
+  /** The application (client) id. */
+  id: string;
+  /** The application's name. */
+  name: string;
+}
+/**
+ * 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.
+ */
+declare function discordRequest(botToken: string, method: string, path: string, apiBaseUrl?: string, body?: unknown): Promise<Response>;
+/**
+ * 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
+ */
+declare function validateApp(botToken: string, apiBaseUrl?: string): Promise<DiscordApplication>;
+/**
+ * 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
+ */
+declare function guildHealthCheck(botToken: string, guildId: string, apiBaseUrl?: string): Promise<boolean>;
+/**
+ * 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
+ */
+declare function registerGuildCommands(botToken: string, applicationId: string, guildId: string, commands: readonly DiscordCommand[], apiBaseUrl?: string): Promise<void>;
+/**
+ * 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
+ */
+declare function registerGlobalCommands(botToken: string, applicationId: string, commands: readonly DiscordCommand[], apiBaseUrl?: string): Promise<void>;
+/** Inputs for {@link buildInviteUrl}. */
+interface BuildInviteUrlOptions {
+  /** The application (client) id — becomes `client_id`. */
+  applicationId: string;
+  /** Permissions bitfield (bigint or decimal string). Defaults to {@link DEFAULT_INVITE_PERMISSIONS}. */
+  permissions?: bigint | string;
+  /** OAuth2 scopes. Defaults to {@link DEFAULT_INVITE_SCOPES} (`bot applications.commands`). */
+  scopes?: readonly string[];
+  /**
+   * Preselect this guild in the authorize screen and lock the picker, so the
+   * operator can't authorize a different guild than the one `connect()` recorded.
+   */
+  guildId?: string;
+}
+/**
+ * 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
+ */
+declare function buildInviteUrl(options: BuildInviteUrlOptions): string;
+//#endregion
+//#region src/commands.d.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
+ */
+declare const DEFAULT_COMMANDS: readonly DiscordCommandInput[];
+/**
+ * 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
+ */
+declare function normalizeCommands(raw: readonly DiscordCommandInput[] | undefined): DiscordCommand[];
+/**
+ * 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.
+ */
+declare function hashCommands(commands: readonly DiscordCommand[]): string;
+//#endregion
+//#region src/crypto.d.ts
+/** Whether a stored value was produced by {@link encrypt}. */
+declare function isEncrypted(value: string): boolean;
+/** Encrypt a UTF-8 string with a per-value random salt + IV. */
+declare function encrypt(plaintext: string, passphrase: string): string;
+/** Decrypt a value from {@link encrypt}. Plaintext (unprefixed) is returned unchanged. */
+declare function decrypt(value: string, passphrase: string): string;
+//#endregion
+export { type BuildInviteUrlOptions, DEFAULT_COMMANDS, DEFAULT_INVITE_PERMISSIONS, DEFAULT_INVITE_SCOPES, DISCORD_API_BASE_URL, DISCORD_OAUTH_AUTHORIZE_URL, DISCORD_PERMISSIONS, DiscordAdapter, type DiscordAdapterConfig, type DiscordAppConfig, type DiscordApplication, type DiscordCommand, type DiscordCommandInput, type DiscordConnectOptions, DiscordInstallStore, type DiscordInstallation, DiscordProvider, type DiscordProviderConfig, PLATFORM, buildInviteUrl, createDiscordAdapter, decrypt, discordRequest, encrypt, guildHealthCheck, hashCommands, isEncrypted, normalizeCommands, registerGlobalCommands, registerGuildCommands, resolveDiscordAdapterConfig, toInstallationInfo, validateApp };
+//# sourceMappingURL=index.d.ts.map