Add typed multi-query builder, single-flight auth, endpoint metadata

- Single-flight Twitch token refresh prevents stampede on cold start
- Typed MultiQueryBuilder compiles QueryBuilder blocks into multi-query syntax
- QueryBuilder gains inspect()/toJSON() for silent introspection
- IGDB_ENDPOINT_METADATA is the single source of truth for paths
- Package smoke script validates ESM, CJS, and declaration files
- Expanded tests cover auth concurrency, error mapping, validation, drift

Author: TDanks2000

.ai/README.md

@@ -0,0 +1,19 @@
+# .ai
+
+Machine-readable planning artifacts written by the **strategist** skill.
+Each entry is a self-contained plan, audit, or investigation an agent can execute.
+
+## How to consume
+1. Read this manifest to find the relevant artifact.
+2. Open its folder; read `plan.html` / `audit.html` / `investigation.html` for full context.
+3. Hand `executor-prompt.md` to the implementing agent.
+
+## Conventions
+- Folders: `<type>/<YYYY-MM-DD>-<slug>/`
+- Primary artifacts default to HTML; Markdown versions are optional.
+- Every artifact has metadata (`type`, `status`, `target`).
+- `status: superseded` means a newer artifact replaces it.
+
+## Artifacts
+<!-- newest first; one line per run -->
+- 2026-06-25 - [API wrapper improvements audit](audits/2026-06-25-api-wrapper-improvements/audit.html) - status: ready - target: TypeScript IGDB wrapper reliability, ergonomics, endpoint metadata, docs, and release validation.

.ai/audits/2026-06-25-api-wrapper-improvements/audit.html

@@ -0,0 +1,143 @@
+---
+type: executor-prompt
+title: Improve IGDB Wrapper Reliability and Ergonomics
+slug: api-wrapper-improvements
+created: 2026-06-25
+status: ready
+target: TypeScript IGDB wrapper reliability, ergonomics, endpoint metadata, docs, and release validation
+related:
+  - audit.html
+---
+
+# Task
+
+Implement the following plan exactly. Do not redesign the approach unless you find a real blocker.
+
+# Context
+
+This repository is `@api-wrappers/igdb-wrapper`, a TypeScript package for IGDB v4. It uses Bun tests, tsdown, strict TypeScript, and `@api-wrappers/api-core` for HTTP transport, retry, rate limiting, auth plugin wiring, timeout, custom fetch, plugins, and logging.
+
+The current baseline is healthy: `bun run typecheck`, `bun test`, and `bun run build` passed during the strategist audit. The package should be improved incrementally, with no broad rewrite and no removal of raw APICalypse escape hatches.
+
+Relevant files:
+- `src/auth/AuthManager.ts`
+- `src/http/HttpClient.ts`
+- `src/client/IGDBClient.ts`
+- `src/client/config.ts`
+- `src/endpoints/registry.ts`
+- `src/endpoints/Endpoint.ts`
+- `src/query/QueryBuilder.ts`
+- `src/query/compiler.ts`
+- `src/query/ast.ts`
+- `src/query/helpers.ts`
+- `src/query/operators.ts`
+- `src/query/fieldProxy.ts`
+- `src/types/models.ts`
+- `src/types/query.types.ts`
+- `src/types/response.types.ts`
+- `src/__tests__/igdb-client.test.ts`
+- `README.md`, `ROADMAP.md`, and `docs/`
+- `package.json`, `tsdown.config.mjs`, and `tsconfig.json`
+
+# Implementation Plan
+
+1. Add single-flight token refresh.
+   - In `AuthManager`, add a private in-flight refresh promise, for example `#refreshing: Promise<string> | null`.
+   - Keep the current cache check.
+   - When the cache is missing or stale, reuse the pending refresh promise if present.
+   - When starting a new refresh, store the promise and clear it in `finally`.
+   - Preserve current Twitch token request shape and current `IGDBAuthError` mapping.
+   - Add a test that fires multiple concurrent IGDB requests against an empty cache and asserts exactly one Twitch token request.
+
+2. Expand error and validation tests.
+   - Add focused tests for 401 IGDB responses mapping to `IGDBAuthError`.
+   - Add a failed Twitch token fetch test that maps to `IGDBAuthError`.
+   - Add tests for non-JSON or string-ish error body formatting if api-core exposes it through `ApiError.responseBody`.
+   - Add validation tests for invalid `limit()`, `offset()`, `paginate()`, empty `fields()`, and unsupported `count()` on a manually created `QueryBuilder`.
+   - Add a not-found test for `findById()` or endpoint `firstOrThrow()`.
+
+3. Create endpoint metadata as the single source of truth.
+   - Introduce structured metadata that binds public key, endpoint path, model type name, and searchability.
+   - Derive `IGDB_ENDPOINTS` and `IGDB_SEARCHABLE_ENDPOINTS` from that metadata.
+   - Preserve the existing exported type names: `IGDBEndpointKey`, `IGDBEndpointPath`, and `IGDBSearchableEndpointPath`.
+   - Preserve all existing endpoint paths and client property names.
+   - If code generation is used, commit generated output and add a check that fails when generation output is stale.
+
+4. Reduce manual endpoint-client drift.
+   - Keep existing named `IGDBClient` properties for backward compatibility.
+   - Either generate the property declarations/assignments from endpoint metadata or add a type-level/runtime drift test that verifies every metadata row has a client property and docs entry.
+   - Do not replace the named properties with only a generic map.
+
+5. Add a minimal typed multi-query builder.
+   - Keep `client.multiQuery(rawString)` unchanged.
+   - Add a small API that supports named list queries and named count queries.
+   - Reuse existing `QueryBuilder.raw()` output for query bodies instead of reimplementing APICalypse compilation.
+   - Ensure output matches IGDB multi-query syntax.
+   - Add tests for compiled body and response typing.
+   - Document the API in README/docs with one concise example.
+
+6. Improve query introspection behavior.
+   - Prefer non-printing introspection as the stable path. `raw()` already exists; add `inspect()` or `toJSON()` only if useful.
+   - If `debug()` and `explain()` remain, document that they write to console and are debug-only.
+   - Do not introduce unconditional extra console output elsewhere.
+
+7. Add package smoke validation.
+   - Add a script or test that runs after build, packs the package locally, verifies expected files, imports ESM, requires CJS, and typechecks a minimal consumer snippet.
+   - Wire it into `verify` if it is fast and deterministic.
+   - Avoid new dependencies unless the smoke test cannot be done cleanly with Bun/Node built-ins.
+
+8. Update docs and roadmap.
+   - Update README/docs for typed multi-query usage, debug guidance, and package verification.
+   - Keep browser credential guidance server-side; do not encourage exposing Twitch client secrets.
+   - Mark completed roadmap items rather than duplicating them.
+
+# Constraints
+
+- Follow existing project patterns.
+- Keep the change focused.
+- Do not perform unrelated refactors.
+- Preserve existing behavior unless explicitly changed by the plan.
+- Reuse existing types, schemas, utilities, services, and components before creating new ones.
+- Avoid adding dependencies unless explicitly allowed.
+- Do not remove raw APICalypse methods or raw `multiQuery(string)`.
+- Do not replace `@api-wrappers/api-core`.
+- Keep named endpoint properties source-compatible.
+
+# TypeScript Rules
+
+- Do not use `any`.
+- Avoid weakening public types.
+- Prefer clear exported types for new public APIs.
+- Keep generic types understandable; do not over-engineer typed multi-query.
+- Maintain strict TypeScript compatibility.
+
+# Validation
+
+Before finishing:
+
+- Run `bun run typecheck`.
+- Run `bun test`.
+- Run `bun run build`.
+- Run `npm pack --dry-run`.
+- Run the new package smoke validation if added.
+- Confirm README examples affected by public API changes still typecheck or are otherwise covered.
+
+# Acceptance Criteria
+
+- Concurrent cold-start requests share exactly one Twitch token refresh.
+- Existing public API remains source-compatible for current README examples.
+- Endpoint metadata has one clear source of truth and tests catch registry/client/searchability drift.
+- Typed multi-query supports at least named list queries and named count queries while raw multi-query remains available.
+- Error mapping and validation behavior are covered by focused tests.
+- Package smoke validation proves ESM, CJS, and declarations work from the built package.
+- `bun run typecheck`, `bun test`, `bun run build`, and package verification pass.
+
+# Final Response
+
+When done, respond with:
+
+1. Summary of changes
+2. Files changed
+3. Commands run
+4. Tests/checks completed
+5. Any blockers, assumptions, or follow-up recommendations

.ai/audits/2026-06-25-api-wrapper-improvements/executor-prompt.md

@@ -104,13 +104,14 @@ const games = await client.games
 ## Why use it?
 
 - **Typed query builder:** select fields, compose filters, sort, limit, offset,
-  inspect the generated APICalypse with `.raw()`, and keep the returned shape
-  typed.
+  inspect the generated APICalypse with `.raw()` / `.inspect()`, and keep the
+  returned shape typed.
 - **Endpoint helpers:** every registered IGDB v4 endpoint is exposed as a
   camel-cased `IGDBClient` property with `.query()`, `.findById()`,
   `.search()`, `.request()`, `.count()`, `.meta()`, and protobuf helpers.
-- **Auth:** Twitch client credentials are exchanged and cached for IGDB
-  requests.
+- **Auth:** Twitch client credentials are exchanged, cached, and refreshed with
+  single-flight concurrency so parallel cold-start requests share one token
+  fetch.
 - **Retries:** transient failures are retried through `@api-wrappers/api-core`.
 - **Rate limiting:** the default limiter matches IGDB's documented request and
   concurrency limits.
@@ -133,7 +134,8 @@ const games = await client.games
   `.query()`, `.findMany()`, `.findById()`, `.search()`, `.request()`,
   `.count()`, `.meta()`, and `.requestProtobuf()`.
 - Client-level helpers cover custom endpoint access, raw requests, counts,
-  metadata, protobuf responses, raw multi-query bodies, and webhooks.
+  metadata, protobuf responses, raw or builder-based multi-query bodies, and
+  webhooks.
 - Utility exports include IGDB image URL building and tag-number creation.
 
 See [Endpoints](./docs/endpoints.md) and [API Reference](./docs/api-reference.md)
@@ -236,8 +238,21 @@ const coverUrl = game.cover?.imageId
 
 ### Send a multi-query request
 
-`multiQuery()` currently accepts IGDB's raw multi-query body. A typed
-multi-query builder is tracked in the roadmap.
+Use `multiQueryBuilder()` when each block can be expressed with the normal
+query builder. It compiles through the same `.raw()` path as regular queries:
+
+```ts
+const query = client
+  .multiQueryBuilder()
+  .query(client.games, "Top Games", (games) =>
+    games.fields("name", "rating").sort((game) => game.rating, "desc").limit(5),
+  )
+  .count(client.platforms, "Platform Count");
+
+const response = await client.multiQuery(query);
+```
+
+Raw IGDB multi-query bodies remain supported for full APICalypse compatibility:
 
 ```ts
 const response = await client.multiQuery(`

README.md

@@ -9,11 +9,13 @@ raw IGDB access when needed.
 - Typed query builder for field selection, filters, sorting, limits, offsets,
   counts, and async pagination.
 - Endpoint helpers for registered IGDB v4 endpoints.
-- Twitch credential auth with token caching.
+- Metadata-driven endpoint helpers for registered IGDB v4 endpoints.
+- Twitch credential auth with token caching and single-flight refresh.
 - Retry, timeout, plugin, and rate-limit behavior through
   `@api-wrappers/api-core`.
 - Structured errors for auth, rate limit, not found, and validation cases.
-- Image URL, tag number, meta, protobuf, webhook, and raw multi-query helpers.
+- Image URL, tag number, meta, protobuf, webhook, raw multi-query, and typed
+  multi-query builder helpers.
 
 ## Near Term
 
@@ -22,28 +24,26 @@ raw IGDB access when needed.
 - Improve generated model docs so users can discover IGDB fields without
   opening source files.
 - Add tests that assert README and docs snippets compile where practical.
-- Add package-content smoke tests for the published tarball.
 - Expand endpoint docs with the searchable endpoints and common field sets.
 
 ## Query Builder Ergonomics
 
-- Explore a typed multi-query builder. `client.multiQuery()` currently accepts
-  IGDB's raw multi-query body, which is accurate but still string-based.
+- Expand the typed multi-query builder with more result-shape examples while
+  keeping raw `client.multiQuery()` bodies supported.
 - Improve relation-array result typing for `select()` examples that fetch nested
   arrays such as `platforms.name` or `genres.name`.
 - Consider clearer helpers for IGDB array/set expressions so fewer examples need
   `whereRaw()`.
 - Add date helper recipes for converting JavaScript `Date` values to IGDB Unix
   timestamps.
-- Add optional query snippet tooling that prints the generated APICalypse for
-  docs and debugging.
+- Add optional query snippet tooling that captures generated APICalypse for
+  docs from `.inspect()` payloads.
 
 ## Reliability and Trust
 
 - Keep CI running typecheck, tests, build, and package smoke checks.
 - Maintain a release-readiness checklist for every release.
-- Add more structured error tests around HTTP status handling and retry
-  exhaustion.
+- Add more structured error tests around retry exhaustion.
 - Document supported runtimes and compatibility expectations.
 
 ## Not Planned Right Now

ROADMAP.md

@@ -20,7 +20,8 @@ class IGDBClient {
   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>>>;
+  multiQuery<T = IGDBAnyEntity>(query: string | MultiQueryBuilder): Promise<Array<MultiQueryResult<T>>>;
+  multiQueryBuilder(): MultiQueryBuilder;
   createWebhook(endpoint: string, options: CreateWebhookOptions): Promise<Webhook>;
   listWebhooks(): Promise<Webhook[]>;
   getWebhook(id: number | string): Promise<Webhook>;
@@ -94,11 +95,57 @@ class QueryBuilder<TModel, TShape = TModel> {
 
   // Debug
   raw(): string;
+  inspect(): QueryDebugInfo;
+  toJSON(): QueryDebugInfo;
   debug(): this;
   explain(): this;
 }
 ```
 
+```ts
+interface QueryDebugInfo {
+  ast: QueryAST;
+  query: string;
+}
+```
+
+---
+
+## MultiQueryBuilder
+
+```ts
+class MultiQueryBuilder {
+  query<TModel extends IGDBEntity>(
+    endpoint: IGDBEndpoint<TModel>,
+    name: string,
+    build: (query: QueryBuilder<TModel>) => QueryBuilder<TModel, unknown>
+  ): MultiQueryBuilder;
+  query<TModel extends IGDBEntity = IGDBEntity>(
+    endpoint: string,
+    name: string,
+    build: (query: QueryBuilder<TModel>) => QueryBuilder<TModel, unknown>
+  ): MultiQueryBuilder;
+  count<TModel extends IGDBEntity>(
+    endpoint: IGDBEndpoint<TModel>,
+    name: string,
+    build?: (query: QueryBuilder<TModel>) => QueryBuilder<TModel, unknown>
+  ): MultiQueryBuilder;
+  count<TModel extends IGDBEntity = IGDBEntity>(
+    endpoint: string,
+    name: string,
+    build?: (query: QueryBuilder<TModel>) => QueryBuilder<TModel, unknown>
+  ): MultiQueryBuilder;
+  raw(): string;
+  inspect(): MultiQueryDebugInfo;
+  toJSON(): MultiQueryDebugInfo;
+}
+
+interface MultiQueryDebugInfo {
+  blocks: MultiQueryBlock[];
+  query: string;
+}
+```
+
 ---
 
 ## WhereHelpers

docs/api-reference.md

@@ -19,6 +19,10 @@ method uniformly so new searchable endpoints do not require a wrapper release;
 the current documented searchable endpoints are exported as
 `IGDB_SEARCHABLE_ENDPOINTS`.
 
+Endpoint properties and path exports are derived from
+`IGDB_ENDPOINT_METADATA`, which is exported for tooling that needs the wrapper's
+registered endpoint list without constructing a client.
+
 Use endpoint properties for known IGDB resources:
 
 ```ts