Align wrapper with IGDB API

Author: TDanks2000

.changeset/igdb-api-alignment.md

@@ -0,0 +1,5 @@
+---
+"@api-wrappers/igdb-wrapper": minor
+---
+
+Align the wrapper with the current IGDB v4 API surface by adding all documented endpoints, broader APICalypse query support, multi-query, webhooks, metadata, protobuf, image URL, and tag-number helpers.

README.md

@@ -22,11 +22,14 @@ const games = await client.games
 
 ## 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()`
+- **All current IGDB v4 endpoints** — every endpoint listed in the official API docs is exposed on `IGDBClient`
+- **Fully type-safe** — field selection and where conditions are inferred from model types where available, with raw field helpers for new IGDB fields
+- **Fluent query builder** — chainable `.select()`, `.fields()`, `.exclude()`, `.where()`, `.whereRaw()`, `.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
+- **Multi-query and webhooks** — helpers for `/multiquery` and IGDB webhook management
+- **Reference helpers** — image URL and tag-number helpers, endpoint `/meta`, and protobuf response access
 - **Structured errors** — `IGDBAuthError`, `IGDBRateLimitError`, `IGDBNotFoundError`, `IGDBValidationError`
 
 ---
@@ -75,7 +78,7 @@ console.log(game?.name); // "Elden Ring"
 |---|---|
 | [Getting Started](./docs/getting-started.md) | Installation, credentials, and your first query |
 | [Querying](./docs/querying.md) | Full query builder API — select, where, sort, paginate |
-| [Endpoints](./docs/endpoints.md) | Games, Genres, Platforms, Companies |
+| [Endpoints](./docs/endpoints.md) | All IGDB v4 endpoint properties and raw endpoint access |
 | [Error Handling](./docs/error-handling.md) | All error types and how to handle them |
 | [Configuration](./docs/configuration.md) | Retry, rate limiting, and advanced options |
 | [API Reference](./docs/api-reference.md) | Complete method signatures |

docs/api-reference.md

@@ -8,12 +8,24 @@ Complete signatures for all public APIs.
 
 ```ts
 class IGDBClient {
-  readonly games: GamesEndpoint;
-  readonly genres: GenresEndpoint;
-  readonly platforms: PlatformsEndpoint;
-  readonly companies: CompaniesEndpoint;
+  readonly games: IGDBEndpoint<Game>;
+  readonly genres: IGDBEndpoint<Genre>;
+  readonly platforms: IGDBEndpoint<Platform>;
+  readonly companies: IGDBEndpoint<Company>;
+  // ...plus every endpoint listed in docs/endpoints.md
 
   constructor(config: IGDBClientConfig);
+  endpoint<TModel extends IGDBEntity = IGDBAnyEntity>(path: string): IGDBEndpoint<TModel>;
+  request<T = IGDBAnyEntity>(endpoint: string, query: string): Promise<T[]>;
+  count(endpoint: string, query?: string): Promise<number>;
+  meta(endpoint: string): Promise<MetaField[]>;
+  requestProtobuf(endpoint: string, query: string): Promise<ArrayBuffer>;
+  multiQuery<T = IGDBAnyEntity>(query: string): Promise<Array<MultiQueryResult<T>>>;
+  createWebhook(endpoint: string, options: CreateWebhookOptions): Promise<Webhook>;
+  listWebhooks(): Promise<Webhook[]>;
+  getWebhook(id: number | string): Promise<Webhook>;
+  deleteWebhook(id: number | string): Promise<Webhook>;
+  testWebhook(endpoint: string, webhookId: number | string, entityId: number | string): Promise<unknown>;
   dispose(): Promise<void>;
 }
 
@@ -47,6 +59,8 @@ class QueryBuilder<TModel, TShape = TModel> {
   select<TNewShape extends Record<string, unknown>>(
     selector: (proxy: SelectProxy<TModel>) => TNewShape
   ): QueryBuilder<TModel, TNewShape>;
+  fields(...fields: string[]): QueryBuilder<TModel, TShape>;
+  exclude(...fields: string[]): QueryBuilder<TModel, TShape>;
 
   // Filtering
   where(
@@ -55,6 +69,7 @@ class QueryBuilder<TModel, TShape = TModel> {
       helpers: WhereHelpers
     ) => Condition | Condition[]
   ): QueryBuilder<TModel, TShape>;
+  whereRaw(condition: string): QueryBuilder<TModel, TShape>;
 
   // Sorting
   sort(
@@ -68,6 +83,7 @@ class QueryBuilder<TModel, TShape = TModel> {
 
   // Full-text search
   search(term: string): QueryBuilder<TModel, TShape>;
+  apicalypse(clause: string): QueryBuilder<TModel, TShape>;
 
   // Execution
   execute(): Promise<TShape[]>;
@@ -93,6 +109,7 @@ Passed as the second argument to `.where()` callbacks.
 interface WhereHelpers {
   or(...conditions: Condition[]): Condition;
   and(...conditions: Condition[]): Condition;
+  raw(expression: string): Condition;
 }
 ```
 
@@ -111,51 +128,44 @@ interface ConditionBuilder<T> {
   lt(value: T): Condition;
   lte(value: T): Condition;
   in(values: T[]): Condition;
+  notIn(values: T[]): Condition;
   contains(value: T): Condition;
+  containsAll(values: T[]): Condition;
+  excludesAll(values: T[]): Condition;
+  exact(values: T[]): Condition;
+  isNull(): Condition;
+  notNull(): Condition;
+  startsWith(value: string, options?: TextMatchOptions): Condition;
+  endsWith(value: string, options?: TextMatchOptions): Condition;
+  containsText(value: string, options?: TextMatchOptions): Condition;
 }
 ```
 
 ---
 
-## Endpoint classes
+## Endpoint class
 
-### GamesEndpoint
+All client endpoint properties use the same class.
 
 ```ts
-class GamesEndpoint {
-  query(): QueryBuilder<Game>;
-  findMany(): QueryBuilder<Game>;           // query().limit(50)
-  findById(id: number): Promise<Game>;      // throws IGDBNotFoundError if missing
-  search(term: string): QueryBuilder<Game>; // query().search(term).limit(50)
+class IGDBEndpoint<TModel extends IGDBEntity = IGDBEntity> {
+  readonly path: string;
+  query(): QueryBuilder<TModel>;
+  findMany(): QueryBuilder<TModel>;
+  findById(id: number): Promise<TModel>;
+  search(term: string): QueryBuilder<TModel>;
+  request<TShape = TModel>(query: string): Promise<TShape[]>;
+  count(query?: string): Promise<number>;
+  meta(): Promise<MetaField[]>;
+  requestProtobuf(query: string): Promise<ArrayBuffer>;
 }
 ```
 
-### GenresEndpoint
+## Reference Helpers
 
 ```ts
-class GenresEndpoint {
-  query(): QueryBuilder<Genre>;
-  findMany(): QueryBuilder<Genre>;
-}
-```
-
-### PlatformsEndpoint
-
-```ts
-class PlatformsEndpoint {
-  query(): QueryBuilder<Platform>;
-  findMany(): QueryBuilder<Platform>;
-}
-```
-
-### CompaniesEndpoint
-
-```ts
-class CompaniesEndpoint {
-  query(): QueryBuilder<Company>;
-  findMany(): QueryBuilder<Company>;
-  search(term: string): QueryBuilder<Company>;
-}
+buildImageUrl("image_id", { size: "cover_big", retina: true });
+createTagNumber("genre", 5);
 ```
 
 ---
@@ -198,60 +208,9 @@ interface RateLimitPluginOptions {
 
 ## Models
 
-```ts
-interface Game {
-  id: number;
-  name: string;
-  slug: string;
-  summary: string;
-  storyline: string;
-  rating: number;
-  rating_count: number;
-  aggregated_rating: number;
-  aggregated_rating_count: number;
-  first_release_date: number;
-  cover: Cover;
-  genres: Genre[];
-  platforms: Platform[];
-  involved_companies: InvolvedCompany[];
-  similar_games: Game[];
-  url: string;
-  status: number;
-  category: number;
-}
-
-interface Cover {
-  id: number;
-  image_id: string;
-  width: number;
-  height: number;
-}
+All endpoint model types are exported from the package root, including `Game`,
+`Artwork`, `AgeRating`, `CompanyWebsite`, `PopularityPrimitive`, `Webhook`, and
+the shared base types `IGDBEntity`, `NamedEntity`, and `ImageEntity`.
 
-interface Genre {
-  id: number;
-  name: string;
-  slug: string;
-}
-
-interface Platform {
-  id: number;
-  name: string;
-  slug: string;
-  abbreviation: string;
-}
-
-interface Company {
-  id: number;
-  name: string;
-  description: string;
-  country: number;
-  slug: string;
-}
-
-interface InvolvedCompany {
-  id: number;
-  company: Company;
-  developer: boolean;
-  publisher: boolean;
-}
-```
+Model fields are optional except for core identifiers and a few established
+fields, because IGDB only returns fields requested by the APICalypse body.

docs/configuration.md

@@ -59,8 +59,9 @@ retry: { maxAttempts: 1 }
 ## Rate Limiting
 
 The built-in rate limiter uses api-core's rate limit plugin. Defaults are
-`maxConcurrent: 4` and `minTimeMs: 250`, which keeps requests comfortably within
-IGDB's free tier limit of 4 requests per second.
+`maxConcurrent: 8`, `maxRequestsPerInterval: 4`, `intervalMs: 1000`, and
+`minTimeMs: 250`, matching IGDB's documented 4 requests-per-second rate limit
+and 8 open-request concurrency limit.
 
 ```ts
 interface RateLimitPluginOptions {
@@ -89,7 +90,8 @@ const client = new IGDBClient({
 ```ts
 rateLimit: {
   maxConcurrent: 8,
-  minTimeMs: 100,
+  maxRequestsPerInterval: 4,
+  intervalMs: 1000,
 }
 ```