racedirector/iracing-data-api

README

iracing-data-api

A monorepo of TypeScript packages for working with the iRacing Data API and its OAuth authentication flow, plus a generated Rust client. Packages cover Zod validation schemas, OpenAPI generation, generated HTTP clients (Fetch and Axios), and an OAuth client.

Which package should I use?

Call the iRacing Data API: start with @iracing-data/api-client-fetch.
Authenticate and refresh tokens: add @iracing-data/oauth-client.
Validate data or use types only: choose @iracing-data/api-schema.
Prefer Axios: use @iracing-data/api-client-axios.
Validate OAuth requests/responses: use @iracing-data/oauth-schema.
Use Rust: start with iracing-data-api-client and its runnable member lookup example.

Local MCP application

For bounded read-only agent queries, use the private local Data API MCP. Its Docker setup and credential recovery use host CLI auth-only login and a loopback Streamable HTTP connection. It is separate from public npm package releases.

The client connection guide covers checked-in configurations for common AI clients, Ollama-backed OpenCode, and ChatGPT private tunnels. Any capable agent can follow the repository onboarding skill.

First Data API call

With an existing bearer token, follow the Fetch-first quickstart: install @iracing-data/api-client-fetch, set IRACING_ACCESS_TOKEN, call DocApi.getDocs(). The runnable example prints the whole Data API documentation JSON and reports HTTP failures. Token acquisition and refresh are a separate step.

OpenAPI contracts

Contract	JSON	YAML	Package/runtime surface
Data API	iracing.json	iracing.yaml	iRacing `/data` endpoints; input to the generated Fetch, Axios, and Rust clients.
OAuth	oauth.json	oauth.yaml	iRacing Auth Service requests/responses shared with the OAuth schemas and authored OAuth client. The OAuth client is not generated from this contract.

Use these contracts to inspect operations and authentication, import into API tooling, or generate an external client. For tools requiring a URL, use the raw Data API JSON or OAuth JSON. Main tracks the current repository contract; pin a commit when reproducible external generation matters, rather than assuming independently versioned packages share a release.

The JSON/YAML files are generated artifacts. Maintained inputs are the Data API Zod schemas and endpoint mappings, and the OAuth Zod schemas and endpoint mappings. Change those inputs rather than editing OpenAPI output. Deterministic verification checks both formats and downstream Data API clients for freshness. These repository contracts describe maintained coverage; generation alone does not verify live upstream behavior.

Examples

See examples/README.md.

Development

Use the Node version in .nvmrc and pnpm pinned in package.json:

pnpm install --frozen-lockfile
pnpm verify

Read repository guidance and the nearest scoped guide before editing. Discover workspace scripts from their manifests; use pnpm --filter <package> for scoped work.

For implementation details, go directly to the Data API document builder, OAuth client, MCP composition, CLI authentication command, generation/freshness orchestrator, or client presentation normalizer.

License

MIT.