yahoo-fantasy-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PeregrineCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# yahoo-fantasy-api
+
+Yahoo Fantasy Sports API client for Node.js with OAuth 2.0 authentication, automatic token refresh, rate limiting, and CLI tools.
+
+Works with any Yahoo Fantasy sport (MLB, NHL, NFL, NBA).
+
+## Installation
+
+```bash
+npm install yahoo-fantasy-api
+```
+
+## Setup
+
+### 1. Create a Yahoo App
+
+1. Go to [Yahoo Developer](https://developer.yahoo.com/apps/)
+2. Create a new app with **Fantasy Sports** read permissions
+3. Set the redirect URI to `https://localhost:3000/auth/callback`
+4. Note your Client ID and Client Secret
+
+### 2. Configure Environment
+
+Create a `.env` file:
+
+```env
+YAHOO_CLIENT_ID=your_client_id
+YAHOO_CLIENT_SECRET=your_client_secret
+YAHOO_REDIRECT_URI=https://localhost:3000/auth/callback
+```
+
+### 3. Generate SSL Certificates
+
+Yahoo requires HTTPS for OAuth callbacks. Generate self-signed certs:
+
+```bash
+mkdir certs
+openssl req -x509 -newkey rsa:2048 -keyout certs/key.pem -out certs/cert.pem -days 365 -nodes -subj '/CN=localhost'
+```
+
+### 4. Authenticate
+
+```bash
+npx yahoo-fantasy-api authenticate
+```
+
+This opens an HTTPS server on localhost:3000, prints an authorization URL, and waits for the OAuth callback. The token is saved to `.yahoo-token.json` and auto-refreshes.
+
+## CLI Usage
+
+```bash
+npx yahoo-fantasy-api authenticate      # Interactive OAuth flow
+npx yahoo-fantasy-api token-status      # Check token expiry
+npx yahoo-fantasy-api list-leagues      # Discover all your leagues
+npx yahoo-fantasy-api league-settings   # Pull settings for all leagues
+npx yahoo-fantasy-api league-settings 469.l.75479  # Specific league
+```
+
+## Programmatic Usage
+
+```javascript
+require('dotenv').config();
+const { createClient } = require('yahoo-fantasy-api');
+
+const { auth, client } = createClient({
+  tokenFile: '.yahoo-token.json',
+  certsDir: 'certs',
+});
+
+// Discover leagues
+const leagues = await client.getUserLeagues(['mlb', 'nhl']);
+
+// Get league settings
+const settings = await client.getLeagueSettings('469.l.75479');
+
+// Get teams in a league
+const teams = await client.getLeagueTeams('469.l.75479');
+
+// Get draft results
+const picks = await client.getDraftResults('469.l.75479');
+
+// Raw API call to any endpoint
+const data = await client.get('/league/469.l.75479/scoreboard');
+```
+
+### createClient(options)
+
+Returns `{ auth, client }` — a `YahooAuth` instance and a `YahooClient` instance.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `clientId` | `YAHOO_CLIENT_ID` env | OAuth client ID |
+| `clientSecret` | `YAHOO_CLIENT_SECRET` env | OAuth client secret |
+| `redirectUri` | `https://localhost:3000/auth/callback` | OAuth redirect URI |
+| `tokenFile` | `.yahoo-token.json` | Path to token storage |
+| `certsDir` | `certs/` | Path to SSL certificates |
+| `minInterval` | `2000` | Minimum ms between API calls |
+| `log` | `console.log` | Custom logging function |
+
+## Client Methods
+
+### `client.get(endpoint)`
+Rate-limited GET request. Handles token refresh on 401 and retries on Yahoo's 999 rate limit. All other methods are built on this.
+
+### `client.getUserLeagues(gameCodes)`
+Discover all leagues for the authenticated user. `gameCodes` defaults to `['mlb', 'nhl']`.
+
+### `client.resolveGameKey(gameCode)`
+Map a game code (`'mlb'`, `'nhl'`) to Yahoo's numeric game key. Cached after first call.
+
+### `client.leagueKey(gameKey, leagueId)`
+Helper to build a league key string (e.g., `'469.l.75479'`).
+
+### `client.getLeagueSettings(leagueKey)`
+Fetch roster positions, stat categories, and league configuration.
+
+### `client.getLeagueTeams(leagueKey)`
+Fetch all teams with names and manager info.
+
+### `client.getDraftResults(leagueKey)`
+Fetch draft picks with costs (for auction leagues).
+
+## Yahoo API Notes
+
+- Base URL: `https://fantasysports.yahooapis.com/fantasy/v2`
+- All endpoints work identically across sports — only the game key differs
+- Rate limit: client enforces 2s minimum between calls (configurable)
+- Yahoo 999 errors: automatic 5s backoff + retry
+- Token auto-refreshes 5 minutes before expiry
+- **Settings quirk:** `/league/{key}/settings` returns stale predraft data. Use `/league/{key};out=settings` instead (this client handles it correctly).
+- **Weekly stats quirk:** `;out=stats;type=week;week=N` returns wrong data. Use the subresource syntax `/players/stats;type=week;week=N` (slash before `stats`).
+- **Positions are always current:** `selected_position` always reflects the current roster, never historical.
+
+## License
+
+MIT

package/auth.js

@@ -0,0 +1,307 @@
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const crypto = require('crypto');
+
+class YahooAuth {
+  constructor(options = {}) {
+    this.clientId = options.clientId || process.env.YAHOO_CLIENT_ID;
+    this.clientSecret = options.clientSecret || process.env.YAHOO_CLIENT_SECRET;
+    this.redirectUri = options.redirectUri || process.env.YAHOO_REDIRECT_URI || 'https://localhost:3000/auth/callback';
+    this.tokenFile = options.tokenFile || path.join(process.cwd(), '.yahoo-token.json');
+    this.certsDir = options.certsDir || path.join(process.cwd(), 'certs');
+    this.token = null;
+    this._refreshTimer = null;
+    this._refreshPromise = null; // mutex for concurrent refresh calls
+    this._log = options.log || ((type, msg) => console.log(`[YahooAuth] ${msg}`));
+
+    // Load token from disk on construction
+    this.loadToken();
+  }
+
+  loadToken() {
+    if (fs.existsSync(this.tokenFile)) {
+      try {
+        this.token = JSON.parse(fs.readFileSync(this.tokenFile, 'utf-8'));
+        if (!this.token.access_token) {
+          this._log('error', `Token file ${this.tokenFile} exists but is missing access_token — re-authenticate`);
+          this.token = null;
+        } else {
+          this._log('info', `Loaded token (expires ${new Date(this.token.expires_at).toISOString()})`);
+        }
+      } catch (e) {
+        this._log('error', `Token file ${this.tokenFile} exists but could not be read: ${e.message}`);
+      }
+    }
+    return this.token;
+  }
+
+  saveToken(token) {
+    if (!token.access_token || !token.expires_at) {
+      throw new Error('Invalid token: missing access_token or expires_at');
+    }
+    this.token = token;
+    fs.writeFileSync(this.tokenFile, JSON.stringify(token, null, 2), { mode: 0o600 });
+    this._log('info', `Token saved (expires ${new Date(token.expires_at).toISOString()})`);
+  }
+
+  isAuthenticated() {
+    return !!this.token;
+  }
+
+  /**
+   * Returns a valid access token, refreshing proactively if within 5 minutes of expiry.
+   */
+  async getAccessToken() {
+    if (!this.token) throw new Error('Not authenticated with Yahoo');
+    const REFRESH_BUFFER = 5 * 60 * 1000;
+    if (Date.now() >= this.token.expires_at - REFRESH_BUFFER) {
+      this._log('info', 'Proactive token refresh (expires soon)');
+      await this.refreshToken();
+    }
+    return this.token.access_token;
+  }
+
+  /**
+   * Build the Yahoo OAuth authorization URL.
+   */
+  getAuthUrl(state) {
+    const params = new URLSearchParams({
+      client_id: this.clientId,
+      redirect_uri: this.redirectUri,
+      response_type: 'code',
+      state: state || crypto.randomBytes(16).toString('hex'),
+    });
+    return `https://api.login.yahoo.com/oauth2/request_auth?${params}`;
+  }
+
+  /**
+   * Exchange an authorization code for tokens.
+   */
+  async handleCallback(code) {
+    const params = new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: this.redirectUri,
+    });
+
+    const basicAuth = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString('base64');
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30000);
+    let res;
+    try {
+      res = await fetch('https://api.login.yahoo.com/oauth2/get_token', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          Authorization: `Basic ${basicAuth}`,
+        },
+        body: params.toString(),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Token exchange failed (${res.status})`);
+    }
+
+    const data = await res.json();
+    this.saveToken({
+      access_token: data.access_token,
+      refresh_token: data.refresh_token,
+      expires_at: Date.now() + data.expires_in * 1000,
+    });
+    return this.token;
+  }
+
+  /**
+   * Refresh the access token using the refresh token.
+   */
+  async refreshToken() {
+    // Mutex: if a refresh is already in progress, piggyback on it
+    // instead of firing a second token exchange (which could invalidate
+    // the refresh token).
+    if (this._refreshPromise) {
+      return this._refreshPromise;
+    }
+
+    this._refreshPromise = this._doRefresh();
+    try {
+      return await this._refreshPromise;
+    } finally {
+      this._refreshPromise = null;
+    }
+  }
+
+  async _doRefresh() {
+    if (!this.token || !this.token.refresh_token) {
+      throw new Error('No refresh token available');
+    }
+    this._log('info', 'Refreshing token...');
+
+    const params = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: this.token.refresh_token,
+    });
+
+    const basicAuth = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString('base64');
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30000);
+    let res;
+    try {
+      res = await fetch('https://api.login.yahoo.com/oauth2/get_token', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          Authorization: `Basic ${basicAuth}`,
+        },
+        body: params.toString(),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    if (!res.ok) {
+      const text = await res.text();
+      this._log('error', `Token refresh failed: ${text.substring(0, 300)}`);
+      throw new Error(`Token refresh failed (${res.status})`);
+    }
+
+    const data = await res.json();
+    if (!data.access_token || !data.expires_in) {
+      throw new Error('Token refresh returned invalid response');
+    }
+    this.saveToken({
+      access_token: data.access_token,
+      refresh_token: data.refresh_token || this.token.refresh_token,
+      expires_at: Date.now() + data.expires_in * 1000,
+    });
+    this._log('info', 'Token refreshed successfully');
+    return this.token;
+  }
+
+  /**
+   * Start a background timer that checks token expiry every intervalMs.
+   */
+  startBackgroundRefresh(intervalMs = 2 * 60 * 1000) {
+    this.stopBackgroundRefresh();
+    this._refreshTimer = setInterval(async () => {
+      if (!this.token) return;
+      const REFRESH_BUFFER = 5 * 60 * 1000;
+      if (Date.now() >= this.token.expires_at - REFRESH_BUFFER) {
+        this._log('info', 'Background token refresh (timer)');
+        try {
+          await this.refreshToken();
+        } catch (e) {
+          this._log('error', `Background refresh failed — will retry: ${e.message}`);
+        }
+      }
+    }, intervalMs);
+    // Don't prevent process exit if nothing else is keeping the event loop alive
+    if (this._refreshTimer.unref) this._refreshTimer.unref();
+  }
+
+  stopBackgroundRefresh() {
+    if (this._refreshTimer) {
+      clearInterval(this._refreshTimer);
+      this._refreshTimer = null;
+    }
+  }
+
+  /**
+   * Interactive OAuth: spin up temp HTTPS server, print auth URL, wait for callback.
+   */
+  async authenticateInteractive(port = 3000) {
+    return new Promise((resolve, reject) => {
+      const certPath = path.join(this.certsDir, 'cert.pem');
+      const keyPath = path.join(this.certsDir, 'key.pem');
+
+      if (!fs.existsSync(certPath) || !fs.existsSync(keyPath)) {
+        reject(new Error(`Certs not found in ${this.certsDir}. Run: openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes`));
+        return;
+      }
+
+      const sslOptions = {
+        key: fs.readFileSync(keyPath),
+        cert: fs.readFileSync(certPath),
+      };
+
+      const expectedState = crypto.randomBytes(16).toString('hex');
+
+      const handler = async (req, res) => {
+        const url = new URL(req.url, `https://localhost:${port}`);
+
+        if (url.pathname === '/auth/callback') {
+          const code = url.searchParams.get('code');
+          const error = url.searchParams.get('error');
+          const returnedState = url.searchParams.get('state');
+
+          if (returnedState !== expectedState) {
+            res.writeHead(400, { 'Content-Type': 'text/plain' });
+            res.end('Invalid state parameter');
+            return; // don't close server — could be a stale/malicious callback
+          }
+
+          if (error) {
+            res.writeHead(400, { 'Content-Type': 'text/plain' });
+            res.end(`OAuth error: ${error}`);
+            server.close();
+            reject(new Error(`OAuth error: ${error}`));
+            return;
+          }
+
+          if (!code) {
+            res.writeHead(400, { 'Content-Type': 'text/plain' });
+            res.end('No authorization code received');
+            server.close();
+            reject(new Error('No authorization code received'));
+            return;
+          }
+
+          try {
+            await this.handleCallback(code);
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end('<h2>Authenticated! You can close this tab.</h2>');
+            server.close();
+            resolve(this.token);
+          } catch (e) {
+            res.writeHead(500, { 'Content-Type': 'text/plain' });
+            res.end(`Auth error: ${e.message}`);
+            server.close();
+            reject(e);
+          }
+        } else {
+          res.writeHead(404);
+          res.end('Not found');
+        }
+      };
+
+      const server = https.createServer(sslOptions, handler);
+
+      // Timeout after 5 minutes if user never completes the flow
+      const authTimeout = setTimeout(() => {
+        server.close();
+        reject(new Error('Authentication timed out after 5 minutes'));
+      }, 5 * 60 * 1000);
+
+      server.listen(port, () => {
+        const authUrl = this.getAuthUrl(expectedState);
+        console.log(`\nOpen this URL to authenticate:\n\n  ${authUrl}\n`);
+        console.log(`Waiting for callback on https://localhost:${port}/auth/callback ...\n`);
+      });
+
+      server.on('close', () => clearTimeout(authTimeout));
+
+      server.on('error', (e) => {
+        clearTimeout(authTimeout);
+        reject(new Error(`Server error: ${e.message}`));
+      });
+    });
+  }
+}
+
+module.exports = { YahooAuth };

package/cli.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+const path = require('path');
+
+// Load .env from current working directory (if dotenv is available)
+try { require('dotenv').config(); } catch (e) { /* dotenv is optional */ }
+
+const { createClient } = require('./index');
+
+const tokenFile = path.join(process.cwd(), '.yahoo-token.json');
+const certsDir = path.join(process.cwd(), 'certs');
+
+const { auth, client } = createClient({ tokenFile, certsDir });
+
+const command = process.argv[2];
+
+async function main() {
+  switch (command) {
+    case 'authenticate':
+      return authenticate();
+    case 'token-status':
+      return tokenStatus();
+    case 'list-leagues':
+      return listLeagues();
+    case 'league-settings':
+      return leagueSettings();
+    default:
+      usage();
+  }
+}
+
+function usage() {
+  console.log(`
+Usage: yahoo-fantasy-api <command>
+
+Commands:
+  authenticate      Interactive OAuth flow (opens browser)
+  token-status      Show current token info
+  list-leagues      Discover all your fantasy leagues
+  league-settings   Pull settings for all leagues (or specify league key)
+
+Examples:
+  npx yahoo-fantasy-api authenticate
+  npx yahoo-fantasy-api list-leagues
+  npx yahoo-fantasy-api league-settings 469.l.75479
+`);
+}
+
+async function authenticate() {
+  console.log('Starting interactive Yahoo OAuth...');
+  try {
+    const token = await auth.authenticateInteractive(3000);
+    console.log('\nAuthentication successful!');
+    console.log(`Token expires: ${new Date(token.expires_at).toISOString()}`);
+  } catch (e) {
+    console.error(`Authentication failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function tokenStatus() {
+  if (!auth.isAuthenticated()) {
+    console.log('Not authenticated. Run: npx yahoo-fantasy-api authenticate');
+    return;
+  }
+  const t = auth.token;
+  const expiresAt = new Date(t.expires_at);
+  const expiresIn = Math.round((t.expires_at - Date.now()) / 1000);
+  const expired = expiresIn <= 0;
+
+  console.log(`Token file:  ${tokenFile}`);
+  console.log(`Expires at:  ${expiresAt.toISOString()}`);
+  console.log(`Expires in:  ${expired ? 'EXPIRED' : `${expiresIn}s (${Math.round(expiresIn / 60)}min)`}`);
+  console.log(`Has refresh: ${t.refresh_token ? 'yes' : 'no'}`);
+}
+
+async function listLeagues() {
+  if (!auth.isAuthenticated()) {
+    console.error('Not authenticated. Run: npx yahoo-fantasy-api authenticate');
+    process.exit(1);
+  }
+
+  console.log('Discovering leagues...\n');
+  const leagues = await client.getUserLeagues(['mlb', 'nhl', 'nfl', 'nba']);
+
+  if (leagues.length === 0) {
+    console.log('No leagues found.');
+    return;
+  }
+
+  // Group by sport
+  const bySport = {};
+  for (const lg of leagues) {
+    if (!bySport[lg.sportName]) bySport[lg.sportName] = [];
+    bySport[lg.sportName].push(lg);
+  }
+
+  for (const [sport, sLeagues] of Object.entries(bySport)) {
+    console.log(`=== ${sport} ===`);
+    for (const lg of sLeagues) {
+      console.log(`  ${lg.name}`);
+      console.log(`    League Key: ${lg.leagueKey}`);
+      console.log(`    League ID:  ${lg.leagueId}`);
+      console.log(`    Season:     ${lg.season}`);
+      console.log(`    Teams:      ${lg.numTeams}`);
+      console.log(`    Scoring:    ${lg.scoringType}`);
+      console.log(`    Draft:      ${lg.draftStatus}`);
+      console.log();
+    }
+  }
+}
+
+async function leagueSettings() {
+  if (!auth.isAuthenticated()) {
+    console.error('Not authenticated. Run: npx yahoo-fantasy-api authenticate');
+    process.exit(1);
+  }
+
+  const specificKey = process.argv[3];
+
+  if (specificKey) {
+    // Fetch settings for a specific league
+    console.log(`Fetching settings for ${specificKey}...\n`);
+    const settings = await client.getLeagueSettings(specificKey);
+    console.log(JSON.stringify(settings, null, 2));
+    return;
+  }
+
+  // Fetch settings for all leagues
+  console.log('Discovering leagues...\n');
+  const leagues = await client.getUserLeagues(['mlb', 'nhl', 'nfl', 'nba']);
+
+  for (const lg of leagues) {
+    console.log(`\n${'='.repeat(60)}`);
+    console.log(`${lg.sportName} — ${lg.name} (${lg.leagueKey})`);
+    console.log('='.repeat(60));
+    try {
+      const settings = await client.getLeagueSettings(lg.leagueKey);
+      console.log(JSON.stringify(settings, null, 2));
+    } catch (e) {
+      console.error(`  Error: ${e.message}`);
+    }
+  }
+}
+
+main().catch(e => {
+  console.error(e.message);
+  process.exit(1);
+});

package/client.js

@@ -0,0 +1,255 @@
+const BASE_URL = 'https://fantasysports.yahooapis.com/fantasy/v2';
+
+class YahooClient {
+  constructor(auth, options = {}) {
+    this.auth = auth;
+    this.minInterval = options.minInterval || 2000;
+    this.userAgent = options.userAgent || 'yahoo-fantasy-api/1.0';
+    this._lastApiCall = 0;
+    this._queue = Promise.resolve(); // serialize calls for rate limiting
+    this._gameKeyCache = new Map(); // gameCode -> gameKey
+    this._log = options.log || auth._log || ((type, msg) => console.log(`[YahooClient] ${msg}`));
+  }
+
+  /**
+   * Rate-limited GET request to Yahoo Fantasy API.
+   * Handles 401 (token expired) and 999 (rate limited) with retry.
+   */
+  async get(endpoint) {
+    // Serialize all API calls through a queue to enforce rate limiting
+    // even under concurrent usage.
+    return this._queue = this._queue.then(
+      () => this._doGet(endpoint),
+      () => this._doGet(endpoint) // continue queue even if previous call failed
+    );
+  }
+
+  async _doGet(endpoint) {
+    await this.auth.getAccessToken();
+
+    // Rate limit our own calls
+    const now = Date.now();
+    const timeSinceLast = now - this._lastApiCall;
+    if (timeSinceLast < this.minInterval) {
+      await new Promise(r => setTimeout(r, this.minInterval - timeSinceLast));
+    }
+    this._lastApiCall = Date.now();
+
+    const url = `${BASE_URL}${endpoint}${endpoint.includes('?') ? '&' : '?'}format=json`;
+    this._log('api', `GET ${endpoint}`);
+
+    const makeRequest = async () => {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 30000);
+      try {
+        return await fetch(url, {
+          headers: {
+            Authorization: `Bearer ${this.auth.token.access_token}`,
+            'User-Agent': this.userAgent,
+          },
+          signal: controller.signal,
+        });
+      } finally {
+        clearTimeout(timeout);
+      }
+    };
+
+    let res = await makeRequest();
+
+    // Handle 401 - token expired
+    if (res.status === 401) {
+      this._log('warn', `401 on ${endpoint} — refreshing token`);
+      await this.auth.refreshToken();
+      res = await makeRequest();
+      if (res.status === 401) {
+        throw new Error('Yahoo API returned 401 after token refresh — re-authenticate');
+      }
+    }
+
+    // Handle 999 - Yahoo rate limiting
+    if (res.status === 999) {
+      this._log('warn', `999 rate limited on ${endpoint} — waiting 5s`);
+      await new Promise(r => setTimeout(r, 5000));
+      res = await makeRequest();
+      if (res.status === 999) {
+        this._log('error', `999 persists on ${endpoint} after retry`);
+        throw new Error('Yahoo rate limited (999). Try again in a moment.');
+      }
+    }
+
+    if (!res.ok) {
+      const text = await res.text();
+      this._log('error', `${res.status} on ${endpoint}: ${text.substring(0, 300)}`);
+      throw new Error(`Yahoo API error: ${res.status} on ${endpoint}`);
+    }
+
+    const data = await res.json();
+    this._log('api', `OK ${endpoint}`);
+    return data;
+  }
+
+  /**
+   * Resolve a game code ('mlb', 'nhl', etc.) to its numeric game key.
+   * Caches the result.
+   */
+  async resolveGameKey(gameCode) {
+    if (!gameCode) throw new Error('gameCode is required');
+    if (this._gameKeyCache.has(gameCode)) {
+      return this._gameKeyCache.get(gameCode);
+    }
+    const data = await this.get(`/game/${gameCode}`);
+    const gameKey = data.fantasy_content?.game?.[0]?.game_key;
+    if (!gameKey) throw new Error(`Could not resolve game key for '${gameCode}'`);
+    this._gameKeyCache.set(gameCode, gameKey);
+    this._log('info', `Resolved ${gameCode} game key: ${gameKey}`);
+    return gameKey;
+  }
+
+  /**
+   * Build a league key from game key + league ID.
+   */
+  leagueKey(gameKey, leagueId) {
+    return `${gameKey}.l.${leagueId}`;
+  }
+
+  /**
+   * Discover all leagues the authenticated user belongs to for the given game codes.
+   * Returns a flat array of league objects.
+   */
+  async getUserLeagues(gameCodes = ['mlb', 'nhl']) {
+    // Resolve all game keys first
+    const gameKeys = [];
+    for (const code of gameCodes) {
+      const key = await this.resolveGameKey(code);
+      gameKeys.push({ code, key });
+    }
+
+    const keyList = gameKeys.map(g => g.key).join(',');
+    const data = await this.get(`/users;use_login=1/games;game_keys=${keyList}/leagues`);
+
+    const leagues = [];
+    try {
+      const games = data.fantasy_content.users[0].user[1].games;
+      const gameCount = games.count;
+      for (let i = 0; i < gameCount; i++) {
+        const game = games[i].game;
+        const gameInfo = game[0];
+        const gameCode = gameInfo.code;
+        const gameKey = gameInfo.game_key;
+        const gameName = gameInfo.name;
+
+        if (game[1] && game[1].leagues) {
+          const leagueData = game[1].leagues;
+          const leagueCount = leagueData.count;
+          for (let j = 0; j < leagueCount; j++) {
+            const lg = leagueData[j].league[0];
+            leagues.push({
+              name: lg.name,
+              sport: gameCode,
+              sportName: gameName,
+              gameKey: gameKey,
+              leagueId: lg.league_id,
+              leagueKey: lg.league_key,
+              season: lg.season,
+              numTeams: lg.num_teams,
+              draftStatus: lg.draft_status,
+              scoringType: lg.scoring_type,
+              url: lg.url,
+            });
+          }
+        }
+      }
+    } catch (e) {
+      this._log('error', `Error parsing leagues response: ${e.message}`);
+      throw new Error(`Failed to parse leagues: ${e.message}`);
+    }
+
+    return leagues;
+  }
+
+  /**
+   * Fetch league settings (roster positions, stat categories, etc.)
+   *
+   * NOTE: Uses the subresource syntax `/league/{key};out=settings` rather
+   * than `/league/{key}/settings`. Yahoo's `/settings` sub-path returns a
+   * STALE predraft snapshot (frozen at draft time) and never refreshes —
+   * `is_auction_draft`, `uses_faab`, `draft_status`, etc. all come back wrong.
+   * The `;out=settings` subresource syntax returns fresh post-draft values.
+   */
+  async getLeagueSettings(leagueKey) {
+    if (!leagueKey) throw new Error('leagueKey is required');
+    const data = await this.get(`/league/${leagueKey};out=settings`);
+    try {
+      const league = data.fantasy_content.league;
+      const meta = league[0];
+      const settings = league[1].settings[0];
+      return { meta, settings };
+    } catch (e) {
+      throw new Error(`Failed to parse league settings: ${e.message}`);
+    }
+  }
+
+  /**
+   * Fetch draft results for a league. For auction drafts, each pick includes
+   * the auction `cost` (dollars paid). Returns an array of:
+   *   { pick, round, cost, teamKey, playerKey }
+   *
+   * Draft results don't change after the draft completes, so this is safe
+   * to cache for the entire season.
+   */
+  async getDraftResults(leagueKey) {
+    if (!leagueKey) throw new Error('leagueKey is required');
+    const data = await this.get(`/league/${leagueKey}/draftresults`);
+    try {
+      const dr = data.fantasy_content.league[1].draft_results;
+      const count = dr.count;
+      const picks = [];
+      for (let i = 0; i < count; i++) {
+        const result = dr[i].draft_result;
+        picks.push({
+          pick: result.pick,
+          round: result.round,
+          cost: result.cost != null ? Number(result.cost) : null,
+          teamKey: result.team_key,
+          playerKey: result.player_key,
+        });
+      }
+      return picks;
+    } catch (e) {
+      throw new Error(`Failed to parse draft results: ${e.message}`);
+    }
+  }
+
+  /**
+   * Fetch all teams in a league.
+   */
+  async getLeagueTeams(leagueKey) {
+    if (!leagueKey) throw new Error('leagueKey is required');
+    const data = await this.get(`/league/${leagueKey}/teams`);
+    try {
+      const teams = [];
+      const teamsData = data.fantasy_content.league[1].teams;
+      const count = teamsData.count;
+      for (let i = 0; i < count; i++) {
+        const team = teamsData[i].team[0];
+        const info = {};
+        for (const item of team) {
+          if (typeof item === 'object' && !Array.isArray(item)) {
+            Object.assign(info, item);
+          }
+        }
+        teams.push({
+          teamKey: info.team_key,
+          teamId: info.team_id,
+          name: info.name,
+          managerName: info.managers?.[0]?.manager?.nickname,
+        });
+      }
+      return teams;
+    } catch (e) {
+      throw new Error(`Failed to parse league teams: ${e.message}`);
+    }
+  }
+}
+
+module.exports = { YahooClient };

package/index.js

@@ -0,0 +1,16 @@
+const { YahooAuth } = require('./auth');
+const { YahooClient } = require('./client');
+
+/**
+ * Convenience factory: creates a YahooAuth + YahooClient pair.
+ *
+ * @param {Object} options - { clientId, clientSecret, redirectUri, tokenFile, certsDir, minInterval, userAgent, log }
+ * @returns {{ auth: YahooAuth, client: YahooClient }}
+ */
+function createClient(options = {}) {
+  const auth = new YahooAuth(options);
+  const client = new YahooClient(auth, options);
+  return { auth, client };
+}
+
+module.exports = { YahooAuth, YahooClient, createClient };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "yahoo-fantasy-api",
+  "version": "1.0.0",
+  "description": "Yahoo Fantasy Sports API client for Node.js — OAuth 2.0, rate limiting, and CLI tools",
+  "main": "index.js",
+  "bin": {
+    "yahoo-fantasy-api": "cli.js"
+  },
+  "files": [
+    "index.js",
+    "auth.js",
+    "client.js",
+    "cli.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "yahoo",
+    "fantasy",
+    "sports",
+    "api",
+    "oauth",
+    "fantasy-sports",
+    "fantasy-baseball",
+    "fantasy-hockey",
+    "fantasy-football"
+  ],
+  "author": "PeregrineCode",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeregrineCode/yahoo-fantasy-api.git"
+  },
+  "homepage": "https://github.com/PeregrineCode/yahoo-fantasy-api#readme",
+  "bugs": {
+    "url": "https://github.com/PeregrineCode/yahoo-fantasy-api/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "optionalDependencies": {
+    "dotenv": "^17.3.1"
+  }
+}