igdb-wrapper

A type-safe TypeScript client for the IGDB API with a fluent query builder, automatic retries, and built-in rate limiting.

const games = await client.games
  .query()
  .select((g) => ({ name: g.name, rating: g.rating }))
  .where((g, { or }) => or(g.rating.gte(90), g.aggregated_rating.gte(90)))
  .sort((g) => g.rating, "desc")
  .limit(10)
  .execute();

Features

• Fully type-safe — field selection and where conditions are inferred from your model types, with no stringly-typed field names
• Fluent query builder — chainable .select(), .where(), .sort(), .limit(), .offset(), .search()
• Automatic retries — exponential backoff on transient failures, configurable
• Rate limiting — respects IGDB's concurrency limits out of the box
• Pagination — async generator via .paginate(), plus .count() for UI pagination
• Structured errors — IGDBAuthError, IGDBRateLimitError, IGDBNotFoundError, IGDBValidationError

Installation

npm install @api-wrappers/igdb-wrapper
# or
yarn add @api-wrappers/igdb-wrapper
# or
pnpm add @api-wrappers/igdb-wrapper
# or
bun add @api-wrappers/igdb-wrapper

Requirements: Node.js 18+ (uses native fetch). TypeScript 5+ recommended.

Quick Start

You'll need a Twitch Developer application to obtain a client_id and client_secret.

import { IGDBClient } from "@api-wrappers/igdb-wrapper";

const client = new IGDBClient({
  clientId: process.env.TWITCH_CLIENT_ID!,
  clientSecret: process.env.TWITCH_CLIENT_SECRET!,
});

const game = await client.games
  .query()
  .where((g) => g.slug.eq("elden-ring"))
  .first();

console.log(game?.name); // "Elden Ring"

Documentation

| Guide | Description | |---|---| | Getting Started | Installation, credentials, and your first query | | Querying | Full query builder API — select, where, sort, paginate | | Endpoints | Games, Genres, Platforms, Companies | | Error Handling | All error types and how to handle them | | Configuration | Retry, rate limiting, and advanced options | | API Reference | Complete method signatures |

License

This project is licensed under the MIT License - see the LICENSE file for details.

❤️