@secondlayer/sdk 6.39.0 → 6.40.1

package/dist/streams/index.d.ts

@@ -230,6 +230,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,
@@ -299,6 +305,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
@@ -310,6 +344,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 = {
@@ -320,6 +360,8 @@ type StreamsEventsStreamParams = {
 	sender?: StreamsFilterValue
 	recipient?: StreamsFilterValue
 	assetIdentifier?: string
+	/** Labelled filter groups; see {@link StreamsEventsListParams.filters}. */
+	filters?: StreamsFilterMap
 	batchSize?: number
 	emptyBackoffMs?: number
 	maxPages?: number
@@ -335,6 +377,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. */
@@ -386,7 +430,8 @@ type StreamsReorgContext = {
 };
 type StreamsEventsConsumeParams<
 	TTx = never,
-	D extends boolean = false
+	D extends boolean = false,
+	F extends StreamsFilterMap = Record<never, never>
 > = {
 	fromCursor?: string | null
 	/**
@@ -420,13 +465,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
@@ -585,9 +650,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>
 		/**

package/dist/streams/index.js

@@ -399,7 +399,8 @@ async function consumeStreamsEvents(opts) {
   const emptyBackoffMs = opts.emptyBackoffMs ?? 500;
   const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;
   const maxEmptyPolls = opts.maxEmptyPolls ?? Number.POSITIVE_INFINITY;
-  let cursor = opts.fromCursor ?? await opts.sink?.loadCursor() ?? null;
+  const committedCursor = await opts.sink?.loadCursor() ?? null;
+  let cursor = opts.fromCursor ?? committedCursor;
   const handledReorgs = new Set;
   let pages = 0;
   let emptyPolls = 0;
@@ -413,7 +414,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,
@@ -490,7 +492,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) {
@@ -527,7 +530,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) {
@@ -802,7 +806,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: {
@@ -1046,7 +1051,8 @@ function createStreamsClient(options) {
     contractId,
     sender,
     recipient,
-    assetIdentifier
+    assetIdentifier,
+    filters
   }) => {
     return listEvents({
       cursor,
@@ -1056,9 +1062,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,
@@ -1070,9 +1080,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({
@@ -1094,33 +1151,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,
@@ -1453,5 +1484,5 @@ export {
   AuthError
 };
 
-//# debugId=5CDDE8F307DF3D9164756E2164756E21
+//# debugId=93D7CDA8BB38740964756E2164756E21
 //# sourceMappingURL=index.js.map