@dev-crew-berlin/enter-js-utils 0.97.5 → 0.98.9

package/dist/api-client/api-base.d.ts

@@ -23,6 +23,12 @@ export type FetchOptions = {
         revalidate: false | 0 | number;
     };
 };
+export type SubscribeOptions = {
+    signal?: AbortSignal;
+    onReset?: () => void;
+    onConnectionChange?: (state: 'connected' | 'reconnecting') => void;
+    initialLastEventId?: string;
+};
 export default class APIBase {
     private credentials;
     private isLoggedIn;
@@ -36,8 +42,8 @@ export default class APIBase {
         onLogout: (reason?: string) => void;
     });
     private static fetchResult;
-    private buildHeaders;
-    private fetchResponse;
+    protected buildHeaders(extraHeaders?: Record<string, string>): Record<string, string>;
+    protected fetchResponse(endpoint: string, init: RequestInit): Promise<APIResult<Response>>;
     /**
      * @category Auth
      */
@@ -56,7 +62,22 @@ export default class APIBase {
         expires: Date;
     }>>;
     private fetchFromEnter;
-    protected stream<T>(endpoint: string, options?: FetchOptions): AsyncGenerator<T>;
+    /**
+     * Self-healing SSE stream with automatic reconnect, heartbeat watchdog, and
+     * cursor-based replay. Yields domain events as parsed JSON.
+     *
+     * Reconnect behaviour: when the connection drops (network error, server
+     * close, or watchdog timeout) the method sleeps with exponential backoff and
+     * jitter, then opens a new request. The last received SSE `id` is sent as
+     * `Last-Event-ID` so the server can replay missed events. Backoff resets
+     * after a connection that stayed alive long enough to be considered healthy.
+     *
+     * The loop exits without retrying on 401 (session expired — logout is
+     * handled by fetchResponse) or when the consumer breaks / the external
+     * signal fires.
+     */
+    protected stream<T>(endpoint: string, options?: SubscribeOptions): AsyncGenerator<T>;
+    private readSseEvents;
     protected get<Path extends keyof paths>(endpoint: Path, options: FetchOptions): Promise<APIResult<ResponseType<Path, 'get'>>>;
     protected post<Path extends keyof paths>(endpoint: Path, data: RequestBody<Path, 'post'>, options: FetchOptions): Promise<APIResult<ResponseType<Path, 'post'>>>;
     protected put<Path extends keyof paths>(endpoint: Path, data: RequestBody<Path, 'put'>, options: FetchOptions): Promise<APIResult<ResponseType<Path, 'put'>>>;

package/dist/api-client/api-base.js

@@ -1,6 +1,21 @@
 import jws from 'jws';
 import { EventSourceParserStream } from 'eventsource-parser/stream';
 import { failure, success } from '../lib';
+const BACKOFF_INITIAL_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+const BACKOFF_RESET_AFTER_MS = 10_000;
+const WATCHDOG_TIMEOUT_MS = 45_000;
+function sleep(ms, signal) {
+  return new Promise(resolve => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener('abort', () => {
+      clearTimeout(timer);
+      resolve();
+    }, {
+      once: true
+    });
+  });
+}
 export default class APIBase {
   constructor(args) {
     this.credentials = args.credentials;
@@ -135,21 +150,121 @@ export default class APIBase {
     const json = await res.data.json();
     return success(json);
   }
+
+  /**
+   * Self-healing SSE stream with automatic reconnect, heartbeat watchdog, and
+   * cursor-based replay. Yields domain events as parsed JSON.
+   *
+   * Reconnect behaviour: when the connection drops (network error, server
+   * close, or watchdog timeout) the method sleeps with exponential backoff and
+   * jitter, then opens a new request. The last received SSE `id` is sent as
+   * `Last-Event-ID` so the server can replay missed events. Backoff resets
+   * after a connection that stayed alive long enough to be considered healthy.
+   *
+   * The loop exits without retrying on 401 (session expired — logout is
+   * handled by fetchResponse) or when the consumer breaks / the external
+   * signal fires.
+   */
   async *stream(endpoint, options = {}) {
-    const res = await this.fetchResponse(endpoint, {
-      method: 'GET',
-      headers: this.buildHeaders({
-        Accept: 'text/event-stream'
-      }),
-      ...options
-    });
-    if (!res.success) {
-      throw new Error(res.error[0]?.message ?? 'Unknown error');
-    }
-    if (!res.data.body) {
-      throw new Error('Response body is null');
+    const {
+      signal: externalSignal,
+      onReset,
+      onConnectionChange
+    } = options;
+
+    // outerAbort is the single switch that stops the whole reconnect loop.
+    // It is wired to the external signal and also fired in the finally block
+    // so that the sleep() in the backoff path is always interrupted on exit.
+    const outerAbort = new AbortController();
+    if (externalSignal?.aborted) return;
+    const onExternalAbort = () => outerAbort.abort();
+    externalSignal?.addEventListener('abort', onExternalAbort);
+    let lastEventId = options.initialLastEventId ?? null;
+    let backoffMs = BACKOFF_INITIAL_MS;
+    let isFirstConnect = true;
+    try {
+      while (!outerAbort.signal.aborted) {
+        // Fresh abort controller per attempt so the watchdog or a read error
+        // on one attempt cannot bleed into the next.
+        const attemptAbort = new AbortController();
+        const propagateAbort = () => attemptAbort.abort();
+        outerAbort.signal.addEventListener('abort', propagateAbort);
+        const hadCursor = lastEventId !== null;
+        const headers = {
+          Accept: 'text/event-stream'
+        };
+        // Sending Last-Event-ID lets the server replay events we missed while
+        // disconnected. If the cursor is unknown or too old, the server replies
+        // with event:reset instead of replaying.
+        if (hadCursor) headers['Last-Event-ID'] = lastEventId;
+
+        // connectedAt stays 0 when the attempt never reached a live stream,
+        // which prevents a spurious backoff reset on pure network failures.
+        let connectedAt = 0;
+        try {
+          const res = await this.fetchResponse(endpoint, {
+            method: 'GET',
+            headers: this.buildHeaders(headers),
+            signal: attemptAbort.signal
+          });
+          if (!res.success) {
+            const err = res.error[0];
+            // 401 means the session is gone — fetchResponse already called
+            // logout(), so stop retrying rather than hammering the server.
+            if (err?.type === 'http-error' && err.statusCode === 401) return;
+            // Any other failure (network error, 5xx, …) falls through to backoff.
+          } else if (res.data.body) {
+            connectedAt = Date.now();
+            onConnectionChange?.('connected');
+            // On a reconnect with no cursor we cannot know what events were
+            // missed, so tell the consumer to refetch their full state.
+            if (!isFirstConnect && !hadCursor) onReset?.();
+            isFirstConnect = false;
+            for await (const {
+              data,
+              id
+            } of this.readSseEvents(res.data.body, attemptAbort, onReset)) {
+              if (id) lastEventId = id;
+              yield data;
+            }
+          }
+        } catch {
+          // Covers fetch throwing (network error) and the stream aborting
+          // mid-read — both fall through to the backoff sleep below.
+        } finally {
+          outerAbort.signal.removeEventListener('abort', propagateAbort);
+          attemptAbort.abort();
+        }
+        if (outerAbort.signal.aborted) break;
+
+        // Reset backoff when the previous connection was healthy long enough;
+        // otherwise double it (with jitter) up to the cap.
+        const lived = connectedAt > 0 ? Date.now() - connectedAt : 0;
+        if (lived >= BACKOFF_RESET_AFTER_MS) backoffMs = BACKOFF_INITIAL_MS;
+        onConnectionChange?.('reconnecting');
+        await sleep(backoffMs, outerAbort.signal);
+        backoffMs = Math.min(backoffMs * 2, BACKOFF_MAX_MS) * (0.5 + Math.random());
+      }
+    } finally {
+      // Aborting here also unblocks any in-progress sleep() call.
+      outerAbort.abort();
+      externalSignal?.removeEventListener('abort', onExternalAbort);
     }
-    const reader = res.data.body.pipeThrough(new TextDecoderStream()).pipeThrough(new EventSourceParserStream()).getReader();
+  }
+
+  // Reads parsed SSE events from a single response body until the stream
+  // closes or the attemptAbort signal fires. Manages the heartbeat watchdog:
+  // if no message arrives within WATCHDOG_TIMEOUT_MS the connection is
+  // considered half-open (common on mobile networks) and is aborted so the
+  // outer loop can reconnect.
+  async *readSseEvents(body, attemptAbort, onReset) {
+    const reader = body.pipeThrough(new TextDecoderStream()).pipeThrough(new EventSourceParserStream()).getReader();
+    let watchdogTimer = null;
+    const resetWatchdog = () => {
+      if (watchdogTimer) clearTimeout(watchdogTimer);
+      watchdogTimer = setTimeout(() => attemptAbort.abort(), WATCHDOG_TIMEOUT_MS);
+    };
+    resetWatchdog();
     try {
       while (true) {
         const {
@@ -157,15 +272,31 @@ export default class APIBase {
           value: event
         } = await reader.read();
         if (done) break;
-        if (event.data === '[DONE]') return;
+
+        // Any message — including heartbeats — proves the connection is alive.
+        resetWatchdog();
+
+        // Heartbeats are only keepalives; never yield them to the consumer.
+        if (event.event === 'heartbeat') continue;
+        // The server sends reset when the requested cursor is unknown or too
+        // old. The consumer should refetch full state; we do not yield it.
+        if (event.event === 'reset') {
+          onReset?.();
+          continue;
+        }
         try {
-          yield JSON.parse(event.data);
+          yield {
+            data: JSON.parse(event.data),
+            id: event.id
+          };
         } catch {
           console.warn('[SSE] Failed to parse event data:', event.data);
         }
       }
     } finally {
+      if (watchdogTimer) clearTimeout(watchdogTimer);
       reader.releaseLock();
+      attemptAbort.abort();
     }
   }
   async get(endpoint, options) {

package/dist/api-client/api-client.test.js

@@ -0,0 +1,696 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import APIBase from './api-base';
+import API from './index';
+class TestAPI extends APIBase {
+  async *subscribe(endpoint, options = {}) {
+    yield* this.stream(endpoint, options);
+  }
+}
+function makeAPI() {
+  return new TestAPI({
+    credentials: {
+      accessToken: 'token',
+      url: 'https://api.example.com'
+    },
+    requesterId: 'req-1',
+    deviceName: 'test',
+    onLogout: vi.fn()
+  });
+}
+function sseChunk(messages) {
+  const text = messages.map(m => {
+    let s = '';
+    if (m.id !== undefined) s += `id: ${m.id}\n`;
+    if (m.event !== undefined) s += `event: ${m.event}\n`;
+    s += `data: ${m.data}\n\n`;
+    return s;
+  }).join('');
+  return new TextEncoder().encode(text);
+}
+
+// Creates a stream that enqueues chunks but does NOT close automatically.
+// Returns an explicit close() handle — the caller decides when the server
+// "shuts the connection", making the cause of any reconnect visible at the
+// call site rather than hidden inside a helper.
+// If the abort signal fires, the stream errors so in-progress reads throw.
+function makeStream(chunks, signal) {
+  let ctrl;
+  const stream = new ReadableStream({
+    start(controller) {
+      ctrl = controller;
+      if (signal?.aborted) {
+        controller.error(new DOMException('Aborted', 'AbortError'));
+        return;
+      }
+      signal?.addEventListener('abort', () => controller.error(new DOMException('Aborted', 'AbortError')), {
+        once: true
+      });
+      for (const chunk of chunks) controller.enqueue(chunk);
+    }
+  });
+  return {
+    stream,
+    push: chunk => ctrl.enqueue(chunk),
+    close: () => ctrl.close()
+  };
+}
+
+// Stream that hangs until the signal fires — intentionally never closed.
+function makeSilentStream(signal) {
+  return makeStream([], signal).stream;
+}
+function okResponse(body) {
+  return new Response(body, {
+    status: 200
+  });
+}
+function unauthorizedResponse() {
+  return new Response(null, {
+    status: 401,
+    statusText: 'Unauthorized'
+  });
+}
+
+// Flush the microtask queue by yielding many times.
+async function flushMicrotasks(rounds = 30) {
+  for (let i = 0; i < rounds; i++) await Promise.resolve();
+}
+
+// Flush pending microtasks (so the generator reaches its sleep() call and
+// registers the setTimeout), then advance fake timers by ms, then flush again
+// so the generator processes the reconnect before we assert.
+async function advanceTime(ms) {
+  await flushMicrotasks();
+  await vi.advanceTimersByTimeAsync(ms);
+  await flushMicrotasks();
+}
+describe('resilientStream', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  // ─── basic event delivery ────────────────────────────────────────────────
+
+  it('yields parsed JSON events', async () => {
+    const payload = {
+      type: 'attendee.updated',
+      id: '42'
+    };
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        data: JSON.stringify(payload)
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const response = await gen.next();
+    expect(response.value).toEqual(payload);
+    expect(response.done).toBe(false);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── reconnect after stream end ──────────────────────────────────────────
+
+  it('reconnects after stream ends normally', async () => {
+    const event1 = {
+      n: 1
+    };
+    const event2 = {
+      n: 2
+    };
+    const events = [event1, event2];
+    let connectionCount = 0;
+    let closeStream;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      const {
+        stream,
+        close
+      } = makeStream([sseChunk([{
+        data: JSON.stringify(events.shift())
+      }])], init.signal);
+      closeStream = close;
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const response1 = await gen.next();
+    expect(response1.value).toEqual(event1);
+
+    // Closing the stream is what triggers the reconnect
+    // the generator exits the read loop and enters backoff.
+    closeStream();
+
+    // Dont await here so we can advance time and dont have to wait for backoff
+    const response2Promise = gen.next();
+    await advanceTime(3000); // past max jittered initial backoff
+    const response2 = await response2Promise;
+    expect(response2.value).toEqual(event2);
+    expect(connectionCount).toBe(2);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── reconnect after fetch error ─────────────────────────────────────────
+
+  it('reconnects after fetch network error', async () => {
+    const event = {
+      ok: true
+    };
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      if (connectionCount === 1) return Promise.reject(new Error('Network failure'));
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        data: JSON.stringify(event)
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+
+    // fails on first attempt and hides retry, but takes some backoff time before retrying
+    const response1Promise = gen.next();
+    await advanceTime(3000);
+    const response1 = await response1Promise;
+    expect(response1.value).toEqual(event);
+    expect(connectionCount).toBe(2);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── Last-Event-ID ───────────────────────────────────────────────────────
+
+  it('sends Last-Event-ID header on reconnect', async () => {
+    const event = {
+      x: 1
+    };
+    const capturedInits = [];
+    // First connection delivers one event with a cursor; second is silent.
+    const streamChunks = [[sseChunk([{
+      id: 'cursor-99',
+      data: JSON.stringify(event)
+    }])], []];
+    let closeStream;
+    vi.stubGlobal('fetch', (_url, init) => {
+      capturedInits.push(init);
+      const {
+        stream,
+        close
+      } = makeStream(streamChunks.shift() ?? [], init.signal);
+      closeStream = close;
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const response1 = await gen.next();
+    expect(response1.value).toEqual(event);
+
+    // Close first stream — reconnect trigger
+    closeStream();
+    const response2Promise = gen.next();
+    await advanceTime(3000);
+    expect(capturedInits.length).toBeGreaterThanOrEqual(2);
+    const secondHeaders = capturedInits[1]?.headers;
+    expect(secondHeaders?.['Last-Event-ID']).toBe('cursor-99');
+    abortController.abort();
+    await response2Promise;
+  });
+  it('does not send Last-Event-ID on first connect', async () => {
+    const capturedInits = [];
+    vi.stubGlobal('fetch', (_url, init) => {
+      capturedInits.push(init);
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const pending = api.subscribe('/test', {
+      signal: abortController.signal
+    }).next();
+    await flushMicrotasks();
+    const firstHeaders = capturedInits[0]?.headers;
+    expect(firstHeaders?.['Last-Event-ID']).toBeUndefined();
+    abortController.abort();
+    await pending;
+  });
+
+  // ─── heartbeat watchdog ───────────────────────────────────────────────────
+
+  it('fires watchdog after 45s of silence and triggers reconnect', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const nextPromise = gen.next();
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+
+    // Fire the 45s watchdog then let the backoff sleep through
+    await advanceTime(45_001);
+    await advanceTime(3_000);
+    expect(connectionCount).toBeGreaterThanOrEqual(2);
+    abortController.abort();
+    await nextPromise;
+  });
+  it('heartbeats reset the watchdog so it does not fire during activity', async () => {
+    const realEvent = {
+      data: 'live'
+    };
+    let connectionCount = 0;
+    let pushChunk;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      const {
+        stream,
+        push
+      } = makeStream([], init.signal);
+      pushChunk = push;
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const responsePromise = gen.next();
+    await flushMicrotasks();
+
+    // Advance to just under the 45s watchdog — it has not fired yet
+    await advanceTime(44_000);
+    expect(connectionCount).toBe(1);
+
+    // Heartbeat arrives and resets the watchdog to another 45s from now
+    pushChunk(sseChunk([{
+      event: 'heartbeat',
+      data: '{}'
+    }]));
+    await flushMicrotasks();
+
+    // Advance another 44s — total 88s elapsed but watchdog was reset at 44s,
+    // so it still hasn't fired
+    await advanceTime(44_000);
+    expect(connectionCount).toBe(1);
+
+    // Real event arrives — generator yields it
+    pushChunk(sseChunk([{
+      data: JSON.stringify(realEvent)
+    }]));
+    const response = await responsePromise;
+    expect(response.value).toEqual(realEvent);
+    expect(connectionCount).toBe(1);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── heartbeat filtering ──────────────────────────────────────────────────
+
+  it('never yields heartbeat events to the consumer', async () => {
+    const realEvent = {
+      type: 'real'
+    };
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        event: 'heartbeat',
+        data: '{}'
+      }, {
+        data: JSON.stringify(realEvent)
+      }, {
+        event: 'heartbeat',
+        data: '{}'
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const response = await gen.next();
+    expect(response.value).toEqual(realEvent);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── reset handling ───────────────────────────────────────────────────────
+
+  it('calls onReset for server reset event and does not yield it', async () => {
+    const realEvent = {
+      type: 'real'
+    };
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        event: 'reset',
+        data: '{}'
+      }, {
+        data: JSON.stringify(realEvent)
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const onReset = vi.fn();
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      onReset,
+      signal: abortController.signal
+    });
+    const response = await gen.next();
+    expect(response.value).toEqual(realEvent);
+    expect(onReset).toHaveBeenCalledTimes(1);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+  it('calls onReset when reconnecting without a stored cursor', async () => {
+    // No id fields → cursor never stored → onReset fires on reconnect
+    const events = ['{"n":1}', '{"n":2}'];
+    let closeStream;
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream,
+        close
+      } = makeStream([sseChunk([{
+        data: events.shift() ?? ''
+      }])], init.signal);
+      closeStream = close;
+      return Promise.resolve(okResponse(stream));
+    });
+    const onReset = vi.fn();
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      onReset,
+      signal: abortController.signal
+    });
+    const response1 = await gen.next();
+    expect(response1.value).toEqual({
+      n: 1
+    });
+    expect(onReset).not.toHaveBeenCalled(); // no onReset on first connect
+
+    // Closing the first stream (no cursor stored) triggers onReset on reconnect
+    closeStream();
+    const response2Promise = gen.next();
+    await advanceTime(3000);
+    const response2 = await response2Promise;
+    expect(response2.value).toEqual({
+      n: 2
+    });
+    expect(onReset).toHaveBeenCalledTimes(1);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+  it('does not call onReset on the first connect', async () => {
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        data: '{"n":1}'
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const onReset = vi.fn();
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      onReset,
+      signal: abortController.signal
+    });
+    await gen.next();
+    expect(onReset).not.toHaveBeenCalled();
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── clean termination ────────────────────────────────────────────────────
+
+  it('does not reconnect after consumer break', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        data: '{"n":1}'
+      }, {
+        data: '{"n":2}'
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const api = makeAPI();
+    const gen = api.subscribe('/test');
+    const response1 = await gen.next();
+    expect(response1.value.n).toBe(1);
+
+    // Consumer breaks — generator terminates cleanly; no server close needed
+    await gen.return(undefined);
+    await vi.advanceTimersByTimeAsync(60_000);
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+  });
+  it('does not reconnect when external AbortSignal is fired', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const pending = api.subscribe('/test', {
+      signal: abortController.signal
+    }).next();
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+    abortController.abort();
+    await pending; // resolves as {done: true}
+
+    await vi.advanceTimersByTimeAsync(60_000);
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+  });
+  it('does not reconnect after a 401 response', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', () => {
+      connectionCount++;
+      return Promise.resolve(unauthorizedResponse());
+    });
+    const api = makeAPI();
+    const gen = api.subscribe('/test');
+    const response = await gen.next();
+    expect(response.done).toBe(true);
+    await vi.advanceTimersByTimeAsync(60_000);
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+  });
+
+  // ─── backoff behaviour ────────────────────────────────────────────────────
+
+  it('backoff grows across successive reconnects', async () => {
+    // Pin jitter to maximum (Math.random() = 1 → multiplier = 1.5) so timing is deterministic:
+    //   1st sleep  = 1_000 ms (initial backoffMs, jitter applied after)
+    //   2nd sleep  = Math.min(1_000 × 2, 30_000) × 1.5 = 3_000 ms
+    vi.spyOn(Math, 'random').mockReturnValue(1);
+    let connectionCount = 0;
+    let closeStream;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      const {
+        stream,
+        close
+      } = makeStream([], init.signal);
+      closeStream = close;
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    gen.next();
+    await flushMicrotasks();
+
+    // 1st disconnect → 1_000 ms backoff
+    closeStream();
+    await advanceTime(999);
+    expect(connectionCount).toBe(1); // not yet
+
+    await advanceTime(2); // crosses 1_000 ms
+    expect(connectionCount).toBe(2);
+
+    // 2nd disconnect → 3_000 ms backoff (grew)
+    closeStream();
+    await advanceTime(2_999);
+    expect(connectionCount).toBe(2); // not yet
+
+    await advanceTime(2); // crosses 3_000 ms
+    expect(connectionCount).toBe(3);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+  it('resets backoff after a connection that lived longer than the threshold', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    gen.next();
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+
+    // Watchdog fires at 45 s (connection lived > 10 s threshold → backoff resets)
+    await advanceTime(45_001);
+
+    // Backoff should have been reset to ~1 s; advance 2 s to cover jitter
+    await advanceTime(2_000);
+
+    // Second fetch triggered
+    expect(connectionCount).toBeGreaterThanOrEqual(2);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── connection state callbacks ───────────────────────────────────────────
+
+  it('emits connected then reconnecting on connection loss', async () => {
+    // First connection delivers one event; second is silent (only the state
+    // sequence matters here, not a second event).
+    const streamChunks = [[sseChunk([{
+      data: '{"n":1}'
+    }])], []];
+    let closeStream;
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream,
+        close
+      } = makeStream(streamChunks.shift() ?? [], init.signal);
+      closeStream = close;
+      return Promise.resolve(okResponse(stream));
+    });
+    const states = [];
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal,
+      onConnectionChange: s => states.push(s)
+    });
+    const response1 = await gen.next();
+    expect(response1.value).toEqual({
+      n: 1
+    });
+
+    // Closing the first stream triggers 'reconnecting', then 'connected' on the second
+    closeStream();
+    const response2Promise = gen.next();
+    await advanceTime(3000);
+    expect(states).toContain('connected');
+    expect(states).toContain('reconnecting');
+    expect(states.indexOf('connected')).toBeLessThan(states.indexOf('reconnecting'));
+    abortController.abort();
+    await response2Promise;
+  });
+
+  // ─── initialLastEventId ───────────────────────────────────────────────────
+
+  it('sends initialLastEventId as Last-Event-ID on the very first connect', async () => {
+    const capturedInits = [];
+    vi.stubGlobal('fetch', (_url, init) => {
+      capturedInits.push(init);
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const pending = api.subscribe('/test', {
+      signal: abortController.signal,
+      initialLastEventId: 'seed-cursor'
+    }).next();
+    await flushMicrotasks();
+    const firstHeaders = capturedInits[0]?.headers;
+    expect(firstHeaders?.['Last-Event-ID']).toBe('seed-cursor');
+    abortController.abort();
+    await pending;
+  });
+});
+function makeFullAPI() {
+  return new API({
+    credentials: {
+      accessToken: 'token',
+      url: 'https://api.example.com'
+    },
+    requesterId: 'req-1',
+    deviceName: 'test',
+    onLogout: vi.fn()
+  });
+}
+describe('getAttendeeList', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  it('returns eventCursor: null when X-Event-Cursor header is absent', async () => {
+    vi.stubGlobal('fetch', () => Promise.resolve(new Response(JSON.stringify([{
+      id: 'att-1'
+    }]), {
+      status: 200
+    })));
+    const api = makeFullAPI();
+    const result = await api.getAttendeeList({
+      instanceName: 'test-instance'
+    });
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.eventCursor).toBeNull();
+    expect(result.data.attendees).toHaveLength(1);
+    expect(result.data.attendees[0].id).toBe('att-1');
+  });
+  it('returns eventCursor from X-Event-Cursor response header', async () => {
+    vi.stubGlobal('fetch', () => Promise.resolve(new Response(JSON.stringify([{
+      id: 'att-1'
+    }]), {
+      status: 200,
+      headers: {
+        'X-Event-Cursor': 'abc123'
+      }
+    })));
+    const api = makeFullAPI();
+    const result = await api.getAttendeeList({
+      instanceName: 'test-instance'
+    });
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.eventCursor).toBe('abc123');
+  });
+});

package/dist/api-client/index.d.ts

@@ -1,4 +1,4 @@
-import APIBase, { FetchOptions, RequestBody } from './api-base';
+import APIBase, { FetchOptions, RequestBody, SubscribeOptions } from './api-base';
 import { APIResult } from '../lib';
 import { Attendee } from '../models/attendee';
 import { Event, EventInput } from '../models';
@@ -9,7 +9,7 @@ import { User } from '../models/user';
 import { Variable } from '../models/variable';
 import { components } from '../generated/api-schema';
 import { Email } from '../models/email';
-export type { APICredentials } from './api-base';
+export type { APICredentials, SubscribeOptions } from './api-base';
 /**
  * api client for the enter backend
  */
@@ -73,7 +73,10 @@ declare class API extends APIBase {
         instanceName: string;
         filter?: string;
         includeDeleted?: boolean;
-    }, options?: FetchOptions): Promise<APIResult<Attendee[]>>;
+    }, options?: FetchOptions): Promise<APIResult<{
+        attendees: Attendee[];
+        eventCursor: string | null;
+    }>>;
     /**
      * @category Attendees
      */
@@ -175,6 +178,6 @@ declare class API extends APIBase {
     subscribeToEvents(args: {
         instanceName: string;
         eventType?: string[];
-    }, options?: FetchOptions): AsyncGenerator<Event>;
+    }, options?: SubscribeOptions): AsyncGenerator<Event>;
 }
 export default API;

package/dist/api-client/index.js

@@ -86,11 +86,20 @@ class API extends APIBase {
     if (args.includeDeleted) {
       query.append('include_deleted', 'true');
     }
-    const instanceName = args.instanceName;
-    const queryString = `?${query.toString()}`;
-    const result = await this.get(`/instances/${instanceName}/attendees${queryString}`, options);
+    const qs = query.toString();
+    const endpoint = `/instances/${args.instanceName}/attendees${qs ? `?${qs}` : ''}`;
+    const result = await this.fetchResponse(endpoint, {
+      method: 'GET',
+      headers: this.buildHeaders(),
+      ...options
+    });
     if (!result.success) return result;
-    return success(result.data.map(attendeeJSON => new Attendee(attendeeJSON)));
+    const data = await result.data.json();
+    const eventCursor = result.data.headers.get('X-Event-Cursor');
+    return success({
+      attendees: data.map(attendeeJSON => new Attendee(attendeeJSON)),
+      eventCursor: eventCursor ?? null
+    });
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-crew-berlin/enter-js-utils",
-  "version": "0.97.5",
+  "version": "0.98.9",
   "description": "utils such as vaildation and other helpers to work with data from the enter app",
   "files": [
     "dist",
@@ -19,7 +19,7 @@
     "prepare": "husky install && npm run build",
     "build": "rm -r dist & babel src --extensions '.ts','.tsx' -d dist && tsc -d",
     "lint": "eslint src/ --ext .ts",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest run",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "generate-client": "openapi-typescript https://api.dev.enter.events/openapi.json --output src/generated/api-schema.ts --empty-objects-unknown --export-type",
@@ -55,22 +55,22 @@
     "@storybook/test": "^8.5.8",
     "@types/cookie": "^0.6.0",
     "@types/jws": "^3.2.9",
-    "@types/node": "^17.0.38",
+    "@types/node": "^22.19.21",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
-    "@types/uuid": "^8.3.4",
     "@typescript-eslint/eslint-plugin": "^5.27.0",
     "@typescript-eslint/parser": "^5.27.0",
     "eslint": "^8.16.0",
     "eslint-config-prettier": "^8.5.0",
     "husky": "^7.0.1",
-    "openapi-typescript": "^6.7.6",
+    "openapi-typescript": "^7.13.0",
     "prettier": "^2.6.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typedoc": "^0.27.8",
     "typedoc-plugin-rename-defaults": "^0.7.2",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.8"
   },
   "peerDependencies": {
     "react": "^19.0.0",
@@ -82,6 +82,6 @@
     "jws": "^4.0.0",
     "stable-hash": "^0.0.5",
     "styled-jsx": "^5.1.6",
-    "uuid": "^9.0.0"
+    "uuid": "^14.0.0"
   }
 }

package/dist/ui/button.stories.d.ts

@@ -1,16 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import { Button } from './button';
-declare const meta: Meta<typeof Button>;
-export default meta;
-type Story = StoryObj<typeof Button>;
-export declare const Basic: Story;
-export declare const FullWidth: Story;
-export declare const Primary: Story;
-export declare const Danger: Story;
-export declare const Green: Story;
-export declare const Borderless: Story;
-export declare const BorderlessPrimary: Story;
-export declare const BorderlessDanger: Story;
-export declare const BorderlessGreen: Story;
-export declare const Disabled: Story;
-export declare const OnePrimaryAndTwoBorderless: Story;

package/dist/ui/checkin-count-indicator.stories.d.ts

@@ -1,14 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { CheckinCountIndicator } from './checkin-count-indicator';
-declare const meta: Meta<typeof CheckinCountIndicator>;
-export default meta;
-type Story = StoryObj<typeof CheckinCountIndicator>;
-export declare const SingleResponse: Story;
-export declare const Decline: Story;
-export declare const NoResponse: Story;
-export declare const MultipleResponses: Story;
-export declare const CheckinAndResponse: Story;
-export declare const MultipleCheckinsAndResponse: Story;
-export declare const CheckinsWithDecline: Story;
-export declare const CheckinWithoutResponse: Story;
-export declare const MultipleCheckins: Story;

package/dist/ui/checkin-progress-bar.stories.d.ts

@@ -1,12 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { CheckinProgressBar } from './checkin-progress-bar';
-declare const meta: Meta<typeof CheckinProgressBar>;
-export default meta;
-type Story = StoryObj<typeof CheckinProgressBar>;
-export declare const Basic: Story;
-export declare const WithoutTagName: Story;
-export declare const NoCheckins: Story;
-export declare const AllCheckinsComplete: Story;
-export declare const MoreCheckinsThanExpected: Story;
-export declare const NoRSVP: Story;
-export declare const CustomLabels: Story;

package/dist/ui/companion-info.stories.d.ts

@@ -1,7 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { CompanionInfo } from './companion-info';
-declare const meta: Meta<typeof CompanionInfo>;
-export default meta;
-type Story = StoryObj<typeof CompanionInfo>;
-export declare const WithMainGuest: Story;
-export declare const NotACompanion: Story;

package/dist/ui/enter-logo.stories.d.ts

@@ -1,7 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { EnterLogo } from './enter-logo';
-declare const meta: Meta<typeof EnterLogo>;
-export default meta;
-type Story = StoryObj<typeof EnterLogo>;
-export declare const Basic: Story;
-export declare const White: Story;

package/dist/ui/form-elements/input.stories.d.ts

@@ -1,8 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { Input } from './input';
-declare const meta: Meta<typeof Input>;
-export default meta;
-type Story = StoryObj<typeof Input>;
-export declare const Basic: Story;
-export declare const NumberInput: Story;
-export declare const WithValue: Story;

package/dist/ui/form-elements/label.stories.d.ts

@@ -1,6 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { Label } from './label';
-declare const meta: Meta<typeof Label>;
-export default meta;
-type Story = StoryObj<typeof Label>;
-export declare const Basic: Story;

package/dist/ui/form-elements/search-input.stories.d.ts

@@ -1,7 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { SearchInput } from './search-input';
-declare const meta: Meta<typeof SearchInput>;
-export default meta;
-type Story = StoryObj<typeof SearchInput>;
-export declare const Basic: Story;
-export declare const WhiteText: Story;

package/dist/ui/form-elements/segmented-control.stories.d.ts

@@ -1,6 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { SegmentedControl } from './segmented-control';
-declare const meta: Meta<typeof SegmentedControl>;
-export default meta;
-type Story = StoryObj<typeof SegmentedControl>;
-export declare const Basic: Story;

package/dist/ui/form-elements/select.stories.d.ts

@@ -1,8 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { Select } from './select';
-declare const meta: Meta<typeof Select>;
-export default meta;
-type Story = StoryObj<typeof Select>;
-export declare const Basic: Story;
-export declare const WithPleaseSelect: Story;
-export declare const WithCustomFormat: Story;

package/dist/ui/guest-card.stories.d.ts

@@ -1,14 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { GuestCard } from './guest-card';
-declare const meta: Meta<typeof GuestCard>;
-export default meta;
-type Story = StoryObj<typeof GuestCard>;
-export declare const WithBackground: Story;
-export declare const Plain: Story;
-export declare const Dense: Story;
-export declare const FilteredTags: Story;
-export declare const WithColorLabel: Story;
-export declare const WithMultipleColorLabels: Story;
-export declare const WithInfoText: Story;
-export declare const WithCompanion: Story;
-export declare const WithCompanionButNoMainGuestInfo: Story;

package/dist/ui/icons/add-guest-icon.stories.d.ts

@@ -1,7 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { AddGuestIcon } from './add-guest-icon';
-declare const meta: Meta<typeof AddGuestIcon>;
-export default meta;
-type Story = StoryObj<typeof AddGuestIcon>;
-export declare const Basic: Story;
-export declare const White: Story;

package/dist/ui/icons/caret-icon.stories.d.ts

@@ -1,7 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { CaretIcon } from './caret-icon';
-declare const meta: Meta<typeof CaretIcon>;
-export default meta;
-type Story = StoryObj<typeof CaretIcon>;
-export declare const Basic: Story;
-export declare const White: Story;

package/dist/ui/icons/filter-icon.stories.d.ts

@@ -1,7 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { FilterIcon } from './filter-icon';
-declare const meta: Meta<typeof FilterIcon>;
-export default meta;
-type Story = StoryObj<typeof FilterIcon>;
-export declare const Basic: Story;
-export declare const White: Story;

package/dist/ui/icons/search-icon.stories.d.ts

@@ -1,7 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { SearchIcon } from './search-icon';
-declare const meta: Meta<typeof SearchIcon>;
-export default meta;
-type Story = StoryObj<typeof SearchIcon>;
-export declare const Basic: Story;
-export declare const White: Story;

package/dist/ui/icons/settings-icon.stories.d.ts

@@ -1,7 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { SettingsIcon } from './settings-icon';
-declare const meta: Meta<typeof SettingsIcon>;
-export default meta;
-type Story = StoryObj<typeof SettingsIcon>;
-export declare const Basic: Story;
-export declare const White: Story;

package/dist/ui/icons/sort-list-icon.stories.d.ts

@@ -1,7 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { SortListIcon } from './sort-list-icon';
-declare const meta: Meta<typeof SortListIcon>;
-export default meta;
-type Story = StoryObj<typeof SortListIcon>;
-export declare const Basic: Story;
-export declare const White: Story;

package/dist/ui/tag.stories.d.ts

@@ -1,6 +0,0 @@
-import { Meta, StoryObj } from '@storybook/react';
-import { Tag } from './tag';
-declare const meta: Meta<typeof Tag>;
-export default meta;
-type Story = StoryObj<typeof Tag>;
-export declare const Basic: Story;