yfs-api

Typed ESM client for the Yahoo Fantasy Sports API.

Requirements

• Node.js 18 or newer
• ESM (import); CommonJS is not published
• Yahoo application credentials

npm install yfs-api

Public Reads

Public mode uses OAuth 1.0 request signing as an observed SDK compatibility path. Yahoo's current Fantasy Sports documentation requires OAuth 2.0, so do not treat public OAuth 1.0 support as a long-term Yahoo contract.

import { YahooFantasyClient } from 'yfs-api';

const client = new YahooFantasyClient({
  clientId: process.env.YAHOO_CLIENT_ID!,
  clientSecret: process.env.YAHOO_CLIENT_SECRET!,
  publicMode: true,
});

const { game } = await client.api().game('nhl').get();

User Authentication

User mode uses OAuth 2.0. Generate and retain a state value, validate it on the callback, then exchange the authorization code.

const client = new YahooFantasyClient({
  clientId: process.env.YAHOO_CLIENT_ID!,
  clientSecret: process.env.YAHOO_CLIENT_SECRET!,
  redirectUri: 'https://example.com/oauth/callback',
});

const request = client.createAuthorizationRequest();
// Store request.state in the user's server-side session and redirect to request.url.

client.validateAuthorizationState(request.state, callbackState);
await client.authenticate(authorizationCode);

Pass a TokenStorage implementation as the second constructor argument and call loadTokens() when starting a session. Access tokens are refreshed when needed and newly issued tokens are saved through that storage.

Resource Reads

Responses preserve the selected parent hierarchy. For example, a nested user request returns users -> games -> teams, not a top-level teams array.

const response = await client.api().users().games(['nhl']).teams([]).get();

for (const user of response.users) {
  for (const game of user.games ?? []) {
    console.log(game.teams ?? []);
  }
}

const league = await client
  .api()
  .league('1.l.2')
  .include('settings', 'standings', 'draftresults')
  .get();

const team = await client.api().team('1.l.2.t.3').include('standings').get();

Root plural selectors require at least one key. Filters and selectors are serialized into Yahoo's semicolon-delimited paths and can be inspected with toPath().

Roster Writes

Roster updates are the only stable write helper exported at the package root. The result is a confirmation object when Yahoo returns one, otherwise undefined.

import { RosterMoveBuilder } from 'yfs-api';

const moves = new RosterMoveBuilder()
  .week(10)
  .movePlayer('1.p.2', 'BN');

const confirmation = await client
  .api()
  .team('1.l.2.t.3')
  .roster()
  .update(moves);

Transaction mutation builders and resources are intentionally not public. Transaction DTOs describe read responses only.

Experimental Frontend Adapter

YahooFrontendApiClient and createFrontendApi target Yahoo's observed web frontend routes. They are separate from the OAuth client and not a supported Yahoo API. Reads under /fantasy/v2/ and /fantasy/v3/ are sent as-is; writes are limited to an internal allowlist (currently the roster PUT) and require a user-supplied browser session. See docs/frontend-api-adapter.md.

Raw XML

Use client.requestRawXml(path, options) when the normalized DTO is not suitable. Regular resource reads continue to parse and normalize Yahoo XML.

Public Surface

The package root exports the client, OAuth 1.0 and OAuth 2.0 clients/types, OAuth state request type, Config, TokenStorage, RequestOptions, error classes and guards, common key/scalar types, normalized DTOs, RosterMoveBuilder, RosterCoverageOptions, parseYahooXML, and the experimental frontend adapter (YahooFrontendApiClient, createFrontendApi, resolveFrontendRoute, FrontendApiError, and their types).

Development

bun install --frozen-lockfile
bun run check:package
SKIP_INTEGRATION_TESTS=true bun run test:integration

Live integration tests are manual. Destructive tests require the separate test:integration:destructive command and explicit configuration. See docs/INTEGRATION_TEST_SETUP.md.

Documentation

• Documentation index — start here for all docs
• Domain glossary — fantasy vocabulary
• Yahoo API overview — protocol reference
• OAuth 2.0
• Token storage contract
• Integration tests
• Experimental frontend adapter

Release History

2.3.0 is the current stable API. Material for the 2.0.0-beta.* and 1.x lines in the changelog and archive is historical, not current guidance.

MIT licensed. See LICENSE.