broccolini-bot/docs/superpowers/specs/2026-06-03-email-flow-toggle-design.md

Email Flow Toggle — Design

Date: 2026-06-03 Status: Approved (design); pending implementation plan

Goal

A staff slash command to turn the inbound email flow on and off at runtime, with the state surviving container restarts.

• ON — Gmail polling runs as today: reads the inbox, creates/append ticket channels, runs all downstream features.
• OFF — Polling stops entirely. The mailbox is never read (inbox untouched). No new tickets are created from email.
• Outbound is unaffected in both states — ticket-close emails, Gmail replies, and notification emails still send when staff act on existing tickets. (Decision: "off" scopes to inbound polling only.)
• Persists across restarts — the off-state is honored on the next boot. (Decision: persisted, not runtime-only.)

Discord-originated tickets are independent of email polling and are unaffected by this toggle.

Decisions (locked)

Decision	Choice
Scope of OFF	Inbound polling only; outbound email still sends
Persistence	Persist to .env via existing config-persistence path; honored on boot
Command shape	New dedicated /email on|off|status command (Approach A)
Existing /gmailpoll	Guarded so it cannot silently re-enable polling while flow is OFF

Rejected: folding into /gmailpoll subcommands (needless churn to a working command); sentinel interval /gmailpoll 0 (poor discoverability).

Architecture

Single source of truth: a new boolean config flag GMAIL_POLL_ENABLED (default true). The live poll timer (gmailPollInterval in broccolini-discord.js) is started/stopped to match the flag.

1. Config flag — GMAIL_POLL_ENABLED

• config.js — add:

  GMAIL_POLL_ENABLED: process.env.GMAIL_POLL_ENABLED !== 'false',
  

  Undefined/absent → true, so existing deployments keep polling with no .env change required.
• services/configSchema.js — add 'GMAIL_POLL_ENABLED' to ALLOWED_CONFIG_KEYS. The existing /ENABLED$/ rule in inferType() already classifies it as a boolean validator, so the settings site can also toggle it (bonus, no extra work).

2. Boot gate

In broccolini-discord.js (client.once('ready'), currently ~lines 210-211), only start the poll when enabled:

if (CONFIG.GMAIL_POLL_ENABLED) {
  gmailPollInterval = trackInterval(setInterval(() => poll(client), CONFIG.GMAIL_POLL_INTERVAL_MS));
  poll(client);
} else {
  console.log('Gmail poll disabled by config (GMAIL_POLL_ENABLED=false)');
}

When disabled, gmailPollInterval stays null — no timer is registered in activeIntervals, nothing reads the inbox.

3. /email command

• Registration — commands/register.js: a SlashCommandBuilder named email with three subcommands (on, off, status), setDefaultMemberPermissions(PermissionFlagsBits.ManageMessages) to match sibling commands.
• Dispatch — add email: handleEmail to COMMAND_HANDLERS in handlers/commands/index.js. Staff-gated automatically via requireStaffRole() at the dispatcher entry.
• Handler — handleEmail(interaction):
  • on:
    1. applyConfigUpdates({ GMAIL_POLL_ENABLED: true }) (updates runtime CONFIG and writes .env).
    2. Clear the auth-suspend latch via require('../../gmail-poll').setPollSuspended(false) so a prior invalid_grant suspend doesn't keep polling dead. If auth is still broken, the next cycle re-suspends and DMs admin, exactly as today.
    3. setGmailPollInterval(CONFIG.GMAIL_POLL_INTERVAL_MS) to start the live timer.
    4. Reply (ephemeral): "Email flow is now on."
  • off:
    1. applyConfigUpdates({ GMAIL_POLL_ENABLED: false }).
    2. clearGmailPollInterval().
    3. Reply (ephemeral): "Email flow is now off — the inbox will not be polled. Outbound emails still send."
  • status:
    • Report CONFIG.GMAIL_POLL_ENABLED, the current interval (CONFIG.GMAIL_POLL_INTERVAL_MS / 1000s), and whether polling is currently suspended by an auth error.
  • On on/off, fire logTicketEvent('Email flow toggled', [...], interaction).catch(() => {}) — fire-and-forget, matching /gmailpoll.

applyConfigUpdates is called in-process (the command runs inside the bot), reusing the same path the internal API uses — no HTTP round-trip.

4. Guard /gmailpoll against silent re-enable

handleGmailPoll currently calls setGmailPollInterval(ms), which starts the timer. While flow is OFF that would silently re-enable polling. Change it so that when CONFIG.GMAIL_POLL_ENABLED is false:

• update the interval in memory only (CONFIG.GMAIL_POLL_INTERVAL_MS = ms) — matching /gmailpoll's existing runtime-only model (it has never persisted to .env), but
• do not start the live timer, and
• reply: "Interval saved (<n>s), but the inbound email flow is currently off — it will apply when you run /email on."

When flow is ON, /gmailpoll behaves exactly as today.

Data flow

/email off ──> applyConfigUpdates({GMAIL_POLL_ENABLED:false})  ──> CONFIG updated + .env written
           └─> clearGmailPollInterval()                        ──> live timer stopped, gmailPollInterval=null
                                                                    (no inbox reads)

restart ──> config.js reads GMAIL_POLL_ENABLED=false ──> ready gate skips poll start ──> stays off

/email on  ──> applyConfigUpdates({GMAIL_POLL_ENABLED:true})   ──> CONFIG updated + .env written
           ├─> setPollSuspended(false)                         ──> clear prior auth-suspend latch
           └─> setGmailPollInterval(interval)                  ──> live timer started, immediate poll

Error handling

• Command runs through runHandler, so any throw is logged and the user gets an ephemeral "Something went wrong."
• applyConfigUpdates returns { applied, errors }; if GMAIL_POLL_ENABLED lands in errors (should not, given the boolean validator), reply with the error rather than claiming success, and do not flip the live timer.
• Logging stays fire-and-forget (.catch(() => {})), per Hard Rule 4.

Files touched

File	Change
config.js	Add GMAIL_POLL_ENABLED (default true)
services/configSchema.js	Add 'GMAIL_POLL_ENABLED' to ALLOWED_CONFIG_KEYS
broccolini-discord.js	Gate poll start in ready on the flag
commands/register.js	Register /email on|off|status
handlers/commands/index.js	Add handleEmail; guard handleGmailPoll
.env.example	Document GMAIL_POLL_ENABLED (optional, default true)

No DB schema changes. No destructive data ops. The mailbox is never read while OFF and is never written by this feature.

Verification

• /email off → logs show no further poll cycles; .env contains GMAIL_POLL_ENABLED=false.
• Restart container → no polling on boot; /email status reports off.
• /email on → poll resumes (immediate cycle), .env flips to true.
• While OFF, /gmailpoll 60 → interval saved, no polling starts.
• npm test (covers services/configSchema.js); node --check on every edited file.