@kody/twitch
Look up Twitch users, channels, streams, and follows, with dry-run chat and channel updates.
Files
@kody/twitch
Official Twitch Glitch logo (#9146FF) from Twitch brand guidelines. Twitch® is
a trademark of Twitch Interactive, Inc. This package is not affiliated with or
endorsed by Twitch.
Share this package as https://kody.codes/@kody/twitch
(never a /community/{listing_id} URL).
Intent
Give any Kody account reusable, headless Twitch Helix helpers for user and
channel lookup, live stream status, and follows as Helix allows. Writes (chat
and channel settings) preview with dryRun: true and run only after
confirm: true. Author identity is always resolved from the connected token —
never hard-coded to a specific channel.
This listing is meant to be forked. After you fork, connect your Twitch
account and run smoke-test on your copy. Do not treat the live
@kody/twitch integration as yours.
What it does
- Look up Twitch users or channel title/game metadata
- Check whether one or more channels are live
- List channels the authorizing user follows, or live streams from those channels
- Read a channel’s follower total (and the follower list when Helix allows it)
- Preview a chat message or channel-title update with
dryRun: true, then apply it only afterconfirm: true - Call uncommon Helix endpoints through
./request
Do not use this package as an EventSub receiver, a chat bot framework, or a place to paste access tokens.
Prerequisites / setup
Twitch is bring-your-own OAuth. There is no built-in Kody Twitch app.
Tokens come from the hosted connect page (createAuthenticatedFetch('twitch')).
Never paste a client secret or access token into chat.
Helix requires both Authorization and Client-Id. Both come from the saved
integration (clientId is sent as Client-Id on every call).
- Open dev.twitch.tv/console/apps → Register Your Application.
- Set OAuth Redirect URLs to exactly
https://kody.codes/connect/oauth(the connect page shows the same value with a copy button). - Category: Application Integration.
- Note the app’s Client ID and Client Secret (paste them into Kody, not into chat).
- Open this prefilled connect URL while signed in to Kody:
https://kody.codes/connect/oauth?provider=twitchFirst-time setup also needs Twitch’s authorize and token URLs. Use this complete prefilled URL when the connection does not exist yet:
https://kody.codes/connect/oauth?provider=twitch&authorizeUrl=https%3A%2F%2Fid.twitch.tv%2Foauth2%2Fauthorize&tokenUrl=https%3A%2F%2Fid.twitch.tv%2Foauth2%2Ftoken&apiBaseUrl=https%3A%2F%2Fapi.twitch.tv%2Fhelix&flow=confidential&tokenExchangeStyle=form&allowedHosts=api.twitch.tv%2Cid.twitch.tv&dashboardUrl=https%3A%2F%2Fdev.twitch.tv%2Fconsole%2Fapps&scopes=user%3Aread%3Afollows%20moderator%3Aread%3Afollowers%20user%3Awrite%3Achat%20moderator%3Aread%3Achatters%20channel%3Amanage%3AbroadcastDecoded:
- Redirect / callback:
https://kody.codes/connect/oauth - Authorize:
https://id.twitch.tv/oauth2/authorize - Token:
https://id.twitch.tv/oauth2/token - API base:
https://api.twitch.tv/helix - Flow:
confidentialwithtokenExchangeStyle=form - Hosts:
api.twitch.tv,id.twitch.tv - Scopes:
user:read:follows,moderator:read:followers,user:write:chat,moderator:read:chatters,channel:manage:broadcast
- Paste the Client ID and Client Secret into the Kody form, continue to Twitch, and approve.
- Run smoke-test on the forked package.
Reconnect the same connection with https://kody.codes/connect/oauth?provider=twitch. Kody reuses the saved authorize/token endpoints.
To connect a second Twitch account, change provider to a distinct name such as twitch-work, then pass integration: 'twitch-work' on every helper call.
Scopes
| Scope | Used by |
|---|---|
| none extra | smoke-test, get-me, get-user, get-channel, get-stream |
user:read:follows | list-follows, list-followed-streams |
moderator:read:followers | list-followers (follower list; total is returned without it) |
moderator:read:chatters | list-chatters |
user:write:chat | send-chat-message |
channel:manage:broadcast | update-channel-info |
Agents: see AGENTS.md for import paths, smoke checks, and
mutation guards.
Done when
- Forked copy has a working
twitchOAuth connection with the scopes above - Smoke-test returns
{ ok: true, hasUserId: true, hasLogin: true }without names or emails - Chat/channel helpers refuse without
confirm: true;dryRun: truenever mutates Twitch
Branding
Keep LICENSE (MIT), ## Intent, and community-icon.svg intact for community listing.
Troubleshooting
- Connect page asks for authorize/token URLs: use the complete first-time URL above.
- HTTP 401 / expired token: reconnect at
https://kody.codes/connect/oauth?provider=twitch. - HTTP 403 / missing scope: add the scope on the Twitch app, then reconnect.
- Follower list is empty but
totalis set: the token user is not the broadcaster/moderator, ormoderator:read:followersis missing. redirect_urimismatch: the Twitch app redirect must be exactlyhttps://kody.codes/connect/oauth.- Host approval for
api.twitch.tvstays in the account security UI.