@oneidentity/safeguard 7.4.0 → 8.0.0-pre36954

package/dist/events.cjs

@@ -0,0 +1,190 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/events/listener.ts
+/**
+* One-shot event listener wrapping a SignalR HubConnection.
+* For persistent auto-reconnect behavior, use PersistentSafeguardEventListener.
+*/
+var SafeguardEventListener = class {
+	#connection;
+	#handlers = [];
+	#state = "stopped";
+	constructor(connection) {
+		this.#connection = connection;
+		this.#connection.onclose(() => {
+			this.#setState("disconnected");
+		});
+		this.#connection.onreconnecting(() => {
+			this.#setState("reconnecting");
+		});
+		this.#connection.onreconnected(() => {
+			this.#setState("connected");
+		});
+		this.#connection.on("NotifyEventAsync", (event) => {
+			for (const handler of this.#handlers) handler(event);
+		});
+	}
+	/** Current connection state. */
+	get state() {
+		return this.#state;
+	}
+	/**
+	* Register an event handler for Safeguard notifications.
+	*/
+	on(_method, handler) {
+		this.#handlers.push(handler);
+		return this;
+	}
+	/**
+	* Start the SignalR connection.
+	*/
+	async start() {
+		this.#setState("starting");
+		await this.#connection.start();
+		this.#setState("connected");
+	}
+	/**
+	* Stop the SignalR connection.
+	*/
+	async stop() {
+		await this.#connection.stop();
+		this.#setState("stopped");
+	}
+	#setState(state) {
+		this.#state = state;
+	}
+};
+//#endregion
+//#region src/events/persistent.ts
+const DEFAULT_RETRY_INTERVAL_MS = 5e3;
+const TOKEN_REFRESH_MARGIN_MS = 6e4;
+/**
+* Persistent event listener with automatic reconnection and token refresh.
+*
+* Wraps SignalR's built-in `withAutomaticReconnect()` AND adds:
+* - Token refresh on reconnect (re-authenticates if needed)
+* - State change event notifications
+* - Manual `stop()` that prevents further auto-reconnect
+*/
+var PersistentSafeguardEventListener = class {
+	#connection;
+	#auth;
+	#host;
+	#httpClient;
+	#storage;
+	#retryIntervalMs;
+	#maxRetries;
+	#handlers = [];
+	#stateChangeHandlers = [];
+	#state = "stopped";
+	#tokenSet;
+	#manualStop = false;
+	#retryCount = 0;
+	#retryTimer;
+	constructor(connection, auth, host, httpClient, storage, options, tokenSet) {
+		this.#connection = connection;
+		this.#auth = auth;
+		this.#host = host;
+		this.#httpClient = httpClient;
+		this.#storage = storage;
+		this.#retryIntervalMs = options?.retryIntervalMs ?? DEFAULT_RETRY_INTERVAL_MS;
+		this.#maxRetries = options?.maxRetries;
+		this.#tokenSet = tokenSet;
+		this.#connection.onclose(() => {
+			this.#setState("disconnected");
+			if (!this.#manualStop) this.#scheduleReconnect();
+		});
+		this.#connection.onreconnecting(() => {
+			this.#setState("reconnecting");
+		});
+		this.#connection.onreconnected(() => {
+			this.#retryCount = 0;
+			this.#setState("connected");
+		});
+		this.#connection.on("NotifyEventAsync", (event) => {
+			for (const handler of this.#handlers) handler(event);
+		});
+	}
+	/** Current connection state. */
+	get state() {
+		return this.#state;
+	}
+	/**
+	* Register an event handler for Safeguard notifications.
+	*/
+	on(_method, handler) {
+		this.#handlers.push(handler);
+		return this;
+	}
+	/**
+	* Register a state change handler.
+	*/
+	onStateChange(handler) {
+		this.#stateChangeHandlers.push(handler);
+		return this;
+	}
+	/**
+	* Start the persistent connection.
+	*/
+	async start() {
+		this.#manualStop = false;
+		this.#retryCount = 0;
+		this.#setState("starting");
+		await this.#connection.start();
+		this.#setState("connected");
+	}
+	/**
+	* Stop the connection. Prevents auto-reconnect.
+	*/
+	async stop() {
+		this.#manualStop = true;
+		if (this.#retryTimer != null) {
+			clearTimeout(this.#retryTimer);
+			this.#retryTimer = void 0;
+		}
+		await this.#connection.stop();
+		this.#setState("stopped");
+	}
+	#setState(state) {
+		this.#state = state;
+		for (const handler of this.#stateChangeHandlers) handler(state);
+	}
+	async #scheduleReconnect() {
+		if (this.#manualStop) return;
+		if (this.#maxRetries != null && this.#retryCount >= this.#maxRetries) {
+			this.#setState("stopped");
+			return;
+		}
+		this.#setState("reconnecting");
+		this.#retryTimer = setTimeout(() => {
+			this.#reconnect();
+		}, this.#retryIntervalMs);
+	}
+	async #reconnect() {
+		if (this.#manualStop) return;
+		this.#retryCount++;
+		try {
+			if (this.#isTokenExpired()) if (this.#auth.refreshToken) {
+				const refreshed = await this.#auth.refreshToken(this.#host, this.#httpClient, this.#storage);
+				if (refreshed) this.#tokenSet = refreshed;
+				else this.#tokenSet = await this.#auth.authenticate(this.#host, this.#httpClient, this.#storage);
+			} else this.#tokenSet = await this.#auth.authenticate(this.#host, this.#httpClient, this.#storage);
+			await this.#connection.start();
+			this.#retryCount = 0;
+			this.#setState("connected");
+		} catch {
+			this.#scheduleReconnect();
+		}
+	}
+	#isTokenExpired() {
+		if (!this.#tokenSet) return true;
+		if (!this.#tokenSet.expiresIn) return true;
+		const elapsed = Date.now() - this.#tokenSet.acquiredAt;
+		const expiresInMs = this.#tokenSet.expiresIn * 1e3;
+		return elapsed + TOKEN_REFRESH_MARGIN_MS >= expiresInMs;
+	}
+};
+//#endregion
+exports.PersistentSafeguardEventListener = PersistentSafeguardEventListener;
+exports.SafeguardEventListener = SafeguardEventListener;
+
+//# sourceMappingURL=events.cjs.map

package/dist/events.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.cjs","names":["#connection","#handlers","#setState","#state","#connection","#auth","#host","#httpClient","#storage","#retryIntervalMs","#maxRetries","#handlers","#stateChangeHandlers","#tokenSet","#setState","#manualStop","#scheduleReconnect","#retryCount","#state","#retryTimer","#reconnect","#isTokenExpired"],"sources":["../src/events/listener.ts","../src/events/persistent.ts"],"sourcesContent":["import type { HubConnection } from '@microsoft/signalr';\nimport type { EventHandler, EventListenerState, SafeguardEvent } from './types.js';\n\n/**\n * One-shot event listener wrapping a SignalR HubConnection.\n * For persistent auto-reconnect behavior, use PersistentSafeguardEventListener.\n */\nexport class SafeguardEventListener {\n  readonly #connection: HubConnection;\n  readonly #handlers: EventHandler[] = [];\n  #state: EventListenerState = 'stopped';\n\n  constructor(connection: HubConnection) {\n    this.#connection = connection;\n\n    this.#connection.onclose(() => {\n      this.#setState('disconnected');\n    });\n\n    this.#connection.onreconnecting(() => {\n      this.#setState('reconnecting');\n    });\n\n    this.#connection.onreconnected(() => {\n      this.#setState('connected');\n    });\n\n    // Register for the Safeguard event method\n    this.#connection.on('NotifyEventAsync', (event: SafeguardEvent) => {\n      for (const handler of this.#handlers) {\n        handler(event);\n      }\n    });\n  }\n\n  /** Current connection state. */\n  get state(): EventListenerState {\n    return this.#state;\n  }\n\n  /**\n   * Register an event handler for Safeguard notifications.\n   */\n  on(_method: 'NotifyEventAsync', handler: EventHandler): this {\n    this.#handlers.push(handler);\n    return this;\n  }\n\n  /**\n   * Start the SignalR connection.\n   */\n  async start(): Promise<void> {\n    this.#setState('starting');\n    await this.#connection.start();\n    this.#setState('connected');\n  }\n\n  /**\n   * Stop the SignalR connection.\n   */\n  async stop(): Promise<void> {\n    await this.#connection.stop();\n    this.#setState('stopped');\n  }\n\n  #setState(state: EventListenerState): void {\n    this.#state = state;\n  }\n}\n","import type { HubConnection } from '@microsoft/signalr';\nimport type { Auth, TokenSet } from '../auth/types.js';\nimport type { HttpClient } from '../http/types.js';\nimport type { StorageProvider } from '../storage/types.js';\nimport type {\n  EventHandler,\n  EventListenerState,\n  PersistentListenerOptions,\n  SafeguardEvent,\n  StateChangeHandler,\n} from './types.js';\n\nconst DEFAULT_RETRY_INTERVAL_MS = 5_000;\nconst TOKEN_REFRESH_MARGIN_MS = 60_000; // refresh 60s before expiry\n\n/**\n * Persistent event listener with automatic reconnection and token refresh.\n *\n * Wraps SignalR's built-in `withAutomaticReconnect()` AND adds:\n * - Token refresh on reconnect (re-authenticates if needed)\n * - State change event notifications\n * - Manual `stop()` that prevents further auto-reconnect\n */\nexport class PersistentSafeguardEventListener {\n  readonly #connection: HubConnection;\n  readonly #auth: Auth;\n  readonly #host: string;\n  readonly #httpClient: HttpClient;\n  readonly #storage: StorageProvider;\n  readonly #retryIntervalMs: number;\n  readonly #maxRetries: number | undefined;\n  readonly #handlers: EventHandler[] = [];\n  readonly #stateChangeHandlers: StateChangeHandler[] = [];\n\n  #state: EventListenerState = 'stopped';\n  #tokenSet: TokenSet | undefined;\n  #manualStop = false;\n  #retryCount = 0;\n  #retryTimer: ReturnType<typeof setTimeout> | undefined;\n\n  constructor(\n    connection: HubConnection,\n    auth: Auth,\n    host: string,\n    httpClient: HttpClient,\n    storage: StorageProvider,\n    options?: PersistentListenerOptions,\n    tokenSet?: TokenSet,\n  ) {\n    this.#connection = connection;\n    this.#auth = auth;\n    this.#host = host;\n    this.#httpClient = httpClient;\n    this.#storage = storage;\n    this.#retryIntervalMs = options?.retryIntervalMs ?? DEFAULT_RETRY_INTERVAL_MS;\n    this.#maxRetries = options?.maxRetries;\n    this.#tokenSet = tokenSet;\n\n    this.#connection.onclose(() => {\n      this.#setState('disconnected');\n      if (!this.#manualStop) {\n        void this.#scheduleReconnect();\n      }\n    });\n\n    this.#connection.onreconnecting(() => {\n      this.#setState('reconnecting');\n    });\n\n    this.#connection.onreconnected(() => {\n      this.#retryCount = 0;\n      this.#setState('connected');\n    });\n\n    this.#connection.on('NotifyEventAsync', (event: SafeguardEvent) => {\n      for (const handler of this.#handlers) {\n        handler(event);\n      }\n    });\n  }\n\n  /** Current connection state. */\n  get state(): EventListenerState {\n    return this.#state;\n  }\n\n  /**\n   * Register an event handler for Safeguard notifications.\n   */\n  on(_method: 'NotifyEventAsync', handler: EventHandler): this {\n    this.#handlers.push(handler);\n    return this;\n  }\n\n  /**\n   * Register a state change handler.\n   */\n  onStateChange(handler: StateChangeHandler): this {\n    this.#stateChangeHandlers.push(handler);\n    return this;\n  }\n\n  /**\n   * Start the persistent connection.\n   */\n  async start(): Promise<void> {\n    this.#manualStop = false;\n    this.#retryCount = 0;\n    this.#setState('starting');\n    await this.#connection.start();\n    this.#setState('connected');\n  }\n\n  /**\n   * Stop the connection. Prevents auto-reconnect.\n   */\n  async stop(): Promise<void> {\n    this.#manualStop = true;\n    if (this.#retryTimer != null) {\n      clearTimeout(this.#retryTimer);\n      this.#retryTimer = undefined;\n    }\n    await this.#connection.stop();\n    this.#setState('stopped');\n  }\n\n  // ─── Private ────────────────────────────────────────────────────────\n\n  #setState(state: EventListenerState): void {\n    this.#state = state;\n    for (const handler of this.#stateChangeHandlers) {\n      handler(state);\n    }\n  }\n\n  async #scheduleReconnect(): Promise<void> {\n    if (this.#manualStop) return;\n    if (this.#maxRetries != null && this.#retryCount >= this.#maxRetries) {\n      this.#setState('stopped');\n      return;\n    }\n\n    this.#setState('reconnecting');\n    this.#retryTimer = setTimeout(() => {\n      void this.#reconnect();\n    }, this.#retryIntervalMs);\n  }\n\n  async #reconnect(): Promise<void> {\n    if (this.#manualStop) return;\n    this.#retryCount++;\n\n    try {\n      // Only refresh the token if it's expired or near-expiry\n      if (this.#isTokenExpired()) {\n        if (this.#auth.refreshToken) {\n          const refreshed = await this.#auth.refreshToken(this.#host, this.#httpClient, this.#storage);\n          if (refreshed) {\n            this.#tokenSet = refreshed;\n          } else {\n            // Refresh failed — full re-auth\n            this.#tokenSet = await this.#auth.authenticate(this.#host, this.#httpClient, this.#storage);\n          }\n        } else {\n          this.#tokenSet = await this.#auth.authenticate(this.#host, this.#httpClient, this.#storage);\n        }\n      }\n\n      await this.#connection.start();\n      this.#retryCount = 0;\n      this.#setState('connected');\n    } catch {\n      // Reconnect failed — try again\n      void this.#scheduleReconnect();\n    }\n  }\n\n  #isTokenExpired(): boolean {\n    if (!this.#tokenSet) return true; // no token at all — must authenticate\n    if (!this.#tokenSet.expiresIn) return true; // can't determine lifetime — refresh to be safe\n\n    const elapsed = Date.now() - this.#tokenSet.acquiredAt;\n    const expiresInMs = this.#tokenSet.expiresIn * 1000;\n    return elapsed + TOKEN_REFRESH_MARGIN_MS >= expiresInMs;\n  }\n}\n"],"mappings":"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"}

package/dist/events.d.cts

@@ -0,0 +1,166 @@
+import { HubConnection } from "@microsoft/signalr";
+import { SecretValue } from './index.d.cts';
+
+//#region src/events/types.d.ts
+/**
+ * Event listener connection states.
+ */
+type EventListenerState = 'starting' | 'connected' | 'disconnected' | 'reconnecting' | 'stopped';
+/**
+ * Handler for Safeguard events (NotifyEventAsync messages from SignalR).
+ */
+type EventHandler = (event: SafeguardEvent) => void;
+/**
+ * Handler for state change notifications.
+ */
+type StateChangeHandler = (state: EventListenerState) => void;
+/**
+ * A Safeguard event as delivered by SignalR.
+ */
+interface SafeguardEvent {
+  EventName: string;
+  [key: string]: unknown;
+}
+/**
+ * Options for persistent event listeners.
+ */
+interface PersistentListenerOptions {
+  /** Delay between reconnection attempts in milliseconds. Default: 5000. */
+  retryIntervalMs?: number;
+  /** Maximum number of reconnect attempts before giving up. Default: unlimited. */
+  maxRetries?: number;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/events/listener.d.ts
+/**
+ * One-shot event listener wrapping a SignalR HubConnection.
+ * For persistent auto-reconnect behavior, use PersistentSafeguardEventListener.
+ */
+declare class SafeguardEventListener {
+  #private;
+  constructor(connection: HubConnection);
+  /** Current connection state. */
+  get state(): EventListenerState;
+  /**
+   * Register an event handler for Safeguard notifications.
+   */
+  on(_method: 'NotifyEventAsync', handler: EventHandler): this;
+  /**
+   * Start the SignalR connection.
+   */
+  start(): Promise<void>;
+  /**
+   * Stop the SignalR connection.
+   */
+  stop(): Promise<void>;
+}
+//# sourceMappingURL=listener.d.ts.map
+//#endregion
+//#region src/http/types.d.ts
+/**
+ * Platform-agnostic HTTP client interface for the Safeguard SDK.
+ */
+interface HttpRequestOptions {
+  url: string;
+  method: string;
+  headers?: Record<string, string>;
+  body?: string | Buffer | null;
+  signal?: AbortSignal;
+  timeout?: number;
+}
+interface HttpResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+}
+/**
+ * Abstract HTTP client interface.
+ * Implementations: NodeHttpClient (undici), BrowserHttpClient (fetch).
+ */
+interface HttpClient {
+  request(options: HttpRequestOptions): Promise<HttpResponse>;
+  dispose?(): void;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/storage/types.d.ts
+/**
+ * Interface for token/state storage backends.
+ */
+interface StorageProvider {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  remove(key: string): void;
+  clear(): void;
+}
+/** Well-known storage keys used by the SDK. */
+//#endregion
+//#region src/auth/types.d.ts
+/**
+ * Token set returned by authentication.
+ */
+interface TokenSet {
+  /** The Safeguard user access token (wrapped to prevent accidental logging). */
+  accessToken: SecretValue;
+  /** Token lifetime in seconds from when it was issued. */
+  expiresIn?: number;
+  /** Timestamp (ms since epoch) when the token was acquired. */
+  acquiredAt: number;
+}
+/**
+ * Auth strategy interface. All authentication methods implement this.
+ */
+interface Auth {
+  /**
+   * Authenticate against the Safeguard RSTS and return a token set.
+   * @param host - Appliance hostname
+   * @param httpClient - HTTP client to use for requests
+   * @param storage - Storage provider for persisting tokens/state
+   */
+  authenticate(host: string, httpClient: HttpClient, storage: StorageProvider): Promise<TokenSet>;
+  /**
+   * Refresh the token if possible. Returns new token set or null if refresh not supported.
+   */
+  refreshToken?(host: string, httpClient: HttpClient, storage: StorageProvider): Promise<TokenSet | null>;
+  /** Human-readable description of this auth strategy (for logging). */
+  readonly description: string;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/events/persistent.d.ts
+/**
+ * Persistent event listener with automatic reconnection and token refresh.
+ *
+ * Wraps SignalR's built-in `withAutomaticReconnect()` AND adds:
+ * - Token refresh on reconnect (re-authenticates if needed)
+ * - State change event notifications
+ * - Manual `stop()` that prevents further auto-reconnect
+ */
+declare class PersistentSafeguardEventListener {
+  #private;
+  constructor(connection: HubConnection, auth: Auth, host: string, httpClient: HttpClient, storage: StorageProvider, options?: PersistentListenerOptions, tokenSet?: TokenSet);
+  /** Current connection state. */
+  get state(): EventListenerState;
+  /**
+   * Register an event handler for Safeguard notifications.
+   */
+  on(_method: 'NotifyEventAsync', handler: EventHandler): this;
+  /**
+   * Register a state change handler.
+   */
+  onStateChange(handler: StateChangeHandler): this;
+  /**
+   * Start the persistent connection.
+   */
+  start(): Promise<void>;
+  /**
+   * Stop the connection. Prevents auto-reconnect.
+   */
+  stop(): Promise<void>;
+}
+//# sourceMappingURL=persistent.d.ts.map
+
+//#endregion
+export { type EventHandler, type EventListenerState, type PersistentListenerOptions, PersistentSafeguardEventListener, type SafeguardEvent, SafeguardEventListener, type StateChangeHandler };
+//# sourceMappingURL=events-zHsrmRBj.d.cts.map

package/dist/events.d.ts

@@ -0,0 +1,166 @@
+import { HubConnection } from "@microsoft/signalr";
+import { SecretValue } from './index.js';
+
+//#region src/events/types.d.ts
+/**
+ * Event listener connection states.
+ */
+type EventListenerState = 'starting' | 'connected' | 'disconnected' | 'reconnecting' | 'stopped';
+/**
+ * Handler for Safeguard events (NotifyEventAsync messages from SignalR).
+ */
+type EventHandler = (event: SafeguardEvent) => void;
+/**
+ * Handler for state change notifications.
+ */
+type StateChangeHandler = (state: EventListenerState) => void;
+/**
+ * A Safeguard event as delivered by SignalR.
+ */
+interface SafeguardEvent {
+  EventName: string;
+  [key: string]: unknown;
+}
+/**
+ * Options for persistent event listeners.
+ */
+interface PersistentListenerOptions {
+  /** Delay between reconnection attempts in milliseconds. Default: 5000. */
+  retryIntervalMs?: number;
+  /** Maximum number of reconnect attempts before giving up. Default: unlimited. */
+  maxRetries?: number;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/events/listener.d.ts
+/**
+ * One-shot event listener wrapping a SignalR HubConnection.
+ * For persistent auto-reconnect behavior, use PersistentSafeguardEventListener.
+ */
+declare class SafeguardEventListener {
+  #private;
+  constructor(connection: HubConnection);
+  /** Current connection state. */
+  get state(): EventListenerState;
+  /**
+   * Register an event handler for Safeguard notifications.
+   */
+  on(_method: 'NotifyEventAsync', handler: EventHandler): this;
+  /**
+   * Start the SignalR connection.
+   */
+  start(): Promise<void>;
+  /**
+   * Stop the SignalR connection.
+   */
+  stop(): Promise<void>;
+}
+//# sourceMappingURL=listener.d.ts.map
+//#endregion
+//#region src/http/types.d.ts
+/**
+ * Platform-agnostic HTTP client interface for the Safeguard SDK.
+ */
+interface HttpRequestOptions {
+  url: string;
+  method: string;
+  headers?: Record<string, string>;
+  body?: string | Buffer | null;
+  signal?: AbortSignal;
+  timeout?: number;
+}
+interface HttpResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+}
+/**
+ * Abstract HTTP client interface.
+ * Implementations: NodeHttpClient (undici), BrowserHttpClient (fetch).
+ */
+interface HttpClient {
+  request(options: HttpRequestOptions): Promise<HttpResponse>;
+  dispose?(): void;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/storage/types.d.ts
+/**
+ * Interface for token/state storage backends.
+ */
+interface StorageProvider {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  remove(key: string): void;
+  clear(): void;
+}
+/** Well-known storage keys used by the SDK. */
+//#endregion
+//#region src/auth/types.d.ts
+/**
+ * Token set returned by authentication.
+ */
+interface TokenSet {
+  /** The Safeguard user access token (wrapped to prevent accidental logging). */
+  accessToken: SecretValue;
+  /** Token lifetime in seconds from when it was issued. */
+  expiresIn?: number;
+  /** Timestamp (ms since epoch) when the token was acquired. */
+  acquiredAt: number;
+}
+/**
+ * Auth strategy interface. All authentication methods implement this.
+ */
+interface Auth {
+  /**
+   * Authenticate against the Safeguard RSTS and return a token set.
+   * @param host - Appliance hostname
+   * @param httpClient - HTTP client to use for requests
+   * @param storage - Storage provider for persisting tokens/state
+   */
+  authenticate(host: string, httpClient: HttpClient, storage: StorageProvider): Promise<TokenSet>;
+  /**
+   * Refresh the token if possible. Returns new token set or null if refresh not supported.
+   */
+  refreshToken?(host: string, httpClient: HttpClient, storage: StorageProvider): Promise<TokenSet | null>;
+  /** Human-readable description of this auth strategy (for logging). */
+  readonly description: string;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/events/persistent.d.ts
+/**
+ * Persistent event listener with automatic reconnection and token refresh.
+ *
+ * Wraps SignalR's built-in `withAutomaticReconnect()` AND adds:
+ * - Token refresh on reconnect (re-authenticates if needed)
+ * - State change event notifications
+ * - Manual `stop()` that prevents further auto-reconnect
+ */
+declare class PersistentSafeguardEventListener {
+  #private;
+  constructor(connection: HubConnection, auth: Auth, host: string, httpClient: HttpClient, storage: StorageProvider, options?: PersistentListenerOptions, tokenSet?: TokenSet);
+  /** Current connection state. */
+  get state(): EventListenerState;
+  /**
+   * Register an event handler for Safeguard notifications.
+   */
+  on(_method: 'NotifyEventAsync', handler: EventHandler): this;
+  /**
+   * Register a state change handler.
+   */
+  onStateChange(handler: StateChangeHandler): this;
+  /**
+   * Start the persistent connection.
+   */
+  start(): Promise<void>;
+  /**
+   * Stop the connection. Prevents auto-reconnect.
+   */
+  stop(): Promise<void>;
+}
+//# sourceMappingURL=persistent.d.ts.map
+
+//#endregion
+export { type EventHandler, type EventListenerState, type PersistentListenerOptions, PersistentSafeguardEventListener, type SafeguardEvent, SafeguardEventListener, type StateChangeHandler };
+//# sourceMappingURL=events-RcqBZBsR.d.ts.map