@hotbunny/hackhub-content-sdk 0.5.2 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @hotbunny/hackhub-content-sdk
 
-Type definitions and API reference for creating HackHub mods.
+Type definitions and build tools for creating HackHub mods.
 
 ## Quick Start
 
@@ -26,18 +26,28 @@ import {
     Quest,
     Events,
     Network,
+    Random,
     RegisterModPackage,
     RegisterQuest,
 } from "@hotbunny/hackhub-content-sdk";
 
-@RegisterModPackage()
+@RegisterModPackage
 class MyMod extends Bootstrap {
+    Settings = [
+        { key: "difficulty", label: "Difficulty", type: "select" as const, default: "normal", options: [
+            { label: "Easy", value: "easy" },
+            { label: "Normal", value: "normal" },
+            { label: "Hard", value: "hard" },
+        ]},
+        { key: "showHints", label: "Show Hints", type: "toggle" as const, default: true },
+    ];
+
     OnModPackageLoaded() {
         console.log("My mod loaded!");
     }
 }
 
-@RegisterQuest()
+@RegisterQuest
 class MyQuest extends Quest {
     definition = {
         name: "MyQuest",
@@ -57,11 +67,13 @@ class MyQuest extends Quest {
     };
 
     OnStart() {
+        const targetIp = Random.pick(["10.0.0.1", "10.0.0.2", "10.0.0.3"]);
+
         Network.createSubnetNetwork({
-            ip: "10.0.0.1",
+            ip: targetIp,
             type: "ROUTER",
             ports: [{ external: 80, internal: 80, active: true, service: "http" }],
-            users: [Network.createUser({ username: "admin" })],
+            users: [Network.createUser({ username: "admin", password: Random.password() })],
             children: [],
         });
     }
@@ -74,8 +86,8 @@ class MyQuest extends Quest {
 
 | Class | Purpose |
 |-------|---------|
-| `Bootstrap` | Mod entry point, receives lifecycle callbacks |
-| `Quest` | Define custom quests with objectives and rewards |
+| `Bootstrap` | Mod entry point with lifecycle callbacks, settings, and manifest |
+| `Quest` | Define custom quests with objectives, rewards, mail, and dialogs |
 | `Website` | Add in-game websites to the browser |
 | `Command` | Register custom terminal commands |
 | `App` | Create desktop applications |
@@ -84,11 +96,12 @@ class MyQuest extends Quest {
 
 | Namespace | Purpose |
 |-----------|---------|
-| `Events` | Listen to game events, emit custom cross-mod events |
+| `Events` | Listen to 60+ game events, emit custom cross-mod events |
 | `Files` | Create, read, write, delete files in the game filesystem |
 | `Network` | Create networks, manage ports, firewalls, domains |
 | `Mail` | Send in-game emails |
 | `Bank` | Manage bank transactions |
+| `Random` | Random generation helpers (id, uuid, number, password, username, pick, sleep) |
 | `Storage` | Persistent key-value storage (per-mod) |
 | `Variables` | Session-only variables (per-mod, reset on game close) |
 | `SharedStorage` | Persistent storage shared between mods |
@@ -102,11 +115,67 @@ class MyQuest extends Quest {
 ### Decorators
 
 ```typescript
-@RegisterModPackage()   // Register the mod's Bootstrap class
-@RegisterQuest()        // Register a Quest
-@RegisterWebsite()      // Register a Website
-@RegisterCommand()      // Register a terminal Command
-@RegisterApp()          // Register a desktop App
+@RegisterModPackage   // Register the mod's Bootstrap class
+@RegisterQuest        // Register a Quest
+@RegisterWebsite      // Register a Website
+@RegisterCommand      // Register a terminal Command
+@RegisterApp          // Register a desktop App
+```
+
+## Mod Settings
+
+Mods can define settings that players can configure from the in-game Mods menu.
+
+### Declarative Settings
+
+Define a `Settings` array on your Bootstrap class:
+
+```typescript
+@RegisterModPackage
+class MyMod extends Bootstrap {
+    Settings = [
+        { key: "difficulty", label: "Difficulty", type: "select" as const, default: "normal", options: [
+            { label: "Easy", value: "easy" },
+            { label: "Normal", value: "normal" },
+            { label: "Hard", value: "hard" },
+        ]},
+        { key: "showHints", label: "Show Hints", type: "toggle" as const, default: true },
+        { key: "volume", label: "Volume", type: "slider" as const, default: 50, min: 0, max: 100, step: 5 },
+        { key: "playerName", label: "Player Name", type: "text" as const, default: "Player" },
+    ];
+}
+```
+
+Setting values are stored in mod-scoped storage and can be read with `Storage.get("key")`.
+
+Available types: `toggle`, `select`, `text`, `number`, `slider`.
+
+### Custom HTML Settings
+
+For advanced settings panels, provide an HTML file:
+
+```typescript
+@RegisterModPackage
+class MyMod extends Bootstrap {
+    SettingsHTML = "settings.html";
+}
+```
+
+The HTML file is rendered in a sandboxed iframe within the Mods menu.
+
+## Random Helpers
+
+```typescript
+import { Random } from "@hotbunny/hackhub-content-sdk";
+
+Random.id();                    // Short unique ID (default 10 chars)
+Random.uuid();                  // UUID v4
+Random.number(1, 100);          // Random integer between 1-100
+Random.password();              // Random password from game's list
+Random.username();              // Random username from game's list
+Random.pick(["a", "b", "c"]);   // Random element from array
+Random.pickMultiple(arr, 3);    // 3 unique random elements
+await Random.sleep(2000);       // Wait 2 seconds
 ```
 
 ## Events
@@ -117,6 +186,14 @@ class MyQuest extends Quest {
 Events.on("Terminal.NmapScan", (data) => {
     console.log(`Player scanned ${data.ip}`);
 });
+
+Events.on("Bettercap.Open", () => {
+    console.log("Player opened Bettercap");
+});
+
+Events.on("Process.Killed", (data) => {
+    console.log(`Process ${data.name} was killed`);
+});
 ```
 
 ### Custom Cross-Mod Events
@@ -136,6 +213,76 @@ Events.on("MyMod.BossDefeated", (data) => {
 });
 ```
 
+## Quest Mail & Dialogs
+
+Quests can send in-game emails and start phone call dialogs:
+
+```typescript
+@RegisterQuest
+class MyQuest extends Quest {
+    Mails = [
+        { title: "Mission Briefing", content: "Your target is...", replyable: false },
+    ];
+
+    Dialog = {
+        default: [
+            { speaker: "Handler", text: "Are you ready?", options: [
+                { label: "Yes", text: "I'm ready.", switchBranch: "briefing" },
+                { label: "No", text: "Not yet.", isEnd: true },
+            ]},
+        ],
+        briefing: [
+            { speaker: "Handler", text: "Good luck.", isEnd: true },
+        ],
+    };
+
+    OnStart() {
+        this.sendMail(0);
+        this.createDialog("default");
+    }
+}
+```
+
+## Manifest
+
+Each mod requires a `manifest.json`:
+
+```json
+{
+    "id": "my-unique-mod-id",
+    "name": "My Mod",
+    "version": "1.0.0",
+    "author": "Your Name",
+    "description": "What the mod does",
+    "apiVersion": 1,
+    "permissions": ["filesystem", "network", "events"],
+    "cover": "cover.png",
+    "tags": ["quest", "network"],
+    "dependencies": [],
+    "workshopId": ""
+}
+```
+
+### Permissions
+
+| Permission | Required for |
+|------------|-------------|
+| `filesystem` | Files API |
+| `network` | Network API |
+| `events` | Events API |
+| `mail` | Mail API |
+| `bank` | Bank API |
+| `shell` | Shell API |
+| `ui` | UI API |
+
+## Steam Workshop
+
+Mods can be published to and downloaded from Steam Workshop directly from the in-game Mods menu.
+
+- **Browse**: View and manage your Workshop subscriptions
+- **Upload**: Publish local mods to Workshop with cover image, tags, and change notes
+- **Auto-discovery**: Subscribed Workshop mods are automatically loaded on game start
+
 ## License
 
 MIT

package/build.mjs

@@ -4,6 +4,12 @@ import path from "node:path";
 const ASSET_EXTS = /\.(png|jpg|jpeg|gif|svg|ico|webp|css|js|cur|woff|woff2|ttf|eot|mp3|wav|ogg|mp4|webm|json|pdf)$/i;
 const SRC_ASSET_PATTERN = /["'](\.[^"']+?\.(png|jpg|jpeg|gif|svg|ico|webp|css|js|cur|woff|woff2|ttf|eot|mp3|wav|ogg|mp4|webm|json|pdf))["']/gi;
 
+// ─── SDK project schema version ─────────────────────────────────────
+// Bump this when the required project structure changes (new files,
+// new manifest fields, tsconfig options, etc.). buildMod() compares
+// it against the project's saved version and runs migrations.
+const PROJECT_SCHEMA_VERSION = 1;
+
 function copyDirSync(src, dest) {
     fs.mkdirSync(dest, { recursive: true });
     for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -40,11 +46,6 @@ function collectFilesRecursive(dir, ext, results = []) {
     return results;
 }
 
-/**
- * Scans all .ts/.tsx files in src/ for relative path strings that
- * reference asset files (images, scripts, styles, etc.) and copies
- * them into dist/ so they're available via mod-asset:// at runtime.
- */
 function scanSourceAssets() {
     const sourceFiles = collectFilesRecursive("src", [".ts", ".tsx"]);
     let copied = 0;
@@ -71,10 +72,112 @@ function scanSourceAssets() {
     return copied;
 }
 
+// ─── Required file templates ────────────────────────────────────────
+// Each entry defines a file that must exist in the mod project.
+// If missing, it's auto-created from the template.
+
+const REQUIRED_FILES = {
+    "src/types.d.ts": {
+        content: `declare module "*.html" {\n    const value: string;\n    export default value;\n}\n`,
+        description: "HTML import type declarations",
+    },
+};
+
+// Fields that must exist in manifest.json (with defaults)
+const REQUIRED_MANIFEST_FIELDS = {
+    apiVersion: "1.0",
+};
+
+// Required tsconfig.json compilerOptions
+const REQUIRED_TSCONFIG_OPTIONS = {
+    experimentalDecorators: true,
+    strict: true,
+};
+
 /**
- * esbuild plugin: scans HTML files for local asset references
- * (script src, link href, img src) and copies them into dist/.
+ * Validates project structure and auto-fixes missing/outdated files.
+ * Returns a list of actions taken.
  */
+function validateProject() {
+    const actions = [];
+
+    // 1. Check required files
+    for (const [filePath, spec] of Object.entries(REQUIRED_FILES)) {
+        if (!fs.existsSync(filePath)) {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, spec.content, "utf-8");
+            actions.push(`Created missing file: ${filePath} (${spec.description})`);
+        }
+    }
+
+    // 2. Check manifest.json required fields
+    if (fs.existsSync("manifest.json")) {
+        const raw = fs.readFileSync("manifest.json", "utf-8");
+        const manifest = JSON.parse(raw);
+        let changed = false;
+
+        for (const [key, defaultValue] of Object.entries(REQUIRED_MANIFEST_FIELDS)) {
+            if (!(key in manifest)) {
+                manifest[key] = defaultValue;
+                changed = true;
+                actions.push(`Added missing manifest field: "${key}" = "${defaultValue}"`);
+            }
+        }
+
+        if (changed) {
+            fs.writeFileSync("manifest.json", JSON.stringify(manifest, null, 4) + "\n", "utf-8");
+        }
+    } else {
+        actions.push("WARNING: manifest.json not found!");
+    }
+
+    // 3. Check tsconfig.json required options
+    if (fs.existsSync("tsconfig.json")) {
+        const raw = fs.readFileSync("tsconfig.json", "utf-8");
+        let tsconfig;
+        try {
+            tsconfig = JSON.parse(raw);
+        } catch {
+            actions.push("WARNING: tsconfig.json has invalid JSON");
+            return actions;
+        }
+
+        if (!tsconfig.compilerOptions) tsconfig.compilerOptions = {};
+        let changed = false;
+
+        for (const [key, value] of Object.entries(REQUIRED_TSCONFIG_OPTIONS)) {
+            if (tsconfig.compilerOptions[key] !== value) {
+                tsconfig.compilerOptions[key] = value;
+                changed = true;
+                actions.push(`Fixed tsconfig option: "${key}" → ${value}`);
+            }
+        }
+
+        if (changed) {
+            fs.writeFileSync("tsconfig.json", JSON.stringify(tsconfig, null, 4) + "\n", "utf-8");
+        }
+    }
+
+    // 4. Check public/ directory exists
+    if (!fs.existsSync("public")) {
+        fs.mkdirSync("public", { recursive: true });
+        actions.push("Created missing public/ directory");
+    }
+
+    // 5. Update schema version stamp
+    const stampFile = "node_modules/.hackhub-schema-version";
+    const currentStamp = fs.existsSync(stampFile) ? parseInt(fs.readFileSync(stampFile, "utf-8").trim(), 10) : 0;
+    if (currentStamp < PROJECT_SCHEMA_VERSION) {
+        fs.mkdirSync(path.dirname(stampFile), { recursive: true });
+        fs.writeFileSync(stampFile, String(PROJECT_SCHEMA_VERSION), "utf-8");
+        if (currentStamp > 0) {
+            actions.push(`Project schema updated: v${currentStamp} → v${PROJECT_SCHEMA_VERSION}`);
+        }
+    }
+
+    return actions;
+}
+
 export function htmlAssetsPlugin() {
     const assetPattern = /(?:src|href)\s*=\s*["'](\.[^"']+)["']/g;
 
@@ -107,10 +210,10 @@ export function htmlAssetsPlugin() {
 
 function log(msg) { process.stdout.write(`\x1b[36m[HackHub]\x1b[0m ${msg}\n`); }
 function logSuccess(msg) { process.stdout.write(`\x1b[32m[HackHub]\x1b[0m ${msg}\n`); }
+function logWarn(msg) { process.stdout.write(`\x1b[33m[HackHub]\x1b[0m ${msg}\n`); }
 
 /**
  * Builds a HackHub mod project.
- * Call this from your esbuild.config.ts — all build logic is handled here.
  *
  * @param {object} [options]
  * @param {string} [options.entryPoint] - Entry file (default: "src/index.ts")
@@ -122,12 +225,18 @@ export async function buildMod(options = {}) {
     const isWatch = process.argv.includes("--watch");
     const start = Date.now();
 
-    log("Preparing dist...");
+    // Validate & auto-fix project structure
+    const fixes = validateProject();
+    for (const fix of fixes) {
+        if (fix.startsWith("WARNING")) logWarn(fix);
+        else logWarn(`Auto-fix: ${fix}`);
+    }
+
     prepareDist();
 
     const assetCount = scanSourceAssets();
     if (assetCount > 0) {
-        log(`Copied ${assetCount} asset(s) from source files`);
+        log(`Copied ${assetCount} asset(s)`);
     }
 
     const outfile = options.outfile || "dist/mod.js";
@@ -152,11 +261,13 @@ export async function buildMod(options = {}) {
                 {
                     name: "rebuild-notify",
                     setup(build) {
+                        let rebuildStart = Date.now();
+                        build.onStart(() => { rebuildStart = Date.now(); });
                         build.onEnd((result) => {
                             if (result.errors.length === 0) {
                                 prepareDist();
                                 scanSourceAssets();
-                                logSuccess(`Rebuilt in ${Date.now() - start}ms → ${outfile}`);
+                                logSuccess(`Rebuilt in ${Date.now() - rebuildStart}ms → ${outfile}`);
                             }
                         });
                     },

package/index.d.ts

@@ -180,6 +180,61 @@ export interface WeeChatMessageDefinition {
 	/** Callback fired after this message is sent. */
 	onSent?: () => void | Promise<void>;
 }
+/** A mail message sent during a quest (e.g. from an employer NPC). */
+export interface QuestMailDefinition {
+	/** Mail subject line. */
+	title: string;
+	/** Mail body content (plain text or HTML string). */
+	content: string;
+	/** If true, the player can reply to this mail. */
+	replyable?: boolean;
+	/** Attachment file to include with the mail. */
+	attachment?: {
+		name: string;
+		extension?: string;
+		content?: string;
+	};
+}
+/** A phone-call dialog tree for quests. Keys are branch names. */
+export interface QuestDialogDefinition {
+	[branchName: string]: QuestDialogSpeech[];
+}
+/** A single speech line in a phone-call dialog. */
+export interface QuestDialogSpeech {
+	/** Who is speaking (NPC name or "player"). */
+	speaker: string;
+	/** The spoken text. */
+	text: string;
+	/** Audio file path (resolved via mod-asset://). Empty string if none. */
+	audio?: string;
+	/** If true, this is the last line and the call ends. */
+	isEnd?: boolean;
+	/** Delay in ms before the next line auto-plays. */
+	timeout?: number;
+	/** Callback fired when this speech line ends. */
+	onEnd?: () => void;
+	/** Player response options (branching). */
+	options?: QuestDialogOption[];
+}
+/** A selectable response option in a dialog. */
+export interface QuestDialogOption {
+	/** Short label shown on the button. */
+	label: string;
+	/** Full text the player says. */
+	text: string;
+	/** Audio file path. Empty string if none. */
+	audio?: string;
+	/** Switch to a different dialog branch by name. */
+	switchBranch?: string;
+	/** Jump to a specific index within the current/target branch. */
+	nextIndex?: number;
+	/** If true, the call ends after this option. */
+	isEnd?: boolean;
+	/** Delay in ms before proceeding. */
+	timeout?: number;
+	/** Callback fired when this option is selected. */
+	onSelect?: () => void;
+}
 /**
  * Game events that mods can listen to.
  * This is a curated subset of the internal GameEvents, exposing only
@@ -390,6 +445,120 @@ export interface RemoteConnectionDisconnectedEvent {
 	ip: string;
 	service?: string;
 }
+export interface TerminalCdEvent {
+	path: string;
+}
+export interface TerminalLsEvent {
+	id: string;
+	name: string;
+}
+export interface TerminalOpensslEvent {
+	file: string;
+}
+export interface TerminalSSHShutdownEvent {
+	ip: string;
+}
+export interface TerminalLynxSearchEvent {
+	query: string;
+}
+export interface TerminalLynxLookupEvent {
+	data: any;
+}
+export interface TerminalMxlookupEvent {
+	domain: string;
+	ip: string;
+}
+export interface TerminalIfconfigEvent {
+	terminalIp: string;
+}
+export interface MetasploitMsfconsoleEvent {
+}
+export interface MetasploitShowOptionsEvent {
+	name: string;
+	type: string;
+}
+export interface MetasploitSetOptionEvent {
+	name: string;
+	value: string | number;
+	allFilled: boolean;
+}
+export interface MetasploitRootgrabEvent {
+	ip: string;
+	file: {
+		id: string;
+		name: string;
+	};
+}
+export interface MeterpreterDownloadEvent {
+	host: string;
+	file: {
+		id: string;
+		name: string;
+	};
+}
+export interface SubfinderResultsEvent {
+	domain: string;
+	subdomains: any[];
+}
+export interface NucleiResultsEvent {
+	file: any;
+	hosts: string[];
+}
+export interface HashcatEvent {
+	id: string;
+	name: string;
+}
+export interface JohnDecryptHashEvent {
+	hash: string;
+	password: string;
+}
+export interface FernFindPasswordEvent {
+	user: any;
+	model: string;
+}
+export interface BettercapOpenEvent {
+}
+export interface BettercapCloseEvent {
+}
+export interface BettercapNetProbeEvent {
+	active: boolean;
+}
+export interface BettercapNetShowEvent {
+}
+export interface BettercapWifiReconEvent {
+}
+export interface BettercapWifiDeAuthEvent {
+}
+export interface MailMailboxOpenedEvent {
+	from: string;
+	to: string;
+	subject: string;
+}
+export interface TwotterAccountLogoutEvent {
+	id: string;
+	username: string;
+}
+export interface BrowserMetaEvent {
+	title: string;
+	url: string;
+}
+export interface ProcessKilledEvent {
+	pid: number;
+	name: string;
+}
+export interface WiresharkStartedEvent {
+	interface: string;
+}
+export interface WiresharkStoppedEvent {
+	interface: string;
+}
+export interface Python3ExecFileEvent {
+	args: string[];
+	file: any;
+}
+export interface BCCNewsOpenedEvent {
+	articleId: string;
+}
 /**
  * Map of event names to their payload types.
  * Mod authors use these as: Events.on("Terminal.NmapScan", (data) => { ... })
@@ -461,6 +630,38 @@ export interface ModEventMap {
 	"RemoteConnection.Established": RemoteConnectionEstablishedEvent;
 	"RemoteConnection.Disconnected": RemoteConnectionDisconnectedEvent;
 	"AppStore.Downloaded": string;
+	"Terminal.Cd": TerminalCdEvent;
+	"Terminal.Ls": TerminalLsEvent;
+	"Terminal.Openssl": TerminalOpensslEvent;
+	"Terminal.SSH.Shutdown": TerminalSSHShutdownEvent;
+	"Terminal.Lynx.Search": TerminalLynxSearchEvent;
+	"Terminal.Lynx.Lookup": TerminalLynxLookupEvent;
+	"Terminal.Mxlookup": TerminalMxlookupEvent;
+	"Terminal.Ifconfig": TerminalIfconfigEvent;
+	"Metasploit.Msfconsole": MetasploitMsfconsoleEvent;
+	"Metasploit.ShowOptions": MetasploitShowOptionsEvent;
+	"Metasploit.SetOption": MetasploitSetOptionEvent;
+	"Metasploit.Rootgrab": MetasploitRootgrabEvent;
+	"Meterpreter.Download": MeterpreterDownloadEvent;
+	"Subfinder.Results": SubfinderResultsEvent;
+	"Nuclei.Results": NucleiResultsEvent;
+	"Hashcat": HashcatEvent;
+	"John.DecryptHash": JohnDecryptHashEvent;
+	"Fern.FindPassword": FernFindPasswordEvent;
+	"Bettercap.Open": BettercapOpenEvent;
+	"Bettercap.Close": BettercapCloseEvent;
+	"Bettercap.NetProbe": BettercapNetProbeEvent;
+	"Bettercap.NetShow": BettercapNetShowEvent;
+	"Bettercap.WifiRecon": BettercapWifiReconEvent;
+	"Bettercap.WifiDeAuth": BettercapWifiDeAuthEvent;
+	"Mail.MailboxOpened": MailMailboxOpenedEvent;
+	"Twotter.AccountLogout": TwotterAccountLogoutEvent;
+	"Browser.Meta": BrowserMetaEvent;
+	"Process.Killed": ProcessKilledEvent;
+	"Wireshark.Started": WiresharkStartedEvent;
+	"Wireshark.Stopped": WiresharkStoppedEvent;
+	"Python3.ExecFile": Python3ExecFileEvent;
+	"BCC.News.Opened": BCCNewsOpenedEvent;
 }
 export type ModEventName = keyof ModEventMap;
 export type ModEventCallback<T extends ModEventName> = (data: ModEventMap[T]) => void;
@@ -711,6 +912,9 @@ export interface ModManifest {
 	dependencies?: string[];
 	permissions?: ModPermission[];
 	icon?: string;
+	cover?: string;
+	workshopId?: string;
+	tags?: string[];
 }
 export type ModPermission = "filesystem" | "network" | "events" | "mail" | "bank" | "shell" | "ui";
 export interface ModInfo {
@@ -720,8 +924,13 @@ export interface ModInfo {
 	author: string;
 	description: string;
 	icon?: string;
+	cover?: string;
 	enabled: boolean;
+	status?: ModStatus;
 	error?: string;
+	permissions?: ModPermission[];
+	workshopId?: string;
+	tags?: string[];
 }
 export declare enum ModStatus {
 	Pending = "PENDING",
@@ -730,6 +939,19 @@ export declare enum ModStatus {
 	Error = "ERROR",
 	Disabled = "DISABLED"
 }
+export interface ModSettingDefinition {
+	key: string;
+	label: string;
+	type: "toggle" | "select" | "text" | "number" | "slider";
+	default: any;
+	options?: {
+		label: string;
+		value: string;
+	}[];
+	min?: number;
+	max?: number;
+	step?: number;
+}
 export interface TwotterCreateUserOptions {
 	id?: string;
 	username?: string;
@@ -828,19 +1050,28 @@ export interface WeeChatServer {
  *
  * @RegisterModPackage
  * export class MyMod extends Bootstrap {
+ *     Settings = [
+ *         { key: "difficulty", label: "Difficulty", type: "select" as const, default: "normal", options: [
+ *             { label: "Easy", value: "easy" },
+ *             { label: "Normal", value: "normal" },
+ *             { label: "Hard", value: "hard" },
+ *         ]},
+ *         { key: "showHints", label: "Show Hints", type: "toggle" as const, default: true },
+ *     ];
+ *
  *     OnModPackageLoaded() {
  *         console.log("My mod has been loaded!");
  *     }
- *
- *     OnModPackageUnloaded() {
- *         console.log("My mod has been unloaded.");
- *     }
  * }
  * ```
  */
 export declare abstract class Bootstrap {
 	/** The parsed manifest.json of this mod. Set by the loader at runtime. */
 	Manifest: ModManifest;
+	/** Declarative settings definitions rendered in the Mods UI. */
+	Settings?: ModSettingDefinition[];
+	/** Path to an HTML file for a custom settings panel (rendered in iframe). */
+	SettingsHTML?: string;
 	/** Called after the mod package and all its registered content are loaded. */
 	OnModPackageLoaded(): void | Promise<void>;
 	/** Called when the mod is being unloaded (e.g. disabled by user). */
@@ -894,6 +1125,10 @@ export declare abstract class Quest {
 	KisscordChats?: KisscordChatDefinition[];
 	/** WeeChat (IRC) chat chains for this quest. */
 	WeeChatChats?: WeeChatChatDefinition[];
+	/** Mail messages that can be sent during the quest via this.sendMail(index). */
+	Mails?: QuestMailDefinition[];
+	/** Phone-call dialog tree for this quest. Use this.createDialog(branch) to start. */
+	Dialog?: QuestDialogDefinition;
 	/**
 	 * Called when the quest is first claimed/started.
 	 * Use this to set up event listeners for objective completion.
@@ -909,6 +1144,12 @@ export declare abstract class Quest {
 	CreateData(): any;
 	/** Complete an objective by its name. */
 	completeObjective(name: string): void;
+	/** Send a mail from the Mails array by index. */
+	sendMail(index: number, from?: string, to?: string): void;
+	/** Start a phone-call dialog. Defaults to "default" branch. */
+	createDialog(branch?: string, startIndex?: number): void;
+	/** @internal */ _sendMailInternal?: (index: number, from?: string, to?: string) => void;
+	/** @internal */ _createDialogInternal?: (branch: string, startIndex: number) => void;
 }
 /**
  * Base class for mod websites. Mod authors extend this to create
@@ -1576,6 +1817,40 @@ export declare namespace WeeChat {
 	export function getHistory(host?: string): WeeChatMessage[];
 	export {};
 }
+/**
+ * Random generation helpers for mod authors.
+ *
+ * @example
+ * ```ts
+ * import { Random } from "@hotbunny/hackhub-content-sdk";
+ *
+ * const uniqueId = Random.id();
+ * const pin = Random.number(1000, 9999);
+ * const pass = Random.password();
+ * const user = Random.username();
+ * const winner = Random.pick(["Alice", "Bob", "Charlie"]);
+ * await Random.sleep(2000);
+ * ```
+ */
+export declare namespace Random {
+	/** Generate a short unique ID. Default length is 10. */
+	export function id(length?: number): string;
+	/** Generate a UUID (v4-like). */
+	export function uuid(): string;
+	/** Generate a random integer between min and max (inclusive). */
+	export function number(min?: number, max?: number): number;
+	/** Get a random password from the game's password list. */
+	export function password(): string;
+	/** Get a random username from the game's username list. */
+	export function username(): string;
+	/** Pick a random element from an array. */
+	export function pick<T>(array: T[]): T;
+	/** Pick multiple unique random elements from an array. */
+	export function pickMultiple<T>(array: T[], count: number): T[];
+	/** Sleep for the given number of milliseconds. */
+	export function sleep(ms: number): Promise<void>;
+	export {};
+}
 /**
  * Marks a class as the mod's entry point.
  * Each mod must have exactly one @RegisterModPackage class extending Bootstrap.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotbunny/hackhub-content-sdk",
-    "version": "0.5.2",
+    "version": "0.9.0",
     "description": "Type definitions and build tools for HackHub mod development",
     "types": "index.d.ts",
     "exports": {