@flagix/js-sdk 1.1.0

package/dist/index.js

@@ -0,0 +1,561 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Flagix: () => Flagix
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_evaluation_core = require("@flagix/evaluation-core");
+
+// src/lib/constants.ts
+var REMOVE_TRAILING_SLASH = /\/$/;
+var EVENT_TO_LISTEN = "flag-update";
+
+// src/lib/emitter.ts
+var import_eventemitter3 = __toESM(require("eventemitter3"));
+var FLAG_UPDATE_EVENT = EVENT_TO_LISTEN;
+var FlagixEventEmitter = class extends import_eventemitter3.default {
+};
+
+// src/lib/logger.ts
+var currentLogLevel = "none";
+var LOG_LEVELS = {
+  none: 0,
+  error: 1,
+  warn: 2,
+  info: 3
+};
+function setLogLevel(level = "none") {
+  currentLogLevel = level;
+}
+function log(level, message, ...args) {
+  const currentLevel = LOG_LEVELS[currentLogLevel];
+  const requiredLevel = LOG_LEVELS[level];
+  if (currentLevel >= requiredLevel) {
+    const prefixedMessage = `[Flagix SDK] ${message}`;
+    if (level === "error") {
+      console.error(prefixedMessage, ...args);
+    } else if (level === "warn") {
+      console.warn(prefixedMessage, ...args);
+    } else {
+      console.info(prefixedMessage, ...args);
+    }
+  }
+}
+
+// src/sse/create-event-source.ts
+async function createEventSource(url, apiKey) {
+  if (typeof window !== "undefined" && "EventSource" in window) {
+    return new EventSource(`${url}?apiKey=${apiKey}`);
+  }
+  try {
+    const { EventSource: NodeEventSource } = await import("eventsource");
+    return new NodeEventSource(url, {
+      headers: { "X-Api-Key": apiKey }
+    });
+  } catch (error) {
+    log("warn", "[Flagix SDK] SSE not supported in this environment.", error);
+    return null;
+  }
+}
+
+// src/client.ts
+var FlagixClient = class {
+  constructor(options) {
+    this.localCache = /* @__PURE__ */ new Map();
+    this.isInitialized = false;
+    this.sseConnection = null;
+    this.reconnectAttempts = 0;
+    this.reconnectTimeoutId = null;
+    this.isReconnecting = false;
+    this.hasEstablishedConnection = false;
+    this.maxReconnectAttempts = Number.POSITIVE_INFINITY;
+    this.baseReconnectDelay = 1e3;
+    this.maxReconnectDelay = 3e4;
+    this.apiKey = options.apiKey;
+    this.apiBaseUrl = options.apiBaseUrl.replace(REMOVE_TRAILING_SLASH, "");
+    this.context = options.initialContext || {};
+    this.emitter = new FlagixEventEmitter();
+    setLogLevel(options.logs?.level ?? "none");
+  }
+  /**
+   * Subscribes a listener to a flag update event.
+   */
+  on(event, listener) {
+    this.emitter.on(event, listener);
+  }
+  /**
+   * Unsubscribes a listener from a flag update event.
+   */
+  off(event, listener) {
+    this.emitter.off(event, listener);
+  }
+  /**
+   * Fetches all flag configurations from the API, populates the local cache,
+   * and sets up the SSE connection for real-time updates.
+   */
+  async initialize() {
+    if (this.isInitialized) {
+      return;
+    }
+    log("info", "[Flagix SDK] Starting initialization...");
+    await this.fetchInitialConfig();
+    this.setupSSEListener();
+    this.isInitialized = true;
+    log("info", "[Flagix SDK] Initialization complete.");
+  }
+  /**
+   * Returns true if the client has completed initialization
+   */
+  getIsInitialized() {
+    return this.isInitialized;
+  }
+  /**
+   * Evaluates a flag locally using the cached configuration and current context.
+   * @param flagKey The key of the flag to evaluate.
+   * @param context Optional, temporary context overrides for this specific evaluation.
+   */
+  evaluate(flagKey, contextOverrides) {
+    if (!this.isInitialized) {
+      log(
+        "warn",
+        `[Flagix SDK] Not initialized. Cannot evaluate flag: ${flagKey}`
+      );
+      return null;
+    }
+    const config = this.localCache.get(flagKey);
+    if (!config) {
+      return null;
+    }
+    const finalContext = { ...this.context, ...contextOverrides };
+    const result = (0, import_evaluation_core.evaluateFlag)(config, finalContext);
+    if (result) {
+      this.trackEvaluation(flagKey, result, finalContext);
+    }
+    return result?.value ?? null;
+  }
+  /**
+   * Sets or updates the global evaluation context.
+   * @param newContext New context attributes to merge or replace.
+   */
+  setContext(newContext) {
+    this.context = { ...this.context, ...newContext };
+    log(
+      "info",
+      "[Flagix SDK] Context updated. Evaluations will use the new context."
+    );
+  }
+  async fetchInitialConfig() {
+    const url = `${this.apiBaseUrl}/api/flag-config/all`;
+    try {
+      const response = await fetch(url, {
+        headers: { "X-Api-Key": this.apiKey }
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Failed to load initial config: ${response.statusText}`
+        );
+      }
+      const allFlags = await response.json();
+      this.localCache.clear();
+      for (const [key, config] of Object.entries(allFlags)) {
+        this.localCache.set(key, config);
+      }
+      log("info", `[Flagix SDK] Loaded ${this.localCache.size} flag configs.`);
+    } catch (error) {
+      log(
+        "error",
+        "[Flagix SDK] CRITICAL: Initial configuration fetch failed.",
+        error
+      );
+    }
+  }
+  async setupSSEListener() {
+    if (this.sseConnection) {
+      try {
+        this.sseConnection.close();
+      } catch (error) {
+        log(
+          "warn",
+          "[Flagix SDK] Error closing existing SSE connection",
+          error
+        );
+      }
+      this.sseConnection = null;
+    }
+    const url = `${this.apiBaseUrl}/api/sse/stream`;
+    const source = await createEventSource(url, this.apiKey);
+    if (!source) {
+      log("warn", "[Flagix SDK] Failed to create EventSource. Retrying...");
+      this.scheduleReconnect();
+      return;
+    }
+    this.sseConnection = source;
+    source.onopen = () => {
+      this.reconnectAttempts = 0;
+      this.isReconnecting = false;
+      if (this.reconnectTimeoutId) {
+        clearTimeout(this.reconnectTimeoutId);
+        this.reconnectTimeoutId = null;
+      }
+      if (this.hasEstablishedConnection && this.isInitialized) {
+        log(
+          "info",
+          "[Flagix SDK] SSE reconnected. Refreshing cache to sync with server..."
+        );
+        this.fetchInitialConfig().catch((error) => {
+          log(
+            "error",
+            "[Flagix SDK] Failed to refresh cache after reconnection",
+            error
+          );
+        });
+      } else {
+        this.hasEstablishedConnection = true;
+      }
+      log("info", "[Flagix SDK] SSE connection established.");
+    };
+    source.onerror = (error) => {
+      const eventSource = error.target;
+      const readyState = eventSource?.readyState;
+      if (readyState === 2) {
+        log(
+          "warn",
+          "[Flagix SDK] SSE connection closed. Attempting to reconnect..."
+        );
+        this.handleReconnect();
+      } else if (readyState === 0) {
+        log(
+          "warn",
+          "[Flagix SDK] SSE connection error (connecting state)",
+          error
+        );
+      } else {
+        log("error", "[Flagix SDK] SSE error", error);
+        this.handleReconnect();
+      }
+    };
+    source.addEventListener("connected", () => {
+      log("info", "[Flagix SDK] SSE connection confirmed by server.");
+    });
+    source.addEventListener(EVENT_TO_LISTEN, (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        const { flagKey, type } = data;
+        log("info", `[Flagix SDK] Received update for ${flagKey} (${type}).`);
+        this.fetchSingleFlagConfig(flagKey, type);
+      } catch (error) {
+        log("error", "[Flagix SDK] Failed to parse SSE event data.", error);
+      }
+    });
+  }
+  handleReconnect() {
+    if (this.isReconnecting || !this.isInitialized) {
+      return;
+    }
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      log(
+        "error",
+        "[Flagix SDK] Max reconnection attempts reached. Stopping reconnection."
+      );
+      return;
+    }
+    this.isReconnecting = true;
+    this.scheduleReconnect();
+  }
+  scheduleReconnect() {
+    if (this.reconnectTimeoutId) {
+      clearTimeout(this.reconnectTimeoutId);
+    }
+    const delay = Math.min(
+      this.baseReconnectDelay * 2 ** this.reconnectAttempts,
+      this.maxReconnectDelay
+    );
+    const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+    const finalDelay = Math.max(100, delay + jitter);
+    this.reconnectAttempts++;
+    log(
+      "info",
+      `[Flagix SDK] Scheduling SSE reconnection attempt ${this.reconnectAttempts} in ${Math.round(finalDelay)}ms...`
+    );
+    this.reconnectTimeoutId = setTimeout(() => {
+      this.isReconnecting = false;
+      this.reconnectTimeoutId = null;
+      this.setupSSEListener().catch((error) => {
+        log("error", "[Flagix SDK] Failed to reconnect SSE", error);
+        this.handleReconnect();
+      });
+    }, finalDelay);
+  }
+  async fetchSingleFlagConfig(flagKey, type) {
+    const url = `${this.apiBaseUrl}/api/flag-config/${flagKey}`;
+    if (type === "FLAG_DELETED" || type === "RULE_DELETED") {
+      this.localCache.delete(flagKey);
+      log("info", `[Flagix SDK] Flag ${flagKey} deleted from cache.`);
+      this.emitter.emit(FLAG_UPDATE_EVENT, flagKey);
+      return;
+    }
+    try {
+      const response = await fetch(url, {
+        headers: { "X-Api-Key": this.apiKey }
+      });
+      if (response.status === 404) {
+        this.localCache.delete(flagKey);
+        log(
+          "warn",
+          `[Flagix SDK] Flag ${flagKey} not found on API, deleted from cache.`
+        );
+        this.emitter.emit(FLAG_UPDATE_EVENT, flagKey);
+        return;
+      }
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch update for ${flagKey}: ${response.statusText}`
+        );
+      }
+      const config = await response.json();
+      this.localCache.set(flagKey, config);
+      log("info", `[Flagix SDK] Flag ${flagKey} updated/synced.`);
+      this.emitter.emit(FLAG_UPDATE_EVENT, flagKey);
+    } catch (error) {
+      log(
+        "error",
+        `[Flagix SDK] Failed to fetch update for ${flagKey}.`,
+        error
+      );
+    }
+  }
+  /**
+   * Records a custom event (conversion) for analytics and A/B testing.
+   */
+  track(eventName, properties, contextOverrides) {
+    const url = `${this.apiBaseUrl}/api/track/event`;
+    const finalContext = { ...this.context, ...contextOverrides };
+    const distinctId = (0, import_evaluation_core.resolveIdentifier)(finalContext);
+    const payload = {
+      apiKey: this.apiKey,
+      event_name: eventName,
+      distinctId,
+      properties: properties || {},
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const payloadJson = JSON.stringify(payload);
+    if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+      const blob = new Blob([payloadJson], { type: "application/json" });
+      if (navigator.sendBeacon(url, blob)) {
+        return;
+      }
+    }
+    this.fireAndForgetFetch(url, payloadJson);
+  }
+  /**
+   * Closes the Server-Sent Events (SSE) connection and cleans up resources.
+   */
+  close() {
+    if (this.reconnectTimeoutId) {
+      clearTimeout(this.reconnectTimeoutId);
+      this.reconnectTimeoutId = null;
+    }
+    this.isReconnecting = false;
+    this.reconnectAttempts = 0;
+    this.hasEstablishedConnection = false;
+    if (this.sseConnection) {
+      try {
+        this.sseConnection.close();
+      } catch (error) {
+        log("warn", "[Flagix SDK] Error closing SSE connection", error);
+      }
+      this.sseConnection = null;
+      log("info", "[Flagix SDK] SSE connection closed.");
+    }
+    this.localCache.clear();
+    this.isInitialized = false;
+    this.emitter.removeAllListeners();
+  }
+  /**
+   * Asynchronously sends an evaluation event to the backend tracking service.
+   */
+  trackEvaluation(flagKey, result, context) {
+    const url = `${this.apiBaseUrl}/api/track/evaluation`;
+    const distinctId = (0, import_evaluation_core.resolveIdentifier)(context);
+    const payload = {
+      apiKey: this.apiKey,
+      flagKey,
+      variationName: result.name,
+      variationValue: result.value,
+      variationType: result.type,
+      distinctId,
+      evaluationContext: context,
+      evaluatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const payloadJson = JSON.stringify(payload);
+    if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+      const blob = new Blob([payloadJson], { type: "application/json" });
+      const success = navigator.sendBeacon(url, blob);
+      if (success) {
+        log("info", `Successfully queued beacon for ${flagKey}.`);
+        return;
+      }
+      log("warn", `Beacon queue full for ${flagKey}. Falling back to fetch.`);
+      this.fireAndForgetFetch(url, payloadJson);
+    } else {
+      this.fireAndForgetFetch(url, payloadJson);
+    }
+  }
+  fireAndForgetFetch(url, payloadJson) {
+    fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: payloadJson,
+      keepalive: true
+    }).catch((error) => {
+      log(
+        "error",
+        `Critical failure sending impression event via fetch: ${error.message}`
+      );
+    });
+  }
+};
+
+// src/index.ts
+var clientInstance = null;
+var isInitializing = false;
+var initializationPromise = null;
+var Flagix = {
+  /**
+   * Initializes the Flagix SDK, fetches all flags, and sets up an SSE connection.
+   */
+  async initialize(options) {
+    if (clientInstance) {
+      log("warn", "Flagix SDK already initialized. Ignoring subsequent call.");
+      return;
+    }
+    if (isInitializing && initializationPromise) {
+      return initializationPromise;
+    }
+    isInitializing = true;
+    try {
+      clientInstance = new FlagixClient(options);
+      initializationPromise = clientInstance.initialize();
+      await initializationPromise;
+    } catch (error) {
+      log("error", "Flagix SDK failed during initialization:", error);
+      throw error;
+    } finally {
+      isInitializing = false;
+      initializationPromise = null;
+    }
+  },
+  /**
+   * Evaluates a flag based on the local cache and current context.
+   * @param flagKey The key of the flag to evaluate.
+   * @param contextOverrides Optional, temporary context overrides.
+   */
+  evaluate(flagKey, contextOverrides) {
+    if (!clientInstance || !clientInstance.getIsInitialized()) {
+      log(
+        "error",
+        "Flagix SDK not initialized. Call Flagix.initialize() first."
+      );
+      return null;
+    }
+    return clientInstance.evaluate(flagKey, contextOverrides);
+  },
+  /**
+   * Records a custom event for analytics.
+   * @param eventName The name of the event.
+   * @param properties Optional custom metadata.
+   * @param contextOverrides Optional context.
+   */
+  track(eventName, properties, contextOverrides) {
+    if (!clientInstance) {
+      log(
+        "error",
+        "Flagix SDK not initialized. Call Flagix.initialize() first."
+      );
+      return;
+    }
+    clientInstance.track(eventName, properties, contextOverrides);
+  },
+  /**
+   * Sets or updates the global evaluation context.
+   * @param newContext New context attributes to merge or replace.
+   */
+  setContext(newContext) {
+    if (!clientInstance) {
+      log("error", "Flagix SDK not initialized.");
+      return;
+    }
+    clientInstance.setContext(newContext);
+  },
+  /**
+   * Closes the SSE connection and cleans up resources.
+   */
+  close() {
+    if (clientInstance) {
+      clientInstance.close();
+      clientInstance = null;
+    }
+  },
+  /**
+   * checks initialization status
+   */
+  isInitialized() {
+    return !!clientInstance && clientInstance.getIsInitialized();
+  },
+  /**
+   * Subscribes a listener to updates for any flag.
+   * @param listener The callback function (receives the updated flagKey).
+   */
+  onFlagUpdate(listener) {
+    if (!clientInstance) {
+      log("warn", "Flagix SDK not initialized. Cannot subscribe to updates.");
+      return;
+    }
+    clientInstance.on(FLAG_UPDATE_EVENT, listener);
+  },
+  /**
+   * Unsubscribes a listener from flag updates.
+   * @param listener The callback function to remove.
+   */
+  offFlagUpdate(listener) {
+    if (!clientInstance) {
+      return;
+    }
+    clientInstance.off(FLAG_UPDATE_EVENT, listener);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Flagix
+});