@secondlayer/sdk 9.0.1 → 10.0.0

package/dist/streams/index.d.ts

@@ -115,8 +115,11 @@ interface ConsumerSink<Tx = unknown> {
 	* same `rewindCursor` (the lowest fork point) but its own
 	* `forkPointHeight` — scope the undo by `forkPointHeight` only (contract
 	* invariant #11), and expect re-application after a crash (#10).
+	*
+	* `rewindCursor` is `null` only for a fork at genesis: clear the
+	* checkpoint so the next run starts from the first event.
 	*/
-	rollback(forkPointHeight: number, rewindCursor: string): Promise<void>;
+	rollback(forkPointHeight: number, rewindCursor: string | null): Promise<void>;
 }
 /** `ctx` gains `tx` exactly when a sink is attached; without one the shape
 *  is unchanged (an intersection with `unknown` is an identity, so
@@ -356,11 +359,41 @@ type StreamsEventsSubscribeParams = {
 	filters?: StreamsFilterMap;
 	/** Abort to unsubscribe (the returned function does the same). */
 	signal?: AbortSignal;
-	/** Called for each pushed event, in order. */
+	/**
+	* Called for each pushed event, in order. The resume cursor advances only
+	* after this resolves, so a handler that throws sees the same event again
+	* on reconnect (at-least-once). Key durable writes by `cursor`.
+	*/
 	onEvent: (event: StreamsEvent) => void | Promise<void>;
-	/** Called on a connection error; the subscription auto-reconnects from the
-	*  last delivered cursor unless the signal has aborted. */
+	/**
+	* Called on every failure. Transport errors (dropped socket, 5xx, 429, a
+	* stale connection, a throwing handler) reconnect from the last handled
+	* cursor with exponential backoff. Errors that a retry cannot fix (401,
+	* 4xx, a bad signature) end the subscription and reject its `done`.
+	*/
 	onError?: (err: unknown) => 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`.
+	*/
+	reconnectDelayMs?: number;
+	/**
+	* Reconnect when no frame (pings included) arrives for this long (default
+	* 60000, three server heartbeats). Catches a half-open socket that never
+	* errors; set it above your instance's heartbeat interval.
+	*/
+	staleAfterMs?: number;
+};
+/**
+* Handle for a live subscription: call it to unsubscribe. `done` resolves
+* after unsubscribe (or the signal aborting) and rejects with the error that
+* ended the loop when a retry could not fix it, so a worker can `await`
+* it instead of polling for silence.
+*/
+type StreamsSubscription = {
+	(): void;
+	done: Promise<void>;
 };
 /**
 * The checkpoint the SDK computes for a batch. Persist `cursor` inside the same
@@ -425,8 +458,11 @@ type StreamsBatchContext = ConsumerBatchContext;
 * The checkpoint for a reorg rollback. Persist `cursor` (the rewind position)
 * inside the same transaction as your rollback so the two commit atomically.
 */
+/** `cursor` is the rewind position the loop resumes from after `onReorg`:
+*  the foot of the fork point, or `null` for a fork at genesis. Persist it
+*  in the same transaction as the rollback. */
 type StreamsReorgContext = {
-	cursor: string;
+	cursor: string | null;
 };
 type StreamsEventsConsumeParams<
 	TTx = never,
@@ -494,12 +530,23 @@ type StreamsEventsConsumeParams<
 	onBatch?: (events: D extends true ? IndexEvent[] : StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext & WithSinkTx<TTx>) => 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).
+	* `ctx.cursor` in the same transaction. Called once per *new* reorg at or
+	* below the checkpoint (deduped in-memory, fork-ascending) before the SDK
+	* rewinds and re-reads the now-canonical events. A reorg whose fork sits
+	* above the checkpoint is not a rollback (nothing past it was written) and
+	* is skipped. Omit it to ignore reorgs (events stay canonical, but stale
+	* rows from an orphaned fork are left in place).
+	*
+	* With `onReorg` or a `sink` attached, every empty page also polls
+	* `reorgs.list` (one extra request per idle poll) so a fork that lands
+	* while the consumer idles at the tip is rolled back too.
 	*/
 	onReorg?: (reorg: StreamsReorg, ctx: StreamsReorgContext) => Promise<void> | void;
+	/** Deepest rewind one reorg may make below the checkpoint before the loop
+	*  refuses with `ValidationError`. Default 1000 blocks. The fork point is
+	*  server supplied and drives a delete on every declared table, so raise
+	*  this only for a source you trust. */
+	maxRollbackDepth?: number;
 	/** Page-fetch retries after the first failure (429/5xx/network only —
 	*  4xx and handler throws always propagate). Default 3; `0` disables. */
 	retryCount?: number;
@@ -562,8 +609,16 @@ type StreamsEventsReplayParams = {
 	* Called once per finalized dump file, in block order, before live tailing.
 	* Process the parquet with your own tooling (e.g. DuckDB) — the SDK does not
 	* decode parquet. Use `client.dumps.download(file)` to fetch + verify bytes.
+	*
+	* Delivery is file-granular and at-least-once: a file whose range straddles
+	* `from` is handed over whole. `ctx.from` is that cursor (`null` from
+	* genesis); skip rows at or below it, or key rows by `cursor` so a re-run
+	* is an idempotent no-op. Files ending at or below `from` are not handed
+	* over at all.
 	*/
-	onDumpFile: (file: StreamsDumpFile) => Promise<void> | void;
+	onDumpFile: (file: StreamsDumpFile, ctx: {
+		from: string | null;
+	}) => 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;
 	/**
@@ -699,9 +754,11 @@ type StreamsClient = {
 		* Subscribe to the real-time SSE push surface. Calls `onEvent` for each new
 		* canonical event as the server pushes it (chain cadence, not poll-bounded),
 		* and verifies each frame's inline ed25519 signature when the client was
-		* created with `verify`. Returns an unsubscribe function.
+		* created with `verify`. Returns an unsubscribe function whose `done`
+		* settles when the loop ends. Not reorg-aware: an event delivered then
+		* orphaned is never retracted. Durable writers use `consume()`.
 		*/
-		subscribe(params: StreamsEventsSubscribeParams): () => void;
+		subscribe(params: StreamsEventsSubscribeParams): StreamsSubscription;
 	};
 	blocks: {
 		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>;
@@ -717,6 +774,8 @@ type StreamsClient = {
 type CreateStreamsClientOptions = {
 	apiKey?: string;
 	baseUrl?: string;
+	/** Deploy origin label sent as `x-sl-origin` (telemetry). Defaults to `cli`. */
+	origin?: "cli" | "mcp" | "session";
 	fetchImpl?: FetchLike2;
 	/**
 	* Public base URL for bulk parquet dumps (the R2/CDN bucket root). Required
@@ -844,26 +903,30 @@ declare class ApiError extends SecondLayerError {
 	body?: unknown;
 	constructor(status: number, message: string, body?: unknown, code?: string, options?: SecondLayerErrorOptions);
 }
-/** Thrown on a 401 — by both the platform clients and Streams. */
+/** Thrown on a 401 by both the instance clients and Streams. Carries the
+*  server's `{error, code}` envelope when it sent one, so a revoked token reads
+*  differently from a missing one. */
 declare class AuthError extends ApiError {
 	readonly status: 401;
-	constructor(message?: string);
+	constructor(message?: string, body?: unknown, code?: string);
 }
-/** Thrown on a 429 — by both the platform clients and Streams. `retryable`,
+/** Thrown on a 429 by both the instance clients and Streams. `retryable`,
 *  with `retryAfterSeconds` parsed from the `Retry-After` header when sent. */
 declare class RateLimitError extends ApiError {
 	/** Raw `Retry-After` header value (seconds or HTTP-date). */
 	readonly retryAfter?: string | undefined;
 	readonly status: 429;
-	constructor(message?: string, retryAfter?: string | undefined);
+	constructor(message?: string, retryAfter?: string | undefined, body?: unknown, code?: string);
 }
-/** Thrown on a 4xx the caller can fix (bad cursor, bad params). Never retried. */
+/** Thrown on a 4xx the caller can fix (bad cursor, bad params). Never retried.
+*  `code` is the server's machine-readable code when the envelope carried one. */
 declare class ValidationError extends ApiError {
-	constructor(message: string, status: number, body?: unknown);
+	constructor(message: string, status: number, body?: unknown, code?: string);
 }
-/** Thrown on a 5xx from the Streams API. `retryable`. */
+/** Thrown on a 5xx from the Streams API, and on a failed signing-key fetch.
+*  `retryable`: the page retry policy tries again. */
 declare class StreamsServerError extends ApiError {
-	constructor(message: string, status: number, body?: unknown);
+	constructor(message: string, status: number, body?: unknown, code?: string);
 }
 /** Thrown when response signature verification is enabled and fails. */
 declare class StreamsSignatureError extends SecondLayerError {
@@ -875,7 +938,9 @@ import { DecodedEventColumns, DecodedEventRow, DecodedFtBurn, DecodedFtBurnPaylo
 * 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.
+* it at call sites. Encode/decode and the rewind sentinel come from the
+* canonical codec in `@secondlayer/shared` so the SDK cannot accept a spelling
+* the server would 400, or rewind to a different foot than Index/Streams.
 */
 declare const Cursor: {
 	/**
@@ -887,18 +952,23 @@ declare const Cursor: {
 	* 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
+	* Encoded as `blockEndCursor(height - 1)` 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(0)` is `null`: the pre-genesis position both consume loops
+	* accept as "read everything from the first event". There is no string
+	* cursor below `0:0`, and `0:0` itself is exclusive, so returning it here
+	* skipped the genesis event.
 	*/
-	atHeight(height: number): string;
+	atHeight(height: number): string | null;
 	/** Parse a `<block>:<index>` cursor. Throws `ValidationError` if malformed. */
 	parse(cursor: string): {
 		blockHeight: number;
 		eventIndex: number;
 	};
 };
-export { isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decode, createStreamsClient, ValidationError, StreamsTip, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, STREAMS_EVENT_TYPES, RateLimitError, NftTransferPayload2 as NftTransferPayload, NftTransferEvent, FtTransferPayload2 as FtTransferPayload, FtTransferEvent, FetchLike2 as 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, ConsumerBatchContext, AuthError };
+export { isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decode, createStreamsClient, ValidationError, StreamsTip, StreamsSubscription, StreamsSignatureError, StreamsServerError, StreamsReorgsListParams, StreamsReorgsListEnvelope, StreamsReorgContext, StreamsReorg, StreamsEventsSubscribeParams, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsListEnvelope, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsDumpsManifest, StreamsDumps, StreamsDumpFile, StreamsConsumeParams, StreamsClient, StreamsCanonicalBlock, StreamsBatchContext, StreamsBatch, STREAMS_EVENT_TYPES, RateLimitError, NftTransferPayload2 as NftTransferPayload, NftTransferEvent, FtTransferPayload2 as FtTransferPayload, FtTransferEvent, FetchLike2 as 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, ConsumerBatchContext, AuthError };