diff --git a/DISTRIBUTION_NOTES.md b/DISTRIBUTION_NOTES.md deleted file mode 100644 index 30f864e..0000000 --- a/DISTRIBUTION_NOTES.md +++ /dev/null @@ -1,41 +0,0 @@ -# Node Module Distribution Considerations - -## 1. Quality Assurance (Completed) - -- **Linting & Formatting**: Integrated `eslint` and `prettier`. Run `npm run lint` and `npm run format`. -- **CI/CD**: GitHub Actions set up in `.github/workflows/ci.yml`. - -## 2. Publishing (Completed) - -- **NPM**: Account created and verified on npmjs.com. -- **Semantic Versioning**: Following SemVer (major.minor.patch). -- **Publishing Pipeline**: GitHub Action `publish.yml` is configured to automate publishing to npm. - -## 3. Bundling (Completed) - -- **Tooling**: Integrated `tsup` to handle bundling. -- **Outputs**: - - **ESM**: `dist/index.js` (for modern bundlers). - - **CJS**: `dist/index.cjs` (for legacy Node.js). - - **IIFE**: `dist/index.global.js` (for direct browser usage). -- **CDN Usage**: The IIFE bundle exposes the library as the global `irdata` variable. It works with unpkg/jsDelivr. -- **Type Definitions**: Bundled into `dist/index.d.ts`. - -## 4. Documentation (Completed) - -- **TypeDoc**: configured to generate API documentation. Run `npm run docs`. -- **CONTRIBUTING.md**: Created guide for contributors. -- **Examples**: Demo application serves as the primary example. - -## 5. Security (Completed) - -- **Dependabot**: Created `.github/dependabot.yml` to automate dependency updates and security patches. -- **Vulnerability Scanning**: Integrated `npm audit` into the CI pipeline to block PRs with insecure dependencies. -- **Native APIs**: Preferred native `fetch` and `crypto` to minimize external dependencies and reduce the attack surface. Currently zero runtime dependencies. - -## 6. Compatibility - -- **Target**: `ES2022`. -- **Node.js**: Requires **v18.0.0+** due to native `fetch` and global `crypto` requirements. -- **Browsers**: Compatible with modern browsers (Chrome 100+, Firefox 100+, Safari 15.4+). -- **Lowering Target**: If support for older environments (like Node 16) is needed, polyfills or target adjustments (e.g., `undici`) would be required. diff --git a/GEMINI.md b/GEMINI.md index 1273ab9..d2b4d4a 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -32,6 +32,7 @@ This project is a JavaScript/TypeScript library for interacting with the iRacing - **Testing**: `npm test` (uses `vitest`). New features should include unit tests. - **Dependencies**: Minimal dependencies. Uses native `fetch` and `crypto` (standard in modern Node and Browsers). - **Proxy Server (`proxy_server.js`)**: + - Required for browser-based usage as iRacing intentionally does not provide CORS headers for third-party sites. - Runs on port 80 (or as configured) via `npm run dev`. - Serves the demo application and proxies API requests to avoid CORS issues. - **Endpoints** (prefixed with `basePath` from config): diff --git a/README.md b/README.md index 2f88395..46868a0 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,11 @@ JavaScript library to interact with the iRacing /data API. npm install irdata_js ``` +## Compatibility + +- **Node.js**: v20.0.0 or newer. +- **Browsers**: Modern browsers supporting ES2022 (Chrome 100+, Firefox 100+, Safari 15.4+). + ## CDN Usage For direct usage in the browser without a build step, you can load the library via a CDN. The library is exposed as the global `irdata` variable. @@ -118,15 +123,15 @@ if (result.metadata.chunkCount > 0) { > **Note:** iRacing's API incorrectly returns `application/octet-stream` as the `Content-Type` for JSON chunks. This library automatically detects and parses these as JSON. -## Proxy Workaround for CORS +## The Proxy Requirement (CORS) -The iRacing API (`members-ng.iracing.com`) and its associated S3 data links do not currently include CORS (`Cross-Origin Resource Sharing`) headers. This means that direct requests from a web browser to the API will be blocked by the browser's security policies. +The iRacing API (`members-ng.iracing.com`) and its associated S3 data links do not provide CORS (`Cross-Origin Resource Sharing`) headers for third-party domains. This means that direct requests from a web browser to the API will be blocked by the browser's security policies. -To use this library in a web application, you must route your requests through a proxy server that adds the necessary CORS headers or resides on the same domain as your application. +This behavior is intentional by iRacing to better protect their business and operations and is unlikely to change (see [this message by their head of operations](https://forums.iracing.com/discussion/comment/772334/#Comment_772334)). -We have reached out to the iRacing developers regarding this limitation. See [this issue](https://github.com/popmonkey/irdata_js/issues/16) for more information. +To use this library in a web application, you must route your requests through a proxy server that adds the necessary CORS headers or resides on the same domain as your application. -For development, this repository includes a `proxy_server.js` that demonstrates how to implement such a workaround. See the [Development](#development) section for more details. +For development and as a reference implementation, this repository includes a `proxy_server.js` that demonstrates how to implement such a workaround. See the [Development](#development) section for more details on how to use it. ## Development diff --git a/proxy_server.js b/proxy_server.js index 13e2cea..c6a52b6 100644 --- a/proxy_server.js +++ b/proxy_server.js @@ -1,3 +1,15 @@ +/** + * iRacing Proxy Server + * + * A proxy is a required architectural component for browser-based usage of the iRacing API. + * iRacing does not provide CORS headers for third-party domains. + * + * This proxy demonstrates how to: + * 1. Proxy OAuth token requests + * 2. Proxy Data API requests + * 3. Proxy S3 file downloads (passthrough) + * 4. Handle OAuth callbacks + */ import express from 'express'; import cors from 'cors'; import path from 'path';