@flagix/js-sdk 1.1.0

package/src/client.ts

@@ -0,0 +1,482 @@
+import { evaluateFlag, resolveIdentifier } from "@flagix/evaluation-core";
+import {
+  EVENT_TO_LISTEN,
+  type FlagUpdateType,
+  REMOVE_TRAILING_SLASH,
+} from "@/lib/constants";
+import { FLAG_UPDATE_EVENT, FlagixEventEmitter } from "@/lib/emitter";
+import { log, setLogLevel } from "@/lib/logger";
+import {
+  createEventSource,
+  type FlagStreamConnection,
+} from "@/sse/create-event-source";
+import type {
+  EvaluationContext,
+  FlagConfig,
+  FlagixClientOptions,
+  FlagVariation,
+  VariationValue,
+} from "@/types";
+
+/**
+ * The primary class for the Flagix SDK. Manages configuration state,
+ * local caching, and evaluation.
+ */
+export class FlagixClient {
+  private readonly apiKey: string;
+  private readonly apiBaseUrl: string;
+  private readonly localCache = new Map<string, FlagConfig>();
+  private context: EvaluationContext;
+  private isInitialized = false;
+  private sseConnection: FlagStreamConnection | null = null;
+  private readonly emitter: FlagixEventEmitter;
+  private reconnectAttempts = 0;
+  private reconnectTimeoutId: ReturnType<typeof setTimeout> | null = null;
+  private isReconnecting = false;
+  private hasEstablishedConnection = false;
+  private readonly maxReconnectAttempts = Number.POSITIVE_INFINITY;
+  private readonly baseReconnectDelay = 1000;
+  private readonly maxReconnectDelay = 30_000;
+
+  constructor(options: FlagixClientOptions) {
+    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: typeof FLAG_UPDATE_EVENT,
+    listener: (flagKey: string) => void
+  ): void {
+    this.emitter.on(event, listener);
+  }
+
+  /**
+   * Unsubscribes a listener from a flag update event.
+   */
+  off(
+    event: typeof FLAG_UPDATE_EVENT,
+    listener: (flagKey: string) => void
+  ): void {
+    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(): Promise<void> {
+    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(): boolean {
+    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<T extends VariationValue>(
+    flagKey: string,
+    contextOverrides?: EvaluationContext
+  ): T | null {
+    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 = evaluateFlag(config, finalContext);
+
+    if (result) {
+      this.trackEvaluation(flagKey, result, finalContext);
+    }
+
+    return (result?.value as T) ?? null;
+  }
+
+  /**
+   * Sets or updates the global evaluation context.
+   * @param newContext New context attributes to merge or replace.
+   */
+  setContext(newContext: EvaluationContext): void {
+    this.context = { ...this.context, ...newContext };
+    log(
+      "info",
+      "[Flagix SDK] Context updated. Evaluations will use the new context."
+    );
+  }
+
+  private async fetchInitialConfig(): Promise<void> {
+    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()) as Record<string, FlagConfig>;
+
+      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
+      );
+    }
+  }
+
+  private async setupSSEListener(): Promise<void> {
+    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 is a reconnection and not the first connection, refresh the cache
+      // this ensures we have the latest flag values that may have changed while disconnected
+      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 as EventSource;
+      const readyState = eventSource?.readyState;
+
+      // EventSource.readyState: 0 = CONNECTING, 1 = OPEN, 2 = CLOSED
+      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();
+      }
+    };
+
+    // Listen for the "connected" event from the server
+    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 as {
+          flagKey: string;
+          type: FlagUpdateType;
+        };
+
+        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);
+      }
+    });
+  }
+
+  private handleReconnect(): void {
+    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();
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimeoutId) {
+      clearTimeout(this.reconnectTimeoutId);
+    }
+
+    // Calculate exponential backoff delay with jitter
+    const delay = Math.min(
+      this.baseReconnectDelay * 2 ** this.reconnectAttempts,
+      this.maxReconnectDelay
+    );
+    // Add ±25% jitter to prevent thundering herd
+    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);
+  }
+
+  private async fetchSingleFlagConfig(
+    flagKey: string,
+    type: FlagUpdateType
+  ): Promise<void> {
+    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()) as FlagConfig;
+
+      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: string,
+    properties?: Record<string, unknown>,
+    contextOverrides?: EvaluationContext
+  ): void {
+    const url = `${this.apiBaseUrl}/api/track/event`;
+
+    const finalContext = { ...this.context, ...contextOverrides };
+    const distinctId = resolveIdentifier(finalContext);
+
+    const payload = {
+      apiKey: this.apiKey,
+      event_name: eventName,
+      distinctId,
+      properties: properties || {},
+      timestamp: 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(): void {
+    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.
+   */
+  private trackEvaluation(
+    flagKey: string,
+    result: FlagVariation,
+    context: EvaluationContext
+  ): void {
+    const url = `${this.apiBaseUrl}/api/track/evaluation`;
+
+    const distinctId = resolveIdentifier(context);
+
+    const payload = {
+      apiKey: this.apiKey,
+      flagKey,
+      variationName: result.name,
+      variationValue: result.value,
+      variationType: result.type,
+      distinctId,
+      evaluationContext: context,
+      evaluatedAt: 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);
+    }
+  }
+
+  private fireAndForgetFetch(url: string, payloadJson: string): void {
+    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}`
+      );
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,139 @@
+import { FlagixClient } from "@/client";
+import { FLAG_UPDATE_EVENT } from "@/lib/emitter";
+import { log } from "@/lib/logger";
+import type {
+  EvaluationContext,
+  FlagixClientOptions,
+  VariationValue,
+} from "@/types";
+
+let clientInstance: FlagixClient | null = null;
+
+let isInitializing = false;
+let initializationPromise: Promise<void> | null = null;
+
+export const Flagix = {
+  /**
+   * Initializes the Flagix SDK, fetches all flags, and sets up an SSE connection.
+   */
+  async initialize(options: FlagixClientOptions): Promise<void> {
+    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<T extends VariationValue>(
+    flagKey: string,
+    contextOverrides?: EvaluationContext
+  ): T | null {
+    if (!clientInstance || !clientInstance.getIsInitialized()) {
+      log(
+        "error",
+        "Flagix SDK not initialized. Call Flagix.initialize() first."
+      );
+
+      return null;
+    }
+    return clientInstance.evaluate<T>(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: string,
+    properties?: Record<string, unknown>,
+    contextOverrides?: EvaluationContext
+  ): void {
+    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: EvaluationContext): void {
+    if (!clientInstance) {
+      log("error", "Flagix SDK not initialized.");
+      return;
+    }
+    clientInstance.setContext(newContext);
+  },
+
+  /**
+   * Closes the SSE connection and cleans up resources.
+   */
+  close(): void {
+    if (clientInstance) {
+      clientInstance.close();
+      clientInstance = null;
+    }
+  },
+
+  /**
+   * checks initialization status
+   */
+  isInitialized(): boolean {
+    return !!clientInstance && clientInstance.getIsInitialized();
+  },
+
+  /**
+   * Subscribes a listener to updates for any flag.
+   * @param listener The callback function (receives the updated flagKey).
+   */
+  onFlagUpdate(listener: (flagKey: string) => void): void {
+    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: (flagKey: string) => void): void {
+    if (!clientInstance) {
+      return;
+    }
+    clientInstance.off(FLAG_UPDATE_EVENT, listener);
+  },
+};
+
+// biome-ignore lint/performance/noBarrelFile: <>
+export * from "./types";

package/src/lib/constants.ts

@@ -0,0 +1,12 @@
+export const REMOVE_TRAILING_SLASH = /\/$/;
+
+export type FlagUpdateType =
+  | "FLAG_CREATED"
+  | "FLAG_UPDATED"
+  | "FLAG_DELETED"
+  | "FLAG_METADATA_UPDATED"
+  | "FLAG_STATE_TOGGLED"
+  | "RULE_UPDATED"
+  | "RULE_DELETED";
+
+export const EVENT_TO_LISTEN = "flag-update";

package/src/lib/emitter.ts

@@ -0,0 +1,10 @@
+import EventEmitter from "eventemitter3";
+import { EVENT_TO_LISTEN } from "@/lib/constants";
+
+export type FlagixEvents = {
+  "flag-update": (flagKey: string) => void;
+};
+
+export const FLAG_UPDATE_EVENT = EVENT_TO_LISTEN;
+
+export class FlagixEventEmitter extends EventEmitter<FlagixEvents> {}

package/src/lib/logger.ts

@@ -0,0 +1,41 @@
+/**
+ * 'info' is for detailed debugging information
+ * 'warn' is for non-critical issues
+ * 'error' is for critical failures
+ * 'none' suppresses all output.
+ */
+export type LogLevel = "none" | "error" | "warn" | "info";
+
+let currentLogLevel: LogLevel = "none";
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  none: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+};
+
+export function setLogLevel(level: LogLevel = "none"): void {
+  currentLogLevel = level;
+}
+
+export function log(
+  level: "error" | "warn" | "info",
+  message: string,
+  ...args: unknown[]
+): void {
+  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);
+    }
+  }
+}