@secondlayer/sdk 6.42.0 → 6.44.0

package/dist/index.d.ts

@@ -686,7 +686,10 @@ type StreamsEventsSubscribeParams = {
 * block as `${height - 1}:<sentinel>`, so a rewound cursor parses to a
 * position that was never reached.
 */
-type ConsumerBatchContext = {
+type ConsumerBatchContext<
+	TTip = unknown,
+	TReorg = unknown
+> = {
 	/** Checkpoint to commit alongside your rows. */
 	cursor: string | null
 	/** Highest canonical block the sweep has reached. `null` before the first
@@ -696,6 +699,19 @@ type ConsumerBatchContext = {
 	tipHeight: number
 	/** `tipHeight - height`, floored at 0. `null` until `height` is known. */
 	blocksBehind: number | null
+	/**
+	* The full tip for this page — `StreamsTip` or `IndexTip` depending on the
+	* surface. Exposed here so a handler never needs the `envelope` parameter,
+	* which is the only way to reach it today and is also how the worst
+	* `finalizedOnly` mistake becomes reachable (`return envelope.next_cursor`
+	* jumps the cursor past events that were filtered out and never delivered).
+	*/
+	tip: TTip
+	/**
+	* Reorgs reported alongside this page; empty when none. Rollback still
+	* belongs in `onReorg` — this is for observability inside a batch.
+	*/
+	reorgs: readonly TReorg[]
 };
 /** @deprecated Use {@link ConsumerBatchContext} — the Index and Streams loops
 *  share one shape now. Kept as an alias so existing annotations compile. */
@@ -1539,8 +1555,8 @@ type IndexTransaction = {
 		cause: number
 	}
 };
-type TransactionsEnvelope = {
-	transactions: IndexTransaction[]
+type TransactionsEnvelope<TRow = IndexTransaction> = {
+	transactions: TRow[]
 	next_cursor: string | null
 	tip: IndexTip
 	reorgs: IndexReorg[]
@@ -1549,7 +1565,17 @@ type TransactionEnvelope = {
 	transaction: IndexTransaction
 	tip: IndexTip
 };
+/** Transaction columns that survive any projection. */
+type TransactionAlwaysFields = "cursor" | "block_height" | "tx_id";
+/** A Transaction row narrowed to the requested columns plus the always-present ones. */
+type TransactionFields<F extends keyof IndexTransaction & string> = Pick<IndexTransaction, (F | TransactionAlwaysFields) & keyof IndexTransaction>;
 type TransactionsListParams = {
+	/**
+	* Columns to return. The server projects the row, so an unrequested column
+	* is physically absent — and the narrowing overload on `list` makes reading
+	* one a compile error rather than `undefined` at runtime.
+	*/
+	fields?: readonly (keyof IndexTransaction & string)[]
 	cursor?: string | null
 	fromCursor?: string | null
 	limit?: number
@@ -1802,8 +1828,8 @@ type IndexSbtcSummary = {
 	total_locked_sats: string
 	sbtc_supply_sats: string | null
 };
-type SbtcDepositsEnvelope = {
-	deposits: IndexSbtcDeposit[]
+type SbtcDepositsEnvelope<TRow = IndexSbtcDeposit> = {
+	deposits: TRow[]
 	next_cursor: string | null
 	tip: IndexTip
 	reorgs: IndexReorg[]
@@ -1814,8 +1840,8 @@ type SbtcDepositEnvelope = {
 	deposit: IndexSbtcDepositDetail
 	tip: IndexTip
 };
-type SbtcWithdrawalsEnvelope = {
-	withdrawals: IndexSbtcWithdrawal[]
+type SbtcWithdrawalsEnvelope<TRow = IndexSbtcWithdrawal> = {
+	withdrawals: TRow[]
 	next_cursor: string | null
 	tip: IndexTip
 	reorgs: IndexReorg[]
@@ -1847,12 +1873,32 @@ type SbtcDepositsListParams = {
 	bitcoinTxid?: string
 	fromHeight?: number
 	toHeight?: number
+	/**
+	* Columns to return. The server projects the row, so an unrequested column
+	* is physically absent — and the narrowing overload on `list` makes reading
+	* one a compile error rather than `undefined` at runtime.
+	*/
+	fields?: readonly (keyof IndexSbtcDeposit & string)[]
 };
+/** Deposit columns that survive any projection — pagination needs them. */
+type SbtcDepositAlwaysFields = "cursor" | "block_height";
+/** A deposit row narrowed to the requested columns plus the always-present ones. */
+type SbtcDepositFields<F extends keyof IndexSbtcDeposit & string> = Pick<IndexSbtcDeposit, (F | SbtcDepositAlwaysFields) & keyof IndexSbtcDeposit>;
 type SbtcDepositsWalkParams = Omit<SbtcDepositsListParams, "limit"> & {
 	batchSize?: number
 	signal?: AbortSignal
 };
+/** SbtcWithdrawal columns that survive any projection. */
+type SbtcWithdrawalAlwaysFields = "cursor" | "request_id";
+/** A SbtcWithdrawal row narrowed to the requested columns plus the always-present ones. */
+type SbtcWithdrawalFields<F extends keyof IndexSbtcWithdrawal & string> = Pick<IndexSbtcWithdrawal, (F | SbtcWithdrawalAlwaysFields) & keyof IndexSbtcWithdrawal>;
 type SbtcWithdrawalsListParams = {
+	/**
+	* Columns to return. The server projects the row, so an unrequested column
+	* is physically absent — and the narrowing overload on `list` makes reading
+	* one a compile error rather than `undefined` at runtime.
+	*/
+	fields?: readonly (keyof IndexSbtcWithdrawal & string)[]
 	cursor?: string | null
 	fromCursor?: string | null
 	limit?: number
@@ -1892,6 +1938,11 @@ type SbtcDepositsConsumeParams<TTx = never> = Omit<SbtcDepositsListParams, "curs
 *  events, scoreboard). The only productized decoded sBTC peg feed on Stacks. */
 interface SbtcResource {
 	deposits: {
+		/** Narrowing overload: `fields` shrinks the row type to exactly the
+		*  requested columns plus {@link SbtcDepositAlwaysFields}. */
+		list<const F extends keyof IndexSbtcDeposit & string>(params: SbtcDepositsListParams & {
+			fields: readonly F[]
+		}): Promise<SbtcDepositsEnvelope<SbtcDepositFields<F>>>
 		list(params?: SbtcDepositsListParams): Promise<SbtcDepositsEnvelope>
 		walk(params?: SbtcDepositsWalkParams): AsyncIterable<IndexSbtcDeposit>
 		/** Checkpointed sweep of completed deposits — append-only, so safe to
@@ -1907,6 +1958,11 @@ interface SbtcResource {
 		get(bitcoinTxid: string): Promise<SbtcDepositEnvelope | null>
 	};
 	withdrawals: {
+		/** Narrowing overload: `fields` shrinks the row type to exactly the
+		*  requested columns plus {@link SbtcWithdrawalAlwaysFields}. */
+		list<const F extends keyof IndexSbtcWithdrawal & string>(params: SbtcWithdrawalsListParams & {
+			fields: readonly F[]
+		}): Promise<SbtcWithdrawalsEnvelope<SbtcWithdrawalFields<F>>>
 		list(params?: SbtcWithdrawalsListParams): Promise<SbtcWithdrawalsEnvelope>
 		walk(params?: SbtcWithdrawalsWalkParams): AsyncIterable<IndexSbtcWithdrawal>
 		/** Fetch a withdrawal's full lifecycle by request id; 404 → null. */
@@ -2011,15 +2067,25 @@ type IndexPox5Event = {
 	/** The full decoded print tuple as JSON. */
 	data: unknown
 };
-type Pox5EventsEnvelope = {
-	events: IndexPox5Event[]
+type Pox5EventsEnvelope<TRow = IndexPox5Event> = {
+	events: TRow[]
 	next_cursor: string | null
 	tip: IndexTip
 	reorgs: IndexReorg[]
 	/** Present only when the PoX-5 decoder is disabled, explaining an empty feed. */
 	notes?: string
 };
+/** Pox5Event columns that survive any projection. */
+type Pox5EventAlwaysFields = "cursor" | "block_height" | "topic";
+/** A Pox5Event row narrowed to the requested columns plus the always-present ones. */
+type Pox5EventFields<F extends keyof IndexPox5Event & string> = Pick<IndexPox5Event, (F | Pox5EventAlwaysFields) & keyof IndexPox5Event>;
 type Pox5EventsListParams = {
+	/**
+	* Columns to return. The server projects the row, so an unrequested column
+	* is physically absent — and the narrowing overload on `list` makes reading
+	* one a compile error rather than `undefined` at runtime.
+	*/
+	fields?: readonly (keyof IndexPox5Event & string)[]
 	cursor?: string | null
 	fromCursor?: string | null
 	limit?: number
@@ -2042,6 +2108,11 @@ type Pox5EventsWalkParams = Omit<Pox5EventsListParams, "limit"> & {
 *  epoch 4.0 hard fork onward (PoX-4's `index.stacking` stream ends there). */
 interface Pox5Resource {
 	events: {
+		/** Narrowing overload: `fields` shrinks the row type to exactly the
+		*  requested columns plus {@link Pox5EventAlwaysFields}. */
+		list<const F extends keyof IndexPox5Event & string>(params: Pox5EventsListParams & {
+			fields: readonly F[]
+		}): Promise<Pox5EventsEnvelope<Pox5EventFields<F>>>
 		list(params?: Pox5EventsListParams): Promise<Pox5EventsEnvelope>
 		walk(params?: Pox5EventsWalkParams): AsyncIterable<IndexPox5Event>
 	};
@@ -2169,7 +2240,16 @@ declare class Index extends BaseClient {
 	/** Full transaction documents: paginated `list`/`walk`, plus `get` by tx_id
 	*  (resolves to null on 404). */
 	readonly transactions: {
-		list: (params?: TransactionsListParams) => Promise<TransactionsEnvelope>
+		/** Narrowing overload: `fields` shrinks the row type to exactly the
+		*  requested columns plus {@link TransactionAlwaysFields}. Declared as
+		*  an overloaded call signature because an arrow property cannot carry
+		*  overloads. */
+		list: {
+			<const F extends keyof IndexTransaction & string>(params: TransactionsListParams & {
+				fields: readonly F[]
+			}): Promise<TransactionsEnvelope<TransactionFields<F>>>
+			(params?: TransactionsListParams): Promise<TransactionsEnvelope>
+		}
 		walk: (params?: TransactionsWalkParams) => AsyncIterable<IndexTransaction>
 		get: (txId: string) => Promise<TransactionEnvelope | null>
 		getProof: (txId: string) => Promise<TransactionProof | null>

package/dist/index.js

@@ -592,12 +592,15 @@ function assertFinalizedCheckpoint(returned, checkpoint) {
     throw new ValidationError(`onBatch returned cursor "${returned}", above the last delivered finalized event${boundary}. With finalizedOnly, events past that point were filtered out and will be re-read once finalized — committing beyond it skips them permanently. Return ctx.cursor (or nothing); never envelope.next_cursor.`, 400);
   }
 }
-function batchContext(cursor, height, tipHeight) {
+function batchContext(cursor, height, tip, reorgs = []) {
+  const tipHeight = tip.block_height;
   return {
     cursor,
     height,
     tipHeight,
-    blocksBehind: height === null ? null : Math.max(0, tipHeight - height)
+    blocksBehind: height === null ? null : Math.max(0, tipHeight - height),
+    tip,
+    reorgs
   };
 }
 var MAX_RETRY_AFTER_MS = 300000;
@@ -699,7 +702,7 @@ async function consumeStreamsEvents(opts) {
     const emitted = finalizedOnly ? envelope.events.filter((event) => event.finalized) : envelope.events;
     const checkpoint = finalizedOnly ? emitted.at(-1)?.cursor ?? cursor : envelope.next_cursor;
     height = emitted.at(-1)?.block_height ?? height;
-    const ctx = batchContext(checkpoint, height, envelope.tip.block_height);
+    const ctx = batchContext(checkpoint, height, envelope.tip, envelope.reorgs);
     opts.onProgress?.(ctx);
     let nextCursor;
     if (opts.sink) {
@@ -860,7 +863,7 @@ async function consumeIndexFeed(opts) {
     const emitted = finalizedOnly ? items.filter((item) => item.block_height <= envelope.tip.finalized_height) : items;
     const checkpoint = finalizedOnly ? emitted.at(-1)?.cursor ?? cursor : envelope.next_cursor;
     height = emitted.at(-1)?.block_height ?? height;
-    const ctx = batchContext(checkpoint, height, envelope.tip.block_height);
+    const ctx = batchContext(checkpoint, height, envelope.tip, envelope.reorgs);
     opts.onProgress?.(ctx);
     let nextCursor;
     if (opts.sink) {
@@ -1177,7 +1180,8 @@ class Index extends BaseClient {
       sender: params.sender,
       contract_id: params.contractId,
       from_height: params.fromHeight,
-      to_height: params.toHeight
+      to_height: params.toHeight,
+      fields: params.fields?.join(",")
     })}`);
   }
   async getTransaction(txId) {
@@ -1229,7 +1233,8 @@ class Index extends BaseClient {
       sender: params.sender,
       bitcoin_txid: params.bitcoinTxid,
       from_height: params.fromHeight,
-      to_height: params.toHeight
+      to_height: params.toHeight,
+      fields: params.fields?.join(",")
     })}`);
   }
   walkSbtcDeposits(params = {}) {
@@ -1249,7 +1254,8 @@ class Index extends BaseClient {
       request_id: params.requestId,
       settlement_confirmed: params.settlementConfirmed,
       from_height: params.fromHeight,
-      to_height: params.toHeight
+      to_height: params.toHeight,
+      fields: params.fields?.join(",")
     })}`);
   }
   walkSbtcWithdrawals(params = {}) {
@@ -1291,7 +1297,8 @@ class Index extends BaseClient {
       bond_index: params.bondIndex,
       reward_cycle: params.rewardCycle,
       from_height: params.fromHeight,
-      to_height: params.toHeight
+      to_height: params.toHeight,
+      fields: params.fields?.join(",")
     })}`);
   }
   walkPox5Events(params = {}) {
@@ -2877,5 +2884,5 @@ export {
   ApiError
 };
 
-//# debugId=E4A30787B92D2A4C64756E2164756E21
+//# debugId=2212082A9E39DB7664756E2164756E21
 //# sourceMappingURL=index.js.map