@secondlayer/sdk 6.38.0 → 6.40.0

package/dist/subgraphs/index.d.ts

@@ -453,6 +453,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,
@@ -522,6 +528,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
@@ -533,6 +567,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 = {
@@ -543,6 +583,8 @@ type StreamsEventsStreamParams = {
 	sender?: StreamsFilterValue
 	recipient?: StreamsFilterValue
 	assetIdentifier?: string
+	/** Labelled filter groups; see {@link StreamsEventsListParams.filters}. */
+	filters?: StreamsFilterMap
 	batchSize?: number
 	emptyBackoffMs?: number
 	maxPages?: number
@@ -558,6 +600,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. */
@@ -609,7 +653,8 @@ type StreamsReorgContext = {
 };
 type StreamsEventsConsumeParams<
 	TTx = never,
-	D extends boolean = false
+	D extends boolean = false,
+	F extends StreamsFilterMap = Record<never, never>
 > = {
 	fromCursor?: string | null
 	/**
@@ -643,13 +688,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
@@ -807,9 +872,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>
 		/**
@@ -1153,8 +1219,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[]
@@ -1187,6 +1264,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
@@ -1887,6 +1979,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<

package/dist/subgraphs/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,
@@ -2148,5 +2179,5 @@ export {
   Subgraphs
 };
 
-//# debugId=E16E22A43378758864756E2164756E21
+//# debugId=4B9D9DF481DBB85464756E2164756E21
 //# sourceMappingURL=index.js.map