fantasy-basketball-sdk 0.0.0

package/AGENTS.md

@@ -0,0 +1,101 @@
+# Fantasy Basketball SDK — Agent Guide
+
+Tree-shakeable, ESM-only TypeScript SDK for fantasy basketball APIs (ESPN, Yahoo, Fantrax, extensible). Infra-first phase: scaffold and build pipeline only until provider logic is explicitly requested.
+
+## Architecture
+
+- **Subpath exports** — import one provider without pulling others: `fantasy-basketball-sdk/espn`, `/yahoo`, `/fantrax`
+- **`src/core/`** — shared types and errors (no provider-specific code)
+- **`src/runtime/`** — web-standard adapters (`fetch`, `URL`, `Headers`); no `node:*` imports
+- **`src/<provider>/`** — one folder per fantasy platform
+
+```text
+Consumers → package.json exports → provider → core → runtime
+```
+
+## Build, Test & Lint
+
+```bash
+npm ci
+npm run typecheck
+npm run lint
+npm run test
+npm run build
+npm run verify   # publint + scripts/verify-dist.mjs (dist ESM smoke imports)
+```
+
+Watch rebuild during development:
+
+```bash
+npm run dev
+```
+
+## Code Conventions
+
+- **ESM only** — `"type": "module"`; use `.js` extensions in relative imports (`./foo.js`)
+- **Strict TypeScript** — `verbatimModuleSyntax`, no `any` without justification
+- **Web-standard APIs only** in `src/` — `fetch`, `URL`, `Headers`; no `process.env`, no `node:*`, no `require()`
+- **Tree-shaking** — add providers as subpath entries, not giant root barrels
+- **Side effects** — keep `"sideEffects": false`; avoid top-level side effects in modules
+
+## File Structure
+
+```text
+src/
+  index.ts           # minimal root re-exports
+  core/              # shared types
+  runtime/           # FetchClient and adapters
+  espn/index.ts
+  yahoo/index.ts
+  fantrax/index.ts
+```
+
+Build output mirrors `src/` under `dist/` via Vite `preserveModules` + `tsc --emitDeclarationOnly`.
+
+## Adding a New Provider
+
+1. Create `src/<provider>/index.ts` with a `PROVIDER` constant or stub exports
+2. Add Vite lib entry in `vite.config.ts`: `'<provider>/index': resolve(__dirname, 'src/<provider>/index.ts')`
+3. Add `exports["./<provider>"]` in `package.json` (`types` + `import` paths under `dist/`)
+4. Add a smoke test in `test/exports.test.ts`
+5. Run `npm run build && npm run verify`
+
+## Releases
+
+Merges to `main` run the `verify` job, then a `release` job that uses [semantic-release](https://github.com/semantic-release/semantic-release) to publish to npm when the squash-merge commit is releasable.
+
+- **Do not manually bump `package.json` version** for routine releases — git tags and GitHub Releases are the source of truth
+- **PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/)** (`feat:`, `fix:`, etc.) because PRs are squash-merged and the title becomes the commit on `main`
+- **`chore:` / `docs:` / `ci:` merges do not publish** — only `feat`, `fix`, `perf`, and breaking changes trigger a release
+- **One-time npm setup:** register `fantasy-basketball-sdk` on npm and configure [trusted publishing](https://docs.npmjs.com/trusted-publishers) for GitHub Actions (`jacobra19/fantasy-basketball-sdk`, workflow `.github/workflows/ci.yml`, branch `main`). Fallback: add an `NPM_TOKEN` repo secret.
+
+## Runtime Import Examples
+
+```ts
+// Node 18+, Bun
+import { PROVIDER } from 'fantasy-basketball-sdk/espn';
+
+// Deno
+import { PROVIDER } from 'npm:fantasy-basketball-sdk/espn';
+
+// Browser / Cloudflare Workers (bundle or bare ESM)
+import { PROVIDER } from 'fantasy-basketball-sdk/espn';
+```
+
+## Boundaries
+
+- Do not commit secrets, tokens, or real league credentials
+- Do not implement ESPN/Yahoo/Fantrax API logic unless explicitly asked
+- Do not add CJS output or `require()` compatibility
+- Do not import Node built-ins in `src/`
+- Do not expand root `src/index.ts` with provider implementations (breaks tree-shaking)
+
+## Common Mistakes
+
+| Wrong                                                   | Correct                                         |
+| ------------------------------------------------------- | ----------------------------------------------- |
+| `import from 'fantasy-basketball-sdk'` for one provider | `import from 'fantasy-basketball-sdk/espn'`     |
+| `import './foo'` without `.js` extension                | `import './foo.js'`                             |
+| `import fs from 'node:fs'` in library code              | Use web APIs or accept injection via `runtime/` |
+| Re-export all providers from root index                 | Keep root minimal; use subpaths                 |
+| `process.env.YAHOO_TOKEN` in SDK                        | Pass config from consumer explicitly            |

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026, Yakov Rakhamimov
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+<p align="center">
+  <h1 align="center">fantasy-basketball-sdk</h1>
+  <p align="center">
+    Tree-shakeable fantasy basketball API SDK for ESPN, Yahoo, Fantrax, and more
+    <br/>
+    by <a href="https://github.com/jacobra19">Yakov Rakhamimov</a>
+  </p>
+</p>
+<br/>
+
+<p align="center">
+<a href="https://github.com/jacobra19/fantasy-basketball-sdk/actions?query=branch%3Amain"><img src="https://github.com/jacobra19/fantasy-basketball-sdk/actions/workflows/ci.yml/badge.svg?event=push&branch=main" alt="CI status" /></a>
+<a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/jacobra19/fantasy-basketball-sdk" alt="License"></a>
+<a href="https://www.npmjs.com/package/fantasy-basketball-sdk" rel="nofollow"><img src="https://img.shields.io/npm/dw/fantasy-basketball-sdk.svg" alt="npm"></a>
+<a href="https://github.com/jacobra19/fantasy-basketball-sdk" rel="nofollow"><img src="https://img.shields.io/github/stars/jacobra19/fantasy-basketball-sdk" alt="stars"></a>
+</p>
+
+<div align="center">
+  <a href="#quick-start">Quick start</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="./CONTRIBUTING.md">Contributing</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="./AGENTS.md">Agents</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://github.com/jacobra19/fantasy-basketball-sdk">GitHub</a>
+  <br />
+</div>
+
+<br/>
+
+> **Early development** — ESPN and Yahoo NBA APIs are available. Fantrax is still a placeholder.
+
+## Features
+
+- **ESM-only** with TypeScript types included (`dist/*.d.ts`)
+- **Subpath imports** per provider — `fantasy-basketball-sdk/espn`, `/yahoo`, `/fantrax`
+- Shared **`/core`** (types, shared constants) and **`/runtime`** (web-standard HTTP adapters)
+- Runs in **Node.js 18+**, **Bun**, **Deno**, **browsers**, and **Cloudflare Workers** (uses `fetch`, no Node built-ins in library code)
+
+## Requirements
+
+- **Node.js >= 18** (when using Node)
+- An **ESM** consumer project (`"type": "module"` in `package.json`, or a bundler that resolves ESM)
+
+## Installation
+
+```bash
+npm install fantasy-basketball-sdk
+```
+
+Releases are published automatically to npm when releasable changes merge to `main`. See [CONTRIBUTING.md](./CONTRIBUTING.md#releases) for how versioning works.
+
+For local development or testing before a release:
+
+```bash
+npm install /path/to/fantasy-basketball-sdk
+# or: npm install github:jacobra19/fantasy-basketball-sdk
+```
+
+## Quick start
+
+Import only what you need. Prefer a **provider subpath** when you work with one platform so bundlers can tree-shake the rest.
+
+### ESPN (Node / Bun)
+
+```ts
+import { League } from 'fantasy-basketball-sdk/espn';
+
+// Public leagues: omit espnS2 and swid. Private leagues: pass ESPN session cookies.
+const league = await League.create({
+  leagueId: 123456,
+  seasonId: 2025,
+  espnS2: '...',
+  swid: '{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}',
+});
+
+console.log(league.settings.name);
+
+for (const team of league.standings()) {
+  console.log(team.teamName, team.wins, team.losses);
+}
+
+const matchups = await league.scoreboard();
+const freeAgents = await league.freeAgents({ size: 25 });
+const transactions = await league.transactions();
+```
+
+`League.create` loads league data by default. Pass `fetchLeague: false` to construct without an initial fetch, then call `await league.fetchLeague()` when ready.
+
+### Yahoo (Node / Bun)
+
+Yahoo requires an OAuth 2.0 access token with Fantasy Sports scope. Obtain tokens via the [Yahoo OAuth 2.0 guide](https://developer.yahoo.com/oauth2/guide/) in your app, then pass the token to the SDK:
+
+```ts
+import { Game, League, YahooClient, addPlayer, setLineup } from 'fantasy-basketball-sdk/yahoo';
+
+const accessToken = '...'; // from your OAuth flow
+
+// Discover leagues for the logged-in user
+const game = Game.forNba(new YahooClient({ accessToken }));
+const leagueKeys = await game.leagueKeys({ seasons: ['2025'] });
+
+// Load a league by key or by numeric id + season
+const league = await League.create({
+  leagueKey: leagueKeys[0],
+  accessToken,
+});
+
+console.log(league.settings?.name);
+
+const standings = await league.standings();
+const matchups = await league.scoreboard();
+const freeAgents = await league.players({ status: 'FA', count: 25 });
+
+// Write: lineup edit (NBA uses date-based rosters)
+const team = league.toTeam(`${league.leagueKey}.t.1`);
+await setLineup(team, {
+  date: '2025-01-15',
+  moves: [{ playerKey: '466.p.1234', position: 'PG' }],
+});
+
+// Write: add a free agent
+await addPlayer(league, {
+  teamKey: `${league.leagueKey}.t.1`,
+  playerKey: '466.p.5678',
+});
+```
+
+Pass `refreshAccessToken` to `YahooClient` or `League.create` for automatic retry when the token expires.
+
+### Deno
+
+```ts
+import { League } from 'npm:fantasy-basketball-sdk/espn';
+
+const league = await League.create({ leagueId: 123456, seasonId: 2025 });
+console.log(league.standings().map((team) => team.teamName));
+```
+
+### Browser / Cloudflare Workers
+
+Use your bundler’s usual ESM resolution (Vite, webpack, esbuild, etc.):
+
+```ts
+import { League } from 'fantasy-basketball-sdk/espn';
+
+const league = await League.create({ leagueId: 123456, seasonId: 2025 });
+```
+
+## Subpath exports
+
+| Subpath                          | Purpose                    | Main symbols (today)               |
+| -------------------------------- | -------------------------- | ---------------------------------- |
+| `fantasy-basketball-sdk`         | Root entry                 | `Provider`, `PROVIDERS`            |
+| `fantasy-basketball-sdk/espn`    | ESPN NBA read API          | `League`, `Team`, `Player`, `Matchup` |
+| `fantasy-basketball-sdk/yahoo`   | Yahoo NBA API (read + write) | `League`, `Game`, `Team`, `Player`, `YahooClient` |
+| `fantasy-basketball-sdk/fantrax` | Fantrax module             | `PROVIDER`                         |
+| `fantasy-basketball-sdk/core`    | Shared types and constants | `Provider`, `PROVIDERS`            |
+| `fantasy-basketball-sdk/runtime` | HTTP adapter               | `FetchClient`, `createFetchClient` |
+
+## Tree-shaking
+
+- Import `fantasy-basketball-sdk/espn` (or `/yahoo`, `/fantrax`) instead of the root package when you only need one platform.
+- The package sets `"sideEffects": false` so unused modules can be dropped by your bundler.
+
+## TypeScript
+
+Types are published next to the JS output under `dist/`. You do not need `@types/fantasy-basketball-sdk`.
+
+For best results, use a modern `moduleResolution` setting (`Node16`, `NodeNext`, or `Bundler`) and ESM in your project.
+
+## Development
+
+Clone the repo and run:
+
+```bash
+npm ci
+npm run typecheck
+npm run lint
+npm run test
+npm run build
+npm run verify
+```
+
+**Contributors:** see [CONTRIBUTING.md](./CONTRIBUTING.md) for the PR workflow, branch protection, and merge policy.
+
+**Coding agents:** see [AGENTS.md](./AGENTS.md) for architecture, conventions, and how to add a new provider.
+
+## Roadmap
+
+ESPN and Yahoo NBA APIs are implemented. Fantrax client is planned.
+
+## License
+
+[ISC](./LICENSE)

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export type { Provider } from './types.js';
+export { PROVIDERS } from './providers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,2 @@
+import { PROVIDERS } from "./providers.js";
+export { PROVIDERS };

package/dist/core/providers.d.ts

@@ -0,0 +1,2 @@
+export declare const PROVIDERS: readonly ["espn", "yahoo", "fantrax"];
+//# sourceMappingURL=providers.d.ts.map

package/dist/core/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/core/providers.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,SAAS,uCAAsE,CAAC"}

package/dist/core/providers.js

@@ -0,0 +1,10 @@
+//#region src/core/providers.ts
+var PROVIDERS = [
+	"espn",
+	"yahoo",
+	"fantrax"
+];
+//#endregion
+export { PROVIDERS };
+
+//# sourceMappingURL=providers.js.map

package/dist/core/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","names":[],"sources":["../../src/core/providers.ts"],"sourcesContent":["import type { Provider } from './types.js';\n\nexport const PROVIDERS = ['espn', 'yahoo', 'fantrax'] as const satisfies readonly Provider[];\n"],"mappings":";AAEA,IAAa,YAAY;CAAC;CAAQ;CAAS;AAAS"}

package/dist/core/types.d.ts

@@ -0,0 +1,2 @@
+export type Provider = 'espn' | 'yahoo' | 'fantrax';
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC"}

package/dist/espn/client.d.ts

@@ -0,0 +1,37 @@
+import type { EspnLeagueResponse, EspnProPlayer, EspnProScheduleResponse } from './types/raw.js';
+export interface EspnClientOptions {
+    leagueId: number;
+    seasonId: number;
+    espnS2?: string;
+    swid?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export interface RequestOptions {
+    params?: Record<string, string | number | string[] | number[] | undefined>;
+    headers?: Record<string, string>;
+    extend?: string;
+}
+export declare class EspnClient {
+    readonly leagueId: number;
+    readonly seasonId: number;
+    private readonly fetchFn;
+    private readonly cookieHeader;
+    private readonly endpoint;
+    private readonly newsEndpoint;
+    private leagueEndpoint;
+    constructor(options: EspnClientOptions);
+    private buildLeagueEndpoint;
+    private swapLeagueEndpoint;
+    private requestJson;
+    private checkLeagueStatus;
+    leagueGet(options?: RequestOptions): Promise<EspnLeagueResponse>;
+    get(options?: RequestOptions): Promise<unknown>;
+    newsGet(options?: RequestOptions): Promise<unknown>;
+    getLeague(): Promise<EspnLeagueResponse>;
+    getProSchedule(): Promise<EspnProScheduleResponse>;
+    getProPlayers(): Promise<EspnProPlayer[]>;
+    getLeagueDraft(): Promise<EspnLeagueResponse>;
+    getPlayerCard(playerIds: number[], maxScoringPeriod: number, additionalFilters?: string[]): Promise<EspnLeagueResponse>;
+    getPlayerNews(playerId: number): Promise<unknown>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/espn/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/espn/client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAGjG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,UAAU;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,cAAc,CAAS;gBAEnB,OAAO,EAAE,iBAAiB;IAUtC,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,kBAAkB;YASZ,WAAW;YAUX,iBAAiB;IA0CzB,SAAS,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA8BpE,GAAG,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBnD,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBvD,SAAS,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAcxC,cAAc,IAAI,OAAO,CAAC,uBAAuB,CAAC;IAMlD,aAAa,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAUzC,cAAc,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAM7C,aAAa,CACjB,SAAS,EAAE,MAAM,EAAE,EACnB,gBAAgB,EAAE,MAAM,EACxB,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAC3B,OAAO,CAAC,kBAAkB,CAAC;IAsBxB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGxD"}

package/dist/espn/client.js

@@ -0,0 +1,145 @@
+import { FANTASY_BASE_ENDPOINT, NEWS_BASE_ENDPOINT, View } from "./constants.js";
+import { EspnAccessDenied, EspnApiError, EspnInvalidLeague, assertEspnResponse } from "./errors.js";
+import { buildCookieHeader, buildQueryString } from "./utils.js";
+//#region src/espn/client.ts
+var EspnClient = class {
+	leagueId;
+	seasonId;
+	fetchFn;
+	cookieHeader;
+	endpoint;
+	newsEndpoint;
+	leagueEndpoint;
+	constructor(options) {
+		this.leagueId = options.leagueId;
+		this.seasonId = options.seasonId;
+		this.fetchFn = options.fetch ?? globalThis.fetch;
+		this.cookieHeader = buildCookieHeader(options.espnS2, options.swid);
+		this.endpoint = `${FANTASY_BASE_ENDPOINT}fba/seasons/${options.seasonId}`;
+		this.newsEndpoint = `${NEWS_BASE_ENDPOINT}fba/news/players`;
+		this.leagueEndpoint = this.buildLeagueEndpoint(options.seasonId, options.leagueId);
+	}
+	buildLeagueEndpoint(seasonId, leagueId) {
+		const base = `${FANTASY_BASE_ENDPOINT}fba`;
+		if (seasonId < 2018) return `${base}/leagueHistory/${leagueId}?seasonId=${seasonId}`;
+		return `${base}/seasons/${seasonId}/segments/0/leagues/${leagueId}`;
+	}
+	swapLeagueEndpoint() {
+		const base = `${FANTASY_BASE_ENDPOINT}fba`;
+		if (this.leagueEndpoint.includes("/leagueHistory/")) this.leagueEndpoint = `${base}/seasons/${this.seasonId}/segments/0/leagues/${this.leagueId}`;
+		else this.leagueEndpoint = `${base}/leagueHistory/${this.leagueId}?seasonId=${this.seasonId}`;
+	}
+	async requestJson(url, init) {
+		const headers = new Headers(init?.headers);
+		if (this.cookieHeader) headers.set("Cookie", this.cookieHeader);
+		const response = await this.fetchFn(url, {
+			...init,
+			headers
+		});
+		return {
+			response,
+			body: await response.json()
+		};
+	}
+	async checkLeagueStatus(status, extend, params, headers) {
+		if (status === 401) {
+			const originalEndpoint = this.leagueEndpoint;
+			this.swapLeagueEndpoint();
+			const query = buildQueryString(params ?? {});
+			const url = `${this.leagueEndpoint}${extend}${query}`;
+			const retryHeaders = new Headers(headers);
+			if (this.cookieHeader) retryHeaders.set("Cookie", this.cookieHeader);
+			const retryResponse = await this.fetchFn(url, { headers: retryHeaders });
+			if (retryResponse.ok) return retryResponse.json();
+			this.leagueEndpoint = originalEndpoint;
+			if (!this.cookieHeader) throw new EspnAccessDenied();
+			throw new EspnAccessDenied(`League ${this.leagueId} cannot be accessed with the provided credentials`);
+		}
+		if (status === 404) throw new EspnInvalidLeague(this.leagueId);
+		if (status !== 200) throw new EspnApiError(status);
+		return null;
+	}
+	async leagueGet(options = {}) {
+		const { params, headers, extend = "" } = options;
+		const query = buildQueryString(params ?? {});
+		const url = `${this.leagueEndpoint}${extend}${query}`;
+		const requestHeaders = new Headers(headers);
+		if (this.cookieHeader) requestHeaders.set("Cookie", this.cookieHeader);
+		const response = await this.fetchFn(url, { headers: requestHeaders });
+		const alternate = await this.checkLeagueStatus(response.status, extend, params, headers);
+		let data;
+		if (alternate !== null) data = alternate;
+		else if (!response.ok) throw new EspnApiError(response.status);
+		else data = await response.json();
+		if (Array.isArray(data)) data = data[0];
+		assertEspnResponse(data);
+		return data;
+	}
+	async get(options = {}) {
+		const { params, headers, extend = "" } = options;
+		const query = buildQueryString(params ?? {});
+		const url = `${this.endpoint}${extend}${query}`;
+		const requestHeaders = new Headers(headers);
+		if (this.cookieHeader) requestHeaders.set("Cookie", this.cookieHeader);
+		const response = await this.fetchFn(url, { headers: requestHeaders });
+		await this.checkLeagueStatus(response.status, extend, params, headers);
+		if (!response.ok) throw new EspnApiError(response.status);
+		const data = await response.json();
+		assertEspnResponse(data);
+		return data;
+	}
+	async newsGet(options = {}) {
+		const { params, headers, extend = "" } = options;
+		const query = buildQueryString(params ?? {});
+		const url = `${this.newsEndpoint}${extend}${query}`;
+		const requestHeaders = new Headers(headers);
+		if (this.cookieHeader) requestHeaders.set("Cookie", this.cookieHeader);
+		const response = await this.fetchFn(url, { headers: requestHeaders });
+		if (!response.ok) throw new EspnApiError(response.status);
+		return response.json();
+	}
+	async getLeague() {
+		return this.leagueGet({ params: { view: [
+			View.MTeam,
+			View.MRoster,
+			View.MMatchup,
+			View.MSettings,
+			View.MStandings
+		] } });
+	}
+	async getProSchedule() {
+		return await this.get({ params: { view: View.ProTeamSchedules } });
+	}
+	async getProPlayers() {
+		return await this.get({
+			extend: "/players",
+			params: { view: View.Players },
+			headers: { "x-fantasy-filter": JSON.stringify({ filterActive: { value: true } }) }
+		});
+	}
+	async getLeagueDraft() {
+		return this.leagueGet({ params: { view: View.MDraftDetail } });
+	}
+	async getPlayerCard(playerIds, maxScoringPeriod, additionalFilters) {
+		const additionalValue = [`00${this.seasonId}`, `10${this.seasonId}`];
+		if (additionalFilters) additionalValue.push(...additionalFilters);
+		const filters = { players: {
+			filterIds: { value: playerIds },
+			filterStatsForTopScoringPeriodIds: {
+				value: maxScoringPeriod,
+				additionalValue
+			}
+		} };
+		return this.leagueGet({
+			params: { view: View.KonaPlayerCard },
+			headers: { "x-fantasy-filter": JSON.stringify(filters) }
+		});
+	}
+	async getPlayerNews(playerId) {
+		return this.newsGet({ params: { playerId } });
+	}
+};
+//#endregion
+export { EspnClient };
+
+//# sourceMappingURL=client.js.map

package/dist/espn/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../../src/espn/client.ts"],"sourcesContent":["import { FANTASY_BASE_ENDPOINT, NEWS_BASE_ENDPOINT, SPORT_PATH, View } from './constants.js';\nimport {\n  EspnAccessDenied,\n  EspnApiError,\n  EspnInvalidLeague,\n  assertEspnResponse,\n} from './errors.js';\nimport type { EspnLeagueResponse, EspnProPlayer, EspnProScheduleResponse } from './types/raw.js';\nimport { buildCookieHeader, buildQueryString } from './utils.js';\n\nexport interface EspnClientOptions {\n  leagueId: number;\n  seasonId: number;\n  espnS2?: string;\n  swid?: string;\n  fetch?: typeof globalThis.fetch;\n}\n\nexport interface RequestOptions {\n  params?: Record<string, string | number | string[] | number[] | undefined>;\n  headers?: Record<string, string>;\n  extend?: string;\n}\n\nexport class EspnClient {\n  readonly leagueId: number;\n  readonly seasonId: number;\n\n  private readonly fetchFn: typeof globalThis.fetch;\n  private readonly cookieHeader: string | undefined;\n  private readonly endpoint: string;\n  private readonly newsEndpoint: string;\n  private leagueEndpoint: string;\n\n  constructor(options: EspnClientOptions) {\n    this.leagueId = options.leagueId;\n    this.seasonId = options.seasonId;\n    this.fetchFn = options.fetch ?? globalThis.fetch;\n    this.cookieHeader = buildCookieHeader(options.espnS2, options.swid);\n    this.endpoint = `${FANTASY_BASE_ENDPOINT}${SPORT_PATH}/seasons/${options.seasonId}`;\n    this.newsEndpoint = `${NEWS_BASE_ENDPOINT}${SPORT_PATH}/news/players`;\n    this.leagueEndpoint = this.buildLeagueEndpoint(options.seasonId, options.leagueId);\n  }\n\n  private buildLeagueEndpoint(seasonId: number, leagueId: number): string {\n    const base = `${FANTASY_BASE_ENDPOINT}${SPORT_PATH}`;\n    if (seasonId < 2018) {\n      return `${base}/leagueHistory/${leagueId}?seasonId=${seasonId}`;\n    }\n    return `${base}/seasons/${seasonId}/segments/0/leagues/${leagueId}`;\n  }\n\n  private swapLeagueEndpoint(): void {\n    const base = `${FANTASY_BASE_ENDPOINT}${SPORT_PATH}`;\n    if (this.leagueEndpoint.includes('/leagueHistory/')) {\n      this.leagueEndpoint = `${base}/seasons/${this.seasonId}/segments/0/leagues/${this.leagueId}`;\n    } else {\n      this.leagueEndpoint = `${base}/leagueHistory/${this.leagueId}?seasonId=${this.seasonId}`;\n    }\n  }\n\n  private async requestJson(url: string, init?: RequestInit): Promise<unknown> {\n    const headers = new Headers(init?.headers);\n    if (this.cookieHeader) {\n      headers.set('Cookie', this.cookieHeader);\n    }\n\n    const response = await this.fetchFn(url, { ...init, headers });\n    return { response, body: await response.json() };\n  }\n\n  private async checkLeagueStatus(\n    status: number,\n    extend: string,\n    params?: RequestOptions['params'],\n    headers?: Record<string, string>,\n  ): Promise<unknown | null> {\n    if (status === 401) {\n      const originalEndpoint = this.leagueEndpoint;\n      this.swapLeagueEndpoint();\n\n      const query = buildQueryString(params ?? {});\n      const url = `${this.leagueEndpoint}${extend}${query}`;\n      const retryHeaders = new Headers(headers);\n      if (this.cookieHeader) {\n        retryHeaders.set('Cookie', this.cookieHeader);\n      }\n\n      const retryResponse = await this.fetchFn(url, { headers: retryHeaders });\n      if (retryResponse.ok) {\n        return retryResponse.json();\n      }\n\n      this.leagueEndpoint = originalEndpoint;\n      if (!this.cookieHeader) {\n        throw new EspnAccessDenied();\n      }\n      throw new EspnAccessDenied(\n        `League ${this.leagueId} cannot be accessed with the provided credentials`,\n      );\n    }\n\n    if (status === 404) {\n      throw new EspnInvalidLeague(this.leagueId);\n    }\n\n    if (status !== 200) {\n      throw new EspnApiError(status);\n    }\n\n    return null;\n  }\n\n  async leagueGet(options: RequestOptions = {}): Promise<EspnLeagueResponse> {\n    const { params, headers, extend = '' } = options;\n    const query = buildQueryString(params ?? {});\n    const url = `${this.leagueEndpoint}${extend}${query}`;\n\n    const requestHeaders = new Headers(headers);\n    if (this.cookieHeader) {\n      requestHeaders.set('Cookie', this.cookieHeader);\n    }\n\n    const response = await this.fetchFn(url, { headers: requestHeaders });\n    const alternate = await this.checkLeagueStatus(response.status, extend, params, headers);\n\n    let data: unknown;\n    if (alternate !== null) {\n      data = alternate;\n    } else if (!response.ok) {\n      throw new EspnApiError(response.status);\n    } else {\n      data = await response.json();\n    }\n\n    if (Array.isArray(data)) {\n      data = data[0];\n    }\n\n    assertEspnResponse(data);\n    return data as EspnLeagueResponse;\n  }\n\n  async get(options: RequestOptions = {}): Promise<unknown> {\n    const { params, headers, extend = '' } = options;\n    const query = buildQueryString(params ?? {});\n    const url = `${this.endpoint}${extend}${query}`;\n\n    const requestHeaders = new Headers(headers);\n    if (this.cookieHeader) {\n      requestHeaders.set('Cookie', this.cookieHeader);\n    }\n\n    const response = await this.fetchFn(url, { headers: requestHeaders });\n    await this.checkLeagueStatus(response.status, extend, params, headers);\n\n    if (!response.ok) {\n      throw new EspnApiError(response.status);\n    }\n\n    const data = await response.json();\n    assertEspnResponse(data);\n    return data;\n  }\n\n  async newsGet(options: RequestOptions = {}): Promise<unknown> {\n    const { params, headers, extend = '' } = options;\n    const query = buildQueryString(params ?? {});\n    const url = `${this.newsEndpoint}${extend}${query}`;\n\n    const requestHeaders = new Headers(headers);\n    if (this.cookieHeader) {\n      requestHeaders.set('Cookie', this.cookieHeader);\n    }\n\n    const response = await this.fetchFn(url, { headers: requestHeaders });\n    if (!response.ok) {\n      throw new EspnApiError(response.status);\n    }\n\n    return response.json();\n  }\n\n  async getLeague(): Promise<EspnLeagueResponse> {\n    return this.leagueGet({\n      params: {\n        view: [\n          View.MTeam,\n          View.MRoster,\n          View.MMatchup,\n          View.MSettings,\n          View.MStandings,\n        ],\n      },\n    });\n  }\n\n  async getProSchedule(): Promise<EspnProScheduleResponse> {\n    return (await this.get({\n      params: { view: View.ProTeamSchedules },\n    })) as EspnProScheduleResponse;\n  }\n\n  async getProPlayers(): Promise<EspnProPlayer[]> {\n    const filters = { filterActive: { value: true } };\n    const data = await this.get({\n      extend: '/players',\n      params: { view: View.Players },\n      headers: { 'x-fantasy-filter': JSON.stringify(filters) },\n    });\n    return data as EspnProPlayer[];\n  }\n\n  async getLeagueDraft(): Promise<EspnLeagueResponse> {\n    return this.leagueGet({\n      params: { view: View.MDraftDetail },\n    });\n  }\n\n  async getPlayerCard(\n    playerIds: number[],\n    maxScoringPeriod: number,\n    additionalFilters?: string[],\n  ): Promise<EspnLeagueResponse> {\n    const additionalValue = [`00${this.seasonId}`, `10${this.seasonId}`];\n    if (additionalFilters) {\n      additionalValue.push(...additionalFilters);\n    }\n\n    const filters = {\n      players: {\n        filterIds: { value: playerIds },\n        filterStatsForTopScoringPeriodIds: {\n          value: maxScoringPeriod,\n          additionalValue,\n        },\n      },\n    };\n\n    return this.leagueGet({\n      params: { view: View.KonaPlayerCard },\n      headers: { 'x-fantasy-filter': JSON.stringify(filters) },\n    });\n  }\n\n  async getPlayerNews(playerId: number): Promise<unknown> {\n    return this.newsGet({ params: { playerId } });\n  }\n}\n"],"mappings":"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"}

package/dist/espn/constants.d.ts

@@ -0,0 +1,34 @@
+export declare const FANTASY_BASE_ENDPOINT = "https://lm-api-reads.fantasy.espn.com/apis/v3/games/";
+export declare const NEWS_BASE_ENDPOINT = "https://site.api.espn.com/apis/fantasy/v3/games/";
+export declare const SPORT_PATH = "fba";
+export declare const View: {
+    readonly Modular: "modular";
+    readonly MNav: "mNav";
+    readonly MSettings: "mSettings";
+    readonly MStatus: "mStatus";
+    readonly MTeam: "mTeam";
+    readonly MBoxscore: "mBoxscore";
+    readonly MMatchupScore: "mMatchupScore";
+    readonly MRoster: "mRoster";
+    readonly MScoreboard: "mScoreboard";
+    readonly MTopPerformers: "mTopPerformers";
+    readonly KonaGameState: "kona_game_state";
+    readonly MMatchup: "mMatchup";
+    readonly MStandings: "mStandings";
+    readonly MDraftDetail: "mDraftDetail";
+    readonly KonaPlayerInfo: "kona_player_info";
+    readonly KonaPlayerCard: "kona_playercard";
+    readonly KonaLeagueCommunication: "kona_league_communication";
+    readonly MTransactions2: "mTransactions2";
+    readonly ProTeamSchedules: "proTeamSchedules_wl";
+    readonly Players: "players_wl";
+};
+export type ViewValue = (typeof View)[keyof typeof View];
+export declare const POSITION_MAP: Record<number | string, number | string>;
+export declare const PRO_TEAM_MAP: Record<number, string>;
+export declare const STATS_MAP: Record<string, string>;
+export declare const STAT_ID_MAP: Record<string, string>;
+export declare const ACTIVITY_MAP: Record<number | string, number | string>;
+export declare const TRANSACTION_TYPES: Set<string>;
+export declare const NINE_CAT_STATS: Set<string>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/espn/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/espn/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,yDACsB,CAAC;AACzD,eAAO,MAAM,kBAAkB,qDAAqD,CAAC;AACrF,eAAO,MAAM,UAAU,QAAQ,CAAC;AAEhC,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;CAqBP,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,OAAO,IAAI,CAAC,CAAC;AAEzD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,CAgCjE,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgC/C,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA+C5C,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAM9C,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,CAWjE,CAAC;AAEF,eAAO,MAAM,iBAAiB,aAc5B,CAAC;AAEH,eAAO,MAAM,cAAc,aAUzB,CAAC"}