@flipswitch-io/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Flipswitch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# @flipswitch-io/sdk
+
+[![CI](https://github.com/flipswitch-io/js-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/flipswitch-io/js-sdk/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@flipswitch-io/sdk.svg)](https://www.npmjs.com/package/@flipswitch-io/sdk)
+
+Flipswitch SDK for JavaScript/TypeScript with real-time SSE support for OpenFeature.
+
+This SDK provides an OpenFeature-compatible provider that wraps OFREP flag evaluation with automatic cache invalidation
+via Server-Sent Events (SSE). When flags change in your Flipswitch dashboard, connected clients receive updates in
+real-time.
+
+## Installation
+
+```bash
+npm install @flipswitch-io/sdk @openfeature/web-sdk
+# or
+npm install @flipswitch-io/sdk @openfeature/server-sdk
+```
+
+## Quick Start
+
+### Browser (React, Vue, etc.)
+
+```typescript
+import { FlipswitchProvider } from '@flipswitch-io/sdk';
+import { OpenFeature } from '@openfeature/web-sdk';
+
+// Only API key is required
+const provider = new FlipswitchProvider({
+  apiKey: 'your-environment-api-key'
+});
+
+// Register with OpenFeature
+await OpenFeature.setProviderAndWait(provider);
+
+// Get a client and evaluate flags
+const client = OpenFeature.getClient();
+const darkMode = await client.getBooleanValue('dark-mode', false);
+const welcomeMessage = await client.getStringValue('welcome-message', 'Hello!');
+```
+
+### Node.js (Server)
+
+```typescript
+import { FlipswitchProvider } from '@flipswitch-io/sdk';
+import { OpenFeature } from '@openfeature/server-sdk';
+
+const provider = new FlipswitchProvider({
+  apiKey: 'your-environment-api-key'
+});
+
+await OpenFeature.setProviderAndWait(provider);
+const client = OpenFeature.getClient();
+
+// Evaluate with context
+const context = {
+  targetingKey: 'user-123',
+  email: 'user@example.com',
+  plan: 'premium',
+};
+
+const showFeature = await client.getBooleanValue('new-feature', false, context);
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | *required* | Environment API key from dashboard |
+| `baseUrl` | `string` | `https://api.flipswitch.io` | Your Flipswitch server URL |
+| `enableRealtime` | `boolean` | `true` | Enable SSE for real-time flag updates |
+| `pollingInterval` | `number` | `30000` | Cache TTL in milliseconds |
+| `fetchImplementation` | `typeof fetch` | `fetch` | Custom fetch function |
+
+## Real-Time Updates
+
+When `enableRealtime` is enabled, the SDK maintains a Server-Sent Events (SSE) connection to receive instant flag change notifications. When a flag changes:
+
+1. The SSE client receives a `flag-change` event
+2. The local cache is immediately invalidated
+3. Next flag evaluation fetches the fresh value
+4. OpenFeature emits a `PROVIDER_CONFIGURATION_CHANGED` event
+
+### Event Handlers
+
+```typescript
+const provider = new FlipswitchProvider(
+  { apiKey: 'your-api-key' },
+  {
+    onFlagChange: (event) => {
+      console.log(`Flag changed: ${event.flagKey}`);
+    },
+    onConnectionStatusChange: (status) => {
+      console.log(`SSE status: ${status}`);
+    },
+  }
+);
+```
+
+### Connection Status
+
+```typescript
+// Check current SSE status
+const status = provider.getSseStatus();
+// 'connecting' | 'connected' | 'disconnected' | 'error'
+
+// Force reconnect
+provider.reconnectSse();
+```
+
+## React Integration
+
+```tsx
+import { OpenFeature, OpenFeatureProvider, useFlag } from '@openfeature/react-sdk';
+import { FlipswitchProvider } from '@flipswitch-io/sdk';
+
+// Initialize provider
+const provider = new FlipswitchProvider({
+  baseUrl: 'https://api.flipswitch.io',
+  apiKey: 'your-api-key',
+});
+
+await OpenFeature.setProviderAndWait(provider);
+
+function App() {
+  return (
+    <OpenFeatureProvider>
+      <MyComponent />
+    </OpenFeatureProvider>
+  );
+}
+
+function MyComponent() {
+  const { value: darkMode } = useFlag('dark-mode', false);
+
+  return (
+    <div className={darkMode ? 'dark' : 'light'}>
+      Dark mode is {darkMode ? 'enabled' : 'disabled'}
+    </div>
+  );
+}
+```
+
+## Bulk Flag Evaluation
+
+Evaluate all flags at once or get detailed evaluation results:
+
+```typescript
+// Evaluate all flags
+const flags = await provider.evaluateAllFlags(context);
+for (const flag of flags) {
+  console.log(`${flag.key} (${flag.valueType}): ${flag.value}`);
+}
+
+// Evaluate a single flag with full details
+const flag = await provider.evaluateFlag('dark-mode', context);
+if (flag) {
+  console.log(`Value: ${flag.value}, Reason: ${flag.reason}, Variant: ${flag.variant}`);
+}
+```
+
+## Reconnection Strategy
+
+The SSE client automatically reconnects with exponential backoff:
+- Initial delay: 1 second
+- Maximum delay: 30 seconds
+- Backoff multiplier: 2x
+
+When reconnected, the provider status changes from `STALE` back to `READY`.
+
+## Demo
+
+A complete working demo is included. To run it:
+
+```bash
+npm install
+npm run demo -- <your-api-key>
+```
+
+The demo will:
+1. Connect to Flipswitch and validate your API key
+2. Load and display all flags with their types and values
+3. Listen for real-time flag changes and display updates
+
+See [examples/demo.ts](./examples/demo.ts) for the full source.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.

package/dist/index.d.mts

@@ -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 };