@secondlayer/sdk 6.38.0 → 6.40.0

package/dist/index.d.ts

@@ -509,6 +509,12 @@ type StreamsEventBase = {
 	* Optional for back-compat; the API always sets it on Streams responses.
 	*/
 	finalized?: boolean
+	/**
+	* Labels whose filter group this event satisfied, present only when the
+	* request used a labelled `filters` map. The SDK dispatches on it for you
+	* (`on.<label>`), so handlers rarely read it directly.
+	*/
+	matched?: string[]
 };
 type StreamsEventOf<
 	T extends StreamsEventType,
@@ -578,6 +584,34 @@ type StreamsReorgsListEnvelope = {
 };
 /** A filter that matches a single value or any value in a list. */
 type StreamsFilterValue = string | readonly string[];
+/**
+* One labelled filter group. Fields inside a group AND together; groups in a
+* map OR together server-side.
+*/
+type StreamsLabelledFilter = {
+	types?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
+	assetIdentifier?: string
+};
+/** A map of label → filter group. Labels are yours; the server echoes them. */
+type StreamsFilterMap = Record<string, StreamsLabelledFilter>;
+/**
+* The events one label can yield. A group that declares `types` narrows to
+* exactly those variants, so a per-label handler needs no `event_type` guard;
+* a group without `types` keeps the full union.
+*/
+type StreamsEventForFilter<
+	F,
+	D extends boolean = false
+> = F extends {
+	types: readonly (infer T extends StreamsEventType)[]
+} ? D extends true ? Extract<IndexEvent, {
+	event_type: T
+}> : Extract<StreamsEvent, {
+	event_type: T
+}> : D extends true ? IndexEvent : StreamsEvent;
 type StreamsEventsListParams = {
 	cursor?: string | null
 	fromHeight?: number
@@ -589,6 +623,12 @@ type StreamsEventsListParams = {
 	sender?: StreamsFilterValue
 	recipient?: StreamsFilterValue
 	assetIdentifier?: string
+	/**
+	* Labelled filter groups. The groups OR together in one scan and each
+	* returned event carries the labels it matched (`event.matched`) — two
+	* unrelated concerns share one page, one cursor, one checkpoint.
+	*/
+	filters?: StreamsFilterMap
 	limit?: number
 };
 type StreamsEventsStreamParams = {
@@ -599,6 +639,8 @@ type StreamsEventsStreamParams = {
 	sender?: StreamsFilterValue
 	recipient?: StreamsFilterValue
 	assetIdentifier?: string
+	/** Labelled filter groups; see {@link StreamsEventsListParams.filters}. */
+	filters?: StreamsFilterMap
 	batchSize?: number
 	emptyBackoffMs?: number
 	maxPages?: number
@@ -614,6 +656,8 @@ type StreamsEventsSubscribeParams = {
 	sender?: StreamsFilterValue
 	recipient?: StreamsFilterValue
 	assetIdentifier?: string
+	/** Labelled filter groups; see {@link StreamsEventsListParams.filters}. */
+	filters?: StreamsFilterMap
 	/** Abort to unsubscribe (the returned function does the same). */
 	signal?: AbortSignal
 	/** Called for each pushed event, in order. */
@@ -665,7 +709,8 @@ type StreamsReorgContext = {
 };
 type StreamsEventsConsumeParams<
 	TTx = never,
-	D extends boolean = false
+	D extends boolean = false,
+	F extends StreamsFilterMap = Record<never, never>
 > = {
 	fromCursor?: string | null
 	/**
@@ -699,13 +744,33 @@ type StreamsEventsConsumeParams<
 	sender?: StreamsFilterValue
 	recipient?: StreamsFilterValue
 	assetIdentifier?: string
+	/**
+	* Labelled filter groups. The groups OR together in ONE server-side scan,
+	* so two unrelated concerns share one page, one cursor, and one checkpoint
+	* instead of two consume loops. Pair with `on` to handle each label.
+	*/
+	filters?: F
+	/**
+	* One handler per label in `filters`. Every label must be handled, so
+	* adding a label is a compile error until its handler exists.
+	*
+	* A label's declared `types` narrows its handler's events, so `payload` is
+	* typed without an `event_type` guard. Labels are dispatched in declaration
+	* order: a label's own events stay in cursor order, but events of different
+	* labels do not interleave within a page — add `onBatch` when you need
+	* strict global order across labels.
+	*/
+	on?: { [K in keyof F] : (events: StreamsEventForFilter<F[K], D>[], ctx: StreamsBatchContext & WithSinkTx<TTx>) => void | Promise<void> }
 	batchSize?: number
 	/**
 	* 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.
+	*
+	* Optional only when `on` handles the page instead; a consume call with
+	* neither throws.
 	*/
-	onBatch: (events: D extends true ? IndexEvent[] : StreamsEvent[], envelope: StreamsEventsEnvelope, ctx: StreamsBatchContext & WithSinkTx<TTx>) => void | string | null | undefined | Promise<void> | Promise<string | null | undefined>
+	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
@@ -864,9 +929,10 @@ type StreamsClient = {
 		* stops it.
 		*/
 		consume<
+			const F extends StreamsFilterMap = Record<never, never>,
 			TTx = never,
 			D extends boolean = false
-		>(params: StreamsEventsConsumeParams<TTx, D> & {
+		>(params: StreamsEventsConsumeParams<TTx, D, F> & {
 			sink?: ConsumerSink<TTx>
 		}): Promise<StreamsEventsConsumeResult>
 		/**
@@ -1241,8 +1307,19 @@ type IndexPrint = IndexEventBase & {
 /** Decoded chain event, discriminated by `event_type`. */
 type IndexEvent = IndexFtTransfer | IndexNftTransfer | IndexStxTransfer | IndexStxMint | IndexStxBurn | IndexStxLock | IndexFtMint | IndexFtBurn | IndexNftMint | IndexNftBurn | IndexPrint;
 type IndexEventType = IndexEvent["event_type"];
-type EventsEnvelope<T extends IndexEventType = IndexEventType> = {
-	events: IndexEventOf<T>[]
+/** Fields every read returns regardless of `fields` — the consume contract
+*  (`cursor`, `block_height`) plus the union discriminant. */
+type IndexAlwaysFields = "cursor" | "block_height" | "event_type";
+/** An event row narrowed to a `fields` selection (plus what always ships). */
+type IndexEventFields<
+	T extends IndexEventType,
+	F extends keyof IndexEventOf<T> & string
+> = Pick<IndexEventOf<T>, (F | IndexAlwaysFields) & keyof IndexEventOf<T>>;
+type EventsEnvelope<
+	T extends IndexEventType = IndexEventType,
+	TRow = IndexEventOf<T>
+> = {
+	events: TRow[]
 	next_cursor: string | null
 	tip: IndexTip
 	reorgs: IndexReorg[]
@@ -1275,6 +1352,21 @@ type EventsListParams<T extends IndexEventType = IndexEventType> = {
 	*  Avoids a `/v1/index/transactions` call per event; for `print` events it's
 	*  the only source of the submitting sender. */
 	txContext?: boolean
+	/**
+	* Return only these columns. The server projects the SELECT, so an
+	* unrequested field is physically absent — and the returned row type
+	* narrows to match, making a read of one a compile error rather than
+	* `undefined`.
+	*
+	* `cursor`, `block_height`, and `event_type` come back regardless: the
+	* first two are the consume contract, the third carries the discriminant.
+	* Don't list them.
+	*
+	* Cost note: this does NOT change your bill — Index meters per row read,
+	* not per field. What it buys is wire bytes, plus skipping the `blocks`
+	* join when `block_time` is omitted.
+	*/
+	fields?: readonly (keyof IndexEventOf<T> & string)[]
 };
 type EventsWalkParams<T extends IndexEventType = IndexEventType> = Omit<EventsListParams<T>, "limit"> & {
 	batchSize?: number
@@ -1975,6 +2067,15 @@ interface NftTransfersResource {
 /** `index.events` — callable shorthand for `.list()`; `eventType` is required. */
 interface IndexEventsResource {
 	<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
+	/** Narrowing overload: `fields` shrinks the returned row type to exactly
+	*  the requested columns plus {@link IndexAlwaysFields}. `const F` means no
+	*  `as const` at the call site. */
+	list<
+		T extends IndexEventType,
+		const F extends keyof IndexEventOf<T> & string
+	>(params: EventsListParams<T> & {
+		fields: readonly F[]
+	}): Promise<EventsEnvelope<T, IndexEventFields<T, F>>>;
 	list<T extends IndexEventType>(params: EventsListParams<T>): Promise<EventsEnvelope<T>>;
 	walk<T extends IndexEventType>(params: EventsWalkParams<T>): AsyncIterable<IndexEventOf<T>>;
 	consume<
@@ -3152,4 +3253,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 { withX402, verifyWebhookSignature, verifyTransactionProof, verify as verifyStandardWebhooksHeaders, verifySecondlayerSignature, trigger, toJsonSafe, shutdownSignal, selectOffer, resolveApiKey, resolveAccountNonce, readX402Receipt, readX402Challenge, payAndRetry, parseRetryAfter, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, fetchRewardSet, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, decodeChainWebhook, decode, createX402Client, createStreamsClient, consumerHealth, consumeIndexFeed, buildSignedX402Payment, X402SpendGuardError, X402Result, X402Receipt, X402Fetch, X402ClientOptions, X402Client, X402Challenge, X402Accept, WithX402Options, WithSinkTx, WebhookHeaderInput, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, UpdateProjectParams, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsUsage, 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, StandardWebhooksHeaders2 as StandardWebhooksHeaders, StackingWalkParams, StackingListParams, StackingEnvelope, SinkTx, SelectOfferOptions, SecondLayerOptions, SecondLayerErrorOptions, SecondLayerError, SecondLayer, ScopedKeyProduct, SbtcWithdrawalsWalkParams, SbtcWithdrawalsListParams, SbtcWithdrawalsEnvelope, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalStatus, SbtcWithdrawalEvent, SbtcWithdrawalEnvelope, SbtcSummaryEnvelope, SbtcResource, SbtcEventsWalkParams, SbtcEventsListParams, SbtcEventsEnvelope, SbtcEventsConsumeParams, SbtcEventTopic2 as SbtcEventTopic, SbtcDepositsWalkParams, SbtcDepositsListParams, SbtcDepositsEnvelope, SbtcDepositsConsumeParams, SbtcDepositEvent, SbtcDepositEnvelope, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, ReplayResult2 as ReplayResult, RateLimitError, Projects, ProjectTeamMember, ProjectTeam, ProjectInvitation, Project, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, PayAndRetryOptions, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStxTransfer, IndexStxMint, IndexStxLock, IndexStxBurn, IndexStackingAction, IndexSbtcWithdrawalPhase, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawal, IndexSbtcSummary, IndexSbtcEvent, IndexSbtcDepositDetail, IndexSbtcDeposit, IndexReorg, IndexPrint, IndexPoxFunctionCount, IndexPoxCycle, IndexPox5EventTopic, IndexPox5Event, IndexPostCondition, IndexNftTransfer, IndexNftMint, IndexNftBurn, IndexMempoolTransaction, IndexFtTransfer, IndexFtMint, IndexFtBurn, IndexFeedItem, IndexFeedFetcher, IndexFeedEnvelope, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEventOf, IndexEvent, IndexDiscovery, IndexContractCall, IndexConsumeOptions, IndexCanonicalBlock, IndexBlock, Index, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, EventsConsumeParams, 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, DEFAULT_PREFER_ASSETS, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateProjectParams, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContractCallsConsumeParams, ContextSnapshot, ContextProject, ContextApiKey, ContextAccount, ConsumerSink, ConsumerHealth, ConsumerBatchContext, ChainWebhookEnvelope, ChainWebhookDelivery2 as ChainWebhookDelivery, ChainTxLevelEvent, ChainTriggerType, ChainTrigger, ChainTestDelivery, ChainStxTransferData, ChainStxMintData, ChainStxLockData, ChainStxBurnData, ChainReorgRollbackEnvelope, ChainReorgRollbackDelivery, ChainReorgOrphanedEntry, ChainPrintEventData, ChainNftTransferData, ChainNftMintData, ChainNftBurnData, ChainFtTransferData, ChainFtMintData, ChainFtBurnData, ChainEventEnvelope, ChainApplyEnvelopeOf, ChainApplyEnvelope, ChainApplyDeliveryOf, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, ByoBreakingChangeError, ByoBreakingChangeDetails, BuildSignedX402PaymentOptions, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiKeySummary, ApiError, ActiveSubgraphOperation };
+export { withX402, verifyWebhookSignature, verifyTransactionProof, verify as verifyStandardWebhooksHeaders, verifySecondlayerSignature, trigger, toJsonSafe, shutdownSignal, selectOffer, resolveApiKey, resolveAccountNonce, readX402Receipt, readX402Challenge, payAndRetry, parseRetryAfter, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, getSubgraph, fetchRewardSet, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, decodeChainWebhook, decode, createX402Client, createStreamsClient, consumerHealth, consumeIndexFeed, buildSignedX402Payment, X402SpendGuardError, X402Result, X402Receipt, X402Fetch, X402ClientOptions, X402Client, X402Challenge, X402Accept, WithX402Options, WithSinkTx, WebhookHeaderInput, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, UpdateProjectParams, TransactionsWalkParams, TransactionsListParams, TransactionsEnvelope, TransactionProofVerifyResult, TransactionProof, TransactionEnvelope, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionKind, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphOperationStatus, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsUsage, 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, StandardWebhooksHeaders2 as StandardWebhooksHeaders, StackingWalkParams, StackingListParams, StackingEnvelope, SinkTx, SelectOfferOptions, SecondLayerOptions, SecondLayerErrorOptions, SecondLayerError, SecondLayer, ScopedKeyProduct, SbtcWithdrawalsWalkParams, SbtcWithdrawalsListParams, SbtcWithdrawalsEnvelope, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalStatus, SbtcWithdrawalEvent, SbtcWithdrawalEnvelope, SbtcSummaryEnvelope, SbtcResource, SbtcEventsWalkParams, SbtcEventsListParams, SbtcEventsEnvelope, SbtcEventsConsumeParams, SbtcEventTopic2 as SbtcEventTopic, SbtcDepositsWalkParams, SbtcDepositsListParams, SbtcDepositsEnvelope, SbtcDepositsConsumeParams, SbtcDepositEvent, SbtcDepositEnvelope, RotateSecretResponse2 as RotateSecretResponse, RewardSet2 as RewardSet, ReplayResult2 as ReplayResult, RateLimitError, Projects, ProjectTeamMember, ProjectTeam, ProjectInvitation, Project, PrintSchemaResponse, PoxResource, PoxCyclesWalkParams, PoxCyclesListParams, PoxCyclesEnvelope, PoxCycleEnvelope, Pox5Resource, Pox5EventsWalkParams, Pox5EventsListParams, Pox5EventsEnvelope, PayAndRetryOptions, NftTransfersWalkParams, NftTransfersResource, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, MempoolWalkParams, MempoolTransactionEnvelope, MempoolListParams, MempoolEnvelope, IndexUsage, IndexTransaction, IndexTip, IndexStxTransfer, IndexStxMint, IndexStxLock, IndexStxBurn, IndexStackingAction, IndexSbtcWithdrawalPhase, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawal, IndexSbtcSummary, IndexSbtcEvent, IndexSbtcDepositDetail, IndexSbtcDeposit, IndexReorg, IndexPrint, IndexPoxFunctionCount, IndexPoxCycle, IndexPox5EventTopic, IndexPox5Event, IndexPostCondition, IndexNftTransfer, IndexNftMint, IndexNftBurn, IndexMempoolTransaction, IndexFtTransfer, IndexFtMint, IndexFtBurn, IndexFeedItem, IndexFeedFetcher, IndexFeedEnvelope, IndexEventsResource, IndexEventTypeFilters, IndexEventType, IndexEventOf, IndexEventFields, IndexEvent, IndexDiscovery, IndexContractCall, IndexConsumeOptions, IndexCanonicalBlock, IndexBlock, IndexAlwaysFields, Index, FtTransfersWalkParams, FtTransfersResource, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike2 as FetchLike, EventsWalkParams, EventsListParams, EventsEnvelope, EventsConsumeParams, 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, DEFAULT_PREFER_ASSETS, Cursor, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, CreateProjectParams, CreateApiKeyResponse, CreateApiKeyParams, ContractsListParams, ContractsEnvelope, Contracts, ContractSummary, ContractConformance, ContractCallsWalkParams, ContractCallsListParams, ContractCallsEnvelope, ContractCallsConsumeParams, ContextSnapshot, ContextProject, ContextApiKey, ContextAccount, ConsumerSink, ConsumerHealth, ConsumerBatchContext, ChainWebhookEnvelope, ChainWebhookDelivery2 as ChainWebhookDelivery, ChainTxLevelEvent, ChainTriggerType, ChainTrigger, ChainTestDelivery, ChainStxTransferData, ChainStxMintData, ChainStxLockData, ChainStxBurnData, ChainReorgRollbackEnvelope, ChainReorgRollbackDelivery, ChainReorgOrphanedEntry, ChainPrintEventData, ChainNftTransferData, ChainNftMintData, ChainNftBurnData, ChainFtTransferData, ChainFtMintData, ChainFtBurnData, ChainEventEnvelope, ChainApplyEnvelopeOf, ChainApplyEnvelope, ChainApplyDeliveryOf, CanonicalWalkParams, CanonicalListParams, CanonicalEnvelope, ByoBreakingChangeError, ByoBreakingChangeDetails, BuildSignedX402PaymentOptions, BlocksWalkParams, BlocksListParams, BlocksEnvelope, BlockEnvelope, AuthError, ApiKeys, ApiKeySummary, ApiError, ActiveSubgraphOperation };

package/dist/index.js

@@ -669,7 +669,8 @@ async function consumeStreamsEvents(opts) {
       contractId: opts.contractId,
       sender: opts.sender,
       recipient: opts.recipient,
-      assetIdentifier: opts.assetIdentifier
+      assetIdentifier: opts.assetIdentifier,
+      filters: opts.filters
     }), {
       retryCount: opts.retryCount,
       retryDelay: opts.retryDelay,
@@ -746,7 +747,8 @@ async function* iterateStreamsBatches(opts) {
       contractId: opts.contractId,
       sender: opts.sender,
       recipient: opts.recipient,
-      assetIdentifier: opts.assetIdentifier
+      assetIdentifier: opts.assetIdentifier,
+      filters: opts.filters
     });
     const checkpoint = envelope.next_cursor ?? cursor;
     if (envelope.events.length > 0 || envelope.reorgs.length > 0) {
@@ -783,7 +785,8 @@ async function* streamStreamsEvents(opts) {
       contractId: opts.contractId,
       sender: opts.sender,
       recipient: opts.recipient,
-      assetIdentifier: opts.assetIdentifier
+      assetIdentifier: opts.assetIdentifier,
+      filters: opts.filters
     });
     pages++;
     for (const event of envelope.events) {
@@ -1113,7 +1116,8 @@ class Index extends BaseClient {
       from_height: params.fromHeight,
       to_height: params.toHeight,
       trait: params.trait,
-      tx_context: params.txContext ? "true" : undefined
+      tx_context: params.txContext ? "true" : undefined,
+      fields: params.fields?.join(",")
     })}`);
   }
   walkEvents(params) {
@@ -1597,7 +1601,8 @@ function subscribeStreamsEvents(opts) {
           contract_id: params.contractId,
           sender: params.sender,
           recipient: params.recipient,
-          asset_identifier: params.assetIdentifier
+          asset_identifier: params.assetIdentifier,
+          filters: params.filters ? JSON.stringify(params.filters) : undefined
         })}`;
         const res = await opts.fetchImpl(url, {
           headers: {
@@ -1841,7 +1846,8 @@ function createStreamsClient(options) {
     contractId,
     sender,
     recipient,
-    assetIdentifier
+    assetIdentifier,
+    filters
   }) => {
     return listEvents({
       cursor,
@@ -1851,9 +1857,13 @@ function createStreamsClient(options) {
       contractId,
       sender,
       recipient,
-      assetIdentifier
+      assetIdentifier,
+      filters
     });
   };
+  function encodeFilters(filters) {
+    return filters ? JSON.stringify(filters) : undefined;
+  }
   async function listEvents(params = {}) {
     return request(`/v1/streams/events${buildQuery({
       cursor: params.cursor,
@@ -1865,9 +1875,56 @@ function createStreamsClient(options) {
       recipient: params.recipient,
       asset_identifier: params.assetIdentifier,
       types: params.types,
-      not_types: params.notTypes
+      not_types: params.notTypes,
+      filters: encodeFilters(params.filters)
     })}`);
   }
+  function consumeEvents(params) {
+    const labels = params.filters ? Object.keys(params.filters) : [];
+    if (labels.length === 0 && !params.onBatch) {
+      throw new ValidationError("consume requires onBatch, or filters + on handlers.", 400);
+    }
+    if (labels.length > 0 && !params.on && !params.onBatch) {
+      throw new ValidationError("consume with filters requires on handlers (or onBatch).", 400);
+    }
+    const dispatch = params.on;
+    const project = (events) => params.decoded ? events.map(decode) : events;
+    const onBatch = async (events, envelope, ctx) => {
+      for (const label of labels) {
+        const forLabel = events.filter((event) => event.matched?.includes(label));
+        if (forLabel.length === 0)
+          continue;
+        await dispatch?.[label]?.(project(forLabel), ctx);
+      }
+      const userOnBatch = params.onBatch;
+      return await userOnBatch?.(project(events), envelope, ctx);
+    };
+    return consumeStreamsEvents({
+      fromCursor: params.fromCursor,
+      sink: params.sink,
+      onProgress: params.onProgress,
+      mode: params.mode,
+      finalizedOnly: params.finalizedOnly,
+      types: params.types,
+      notTypes: params.notTypes,
+      contractId: params.contractId,
+      sender: params.sender,
+      recipient: params.recipient,
+      assetIdentifier: params.assetIdentifier,
+      filters: params.filters,
+      batchSize: params.batchSize ?? 100,
+      fetchEvents,
+      onBatch,
+      onReorg: params.onReorg,
+      emptyBackoffMs: params.emptyBackoffMs,
+      maxPages: params.maxPages,
+      maxEmptyPolls: params.maxEmptyPolls,
+      signal: params.signal,
+      retryCount: params.retryCount,
+      retryDelay: params.retryDelay,
+      onError: params.onError
+    });
+  }
   return {
     consume(params = {}) {
       return iterateStreamsBatches({
@@ -1889,33 +1946,7 @@ function createStreamsClient(options) {
       byTxId(txId) {
         return request(`/v1/streams/events/${encodeURIComponent(txId)}`);
       },
-      consume(params) {
-        const onBatch = params.decoded ? (events, envelope, ctx) => params.onBatch(events.map(decode), envelope, ctx) : params.onBatch;
-        return consumeStreamsEvents({
-          fromCursor: params.fromCursor,
-          sink: params.sink,
-          onProgress: params.onProgress,
-          mode: params.mode,
-          finalizedOnly: params.finalizedOnly,
-          types: params.types,
-          notTypes: params.notTypes,
-          contractId: params.contractId,
-          sender: params.sender,
-          recipient: params.recipient,
-          assetIdentifier: params.assetIdentifier,
-          batchSize: params.batchSize ?? 100,
-          fetchEvents,
-          onBatch,
-          onReorg: params.onReorg,
-          emptyBackoffMs: params.emptyBackoffMs,
-          maxPages: params.maxPages,
-          maxEmptyPolls: params.maxEmptyPolls,
-          signal: params.signal,
-          retryCount: params.retryCount,
-          retryDelay: params.retryDelay,
-          onError: params.onError
-        });
-      },
+      consume: consumeEvents,
       stream(params = {}) {
         return streamStreamsEvents({
           fromCursor: params.fromCursor,
@@ -2844,5 +2875,5 @@ export {
   ApiError
 };
 
-//# debugId=1D3B2F9E333F939964756E2164756E21
+//# debugId=0D258137688545B064756E2164756E21
 //# sourceMappingURL=index.js.map