twitch-gql-queries

Type-safe requests to twitch public GraphQL API

You can try queries right in the browser: Swagger UI / Scalar Swagger UI

Features

• Type-safe objects for all queries: Variables and Response
• Swagger UI to see and try all queries or generate types for your language
• TypeBox Schemas for Variables and Response objects
• Tests to validate types with real requests
• Zero dependencies

Installation

npm i twitch-gql-queries

pnpm i twitch-gql-queries

yarn add twitch-gql-queries

Usage

import {
  getQueryClipsCardsUser,
  getQueryStreamMetadata,
  getQueryFfzRecentBroadcasts,
  getQueryUseViewCount,
  gqlRequest,
} from 'twitch-gql-queries';

const [
  streamMetadataResponse,
  FfzRecentBroadcastsResponse,
  clipsCardsUserResponse,
] = await gqlRequest([
  getQueryStreamMetadata({ channelLogin: 'xqc' }),
  getQueryFfzRecentBroadcasts({ id: '71092938', sort: 'time', limit: 5 }),
  getQueryClipsCardsUser({
    login: 'xqc',
    limit: 30,
    criteria: { filter: 'LAST_MONTH' },
  }),
]);

console.log({
  streamMetadataResponse,
  ffzBroadcastIdResponse,
  clipsCardsUserResponse,
});

const channels = await gqlRequest(
  ['lirik', 'forsen'].map((channelLogin) =>
    getQueryUseViewCount({ channelLogin }),
  ),
);

console.log(channels);

Using raw queries:

import { getRawQuery, gqlRequest, type GetRawQueryReturnType } from 'twitch-gql-queries';

const query = `
query GetVideo($videoId: ID!) {
  video(id: $videoId) {
    id
    title
    game {
      id
      name
    }
  }
}`;
type GetVideoData = {
  video: {
    id: string;
    title: string;
    game: null | {
      id: string;
      name: string;
    }
  }
}
const getQueryGetVideo = (variables: { videoId: string }) =>
  ({ query, variables }) as GetRawQueryReturnType<GetVideoData>;

const responses = await gqlRequest([
  getRawQuery<GetVideoData>({
    query,
    variables: { videoId: '1622426365' },
  }),
  getQueryGetVideo({ videoId: '1816688726' }),
]);

console.log(responses);

Available queries

• BitsConfigContext_Global
• BrowsePage_AllDirectories
• ChannelRoot_AboutPanel
• ChannelShell
• ChannelVideoShelvesQuery
• ChatList_Badges
• ClipsCards__Game
• ClipsCards__User
• ClipsDownloadButton
• DirectoryPage_Game
• FFZ_RecentBroadcasts
• FilterableVideoTower_Videos
• GetPinnedChat
• GetUserID
• GlobalBadges
• PlaybackAccessToken
• SearchResultsPage_SearchResults
• SearchTray_SearchSuggestions
• ShareClipRenderStatus
• StreamMetadata
• UseLive
• UseViewCount
• VideoAccessToken_Clip
• VideoMetadata
• VideoPreviewOverlay
• WatchLivePrompt

Adding new query

Step 1. Generate query template

pnpm add-query QueryName

Step 2: Add schemas

Add VariablesSchema and DataSchema (data field in the query response) using TypeBox.

It's possible to export additional schemas like ClipSchema or UserSchema if needed. Schema name should end with Schema and should have an $id property. Use LegacyRef to link them to main schemas.

Step 3: Generate types

pnpm gen

Step 4: Add http requests

Add at least one http request to query.http. Add more cases for various scenarios if possible.

See VS Code REST Client extension

Step 5: Add tests

Add tests for all possible query responses.

If it's impossible to test some cases with real requests, add responses to src/queries/QueryName/mocks folder. For example:

• mocks/response-online.json
• mocks/response-offline.json
• mocks/response-banned.json

Currently banned channels can be found here: x.com/StreamerBans.

Removing query

pnpm remove-query QueryName