@teracrafts/flagkit 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2048 @@
+/**
+ * Log levels supported by the SDK
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+/**
+ * Log entry structure
+ */
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: Date;
+    data?: Record<string, unknown>;
+}
+/**
+ * Logger interface for custom implementations
+ */
+interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Default console logger implementation
+ */
+declare class ConsoleLogger implements Logger {
+    private readonly prefix;
+    private readonly minLevel;
+    constructor(options?: {
+        prefix?: string;
+        level?: LogLevel;
+    });
+    private shouldLog;
+    private formatMessage;
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * No-op logger that discards all messages
+ */
+declare class NoopLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}
+/**
+ * Create a logger instance based on configuration
+ */
+declare function createLogger(options?: {
+    logger?: Logger;
+    debug?: boolean;
+}): Logger;
+
+/**
+ * Flag value types supported by FlagKit
+ */
+type FlagType = 'boolean' | 'string' | 'number' | 'json';
+/**
+ * Possible flag value
+ */
+type FlagValue = boolean | string | number | Record<string, unknown>;
+/**
+ * Reasons for an evaluation result
+ */
+type EvaluationReason = 'FLAG_NOT_FOUND' | 'FLAG_DISABLED' | 'ENVIRONMENT_NOT_CONFIGURED' | 'FALLTHROUGH' | 'RULE_MATCH' | 'SEGMENT_MATCH' | 'DEFAULT' | 'EVALUATION_ERROR' | 'CACHED' | 'STALE_CACHE' | 'BOOTSTRAP' | 'OFFLINE';
+/**
+ * State of a feature flag returned from the API
+ */
+interface FlagState {
+    /** Unique flag key */
+    key: string;
+    /** Current flag value */
+    value: FlagValue;
+    /** Whether the flag is enabled */
+    enabled: boolean;
+    /** Flag version number */
+    version: number;
+    /** Type of the flag value */
+    flagType: FlagType;
+    /** Last modification timestamp */
+    lastModified: string;
+}
+/**
+ * Result of a flag evaluation
+ */
+interface EvaluationResult<T = FlagValue> {
+    /** The flag key that was evaluated */
+    flagKey: string;
+    /** The resolved flag value */
+    value: T;
+    /** Whether the flag is enabled */
+    enabled: boolean;
+    /** Reason for the evaluation result */
+    reason: EvaluationReason;
+    /** Variation ID if applicable */
+    variationId?: string;
+    /** Rule ID that matched */
+    ruleId?: string;
+    /** Segment ID that matched */
+    segmentId?: string;
+    /** Flag version at time of evaluation */
+    version: number;
+    /** Timestamp of evaluation */
+    timestamp: Date;
+}
+/**
+ * API response for SDK initialization
+ */
+interface InitResponse {
+    flags: FlagState[];
+    environment: string;
+    environmentId: string;
+    projectId: string;
+    organizationId: string;
+    serverTime: string;
+    pollingIntervalSeconds: number;
+    streamingUrl: string | null;
+    metadata: {
+        /** Minimum SDK version required (older versions may not work) */
+        sdkVersionMin?: string;
+        /** Recommended SDK version for optimal experience */
+        sdkVersionRecommended?: string;
+        /** Latest available SDK version */
+        sdkVersionLatest?: string;
+        /** Deprecation warning message from server */
+        deprecationWarning?: string | null;
+        features: {
+            streaming: boolean;
+            localEval: boolean;
+            experiments: boolean;
+            segments: boolean;
+        };
+    };
+}
+/**
+ * API response for flag evaluation
+ */
+interface EvaluateResponse {
+    flagKey: string;
+    value: FlagValue;
+    enabled: boolean;
+    reason: EvaluationReason;
+    variationId?: string;
+    ruleId?: string;
+    segmentId?: string;
+    version: number;
+    timestamp: string;
+}
+/**
+ * API response for batch evaluation
+ */
+interface BatchEvaluateResponse {
+    flags: Record<string, EvaluateResponse>;
+    evaluatedAt: string;
+}
+/**
+ * API response for polling updates
+ */
+interface UpdatesResponse {
+    flags: FlagState[];
+    checkedAt: string;
+    since: string;
+}
+
+/**
+ * All error codes with their numeric values and default messages
+ */
+declare const ErrorCodes: {
+    readonly INIT_FAILED: {
+        readonly code: "INIT_FAILED";
+        readonly numericCode: 1000;
+        readonly message: "SDK initialization failed";
+        readonly recoverable: false;
+    };
+    readonly INIT_TIMEOUT: {
+        readonly code: "INIT_TIMEOUT";
+        readonly numericCode: 1001;
+        readonly message: "Initialization timed out";
+        readonly recoverable: true;
+    };
+    readonly INIT_INVALID_CONFIG: {
+        readonly code: "INIT_INVALID_CONFIG";
+        readonly numericCode: 1002;
+        readonly message: "Invalid SDK configuration";
+        readonly recoverable: false;
+    };
+    readonly INIT_MISSING_API_KEY: {
+        readonly code: "INIT_MISSING_API_KEY";
+        readonly numericCode: 1003;
+        readonly message: "API key is required";
+        readonly recoverable: false;
+    };
+    readonly INIT_INVALID_BASE_URL: {
+        readonly code: "INIT_INVALID_BASE_URL";
+        readonly numericCode: 1004;
+        readonly message: "Invalid base URL format";
+        readonly recoverable: false;
+    };
+    readonly INIT_ALREADY_INITIALIZED: {
+        readonly code: "INIT_ALREADY_INITIALIZED";
+        readonly numericCode: 1005;
+        readonly message: "SDK already initialized";
+        readonly recoverable: false;
+    };
+    readonly AUTH_INVALID_KEY: {
+        readonly code: "AUTH_INVALID_KEY";
+        readonly numericCode: 1100;
+        readonly message: "Invalid API key";
+        readonly recoverable: false;
+    };
+    readonly AUTH_EXPIRED_KEY: {
+        readonly code: "AUTH_EXPIRED_KEY";
+        readonly numericCode: 1101;
+        readonly message: "API key has expired";
+        readonly recoverable: false;
+    };
+    readonly AUTH_REVOKED_KEY: {
+        readonly code: "AUTH_REVOKED_KEY";
+        readonly numericCode: 1102;
+        readonly message: "API key has been revoked";
+        readonly recoverable: false;
+    };
+    readonly AUTH_INSUFFICIENT_PERMISSIONS: {
+        readonly code: "AUTH_INSUFFICIENT_PERMISSIONS";
+        readonly numericCode: 1103;
+        readonly message: "API key lacks required permissions";
+        readonly recoverable: false;
+    };
+    readonly AUTH_RATE_LIMITED: {
+        readonly code: "AUTH_RATE_LIMITED";
+        readonly numericCode: 1104;
+        readonly message: "Rate limit exceeded";
+        readonly recoverable: true;
+    };
+    readonly AUTH_PROJECT_MISMATCH: {
+        readonly code: "AUTH_PROJECT_MISMATCH";
+        readonly numericCode: 1105;
+        readonly message: "API key not valid for this project";
+        readonly recoverable: false;
+    };
+    readonly AUTH_ENVIRONMENT_MISMATCH: {
+        readonly code: "AUTH_ENVIRONMENT_MISMATCH";
+        readonly numericCode: 1106;
+        readonly message: "API key not valid for this environment";
+        readonly recoverable: false;
+    };
+    readonly AUTH_IP_RESTRICTED: {
+        readonly code: "AUTH_IP_RESTRICTED";
+        readonly numericCode: 1107;
+        readonly message: "IP address not allowed for this API key";
+        readonly recoverable: false;
+    };
+    readonly AUTH_ORGANIZATION_REQUIRED: {
+        readonly code: "AUTH_ORGANIZATION_REQUIRED";
+        readonly numericCode: 1108;
+        readonly message: "Organization context missing from token";
+        readonly recoverable: false;
+    };
+    readonly AUTH_SUBSCRIPTION_SUSPENDED: {
+        readonly code: "AUTH_SUBSCRIPTION_SUSPENDED";
+        readonly numericCode: 1109;
+        readonly message: "Subscription is suspended";
+        readonly recoverable: false;
+    };
+    readonly EVAL_FLAG_NOT_FOUND: {
+        readonly code: "EVAL_FLAG_NOT_FOUND";
+        readonly numericCode: 1200;
+        readonly message: "Flag does not exist";
+        readonly recoverable: false;
+    };
+    readonly EVAL_FLAG_DISABLED: {
+        readonly code: "EVAL_FLAG_DISABLED";
+        readonly numericCode: 1201;
+        readonly message: "Flag is disabled";
+        readonly recoverable: false;
+    };
+    readonly EVAL_TYPE_MISMATCH: {
+        readonly code: "EVAL_TYPE_MISMATCH";
+        readonly numericCode: 1202;
+        readonly message: "Flag value type mismatch";
+        readonly recoverable: false;
+    };
+    readonly EVAL_INVALID_CONTEXT: {
+        readonly code: "EVAL_INVALID_CONTEXT";
+        readonly numericCode: 1203;
+        readonly message: "Invalid evaluation context";
+        readonly recoverable: false;
+    };
+    readonly EVAL_RULE_ERROR: {
+        readonly code: "EVAL_RULE_ERROR";
+        readonly numericCode: 1204;
+        readonly message: "Error evaluating targeting rule";
+        readonly recoverable: true;
+    };
+    readonly EVAL_SEGMENT_ERROR: {
+        readonly code: "EVAL_SEGMENT_ERROR";
+        readonly numericCode: 1205;
+        readonly message: "Error evaluating segment";
+        readonly recoverable: true;
+    };
+    readonly EVAL_DEFAULT_USED: {
+        readonly code: "EVAL_DEFAULT_USED";
+        readonly numericCode: 1206;
+        readonly message: "Using default value";
+        readonly recoverable: false;
+    };
+    readonly EVAL_CACHED_VALUE: {
+        readonly code: "EVAL_CACHED_VALUE";
+        readonly numericCode: 1207;
+        readonly message: "Using cached value";
+        readonly recoverable: false;
+    };
+    readonly EVAL_STALE_VALUE: {
+        readonly code: "EVAL_STALE_VALUE";
+        readonly numericCode: 1208;
+        readonly message: "Using stale cached value";
+        readonly recoverable: false;
+    };
+    readonly NETWORK_ERROR: {
+        readonly code: "NETWORK_ERROR";
+        readonly numericCode: 1300;
+        readonly message: "Network request failed";
+        readonly recoverable: true;
+    };
+    readonly NETWORK_TIMEOUT: {
+        readonly code: "NETWORK_TIMEOUT";
+        readonly numericCode: 1301;
+        readonly message: "Request timed out";
+        readonly recoverable: true;
+    };
+    readonly NETWORK_DNS_ERROR: {
+        readonly code: "NETWORK_DNS_ERROR";
+        readonly numericCode: 1302;
+        readonly message: "DNS resolution failed";
+        readonly recoverable: true;
+    };
+    readonly NETWORK_CONNECTION_REFUSED: {
+        readonly code: "NETWORK_CONNECTION_REFUSED";
+        readonly numericCode: 1303;
+        readonly message: "Connection refused";
+        readonly recoverable: true;
+    };
+    readonly NETWORK_SSL_ERROR: {
+        readonly code: "NETWORK_SSL_ERROR";
+        readonly numericCode: 1304;
+        readonly message: "SSL/TLS error";
+        readonly recoverable: false;
+    };
+    readonly NETWORK_OFFLINE: {
+        readonly code: "NETWORK_OFFLINE";
+        readonly numericCode: 1305;
+        readonly message: "Device is offline";
+        readonly recoverable: true;
+    };
+    readonly NETWORK_SERVER_ERROR: {
+        readonly code: "NETWORK_SERVER_ERROR";
+        readonly numericCode: 1306;
+        readonly message: "Server error";
+        readonly recoverable: true;
+    };
+    readonly NETWORK_INVALID_RESPONSE: {
+        readonly code: "NETWORK_INVALID_RESPONSE";
+        readonly numericCode: 1307;
+        readonly message: "Invalid server response";
+        readonly recoverable: true;
+    };
+    readonly NETWORK_SERVICE_UNAVAILABLE: {
+        readonly code: "NETWORK_SERVICE_UNAVAILABLE";
+        readonly numericCode: 1308;
+        readonly message: "Service unavailable";
+        readonly recoverable: true;
+    };
+    readonly CACHE_READ_ERROR: {
+        readonly code: "CACHE_READ_ERROR";
+        readonly numericCode: 1400;
+        readonly message: "Failed to read from cache";
+        readonly recoverable: true;
+    };
+    readonly CACHE_WRITE_ERROR: {
+        readonly code: "CACHE_WRITE_ERROR";
+        readonly numericCode: 1401;
+        readonly message: "Failed to write to cache";
+        readonly recoverable: true;
+    };
+    readonly CACHE_EXPIRED: {
+        readonly code: "CACHE_EXPIRED";
+        readonly numericCode: 1402;
+        readonly message: "Cache has expired";
+        readonly recoverable: true;
+    };
+    readonly CACHE_CORRUPT: {
+        readonly code: "CACHE_CORRUPT";
+        readonly numericCode: 1403;
+        readonly message: "Cache data is corrupted";
+        readonly recoverable: true;
+    };
+    readonly CACHE_STORAGE_FULL: {
+        readonly code: "CACHE_STORAGE_FULL";
+        readonly numericCode: 1404;
+        readonly message: "Storage quota exceeded";
+        readonly recoverable: true;
+    };
+    readonly EVENT_SEND_FAILED: {
+        readonly code: "EVENT_SEND_FAILED";
+        readonly numericCode: 1500;
+        readonly message: "Failed to send event";
+        readonly recoverable: true;
+    };
+    readonly EVENT_INVALID_TYPE: {
+        readonly code: "EVENT_INVALID_TYPE";
+        readonly numericCode: 1501;
+        readonly message: "Invalid event type";
+        readonly recoverable: false;
+    };
+    readonly EVENT_INVALID_DATA: {
+        readonly code: "EVENT_INVALID_DATA";
+        readonly numericCode: 1502;
+        readonly message: "Invalid event data";
+        readonly recoverable: false;
+    };
+    readonly EVENT_QUEUE_FULL: {
+        readonly code: "EVENT_QUEUE_FULL";
+        readonly numericCode: 1503;
+        readonly message: "Event queue is full";
+        readonly recoverable: true;
+    };
+    readonly EVENT_BATCH_PARTIAL: {
+        readonly code: "EVENT_BATCH_PARTIAL";
+        readonly numericCode: 1504;
+        readonly message: "Some events failed to send";
+        readonly recoverable: true;
+    };
+    readonly CONFIG_INVALID_OPTION: {
+        readonly code: "CONFIG_INVALID_OPTION";
+        readonly numericCode: 1600;
+        readonly message: "Invalid configuration option";
+        readonly recoverable: false;
+    };
+    readonly CONFIG_MISSING_REQUIRED: {
+        readonly code: "CONFIG_MISSING_REQUIRED";
+        readonly numericCode: 1601;
+        readonly message: "Missing required configuration";
+        readonly recoverable: false;
+    };
+    readonly CONFIG_TYPE_ERROR: {
+        readonly code: "CONFIG_TYPE_ERROR";
+        readonly numericCode: 1602;
+        readonly message: "Configuration type mismatch";
+        readonly recoverable: false;
+    };
+    readonly CONFIG_DEPRECATED: {
+        readonly code: "CONFIG_DEPRECATED";
+        readonly numericCode: 1603;
+        readonly message: "Configuration option deprecated";
+        readonly recoverable: false;
+    };
+    readonly SECURITY_ERROR: {
+        readonly code: "SECURITY_ERROR";
+        readonly numericCode: 1700;
+        readonly message: "Security violation detected";
+        readonly recoverable: false;
+    };
+    readonly SECURITY_PII_DETECTED: {
+        readonly code: "SECURITY_PII_DETECTED";
+        readonly numericCode: 1701;
+        readonly message: "PII detected in data without privateAttributes";
+        readonly recoverable: false;
+    };
+    readonly SECURITY_LOCAL_PORT_IN_PRODUCTION: {
+        readonly code: "SECURITY_LOCAL_PORT_IN_PRODUCTION";
+        readonly numericCode: 1702;
+        readonly message: "localPort cannot be used in production";
+        readonly recoverable: false;
+    };
+    readonly SECURITY_KEY_ROTATION_FAILED: {
+        readonly code: "SECURITY_KEY_ROTATION_FAILED";
+        readonly numericCode: 1703;
+        readonly message: "Key rotation failed - both primary and secondary keys rejected";
+        readonly recoverable: false;
+    };
+    readonly SECURITY_BOOTSTRAP_VERIFICATION_FAILED: {
+        readonly code: "SECURITY_BOOTSTRAP_VERIFICATION_FAILED";
+        readonly numericCode: 1704;
+        readonly message: "Bootstrap data signature verification failed";
+        readonly recoverable: false;
+    };
+    readonly STREAMING_TOKEN_INVALID: {
+        readonly code: "STREAMING_TOKEN_INVALID";
+        readonly numericCode: 1800;
+        readonly message: "Stream token is invalid";
+        readonly recoverable: true;
+    };
+    readonly STREAMING_TOKEN_EXPIRED: {
+        readonly code: "STREAMING_TOKEN_EXPIRED";
+        readonly numericCode: 1801;
+        readonly message: "Stream token has expired";
+        readonly recoverable: true;
+    };
+    readonly STREAMING_SUBSCRIPTION_SUSPENDED: {
+        readonly code: "STREAMING_SUBSCRIPTION_SUSPENDED";
+        readonly numericCode: 1802;
+        readonly message: "Organization subscription suspended";
+        readonly recoverable: false;
+    };
+    readonly STREAMING_CONNECTION_LIMIT: {
+        readonly code: "STREAMING_CONNECTION_LIMIT";
+        readonly numericCode: 1803;
+        readonly message: "Too many concurrent streaming connections";
+        readonly recoverable: true;
+    };
+    readonly STREAMING_UNAVAILABLE: {
+        readonly code: "STREAMING_UNAVAILABLE";
+        readonly numericCode: 1804;
+        readonly message: "Streaming service not available";
+        readonly recoverable: true;
+    };
+    readonly INTERNAL_ERROR: {
+        readonly code: "INTERNAL_ERROR";
+        readonly numericCode: 1900;
+        readonly message: "Internal SDK error";
+        readonly recoverable: false;
+    };
+    readonly INTERNAL_STATE_ERROR: {
+        readonly code: "INTERNAL_STATE_ERROR";
+        readonly numericCode: 1901;
+        readonly message: "Invalid internal state";
+        readonly recoverable: false;
+    };
+    readonly UNKNOWN_ERROR: {
+        readonly code: "UNKNOWN_ERROR";
+        readonly numericCode: 1999;
+        readonly message: "Unknown error occurred";
+        readonly recoverable: false;
+    };
+};
+type ErrorCode = keyof typeof ErrorCodes;
+/**
+ * Check if an error code is retryable
+ */
+declare function isRetryableCode(code: ErrorCode): boolean;
+
+/**
+ * Error details for additional context
+ */
+interface ErrorDetails {
+    [key: string]: unknown;
+}
+/**
+ * Extended options for FlagKitError constructor
+ */
+interface FlagKitErrorOptions {
+    statusCode?: number;
+    details?: ErrorDetails;
+    retryAfter?: number;
+    requestId?: string;
+    cause?: Error;
+    /** Override sanitization for this specific error */
+    sanitization?: ErrorSanitizationOptions;
+}
+/**
+ * Base error class for all FlagKit SDK errors
+ */
+declare class FlagKitError extends Error {
+    /** Error code string (e.g., "NETWORK_TIMEOUT") */
+    readonly code: ErrorCode;
+    /** Numeric error code (e.g., 1301) */
+    readonly numericCode: number;
+    /** HTTP status code if applicable */
+    readonly statusCode?: number;
+    /** Additional error details */
+    readonly details?: ErrorDetails;
+    /** Whether the operation can be retried */
+    readonly recoverable: boolean;
+    /** Seconds to wait before retrying (from Retry-After header) */
+    readonly retryAfter?: number;
+    /** Server request ID for debugging */
+    readonly requestId?: string;
+    /** Timestamp when error occurred */
+    readonly timestamp: Date;
+    /** Original unsanitized message (only set when preserveOriginal is true) */
+    readonly originalMessage?: string;
+    constructor(code: ErrorCode, message?: string, options?: FlagKitErrorOptions);
+    /**
+     * Create a string representation of the error
+     */
+    toString(): string;
+    /**
+     * Convert error to JSON for logging/serialization
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Initialization error - SDK cannot start
+ */
+declare class InitializationError extends FlagKitError {
+    constructor(code: Extract<ErrorCode, 'INIT_FAILED' | 'INIT_TIMEOUT' | 'INIT_INVALID_CONFIG' | 'INIT_MISSING_API_KEY' | 'INIT_INVALID_BASE_URL' | 'INIT_ALREADY_INITIALIZED'>, message?: string, options?: {
+        details?: ErrorDetails;
+        cause?: Error;
+    });
+}
+/**
+ * Authentication error - API key issues
+ */
+declare class AuthenticationError extends FlagKitError {
+    constructor(code: Extract<ErrorCode, 'AUTH_INVALID_KEY' | 'AUTH_EXPIRED_KEY' | 'AUTH_REVOKED_KEY' | 'AUTH_INSUFFICIENT_PERMISSIONS' | 'AUTH_RATE_LIMITED' | 'AUTH_PROJECT_MISMATCH' | 'AUTH_ENVIRONMENT_MISMATCH'>, message?: string, options?: {
+        statusCode?: number;
+        details?: ErrorDetails;
+        retryAfter?: number;
+        requestId?: string;
+    });
+}
+/**
+ * Network error - connectivity issues
+ */
+declare class NetworkError extends FlagKitError {
+    constructor(code: Extract<ErrorCode, 'NETWORK_ERROR' | 'NETWORK_TIMEOUT' | 'NETWORK_DNS_ERROR' | 'NETWORK_CONNECTION_REFUSED' | 'NETWORK_SSL_ERROR' | 'NETWORK_OFFLINE' | 'NETWORK_SERVER_ERROR' | 'NETWORK_INVALID_RESPONSE'>, message?: string, options?: {
+        statusCode?: number;
+        details?: ErrorDetails;
+        retryAfter?: number;
+        requestId?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Evaluation error - flag evaluation issues
+ */
+declare class EvaluationError extends FlagKitError {
+    constructor(code: Extract<ErrorCode, 'EVAL_FLAG_NOT_FOUND' | 'EVAL_FLAG_DISABLED' | 'EVAL_TYPE_MISMATCH' | 'EVAL_INVALID_CONTEXT' | 'EVAL_RULE_ERROR' | 'EVAL_SEGMENT_ERROR' | 'EVAL_DEFAULT_USED' | 'EVAL_CACHED_VALUE' | 'EVAL_STALE_VALUE'>, message?: string, options?: {
+        details?: ErrorDetails;
+    });
+}
+/**
+ * Security error - security violations
+ */
+declare class SecurityError extends FlagKitError {
+    constructor(code: Extract<ErrorCode, 'SECURITY_ERROR' | 'SECURITY_PII_DETECTED' | 'SECURITY_LOCAL_PORT_IN_PRODUCTION' | 'SECURITY_KEY_ROTATION_FAILED' | 'SECURITY_BOOTSTRAP_VERIFICATION_FAILED'>, message?: string, options?: {
+        details?: ErrorDetails;
+    });
+}
+/**
+ * Create an error from an HTTP response
+ */
+declare function createErrorFromResponse(statusCode: number, body?: {
+    error?: string;
+    message?: string;
+    code?: string;
+    requestId?: string;
+}, retryAfter?: number): FlagKitError;
+/**
+ * Check if an error is a FlagKitError
+ */
+declare function isFlagKitError(error: unknown): error is FlagKitError;
+/**
+ * Check if an error is retryable
+ */
+declare function isRetryableError(error: unknown): boolean;
+
+/**
+ * Circuit breaker states
+ */
+declare enum CircuitState {
+    /** Normal operation - requests are allowed */
+    CLOSED = "CLOSED",
+    /** Circuit is open - requests are rejected */
+    OPEN = "OPEN",
+    /** Testing recovery - limited requests allowed */
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Circuit breaker configuration
+ */
+interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit. Default: 5 */
+    failureThreshold: number;
+    /** Time in ms before attempting recovery. Default: 30000 */
+    resetTimeout: number;
+    /** Number of successful requests in half-open to close circuit. Default: 1 */
+    successThreshold: number;
+}
+/**
+ * Error thrown when circuit is open
+ */
+declare class CircuitOpenError extends Error {
+    readonly timeUntilReset: number;
+    constructor(timeUntilReset: number);
+}
+/**
+ * Circuit breaker for protecting against cascading failures
+ *
+ * State transitions:
+ * - CLOSED -> OPEN: When failures >= failureThreshold
+ * - OPEN -> HALF_OPEN: After resetTimeout
+ * - HALF_OPEN -> CLOSED: After successThreshold successes
+ * - HALF_OPEN -> OPEN: On any failure
+ */
+declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private lastFailureTime;
+    private readonly config;
+    private readonly logger?;
+    constructor(config?: Partial<CircuitBreakerConfig>, logger?: Logger);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Execute an operation through the circuit breaker
+     */
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Record a success
+     */
+    onSuccess(): void;
+    /**
+     * Record a failure
+     */
+    onFailure(): void;
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Check if state should transition from OPEN to HALF_OPEN
+     */
+    private checkStateTransition;
+    /**
+     * Transition to a new state
+     */
+    private transitionTo;
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats(): {
+        state: CircuitState;
+        failures: number;
+        successes: number;
+        lastFailureTime: number;
+    };
+}
+
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts. Default: 3 */
+    maxAttempts: number;
+    /** Base delay in milliseconds. Default: 1000 */
+    baseDelay: number;
+    /** Maximum delay in milliseconds. Default: 30000 */
+    maxDelay: number;
+    /** Backoff multiplier. Default: 2 */
+    backoffMultiplier: number;
+    /** Maximum jitter in milliseconds. Default: 100 */
+    jitter: number;
+}
+/**
+ * Calculate backoff delay with exponential backoff and jitter
+ */
+declare function calculateBackoff(attempt: number, config: RetryConfig): number;
+/**
+ * Execute an operation with retry logic
+ */
+declare function withRetry<T>(operation: () => Promise<T>, config?: Partial<RetryConfig>, options?: {
+    logger?: Logger;
+    operationName?: string;
+    shouldRetry?: (error: unknown) => boolean;
+    onRetry?: (attempt: number, error: unknown, delay: number) => void;
+}): Promise<T>;
+/**
+ * Parse Retry-After header value
+ * Can be either a number of seconds or an HTTP date
+ */
+declare function parseRetryAfter(value: string | null): number | undefined;
+
+/**
+ * SDK version - should be updated with releases
+ */
+declare const SDK_VERSION = "1.0.0";
+/**
+ * HTTP request options
+ */
+interface RequestOptions {
+    /** HTTP method */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body (will be JSON serialized) */
+    body?: unknown;
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Skip retry logic */
+    skipRetry?: boolean;
+    /** Skip circuit breaker */
+    skipCircuitBreaker?: boolean;
+}
+/**
+ * HTTP response wrapper
+ */
+interface HttpResponse<T = unknown> {
+    /** Response status code */
+    status: number;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Parsed response body */
+    data: T;
+    /** Server request ID if available */
+    requestId?: string;
+    /** Usage metrics from response headers */
+    usageMetrics?: UsageMetrics;
+}
+/**
+ * Usage metrics extracted from response headers
+ */
+interface UsageMetrics {
+    /** Percentage of API call limit used this period (0-150+) */
+    apiUsagePercent?: number;
+    /** Percentage of evaluation limit used (0-150+) */
+    evaluationUsagePercent?: number;
+    /** Whether approaching rate limit threshold */
+    rateLimitWarning: boolean;
+    /** Current subscription status */
+    subscriptionStatus?: 'active' | 'trial' | 'past_due' | 'suspended' | 'cancelled';
+}
+/**
+ * Usage update callback type
+ */
+type UsageUpdateCallback = (metrics: UsageMetrics) => void;
+/**
+ * HTTP client configuration
+ */
+interface HttpClientConfig {
+    /** Base URL for all requests */
+    baseUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Secondary API key for key rotation */
+    secondaryApiKey?: string;
+    /** Grace period for key rotation in ms. Default: 300000 (5 minutes) */
+    keyRotationGracePeriod?: number;
+    /** Default request timeout in ms */
+    timeout: number;
+    /** Retry configuration */
+    retry: Partial<RetryConfig>;
+    /** Circuit breaker configuration */
+    circuitBreaker: Partial<CircuitBreakerConfig>;
+    /** Logger instance */
+    logger?: Logger;
+    /** Enable request signing for POST requests. Default: true */
+    enableRequestSigning?: boolean;
+    /** Callback for usage metrics updates */
+    onUsageUpdate?: UsageUpdateCallback;
+}
+/**
+ * HTTP client for FlagKit API communication
+ *
+ * Features:
+ * - Automatic retry with exponential backoff
+ * - Circuit breaker for failure protection
+ * - Request timeout handling
+ * - Rate limit header parsing
+ * - HMAC-SHA256 request signing for POST requests
+ * - Signed beacon payloads for page unload events
+ * - Key rotation support with automatic failover
+ */
+declare class HttpClient {
+    private readonly config;
+    private readonly circuitBreaker;
+    private readonly logger?;
+    private currentApiKey;
+    private keyRotationTimestamp;
+    constructor(config: HttpClientConfig);
+    /**
+     * Get the current active API key
+     */
+    getActiveApiKey(): string;
+    /**
+     * Get the key identifier (first 8 chars) for the current key
+     */
+    getKeyId(): string;
+    /**
+     * Check if key rotation is currently active
+     */
+    isInKeyRotation(): boolean;
+    /**
+     * Rotate to secondary API key
+     */
+    private rotateToSecondaryKey;
+    /**
+     * Handle key rotation on authentication failure
+     * Returns true if rotation was performed and request should be retried
+     */
+    private handleAuthFailure;
+    /**
+     * Make a GET request
+     */
+    get<T>(path: string, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<HttpResponse<T>>;
+    /**
+     * Make a POST request with automatic signing
+     */
+    post<T>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method'>): Promise<HttpResponse<T>>;
+    /**
+     * Make an HTTP request
+     */
+    request<T>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Execute a single HTTP request
+     */
+    private executeRequest;
+    /**
+     * Build full URL from path
+     */
+    private buildUrl;
+    /**
+     * Build request headers
+     */
+    private buildHeaders;
+    /**
+     * Extract usage metrics from response headers
+     */
+    private extractUsageMetrics;
+    /**
+     * Send events using beacon API (for page unload)
+     * Only available in browser environments
+     *
+     * VULN-025: Uses HMAC-SHA256 signed payload for beacon authentication.
+     * Beacon requests cannot include Authorization headers, so authentication
+     * is done via payload-based HMAC signatures.
+     *
+     * Payload format:
+     * {
+     *   data: object,          // Event data
+     *   signature: string,     // HMAC-SHA256 signature of data
+     *   timestamp: number,     // Unix timestamp in milliseconds
+     *   apiKeyId: string       // Last 8 characters of API key
+     * }
+     *
+     * Note: This method uses a pre-computed signature approach since
+     * sendBeacon must complete synchronously. For better security,
+     * use sendSignedBeacon when you have time (e.g., visibilitychange).
+     */
+    sendBeacon(path: string, data: unknown): boolean;
+    /**
+     * Send events using beacon API with HMAC-SHA256 signing
+     * This is the preferred method when you have time before page unload
+     * (e.g., during visibilitychange event)
+     *
+     * VULN-025: Computes full HMAC-SHA256 signature for authenticated beacons.
+     */
+    sendSignedBeacon(path: string, data: unknown): Promise<boolean>;
+    /**
+     * Get circuit breaker state
+     */
+    getCircuitState(): CircuitState;
+    /**
+     * Reset circuit breaker
+     */
+    resetCircuit(): void;
+}
+
+/**
+ * Bootstrap configuration with optional signature verification
+ */
+interface BootstrapConfig {
+    /** Flag values for offline/fallback */
+    flags: Record<string, unknown>;
+    /** HMAC-SHA256 signature of canonical flags JSON */
+    signature?: string;
+    /** Unix timestamp in milliseconds when bootstrap was generated */
+    timestamp?: number;
+}
+/**
+ * Options for bootstrap signature verification
+ */
+interface BootstrapVerificationOptions {
+    /** Enable signature verification. Default: true (verify if signature present) */
+    enabled?: boolean;
+    /** Maximum age in milliseconds. Default: 86400000 (24 hours) */
+    maxAge?: number;
+    /** Behavior on verification failure. Default: 'warn' */
+    onFailure?: 'warn' | 'error' | 'ignore';
+}
+/**
+ * Bootstrap data - supports both legacy format (Record) and new format (BootstrapConfig)
+ */
+type BootstrapData = BootstrapConfig | Record<string, unknown>;
+/**
+ * Options for error message sanitization to prevent sensitive data leakage
+ */
+interface ErrorSanitizationOptions {
+    /** Enable error message sanitization. Default: true */
+    enabled?: boolean;
+    /** Preserve original message (for debugging). Default: false (true in debug mode) */
+    preserveOriginal?: boolean;
+}
+/**
+ * Configuration options for initializing the FlagKit SDK
+ */
+interface FlagKitOptions {
+    /** Required: API key for authentication */
+    apiKey: string;
+    /** Polling interval in milliseconds. Default: 30000 */
+    pollingInterval?: number;
+    /** Enable background polling for flag updates. Default: true */
+    enablePolling?: boolean;
+    /** Enable in-memory caching. Default: true */
+    cacheEnabled?: boolean;
+    /** Cache TTL in milliseconds. Default: 300000 (5 minutes) */
+    cacheTTL?: number;
+    /** Enable offline mode. Default: false */
+    offline?: boolean;
+    /** Request timeout in milliseconds. Default: 5000 */
+    timeout?: number;
+    /** Number of retry attempts. Default: 3 */
+    retries?: number;
+    /** Custom logger implementation */
+    logger?: Logger;
+    /** Bootstrap flag values for offline/fallback */
+    bootstrap?: BootstrapData;
+    /** Options for bootstrap signature verification */
+    bootstrapVerification?: BootstrapVerificationOptions;
+    /** Persist cache to storage. Default: false */
+    persistCache?: boolean;
+    /** Storage key for persisted cache. Default: 'flagkit_cache' */
+    cacheStorageKey?: string;
+    /** Called when SDK is initialized and ready */
+    onReady?: () => void;
+    /** Called when an error occurs */
+    onError?: (error: FlagKitError) => void;
+    /** Called when flags are updated */
+    onUpdate?: (flags: FlagState[]) => void;
+    /**
+     * Called when usage metrics are received from API responses.
+     * Provides visibility into API usage, rate limits, and subscription status.
+     */
+    onUsageUpdate?: (metrics: UsageMetrics) => void;
+    /** Enable debug logging. Default: false */
+    debug?: boolean;
+    /** Local development port. When set, uses http://localhost:{port}/api/v1 */
+    localPort?: number;
+    /**
+     * Secondary API key for key rotation support.
+     * On 401 errors, SDK will automatically retry with this key.
+     */
+    secondaryApiKey?: string;
+    /**
+     * Grace period in milliseconds during key rotation.
+     * Default: 300000 (5 minutes)
+     */
+    keyRotationGracePeriod?: number;
+    /**
+     * Strict PII mode - throws SecurityError instead of warning when PII detected
+     * without privateAttributes. Default: false
+     */
+    strictPIIMode?: boolean;
+    /**
+     * Evaluation jitter configuration for cache timing attack protection.
+     * Adds a random delay at the start of flag evaluation to prevent
+     * attackers from inferring flag values based on response timing.
+     */
+    evaluationJitter?: {
+        /** Enable evaluation jitter. Default: false */
+        enabled?: boolean;
+        /** Minimum jitter delay in milliseconds. Default: 5 */
+        minMs?: number;
+        /** Maximum jitter delay in milliseconds. Default: 15 */
+        maxMs?: number;
+    };
+    /**
+     * Error message sanitization options to prevent sensitive data leakage.
+     * Removes paths, IPs, API keys, emails, and connection strings from error messages.
+     */
+    errorSanitization?: ErrorSanitizationOptions;
+    /**
+     * Real-time streaming configuration for SSE-based flag updates.
+     * When enabled, provides near-instant flag updates (~200ms) instead of polling (~30s).
+     */
+    streaming?: {
+        /** Enable SSE streaming for real-time updates. Default: true */
+        enabled?: boolean;
+        /** Reconnection interval in ms after connection failure. Default: 3000 */
+        reconnectInterval?: number;
+        /** Maximum reconnection attempts before falling back to polling. Default: 3 */
+        maxReconnectAttempts?: number;
+        /** Expected heartbeat interval in ms. Default: 30000 */
+        heartbeatInterval?: number;
+    };
+}
+/**
+ * Resolved configuration with all defaults applied
+ */
+interface ResolvedConfig {
+    apiKey: string;
+    pollingInterval: number;
+    enablePolling: boolean;
+    cacheEnabled: boolean;
+    cacheTTL: number;
+    offline: boolean;
+    timeout: number;
+    retries: number;
+    logger: Logger;
+    bootstrap: BootstrapData;
+    bootstrapVerification: Required<BootstrapVerificationOptions>;
+    persistCache: boolean;
+    cacheStorageKey: string;
+    onReady?: () => void;
+    onError?: (error: FlagKitError) => void;
+    onUpdate?: (flags: FlagState[]) => void;
+    onUsageUpdate?: (metrics: UsageMetrics) => void;
+    debug: boolean;
+    localPort?: number;
+    secondaryApiKey?: string;
+    keyRotationGracePeriod: number;
+    strictPIIMode: boolean;
+    evaluationJitter: {
+        enabled: boolean;
+        minMs: number;
+        maxMs: number;
+    };
+    errorSanitization: Required<ErrorSanitizationOptions>;
+    streaming: {
+        enabled: boolean;
+        reconnectInterval: number;
+        maxReconnectAttempts: number;
+        heartbeatInterval: number;
+    };
+}
+
+/**
+ * Evaluation context containing user and environment attributes
+ * Used for targeting rules and personalization
+ */
+interface EvaluationContext {
+    /** Unique user identifier */
+    userId?: string;
+    /** Alternative user key (e.g., email hash) */
+    userKey?: string;
+    /** User email address */
+    email?: string;
+    /** User display name */
+    name?: string;
+    /** Whether the user is anonymous */
+    anonymous?: boolean;
+    /** ISO country code (e.g., "US", "GB") */
+    country?: string;
+    /** User IP address */
+    ip?: string;
+    /** Browser/device user agent string */
+    userAgent?: string;
+    /** Custom attributes for targeting */
+    custom?: Record<string, unknown>;
+    /** List of attribute names that should not be sent to the server */
+    privateAttributes?: string[];
+}
+/**
+ * Context with all attributes resolved for sending to API
+ */
+interface ResolvedContext {
+    userId?: string;
+    userKey?: string;
+    email?: string;
+    name?: string;
+    anonymous?: boolean;
+    country?: string;
+    ip?: string;
+    userAgent?: string;
+    custom?: Record<string, unknown>;
+}
+
+/**
+ * FlagKit SDK Client
+ *
+ * Main interface for feature flag evaluation and event tracking.
+ */
+declare class FlagKitClient {
+    private readonly config;
+    private readonly cache;
+    private readonly contextManager;
+    private readonly httpClient;
+    private readonly eventQueue;
+    private readonly logger;
+    private readonly sessionId;
+    private pollingManager;
+    private streamingManager;
+    private readyPromise;
+    private isReadyFlag;
+    private isClosedFlag;
+    private lastUpdateTime;
+    private isStreamingActive;
+    constructor(options: FlagKitOptions);
+    /**
+     * Initialize the SDK by fetching flag configurations
+     */
+    initialize(): Promise<void>;
+    private doInitialize;
+    /**
+     * Check if SDK is ready
+     */
+    isReady(): boolean;
+    /**
+     * Wait for SDK to be ready
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Evaluate a boolean flag
+     */
+    getBooleanValue(key: string, defaultValue: boolean, context?: EvaluationContext): Promise<boolean>;
+    /**
+     * Evaluate a string flag
+     */
+    getStringValue(key: string, defaultValue: string, context?: EvaluationContext): Promise<string>;
+    /**
+     * Evaluate a number flag
+     */
+    getNumberValue(key: string, defaultValue: number, context?: EvaluationContext): Promise<number>;
+    /**
+     * Evaluate a JSON flag
+     */
+    getJsonValue<T extends Record<string, unknown>>(key: string, defaultValue: T, context?: EvaluationContext): Promise<T>;
+    /**
+     * Evaluate a flag and return full result details
+     */
+    evaluate(key: string, context?: EvaluationContext): Promise<EvaluationResult>;
+    /**
+     * Synchronously get a boolean flag value from cache
+     * Returns the default value if not cached
+     */
+    getBooleanValueSync(key: string, defaultValue: boolean): boolean;
+    /**
+     * Synchronously get a string flag value from cache
+     * Returns the default value if not cached
+     */
+    getStringValueSync(key: string, defaultValue: string): string;
+    /**
+     * Synchronously get a number flag value from cache
+     * Returns the default value if not cached
+     */
+    getNumberValueSync(key: string, defaultValue: number): number;
+    /**
+     * Synchronously get a JSON flag value from cache
+     * Returns the default value if not cached
+     */
+    getJsonValueSync<T extends Record<string, unknown>>(key: string, defaultValue: T): T;
+    /**
+     * Synchronously evaluate a flag from cache and return full result details
+     * Returns a default result if not cached
+     */
+    evaluateSync(key: string, defaultValue?: FlagValue): EvaluationResult;
+    /**
+     * Evaluate all flags
+     */
+    evaluateAll(context?: EvaluationContext): Promise<Record<string, EvaluationResult>>;
+    /**
+     * Get bootstrap flags (handles both legacy and new format)
+     */
+    private getBootstrapFlags;
+    /**
+     * Check if a flag exists
+     */
+    hasFlag(key: string): boolean;
+    /**
+     * Get all flag keys
+     */
+    getAllFlagKeys(): string[];
+    /**
+     * Set global evaluation context
+     * @throws {SecurityError} If strictPIIMode is enabled and PII is detected without privateAttributes
+     */
+    setContext(context: EvaluationContext): void;
+    /**
+     * Get current global context
+     */
+    getContext(): EvaluationContext | null;
+    /**
+     * Clear global context
+     */
+    clearContext(): void;
+    /**
+     * Identify a user
+     * @throws {SecurityError} If strictPIIMode is enabled and PII is detected without privateAttributes
+     */
+    identify(userId: string, attributes?: Partial<EvaluationContext>): void;
+    /**
+     * Reset to anonymous user
+     */
+    reset(): void;
+    /**
+     * Track a custom event
+     * @throws {SecurityError} If strictPIIMode is enabled and PII is detected in event data
+     */
+    track(eventType: string, eventData?: Record<string, unknown>): void;
+    /**
+     * Flush pending events
+     */
+    flush(): Promise<void>;
+    /**
+     * Force refresh flags from server
+     */
+    refresh(): Promise<void>;
+    /**
+     * Close the SDK and cleanup resources
+     */
+    close(): Promise<void>;
+    /**
+     * Synchronous flag evaluation from cache only
+     * Used by React hooks for immediate value access
+     */
+    private evaluateFlagSync;
+    /**
+     * Internal flag evaluation logic
+     */
+    private evaluateFlag;
+    /**
+     * Check if bootstrap data is in the new BootstrapConfig format
+     */
+    private isBootstrapConfig;
+    /**
+     * Apply bootstrap values to cache
+     */
+    private applyBootstrap;
+    /**
+     * Apply bootstrap values to cache with async verification
+     */
+    private applyBootstrapAsync;
+    /**
+     * Infer flag type from value
+     */
+    private inferFlagType;
+    /**
+     * Start background polling
+     */
+    private startPolling;
+    /**
+     * Start SSE streaming for real-time flag updates
+     */
+    private startStreaming;
+    /**
+     * Handle flag update from streaming
+     */
+    private handleStreamFlagUpdate;
+    /**
+     * Handle flag deletion from streaming
+     */
+    private handleStreamFlagDelete;
+    /**
+     * Handle flags reset from streaming
+     */
+    private handleStreamFlagsReset;
+    /**
+     * Handle streaming fallback to polling
+     */
+    private handleStreamingFallback;
+    /**
+     * Check if streaming is currently active
+     */
+    isStreaming(): boolean;
+    /**
+     * Check SDK version metadata from init response and emit appropriate warnings.
+     *
+     * Per spec, the SDK should parse and surface:
+     * - sdkVersionMin: Minimum required version (older may not work)
+     * - sdkVersionRecommended: Recommended version for optimal experience
+     * - sdkVersionLatest: Latest available version
+     * - deprecationWarning: Server-provided deprecation message
+     */
+    private checkVersionMetadata;
+}
+
+/**
+ * FlagKit SDK static factory
+ *
+ * Provides a singleton interface for SDK initialization and access.
+ */
+declare class FlagKit {
+    private static instance;
+    private static initPromise;
+    /**
+     * Initialize the FlagKit SDK
+     *
+     * @param options SDK configuration options
+     * @returns Promise resolving to the FlagKit client
+     *
+     * @example
+     * ```typescript
+     * const client = await FlagKit.initialize({
+     *   apiKey: 'sdk_your_api_key',
+     *   onReady: () => console.log('FlagKit ready!'),
+     * });
+     *
+     * const darkMode = client.getBooleanValue('dark-mode', false);
+     * ```
+     */
+    static initialize(options: FlagKitOptions): Promise<FlagKitClient>;
+    /**
+     * Get the current FlagKit client instance
+     *
+     * @throws Error if SDK is not initialized
+     */
+    static getInstance(): FlagKitClient;
+    /**
+     * Check if SDK is initialized
+     */
+    static isInitialized(): boolean;
+    /**
+     * Reset the SDK (for testing or reinitialization)
+     */
+    static reset(): Promise<void>;
+    /**
+     * Internal initialization logic
+     */
+    private static doInitialize;
+}
+
+/**
+ * Base event structure for all FlagKit events
+ */
+interface BaseEvent {
+    /** Event type identifier */
+    eventType: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** SDK version */
+    sdkVersion: string;
+    /** SDK language identifier */
+    sdkLanguage: string;
+    /** Session identifier */
+    sessionId: string;
+    /** Environment UUID */
+    environmentId: string;
+    /** User identifier */
+    userId?: string;
+    /** Alternative user key */
+    userKey?: string;
+    /** Whether the user is anonymous */
+    anonymous?: boolean;
+    /** Custom event data */
+    eventData?: Record<string, unknown>;
+    /** Event metadata */
+    metadata?: EventMetadata;
+}
+/**
+ * Optional metadata for events
+ */
+interface EventMetadata {
+    /** Event source (sdk, api, webhook) */
+    source?: string;
+    /** Platform (web, ios, android, server) */
+    platform?: string;
+    /** Device identifier */
+    deviceId?: string;
+    /** Application version */
+    appVersion?: string;
+    /** User locale (e.g., en-US) */
+    locale?: string;
+    /** User timezone */
+    timezone?: string;
+}
+/**
+ * Flag evaluation event (automatic, opt-in)
+ */
+interface FlagEvaluatedEvent extends BaseEvent {
+    eventType: 'flag.evaluated';
+    eventData: {
+        flagKey: string;
+        value: unknown;
+        defaultValue: unknown;
+        reason: EvaluationReason;
+        variationId?: string;
+        ruleId?: string;
+        segmentId?: string;
+        version: number;
+        evaluationTimeMs: number;
+        fromCache: boolean;
+    };
+}
+/**
+ * Custom event tracked by user code
+ */
+interface CustomEvent extends BaseEvent {
+    eventType: string;
+    eventData: Record<string, unknown>;
+}
+/**
+ * SDK system event types
+ */
+type SystemEventType = 'sdk.initialized' | 'sdk.ready' | 'sdk.error' | 'flag.evaluated' | 'context.identified' | 'context.reset';
+/**
+ * Event queue configuration
+ */
+interface EventQueueConfig {
+    /** Maximum events to queue. Default: 100 */
+    maxQueueSize: number;
+    /** Batch size for sending. Default: 10 */
+    batchSize: number;
+    /** Flush interval in ms. Default: 30000 */
+    flushInterval: number;
+    /** Maximum retry attempts. Default: 3 */
+    maxRetries: number;
+    /** Base retry delay in ms. Default: 1000 */
+    retryDelay: number;
+    /** Retry backoff multiplier. Default: 2 */
+    retryBackoff: number;
+    /** Persist queue to storage. Default: false */
+    persistQueue: boolean;
+    /** Storage key for persistence. Default: 'flagkit_events' */
+    storageKey: string;
+    /** Enabled event types. Default: ['*'] (all) */
+    enabledEventTypes: string[];
+    /** Disabled event types. Default: [] */
+    disabledEventTypes: string[];
+    /** Event sampling rate (0.0 - 1.0). Default: 1.0 */
+    sampleRate: number;
+}
+/**
+ * API response for batch events
+ */
+interface BatchEventsResponse {
+    success: boolean;
+    message: string;
+    recorded: number;
+    errors: number;
+}
+
+/**
+ * Security utilities for FlagKit SDK
+ */
+
+/**
+ * Check if a field name potentially contains PII
+ */
+declare function isPotentialPIIField(fieldName: string): boolean;
+/**
+ * Detect potential PII in an object and return the field names
+ */
+declare function detectPotentialPII(data: Record<string, unknown>, prefix?: string): string[];
+/**
+ * PII detection result
+ */
+interface PIIDetectionResult {
+    hasPII: boolean;
+    fields: string[];
+    message: string;
+}
+/**
+ * Check for potential PII in data and return detailed result
+ */
+declare function checkForPotentialPII(data: Record<string, unknown> | undefined, dataType: 'context' | 'event'): PIIDetectionResult;
+/**
+ * Warn about potential PII in data
+ */
+declare function warnIfPotentialPII(data: Record<string, unknown> | undefined, dataType: 'context' | 'event', logger?: Logger): void;
+/**
+ * Check if an API key is a server key
+ */
+declare function isServerKey(apiKey: string): boolean;
+/**
+ * Check if an API key is a client/SDK key
+ */
+declare function isClientKey(apiKey: string): boolean;
+/**
+ * Warn if server key is used in browser environment
+ */
+declare function warnIfServerKeyInBrowser(apiKey: string, logger?: Logger): void;
+/**
+ * Security configuration options
+ */
+interface SecurityConfig {
+    /** Warn about potential PII in context/events. Default: true in development */
+    warnOnPotentialPII?: boolean;
+    /** Warn when server keys are used in browser. Default: true */
+    warnOnServerKeyInBrowser?: boolean;
+    /** Custom PII patterns to detect */
+    additionalPIIPatterns?: string[];
+}
+/**
+ * Default security configuration
+ */
+declare const DEFAULT_SECURITY_CONFIG: Required<SecurityConfig>;
+/**
+ * Signed payload structure for beacon requests
+ */
+interface SignedPayload<T = unknown> {
+    data: T;
+    signature: string;
+    timestamp: number;
+    keyId: string;
+}
+/**
+ * Get the first 8 characters of an API key for identification
+ * This is safe to expose as it doesn't reveal the full key
+ */
+declare function getKeyId(apiKey: string): string;
+/**
+ * Generate HMAC-SHA256 signature
+ * Uses Web Crypto API in browser, Node.js crypto in server
+ */
+declare function generateHMACSHA256(message: string, key: string): Promise<string>;
+/**
+ * Sign a payload with HMAC-SHA256
+ */
+declare function signPayload<T>(data: T, apiKey: string, timestamp?: number): Promise<SignedPayload<T>>;
+/**
+ * Create signature string for request headers
+ * Format: timestamp.signature
+ */
+declare function createRequestSignature(body: string, apiKey: string, timestamp?: number): Promise<{
+    signature: string;
+    timestamp: number;
+}>;
+/**
+ * Verify a signed payload (for testing/debugging)
+ */
+declare function verifySignedPayload<T>(signedPayload: SignedPayload<T>, apiKey: string, maxAgeMs?: number): Promise<boolean>;
+/**
+ * Check if environment is production
+ */
+declare function isProductionEnvironment(): boolean;
+
+/**
+ * Storage interface for cache persistence
+ */
+interface Storage {
+    /**
+     * Get an item from storage
+     * @param key The storage key
+     * @returns The stored value or null if not found
+     */
+    get(key: string): string | null;
+    /**
+     * Set an item in storage
+     * @param key The storage key
+     * @param value The value to store
+     */
+    set(key: string, value: string): void;
+    /**
+     * Remove an item from storage
+     * @param key The storage key
+     */
+    remove(key: string): void;
+    /**
+     * Clear all items from storage
+     */
+    clear(): void;
+    /**
+     * Check if storage is available
+     */
+    isAvailable(): boolean;
+}
+
+/**
+ * Browser localStorage adapter
+ */
+declare class LocalStorage implements Storage {
+    private readonly prefix;
+    private available;
+    constructor(prefix?: string);
+    /**
+     * Get an item from localStorage
+     */
+    get(key: string): string | null;
+    /**
+     * Set an item in localStorage
+     */
+    set(key: string, value: string): void;
+    /**
+     * Remove an item from localStorage
+     */
+    remove(key: string): void;
+    /**
+     * Clear all FlagKit items from localStorage
+     */
+    clear(): void;
+    /**
+     * Check if localStorage is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Add prefix to key
+     */
+    private prefixKey;
+}
+
+/**
+ * In-memory storage adapter
+ * Used as fallback when localStorage is not available
+ */
+declare class MemoryStorage implements Storage {
+    private readonly store;
+    /**
+     * Get an item from memory
+     */
+    get(key: string): string | null;
+    /**
+     * Set an item in memory
+     */
+    set(key: string, value: string): void;
+    /**
+     * Remove an item from memory
+     */
+    remove(key: string): void;
+    /**
+     * Clear all items from memory
+     */
+    clear(): void;
+    /**
+     * Memory storage is always available
+     */
+    isAvailable(): boolean;
+}
+
+/**
+ * Encrypted storage wrapper using AES-256-GCM
+ *
+ * Wraps another storage implementation and encrypts/decrypts data automatically.
+ * Uses Web Crypto API in browser and Node.js crypto in server environments.
+ */
+
+/**
+ * Configuration for encrypted storage
+ */
+interface EncryptedStorageConfig {
+    /** The underlying storage to wrap */
+    storage: Storage;
+    /** API key used to derive encryption key */
+    apiKey: string;
+    /** Optional logger for debugging */
+    logger?: Logger;
+}
+/**
+ * Encrypted storage wrapper
+ *
+ * Provides transparent encryption for cached data using AES-256-GCM.
+ * Falls back to unencrypted storage if encryption is unavailable.
+ */
+declare class EncryptedStorage implements Storage {
+    private readonly storage;
+    private readonly apiKey;
+    private readonly logger?;
+    private derivedKey;
+    private keyDerivationPromise;
+    private cryptoAvailable;
+    constructor(config: EncryptedStorageConfig);
+    /**
+     * Check if crypto is available
+     */
+    private isCryptoAvailable;
+    /**
+     * Derive encryption key from API key
+     */
+    private deriveKey;
+    /**
+     * Derive key using Web Crypto API
+     */
+    private deriveKeyWebCrypto;
+    /**
+     * Derive key using Node.js crypto
+     */
+    private deriveKeyNode;
+    /**
+     * Wait for key derivation to complete
+     */
+    private ensureKeyReady;
+    /**
+     * Encrypt data using AES-256-GCM
+     */
+    private encrypt;
+    /**
+     * Encrypt using Web Crypto API
+     */
+    private encryptWebCrypto;
+    /**
+     * Encrypt using Node.js crypto
+     */
+    private encryptNode;
+    /**
+     * Decrypt data using AES-256-GCM
+     */
+    private decrypt;
+    /**
+     * Decrypt using Web Crypto API
+     */
+    private decryptWebCrypto;
+    /**
+     * Decrypt using Node.js crypto
+     */
+    private decryptNode;
+    /**
+     * Convert Uint8Array to Base64
+     */
+    private arrayToBase64;
+    /**
+     * Convert Base64 to Uint8Array
+     */
+    private base64ToArray;
+    /**
+     * Get an item from storage (decrypted)
+     */
+    get(key: string): string | null;
+    /**
+     * Check if data looks like encrypted format
+     */
+    private isEncryptedFormat;
+    /**
+     * Get an item from storage (async, with decryption)
+     */
+    getAsync(key: string): Promise<string | null>;
+    /**
+     * Set an item in storage (encrypted)
+     */
+    set(key: string, value: string): void;
+    /**
+     * Set an item in storage (async, with encryption)
+     */
+    setAsync(key: string, value: string): Promise<void>;
+    /**
+     * Remove an item from storage
+     */
+    remove(key: string): void;
+    /**
+     * Clear all items from storage
+     */
+    clear(): void;
+    /**
+     * Check if storage is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Check if encryption is available
+     */
+    isEncryptionAvailable(): boolean;
+}
+
+/**
+ * Stream event types from server
+ */
+type StreamEventType = 'flag_updated' | 'flag_deleted' | 'flags_reset' | 'heartbeat' | 'error';
+interface StreamEvent {
+    type: StreamEventType;
+    data: FlagState | {
+        key: string;
+    } | FlagState[] | {
+        timestamp: string;
+    } | StreamErrorData;
+}
+/**
+ * SSE error event data structure
+ */
+interface StreamErrorData {
+    code: StreamErrorCode;
+    message: string;
+}
+/**
+ * SSE error codes from server
+ */
+type StreamErrorCode = 'TOKEN_INVALID' | 'TOKEN_EXPIRED' | 'SUBSCRIPTION_SUSPENDED' | 'CONNECTION_LIMIT' | 'STREAMING_UNAVAILABLE';
+/**
+ * Response from the stream token endpoint
+ */
+interface StreamTokenResponse {
+    /** Short-lived token for SSE connection */
+    token: string;
+    /** Token expiry time in seconds */
+    expiresIn: number;
+}
+/**
+ * Streaming configuration
+ */
+interface StreamingConfig {
+    /** Base URL for API endpoints */
+    baseUrl: string;
+    /** Reconnection interval in ms. Default: 3000 */
+    reconnectInterval: number;
+    /** Maximum reconnection attempts before fallback. Default: 3 */
+    maxReconnectAttempts: number;
+    /** Expected heartbeat interval in ms. Default: 30000 */
+    heartbeatInterval: number;
+    /** API key for authentication (used to fetch stream token) */
+    apiKey: string;
+    /** Callback when flag is updated */
+    onFlagUpdate: (flag: FlagState) => void;
+    /** Callback when flag is deleted */
+    onFlagDelete: (key: string) => void;
+    /** Callback when all flags are reset */
+    onFlagsReset: (flags: FlagState[]) => void;
+    /** Callback when streaming fails and falls back to polling */
+    onFallbackToPolling: () => void;
+    /** Callback when subscription error occurs (e.g., suspended) */
+    onSubscriptionError?: (message: string) => void;
+    /** Callback when connection limit is reached */
+    onConnectionLimitError?: () => void;
+    /** Logger instance */
+    logger?: Logger;
+}
+/**
+ * Connection states for streaming
+ */
+type StreamingState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed';
+/**
+ * Manages Server-Sent Events (SSE) connection for real-time flag updates
+ *
+ * Security: Uses token exchange pattern to avoid exposing API keys in URLs.
+ * 1. Fetches short-lived token via POST with API key in header
+ * 2. Connects to SSE endpoint with disposable token in URL
+ *
+ * Features:
+ * - Secure token-based authentication
+ * - Automatic token refresh before expiry
+ * - Automatic reconnection with exponential backoff
+ * - Graceful degradation to polling after max failures
+ * - Heartbeat monitoring for connection health
+ * - Event parsing and dispatch
+ */
+declare class StreamingManager {
+    private readonly config;
+    private readonly logger?;
+    private eventSource;
+    private state;
+    private consecutiveFailures;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private tokenRefreshTimer;
+    private lastHeartbeat;
+    private retryStreamingTimer;
+    constructor(config: Partial<StreamingConfig> & Pick<StreamingConfig, 'baseUrl' | 'apiKey' | 'onFlagUpdate' | 'onFlagDelete' | 'onFlagsReset' | 'onFallbackToPolling'>);
+    /**
+     * Get current connection state
+     */
+    getState(): StreamingState;
+    /**
+     * Check if streaming is active
+     */
+    isConnected(): boolean;
+    /**
+     * Start streaming connection
+     */
+    connect(): void;
+    /**
+     * Stop streaming connection
+     */
+    disconnect(): void;
+    /**
+     * Retry streaming connection (called periodically after fallback to polling)
+     */
+    retryConnection(): void;
+    /**
+     * Initiate connection by first fetching a stream token
+     */
+    private initiateConnection;
+    /**
+     * Fetch a short-lived stream token from the API
+     * Token is fetched via POST with API key in header (secure)
+     */
+    private fetchStreamToken;
+    /**
+     * Schedule token refresh before expiry
+     */
+    private scheduleTokenRefresh;
+    /**
+     * Clear token refresh timer
+     */
+    private clearTokenRefreshTimer;
+    /**
+     * Create SSE connection with token
+     */
+    private createConnection;
+    /**
+     * Handle successful connection
+     */
+    private handleOpen;
+    /**
+     * Handle generic message (fallback for unnamed events)
+     */
+    private handleMessage;
+    /**
+     * Handle flag_updated event
+     */
+    private handleFlagUpdated;
+    /**
+     * Handle flag_deleted event
+     */
+    private handleFlagDeleted;
+    /**
+     * Handle flags_reset event
+     */
+    private handleFlagsReset;
+    /**
+     * Handle heartbeat event
+     */
+    private handleHeartbeat;
+    /**
+     * Handle SSE error event from server
+     * These are application-level errors sent as SSE events, not connection errors
+     *
+     * Error codes:
+     * - TOKEN_INVALID: Re-authenticate completely
+     * - TOKEN_EXPIRED: Refresh token and reconnect
+     * - SUBSCRIPTION_SUSPENDED: Notify user, fall back to cached values
+     * - CONNECTION_LIMIT: Implement backoff or close other connections
+     * - STREAMING_UNAVAILABLE: Fall back to polling
+     */
+    private handleStreamError;
+    /**
+     * Dispatch parsed event to appropriate handler
+     */
+    private dispatchEvent;
+    /**
+     * Handle connection error
+     */
+    private handleError;
+    /**
+     * Handle connection failure
+     */
+    private handleConnectionFailure;
+    /**
+     * Schedule reconnection attempt
+     */
+    private scheduleReconnect;
+    /**
+     * Get reconnection delay with exponential backoff
+     */
+    private getReconnectDelay;
+    /**
+     * Schedule retry of streaming after fallback to polling
+     */
+    private scheduleStreamingRetry;
+    /**
+     * Start heartbeat monitoring
+     */
+    private startHeartbeatMonitor;
+    /**
+     * Stop heartbeat monitoring
+     */
+    private stopHeartbeatMonitor;
+    /**
+     * Set connection state
+     */
+    private setState;
+    /**
+     * Cleanup resources
+     */
+    private cleanup;
+}
+
+export { AuthenticationError, type BaseEvent, type BatchEvaluateResponse, type BatchEventsResponse, CircuitBreaker, type CircuitBreakerConfig, CircuitOpenError, CircuitState, ConsoleLogger, type CustomEvent, DEFAULT_SECURITY_CONFIG, EncryptedStorage, type EncryptedStorageConfig, type ErrorCode, ErrorCodes, type EvaluateResponse, type EvaluationContext, EvaluationError, type EvaluationReason, type EvaluationResult, type EventMetadata, type EventQueueConfig, type FlagEvaluatedEvent, FlagKit, FlagKitClient, FlagKitError, type FlagKitOptions, type FlagState, type FlagType, type FlagValue, HttpClient, type HttpResponse, type InitResponse, InitializationError, LocalStorage, type LogEntry, type LogLevel, type Logger, MemoryStorage, NetworkError, NoopLogger, type PIIDetectionResult, type ResolvedConfig, type ResolvedContext, type RetryConfig, SDK_VERSION, type SecurityConfig, SecurityError, type SignedPayload, type Storage, type StreamErrorCode, type StreamErrorData, type StreamEvent, type StreamEventType, type StreamTokenResponse, type StreamingConfig, StreamingManager, type StreamingState, type SystemEventType, type UpdatesResponse, type UsageMetrics, type UsageUpdateCallback, calculateBackoff, checkForPotentialPII, createErrorFromResponse, createLogger, createRequestSignature, FlagKit as default, detectPotentialPII, generateHMACSHA256, getKeyId, isClientKey, isFlagKitError, isPotentialPIIField, isProductionEnvironment, isRetryableCode, isRetryableError, isServerKey, parseRetryAfter, signPayload, verifySignedPayload, warnIfPotentialPII, warnIfServerKeyInBrowser, withRetry };