@flipswitch-io/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,645 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FlagCache: () => FlagCache,
+  FlipswitchProvider: () => FlipswitchProvider,
+  SseClient: () => SseClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/provider.ts
+var import_ofrep_web_provider = require("@openfeature/ofrep-web-provider");
+
+// src/sse-client.ts
+var MIN_RETRY_DELAY = 1e3;
+var MAX_RETRY_DELAY = 3e4;
+var SseClient = class {
+  constructor(baseUrl, apiKey, onFlagChange, onStatusChange, telemetryHeaders) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.onFlagChange = onFlagChange;
+    this.onStatusChange = onStatusChange;
+    this.telemetryHeaders = telemetryHeaders;
+    this.eventSource = null;
+    this.retryDelay = MIN_RETRY_DELAY;
+    this.reconnectTimeout = null;
+    this.closed = false;
+    this.status = "disconnected";
+  }
+  /**
+   * Start the SSE connection.
+   */
+  connect() {
+    if (this.closed) return;
+    if (this.eventSource) {
+      this.eventSource.close();
+    }
+    this.updateStatus("connecting");
+    const url = `${this.baseUrl}/api/v1/flags/events`;
+    try {
+      if (typeof EventSource !== "undefined") {
+        this.connectWithFetch(url);
+      } else {
+        this.connectWithPolyfill(url);
+      }
+    } catch (error) {
+      console.error("[Flipswitch] Failed to establish SSE connection:", error);
+      this.updateStatus("error");
+      this.scheduleReconnect();
+    }
+  }
+  /**
+   * Connect using fetch-based SSE (supports custom headers).
+   */
+  async connectWithFetch(url) {
+    try {
+      const headers = {
+        "X-API-Key": this.apiKey,
+        Accept: "text/event-stream",
+        "Cache-Control": "no-cache",
+        ...this.telemetryHeaders
+      };
+      const response = await fetch(url, {
+        method: "GET",
+        headers
+      });
+      if (!response.ok) {
+        throw new Error(`SSE connection failed: ${response.status}`);
+      }
+      if (!response.body) {
+        throw new Error("Response body is null");
+      }
+      this.updateStatus("connected");
+      this.retryDelay = MIN_RETRY_DELAY;
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      const processStream = async () => {
+        while (!this.closed) {
+          const { done, value } = await reader.read();
+          if (done) {
+            this.updateStatus("disconnected");
+            this.scheduleReconnect();
+            return;
+          }
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() || "";
+          let eventType = "";
+          let eventData = "";
+          for (const line of lines) {
+            if (line.startsWith("event:")) {
+              eventType = line.slice(6).trim();
+            } else if (line.startsWith("data:")) {
+              eventData = line.slice(5).trim();
+            } else if (line === "" && eventData) {
+              this.handleEvent(eventType, eventData);
+              eventType = "";
+              eventData = "";
+            }
+          }
+        }
+      };
+      processStream().catch((error) => {
+        if (!this.closed) {
+          console.error("[Flipswitch] SSE stream error:", error);
+          this.updateStatus("error");
+          this.scheduleReconnect();
+        }
+      });
+    } catch (error) {
+      if (!this.closed) {
+        console.error("[Flipswitch] SSE connection error:", error);
+        this.updateStatus("error");
+        this.scheduleReconnect();
+      }
+    }
+  }
+  /**
+   * Connect using native EventSource (for environments that support it).
+   * Note: This requires server-side support for API key in query params.
+   */
+  connectWithPolyfill(url) {
+    this.connectWithFetch(url);
+  }
+  /**
+   * Handle incoming SSE events.
+   */
+  handleEvent(eventType, data) {
+    if (eventType === "heartbeat") {
+      return;
+    }
+    if (eventType === "flag-change") {
+      try {
+        const event = JSON.parse(data);
+        this.onFlagChange(event);
+      } catch (error) {
+        console.error("[Flipswitch] Failed to parse flag-change event:", error);
+      }
+    }
+  }
+  /**
+   * Schedule a reconnection attempt with exponential backoff.
+   */
+  scheduleReconnect() {
+    if (this.closed) return;
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+    }
+    this.reconnectTimeout = setTimeout(() => {
+      if (!this.closed) {
+        this.connect();
+        this.retryDelay = Math.min(this.retryDelay * 2, MAX_RETRY_DELAY);
+      }
+    }, this.retryDelay);
+  }
+  /**
+   * Update and broadcast connection status.
+   */
+  updateStatus(status) {
+    this.status = status;
+    this.onStatusChange?.(status);
+  }
+  /**
+   * Get current connection status.
+   */
+  getStatus() {
+    return this.status;
+  }
+  /**
+   * Close the SSE connection and stop reconnection attempts.
+   */
+  close() {
+    this.closed = true;
+    this.updateStatus("disconnected");
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+  }
+};
+
+// src/provider.ts
+var DEFAULT_BASE_URL = "https://api.flipswitch.io";
+var SDK_VERSION = "0.1.0";
+var FlipswitchProvider = class {
+  constructor(options, eventHandlers) {
+    this.metadata = {
+      name: "flipswitch"
+    };
+    this.rulesFromFlagValue = false;
+    this.sseClient = null;
+    this._status = "NOT_READY";
+    this.eventHandlers = /* @__PURE__ */ new Map();
+    this.userEventHandlers = {};
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+    this.enableRealtime = options.enableRealtime ?? true;
+    this.enableTelemetry = options.enableTelemetry ?? true;
+    this.fetchImpl = options.fetchImplementation ?? (typeof window !== "undefined" ? fetch.bind(window) : fetch);
+    this.userEventHandlers = eventHandlers ?? {};
+    const headers = [["X-API-Key", this.apiKey]];
+    if (this.enableTelemetry) {
+      headers.push(["X-Flipswitch-SDK", this.getTelemetrySdkHeader()]);
+      headers.push(["X-Flipswitch-Runtime", this.getTelemetryRuntimeHeader()]);
+      headers.push(["X-Flipswitch-OS", this.getTelemetryOsHeader()]);
+      headers.push(["X-Flipswitch-Features", this.getTelemetryFeaturesHeader()]);
+    }
+    this.ofrepProvider = new import_ofrep_web_provider.OFREPWebProvider({
+      baseUrl: this.baseUrl + "/ofrep/v1",
+      fetchImplementation: this.fetchImpl,
+      headers
+    });
+  }
+  getTelemetrySdkHeader() {
+    return `javascript/${SDK_VERSION}`;
+  }
+  getTelemetryRuntimeHeader() {
+    if (typeof process !== "undefined" && process.versions?.node) {
+      return `node/${process.versions.node}`;
+    }
+    if (typeof navigator !== "undefined") {
+      const ua = navigator.userAgent;
+      if (ua.includes("Chrome")) {
+        const match = ua.match(/Chrome\/(\d+)/);
+        return `chrome/${match?.[1] ?? "unknown"}`;
+      }
+      if (ua.includes("Firefox")) {
+        const match = ua.match(/Firefox\/(\d+)/);
+        return `firefox/${match?.[1] ?? "unknown"}`;
+      }
+      if (ua.includes("Safari") && !ua.includes("Chrome")) {
+        const match = ua.match(/Version\/(\d+)/);
+        return `safari/${match?.[1] ?? "unknown"}`;
+      }
+      return "browser/unknown";
+    }
+    return "unknown/unknown";
+  }
+  getTelemetryOsHeader() {
+    if (typeof process !== "undefined" && process.platform) {
+      const platform = process.platform;
+      const arch = process.arch;
+      const os = platform === "darwin" ? "darwin" : platform === "win32" ? "windows" : platform;
+      return `${os}/${arch}`;
+    }
+    if (typeof navigator !== "undefined") {
+      const ua = navigator.userAgent.toLowerCase();
+      let os = "unknown";
+      let arch = "unknown";
+      if (ua.includes("mac")) os = "darwin";
+      else if (ua.includes("win")) os = "windows";
+      else if (ua.includes("linux")) os = "linux";
+      else if (ua.includes("android")) os = "android";
+      else if (ua.includes("iphone") || ua.includes("ipad")) os = "ios";
+      if (ua.includes("arm64") || ua.includes("aarch64")) arch = "arm64";
+      else if (ua.includes("x64") || ua.includes("x86_64") || ua.includes("amd64")) arch = "amd64";
+      return `${os}/${arch}`;
+    }
+    return "unknown/unknown";
+  }
+  getTelemetryFeaturesHeader() {
+    return `sse=${this.enableRealtime}`;
+  }
+  getTelemetryHeaders() {
+    if (!this.enableTelemetry) return {};
+    return {
+      "X-Flipswitch-SDK": this.getTelemetrySdkHeader(),
+      "X-Flipswitch-Runtime": this.getTelemetryRuntimeHeader(),
+      "X-Flipswitch-OS": this.getTelemetryOsHeader(),
+      "X-Flipswitch-Features": this.getTelemetryFeaturesHeader()
+    };
+  }
+  get status() {
+    return this._status;
+  }
+  /**
+   * Initialize the provider.
+   * Validates the API key and starts SSE connection if real-time is enabled.
+   */
+  async initialize(context) {
+    this._status = "NOT_READY";
+    try {
+      await this.ofrepProvider.initialize(context);
+    } catch (error) {
+      try {
+        const response = await this.fetchImpl(`${this.baseUrl}/ofrep/v1/evaluate/flags`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": this.apiKey,
+            ...this.getTelemetryHeaders()
+          },
+          body: JSON.stringify({
+            context: { targetingKey: "_init_" }
+          })
+        });
+        if (response.status === 401 || response.status === 403) {
+          this._status = "ERROR";
+          throw new Error("Invalid API key");
+        }
+        if (!response.ok && response.status !== 404) {
+          this._status = "ERROR";
+          throw new Error(`Failed to connect to Flipswitch: ${response.status}`);
+        }
+      } catch (validationError) {
+        this._status = "ERROR";
+        throw validationError;
+      }
+    }
+    if (this.enableRealtime) {
+      this.startSseConnection();
+    }
+    this._status = "READY";
+    this.emit("PROVIDER_READY");
+  }
+  /**
+   * Called when the provider is shut down.
+   */
+  async onClose() {
+    this.sseClient?.close();
+    this.sseClient = null;
+    await this.ofrepProvider.onClose?.();
+    this._status = "NOT_READY";
+  }
+  /**
+   * Start the SSE connection for real-time updates.
+   */
+  startSseConnection() {
+    const telemetryHeaders = this.getTelemetryHeadersMap();
+    this.sseClient = new SseClient(
+      this.baseUrl,
+      this.apiKey,
+      (event) => {
+        this.handleFlagChange(event);
+      },
+      (status) => {
+        this.userEventHandlers.onConnectionStatusChange?.(status);
+        if (status === "error") {
+          this._status = "STALE";
+          this.emit("PROVIDER_STALE");
+        } else if (status === "connected" && this._status === "STALE") {
+          this._status = "READY";
+          this.emit("PROVIDER_READY");
+        }
+      },
+      telemetryHeaders
+    );
+    this.sseClient.connect();
+  }
+  /**
+   * Get telemetry headers as a map.
+   */
+  getTelemetryHeadersMap() {
+    if (!this.enableTelemetry) {
+      return void 0;
+    }
+    return {
+      "X-Flipswitch-SDK": this.getTelemetrySdkHeader(),
+      "X-Flipswitch-Runtime": this.getTelemetryRuntimeHeader(),
+      "X-Flipswitch-OS": this.getTelemetryOsHeader(),
+      "X-Flipswitch-Features": this.getTelemetryFeaturesHeader()
+    };
+  }
+  /**
+   * Handle a flag change event from SSE.
+   * Emits PROVIDER_CONFIGURATION_CHANGED to trigger re-evaluation.
+   */
+  handleFlagChange(event) {
+    this.userEventHandlers.onFlagChange?.(event);
+    this.emit("PROVIDER_CONFIGURATION_CHANGED");
+  }
+  /**
+   * Emit an event to registered handlers.
+   */
+  emit(event) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      Array.from(handlers).forEach((handler) => handler());
+    }
+  }
+  /**
+   * Register an event handler.
+   */
+  onProviderEvent(event, handler) {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.eventHandlers.get(event).add(handler);
+  }
+  // ===============================
+  // Flag Resolution Methods - Delegated to OFREP Provider
+  // ===============================
+  resolveBooleanEvaluation(flagKey, defaultValue, context) {
+    return this.ofrepProvider.resolveBooleanEvaluation(flagKey, defaultValue, context);
+  }
+  resolveStringEvaluation(flagKey, defaultValue, context) {
+    return this.ofrepProvider.resolveStringEvaluation(flagKey, defaultValue, context);
+  }
+  resolveNumberEvaluation(flagKey, defaultValue, context) {
+    return this.ofrepProvider.resolveNumberEvaluation(flagKey, defaultValue, context);
+  }
+  resolveObjectEvaluation(flagKey, defaultValue, context) {
+    return this.ofrepProvider.resolveObjectEvaluation(flagKey, defaultValue, context);
+  }
+  /**
+   * Get SSE connection status.
+   */
+  getSseStatus() {
+    return this.sseClient?.getStatus() ?? "disconnected";
+  }
+  /**
+   * Force reconnect SSE connection.
+   */
+  reconnectSse() {
+    if (this.enableRealtime && this.sseClient) {
+      this.sseClient.close();
+      this.startSseConnection();
+    }
+  }
+  // ===============================
+  // Bulk Flag Evaluation (Direct HTTP - OFREP providers don't expose bulk API)
+  // ===============================
+  /**
+   * Transform OpenFeature context to OFREP context format.
+   */
+  transformContext(context) {
+    const result = {};
+    if (context.targetingKey) {
+      result.targetingKey = context.targetingKey;
+    }
+    for (const [key, value] of Object.entries(context)) {
+      if (key !== "targetingKey") {
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+  /**
+   * Infer the type of a value.
+   */
+  inferType(value) {
+    if (value === null) return "null";
+    if (Array.isArray(value)) return "array";
+    const t = typeof value;
+    if (t === "boolean" || t === "string" || t === "number" || t === "object") {
+      return t;
+    }
+    return "unknown";
+  }
+  /**
+   * Get flag type from metadata or infer from value.
+   */
+  getFlagType(flag) {
+    if (flag.metadata?.flagType) {
+      const metaType = flag.metadata.flagType;
+      if (metaType === "boolean" || metaType === "string" || metaType === "integer" || metaType === "decimal") {
+        return metaType === "integer" || metaType === "decimal" ? "number" : metaType;
+      }
+    }
+    return this.inferType(flag.value);
+  }
+  /**
+   * Format a value for display.
+   */
+  formatValue(value) {
+    if (value === null) return "null";
+    if (typeof value === "string") return `"${value}"`;
+    if (typeof value === "object") return JSON.stringify(value);
+    return String(value);
+  }
+  /**
+   * 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
+   */
+  async evaluateAllFlags(context) {
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}/ofrep/v1/evaluate/flags`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey,
+          ...this.getTelemetryHeaders()
+        },
+        body: JSON.stringify({
+          context: this.transformContext(context)
+        })
+      });
+      if (!response.ok) {
+        console.error(`Failed to evaluate all flags: ${response.status}`);
+        return [];
+      }
+      const result = await response.json();
+      const flags = [];
+      if (result.flags && Array.isArray(result.flags)) {
+        for (const flag of result.flags) {
+          if (flag.key) {
+            flags.push({
+              key: flag.key,
+              value: flag.value,
+              valueType: this.getFlagType(flag),
+              reason: flag.reason ?? null,
+              variant: flag.variant ?? null
+            });
+          }
+        }
+      }
+      return flags;
+    } catch (error) {
+      console.error("Error evaluating all flags:", error);
+      return [];
+    }
+  }
+  /**
+   * 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
+   */
+  async evaluateFlag(flagKey, context) {
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}/ofrep/v1/evaluate/flags/${flagKey}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey,
+          ...this.getTelemetryHeaders()
+        },
+        body: JSON.stringify({
+          context: this.transformContext(context)
+        })
+      });
+      if (!response.ok) {
+        return null;
+      }
+      const result = await response.json();
+      return {
+        key: result.key ?? flagKey,
+        value: result.value,
+        valueType: this.getFlagType(result),
+        reason: result.reason ?? null,
+        variant: result.variant ?? null
+      };
+    } catch (error) {
+      console.error(`Error evaluating flag '${flagKey}':`, error);
+      return null;
+    }
+  }
+};
+
+// src/cache.ts
+var DEFAULT_TTL_MS = 5 * 60 * 1e3;
+var FlagCache = class {
+  /**
+   * Create a new FlagCache.
+   * @param ttlMs Time-to-live in milliseconds (default: 5 minutes)
+   */
+  constructor(ttlMs = DEFAULT_TTL_MS) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.ttlMs = ttlMs;
+  }
+  /**
+   * Get a value from the cache.
+   * Returns undefined if the key doesn't exist or has expired.
+   */
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      return void 0;
+    }
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  /**
+   * Set a value in the cache.
+   */
+  set(key, value) {
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + this.ttlMs
+    });
+  }
+  /**
+   * Invalidate a specific key or all keys if no key is provided.
+   */
+  invalidate(key) {
+    if (key) {
+      this.cache.delete(key);
+    } else {
+      this.cache.clear();
+    }
+  }
+  /**
+   * Handle a flag change event from SSE.
+   * Invalidates the specific flag or all flags if flagKey is null.
+   */
+  handleFlagChange(event) {
+    if (event.flagKey) {
+      this.invalidate(event.flagKey);
+    } else {
+      this.invalidate();
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlagCache,
+  FlipswitchProvider,
+  SseClient
+});