skewtape 0.0.1 → 0.1.4

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 (95) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +182 -0
  3. package/dist/cjs/backtest.d.ts +146 -0
  4. package/dist/cjs/backtest.js +410 -0
  5. package/dist/cjs/client.d.ts +255 -0
  6. package/dist/cjs/client.js +447 -0
  7. package/dist/cjs/download.d.ts +33 -0
  8. package/dist/cjs/download.js +160 -0
  9. package/dist/cjs/errors.d.ts +76 -0
  10. package/dist/cjs/errors.js +159 -0
  11. package/dist/cjs/exact.d.ts +36 -0
  12. package/dist/cjs/exact.js +168 -0
  13. package/dist/cjs/fees.d.ts +68 -0
  14. package/dist/cjs/fees.js +196 -0
  15. package/dist/cjs/geoblock.d.ts +48 -0
  16. package/dist/cjs/geoblock.js +78 -0
  17. package/dist/cjs/index.d.ts +31 -0
  18. package/dist/cjs/index.js +98 -0
  19. package/dist/cjs/kalshi.d.ts +261 -0
  20. package/dist/cjs/kalshi.js +416 -0
  21. package/dist/cjs/keccak.d.ts +10 -0
  22. package/dist/cjs/keccak.js +84 -0
  23. package/dist/cjs/msgpack.d.ts +15 -0
  24. package/dist/cjs/msgpack.js +112 -0
  25. package/dist/cjs/package.json +1 -0
  26. package/dist/cjs/paginated.d.ts +26 -0
  27. package/dist/cjs/paginated.js +51 -0
  28. package/dist/cjs/quote-math.d.ts +146 -0
  29. package/dist/cjs/quote-math.js +446 -0
  30. package/dist/cjs/quote.d.ts +108 -0
  31. package/dist/cjs/quote.js +307 -0
  32. package/dist/cjs/route-hyperliquid.d.ts +228 -0
  33. package/dist/cjs/route-hyperliquid.js +387 -0
  34. package/dist/cjs/route.d.ts +297 -0
  35. package/dist/cjs/route.js +516 -0
  36. package/dist/cjs/stream.d.ts +99 -0
  37. package/dist/cjs/stream.js +529 -0
  38. package/dist/cjs/version.d.ts +6 -0
  39. package/dist/cjs/version.js +9 -0
  40. package/dist/esm/backtest.d.ts +146 -0
  41. package/dist/esm/backtest.js +403 -0
  42. package/dist/esm/client.d.ts +255 -0
  43. package/dist/esm/client.js +441 -0
  44. package/dist/esm/download.d.ts +33 -0
  45. package/dist/esm/download.js +155 -0
  46. package/dist/esm/errors.d.ts +76 -0
  47. package/dist/esm/errors.js +142 -0
  48. package/dist/esm/exact.d.ts +36 -0
  49. package/dist/esm/exact.js +158 -0
  50. package/dist/esm/fees.d.ts +68 -0
  51. package/dist/esm/fees.js +185 -0
  52. package/dist/esm/geoblock.d.ts +48 -0
  53. package/dist/esm/geoblock.js +74 -0
  54. package/dist/esm/index.d.ts +31 -0
  55. package/dist/esm/index.js +30 -0
  56. package/dist/esm/kalshi.d.ts +261 -0
  57. package/dist/esm/kalshi.js +404 -0
  58. package/dist/esm/keccak.d.ts +10 -0
  59. package/dist/esm/keccak.js +80 -0
  60. package/dist/esm/msgpack.d.ts +15 -0
  61. package/dist/esm/msgpack.js +109 -0
  62. package/dist/esm/paginated.d.ts +26 -0
  63. package/dist/esm/paginated.js +47 -0
  64. package/dist/esm/quote-math.d.ts +146 -0
  65. package/dist/esm/quote-math.js +437 -0
  66. package/dist/esm/quote.d.ts +108 -0
  67. package/dist/esm/quote.js +297 -0
  68. package/dist/esm/route-hyperliquid.d.ts +228 -0
  69. package/dist/esm/route-hyperliquid.js +376 -0
  70. package/dist/esm/route.d.ts +297 -0
  71. package/dist/esm/route.js +507 -0
  72. package/dist/esm/stream.d.ts +99 -0
  73. package/dist/esm/stream.js +524 -0
  74. package/dist/esm/version.d.ts +6 -0
  75. package/dist/esm/version.js +6 -0
  76. package/package.json +48 -1
  77. package/src/backtest.ts +490 -0
  78. package/src/client.ts +595 -0
  79. package/src/download.ts +161 -0
  80. package/src/errors.ts +143 -0
  81. package/src/exact.ts +159 -0
  82. package/src/fees.ts +189 -0
  83. package/src/generated/schema.d.ts +2500 -0
  84. package/src/geoblock.ts +90 -0
  85. package/src/index.ts +146 -0
  86. package/src/kalshi.ts +563 -0
  87. package/src/keccak.ts +82 -0
  88. package/src/msgpack.ts +83 -0
  89. package/src/paginated.ts +51 -0
  90. package/src/quote-math.ts +555 -0
  91. package/src/quote.ts +324 -0
  92. package/src/route-hyperliquid.ts +457 -0
  93. package/src/route.ts +631 -0
  94. package/src/stream.ts +539 -0
  95. package/src/version.ts +6 -0
@@ -0,0 +1,447 @@
1
+ "use strict";
2
+ /**
3
+ * The facade: sk.markets, sk.events (and sk.events.get), sk.pairs, sk.fills,
4
+ * sk.candles, sk.resolutions, sk.fees, sk.venues, sk.download and sk.quote
5
+ * (quote.ts), over the openapi-fetch client typed by the generated schema.
6
+ * Lists come back as a Paginated: iterate (for await) for every item across
7
+ * pages, .pages() for the pages themselves, .first() for the first item. A 429
8
+ * rate_limited is retried with the server's Retry-After; every other error, a
9
+ * quota_exceeded 429 included, is a SkewtapeError with the envelope's fields,
10
+ * thrown at once.
11
+ * sk.kalshi() is the optional live Kalshi client (./kalshi.ts), apart from
12
+ * the API. sk.route builds an unsigned order with the developer's own code
13
+ * (./route.ts) and sk.geoblock asks a venue's own geoblock check
14
+ * (./geoblock.ts); neither sends the API key.
15
+ */
16
+ Object.defineProperty(exports, "__esModule", { value: true });
17
+ exports.Skewtape = exports.ENV_API_KEY = exports.DEFAULT_BASE_URL = exports.Paginated = void 0;
18
+ exports.activeMembers = activeMembers;
19
+ const node_path_1 = require("node:path");
20
+ const openapi_fetch_1 = require("openapi-fetch");
21
+ const backtest_js_1 = require("./backtest.js");
22
+ const download_js_1 = require("./download.js");
23
+ const errors_js_1 = require("./errors.js");
24
+ const stream_js_1 = require("./stream.js");
25
+ const geoblock_js_1 = require("./geoblock.js");
26
+ const route_js_1 = require("./route.js");
27
+ const exact_js_1 = require("./exact.js");
28
+ const kalshi_js_1 = require("./kalshi.js");
29
+ const paginated_js_1 = require("./paginated.js");
30
+ const quote_js_1 = require("./quote.js");
31
+ const version_js_1 = require("./version.js");
32
+ var paginated_js_2 = require("./paginated.js");
33
+ Object.defineProperty(exports, "Paginated", { enumerable: true, get: function () { return paginated_js_2.Paginated; } });
34
+ exports.DEFAULT_BASE_URL = "https://api.skewtape.com";
35
+ exports.ENV_API_KEY = "SKEWTAPE_API_KEY";
36
+ /**
37
+ * The windows [t - lookback, t + 1 ms) up to each time (microseconds), as the
38
+ * API's exclusive to reads them: dateOf drops the microseconds, so the next
39
+ * millisecond keeps a row at t itself in. Overlapping ones merged.
40
+ */
41
+ function windows(times, lookback) {
42
+ const spans = times.map((t) => [t - lookback, t + 1000n]).sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
43
+ const merged = [];
44
+ for (const [start, end] of spans) {
45
+ const last = merged.at(-1);
46
+ if (last && start <= last[1])
47
+ last[1] = end > last[1] ? end : last[1];
48
+ else
49
+ merged.push([start, end]);
50
+ }
51
+ return merged;
52
+ }
53
+ function dateOf(micros) {
54
+ return new Date(Number(micros / 1000n));
55
+ }
56
+ function iso(v) {
57
+ return v instanceof Date ? v.toISOString() : v;
58
+ }
59
+ function defaultSleep(seconds) {
60
+ return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
61
+ }
62
+ /** How many of an event's members are active. */
63
+ function activeMembers(event) {
64
+ return event.members.filter((m) => m.status === "active").length;
65
+ }
66
+ /** The envelope's code in an openapi-fetch error body, when it is one. */
67
+ function envelopeCode(error) {
68
+ if (error === null || typeof error !== "object" || !("error" in error))
69
+ return undefined;
70
+ const e = error.error;
71
+ return e !== null && typeof e === "object" && typeof e.code === "string" ? e.code : undefined;
72
+ }
73
+ /** A fetch that gives up after timeout seconds, unless the caller brought its own abort handle. */
74
+ function withTimeout(fetchImpl, timeout) {
75
+ return (input, init) => fetchImpl(input, { ...init, signal: init?.signal ?? AbortSignal.timeout(timeout * 1000) });
76
+ }
77
+ class Skewtape {
78
+ baseUrl;
79
+ maxRetries;
80
+ timeout;
81
+ api;
82
+ sleep;
83
+ userSleep;
84
+ /** A private field: inspecting or logging the client does not show the key. */
85
+ #apiKey;
86
+ constructor(options = {}) {
87
+ const key = options.apiKey ?? process.env[exports.ENV_API_KEY] ?? "";
88
+ if (!key)
89
+ throw new errors_js_1.ConfigurationError(`no API key: pass apiKey or set ${exports.ENV_API_KEY}`);
90
+ if (options.maxRetries !== undefined && options.maxRetries < 0)
91
+ throw new errors_js_1.ConfigurationError("maxRetries must not be negative");
92
+ if (options.timeout !== undefined && !(options.timeout > 0))
93
+ throw new errors_js_1.ConfigurationError("timeout is seconds, above zero");
94
+ this.baseUrl = (options.baseUrl ?? exports.DEFAULT_BASE_URL).replace(/\/+$/, "");
95
+ this.#apiKey = key;
96
+ this.maxRetries = options.maxRetries ?? 3;
97
+ this.timeout = options.timeout ?? 30;
98
+ this.sleep = options.sleep ?? defaultSleep;
99
+ this.userSleep = options.sleep;
100
+ this.api = (0, openapi_fetch_1.default)({
101
+ baseUrl: this.baseUrl,
102
+ fetch: withTimeout(options.fetch ?? fetch, this.timeout),
103
+ headers: { "X-API-Key": key, "User-Agent": `skewtape-ts/${version_js_1.VERSION}` },
104
+ });
105
+ }
106
+ /**
107
+ * Run one request: a 429 whose envelope says rate_limited (or carries no
108
+ * envelope, as a proxy's would) retried up to maxRetries times after the
109
+ * server's Retry-After (one second without it); a 2xx returned as parsed;
110
+ * anything else, a quota_exceeded 429 included, thrown at once from the
111
+ * error envelope. A request past the timeout is a SkewtapeError.
112
+ */
113
+ async call(run) {
114
+ for (let attempt = 0;; attempt++) {
115
+ let result;
116
+ try {
117
+ result = await run();
118
+ }
119
+ catch (err) {
120
+ if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
121
+ throw new errors_js_1.SkewtapeError(`the request took longer than ${this.timeout} s`);
122
+ }
123
+ throw err;
124
+ }
125
+ const { data, error, response } = result;
126
+ if (response.ok) {
127
+ if (data === undefined)
128
+ throw new errors_js_1.SkewtapeError(`HTTP ${response.status} with no body the client knows`, { status: response.status });
129
+ return data;
130
+ }
131
+ const code = envelopeCode(error);
132
+ if (response.status === 429 && (code === "rate_limited" || code === undefined) && attempt < this.maxRetries) {
133
+ await this.sleep((0, errors_js_1.retryAfterSeconds)(response.headers) ?? 1);
134
+ continue;
135
+ }
136
+ throw (0, errors_js_1.errorFromResponse)(response.status, response.headers, error);
137
+ }
138
+ }
139
+ /** sk.markets({venue, resolved}) lists markets; sk.markets.get(venue, marketId) reads one. */
140
+ markets = Object.assign((options = {}) => new paginated_js_1.Paginated(async (cursor) => {
141
+ const query = {
142
+ venue: options.venue,
143
+ market_id: options.marketId,
144
+ updated_since: iso(options.updatedSince),
145
+ limit: options.limit ?? 100,
146
+ cursor,
147
+ };
148
+ const data = await this.call(() => this.api.GET("/v1/markets", { params: { query } }));
149
+ return { items: data.data, nextCursor: data.next_cursor ?? null };
150
+ }, options.resolved === undefined ? undefined : (m) => (m.status === "resolved") === options.resolved), {
151
+ get: (venue, marketId) => this.call(() => this.api.GET("/v1/markets/{venue}/{market_id}", { params: { path: { venue, market_id: marketId } } })),
152
+ });
153
+ /** sk.events({minConfidence, resolutionEqual}) lists matched events; sk.events.get(eventId) reads one. */
154
+ events = Object.assign((options = {}) => new paginated_js_1.Paginated(this.eventsPage(options)), {
155
+ get: (eventId) => this.call(() => this.api.GET("/v1/matched_events/{event_id}", { params: { path: { event_id: eventId } } })),
156
+ });
157
+ /** sk.pairs(...) is sk.events(...) kept to the pairs: a pair is a matched event with exactly two active members. sk.pairs.get refuses, as a 404 would, any other. */
158
+ pairs = Object.assign((options = {}) => new paginated_js_1.Paginated(this.eventsPage(options), (e) => activeMembers(e) === 2), {
159
+ get: async (eventId) => {
160
+ const event = await this.events.get(eventId);
161
+ const n = activeMembers(event);
162
+ if (n !== 2)
163
+ throw new errors_js_1.NotFoundError(`${eventId} is not a pair: ${n} active members`, { status: 404, code: "not_found" });
164
+ return event;
165
+ },
166
+ });
167
+ eventsPage(options) {
168
+ return async (cursor) => {
169
+ const query = {
170
+ min_confidence: options.minConfidence,
171
+ resolution_equal: options.resolutionEqual,
172
+ venue: options.venue,
173
+ status: options.status,
174
+ limit: options.limit ?? 100,
175
+ cursor,
176
+ };
177
+ const data = await this.call(() => this.api.GET("/v1/matched_events", { params: { query } }));
178
+ return { items: data.data, nextCursor: data.next_cursor ?? null };
179
+ };
180
+ }
181
+ /** sk.fills({eventId, since}) lists fills from since to until (now by default), maker legs by default. */
182
+ fills(options) {
183
+ const to = iso(options.until) ?? new Date().toISOString();
184
+ return new paginated_js_1.Paginated(async (cursor) => {
185
+ const query = {
186
+ venue: options.venue,
187
+ market_id: options.marketId,
188
+ event_id: options.eventId,
189
+ from: iso(options.since),
190
+ to,
191
+ leg: options.leg ?? "maker",
192
+ limit: options.limit ?? 100,
193
+ cursor,
194
+ };
195
+ const data = await this.call(() => this.api.GET("/v1/fills", { params: { query } }));
196
+ return { items: data.data, nextCursor: data.next_cursor ?? null };
197
+ });
198
+ }
199
+ /** sk.candles({res, since}) lists candles of one size from since to until. */
200
+ candles(options) {
201
+ const to = iso(options.until) ?? new Date().toISOString();
202
+ return new paginated_js_1.Paginated(async (cursor) => {
203
+ const query = {
204
+ venue: options.venue,
205
+ market_id: options.marketId,
206
+ event_id: options.eventId,
207
+ from: iso(options.since),
208
+ to,
209
+ res: options.res,
210
+ limit: options.limit ?? 100,
211
+ cursor,
212
+ };
213
+ const data = await this.call(() => this.api.GET("/v1/candles", { params: { query } }));
214
+ return { items: data.data, nextCursor: data.next_cursor ?? null };
215
+ });
216
+ }
217
+ /** sk.resolutions({venue, marketId, createdSince}) lists resolution events, of up to 100 markets when marketId is given. */
218
+ resolutions(options = {}) {
219
+ return new paginated_js_1.Paginated(async (cursor) => {
220
+ const query = {
221
+ venue: options.venue,
222
+ market_id: options.marketId,
223
+ created_since: iso(options.createdSince),
224
+ limit: options.limit ?? 100,
225
+ cursor,
226
+ };
227
+ const data = await this.call(() => this.api.GET("/v1/resolutions", { params: { query } }));
228
+ return { items: data.data, nextCursor: data.next_cursor ?? null };
229
+ });
230
+ }
231
+ /** sk.fees({venue}) lists the fee schedule rows. */
232
+ fees(options = {}) {
233
+ return new paginated_js_1.Paginated(async (cursor) => {
234
+ const query = { venue: options.venue, limit: options.limit ?? 100, cursor };
235
+ const data = await this.call(() => this.api.GET("/v1/fees", { params: { query } }));
236
+ return { items: data.data, nextCursor: data.next_cursor ?? null };
237
+ });
238
+ }
239
+ /** sk.venues() lists the venues with their rights and flags. */
240
+ async venues() {
241
+ const data = await this.call(() => this.api.GET("/v1/venues"));
242
+ return data.data;
243
+ }
244
+ /** sk.quoteContext(eventId) reads a matched event's quote context: its active members' tokens, outcome maps and fee rows (one metered data call). */
245
+ quoteContext(eventId) {
246
+ return this.call(() => this.api.GET("/v1/quote-context/{event_id}", { params: { path: { event_id: eventId } } }));
247
+ }
248
+ /**
249
+ * sk.quote(eventId, {outcome, side, size}) is the best venue, or split
250
+ * across venues, for size contracts of one outcome once each venue's taker
251
+ * fee is counted, in micro-units: the plan and its legs, every reachable
252
+ * venue alone, the members left out and why, and warnings (rule_mismatch,
253
+ * fee_unknown, partial). One call to Skewtape for the context; the books
254
+ * are read from each venue with a plain fetch that never carries the key.
255
+ * It places nothing. A rule mismatch throws RuleMismatchError unless
256
+ * allowRuleMismatch; no readable book throws VenueUnreachableError.
257
+ */
258
+ async quote(eventId, options) {
259
+ return (0, quote_js_1.quoteFromContext)(await this.quoteContext(eventId), options);
260
+ }
261
+ /**
262
+ * sk.backtest(trades, {asOf}) replays trades the caller supplies and gives
263
+ * their fee-aware P&L (runBacktest, which this feeds). It is arithmetic on
264
+ * history: it forecasts nothing, suggests no trade and optimises nothing.
265
+ * Unless passed in, it reads the fee rows of the trades' venues, their
266
+ * markets and those markets' resolution events (a request per 100
267
+ * markets), and the history window up to each trade without a price, and
268
+ * up to asOf for a market its resolutions do not settle by then, per
269
+ * market. A candle window starts a candle earlier, since a candle prices a
270
+ * time once it has ended. A backtest whose trades have prices and whose
271
+ * markets are settled reads no history. A window with no row at or before
272
+ * a trade's time is a BacktestError price_missing: widen lookbackSeconds
273
+ * or give the price.
274
+ */
275
+ async backtest(trades, options = {}) {
276
+ const history = options.history ?? "fills";
277
+ if (history !== "fills" && history !== "candles" && history !== "none")
278
+ throw new errors_js_1.ConfigurationError(`history is fills, candles or none, not ${String(history)}`);
279
+ const candleRes = options.candleRes ?? "1h";
280
+ if (candleRes !== "1m" && candleRes !== "1h" && candleRes !== "1d")
281
+ throw new errors_js_1.ConfigurationError(`candleRes is 1m, 1h or 1d, not ${String(candleRes)}`);
282
+ const list = [...trades];
283
+ const asOf = options.asOf ?? new Date();
284
+ const asOfMicros = (0, exact_js_1.parseMicros)(asOf, "asOf");
285
+ const lookback = BigInt(Math.round((options.lookbackSeconds ?? 86_400) * 1e6));
286
+ const byVenue = new Map();
287
+ for (const t of list) {
288
+ const ids = byVenue.get(t.venue) ?? [];
289
+ if (!ids.includes(t.market_id))
290
+ ids.push(t.market_id);
291
+ byVenue.set(t.venue, ids);
292
+ }
293
+ let fees = options.fees;
294
+ if (fees === undefined) {
295
+ const rows = [];
296
+ for (const venue of byVenue.keys())
297
+ rows.push(...(await this.fees({ venue }).toArray()));
298
+ fees = rows;
299
+ }
300
+ let markets = options.markets ? [...options.markets] : undefined;
301
+ if (markets === undefined) {
302
+ markets = [];
303
+ for (const [venue, ids] of byVenue) {
304
+ for (let start = 0; start < ids.length; start += 100) {
305
+ markets.push(...(await this.markets({ venue, marketId: ids.slice(start, start + 100) }).toArray()));
306
+ }
307
+ }
308
+ }
309
+ let resolutions = options.resolutions;
310
+ if (resolutions === undefined) {
311
+ const rows = [];
312
+ for (const [venue, ids] of byVenue) {
313
+ for (let start = 0; start < ids.length; start += 100) {
314
+ rows.push(...(await this.resolutions({ venue, marketId: ids.slice(start, start + 100), limit: 1000 }).toArray()));
315
+ }
316
+ }
317
+ resolutions = rows;
318
+ }
319
+ const resolutionRows = [...resolutions];
320
+ let fills = options.fills;
321
+ let candles = options.candles;
322
+ if (history !== "none" && (history === "fills" ? fills : candles) === undefined) {
323
+ const rows = [];
324
+ const bucket = history === "candles" ? backtest_js_1.CANDLE_MICROS[candleRes] : 0n;
325
+ for (const [venue, ids] of byVenue) {
326
+ for (const marketId of ids) {
327
+ const times = list
328
+ .filter((t) => t.venue === venue && t.market_id === marketId && (t.price === undefined || t.price === null) && (t.notional_raw === undefined || t.notional_raw === null))
329
+ .map((t) => (0, exact_js_1.parseMicros)(t.ts, "trade ts"));
330
+ const own = resolutionRows.filter((r) => r.venue === venue && r.market_id === marketId);
331
+ if (!(0, backtest_js_1.settledAt)(own, asOf))
332
+ times.push(asOfMicros);
333
+ for (const [since, until] of windows(times, lookback + bucket)) {
334
+ const page = history === "fills"
335
+ ? await this.fills({ venue, marketId, since: dateOf(since), until: dateOf(until) }).toArray()
336
+ : await this.candles({ res: candleRes, venue, marketId, since: dateOf(since), until: dateOf(until) }).toArray();
337
+ rows.push(...page);
338
+ }
339
+ }
340
+ }
341
+ if (history === "fills")
342
+ fills = rows;
343
+ else
344
+ candles = rows;
345
+ }
346
+ return (0, backtest_js_1.runBacktest)(list, {
347
+ asOf,
348
+ fees,
349
+ markets,
350
+ resolutions: resolutionRows,
351
+ fills: fills ?? [],
352
+ candles: candles ?? [],
353
+ prefer: history === "candles" ? "candles" : "fills",
354
+ ...(options.voidPayout !== undefined ? { voidPayout: options.voidPayout } : {}),
355
+ ...(options.onMissingFee !== undefined ? { onMissingFee: options.onMissingFee } : {}),
356
+ });
357
+ }
358
+ /**
359
+ * sk.stream({topics}) is the live feed (Builder and Pro), an async iterable
360
+ * of the server's messages that reconnects by itself: it resumes from the
361
+ * last seq it yielded, so nothing is missed or sent twice, and drops a
362
+ * trade it already yielded. venues, markets and events filter as the feed's
363
+ * subscribe does; resumeFrom starts from a seq kept earlier; maxReconnects
364
+ * bounds the failed connections in a row. It uses the platform's WebSocket;
365
+ * on Node 20 pass one (the ws package's): {WebSocket}.
366
+ */
367
+ stream(options) {
368
+ // The client's own sleep only when one was given (tests): the stream's
369
+ // default is a timer close() clears.
370
+ return new stream_js_1.Stream((0, stream_js_1.feedUrl)(this.baseUrl), this.#apiKey, options, this.userSleep);
371
+ }
372
+ /**
373
+ * sk.kalshi() is the optional live Kalshi client, under the user's own
374
+ * Kalshi membership ({accessKey, privateKey} sign its calls; without them
375
+ * they are public requests). It calls Kalshi's host from this machine and
376
+ * shares nothing with this client, not the API key: Skewtape's Kalshi data
377
+ * ships from sk.markets, sk.fills, sk.candles and sk.resolutions, under the
378
+ * Kalshi data licence; this is a reading of the live venue beside it.
379
+ */
380
+ kalshi(options = {}) {
381
+ return new kalshi_js_1.Kalshi(options);
382
+ }
383
+ /** sk.route: an unsigned order with your own code or fee (route.ts); it sends nothing, the API key included. */
384
+ route = route_js_1.route;
385
+ /** sk.geoblock: the venues' own checks (geoblock.ts); they never send the API key. */
386
+ geoblock = geoblock_js_1.geoblock;
387
+ /**
388
+ * The History snapshot and the monthly deltas, file by file, with an API key
389
+ * on the Builder or Pro plan (a History purchase downloads from the
390
+ * dashboard; a key on Free or History is a ForbiddenPlanError naming
391
+ * builder):
392
+ * - sk.download.bundles() lists the bundles the account may download, each
393
+ * with its files' paths, sizes and sha256 (GET /v1/bundles);
394
+ * - sk.download.url(bundle, path) is a file's link, valid for an hour and
395
+ * logged against the account (POST /v1/downloads/{bundle}/url);
396
+ * - sk.download.file(bundle, path, dest) fetches that link to dest, resuming
397
+ * a partial download and checking the sha256;
398
+ * - sk.download.bundle(bundle, folder) does that for every file, skipping
399
+ * those already there, then checks the folder against its
400
+ * CHECKSUMS.sha256;
401
+ * - sk.download(url, dest, {sha256}) fetches a link already in hand, such as
402
+ * one the dashboard gave, and sk.download.verify(folder) checks a folder.
403
+ * A link carries no key: files are fetched with a plain fetch (options.fetch
404
+ * to pass one), so the file host never sees the API key.
405
+ */
406
+ download = Object.assign((url, dest, options = {}) => (0, download_js_1.downloadFile)(url, dest, options), {
407
+ verify: (folder) => (0, download_js_1.verifyChecksums)(folder),
408
+ bundles: async () => (await this.call(() => this.api.GET("/v1/bundles"))).bundles,
409
+ url: (bundle, path) => this.call(() => this.api.POST("/v1/downloads/{bundle}/url", { params: { path: { bundle } }, body: { path } })),
410
+ file: async (bundle, path, dest, options = {}) => {
411
+ const sha256 = options.sha256 ?? (await this.bundleFile(bundle, path)).sha256;
412
+ if (await (0, download_js_1.holds)(dest, sha256))
413
+ return dest;
414
+ const link = await this.download.url(bundle, path);
415
+ return (0, download_js_1.downloadFile)(link.url, dest, { ...options, sha256 });
416
+ },
417
+ bundle: async (bundle, folder, options = {}) => {
418
+ const root = (0, node_path_1.resolve)(folder);
419
+ for (const f of (await this.findBundle(bundle)).files) {
420
+ const dest = (0, node_path_1.resolve)(root, f.path);
421
+ if (!dest.startsWith(root + node_path_1.sep))
422
+ throw new errors_js_1.SkewtapeError(`${bundle} lists ${f.path}, a path outside the folder`);
423
+ const progress = options.onProgress;
424
+ await this.download.file(bundle, f.path, dest, {
425
+ sha256: f.sha256,
426
+ fetch: options.fetch,
427
+ onProgress: progress && ((done, total) => progress(f.path, done, total)),
428
+ });
429
+ }
430
+ await (0, download_js_1.verifyChecksums)(root);
431
+ return root;
432
+ },
433
+ });
434
+ async findBundle(bundle) {
435
+ const found = (await this.download.bundles()).find((b) => b.id === bundle);
436
+ if (!found)
437
+ throw new errors_js_1.NotFoundError(`${bundle} is not among the bundles this account may download`, { status: 404 });
438
+ return found;
439
+ }
440
+ async bundleFile(bundle, path) {
441
+ const found = (await this.findBundle(bundle)).files.find((f) => f.path === path);
442
+ if (!found)
443
+ throw new errors_js_1.NotFoundError(`${bundle} lists no file ${path}`, { status: 404 });
444
+ return found;
445
+ }
446
+ }
447
+ exports.Skewtape = Skewtape;
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Files from a bundle: a download that resumes and checks its sha256, and the
3
+ * check of a whole folder against its CHECKSUMS.sha256. The History snapshot
4
+ * and the monthly deltas ship behind links that work for an hour: a Builder or
5
+ * Pro key asks for them (sk.download.file and sk.download.bundle, through POST
6
+ * /v1/downloads/{bundle}/url), and the dashboard hands them out too. This
7
+ * module takes the link itself.
8
+ */
9
+ export interface DownloadOptions {
10
+ /** The expected sha256 (hex); the file is checked after the download and a wrong one is deleted. */
11
+ sha256?: string | undefined;
12
+ /** Called after each chunk with the bytes so far and the total when known. */
13
+ onProgress?: ((done: number, total: number | undefined) => void) | undefined;
14
+ /** The fetch to use (the global one by default). The file host never sees the API key. */
15
+ fetch?: typeof fetch | undefined;
16
+ }
17
+ /** Whether dest already holds the file whose sha256 (hex) is given. */
18
+ export declare function holds(dest: string, sha256: string): Promise<boolean>;
19
+ /**
20
+ * Download url to dest, resuming a partial download (dest plus .part) with a
21
+ * Range request, and verify sha256 when given. A dest that exists with the
22
+ * expected sha256 is not downloaded again; a .part that already holds the
23
+ * whole file (the host answers 416 to the range) goes straight to the check.
24
+ * Returns dest.
25
+ */
26
+ export declare function downloadFile(url: string, dest: string, options?: DownloadOptions): Promise<string>;
27
+ /**
28
+ * Check every file a bundle's CHECKSUMS.sha256 lists ("<sha256> <path>", one
29
+ * per line). Returns the paths checked; throws ChecksumError on the first
30
+ * mismatch and SkewtapeError on a listed file that is missing or on a path
31
+ * that leaves the folder (absolute, or with a .. segment).
32
+ */
33
+ export declare function verifyChecksums(folder: string, checksums?: string): Promise<string[]>;
@@ -0,0 +1,160 @@
1
+ "use strict";
2
+ /**
3
+ * Files from a bundle: a download that resumes and checks its sha256, and the
4
+ * check of a whole folder against its CHECKSUMS.sha256. The History snapshot
5
+ * and the monthly deltas ship behind links that work for an hour: a Builder or
6
+ * Pro key asks for them (sk.download.file and sk.download.bundle, through POST
7
+ * /v1/downloads/{bundle}/url), and the dashboard hands them out too. This
8
+ * module takes the link itself.
9
+ */
10
+ Object.defineProperty(exports, "__esModule", { value: true });
11
+ exports.holds = holds;
12
+ exports.downloadFile = downloadFile;
13
+ exports.verifyChecksums = verifyChecksums;
14
+ const node_crypto_1 = require("node:crypto");
15
+ const node_fs_1 = require("node:fs");
16
+ const promises_1 = require("node:fs/promises");
17
+ const node_path_1 = require("node:path");
18
+ const node_stream_1 = require("node:stream");
19
+ const promises_2 = require("node:stream/promises");
20
+ const errors_js_1 = require("./errors.js");
21
+ async function sha256Of(path) {
22
+ const hash = (0, node_crypto_1.createHash)("sha256");
23
+ await (0, promises_2.pipeline)((0, node_fs_1.createReadStream)(path), hash);
24
+ return hash.digest("hex");
25
+ }
26
+ async function sizeOf(path) {
27
+ try {
28
+ return (await (0, promises_1.stat)(path)).size;
29
+ }
30
+ catch {
31
+ return 0;
32
+ }
33
+ }
34
+ // The file's size from a 416's Content-Range header, "bytes */N".
35
+ function unsatisfiedTotal(resp) {
36
+ const range = resp.headers.get("content-range") ?? "";
37
+ if (!range.startsWith("bytes */"))
38
+ return undefined;
39
+ const n = Number(range.slice("bytes */".length));
40
+ return Number.isFinite(n) ? n : undefined;
41
+ }
42
+ function totalSize(resp, have) {
43
+ const range = resp.headers.get("content-range");
44
+ if (range && range.includes("/")) {
45
+ const n = Number(range.slice(range.lastIndexOf("/") + 1));
46
+ return Number.isFinite(n) ? n : undefined;
47
+ }
48
+ const length = resp.headers.get("content-length");
49
+ if (length) {
50
+ const n = Number(length);
51
+ return Number.isFinite(n) ? have + n : undefined;
52
+ }
53
+ return undefined;
54
+ }
55
+ /** Whether dest already holds the file whose sha256 (hex) is given. */
56
+ async function holds(dest, sha256) {
57
+ return (await exists(dest)) && (await sha256Of(dest)) === sha256.toLowerCase();
58
+ }
59
+ /**
60
+ * Download url to dest, resuming a partial download (dest plus .part) with a
61
+ * Range request, and verify sha256 when given. A dest that exists with the
62
+ * expected sha256 is not downloaded again; a .part that already holds the
63
+ * whole file (the host answers 416 to the range) goes straight to the check.
64
+ * Returns dest.
65
+ */
66
+ async function downloadFile(url, dest, options = {}) {
67
+ const fetchFn = options.fetch ?? fetch;
68
+ const expected = options.sha256?.toLowerCase();
69
+ if (expected && (await sizeOf(dest)) > 0 && (await sha256Of(dest)) === expected)
70
+ return dest;
71
+ await (0, promises_1.mkdir)((0, node_path_1.dirname)(dest), { recursive: true });
72
+ const part = `${dest}.part`;
73
+ let have = await sizeOf(part);
74
+ for (let attempt = 0; attempt < 2; attempt++) {
75
+ const resp = await fetchFn(url, { headers: have ? { Range: `bytes=${have}-` } : {} });
76
+ if (have && resp.status === 416) {
77
+ // 416 on a resume: the .part is whole when the file's size (Content-Range: bytes */N)
78
+ // is what it holds; otherwise it is longer than the file or another file's, so start over.
79
+ await resp.body?.cancel();
80
+ if (unsatisfiedTotal(resp) === have)
81
+ break;
82
+ await (0, promises_1.unlink)(part).catch(() => undefined);
83
+ have = 0;
84
+ continue;
85
+ }
86
+ if (have && resp.status === 200)
87
+ have = 0; // the server ignored the range: start over
88
+ else if (have && resp.status !== 206)
89
+ throw new errors_js_1.SkewtapeError(`download ${url}: HTTP ${resp.status} on resume`, { status: resp.status });
90
+ else if (!have && resp.status !== 200)
91
+ throw new errors_js_1.SkewtapeError(`download ${url}: HTTP ${resp.status}`, { status: resp.status });
92
+ if (!resp.body)
93
+ throw new errors_js_1.SkewtapeError(`download ${url}: no body`, { status: resp.status });
94
+ const total = totalSize(resp, have);
95
+ let done = have;
96
+ const progress = options.onProgress;
97
+ const counted = node_stream_1.Readable.from(countChunks(resp.body, (n) => {
98
+ done += n;
99
+ progress?.(done, total);
100
+ }));
101
+ await (0, promises_2.pipeline)(counted, (0, node_fs_1.createWriteStream)(part, { flags: have ? "a" : "w" }));
102
+ break;
103
+ }
104
+ if (expected) {
105
+ const actual = await sha256Of(part);
106
+ if (actual !== expected) {
107
+ await (0, promises_1.unlink)(part).catch(() => undefined);
108
+ throw new errors_js_1.ChecksumError(dest, expected, actual);
109
+ }
110
+ }
111
+ await (0, promises_1.rename)(part, dest);
112
+ return dest;
113
+ }
114
+ async function* countChunks(body, onChunk) {
115
+ const reader = body.getReader();
116
+ for (;;) {
117
+ const { done, value } = await reader.read();
118
+ if (done)
119
+ return;
120
+ onChunk(value.byteLength);
121
+ yield value;
122
+ }
123
+ }
124
+ /**
125
+ * Check every file a bundle's CHECKSUMS.sha256 lists ("<sha256> <path>", one
126
+ * per line). Returns the paths checked; throws ChecksumError on the first
127
+ * mismatch and SkewtapeError on a listed file that is missing or on a path
128
+ * that leaves the folder (absolute, or with a .. segment).
129
+ */
130
+ async function verifyChecksums(folder, checksums = "CHECKSUMS.sha256") {
131
+ const text = await (0, promises_1.readFile)((0, node_path_1.join)(folder, checksums), "utf8");
132
+ const checked = [];
133
+ for (const raw of text.split("\n")) {
134
+ const line = raw.trim();
135
+ if (!line || line.startsWith("#"))
136
+ continue;
137
+ const space = line.indexOf(" ");
138
+ const digest = line.slice(0, space).toLowerCase();
139
+ const rel = line.slice(space + 1).trim().replace(/^\*/, "");
140
+ if ((0, node_path_1.isAbsolute)(rel) || rel.split(/[\\/]+/).includes(".."))
141
+ throw new errors_js_1.SkewtapeError(`${checksums} names ${rel}, a path outside the folder`);
142
+ const path = (0, node_path_1.join)(folder, rel);
143
+ if ((await sizeOf(path)) === 0 && !(await exists(path)))
144
+ throw new errors_js_1.SkewtapeError(`${path}: listed in ${checksums} and missing`);
145
+ const actual = await sha256Of(path);
146
+ if (actual !== digest)
147
+ throw new errors_js_1.ChecksumError(path, digest, actual);
148
+ checked.push(path);
149
+ }
150
+ return checked;
151
+ }
152
+ async function exists(path) {
153
+ try {
154
+ await (0, promises_1.stat)(path);
155
+ return true;
156
+ }
157
+ catch {
158
+ return false;
159
+ }
160
+ }