@flipswitch-io/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,305 @@
+import { ProviderMetadata, EvaluationContext, ResolutionDetails, JsonValue } from '@openfeature/core';
+
+/**
+ * Configuration options for the Flipswitch provider.
+ */
+interface FlipswitchOptions {
+    /**
+     * The API key for your environment.
+     * Obtain this from your Flipswitch dashboard.
+     */
+    apiKey: string;
+    /**
+     * The base URL of your Flipswitch server.
+     * @default 'https://api.flipswitch.io'
+     */
+    baseUrl?: string;
+    /**
+     * Enable real-time flag updates via SSE.
+     * When enabled, the provider will connect to the SSE endpoint
+     * and automatically invalidate cached flags when changes occur.
+     * @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;
+}
+/**
+ * Event emitted when a flag changes.
+ */
+interface FlagChangeEvent {
+    /**
+     * The ID of the environment where the change occurred.
+     */
+    environmentId: number;
+    /**
+     * The key of the flag that changed, or null for bulk invalidation.
+     */
+    flagKey: string | null;
+    /**
+     * ISO timestamp of when the change occurred.
+     */
+    timestamp: string;
+}
+/**
+ * SSE connection status.
+ */
+type SseConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
+/**
+ * Event handler types for the provider.
+ */
+interface FlipswitchEventHandlers {
+    /**
+     * Called when a flag changes.
+     */
+    onFlagChange?: (event: FlagChangeEvent) => void;
+    /**
+     * Called when the SSE connection status changes.
+     */
+    onConnectionStatusChange?: (status: SseConnectionStatus) => void;
+}
+/**
+ * Represents the result of evaluating a single flag.
+ */
+interface FlagEvaluation {
+    /**
+     * The flag key.
+     */
+    key: string;
+    /**
+     * The evaluated value.
+     */
+    value: unknown;
+    /**
+     * The inferred type of the value.
+     */
+    valueType: 'boolean' | 'string' | 'number' | 'object' | 'array' | 'null' | 'unknown';
+    /**
+     * The reason for this evaluation result.
+     */
+    reason: string | null;
+    /**
+     * The variant that matched, if applicable.
+     */
+    variant: string | null;
+}
+
+type ProviderStatus = 'NOT_READY' | 'READY' | 'ERROR' | 'STALE';
+type ProviderEvent = 'PROVIDER_READY' | 'PROVIDER_ERROR' | 'PROVIDER_STALE' | 'PROVIDER_CONFIGURATION_CHANGED';
+type EventHandler = () => void;
+/**
+ * Flipswitch OpenFeature provider with real-time SSE support.
+ *
+ * This provider wraps the OFREP provider for flag evaluation and adds
+ * real-time updates via Server-Sent Events (SSE).
+ *
+ * @example
+ * ```typescript
+ * import { FlipswitchProvider } from '@flipswitch-io/sdk';
+ * import { OpenFeature } from '@openfeature/web-sdk';
+ *
+ * // Only API key is required - defaults to https://api.flipswitch.io
+ * const provider = new FlipswitchProvider({
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * await OpenFeature.setProviderAndWait(provider);
+ * const client = OpenFeature.getClient();
+ * const darkMode = await client.getBooleanValue('dark-mode', false);
+ * ```
+ */
+declare class FlipswitchProvider {
+    readonly metadata: ProviderMetadata;
+    readonly rulesFromFlagValue = false;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly enableRealtime;
+    private readonly enableTelemetry;
+    private readonly fetchImpl;
+    private readonly ofrepProvider;
+    private sseClient;
+    private _status;
+    private eventHandlers;
+    private userEventHandlers;
+    constructor(options: FlipswitchOptions, eventHandlers?: FlipswitchEventHandlers);
+    private getTelemetrySdkHeader;
+    private getTelemetryRuntimeHeader;
+    private getTelemetryOsHeader;
+    private getTelemetryFeaturesHeader;
+    private getTelemetryHeaders;
+    get status(): ProviderStatus;
+    /**
+     * Initialize the provider.
+     * Validates the API key and starts SSE connection if real-time is enabled.
+     */
+    initialize(context?: EvaluationContext): Promise<void>;
+    /**
+     * Called when the provider is shut down.
+     */
+    onClose(): Promise<void>;
+    /**
+     * Start the SSE connection for real-time updates.
+     */
+    private startSseConnection;
+    /**
+     * Get telemetry headers as a map.
+     */
+    private getTelemetryHeadersMap;
+    /**
+     * Handle a flag change event from SSE.
+     * Emits PROVIDER_CONFIGURATION_CHANGED to trigger re-evaluation.
+     */
+    private handleFlagChange;
+    /**
+     * Emit an event to registered handlers.
+     */
+    private emit;
+    /**
+     * Register an event handler.
+     */
+    onProviderEvent?(event: ProviderEvent, handler: EventHandler): void;
+    resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context: EvaluationContext): ResolutionDetails<boolean>;
+    resolveStringEvaluation(flagKey: string, defaultValue: string, context: EvaluationContext): ResolutionDetails<string>;
+    resolveNumberEvaluation(flagKey: string, defaultValue: number, context: EvaluationContext): ResolutionDetails<number>;
+    resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T, context: EvaluationContext): ResolutionDetails<T>;
+    /**
+     * Get SSE connection status.
+     */
+    getSseStatus(): SseConnectionStatus;
+    /**
+     * Force reconnect SSE connection.
+     */
+    reconnectSse(): void;
+    /**
+     * Transform OpenFeature context to OFREP context format.
+     */
+    private transformContext;
+    /**
+     * Infer the type of a value.
+     */
+    private inferType;
+    /**
+     * Get flag type from metadata or infer from value.
+     */
+    private getFlagType;
+    /**
+     * Format a value for display.
+     */
+    formatValue(value: unknown): string;
+    /**
+     * Evaluate all flags for the given context.
+     * Returns a list of all flag evaluations with their keys, values, types, and reasons.
+     *
+     * Note: This method makes direct HTTP calls since OFREP providers don't expose
+     * the bulk evaluation API.
+     *
+     * @param context The evaluation context
+     * @returns List of flag evaluations
+     */
+    evaluateAllFlags(context: EvaluationContext): Promise<FlagEvaluation[]>;
+    /**
+     * Evaluate a single flag and return its evaluation result.
+     *
+     * Note: This method makes direct HTTP calls for demo purposes.
+     * For standard flag evaluation, use the OpenFeature client methods.
+     *
+     * @param flagKey The flag key to evaluate
+     * @param context The evaluation context
+     * @returns The flag evaluation, or null if the flag doesn't exist
+     */
+    evaluateFlag(flagKey: string, context: EvaluationContext): Promise<FlagEvaluation | null>;
+}
+
+/**
+ * SSE client for real-time flag change notifications.
+ * Handles automatic reconnection with exponential backoff.
+ */
+declare class SseClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly onFlagChange;
+    private readonly onStatusChange?;
+    private readonly telemetryHeaders?;
+    private eventSource;
+    private retryDelay;
+    private reconnectTimeout;
+    private closed;
+    private status;
+    constructor(baseUrl: string, apiKey: string, onFlagChange: (event: FlagChangeEvent) => void, onStatusChange?: ((status: SseConnectionStatus) => void) | undefined, telemetryHeaders?: Record<string, string> | undefined);
+    /**
+     * Start the SSE connection.
+     */
+    connect(): void;
+    /**
+     * Connect using fetch-based SSE (supports custom headers).
+     */
+    private connectWithFetch;
+    /**
+     * Connect using native EventSource (for environments that support it).
+     * Note: This requires server-side support for API key in query params.
+     */
+    private connectWithPolyfill;
+    /**
+     * Handle incoming SSE events.
+     */
+    private handleEvent;
+    /**
+     * Schedule a reconnection attempt with exponential backoff.
+     */
+    private scheduleReconnect;
+    /**
+     * Update and broadcast connection status.
+     */
+    private updateStatus;
+    /**
+     * Get current connection status.
+     */
+    getStatus(): SseConnectionStatus;
+    /**
+     * Close the SSE connection and stop reconnection attempts.
+     */
+    close(): void;
+}
+
+/**
+ * Simple in-memory cache for flag values with TTL support.
+ */
+declare class FlagCache {
+    private cache;
+    private readonly ttlMs;
+    /**
+     * Create a new FlagCache.
+     * @param ttlMs Time-to-live in milliseconds (default: 5 minutes)
+     */
+    constructor(ttlMs?: number);
+    /**
+     * Get a value from the cache.
+     * Returns undefined if the key doesn't exist or has expired.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set a value in the cache.
+     */
+    set<T>(key: string, value: T): void;
+    /**
+     * Invalidate a specific key or all keys if no key is provided.
+     */
+    invalidate(key?: string): void;
+    /**
+     * Handle a flag change event from SSE.
+     * Invalidates the specific flag or all flags if flagKey is null.
+     */
+    handleFlagChange(event: FlagChangeEvent): void;
+}
+
+export { FlagCache, type FlagChangeEvent, type FlagEvaluation, type FlipswitchEventHandlers, type FlipswitchOptions, FlipswitchProvider, SseClient, type SseConnectionStatus };