Bot Viewer Detector

Scans your Twitch chat's current viewer list and flags accounts that look like follow/view-bots, so you can review and block them manually. Nothing is banned automatically.

Connect my channel

After connecting: mod the bot with /mod guildscribebot (or whichever account owns TWITCH_BOT_ID) so it can reply to !botcheck.

`,\n );\n }\n\n const data = await getFlaggedChatters(broadcasterId);\n const broadcaster = await getBroadcaster(broadcasterId);\n if (!data) {\n return page(\n \"Bot Viewer Detector\",\n `

Reconnect needed

This channel's Twitch connection has expired or been revoked.

Reconnect

`,\n );\n }\n\n const rows = data.results\n .map(\n (r) =>\n `${\n escapeHtml(r.displayName)\n }${r.score}${r.accountAgeDays}d${\n escapeHtml(r.reasons.join(\"; \"))\n }`,\n )\n .join(\"\");\n\n return page(\n \"Likely Bot Viewers\",\n `

Likely Bot Viewers${\n broadcaster ? ` — ${escapeHtml(String(broadcaster.display_name))}` : \"\"\n }

${data.totalChatters} chatters checked · ${data.results.length} flagged for review. Heuristic guess, not a certainty — check an account before blocking it.

\n \n \n ${rows || ''}\n

Username	Score	Account age	Why flagged
Nothing flagged right now.

\n \n

Reconnect / grant new permissions

`,\n );\n});\n\napp.get(\"/json\", async (c) => {\n const broadcasterId = await resolveBroadcasterId(c);\n if (!broadcasterId) {\n return c.json({ error: \"No channel connected yet. Visit /connect.\" }, 400);\n }\n const data = await getFlaggedChatters(broadcasterId);\n if (!data) {\n return c.json(\n { error: \"This channel needs to reconnect at /connect.\" },\n 401,\n );\n }\n return c.json({ total_chatters: data.totalChatters, flagged: data.results });\n});\n\n// ── OAuth connect flow ──\n\napp.get(\"/connect\", async (c) => {\n const state = crypto.randomUUID();\n await saveOAuthState(state, Date.now() + 10 * 60 * 1000);\n const url = new URL(c.req.url);\n const auth = new URL(\"https://id.twitch.tv/oauth2/authorize\");\n auth.search = new URLSearchParams({\n client_id: env(\"TWITCH_CLIENT_ID\"),\n redirect_uri: `${url.origin}/callback`,\n response_type: \"code\",\n // Broadcasters are implicitly moderators of their own channel, so\n // authorizing here as the broadcaster covers moderator:read:chatters too.\n scope: \"channel:bot moderator:read:chatters\",\n state,\n }).toString();\n return new Response(null, {\n status: 302,\n headers: { Location: auth.toString() },\n });\n});\n\napp.get(\"/callback\", async (c) => {\n const url = new URL(c.req.url);\n const error = url.searchParams.get(\"error\");\n if (error) {\n return page(\n \"Connection cancelled\",\n `

Connection cancelled

${\n escapeHtml(url.searchParams.get(\"error_description\") ?? error)\n }

`,\n );\n }\n const code = url.searchParams.get(\"code\");\n const state = url.searchParams.get(\"state\");\n if (!code || !state) return c.text(\"Missing OAuth code or state\", 400);\n const valid = await consumeOAuthState(state);\n if (!valid) return c.text(\"Invalid or expired OAuth state\", 400);\n\n try {\n const token = await exchangeCode(code, `${url.origin}/callback`);\n const user = await getSelf(token.access_token);\n\n // Reconnecting would otherwise try to create a duplicate\n // channel.chat.message subscription with the same type/condition/\n // callback, which Twitch rejects — clean up first so this is safe to\n // run repeatedly (e.g. to pick up newly requested scopes).\n const existing = await getBroadcaster(user.id);\n if (existing?.subscription_id) {\n try {\n await deleteEventSubSubscription(String(existing.subscription_id));\n } catch (e) {\n console.error(\"eventsub cleanup failed\", e);\n }\n }\n\n const sub = await createChatSubscription(user.id, `${url.origin}/eventsub`);\n await upsertBroadcaster(user.id, user.login, user.display_name, sub.id);\n await saveModToken(\n user.id,\n token.access_token,\n token.refresh_token,\n Array.isArray(token.scope)\n ? token.scope.join(\" \")\n : String(token.scope ?? \"\"),\n Date.now() + Math.max(0, Number(token.expires_in ?? 0) * 1000 - 60_000),\n );\n\n return page(\n \"Connected\",\n `

Connected

${\n escapeHtml(user.display_name)\n } is now connected. !botcheck will work once the bot is modded.

Important: in Twitch chat, run /mod guildscribebot (or whichever account owns TWITCH_BOT_ID) so it can reply.

View dashboard

`,\n );\n } catch (e) {\n console.error(e);\n return page(\n \"Connection failed\",\n `

Connection failed

Could not complete the Twitch connection. Please try again.

`,\n );\n }\n});\n\n// ── EventSub webhook: challenge handshake + incoming chat messages ──\n\napp.post(\"/eventsub\", async (c) => {\n const rawBody = await c.req.text();\n const valid = await verifyEventSub(c.req.raw, rawBody);\n if (!valid) return c.text(\"Invalid signature\", 403);\n\n const messageType = c.req.header(\"Twitch-Eventsub-Message-Type\");\n const payload = JSON.parse(rawBody);\n\n if (messageType === \"webhook_callback_verification\") {\n return c.text(payload.challenge, 200);\n }\n\n if (messageType === \"revocation\") {\n console.error(\"EventSub subscription revoked:\", payload.subscription);\n return c.text(\"\", 200);\n }\n\n if (\n messageType === \"notification\" &&\n payload.subscription?.type === \"channel.chat.message\"\n ) {\n const event = payload.event;\n const text: string = event?.message?.text ?? \"\";\n const broadcasterId: string = event?.broadcaster_user_id;\n\n if (text.trim().toLowerCase().startsWith(\"!botcheck\")) {\n handleBotCheck(broadcasterId).catch((err) =>\n console.error(\"botcheck failed\", err)\n );\n }\n\n return c.text(\"\", 200);\n }\n\n return c.text(\"\", 200);\n});\n\nasync function handleBotCheck(broadcasterId: string) {\n const data = await getFlaggedChatters(broadcasterId);\n if (!data) {\n await sendChatMessage(\n \"🤖 Bot check needs the channel to reconnect — visit /connect.\",\n broadcasterId,\n );\n return;\n }\n const reply = data.results.length === 0\n ? `🤖 No likely bot viewers spotted out of ${data.totalChatters} in chat right now.`\n : `🤖 ${data.results.length} likely bot viewer${\n data.results.length === 1 ? \"\" : \"s\"\n } out of ${data.totalChatters} in chat right now.`;\n await sendChatMessage(reply, broadcasterId);\n}\n\nexport default app.fetch;","botdetector",[134],"38500745-f00c-485f-813c-835b14d9a297","db.ts","725abbfa-b0a1-11f1-9048-1607ee4eb77e",19,["D",1789434299195],2,"// Storage for the bot-viewer detector — connected broadcasters and their\n// moderator:read:chatters tokens. Mirrors GuildScribe's db.ts / ads_db.ts\n// conventions (INSERT OR REPLACE, broadcaster_id-keyed rows) so behavior\n// matches your other bots if this ever moves into the same monorepo.\n\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\n\nexport async function ensureTables() {\n await sqlite.execute(\n `CREATE TABLE IF NOT EXISTS oauth_states (state TEXT PRIMARY KEY, expires_at INTEGER)`,\n );\n await sqlite.execute(\n `CREATE TABLE IF NOT EXISTS broadcasters (\n broadcaster_id TEXT PRIMARY KEY, login TEXT, display_name TEXT,\n subscription_id TEXT, connected_at INTEGER, connected INTEGER NOT NULL DEFAULT 1\n )`,\n );\n // The connecting account's own OAuth token, scope moderator:read:chatters —\n // refreshed on demand (see getValidModToken in twitch.ts). Broadcasters are\n // implicitly moderators of their own channel, so having the broadcaster\n // authorize at /connect is enough; no separate mod account login needed.\n await sqlite.execute(\n `CREATE TABLE IF NOT EXISTS mod_tokens (\n broadcaster_id TEXT PRIMARY KEY, access_token TEXT NOT NULL, refresh_token TEXT NOT NULL,\n scope TEXT, expires_at INTEGER NOT NULL, updated_at INTEGER NOT NULL\n )`,\n );\n}\n\nexport async function saveOAuthState(state: string, expiresAt: number) {\n await sqlite.execute(\n \"INSERT INTO oauth_states (state, expires_at) VALUES (?,?)\",\n [state, expiresAt],\n );\n}\n\n/** Deletes the state either way (single use), returns whether it was valid. */\nexport async function consumeOAuthState(state: string): Promise {\n const check = await sqlite.execute(\n \"SELECT * FROM oauth_states WHERE state = ? AND expires_at > ?\",\n [\n state,\n Date.now(),\n ],\n );\n await sqlite.execute(\"DELETE FROM oauth_states WHERE state = ?\", [state]);\n return check.rows.length > 0;\n}\n\nexport async function upsertBroadcaster(\n broadcasterId: string,\n login: string,\n displayName: string,\n subscriptionId: string,\n) {\n await sqlite.execute(\n `INSERT OR REPLACE INTO broadcasters (broadcaster_id, login, display_name, subscription_id, connected_at, connected)\n VALUES (?,?,?,?,?,1)`,\n [broadcasterId, login, displayName, subscriptionId, Date.now()],\n );\n}\n\nexport async function getBroadcaster(broadcasterId: string) {\n const res = await sqlite.execute(\n \"SELECT * FROM broadcasters WHERE broadcaster_id = ?\",\n [broadcasterId],\n );\n return res.rows.length ? res.rows[0] : null;\n}\n\n/** This is a personal-use tool, so in practice one channel connects. Used by\n * \"/\" and \"/json\" when no ?channel= query param is given. */\nexport async function getFirstConnectedBroadcaster() {\n const res = await sqlite.execute(\n \"SELECT * FROM broadcasters WHERE connected = 1 ORDER BY connected_at ASC LIMIT 1\",\n );\n return res.rows.length ? res.rows[0] : null;\n}\n\nexport async function saveModToken(\n broadcasterId: string,\n accessToken: string,\n refreshToken: string,\n scope: string,\n expiresAt: number,\n) {\n await sqlite.execute(\n `INSERT OR REPLACE INTO mod_tokens (broadcaster_id, access_token, refresh_token, scope, expires_at, updated_at)\n VALUES (?,?,?,?,?,?)`,\n [broadcasterId, accessToken, refreshToken, scope, expiresAt, Date.now()],\n );\n}\n\nexport async function getModToken(broadcasterId: string) {\n const res = await sqlite.execute(\n \"SELECT * FROM mod_tokens WHERE broadcaster_id = ?\",\n [broadcasterId],\n );\n return res.rows.length ? res.rows[0] : null;\n}",[141],"46df2354-64f4-4991-8d06-30482d932865","botDetection.ts","8475738a-b09b-11f1-a52d-1607ee4eb77e",5,["D",1789431761819],"import type { TwitchUser } from \"./twitch.ts\";\n\n// Well-known, legitimate service bots — never flag these regardless of score.\n// Add your own bot accounts here (e.g. your GuildScribe/Hunt & Hoard bot logins).\nconst KNOWN_SAFE_BOTS = new Set([\n \"nightbot\",\n \"streamelements\",\n \"streamlabs\",\n \"moobot\",\n \"soundalerts\",\n \"wizebot\",\n \"fossabot\",\n \"pretzelrocks\",\n \"own3d\",\n \"sery_bot\",\n \"restreambot\",\n \"commanderroot\",\n]);\n\n// Shapes commonly produced by follow/view-bot generator tools.\nconst BOT_NAME_PATTERNS = [\n /^[a-z]{3,12}\\d{5,}$/i, // short word + 5+ trailing digits, e.g. \"coolgamer88421\"\n /^[a-z0-9]{16,}$/i, // long random alphanumeric blob\n];\n\nexport interface BotScoreResult {\n login: string;\n displayName: string;\n score: number;\n reasons: string[];\n accountAgeDays: number;\n profileUrl: string;\n}\n\n/** Returns null if the account isn't flagged at all. */\nexport function scoreUser(user: TwitchUser): BotScoreResult | null {\n const login = user.login.toLowerCase();\n if (KNOWN_SAFE_BOTS.has(login)) return null;\n\n const reasons: string[] = [];\n let score = 0;\n\n const createdAt = new Date(user.created_at).getTime();\n const ageDays = (Date.now() - createdAt) / (1000 * 60 * 60 * 24);\n\n if (ageDays < 3) {\n score += 3;\n reasons.push(`Account is ${ageDays.toFixed(1)} days old`);\n } else if (ageDays < 14) {\n score += 2;\n reasons.push(`Account is only ${Math.round(ageDays)} days old`);\n } else if (ageDays < 45) {\n score += 1;\n reasons.push(`Account is ${Math.round(ageDays)} days old`);\n }\n\n if (\n !user.profile_image_url ||\n user.profile_image_url.includes(\"user-default-pictures\")\n ) {\n score += 2;\n reasons.push(\"Using the default profile picture\");\n }\n\n if (BOT_NAME_PATTERNS.some((p) => p.test(login))) {\n score += 2;\n reasons.push(\"Username matches common bot-generator patterns\");\n }\n\n if (score === 0) return null;\n\n return {\n login: user.login,\n displayName: user.display_name,\n score,\n reasons,\n accountAgeDays: Math.round(ageDays),\n profileUrl: `https://twitch.tv/${user.login}`,\n };\n}",[149],"62666a88-9024-4411-9fd6-9955295cd17e","README.md","92e96052-b09b-11f1-b904-1607ee4eb77e",14,["D",1789434214479],"# Bot Viewer Detector\n\nScans your Twitch chat's current viewer list and flags accounts that look like\nfollow/view-bots, so you can review and block them manually. Nothing is banned\nautomatically.\n\n- **`/`** — dashboard: sorted table of flagged accounts with reasons. Once\n connected, this is also the landing page.\n- **`/json`** — same data as JSON.\n- **`!botcheck`** — chat command that replies with just the count, e.g. \"🤖 4\n likely bot viewers out of 212 in chat right now.\"\n\n## What changed from the env-var version\n\nYou no longer set `TWITCH_BROADCASTER_LOGIN` or `TWITCH_MOD_OAUTH_TOKEN` by\nhand. Instead, visiting `/connect` and authorizing on Twitch captures your\nlogin, ID, and a refreshable moderator:read:chatters token automatically — same\nOAuth pattern GuildScribe already uses (`/connect` → Twitch → `/callback`),\nstored in this project's own SQLite database. The token also now refreshes\nitself instead of expiring every ~4 hours.\n\n## How detection works\n\nEach chatter is scored on:\n\n- Account age (younger = more suspicious)\n- Default/missing profile picture\n- Username shape (word+digits, long random strings — common bot-generator\n patterns)\n\nKnown legitimate bots (Nightbot, StreamElements, etc. — see `botDetection.ts`)\nare always excluded. This is heuristic, not certain — glance at a flagged\naccount before blocking it.\n\n## Setup on Val Town\n\n1. Create a new Val Town project and upload `main.ts`, `twitch.ts`, `db.ts`, and\n `botDetection.ts`. Set `main.ts` as the HTTP val entrypoint.\n2. Add these four environment variables (account-level Environment Variables\n page):\n\n | Key | Value |\n | ---------------------- | ------------------------------------------------------------------- |\n | `TWITCH_CLIENT_ID` | your app's Client ID — reuse GuildScribe's |\n | `TWITCH_CLIENT_SECRET` | your app's Client Secret — reuse GuildScribe's |\n | `TWITCH_BOT_ID` | your bot account's numeric user id — reuse GuildScribe's |\n | `EVENTSUB_SECRET` | any random string you make up — doesn't need to match GuildScribe's |\n\n3. Open the val's URL — you'll land on a \"Connect my channel\" page. Click it,\n authorize on Twitch, and you're done: broadcaster login, chatters token, and\n EventSub subscription are all set up automatically in that one step.\n4. In Twitch chat, run `/mod guildscribebot` (or whichever account owns\n `TWITCH_BOT_ID`) if it isn't already modded, so it's allowed to speak.\n5. Type `!botcheck` in chat — you should get a reply within a few seconds.\n6. Reloading `/` from then on shows the dashboard directly, no reconnecting\n needed unless Twitch revokes the authorization.\n\n## Known limitations\n\n- If the stored token ever gets revoked (e.g. you remove the app's access in\n your Twitch settings), `!botcheck` and `/` will say the channel needs to\n reconnect — just visit `/connect` again.\n- `!botcheck` re-scans the whole chatter list on every call, so there's a couple\n seconds of delay before the reply — that's expected, not a bug.",[156],"pulls","branches",1,"forks","envVars",{"_170":172,"_173":42},"connections",{"_170":42,"_171":42},"count","unfilledCount",4,"emptyCount",{"_18":155,"_20":156,"_117":157,"_119":-5,"_120":71,"_121":158,"_123":38,"_22":192,"_68":151,"_126":99,"_128":160,"_130":26,"_131":-5,"_180":193,"_89":194},{"_18":148,"_20":149,"_117":150,"_119":-5,"_120":71,"_121":151,"_123":38,"_22":189,"_68":145,"_126":127,"_128":153,"_130":26,"_131":-5,"_180":190,"_89":191},{"_18":140,"_20":141,"_117":142,"_119":-5,"_120":71,"_121":143,"_123":38,"_22":186,"_68":145,"_126":127,"_128":146,"_130":26,"_131":-5,"_180":187,"_89":188},{"_18":133,"_20":134,"_117":36,"_119":-5,"_120":71,"_121":69,"_123":38,"_22":183,"_68":125,"_126":136,"_128":137,"_130":26,"_131":138,"_180":184,"_89":185},{"_18":115,"_20":116,"_117":118,"_119":-5,"_120":71,"_121":122,"_123":38,"_22":179,"_68":125,"_126":127,"_128":129,"_130":26,"_131":-5,"_180":181,"_89":182},["D",1789434268736],"children",[],[116],["D",1789434764818],[],[134],["D",1789434299195],[],[141],["D",1789431761819],[],[149],["D",1789434214479],[],[156],["D",1789431551373],["D",1789522252250],{"_16":17,"_87":83},{"_16":17,"_80":81,"_82":83,"_33":34,"_84":85,"_86":26},{"_68":69,"_20":70,"_18":71,"_72":19,"_73":-5,"_74":-5,"_75":-5,"_76":-5,"_77":-5,"_78":21,"_79":17},"ctx",{"_61":-5,"_107":233,"_234":235,"_236":237,"_238":26,"_239":26,"_240":26,"_241":38,"_242":-5,"_243":-7,"_244":-7,"_245":42,"_246":26,"_247":26,"_248":-5,"_249":26,"_250":26,"_251":26,"_252":-5},"ENV",{"_204":205,"_206":207,"_208":70,"_209":210,"_211":212,"_213":214,"_215":216,"_217":218,"_219":220,"_221":222,"_223":224,"_225":226,"_227":228,"_229":230,"_231":232},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]