@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 +80 -14
- package/dist/index.cjs +355 -33
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +10584 -781
- package/dist/index.d.ts +10584 -781
- package/dist/index.js +354 -33
- package/dist/index.js.map +1 -1
- package/package.json +7 -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,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
|
-
| `
|
|
53
|
-
| `
|
|
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
|
-
| `
|
|
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
|
-
| `
|
|
61
|
-
| `
|
|
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
|
-
-
|
|
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)
|
|
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.
|
|
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
|
|
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",
|
|
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
|
-
/**
|
|
195
|
-
|
|
196
|
-
|
|
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
|
-
/**
|
|
203
|
-
*
|
|
204
|
-
*
|
|
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
|
-
|
|
210
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
259
|
-
|
|
260
|
-
|
|
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
|
-
/**
|
|
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
|
|
271
|
-
|
|
272
|
-
|
|
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
|
-
/**
|
|
298
|
-
|
|
299
|
-
|
|
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(
|
|
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
|
-
/**
|
|
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
|
|
345
|
-
*
|
|
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
|