@secondlayer/sdk 6.43.0 → 6.45.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. */
@@ -1150,6 +1166,7 @@ type IndexUsage = {
 type FtTransfer = {
 	cursor: string
 	block_height: number
+	block_time?: string | null
 	tx_id: string
 	tx_index: number
 	event_index: number
@@ -1160,13 +1177,25 @@ type FtTransfer = {
 	recipient: string
 	amount: string
 };
-type FtTransfersEnvelope = {
-	events: FtTransfer[]
+type FtTransfersEnvelope<TRow = FtTransfer> = {
+	events: TRow[]
 	next_cursor: string | null
 	tip: IndexTip
 	reorgs: IndexReorg[]
 };
+/** Transfer columns that survive any projection — the consume contract
+*  (`cursor`, `block_height`) plus the `event_type` discriminant. */
+type FtTransferAlwaysFields = "cursor" | "block_height" | "event_type";
+/** An ft-transfer row narrowed to the requested columns plus the always-present ones. */
+type FtTransferFields<F extends keyof FtTransfer & string> = Pick<FtTransfer, (F | FtTransferAlwaysFields) & keyof FtTransfer>;
 type FtTransfersListParams = {
+	/**
+	* 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. Omitting
+	* `block_time` also lets the server skip the blocks join.
+	*/
+	fields?: readonly (keyof FtTransfer & string)[]
 	cursor?: string | null
 	fromCursor?: string | null
 	limit?: number
@@ -1183,6 +1212,7 @@ type FtTransfersWalkParams = Omit<FtTransfersListParams, "limit"> & {
 type NftTransfer = {
 	cursor: string
 	block_height: number
+	block_time?: string | null
 	tx_id: string
 	tx_index: number
 	event_index: number
@@ -1193,13 +1223,19 @@ type NftTransfer = {
 	recipient: string
 	value: string
 };
-type NftTransfersEnvelope = {
-	events: NftTransfer[]
+type NftTransfersEnvelope<TRow = NftTransfer> = {
+	events: TRow[]
 	next_cursor: string | null
 	tip: IndexTip
 	reorgs: IndexReorg[]
 };
+/** See {@link FtTransferAlwaysFields}. */
+type NftTransferAlwaysFields = "cursor" | "block_height" | "event_type";
+/** An nft-transfer row narrowed to the requested columns plus the always-present ones. */
+type NftTransferFields<F extends keyof NftTransfer & string> = Pick<NftTransfer, (F | NftTransferAlwaysFields) & keyof NftTransfer>;
 type NftTransfersListParams = {
+	/** Columns to return (see {@link FtTransfersListParams.fields}). */
+	fields?: readonly (keyof NftTransfer & string)[]
 	cursor?: string | null
 	fromCursor?: string | null
 	limit?: number
@@ -1539,8 +1575,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 +1585,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
@@ -1814,8 +1860,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[]
@@ -1862,7 +1908,17 @@ 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
@@ -1922,6 +1978,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. */
@@ -2026,15 +2087,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
@@ -2057,6 +2128,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>
 	};
@@ -2069,14 +2145,44 @@ interface Pox5Resource {
 * no amount filtering and no asset-slug resolution on /v1/index/ft-transfers.
 */
 interface FtTransfersResource {
+	/** Narrowing overload for the callable shorthand — same wire path as
+	*  `list`, so it must narrow identically. */
+	<const F extends keyof FtTransfer & string>(params: FtTransfersListParams & {
+		fields: readonly F[]
+	}): Promise<FtTransfersEnvelope<FtTransferFields<F>>>;
 	(params?: FtTransfersListParams): Promise<FtTransfersEnvelope>;
+	/** Narrowing overload: `fields` shrinks the row type to exactly the
+	*  requested columns plus {@link FtTransferAlwaysFields}. */
+	list<const F extends keyof FtTransfer & string>(params: FtTransfersListParams & {
+		fields: readonly F[]
+	}): Promise<FtTransfersEnvelope<FtTransferFields<F>>>;
 	list(params?: FtTransfersListParams): Promise<FtTransfersEnvelope>;
+	/** Narrowing overload, matching `list`: `walk` forwards `fields` to the
+	*  wire, so without this the yielded rows are stripped while the type
+	*  still promises every column. */
+	walk<const F extends keyof FtTransfer & string>(params: FtTransfersWalkParams & {
+		fields: readonly F[]
+	}): AsyncIterable<FtTransferFields<F>>;
 	walk(params?: FtTransfersWalkParams): AsyncIterable<FtTransfer>;
 }
 /** `index.nftTransfers` — callable shorthand for `.list()` (see {@link FtTransfersResource}). */
 interface NftTransfersResource {
+	/** Narrowing overload for the callable shorthand — same wire path as
+	*  `list`, so it must narrow identically. */
+	<const F extends keyof NftTransfer & string>(params: NftTransfersListParams & {
+		fields: readonly F[]
+	}): Promise<NftTransfersEnvelope<NftTransferFields<F>>>;
 	(params?: NftTransfersListParams): Promise<NftTransfersEnvelope>;
+	/** Narrowing overload: `fields` shrinks the row type to exactly the
+	*  requested columns plus {@link NftTransferAlwaysFields}. */
+	list<const F extends keyof NftTransfer & string>(params: NftTransfersListParams & {
+		fields: readonly F[]
+	}): Promise<NftTransfersEnvelope<NftTransferFields<F>>>;
 	list(params?: NftTransfersListParams): Promise<NftTransfersEnvelope>;
+	/** Narrowing overload, matching `list` (see {@link FtTransfersResource}). */
+	walk<const F extends keyof NftTransfer & string>(params: NftTransfersWalkParams & {
+		fields: readonly F[]
+	}): AsyncIterable<NftTransferFields<F>>;
 	walk(params?: NftTransfersWalkParams): AsyncIterable<NftTransfer>;
 }
 /** `index.events` — callable shorthand for `.list()`; `eventType` is required. */
@@ -2184,7 +2290,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) {
@@ -1058,7 +1061,8 @@ class Index extends BaseClient {
       sender: params.sender,
       recipient: params.recipient,
       from_height: params.fromHeight,
-      to_height: params.toHeight
+      to_height: params.toHeight,
+      fields: params.fields?.join(",")
     })}`);
   }
   async listNftTransfers(params = {}) {
@@ -1071,7 +1075,8 @@ class Index extends BaseClient {
       sender: params.sender,
       recipient: params.recipient,
       from_height: params.fromHeight,
-      to_height: params.toHeight
+      to_height: params.toHeight,
+      fields: params.fields?.join(",")
     })}`);
   }
   async* keysetWalk(params, list, itemsOf) {
@@ -1177,7 +1182,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) {
@@ -1250,7 +1256,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 = {}) {
@@ -1292,7 +1299,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 = {}) {
@@ -2878,5 +2886,5 @@ export {
   ApiError
 };
 
-//# debugId=F96DBA9B81801E0B64756E2164756E21
+//# debugId=798F8DCB6A6B9EBD64756E2164756E21
 //# sourceMappingURL=index.js.map