@secondlayer/sdk 6.23.1 → 6.24.1

package/dist/index.d.ts

@@ -488,6 +488,12 @@ type StreamsReorg = {
 		from: string
 		to: string
 	}
+	/**
+	* First position of the new canonical chain at the fork, `fork:0`
+	* (INCLUSIVE). Not an exclusive resume token — resuming directly from it
+	* skips `fork:0`. The consumer rewinds to the foot of `fork_point_height`
+	* (`Cursor.atHeight`) to re-read the new run from `fork:0` inclusive.
+	*/
 	new_canonical_tip: string
 };
 type StreamsEventsEnvelope = {
@@ -649,6 +655,13 @@ type StreamsEventsReplayParams = {
 	onDumpFile: (file: StreamsDumpFile) => Promise<void> | void
 	/** Called per live page after the dump phase, like `consume`. */
 	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined
+	/**
+	* Called when the live-tail phase (after the dump backfill) crosses a reorg,
+	* before the cursor rewinds and re-reads the now-canonical events — same
+	* contract as `consume`. The dump-backfill phase is finalized and never
+	* reorgs; omit this to leave stale rows from an orphaned fork in place.
+	*/
+	onReorg?: (reorg: StreamsReorg, ctx: StreamsReorgContext) => Promise<void> | void
 	mode?: "tail" | "bounded"
 	batchSize?: number
 	emptyBackoffMs?: number
@@ -863,9 +876,12 @@ type IndexTip = {
 /**
 * A chain reorg overlapping a returned page's height range. Height-keyed feeds
 * (`/transactions`, `/contract-calls`, `/stacking`) populate this so a consumer
-* can reconcile: roll back the rows whose `block_height:tx_index` cursor falls in
-* `orphaned_range`, then re-fetch from `new_canonical_tip`. Empty when the page
-* spans no reorg.
+* can reconcile: roll back every row at `block_height >= fork_point_height`
+* (the whole fork block is replaced, so the rollback is inclusive of the fork
+* height), then re-read the canonical run from the foot of `fork_point_height`.
+* The SDK consumers do exactly this — they rewind to `Cursor.atHeight(
+* fork_point_height)`, an exclusive cursor that re-reads from `fork:0`
+* inclusive. Empty when the page spans no reorg.
 */
 type IndexReorg = {
 	id: string
@@ -878,7 +894,12 @@ type IndexReorg = {
 		from: string
 		to: string
 	}
-	/** New canonical tip cursor to resume from. */
+	/**
+	* First position of the new canonical chain at the fork, `fork:0`
+	* (INCLUSIVE). Not an exclusive resume token — resuming a `(bh,ei) > cursor`
+	* read directly from it would skip `fork:0`. To re-read the new run, rewind
+	* to the foot of `fork_point_height` (`Cursor.atHeight`), not to this value.
+	*/
 	new_canonical_tip: string
 };
 type IndexUsage = {
@@ -2018,9 +2039,20 @@ type DecodedEventColumns = {
 */
 declare const Cursor: {
 	/**
-	* Cursor at the foot of `height`. Resuming from it re-reads every event
-	* strictly above block `height` (cursors are exclusive), so this is the
-	* position to rewind to after a reorg whose fork point is `height`.
+	* Cursor at the foot of `height` — a position that sorts strictly below the
+	* first event of block `height` (`height:0`) and strictly above every event
+	* of block `height - 1`. Cursors are exclusive (`(bh,ei) > after`), so
+	* resuming from it re-reads the entire canonical run starting at `height:0`
+	* inclusive. This is the position to rewind to after a reorg whose fork point
+	* is `height`: the new canonical block at `height` carries a fresh first
+	* event at `(height, 0)` that the consumer MUST re-read.
+	*
+	* Encoded as `${height-1}:${SENTINEL}` rather than the seemingly-natural
+	* `${height}:0` — that earlier form was an off-by-one: being exclusive, it
+	* skipped `(height, 0)`, silently dropping the fork block's first row on
+	* every reorg. The sentinel is int4 max (the `event_index`/`tx_index` column
+	* type), larger than any real index, so nothing at `height - 1` survives the
+	* keyset and the next returned row is exactly `(height, 0)`.
 	*/
 	atHeight(height: number): string
 	/** Parse a `<block>:<index>` cursor. Throws `ValidationError` if malformed. */

package/dist/index.js

@@ -491,9 +491,12 @@ class StreamsSignatureError extends Error {
 }
 
 // src/streams/cursor.ts
+var REWIND_FOOT_INDEX_SENTINEL = 2147483647;
 var Cursor = {
   atHeight(height) {
-    return `${height}:0`;
+    if (height <= 0)
+      return "0:0";
+    return `${height - 1}:${REWIND_FOOT_INDEX_SENTINEL}`;
   },
   parse(cursor) {
     const parts = cursor.split(":");
@@ -1637,6 +1640,7 @@ function createStreamsClient(options) {
           batchSize: params.batchSize ?? 100,
           fetchEvents,
           onBatch: params.onBatch,
+          onReorg: params.onReorg,
           emptyBackoffMs: params.emptyBackoffMs,
           maxPages: params.maxPages,
           maxEmptyPolls: params.maxEmptyPolls,
@@ -2501,5 +2505,5 @@ export {
   ApiError
 };
 
-//# debugId=949AD5368987433264756E2164756E21
+//# debugId=83F19CEB4B72C83564756E2164756E21
 //# sourceMappingURL=index.js.map