@secondlayer/sdk 6.0.0 → 6.1.0

package/dist/streams/index.d.ts

@@ -71,6 +71,11 @@ type PrintPayload = {
 *  parent `StreamsEvent`. */
 type StreamsEventPayload = StxTransferPayload | StxMintPayload | StxBurnPayload | StxLockPayload | FtTransferPayload | FtMintPayload | FtBurnPayload | NftTransferPayload | NftMintPayload | NftBurnPayload | PrintPayload;
 type StreamsEventBase = {
+	/**
+	* Globally unique, monotonic position of this event (`<block>:<index>`). Use
+	* it as the primary key of your projection rows — replaying a batch then
+	* upserts cleanly. Don't synthesize your own id from `tx_id`/`event_index`.
+	*/
 	cursor: string
 	block_height: number
 	block_hash: string
@@ -167,9 +172,32 @@ type StreamsEventsStreamParams = {
 	maxEmptyPolls?: number
 	signal?: AbortSignal
 };
+/**
+* The checkpoint the SDK computes for a batch. Persist `cursor` inside the same
+* transaction as your projection writes, then resume from it via `fromCursor`.
+* It is the position to advance to: `next_cursor` normally, or the last
+* finalized event when `finalizedOnly` is set.
+*/
+type StreamsBatchContext = {
+	cursor: string | null
+};
+/**
+* The checkpoint for a reorg rollback. Persist `cursor` (the rewind position)
+* inside the same transaction as your rollback so the two commit atomically.
+*/
+type StreamsReorgContext = {
+	cursor: string
+};
 type StreamsEventsConsumeParams = {
 	fromCursor?: string | null
 	mode?: "tail" | "bounded"
+	/**
+	* Emit only finalized (immutable) events and never surface reorgs. The SDK
+	* checkpoints at the last finalized event and re-reads the unfinalized tail
+	* until it settles. Trades finality lag for zero reorg handling; `onReorg` is
+	* ignored.
+	*/
+	finalizedOnly?: boolean
 	types?: readonly StreamsEventType[]
 	notTypes?: readonly StreamsEventType[]
 	contractId?: StreamsFilterValue
@@ -177,7 +205,20 @@ type StreamsEventsConsumeParams = {
 	recipient?: StreamsFilterValue
 	assetIdentifier?: string
 	batchSize?: number
-	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined
+	/**
+	* Apply a page of canonical events. Persist `ctx.cursor` in the same
+	* transaction as your writes. Returning a cursor overrides `ctx.cursor` as
+	* the resume point (advanced manual control); returning nothing uses it.
+	*/
+	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
+	/**
+	* Roll your projection back to `reorg.fork_point_height`, persisting
+	* `ctx.cursor` in the same transaction. Called once per *new* reorg
+	* (deduped in-memory, fork-ascending) before the SDK rewinds and re-reads the
+	* now-canonical events. Omit it to ignore reorgs (events stay canonical, but
+	* stale rows from an orphaned fork are left in place).
+	*/
+	onReorg?: (reorg: StreamsReorg, ctx: StreamsReorgContext) => Promise<void> | void
 	emptyBackoffMs?: number
 	maxPages?: number
 	maxEmptyPolls?: number
@@ -579,5 +620,24 @@ type DecodedEventColumns = {
 	/** JSONB overflow for non-flat types (e.g. print's decoded value). */
 	payload?: unknown
 };
+/**
+* Helpers for Streams cursors. A cursor is the opaque `<block>:<index>` string
+* that marks a position in the event stream; treat the format as an
+* implementation detail and go through these helpers instead of string-building
+* it at call sites.
+*/
+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`.
+	*/
+	atHeight(height: number): string
+	/** Parse a `<block>:<index>` cursor. Throws `ValidationError` if malformed. */
+	parse(cursor: string): {
+		blockHeight: number
+		eventIndex: number
+	}
+};
 type DecodedEventRow = DecodedFtTransfer | DecodedNftTransfer | DecodedStxTransfer | DecodedStxMint | DecodedStxBurn | DecodedStxLock | DecodedFtMint | DecodedFtBurn | DecodedNftMint | DecodedNftBurn | DecodedPrint;
-export { isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, createStreamsClient, ValidationError, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, STREAMS_EVENT_TYPES, RateLimitError, NftTransferPayload, NftTransferEvent, FtTransferPayload, FtTransferEvent, FetchLike, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, AuthError };
+export { isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, createStreamsClient, ValidationError, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, STREAMS_EVENT_TYPES, RateLimitError, NftTransferPayload, NftTransferEvent, FtTransferPayload, FtTransferEvent, FetchLike, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns, Cursor, AuthError };