@ufcalendar/sdk 0.3.0 → 0.6.1

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 **MMA data API with point-in-time UFC rankings 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,27 +47,57 @@ 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` |
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) |
52
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=…` |
53
55
  | `subscribeLive(slug, onFrame, opts?)` | the **WebSocket** itself — every `LiveFrame` as it lands (Pro plans and up); returns an unsubscribe function |
54
- | `fight(id)` / `fightStats(id)` / `fightRounds(id)` | `GET /v1/fights/{id}` / `…/stats` / `…/rounds` |
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) |
55
60
  | `fightScorecards(id)` | `GET /v1/fights/{id}/scorecards` — judges, rounds, totals, deductions |
56
- | `judges({ q, org, minFights })` / `judge(id)` / `judgeScorecards(id)` | `GET /v1/judges` / `…/{id}` / `…/{id}/scorecards` |
57
- | `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) |
58
64
  | `fighterHistory` / `fighterStats` / `fighterRankings` / `fighterPowerIndex` | `GET /v1/fighters/{slug}/…` |
59
- | `rankings(org, { date })` / `divisionRankings(org, division)` / `champions()` | `GET /v1/rankings/…` / `/v1/champions` |
60
- | `powerIndex(org)` / `predictionsUpcoming()` | `GET /v1/power-index/{org}` / `/v1/predictions/upcoming` |
61
- | `broadcastRights(org, { country })` / `venue(id)` / `search(q)` / `usage()` | misc |
62
- | `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) |
63
78
  | `calendarIcsUrl(org)` | `GET /v1/calendar/{org}.ics` (URL builder — no request) |
64
79
  | `get(path, params)` / `getWithMeta(path, params)` | escape hatch for anything new |
65
80
 
66
- 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.
67
97
 
68
98
  ## Live stream (UFC fight nights, Pro plans and up)
69
99
 
70
- The **UFC live API**: a WebSocket that pushes the fight-night document the moment it
100
+ The **live stream** of the MMA Fight Data API: a WebSocket that pushes the fight-night document the moment it
71
101
  changes — card order and statuses, the bout in progress (round, running clock,
72
102
  unofficial in-fight stats, per-round splits, a timestamped action timeline) and the
73
103
  last result. It is the streaming half of `eventLive()`, and it is the **UFC live stats
@@ -128,11 +158,12 @@ Every error throws `FightAPIError` with `.status`, `.code`, `.message` and `.req
128
158
 
129
159
  ## Notes
130
160
 
131
- - No betting odds are served, by design.
161
+ - Odds are the UFCalendar consensus line only (no book identities). Information only, not betting advice.
132
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.
133
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).
134
165
  - Not affiliated with UFC, Zuffa, TKO or any promotion. Terms: <https://www.ufcalendar.com/developers/terms>
135
166
 
136
- 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)
137
168
 
138
169
  MIT licensed.
package/dist/index.cjs CHANGED
@@ -29,7 +29,7 @@ __export(index_exports, {
29
29
  module.exports = __toCommonJS(index_exports);
30
30
 
31
31
  // src/version.ts
32
- var VERSION = "0.3.0";
32
+ var VERSION = "0.6.1";
33
33
 
34
34
  // src/client.ts
35
35
  var DEFAULT_BASE_URL = "https://api.ufcalendar.com/v1";
@@ -176,31 +176,99 @@ var FightAPI = class {
176
176
  return (await this.#request("GET", "plans", { open: true })).data;
177
177
  }
178
178
  /* ---------------------------------------------------------------- orgs */
179
- /** Launch orgs with capability flags (stats / rounds / rankings / broadcasts / predictions). */
179
+ /** Launch orgs with capability flags (stats / rounds / rankings / broadcasts / predictions / scorecards / odds). */
180
180
  orgs() {
181
181
  return this.get("orgs");
182
182
  }
183
183
  org(slug) {
184
184
  return this.get(`orgs/${encodeURIComponent(slug)}`);
185
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
+ }
186
195
  /* -------------------------------------------------------------- events */
187
196
  /**
188
197
  * Schedule + results. Bare call = the upcoming calendar, soonest first.
189
198
  * `status: 'completed'` (or `order: 'desc'`) browses the archive
190
- * 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`.
191
201
  */
192
202
  events(opts = {}) {
193
- const { limit, ...params } = opts;
194
- 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 });
195
210
  }
196
- /** One event with its full fight card, venue and broadcasts. */
197
- event(idOrSlug) {
198
- 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`);
199
258
  }
200
259
  /** Card-change diff log (fight added/removed, opponent swapped, date moved, profile merged). */
201
260
  eventChanges(idOrSlug) {
202
261
  return this.get(`events/${encodeURIComponent(String(idOrSlug))}/changes`);
203
262
  }
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
+ }
204
272
  /** Latest real-time LiveState snapshot on fight night (Pro plans and up), or
205
273
  * null when nothing is being streamed. The WebSocket at
206
274
  * wss://live.ufcalendar.com/v1 pushes the same document as it changes — see
@@ -211,7 +279,7 @@ var FightAPI = class {
211
279
  /**
212
280
  * Subscribe to the live WebSocket and receive every frame (Pro plans and up).
213
281
  *
214
- * The UFC live API: opens `wss://live.ufcalendar.com/v1?key=…`, sends
282
+ * The live MMA data stream: opens `wss://live.ufcalendar.com/v1?key=…`, sends
215
283
  * `{"action":"subscribe","event":<slug>}` and calls `onFrame` with each
216
284
  * `LiveFrame` — round, running clock, unofficial in-fight statistics and the
217
285
  * action timeline, the same `LiveState` `eventLive()` returns.
@@ -283,8 +351,36 @@ var FightAPI = class {
283
351
  };
284
352
  }
285
353
  /* -------------------------------------------------------------- fights */
286
- fight(fightId) {
287
- 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
+ );
288
384
  }
289
385
  /** Per-fight totals for both corners. */
290
386
  fightStats(fightId) {
@@ -307,6 +403,22 @@ var FightAPI = class {
307
403
  fightScorecards(fightId) {
308
404
  return this.get(`fights/${encodeURIComponent(String(fightId))}/scorecards`);
309
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
+ }
310
422
  /* -------------------------------------------------------------- judges */
311
423
  /**
312
424
  * Every official who has scored a launch-org bout, busiest first. Rates
@@ -319,7 +431,18 @@ var FightAPI = class {
319
431
  judge(judgeId) {
320
432
  return this.get(`judges/${encodeURIComponent(String(judgeId))}`);
321
433
  }
322
- /** 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
+ */
323
446
  judgeScorecards(judgeId, opts = {}) {
324
447
  return this.#paginate(
325
448
  `judges/${encodeURIComponent(String(judgeId))}/scorecards`,
@@ -332,27 +455,53 @@ var FightAPI = class {
332
455
  const { limit, ...params } = opts;
333
456
  return this.#paginate("fighters", params, { limit });
334
457
  }
335
- /** Bio, records, career stats, Power Index and CC-licensed images. */
336
- fighter(idOrSlug) {
337
- 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
+ );
338
469
  }
339
470
  /** Complete multi-promotion career timeline. */
340
471
  fighterHistory(idOrSlug) {
341
472
  return this.get(`fighters/${encodeURIComponent(String(idOrSlug))}/history`);
342
473
  }
343
- /** 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`. */
344
476
  fighterStats(idOrSlug) {
345
477
  return this.get(`fighters/${encodeURIComponent(String(idOrSlug))}/stats`);
346
478
  }
347
- /** Every official ranking row the fighter ever held, newest first. */
348
- fighterRankings(idOrSlug) {
349
- 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;
350
490
  }
351
491
  fighterPowerIndex(idOrSlug) {
352
492
  return this.get(
353
493
  `fighters/${encodeURIComponent(String(idOrSlug))}/power-index`
354
494
  );
355
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
+ }
356
505
  /* ------------------------------------------------------------ rankings */
357
506
  /**
358
507
  * Official board, point-in-time. `date: 'YYYY-MM-DD'` returns the board
@@ -367,30 +516,123 @@ var FightAPI = class {
367
516
  opts
368
517
  );
369
518
  }
370
- /** Current champions across every launch org. */
371
- champions() {
372
- 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
+ });
548
+ }
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 });
373
574
  }
374
- /** UFCalendar Power Index board. */
375
- powerIndex(org = "ufc") {
376
- return this.get(`power-index/${encodeURIComponent(org)}`);
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);
377
583
  }
378
584
  /* ---------------------------------------------------------------- misc */
379
- /** Model win probabilities for upcoming UFC bouts. */
380
- predictionsUpcoming() {
381
- 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
+ );
382
591
  }
383
- /** 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
+ */
384
596
  broadcastRights(org = "ufc", opts = {}) {
385
597
  return this.get(`broadcast-rights/${encodeURIComponent(org)}`, opts);
386
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
+ }
387
607
  venue(venueId) {
388
608
  return this.get(`venues/${encodeURIComponent(String(venueId))}`);
389
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
+ }
390
615
  /** Typeahead across fighters and events. */
391
616
  search(q) {
392
617
  return this.get("search", { q });
393
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
+ }
394
636
  /** Your key's month-to-date quota usage. */
395
637
  usage() {
396
638
  return this.get("usage");
@@ -418,8 +660,10 @@ var FightAPI = class {
418
660
  }
419
661
  /**
420
662
  * Register a signed webhook (Pro and up). `events` ⊆ `event.announced`,
421
- * `fight.result`, `card.changed`, `event.completed`. The signing secret is
422
- * 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.
423
667
  */
424
668
  async createWebhookEndpoint(url, events) {
425
669
  const body = { url };