odds-api-io 1.3.1 → 1.5.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.
Files changed (60) hide show
  1. package/README.md +325 -244
  2. package/dist/cjs/client.d.ts +278 -0
  3. package/dist/cjs/client.js +536 -292
  4. package/dist/cjs/client.js.map +1 -1
  5. package/dist/cjs/errors.d.ts +63 -0
  6. package/dist/cjs/errors.js +54 -36
  7. package/dist/cjs/errors.js.map +1 -1
  8. package/dist/cjs/helpers.d.ts +5 -0
  9. package/dist/cjs/helpers.js +13 -0
  10. package/dist/cjs/helpers.js.map +1 -0
  11. package/dist/cjs/index.d.ts +15 -0
  12. package/dist/cjs/index.js +15 -3
  13. package/dist/cjs/index.js.map +1 -1
  14. package/dist/cjs/package.json +1 -0
  15. package/dist/cjs/types.d.ts +770 -0
  16. package/dist/cjs/types.js +4 -1
  17. package/dist/cjs/types.js.map +1 -1
  18. package/dist/cjs/version.d.ts +1 -0
  19. package/dist/cjs/version.js +5 -0
  20. package/dist/cjs/version.js.map +1 -0
  21. package/dist/cjs/websocket.d.ts +210 -0
  22. package/dist/cjs/websocket.js +405 -0
  23. package/dist/cjs/websocket.js.map +1 -0
  24. package/dist/esm/client.d.ts +278 -0
  25. package/dist/esm/client.js +537 -293
  26. package/dist/esm/client.js.map +1 -1
  27. package/dist/esm/errors.d.ts +63 -0
  28. package/dist/esm/errors.js +49 -34
  29. package/dist/esm/errors.js.map +1 -1
  30. package/dist/esm/helpers.d.ts +5 -0
  31. package/dist/esm/helpers.js +9 -0
  32. package/dist/esm/helpers.js.map +1 -0
  33. package/dist/esm/index.d.ts +15 -0
  34. package/dist/esm/index.js +5 -2
  35. package/dist/esm/index.js.map +1 -1
  36. package/dist/esm/package.json +1 -0
  37. package/dist/esm/types.d.ts +770 -0
  38. package/dist/esm/types.js +4 -1
  39. package/dist/esm/types.js.map +1 -1
  40. package/dist/esm/version.d.ts +1 -0
  41. package/dist/esm/version.js +2 -0
  42. package/dist/esm/version.js.map +1 -0
  43. package/dist/esm/websocket.d.ts +210 -0
  44. package/dist/esm/websocket.js +367 -0
  45. package/dist/esm/websocket.js.map +1 -0
  46. package/dist/types/client.d.ts +155 -195
  47. package/dist/types/client.d.ts.map +1 -1
  48. package/dist/types/errors.d.ts +48 -24
  49. package/dist/types/errors.d.ts.map +1 -1
  50. package/dist/types/helpers.d.ts +6 -0
  51. package/dist/types/helpers.d.ts.map +1 -0
  52. package/dist/types/index.d.ts +8 -3
  53. package/dist/types/index.d.ts.map +1 -1
  54. package/dist/types/types.d.ts +659 -187
  55. package/dist/types/types.d.ts.map +1 -1
  56. package/dist/types/version.d.ts +2 -0
  57. package/dist/types/version.d.ts.map +1 -0
  58. package/dist/types/websocket.d.ts +211 -0
  59. package/dist/types/websocket.d.ts.map +1 -0
  60. package/package.json +46 -16
@@ -0,0 +1,278 @@
1
+ import type { OddsAPIClientConfig, RateLimitInfo, Sport, League, Event, HistoricalEvent, Participant, Bookmaker, SelectedBookmakers, MarketsResponse, MarketsBySport, EventOdds, HistoricalEventOdds, OddsMovement, UpdatedOddsResult, OddsSnapshot, EventSummary, ArbitrageBet, ValueBet, DroppingOddsEntry, DroppingOddsPage, SettlementsResponse, GradeSelection, GradesResponse, Outright, OutrightOdds, OutrightResults, Mapping, MappingsPage, GetLeaguesOptions, GetEventsParams, SearchEventsOptions, GetHistoricalEventsParams, SearchHistoricalEventsParams, GetOddsParams, GetMultiEventOddsParams, GetHistoricalOddsParams, GetClosingLinesParams, GetOddsMovementParams, GetUpdatedOddsSinceParams, PollUpdatedOddsParams, GetOddsSummaryParams, GetOddsSummaryMultiParams, GetParticipantsParams, GetArbitrageBetsParams, GetValueBetsParams, GetDroppingOddsParams, GetOutrightsParams, GetOutrightOddsParams, GetMappingsParams, PageOptions, CommaList } from './types.js';
2
+ /**
3
+ * Official Node.js client for Odds-API.io.
4
+ *
5
+ * @example
6
+ * ```typescript
7
+ * import { OddsAPIClient } from 'odds-api-io';
8
+ *
9
+ * const client = new OddsAPIClient({ apiKey: process.env.ODDS_API_KEY! });
10
+ * const sports = await client.getSports();
11
+ * ```
12
+ */
13
+ export declare class OddsAPIClient {
14
+ private readonly apiKey;
15
+ private readonly baseUrl;
16
+ private readonly timeout;
17
+ private readonly maxRetries;
18
+ private readonly maxRetryDelay;
19
+ private readonly fetchImpl?;
20
+ /** Rate-limit headers from the most recent response, when the server sent them. */
21
+ lastRateLimit?: RateLimitInfo;
22
+ constructor(config: OddsAPIClientConfig);
23
+ private buildUrl;
24
+ private send;
25
+ private backoff;
26
+ private retryDelay;
27
+ private toError;
28
+ private get;
29
+ /** All sports. No API key needed. */
30
+ getSports(): Promise<Sport[]>;
31
+ /**
32
+ * Leagues for a sport.
33
+ *
34
+ * @example
35
+ * ```typescript
36
+ * const leagues = await client.getLeagues('football');
37
+ * ```
38
+ */
39
+ getLeagues(sport: string, options?: GetLeaguesOptions): Promise<League[]>;
40
+ /**
41
+ * The market catalogue: exact market names per sport, with shape, period and
42
+ * whether each is served prematch and live. Use it before passing `markets`
43
+ * to other calls. No API key needed.
44
+ *
45
+ * @example
46
+ * ```typescript
47
+ * const { markets } = await client.getMarkets('football');
48
+ * ```
49
+ */
50
+ getMarkets(sport: string): Promise<MarketsResponse>;
51
+ getMarkets(): Promise<MarketsBySport>;
52
+ /**
53
+ * Events for a sport. Without `to` the window is the next 14 days; each
54
+ * response is capped at 5000 events (see `iterateEvents`).
55
+ *
56
+ * @example
57
+ * ```typescript
58
+ * const events = await client.getEvents({ sport: 'football', league: 'england-premier-league', status: 'pending,live' });
59
+ * ```
60
+ */
61
+ getEvents(params: GetEventsParams): Promise<Event[]>;
62
+ /**
63
+ * Every event matching the filters, paging with limit and skip.
64
+ *
65
+ * @example
66
+ * ```typescript
67
+ * for await (const event of client.iterateEvents({ sport: 'football', to: '2027-01-01T00:00:00Z' })) {
68
+ * console.log(event.home, event.away);
69
+ * }
70
+ * ```
71
+ */
72
+ iterateEvents(params: GetEventsParams, options?: PageOptions): AsyncGenerator<Event>;
73
+ /** One event by id. */
74
+ getEventById(eventId: string | number): Promise<Event>;
75
+ /** Live events, optionally for one sport. Live events carry `clock`. */
76
+ getLiveEvents(sport?: string): Promise<Event[]>;
77
+ /**
78
+ * Search events by team or league name (min 3 characters, up to 10 results).
79
+ *
80
+ * @example
81
+ * ```typescript
82
+ * const live = await client.searchEvents('Liverpool', { status: 'live' });
83
+ * ```
84
+ */
85
+ searchEvents(query: string, options?: SearchEventsOptions): Promise<Event[]>;
86
+ /**
87
+ * Finished events for one league. The span from `from` to `to` is at most 31
88
+ * days; use `iterateHistoricalEvents` for longer ranges.
89
+ */
90
+ getHistoricalEvents(params: GetHistoricalEventsParams): Promise<HistoricalEvent[]>;
91
+ /** Finished events for one league over any range, fetched in 31-day windows. */
92
+ iterateHistoricalEvents(params: GetHistoricalEventsParams): AsyncGenerator<HistoricalEvent>;
93
+ /** Search finished events by team name, across leagues (31-day span, default the last 31 days). */
94
+ searchHistoricalEvents(params: SearchHistoricalEventsParams): Promise<HistoricalEvent[]>;
95
+ /**
96
+ * Odds for a finished event, in the `/odds` shape.
97
+ *
98
+ * @example
99
+ * ```typescript
100
+ * const odds = await client.getHistoricalOdds({ eventId: 67697888, bookmakers: ['Bet365', 'SingBet'], markets: ['ML'] });
101
+ * ```
102
+ */
103
+ getHistoricalOdds(params: GetHistoricalOddsParams): Promise<HistoricalEventOdds>;
104
+ /**
105
+ * Closing odds for every settled event across up to 10 leagues (paid plans).
106
+ * Up to 366 days per call, 100 events per page (see `iterateClosingLines`).
107
+ *
108
+ * @example
109
+ * ```typescript
110
+ * const lines = await client.getClosingLines({
111
+ * sport: 'football',
112
+ * leagues: ['england-premier-league'],
113
+ * from: '2026-08-01T00:00:00Z',
114
+ * to: '2026-10-31T23:59:59Z',
115
+ * markets: ['ML', 'Totals'],
116
+ * bookmakers: ['Bet365'],
117
+ * });
118
+ * ```
119
+ */
120
+ getClosingLines(params: GetClosingLinesParams): Promise<HistoricalEventOdds[]>;
121
+ /** Every closing line matching the filters, paging with limit and skip. */
122
+ iterateClosingLines(params: GetClosingLinesParams, options?: PageOptions): AsyncGenerator<HistoricalEventOdds>;
123
+ /**
124
+ * Odds for one event. Pass `markets` to keep the response small.
125
+ *
126
+ * @example
127
+ * ```typescript
128
+ * const odds = await client.getEventOdds({ eventId: 62924717, bookmakers: ['Bet365', 'SingBet'], markets: ['ML', 'Totals'] });
129
+ * const ml = odds.bookmakers['Bet365']?.find((m) => m.name === 'ML');
130
+ * ```
131
+ */
132
+ getEventOdds(params: GetOddsParams): Promise<EventOdds>;
133
+ /** Odds for up to 10 events in one request. */
134
+ getOddsForMultipleEvents(params: GetMultiEventOddsParams): Promise<EventOdds[]>;
135
+ /**
136
+ * Odds for up to 10 events plus the WebSocket sequence at that moment.
137
+ * Rebuild state from `data`, then connect or reconnect with `lastSeq: seq`.
138
+ */
139
+ getOddsSnapshot(params: GetMultiEventOddsParams): Promise<OddsSnapshot>;
140
+ private multiOddsQuery;
141
+ /**
142
+ * Price history for one market at one bookmaker (prematch only).
143
+ *
144
+ * @example
145
+ * ```typescript
146
+ * const history = await client.getOddsMovement({ eventId: 62924717, bookmaker: 'Bet365', market: 'ML' });
147
+ * ```
148
+ */
149
+ getOddsMovement(params: GetOddsMovementParams): Promise<OddsMovement>;
150
+ /**
151
+ * Market groups changed since `since` for one bookmaker and sport. The result
152
+ * is a delta: merge it into what you hold, keyed by event and market.
153
+ * See `pollUpdatedOdds` for a loop that follows X-Next-Since.
154
+ */
155
+ getUpdatedOddsSince(params: GetUpdatedOddsSinceParams): Promise<EventOdds[]>;
156
+ /** Like `getUpdatedOddsSince`, plus the X-Next-Since, X-Server-Time and X-Unknown-Markets headers. */
157
+ getUpdatedOddsSinceWithMeta(params: GetUpdatedOddsSinceParams): Promise<UpdatedOddsResult>;
158
+ /**
159
+ * Polls `/odds/updated`, passing each X-Next-Since as the next `since`.
160
+ * A page cut short by `limit` is followed up at once.
161
+ *
162
+ * @example
163
+ * ```typescript
164
+ * const controller = new AbortController();
165
+ * for await (const batch of client.pollUpdatedOdds({ bookmaker: 'Bet365', sport: 'football', markets: ['ML'], signal: controller.signal })) {
166
+ * for (const event of batch.data) merge(event);
167
+ * }
168
+ * ```
169
+ */
170
+ pollUpdatedOdds(params: PollUpdatedOddsParams): AsyncGenerator<UpdatedOddsResult>;
171
+ /**
172
+ * Best, average, median, worst and fair price per market line across
173
+ * bookmakers (Growth plans and above; lower plans get `demo: true`).
174
+ */
175
+ getOddsSummary(params: GetOddsSummaryParams): Promise<EventSummary>;
176
+ /** `getOddsSummary` for up to 10 events in one request. */
177
+ getOddsSummaryMulti(params: GetOddsSummaryMultiParams): Promise<EventSummary[]>;
178
+ private summaryQuery;
179
+ /** Teams and players for a sport. */
180
+ getParticipants(params: GetParticipantsParams): Promise<Participant[]>;
181
+ /** One participant by id. */
182
+ getParticipantById(participantId: number | string): Promise<Participant>;
183
+ /**
184
+ * URL of a participant's PNG logo (use `homeId`/`awayId` from events).
185
+ * The URL carries your API key, so only hand it to a browser you trust;
186
+ * otherwise proxy it with `getParticipantLogo`.
187
+ */
188
+ getParticipantLogoUrl(participantId: number | string): string;
189
+ /** A participant's logo as PNG bytes. Throws NotFoundError when there is none. */
190
+ getParticipantLogo(participantId: number | string): Promise<ArrayBuffer>;
191
+ /** All bookmakers with their current status. No API key needed. */
192
+ getBookmakers(): Promise<Bookmaker[]>;
193
+ /** The bookmakers selected on your key. */
194
+ getSelectedBookmakers(): Promise<SelectedBookmakers>;
195
+ /** Add bookmakers to your selection. */
196
+ selectBookmakers(bookmakers: CommaList): Promise<SelectedBookmakers>;
197
+ /** Clear your selection. Allowed once every 12 hours. */
198
+ clearSelectedBookmakers(): Promise<SelectedBookmakers>;
199
+ /**
200
+ * Price gaps across your bookmakers where the best prices imply under 100%
201
+ * (prematch only, refreshed every few seconds). Prices move and limits
202
+ * apply, so check every leg before acting.
203
+ *
204
+ * @example
205
+ * ```typescript
206
+ * const arbs = await client.getArbitrageBets({ bookmakers: ['Bet365', 'SingBet'], sport: 'football', minProfit: 1 });
207
+ * ```
208
+ */
209
+ getArbitrageBets(params: GetArbitrageBetsParams): Promise<ArbitrageBet[]>;
210
+ /** Prices above a fair-odds estimate at one bookmaker. */
211
+ getValueBets(params: GetValueBetsParams): Promise<ValueBet[]>;
212
+ /**
213
+ * Dropping odds from sharp bookmakers (paid plans).
214
+ *
215
+ * @example
216
+ * ```typescript
217
+ * const drops = await client.getDroppingOdds({ sport: 'football', markets: ['ML'], minDrop: 10 });
218
+ * ```
219
+ */
220
+ getDroppingOdds(params?: GetDroppingOddsParams): Promise<DroppingOddsEntry[]>;
221
+ /** Like `getDroppingOdds`, plus the pagination headers. */
222
+ getDroppingOddsPage(params?: GetDroppingOddsParams): Promise<DroppingOddsPage>;
223
+ /** Every dropping-odds entry matching the filters, page by page. */
224
+ iterateDroppingOdds(params?: GetDroppingOddsParams, options?: PageOptions): AsyncGenerator<DroppingOddsEntry>;
225
+ /**
226
+ * Settlement records (status, final flag, final scores) for events (paid plans).
227
+ * More than 50 ids are split into several requests.
228
+ *
229
+ * @example
230
+ * ```typescript
231
+ * const { settlements, notFound } = await client.getSettlements([74919888, 73101436]);
232
+ * ```
233
+ */
234
+ getSettlements(eventIds: CommaList<string | number>): Promise<SettlementsResponse>;
235
+ /**
236
+ * Grade bet selections against final results (paid plans). Returns one grade
237
+ * per selection, in order. More than 50 selections are sent in batches.
238
+ * Re-send selections that are not `final`, at most once a minute.
239
+ *
240
+ * @example
241
+ * ```typescript
242
+ * const { grades } = await client.gradeBets([
243
+ * { ref: 'bet-1', eventId: 74919888, market: 'Spread', hdp: -0.75, side: 'home' },
244
+ * ]);
245
+ * ```
246
+ */
247
+ gradeBets(selections: GradeSelection[]): Promise<GradesResponse>;
248
+ /** Same as `gradeBets` (the API operation is called GradeSelections). */
249
+ gradeSelections(selections: GradeSelection[]): Promise<GradesResponse>;
250
+ /**
251
+ * Tournaments for a sport (golf today), sorted by date.
252
+ *
253
+ * @example
254
+ * ```typescript
255
+ * const tournaments = await client.getOutrights({ sport: 'golf', league: 'pga-tour' });
256
+ * ```
257
+ */
258
+ getOutrights(params: GetOutrightsParams): Promise<Outright[]>;
259
+ /**
260
+ * Prices for one tournament: Winner, Top 5/10/20, the "(Incl. Ties)"
261
+ * variants and Make Cut, per bookmaker.
262
+ *
263
+ * @example
264
+ * ```typescript
265
+ * const odds = await client.getOutrightOdds({ id: 1001, bookmakers: ['DraftKings', 'Betfair Exchange'] });
266
+ * ```
267
+ */
268
+ getOutrightOdds(params: GetOutrightOddsParams): Promise<OutrightOdds>;
269
+ /** Final positions and winners per market for one tournament. */
270
+ getOutrightResults(id: string | number): Promise<OutrightResults>;
271
+ /**
272
+ * A bookmaker's own event, market and outcome ids for our events (paid plans).
273
+ * Without eventId(s), marketId(s) or outcomeId it is a bulk sync with a cursor.
274
+ */
275
+ getMappings(params: GetMappingsParams): Promise<MappingsPage>;
276
+ /** Every mapping row, following `nextCursor` until it is null. */
277
+ iterateMappings(params: GetMappingsParams, options?: PageOptions): AsyncGenerator<Mapping>;
278
+ }