@ufcalendar/sdk 0.3.0 → 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 +44 -13
- package/dist/index.cjs +274 -30
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +10544 -782
- package/dist/index.d.ts +10544 -782
- package/dist/index.js +274 -30
- package/dist/index.js.map +1 -1
- package/package.json +4 -2
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,23 +47,53 @@ 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
|
-
| `
|
|
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
|
-
| `
|
|
62
|
-
| `
|
|
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
|
|
|
@@ -128,11 +158,12 @@ Every error throws `FightAPIError` with `.status`, `.code`, `.message` and `.req
|
|
|
128
158
|
|
|
129
159
|
## Notes
|
|
130
160
|
|
|
131
|
-
-
|
|
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)
|
|
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.
|
|
32
|
+
var VERSION = "0.6.0";
|
|
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
|
|
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",
|
|
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
|
-
/**
|
|
197
|
-
|
|
198
|
-
|
|
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
|
|
@@ -283,8 +351,36 @@ var FightAPI = class {
|
|
|
283
351
|
};
|
|
284
352
|
}
|
|
285
353
|
/* -------------------------------------------------------------- fights */
|
|
286
|
-
|
|
287
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
336
|
-
|
|
337
|
-
|
|
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
|
-
/**
|
|
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
|
|
348
|
-
|
|
349
|
-
|
|
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
|
-
/**
|
|
375
|
-
|
|
376
|
-
|
|
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(
|
|
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
|
-
/**
|
|
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
|
|
422
|
-
*
|
|
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 };
|