@flipswitch-io/sdk 0.1.4 → 0.1.6

package/dist/index.d.mts

@@ -21,27 +21,105 @@ interface FlipswitchOptions {
      * @default true
      */
     enableRealtime?: boolean;
-    /**
-     * Enable telemetry collection.
-     * When enabled, the SDK sends usage statistics (SDK version, runtime version,
-     * OS, architecture) to help improve the service. No personal data is collected.
-     * @default true
-     */
-    enableTelemetry?: boolean;
     /**
      * Custom fetch function for making HTTP requests.
      * Useful for testing or custom networking needs.
      */
     fetchImplementation?: typeof fetch;
+    /**
+     * Persist flag values to localStorage (browser only).
+     * When enabled, flag values are cached in localStorage and used
+     * as fallback when offline or during initial load.
+     * @default true (in browser environments)
+     */
+    persistCache?: boolean;
+    /**
+     * Enable offline mode support.
+     * When enabled, the provider will detect offline state and serve
+     * cached values without attempting network requests.
+     * @default true (in browser environments)
+     */
+    offlineMode?: boolean;
+    /**
+     * Enable visibility API integration (browser only).
+     * When enabled, SSE connection is paused when the tab is hidden
+     * and resumed when it becomes visible, saving resources.
+     * @default true (in browser environments)
+     */
+    enableVisibilityHandling?: boolean;
+    /**
+     * Enable polling fallback when SSE fails.
+     * After maxSseRetries, the provider will fall back to polling.
+     * @default true
+     */
+    enablePollingFallback?: boolean;
+    /**
+     * Polling interval in milliseconds for fallback mode.
+     * Only used when SSE connection fails and polling fallback is enabled.
+     * @default 30000 (30 seconds)
+     */
+    pollingInterval?: number;
+    /**
+     * Maximum SSE retry attempts before falling back to polling.
+     * @default 5
+     */
+    maxSseRetries?: number;
 }
 /**
- * Event emitted when a flag changes.
+ * Event emitted when a single flag is updated.
  */
-interface FlagChangeEvent {
+interface FlagUpdatedEvent {
+    /**
+     * The key of the flag that changed.
+     */
+    flagKey: string;
+    /**
+     * ISO timestamp of when the change occurred.
+     */
+    timestamp: string;
+}
+/**
+ * Event emitted when configuration changes that may affect multiple flags.
+ */
+interface ConfigUpdatedEvent {
+    /**
+     * ISO timestamp of when the change occurred.
+     */
+    timestamp: string;
+}
+/**
+ * Event emitted when an API key has been rotated or rotation was aborted.
+ */
+interface ApiKeyRotatedEvent {
     /**
-     * The ID of the environment where the change occurred.
+     * ISO timestamp when the current key expires.
+     * Null if the rotation was aborted.
      */
-    environmentId: number;
+    validUntil: string | null;
+    /**
+     * ISO timestamp of when the event occurred.
+     */
+    timestamp: string;
+}
+/**
+ * Union type for all flag events.
+ * Used internally to handle event types.
+ */
+type FlagEvent = {
+    type: 'flag-updated';
+    data: FlagUpdatedEvent;
+} | {
+    type: 'config-updated';
+    data: ConfigUpdatedEvent;
+} | {
+    type: 'api-key-rotated';
+    data: ApiKeyRotatedEvent;
+};
+/**
+ * @deprecated Use FlagUpdatedEvent or ConfigUpdatedEvent instead.
+ * Event emitted when a flag changes (legacy format).
+ */
+interface FlagChangeEvent {
     /**
      * The key of the flag that changed, or null for bulk invalidation.
      */
@@ -122,13 +200,24 @@ declare class FlipswitchProvider {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly enableRealtime;
-    private readonly enableTelemetry;
     private readonly fetchImpl;
     private readonly ofrepProvider;
+    private readonly browserCache;
+    private readonly enableVisibilityHandling;
+    private readonly enablePollingFallback;
+    private readonly pollingInterval;
+    private readonly maxSseRetries;
+    private readonly offlineMode;
     private sseClient;
     private _status;
     private eventHandlers;
     private userEventHandlers;
+    private pollingTimer;
+    private sseRetryCount;
+    private isPollingFallbackActive;
+    private onlineHandler;
+    private offlineHandler;
+    private _isOnline;
     constructor(options: FlipswitchOptions, eventHandlers?: FlipswitchEventHandlers);
     private getTelemetrySdkHeader;
     private getTelemetryRuntimeHeader;
@@ -141,10 +230,34 @@ declare class FlipswitchProvider {
      * Validates the API key and starts SSE connection if real-time is enabled.
      */
     initialize(context?: EvaluationContext): Promise<void>;
+    /**
+     * Setup online/offline event handling.
+     */
+    private setupOfflineHandling;
+    /**
+     * Refresh flags from the server.
+     */
+    private refreshFlags;
     /**
      * Called when the provider is shut down.
      */
     onClose(): Promise<void>;
+    /**
+     * Stop the polling fallback.
+     */
+    private stopPolling;
+    /**
+     * Start polling fallback when SSE fails.
+     */
+    private startPollingFallback;
+    /**
+     * Check if the provider is currently online.
+     */
+    isOnline(): boolean;
+    /**
+     * Check if polling fallback is active.
+     */
+    isPollingActive(): boolean;
     /**
      * Start the SSE connection for real-time updates.
      */
@@ -155,7 +268,7 @@ declare class FlipswitchProvider {
     private getTelemetryHeadersMap;
     /**
      * Handle a flag change event from SSE.
-     * Emits PROVIDER_CONFIGURATION_CHANGED to trigger re-evaluation.
+     * Triggers OFREP cache refresh, updates browser cache, and emits PROVIDER_CONFIGURATION_CHANGED.
      */
     private handleFlagChange;
     /**
@@ -221,6 +334,7 @@ declare class FlipswitchProvider {
 /**
  * SSE client for real-time flag change notifications.
  * Handles automatic reconnection with exponential backoff.
+ * Includes visibility API integration for browser environments.
  */
 declare class SseClient {
     private readonly baseUrl;
@@ -228,16 +342,38 @@ declare class SseClient {
     private readonly onFlagChange;
     private readonly onStatusChange?;
     private readonly telemetryHeaders?;
+    private readonly enableVisibilityHandling;
     private eventSource;
     private retryDelay;
     private reconnectTimeout;
     private closed;
+    private paused;
     private status;
-    constructor(baseUrl: string, apiKey: string, onFlagChange: (event: FlagChangeEvent) => void, onStatusChange?: ((status: SseConnectionStatus) => void) | undefined, telemetryHeaders?: Record<string, string> | undefined);
+    private visibilityHandler;
+    private abortController;
+    constructor(baseUrl: string, apiKey: string, onFlagChange: (event: FlagChangeEvent) => void, onStatusChange?: ((status: SseConnectionStatus) => void) | undefined, telemetryHeaders?: Record<string, string> | undefined, enableVisibilityHandling?: boolean);
     /**
      * Start the SSE connection.
      */
     connect(): void;
+    /**
+     * Setup visibility API handling.
+     * Disconnects when tab is hidden, reconnects when visible.
+     */
+    private setupVisibilityHandling;
+    /**
+     * Pause the SSE connection (used by visibility API).
+     * Different from close() - can be resumed.
+     */
+    pause(): void;
+    /**
+     * Resume the SSE connection after being paused.
+     */
+    resume(): void;
+    /**
+     * Check if the connection is paused.
+     */
+    isPaused(): boolean;
     /**
      * Connect using fetch-based SSE (supports custom headers).
      */
@@ -300,4 +436,81 @@ declare class FlagCache {
     handleFlagChange(event: FlagChangeEvent): void;
 }
 
-export { FlagCache, type FlagChangeEvent, type FlagEvaluation, type FlipswitchEventHandlers, type FlipswitchOptions, FlipswitchProvider, SseClient, type SseConnectionStatus };
+/**
+ * Browser-based cache for flag values using localStorage.
+ * Provides persistence across page reloads and offline support.
+ */
+interface CachedFlag {
+    value: unknown;
+    timestamp: number;
+    variant?: string;
+    reason?: string;
+}
+interface CacheMeta {
+    lastUpdated: number;
+    version: number;
+}
+/**
+ * Browser cache for persisting flag values to localStorage.
+ * Falls back gracefully when localStorage is unavailable.
+ */
+declare class BrowserCache {
+    private readonly storage;
+    private readonly cacheVersion;
+    constructor();
+    /**
+     * Get storage instance if available.
+     */
+    private getStorage;
+    /**
+     * Check if browser cache is available.
+     */
+    isAvailable(): boolean;
+    /**
+     * Get a cached flag value.
+     */
+    get(flagKey: string): CachedFlag | null;
+    /**
+     * Set a cached flag value.
+     */
+    set(flagKey: string, value: unknown, variant?: string, reason?: string): void;
+    /**
+     * Set multiple cached flag values at once.
+     */
+    setAll(flags: Array<{
+        key: string;
+        value: unknown;
+        variant?: string;
+        reason?: string;
+    }>): void;
+    /**
+     * Get all cached flags.
+     */
+    getAll(): Map<string, CachedFlag>;
+    /**
+     * Invalidate a specific flag or all flags.
+     */
+    invalidate(flagKey?: string): void;
+    /**
+     * Update cache metadata.
+     */
+    private updateMeta;
+    /**
+     * Get cache metadata.
+     */
+    getMeta(): CacheMeta | null;
+    /**
+     * Get the age of a cached flag in milliseconds.
+     */
+    getAge(flagKey: string): number | null;
+    /**
+     * Check if a cached flag is stale based on max age.
+     */
+    isStale(flagKey: string, maxAgeMs: number): boolean;
+    /**
+     * Clear all Flipswitch data from localStorage.
+     */
+    clear(): void;
+}
+
+export { type ApiKeyRotatedEvent, BrowserCache, type ConfigUpdatedEvent, FlagCache, type FlagChangeEvent, type FlagEvaluation, type FlagEvent, type FlagUpdatedEvent, type FlipswitchEventHandlers, type FlipswitchOptions, FlipswitchProvider, SseClient, type SseConnectionStatus };

package/dist/index.d.ts

@@ -21,27 +21,105 @@ interface FlipswitchOptions {
      * @default true
      */
     enableRealtime?: boolean;
-    /**
-     * Enable telemetry collection.
-     * When enabled, the SDK sends usage statistics (SDK version, runtime version,
-     * OS, architecture) to help improve the service. No personal data is collected.
-     * @default true
-     */
-    enableTelemetry?: boolean;
     /**
      * Custom fetch function for making HTTP requests.
      * Useful for testing or custom networking needs.
      */
     fetchImplementation?: typeof fetch;
+    /**
+     * Persist flag values to localStorage (browser only).
+     * When enabled, flag values are cached in localStorage and used
+     * as fallback when offline or during initial load.
+     * @default true (in browser environments)
+     */
+    persistCache?: boolean;
+    /**
+     * Enable offline mode support.
+     * When enabled, the provider will detect offline state and serve
+     * cached values without attempting network requests.
+     * @default true (in browser environments)
+     */
+    offlineMode?: boolean;
+    /**
+     * Enable visibility API integration (browser only).
+     * When enabled, SSE connection is paused when the tab is hidden
+     * and resumed when it becomes visible, saving resources.
+     * @default true (in browser environments)
+     */
+    enableVisibilityHandling?: boolean;
+    /**
+     * Enable polling fallback when SSE fails.
+     * After maxSseRetries, the provider will fall back to polling.
+     * @default true
+     */
+    enablePollingFallback?: boolean;
+    /**
+     * Polling interval in milliseconds for fallback mode.
+     * Only used when SSE connection fails and polling fallback is enabled.
+     * @default 30000 (30 seconds)
+     */
+    pollingInterval?: number;
+    /**
+     * Maximum SSE retry attempts before falling back to polling.
+     * @default 5
+     */
+    maxSseRetries?: number;
 }
 /**
- * Event emitted when a flag changes.
+ * Event emitted when a single flag is updated.
  */
-interface FlagChangeEvent {
+interface FlagUpdatedEvent {
+    /**
+     * The key of the flag that changed.
+     */
+    flagKey: string;
+    /**
+     * ISO timestamp of when the change occurred.
+     */
+    timestamp: string;
+}
+/**
+ * Event emitted when configuration changes that may affect multiple flags.
+ */
+interface ConfigUpdatedEvent {
+    /**
+     * ISO timestamp of when the change occurred.
+     */
+    timestamp: string;
+}
+/**
+ * Event emitted when an API key has been rotated or rotation was aborted.
+ */
+interface ApiKeyRotatedEvent {
     /**
-     * The ID of the environment where the change occurred.
+     * ISO timestamp when the current key expires.
+     * Null if the rotation was aborted.
      */
-    environmentId: number;
+    validUntil: string | null;
+    /**
+     * ISO timestamp of when the event occurred.
+     */
+    timestamp: string;
+}
+/**
+ * Union type for all flag events.
+ * Used internally to handle event types.
+ */
+type FlagEvent = {
+    type: 'flag-updated';
+    data: FlagUpdatedEvent;
+} | {
+    type: 'config-updated';
+    data: ConfigUpdatedEvent;
+} | {
+    type: 'api-key-rotated';
+    data: ApiKeyRotatedEvent;
+};
+/**
+ * @deprecated Use FlagUpdatedEvent or ConfigUpdatedEvent instead.
+ * Event emitted when a flag changes (legacy format).
+ */
+interface FlagChangeEvent {
     /**
      * The key of the flag that changed, or null for bulk invalidation.
      */
@@ -122,13 +200,24 @@ declare class FlipswitchProvider {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly enableRealtime;
-    private readonly enableTelemetry;
     private readonly fetchImpl;
     private readonly ofrepProvider;
+    private readonly browserCache;
+    private readonly enableVisibilityHandling;
+    private readonly enablePollingFallback;
+    private readonly pollingInterval;
+    private readonly maxSseRetries;
+    private readonly offlineMode;
     private sseClient;
     private _status;
     private eventHandlers;
     private userEventHandlers;
+    private pollingTimer;
+    private sseRetryCount;
+    private isPollingFallbackActive;
+    private onlineHandler;
+    private offlineHandler;
+    private _isOnline;
     constructor(options: FlipswitchOptions, eventHandlers?: FlipswitchEventHandlers);
     private getTelemetrySdkHeader;
     private getTelemetryRuntimeHeader;
@@ -141,10 +230,34 @@ declare class FlipswitchProvider {
      * Validates the API key and starts SSE connection if real-time is enabled.
      */
     initialize(context?: EvaluationContext): Promise<void>;
+    /**
+     * Setup online/offline event handling.
+     */
+    private setupOfflineHandling;
+    /**
+     * Refresh flags from the server.
+     */
+    private refreshFlags;
     /**
      * Called when the provider is shut down.
      */
     onClose(): Promise<void>;
+    /**
+     * Stop the polling fallback.
+     */
+    private stopPolling;
+    /**
+     * Start polling fallback when SSE fails.
+     */
+    private startPollingFallback;
+    /**
+     * Check if the provider is currently online.
+     */
+    isOnline(): boolean;
+    /**
+     * Check if polling fallback is active.
+     */
+    isPollingActive(): boolean;
     /**
      * Start the SSE connection for real-time updates.
      */
@@ -155,7 +268,7 @@ declare class FlipswitchProvider {
     private getTelemetryHeadersMap;
     /**
      * Handle a flag change event from SSE.
-     * Emits PROVIDER_CONFIGURATION_CHANGED to trigger re-evaluation.
+     * Triggers OFREP cache refresh, updates browser cache, and emits PROVIDER_CONFIGURATION_CHANGED.
      */
     private handleFlagChange;
     /**
@@ -221,6 +334,7 @@ declare class FlipswitchProvider {
 /**
  * SSE client for real-time flag change notifications.
  * Handles automatic reconnection with exponential backoff.
+ * Includes visibility API integration for browser environments.
  */
 declare class SseClient {
     private readonly baseUrl;
@@ -228,16 +342,38 @@ declare class SseClient {
     private readonly onFlagChange;
     private readonly onStatusChange?;
     private readonly telemetryHeaders?;
+    private readonly enableVisibilityHandling;
     private eventSource;
     private retryDelay;
     private reconnectTimeout;
     private closed;
+    private paused;
     private status;
-    constructor(baseUrl: string, apiKey: string, onFlagChange: (event: FlagChangeEvent) => void, onStatusChange?: ((status: SseConnectionStatus) => void) | undefined, telemetryHeaders?: Record<string, string> | undefined);
+    private visibilityHandler;
+    private abortController;
+    constructor(baseUrl: string, apiKey: string, onFlagChange: (event: FlagChangeEvent) => void, onStatusChange?: ((status: SseConnectionStatus) => void) | undefined, telemetryHeaders?: Record<string, string> | undefined, enableVisibilityHandling?: boolean);
     /**
      * Start the SSE connection.
      */
     connect(): void;
+    /**
+     * Setup visibility API handling.
+     * Disconnects when tab is hidden, reconnects when visible.
+     */
+    private setupVisibilityHandling;
+    /**
+     * Pause the SSE connection (used by visibility API).
+     * Different from close() - can be resumed.
+     */
+    pause(): void;
+    /**
+     * Resume the SSE connection after being paused.
+     */
+    resume(): void;
+    /**
+     * Check if the connection is paused.
+     */
+    isPaused(): boolean;
     /**
      * Connect using fetch-based SSE (supports custom headers).
      */
@@ -300,4 +436,81 @@ declare class FlagCache {
     handleFlagChange(event: FlagChangeEvent): void;
 }
 
-export { FlagCache, type FlagChangeEvent, type FlagEvaluation, type FlipswitchEventHandlers, type FlipswitchOptions, FlipswitchProvider, SseClient, type SseConnectionStatus };
+/**
+ * Browser-based cache for flag values using localStorage.
+ * Provides persistence across page reloads and offline support.
+ */
+interface CachedFlag {
+    value: unknown;
+    timestamp: number;
+    variant?: string;
+    reason?: string;
+}
+interface CacheMeta {
+    lastUpdated: number;
+    version: number;
+}
+/**
+ * Browser cache for persisting flag values to localStorage.
+ * Falls back gracefully when localStorage is unavailable.
+ */
+declare class BrowserCache {
+    private readonly storage;
+    private readonly cacheVersion;
+    constructor();
+    /**
+     * Get storage instance if available.
+     */
+    private getStorage;
+    /**
+     * Check if browser cache is available.
+     */
+    isAvailable(): boolean;
+    /**
+     * Get a cached flag value.
+     */
+    get(flagKey: string): CachedFlag | null;
+    /**
+     * Set a cached flag value.
+     */
+    set(flagKey: string, value: unknown, variant?: string, reason?: string): void;
+    /**
+     * Set multiple cached flag values at once.
+     */
+    setAll(flags: Array<{
+        key: string;
+        value: unknown;
+        variant?: string;
+        reason?: string;
+    }>): void;
+    /**
+     * Get all cached flags.
+     */
+    getAll(): Map<string, CachedFlag>;
+    /**
+     * Invalidate a specific flag or all flags.
+     */
+    invalidate(flagKey?: string): void;
+    /**
+     * Update cache metadata.
+     */
+    private updateMeta;
+    /**
+     * Get cache metadata.
+     */
+    getMeta(): CacheMeta | null;
+    /**
+     * Get the age of a cached flag in milliseconds.
+     */
+    getAge(flagKey: string): number | null;
+    /**
+     * Check if a cached flag is stale based on max age.
+     */
+    isStale(flagKey: string, maxAgeMs: number): boolean;
+    /**
+     * Clear all Flipswitch data from localStorage.
+     */
+    clear(): void;
+}
+
+export { type ApiKeyRotatedEvent, BrowserCache, type ConfigUpdatedEvent, FlagCache, type FlagChangeEvent, type FlagEvaluation, type FlagEvent, type FlagUpdatedEvent, type FlipswitchEventHandlers, type FlipswitchOptions, FlipswitchProvider, SseClient, type SseConnectionStatus };