@secondlayer/sdk 9.0.1 → 10.0.0

package/dist/streams/index.js

@@ -88,8 +88,8 @@ class ApiError extends SecondLayerError {
 
 class AuthError extends ApiError {
   status = 401;
-  constructor(message = "API key invalid or expired.") {
-    super(401, message);
+  constructor(message = "API key invalid or expired.", body, code) {
+    super(401, message, body, code);
     this.name = "AuthError";
   }
 }
@@ -97,8 +97,8 @@ class AuthError extends ApiError {
 class RateLimitError extends ApiError {
   retryAfter;
   status = 429;
-  constructor(message = "Rate limited. Try again later.", retryAfter) {
-    super(429, message, undefined, undefined, {
+  constructor(message = "Rate limited. Try again later.", retryAfter, body, code) {
+    super(429, message, body, code, {
       retryable: true,
       retryAfterSeconds: parseRetryAfter(retryAfter)
     });
@@ -108,8 +108,8 @@ class RateLimitError extends ApiError {
 }
 
 class ValidationError extends ApiError {
-  constructor(message, status, body) {
-    super(status, message, body, undefined, { retryable: false });
+  constructor(message, status, body, code) {
+    super(status, message, body, code, { retryable: false });
     this.name = "ValidationError";
   }
 }
@@ -125,18 +125,22 @@ function parseRetryAfter(value) {
   return;
 }
 
-class VersionConflictError extends ApiError {
-  currentVersion;
-  expectedVersion;
-  constructor(currentVersion, expectedVersion, message = `Version conflict: expected ${expectedVersion}, current ${currentVersion}`) {
-    super(409, message, { currentVersion, expectedVersion });
-    this.currentVersion = currentVersion;
-    this.expectedVersion = expectedVersion;
-    this.name = "VersionConflictError";
-  }
-}
-
 // src/base.ts
+var DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+function abortError() {
+  return new DOMException("This operation was aborted", "AbortError");
+}
+function raceAbort(promise, signal) {
+  if (signal.aborted)
+    return Promise.reject(signal.reason ?? abortError());
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason ?? abortError());
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(resolve, reject).finally(() => {
+      signal.removeEventListener("abort", onAbort);
+    });
+  });
+}
 var LOCAL_API_URL = "http://127.0.0.1:3800";
 function resolveBaseUrl(explicit) {
   if (explicit && explicit.length > 0)
@@ -166,6 +170,9 @@ function resolveApiKey(apiKey) {
   }
   return instanceToken ?? legacyKey;
 }
+function seg(value) {
+  return encodeURIComponent(String(value));
+}
 function buildQuery(params) {
   const search = new URLSearchParams;
   for (const [name, value] of Object.entries(params)) {
@@ -179,16 +186,39 @@ function buildQuery(params) {
   const query = search.toString();
   return query ? `?${query}` : "";
 }
+function parseErrorEnvelope(text) {
+  if (text.length === 0)
+    return { body: undefined };
+  try {
+    const json = JSON.parse(text);
+    let message;
+    let code;
+    if (json && typeof json === "object") {
+      const err = json.error ?? json.message;
+      if (typeof err === "string" && err.length > 0)
+        message = err;
+      else if (err && typeof err === "object")
+        message = JSON.stringify(err);
+      if (typeof json.code === "string")
+        code = json.code;
+    }
+    return { message, code, body: json };
+  } catch {
+    return { message: text, body: text };
+  }
+}
 
 class BaseClient {
   baseUrl;
   apiKey;
   origin;
   fetchImpl;
+  requestTimeoutMs;
   constructor(options = {}) {
     this.baseUrl = resolveBaseUrl(options.baseUrl);
     this.apiKey = resolveApiKey(options.apiKey);
     this.origin = options.origin ?? "cli";
+    this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     this.fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args));
   }
   static authHeaders(apiKey) {
@@ -200,27 +230,56 @@ class BaseClient {
     }
     return headers;
   }
-  async request(method, path, body) {
-    const response = await this.fetchResponse(method, path, body);
-    if (response.status === 204) {
-      return;
-    }
-    return response.json();
+  async request(method, path, body, opts = {}) {
+    return this.withRequestBudget(opts.signal, async (signal) => {
+      const response = await this.fetchResponse(method, path, body, signal);
+      if (response.status === 204) {
+        return;
+      }
+      return await raceAbort(response.json(), signal);
+    });
   }
-  async requestOrNull(method, path, body) {
+  async requestOrNull(method, path, body, opts = {}) {
     try {
-      return await this.request(method, path, body);
+      return await this.request(method, path, body, opts);
     } catch (err) {
       if (err instanceof ApiError && err.status === 404)
         return null;
       throw err;
     }
   }
-  async requestText(method, path, body) {
-    const response = await this.fetchResponse(method, path, body);
-    return response.text();
+  async requestText(method, path, body, opts = {}) {
+    return this.withRequestBudget(opts.signal, async (signal) => {
+      const response = await this.fetchResponse(method, path, body, signal);
+      return raceAbort(response.text(), signal);
+    });
+  }
+  async withRequestBudget(callerSignal, run) {
+    const controller = new AbortController;
+    let timedOut = false;
+    const forward = () => controller.abort(callerSignal?.reason ?? abortError());
+    if (callerSignal?.aborted)
+      forward();
+    else
+      callerSignal?.addEventListener("abort", forward, { once: true });
+    const timer = this.requestTimeoutMs > 0 ? setTimeout(() => {
+      timedOut = true;
+      controller.abort(abortError());
+    }, this.requestTimeoutMs) : undefined;
+    try {
+      return await run(controller.signal);
+    } catch (err) {
+      if (timedOut && !callerSignal?.aborted) {
+        throw new ApiError(0, `No response from ${this.baseUrl} within ${this.requestTimeoutMs}ms. Retryable. Raise requestTimeoutMs for slow filtered reads.`, undefined, "REQUEST_TIMEOUT", { retryable: true, cause: err instanceof Error ? err : undefined });
+      }
+      throw err;
+    } finally {
+      if (timer !== undefined)
+        clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", forward);
+    }
   }
-  async fetchResponse(method, path, body) {
+  async fetchResponse(method, path, body, signal) {
     const url = `${this.baseUrl}${path}`;
     const headers = BaseClient.authHeaders(this.apiKey);
     headers["x-sl-origin"] = this.origin;
@@ -235,56 +294,50 @@ class BaseClient {
     }
     let response;
     try {
-      response = await this.fetchImpl(url, {
+      const pending = this.fetchImpl(url, {
         method,
         headers,
-        body: serializedBody
+        body: serializedBody,
+        signal
       });
+      response = signal ? await raceAbort(pending, signal) : await pending;
     } catch (err) {
+      if (signal?.aborted)
+        throw err;
       throw new ApiError(0, `Cannot reach API at ${this.baseUrl}. Check your connection or try again.`, undefined, undefined, { retryable: true, cause: err instanceof Error ? err : undefined });
     }
     if (!response.ok) {
+      const errorBody = signal ? await raceAbort(response.text(), signal) : await response.text();
+      const envelope = parseErrorEnvelope(errorBody);
+      const retryAfter = response.headers.get("Retry-After") ?? undefined;
       if (response.status === 401) {
-        throw new AuthError;
+        throw new AuthError(envelope.message ?? "API key invalid or expired.", envelope.body, envelope.code);
       }
       if (response.status === 429) {
-        const retryAfter = response.headers.get("Retry-After");
-        const msg = retryAfter ? `Rate limited. Wait ${retryAfter} seconds.` : "Rate limited. Try again later.";
-        throw new RateLimitError(msg, retryAfter ?? undefined);
+        const fallback = retryAfter ? `Rate limited. Wait ${retryAfter} seconds.` : "Rate limited. Try again later.";
+        throw new RateLimitError(envelope.message ?? fallback, retryAfter, envelope.body, envelope.code);
       }
       if (response.status >= 500) {
-        throw new ApiError(response.status, `Server error. Try again or check status at ${this.baseUrl}/health`);
+        const retryAfterSeconds = parseRetryAfter(retryAfter);
+        throw new ApiError(response.status, envelope.message ?? `Server error. Try again or check status at ${this.baseUrl}/health`, envelope.body, envelope.code, retryAfterSeconds !== undefined ? { retryAfterSeconds } : {});
       }
-      const errorBody = await response.text();
-      let message = `HTTP ${response.status}`;
-      let parsedBody = errorBody;
-      let code;
-      try {
-        const json = JSON.parse(errorBody);
-        parsedBody = json;
-        const err = json.error ?? json.message;
-        if (typeof err === "string") {
-          message = err;
-        } else if (err && typeof err === "object") {
-          message = JSON.stringify(err);
-        }
-        if (typeof json.code === "string") {
-          code = json.code;
-        }
-      } catch {
-        if (errorBody)
-          message = errorBody;
-      }
-      throw new ApiError(response.status, message, parsedBody, code);
+      throw new ApiError(response.status, envelope.message ?? `HTTP ${response.status}`, envelope.body, envelope.code);
     }
     return response;
   }
 }
 
+// src/streams/cursor.ts
+import {
+  blockEndCursor,
+  decodeStreamsCursor,
+  encodeStreamsCursor
+} from "@secondlayer/shared";
+
 // src/streams/errors.ts
 class StreamsServerError extends ApiError {
-  constructor(message, status, body) {
-    super(status, message, body, undefined, { retryable: true });
+  constructor(message, status, body, code) {
+    super(status, message, body, code, { retryable: true });
     this.name = "StreamsServerError";
   }
 }
@@ -295,23 +348,38 @@ class StreamsSignatureError extends SecondLayerError {
     this.name = "StreamsSignatureError";
   }
 }
+async function mapStreamsError(response) {
+  const { message, code, body } = parseErrorEnvelope(await response.text());
+  if (response.status === 401) {
+    throw new AuthError(message ?? "API key invalid or expired.", body, code);
+  }
+  if (response.status === 429) {
+    const retryAfter = response.headers.get("Retry-After") ?? undefined;
+    throw new RateLimitError(message ?? "Rate limited. Try again later.", retryAfter, body, code);
+  }
+  if (response.status >= 500) {
+    throw new StreamsServerError(message ?? `Streams server returned ${response.status}.`, response.status, body, code);
+  }
+  throw new ValidationError(message ?? `Streams request returned ${response.status}.`, response.status, body, code);
+}
 
 // src/streams/cursor.ts
-var REWIND_FOOT_INDEX_SENTINEL = 2147483647;
 var Cursor = {
   atHeight(height) {
     if (height <= 0)
-      return "0:0";
-    return `${height - 1}:${REWIND_FOOT_INDEX_SENTINEL}`;
+      return null;
+    return encodeStreamsCursor(blockEndCursor(height - 1));
   },
   parse(cursor) {
-    const parts = cursor.split(":");
-    const blockHeight = Number(parts[0]);
-    const eventIndex = Number(parts[1]);
-    if (parts.length !== 2 || !Number.isInteger(blockHeight) || !Number.isInteger(eventIndex)) {
+    try {
+      const decoded = decodeStreamsCursor(cursor);
+      return {
+        blockHeight: decoded.block_height,
+        eventIndex: decoded.event_index
+      };
+    } catch {
       throw new ValidationError(`Invalid stream cursor "${cursor}"; expected "<block>:<index>" (e.g. "951475:3").`, 400);
     }
-    return { blockHeight, eventIndex };
   }
 };
 
@@ -319,6 +387,39 @@ var Cursor = {
 function reorgKey(reorg) {
   return `${reorg.detected_at}|${reorg.fork_point_height}|${reorg.new_canonical_tip}`;
 }
+var DEFAULT_MAX_ROLLBACK_DEPTH = 1000;
+async function applyReorgs(opts) {
+  const fresh = opts.reorgs.filter((reorg) => !opts.handled.has(opts.keyOf(reorg)));
+  if (fresh.length === 0)
+    return null;
+  for (const reorg of fresh) {
+    const fork = reorg.fork_point_height;
+    if (!Number.isSafeInteger(fork) || fork < 0) {
+      throw new ValidationError(`Reorg fork_point_height ${String(fork)} is not a non-negative integer. Rollback deletes every row at or above the fork from every declared table, so a malformed fork point is refused before the sink runs.`, 400);
+    }
+  }
+  const position = resumeHeight(opts.cursor);
+  const applicable = fresh.filter((reorg) => position !== null && reorg.fork_point_height <= position).sort((a, b) => a.fork_point_height - b.fork_point_height);
+  for (const reorg of fresh) {
+    if (!applicable.includes(reorg))
+      opts.handled.add(opts.keyOf(reorg));
+  }
+  if (applicable.length === 0 || position === null)
+    return null;
+  const forkPoint = applicable[0]?.fork_point_height ?? position;
+  const depth = position - forkPoint;
+  const maxDepth = opts.maxRollbackDepth ?? DEFAULT_MAX_ROLLBACK_DEPTH;
+  if (depth > maxDepth) {
+    throw new ValidationError(`Reorg at fork ${forkPoint} rewinds ${depth} blocks below the checkpoint at height ${position}, past maxRollbackDepth (${maxDepth}). A rollback this deep deletes every row at or above the fork from every declared table. Confirm the source is trusted, then pass maxRollbackDepth: ${depth} or higher to allow it.`, 400);
+  }
+  const rewind = Cursor.atHeight(forkPoint);
+  for (const reorg of applicable) {
+    await opts.sink?.rollback(reorg.fork_point_height, rewind);
+    await opts.onReorg?.(reorg, { cursor: rewind });
+    opts.handled.add(opts.keyOf(reorg));
+  }
+  return { forkPoint, cursor: rewind };
+}
 function assertFinalizedCheckpoint(returned, checkpoint) {
   if (returned === null || returned === undefined)
     return;
@@ -398,13 +499,15 @@ async function defaultSleep(ms, signal) {
   if (signal?.aborted)
     return;
   await new Promise((resolve) => {
-    const timeout = setTimeout(resolve, ms);
-    if (!signal)
-      return;
-    signal.addEventListener("abort", () => {
+    const onAbort = () => {
       clearTimeout(timeout);
       resolve();
-    }, { once: true });
+    };
+    const timeout = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
 async function consumeStreamsEvents(opts) {
@@ -418,6 +521,7 @@ async function consumeStreamsEvents(opts) {
   const committedCursor = await opts.sink?.loadCursor() ?? null;
   let cursor = opts.fromCursor ?? committedCursor;
   const handledReorgs = new Set;
+  let reorgSince = null;
   let pages = 0;
   let emptyPolls = 0;
   let height = resumeHeight(cursor);
@@ -441,23 +545,57 @@ async function consumeStreamsEvents(opts) {
       signal: opts.signal
     });
     pages++;
-    if (!finalizedOnly && (opts.onReorg || opts.sink)) {
-      const fresh = envelope.reorgs.filter((reorg) => !handledReorgs.has(reorgKey(reorg))).sort((a, b) => a.fork_point_height - b.fork_point_height);
-      if (fresh.length > 0) {
-        const forkPoint = Math.min(...fresh.map((reorg) => reorg.fork_point_height));
-        const rewind = Cursor.atHeight(forkPoint);
-        for (const reorg of fresh) {
-          await opts.sink?.rollback(reorg.fork_point_height, rewind);
-          await opts.onReorg?.(reorg, { cursor: rewind });
-          handledReorgs.add(reorgKey(reorg));
-        }
-        cursor = rewind;
-        height = forkPoint > 0 ? forkPoint - 1 : null;
+    const reorgsOn = !finalizedOnly && Boolean(opts.onReorg || opts.sink);
+    if (reorgsOn) {
+      const rewound = await applyReorgs({
+        reorgs: envelope.reorgs,
+        cursor,
+        handled: handledReorgs,
+        keyOf: reorgKey,
+        sink: opts.sink,
+        onReorg: opts.onReorg,
+        maxRollbackDepth: opts.maxRollbackDepth
+      });
+      if (rewound) {
+        cursor = rewound.cursor;
+        height = rewound.forkPoint > 0 ? rewound.forkPoint - 1 : null;
         scanned = height;
         emptyPolls = 0;
         continue;
       }
     }
+    if (reorgsOn && opts.fetchReorgs && envelope.events.length === 0) {
+      reorgSince ??= cursor;
+      if (reorgSince !== null) {
+        const since = reorgSince;
+        const fetchReorgs = opts.fetchReorgs;
+        const listed = await fetchPageWithRetry(() => fetchReorgs({ since }), {
+          retryCount: opts.retryCount,
+          retryDelay: opts.retryDelay,
+          onError: opts.onError,
+          sleep,
+          signal: opts.signal
+        });
+        if (listed.next_since !== null)
+          reorgSince = listed.next_since;
+        const rewound = await applyReorgs({
+          reorgs: listed.reorgs,
+          cursor,
+          handled: handledReorgs,
+          keyOf: reorgKey,
+          sink: opts.sink,
+          onReorg: opts.onReorg,
+          maxRollbackDepth: opts.maxRollbackDepth
+        });
+        if (rewound) {
+          cursor = rewound.cursor;
+          height = rewound.forkPoint > 0 ? rewound.forkPoint - 1 : null;
+          scanned = height;
+          emptyPolls = 0;
+          continue;
+        }
+      }
+    }
     const emitted = finalizedOnly ? envelope.events.filter((event) => event.finalized) : envelope.events;
     const checkpoint = finalizedOnly ? emitted.at(-1)?.cursor ?? cursor : envelope.next_cursor;
     height = emitted.at(-1)?.block_height ?? height;
@@ -735,15 +873,46 @@ function createStreamsDumps(opts) {
     return manifest;
   }
   async function download(file) {
+    return fetchPageWithRetry(() => downloadOnce(file), {
+      sleep: defaultSleep
+    });
+  }
+  async function downloadOnce(file) {
     const res = await opts.fetchImpl(fileUrl(file));
     if (!res.ok) {
       throw new StreamsServerError(`Could not download dump ${file.path} (${res.status}).`, res.status);
     }
-    const bytes = new Uint8Array(await res.arrayBuffer());
-    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (!res.body) {
+      throw new StreamsServerError(`Dump ${file.path} response has no body.`, 0);
+    }
+    const hash = createHash("sha256");
+    const chunks = [];
+    let total = 0;
+    const reader = res.body.getReader();
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+          break;
+        hash.update(value);
+        chunks.push(value);
+        total += value.byteLength;
+      }
+    } catch {
+      throw new StreamsServerError(`Download of dump ${file.path} was interrupted after ${total} bytes.`, 0);
+    }
+    const digest = hash.digest("hex");
     if (digest !== file.sha256) {
       throw new StreamsSignatureError(`Dump ${file.path} sha256 mismatch (expected ${file.sha256}, got ${digest}).`);
     }
+    if (chunks.length === 1 && chunks[0])
+      return chunks[0];
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
     return bytes;
   }
   return { list, fileUrl, download };
@@ -751,6 +920,19 @@ function createStreamsDumps(opts) {
 
 // src/streams/subscribe.ts
 import { ed25519 } from "@secondlayer/shared";
+var SUBSCRIBE_MAX_RECONNECT_DELAY_MS = 30000;
+var SUBSCRIBE_DEFAULT_STALE_AFTER_MS = 60000;
+function reconnectDelay(attempt, baseMs, retryAfterSeconds, random = Math.random) {
+  const capped = Math.min(baseMs * 2 ** Math.max(0, attempt), SUBSCRIBE_MAX_RECONNECT_DELAY_MS);
+  const jittered = capped * (0.5 + random() * 0.5);
+  const floor = (retryAfterSeconds ?? 0) * 1000;
+  return Math.max(jittered, floor);
+}
+function isTerminal(err) {
+  if (err instanceof StreamsSignatureError)
+    return true;
+  return err?.retryable === false;
+}
 function subscribeStreamsEvents(opts) {
   const { params } = opts;
   const controller = new AbortController;
@@ -764,7 +946,9 @@ function subscribeStreamsEvents(opts) {
       });
   }
   let cursor = params.fromCursor ?? null;
-  const reconnectDelayMs = opts.reconnectDelayMs ?? 1000;
+  const baseDelayMs = opts.reconnectDelayMs ?? params.reconnectDelayMs ?? 1000;
+  const staleAfterMs = opts.staleAfterMs ?? params.staleAfterMs ?? SUBSCRIBE_DEFAULT_STALE_AFTER_MS;
+  let attempt = 0;
   const run = async () => {
     while (!controller.signal.aborted) {
       try {
@@ -778,55 +962,76 @@ function subscribeStreamsEvents(opts) {
           asset_identifier: params.assetIdentifier,
           filters: params.filters ? JSON.stringify(params.filters) : undefined
         })}`;
-        const res = await opts.fetchImpl(url, {
-          headers: {
-            ...opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {},
-            Accept: "text/event-stream"
-          },
-          signal: controller.signal
-        });
-        if (!res.ok) {
-          throw new StreamsServerError(`Streams SSE returned ${res.status}.`, res.status);
-        }
-        if (!res.body) {
-          throw new StreamsServerError("Streams SSE response has no body.", 0);
-        }
-        for await (const frame of parseSseFrames(res.body, controller.signal)) {
-          if (frame.event === "ping" || !frame.data)
-            continue;
-          let parsed;
-          try {
-            parsed = JSON.parse(frame.data);
-          } catch {
-            continue;
-          }
-          if (!parsed.event)
-            continue;
-          if (opts.verify !== "off") {
-            if (!parsed.sig) {
-              if (opts.verify === "strict") {
-                throw new StreamsSignatureError("Streams SSE frame signature is missing.");
-              }
-            } else {
-              const key = await opts.loadKey();
-              if (!ed25519.verifyEd25519(JSON.stringify(parsed.event), parsed.sig, key.publicKey)) {
-                throw new StreamsSignatureError("Streams SSE frame signature is invalid.");
+        await readSse({
+          url,
+          headers: opts.headers ?? {},
+          signal: controller.signal,
+          fetchImpl: opts.fetchImpl,
+          staleAfterMs,
+          mapError: mapStreamsError,
+          onFrame: async (frame) => {
+            attempt = 0;
+            if (frame.event === "ping" || !frame.data)
+              return;
+            let parsed;
+            try {
+              parsed = JSON.parse(frame.data);
+            } catch {
+              return;
+            }
+            if (!parsed.event)
+              return;
+            if (opts.verify !== "off") {
+              if (!parsed.sig) {
+                if (opts.verify === "strict") {
+                  throw new StreamsSignatureError("Streams SSE frame signature is missing.");
+                }
+              } else {
+                const key = await opts.loadKey(parsed.key_id);
+                if (!ed25519.verifyEd25519(JSON.stringify(parsed.event), parsed.sig, key.publicKey)) {
+                  throw new StreamsSignatureError("Streams SSE frame signature is invalid.");
+                }
               }
             }
+            await params.onEvent(parsed.event);
+            cursor = parsed.event.cursor ?? cursor;
           }
-          cursor = parsed.event.cursor ?? cursor;
-          await params.onEvent(parsed.event);
-        }
+        });
+        await sleep(reconnectDelay(attempt, baseDelayMs, undefined, opts.random), controller.signal);
+        attempt += 1;
       } catch (err) {
         if (controller.signal.aborted)
           return;
         params.onError?.(err);
-        await sleep(reconnectDelayMs, controller.signal);
+        if (isTerminal(err))
+          throw err;
+        const retryAfterSeconds = err.retryAfterSeconds;
+        await sleep(reconnectDelay(attempt, baseDelayMs, retryAfterSeconds, opts.random), controller.signal);
+        attempt += 1;
       }
     }
   };
-  run();
-  return () => controller.abort();
+  const done = run();
+  done.catch(() => {});
+  const unsubscribe = () => controller.abort();
+  return Object.assign(unsubscribe, { done });
+}
+async function readSse(opts) {
+  const res = await opts.fetchImpl(opts.url, {
+    headers: { ...opts.headers ?? {}, Accept: "text/event-stream" },
+    signal: opts.signal
+  });
+  if (!res.ok) {
+    if (opts.mapError)
+      await opts.mapError(res);
+    throw new StreamsServerError(`Streams SSE returned ${res.status}.`, res.status);
+  }
+  if (!res.body) {
+    throw new StreamsServerError("Streams SSE response has no body.", 0);
+  }
+  for await (const frame of parseSseFrames(res.body, opts.signal, opts.staleAfterMs)) {
+    await opts.onFrame(frame);
+  }
 }
 function sleep(ms, signal) {
   return new Promise((resolve) => {
@@ -843,13 +1048,27 @@ function sleep(ms, signal) {
     signal.addEventListener("abort", onAbort, { once: true });
   });
 }
-async function* parseSseFrames(body, signal) {
+async function readWithStaleTimer(reader, staleAfterMs) {
+  if (staleAfterMs === undefined || !Number.isFinite(staleAfterMs)) {
+    return reader.read();
+  }
+  let timer;
+  const stale = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new StreamsServerError(`Streams SSE went quiet for ${staleAfterMs} ms; reconnecting.`, 0, undefined, "STREAM_STALE")), staleAfterMs);
+  });
+  try {
+    return await Promise.race([reader.read(), stale]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function* parseSseFrames(body, signal, staleAfterMs) {
   const reader = body.getReader();
   const decoder = new TextDecoder;
   let buffer = "";
   try {
     while (!signal.aborted) {
-      const { value, done } = await reader.read();
+      const { value, done } = await readWithStaleTimer(reader, staleAfterMs);
       if (done)
         break;
       buffer += decoder.decode(value, { stream: true });
@@ -889,12 +1108,8 @@ function parseFrame(raw) {
 function cursorTuple(cursor) {
   if (!cursor)
     return [-1, -1];
-  const parts = cursor.split(":");
-  const [block, index] = parts.map(Number);
-  if (parts.length !== 2 || !Number.isInteger(block) || !Number.isInteger(index)) {
-    throw new ValidationError(`Invalid stream cursor "${cursor}"; expected "<block>:<index>" (e.g. "951475:3").`, 400);
-  }
-  return [block, index];
+  const { blockHeight, eventIndex } = Cursor.parse(cursor);
+  return [blockHeight, eventIndex];
 }
 function maxCursor(a, b) {
   const [ah, ai] = cursorTuple(a);
@@ -915,51 +1130,33 @@ function streamsFilters(params) {
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
-async function responseBody(response) {
-  const text = await response.text();
-  if (text.length === 0)
-    return;
+function isLoopbackUrl(baseUrl) {
   try {
-    return JSON.parse(text);
+    const { hostname } = new URL(baseUrl);
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]" || hostname.startsWith("127.");
   } catch {
-    return text;
-  }
-}
-function errorMessage(body, fallback) {
-  if (body && typeof body === "object") {
-    const record = body;
-    const message = record.error ?? record.message;
-    if (typeof message === "string" && message.length > 0)
-      return message;
-  }
-  if (typeof body === "string" && body.length > 0)
-    return body;
-  return fallback;
-}
-async function mapStreamsError(response) {
-  const body = await responseBody(response);
-  if (response.status === 401) {
-    throw new AuthError(errorMessage(body, "API key invalid or expired."));
-  }
-  if (response.status === 429) {
-    const retryAfter = response.headers.get("Retry-After") ?? undefined;
-    throw new RateLimitError(errorMessage(body, "Rate limited. Try again later."), retryAfter);
-  }
-  if (response.status >= 500) {
-    throw new StreamsServerError(errorMessage(body, `Streams server returned ${response.status}.`), response.status, body);
+    return false;
   }
-  throw new ValidationError(errorMessage(body, `Streams request returned ${response.status}.`), response.status, body);
 }
 function createStreamsClient(options) {
   const baseUrl = normalizeBaseUrl(resolveBaseUrl(options.baseUrl));
+  const apiKey = resolveApiKey(options.apiKey);
+  const origin = options.origin ?? "cli";
+  const authHeaders = () => ({
+    "x-sl-origin": origin,
+    ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+  });
   const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
   const verify = options.verify;
   const verifyMode = verify === false ? "off" : verify === undefined ? "lenient" : "strict";
+  if (verify === true && baseUrl.startsWith("http:") && !isLoopbackUrl(baseUrl)) {
+    throw new ValidationError(`verify: true over plain http to ${baseUrl} fetches the signing key from the same unprotected path it verifies. Pin the key with verify: { publicKey } (see GET /public/streams/signing-key), or use https.`, 400);
+  }
   let keyPromise = null;
   function loadKey() {
     if (keyPromise)
       return keyPromise;
-    keyPromise = (async () => {
+    const pending = (async () => {
       if (typeof verify === "object") {
         return {
           keyId: ed255192.ed25519KeyId(verify.publicKey),
@@ -967,8 +1164,16 @@ function createStreamsClient(options) {
           publicKey: ed255192.loadEd25519PublicKey(verify.publicKey)
         };
       }
-      const res = await fetchImpl(`${baseUrl}/public/streams/signing-key`);
+      let res;
+      try {
+        res = await fetchImpl(`${baseUrl}/public/streams/signing-key`);
+      } catch {
+        throw new StreamsServerError(`Could not reach the signing key at ${baseUrl}/public/streams/signing-key. Retryable.`, 0, undefined, "SIGNING_KEY_UNAVAILABLE");
+      }
       if (!res.ok) {
+        if (res.status >= 500 || res.status === 429) {
+          throw new StreamsServerError(`Could not fetch signing key (${res.status}). Retryable.`, res.status, undefined, "SIGNING_KEY_UNAVAILABLE");
+        }
         throw new StreamsSignatureError(`Could not fetch signing key (${res.status}).`);
       }
       const body = await res.json();
@@ -981,7 +1186,26 @@ function createStreamsClient(options) {
         publicKey: ed255192.loadEd25519PublicKey(body.public_key_pem)
       };
     })();
-    return keyPromise;
+    keyPromise = pending;
+    pending.catch(() => {
+      if (keyPromise === pending)
+        keyPromise = null;
+    });
+    return pending;
+  }
+  async function loadKeyFor(responseKeyId) {
+    let key = await loadKey();
+    if (!responseKeyId || responseKeyId === key.keyId)
+      return key;
+    if (typeof verify === "object") {
+      throw new StreamsSignatureError(`Response signed with key '${responseKeyId}', expected pinned key '${key.keyId}'.`);
+    }
+    keyPromise = null;
+    key = await loadKey();
+    if (responseKeyId !== key.keyId) {
+      throw new StreamsSignatureError(`Response signed with key '${responseKeyId}' not served by the signing-key endpoint.`);
+    }
+    return key;
   }
   const dumps = createStreamsDumps({
     baseUrl: options.dumpsBaseUrl,
@@ -991,7 +1215,7 @@ function createStreamsClient(options) {
   });
   async function request(path) {
     const response = await fetchImpl(`${baseUrl}${path}`, {
-      headers: options.apiKey ? { Authorization: `Bearer ${options.apiKey}` } : {}
+      headers: authHeaders()
     });
     if (!response.ok)
       await mapStreamsError(response);
@@ -1003,18 +1227,7 @@ function createStreamsClient(options) {
           throw new StreamsSignatureError("Response is missing X-Signature.");
         }
       } else {
-        const responseKeyId = response.headers.get("X-Signature-KeyId");
-        let key = await loadKey();
-        if (responseKeyId && responseKeyId !== key.keyId) {
-          if (typeof verify === "object") {
-            throw new StreamsSignatureError(`Response signed with key '${responseKeyId}', expected pinned key '${key.keyId}'.`);
-          }
-          keyPromise = null;
-          key = await loadKey();
-          if (responseKeyId !== key.keyId) {
-            throw new StreamsSignatureError(`Response signed with key '${responseKeyId}' not served by the signing-key endpoint.`);
-          }
-        }
+        const key = await loadKeyFor(response.headers.get("X-Signature-KeyId"));
         if (!ed255192.verifyEd25519(text, signature, key.publicKey)) {
           throw new StreamsSignatureError;
         }
@@ -1023,6 +1236,13 @@ function createStreamsClient(options) {
     return JSON.parse(text);
   }
   const fetchEvents = listEvents;
+  function listReorgs(params) {
+    return request(`/v1/streams/reorgs${buildQuery({
+      since: params.since,
+      limit: params.limit
+    })}`);
+  }
+  const fetchReorgs = (params) => listReorgs(params);
   function encodeFilters(filters) {
     return filters ? JSON.stringify(filters) : undefined;
   }
@@ -1070,8 +1290,10 @@ function createStreamsClient(options) {
       ...streamsFilters(params),
       batchSize: params.batchSize ?? 100,
       fetchEvents,
+      fetchReorgs,
       onBatch,
       onReorg: params.onReorg,
+      maxRollbackDepth: params.maxRollbackDepth,
       emptyBackoffMs: params.emptyBackoffMs,
       maxPages: params.maxPages,
       maxEmptyPolls: params.maxEmptyPolls,
@@ -1113,10 +1335,12 @@ function createStreamsClient(options) {
       subscribe(params) {
         return subscribeStreamsEvents({
           baseUrl,
-          apiKey: options.apiKey,
+          headers: authHeaders(),
           fetchImpl,
           verify: verifyMode,
-          loadKey,
+          loadKey: loadKeyFor,
+          reconnectDelayMs: params.reconnectDelayMs,
+          staleAfterMs: params.staleAfterMs,
           params
         });
       },
@@ -1124,11 +1348,11 @@ function createStreamsClient(options) {
         const fromCursor = params.from === "genesis" ? null : params.from ?? null;
         const fromBlock = fromCursor ? cursorTuple(fromCursor)[0] : 0;
         const manifest = await dumps.list();
-        const files = manifest.files.filter((file) => file.to_block >= fromBlock).sort((a, b) => a.from_block - b.from_block || a.to_block - b.to_block);
+        const files = manifest.files.filter((file) => file.to_block >= fromBlock).filter((file) => fromCursor === null || file.max_cursor === null || maxCursor(fromCursor, file.max_cursor) !== fromCursor).sort((a, b) => a.from_block - b.from_block || a.to_block - b.to_block);
         for (const file of files) {
           if (params.signal?.aborted)
             break;
-          await params.onDumpFile(file);
+          await params.onDumpFile(file, { from: fromCursor });
         }
         const seam = maxCursor(fromCursor, manifest.latest_finalized_cursor);
         return consumeStreamsEvents({
@@ -1153,14 +1377,7 @@ function createStreamsClient(options) {
         return request(`/v1/streams/blocks/${encodeURIComponent(String(heightOrHash))}/events`);
       }
     },
-    reorgs: {
-      list(params) {
-        return request(`/v1/streams/reorgs${buildQuery({
-          since: params.since,
-          limit: params.limit
-        })}`);
-      }
-    },
+    reorgs: { list: listReorgs },
     dumps,
     canonical(height) {
       return request(`/v1/streams/canonical/${height}`);
@@ -1235,5 +1452,5 @@ export {
   AuthError
 };
 
-//# debugId=3058A2F9A6830C7464756E2164756E21
+//# debugId=6013F1D9BD2F6AD764756E2164756E21
 //# sourceMappingURL=index.js.map