@flagify/node 1.0.0

package/dist/index.mjs

@@ -0,0 +1,332 @@
+// 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();
+  }
+};
+export {
+  Flagify,
+  RealtimeListener
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@flagify/node",
+  "version": "1.0.0",
+  "description": "Official Flagify SDK for feature flag evaluation. TypeScript-first with local caching.",
+  "author": "Mario Campbell R <mario@mariocampbellr.com>",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "dotenv": "^16.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0"
+  },
+  "keywords": [
+    "feature-flags",
+    "flagify",
+    "feature-toggle",
+    "sdk"
+  ],
+  "homepage": "https://flagify.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flagifyhq/javascript",
+    "directory": "packages/node"
+  },
+  "bugs": {
+    "url": "https://github.com/flagifyhq/javascript/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate": "barrelsby -c ./barrelsby.json",
+    "build": "pnpm run generate && tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}