@midnight-ntwrk/wallet-sdk-indexer-client 1.2.2 → 1.2.3

package/README.md

@@ -1,3 +1,10 @@
+> [!IMPORTANT]
+> **This package has moved.** The `@midnight-ntwrk` scope is published only
+> during the migration window and will stop receiving updates. Please migrate to
+> [`@midnightntwrk/wallet-sdk-indexer-client`](https://www.npmjs.com/package/@midnightntwrk/wallet-sdk-indexer-client).
+
+---
+
 # @midnight-ntwrk/wallet-sdk-indexer-client
 
 Client for communicating with the Midnight indexer service.

package/dist/effect/Backpressure.d.ts

@@ -0,0 +1,97 @@
+import { Stream } from 'effect';
+/**
+ * Options controlling the bounded backpressure behavior.
+ *
+ * The implementation caps the number of in-flight (emitted but not yet consumed downstream) items. Once
+ * {@link bufferSize} is reached the underlying source is disposed; when the consumer drains back down to
+ * {@link resumeThreshold} a fresh subscription is opened with `variables(cursor)` for the running cursor.
+ *
+ * Emitted items are guaranteed strictly monotonic by {@link key}. Dedup uses a single exclusive watermark: any item with
+ * a key `<= watermark` is dropped, and each emitted key advances the watermark. The watermark seeds from {@link from},
+ * so the item _at_ `from` is treated as already-seen and dropped. This is what makes resume safe over an inclusive
+ * cursor: the boundary item a resume re-delivers has a key equal to the watermark and is dropped — without it, the
+ * first item after a resume would duplicate the last one emitted before the pause. A caller that needs the item at its
+ * logical cursor emitted (e.g. to let an already-caught-up consumer observe its tip) passes `from` one below that
+ * cursor.
+ *
+ * The cursor is the single source of truth for both initial open and resume — no separate "initial variables" field;
+ * `variables(from)` opens the first subscription, `variables(key(lastItem))` opens every subsequent one.
+ *
+ * No items above the watermark are dropped — the producer is paused, never thrown away.
+ *
+ * **Totality contract:** {@link key} and {@link variables} MUST be total — they must not throw for any input of their
+ * declared types. The wrapper does not catch exceptions from these closures: a throw from `key` propagates back through
+ * the source's sync callback (undefined behavior depending on the source's internals), and a throw from `variables`
+ * surfaces as an unhandled defect on the resulting `Stream` rather than a typed `E`. The signatures `(cursor: bigint)
+ * => V` and `(item: Item) => bigint` are the contract; honor them.
+ */
+export interface BackpressureOptions<Item, V> {
+    /** Pause the underlying subscription once in-flight reaches this count. */
+    readonly bufferSize: number;
+    /**
+     * Resume once in-flight drains back to this count. Must be strictly less than `bufferSize` to give the consumer real
+     * hysteresis.
+     */
+    readonly resumeThreshold: number;
+    /** Initial cursor (bigint watermark). The first subscription opens with `variables(from)`. */
+    readonly from: bigint;
+    /** Derives subscription variables from a cursor. Used for the initial open and on every resume. */
+    readonly variables: (cursor: bigint) => V;
+    /** Monotonic key extractor — items with a key not strictly greater than the running watermark are dropped. */
+    readonly key: (result: Item) => bigint;
+}
+/**
+ * A push-based source. Each call opens a fresh session and returns a dispose handle. Items, errors and completion flow
+ * through the supplied callbacks.
+ *
+ * The source MUST stop delivering callbacks after `dispose()` is invoked. The caller pauses by disposing and resumes by
+ * calling the factory again with new variables; the source has no other backpressure signalling.
+ */
+export type Source<Item, V, E> = (params: {
+    readonly variables: V;
+    readonly onItem: (item: Item) => void;
+    readonly onError: (error: E) => void;
+    readonly onComplete: () => void;
+}) => () => void;
+/** @internal — exported only for unit tests; not part of the public API. */
+export type BPState = {
+    readonly paused: boolean;
+    readonly inFlight: number;
+    readonly lastKey: bigint;
+    readonly generation: number;
+    readonly terminal: boolean;
+};
+/** @internal */
+export type ItemDecision = {
+    readonly emit: boolean;
+    readonly pause: boolean;
+};
+/** @internal */
+export declare const initialBPState: (from: bigint) => BPState;
+/**
+ * @internal Decide what to do with an item arriving on `onItem`.
+ *
+ * The watermark is exclusive throughout: an item is dropped iff its key is `<= lastKey`, and each emitted key advances
+ * the watermark. The watermark seeds from `from`, so the item at `from` itself is treated as already-seen and dropped —
+ * a caller that wants the item at its logical cursor emitted seeds `from` one below it. The same exclusive rule drops
+ * the boundary item an inclusive-cursor resume re-delivers (its key equals `lastKey`).
+ */
+export declare const decideItem: (s: BPState, k: bigint, myGen: number, bufferSize: number) => readonly [ItemDecision, BPState];
+/** @internal Decide whether an error callback should surface (false for stale/terminal). */
+export declare const decideTerminate: (s: BPState, myGen: number) => readonly [boolean, BPState];
+/** @internal Decide whether a completion is consumer-visible end-of-stream or dispose-induced. */
+export declare const decideComplete: (s: BPState, myGen: number) => readonly [boolean, BPState];
+/**
+ * @internal Decide whether to resume the source after a downstream consume. Paused implies we've emitted at least
+ * bufferSize items, so lastKey is meaningful. Returns true when the caller should open a new session — the caller
+ * derives the resume variables from `state.lastKey` itself.
+ */
+export declare const decideResume: (s: BPState, resumeThreshold: number) => readonly [boolean, BPState];
+/**
+ * Wrap a push-based {@link Source} with bounded backpressure. The source is paused (disposed) when the in-flight count
+ * reaches `bufferSize` and resumed (re-opened with `variables(lastKey)`) once the consumer drains back to
+ * `resumeThreshold`.
+ *
+ * See {@link BackpressureOptions} for the monotonic-key dedup invariant.
+ */
+export declare const withBackpressure: <Item, V, E>(source: Source<Item, V, E>, options: BackpressureOptions<Item, V>) => Stream.Stream<Item, E>;

package/dist/effect/Backpressure.js

@@ -0,0 +1,146 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Bounded backpressure over a push-only source whose only knob is "dispose and
+// re-open from a cursor". The classic shape for graphql-ws / SSE-style feeds
+// that don't support pull or pause signalling.
+//
+// Composition:
+//   - Pure state machine (decideItem/decideTerminate/decideComplete/decideResume)
+//     contains all transition rules and is unit-testable in isolation.
+//   - `withBackpressure` wires the state machine to a {@link Source}, an
+//     internal Stream.asyncPush queue, and a Stream.tap drain detector.
+//   - Source authors translate their callbacks to the {@link Source} contract
+//     once; backpressure is independent of the underlying transport.
+import { Effect, Stream, Ref } from 'effect';
+/** @internal */
+export const initialBPState = (from) => ({
+    paused: false,
+    inFlight: 0,
+    lastKey: from,
+    generation: 0,
+    terminal: false,
+});
+/**
+ * @internal Decide what to do with an item arriving on `onItem`.
+ *
+ * The watermark is exclusive throughout: an item is dropped iff its key is `<= lastKey`, and each emitted key advances
+ * the watermark. The watermark seeds from `from`, so the item at `from` itself is treated as already-seen and dropped —
+ * a caller that wants the item at its logical cursor emitted seeds `from` one below it. The same exclusive rule drops
+ * the boundary item an inclusive-cursor resume re-delivers (its key equals `lastKey`).
+ */
+export const decideItem = (s, k, myGen, bufferSize) => {
+    if (s.terminal || s.generation !== myGen)
+        return [{ emit: false, pause: false }, s];
+    if (k <= s.lastKey)
+        return [{ emit: false, pause: false }, s];
+    const inFlight = s.inFlight + 1;
+    const pause = inFlight >= bufferSize && !s.paused;
+    return [
+        { emit: true, pause },
+        { ...s, inFlight, lastKey: k, paused: s.paused || pause },
+    ];
+};
+/** @internal Decide whether an error callback should surface (false for stale/terminal). */
+export const decideTerminate = (s, myGen) => s.terminal || s.generation !== myGen ? [false, s] : [true, { ...s, terminal: true }];
+/** @internal Decide whether a completion is consumer-visible end-of-stream or dispose-induced. */
+export const decideComplete = (s, myGen) => {
+    if (s.paused || s.terminal || s.generation !== myGen)
+        return [false, s];
+    return [true, { ...s, terminal: true }];
+};
+/**
+ * @internal Decide whether to resume the source after a downstream consume. Paused implies we've emitted at least
+ * bufferSize items, so lastKey is meaningful. Returns true when the caller should open a new session — the caller
+ * derives the resume variables from `state.lastKey` itself.
+ */
+export const decideResume = (s, resumeThreshold) => {
+    if (s.terminal)
+        return [false, s];
+    const inFlight = Math.max(0, s.inFlight - 1);
+    if (s.paused && inFlight <= resumeThreshold) {
+        return [true, { ...s, inFlight, paused: false, generation: s.generation + 1 }];
+    }
+    return [false, { ...s, inFlight }];
+};
+// ============================================================================
+// Stream wrapper
+// ============================================================================
+/**
+ * Wrap a push-based {@link Source} with bounded backpressure. The source is paused (disposed) when the in-flight count
+ * reaches `bufferSize` and resumed (re-opened with `variables(lastKey)`) once the consumer drains back to
+ * `resumeThreshold`.
+ *
+ * See {@link BackpressureOptions} for the monotonic-key dedup invariant.
+ */
+export const withBackpressure = (source, options) => {
+    const { bufferSize, resumeThreshold, key, from, variables } = options;
+    // Stream.unwrap re-runs the factory per subscription, so each consumer of
+    // the returned Stream gets its own Refs and its own source session.
+    return Stream.unwrap(Effect.gen(function* () {
+        // Three refs cover the inherently mutable bridge between sync source
+        // callbacks and Effect: the state machine, the current dispose handle,
+        // and the asyncPush emit handle (only bound while a consumer is
+        // attached).
+        const stateRef = yield* Ref.make(initialBPState(from));
+        const disposerRef = yield* Ref.make(null);
+        const emitRef = yield* Ref.make(null);
+        // Source callbacks are sync JS. Ref ops are sync internally, so runSync
+        // is safe here. Confined to these two helpers for auditability.
+        const modify = (f) => Effect.runSync(Ref.modify(stateRef, f));
+        const takeDisposer = () => Effect.runSync(Ref.getAndSet(disposerRef, null));
+        const openSession = () => Effect.gen(function* () {
+            const state = yield* Ref.get(stateRef);
+            if (state.terminal)
+                return;
+            const emit = yield* Ref.get(emitRef);
+            if (emit === null)
+                return;
+            const myGen = state.generation;
+            const dispose = source({
+                variables: variables(state.lastKey),
+                onItem: (item) => {
+                    const action = modify((s) => decideItem(s, key(item), myGen, bufferSize));
+                    if (!action.emit)
+                        return;
+                    emit.single(item);
+                    if (action.pause)
+                        takeDisposer()?.();
+                },
+                onError: (error) => {
+                    if (modify((s) => decideTerminate(s, myGen)))
+                        emit.fail(error);
+                },
+                onComplete: () => {
+                    if (modify((s) => decideComplete(s, myGen)))
+                        emit.end();
+                },
+            });
+            yield* Ref.set(disposerRef, dispose);
+        });
+        return Stream.asyncPush((emit) => Effect.acquireRelease(Effect.gen(function* () {
+            yield* Ref.set(emitRef, emit);
+            yield* openSession();
+        }), () => Effect.gen(function* () {
+            yield* Ref.update(stateRef, (s) => ({ ...s, terminal: true }));
+            const d = yield* Ref.getAndSet(disposerRef, null);
+            if (d !== null)
+                yield* Effect.sync(() => d());
+            yield* Ref.set(emitRef, null);
+        })), { bufferSize: 'unbounded' }).pipe(Stream.tap(() => Effect.gen(function* () {
+            const shouldResume = yield* Ref.modify(stateRef, (s) => decideResume(s, resumeThreshold));
+            if (shouldResume)
+                yield* openSession();
+        })));
+    }));
+};

package/dist/effect/Subscription.d.ts

@@ -6,6 +6,12 @@ import type { Query } from './Query.js';
 export interface Subscription<R, V, F extends Subscription.SubscriptionFn<R, V> = Subscription.SubscriptionFn<R, V>> extends Effect.Effect<F> {
     readonly tag: Context.Tag<Subscription<R, V>, F>;
     readonly run: F;
+    /**
+     * Like {@link run}, but caps the in-flight item count by disposing the underlying GraphQL subscription when the
+     * consumer can't keep up, and re-opens it with `variables(cursor)` for the running monotonic cursor once the queue
+     * drains. Items are never dropped.
+     */
+    readonly runWithBackpressure: (options: SubscriptionClient.BackpressureOptions<R, V>) => Stream.Stream<R, ClientError | ServerError, SubscriptionClient>;
 }
 export declare namespace Subscription {
     /**

package/dist/effect/Subscription.js

@@ -34,6 +34,22 @@ class SubscriptionImpl extends Effectable.Class {
             });
         });
     }
+    runWithBackpressure(options) {
+        const self = this; // eslint-disable-line @typescript-eslint/no-this-alias
+        // Mirror the `run`/`commit` dispatch: if a caller has provided an override
+        // via `self.tag` (test mocks do this), fall back to it — those overrides
+        // can't speak backpressure, but tests don't need to. The override is
+        // invoked with the initial variables derived from the cursor, since the
+        // override doesn't know the cursor protocol. Without an override, take the
+        // bounded pause/resume path against the underlying client.
+        return Stream.unwrap(Effect.gen(function* () {
+            const tagged = yield* Effect.serviceOption(self.tag);
+            return Option.match(tagged, {
+                onSome: (fn) => fn(options.variables(options.from)),
+                onNone: () => SubscriptionClient.pipe(Stream.flatMap((client) => client.subscribeWithBackpressure(self.document, options))),
+            });
+        }));
+    }
     defaultFn(variables) {
         return SubscriptionClient.pipe(Stream.flatMap((client) => client.subscribe(this.document, variables)));
     }

package/dist/effect/SubscriptionClient.d.ts

@@ -1,5 +1,6 @@
 import { type Stream, Context } from 'effect';
 import type { Query } from './Query.js';
+import type { BackpressureOptions as BackpressureOptionsImpl } from './Backpressure.js';
 import { type ClientError, type ServerError } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
 declare const SubscriptionClient_base: Context.TagClass<SubscriptionClient, "@midnight-ntwrk/indexer-client#SubscriptionClient", SubscriptionClient.Service>;
 export declare class SubscriptionClient extends SubscriptionClient_base {
@@ -9,8 +10,14 @@ export declare namespace SubscriptionClient {
         readonly url: URL | string;
         readonly keepAlive?: number | undefined;
     }
+    /**
+     * Options for {@link Service.subscribeWithBackpressure}. Canonical definition lives in
+     * {@link ./Backpressure.BackpressureOptions} — re-exported here for ergonomic access through the namespace.
+     */
+    type BackpressureOptions<R, V> = BackpressureOptionsImpl<R, V>;
     interface Service {
         subscribe<R, V, T extends Query.Document<R, V> = Query.Document<R, V>>(document: T, variables: V): Stream.Stream<Query.Result<T>, ClientError | ServerError>;
+        subscribeWithBackpressure<R, V, T extends Query.Document<R, V> = Query.Document<R, V>>(document: T, options: BackpressureOptions<Query.Result<T>, V>): Stream.Stream<Query.Result<T>, ClientError | ServerError>;
     }
 }
 export {};

package/dist/effect/WsSubscriptionClient.js

@@ -10,11 +10,30 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-import { Effect, Stream, Layer } from 'effect';
+import { Effect, Stream, Layer, Array as Arr } from 'effect';
 import { createClient } from 'graphql-ws';
 import { print } from 'graphql';
 import { SubscriptionClient } from './SubscriptionClient.js';
+import { withBackpressure } from './Backpressure.js';
 import { WsURL, ClientError, ServerError, } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
+// ============================================================================
+// Error classification
+// ============================================================================
+// graphql-ws delivers a subscription sink error as one of: `Error`, `CloseEvent`,
+// or `readonly GraphQLError[]` (per its Sink docs). Only the array form should
+// surface as a ClientError; everything else is a transport/server failure.
+const isGraphQLErrorArray = (err) => {
+    if (!Arr.isArray(err) || err.length === 0)
+        return false;
+    const first = err[0];
+    return typeof first === 'object' && first !== null && 'message' in first && typeof first.message === 'string';
+};
+const toClientOrServerError = (err) => isGraphQLErrorArray(err)
+    ? new ClientError({ message: err.map((e) => e.message).join('; '), cause: err })
+    : new ServerError({ message: String(err) });
+// ============================================================================
+// Layer / class
+// ============================================================================
 export const layer = (config) => Layer.scoped(SubscriptionClient, WsURL.make(config.url).pipe(Effect.flatMap((url) => Effect.acquireRelease(Effect.sync(() => createClient({ url: url.toString(), shouldRetry: () => false, keepAlive: config.keepAlive ?? 15_000 })), (client) => Effect.sync(() => client.dispose()))), Effect.map((client) => new WebSocketSubscriptionClientImpl(client))));
 class WebSocketSubscriptionClientImpl {
     constructor(client) {
@@ -22,23 +41,49 @@ class WebSocketSubscriptionClientImpl {
     }
     client;
     subscribe(document, variables) {
-        return Stream.async((emit) => {
-            const dispose = this.client.subscribe({ query: print(document), variables: variables }, {
-                next: (data) => {
-                    if (data.errors) {
-                        return void emit.fail(new ClientError({ message: data.errors[0].message, cause: data.errors }));
-                    }
-                    void emit.single(data.data);
-                },
-                error: (err) => {
-                    void emit.fail(Array.isArray(err)
-                        ? new ClientError({ message: err[0].message })
-                        : new ServerError({ message: String(err) }));
-                },
-                complete: () => void emit.end(),
-            });
-            // Ensure we dispose of the query if the running Fiber is terminated.
-            return Effect.sync(dispose);
+        // Stream.async forks a top-level fiber per emit.single (via
+        // Runtime.runPromiseExit), which leaks into Effect's Global.roots at the
+        // ~1k msg/sec rate the indexer pushes. Stream.asyncPush writes straight
+        // to an internal queue and tears it down with the surrounding scope.
+        return Stream.asyncPush((emit) => Effect.acquireRelease(Effect.sync(() => this.client.subscribe({ query: print(document), variables: variables }, {
+            next: (data) => {
+                if (data.errors) {
+                    emit.fail(new ClientError({
+                        message: data.errors.map((e) => e.message).join('; '),
+                        cause: data.errors,
+                    }));
+                }
+                else {
+                    emit.single(data.data);
+                }
+            },
+            error: (err) => {
+                if (isGraphQLErrorArray(err)) {
+                    emit.fail(new ClientError({ message: err.map((e) => e.message).join('; '), cause: err }));
+                }
+                else {
+                    emit.fail(new ServerError({ message: String(err) }));
+                }
+            },
+            complete: () => {
+                emit.end();
+            },
+        })), (dispose) => Effect.sync(() => dispose())), { bufferSize: 'unbounded' });
+    }
+    subscribeWithBackpressure(document, options) {
+        const client = this.client;
+        // Adapt graphql-ws's Sink callbacks to the generic Source contract; the
+        // backpressure/lifecycle logic lives in `withBackpressure`.
+        const source = ({ variables, onItem, onError, onComplete }) => client.subscribe({ query: print(document), variables: variables }, {
+            next: (data) => {
+                if (data.errors)
+                    onError(toClientOrServerError(data.errors));
+                else
+                    onItem(data.data);
+            },
+            error: (err) => onError(toClientOrServerError(err)),
+            complete: onComplete,
         });
+        return withBackpressure(source, options);
     }
 }

package/dist/effect/test/backpressure.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/effect/test/backpressure.test.js

@@ -0,0 +1,146 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { describe, it, expect } from 'vitest';
+import { initialBPState, decideItem, decideTerminate, decideComplete, decideResume, } from '../Backpressure.js';
+const state = (overrides = {}) => ({
+    ...initialBPState(0n),
+    ...overrides,
+});
+describe('Backpressure state machine', () => {
+    describe('decideItem', () => {
+        it('emits and advances watermark when key is strictly greater than lastKey', () => {
+            const [decision, next] = decideItem(state({ lastKey: 5n }), 6n, 0, 1000);
+            expect(decision).toEqual({ emit: true, pause: false });
+            expect(next.lastKey).toBe(6n);
+            expect(next.inFlight).toBe(1);
+        });
+        it('drops the item at `from` on the initial session (exclusive watermark)', () => {
+            // The watermark seeds from `from`, so the item whose key equals `from` is treated as
+            // already-seen. A caller that wants the item at its logical cursor emitted seeds `from` one
+            // below it (e.g. a wallet passes `appliedIndex - 1` to still receive the boundary event).
+            const before = initialBPState(5n);
+            const [decision, next] = decideItem(before, 5n, 0, 1000);
+            expect(decision.emit).toBe(false);
+            expect(next).toBe(before);
+        });
+        it('drops a re-delivered boundary equal to lastKey (inclusive-cursor dedup)', () => {
+            // An inclusive resume cursor re-delivers the last-emitted key; the exclusive watermark drops
+            // it so it is not emitted twice.
+            const before = state({ lastKey: 5n, inFlight: 0 });
+            const [decision, next] = decideItem(before, 5n, 0, 1000);
+            expect(decision.emit).toBe(false);
+            expect(next).toBe(before);
+        });
+        it('drops items below lastKey', () => {
+            const before = state({ lastKey: 5n });
+            const [decision, next] = decideItem(before, 3n, 0, 1000);
+            expect(decision.emit).toBe(false);
+            expect(next).toBe(before);
+        });
+        it('drops items from a stale generation', () => {
+            const before = state({ generation: 2 });
+            const [decision, next] = decideItem(before, 1n, 1, 1000);
+            expect(decision.emit).toBe(false);
+            expect(next).toBe(before);
+        });
+        it('drops items when terminal', () => {
+            const before = state({ terminal: true });
+            const [decision, next] = decideItem(before, 1n, 0, 1000);
+            expect(decision.emit).toBe(false);
+            expect(next).toBe(before);
+        });
+        it('sets pause when inFlight reaches bufferSize', () => {
+            const [decision, next] = decideItem(state({ lastKey: 5n, inFlight: 2 }), 6n, 0, 3);
+            expect(decision).toEqual({ emit: true, pause: true });
+            expect(next.paused).toBe(true);
+            expect(next.inFlight).toBe(3);
+        });
+        it('does not re-pause when already paused', () => {
+            const [decision, next] = decideItem(state({ lastKey: 5n, inFlight: 3, paused: true }), 6n, 0, 3);
+            expect(decision).toEqual({ emit: true, pause: false });
+            expect(next.paused).toBe(true);
+        });
+    });
+    describe('decideTerminate', () => {
+        it('surfaces a terminal event and marks state terminal', () => {
+            const [shouldSurface, next] = decideTerminate(state(), 0);
+            expect(shouldSurface).toBe(true);
+            expect(next.terminal).toBe(true);
+        });
+        it('swallows terminal events from a stale generation', () => {
+            const before = state({ generation: 2 });
+            const [shouldSurface, next] = decideTerminate(before, 1);
+            expect(shouldSurface).toBe(false);
+            expect(next).toBe(before);
+        });
+        it('is idempotent — already-terminal state returns false', () => {
+            const before = state({ terminal: true });
+            const [shouldSurface, next] = decideTerminate(before, 0);
+            expect(shouldSurface).toBe(false);
+            expect(next).toBe(before);
+        });
+    });
+    describe('decideComplete', () => {
+        it('signals end-of-stream when not paused, stale, or terminal', () => {
+            const [shouldEnd, next] = decideComplete(state(), 0);
+            expect(shouldEnd).toBe(true);
+            expect(next.terminal).toBe(true);
+        });
+        it('treats paused completion as dispose-induced (no end)', () => {
+            // This is the regression case: without the paused check, a dispose-on-pause
+            // would deliver a `complete:` from the old session and terminate the
+            // consumer-visible stream mid-resume.
+            const before = state({ paused: true });
+            const [shouldEnd, next] = decideComplete(before, 0);
+            expect(shouldEnd).toBe(false);
+            expect(next).toBe(before);
+        });
+        it('swallows completions from a stale generation', () => {
+            const before = state({ generation: 2 });
+            const [shouldEnd, next] = decideComplete(before, 1);
+            expect(shouldEnd).toBe(false);
+            expect(next).toBe(before);
+        });
+    });
+    describe('decideResume', () => {
+        it('resumes and bumps generation when paused and drained to threshold', () => {
+            const [shouldResume, next] = decideResume(state({ paused: true, inFlight: 3, generation: 4 }), 2);
+            expect(shouldResume).toBe(true);
+            expect(next).toMatchObject({ paused: false, inFlight: 2, generation: 5 });
+        });
+        it('decrements inFlight even when not resuming (drain accounting)', () => {
+            const [shouldResume, next] = decideResume(state({ paused: false, inFlight: 7 }), 2);
+            expect(shouldResume).toBe(false);
+            expect(next.inFlight).toBe(6);
+        });
+        it('does not resume when above threshold', () => {
+            const [shouldResume, next] = decideResume(state({ paused: true, inFlight: 5 }), 2);
+            expect(shouldResume).toBe(false);
+            expect(next).toMatchObject({ paused: true, inFlight: 4 });
+        });
+        it('does not resume when terminal', () => {
+            const before = state({ paused: true, inFlight: 3, terminal: true });
+            const [shouldResume, next] = decideResume(before, 2);
+            expect(shouldResume).toBe(false);
+            expect(next).toBe(before);
+        });
+        it('clamps inFlight at zero (defensive against drain underflow)', () => {
+            const [, next] = decideResume(state({ inFlight: 0 }), 2);
+            expect(next.inFlight).toBe(0);
+        });
+        it('does not resume when not paused, even if drained', () => {
+            const [shouldResume] = decideResume(state({ paused: false, inFlight: 0 }), 2);
+            expect(shouldResume).toBe(false);
+        });
+    });
+});

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-indexer-client",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "type": "module",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "Midnight Foundation",
   "license": "Apache-2.0",
   "publishConfig": {
-    "registry": "https://npm.pkg.github.com/"
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   },
   "files": [
     "dist/"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/midnight-ntwrk/artifacts.git"
+    "url": "git+https://github.com/midnightntwrk/midnight-wallet.git",
+    "directory": "packages/indexer-client"
   },
   "exports": {
     ".": {
@@ -35,10 +37,10 @@
     "graphql-ws": "^6.0.7"
   },
   "devDependencies": {
-    "@graphql-codegen/cli": "^7.0.0",
-    "@graphql-codegen/client-preset": "^6.0.0",
-    "@graphql-codegen/typescript": "^6.0.0",
-    "@graphql-codegen/typescript-operations": "^6.0.0"
+    "@graphql-codegen/cli": "7.1.2",
+    "@graphql-codegen/client-preset": "6.0.1",
+    "@graphql-codegen/typescript": "6.0.2",
+    "@graphql-codegen/typescript-operations": "6.0.3"
   },
   "scripts": {
     "gql:codegen": "graphql-codegen --clean --config codegen.ts",