@minesa-org/mini-interaction 0.1.6 → 0.1.9

package/README.md

@@ -1,7 +1,3 @@
 # Mini Interaction
 
 Mini interaction, connecting your app with Discord via HTTP-interaction (Vercel support).
-
-- Read the [Discord OAuth Linked Roles setup guide](docs/discord-oauth-setup.md)
-  for a step-by-step walkthrough that uses `mini.discordOAuthCallback()` and a
-  MongoDB connection configured via `MONGODB_URI`.

package/dist/clients/MiniInteraction.d.ts

@@ -113,6 +113,23 @@ export type DiscordOAuthCallbackOptions = {
     successRedirect?: string | ((context: DiscordOAuthAuthorizeContext) => string | null | undefined);
     templates?: Partial<DiscordOAuthCallbackTemplates>;
 };
+/** Options accepted by {@link MiniInteraction.discordOAuthVerificationPage}. */
+export type DiscordOAuthVerificationPageOptions = {
+    oauth?: OAuthConfig;
+    scopes?: string[];
+    /**
+     * Path to the HTML file to load. Relative paths resolve from {@link process.cwd}.
+     *
+     * @defaultValue "index.html"
+     */
+    htmlFile?: string;
+    /**
+     * Placeholder token (with or without the `{{ }}` wrapper) that will be replaced with the generated OAuth URL.
+     *
+     * @defaultValue "OAUTH_URL"
+     */
+    placeholder?: string;
+};
 /**
  * Minimal interface describing a function capable of verifying Discord interaction signatures.
  */
@@ -123,7 +140,6 @@ type VerifyKeyFunction = (message: string | Uint8Array, signature: string, times
 export declare class MiniInteraction {
     readonly applicationId: string;
     readonly publicKey: string;
-    private readonly baseUrl;
     private readonly fetchImpl;
     private readonly verifyKeyImpl;
     private readonly commandsDirectory;
@@ -213,25 +229,32 @@ export declare class MiniInteraction {
      */
     handleRequest(request: MiniInteractionRequest): Promise<MiniInteractionHandlerResult>;
     /**
-     * Creates a Node.js style request handler that validates and processes interactions.
+     * Creates a Node.js style request handler compatible with Express, Next.js API routes,
+     * Vercel serverless functions, and any runtime that expects a `(req, res)` listener.
      */
     createNodeHandler(): MiniInteractionNodeHandler;
     /**
-     * Alias for {@link createNodeHandler} for frameworks expecting a listener function.
-     */
-    createNodeListener(): MiniInteractionNodeHandler;
-    /**
-     * Convenience alias for {@link createNodeHandler} tailored to Vercel serverless functions.
+     * Generates a lightweight verification handler that serves an HTML page with an embedded OAuth link.
+     *
+     * This is primarily used when Discord asks for a verification URL while setting up Linked Roles.
+     * Provide an HTML file that contains the `{{OAUTH_URL}}` placeholder (or a custom placeholder defined in options)
+     * and this helper will replace the token with a freshly generated OAuth link on every request.
+     *
+     * Available placeholders:
+     * - `{{OAUTH_URL}}` - HTML-escaped OAuth URL for links/buttons.
+     * - `{{OAUTH_URL_RAW}}` - raw OAuth URL, ideal for `<script>` usage.
+     * - `{{OAUTH_STATE}}` - HTML-escaped OAuth state value.
+     * - Custom placeholder name (from {@link DiscordOAuthVerificationPageOptions.placeholder}) and its `_RAW` variant.
      */
-    createVercelHandler(): MiniInteractionNodeHandler;
+    discordOAuthVerificationPage(options?: DiscordOAuthVerificationPageOptions): MiniInteractionNodeHandler;
     /**
      * Loads an HTML file and returns a success template that replaces useful placeholders.
      *
      * The following placeholders are available in the HTML file:
      * - `{{username}}`, `{{discriminator}}`, `{{user_id}}`, `{{user_tag}}`
      * - `{{access_token}}`, `{{refresh_token}}`, `{{token_type}}`, `{{scope}}`, `{{expires_at}}`
-     * - `{{state}}`
-     */
+         * - `{{state}}`
+         */
     connectedOAuthPage(filePath: string): DiscordOAuthCallbackTemplates["success"];
     /**
      * Loads an HTML file and returns an error template that can be reused for all failure cases.
@@ -247,8 +270,12 @@ export declare class MiniInteraction {
     private loadHtmlTemplate;
     /**
      * Replaces placeholder tokens in a template with escaped HTML values.
-     */
+ */
     private renderHtmlTemplate;
+    /**
+     * Normalizes placeholder tokens to the bare key the HTML renderer expects.
+     */
+    private normalizeTemplateKey;
     /**
      * Creates a minimal Discord OAuth callback handler that renders helpful HTML responses.
      *

package/dist/clients/MiniInteraction.js

@@ -9,7 +9,7 @@ import { createCommandInteraction } from "../utils/CommandInteractionOptions.js"
 import { createMessageComponentInteraction, } from "../utils/MessageComponentInteraction.js";
 import { createModalSubmitInteraction, } from "../utils/ModalSubmitInteraction.js";
 import { createUserContextMenuInteraction, createMessageContextMenuInteraction, } from "../utils/ContextMenuInteraction.js";
-import { getOAuthTokens, getDiscordUser, } from "../oauth/DiscordOAuth.js";
+import { generateOAuthUrl, getOAuthTokens, getDiscordUser, } from "../oauth/DiscordOAuth.js";
 /** File extensions that are treated as loadable modules when auto-loading. */
 const SUPPORTED_MODULE_EXTENSIONS = new Set([
     ".js",
@@ -25,7 +25,6 @@ const SUPPORTED_MODULE_EXTENSIONS = new Set([
 export class MiniInteraction {
     applicationId;
     publicKey;
-    baseUrl;
     fetchImpl;
     verifyKeyImpl;
     commandsDirectory;
@@ -54,7 +53,6 @@ export class MiniInteraction {
         }
         this.applicationId = applicationId;
         this.publicKey = publicKey;
-        this.baseUrl = DISCORD_BASE_URL;
         this.fetchImpl = fetchImpl;
         this.verifyKeyImpl = verifyKeyImplementation ?? verifyKey;
         this.commandsDirectory =
@@ -271,7 +269,7 @@ export class MiniInteraction {
         if (!Array.isArray(resolvedCommands) || resolvedCommands.length === 0) {
             throw new Error("[MiniInteraction] commands must be a non-empty array payload");
         }
-        const url = `${this.baseUrl}/applications/${this.applicationId}/commands`;
+        const url = `${DISCORD_BASE_URL}/applications/${this.applicationId}/commands`;
         const response = await this.fetchImpl(url, {
             method: "PUT",
             headers: {
@@ -299,7 +297,7 @@ export class MiniInteraction {
         if (!Array.isArray(metadata) || metadata.length === 0) {
             throw new Error("[MiniInteraction] metadata must be a non-empty array payload");
         }
-        const url = `${this.baseUrl}/applications/${this.applicationId}/role-connections/metadata`;
+        const url = `${DISCORD_BASE_URL}/applications/${this.applicationId}/role-connections/metadata`;
         const response = await this.fetchImpl(url, {
             method: "PUT",
             headers: {
@@ -372,7 +370,8 @@ export class MiniInteraction {
         };
     }
     /**
-     * Creates a Node.js style request handler that validates and processes interactions.
+     * Creates a Node.js style request handler compatible with Express, Next.js API routes,
+     * Vercel serverless functions, and any runtime that expects a `(req, res)` listener.
      */
     createNodeHandler() {
         return (request, response) => {
@@ -426,16 +425,49 @@ export class MiniInteraction {
         };
     }
     /**
-     * Alias for {@link createNodeHandler} for frameworks expecting a listener function.
-     */
-    createNodeListener() {
-        return this.createNodeHandler();
-    }
-    /**
-     * Convenience alias for {@link createNodeHandler} tailored to Vercel serverless functions.
+     * Generates a lightweight verification handler that serves an HTML page with an embedded OAuth link.
+     *
+     * This is primarily used when Discord asks for a verification URL while setting up Linked Roles.
+     * Provide an HTML file that contains the `{{OAUTH_URL}}` placeholder (or a custom placeholder defined in options)
+     * and this helper will replace the token with a freshly generated OAuth link on every request.
+     *
+     * Available placeholders:
+     * - `{{OAUTH_URL}}` - HTML-escaped OAuth URL for links/buttons.
+     * - `{{OAUTH_URL_RAW}}` - raw OAuth URL, ideal for `<script>` usage.
+     * - `{{OAUTH_STATE}}` - HTML-escaped OAuth state value.
+     * - Custom placeholder name (from {@link DiscordOAuthVerificationPageOptions.placeholder}) and its `_RAW` variant.
      */
-    createVercelHandler() {
-        return this.createNodeHandler();
+    discordOAuthVerificationPage(options = {}) {
+        const scopes = options.scopes ?? ["identify", "role_connections.write"];
+        const htmlFile = options.htmlFile ?? "index.html";
+        const placeholderKey = this.normalizeTemplateKey(options.placeholder ?? "OAUTH_URL");
+        const template = this.loadHtmlTemplate(htmlFile);
+        const oauthConfig = resolveOAuthConfig(options.oauth);
+        return (_request, response) => {
+            try {
+                const { url, state } = generateOAuthUrl(oauthConfig, scopes);
+                const values = {
+                    OAUTH_URL: url,
+                    OAUTH_URL_RAW: url,
+                    OAUTH_STATE: state,
+                };
+                const rawKeys = new Set(["OAUTH_URL_RAW"]);
+                if (placeholderKey !== "OAUTH_URL") {
+                    values[placeholderKey] = url;
+                    const rawVariant = `${placeholderKey}_RAW`;
+                    values[rawVariant] = url;
+                    rawKeys.add(rawVariant);
+                }
+                const html = this.renderHtmlTemplate(template, values, {
+                    rawKeys,
+                });
+                sendHtml(response, html);
+            }
+            catch (error) {
+                console.error("[MiniInteraction] Failed to render OAuth verification page:", error);
+                sendHtml(response, DEFAULT_VERIFICATION_ERROR_HTML, 500);
+            }
+        };
     }
     /**
      * Loads an HTML file and returns a success template that replaces useful placeholders.
@@ -443,8 +475,8 @@ export class MiniInteraction {
      * The following placeholders are available in the HTML file:
      * - `{{username}}`, `{{discriminator}}`, `{{user_id}}`, `{{user_tag}}`
      * - `{{access_token}}`, `{{refresh_token}}`, `{{token_type}}`, `{{scope}}`, `{{expires_at}}`
-     * - `{{state}}`
-     */
+         * - `{{state}}`
+         */
     connectedOAuthPage(filePath) {
         const template = this.loadHtmlTemplate(filePath);
         return ({ user, tokens, state }) => {
@@ -501,16 +533,34 @@ export class MiniInteraction {
     }
     /**
      * Replaces placeholder tokens in a template with escaped HTML values.
-     */
-    renderHtmlTemplate(template, values) {
+ */
+    renderHtmlTemplate(template, values, options) {
+        const rawKeys = options?.rawKeys instanceof Set
+            ? options.rawKeys
+            : new Set(options?.rawKeys ?? []);
         return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, key) => {
             const value = values[key];
             if (value === undefined || value === null) {
                 return "";
             }
-            return escapeHtml(String(value));
+            const stringValue = String(value);
+            return rawKeys.has(key) ? stringValue : escapeHtml(stringValue);
         });
     }
+    /**
+     * Normalizes placeholder tokens to the bare key the HTML renderer expects.
+     */
+    normalizeTemplateKey(token) {
+        if (!token) {
+            return "OAUTH_URL";
+        }
+        const trimmed = token.trim();
+        const match = trimmed.match(/^\{\{\s*(\w+)\s*\}\}$/);
+        if (match) {
+            return match[1];
+        }
+        return trimmed || "OAUTH_URL";
+    }
     /**
      * Creates a minimal Discord OAuth callback handler that renders helpful HTML responses.
      *
@@ -1224,6 +1274,22 @@ const DEFAULT_DISCORD_OAUTH_TEMPLATES = {
 </body>
 </html>`,
 };
+const DEFAULT_VERIFICATION_ERROR_HTML = `<!DOCTYPE html>
+<html>
+<head>
+        <meta charset="utf-8" />
+        <title>Server Error</title>
+        <style>
+                body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; text-align: center; }
+                .error { color: #d32f2f; background: #ffebee; padding: 15px; border-radius: 5px; display: inline-block; }
+        </style>
+</head>
+<body>
+        <div class="error">
+                <p>We were unable to load the Discord verification page. Please try again later.</p>
+        </div>
+</body>
+</html>`;
 function sendHtml(response, body, statusCode = 200) {
     if (response.headersSent || response.writableEnded) {
         return;

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export type { AttachmentOptionBuilder, ChannelOptionBuilder, MentionableOptionBu
 export { CommandInteractionOptionResolver, createCommandInteraction, } from "./utils/CommandInteractionOptions.js";
 export type { CommandInteraction, MentionableOption, ResolvedUserOption, } from "./utils/CommandInteractionOptions.js";
 export type { UserContextMenuInteraction, MessageContextMenuInteraction, } from "./utils/ContextMenuInteraction.js";
-export type { MiniInteractionFetchHandler, MiniInteractionNodeHandler, MiniInteractionHandlerResult, MiniInteractionRequest, MiniInteractionOptions, DiscordOAuthAuthorizeContext, DiscordOAuthCallbackOptions, DiscordOAuthCallbackTemplates, DiscordOAuthErrorTemplateContext, DiscordOAuthServerErrorTemplateContext, DiscordOAuthStateTemplateContext, DiscordOAuthSuccessTemplateContext, } from "./clients/MiniInteraction.js";
+export type { MiniInteractionFetchHandler, MiniInteractionNodeHandler, MiniInteractionHandlerResult, MiniInteractionRequest, MiniInteractionOptions, DiscordOAuthAuthorizeContext, DiscordOAuthCallbackOptions, DiscordOAuthCallbackTemplates, DiscordOAuthErrorTemplateContext, DiscordOAuthServerErrorTemplateContext, DiscordOAuthStateTemplateContext, DiscordOAuthSuccessTemplateContext, DiscordOAuthVerificationPageOptions, } from "./clients/MiniInteraction.js";
 export type { MiniInteractionCommand, SlashCommandHandler, UserCommandHandler, MessageCommandHandler, CommandHandler, } from "./types/Commands.js";
 export type { MiniInteractionComponent, MiniInteractionButtonHandler, MiniInteractionStringSelectHandler, MiniInteractionRoleSelectHandler, MiniInteractionUserSelectHandler, MiniInteractionChannelSelectHandler, MiniInteractionMentionableSelectHandler, MiniInteractionComponentHandler, MiniInteractionModal, MiniInteractionModalHandler, MiniInteractionHandler, } from "./clients/MiniInteraction.js";
 export type { MessageComponentInteraction, ButtonInteraction, StringSelectInteraction, RoleSelectInteraction, UserSelectInteraction, ChannelSelectInteraction, MentionableSelectInteraction, ResolvedUserOption as ComponentResolvedUserOption, ResolvedMentionableOption as ComponentResolvedMentionableOption, } from "./utils/MessageComponentInteraction.js";

package/dist/utils/constants.d.ts

@@ -1,16 +1,2 @@
-import "dotenv/config";
-/** Discord application's public key used for request signature verification. */
-declare const DISCORD_APP_PUBLIC_KEY: string;
-/** Discord application identifier used for REST requests. */
-declare const DISCORD_APPLICATION_ID: string;
-/** Bot token used when registering commands against Discord's API. */
-declare const DISCORD_BOT_TOKEN: string;
-/** Guild identifier used for guild-scoped command registration. */
-declare const DISCORD_GUILD_ID: string;
-/** Whether commands should be registered globally instead of per guild. */
-declare const DISCORD_GLOBAL: boolean;
-/** Local development port for the example interaction server. */
-declare const DISCORD_APP_PORT: string;
 /** Discord REST API base URL used for all network requests. */
-declare const DISCORD_BASE_URL = "https://discord.com/api/v10";
-export { DISCORD_APPLICATION_ID, DISCORD_APP_PORT, DISCORD_APP_PUBLIC_KEY, DISCORD_BASE_URL, DISCORD_BOT_TOKEN, DISCORD_GLOBAL, DISCORD_GUILD_ID, };
+export declare const DISCORD_BASE_URL: "https://discord.com/api/v10";

package/dist/utils/constants.js

@@ -1,16 +1,2 @@
-import "dotenv/config";
-/** Discord application's public key used for request signature verification. */
-const DISCORD_APP_PUBLIC_KEY = process.env.DISCORD_APP_PUBLIC_KEY;
-/** Discord application identifier used for REST requests. */
-const DISCORD_APPLICATION_ID = process.env.DISCORD_APPLICATION_ID;
-/** Bot token used when registering commands against Discord's API. */
-const DISCORD_BOT_TOKEN = process.env.DISCORD_BOT_TOKEN;
-/** Guild identifier used for guild-scoped command registration. */
-const DISCORD_GUILD_ID = process.env.DISCORD_GUILD_ID;
-/** Whether commands should be registered globally instead of per guild. */
-const DISCORD_GLOBAL = (process.env.DISCORD_GLOBAL ?? "false").toLowerCase() === "true";
-/** Local development port for the example interaction server. */
-const DISCORD_APP_PORT = process.env.DISCORD_PORT;
 /** Discord REST API base URL used for all network requests. */
-const DISCORD_BASE_URL = "https://discord.com/api/v10";
-export { DISCORD_APPLICATION_ID, DISCORD_APP_PORT, DISCORD_APP_PUBLIC_KEY, DISCORD_BASE_URL, DISCORD_BOT_TOKEN, DISCORD_GLOBAL, DISCORD_GUILD_ID, };
+export const DISCORD_BASE_URL = "https://discord.com/api/v10";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@minesa-org/mini-interaction",
-	"version": "0.1.6",
+	"version": "0.1.9",
 	"description": "Mini interaction, connecting your app with Discord via HTTP-interaction (Vercel support).",
 	"type": "module",
 	"main": "dist/index.js",
@@ -41,8 +41,7 @@
 	"homepage": "https://github.com/minesa-org/mini-interaction#readme",
 	"dependencies": {
 		"discord-api-types": "^0.38.32",
-		"discord-interactions": "^4.4.0",
-		"dotenv": "^17.2.3"
+		"discord-interactions": "^4.4.0"
 	},
 	"devDependencies": {
 		"@types/node": "^24.10.0",