Skip to content
← Public packages

@kody/twitch

Look up Twitch users, channels, streams, and follows, with dry-run chat and channel updates.

FollowFork

Files

README.md

107 lines · 5.1 KB · Markdown

@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 after confirm: 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).

  1. Open dev.twitch.tv/console/apps → Register Your Application.
  2. Set OAuth Redirect URLs to exactly https://kody.codes/connect/oauth (the connect page shows the same value with a copy button).
  3. Category: Application Integration.
  4. Note the app’s Client ID and Client Secret (paste them into Kody, not into chat).
  5. Open this prefilled connect URL while signed in to Kody:
https://kody.codes/connect/oauth?provider=twitch

First-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%3Abroadcast

Decoded:

  • 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: confidential with tokenExchangeStyle=form
  • Hosts: api.twitch.tv, id.twitch.tv
  • Scopes: user:read:follows, moderator:read:followers, user:write:chat, moderator:read:chatters, channel:manage:broadcast
  1. Paste the Client ID and Client Secret into the Kody form, continue to Twitch, and approve.
  2. 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
ScopeUsed by
none extrasmoke-test, get-me, get-user, get-channel, get-stream
user:read:followslist-follows, list-followed-streams
moderator:read:followerslist-followers (follower list; total is returned without it)
moderator:read:chatterslist-chatters
user:write:chatsend-chat-message
channel:manage:broadcastupdate-channel-info

Agents: see AGENTS.md for import paths, smoke checks, and mutation guards.

Done when

  • Forked copy has a working twitch OAuth 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: true never 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 total is set: the token user is not the broadcaster/moderator, or moderator:read:followers is missing.
  • redirect_uri mismatch: the Twitch app redirect must be exactly https://kody.codes/connect/oauth.
  • Host approval for api.twitch.tv stays in the account security UI.