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
package/src/stream.ts ADDED
@@ -0,0 +1,539 @@
1
+ /**
2
+ * sk.stream: the live feed (GET /v1/feed, a WebSocket) as an async iterable
3
+ * that reconnects by itself (ADR-0013: the SDK handles reconnects). The
4
+ * Python client's sk.stream does the same, rule for rule.
5
+ *
6
+ * for await (const msg of sk.stream({ topics: ["trades"], venues: ["kalshi"] })) {
7
+ * if (msg.op === "event" && msg.kind === "trade") ...
8
+ * }
9
+ *
10
+ * It yields the server's messages of interest: every `event` (the feed's own
11
+ * `gap` notices included), `snapshot`, `resync`, and the `error`s that leave
12
+ * the connection running (a topic a plan change took away, a subscription
13
+ * replaced). It handles the rest: it sends the key as the first message (so
14
+ * a browser, which cannot set headers, works too), subscribes, and on a
15
+ * reconnect subscribes again with resume_from set to the last seq it
16
+ * yielded, or before any event the seq the first connection's hello or a
17
+ * close reason (resume_from=N) gave, so a quiet stream misses nothing; it
18
+ * reconnects on the codes the feed says to reconnect on, at once on a
19
+ * `reconnect` notice, and after a wait that doubles from 1 s to 30 s, with
20
+ * jitter, when a connection fails; it pings every heartbeat_seconds and
21
+ * reconnects when nothing comes back for two of them; it drops a trade it
22
+ * already yielded, by (venue, tx_hash, log_index), and in a trades_batch the
23
+ * fills already yielded, and forgets a trade's identity on its
24
+ * trade_withdrawn; it leaves a topic a plan change took away out of the next
25
+ * subscription; it throws on what reconnecting cannot fix (a bad key, a plan
26
+ * without the feed or the topic, the connection limit on a first connection
27
+ * or for two minutes on a reconnect, a refused subscription, a message the
28
+ * server could not read). It holds at most MAX_BUFFERED messages the loop
29
+ * has not taken: past that it reconnects from the last seq yielded, as the
30
+ * server's slow-reader close would. The key is a private field: inspecting
31
+ * or logging the stream does not show it.
32
+ *
33
+ * It uses the platform's WebSocket (browsers, Node 22 and later, Deno, Bun);
34
+ * on Node 20 pass one, for example the ws package's: sk.stream({ ..., WebSocket }).
35
+ */
36
+ import {
37
+ AuthenticationError,
38
+ BlockedError,
39
+ ConfigurationError,
40
+ ForbiddenPlanError,
41
+ InvalidRequestError,
42
+ SkewtapeError,
43
+ } from "./errors.js";
44
+
45
+ export const FEED_PATH = "/v1/feed";
46
+
47
+ /** A server message, as docs/public/feed.md gives it. */
48
+ export type FeedMessage = { op: string; [field: string]: unknown };
49
+
50
+ /**
51
+ * What the stream needs of a WebSocket: the WHATWG interface. The handlers'
52
+ * events are typed loosely so the platform's WebSocket and the ws package's
53
+ * both fit as they are; the stream reads data, code and reason alone.
54
+ */
55
+ export interface FeedSocket {
56
+ send(data: string): void;
57
+ close(code?: number, reason?: string): void;
58
+ /* eslint-disable @typescript-eslint/no-explicit-any */
59
+ onopen: ((ev: any) => void) | null;
60
+ onmessage: ((ev: any) => void) | null;
61
+ onclose: ((ev: any) => void) | null;
62
+ onerror: ((ev: any) => void) | null;
63
+ /* eslint-enable @typescript-eslint/no-explicit-any */
64
+ }
65
+
66
+ export type FeedSocketConstructor = new (url: string) => FeedSocket;
67
+
68
+ export interface StreamOptions {
69
+ topics: string[];
70
+ venues?: string[];
71
+ markets?: { venue: string; market_id: string }[];
72
+ events?: string[];
73
+ /** A seq kept earlier: the feed replays the events after it. */
74
+ resumeFrom?: number;
75
+ /** Failed connections in a row before the stream gives up; none by default. */
76
+ maxReconnects?: number;
77
+ /** A WebSocket constructor, where the platform has none (Node 20). */
78
+ WebSocket?: FeedSocketConstructor;
79
+ }
80
+
81
+ /** Close codes reconnecting cannot fix; every other end reconnects. */
82
+ const FATAL_CLOSES: Record<number, new (message: string, fields?: { code?: string }) => SkewtapeError> = {
83
+ 4001: AuthenticationError,
84
+ 4003: ForbiddenPlanError,
85
+ 4008: ForbiddenPlanError,
86
+ 4029: AuthenticationError,
87
+ 4400: InvalidRequestError,
88
+ 1009: InvalidRequestError,
89
+ };
90
+
91
+ /** Error codes that end the stream: the subscription cannot run as it is. */
92
+ const FATAL_ERRORS: Record<string, new (message: string, fields?: { code?: string; docsUrl?: string; upgradeUrl?: string }) => SkewtapeError> = {
93
+ unauthorized: AuthenticationError,
94
+ lookup_rate_limited: AuthenticationError,
95
+ plan_no_feed: ForbiddenPlanError,
96
+ connection_limit: ForbiddenPlanError,
97
+ venue_blocked: BlockedError,
98
+ invalid_subscription: InvalidRequestError,
99
+ unknown_op: InvalidRequestError,
100
+ bad_message: InvalidRequestError,
101
+ };
102
+ /**
103
+ * Error codes that end the stream when they answer a connection's first
104
+ * subscribe: nothing runs on it. topic_not_in_plan later is a topic a plan
105
+ * change took away, and the others go on.
106
+ */
107
+ const FIRST_SUBSCRIBE_FATAL: Record<string, new (message: string, fields?: { code?: string; docsUrl?: string; upgradeUrl?: string }) => SkewtapeError> = {
108
+ topic_not_in_plan: ForbiddenPlanError,
109
+ unknown_plan: ForbiddenPlanError,
110
+ unknown_topic: InvalidRequestError,
111
+ };
112
+ const RECONNECT_ERRORS = new Set(["slow_consumer", "connection_expired", "internal"]);
113
+
114
+ const BACKOFF_FIRST = 1;
115
+ const BACKOFF_MAX = 30;
116
+ /** How long a reconnect refused for the connection limit is tried again (s): a moved connection can count for 90 s. */
117
+ const LIMIT_RETRY = 120;
118
+ /** The heartbeat when hello gives none (s). */
119
+ const HEARTBEAT_DEFAULT = 30;
120
+ /** Messages received and not yet taken by the loop, at most. */
121
+ export const MAX_BUFFERED = 10_000;
122
+ /** How many trade identities are remembered. */
123
+ export const DEDUPE_TRADES = 100_000;
124
+
125
+ /** The feed's WebSocket URL for an API base URL: https to wss, http to ws. */
126
+ export function feedUrl(baseUrl: string): string {
127
+ const base = baseUrl.replace(/\/+$/, "");
128
+ if (base.startsWith("https://")) return "wss://" + base.slice("https://".length) + FEED_PATH;
129
+ if (base.startsWith("http://")) return "ws://" + base.slice("http://".length) + FEED_PATH;
130
+ throw new ConfigurationError(`baseUrl ${JSON.stringify(baseUrl)} is not http or https`);
131
+ }
132
+
133
+ type Item =
134
+ | { kind: "message"; msg: FeedMessage }
135
+ | { kind: "unreadable"; text: string }
136
+ | { kind: "close"; code: number; reason: string }
137
+ | { kind: "open" }
138
+ | { kind: "stale" }
139
+ | { kind: "overflow" };
140
+
141
+ class Reconnect {
142
+ constructor(
143
+ readonly atOnce: boolean,
144
+ readonly cause?: unknown,
145
+ ) {}
146
+ }
147
+
148
+ /** One subscription to the live feed, across as many connections as it takes. */
149
+ export class Stream implements AsyncIterable<FeedMessage> {
150
+ /** The seq of the last event yielded, or the resumeFrom given. */
151
+ lastSeq: number | undefined;
152
+ hello: FeedMessage | undefined;
153
+ subscribed: FeedMessage | undefined;
154
+ readonly #apiKey: string;
155
+ private readonly subscription: Record<string, unknown> & { topics: string[] };
156
+ private readonly seen = new Map<string, true>();
157
+ private socket: FeedSocket | undefined;
158
+ private closed = false;
159
+ private wake: (() => void) | undefined;
160
+ /** Where to resume when no event was yielded since: the first hello's seq, raised by a close reason's or a resync's. */
161
+ private floor: number | undefined;
162
+ private failures = 0;
163
+ /** A connection of this stream was subscribed once: a connection limit after it may be its own moved connection. */
164
+ private worked = false;
165
+ private limitedSince: number | undefined;
166
+ private readonly closedSignal: Promise<void>;
167
+ /** Ends the timer of a wait in progress (pause), at once. */
168
+ private endPause: (() => void) | undefined;
169
+ private signalClosed: () => void = () => undefined;
170
+
171
+ constructor(
172
+ readonly url: string,
173
+ apiKey: string,
174
+ options: StreamOptions,
175
+ /** A sleep for tests; none is a timer close() clears. */
176
+ private readonly sleep?: (seconds: number) => Promise<void>,
177
+ private readonly jitter: () => number = Math.random,
178
+ private readonly now: () => number = Date.now,
179
+ ) {
180
+ this.#apiKey = apiKey;
181
+ this.closedSignal = new Promise((r) => (this.signalClosed = r));
182
+ if (!options.topics?.length) throw new ConfigurationError("sk.stream needs at least one topic");
183
+ if (options.maxReconnects !== undefined && options.maxReconnects < 0) throw new ConfigurationError("maxReconnects must not be negative");
184
+ const WS = options.WebSocket ?? (globalThis as { WebSocket?: FeedSocketConstructor }).WebSocket;
185
+ if (!WS) throw new ConfigurationError("this platform has no WebSocket: pass one, sk.stream({ ..., WebSocket })");
186
+ this.WS = WS;
187
+ this.maxReconnects = options.maxReconnects;
188
+ this.subscription = { op: "subscribe", topics: [...options.topics] };
189
+ if (options.venues?.length) this.subscription.venues = [...options.venues];
190
+ if (options.markets?.length) this.subscription.markets = options.markets.map((m) => ({ ...m }));
191
+ if (options.events?.length) this.subscription.events = [...options.events];
192
+ this.lastSeq = options.resumeFrom;
193
+ }
194
+
195
+ private readonly WS: FeedSocketConstructor;
196
+ private readonly maxReconnects: number | undefined;
197
+
198
+ /** Ends the stream: the connection closes, a wait ends, and iteration stops. */
199
+ close(): void {
200
+ this.closed = true;
201
+ this.socket?.close(1000, "closed by the client");
202
+ this.wake?.();
203
+ this.endPause?.();
204
+ this.signalClosed();
205
+ }
206
+
207
+ async *[Symbol.asyncIterator](): AsyncIterator<FeedMessage> {
208
+ let reason = "closed by the client";
209
+ try {
210
+ while (!this.closed) {
211
+ const items: Item[] = [];
212
+ const socket = new this.WS(this.url);
213
+ this.socket = socket;
214
+ let lastHeard = Date.now(); // the heartbeat runs on real timers, so on the real clock
215
+ let beat: ReturnType<typeof setInterval> | undefined;
216
+ socket.onopen = () => this.push(items, { kind: "open" });
217
+ socket.onmessage = (ev: { data: unknown }) => {
218
+ lastHeard = Date.now();
219
+ if (items.length >= MAX_BUFFERED) {
220
+ // The loop fell behind: stop reading, hand it what is held, then
221
+ // reconnect from the last seq yielded.
222
+ socket.onmessage = null;
223
+ this.push(items, { kind: "overflow" });
224
+ return;
225
+ }
226
+ const text = typeof ev.data === "string" ? ev.data : String(ev.data);
227
+ const msg = parse(text);
228
+ if (msg?.op === "hello" && beat === undefined) {
229
+ const every = typeof msg.heartbeat_seconds === "number" && msg.heartbeat_seconds > 0 ? msg.heartbeat_seconds : HEARTBEAT_DEFAULT;
230
+ // A ping every heartbeat; a socket silent for two is dead, even
231
+ // with no close event (a sleep, a NAT timeout).
232
+ beat = setInterval(() => {
233
+ if (Date.now() - lastHeard > 2 * every * 1000) {
234
+ this.push(items, { kind: "stale" });
235
+ return;
236
+ }
237
+ try {
238
+ socket.send(JSON.stringify({ op: "ping" }));
239
+ } catch {
240
+ // closing: its close event follows
241
+ }
242
+ }, every * 1000);
243
+ }
244
+ this.push(items, msg ? { kind: "message", msg } : { kind: "unreadable", text });
245
+ };
246
+ socket.onclose = (ev: { code: number; reason: string }) => this.push(items, { kind: "close", code: ev.code, reason: String(ev.reason) });
247
+ socket.onerror = () => undefined; // the close that follows says what happened
248
+ try {
249
+ for await (const msg of this.session(socket, items)) {
250
+ if (this.closed) return;
251
+ // Data ends a run of failures; a refusal told to the caller (replay_limited) does not.
252
+ if (msg.op !== "error") this.failures = 0;
253
+ yield msg;
254
+ }
255
+ return; // closed by the client
256
+ } catch (err) {
257
+ if (!(err instanceof Reconnect)) {
258
+ reason = "the stream ended";
259
+ throw err;
260
+ }
261
+ if (!err.atOnce) await this.wait(err.cause);
262
+ } finally {
263
+ if (beat !== undefined) clearInterval(beat);
264
+ socket.onopen = socket.onmessage = socket.onclose = null;
265
+ try {
266
+ socket.close(1000, this.closed ? "closed by the client" : reason === "the stream ended" ? reason : "reconnecting");
267
+ } catch {
268
+ // already closed
269
+ }
270
+ this.socket = undefined;
271
+ }
272
+ }
273
+ } finally {
274
+ this.closed = true;
275
+ this.signalClosed();
276
+ }
277
+ }
278
+
279
+ /**
280
+ * Waits seconds, or less when close() runs. With no sleep given, the wait
281
+ * is a timer close() clears, so a closed stream keeps no timer pending
282
+ * and the process can exit.
283
+ */
284
+ private async pause(seconds: number): Promise<void> {
285
+ if (this.sleep !== undefined) {
286
+ await Promise.race([this.sleep(seconds), this.closedSignal]);
287
+ return;
288
+ }
289
+ if (this.closed) return;
290
+ await new Promise<void>((resolve) => {
291
+ const timer = setTimeout(done, seconds * 1000);
292
+ function done(): void {
293
+ clearTimeout(timer);
294
+ resolve();
295
+ }
296
+ this.endPause = done;
297
+ });
298
+ this.endPause = undefined;
299
+ }
300
+
301
+ private push(items: Item[], item: Item): void {
302
+ items.push(item);
303
+ this.wake?.();
304
+ }
305
+
306
+ private async next(items: Item[]): Promise<Item | undefined> {
307
+ while (items.length === 0) {
308
+ if (this.closed) return undefined;
309
+ await new Promise<void>((resolve) => (this.wake = resolve));
310
+ this.wake = undefined;
311
+ }
312
+ return items.shift();
313
+ }
314
+
315
+ private async wait(cause: unknown): Promise<void> {
316
+ this.failures += 1;
317
+ const failures = this.failures;
318
+ if (this.maxReconnects !== undefined && failures > this.maxReconnects) {
319
+ throw new SkewtapeError(`the live feed did not answer after ${failures} tries: ${String(cause)}`);
320
+ }
321
+ const delay = Math.min(BACKOFF_FIRST * 2 ** (failures - 1), BACKOFF_MAX);
322
+ await this.pause(delay * (0.5 + 0.5 * this.jitter()));
323
+ }
324
+
325
+ /**
326
+ * Where the stream would resume: the last seq yielded, or its position
327
+ * before its first event or past a resync, the later of the two. Keep
328
+ * this one, not lastSeq, to go on later with sk.stream({ ..., resumeFrom }).
329
+ */
330
+ get resumeFrom(): number | undefined {
331
+ if (this.lastSeq === undefined) return this.floor;
332
+ if (this.floor === undefined) return this.lastSeq;
333
+ return Math.max(this.lastSeq, this.floor);
334
+ }
335
+
336
+ private raiseFloor(seq: number): void {
337
+ if (this.floor === undefined || seq > this.floor) this.floor = seq;
338
+ }
339
+
340
+ /** Whether a connection limit is tried again: on a reconnect, for LIMIT_RETRY after the first refusal. */
341
+ private limitRetry(): boolean {
342
+ if (!this.worked) return false;
343
+ const now = this.now();
344
+ if (this.limitedSince === undefined) this.limitedSince = now;
345
+ return now - this.limitedSince < LIMIT_RETRY * 1000;
346
+ }
347
+
348
+ private sendSubscribe(socket: FeedSocket): void {
349
+ const msg: Record<string, unknown> = { ...this.subscription };
350
+ const resume = this.resumeFrom;
351
+ if (resume !== undefined) msg.resume_from = resume;
352
+ socket.send(JSON.stringify(msg));
353
+ }
354
+
355
+ private async *session(socket: FeedSocket, items: Item[]): AsyncGenerator<FeedMessage> {
356
+ let subscribed = false;
357
+ let sent = false;
358
+ for (;;) {
359
+ const item = await this.next(items);
360
+ if (item === undefined || this.closed) return; // closed by the client: lastSeq stays the last event yielded
361
+ if (item.kind === "open") {
362
+ socket.send(JSON.stringify({ op: "auth", key: this.#apiKey }));
363
+ continue;
364
+ }
365
+ if (item.kind === "stale") throw new Reconnect(false, "no message for two heartbeats");
366
+ if (item.kind === "overflow") throw new Reconnect(false, `more than ${MAX_BUFFERED} messages not yet read`);
367
+ if (item.kind === "unreadable") {
368
+ throw new SkewtapeError(`the live feed sent a message this client cannot read: ${item.text.slice(0, 200)}`);
369
+ }
370
+ if (item.kind === "close") {
371
+ if (this.closed) return;
372
+ // A close reason's seq is this connection's position: trusted only
373
+ // once its subscription ran (a refused or unread subscribe leaves it
374
+ // at the hello's head, past events never delivered).
375
+ const resume = /resume_from=(\d+)/.exec(item.reason);
376
+ if (resume && subscribed) this.raiseFloor(Number(resume[1]));
377
+ if (item.code === 4008 && this.limitRetry()) throw new Reconnect(false, `closed with 4008 ${item.reason}`);
378
+ const cls = FATAL_CLOSES[item.code];
379
+ if (cls) throw new cls(`the live feed closed the connection (${item.code}): ${item.reason}`, { code: String(item.code) });
380
+ throw new Reconnect(false, `closed with ${item.code} ${item.reason}`);
381
+ }
382
+ const msg = item.msg;
383
+ switch (msg.op) {
384
+ case "hello":
385
+ this.hello = msg;
386
+ if (!sent) {
387
+ this.sendSubscribe(socket);
388
+ sent = true;
389
+ }
390
+ // The first connection subscribes from now; a later one, before any event, from this seq.
391
+ if (this.lastSeq === undefined && this.floor === undefined && typeof msg.seq === "number") this.floor = msg.seq;
392
+ break;
393
+ case "subscribed":
394
+ subscribed = true;
395
+ this.subscribed = msg;
396
+ // A connection that works ends a run of failures.
397
+ this.failures = 0;
398
+ this.worked = true;
399
+ this.limitedSince = undefined;
400
+ break;
401
+ case "event": {
402
+ const out = this.event(msg);
403
+ if (out) yield out;
404
+ break;
405
+ }
406
+ case "snapshot":
407
+ yield msg;
408
+ break;
409
+ case "resync":
410
+ // What came before head cannot be replayed: resume past it.
411
+ if (typeof msg.head === "number") this.raiseFloor(msg.head);
412
+ yield msg;
413
+ break;
414
+ case "reconnect": {
415
+ // The notice's seq is this connection's position: trusted only once its subscription ran.
416
+ const resume = msg.resume_from;
417
+ if (subscribed && typeof resume === "number") this.raiseFloor(resume);
418
+ throw new Reconnect(true);
419
+ }
420
+ case "error": {
421
+ const code = typeof msg.code === "string" ? msg.code : "";
422
+ const text = typeof msg.message === "string" ? msg.message : code;
423
+ if (code === "connection_limit" && this.limitRetry()) throw new Reconnect(false, text);
424
+ const firstFatal = subscribed ? undefined : FIRST_SUBSCRIBE_FATAL[code];
425
+ if (FATAL_ERRORS[code] || firstFatal) {
426
+ const cls = FATAL_ERRORS[code] ?? firstFatal ?? ForbiddenPlanError;
427
+ throw new cls(text, { code, docsUrl: str(msg.docs_url), upgradeUrl: str(msg.upgrade_url) });
428
+ }
429
+ if (code === "replay_limited") {
430
+ // Told before the wait, which can last most of an hour: the
431
+ // message names it. Refusals in a row count toward maxReconnects.
432
+ yield msg;
433
+ this.failures += 1;
434
+ if (this.maxReconnects !== undefined && this.failures > this.maxReconnects) {
435
+ throw new SkewtapeError(`the live feed refused ${this.failures} replays in a row: ${text}`, { code });
436
+ }
437
+ const wait = /in (\d+) seconds/.exec(text);
438
+ await this.pause(wait ? Number(wait[1]) : BACKOFF_FIRST);
439
+ if (this.closed) return;
440
+ this.sendSubscribe(socket);
441
+ break;
442
+ }
443
+ if (code === "not_ready") {
444
+ // No wait is named: the failure backoff, with jitter, so a new
445
+ // instance's clients do not come back in lockstep.
446
+ await this.wait(text);
447
+ if (this.closed) return;
448
+ this.sendSubscribe(socket);
449
+ break;
450
+ }
451
+ if (RECONNECT_ERRORS.has(code)) throw new Reconnect(false, text);
452
+ if (code === "topic_not_in_plan") {
453
+ // The server dropped the topic and kept the others: the next connection subscribes without it.
454
+ const lost = /^topic (\w+) needs/.exec(text)?.[1];
455
+ const topics = this.subscription.topics;
456
+ if (lost !== undefined && topics.includes(lost) && topics.length > 1) this.subscription.topics = topics.filter((t) => t !== lost);
457
+ }
458
+ // superseded, a topic a plan change took away, and codes this
459
+ // version does not know: the connection goes on, and the caller is told.
460
+ yield msg;
461
+ break;
462
+ }
463
+ default:
464
+ break; // pong, and messages this version does not know
465
+ }
466
+ }
467
+ }
468
+
469
+ private event(msg: FeedMessage): FeedMessage | undefined {
470
+ const seq = msg.seq;
471
+ if (typeof seq === "number") {
472
+ if (this.lastSeq !== undefined && seq <= this.lastSeq) return undefined;
473
+ this.lastSeq = seq;
474
+ }
475
+ const payload = msg.payload;
476
+ if (payload === null || typeof payload !== "object") return msg;
477
+ const row = payload as Record<string, unknown>;
478
+ const venue = str(msg.venue) ?? str(row.venue) ?? "";
479
+ switch (msg.kind) {
480
+ case "trade": {
481
+ const key = identity(venue, row);
482
+ if (key === undefined) return msg;
483
+ if (this.seen.has(key)) return undefined;
484
+ this.remember(key);
485
+ return msg;
486
+ }
487
+ case "trades_batch": {
488
+ const fills = row.fills;
489
+ if (!Array.isArray(fills)) return msg;
490
+ const fresh = fills.filter((f) => {
491
+ const key = f !== null && typeof f === "object" ? identity(venue, f as Record<string, unknown>) : undefined;
492
+ if (key === undefined) return true;
493
+ if (this.seen.has(key)) return false;
494
+ this.remember(key);
495
+ return true;
496
+ });
497
+ if (fresh.length === 0) return undefined;
498
+ if (fresh.length === fills.length) return msg;
499
+ return { ...msg, payload: { ...row, fills: fresh, count: fresh.length } };
500
+ }
501
+ case "trade_withdrawn": {
502
+ const key = identity(venue, row);
503
+ if (key !== undefined) this.seen.delete(key);
504
+ return msg;
505
+ }
506
+ default:
507
+ return msg;
508
+ }
509
+ }
510
+
511
+ private remember(key: string): void {
512
+ this.seen.set(key, true);
513
+ if (this.seen.size > DEDUPE_TRADES) {
514
+ const oldest = this.seen.keys().next().value;
515
+ if (oldest !== undefined) this.seen.delete(oldest);
516
+ }
517
+ }
518
+ }
519
+
520
+ function parse(text: string): FeedMessage | undefined {
521
+ try {
522
+ const v = JSON.parse(text) as unknown;
523
+ if (v !== null && typeof v === "object" && typeof (v as { op?: unknown }).op === "string") return v as FeedMessage;
524
+ } catch {
525
+ // unreadable: the caller says so
526
+ }
527
+ return undefined;
528
+ }
529
+
530
+ function identity(venue: string, row: Record<string, unknown>): string | undefined {
531
+ const tx = row.tx_hash;
532
+ const index = row.log_index;
533
+ if (typeof tx !== "string" || typeof index !== "number") return undefined;
534
+ return `${str(row.venue) ?? venue}|${tx.toLowerCase()}|${index}`;
535
+ }
536
+
537
+ function str(v: unknown): string | undefined {
538
+ return typeof v === "string" ? v : undefined;
539
+ }
package/src/version.ts ADDED
@@ -0,0 +1,6 @@
1
+ /**
2
+ * The package version: major and minor follow the API's info.version, the
3
+ * patch is this package's own (ADR-0015). release-sdks.yml sets package.json
4
+ * from the api/vX.Y.Z tag; keep this constant equal to it.
5
+ */
6
+ export const VERSION = "0.1.4";