# @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](https://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: ```text 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: ```text 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` 6. Paste the Client ID and Client Secret into the Kody form, continue to Twitch, and approve. 7. 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`](./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.