@ufcalendar/sdk 0.2.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @ufcalendar/sdk — TypeScript client for the UFCalendar Fight API
2
2
 
3
- The [UFCalendar Fight API](https://www.ufcalendar.com/developers) is a REST API for MMA data: **UFC, PFL, OKTAGON, BKFC and RIZIN** events, full fight cards, results within minutes, per-fight and round-by-round statistics, complete fighter careers, the only **UFC rankings API with point-in-time history back to 2013**, and the only one serving **judges' scorecards** — every official, every round. This package is a dependency-free `fetch` wrapper over it: one method per endpoint, cursor pagination handled for you, ESM + CJS, Node 18+, browsers and edge runtimes.
3
+ The [UFCalendar Fight API](https://www.ufcalendar.com/developers) is a REST API for MMA data: **UFC, PFL, OKTAGON, BKFC and RIZIN** events, full fight cards, results within minutes, per-fight and round-by-round statistics, complete fighter careers, the only **UFC rankings API with point-in-time history back to 2013**, and the only one serving **judges' scorecards** — every official, every round — plus the **UFCalendar consensus odds line** (current, opening and closing on every plan, line movement on Pro). This package is a dependency-free `fetch` wrapper over it: one method per endpoint, cursor pagination handled for you, ESM + CJS, Node 18+, browsers and edge runtimes.
4
4
 
5
5
  ```bash
6
6
  npm install @ufcalendar/sdk
@@ -47,22 +47,87 @@ List endpoints are **async generators** that follow `meta.pagination.next_cursor
47
47
  |---|---|
48
48
  | `plans()` | `GET /v1/plans` — plans, quotas, trial terms, MCP endpoint (no key required) |
49
49
  | `orgs()` / `org(slug)` | `GET /v1/orgs` / `…/{slug}` |
50
- | `events({ org, status, from, to, order, limit })` | `GET /v1/events` (paginated) |
51
- | `event(slug)` / `eventChanges(slug)` | `GET /v1/events/{slug}` / `…/changes` |
52
- | `eventLive(slug)` | `GET /v1/events/{slug}/live` — real-time `LiveState` on fight night (Pro+); the same document streams over `wss://live.ufcalendar.com/v1?key=…` |
53
- | `fight(id)` / `fightStats(id)` / `fightRounds(id)` | `GET /v1/fights/{id}` / `…/stats` / `…/rounds` |
50
+ | `events({ org, status, from, to, order, isTitleCard, isPpv, include: ['headline'], limit })` | `GET /v1/events` (paginated; `headline` = each card's main event and its result) |
51
+ | `event(slug, { include: ['eta', 'odds'] })` / `eventChanges(slug)` | `GET /v1/events/{slug}` / `…/changes` (`eta` = per-bout estimated start; `odds` = each bout's latest consensus line) |
52
+ | `eventWatch(slug, { country })` | `GET /v1/events/{slug}/watch` — how to watch one event, per country: the rights deals for its series merged with the event's own listings |
53
+ | `changes({ org, since, kind, limit })` | `GET /v1/changes` — the card-change feed across every event, newest first (paginated; default last 90 days) |
54
+ | `eventLive(slug)` | `GET /v1/events/{slug}/live` — real-time `LiveState` on fight night (Pro plans and up); the same document streams over `wss://live.ufcalendar.com/v1?key=…` |
55
+ | `subscribeLive(slug, onFrame, opts?)` | the **WebSocket** itself — every `LiveFrame` as it lands (Pro plans and up); returns an unsubscribe function |
56
+ | `fight(id, { include: ['odds'] })` / `fightStats(id)` / `fightRounds(id)` | `GET /v1/fights/{id}` / `…/stats` / `…/rounds` |
57
+ | `fightOdds(id)` / `eventOdds(slug)` | `GET /v1/fights/{id}/odds` / `GET /v1/events/{slug}/odds` — the UFCalendar consensus line: current, opening, closing (settled bouts), movement and `sources` (how many sportsbooks backed each point). Information only, not betting advice |
58
+ | `fightOddsHistory(id, { from, to })` | `GET /v1/fights/{id}/odds/history` — every consensus point, oldest first (async generator; Pro plans and up) |
59
+ | `findFights({ org, titleOnly, method, division, fighter, winner, from, to, mainEventsOnly, order, limit })` | `GET /v1/fights/search` — completed bouts, filtered, newest first (at least one narrowing filter; 25 a page, 10 pages deep) |
54
60
  | `fightScorecards(id)` | `GET /v1/fights/{id}/scorecards` — judges, rounds, totals, deductions |
55
- | `judges({ q, org, minFights })` / `judge(id)` / `judgeScorecards(id)` | `GET /v1/judges` / `…/{id}` / `…/{id}/scorecards` |
56
- | `fighters({ q, org, country })` / `fighter(slug)` | `GET /v1/fighters` / `…/{slug}` |
61
+ | `judges({ q, org, minFights })` / `judge(id)` / `judgeScorecards(id)` | `GET /v1/judges` / `…/{id}` / `…/{id}/scorecards` (`lastMeta.league` = baseline rates; each card row flags `lone_dissent` / `split` and lists `colleagues`) |
62
+ | `splitDecisions({ org, from, to, limit })` | `GET /v1/scorecards/splits` — split and majority decisions, newest first, with every judge's card and the dissenters named (paginated) |
63
+ | `fighters({ q, org, country })` / `fighter(slug, { include: ['bonuses', 'credentials'] })` | `GET /v1/fighters` / `…/{slug}` (always carries `next_fight` / `last_fight`; `bonuses` = the UFC bonus ledger; `credentials` = grappling and wrestling pedigree, gyms and coaches, each row sourced and confidence-graded) |
57
64
  | `fighterHistory` / `fighterStats` / `fighterRankings` / `fighterPowerIndex` | `GET /v1/fighters/{slug}/…` |
58
- | `rankings(org, { date })` / `divisionRankings(org, division)` / `champions()` | `GET /v1/rankings/…` / `/v1/champions` |
59
- | `powerIndex(org)` / `predictionsUpcoming()` | `GET /v1/power-index/{org}` / `/v1/predictions/upcoming` |
60
- | `broadcastRights(org, { country })` / `venue(id)` / `search(q)` / `usage()` | misc |
61
- | `webhookEndpoints()` / `createWebhookEndpoint(url, events)` / `rotateWebhookSecret(id)` / `deleteWebhookEndpoint(id)` | `/v1/webhook-endpoints` (Pro+) |
65
+ | `rankings(org, { date })` / `divisionRankings(org, division)` / `champions()` | `GET /v1/rankings/…` / `/v1/champions` (entries carry `movement`, `is_new`, `country_code`; `lastMeta` names the previous/next snapshot) |
66
+ | `powerIndex(org, { view, division, days, limit })` / `predictionsUpcoming({ event })` | `GET /v1/power-index/{org}` (`view`: `current` · `movers` · `peaks`) / `/v1/predictions/upcoming` |
67
+ | `matchmaker(org, { division, limit })` / `whosNext(fighter, { limit })` | `GET /v1/matchmaker/{org}` / `…/next/{fighter}` — UFCalendar's matchmaker: the fights worth making (scored 0–100, per division or across the roster; not bookings), and one fighter's best next opponents with the win probability for each and the bout already booked |
68
+ | `leaderboard(org, metric, { division, country, population, limit })` / `recordBook(org, { division, country, population, scope, top })` | `GET /v1/stats/leaders` / `…/record-book` — the Record Book: one leaderboard (48 metrics; ties flagged, sample size on every row), or every board's top rows grouped by category |
69
+ | `orgDivision(org, division)` | `GET /v1/orgs/{org}/divisions/{division}` — one weight class: rankings board, upcoming bouts, latest results, roster by recency |
70
+ | `yearStats(year, { org })` | `GET /v1/stats/years/{year}` — one calendar year in numbers for one promotion (or every covered one): methods, divisions, fastest finishes, upsets, Power Index climbers, busiest fighters, countries, judges |
71
+ | `compare(a, b)` | `GET /v1/compare` — two fighters side by side: bios, career stats, strike mix, streaks, previous meetings, common opponents, booked bout, model prediction (UFC), Power Index |
72
+ | `eventStorylines(slug)` | `GET /v1/events/{slug}/storylines` — the talking points of one card: title fights, eliminators, closest bout, rematches, streaks, debuts, returns, ranked fighters, nations |
73
+ | `eventPickem(slug)` | `GET /v1/events/{slug}/pickem` — how the UFCalendar community is picking each bout on one card (picks per corner, total, percentage); crowd sentiment, not a market and not a forecast |
74
+ | `broadcastRights(org, { country, series })` / `venue(id)` / `search(q)` / `usage()` | misc (`series: 'dwcs' \| 'rtufc'` = a UFC sub-series grid) |
75
+ | `venues({ q, country, limit })` / `venueEvents(id, { status, from, to, order, limit })` | `GET /v1/venues` / `…/{id}/events` — venue search, and every covered event at one venue, newest first (paginated) |
76
+ | `articles({ q, tag, locale, limit })` / `article(slug, { locale })` | `GET /v1/articles` / `…/{slug}` — UFCalendar's own editorial archive, newest first, in any of the 13 site languages (paginated), and one article's full Markdown body |
77
+ | `webhookEndpoints()` / `createWebhookEndpoint(url, events)` / `rotateWebhookSecret(id)` / `deleteWebhookEndpoint(id)` | `/v1/webhook-endpoints` (Pro+; kinds `event.announced`, `fight.result`, `card.changed`, `event.completed`, `odds.moved` — the consensus line moved 5+ points or the favourite flipped) |
62
78
  | `calendarIcsUrl(org)` | `GET /v1/calendar/{org}.ics` (URL builder — no request) |
63
79
  | `get(path, params)` / `getWithMeta(path, params)` | escape hatch for anything new |
64
80
 
65
- Hand-written types cover events, fights, fighters, rankings, scorecards and plans; the generated `paths` / `operations` types from the OpenAPI document are exported for everything else.
81
+ Hand-written types cover events, fights, fighters, rankings, scorecards, consensus odds and plans; the generated `paths` / `operations` types from the OpenAPI document are exported for everything else.
82
+
83
+ ## Consensus odds
84
+
85
+ ```ts
86
+ const o = await api.fightOdds(83379);
87
+ console.log(o.consensus?.a.american, o.consensus?.b.american, o.consensus?.sources);
88
+ console.log(o.movement?.delta_points_a, o.closing); // closing = last line before the start (settled bouts)
89
+
90
+ for await (const point of api.fightOddsHistory(83379)) { // Pro plans and up
91
+ console.log(point.recorded_at, point.a.american, point.b.american);
92
+ }
93
+ ```
94
+
95
+ One anonymised UFCalendar consensus line per corner across the sportsbooks we track;
96
+ book identities are never exposed. Information only, not betting advice.
97
+
98
+ ## Live stream (UFC fight nights, Pro plans and up)
99
+
100
+ The **UFC live API**: a WebSocket that pushes the fight-night document the moment it
101
+ changes — card order and statuses, the bout in progress (round, running clock,
102
+ unofficial in-fight stats, per-round splits, a timestamped action timeline) and the
103
+ last result. It is the streaming half of `eventLive()`, and it is the **UFC live stats
104
+ API** you want instead of polling.
105
+
106
+ ```ts
107
+ import { FightAPI } from '@ufcalendar/sdk';
108
+
109
+ const api = new FightAPI(); // UFCAL_API_KEY
110
+
111
+ const stop = api.subscribeLive(
112
+ 'ufc-331',
113
+ (frame) => {
114
+ // frame.type: "snapshot" | "update" | "fight.final" | "event.completed"
115
+ const cur = frame.data?.current;
116
+ if (cur) console.log(frame.type, 'R', cur.round, cur.clock_sec);
117
+ },
118
+ { until: 'final' }, // close after the first fight.final; omit to run all night
119
+ );
120
+
121
+ // later
122
+ stop();
123
+ ```
124
+
125
+ `subscribeLive` uses the global `WebSocket` (browser, Node >= 22). On older Node inject
126
+ one: `{ WebSocketImpl: (await import('ws')).default as unknown as typeof WebSocket }`.
127
+ A dropped socket reconnects and re-subscribes once.
128
+
129
+ Runnable ticker: [`examples/live-ticker.ts`](examples/live-ticker.ts) — ~40 lines that
130
+ print `R2 3:41 · Oliveira 41 vs Makhachev 37 sig. strikes` as the round unfolds.
66
131
 
67
132
  ## Agents and MCP
68
133
 
@@ -93,11 +158,12 @@ Every error throws `FightAPIError` with `.status`, `.code`, `.message` and `.req
93
158
 
94
159
  ## Notes
95
160
 
96
- - No betting odds are served, by design.
161
+ - Odds are the UFCalendar consensus line only (no book identities). Information only, not betting advice.
97
162
  - Fighter `images` are Wikimedia Commons / Creative Commons files: displaying the `license` and `artist` fields as a credit is a licence requirement, not a style preference.
98
163
  - Scorecards are the official commission record. Media-member and fan scorecards are not part of the API.
164
+ - `source` / `source_slug` values (typed as `PublicSource`) name official publishers only — `ufc-stats`, `ufc-official`, `ufc-official-cards`, a promotion's `*-official`, `wikipedia`, `ufcalendar`. Every other publisher arrives as `public-records` (career records, history rows) or `commission-record` (judges' scorecards).
99
165
  - Not affiliated with UFC, Zuffa, TKO or any promotion. Terms: <https://www.ufcalendar.com/developers/terms>
100
166
 
101
- Full reference: <https://api.ufcalendar.com/docs> · OpenAPI 3.1: <https://api.ufcalendar.com/openapi.json> · Also on [PyPI (Python client)](https://pypi.org/project/ufcalendar/), [RapidAPI Hub](https://rapidapi.com/ceo-SP8r6F1JT/api/ufc-and-mma-fight-data-by-ufcalendar) and [Postman](https://www.postman.com/ceo-5d84eedc/workspace/ufcalendar-fight-api)
167
+ Full reference: <https://api.ufcalendar.com/docs> · OpenAPI 3.1: <https://api.ufcalendar.com/openapi.json> · Also on [PyPI (Python client)](https://pypi.org/project/ufcalendar/), [RapidAPI Hub](https://rapidapi.com/ceo-SP8r6F1JT/api/ufc-and-mma-fight-data-by-ufcalendar), [Postman](https://www.postman.com/ceo-5d84eedc/workspace/ufcalendar-fight-api) and the [hosted MCP server](https://github.com/UFCalendar/ufcalendar-mcp)
102
168
 
103
169
  MIT licensed.
package/dist/index.cjs CHANGED
@@ -23,15 +23,17 @@ __export(index_exports, {
23
23
  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
24
24
  FightAPI: () => FightAPI,
25
25
  FightAPIError: () => FightAPIError,
26
+ LIVE_WS_URL: () => LIVE_WS_URL,
26
27
  VERSION: () => VERSION
27
28
  });
28
29
  module.exports = __toCommonJS(index_exports);
29
30
 
30
31
  // src/version.ts
31
- var VERSION = "0.2.1";
32
+ var VERSION = "0.6.0";
32
33
 
33
34
  // src/client.ts
34
35
  var DEFAULT_BASE_URL = "https://api.ufcalendar.com/v1";
36
+ var LIVE_WS_URL = "wss://live.ufcalendar.com/v1";
35
37
  var DEFAULT_TIMEOUT_MS = 3e4;
36
38
  var FightAPIError = class extends Error {
37
39
  status;
@@ -174,40 +176,211 @@ var FightAPI = class {
174
176
  return (await this.#request("GET", "plans", { open: true })).data;
175
177
  }
176
178
  /* ---------------------------------------------------------------- orgs */
177
- /** Launch orgs with capability flags (stats / rounds / rankings / broadcasts / predictions). */
179
+ /** Launch orgs with capability flags (stats / rounds / rankings / broadcasts / predictions / scorecards / odds). */
178
180
  orgs() {
179
181
  return this.get("orgs");
180
182
  }
181
183
  org(slug) {
182
184
  return this.get(`orgs/${encodeURIComponent(slug)}`);
183
185
  }
186
+ /**
187
+ * One weight class in one promotion: its rankings board (null where the
188
+ * promotion publishes none), upcoming bouts at that weight, the latest
189
+ * results and the roster by recency. `division` is a slug, e.g.
190
+ * `lightweight` or `womens-strawweight`.
191
+ */
192
+ orgDivision(org, division) {
193
+ return this.get(`orgs/${encodeURIComponent(org)}/divisions/${encodeURIComponent(division)}`);
194
+ }
184
195
  /* -------------------------------------------------------------- events */
185
196
  /**
186
197
  * Schedule + results. Bare call = the upcoming calendar, soonest first.
187
198
  * `status: 'completed'` (or `order: 'desc'`) browses the archive
188
- * newest-first. `from` / `to` are `YYYY-MM-DD`.
199
+ * newest-first; `status: 'upcoming'` = every card not yet over (announced,
200
+ * scheduled or live). `from` / `to` are `YYYY-MM-DD`.
189
201
  */
190
202
  events(opts = {}) {
191
- const { limit, ...params } = opts;
192
- return this.#paginate("events", params, { limit });
203
+ const { limit, isTitleCard, isPpv, include, ...params } = opts;
204
+ return this.#paginate("events", {
205
+ ...params,
206
+ is_title_card: isTitleCard,
207
+ is_ppv: isPpv,
208
+ include: include?.length ? include.join(",") : void 0
209
+ }, { limit });
193
210
  }
194
- /** One event with its full fight card, venue and broadcasts. */
195
- event(idOrSlug) {
196
- return this.get(`events/${encodeURIComponent(String(idOrSlug))}`);
211
+ /**
212
+ * One event with its full fight card, venue and broadcasts.
213
+ * `include: ['eta']` adds an estimated start time to every bout;
214
+ * `include: ['odds']` adds each bout's current consensus line (the closing line once settled) (null when
215
+ * unpriced). Pass both as `['eta', 'odds']`.
216
+ */
217
+ event(idOrSlug, opts = {}) {
218
+ return this.get(
219
+ `events/${encodeURIComponent(String(idOrSlug))}`,
220
+ opts.include?.length ? { include: opts.include.join(",") } : void 0
221
+ );
222
+ }
223
+ /**
224
+ * Who airs one event, per country: the promotion's rights deals for the
225
+ * event's series merged with the event's own listings. `country` (ISO-2)
226
+ * narrows to that market plus worldwide.
227
+ */
228
+ eventWatch(idOrSlug, opts = {}) {
229
+ return this.get(`events/${encodeURIComponent(String(idOrSlug))}/watch`, opts);
230
+ }
231
+ /**
232
+ * The talking points of one card as of its start: title fights and
233
+ * eliminators, the closest bout (UFCalendar model, else Power Index — not
234
+ * betting advice), rematches and trilogy deciders, streaks, debuts and
235
+ * returns, ranked fighters, nations, tallest / longest reach, the fastest
236
+ * career finish.
237
+ */
238
+ eventStorylines(idOrSlug) {
239
+ return this.get(`events/${encodeURIComponent(String(idOrSlug))}/storylines`);
240
+ }
241
+ /**
242
+ * How the UFCalendar community is picking each bout on one card: picks per
243
+ * corner, the total and `pct_a`, in card order. Crowd sentiment from our
244
+ * own pick'em game, not a market and not a forecast.
245
+ */
246
+ eventPickem(idOrSlug) {
247
+ return this.get(`events/${encodeURIComponent(String(idOrSlug))}/pickem`);
248
+ }
249
+ /**
250
+ * The UFCalendar consensus odds for every non-cancelled bout on one card, in
251
+ * card order: `consensus`, `opening`, `closing` (settled bouts), `movement`
252
+ * and `points`. Unpriced bouts stay on the list with nulls and `points: 0`;
253
+ * `lastMeta.priced` / `lastMeta.unpriced` count both. Information only, not
254
+ * betting advice.
255
+ */
256
+ eventOdds(idOrSlug) {
257
+ return this.get(`events/${encodeURIComponent(String(idOrSlug))}/odds`);
197
258
  }
198
259
  /** Card-change diff log (fight added/removed, opponent swapped, date moved, profile merged). */
199
260
  eventChanges(idOrSlug) {
200
261
  return this.get(`events/${encodeURIComponent(String(idOrSlug))}/changes`);
201
262
  }
202
- /** Latest real-time LiveState snapshot on fight night (Business+), or null
203
- * when nothing is being streamed. The WebSocket at wss://live.ufcalendar.com/v1
204
- * pushes the same document as it changes. */
263
+ /**
264
+ * The card-change feed across every event, newest first (default: the last
265
+ * 90 days) — the `card.changed` webhook's audit trail, for callers that
266
+ * poll. `since` is `YYYY-MM-DD` or an ISO-8601 datetime.
267
+ */
268
+ changes(opts = {}) {
269
+ const { limit, ...params } = opts;
270
+ return this.#paginate("changes", params, { limit });
271
+ }
272
+ /** Latest real-time LiveState snapshot on fight night (Pro plans and up), or
273
+ * null when nothing is being streamed. The WebSocket at
274
+ * wss://live.ufcalendar.com/v1 pushes the same document as it changes — see
275
+ * `subscribeLive()`. */
205
276
  eventLive(idOrSlug) {
206
277
  return this.get(`events/${encodeURIComponent(String(idOrSlug))}/live`);
207
278
  }
279
+ /**
280
+ * Subscribe to the live WebSocket and receive every frame (Pro plans and up).
281
+ *
282
+ * The UFC live API: opens `wss://live.ufcalendar.com/v1?key=…`, sends
283
+ * `{"action":"subscribe","event":<slug>}` and calls `onFrame` with each
284
+ * `LiveFrame` — round, running clock, unofficial in-fight statistics and the
285
+ * action timeline, the same `LiveState` `eventLive()` returns.
286
+ *
287
+ * ```ts
288
+ * const stop = api.subscribeLive('ufc-331', (f) => console.log(f.type), { until: 'final' });
289
+ * ```
290
+ *
291
+ * Uses the global `WebSocket` (browser, Node >= 22) unless you inject one
292
+ * (`ws` on older Node). A dropped socket reconnects and re-subscribes ONCE.
293
+ *
294
+ * @returns an unsubscribe function — call it to close the socket for good.
295
+ */
296
+ subscribeLive(event, onFrame, opts = {}) {
297
+ const Impl = opts.WebSocketImpl ?? globalThis.WebSocket;
298
+ if (!Impl) {
299
+ throw new Error(
300
+ "subscribeLive() needs a WebSocket: use Node >= 22 (or a browser), or pass { WebSocketImpl } \u2014 e.g. `import WebSocket from 'ws'`."
301
+ );
302
+ }
303
+ if (!this.apiKey) {
304
+ throw new Error(
305
+ "No API key. The live stream authenticates with ?key=. Keys (and the free 1-day trial) live at https://www.ufcalendar.com/account/api"
306
+ );
307
+ }
308
+ const url = `${LIVE_WS_URL}?key=${encodeURIComponent(this.apiKey)}`;
309
+ let done = false;
310
+ let reconnects = 0;
311
+ let sock = null;
312
+ const open = () => {
313
+ const ws = new Impl(url);
314
+ sock = ws;
315
+ ws.onopen = () => {
316
+ try {
317
+ ws.send(JSON.stringify({ action: "subscribe", event }));
318
+ } catch {
319
+ }
320
+ };
321
+ ws.onmessage = (ev) => {
322
+ let frame;
323
+ try {
324
+ frame = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
325
+ } catch {
326
+ return;
327
+ }
328
+ if (!frame || typeof frame !== "object") return;
329
+ onFrame(frame);
330
+ if (opts.until === "final" && frame.type === "fight.final") {
331
+ done = true;
332
+ try {
333
+ ws.close();
334
+ } catch {
335
+ }
336
+ }
337
+ };
338
+ ws.onclose = () => {
339
+ if (done || reconnects >= 1) return;
340
+ reconnects += 1;
341
+ open();
342
+ };
343
+ };
344
+ open();
345
+ return () => {
346
+ done = true;
347
+ try {
348
+ sock?.close();
349
+ } catch {
350
+ }
351
+ };
352
+ }
208
353
  /* -------------------------------------------------------------- fights */
209
- fight(fightId) {
210
- return this.get(`fights/${encodeURIComponent(String(fightId))}`);
354
+ /** One bout with its result. `include: ['odds']` adds the current consensus line (the closing line once the bout is settled). */
355
+ fight(fightId, opts = {}) {
356
+ return this.get(
357
+ `fights/${encodeURIComponent(String(fightId))}`,
358
+ opts.include?.length ? { include: opts.include.join(",") } : void 0
359
+ );
360
+ }
361
+ /**
362
+ * The UFCalendar consensus line for one bout: `consensus` (latest point; the closing line once settled),
363
+ * `opening`, `closing` (the last point at or before the event start,
364
+ * settled bouts only), `movement` (opening → consensus in implied-probability
365
+ * points on corner a) and `sources` on every point (how many sportsbooks
366
+ * backed it; book identities are never exposed). An unpriced bout resolves
367
+ * with null blocks and `points: 0`. Information only, not betting advice.
368
+ */
369
+ fightOdds(fightId) {
370
+ return this.get(`fights/${encodeURIComponent(String(fightId))}/odds`);
371
+ }
372
+ /**
373
+ * Every consensus point for one bout, oldest first (Pro plans and up; a
374
+ * lower plan throws `FightAPIError` 403 `tier_required`). A point is stored
375
+ * only when the consensus moves. `from` / `to` are inclusive `YYYY-MM-DD`.
376
+ */
377
+ fightOddsHistory(fightId, opts = {}) {
378
+ const { limit, ...params } = opts;
379
+ return this.#paginate(
380
+ `fights/${encodeURIComponent(String(fightId))}/odds/history`,
381
+ params,
382
+ { limit }
383
+ );
211
384
  }
212
385
  /** Per-fight totals for both corners. */
213
386
  fightStats(fightId) {
@@ -230,6 +403,22 @@ var FightAPI = class {
230
403
  fightScorecards(fightId) {
231
404
  return this.get(`fights/${encodeURIComponent(String(fightId))}/scorecards`);
232
405
  }
406
+ /**
407
+ * Completed bouts, filtered — newest first unless `order: 'oldest'`. At
408
+ * least one narrowing filter is required (`titleOnly`, `method`,
409
+ * `division`, `fighter`, `winner`, `from`, `to`, `mainEventsOnly`); the
410
+ * server serves 25 rows a page and at most 10 pages.
411
+ */
412
+ findFights(opts = {}) {
413
+ const { limit, titleOnly, mainEventsOnly, fighter, winner, ...rest } = opts;
414
+ return this.#paginate("fights/search", {
415
+ ...rest,
416
+ title_only: titleOnly,
417
+ main_events_only: mainEventsOnly,
418
+ fighter: fighter === void 0 ? void 0 : String(fighter),
419
+ winner: winner === void 0 ? void 0 : String(winner)
420
+ }, { limit });
421
+ }
233
422
  /* -------------------------------------------------------------- judges */
234
423
  /**
235
424
  * Every official who has scored a launch-org bout, busiest first. Rates
@@ -242,7 +431,18 @@ var FightAPI = class {
242
431
  judge(judgeId) {
243
432
  return this.get(`judges/${encodeURIComponent(String(judgeId))}`);
244
433
  }
245
- /** Every card this judge has turned in, newest first. */
434
+ /**
435
+ * Split and majority decisions, newest first, with every judge's card and
436
+ * the dissenting judges named. Commission records only.
437
+ */
438
+ splitDecisions(opts = {}) {
439
+ const { limit, ...params } = opts;
440
+ return this.#paginate("scorecards/splits", params, { limit });
441
+ }
442
+ /**
443
+ * Every card this judge has turned in, newest first, with `lone_dissent`,
444
+ * `split` and the `colleagues`' totals on each row.
445
+ */
246
446
  judgeScorecards(judgeId, opts = {}) {
247
447
  return this.#paginate(
248
448
  `judges/${encodeURIComponent(String(judgeId))}/scorecards`,
@@ -255,27 +455,53 @@ var FightAPI = class {
255
455
  const { limit, ...params } = opts;
256
456
  return this.#paginate("fighters", params, { limit });
257
457
  }
258
- /** Bio, records, career stats, Power Index and CC-licensed images. */
259
- fighter(idOrSlug) {
260
- return this.get(`fighters/${encodeURIComponent(String(idOrSlug))}`);
458
+ /**
459
+ * Bio, records, career stats, Power Index, CC-licensed images, `next_fight`
460
+ * and `last_fight`. `include: ['bonuses']` adds the UFC bonus ledger;
461
+ * `include: ['credentials']` adds grappling and wrestling pedigree, gyms and
462
+ * coaches (every row with `sources` and a `confidence` grade).
463
+ */
464
+ fighter(idOrSlug, opts = {}) {
465
+ return this.get(
466
+ `fighters/${encodeURIComponent(String(idOrSlug))}`,
467
+ opts.include?.length ? { include: opts.include.join(",") } : void 0
468
+ );
261
469
  }
262
470
  /** Complete multi-promotion career timeline. */
263
471
  fighterHistory(idOrSlug) {
264
472
  return this.get(`fighters/${encodeURIComponent(String(idOrSlug))}/history`);
265
473
  }
266
- /** Career statistics, one source-stamped row per scope (`pro-mma`, `ufc-only` …). */
474
+ /** Raw career stat rows, one source-stamped row per scope (`pro-mma`, `ufc-only` …).
475
+ * For the readable split use `fighter().records` / `fighter().stats`. */
267
476
  fighterStats(idOrSlug) {
268
477
  return this.get(`fighters/${encodeURIComponent(String(idOrSlug))}/stats`);
269
478
  }
270
- /** Every official ranking row the fighter ever held, newest first. */
271
- fighterRankings(idOrSlug) {
272
- return this.get(`fighters/${encodeURIComponent(String(idOrSlug))}/rankings`);
479
+ /** Every ranking row the fighter ever held, newest first, across every board
480
+ * (`board` is `official` / `meta`; `is_champion` when rank 0). The endpoint is
481
+ * cursor-paginated since 2026-09-24 — this walks every page so the array is
482
+ * complete (a long career is 900+ rows). */
483
+ async fighterRankings(idOrSlug) {
484
+ const out = [];
485
+ for await (const row of this.#paginate(
486
+ `fighters/${encodeURIComponent(String(idOrSlug))}/rankings`,
487
+ { limit: 500 }
488
+ )) out.push(row);
489
+ return out;
273
490
  }
274
491
  fighterPowerIndex(idOrSlug) {
275
492
  return this.get(
276
493
  `fighters/${encodeURIComponent(String(idOrSlug))}/power-index`
277
494
  );
278
495
  }
496
+ /**
497
+ * Two fighters side by side (slugs or ids): bios with age, career stats,
498
+ * strike mix, win streaks, previous meetings, common opponents, the booked
499
+ * bout between them, the UFCalendar model prediction for it (UFC; not
500
+ * betting advice) and Power Index ratings.
501
+ */
502
+ compare(a, b) {
503
+ return this.get("compare", { a: String(a), b: String(b) });
504
+ }
279
505
  /* ------------------------------------------------------------ rankings */
280
506
  /**
281
507
  * Official board, point-in-time. `date: 'YYYY-MM-DD'` returns the board
@@ -290,30 +516,123 @@ var FightAPI = class {
290
516
  opts
291
517
  );
292
518
  }
293
- /** Current champions across every launch org. */
294
- champions() {
295
- return this.get("champions");
519
+ /** Current champions across every launch org, or one `org` / `division`. */
520
+ champions(opts = {}) {
521
+ return this.get("champions", opts);
522
+ }
523
+ /**
524
+ * UFCalendar Power Index board. `view: 'movers'` = biggest risers over
525
+ * `days` (default 365), `view: 'peaks'` = all-time peak ratings;
526
+ * `division` narrows any view.
527
+ */
528
+ powerIndex(org = "ufc", opts = {}) {
529
+ return this.get(`power-index/${encodeURIComponent(org)}`, {
530
+ view: opts.view,
531
+ division: opts.division,
532
+ days: opts.days,
533
+ limit: opts.limit
534
+ });
535
+ }
536
+ /* ---------------------------------------------------------- matchmaker */
537
+ /**
538
+ * UFCalendar's matchmaker: the fights worth making in one MMA promotion,
539
+ * scored 0–100, across the roster or for one `division` (`lastMeta.divisions`
540
+ * lists the valid ones). Not a list of bookings; computed without the
541
+ * site's Fight DNA factor.
542
+ */
543
+ matchmaker(org = "ufc", opts = {}) {
544
+ return this.get(`matchmaker/${encodeURIComponent(org)}`, {
545
+ division: opts.division,
546
+ limit: opts.limit
547
+ });
296
548
  }
297
- /** UFCalendar Power Index board. */
298
- powerIndex(org = "ufc") {
299
- return this.get(`power-index/${encodeURIComponent(org)}`);
549
+ /**
550
+ * Who one fighter (slug or id) should fight next: the best-scored
551
+ * opponents with the Power Index win probability for each, plus the bout
552
+ * already booked (`booked_next`).
553
+ */
554
+ whosNext(fighter, opts = {}) {
555
+ return this.get(`matchmaker/next/${encodeURIComponent(String(fighter))}`, { limit: opts.limit });
556
+ }
557
+ /* --------------------------------------------------------------- stats */
558
+ /**
559
+ * One Record Book leaderboard for one promotion (`metric` e.g. `wins`,
560
+ * `fastest_knockout`, `finish_rate`). Narrow with `division` (slug),
561
+ * `country` (ISO-2) or `population: 'active'` — not `country` and
562
+ * `active` together. `lastMeta.metric` names the unit and what
563
+ * `value_secondary` means.
564
+ */
565
+ leaderboard(org, metric, opts = {}) {
566
+ return this.get("stats/leaders", { org, metric, ...opts });
567
+ }
568
+ /**
569
+ * Every leaderboard's top rows (`top`, default 10, max 25) for one
570
+ * promotion, grouped by category.
571
+ */
572
+ recordBook(org, opts = {}) {
573
+ return this.get("stats/record-book", { org, ...opts });
574
+ }
575
+ /**
576
+ * One calendar year in numbers for one promotion, or every covered
577
+ * promotion when `org` is omitted: events, title fights, finish methods,
578
+ * divisions, fastest finishes, upsets, Power Index climbers, busiest
579
+ * fighters, host countries and the most-used judges.
580
+ */
581
+ yearStats(year, opts = {}) {
582
+ return this.get(`stats/years/${encodeURIComponent(String(year))}`, opts);
300
583
  }
301
584
  /* ---------------------------------------------------------------- misc */
302
- /** Model win probabilities for upcoming UFC bouts. */
303
- predictionsUpcoming() {
304
- return this.get("predictions/upcoming");
585
+ /** Model win probabilities for upcoming UFC bouts; `event` narrows to one card. */
586
+ predictionsUpcoming(opts = {}) {
587
+ return this.get(
588
+ "predictions/upcoming",
589
+ opts.event !== void 0 ? { event: String(opts.event) } : void 0
590
+ );
305
591
  }
306
- /** Who airs the promotion, per ISO-2 country. */
592
+ /**
593
+ * Who airs the promotion, per ISO-2 country — the org-wide deals, or a UFC
594
+ * sub-series grid with `series: 'dwcs' | 'rtufc'`.
595
+ */
307
596
  broadcastRights(org = "ufc", opts = {}) {
308
597
  return this.get(`broadcast-rights/${encodeURIComponent(org)}`, opts);
309
598
  }
599
+ /**
600
+ * Venues that hosted a covered promotion, alphabetical. `q` (2+ chars)
601
+ * matches name or city; `country` is an ISO-2 code or an English name.
602
+ */
603
+ venues(opts = {}) {
604
+ const { limit, ...params } = opts;
605
+ return this.#paginate("venues", params, { limit });
606
+ }
310
607
  venue(venueId) {
311
608
  return this.get(`venues/${encodeURIComponent(String(venueId))}`);
312
609
  }
610
+ /** Every covered event at one venue, newest first (`order: 'asc'` reverses). */
611
+ venueEvents(venueId, opts = {}) {
612
+ const { limit, ...params } = opts;
613
+ return this.#paginate(`venues/${encodeURIComponent(String(venueId))}/events`, params, { limit });
614
+ }
313
615
  /** Typeahead across fighters and events. */
314
616
  search(q) {
315
617
  return this.get("search", { q });
316
618
  }
619
+ /**
620
+ * UFCalendar's own editorial archive, newest first. `q` (2+ chars) matches
621
+ * title, summary or a tag; `tag` is exact; `locale` is one of the 13 site
622
+ * languages (English fallback).
623
+ */
624
+ articles(opts = {}) {
625
+ const { limit, ...params } = opts;
626
+ return this.#paginate("articles", params, { limit });
627
+ }
628
+ /**
629
+ * One article: full Markdown `body_md` (client widgets removed), author,
630
+ * tags, `published_at`; `served_locale` names the language
631
+ * delivered.
632
+ */
633
+ article(slug, opts = {}) {
634
+ return this.get(`articles/${encodeURIComponent(slug)}`, opts);
635
+ }
317
636
  /** Your key's month-to-date quota usage. */
318
637
  usage() {
319
638
  return this.get("usage");
@@ -341,8 +660,10 @@ var FightAPI = class {
341
660
  }
342
661
  /**
343
662
  * Register a signed webhook (Pro and up). `events` ⊆ `event.announced`,
344
- * `fight.result`, `card.changed`, `event.completed`. The signing secret is
345
- * returned ONCE, in this response.
663
+ * `fight.result`, `card.changed`, `event.completed`, `odds.moved` (the
664
+ * consensus line on an upcoming bout moved 5+ implied-probability points or
665
+ * the favourite flipped). The signing secret is returned ONCE, in this
666
+ * response.
346
667
  */
347
668
  async createWebhookEndpoint(url, events) {
348
669
  const body = { url };
@@ -364,6 +685,7 @@ var FightAPI = class {
364
685
  DEFAULT_BASE_URL,
365
686
  FightAPI,
366
687
  FightAPIError,
688
+ LIVE_WS_URL,
367
689
  VERSION
368
690
  });
369
691
  //# sourceMappingURL=index.cjs.map