@minesa-org/mini-interaction 0.1.2 → 0.1.4

package/README.md

@@ -1,3 +1,7 @@
 # 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

@@ -4,6 +4,7 @@ import type { MiniInteractionCommand } from "../types/Commands.js";
 import { RoleConnectionMetadataTypes } from "../types/RoleConnectionMetadataTypes.js";
 import { type MessageComponentInteraction, type ButtonInteraction, type StringSelectInteraction, type RoleSelectInteraction, type UserSelectInteraction, type ChannelSelectInteraction, type MentionableSelectInteraction } from "../utils/MessageComponentInteraction.js";
 import { type ModalSubmitInteraction } from "../utils/ModalSubmitInteraction.js";
+import { type OAuthConfig, type OAuthTokens, type DiscordUser } from "../oauth/DiscordOAuth.js";
 /** Configuration parameters for the MiniInteraction client. */
 export type MiniInteractionOptions = {
     applicationId: string;
@@ -73,6 +74,45 @@ export type MiniInteractionModal = {
 export type MiniInteractionNodeHandler = (request: IncomingMessage, response: ServerResponse) => void;
 /** Web Fetch API compatible request handler for platforms such as Cloudflare Workers. */
 export type MiniInteractionFetchHandler = (request: Request) => Promise<Response>;
+/** Context passed to OAuth success handlers and templates. */
+export type DiscordOAuthAuthorizeContext = {
+    tokens: OAuthTokens;
+    user: DiscordUser;
+    state: string | null;
+    request: IncomingMessage;
+    response: ServerResponse;
+};
+/** Context provided to templates that only need access to the state value. */
+export type DiscordOAuthStateTemplateContext = {
+    state: string | null;
+};
+/** Context provided to templates that display OAuth error messages. */
+export type DiscordOAuthErrorTemplateContext = DiscordOAuthStateTemplateContext & {
+    error: string;
+};
+/** Context provided to templates used for successful authorisation messages. */
+export type DiscordOAuthSuccessTemplateContext = DiscordOAuthStateTemplateContext & {
+    user: DiscordUser;
+    tokens: OAuthTokens;
+};
+/** Context provided to templates that handle server side failures. */
+export type DiscordOAuthServerErrorTemplateContext = DiscordOAuthStateTemplateContext;
+/** Template functions used to render HTML responses during the OAuth flow. */
+export type DiscordOAuthCallbackTemplates = {
+    success: (context: DiscordOAuthSuccessTemplateContext) => string;
+    missingCode: (context: DiscordOAuthStateTemplateContext) => string;
+    oauthError: (context: DiscordOAuthErrorTemplateContext) => string;
+    invalidState: (context: DiscordOAuthStateTemplateContext) => string;
+    serverError: (context: DiscordOAuthServerErrorTemplateContext) => string;
+};
+/** Options accepted by {@link MiniInteraction.discordOAuthCallback}. */
+export type DiscordOAuthCallbackOptions = {
+    oauth?: OAuthConfig;
+    onAuthorize?: (context: DiscordOAuthAuthorizeContext) => Promise<void> | void;
+    validateState?: (state: string | null, request: IncomingMessage) => Promise<boolean> | boolean;
+    successRedirect?: string | ((context: DiscordOAuthAuthorizeContext) => string | null | undefined);
+    templates?: Partial<DiscordOAuthCallbackTemplates>;
+};
 /**
  * Minimal interface describing a function capable of verifying Discord interaction signatures.
  */
@@ -91,6 +131,7 @@ export declare class MiniInteraction {
     private readonly commands;
     private readonly componentHandlers;
     private readonly modalHandlers;
+    private readonly htmlTemplateCache;
     private commandsLoaded;
     private loadCommandsPromise;
     private componentsLoaded;
@@ -183,6 +224,38 @@ export declare class MiniInteraction {
      * Convenience alias for {@link createNodeHandler} tailored to Vercel serverless functions.
      */
     createVercelHandler(): 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}}`
+     */
+    connectedOAuthPage(filePath: string): DiscordOAuthCallbackTemplates["success"];
+    /**
+     * Loads an HTML file and returns an error template that can be reused for all failure cases.
+     *
+     * The following placeholders are available in the HTML file:
+     * - `{{error}}`
+     * - `{{state}}`
+     */
+    failedOAuthPage(filePath: string): ((context: DiscordOAuthErrorTemplateContext) => string) & ((context: DiscordOAuthStateTemplateContext) => string);
+    /**
+     * Resolves an HTML template from disk and caches the result for reuse.
+     */
+    private loadHtmlTemplate;
+    /**
+     * Replaces placeholder tokens in a template with escaped HTML values.
+     */
+    private renderHtmlTemplate;
+    /**
+     * Creates a minimal Discord OAuth callback handler that renders helpful HTML responses.
+     *
+     * This helper keeps the user-side implementation tiny while still exposing hooks for
+     * storing metadata or validating the OAuth state value.
+     */
+    discordOAuthCallback(options: DiscordOAuthCallbackOptions): MiniInteractionNodeHandler;
     /**
      * Creates a Fetch API compatible handler for runtimes like Workers or Deno.
      */

package/dist/clients/MiniInteraction.js

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -9,6 +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";
 /** File extensions that are treated as loadable modules when auto-loading. */
 const SUPPORTED_MODULE_EXTENSIONS = new Set([
     ".js",
@@ -32,6 +33,7 @@ export class MiniInteraction {
     commands = new Map();
     componentHandlers = new Map();
     modalHandlers = new Map();
+    htmlTemplateCache = new Map();
     commandsLoaded = false;
     loadCommandsPromise = null;
     componentsLoaded = false;
@@ -435,6 +437,172 @@ export class MiniInteraction {
     createVercelHandler() {
         return this.createNodeHandler();
     }
+    /**
+     * 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}}`
+     */
+    connectedOAuthPage(filePath) {
+        const template = this.loadHtmlTemplate(filePath);
+        return ({ user, tokens, state }) => {
+            const discriminator = user.discriminator;
+            const userTag = discriminator && discriminator !== "0"
+                ? `${user.username}#${discriminator}`
+                : user.username;
+            return this.renderHtmlTemplate(template, {
+                username: user.username,
+                discriminator,
+                user_id: user.id,
+                user_tag: userTag,
+                access_token: tokens.access_token,
+                refresh_token: tokens.refresh_token,
+                token_type: tokens.token_type,
+                scope: tokens.scope,
+                expires_at: tokens.expires_at.toString(),
+                state,
+            });
+        };
+    }
+    /**
+     * Loads an HTML file and returns an error template that can be reused for all failure cases.
+     *
+     * The following placeholders are available in the HTML file:
+     * - `{{error}}`
+     * - `{{state}}`
+     */
+    failedOAuthPage(filePath) {
+        const template = this.loadHtmlTemplate(filePath);
+        const renderer = (context) => this.renderHtmlTemplate(template, {
+            error: context.error,
+            state: context.state,
+        });
+        return renderer;
+    }
+    /**
+     * Resolves an HTML template from disk and caches the result for reuse.
+     */
+    loadHtmlTemplate(filePath) {
+        const resolvedPath = path.isAbsolute(filePath)
+            ? filePath
+            : path.join(process.cwd(), filePath);
+        const cached = this.htmlTemplateCache.get(resolvedPath);
+        if (cached) {
+            return cached;
+        }
+        if (!existsSync(resolvedPath)) {
+            throw new Error(`[MiniInteraction] HTML template not found: ${resolvedPath}`);
+        }
+        const fileContents = readFileSync(resolvedPath, "utf8");
+        this.htmlTemplateCache.set(resolvedPath, fileContents);
+        return fileContents;
+    }
+    /**
+     * Replaces placeholder tokens in a template with escaped HTML values.
+     */
+    renderHtmlTemplate(template, values) {
+        return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, key) => {
+            const value = values[key];
+            if (value === undefined || value === null) {
+                return "";
+            }
+            return escapeHtml(String(value));
+        });
+    }
+    /**
+     * Creates a minimal Discord OAuth callback handler that renders helpful HTML responses.
+     *
+     * This helper keeps the user-side implementation tiny while still exposing hooks for
+     * storing metadata or validating the OAuth state value.
+     */
+    discordOAuthCallback(options) {
+        const templates = {
+            ...DEFAULT_DISCORD_OAUTH_TEMPLATES,
+            ...options.templates,
+        };
+        const oauthConfig = resolveOAuthConfig(options.oauth);
+        return async (request, response) => {
+            if (request.method !== "GET") {
+                response.statusCode = 405;
+                response.setHeader("content-type", "application/json");
+                response.end(JSON.stringify({
+                    error: "[MiniInteraction] Only GET is supported",
+                }));
+                return;
+            }
+            let state = null;
+            try {
+                const host = request.headers.host ?? "localhost";
+                const url = new URL(request.url ?? "", `http://${host}`);
+                const code = url.searchParams.get("code");
+                state = url.searchParams.get("state");
+                const error = url.searchParams.get("error");
+                if (error) {
+                    sendHtml(response, templates.oauthError({
+                        error,
+                        state,
+                    }), 400);
+                    return;
+                }
+                if (!code) {
+                    sendHtml(response, templates.missingCode({
+                        state,
+                    }), 400);
+                    return;
+                }
+                if (options.validateState) {
+                    const isValid = await options.validateState(state, request);
+                    if (!isValid) {
+                        sendHtml(response, templates.invalidState({
+                            state,
+                        }), 400);
+                        return;
+                    }
+                }
+                const tokens = await getOAuthTokens(code, oauthConfig);
+                const user = await getDiscordUser(tokens.access_token);
+                const authorizeContext = {
+                    tokens,
+                    user,
+                    state,
+                    request,
+                    response,
+                };
+                if (options.onAuthorize) {
+                    await options.onAuthorize(authorizeContext);
+                    if (response.writableEnded || response.headersSent) {
+                        return;
+                    }
+                }
+                if (options.successRedirect) {
+                    const location = typeof options.successRedirect === "function"
+                        ? options.successRedirect(authorizeContext)
+                        : options.successRedirect;
+                    if (location && !response.headersSent && !response.writableEnded) {
+                        response.statusCode = 302;
+                        response.setHeader("location", location);
+                        response.end();
+                        return;
+                    }
+                }
+                sendHtml(response, templates.success({
+                    user,
+                    tokens,
+                    state,
+                }));
+            }
+            catch (error) {
+                console.error("[MiniInteraction] Discord OAuth callback failed:", error);
+                if (!response.headersSent && !response.writableEnded) {
+                    sendHtml(response, templates.serverError({
+                        state,
+                    }), 500);
+                }
+            }
+        };
+    }
     /**
      * Creates a Fetch API compatible handler for runtimes like Workers or Deno.
      */
@@ -950,3 +1118,151 @@ export class MiniInteraction {
         }
     }
 }
+const DEFAULT_DISCORD_OAUTH_TEMPLATES = {
+    success: ({ user }) => {
+        const username = escapeHtml(user.username ?? "Discord User");
+        const discriminator = user.discriminator && user.discriminator !== "0"
+            ? `#${escapeHtml(user.discriminator)}`
+            : "";
+        return `<!DOCTYPE html>
+<html>
+<head>
+        <meta charset="utf-8" />
+        <title>Linked Role Connected</title>
+        <style>
+                body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; text-align: center; }
+                .success { color: #2e7d32; background: #e8f5e9; padding: 20px; border-radius: 10px; margin: 20px 0; }
+                .info { background: #e3f2fd; padding: 15px; border-radius: 5px; margin: 20px 0; }
+                h1 { color: #5865f2; }
+                .user-info { margin: 10px 0; font-size: 18px; }
+        </style>
+</head>
+<body>
+        <h1>✅ Successfully Connected!</h1>
+        <div class="success">
+                <p><strong>Your Discord account has been linked!</strong></p>
+                <div class="user-info">
+                        <p>👤 ${username}${discriminator}</p>
+                </div>
+        </div>
+        <div class="info">
+                <p>Your linked role metadata has been updated.</p>
+                <p>You can now close this window and return to Discord.</p>
+        </div>
+</body>
+</html>`;
+    },
+    missingCode: () => `<!DOCTYPE html>
+<html>
+<head>
+        <meta charset="utf-8" />
+        <title>Missing Authorization Code</title>
+        <style>
+                body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; }
+                .error { color: #d32f2f; background: #ffebee; padding: 15px; border-radius: 5px; }
+        </style>
+</head>
+<body>
+        <h1>Missing Authorization Code</h1>
+        <div class="error">
+                <p>No authorization code was provided.</p>
+        </div>
+</body>
+</html>`,
+    oauthError: ({ error }) => `<!DOCTYPE html>
+<html>
+<head>
+        <meta charset="utf-8" />
+        <title>OAuth Error</title>
+        <style>
+                body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; }
+                .error { color: #d32f2f; background: #ffebee; padding: 15px; border-radius: 5px; }
+        </style>
+</head>
+<body>
+        <h1>OAuth Error</h1>
+        <div class="error">
+                <p>Authorization failed: ${escapeHtml(error)}</p>
+                <p>Please try again.</p>
+        </div>
+</body>
+</html>`,
+    invalidState: () => `<!DOCTYPE html>
+<html>
+<head>
+        <meta charset="utf-8" />
+        <title>Invalid Session</title>
+        <style>
+                body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; }
+                .error { color: #d32f2f; background: #ffebee; padding: 15px; border-radius: 5px; }
+        </style>
+</head>
+<body>
+        <h1>Invalid Session</h1>
+        <div class="error">
+                <p>The provided state value did not match an active session.</p>
+                <p>Please restart the linking process.</p>
+        </div>
+</body>
+</html>`,
+    serverError: () => `<!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; }
+                .error { color: #d32f2f; background: #ffebee; padding: 15px; border-radius: 5px; }
+        </style>
+</head>
+<body>
+        <h1>Server Error</h1>
+        <div class="error">
+                <p>An error occurred while processing your request.</p>
+                <p>Please try again later.</p>
+        </div>
+</body>
+</html>`,
+};
+function sendHtml(response, body, statusCode = 200) {
+    if (response.headersSent || response.writableEnded) {
+        return;
+    }
+    response.statusCode = statusCode;
+    response.setHeader("content-type", "text/html; charset=utf-8");
+    response.end(body);
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => {
+        switch (character) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case '"':
+                return "&quot;";
+            case "'":
+                return "&#39;";
+            default:
+                return character;
+        }
+    });
+}
+function resolveOAuthConfig(provided) {
+    if (provided) {
+        return provided;
+    }
+    const appId = process.env.DISCORD_APPLICATION_ID ?? process.env.DISCORD_CLIENT_ID;
+    const appSecret = process.env.DISCORD_CLIENT_SECRET;
+    const redirectUri = process.env.DISCORD_REDIRECT_URI;
+    if (!appId || !appSecret || !redirectUri) {
+        throw new Error("[MiniInteraction] Missing OAuth configuration. Provide options.oauth or set DISCORD_APPLICATION_ID, DISCORD_CLIENT_SECRET, and DISCORD_REDIRECT_URI environment variables.");
+    }
+    return {
+        appId,
+        appSecret,
+        redirectUri,
+    };
+}

package/dist/database/MiniDataBuilder.d.ts

@@ -0,0 +1,62 @@
+import type { JSONEncodable } from "../builders/shared.js";
+/**
+ * Represents a field in the data schema.
+ */
+export interface DataField {
+    name: string;
+    type: "string" | "number" | "boolean" | "object" | "array";
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+}
+/**
+ * Builder for defining data schemas in MiniDatabase.
+ * Provides a fluent API for developers to define their data structure.
+ *
+ * @example
+ * ```typescript
+ * const userSchema = new MiniDataBuilder()
+ *   .addField("userId", "string", { required: true })
+ *   .addField("username", "string", { required: true })
+ *   .addField("coins", "number", { default: 0 })
+ *   .addField("metadata", "object", { default: {} });
+ * ```
+ */
+export declare class MiniDataBuilder implements JSONEncodable<Record<string, DataField>> {
+    private fields;
+    /**
+     * Adds a field to the data schema.
+     */
+    addField(name: string, type: "string" | "number" | "boolean" | "object" | "array", options?: {
+        required?: boolean;
+        default?: unknown;
+        description?: string;
+    }): this;
+    /**
+     * Removes a field from the schema.
+     */
+    removeField(name: string): this;
+    /**
+     * Gets a specific field definition.
+     */
+    getField(name: string): DataField | undefined;
+    /**
+     * Gets all fields in the schema.
+     */
+    getFields(): DataField[];
+    /**
+     * Validates data against the schema.
+     */
+    validate(data: Record<string, unknown>): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Applies default values to data.
+     */
+    applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Serializes the schema to JSON.
+     */
+    toJSON(): Record<string, DataField>;
+}

package/dist/database/MiniDataBuilder.js

@@ -0,0 +1,98 @@
+/**
+ * Builder for defining data schemas in MiniDatabase.
+ * Provides a fluent API for developers to define their data structure.
+ *
+ * @example
+ * ```typescript
+ * const userSchema = new MiniDataBuilder()
+ *   .addField("userId", "string", { required: true })
+ *   .addField("username", "string", { required: true })
+ *   .addField("coins", "number", { default: 0 })
+ *   .addField("metadata", "object", { default: {} });
+ * ```
+ */
+export class MiniDataBuilder {
+    fields = new Map();
+    /**
+     * Adds a field to the data schema.
+     */
+    addField(name, type, options) {
+        this.fields.set(name, {
+            name,
+            type,
+            required: options?.required ?? false,
+            default: options?.default,
+            description: options?.description,
+        });
+        return this;
+    }
+    /**
+     * Removes a field from the schema.
+     */
+    removeField(name) {
+        this.fields.delete(name);
+        return this;
+    }
+    /**
+     * Gets a specific field definition.
+     */
+    getField(name) {
+        return this.fields.get(name);
+    }
+    /**
+     * Gets all fields in the schema.
+     */
+    getFields() {
+        return Array.from(this.fields.values());
+    }
+    /**
+     * Validates data against the schema.
+     */
+    validate(data) {
+        const errors = [];
+        for (const field of this.fields.values()) {
+            const value = data[field.name];
+            // Check required fields
+            if (field.required && (value === undefined || value === null)) {
+                errors.push(`Field "${field.name}" is required`);
+                continue;
+            }
+            // Check type if value exists
+            if (value !== undefined && value !== null) {
+                const actualType = Array.isArray(value) ? "array" : typeof value;
+                if (actualType !== field.type) {
+                    errors.push(`Field "${field.name}" must be of type "${field.type}", got "${actualType}"`);
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    }
+    /**
+     * Applies default values to data.
+     */
+    applyDefaults(data) {
+        const result = { ...data };
+        for (const field of this.fields.values()) {
+            if (result[field.name] === undefined && field.default !== undefined) {
+                result[field.name] =
+                    typeof field.default === "object"
+                        ? JSON.parse(JSON.stringify(field.default))
+                        : field.default;
+            }
+        }
+        return result;
+    }
+    /**
+     * Serializes the schema to JSON.
+     */
+    toJSON() {
+        const result = {};
+        for (const [key, field] of this.fields) {
+            result[key] = field;
+        }
+        return result;
+    }
+}

package/dist/database/MiniDatabase.d.ts

@@ -0,0 +1,66 @@
+import type { MiniDataBuilder } from "./MiniDataBuilder.js";
+import type { DatabaseConfig } from "./MiniDatabaseBuilder.js";
+/**
+ * MiniDatabase provides async data storage backed by MongoDB.
+ * Designed to work seamlessly with Vercel and other serverless environments.
+ *
+ * @example
+ * ```typescript
+ * const db = new MiniDatabase(config, schema);
+ *
+ * // Get data
+ * const user = await db.get("user123");
+ *
+ * // Set data
+ * await db.set("user123", { username: "john", coins: 100 });
+ *
+ * // Update data
+ * await db.update("user123", { coins: 150 });
+ * ```
+ */
+export declare class MiniDatabase {
+    private config;
+    private schema?;
+    private mongoClient?;
+    private mongoDb?;
+    private mongoCollection?;
+    private initPromise?;
+    /**
+     * Creates a MiniDatabase instance using an environment variable for the MongoDB URI.
+     * Defaults to the `MONGODB_URI` variable expected by Vercel and many hosting providers.
+     */
+    static fromEnv(schema?: MiniDataBuilder, options?: {
+        variable?: string;
+        dbName?: string;
+        collectionName?: string;
+    }): MiniDatabase;
+    constructor(config: DatabaseConfig, schema?: MiniDataBuilder);
+    /**
+     * Initializes the database connection.
+     */
+    private initialize;
+    /**
+     * Initializes MongoDB connection.
+     */
+    private initializeMongoDB;
+    /**
+     * Gets data by key.
+     */
+    get(key: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Sets data by key (overwrites existing data).
+     */
+    set(key: string, data: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Updates specific fields in data (merges with existing data).
+     */
+    update(key: string, updates: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Deletes data by key.
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Closes the database connection (for MongoDB).
+     */
+    close(): Promise<void>;
+}