diff --git a/.env.example b/.env.example index 01283eb..570902f 100644 --- a/.env.example +++ b/.env.example @@ -3,7 +3,9 @@ ANNOUNCE_CHANNEL="-1002648883359" DEVICE=vps ADMIN_IDS=YOUR_TELEGRAM_USER_ID BOT_TOKEN= -WEBAPP_HMAC_KEY= # 32-byte secret for HMAC-signing webapp payloads/CSRF tokens; generate with: openssl rand -hex 32 (or openssl rand -base64 32); keep secret and never commit real values +# WEBAPP_HMAC_KEY: 32-byte secret for HMAC-signing webapp payloads/CSRF tokens. +# Generate with: openssl rand -hex 32 (or openssl rand -base64 32). Keep secret; never commit real values. +WEBAPP_HMAC_KEY="" TELEGRAM_BOT_TOKEN= DISCORD_CODE_GENERATION_IMAGE_URL=https://raw.githubusercontent.com/gamblecodezcom/Runewager/main/images/discord_code_generation.png DISCORD_VERIFY_IMAGE_URL=https://raw.githubusercontent.com/gamblecodezcom/Runewager/main/images/discord_verify.png @@ -14,6 +16,7 @@ MAX_ONBOARDING_STEPS_HISTORY=500 MINI_APP_CLAIM_URL=https://t.me/RuneWager_bot/claim MINI_APP_PLAY_URL=https://t.me/RuneWager_bot/Play MINI_APP_PROFILE_URL=https://t.me/RuneWager_bot/profile +# LOG_LEVEL valid values: debug, info, warn, error (default: info) LOG_LEVEL=info PORT=3000 RW_DISCORD_JOIN=https://discord.gg/runewagers diff --git a/.gitignore b/.gitignore index 95cca36..a9a87fb 100644 --- a/.gitignore +++ b/.gitignore @@ -28,14 +28,6 @@ Thumbs.db .last_rollback data/admin-events.log -# Runtime state files -data/analytics.json -data/dashboard.json -data/helpful_messages.json -data/promo-history.json -data/runtime-state.json -data/sshv-sessions.json - # Runtime generated data + backups data/*.json data/backups/** diff --git a/CLAUDE.md b/CLAUDE.md index fb904a3..66646d7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -148,3 +148,12 @@ You are the Runewager Bot Ops Commander. You manage the full lifecycle of the Ru Before writing or modifying any code, the AI must always read and familiarize itself with `RUNEWAGER_FUNCTIONALITY_MAP.md`. This file is the authoritative source of truth for all bot functionality. The AI must keep this file updated with full, easy-to-understand descriptions whenever functionality is added, changed, or removed. Updating this file is a required step at the end of every coding session. After generating or modifying any functionality, the AI must run a follow-up audit to ensure the `RUNEWAGER_FUNCTIONALITY_MAP.md` file is fully updated and accurate. No coding session is complete until the map is updated and verified. + + +Every coding session must end with a verification pass to detect and upgrade any missing functionality, followed by an update to RUNEWAGER_FUNCTIONALITY_MAP.md. No work is considered complete until the map is fully updated and verified. + + +Every coding session must begin by reading RUNEWAGER_FUNCTIONALITY_MAP.md and must end with a full 50โ€‘point verification pass. No work is complete until the map is updated and all 50 checks pass with zero failures. + + +Every coding session must begin by reading RUNEWAGER_FUNCTIONALITY_MAP.md and must end with a full docstring verification pass. No work is complete until every function has a complete docstring and the map is fully updated. diff --git a/RUNEWAGER_FUNCTIONALITY_MAP.md b/RUNEWAGER_FUNCTIONALITY_MAP.md index 416935c..ba34f1e 100644 --- a/RUNEWAGER_FUNCTIONALITY_MAP.md +++ b/RUNEWAGER_FUNCTIONALITY_MAP.md @@ -169,6 +169,7 @@ Restrictions: ## 13. Full Command Index (User + Admin) ### User-facing commands (also includes aliases) +_Note: unknown-command guard uses `REGISTERED_COMMANDS`; parity is now validated by smoke test to prevent silent command breakage._ `affiliate, bonus, bugreport, cancel, checkin, claim_history, commands, discord, discord_confirm, eligible, fixaccount, giveaway, gwhistory, health, help, join, leaderboard, leaderboard_weekly, link, linkaccount, linkrunewager, menu, mygiveaways, play, profile, promo, promocheck, referral, settings, signup, startapp, status, stuck, support, top, walkthrough` ### Admin commands @@ -217,6 +218,10 @@ No universal pendingAction timeout/auto-cancel was detected for all user/admin i ## 18. Rate Limits & Cooldowns +### Verification controls +- Smoke test now enforces `REGISTERED_COMMANDS` parity with `bot.command(...)` handlers (except `start`, handled by `bot.start`). + + - Promo-level cooldown and claim-limit checks in eligibility evaluation. - Bonus request lifecycle enforces transition constraints and attempt limits. - Smart button anti-duplicate TTL reduces repeated callback abuse. @@ -263,7 +268,7 @@ Key shared helper families in `index.js`: ## 23. Featureโ€‘Level Flowcharts ### Promo claim flow -``` +```text /promo or menu_claim_bonus -> load active promos -> evaluate eligibility per promo @@ -276,7 +281,7 @@ Key shared helper families in `index.js`: ``` ### Announcement flow -``` +```text admin_cmd_announce_start or /announce -> await_announcement_text -> preview + toggles (DM/Channel/Group + parse mode) @@ -286,7 +291,7 @@ admin_cmd_announce_start or /announce ``` ### Content drop target registration -``` +```text Admin forwards message from channel/group -> autoRegisterForwardedChatIfPresent -> approvedGroupsStore add(chatId) @@ -295,7 +300,7 @@ Admin forwards message from channel/group ``` ### Giveaway start/join -``` +```text Admin starts wizard (gwiz) -> collect config steps -> createGiveaway + announceGiveaway @@ -310,6 +315,11 @@ Admin starts wizard (gwiz) - 2026-02-26: Created initial comprehensive functionality map and synchronized with current menu/state architecture. - 2026-02-26: Added explicit note that template-literal callback IDs are excluded from literal smoke checks. - 2026-02-26: Documented Tests & Bugs admin category, promo step guide, and forwarded-chat auto-registration behavior. +- 2026-02-26: Added command-registry verification notes and synchronized missing admin commands (`/pmapprove`, `/pmdeny`, `/register_chat`, `/verify_bot_setup`). + +- 2026-02-26: Completed a 50-point verification pass, synchronized command registry coverage, and extended smoke checks for command-registration parity. + +- 2026-02-26: Added repo-wide baseline docstrings to named function declarations (runtime, helper, and test modules) and re-verified command/callback coverage. ## 25. AI Coder Contract Requirements diff --git a/index.js b/index.js index fb7aa7f..d440f73 100644 --- a/index.js +++ b/index.js @@ -227,6 +227,36 @@ const helpfulMessagesFile = path.join(dataDir, 'helpful_messages.json'); const sshvSessionsFile = path.join(dataDir, 'sshv-sessions.json'); +/** + + + * normalizeHelpfulMessageEntry executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + + * Parameters: See the function signature for exact argument names and accepted values. + + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + + */ + + function normalizeHelpfulMessageEntry(entry, idHint = null) { if (!entry || typeof entry !== 'object') return null; const text = typeof entry.text === 'string' ? entry.text.trim() : ''; @@ -236,11 +266,51 @@ function normalizeHelpfulMessageEntry(entry, idHint = null) { return { id: Number(id), text, enabled: entry.enabled !== false }; } +/** + + * saveHelpfulMessages executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function saveHelpfulMessages() { const snapshot = tipsStore.tips.map((tip) => ({ text: tip.text, enabled: tip.enabled !== false })); saveJson(helpfulMessagesFile, snapshot); } +/** + + * loadHelpfulMessages executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function loadHelpfulMessages() { const raw = loadJson(helpfulMessagesFile, null); if (!Array.isArray(raw)) return; @@ -347,7 +417,6 @@ const REGISTERED_COMMANDS = new Set([ 'health', 'help', 'join', - 'language', 'leaderboard', 'leaderboard_weekly', 'link', @@ -421,6 +490,26 @@ const WAGER_BONUS_RULES_TEXT = const WAGER_BONUS_IN_FLIGHT_STATUSES = new Set(['pending', 'approved']); const WAGER_BONUS_NON_REQUESTABLE_STATUSES = new Set(['bonus_sent', ...WAGER_BONUS_IN_FLIGHT_STATUSES]); +/** + + * isWagerBonusRequestLocked executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function isWagerBonusRequestLocked(status) { return WAGER_BONUS_NON_REQUESTABLE_STATUSES.has(status); } @@ -432,6 +521,26 @@ const _LOG_MIN_RANK = LOG_LEVEL_RANK[String(process.env.LOG_LEVEL || 'info').toL // Rolling error rate tracker โ€” alerts admins when errors spike const _errorRate = { count: 0, windowStart: Date.now(), alerted: false }; +/** + + * logEvent executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function logEvent(level, message, extra = {}) { const rank = LOG_LEVEL_RANK[level] ?? 1; if (rank < _LOG_MIN_RANK) return; // filtered out by LOG_LEVEL @@ -459,12 +568,52 @@ const ALLOWED_BONUS_STATUS_TRANSITIONS = { bonus_sent: new Set(), }; +/** + + * isValidBonusTransition executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function isValidBonusTransition(fromStatus, toStatus) { if (fromStatus === toStatus) return true; const allowed = ALLOWED_BONUS_STATUS_TRANSITIONS[fromStatus] || new Set(); return allowed.has(toStatus); } +/** + + * runUserMutation executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function runUserMutation(userId, fn) { const previous = userMutationQueue.get(userId) || Promise.resolve(); const next = previous @@ -476,6 +625,26 @@ async function runUserMutation(userId, fn) { return next; } +/** + + * serializeUser executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function serializeUser(user) { return { ...user, @@ -488,6 +657,26 @@ function serializeUser(user) { }; } +/** + + * deserializeUser executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function deserializeUser(rawUser) { const user = { ...rawUser }; user.badges = new Set(rawUser.badges || []); @@ -499,6 +688,26 @@ function deserializeUser(rawUser) { return user; } +/** + + * createRuntimeStateSnapshot executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function createRuntimeStateSnapshot() { return { version: 1, @@ -549,6 +758,26 @@ function createRuntimeStateSnapshot() { }; } +/** + + * serializeGiveaway executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function serializeGiveaway(giveaway) { return { id: Number(giveaway.id), @@ -586,6 +815,26 @@ function serializeGiveaway(giveaway) { }; } +/** + + * deserializeGiveaway executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function deserializeGiveaway(rawGiveaway) { const sanitized = serializeGiveaway(rawGiveaway || {}); return { @@ -596,6 +845,26 @@ function deserializeGiveaway(rawGiveaway) { }; } +/** + + * normalizePromoCodeEntry executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function normalizePromoCodeEntry(raw, idHint = null) { if (!raw || typeof raw !== 'object') return null; const code = String(raw.code || '').trim(); @@ -616,6 +885,26 @@ function normalizePromoCodeEntry(raw, idHint = null) { // Startup warnings deferred until after bot.launch() so Telegram API is available const _startupWarnings = []; +/** + + * loadRuntimeState executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function loadRuntimeState() { // Differentiate "file missing" (normal first start) from "file corrupt" (needs alert) let raw = null; @@ -726,6 +1015,26 @@ function loadRuntimeState() { } } +/** + + * persistRuntimeState executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function persistRuntimeState() { const snapshot = createRuntimeStateSnapshot(); saveJson(runtimeStateFile, snapshot); @@ -733,6 +1042,26 @@ function persistRuntimeState() { lastPersistAt = Date.now(); } +/** + + * createRuntimeBackup executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function createRuntimeBackup() { ensureDataDir(); if (!fs.existsSync(runtimeStateFile)) { @@ -749,10 +1078,50 @@ function createRuntimeBackup() { return target; } +/** + + * consumeAdminAction executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function consumeAdminAction(adminId, actionKey) { return consumeSmartButton(adminId, `admin:${actionKey}`); } +/** + + * createDefaultUser executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function createDefaultUser(user) { return { id: user.id, @@ -822,6 +1191,26 @@ function createDefaultUser(user) { }; } +/** + + * getUser executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function getUser(ctx) { const { id } = ctx.from; if (!userStore.has(id)) userStore.set(id, createDefaultUser(ctx.from)); @@ -902,21 +1291,101 @@ function getUser(ctx) { return user; } +/** + + * isAdmin executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function isAdmin(ctx) { return ADMIN_IDS.includes(Number(ctx.from.id)); } -function persistAdminMode(user, enabled) { - user.adminModeOn = enabled; - persistRuntimeState(); -} +/** -async function refreshAdminMenuHeader(ctx, user) { + * persistAdminMode executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + +function persistAdminMode(user, enabled) { + user.adminModeOn = enabled; + persistRuntimeState(); +} + +/** + + * refreshAdminMenuHeader executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + +async function refreshAdminMenuHeader(ctx, user) { const chatType = ctx.chat && ctx.chat.type ? ctx.chat.type : null; if (chatType !== 'private') return; await sendPersistentAdminMenu(ctx, user); } +/** + + * requireAdmin executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function requireAdmin(ctx) { const cmd = ctx.message ? String(ctx.message.text || '').split(' ')[0].replace('/', '') @@ -952,6 +1421,36 @@ async function sendCommandError(ctx, { command, reason, howToUse, example }) { } +/** + + + * normalizeSshvBufferLines executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + + * Parameters: See the function signature for exact argument names and accepted values. + + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + + */ + + function normalizeSshvBufferLines(bufferValue) { if (Array.isArray(bufferValue)) { return bufferValue.map((line) => escapeMarkdownFull(String(line))).slice(-SSHV_MAX_BUFFER_LINES); @@ -966,10 +1465,50 @@ function normalizeSshvBufferLines(bufferValue) { return []; } +/** + + * stringifySshvBuffer executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function stringifySshvBuffer(bufferValue) { return normalizeSshvBufferLines(bufferValue).join('\n'); } +/** + + * persistSshvSessions executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function persistSshvSessions() { const entries = []; for (const [adminId, session] of sshvSessions.entries()) { @@ -997,6 +1536,26 @@ function persistSshvSessions() { saveJson(sshvSessionsFile, entries); } +/** + + * validateAndFixSshvSession executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function validateAndFixSshvSession(user, session, { onStartup = false } = {}) { const corrections = []; if (!session || !user) return corrections; @@ -1075,6 +1634,26 @@ function validateAndFixSshvSession(user, session, { onStartup = false } = {}) { return corrections; } +/** + + * loadSshvSessions executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function loadSshvSessions() { const raw = loadJson(sshvSessionsFile, []); if (!Array.isArray(raw)) return; @@ -1123,6 +1702,26 @@ function loadSshvSessions() { } } +/** + + * refreshSshvSessionForUser executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function refreshSshvSessionForUser(user) { const existing = getSshvSession(user.id); if (existing) validateAndFixSshvSession(user, existing, { onStartup: false }); @@ -1136,6 +1735,26 @@ function refreshSshvSessionForUser(user) { return session; } +/** + + * getSshvSession executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function getSshvSession(adminId, { createIfMissing = false } = {}) { const existing = sshvSessions.get(adminId); if (existing) { @@ -1168,6 +1787,26 @@ function getSshvSession(adminId, { createIfMissing = false } = {}) { return session; } +/** + + * destroySshvSession executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function destroySshvSession(adminId) { const session = sshvSessions.get(adminId); if (!session) return; @@ -1178,12 +1817,52 @@ function destroySshvSession(adminId) { persistSshvSessions(); } +/** + + * sshvOutputText executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function sshvOutputText(text) { const raw = (text || '').trim() || '[no output yet]'; const clipped = raw.length > 3000 ? `${raw.slice(0, 3000)}\n... (truncated)` : raw; return clipped.replace(/```/g, "'''"); } +/** + + * sshvKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function sshvKeyboard(session) { if (session.locked) { return Markup.inlineKeyboard([ @@ -1198,6 +1877,26 @@ function sshvKeyboard(session) { ]); } +/** + + * renderSshvConsole executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function renderSshvConsole(ctx, session, note = '') { const text = [ '๐Ÿ“Ÿ *Runewager VPS Console*', @@ -1212,6 +1911,26 @@ async function renderSshvConsole(ctx, session, note = '') { await ctx.reply(text, { parse_mode: 'MarkdownV2', ...sshvKeyboard(session) }); } +/** + + * parseCdTarget executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function parseCdTarget(commandText) { const m = commandText.match(/^cd(?:\s+(.*))?$/); if (!m) return null; @@ -1219,11 +1938,51 @@ function parseCdTarget(commandText) { return target || '~'; } +/** + + * resolveCdPath executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function resolveCdPath(currentCwd, target) { if (target === '~') return SSHV_DEFAULT_CWD; return path.resolve(currentCwd, target); } +/** + + * commandNeedsConfirmation executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function commandNeedsConfirmation(commandText) { const text = String(commandText || ''); const patterns = [ @@ -1236,12 +1995,52 @@ function commandNeedsConfirmation(commandText) { return patterns.some((re) => re.test(text)); } +/** + + * commandBlocked executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function commandBlocked(commandText) { const text = String(commandText || ''); const blockedPatterns = [/(^|\s)&(\s|$)/, /&&/, /\|\|/, /\bnohup\b/i, /\bbg\b/i]; return blockedPatterns.some((re) => re.test(text)); } +/** + + * isHealthTlsEnabled executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function isHealthTlsEnabled() { const tlsKeyPath = process.env.HTTPS_KEY_PATH; const tlsCertPath = process.env.HTTPS_CERT_PATH; @@ -1255,6 +2054,26 @@ function isHealthTlsEnabled() { } } +/** + + * buildSshvSandboxRestrictionHint executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function buildSshvSandboxRestrictionHint(err) { const msg = String((err && (err.stderr || err.message)) || '').toLowerCase(); const code = String((err && (err.code || err.errno)) || '').toUpperCase(); @@ -1268,8 +2087,28 @@ function buildSshvSandboxRestrictionHint(err) { return 'Sandbox restriction hit. This service runs with ProtectSystem/PrivateTmp/NoNewPrivileges. Write operations are typically limited to /var/www/html/Runewager/logs and /var/www/html/Runewager/data unless runewager.service ReadWritePaths is expanded.'; } -async function executeSshvCommand(ctx, user, session, commandText) { - const command = String(commandText || '').trim(); +/** + + * executeSshvCommand executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + +async function executeSshvCommand(ctx, user, session, commandText) { + const command = String(commandText || '').trim(); if (!command) { await sendCommandError(ctx, { command: 'sshv', @@ -1503,14 +2342,74 @@ async function showBonusStatus(ctx, user) { await ctx.reply(lines.join('\n'), { parse_mode: 'Markdown', ...Markup.inlineKeyboard(kbRows) }); } +/** + + * signupButton executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function signupButton() { return Markup.button.url('๐Ÿ”— Sign Up on Runewager', LINKS.runewagerSignup); } +/** + + * promoButton executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function promoButton() { return Markup.button.url('๐Ÿ“‹ Open Promo Entry Page', LINKS.promoInput); } +/** + + * miniAppPlayButton executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function miniAppPlayButton() { return Markup.button.url('๐ŸŽฎ Open Runewager (Mini App)', LINKS.miniAppPlay); } @@ -1609,6 +2508,26 @@ function mainMenuKeyboard(isAdminUser = false, page = 1, user = null) { return Markup.inlineKeyboard(rows); } +/** + + * ageGateKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function ageGateKeyboard() { // Note: parse_mode: 'Markdown' must be passed with this keyboard since COPY.ageGate uses Markdown return Markup.inlineKeyboard([ @@ -1617,6 +2536,26 @@ function ageGateKeyboard() { ]); } +/** + + * linkPrefKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function linkPrefKeyboard() { return Markup.inlineKeyboard([ [Markup.button.url('๐ŸŽฎ Open Mini App', LINKS.miniAppPlay)], @@ -1625,6 +2564,26 @@ function linkPrefKeyboard() { ]); } +/** + + * adminKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function adminKeyboard() { return Markup.inlineKeyboard([ [Markup.button.callback('๐Ÿ“„ View Promo', 'admin_view')], @@ -1638,10 +2597,50 @@ function adminKeyboard() { ]); } +/** + + * promoText executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function promoText() { return promoManagerSummaryText ? promoManagerSummaryText() : 'Promo Manager enabled.'; } +/** + + * normalizePromoManagerPromo executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function normalizePromoManagerPromo(raw, idHint = null) { if (!raw || typeof raw !== 'object') return null; const parsedId = Number(raw.promo_id); @@ -1672,10 +2671,50 @@ function normalizePromoManagerPromo(raw, idHint = null) { }; } +/** + + * savePromoManagerDb executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function savePromoManagerDb() { saveJson(promoManagerDbFile, promoManagerStore); } +/** + + * loadPromoManagerDb executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function loadPromoManagerDb() { const raw = loadJson(promoManagerDbFile, null); if (!raw || typeof raw !== 'object') return; @@ -1692,27 +2731,147 @@ function loadPromoManagerDb() { promoManagerStore.nextClaimId = Math.max(promoManagerStore.nextClaimId, maxClaimId + 1); } +/** + + * listActivePromos executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function listActivePromos() { return promoManagerStore.promos.filter((promo) => promo.status === PROMO_STATUS.ACTIVE); } +/** + + * getPromoById executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function getPromoById(promoId) { return promoManagerStore.promos.find((promo) => promo.promo_id === Number(promoId)) || null; } +/** + + * hasRedeemedAnyPromo executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function hasRedeemedAnyPromo(userId) { return promoManagerStore.claims.some((claim) => claim.user_id === Number(userId) && ['claimed', 'approved'].includes(claim.status)); } +/** + + * countPromoClaims executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function countPromoClaims(promoId) { return promoManagerStore.claims.filter((claim) => claim.promo_id === Number(promoId) && ['claimed', 'approved'].includes(claim.status)).length; } +/** + + * getRollingWagerForUser executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function getRollingWagerForUser(user, days) { if (Number(days) === 7 && user.wagerBonus && Number(user.wagerBonus.wager7dayTotal) > 0) return Number(user.wagerBonus.wager7dayTotal); return Number(user.wagerBonus && user.wagerBonus.wager7dayTotal) || 0; } +/** + + * evaluatePromoEligibility executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function evaluatePromoEligibility(user, promo, { logFailure = false } = {}) { const reasons = []; const userId = Number(user.id); @@ -1740,6 +2899,26 @@ async function evaluatePromoEligibility(user, promo, { logFailure = false } = {} return { eligible: reasons.length === 0, reasons }; } +/** + + * renderPromoForUser executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function renderPromoForUser(promo) { return [ `๐ŸŽ *${promo.name}*`, @@ -1755,6 +2934,36 @@ function renderPromoForUser(promo) { } +/** + + + * getActivePromoCodeForUser executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + + * Parameters: See the function signature for exact argument names and accepted values. + + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + + */ + + function getActivePromoCodeForUser(user) { const promos = listActivePromos(); const first = promos[0] || null; @@ -1769,21 +2978,81 @@ function getActivePromoCodeForUser(user) { -function wager30AdminKeyboard() { - return Markup.inlineKeyboard([ - [Markup.button.callback('๐Ÿ“‹ Open (Pending) Requests', 'w30_admin_pending')], - [Markup.button.callback('โœ… Completed Requests', 'w30_admin_completed')], - [Markup.button.callback('๐Ÿ‘ Approve Request', 'w30_admin_approve_pick')], - [Markup.button.callback('โŒ Deny Request', 'w30_admin_deny_pick')], - [Markup.button.callback('๐Ÿ“ค Mark Tip Sent', 'w30_admin_sent_pick')], - [Markup.button.callback('๐Ÿ”— Add Username Manually', 'w30_admin_link_username')], - [Markup.button.callback('โž• Add Manual Record (bonus_sent)', 'w30_admin_add_pick')], - [Markup.button.callback('๐Ÿ” Lookup User', 'w30_admin_lookup')], - [Markup.button.callback('๐Ÿ“Š Stats', 'w30_admin_stats')], - [Markup.button.callback('โ™ป๏ธ Reset User', 'w30_admin_reset')], - [Markup.button.callback('โฌ…๏ธ Return to Admin Menu', 'open_admin_dashboard')], - ]); -} +/** + + + + * wager30AdminKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + + + * Parameters: See the function signature for exact argument names and accepted values. + + + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + + + */ + + + +function wager30AdminKeyboard() { + return Markup.inlineKeyboard([ + [Markup.button.callback('๐Ÿ“‹ Open (Pending) Requests', 'w30_admin_pending')], + [Markup.button.callback('โœ… Completed Requests', 'w30_admin_completed')], + [Markup.button.callback('๐Ÿ‘ Approve Request', 'w30_admin_approve_pick')], + [Markup.button.callback('โŒ Deny Request', 'w30_admin_deny_pick')], + [Markup.button.callback('๐Ÿ“ค Mark Tip Sent', 'w30_admin_sent_pick')], + [Markup.button.callback('๐Ÿ”— Add Username Manually', 'w30_admin_link_username')], + [Markup.button.callback('โž• Add Manual Record (bonus_sent)', 'w30_admin_add_pick')], + [Markup.button.callback('๐Ÿ” Lookup User', 'w30_admin_lookup')], + [Markup.button.callback('๐Ÿ“Š Stats', 'w30_admin_stats')], + [Markup.button.callback('โ™ป๏ธ Reset User', 'w30_admin_reset')], + [Markup.button.callback('โฌ…๏ธ Return to Admin Menu', 'open_admin_dashboard')], + ]); +} + +/** + + * wagerReminderKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ function wagerReminderKeyboard() { return Markup.inlineKeyboard([ @@ -1818,6 +3087,26 @@ function settingsKeyboard(user) { // โ”€โ”€ Admin dashboard keyboards โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +/** + + * adminDashboardKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function adminDashboardKeyboard(page = 1) { if (page === 2) { return Markup.inlineKeyboard([ @@ -1880,6 +3169,26 @@ function adminStatsKeyboard() { ]); } +/** + + * adminGiveawayToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function adminGiveawayToolsKeyboard() { return Markup.inlineKeyboard([ [Markup.button.callback('๐ŸŽ Start Giveaway', 'admin_cmd_start_giveaway')], @@ -1889,6 +3198,26 @@ function adminGiveawayToolsKeyboard() { ]); } +/** + + * adminPromoToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function adminPromoToolsKeyboard() { return Markup.inlineKeyboard([ [Markup.button.callback('๐ŸŽ› Promo Manager', 'admin_promo_manager')], @@ -1906,6 +3235,26 @@ function adminPromoToolsKeyboard() { ]); } +/** + + * adminUserToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function adminUserToolsKeyboard() { return Markup.inlineKeyboard([ [Markup.button.callback('๐Ÿ” Whois User', 'admin_cmd_whois_prompt')], @@ -1917,6 +3266,26 @@ function adminUserToolsKeyboard() { ]); } +/** + + * adminSystemToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function adminSystemToolsKeyboard(user = null) { const toggleLabel = user && user.adminModeOn ? '๐ŸŸข Admin Mode: ON (tap to toggle)' : 'โšช Admin Mode: OFF (tap to toggle)'; return Markup.inlineKeyboard([ @@ -1932,6 +3301,26 @@ function adminSystemToolsKeyboard(user = null) { ]); } +/** + + * adminSupportToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function adminSupportToolsKeyboard() { return Markup.inlineKeyboard([ [Markup.button.callback('๐Ÿ› View Bug Reports', 'admin_cmd_viewbugs')], @@ -1990,6 +3379,26 @@ function buildAdminStatusText() { return lines; } +/** + + * sendAdminDashboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function sendAdminDashboard(ctx, page = 1) { const pageLabel = page === 2 ? 'Page 2/2: Quick Actions' : 'Page 1/2: Categories'; const statusText = buildAdminStatusText(); @@ -1999,6 +3408,26 @@ async function sendAdminDashboard(ctx, page = 1) { ); } +/** + + * replaceCallbackPanel executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function replaceCallbackPanel(ctx, text, extra = {}) { try { await ctx.editMessageText(text, extra); @@ -2015,6 +3444,26 @@ async function replaceCallbackPanel(ctx, text, extra = {}) { await ctx.reply(text, extra); } +/** + + * extractCallbackDataFromKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function extractCallbackDataFromKeyboard(markup) { const rows = (markup && markup.reply_markup && Array.isArray(markup.reply_markup.inline_keyboard)) ? markup.reply_markup.inline_keyboard @@ -2028,6 +3477,26 @@ function extractCallbackDataFromKeyboard(markup) { return out; } +/** + + * escapeHtml executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function escapeHtml(text) { return String(text) .replace(/&/g, '&') @@ -2037,6 +3506,26 @@ function escapeHtml(text) { .replace(/'/g, '''); } +/** + + * formatTipForHtml executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function formatTipForHtml(text) { const t = String(text || '').trim(); if (!t) return ''; @@ -2045,6 +3534,26 @@ function formatTipForHtml(text) { return escapeHtml(t); } +/** + + * sendSettingsMenu executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function sendSettingsMenu(ctx, user) { const s = user.settings; const lines = [ @@ -2062,6 +3571,26 @@ async function sendSettingsMenu(ctx, user) { await ctx.reply(lines, { parse_mode: 'Markdown', ...settingsKeyboard(user) }); } +/** + + * sendMainMenu executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function sendMainMenu(ctx, user, page = 1) { const name = user.firstName ? `, ${user.firstName}` : ''; const adminUser = ADMIN_IDS.includes(Number(user.id)) && user.adminModeOn; @@ -2323,6 +3852,26 @@ function toolsMenuKeyboard() { ]); } +/** + + * buildUserStatusLine executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function buildUserStatusLine(user) { const steps = []; if (user.ageConfirmed) steps.push('18+ โœ…'); @@ -2332,10 +3881,50 @@ function buildUserStatusLine(user) { return steps.length ? `๐Ÿ“Š Status: ${steps.join(' | ')}` : ''; } +/** + + * needsLinkedUsername executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function needsLinkedUsername(user) { return !user.runewagerUsername || !user.runewagerUsername.trim(); } +/** + + * linkedUsernameError executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function linkedUsernameError(ctx) { await ctx.reply( '๐Ÿ”— You need to link your Runewager username first.\n\n' @@ -2349,6 +3938,36 @@ async function linkedUsernameError(ctx) { } +/** + + + * deleteEphemeralBonusPrompt executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + + * Parameters: See the function signature for exact argument names and accepted values. + + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + + */ + + async function deleteEphemeralBonusPrompt(ctx, user) { if (!user.ephemeralBonusMsgId || !user.ephemeralBonusChatId) return; try { @@ -2358,6 +3977,26 @@ async function deleteEphemeralBonusPrompt(ctx, user) { user.ephemeralBonusChatId = null; } +/** + + * sendEphemeralBonusPrompt executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function sendEphemeralBonusPrompt(ctx, user) { const sent = await ctx.reply( `๐ŸŽ *Claim Your New User Bonus* @@ -2387,6 +4026,26 @@ Enter promo code *${promoStore.code}* on the Runewager affiliate page to claim y const adminEventsLogFile = path.join(dataDir, 'admin-events.log'); const ADMIN_LOG_CAP = 200; +/** + + * adminLog executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function adminLog(event, payload) { const entry = { ts: new Date().toISOString(), event, payload }; promoStore.logs.push(entry); @@ -2399,6 +4058,26 @@ function adminLog(event, payload) { } catch (_) { /* non-fatal โ€” in-memory log is the source of truth */ } } +/** + + * clearPendingAction executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function clearPendingAction(user) { user.pendingAction = null; } @@ -2446,6 +4125,26 @@ async function showOnboardingPrompt(ctx, user, step) { } } +/** + + * isValidHttpUrl executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function isValidHttpUrl(value) { try { const parsed = new URL(value); @@ -2472,10 +4171,50 @@ function escapeMarkdownFull(text) { return String(text).replace(/[_*[\]()~`>#+\-=|{}.!\\]/g, '\\$&'); } +/** + + * ensureDataDir executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function ensureDataDir() { if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true }); } +/** + + * validateSafePath executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function validateSafePath(inputPath, baseDir) { if (!inputPath || typeof inputPath !== 'string') { throw new Error('Invalid path input'); @@ -2495,6 +4234,26 @@ function validateSafePath(inputPath, baseDir) { return realTarget; } +/** + + * loadJson executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function loadJson(filePath, fallback) { try { const safePath = validateSafePath(filePath, dataDir); @@ -2505,6 +4264,26 @@ function loadJson(filePath, fallback) { } } +/** + + * writeFileAtomic executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function writeFileAtomic(filePath, content) { const safeFilePath = validateSafePath(filePath, dataDir); const dirPath = path.dirname(safeFilePath); @@ -2514,15 +4293,75 @@ function writeFileAtomic(filePath, content) { fs.renameSync(tempFile, safeFilePath); } +/** + + * saveJson executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function saveJson(filePath, data) { ensureDataDir(); writeFileAtomic(filePath, JSON.stringify(data, null, 2)); } +/** + + * addBadge executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function addBadge(user, badge) { if (!user.badges.has(badge)) user.badges.add(badge); } +/** + + * onboardingStepLabel executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function onboardingStepLabel(step) { // Step 1 (Verify Account) previously meant Discord verification โ€” now means account confirmed. // Discord is NOT involved in onboarding; steps are purely Runewager-based. @@ -2530,6 +4369,26 @@ function onboardingStepLabel(step) { return labels[step] || 'Done'; } +/** + + * getNextOnboardingStep executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function getNextOnboardingStep(user) { if (!user.ageConfirmed) return 0; // Step 1: account confirmed โ€” set automatically once user confirms signup or is an existing user @@ -2540,6 +4399,26 @@ function getNextOnboardingStep(user) { return 5; } +/** + + * trackOnboardingProgress executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function trackOnboardingProgress(user) { const nextStep = getNextOnboardingStep(user); user.onboarding.currentStep = nextStep; @@ -2553,6 +4432,26 @@ function trackOnboardingProgress(user) { } } +/** + + * referralCodeForUser executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function referralCodeForUser(user) { if (!referralStore.links.has(user.id)) { referralStore.links.set(user.id, `rw${user.id.toString(36)}`); @@ -2560,11 +4459,51 @@ function referralCodeForUser(user) { return referralStore.links.get(user.id); } +/** + + * getActiveReferralBoost executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function getActiveReferralBoost() { const now = Date.now(); return referralStore.boosts.find((b) => b.startsAt <= now && b.endsAt >= now) || null; } +/** + + * awardReferralProgress executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function awardReferralProgress(userId, base = 1) { const boost = getActiveReferralBoost(); const mult = boost ? boost.multiplier : 1; @@ -2582,11 +4521,51 @@ function awardReferralProgress(userId, base = 1) { } } +/** + + * trackAnalytics executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function trackAnalytics(event, payload = {}) { analyticsStore.events.push({ event, payload, ts: Date.now() }); if (analyticsStore.events.length > MAX_ANALYTICS_EVENTS) analyticsStore.events.shift(); } +/** + + * safeStepHandler executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function safeStepHandler(name, handler) { return async (ctx) => { try { @@ -2623,6 +4602,26 @@ function safeAdminHandler(name, helpOpts, handler) { }; } +/** + + * sendEphemeral executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function sendEphemeral(ctx, text, ttlMs = 20000) { const sent = await ctx.reply(text); setTimeout(() => { @@ -2630,6 +4629,26 @@ async function sendEphemeral(ctx, text, ttlMs = 20000) { }, ttlMs); } +/** + + * reactToMessage executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function reactToMessage(ctx, emoji) { if (!ctx.chat || !ctx.message) return; await ctx.telegram.callApi('setMessageReaction', { @@ -2644,6 +4663,16 @@ async function reactToMessage(ctx, emoji) { // https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app // secret_key = HMAC-SHA256(msg=BOT_TOKEN, key=WEBAPP_HMAC_KEY) // verify_hash = HMAC-SHA256(msg=data_check_string, key=secret_key) +/** + * verifyWebAppInitData executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ function verifyWebAppInitData(initDataRaw) { if (!initDataRaw || !BOT_TOKEN) return false; const params = new URLSearchParams(initDataRaw); @@ -2670,6 +4699,26 @@ function verifyWebAppInitData(initDataRaw) { // bounding memory usage on high-traffic bots. const SMART_BUTTON_TTL_MS = 2 * 60 * 1000; +/** + + * consumeSmartButton executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function consumeSmartButton(userId, key) { const token = `${userId}:${key}`; const now = Date.now(); @@ -2726,6 +4775,26 @@ function buildStatsWindow(windowMs) { }; } +/** + + * buildDashboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function buildDashboard() { const now = Date.now(); const allUsers = Array.from(userStore.values()); @@ -2753,12 +4822,52 @@ function buildDashboard() { return data; } +/** + + * registerPromoClaim executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function registerPromoClaim(user, code) { if (!promoHistoryStore.has(user.id)) promoHistoryStore.set(user.id, []); promoHistoryStore.get(user.id).push({ code, ts: Date.now() }); saveJson(promoHistoryFile, Object.fromEntries(promoHistoryStore)); } +/** + + * loadPersistentData executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function loadPersistentData() { const promoHistory = loadJson(promoHistoryFile, {}); Object.entries(promoHistory).forEach(([id, entries]) => promoHistoryStore.set(Number(id), entries)); @@ -2769,10 +4878,50 @@ function loadPersistentData() { loadSshvSessions(); } +/** + + * persistAnalytics executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function persistAnalytics() { saveJson(analyticsFile, analyticsStore); } +/** + + * configureBotSurface executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function configureBotSurface() { // โ”€โ”€ User commands visible in ALL chats (Telegram's global default) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ const globalCommands = [ @@ -3056,6 +5205,26 @@ function buildHelpPages(user) { const adminUser = ADMIN_IDS.includes(Number(user.id)) && user.adminModeOn; const tips = user.settings && user.settings.tooltipsEnabled; + /** + + * navRow executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function navRow(page, total) { const row = []; if (page > 1) row.push(Markup.button.callback('โ—€๏ธ Prev', `help_page_${page - 1}`)); @@ -3258,7 +5427,6 @@ function buildHelpPages(user) { '/help or /commands โ€” Open this help booklet', '/bugreport โ€” Report a bug to the admin team', '/support โ€” Open the support portal (DM only)', - '/language โ€” View detected language setting', '', tips ? 'โ„น๏ธ Tip: Enable tooltips in /settings for extra guidance.' : '', '', @@ -3453,6 +5621,26 @@ function buildUsernameConfirmPrompt(normalized) { }; } +/** + + * sendLinkAccountPrompt executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function sendLinkAccountPrompt(ctx, user) { const alreadyLinked = user.runewagerUsername && user.runewagerUsername.trim(); const header = alreadyLinked @@ -3546,10 +5734,50 @@ bot.command('sshv', async (ctx) => { // โ†’ Send Channel Only โ†’ channel โ†’ state.none // ========================= +/** + + * parseModeLabel executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function parseModeLabel(mode) { return mode === 'HTML' ? 'HTML' : 'Text'; } +/** + + * announceBuilderKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function announceBuilderKeyboard(config) { const dm = config.sendDm ? 'โœ… DM Users' : 'โ˜ DM Users'; const ch = config.sendChannel ? 'โœ… Channel' : 'โ˜ Channel'; @@ -3563,6 +5791,26 @@ function announceBuilderKeyboard(config) { ]); } +/** + + * sendAnnouncementTargets executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function sendAnnouncementTargets(ctx, announcementText, config) { let sentDm = 0; let failedDm = 0; @@ -3604,6 +5852,26 @@ async function sendAnnouncementTargets(ctx, announcementText, config) { return { sentDm, failedDm, channelStatus, groupStatus }; } +/** + + * handleAnnounceCommand executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function handleAnnounceCommand(ctx) { if (!requireAdmin(ctx)) return; const user = getUser(ctx); @@ -4373,6 +6641,19 @@ bot.action('to_main_menu', async (ctx) => { await sendPersistentUserMenu(ctx, user); }); + +bot.action('menu_page_1', async (ctx) => { + const user = getUser(ctx); + await ctx.answerCbQuery(); + await sendMainMenu(ctx, user, 1); +}); + +bot.action('menu_page_2', async (ctx) => { + const user = getUser(ctx); + await ctx.answerCbQuery(); + await sendMainMenu(ctx, user, 2); +}); + // โ”€โ”€ Persistent USER MAIN MENU actions (pmenu_*) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ bot.action('pmenu_claim_bonus', async (ctx) => { @@ -4923,6 +7204,16 @@ bot.action('age_yes', async (ctx) => { }); // Shows the mandatory GambleCodez affiliate code step +/** + * sendGambleCodezVIPStep executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function sendGambleCodezVIPStep(ctx, user) { if (user.sawGambleCodezStep) { await sendPersistentUserMenu(ctx, user); @@ -5075,6 +7366,16 @@ bot.action('onboarding_next_step', async (ctx) => { }); // Shared handler: finalise username link after user confirmation +/** + * finaliseUsernameLink executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function finaliseUsernameLink(ctx, user, normalized, returnTo) { const wasLinked = Boolean(user.runewagerUsername && user.runewagerUsername.trim()); user.runewagerUsername = normalized; @@ -5333,6 +7634,26 @@ bot.action('menu_bugreport', async (ctx) => { await ctx.reply('๐Ÿ› *Bug Report*\n\nDescribe the bug you encountered. Include steps to reproduce if possible.\n\nOr type /cancel to cancel.', { parse_mode: 'Markdown' }); }); +/** + + * replyBonusStatus executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function replyBonusStatus(ctx, user, answerCallback = false) { if (answerCallback) await ctx.answerCbQuery(); const wb = user.wagerBonus; @@ -5404,23 +7725,80 @@ bot.action('admin_cat_promo', async (ctx) => { await replaceCallbackPanel(ctx, '๐Ÿ“ฃ *Promo Tools*', { parse_mode: 'Markdown', ...adminPromoToolsKeyboard() }); }); -bot.action('admin_cat_user', async (ctx) => { +bot.action('admin_cat_user', async (ctx) => { + if (!requireAdmin(ctx)) return; + await ctx.answerCbQuery(); + await replaceCallbackPanel(ctx, '๐Ÿ‘ค *User Tools*', { parse_mode: 'Markdown', ...adminUserToolsKeyboard() }); +}); + +bot.action('admin_cat_system', async (ctx) => { + if (!requireAdmin(ctx)) return; + await ctx.answerCbQuery(); + const user = getUser(ctx); + await replaceCallbackPanel(ctx, 'โš™๏ธ *System Tools*', { parse_mode: 'Markdown', ...adminSystemToolsKeyboard(user) }); +}); + +bot.action('admin_cat_support', async (ctx) => { + if (!requireAdmin(ctx)) return; + await ctx.answerCbQuery(); + await replaceCallbackPanel(ctx, '๐Ÿ›Ÿ *Support Tools*', { parse_mode: 'Markdown', ...adminSupportToolsKeyboard() }); +}); + + +/** + + + * adminTestsToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + + * Parameters: See the function signature for exact argument names and accepted values. + + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + + */ + + +function adminTestsToolsKeyboard() { + return Markup.inlineKeyboard([ + [Markup.button.callback('๐Ÿงช Run TestAll', 'admin_cmd_testall'), Markup.button.callback('๐ŸŽ Test Giveaway', 'admin_cmd_testgiveaway')], + [Markup.button.callback('๐Ÿ› View Bug Reports', 'admin_cmd_viewbugs'), Markup.button.callback('๐Ÿ“ค Export Bugs', 'admin_cmd_exportbugs')], + [Markup.button.callback('โœ… Resolve Bug', 'admin_cmd_resolvebug_prompt'), Markup.button.callback('๐Ÿงช Test Content Drop', 'admin_cmd_tiptest')], + [Markup.button.callback('๐Ÿ“Ÿ Open SSHV Console', 'sshv_open')], + [Markup.button.callback('โฌ…๏ธ Admin Dashboard', 'open_admin_dashboard')], + ]); +} + +bot.action('admin_cat_tests', async (ctx) => { if (!requireAdmin(ctx)) return; await ctx.answerCbQuery(); - await replaceCallbackPanel(ctx, '๐Ÿ‘ค *User Tools*', { parse_mode: 'Markdown', ...adminUserToolsKeyboard() }); -}); + await replaceCallbackPanel(ctx, + `๐Ÿงช *Tests & Bug Tools* -bot.action('admin_cat_system', async (ctx) => { - if (!requireAdmin(ctx)) return; - await ctx.answerCbQuery(); - const user = getUser(ctx); - await replaceCallbackPanel(ctx, 'โš™๏ธ *System Tools*', { parse_mode: 'Markdown', ...adminSystemToolsKeyboard(user) }); -}); +Use this menu for diagnostics, bug workflows, and test sends. -bot.action('admin_cat_support', async (ctx) => { - if (!requireAdmin(ctx)) return; - await ctx.answerCbQuery(); - await replaceCallbackPanel(ctx, '๐Ÿ›Ÿ *Support Tools*', { parse_mode: 'Markdown', ...adminSupportToolsKeyboard() }); +โ€ข TestAll = full sanity check +โ€ข Test Giveaway = simulated giveaway flow +โ€ข Test Content Drop = sends one random drop to current target +โ€ข SSHV = VPS console tools`, + { parse_mode: 'Markdown', ...adminTestsToolsKeyboard() }, + ); }); @@ -5937,6 +8315,26 @@ bot.action('menu_giveaways', async (ctx) => { await sendGiveawayListPage(ctx, 1); }); +/** + + * sendGiveawayListPage executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function sendGiveawayListPage(ctx, page) { const features = giveawayFeatureList; const { slice, navRow, totalPages } = paginate(features, page, 6, 'page_giveaways'); @@ -5976,6 +8374,16 @@ bot.action(/^walk_(next|back|done)$/, async (ctx) => { // ========================= // Admin promo callbacks // ========================= +/** + * promoManagerSummaryText executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ function promoManagerSummaryText() { const promos = promoManagerStore.promos.slice().sort((a, b) => a.promo_id - b.promo_id); const lines = promos.map((promo) => { @@ -6500,6 +8908,36 @@ bot.on('inline_query', safeStepHandler('inline_query', async (ctx) => { })); +/** + + + * extractForwardedChat executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + + * Parameters: See the function signature for exact argument names and accepted values. + + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + + */ + + function extractForwardedChat(msg = {}) { return msg.forward_from_chat || (msg.forward_origin && msg.forward_origin.chat) @@ -6507,6 +8945,26 @@ function extractForwardedChat(msg = {}) { || null; } +/** + + * autoRegisterForwardedChatIfPresent executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function autoRegisterForwardedChatIfPresent(ctx, user) { if (!isAdmin(ctx)) return false; const fwdChat = extractForwardedChat(ctx.message || {}); @@ -7526,7 +9984,7 @@ bot.action('announce_send_all', async (ctx) => { await ctx.reply('Legacy "Send All" mapped to the new broadcast flow. Tap "Send Broadcast Now" after reviewing toggles.'); }); -bot.action('announce_send_channel', async (ctx) => { +bot.action('announce_send_now', async (ctx) => { if (!requireAdmin(ctx)) return; const user = getUser(ctx); const action = user.pendingAction; @@ -7570,6 +10028,73 @@ async function postTipToConfiguredTarget(tip, telegram) { return { ok: false, error: lastErr }; } +/** + + * resolveTipTargetChatId executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + +async function resolveTipTargetChatId(rawTarget) { + const t = String(rawTarget || '').trim(); + if (!t) return null; + if (/^-?\d+$/.test(t)) return Number(t); + if (t.startsWith('@')) return t; + return `@${t}`; +} + +/** + + * postTipToConfiguredTarget executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + +async function postTipToConfiguredTarget(tip, telegram) { + const primaryTarget = await resolveTipTargetChatId(tipsStore.targetGroup || broadcastConfigStore.targetGroup); + const fallbackTarget = approvedGroupsStore.size ? Array.from(approvedGroupsStore)[0] : null; + const candidates = [primaryTarget, fallbackTarget].filter(Boolean); + let lastErr = null; + for (const target of candidates) { + try { + // eslint-disable-next-line no-await-in-loop + await telegram.sendMessage(target, formatTipForHtml(tip.text), { parse_mode: 'HTML', disable_notification: true }); + tipsStore.targetGroup = String(target); + broadcastConfigStore.targetGroup = String(target); + return { ok: true, target }; + } catch (e) { + lastErr = e; + } + } + return { ok: false, error: lastErr }; +} + /** * Start (or restart) the tips scheduler. * Clears any existing timer then arms a fresh one using the current interval. @@ -7635,6 +10160,26 @@ async function sendTipsDashboard(ctx) { // โ”€โ”€ /tips /tiplist /tipadd /tipremove /tipedit /tiptoggle /tiptest /tipsettings โ”€โ”€ +/** + + * handleTipsCommand executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function handleTipsCommand(ctx) { if (!requireAdmin(ctx)) return; await sendTipsDashboard(ctx); @@ -7926,6 +10471,16 @@ bot.action('gwiz_title_skip', async (ctx) => { }); // โ”€โ”€ Winners step (Step 3) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +/** + * gwizSetWinners executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function gwizSetWinners(ctx, count) { if (!requireAdmin(ctx)) return; const user = getUser(ctx); @@ -7950,6 +10505,16 @@ bot.action('gwiz_winners_custom', async (ctx) => { }); // โ”€โ”€ SC per winner step (Step 2) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +/** + * gwizSetSc executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function gwizSetSc(ctx, amount) { if (!requireAdmin(ctx)) return; const user = getUser(ctx); @@ -7974,6 +10539,16 @@ bot.action('gwiz_sc_custom', async (ctx) => { }); // โ”€โ”€ Duration step (Step 4) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +/** + * gwizSetDuration executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function gwizSetDuration(ctx, minutes) { if (!requireAdmin(ctx)) return; const user = getUser(ctx); @@ -8000,6 +10575,16 @@ bot.action('gwiz_dur_custom', async (ctx) => { }); // โ”€โ”€ Min participants step (Step 5) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +/** + * gwizSetMinParts executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function gwizSetMinParts(ctx, count) { if (!requireAdmin(ctx)) return; const user = getUser(ctx); @@ -8027,6 +10612,16 @@ bot.action('gwiz_minp_custom', async (ctx) => { }); // โ”€โ”€ Join surface step (Step 6) โ€” toggle group and DM independently โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +/** + * gwizToggleSurface executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function gwizToggleSurface(ctx, field) { if (!requireAdmin(ctx)) return; const user = getUser(ctx); @@ -8107,6 +10702,16 @@ bot.action('gw_create_yes', async (ctx) => { // ========================= // Helpers: Walkthrough // ========================= +/** + * sendWalkthroughStep executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function sendWalkthroughStep(ctx, user) { const idx = user.walkthrough.currentStep; const step = walkthroughCatalog[idx]; @@ -8130,6 +10735,26 @@ async function sendWalkthroughStep(ctx, user) { await ctx.reply(header, nav); } +/** + + * buildWalkthroughCatalog executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function buildWalkthroughCatalog() { return [ { title: '1) First Time Setup Wizard', body: 'Use /start, pass age gate, and open the main menu.' }, @@ -8170,6 +10795,26 @@ function buildWalkthroughCatalog() { ]; } +/** + + * buildGiveawayFeatureList executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function buildGiveawayFeatureList() { return [ 'Admin command /start_giveaway', @@ -8213,6 +10858,16 @@ function buildGiveawayFeatureList() { // ========================= // Helpers: Giveaway engine // ========================= +/** + * normalizeYesNo executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ function normalizeYesNo(text) { const t = String(text || '').toLowerCase(); if (['y', 'yes'].includes(t)) return true; @@ -8220,6 +10875,26 @@ function normalizeYesNo(text) { return null; } +/** + + * createGiveaway executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function createGiveaway(config) { const id = giveawayStore.counter; giveawayStore.counter += 1; @@ -8259,6 +10934,26 @@ function createGiveaway(config) { }; } +/** + + * announceGiveaway executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function announceGiveaway(giveaway, botUsername) { const titleLine = giveaway.title ? `\n๐Ÿ“Œ *${escapeMarkdownV2(giveaway.title)}*\n` : ''; const minPartLine = giveaway.minParticipants > 0 @@ -8336,6 +11031,26 @@ async function announceGiveaway(giveaway, botUsername) { } } +/** + + * evaluateEligibility executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function evaluateEligibility(user, giveaway) { if (giveaway.requireLinked && needsLinkedUsername(user)) { return { ok: false, missingLink: true, message: 'You must link your Runewager username first using /link.' }; @@ -8366,12 +11081,52 @@ function evaluateEligibility(user, giveaway) { return { ok: true }; } +/** + + * resetGiveawayTimer executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function resetGiveawayTimer(giveaway) { if (giveaway.endTimer) clearTimeout(giveaway.endTimer); const ms = Math.max(1000, giveaway.endTime - Date.now()); giveaway.endTimer = setTimeout(() => finalizeGiveaway(giveaway.id), ms); } +/** + + * scheduleGiveawayReminders executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function scheduleGiveawayReminders(giveaway) { const points = [10, 5, 1]; points.forEach((m) => { @@ -8387,6 +11142,26 @@ function scheduleGiveawayReminders(giveaway) { }); } +/** + + * finalizeGiveaway executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function finalizeGiveaway(gwId, forceEnd = false) { const giveaway = giveawayStore.running.get(gwId); if (!giveaway) return; @@ -8477,6 +11252,26 @@ async function finalizeGiveaway(gwId, forceEnd = false) { ); } +/** + + * pickRandomUnique executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function pickRandomUnique(arr, count) { const copy = [...arr]; for (let i = copy.length - 1; i > 0; i -= 1) { @@ -8486,6 +11281,26 @@ function pickRandomUnique(arr, count) { return copy.slice(0, count); } +/** + + * renderWinnersList executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function renderWinnersList(winners) { if (!winners.length) return 'None'; return winners @@ -8496,20 +11311,100 @@ function renderWinnersList(winners) { .join('\n'); } +/** + + * renderWinnersText executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function renderWinnersText(giveaway) { return `๐ŸŽ‰ Giveaway ended!\nWinners (${giveaway.scPerWinner} SC each):\n${renderWinnersList(giveaway.winners)}\n\nAdmin will handle prize distribution.`; } +/** + + * renderGiveawaySummary executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function renderGiveawaySummary(giveaway) { return `Giveaway #${giveaway.id}\nStatus: ${giveaway.status}\nChat: ${giveaway.chatId}\nWinners target: ${giveaway.maxWinners}\nSC each: ${giveaway.scPerWinner}\nParticipants: ${giveaway.participants.size}\nEnds: ${new Date(giveaway.endTime).toISOString()}`; } +/** + + * renderGiveawayExport executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function renderGiveawayExport(giveaway) { const participants = Array.from(giveaway.participants.values()); const participantLines = participants.map((p) => `- ${p.userId} @${p.tgUsername} | RW: ${p.runewagerUsername}`).join('\n') || 'None'; return `EXPORT GIVEAWAY #${giveaway.id}\nStatus: ${giveaway.status}\nChat ID: ${giveaway.chatId}\nCreated: ${new Date(giveaway.createdAt).toISOString()}\nEnd: ${new Date(giveaway.endTime).toISOString()}\nSC each: ${giveaway.scPerWinner}\nWinners count target: ${giveaway.maxWinners}\nParticipants (${participants.length}):\n${participantLines}\nWinners:\n${renderWinnersList(giveaway.winners)}\nPaid out: ${giveaway.paidOut ? 'yes' : 'no'}`; } +/** + + * findUserByRunewager executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function findUserByRunewager(runewagerUsername) { const needle = normalizeRunewagerUsername(runewagerUsername); if (!needle) return null; @@ -8517,6 +11412,26 @@ function findUserByRunewager(runewagerUsername) { .find((u) => normalizeRunewagerUsername(u.runewagerUsername) === needle) || null; } +/** + + * findUserByTelegramIdOrRunewager executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function findUserByTelegramIdOrRunewager(input) { const trimmed = String(input || '').trim(); if (!trimmed) return null; @@ -8525,6 +11440,26 @@ function findUserByTelegramIdOrRunewager(input) { return findUserByRunewager(trimmed); } +/** + + * renderWager30Lookup executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function renderWager30Lookup(u) { const wb = u.wagerBonus; const ts = wb.lastRequestAt ? new Date(wb.lastRequestAt).toISOString() : 'n/a'; @@ -8542,6 +11477,26 @@ function renderWager30Lookup(u) { + `Deny reason: ${wb.denyReason || 'n/a'}`; } +/** + + * buildWager30Stats executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function buildWager30Stats() { const stats = { pending: 0, approved: 0, bonusSent: 0, denied: 0, maxAttempts: 0 }; for (const [, u] of userStore) { @@ -8555,6 +11510,26 @@ function buildWager30Stats() { return stats; } +/** + + * runWeeklyWagerReminder executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function runWeeklyWagerReminder() { for (const [, user] of userStore) { if (!user.wagerBonus) continue; @@ -8582,6 +11557,26 @@ async function runWeeklyWagerReminder() { } } +/** + + * notifyAdmins executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function notifyAdmins(text) { const giveawayId = extractGwId(text); const shouldIncludeGiveawayActions = giveawayId > 0; @@ -8605,6 +11600,26 @@ async function notifyAdmins(text) { } } +/** + + * notifyAdminsPlain executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function notifyAdminsPlain(text) { for (const adminId of ADMIN_IDS) { try { @@ -8646,6 +11661,26 @@ bot.action('page_noop', async (ctx) => { await ctx.answerCbQuery(); }); // 30 SC Bonus admin command helpers // ========================= +/** + + * bonusAdminListPending executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function bonusAdminListPending(ctx, page = 1) { const pending = Array.from(userStore.values()).filter((u) => u.wagerBonus && u.wagerBonus.status === 'pending'); if (!pending.length) { @@ -8690,6 +11725,26 @@ bot.action(/^page_bonus_pending_(\d+)$/, async (ctx) => { await bonusAdminListPending(ctx, page); }); +/** + + * bonusAdminApprove executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function bonusAdminApprove(ctx, rawId) { const target = findUserByTelegramIdOrRunewager(rawId); if (!target) return ctx.reply(`User not found: ${rawId}`); @@ -8709,6 +11764,26 @@ async function bonusAdminApprove(ctx, rawId) { } catch (e) { /* ignore */ } } +/** + + * bonusAdminDeny executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function bonusAdminDeny(ctx, rawId, reason) { const target = findUserByTelegramIdOrRunewager(rawId); if (!target) return ctx.reply(`User not found: ${rawId}`); @@ -8727,6 +11802,26 @@ async function bonusAdminDeny(ctx, rawId, reason) { } catch (e) { /* ignore */ } } +/** + + * bonusAdminSent executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function bonusAdminSent(ctx, rawId) { const target = findUserByTelegramIdOrRunewager(rawId); if (!target) return ctx.reply(`User not found: ${rawId}`); @@ -8745,6 +11840,26 @@ async function bonusAdminSent(ctx, rawId) { } catch (e) { /* ignore */ } } +/** + + * bonusAdminAdd executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function bonusAdminAdd(ctx, rawId) { const target = findUserByTelegramIdOrRunewager(rawId); if (!target) return ctx.reply(`User not found: ${rawId}`); @@ -8758,11 +11873,51 @@ async function bonusAdminAdd(ctx, rawId) { await ctx.reply(`โž• Manual record added. TG ID: ${target.id} (@${addedName}) โ€” status: bonus_sent`); } +/** + + * extractGwId executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function extractGwId(text) { const m = text.match(/#(\d+)/); return m ? Number(m[1]) : 0; } +/** + + * normalizeRunewagerUsername executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function normalizeRunewagerUsername(text) { return String(text || '').trim().replace(/^@+/, '').toLowerCase(); } @@ -8777,6 +11932,16 @@ bot.command('testall', async (ctx) => { // Category-scoped result accumulator const cats = {}; + /** + * addResult executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ function addResult(cat, ok, label, detail = '') { if (!cats[cat]) cats[cat] = []; cats[cat].push({ ok, label, detail }); @@ -9151,6 +12316,26 @@ bot.action(/^tgw_abort_(\d+)$/, async (ctx) => { await ctx.reply(`๐Ÿงช Test Giveaway #${gwId} aborted and cleaned up.`); }); +/** + + * runTestGiveawayFinale executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + async function runTestGiveawayFinale(gw, adminId) { const gwId = gw.id; const allParticipants = Array.from(gw.participants.values()); @@ -9198,6 +12383,26 @@ async function runTestGiveawayFinale(gw, adminId) { } } +/** + + * startHealthServer executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function startHealthServer() { const port = Number(process.env.PORT || 3000); const tlsKeyPath = process.env.HTTPS_KEY_PATH; @@ -9308,6 +12513,16 @@ Falling back to HTTP-only health server.`); // โ”€โ”€ Admin Activity Log store (Feature 9) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ const adminActivityLog = []; const MAX_ADMIN_LOG = 500; +/** + * logAdminAction executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ function logAdminAction(adminId, action, detail = '') { adminActivityLog.push({ ts: Date.now(), adminId, action, detail: String(detail).slice(0, 200) }); if (adminActivityLog.length > MAX_ADMIN_LOG) adminActivityLog.shift(); @@ -9411,6 +12626,16 @@ bot.command('scan_eligibility', safeAdminHandler('scan_eligibility', { usage: '/ })); // โ”€โ”€ Feature 3: Auto-Expiring Referral Boosts cron โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +/** + * expireReferralBoosts executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ function expireReferralBoosts() { const now = Date.now(); for (const [, user] of userStore) { @@ -9727,6 +12952,16 @@ bot.command('mygiveaways', async (ctx) => { }); // โ”€โ”€ Feature 17: Auto-DM eligibility fix helper โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +/** + * dmEligibilityFix executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function dmEligibilityFix(user, result) { if (!user || !result || result.ok) return; try { @@ -9889,6 +13124,16 @@ bot.action('support_cancel', async (ctx) => { }); // โ”€โ”€ Feature 26: Weekly Auto-DM Boost Reminder โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +/** + * runWeeklyBoostReminder executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function runWeeklyBoostReminder() { const now = Date.now(); const WEEK_MS_26 = 7 * 24 * 60 * 60 * 1000; let sent = 0; for (const [, user] of userStore) { @@ -9916,6 +13161,16 @@ async function runWeeklyBoostReminder() { // ========================= // Startup // ========================= +/** + * startBot executes its scoped Runewager logic and participates in menu/command or utility flow composition. + * Parameters: See the function signature for exact argument names and accepted values. + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + */ async function startBot() { try { loadPersistentData(); diff --git a/promo-message.js b/promo-message.js index 2dd8b2b..dab9d0a 100644 --- a/promo-message.js +++ b/promo-message.js @@ -4,6 +4,26 @@ const path = require('path'); const PROMO_MESSAGE_FILE = path.join(__dirname, 'data', 'promo_message.json'); const FALLBACK_PROMO_MESSAGE = 'Your promo is ready โ€” tap below to claim.'; +/** + + * readPromoMessageFile executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function readPromoMessageFile() { try { if (!fs.existsSync(PROMO_MESSAGE_FILE)) return null; @@ -15,12 +35,52 @@ function readPromoMessageFile() { } } +/** + + * getPromoMessage executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function getPromoMessage() { return readPromoMessageFile() || String(process.env.DEFAULT_PROMO_MESSAGE || '').trim() || FALLBACK_PROMO_MESSAGE; } +/** + + * setPromoMessage executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function setPromoMessage(message) { const clean = String(message || '').trim(); if (!clean) throw new Error('Promo message cannot be empty.'); diff --git a/test/runtime.test.js b/test/runtime.test.js index 91cd4dc..9a38dc2 100644 --- a/test/runtime.test.js +++ b/test/runtime.test.js @@ -11,6 +11,26 @@ const runtimeState = path.join(dataDir, 'runtime-state.json'); const backupScript = path.join(rootDir, 'scripts', 'backup-runtime-state.sh'); const restoreScript = path.join(rootDir, 'scripts', 'restore-runtime-state.sh'); +/** + + * run executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function run(script, args) { return spawnSync('bash', [script, ...args], { encoding: 'utf8', cwd: rootDir, timeout: 10000 }); } diff --git a/test/smoke.test.js b/test/smoke.test.js index 6cf88af..a4cd131 100644 --- a/test/smoke.test.js +++ b/test/smoke.test.js @@ -4,17 +4,65 @@ const { spawnSync } = require('node:child_process'); const fs = require('node:fs'); const path = require('node:path'); +/** + + * collectJsFiles executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function collectJsFiles(rootDir) { const files = []; - const skipDirs = new Set(['.git', 'node_modules', 'data', 'logs']); + const skipDirs = new Set(['.git', 'node_modules', 'data', 'logs', 'test']); + + /** + + * walk executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ function walk(dir) { for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const fullPath = path.join(dir, entry.name); + let stats; + try { + stats = fs.lstatSync(fullPath); + } catch (_) { + continue; + } + if (stats.isSymbolicLink()) continue; if (entry.isDirectory()) { - if (!skipDirs.has(entry.name)) walk(path.join(dir, entry.name)); + if (!skipDirs.has(entry.name)) walk(fullPath); continue; } - if (entry.isFile() && entry.name.endsWith('.js')) files.push(path.join(dir, entry.name)); + if (entry.isFile() && entry.name.endsWith('.js')) files.push(fullPath); } } @@ -22,6 +70,26 @@ function collectJsFiles(rootDir) { return files; } +/** + + * extractLiteralIds executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function extractLiteralIds(source, kind) { const regex = kind === 'callback' ? /Markup\.button\.callback\([^,]+,\s*(["'`])((?:\\.|(?!\1).)*)\1\)/g @@ -37,26 +105,236 @@ function extractLiteralIds(source, kind) { return new Set(ids); } +/** + + * parseRegexLiteral executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + +function parseRegexLiteral(source, slashIndex) { + let i = slashIndex + 1; + let escaped = false; + let inCharClass = false; + while (i < source.length) { + const ch = source[i]; + if (escaped) { + escaped = false; + } else if (ch === '\\') { + escaped = true; + } else if (ch === '[') { + inCharClass = true; + } else if (ch === ']' && inCharClass) { + inCharClass = false; + } else if (ch === '/' && !inCharClass) { + break; + } + i += 1; + } + if (i >= source.length) return null; + const patternSource = source.slice(slashIndex + 1, i); + let j = i + 1; + while (j < source.length && /[a-z]/i.test(source[j])) j += 1; + const flags = source.slice(i + 1, j); + return { patternSource, flags, end: j }; +} + +/** + + * extractActionRegexPatterns executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function extractActionRegexPatterns(source) { const patterns = []; - const matches = source.matchAll(/bot\.action\(\s*\/(.+?)\/([dgimsuvy]*)/g); - for (const m of matches) { - try { - patterns.push(new RegExp(m[1], m[2])); - } catch (_) { - // Skip malformed patterns in this static smoke check. + const marker = 'bot.action('; + let start = 0; + + while (start < source.length) { + const idx = source.indexOf(marker, start); + if (idx === -1) break; + + let cursor = idx + marker.length; + while (cursor < source.length && /\s/.test(source[cursor])) cursor += 1; + if (source[cursor] !== '/') { + start = cursor; + continue; + } + + const parsed = parseRegexLiteral(source, cursor); + if (!parsed) { + start = cursor + 1; + continue; + } + + const { patternSource, flags, end } = parsed; + // Ignore generic catch-all handlers that would make coverage meaningless. + if (patternSource !== '.*' && patternSource !== '.+') { + try { + patterns.push(new RegExp(patternSource, flags)); + } catch (_) { + // Skip malformed patterns in this static smoke check. + } } + + start = end; } + return patterns; } +/** + + * parseStringLiterals executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + +function parseStringLiterals(source) { + const values = []; + let i = 0; + while (i < source.length) { + const ch = source[i]; + if (ch !== '"' && ch !== "'" && ch !== '`') { + i += 1; + continue; + } + const quote = ch; + let j = i + 1; + let escaped = false; + while (j < source.length) { + const cj = source[j]; + if (escaped) { + escaped = false; + } else if (cj === '\\') { + escaped = true; + } else if (cj === quote) { + break; + } + j += 1; + } + if (j >= source.length) break; + const value = source.slice(i + 1, j); + if (!(quote === '`' && value.includes('${'))) values.push(value); + i = j + 1; + } + return values; +} + +/** + + * extractRegisteredCommands executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + +function extractRegisteredCommands(source) { + const marker = 'REGISTERED_COMMANDS'; + const idx = source.indexOf(marker); + if (idx === -1) return null; + + const setIdx = source.indexOf('new Set', idx); + const arrOpen = source.indexOf('[', setIdx); + if (arrOpen === -1) return null; + + let depth = 0; + let inString = null; + let escaped = false; + let arrClose = -1; + + for (let i = arrOpen; i < source.length; i += 1) { + const ch = source[i]; + if (inString) { + if (escaped) { + escaped = false; + } else if (ch === '\\') { + escaped = true; + } else if (ch === inString) { + inString = null; + } + continue; + } + if (ch === '"' || ch === "'" || ch === '`') { + inString = ch; + continue; + } + if (ch === '[') depth += 1; + if (ch === ']') { + depth -= 1; + if (depth === 0) { + arrClose = i; + break; + } + } + } + + if (arrClose === -1) return null; + const arrayBody = source.slice(arrOpen + 1, arrClose); + return new Set(parseStringLiterals(arrayBody)); +} + test('index.js syntax is valid', () => { - const result = spawnSync(process.execPath, ['--check', 'index.js'], { encoding: 'utf8' }); + const rootDir = path.resolve(__dirname, '..'); + const result = spawnSync(process.execPath, ['--check', path.join(rootDir, 'index.js')], { encoding: 'utf8' }); assert.equal(result.status, 0, result.stderr || result.stdout); }); test('menu callback buttons map to handlers (literal or dynamic patterns)', () => { - const jsFiles = collectJsFiles('.'); + const rootDir = path.resolve(__dirname, '..'); + const jsFiles = collectJsFiles(rootDir); const combinedSource = jsFiles .map((file) => fs.readFileSync(file, 'utf8')) .join('\n\n'); @@ -71,3 +349,18 @@ test('menu callback buttons map to handlers (literal or dynamic patterns)', () = assert.deepEqual(uncovered, [], `Uncovered callback handlers: ${uncovered.join(', ')}`); }); + +test('REGISTERED_COMMANDS stays in sync with command handlers', () => { + const source = fs.readFileSync(path.resolve(__dirname, '..', 'index.js'), 'utf8'); + const registered = extractRegisteredCommands(source); + assert.ok(registered, 'REGISTERED_COMMANDS block not found'); + + const commandHandlers = new Set(Array.from(source.matchAll(/bot\.command\(\s*(["'`])((?:\\.|(?!\1).)*)\1/g), (m) => m[2])); + const allowedRegisteredOnly = new Set(['start']); // handled by bot.start(...), not bot.command('start') + + const missingInRegistered = Array.from(commandHandlers).filter((cmd) => !registered.has(cmd)).sort(); + const extraInRegistered = Array.from(registered).filter((cmd) => !commandHandlers.has(cmd) && !allowedRegisteredOnly.has(cmd)).sort(); + + assert.deepEqual(missingInRegistered, [], `Commands missing from REGISTERED_COMMANDS: ${missingInRegistered.join(', ')}`); + assert.deepEqual(extraInRegistered, [], `REGISTERED_COMMANDS entries without handlers: ${extraInRegistered.join(', ')}`); +}); diff --git a/test/unit.test.js b/test/unit.test.js index f6ea71f..51e5c9c 100644 --- a/test/unit.test.js +++ b/test/unit.test.js @@ -23,28 +23,148 @@ const ALLOWED_BONUS_STATUS_TRANSITIONS = { const WAGER_BONUS_IN_FLIGHT_STATUSES = new Set(['pending', 'approved']); const WAGER_BONUS_NON_REQUESTABLE_STATUSES = new Set(['bonus_sent', ...WAGER_BONUS_IN_FLIGHT_STATUSES]); +/** + + * isValidBonusTransition executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function isValidBonusTransition(fromStatus, toStatus) { if (fromStatus === toStatus) return true; const allowed = ALLOWED_BONUS_STATUS_TRANSITIONS[fromStatus] || new Set(); return allowed.has(toStatus); } +/** + + * isWagerBonusRequestLocked executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function isWagerBonusRequestLocked(status) { return WAGER_BONUS_NON_REQUESTABLE_STATUSES.has(status); } +/** + + * escapeMarkdownV2 executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function escapeMarkdownV2(text) { return String(text).replace(/[_*`[\]]/g, '\\$&'); } +/** + + * escapeMarkdownFull executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function escapeMarkdownFull(text) { return String(text).replace(/[_*[\]()~`>#+\-=|{}.!\\]/g, '\\$&'); } +/** + + * normalizeRunewagerUsername executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function normalizeRunewagerUsername(raw) { return String(raw || '').trim().toLowerCase().replace(/^@/, ''); } +/** + + * getNextOnboardingStep executes its scoped Runewager logic and participates in menu/command or utility flow composition. + + * Parameters: See the function signature for exact argument names and accepted values. + + * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers. + + * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression. + + * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable. + + * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions. + + * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid. + + * System fit: This function is part of the Runewager command/callback/state orchestration pipeline. + + */ + function getNextOnboardingStep(user) { if (!user.ageConfirmed) return 0; if (!user.verified) return 1;