Documentation updates

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):

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
 

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';