{"_id":"@carlosnc/igdb-sdk","_rev":"2-89f4bd00a37e5c25bbd8b0e7bf145a99","name":"@carlosnc/igdb-sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@carlosnc/igdb-sdk","version":"0.1.1","keywords":["igdb","twitch","sdk","api","games","videogames"],"author":{"url":"https://github.com/carllosnc","name":"Carlos Costa"},"license":"MIT","_id":"@carlosnc/igdb-sdk@0.1.1","maintainers":[{"name":"carlosnc","email":"carllos.nc@gmail.com"}],"homepage":"https://github.com/carllosnc/igdb-sdk#readme","bugs":{"url":"https://github.com/carllosnc/igdb-sdk/issues"},"dist":{"shasum":"72d524d1b3a21be0f1df175df79f88c990757e98","tarball":"https://registry.npmjs.org/@carlosnc/igdb-sdk/-/igdb-sdk-0.1.1.tgz","fileCount":237,"integrity":"sha512-iHhazaROx6UipqC8qs0AZhzEvWYUbLepVkppQPr74z3H73LcAzpWpBbEcB2ftcp6Kr7y8J0vH3YOaI8qZDsqrg==","signatures":[{"sig":"MEUCIQDrQXPO2xousZfq+HNRC2YEyhEswlOeNrUfhsUBtm3v9wIgATLISpA3+lg+KOsmmuvE9BSgdHfkK6BTqnH2HL6oEsc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":248262},"main":"./dist/cjs/index.js","type":"module","types":"./dist/esm/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/esm/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"},"./package.json":"./package.json"},"gitHead":"0f710910c80ef9e19a391e074ac82d3684b76fcc","scripts":{"test":"bun test","build":"tsc -p tsconfig.build.json && tsc -p tsconfig.build.cjs.json","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"_npmUser":{"name":"carlosnc","email":"carllos.nc@gmail.com"},"repository":{"url":"git+https://github.com/carllosnc/igdb-sdk.git","type":"git"},"_npmVersion":"11.6.2","description":"Unofficial IGDB API v4 SDK for TypeScript","directories":{},"sideEffects":false,"_nodeVersion":"24.11.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/igdb-sdk_0.1.1_1779906227847_0.3401848874654032","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-27T18:23:47.624Z","modified":"2026-07-17T23:52:17.857Z","0.1.1":"2026-05-27T18:23:47.999Z"},"bugs":{"url":"https://github.com/carllosnc/igdb-sdk/issues"},"author":{"url":"https://github.com/carllosnc","name":"Carlos Costa"},"license":"MIT","homepage":"https://github.com/carllosnc/igdb-sdk#readme","keywords":["igdb","twitch","sdk","api","games","videogames"],"repository":{"url":"git+https://github.com/carllosnc/igdb-sdk.git","type":"git"},"description":"Unofficial IGDB API v4 SDK for TypeScript","maintainers":[{"email":"carllos.nc@gmail.com","name":"carllosnc"}],"readme":"\n<picture>\n  <img alt=\"IGDB logo\" src=\"https://upload.wikimedia.org/wikipedia/commons/1/19/IGDB_logo.svg\" width=\"70\">\n</picture>\n\n# IGDB SDK\n\n[![CI](https://github.com/carllosnc/igdb-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/carllosnc/igdb-sdk/actions/workflows/ci.yml)\n\nUnofficial [IGDB API v4](https://api-docs.igdb.com/) SDK for TypeScript.\n\nZero runtime dependencies — uses the global `fetch` API (Node 18+, Bun, Deno).\n\n## Setup\n\n```bash\nnpm install @carlosnc/igdb-sdk\n```\n\n```bash\nbun install @carlosnc/igdb-sdk\n```\n\nCopy `.env.example` to `.env` and fill in your Twitch credentials ([register here](https://dev.twitch.tv/console/apps)):\n\n```bash\ncp .env.example .env\n```\n\n## Usage\n\n```typescript\nimport { IGDBClient, gameQuery } from \"@carlosnc/igdb-sdk\";\n\nconst client = new IGDBClient({\n  clientId: process.env.TWITCH_CLIENT_ID!,\n  clientSecret: process.env.TWITCH_CLIENT_SECRET!,\n});\n\nconst games = await client.game.getGames(\n  gameQuery()\n    .fields(\"name\", \"rating\", \"cover\")\n    .where(\"rating\", \">\", 80)\n    .sort(\"rating\", \"desc\")\n    .limit(5)\n    .build(),\n);\n```\n\n### QueryBuilder\n\nBuild IGDB query strings with a typed chainable API. Field names auto-complete from the response type.\n\n| Method | Example |\n|---|---|\n| `.fields(\"name\", \"rating\")` | Select fields |\n| `.expand(\"cover.url\", \"screenshots.url\")` | Nested expansions (dot notation) |\n| `.where(\"rating\", \">\", 80)` | Filter conditions |\n| `.where(\"platforms\", \"=\", [48, 130])` | Array containment |\n| `.whereIn(\"id\", [1020, 1025])` | IN-list (`id = (1020,1025)`) |\n| `.sort(\"rating\", \"desc\")` | Sort direction |\n| `.search(\"Mario\")` | Full-text search |\n| `.limit(5).offset(10)` | Pagination |\n| `.build()` | Produces final query string |\n\nTyped factory functions: `gameQuery()`, `platformQuery()`, `companyQuery()`, `searchQuery()`, `genreQuery()`, `themeQuery()`, `coverQuery()`, `franchiseQuery()`, `playerPerspectiveQuery()`, and more. For ad-hoc types use `queryFor<T>()`.\n\n### Bare string (for complex queries)\n\n```typescript\nclient.game.getGames(\"fields name,rating; where rating > 80; sort rating desc; limit 5;\");\n```\n\n### Convenience methods\n\n```typescript\n// Get by ID — returns item or null\nconst game = await client.game.getById(1020, \"name,rating,cover\");\n\n// Count matching records\nconst count = await client.game.getCount(\"where rating > 80;\");\n```\n\n### Error handling\n\n```typescript\nimport { IgdbApiError, IgdbAuthError, IgdbRateLimitError } from \"@carlosnc/igdb-sdk\";\n\ntry {\n  await client.query(\"games\", \"...\");\n} catch (e) {\n  if (e instanceof IgdbRateLimitError) console.log(\"rate limited\");\n  if (e instanceof IgdbAuthError) console.log(\"bad credentials\");\n  if (e instanceof IgdbApiError) console.log(`${e.statusCode} on ${e.endpoint}`);\n}\n```\n\n### Retry\n\nTransient failures (429, 5xx, network errors) are retried automatically with exponential backoff.\n\n```typescript\nconst client = new IGDBClient({\n  clientId: \"...\",\n  clientSecret: \"...\",\n  retry: { maxRetries: 5, baseDelayMs: 500 },\n});\n```\n\n### Middleware\n\nIntercept requests and responses with custom hooks.\n\n```typescript\nconst logger = {\n  name: \"logger\",\n  onRequest(ctx) { console.log(`→ ${ctx.endpoint}`); return ctx; },\n  onResponse(res, ctx) { console.log(`← ${ctx.endpoint} ${res.status}`); return res; },\n  onError(err, ctx) { console.error(`✗ ${ctx.endpoint} ${err.message}`); },\n};\n\nconst client = new IGDBClient({ clientId, clientSecret, middlewares: [logger] });\n```\n\n### Custom HttpClient\n\nInject your own HTTP layer — useful for adding tracing, using axios, or mocking in tests.\n\n```typescript\nimport type { HttpClient } from \"@carlosnc/igdb-sdk\";\n\nconst tracingClient: HttpClient = {\n  async post(url, headers, body) {\n    console.log(`POST ${url}`);\n    const res = await fetch(url, { method: \"POST\", headers, body });\n    return { status: res.status, body: await res.text(), headers: Object.fromEntries(res.headers.entries()) };\n  },\n};\n\nconst client = new IGDBClient({ clientId, clientSecret, httpClient: tracingClient });\n```\n\n### Debug mode\n\nBuilt-in request/response logging — shorthand for the logger middleware above.\n\n```typescript\nconst client = new IGDBClient({ clientId, clientSecret, debug: true });\n// → games\n//   body: fields name,rating; limit 5;\n// ← games 200\n```\n\n## Examples\n\nSee [`examples/`](./examples) for runnable scripts. Run with your `.env` file loaded:\n\n```bash\nbun run --env-file .env examples/basic-usage.ts          # intro\nbun run --env-file .env examples/search-games.ts          # search + filters\nbun run --env-file .env examples/game-details.ts          # multi-endpoint assembly\nbun run --env-file .env examples/company-and-platforms.ts # company info + platforms\nbun run --env-file .env examples/reference-data.ts        # parallel queries + dynamic building\nbun run --env-file .env examples/middleware.ts             # middleware pipeline\nbun run --env-file .env examples/error-handling-and-retry.ts\nbun run --env-file .env examples/query-count-and-by-id.ts\n```\n\n## Sub-clients\n\n| Client | Endpoints |\n|---|---|\n| `client.game` | games, game_engines, game_engine_logos, game_localizations, game_modes, game_release_formats, game_statuses, game_time_to_beats, game_types, game_videos |\n| `client.platform` | platforms, platform_families, platform_logos, platform_types, platform_versions, platform_version_companies, platform_version_release_dates, platform_websites |\n| `client.company` | companies, company_logos, company_sizes, company_statuses, company_type_histories, company_types, company_websites |\n| `client.ageRating` | age_ratings, age_rating_categories, age_rating_content_descriptions, age_rating_content_description_types, age_rating_content_descriptions_v2, age_rating_organizations |\n| `client.artwork` | artworks, artwork_types, covers, screenshots |\n| `client.character` | characters, character_genders, character_mug_shots, character_species |\n| `client.collection` | collections, collection_memberships, collection_membership_types, collection_relations, collection_relation_types, collection_types |\n| `client.event` | events, event_logos, event_networks |\n| `client.externalGame` | external_games, external_game_sources |\n| `client.popularity` | popularity_primitives, popularity_types |\n| `client.releaseDate` | release_dates, release_date_regions, release_date_statuses |\n| `client.report` | reports, report_types |\n| `client.search` | search |\n| `client.website` | websites, website_types |\n| `client.misc` | alternative_names, date_formats, entity_types, franchises, genres, involved_companies, keywords, languages, language_supports, language_support_types, multiplayer_modes, network_types, player_perspectives, regions, themes |\n\n## Scripts\n\n| Command | Action |\n|---|---|\n| `bun run build` | Compile ESM + CJS to `dist/` |\n| `bun test` | Run tests (140+) |\n| `bun run typecheck` | TypeScript type checking |\n\n---\n\nCarlos Costa @ 2026\n","readmeFilename":"README.md"}