@secondlayer/sdk 16.2.0 → 16.3.0

package/dist/streams/index.d.ts

@@ -482,6 +482,8 @@ type StreamsEventsStreamBitcoinParams = StreamsEventsStreamCommon & {
 	address?: string;
 };
 type StreamsEventsStreamParams = StreamsEventsStreamStacksParams | StreamsEventsStreamBitcoinParams;
+/** Where a `subscribe` connection is in its lifecycle. */
+type StreamsSubscriptionState = "connecting" | "open" | "reconnecting" | "closed";
 type StreamsEventsSubscribeCommon = {
 	/** Resume strictly after this cursor; omit to live-tail from the tip. */
 	fromCursor?: string | null;
@@ -495,6 +497,13 @@ type StreamsEventsSubscribeCommon = {
 	*/
 	onError?: (err: unknown) => void;
 	/**
+	* Lifecycle observer. `connecting` before each connection attempt, `open`
+	* once the server answers, `reconnecting` while backing off after a drop
+	* or error, `closed` once, when the subscription ends (unsubscribed,
+	* aborted, or stopped by an error a retry cannot fix).
+	*/
+	onState?: (state: StreamsSubscriptionState) => void;
+	/**
 	* First reconnect pause in ms (default 1000). Doubles per consecutive
 	* failure up to 30 s with jitter, resets once a frame arrives, and never
 	* undercuts a `Retry-After`.
@@ -1111,6 +1120,13 @@ type CreateStreamsClientOptions = {
 	origin?: "cli" | "mcp" | "session";
 	fetchImpl?: FetchLike2;
 	/**
+	* Give up on a request that has not connected and returned response headers
+	* within this many ms (default 30000; `0` disables). Retryable: the consume
+	* loops retry it and `subscribe` reconnects. Body reads are not covered, so
+	* a healthy long-lived stream is never cut off.
+	*/
+	connectTimeoutMs?: number;
+	/**
 	* Public base URL for bulk parquet dumps (the R2/CDN bucket root). Required
 	* to use `client.dumps`. See `GET /public/streams/dumps/manifest`.
 	*/
@@ -1310,4 +1326,4 @@ declare const Cursor: {
 		eventIndex: number;
 	};
 };
-export { AuthError, ConsumerBatchContext, Cursor, DecodedEventColumns, DecodedEventRow, DecodedFtBurn, DecodedFtBurnPayload, DecodedFtMint, DecodedFtMintPayload, DecodedFtTransfer, DecodedFtTransferPayload, DecodedNftBurn, DecodedNftBurnPayload, DecodedNftMint, DecodedNftMintPayload, DecodedNftTransfer, DecodedNftTransferPayload, DecodedPrint, DecodedPrintPayload, DecodedPrintValue, DecodedStxBurn, DecodedStxBurnPayload, DecodedStxLock, DecodedStxLockPayload, DecodedStxMint, DecodedStxMintPayload, DecodedStxTransfer, DecodedStxTransferPayload, FetchLike2 as FetchLike, FtTransferEvent, FtTransferPayload2 as FtTransferPayload, NftTransferEvent, NftTransferPayload2 as NftTransferPayload, RateLimitError, RuneEtchEntry, RuneEventPayload, RuneEventType, RuneStreamsEvent, STREAMS_EVENT_TYPES, StreamsBatch, StreamsBitcoinCanonicalBlock, StreamsBitcoinTip, StreamsCanonicalBlock, StreamsClient, StreamsConsumeBitcoinParams, StreamsConsumeParams, StreamsConsumeStacksParams, StreamsDumpFile, StreamsDumps, StreamsDumpsManifest, StreamsEvent, StreamsEventPayload, StreamsEventType, StreamsEventsBitcoinListParams, StreamsEventsConsumeBitcoinParams, StreamsEventsConsumeParams, StreamsEventsConsumeResult, StreamsEventsEnvelope, StreamsEventsListEnvelope, StreamsEventsListParams, StreamsEventsStacksListParams, StreamsEventsStreamBitcoinParams, StreamsEventsStreamParams, StreamsEventsStreamStacksParams, StreamsEventsSubscribeBitcoinParams, StreamsEventsSubscribeParams, StreamsEventsSubscribeStacksParams, StreamsReorg, StreamsReorgContext, StreamsReorgsListEnvelope, StreamsReorgsListParams, StreamsServerError, StreamsSignatureError, StreamsSubscription, StreamsTip, StreamsWireEvent2 as StreamsWireEvent, ValidationError, VmStreamsEvent, createStreamsClient, decode };
+export { AuthError, ConsumerBatchContext, Cursor, DecodedEventColumns, DecodedEventRow, DecodedFtBurn, DecodedFtBurnPayload, DecodedFtMint, DecodedFtMintPayload, DecodedFtTransfer, DecodedFtTransferPayload, DecodedNftBurn, DecodedNftBurnPayload, DecodedNftMint, DecodedNftMintPayload, DecodedNftTransfer, DecodedNftTransferPayload, DecodedPrint, DecodedPrintPayload, DecodedPrintValue, DecodedStxBurn, DecodedStxBurnPayload, DecodedStxLock, DecodedStxLockPayload, DecodedStxMint, DecodedStxMintPayload, DecodedStxTransfer, DecodedStxTransferPayload, FetchLike2 as FetchLike, FtTransferEvent, FtTransferPayload2 as FtTransferPayload, NftTransferEvent, NftTransferPayload2 as NftTransferPayload, RateLimitError, RuneEtchEntry, RuneEventPayload, RuneEventType, RuneStreamsEvent, STREAMS_EVENT_TYPES, StreamsBatch, StreamsBitcoinCanonicalBlock, StreamsBitcoinTip, StreamsCanonicalBlock, StreamsClient, StreamsConsumeBitcoinParams, StreamsConsumeParams, StreamsConsumeStacksParams, StreamsDumpFile, StreamsDumps, StreamsDumpsManifest, StreamsEvent, StreamsEventPayload, StreamsEventType, StreamsEventsBitcoinListParams, StreamsEventsConsumeBitcoinParams, StreamsEventsConsumeParams, StreamsEventsConsumeResult, StreamsEventsEnvelope, StreamsEventsListEnvelope, StreamsEventsListParams, StreamsEventsStacksListParams, StreamsEventsStreamBitcoinParams, StreamsEventsStreamParams, StreamsEventsStreamStacksParams, StreamsEventsSubscribeBitcoinParams, StreamsEventsSubscribeParams, StreamsEventsSubscribeStacksParams, StreamsReorg, StreamsReorgContext, StreamsReorgsListEnvelope, StreamsReorgsListParams, StreamsServerError, StreamsSignatureError, StreamsSubscription, StreamsSubscriptionState, StreamsTip, StreamsWireEvent2 as StreamsWireEvent, ValidationError, VmStreamsEvent, createStreamsClient, decode };

package/dist/streams/index.js

@@ -247,6 +247,22 @@ function resolveAccountKey(accountKey) {
     return;
   return process.env?.SECONDLAYER_API_KEY || undefined;
 }
+function resolveAccountUrl() {
+  const env = typeof process !== "undefined" ? process.env : undefined;
+  return (env?.SL_CREDITS_API_URL || env?.ARCHIVE_OPS_API_URL || HOSTED_API_URL).replace(/\/+$/, "");
+}
+var ACCOUNT_CREDENTIAL_RE = /^s[ks]-sl_/;
+function resolveIdentity(target, options = {}) {
+  const url = target === "account" ? resolveAccountUrl() : resolveBaseUrl();
+  const envKey = target === "account" ? resolveAccountKey() : typeof process !== "undefined" ? process.env?.[INSTANCE_TOKEN_ENV] || undefined : undefined;
+  if (envKey && (target === "instance" || ACCOUNT_CREDENTIAL_RE.test(envKey))) {
+    return { source: "env", token: envKey, url };
+  }
+  if (options.session) {
+    return { source: "session", token: options.session, url };
+  }
+  return { source: "none", token: undefined, url };
+}
 function seg(value) {
   return encodeURIComponent(String(value));
 }
@@ -749,13 +765,70 @@ async function consumeStreamsEvents(opts) {
   }
   return { cursor, pages, emptyPolls };
 }
+async function* pullFromLoop(start, external) {
+  const controller = new AbortController;
+  if (external) {
+    if (external.aborted)
+      controller.abort();
+    else
+      external.addEventListener("abort", () => controller.abort(), {
+        once: true
+      });
+  }
+  const state = {
+    delivered: null,
+    held: null,
+    finished: false,
+    failure: null,
+    wake: null
+  };
+  const notify = () => {
+    const resolve = state.wake;
+    state.wake = null;
+    resolve?.();
+  };
+  const loop = start((value) => new Promise((release) => {
+    state.delivered = { value, release };
+    notify();
+  }), controller.signal).then(() => {
+    state.finished = true;
+  }, (error) => {
+    state.failure = { error };
+    state.finished = true;
+  }).finally(notify);
+  try {
+    while (true) {
+      if (state.delivered) {
+        const { value, release } = state.delivered;
+        state.delivered = null;
+        state.held = release;
+        yield value;
+        state.held = null;
+        release();
+        continue;
+      }
+      if (state.finished)
+        break;
+      await new Promise((resolve) => {
+        state.wake = resolve;
+        if (state.delivered || state.finished)
+          notify();
+      });
+    }
+    if (state.failure)
+      throw state.failure.error;
+  } finally {
+    controller.abort();
+    state.held?.();
+    state.delivered?.release();
+    await loop;
+  }
+}
 async function* iterateStreamsBatches(opts) {
-  const sleep = opts.sleep ?? defaultSleep;
-  let cursor = opts.fromCursor ?? null;
-  while (!opts.signal?.aborted) {
-    const envelope = await opts.fetchEvents({
-      cursor,
-      limit: opts.batchSize,
+  yield* pullFromLoop(async (deliver, signal) => {
+    const result = await consumeStreamsEvents({
+      fromCursor: opts.fromCursor,
+      batchSize: opts.batchSize,
       chain: opts.chain,
       types: opts.types,
       notTypes: opts.notTypes,
@@ -765,38 +838,41 @@ async function* iterateStreamsBatches(opts) {
       assetIdentifier: opts.assetIdentifier,
       rune: opts.rune,
       address: opts.address,
-      filters: opts.filters
+      filters: opts.filters,
+      fetchEvents: opts.fetchEvents,
+      sleep: opts.sleep,
+      emptyBackoffMs: opts.intervalMs,
+      signal,
+      onBatch: async (events, ctx) => {
+        if (events.length === 0 && ctx.reorgs.length === 0)
+          return;
+        await deliver({
+          events,
+          cursor: ctx.cursor,
+          tip: ctx.tip,
+          reorgs: [...ctx.reorgs]
+        });
+      }
     });
-    const checkpoint = envelope.next_cursor ?? cursor;
-    if (envelope.events.length > 0 || envelope.reorgs.length > 0) {
-      yield {
-        events: envelope.events,
-        cursor: checkpoint,
-        tip: envelope.tip,
-        reorgs: envelope.reorgs
-      };
-    }
-    const advanced = checkpoint !== null && checkpoint !== cursor;
-    cursor = checkpoint;
-    if (!advanced && envelope.events.length === 0) {
-      if (opts.signal?.aborted)
-        return;
-      await sleep(opts.intervalMs, opts.signal);
-    }
+    assertNotStalled(result, signal);
+  }, opts.signal);
+}
+function assertNotStalled(result, signal, bounds = {}) {
+  if (signal.aborted)
+    return;
+  if (bounds.maxPages !== undefined && (bounds.pages ?? 0) >= bounds.maxPages) {
+    return;
   }
+  if (bounds.maxEmptyPolls !== undefined && result.emptyPolls >= bounds.maxEmptyPolls) {
+    return;
+  }
+  throw new StreamsServerError(`Streams returned events at cursor ${result.cursor ?? "(start)"} but the cursor did not advance, so the stream stopped instead of re-reading the same page.`, 0, undefined, "CURSOR_STALLED");
 }
 async function* streamStreamsEvents(opts) {
-  const sleep = opts.sleep ?? defaultSleep;
-  const emptyBackoffMs = opts.emptyBackoffMs ?? 500;
-  const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;
-  const maxEmptyPolls = opts.maxEmptyPolls ?? Number.POSITIVE_INFINITY;
-  let cursor = opts.fromCursor ?? null;
-  let pages = 0;
-  let emptyPolls = 0;
-  while (pages < maxPages && emptyPolls < maxEmptyPolls && !opts.signal?.aborted) {
-    const envelope = await opts.fetchEvents({
-      cursor,
-      limit: opts.batchSize,
+  yield* pullFromLoop(async (deliver, signal) => {
+    const result = await consumeStreamsEvents({
+      fromCursor: opts.fromCursor,
+      batchSize: opts.batchSize,
       chain: opts.chain,
       types: opts.types,
       notTypes: opts.notTypes,
@@ -806,29 +882,27 @@ async function* streamStreamsEvents(opts) {
       assetIdentifier: opts.assetIdentifier,
       rune: opts.rune,
       address: opts.address,
-      filters: opts.filters
+      filters: opts.filters,
+      fetchEvents: opts.fetchEvents,
+      sleep: opts.sleep,
+      emptyBackoffMs: opts.emptyBackoffMs,
+      maxPages: opts.maxPages,
+      maxEmptyPolls: opts.maxEmptyPolls,
+      signal,
+      onBatch: async (events) => {
+        for (const event of events) {
+          if (signal.aborted)
+            return;
+          await deliver(event);
+        }
+      }
     });
-    pages++;
-    for (const event of envelope.events) {
-      if (opts.signal?.aborted)
-        return;
-      yield event;
-    }
-    const nextCursor = envelope.next_cursor;
-    if (nextCursor && nextCursor !== cursor) {
-      cursor = nextCursor;
-      emptyPolls = 0;
-      continue;
-    }
-    if (envelope.events.length === 0) {
-      emptyPolls++;
-      if (emptyPolls >= maxEmptyPolls || pages >= maxPages)
-        return;
-      await sleep(emptyBackoffMs, opts.signal);
-      continue;
-    }
-    return;
-  }
+    assertNotStalled(result, signal, {
+      maxPages: opts.maxPages,
+      maxEmptyPolls: opts.maxEmptyPolls,
+      pages: result.pages
+    });
+  }, opts.signal);
 }
 
 // src/streams/decode.ts
@@ -1061,8 +1135,14 @@ function subscribeStreamsEvents(opts) {
   const baseDelayMs = opts.reconnectDelayMs ?? params.reconnectDelayMs ?? 1000;
   const staleAfterMs = opts.staleAfterMs ?? params.staleAfterMs ?? SUBSCRIBE_DEFAULT_STALE_AFTER_MS;
   let attempt = 0;
+  const emit = (state) => {
+    try {
+      params.onState?.(state);
+    } catch {}
+  };
   const run = async () => {
     while (!controller.signal.aborted) {
+      emit("connecting");
       try {
         const url = `${opts.baseUrl}/v1/streams/events/stream${buildQuery({
           chain: params.chain === "bitcoin" ? "bitcoin" : undefined,
@@ -1084,6 +1164,7 @@ function subscribeStreamsEvents(opts) {
           fetchImpl: opts.fetchImpl,
           staleAfterMs,
           mapError: mapStreamsError,
+          onOpen: () => emit("open"),
           onFrame: async (frame) => {
             attempt = 0;
             if (frame.event === "ping" || !frame.data)
@@ -1112,6 +1193,8 @@ function subscribeStreamsEvents(opts) {
             cursor = parsed.event.cursor ?? cursor;
           }
         });
+        if (!controller.signal.aborted)
+          emit("reconnecting");
         await sleep(reconnectDelay(attempt, baseDelayMs, undefined, opts.random), controller.signal);
         attempt += 1;
       } catch (err) {
@@ -1120,13 +1203,14 @@ function subscribeStreamsEvents(opts) {
         params.onError?.(err);
         if (isTerminal(err))
           throw err;
+        emit("reconnecting");
         const retryAfterSeconds = err.retryAfterSeconds;
         await sleep(reconnectDelay(attempt, baseDelayMs, retryAfterSeconds, opts.random), controller.signal);
         attempt += 1;
       }
     }
   };
-  const done = run();
+  const done = run().finally(() => emit("closed"));
   done.catch(() => {});
   const unsubscribe = () => controller.abort();
   return Object.assign(unsubscribe, { done });
@@ -1144,6 +1228,7 @@ async function readSse(opts) {
   if (!res.body) {
     throw new StreamsServerError("Streams SSE response has no body.", 0);
   }
+  opts.onOpen?.();
   for await (const frame of parseSseFrames(res.body, opts.signal, opts.staleAfterMs)) {
     await opts.onFrame(frame);
   }
@@ -1219,6 +1304,33 @@ function parseFrame(raw) {
 `) : undefined };
 }
 
+// src/streams/timeout-fetch.ts
+var STREAMS_CONNECT_TIMEOUT_MS = 30000;
+function withConnectTimeout(fetchImpl, timeoutMs) {
+  if (!(timeoutMs > 0) || !Number.isFinite(timeoutMs))
+    return fetchImpl;
+  return async (input, init) => {
+    const callerSignal = init?.signal ?? undefined;
+    const timeout = new AbortController;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      timeout.abort();
+    }, timeoutMs);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, timeout.signal]) : timeout.signal;
+    try {
+      return await fetchImpl(input, { ...init, signal });
+    } catch (err) {
+      if (timedOut && !callerSignal?.aborted) {
+        throw new StreamsServerError(`No response headers within ${timeoutMs}ms. Retryable.`, 0, undefined, "REQUEST_TIMEOUT");
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+
 // src/streams/client.ts
 function cursorTuple(cursor) {
   if (!cursor)
@@ -1264,7 +1376,7 @@ function createStreamsClient(options) {
     "x-sl-origin": origin,
     ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
   });
-  const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
+  const fetchImpl = withConnectTimeout(options.fetchImpl ?? ((input, init) => fetch(input, init)), options.connectTimeoutMs ?? STREAMS_CONNECT_TIMEOUT_MS);
   const verify = options.verify;
   const verifyMode = verify === false ? "off" : verify === undefined ? "lenient" : "strict";
   if (verify === true && baseUrl.startsWith("http:") && !isLoopbackUrl(baseUrl)) {
@@ -1575,5 +1687,5 @@ export {
   decode
 };
 
-//# debugId=C74383F8F8E34A3564756E2164756E21
+//# debugId=8BCAE1BCFFCE4BBA64756E2164756E21
 //# sourceMappingURL=index.js.map