propline 0.44.0 → 0.46.0

package/README.md

@@ -805,6 +805,7 @@ Each POST carries these headers:
 | `X-PropLine-Timestamp` | Unix seconds |
 | `X-PropLine-Signature` | HMAC-SHA256 over `${timestamp}.` + body |
 | `X-PropLine-Delivery` | Stable delivery id (use for idempotency) |
+| `X-PropLine-Sequence` | Your subscription's own event counter (use for replay) |
 
 ```ts
 import express from "express";
@@ -936,6 +937,75 @@ await client.listWebhookDeliveries(whId, { limit: 200, beforeId: 123456 });
 await client.deleteWebhook(whId);
 ```
 
+### Catching up after an outage
+
+Every delivery carries `X-PropLine-Sequence` — a counter monotonic *within your
+subscription*. Store the highest one you processed, then read forward from it.
+Do not use `X-PropLine-Delivery` as the cursor: that id is global across all
+subscriptions, so its gaps are other customers' traffic.
+
+```ts
+let cursor = await loadMyCursor(); // highest X-PropLine-Sequence processed
+
+for (;;) {
+  const page = await client.replayWebhookEvents(whId, { sinceSeq: cursor, limit: 100 });
+
+  if (page.truncated) {
+    // Events after your cursor aged out of retention and are gone.
+    // Resync from the REST endpoints rather than assume you are current.
+    await resyncFromRest();
+  }
+
+  for (const ev of page.events) {   // oldest first
+    await handle(ev.event_type, ev.data);
+  }
+
+  cursor = page.next_seq;
+  await saveMyCursor(cursor);
+  if (!page.has_more) {
+    console.log(`behind by ${page.latest_seq - cursor} events`);
+    break;
+  }
+}
+```
+
+### Websocket streaming
+
+If your stack already speaks websockets — or you can't host a public HTTPS
+endpoint — connect a socket instead of receiving POSTs. Same events, same
+filters, same `seq`: a stream and a webhook are the **same subscription with a
+different transport**.
+
+```ts
+const wh = await client.createWebhook({
+  transport: "websocket",          // no url — there is nowhere to POST
+  events: ["line_movement"],
+  filterSportKey: "baseball_mlb",
+});
+
+for await (const ev of client.stream({ webhookId: wh.id, sinceSeq: myCursor })) {
+  await handle(ev.event_type, ev.data);
+  myCursor = ev.seq;               // persist it; this is your resume point
+}
+```
+
+Reconnects and resumes from the last `seq` automatically, so a dropped
+connection is not a gap in your data. `onTruncated` fires when events after
+your cursor aged out of retention — the one case streaming cannot make you
+whole, where you should resync from REST. Zero dependencies: it uses Node's
+built-in `WebSocket` (Node 22+).
+
+Concurrent connections are capped per plan (Streaming Lite 2, Streaming 5).
+Delivered events are **not** metered.
+
+Replay is bounded by delivery retention: 2 days, and at most 5,000 deliveries
+per subscription. `latest_seq` is **not** subject to retention, so
+`latest_seq - next_seq` stays honest even after the rows are pruned. Sequence
+numbers always increase and never repeat but are not guaranteed to be dense —
+treat a skipped number as normal, and read `truncated` for real loss. Neither
+`replayWebhookEvents` nor `listWebhookDeliveries` counts against your daily
+quota.
+
 ## Error handling
 
 ```ts

package/dist/index.cjs

@@ -818,6 +818,139 @@ var PropLine = class {
       { params: { limit: options.limit ?? 50, before_id: options.beforeId } }
     );
   }
+  /**
+   * Re-read this subscription's events in order, from a cursor.
+   *
+   * Answers "my endpoint was down — what did I miss?". Every delivery carries
+   * an `X-PropLine-Sequence` header: a counter monotonic *within your
+   * subscription*. Store the highest one you processed and pass it as
+   * `sinceSeq`.
+   *
+   * Do NOT use `X-PropLine-Delivery` as the cursor — that id is global across
+   * every subscription, so its gaps are other customers' traffic.
+   *
+   * Events come back oldest-first (the opposite of `listWebhookDeliveries`,
+   * which is a newest-first debugging log). Page by passing `next_seq` back
+   * as `sinceSeq` while `has_more` is true.
+   *
+   * **Check `truncated`.** True means events after your cursor have aged out
+   * of retention (2 days, max 5,000 deliveries per subscription) and are gone
+   * — resync from the REST endpoints instead of assuming you are current.
+   *
+   * Does not count against your daily request quota.
+   */
+  replayWebhookEvents(webhookId, options = {}) {
+    return this._request(
+      "GET",
+      `/webhooks/${webhookId}/replay`,
+      { params: { since_seq: options.sinceSeq ?? 0, limit: options.limit ?? 100 } }
+    );
+  }
+  /**
+   * Stream a websocket subscription as an async iterable.
+   *
+   * ```ts
+   * for await (const ev of client.stream({ webhookId: 12, sinceSeq: 4180 })) {
+   *   console.log(ev.seq, ev.event_type, ev.data);
+   * }
+   * ```
+   *
+   * The subscription must have been created with `transport: "websocket"`.
+   * Same events, same filters, same `seq` as an HTTP webhook — one
+   * subscription, different transport.
+   *
+   * **Reconnects automatically and resumes from the last `seq` it saw**, which
+   * is the whole point of the sequence: a dropped connection does not become a
+   * gap in your data. Set `reconnect: false` to get a single connection that
+   * ends when the socket closes.
+   *
+   * If the server reports `truncated` — events after your cursor aged out of
+   * retention and are gone — `onTruncated` fires. Handle it: that is the one
+   * case where the stream cannot make you whole and you should resync from the
+   * REST endpoints.
+   */
+  async *stream(options) {
+    const wsBase = (options.wsUrl ?? this.baseUrl).replace(/^http:/, "ws:").replace(/^https:/, "wss:").replace(/\/v1\/?$/, "");
+    const url = `${wsBase}/v1/stream`;
+    let cursor = options.sinceSeq ?? 0;
+    let attempt = 0;
+    for (; ; ) {
+      const queue = [];
+      let notify = null;
+      let closed = null;
+      let opened = false;
+      const ws = new WebSocket(url);
+      const wake = () => {
+        const n = notify;
+        notify = null;
+        n?.();
+      };
+      ws.addEventListener("open", () => {
+        opened = true;
+        ws.send(JSON.stringify({
+          type: "auth",
+          api_key: this.apiKey,
+          webhook_id: options.webhookId,
+          since_seq: cursor
+        }));
+      });
+      ws.addEventListener("message", (e) => {
+        let msg;
+        try {
+          msg = JSON.parse(String(e.data));
+        } catch {
+          return;
+        }
+        if (msg.type === "ready") {
+          attempt = 0;
+          if (msg.truncated) options.onTruncated?.(msg);
+          options.onReady?.(msg);
+        } else if (msg.type === "event") {
+          queue.push(msg);
+          wake();
+        }
+      });
+      ws.addEventListener("close", (e) => {
+        const terminal = [4400, 4401, 4403, 4404].includes(e.code);
+        closed = new PropLineError(
+          e.code,
+          `stream closed${e.reason ? `: ${e.reason}` : ""}`
+        );
+        closed.terminal = terminal;
+        wake();
+      });
+      ws.addEventListener("error", () => {
+        if (!closed) closed = new PropLineError(0, "stream connection error");
+        wake();
+      });
+      try {
+        for (; ; ) {
+          while (queue.length) {
+            const ev = queue.shift();
+            cursor = ev.seq;
+            yield ev;
+          }
+          if (closed) break;
+          await new Promise((r) => {
+            notify = r;
+          });
+        }
+      } finally {
+        try {
+          ws.close();
+        } catch {
+        }
+      }
+      const err = closed;
+      if (err?.terminal) throw err;
+      if (options.reconnect === false) {
+        if (err && !opened) throw err;
+        return;
+      }
+      const delayMs = Math.min(3e4, 500 * 2 ** attempt++);
+      await new Promise((r) => setTimeout(r, delayMs));
+    }
+  }
   /**
    * Grade placed bets against their closing lines (CLV).
    *
@@ -958,7 +1091,7 @@ var Bookmakers = {
   POLYMARKET: "polymarket",
   PRIZEPICKS: "prizepicks"
 };
-var VERSION = "0.44.0";
+var VERSION = "0.46.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthError,