🏁 iRacing API SDK

TypeScript SDK for iRacing OAuth2 Authentication & Data API

⭐ If you find this project useful, please give it a star! ⭐

📖 Documentation • 🚀 Examples • 🔒 Security • 🤝 Contributing

🎯 What is this?

iracing-api-sdk is a zero-dependency TypeScript SDK that provides type-safe primitives for:

• OAuth2 Authentication: Password Limited, Authorization Code + PKCE, automatic token refresh
• Data API Client: Type-safe access to iRacing's Data API with automatic rate limiting
• Session Management: List, audit, and revoke OAuth2 sessions
• Security First: Automatic credential masking, secure token storage, authorization header protection

Built for Node.js ≥ 20 with strict TypeScript and ESM-only.

✨ Features

• ✅ Zero runtime dependencies - Minimal footprint, maximum control
• ✅ Type-safe - Full TypeScript support with strict mode
• ✅ Security built-in - Never logs secrets, automatic credential masking
• ✅ Rate limit aware - Built-in rate limiting with automatic retry/backoff
• ✅ OAuth2 complete - Password Limited, Authorization Code + PKCE, token refresh
• ✅ Flexible storage - File-based storage with interfaces for custom implementations
• ✅ Production ready - Comprehensive tests, error handling, and logging

📦 Installation

npm i iracing-api-sdk-node

pnpm add iracing-api-sdk-node

yarn add iracing-api-sdk-node

🚀 Quick Start

1. Configure Environment

# .env
IRACING_OAUTH_CLIENT_ID=your-client-id
IRACING_OAUTH_CLIENT_SECRET=your-client-secret
IRACING_OAUTH_CLIENT_USER=your-username
IRACING_OAUTH_CLIENT_PASS=your-password

2. Authenticate & Access Data

import { Config } from "iracing-api-sdk-node/config";
import { OAuthClient } from "iracing-api-sdk-node/oauth";
import { DataApiClient } from "iracing-api-sdk-node/data";
import { HttpClient } from "iracing-api-sdk-node/http";

// Configure SDK
const config = Config.fromEnv();
const http = new HttpClient();
const oauth = new OAuthClient(config, http);

// Authenticate
const tokenSet = await oauth.authenticatePasswordLimited(
    process.env.IRACING_OAUTH_CLIENT_ID!,
    process.env.IRACING_OAUTH_CLIENT_SECRET!,
    process.env.IRACING_OAUTH_CLIENT_USER!,
    process.env.IRACING_OAUTH_CLIENT_PASS!,
    "iracing.data.read",
);

// Access Data API
const data = new DataApiClient(config, http, tokenSet);
const result = await data.car().get();

if (result.isOk()) {
    console.log("Cars:", result.getData());
}

📚 Documentation

Core Guides

| Guide | Description | | ------------------------------------------- | ---------------------------------------------- | | 📖 Documentation Index | Complete documentation overview | | ⚙️ Configuration | Environment variables and config setup | | 🔐 OAuth Flows | Authentication methods and token management | | 📡 Data API | Accessing iRacing Data API with typed services | | 🔒 Security | Security features and best practices |

Advanced Topics

| Guide | Description | | ------------------------------------------- | ---------------------------------------- | | 📋 Sessions | OAuth2 session management and revocation | | 🎯 Data Services | Generated typed service wrappers | | 🔧 Integration | Production application patterns | | 🧪 Testing | Unit and integration testing guide |

Examples

See examples/ for runnable code samples:

• OAuth2 authentication flows
• Token refresh patterns
• Data API calls
• Session management
• Custom storage implementations

🎯 Use Cases

Racing Teams & Analytics

Track performance, analyze telemetry data, and monitor race results using iRacing's official data.

const data = new DataApiClient(config, http, tokenSet);

// Get driver stats
const stats = await data.stats().memberCareer({ custId: 123456 });

// Get race results
const results = await data.results().searchSeries({ seasonYear: 2026 });

League Management

Automate league operations, track member activity, and manage rosters.

// Get league data
const league = await data.league().get({ leagueId: 789 });

// Track member sessions
const sessions = await data.stats().memberRecentRaces({ custId: 123456 });

Development Tools & Bots

Build Discord bots, dashboards, or custom tools integrating with iRacing.

// Custom rate limiting
const rateLimitStore = new FileRateLimitStore(cacheDir);
const rateLimitedHttp = new RateLimitedHttpClient(http, rateLimitGuard, rateLimitStore);

// Automatic token refresh
const storage = new FileTokenStorage(cacheDir, logger);
await storage.save("my-app", tokenSet);

🛡️ Security

This SDK follows strict security practices:

• Never logs secrets - Client secrets, passwords, and tokens are never logged
• Automatic credential masking - Passwords masked with SHA-256 before transmission
• Authorization header protection - Auth headers only forwarded to trusted origins
• Secure file storage - Tokens stored with 0600 permissions (user read/write only)

See Security Documentation for details.

🧪 Development

Prerequisites

• Node.js ≥ 20
• pnpm ≥ 8

Commands

# Install dependencies
pnpm install

# Run tests (unit tests, no credentials needed)
pnpm test

# Run integration tests (requires valid .env)
pnpm test:integration

# Type checking
pnpm typecheck

# Linting
pnpm lint

# Build
pnpm build

# Format code
pnpm format

Project Structure

src/
├── config/          # Configuration management
├── crypto/          # Credential masking (SHA-256)
├── data/            # Data API client + generated services
├── errors/          # Exception handling
├── fs/              # Atomic file operations
├── http/            # HTTP client abstraction
├── log/             # Logger interfaces
├── oauth/           # OAuth2 flows (password_limited, auth code + PKCE)
├── rate-limit/      # Rate limiting with guards and stores
├── response/        # Response wrappers
├── sessions/        # OAuth2 session management
├── token/           # Token storage and expiration handling
└── types/           # TypeScript type definitions

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development workflow
• Code standards
• Testing requirements
• Commit message format
• Pull request process

📄 License

MIT © Manu Overa

See LICENSE for details.

🔗 Related Projects

• iRacing Official API Documentation
• iRacing OAuth2 Service
• iRacing Members Site

Author Manu Overa

Report Bug • Request Feature • Discussions