@secondlayer/sdk 6.0.0 → 6.1.0

package/dist/index.d.ts

@@ -417,6 +417,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
@@ -513,9 +518,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
@@ -523,7 +551,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
@@ -979,6 +1020,25 @@ 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;
 /**
 * Typed client for the Foundation Datasets REST API (`/v1/datasets/*`).
@@ -1103,7 +1163,9 @@ declare class Datasets extends BaseClient {
 		summary: DatasetRow
 	}>;
 	private get;
-	private buildParams;
+	/** Map camelCase filter fields to snake_case query keys (dropping pagination
+	*  controls) and build the canonical query suffix. */
+	private paramsToQuery;
 	private cursorDataset;
 }
 import { SubgraphAgentSchema as SubgraphAgentSchema3, SubgraphSpecFormat as SubgraphSpecFormat2, SubgraphSpecOptions as SubgraphSpecOptions3 } from "@secondlayer/shared/subgraphs/spec";
@@ -1224,4 +1286,4 @@ declare function toJsonSafe(value: unknown): unknown;
 /** Decode a hex-encoded Clarity value to JSON-safe JS (uints as strings,
 *  buffers as `0x…` hex, tuples as objects). Returns the input hex on failure. */
 declare function decodeClarityValue(hex: string): unknown;
-export { verifyWebhookSignature, toJsonSafe, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, createStreamsClient, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, SecondLayerOptions, SecondLayer, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, RateLimitError, Pox4CallsParams, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, IndexTip, IndexEventType, IndexEvent, IndexContractCall, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, DeliveryRow2 as DeliveryRow, 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, DeadRow2 as DeadRow, Datasets, DatasetRow, CursorListParams, CursorEnvelope, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, CURSOR_SLUGS, AuthError, ApiError };
+export { verifyWebhookSignature, toJsonSafe, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, createStreamsClient, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, SecondLayerOptions, SecondLayer, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, RateLimitError, Pox4CallsParams, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, IndexTip, IndexEventType, IndexEvent, IndexContractCall, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, DeliveryRow2 as DeliveryRow, 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, DeadRow2 as DeadRow, Datasets, DatasetRow, CursorListParams, CursorEnvelope, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, CURSOR_SLUGS, AuthError, ApiError };