@stream-io/video-client 1.48.0 → 1.49.0

package/src/StreamSfuClient.ts

@@ -28,7 +28,7 @@ import {
 } from './gen/video/sfu/signal_rpc/signal';
 import { ICETrickle } from './gen/video/sfu/models/models';
 import { StreamClient } from './coordinator/connection/client';
-import { generateUUIDv4 } from './coordinator/connection/utils';
+import { generateUUIDv4, sleep } from './coordinator/connection/utils';
 import { Credentials } from './gen/coordinator';
 import { ScopedLogger, videoLoggerSystem } from './logger';
 import {
@@ -104,6 +104,21 @@ type SfuWebSocketParams = {
   cid: string;
 };
 
+/**
+ * Creates a fresh `joinResponseTask` with a no-op rejection handler attached
+ * to the underlying promise. The handler marks the rejection path as handled
+ * so a teardown-time reject (e.g., from `close()` during disposal) does not
+ * surface as an `UnhandledPromiseRejection`. Explicit awaiters of
+ * `StreamSfuClient.joinTask` still observe the rejection through their own
+ * `then`/`catch` chain. `.catch()` returns a new promise; the original is
+ * unchanged.
+ */
+const makeJoinResponseTask = (): PromiseWithResolvers<JoinResponse> => {
+  const task = promiseWithResolvers<JoinResponse>();
+  task.promise.catch(() => {}); // see the comment above
+  return task;
+};
+
 /**
  * The client used for exchanging information with the SFU.
  */
@@ -171,9 +186,10 @@ export class StreamSfuClient {
   private networkAvailableTask: PromiseWithResolvers<void> | undefined;
   /**
    * Promise that resolves when the JoinResponse is received.
-   * Rejects after a certain threshold if the response is not received.
+   * Rejects after a certain threshold if the response is not received,
+   * or when the SFU client is disposed before a join completes.
    */
-  private joinResponseTask = promiseWithResolvers<JoinResponse>();
+  private joinResponseTask = makeJoinResponseTask();
 
   /**
    * Promise that resolves when the migration is complete.
@@ -207,6 +223,12 @@ export class StreamSfuClient {
    * The close code used when the client fails to join the call (on the SFU).
    */
   static JOIN_FAILED = 4101;
+  /**
+   * Best-effort grace period in `leaveAndClose` for an in-flight join to
+   * complete before we give up and close without sending `leaveCallRequest`.
+   * Bounded so a stuck join can never hang the leave path.
+   */
+  static LEAVE_NOTIFY_GRACE_MS = 1000;
 
   /**
    * Constructs a new SFU client.
@@ -358,15 +380,24 @@ export class StreamSfuClient {
 
   close = (code: number = StreamSfuClient.NORMAL_CLOSURE, reason?: string) => {
     this.isClosingClean = code !== StreamSfuClient.ERROR_CONNECTION_UNHEALTHY;
-    if (this.signalWs.readyState === WebSocket.OPEN) {
+    // Close the WebSocket whether it has fully opened (`OPEN`) or is still
+    // mid-handshake (`CONNECTING`). The WebSocket spec aborts the handshake
+    // when `close()` is called on a CONNECTING socket. Without this, an
+    // SFU socket that opens just after teardown would dispatch events into
+    // a Call instance that has already moved on.
+    const ws = this.signalWs;
+    if (
+      ws.readyState === WebSocket.OPEN ||
+      ws.readyState === WebSocket.CONNECTING
+    ) {
       this.logger.debug(`Closing SFU WS connection: ${code} - ${reason}`);
-      this.signalWs.close(code, `js-client: ${reason}`);
-      this.signalWs.removeEventListener('close', this.handleWebSocketClose);
+      ws.close(code, `js-client: ${reason}`);
+      ws.removeEventListener('close', this.handleWebSocketClose);
     }
-    this.dispose();
+    this.dispose(reason);
   };
 
-  private dispose = () => {
+  private dispose = (reason?: string) => {
     this.logger.debug('Disposing SFU client');
     this.unsubscribeIceTrickle();
     this.unsubscribeNetworkChanged();
@@ -375,6 +406,19 @@ export class StreamSfuClient {
     clearTimeout(this.migrateAwayTimeout);
     this.abortController.abort();
     this.migrationTask?.resolve();
+    // Settle a pending `joinResponseTask` so `leaveAndClose`, `join()`, and
+    // any other awaiters (`await this.joinTask`) don't hang indefinitely
+    // when the SFU client is torn down before the SFU sent a JoinResponse.
+    if (
+      !this.joinResponseTask.isResolved() &&
+      !this.joinResponseTask.isRejected()
+    ) {
+      this.joinResponseTask.reject(
+        new Error(
+          `SFU client disposed before join completed${reason ? `: ${reason}` : ''}`,
+        ),
+      );
+    }
     this.iceTrickleBuffer.dispose();
   };
 
@@ -385,8 +429,27 @@ export class StreamSfuClient {
   leaveAndClose = async (reason: string) => {
     try {
       this.isLeaving = true;
-      await this.joinTask;
-      await this.notifyLeave(reason);
+      // Best-effort: give an in-flight join a short grace period to complete
+      // so we can send a graceful `leaveCallRequest`. Bounded so we never hang
+      // here if the SFU is unresponsive. If the task settles either way during
+      // the wait, the re-check below decides whether to notify.
+      if (
+        !this.joinResponseTask.isResolved() &&
+        !this.joinResponseTask.isRejected()
+      ) {
+        await Promise.race([
+          // swallow rejection — we re-check `isResolved()` below to decide
+          this.joinResponseTask.promise.catch(() => {}),
+          sleep(StreamSfuClient.LEAVE_NOTIFY_GRACE_MS),
+        ]);
+      }
+      if (this.joinResponseTask.isResolved()) {
+        await this.notifyLeave(reason);
+      } else {
+        this.logger.debug(
+          '[leaveAndClose] join not completed within grace period, skipping notifyLeave',
+        );
+      }
     } catch (err) {
       this.logger.debug('Error notifying SFU about leaving call', err);
     }
@@ -535,9 +598,9 @@ export class StreamSfuClient {
     ) {
       // we need to lock the RPC requests until we receive a JoinResponse.
       // that's why we have this primitive lock mechanism.
-      // the client starts with already initialized joinResponseTask,
+      // the client starts with an already initialized joinResponseTask,
       // and this code creates a new one for the next join request.
-      this.joinResponseTask = promiseWithResolvers<JoinResponse>();
+      this.joinResponseTask = makeJoinResponseTask();
     }
 
     // capture a reference to the current joinResponseTask as it might

package/src/__tests__/Call.publishing.test.ts

@@ -290,6 +290,109 @@ describe('Publishing and Unpublishing tracks', () => {
       expect(participant!.screenShareStream).toBeUndefined();
       expect(participant!.screenShareAudioStream).toBeUndefined();
     });
+
+    it('does not throw if sfuClient is cleared while the mute-state RPC is in flight', async () => {
+      let releaseMuteUpdate!: () => void;
+      let signalMuteUpdateEntered!: () => void;
+      const muteUpdateEntered = new Promise<void>(
+        (resolve) => (signalMuteUpdateEntered = resolve),
+      );
+      sfuClient.updateMuteStates = vi.fn().mockImplementation(() => {
+        signalMuteUpdateEntered();
+        return new Promise<void>((resolve) => (releaseMuteUpdate = resolve));
+      });
+
+      const track = new MediaStreamTrack() as MediaStreamAudioTrack;
+      const mediaStream = new MediaStream();
+      vi.spyOn(mediaStream, 'getAudioTracks').mockReturnValue([track]);
+
+      const inflight = call.publish(mediaStream, TrackType.AUDIO);
+
+      await muteUpdateEntered;
+
+      call['sfuClient'] = undefined;
+      releaseMuteUpdate();
+
+      await inflight;
+    });
+
+    it('updates local stream state when sfuClient is replaced with the same session id', async () => {
+      let releaseMuteUpdate!: () => void;
+      let signalMuteUpdateEntered!: () => void;
+      const muteUpdateEntered = new Promise<void>(
+        (resolve) => (signalMuteUpdateEntered = resolve),
+      );
+      sfuClient.updateMuteStates = vi.fn().mockImplementation(() => {
+        signalMuteUpdateEntered();
+        return new Promise<void>((resolve) => (releaseMuteUpdate = resolve));
+      });
+
+      const track = new MediaStreamTrack() as MediaStreamAudioTrack;
+      const mediaStream = new MediaStream();
+      vi.spyOn(mediaStream, 'getAudioTracks').mockReturnValue([track]);
+
+      const inflight = call.publish(mediaStream, TrackType.AUDIO);
+
+      await muteUpdateEntered;
+
+      const replacementSfuClient = vi.fn() as unknown as StreamSfuClient;
+      // @ts-expect-error sessionId is readonly
+      replacementSfuClient['sessionId'] = sessionId;
+      replacementSfuClient.updateMuteStates = vi.fn();
+      call['sfuClient'] = replacementSfuClient;
+      releaseMuteUpdate();
+
+      await inflight;
+
+      const participant = call.state.findParticipantBySessionId(sessionId);
+      expect(participant?.publishedTracks).toEqual([TrackType.AUDIO]);
+      expect(participant?.audioStream).toBe(mediaStream);
+    });
+
+    it('skips local stream state update when sfuClient is replaced with a new session id', async () => {
+      let releaseMuteUpdate!: () => void;
+      let signalMuteUpdateEntered!: () => void;
+      const muteUpdateEntered = new Promise<void>(
+        (resolve) => (signalMuteUpdateEntered = resolve),
+      );
+      sfuClient.updateMuteStates = vi.fn().mockImplementation(() => {
+        signalMuteUpdateEntered();
+        return new Promise<void>((resolve) => (releaseMuteUpdate = resolve));
+      });
+
+      const track = new MediaStreamTrack() as MediaStreamAudioTrack;
+      const mediaStream = new MediaStream();
+      vi.spyOn(mediaStream, 'getAudioTracks').mockReturnValue([track]);
+
+      const inflight = call.publish(mediaStream, TrackType.AUDIO);
+
+      await muteUpdateEntered;
+
+      const replacementSessionId = 'replacement-session-id';
+      // @ts-expect-error partial data
+      call.state.updateOrAddParticipant(replacementSessionId, {
+        sessionId: replacementSessionId,
+        publishedTracks: [],
+      });
+
+      const replacementSfuClient = vi.fn() as unknown as StreamSfuClient;
+      // @ts-expect-error sessionId is readonly
+      replacementSfuClient['sessionId'] = replacementSessionId;
+      replacementSfuClient.updateMuteStates = vi.fn();
+      call['sfuClient'] = replacementSfuClient;
+      releaseMuteUpdate();
+
+      await inflight;
+
+      const originalParticipant =
+        call.state.findParticipantBySessionId(sessionId);
+      const replacementParticipant =
+        call.state.findParticipantBySessionId(replacementSessionId);
+      expect(originalParticipant?.publishedTracks).toEqual([]);
+      expect(originalParticipant?.audioStream).toBeUndefined();
+      expect(replacementParticipant?.publishedTracks).toEqual([]);
+      expect(replacementParticipant?.audioStream).toBeUndefined();
+    });
   });
 
   describe('Deprecated methods', () => {

package/src/__tests__/StreamSfuClient.test.ts

@@ -0,0 +1,275 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { StreamSfuClient } from '../StreamSfuClient';
+import { Dispatcher } from '../rtc';
+import { StreamClient } from '../coordinator/connection/client';
+
+/**
+ * Minimal `WebSocket` stub used to drive `StreamSfuClient.close()` while the
+ * underlying connection is still in `CONNECTING` state. The constructor
+ * leaves `readyState = CONNECTING`; `close()` records the call and flips
+ * to `CLOSED` so subsequent assertions can see what happened.
+ */
+class CapturingWebSocket {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSING = 2;
+  static CLOSED = 3;
+  static instances: CapturingWebSocket[] = [];
+
+  readyState = CapturingWebSocket.CONNECTING;
+  url: string;
+  binaryType = 'blob';
+  closeArgs: { code?: number; reason?: string } | undefined;
+  private listeners = new Map<string, Set<(e: unknown) => void>>();
+
+  constructor(url: string | URL) {
+    this.url = typeof url === 'string' ? url : url.toString();
+    CapturingWebSocket.instances.push(this);
+  }
+
+  addEventListener(event: string, listener: (e: unknown) => void) {
+    if (!this.listeners.has(event)) this.listeners.set(event, new Set());
+    this.listeners.get(event)!.add(listener);
+  }
+  removeEventListener(event: string, listener: (e: unknown) => void) {
+    this.listeners.get(event)?.delete(listener);
+  }
+  close(code?: number, reason?: string) {
+    this.closeArgs = { code, reason };
+    this.readyState = CapturingWebSocket.CLOSED;
+  }
+}
+
+const buildSfuClient = () => {
+  const dispatcher = new Dispatcher();
+  const streamClient = new StreamClient('test-key');
+  return new StreamSfuClient({
+    dispatcher,
+    sessionId: 'session-id-test',
+    streamClient,
+    cid: 'default:test',
+    credentials: {
+      server: {
+        url: 'https://test.invalid',
+        ws_endpoint: 'wss://test.invalid/ws',
+        edge_name: 'sfu-test',
+      },
+      token: 'token',
+      ice_servers: [],
+    },
+    tag: 'test',
+    enableTracing: false,
+  });
+};
+
+describe('StreamSfuClient.close()', () => {
+  beforeEach(() => {
+    CapturingWebSocket.instances = [];
+    vi.stubGlobal('WebSocket', CapturingWebSocket);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+  });
+
+  it('closes the WebSocket even when it is still in CONNECTING state', () => {
+    const sfuClient = buildSfuClient();
+    const ws = CapturingWebSocket.instances.at(-1)!;
+    expect(ws.readyState).toBe(CapturingWebSocket.CONNECTING);
+
+    sfuClient.close(1000, 'tearing down');
+
+    expect(ws.closeArgs).toBeDefined();
+    expect(ws.closeArgs?.code).toBe(1000);
+    expect(ws.readyState).toBe(CapturingWebSocket.CLOSED);
+  });
+
+  it('rejects a pending joinResponseTask on close so awaiters do not hang', async () => {
+    const sfuClient = buildSfuClient();
+    const joinTask = sfuClient.joinTask;
+
+    sfuClient.close(1000, 'aborting');
+
+    await expect(joinTask).rejects.toThrow(/SFU client disposed/);
+  });
+
+  it('does not blow up when the WebSocket is already CLOSED', () => {
+    const sfuClient = buildSfuClient();
+    const ws = CapturingWebSocket.instances.at(-1)!;
+    ws.readyState = CapturingWebSocket.CLOSED;
+
+    expect(() => sfuClient.close(1000, 'noop')).not.toThrow();
+    // close() should not be called twice
+    expect(ws.closeArgs).toBeUndefined();
+  });
+
+  it('leaveAndClose returns within ~grace period when the SFU is silent (no hang)', async () => {
+    const sfuClient = buildSfuClient();
+    vi.spyOn(
+      sfuClient as unknown as {
+        notifyLeave: (reason: string) => Promise<void>;
+      },
+      'notifyLeave',
+    ).mockResolvedValue(undefined);
+
+    // joinResponseTask stays pending forever — verify leaveAndClose still returns.
+    const start = Date.now();
+    await Promise.race([
+      sfuClient.leaveAndClose('silent-sfu'),
+      new Promise((_, reject) =>
+        setTimeout(
+          () => reject(new Error('leaveAndClose hung past 2x grace')),
+          StreamSfuClient.LEAVE_NOTIFY_GRACE_MS * 2,
+        ),
+      ),
+    ]);
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeLessThan(StreamSfuClient.LEAVE_NOTIFY_GRACE_MS * 2);
+  });
+
+  it('close() does NOT produce an unhandled rejection when nobody awaits joinTask', async () => {
+    // Capture unhandledrejection events that fire during this test. Without
+    // the safe-catch attached to `joinResponseTask.promise`, dispose-time
+    // reject would surface here.
+    const unhandled: PromiseRejectionEvent[] = [];
+    const onUnhandled = (e: PromiseRejectionEvent) => {
+      unhandled.push(e);
+      // mark as handled so it doesn't crash the test runner
+      e.preventDefault?.();
+    };
+    if (typeof window !== 'undefined') {
+      window.addEventListener('unhandledrejection', onUnhandled);
+    }
+    // Node-side fallback so the test passes regardless of test environment.
+    const onProcessUnhandled = (reason: unknown) => {
+      unhandled.push({ reason } as unknown as PromiseRejectionEvent);
+    };
+    process.on('unhandledRejection', onProcessUnhandled);
+
+    try {
+      const sfuClient = buildSfuClient();
+      // Intentionally do NOT touch joinTask anywhere — no .catch, no await.
+      sfuClient.close(1000, 'aborting before any join');
+
+      // give microtasks + a tick for any unhandledrejection event to fire
+      await new Promise((r) => setTimeout(r, 50));
+      expect(unhandled).toHaveLength(0);
+    } finally {
+      if (typeof window !== 'undefined') {
+        window.removeEventListener('unhandledrejection', onUnhandled);
+      }
+      process.off('unhandledRejection', onProcessUnhandled);
+    }
+  });
+});
+
+describe('StreamSfuClient.leaveAndClose()', () => {
+  beforeEach(() => {
+    CapturingWebSocket.instances = [];
+    vi.stubGlobal('WebSocket', CapturingWebSocket);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+  });
+
+  type JoinResponseTaskHandle = {
+    joinResponseTask: {
+      resolve: (v: unknown) => void;
+      reject: (err: unknown) => void;
+    };
+  };
+
+  it('notifies the SFU when joinResponseTask is already resolved', async () => {
+    const sfuClient = buildSfuClient();
+    (sfuClient as unknown as JoinResponseTaskHandle).joinResponseTask.resolve(
+      {},
+    );
+    const notifyLeaveSpy = vi
+      .spyOn(
+        sfuClient as unknown as {
+          notifyLeave: (reason: string) => Promise<void>;
+        },
+        'notifyLeave',
+      )
+      .mockResolvedValue(undefined);
+
+    await sfuClient.leaveAndClose('user-leaving');
+
+    expect(notifyLeaveSpy).toHaveBeenCalledWith('user-leaving');
+  });
+
+  it('waits for an in-flight join and notifies the SFU when it resolves within the grace period', async () => {
+    const sfuClient = buildSfuClient();
+    const notifyLeaveSpy = vi
+      .spyOn(
+        sfuClient as unknown as {
+          notifyLeave: (reason: string) => Promise<void>;
+        },
+        'notifyLeave',
+      )
+      .mockResolvedValue(undefined);
+
+    vi.useFakeTimers();
+    const leavePromise = sfuClient.leaveAndClose('user-leaving');
+
+    // simulate the SFU sending JoinResponse 50 ms in (well within the grace window)
+    await vi.advanceTimersByTimeAsync(50);
+    (sfuClient as unknown as JoinResponseTaskHandle).joinResponseTask.resolve(
+      {},
+    );
+    // flush remaining timers (the losing race branch and any microtasks)
+    await vi.runAllTimersAsync();
+    await leavePromise;
+
+    expect(notifyLeaveSpy).toHaveBeenCalledWith('user-leaving');
+  });
+
+  it('skips notifyLeave when the join does not complete within the grace period', async () => {
+    const sfuClient = buildSfuClient();
+    const notifyLeaveSpy = vi
+      .spyOn(
+        sfuClient as unknown as {
+          notifyLeave: (reason: string) => Promise<void>;
+        },
+        'notifyLeave',
+      )
+      .mockResolvedValue(undefined);
+
+    vi.useFakeTimers();
+    const leavePromise = sfuClient.leaveAndClose('silent-sfu');
+    // run past the grace window — the task is never resolved
+    await vi.advanceTimersByTimeAsync(
+      StreamSfuClient.LEAVE_NOTIFY_GRACE_MS + 50,
+    );
+    await leavePromise;
+
+    expect(notifyLeaveSpy).not.toHaveBeenCalled();
+  });
+
+  it('skips notifyLeave when joinResponseTask rejects within the grace period', async () => {
+    const sfuClient = buildSfuClient();
+    const notifyLeaveSpy = vi
+      .spyOn(
+        sfuClient as unknown as {
+          notifyLeave: (reason: string) => Promise<void>;
+        },
+        'notifyLeave',
+      )
+      .mockResolvedValue(undefined);
+
+    vi.useFakeTimers();
+    const leavePromise = sfuClient.leaveAndClose('rejected');
+    await vi.advanceTimersByTimeAsync(20);
+    (sfuClient as unknown as JoinResponseTaskHandle).joinResponseTask.reject(
+      new Error('SFU went away'),
+    );
+    await vi.runAllTimersAsync();
+    await leavePromise;
+
+    expect(notifyLeaveSpy).not.toHaveBeenCalled();
+  });
+});

package/src/devices/DeviceManagerState.ts

@@ -19,6 +19,9 @@ export abstract class DeviceManagerState<C = MediaTrackConstraints> {
   protected mediaStreamSubject = new BehaviorSubject<MediaStream | undefined>(
     undefined,
   );
+  protected rootMediaStreamSubject = new BehaviorSubject<
+    MediaStream | undefined
+  >(undefined);
   protected selectedDeviceSubject = new BehaviorSubject<string | undefined>(
     undefined,
   );
@@ -37,6 +40,13 @@ export abstract class DeviceManagerState<C = MediaTrackConstraints> {
    */
   mediaStream$ = this.mediaStreamSubject.asObservable();
 
+  /**
+   * An Observable that emits the raw device media stream (before any filters are applied),
+   * or `undefined` if the device is currently disabled. When no filters are active, this
+   * emits the same stream as `mediaStream$`.
+   */
+  rootMediaStream$ = this.rootMediaStreamSubject.asObservable();
+
   /**
    * An Observable that emits the currently selected device
    */
@@ -134,6 +144,15 @@ export abstract class DeviceManagerState<C = MediaTrackConstraints> {
     return RxUtils.getCurrentValue(this.mediaStream$);
   }
 
+  /**
+   * The raw device media stream (before any filters are applied), or `undefined`
+   * if the device is currently disabled. When no filters are active, this is the
+   * same as `mediaStream`.
+   */
+  get rootMediaStream() {
+    return RxUtils.getCurrentValue(this.rootMediaStream$);
+  }
+
   /**
    * @internal
    * @param status
@@ -163,6 +182,7 @@ export abstract class DeviceManagerState<C = MediaTrackConstraints> {
     rootStream: MediaStream | undefined,
   ) {
     RxUtils.setCurrentValue(this.mediaStreamSubject, stream);
+    RxUtils.setCurrentValue(this.rootMediaStreamSubject, rootStream);
     if (rootStream) {
       this.setDevice(this.getDeviceIdFromStream(rootStream));
     }

package/src/devices/__tests__/ScreenShareManager.test.ts

@@ -34,7 +34,6 @@ describe('ScreenShareManager', () => {
   let manager: ScreenShareManager;
 
   beforeEach(() => {
-    const devicePersistence = { enabled: false, storageKey: '' };
     manager = new ScreenShareManager(
       new Call({
         id: '',
@@ -42,7 +41,6 @@ describe('ScreenShareManager', () => {
         streamClient: new StreamClient('abc123'),
         clientStore: new StreamVideoWriteableStateStore(),
       }),
-      devicePersistence,
     );
   });
 

package/src/devices/devices.ts

@@ -340,7 +340,6 @@ export const getScreenShareStream = async (
   const tag = `navigator.mediaDevices.getDisplayMedia.${getDisplayMediaExecId++}.`;
   try {
     const constraints: DisplayMediaStreamOptions = {
-      // @ts-expect-error - not present in types yet
       systemAudio: 'include',
       ...options,
       video:
@@ -357,6 +356,8 @@ export const getScreenShareStream = async (
           ? options.audio
           : {
               channelCount: { ideal: 2 },
+              // @ts-expect-error not yet present in the types
+              restrictOwnAudio: true,
               echoCancellation: false,
               autoGainControl: false,
               noiseSuppression: false,

package/src/helpers/SlidingWindowRateLimiter.ts

@@ -0,0 +1,49 @@
+/**
+ * A generic sliding-window rate limiter.
+ *
+ * Allows at most `maxAttempts` registrations inside a rolling `windowMs`.
+ * Attempts spaced further apart than `windowMs` are always allowed.
+ */
+export class SlidingWindowRateLimiter {
+  private maxAttempts: number;
+  private windowMs: number;
+  private timestamps: number[] = [];
+
+  constructor(maxAttempts: number, windowMs: number) {
+    this.maxAttempts = maxAttempts;
+    this.windowMs = windowMs;
+  }
+
+  /**
+   * Attempts to register a new event at `now`. Returns `true` if the attempt
+   * fits inside the budget (and records it), or `false` if the budget is
+   * exhausted (in which case no timestamp is recorded).
+   */
+  tryRegister = (now: number = Date.now()): boolean => {
+    this.prune(now);
+    if (this.timestamps.length >= this.maxAttempts) return false;
+    this.timestamps.push(now);
+    return true;
+  };
+
+  /**
+   * Clears the attempt history.
+   */
+  reset = (): void => {
+    this.timestamps = [];
+  };
+
+  /**
+   * Updates the budget and window size. Existing timestamps are kept; they
+   * will be pruned by the next `tryRegister` call.
+   */
+  setLimits = (maxAttempts: number, windowMs: number): void => {
+    this.maxAttempts = maxAttempts;
+    this.windowMs = windowMs;
+  };
+
+  private prune = (now: number): void => {
+    const cutoff = now - this.windowMs;
+    this.timestamps = this.timestamps.filter((t) => t >= cutoff);
+  };
+}