@flagify/node 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Represents a user context object used for feature flag targeting.
+ *
+ * You can define standard properties like `id`, `email`, `role`, and `group`,
+ * as well as any number of custom attributes for segmentation purposes.
+ */
+interface FlagifyUser {
+    /**
+     * Unique identifier for the user.
+     * This is typically required for targeting, experimentation, or auditing.
+     */
+    id: string;
+    /**
+     * Optional email address of the user.
+     */
+    email?: string;
+    /**
+     * Optional role or access level of the user (e.g., "admin", "editor", "viewer").
+     */
+    role?: string;
+    /**
+     * Optional group or organization to which the user belongs.
+     */
+    group?: string;
+    /**
+     * Optional geolocation details used for region-based targeting.
+     */
+    geolocation?: {
+        /**
+         * ISO country code (e.g., "US", "MX", "DE").
+         */
+        country?: string;
+        /**
+         * Optional region or state within the country.
+         */
+        region?: string;
+        /**
+         * Optional city or locality.
+         */
+        city?: string;
+    };
+    /**
+     * Any other custom attributes for advanced targeting rules.
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * Configuration options required to initialize the Flagify client.
+ */
+interface FlagifyOptions {
+    /**
+     * The key identifying the project within your Flagify workspace.
+     */
+    projectKey: string;
+    /**
+     * Public API key used to identify the client or application.
+     * This is safe to expose in client-side environments (e.g., browser, mobile).
+     */
+    publicKey: string;
+    /**
+     * Optional private key for secure server-side communication.
+     * Never expose this in frontend environments.
+     */
+    secretKey?: string;
+    /**
+     * Additional optional configuration for advanced use cases.
+     */
+    options?: {
+        /**
+         * Contextual user data for targeting rules and segmentation.
+         * You may provide built-in fields like `id`, `email`, `role`, or custom traits.
+         */
+        user?: FlagifyUser;
+        /**
+         * Custom base URL for the Flagify API (e.g., for self-hosted instances or testing).
+         * Defaults to "https://api.flagify.app" if not provided.
+         */
+        apiUrl?: string;
+        /**
+         * Optional cache stale time in milliseconds for local flag resolution.
+         * Defaults to 5 minutes.
+         */
+        staleTimeMs?: number;
+        /**
+         * Enables real-time flag updates via Server-Sent Events.
+         */
+        realtime?: boolean;
+        /**
+         * Interval in milliseconds to periodically re-sync all flags.
+         * Useful as a fallback when realtime is unavailable.
+         * Example: 30000 (every 30 seconds).
+         */
+        pollIntervalMs?: number;
+    };
+}
+
+interface FlagifyHttpClient {
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown, B = unknown>(path: string, body: B): Promise<T>;
+    baseUrl: string;
+    headers: Record<string, string>;
+}
+
+interface RealtimeEvents {
+    onFlagChange: (event: FlagChangeEvent) => void;
+    onConnected: () => void;
+    onReconnected: () => void;
+    onError: (error: Error) => void;
+}
+interface FlagChangeEvent {
+    environmentId: string;
+    flagKey: string;
+    action: "updated" | "created" | "archived";
+}
+declare class RealtimeListener {
+    private readonly httpClient;
+    private readonly events;
+    private controller;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private hasConnectedBefore;
+    constructor(httpClient: FlagifyHttpClient, events: RealtimeEvents);
+    connect(): void;
+    disconnect(): void;
+    private stream;
+    private parseSSEFrame;
+    private scheduleReconnect;
+}
+
+/**
+ * Interface defining the core methods for the Flaggy client.
+ */
+interface IFlagifyClient {
+    /**
+     * Retrieves the resolved value of a feature flag.
+     * Falls back to defaultValue if evaluation fails or flag is not found.
+     *
+     * @param flagKey - The key of the feature flag to retrieve.
+     * @returns The resolved value of the feature flag.
+     */
+    getValue<T>(flagKey: string, fallback: T): T;
+    /**
+     * Checks if a boolean feature flag is enabled.
+     * Returns false if flag is not found or default is false.
+     *
+     * @param flagKey - The key of the feature flag to check.
+     * @returns True if the flag is enabled, false otherwise.
+     */
+    isEnabled(flagKey: string): boolean;
+    /**
+     * Returns the variant key with the highest weight for a multivariate flag.
+     * Returns fallback if the flag is missing, disabled, or has no variants.
+     *
+     * @param flagKey - The key of the feature flag.
+     * @param fallback - The default variant key.
+     * @returns The winning variant key.
+     */
+    getVariant(flagKey: string, fallback: string): string;
+    /**
+     * Evaluates a flag with user context for targeting rules.
+     * Calls the API's evaluate endpoint directly (not cached).
+     */
+    evaluate(flagKey: string, user: FlagifyUser): Promise<EvaluateResult>;
+}
+
+interface EvaluateResult {
+    key: string;
+    value: unknown;
+    reason: "targeting_rule" | "rollout" | "default" | "disabled";
+}
+declare class Flagify implements IFlagifyClient {
+    private readonly config;
+    private flagCache;
+    private httpClient;
+    private realtime;
+    private readyPromise;
+    private pollTimer;
+    /** Called when a flag changes via SSE. Useful for triggering React re-renders. */
+    onFlagChange: ((event: FlagChangeEvent) => void) | null;
+    constructor(config: FlagifyOptions);
+    /** Resolves when the initial flag sync is complete. */
+    ready(): Promise<void>;
+    getValue<T>(flagKey: string, fallback: T): T;
+    isEnabled(flagKey: string): boolean;
+    getVariant(flagKey: string, fallback: string): string;
+    evaluate(flagKey: string, user: FlagifyUser): Promise<EvaluateResult>;
+    /**
+     * Disconnects the realtime listener and cleans up resources.
+     */
+    destroy(): void;
+    private isStale;
+    private refetchFlag;
+    private syncFlags;
+    private evaluateWithUser;
+    private validateConfig;
+    private setupPolling;
+    private setupRealtimeListener;
+}
+
+/**
+ * Represents a feature flag within the Flagify system.
+ */
+interface FlagifyFlaggy {
+    /**
+     * Unique identifier for the flag (e.g., "new-dashboard").
+     */
+    key: string;
+    /**
+     * Human-readable name of the flag.
+     */
+    name: string;
+    /**
+     * The current value of the flag, which can be a boolean, string, number, or JSON object.
+     * This is the value that will be returned when the flag is evaluated.
+     */
+    value: boolean | string | number | Record<string, unknown>;
+    /**
+     * Detailed description of the flag's purpose.
+     */
+    description?: string;
+    /**
+     * Data type of the flag's value (e.g., "boolean", "string", "number", "json").
+     */
+    type: 'boolean' | 'string' | 'number' | 'json';
+    /**
+     * Default value returned when the flag is enabled but no targeting rules match.
+     */
+    defaultValue: boolean | string | number | Record<string, unknown>;
+    /**
+     * Value returned when the flag is disabled (enabled = false).
+     */
+    offValue: boolean | string | number | Record<string, unknown>;
+    /**
+     * Indicates whether the flag is currently active.
+     */
+    enabled: boolean;
+    /**
+     * Optional rollout percentage (0 to 100) for gradual feature releases.
+     */
+    rolloutPercentage?: number;
+    /**
+     * Optional targeting rules for user segmentation.
+     */
+    targetingRules?: Array<{
+        priority: number;
+        segmentId?: string;
+        valueOverride?: unknown;
+        rolloutPercentage?: number;
+        enabled: boolean;
+        conditions?: Array<{
+            attribute: string;
+            operator: 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'in' | 'not_in' | 'gt' | 'lt';
+            value: unknown;
+        }>;
+    }>;
+    /**
+     * Optional multivariate variants for A/B testing.
+     */
+    variants?: Array<{
+        key: string;
+        value: boolean | string | number | Record<string, unknown>;
+        weight: number;
+    }>;
+    /**
+     * Timestamp of when the flag was created.
+     */
+    createdAt: string;
+    /**
+     * Timestamp of the last update to the flag.
+     */
+    updatedAt: string;
+}
+
+export { type EvaluateResult, type FlagChangeEvent, Flagify, type FlagifyFlaggy, type FlagifyOptions, type FlagifyUser, type IFlagifyClient, type RealtimeEvents, RealtimeListener };

package/dist/index.js

@@ -0,0 +1,360 @@
+"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, {
+  Flagify: () => Flagify,
+  RealtimeListener: () => RealtimeListener
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/api/httpClient.ts
+function createHttpClient(config) {
+  const baseUrl = config.options?.apiUrl ?? (typeof process !== "undefined" ? process.env.FLAGIFY_API_URL : void 0) ?? "https://api.flagify.dev";
+  const headers = {
+    "Content-Type": "application/json",
+    "x-api-key": config.publicKey
+  };
+  return {
+    baseUrl,
+    headers,
+    get: async (path) => {
+      const res = await fetch(`${baseUrl}${path}`, {
+        method: "GET",
+        headers
+      });
+      if (!res.ok) {
+        throw new Error(`[HTTP GET] ${res.status} ${res.statusText}`);
+      }
+      return res.json();
+    },
+    post: async (path, body) => {
+      const res = await fetch(`${baseUrl}${path}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body)
+      });
+      if (!res.ok) {
+        throw new Error(`[HTTP POST] ${res.status} ${res.statusText}`);
+      }
+      return res.json();
+    }
+  };
+}
+
+// src/realtime.ts
+var RECONNECT_BASE_MS = 1e3;
+var RECONNECT_MAX_MS = 3e4;
+var RealtimeListener = class {
+  constructor(httpClient, events) {
+    this.httpClient = httpClient;
+    this.events = events;
+    this.controller = null;
+    this.reconnectAttempts = 0;
+    this.reconnectTimer = null;
+    this.hasConnectedBefore = false;
+  }
+  connect() {
+    this.disconnect();
+    this.controller = new AbortController();
+    this.stream(this.controller.signal);
+  }
+  disconnect() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.controller) {
+      this.controller.abort();
+      this.controller = null;
+    }
+    this.reconnectAttempts = 0;
+  }
+  async stream(signal) {
+    try {
+      const res = await fetch(
+        `${this.httpClient.baseUrl}/v1/eval/flags/stream`,
+        {
+          method: "GET",
+          headers: this.httpClient.headers,
+          signal
+        }
+      );
+      if (!res.ok) {
+        throw new Error(`SSE connection failed: ${res.status} ${res.statusText}`);
+      }
+      if (!res.body) {
+        throw new Error("SSE response has no body");
+      }
+      this.reconnectAttempts = 0;
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const parts = buffer.split("\n\n");
+        buffer = parts.pop() ?? "";
+        for (const part of parts) {
+          this.parseSSEFrame(part);
+        }
+      }
+      if (!signal.aborted) {
+        this.scheduleReconnect();
+      }
+    } catch (err) {
+      if (signal.aborted) return;
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.events.onError(error);
+      this.scheduleReconnect();
+    }
+  }
+  parseSSEFrame(frame) {
+    let eventType = "";
+    let data = "";
+    for (const line of frame.split("\n")) {
+      if (line.startsWith("event: ")) {
+        eventType = line.slice(7).trim();
+      } else if (line.startsWith("data: ")) {
+        data = line.slice(6).trim();
+      }
+    }
+    if (eventType === "connected") {
+      if (this.hasConnectedBefore) {
+        this.events.onReconnected();
+      } else {
+        this.hasConnectedBefore = true;
+        this.events.onConnected();
+      }
+      return;
+    }
+    if (eventType === "flag_change" && data) {
+      try {
+        const parsed = JSON.parse(data);
+        this.events.onFlagChange(parsed);
+      } catch {
+        console.warn("[Flagify] Failed to parse SSE event:", data);
+      }
+    }
+  }
+  scheduleReconnect() {
+    const delay = Math.min(
+      RECONNECT_BASE_MS * Math.pow(2, this.reconnectAttempts),
+      RECONNECT_MAX_MS
+    );
+    this.reconnectAttempts++;
+    this.reconnectTimer = setTimeout(() => this.connect(), delay);
+  }
+};
+
+// src/client.ts
+var Flagify = class {
+  constructor(config) {
+    this.config = config;
+    this.flagCache = /* @__PURE__ */ new Map();
+    this.realtime = null;
+    this.pollTimer = null;
+    /** Called when a flag changes via SSE. Useful for triggering React re-renders. */
+    this.onFlagChange = null;
+    this.validateConfig();
+    this.httpClient = createHttpClient(config);
+    this.readyPromise = this.syncFlags();
+    if (this.config.options?.realtime) {
+      this.setupRealtimeListener();
+    }
+    if (this.config.options?.pollIntervalMs) {
+      this.setupPolling();
+    }
+  }
+  /** Resolves when the initial flag sync is complete. */
+  ready() {
+    return this.readyPromise;
+  }
+  getValue(flagKey, fallback) {
+    const cached = this.flagCache.get(flagKey);
+    if (!cached) return fallback;
+    if (this.isStale(cached)) {
+      this.refetchFlag(flagKey);
+    }
+    if (!cached.flag.enabled) return cached.flag.offValue;
+    return cached.flag.value ?? fallback;
+  }
+  isEnabled(flagKey) {
+    const cached = this.flagCache.get(flagKey);
+    if (!cached) return false;
+    if (this.isStale(cached)) {
+      this.refetchFlag(flagKey);
+    }
+    if (cached.flag.type !== "boolean") return false;
+    if (!cached.flag.enabled) return cached.flag.offValue === true;
+    return cached.flag.value === true;
+  }
+  getVariant(flagKey, fallback) {
+    const cached = this.flagCache.get(flagKey);
+    if (!cached || !cached.flag.enabled) return fallback;
+    const variants = cached.flag.variants;
+    if (!variants || variants.length === 0) return fallback;
+    let best = variants[0];
+    for (let i = 1; i < variants.length; i++) {
+      if (variants[i].weight > best.weight) {
+        best = variants[i];
+      }
+    }
+    return best.key;
+  }
+  async evaluate(flagKey, user) {
+    return this.httpClient.post(
+      `/v1/eval/flags/${flagKey}/evaluate`,
+      { userId: user.id, attributes: user }
+    );
+  }
+  /**
+   * Disconnects the realtime listener and cleans up resources.
+   */
+  destroy() {
+    if (this.realtime) {
+      this.realtime.disconnect();
+      this.realtime = null;
+    }
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+  isStale(cached) {
+    const staleTime = this.config.options?.staleTimeMs;
+    if (typeof staleTime !== "number") {
+      return false;
+    }
+    return Date.now() - cached.lastFetchedAt > staleTime;
+  }
+  async refetchFlag(flagKey) {
+    try {
+      const fresh = await this.httpClient.get(
+        `/v1/eval/flags/${flagKey}`
+      );
+      this.flagCache.set(flagKey, {
+        flag: fresh,
+        lastFetchedAt: Date.now()
+      });
+      const user = this.config.options?.user;
+      if (user) {
+        const result = await this.httpClient.post(`/v1/eval/flags/${flagKey}/evaluate`, {
+          userId: user.id,
+          attributes: user
+        });
+        const cached = this.flagCache.get(flagKey);
+        if (cached) {
+          this.flagCache.set(flagKey, {
+            flag: { ...cached.flag, value: result.value },
+            lastFetchedAt: cached.lastFetchedAt
+          });
+        }
+      }
+      this.onFlagChange?.({
+        environmentId: "",
+        flagKey,
+        action: "updated"
+      });
+    } catch (err) {
+      console.warn(`[Flagify] Failed to refetch flag "${flagKey}":`, err);
+    }
+  }
+  async syncFlags() {
+    try {
+      const flags = await this.httpClient.get(`/v1/eval/flags`);
+      for (const flag of flags) {
+        this.flagCache.set(flag.key, {
+          flag,
+          lastFetchedAt: Date.now()
+        });
+      }
+      const user = this.config.options?.user;
+      if (user) {
+        await this.evaluateWithUser(user);
+      }
+    } catch (err) {
+      console.warn(`[Flagify] Failed to sync flags: ${err}`);
+    }
+  }
+  async evaluateWithUser(user) {
+    try {
+      const results = await this.httpClient.post(`/v1/eval/flags/evaluate`, { userId: user.id, attributes: user });
+      for (const result of results) {
+        const cached = this.flagCache.get(result.key);
+        if (cached) {
+          this.flagCache.set(result.key, {
+            flag: { ...cached.flag, value: result.value },
+            lastFetchedAt: cached.lastFetchedAt
+          });
+        }
+      }
+    } catch (err) {
+      console.warn(`[Flagify] Failed to evaluate flags for user: ${err}`);
+    }
+  }
+  validateConfig() {
+    const missing = [];
+    if (!this.config.publicKey) {
+      missing.push("publicKey");
+    }
+    if (!this.config.projectKey) {
+      missing.push("projectKey");
+    }
+    if (missing.length > 0) {
+      console.error(
+        `[Flagify] Missing required config keys: ${missing.join(", ")}`,
+        "All feature flags will be disabled."
+      );
+    }
+  }
+  setupPolling() {
+    const interval = this.config.options.pollIntervalMs;
+    this.pollTimer = setInterval(async () => {
+      await this.syncFlags();
+      this.onFlagChange?.({ environmentId: "", flagKey: "*", action: "updated" });
+    }, interval);
+  }
+  setupRealtimeListener() {
+    this.realtime = new RealtimeListener(this.httpClient, {
+      onConnected: () => {
+        console.info("[Flagify] Realtime connected");
+      },
+      onReconnected: () => {
+        console.info("[Flagify] Realtime reconnected \u2014 resyncing all flags");
+        this.syncFlags();
+      },
+      onFlagChange: (event) => {
+        console.debug(`[Flagify] Flag changed: ${event.flagKey} (${event.action})`);
+        this.refetchFlag(event.flagKey);
+      },
+      onError: (error) => {
+        console.warn("[Flagify] Realtime error (will reconnect):", error.message);
+      }
+    });
+    this.realtime.connect();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Flagify,
+  RealtimeListener
+});