@flaggy.io/sdk-js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flaggy.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,333 @@
+# Flaggy.io Feature Flag SDK
+
+A JavaScript / TypeScript SDK for managing feature flags from Flaggy.io that is fully compatible for both client-side (browser) and server-side (Node.js) environments.
+
+## Features
+
+- ✅ **Safe defaults**: Optional default values for graceful handling of new users and network failures
+- ✅ **Auto-environment detection**: Uses localStorage in browsers, in-memory storage in Node.js
+- ✅ **Automatic caching**: Reduces API calls and improves performance
+- ✅ **Auto-refresh**: Refreshes on a 60-second base interval with exponential backoff on failures
+- ✅ **Request deduplication**: Prevents concurrent duplicate API requests
+- ✅ **TypeScript support**: Full type safety
+- ✅ **Environment-based flags**: Support for production, staging, and development environments
+- ✅ **Simple configuration**: Only requires an API key
+- ✅ **Input validation**: Validates API keys and response data
+
+## Requirements
+
+- **Node.js**: 18.0.0 or higher (required for native `fetch()` API support)
+- **Browser**: Any modern browser with ES2020 support
+
+## Installation
+
+```bash
+npm install @flaggy.io/sdk-js
+```
+
+## Client-Side (React)
+
+Create a dedicated file (e.g., `src/lib/flaggy.ts`):
+
+```typescript
+import { flaggy } from "@flaggy.io/sdk-js";
+
+export const flagClient = flaggy({
+  apiKey: import.meta.env.VITE_FLAGGY_API_KEY!,
+  environment: import.meta.env.VITE_ENVIRONMENT,
+});
+
+// Export a wrapper function for cleaner usage throughout your app
+export function featureEnabled(
+  flagName: string,
+  defaultValue?: boolean,
+): boolean {
+  return flagClient.isEnabled(flagName, defaultValue);
+}
+```
+
+Initialize and wait for flags:
+
+```tsx
+// src/main.tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import App from "./App";
+import { flagClient } from "./lib/flaggy";
+
+await flagClient.initialize();
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+```
+
+Simple usage example:
+
+```tsx
+import { featureEnabled } from "./lib/flaggy";
+
+export function Header() {
+  // Specify safe default for new users (before flags load)
+  return featureEnabled("new-header", false) ? <NewHeader /> : <OldHeader />;
+}
+```
+
+## Server-Side (Node.js)
+
+Create a dedicated client file (e.g., `src/lib/flaggy.ts`):
+
+```typescript
+import { flaggy } from "@flaggy.io/sdk-js";
+
+export const flagClient = flaggy({
+  apiKey: process.env.FLAGGY_API_KEY!,
+  environment: process.env.NODE_ENV,
+});
+
+// Export a wrapper function for cleaner usage
+export function featureEnabled(
+  flagName: string,
+  defaultValue?: boolean,
+): boolean {
+  return flagClient.isEnabled(flagName, defaultValue);
+}
+```
+
+Then in your server startup file (e.g., `src/server.ts` or `src/index.ts`), **await the initial flag load before starting your server**:
+
+```typescript
+import { featureEnabled, flagClient } from "./lib/flaggy";
+import express, { Application, Request, Response } from "express";
+
+const app: Application = express();
+const port = process.env.PORT || 3000;
+
+app.get("/", (req: Request, res: Response) => {
+  if (featureEnabled("new-service")) {
+    // Logic for the new service
+  } else {
+    // Logic for the old service
+  }
+});
+
+async function start(): Promise<void> {
+  await flagClient.initialize();
+
+  app.listen(port, () => {
+    console.log(`Server is Fire at http://localhost:${port}`);
+  });
+}
+
+void start();
+```
+
+Use throughout your application:
+
+```typescript
+import { featureEnabled } from "./lib/flaggy";
+
+if (featureEnabled("new-algorithm", true)) {
+  // Defaulting to enabled
+}
+```
+
+To react to fetch errors without throwing, provide an `onError` callback:
+
+```typescript
+const flagClient = flaggy({
+  apiKey: import.meta.env.VITE_FLAGGY_API_KEY!,
+  onError: (error) => {
+    console.warn("Flag fetch failed:", error);
+  },
+});
+```
+
+**Environment:** The `environment` field is optional and defaults to `"production"`. You can pass raw strings (for example `process.env.NODE_ENV` / `import.meta.env.VITE_ENVIRONMENT`), and the SDK will only use `"production"`, `"staging"`, or `"development"`—any other value falls back to `"production"`.
+
+```typescript
+// Omit entirely (uses "production")
+const flagClient = flaggy({
+  apiKey: import.meta.env.VITE_FLAGGY_API_KEY!,
+});
+
+// Or pass env directly (SDK normalizes invalid values to "production")
+environment: import.meta.env.VITE_ENVIRONMENT,
+```
+
+**Network Errors:** The SDK logs fetch errors to the console and invokes the `onError` callback if provided. If the API is unreachable, the SDK will continue to use cached flags and retry on the next refresh interval using exponential backoff (base 60 seconds, capped at 15 minutes).
+
+**Timeout:** Requests are aborted after 2 seconds to avoid long stalls.
+
+## API Reference
+
+### Configuration
+
+The SDK uses the following hard-coded values:
+
+- **API URL**: `https://api.flaggy.io/public/feature-flags`
+- **Storage Key**: `feature-flags`
+- **Refresh Interval**: 60-second base with exponential backoff on failures (capped at 15 minutes)
+- **Authentication**: `x-api-key` header
+
+### Feature Flag Structure
+
+Each feature flag has the following structure:
+
+```typescript
+interface FeatureFlag {
+  key: string;
+  enabled_production: boolean;
+  enabled_staging: boolean;
+  enabled_development: boolean;
+}
+```
+
+This allows the same flag to have different states across different environments.
+
+### `flaggy(config: FeatureFlagConfig): FeatureFlagClient`
+
+Initialize the global feature flag client with your API key and environment.
+
+**Factory-only:** `FeatureFlagClient` is not exported, so clients must be created via `flaggy()`.
+
+**Singleton Behavior:** Multiple calls to `flaggy()` return the same instance. This makes it safe to call in React components that re-render, and prevents duplicate API requests and race conditions.
+
+**Auto-initialization:** Flags are automatically fetched in the background when you instantiate the client via `flaggy()`. The client loads from cache immediately if available and auto-refreshes on a 60-second base interval with exponential backoff on failures.
+
+**React / Client-Side:** Call `await client.initialize()` before rendering your app. If cached flags exist in localStorage, `initialize()` returns immediately without blocking—preventing flash screens on page refresh. If no cache exists, it waits up to 2 seconds for the initial fetch.
+
+**Node.js / Server Startup:** Call `await client.initialize()` before starting your server. Since the in-memory cache is empty on server restart, `initialize()` will wait up to 2 seconds for the initial fetch to ensure flags are available before accepting requests.
+
+**Config Options:**
+
+- `apiKey` (required): Your Flaggy.io API key for authentication
+- `environment` (optional): Accepts any string input (e.g. `process.env.NODE_ENV`), but only `'production'`, `'staging'`, and `'development'` are used; all other values default to `'production'`.
+- `onError` (optional): Callback invoked when a flag fetch fails. Does not throw.
+
+**Returns:** `FeatureFlagClient` instance
+
+**Important:** Configuration is locked after the first call. Subsequent calls with different config values will return the existing instance with the original configuration.
+
+## Client API (returned by `flaggy()`)
+
+**Caching behavior:**
+
+- **Client-side (React/browser):** Flags are loaded from localStorage immediately on instantiation. If cache is stale (> 60 seconds), a background fetch updates the flags without blocking.
+- **Server-side (Node.js):** In-memory cache is empty on server restart, so `initialize()` should be awaited to ensure flags are loaded before serving requests.
+- All flag evaluations (`isEnabled()`, `getFlag()`) trigger automatic background refreshes when the cache interval expires.
+
+### `isEnabled(flagName: string, defaultValue?: boolean): boolean`
+
+Check if a feature flag is enabled for the configured environment.
+
+**Parameters:**
+
+- `flagName`: The key of the feature flag to check
+- `defaultValue`: Optional default value to return if flag doesn't exist or isn't loaded yet (defaults to `false`)
+
+**Returns:** `boolean` - Whether the flag is enabled
+
+**Example:**
+
+```typescript
+// Safe default for new users (flag not loaded yet)
+if (flagClient.isEnabled("new-ui", false)) {
+  // Show new UI only if flag exists and is enabled
+}
+
+// Default to enabled for opt-out features
+if (flagClient.isEnabled("analytics", true)) {
+  // Analytics enabled unless explicitly disabled
+}
+```
+
+**Best Practice:** Always specify a safe default value that provides the correct experience for new users before flags load, or during network failures.
+
+### `getFlag(flagName: string): FeatureFlag | undefined`
+
+Get the full feature flag object with all environment states.
+
+### `getAllFlags(): FeatureFlag[]`
+
+Get all cached feature flags.
+
+### `initialize(): Promise<void>`
+
+Initialize the feature flag client. **This is the recommended method to call during application startup.**
+
+**Behavior:**
+
+- **If cached flags exist** (React/browser with localStorage): Returns immediately without fetching or blocking
+- **If no cache exists** (Node.js server startup or first-time browser load): Waits up to 2 seconds for the initial fetch, then resolves even if the request hasn't finished
+
+```typescript
+// React: instant return if cache exists, prevents flash screen
+await flagClient.initialize();
+
+// Node.js: waits for initial fetch since cache is always empty on restart
+await flagClient.initialize();
+```
+
+**Use cases:**
+
+- React/browser: Prevents blocking on page refresh when flags are cached
+- Node.js: Ensures flags are loaded before accepting requests
+
+### `async fetchFlags(): Promise<void>`
+
+Manually fetch flags from the API. Use this for manual refreshes after the initial setup.
+
+**Rate Limiting:** Respects the refresh interval. Multiple calls within the interval will return immediately without fetching. The interval uses a 60-second base and exponential backoff on failures (capped at 15 minutes).
+
+**Use cases:**
+
+- Manual refresh outside the automatic 60-second interval
+- Testing scenarios where you need deterministic flag state
+
+**Note:** `fetchFlags()` always respects the refresh interval. There is no force-refresh API; after calling `clearCache()`, the SDK will refresh on the next interval or when `initialize()` decides a fetch is needed.
+
+### `clearCache(): void`
+
+Clear all cached flags.
+
+### `getRefreshIntervalMs(): number`
+
+Returns the current refresh interval in milliseconds. The SDK uses a 60-second base interval and applies exponential backoff on failures, capped at 15 minutes.
+
+## API Response Format
+
+The Flaggy.io API returns feature flags in the following format:
+
+```json
+{
+  "data": [
+    {
+      "key": "dark-mode",
+      "enabled_production": true,
+      "enabled_staging": true,
+      "enabled_development": true
+    },
+    {
+      "key": "new-feature",
+      "enabled_production": false,
+      "enabled_staging": true,
+      "enabled_development": true
+    }
+  ]
+}
+```
+
+The SDK automatically:
+
+- Validates the API response structure
+- Filters out invalid flags
+- Checks the appropriate `enabled_*` field based on your configured environment
+- Sends your API key in the `x-api-key` header
+
+## License
+
+MIT © Flaggy.io

package/dist/index.cjs

@@ -0,0 +1,243 @@
+'use strict';
+
+// src/index.ts
+var LocalStorageAdapter = class {
+  get(key) {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return null;
+    }
+    try {
+      const data = window.localStorage.getItem(key);
+      return data ? JSON.parse(data) : null;
+    } catch (error) {
+      console.error("Error reading from localStorage:", error);
+      return null;
+    }
+  }
+  set(key, value) {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    try {
+      window.localStorage.setItem(key, JSON.stringify(value));
+    } catch (error) {
+      console.error("Error writing to localStorage:", error);
+    }
+  }
+  clear(key) {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    try {
+      window.localStorage.removeItem(key);
+    } catch (error) {
+      console.error("Error clearing localStorage:", error);
+    }
+  }
+};
+var InMemoryStorageAdapter = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  get(key) {
+    return this.store.get(key) || null;
+  }
+  set(key, value) {
+    this.store.set(key, value);
+  }
+  clear(key) {
+    this.store.delete(key);
+  }
+};
+var FeatureFlagClient = class {
+  constructor(config) {
+    this.flags = [];
+    this.lastFetch = 0;
+    this.isFetching = false;
+    this.fetchPromise = null;
+    this.failureCount = 0;
+    this.baseRefreshMs = 6e4;
+    this.maxRefreshMs = 15 * 60 * 1e3;
+    if (!config.apiKey || typeof config.apiKey !== "string") {
+      throw new Error("API key is required and must be a non-empty string");
+    }
+    if (config.apiKey.trim().length === 0) {
+      throw new Error("API key cannot be empty or whitespace");
+    }
+    this.config = config;
+    this.environment = config.environment === "production" || config.environment === "staging" || config.environment === "development" ? config.environment : "production";
+    this.storage = this.detectEnvironment() ? new LocalStorageAdapter() : new InMemoryStorageAdapter();
+    this.loadFromCache();
+    this.fetchFlags();
+  }
+  detectEnvironment() {
+    return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+  }
+  loadFromCache() {
+    const cached = this.storage.get("feature-flags");
+    if (cached && this.isValidCachedData(cached)) {
+      this.flags = cached.flags;
+      this.lastFetch = cached.timestamp || 0;
+    }
+  }
+  isValidCachedData(data) {
+    return data && typeof data === "object" && Array.isArray(data.flags) && data.flags.every(this.isValidFeatureFlag) && typeof data.timestamp === "number";
+  }
+  isValidFeatureFlag(flag) {
+    return flag && typeof flag === "object" && typeof flag.key === "string" && typeof flag.enabled_production === "boolean" && typeof flag.enabled_staging === "boolean" && typeof flag.enabled_development === "boolean";
+  }
+  saveToCache() {
+    this.storage.set("feature-flags", {
+      flags: this.flags,
+      timestamp: this.lastFetch
+    });
+  }
+  // Check if valid flags exist in cache
+  hasCachedFlags() {
+    const cached = this.storage.get("feature-flags");
+    return cached ? this.isValidCachedData(cached) : false;
+  }
+  // Check if cache interval has elapsed and a fetch is needed
+  shouldFetch() {
+    const now = Date.now();
+    return now - this.lastFetch > this.getRefreshIntervalMs();
+  }
+  // Exponential backoff: base * 2^failureCount (capped)
+  getRefreshIntervalMs() {
+    const backoffMs = this.baseRefreshMs * Math.pow(2, this.failureCount);
+    return Math.min(backoffMs, this.maxRefreshMs);
+  }
+  async fetchFlags() {
+    if (!this.shouldFetch()) {
+      return;
+    }
+    if (this.isFetching && this.fetchPromise) {
+      return this.fetchPromise;
+    }
+    this.isFetching = true;
+    this.fetchPromise = this.doFetch();
+    try {
+      await this.fetchPromise;
+    } finally {
+      this.isFetching = false;
+      this.fetchPromise = null;
+    }
+  }
+  async doFetch() {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 2e3);
+    try {
+      const response = await fetch(
+        "https://api.flaggy.io/public/feature-flags",
+        {
+          method: "GET",
+          headers: {
+            "x-api-key": this.config.apiKey,
+            "Content-Type": "application/json"
+          },
+          signal: controller.signal
+        }
+      );
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch feature flags: ${response.status} ${response.statusText}`
+        );
+      }
+      const json = await response.json();
+      if (!json || typeof json !== "object") {
+        throw new Error("Invalid API response: expected JSON object");
+      }
+      if (!json.data) {
+        throw new Error("Invalid API response: missing data property");
+      }
+      const data = json.data;
+      if (!Array.isArray(data)) {
+        throw new Error("Invalid API response: data must be an array");
+      }
+      this.flags = data.filter(this.isValidFeatureFlag);
+      if (data.length > 0 && this.flags.length === 0) {
+        console.warn(
+          "All feature flags in API response were invalid and filtered out"
+        );
+      }
+      this.lastFetch = Date.now();
+      this.failureCount = 0;
+      this.saveToCache();
+    } catch (error) {
+      this.failureCount += 1;
+      const err = error;
+      if (this.config.onError) {
+        this.config.onError(err);
+      }
+      if (err.name === "AbortError") {
+        console.warn("Feature flag fetch timed out");
+        return;
+      }
+      console.error("Error fetching feature flags:", err);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  initialize() {
+    if (this.hasCachedFlags()) {
+      return Promise.resolve();
+    }
+    if (!this.shouldFetch()) {
+      return Promise.resolve();
+    }
+    const timeoutMs = 2e3;
+    return Promise.race([
+      this.fetchFlags(),
+      new Promise((resolve) => {
+        setTimeout(resolve, timeoutMs);
+      })
+    ]);
+  }
+  isEnabled(flagName, defaultValue = false) {
+    if (this.shouldFetch() && !this.isFetching) {
+      this.fetchFlags();
+    }
+    const flag = this.flags.find((f) => f.key === flagName);
+    if (!flag) {
+      return defaultValue;
+    }
+    switch (this.environment) {
+      case "production":
+        return flag.enabled_production;
+      case "staging":
+        return flag.enabled_staging;
+      case "development":
+        return flag.enabled_development;
+      default:
+        return defaultValue;
+    }
+  }
+  getFlag(flagName) {
+    if (this.shouldFetch() && !this.isFetching) {
+      this.fetchFlags();
+    }
+    return this.flags.find((f) => f.key === flagName);
+  }
+  getAllFlags() {
+    return [...this.flags];
+  }
+  clearCache() {
+    this.storage.clear("feature-flags");
+    this.flags = [];
+  }
+  // Set custom storage adapter (useful for testing or custom implementations)
+  setStorageAdapter(adapter) {
+    this.storage = adapter;
+    this.loadFromCache();
+  }
+};
+var globalClient = null;
+function flaggy(config) {
+  if (globalClient) return globalClient;
+  globalClient = new FeatureFlagClient(config);
+  return globalClient;
+}
+
+exports.flaggy = flaggy;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["export interface FeatureFlag {\n  key: string;\n  enabled_production: boolean;\n  enabled_staging: boolean;\n  enabled_development: boolean;\n}\n\nexport interface FeatureFlagConfig {\n  apiKey: string;\n  environment?: \"production\" | \"staging\" | \"development\" | string;\n  onError?: (error: Error) => void;\n}\n\n// Storage adapter interface for custom implementations\nexport interface StorageAdapter {\n  get(key: string): CachedData | null;\n  set(key: string, value: CachedData): void;\n  clear(key: string): void;\n}\n\n// Storage adapter interface\ninterface CachedData {\n  flags: FeatureFlag[];\n  timestamp: number;\n}\n\n// LocalStorage adapter for browser\nclass LocalStorageAdapter implements StorageAdapter {\n  get(key: string): CachedData | null {\n    if (typeof window === \"undefined\" || !window.localStorage) {\n      return null;\n    }\n    try {\n      const data = window.localStorage.getItem(key);\n      return data ? JSON.parse(data) : null;\n    } catch (error) {\n      console.error(\"Error reading from localStorage:\", error);\n      return null;\n    }\n  }\n\n  set(key: string, value: CachedData): void {\n    if (typeof window === \"undefined\" || !window.localStorage) {\n      return;\n    }\n    try {\n      window.localStorage.setItem(key, JSON.stringify(value));\n    } catch (error) {\n      console.error(\"Error writing to localStorage:\", error);\n    }\n  }\n\n  clear(key: string): void {\n    if (typeof window === \"undefined\" || !window.localStorage) {\n      return;\n    }\n    try {\n      window.localStorage.removeItem(key);\n    } catch (error) {\n      console.error(\"Error clearing localStorage:\", error);\n    }\n  }\n}\n\n// In-memory adapter for server-side\nclass InMemoryStorageAdapter implements StorageAdapter {\n  private store: Map<string, CachedData> = new Map();\n\n  get(key: string): CachedData | null {\n    return this.store.get(key) || null;\n  }\n\n  set(key: string, value: CachedData): void {\n    this.store.set(key, value);\n  }\n\n  clear(key: string): void {\n    this.store.delete(key);\n  }\n}\n\nclass FeatureFlagClient {\n  private config: FeatureFlagConfig;\n  private storage: StorageAdapter;\n  private flags: FeatureFlag[] = [];\n  private lastFetch: number = 0;\n  private isFetching: boolean = false;\n  private fetchPromise: Promise<void> | null = null;\n  private environment: \"production\" | \"staging\" | \"development\";\n  private failureCount: number = 0;\n  private readonly baseRefreshMs: number = 60000;\n  private readonly maxRefreshMs: number = 15 * 60 * 1000;\n\n  constructor(config: FeatureFlagConfig) {\n    // Validate API key\n    if (!config.apiKey || typeof config.apiKey !== \"string\") {\n      throw new Error(\"API key is required and must be a non-empty string\");\n    }\n\n    if (config.apiKey.trim().length === 0) {\n      throw new Error(\"API key cannot be empty or whitespace\");\n    }\n\n    this.config = config;\n    this.environment =\n      config.environment === \"production\" ||\n      config.environment === \"staging\" ||\n      config.environment === \"development\"\n        ? config.environment\n        : \"production\";\n\n    // Auto-detect environment and use appropriate storage\n    this.storage = this.detectEnvironment()\n      ? new LocalStorageAdapter()\n      : new InMemoryStorageAdapter();\n\n    // Load cached flags on initialization\n    this.loadFromCache();\n\n    // Auto-fetch flags in background (fire and forget)\n    this.fetchFlags();\n  }\n\n  private detectEnvironment(): boolean {\n    return (\n      typeof window !== \"undefined\" &&\n      typeof window.localStorage !== \"undefined\"\n    );\n  }\n\n  private loadFromCache(): void {\n    const cached = this.storage.get(\"feature-flags\");\n    if (cached && this.isValidCachedData(cached)) {\n      this.flags = cached.flags;\n      this.lastFetch = cached.timestamp || 0;\n    }\n  }\n\n  private isValidCachedData(data: any): data is CachedData {\n    return (\n      data &&\n      typeof data === \"object\" &&\n      Array.isArray(data.flags) &&\n      data.flags.every(this.isValidFeatureFlag) &&\n      typeof data.timestamp === \"number\"\n    );\n  }\n\n  private isValidFeatureFlag(flag: any): flag is FeatureFlag {\n    return (\n      flag &&\n      typeof flag === \"object\" &&\n      typeof flag.key === \"string\" &&\n      typeof flag.enabled_production === \"boolean\" &&\n      typeof flag.enabled_staging === \"boolean\" &&\n      typeof flag.enabled_development === \"boolean\"\n    );\n  }\n\n  private saveToCache(): void {\n    this.storage.set(\"feature-flags\", {\n      flags: this.flags,\n      timestamp: this.lastFetch,\n    });\n  }\n\n  // Check if valid flags exist in cache\n  private hasCachedFlags(): boolean {\n    const cached = this.storage.get(\"feature-flags\");\n    return cached ? this.isValidCachedData(cached) : false;\n  }\n\n  // Check if cache interval has elapsed and a fetch is needed\n  private shouldFetch(): boolean {\n    const now = Date.now();\n    return now - this.lastFetch > this.getRefreshIntervalMs();\n  }\n\n  // Exponential backoff: base * 2^failureCount (capped)\n  getRefreshIntervalMs(): number {\n    const backoffMs = this.baseRefreshMs * Math.pow(2, this.failureCount);\n    return Math.min(backoffMs, this.maxRefreshMs);\n  }\n\n  async fetchFlags(): Promise<void> {\n    if (!this.shouldFetch()) {\n      return;\n    }\n\n    // If already fetching, return the existing promise\n    if (this.isFetching && this.fetchPromise) {\n      return this.fetchPromise;\n    }\n\n    this.isFetching = true;\n    this.fetchPromise = this.doFetch();\n\n    try {\n      await this.fetchPromise;\n    } finally {\n      this.isFetching = false;\n      this.fetchPromise = null;\n    }\n  }\n\n  private async doFetch(): Promise<void> {\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), 2000);\n\n    try {\n      const response = await fetch(\n        \"https://api.flaggy.io/public/feature-flags\",\n        {\n          method: \"GET\",\n          headers: {\n            \"x-api-key\": this.config.apiKey,\n            \"Content-Type\": \"application/json\",\n          },\n          signal: controller.signal,\n        },\n      );\n\n      if (!response.ok) {\n        throw new Error(\n          `Failed to fetch feature flags: ${response.status} ${response.statusText}`,\n        );\n      }\n\n      const json = await response.json();\n\n      // Validate response structure\n      if (!json || typeof json !== \"object\") {\n        throw new Error(\"Invalid API response: expected JSON object\");\n      }\n\n      if (!json.data) {\n        throw new Error(\"Invalid API response: missing data property\");\n      }\n\n      const data = json.data;\n\n      // Validate and filter feature flags\n      if (!Array.isArray(data)) {\n        throw new Error(\"Invalid API response: data must be an array\");\n      }\n\n      // Filter out invalid flags and keep only valid ones\n      this.flags = data.filter(this.isValidFeatureFlag);\n\n      if (data.length > 0 && this.flags.length === 0) {\n        console.warn(\n          \"All feature flags in API response were invalid and filtered out\",\n        );\n      }\n\n      this.lastFetch = Date.now();\n      this.failureCount = 0;\n      this.saveToCache();\n    } catch (error) {\n      this.failureCount += 1;\n      const err = error as Error;\n      if (this.config.onError) {\n        this.config.onError(err);\n      }\n      if (err.name === \"AbortError\") {\n        console.warn(\"Feature flag fetch timed out\");\n        return;\n      }\n      console.error(\"Error fetching feature flags:\", err);\n    } finally {\n      clearTimeout(timeoutId);\n    }\n  }\n\n  initialize(): Promise<void> {\n    if (this.hasCachedFlags()) {\n      return Promise.resolve();\n    }\n\n    if (!this.shouldFetch()) {\n      return Promise.resolve();\n    }\n\n    const timeoutMs = 2000;\n    return Promise.race([\n      this.fetchFlags(),\n      new Promise<void>((resolve) => {\n        setTimeout(resolve, timeoutMs);\n      }),\n    ]);\n  }\n\n  isEnabled(flagName: string, defaultValue: boolean = false): boolean {\n    // Auto-refresh if needed\n    if (this.shouldFetch() && !this.isFetching) {\n      this.fetchFlags(); // Fire and forget\n    }\n\n    const flag = this.flags.find((f) => f.key === flagName);\n    if (!flag) {\n      return defaultValue; // Return provided default for unknown flags\n    }\n\n    // Check the environment-specific enabled field\n    switch (this.environment) {\n      case \"production\":\n        return flag.enabled_production;\n      case \"staging\":\n        return flag.enabled_staging;\n      case \"development\":\n        return flag.enabled_development;\n      default:\n        return defaultValue;\n    }\n  }\n\n  getFlag(flagName: string): FeatureFlag | undefined {\n    // Auto-refresh if needed\n    if (this.shouldFetch() && !this.isFetching) {\n      this.fetchFlags(); // Fire and forget\n    }\n\n    return this.flags.find((f) => f.key === flagName);\n  }\n\n  getAllFlags(): FeatureFlag[] {\n    return [...this.flags];\n  }\n\n  clearCache(): void {\n    this.storage.clear(\"feature-flags\");\n    this.flags = [];\n  }\n\n  // Set custom storage adapter (useful for testing or custom implementations)\n  setStorageAdapter(adapter: StorageAdapter): void {\n    this.storage = adapter;\n    this.loadFromCache();\n  }\n}\n\nlet globalClient: FeatureFlagClient | null = null;\n\nexport function flaggy(config: FeatureFlagConfig): FeatureFlagClient {\n  if (globalClient) return globalClient;\n\n  globalClient = new FeatureFlagClient(config);\n  return globalClient;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+interface FeatureFlag {
+    key: string;
+    enabled_production: boolean;
+    enabled_staging: boolean;
+    enabled_development: boolean;
+}
+interface FeatureFlagConfig {
+    apiKey: string;
+    environment?: "production" | "staging" | "development" | string;
+    onError?: (error: Error) => void;
+}
+interface StorageAdapter {
+    get(key: string): CachedData | null;
+    set(key: string, value: CachedData): void;
+    clear(key: string): void;
+}
+interface CachedData {
+    flags: FeatureFlag[];
+    timestamp: number;
+}
+declare class FeatureFlagClient {
+    private config;
+    private storage;
+    private flags;
+    private lastFetch;
+    private isFetching;
+    private fetchPromise;
+    private environment;
+    private failureCount;
+    private readonly baseRefreshMs;
+    private readonly maxRefreshMs;
+    constructor(config: FeatureFlagConfig);
+    private detectEnvironment;
+    private loadFromCache;
+    private isValidCachedData;
+    private isValidFeatureFlag;
+    private saveToCache;
+    private hasCachedFlags;
+    private shouldFetch;
+    getRefreshIntervalMs(): number;
+    fetchFlags(): Promise<void>;
+    private doFetch;
+    initialize(): Promise<void>;
+    isEnabled(flagName: string, defaultValue?: boolean): boolean;
+    getFlag(flagName: string): FeatureFlag | undefined;
+    getAllFlags(): FeatureFlag[];
+    clearCache(): void;
+    setStorageAdapter(adapter: StorageAdapter): void;
+}
+declare function flaggy(config: FeatureFlagConfig): FeatureFlagClient;
+
+export { type FeatureFlag, type FeatureFlagConfig, type StorageAdapter, flaggy };

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+interface FeatureFlag {
+    key: string;
+    enabled_production: boolean;
+    enabled_staging: boolean;
+    enabled_development: boolean;
+}
+interface FeatureFlagConfig {
+    apiKey: string;
+    environment?: "production" | "staging" | "development" | string;
+    onError?: (error: Error) => void;
+}
+interface StorageAdapter {
+    get(key: string): CachedData | null;
+    set(key: string, value: CachedData): void;
+    clear(key: string): void;
+}
+interface CachedData {
+    flags: FeatureFlag[];
+    timestamp: number;
+}
+declare class FeatureFlagClient {
+    private config;
+    private storage;
+    private flags;
+    private lastFetch;
+    private isFetching;
+    private fetchPromise;
+    private environment;
+    private failureCount;
+    private readonly baseRefreshMs;
+    private readonly maxRefreshMs;
+    constructor(config: FeatureFlagConfig);
+    private detectEnvironment;
+    private loadFromCache;
+    private isValidCachedData;
+    private isValidFeatureFlag;
+    private saveToCache;
+    private hasCachedFlags;
+    private shouldFetch;
+    getRefreshIntervalMs(): number;
+    fetchFlags(): Promise<void>;
+    private doFetch;
+    initialize(): Promise<void>;
+    isEnabled(flagName: string, defaultValue?: boolean): boolean;
+    getFlag(flagName: string): FeatureFlag | undefined;
+    getAllFlags(): FeatureFlag[];
+    clearCache(): void;
+    setStorageAdapter(adapter: StorageAdapter): void;
+}
+declare function flaggy(config: FeatureFlagConfig): FeatureFlagClient;
+
+export { type FeatureFlag, type FeatureFlagConfig, type StorageAdapter, flaggy };

package/dist/index.js

@@ -0,0 +1,241 @@
+// src/index.ts
+var LocalStorageAdapter = class {
+  get(key) {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return null;
+    }
+    try {
+      const data = window.localStorage.getItem(key);
+      return data ? JSON.parse(data) : null;
+    } catch (error) {
+      console.error("Error reading from localStorage:", error);
+      return null;
+    }
+  }
+  set(key, value) {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    try {
+      window.localStorage.setItem(key, JSON.stringify(value));
+    } catch (error) {
+      console.error("Error writing to localStorage:", error);
+    }
+  }
+  clear(key) {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    try {
+      window.localStorage.removeItem(key);
+    } catch (error) {
+      console.error("Error clearing localStorage:", error);
+    }
+  }
+};
+var InMemoryStorageAdapter = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  get(key) {
+    return this.store.get(key) || null;
+  }
+  set(key, value) {
+    this.store.set(key, value);
+  }
+  clear(key) {
+    this.store.delete(key);
+  }
+};
+var FeatureFlagClient = class {
+  constructor(config) {
+    this.flags = [];
+    this.lastFetch = 0;
+    this.isFetching = false;
+    this.fetchPromise = null;
+    this.failureCount = 0;
+    this.baseRefreshMs = 6e4;
+    this.maxRefreshMs = 15 * 60 * 1e3;
+    if (!config.apiKey || typeof config.apiKey !== "string") {
+      throw new Error("API key is required and must be a non-empty string");
+    }
+    if (config.apiKey.trim().length === 0) {
+      throw new Error("API key cannot be empty or whitespace");
+    }
+    this.config = config;
+    this.environment = config.environment === "production" || config.environment === "staging" || config.environment === "development" ? config.environment : "production";
+    this.storage = this.detectEnvironment() ? new LocalStorageAdapter() : new InMemoryStorageAdapter();
+    this.loadFromCache();
+    this.fetchFlags();
+  }
+  detectEnvironment() {
+    return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+  }
+  loadFromCache() {
+    const cached = this.storage.get("feature-flags");
+    if (cached && this.isValidCachedData(cached)) {
+      this.flags = cached.flags;
+      this.lastFetch = cached.timestamp || 0;
+    }
+  }
+  isValidCachedData(data) {
+    return data && typeof data === "object" && Array.isArray(data.flags) && data.flags.every(this.isValidFeatureFlag) && typeof data.timestamp === "number";
+  }
+  isValidFeatureFlag(flag) {
+    return flag && typeof flag === "object" && typeof flag.key === "string" && typeof flag.enabled_production === "boolean" && typeof flag.enabled_staging === "boolean" && typeof flag.enabled_development === "boolean";
+  }
+  saveToCache() {
+    this.storage.set("feature-flags", {
+      flags: this.flags,
+      timestamp: this.lastFetch
+    });
+  }
+  // Check if valid flags exist in cache
+  hasCachedFlags() {
+    const cached = this.storage.get("feature-flags");
+    return cached ? this.isValidCachedData(cached) : false;
+  }
+  // Check if cache interval has elapsed and a fetch is needed
+  shouldFetch() {
+    const now = Date.now();
+    return now - this.lastFetch > this.getRefreshIntervalMs();
+  }
+  // Exponential backoff: base * 2^failureCount (capped)
+  getRefreshIntervalMs() {
+    const backoffMs = this.baseRefreshMs * Math.pow(2, this.failureCount);
+    return Math.min(backoffMs, this.maxRefreshMs);
+  }
+  async fetchFlags() {
+    if (!this.shouldFetch()) {
+      return;
+    }
+    if (this.isFetching && this.fetchPromise) {
+      return this.fetchPromise;
+    }
+    this.isFetching = true;
+    this.fetchPromise = this.doFetch();
+    try {
+      await this.fetchPromise;
+    } finally {
+      this.isFetching = false;
+      this.fetchPromise = null;
+    }
+  }
+  async doFetch() {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 2e3);
+    try {
+      const response = await fetch(
+        "https://api.flaggy.io/public/feature-flags",
+        {
+          method: "GET",
+          headers: {
+            "x-api-key": this.config.apiKey,
+            "Content-Type": "application/json"
+          },
+          signal: controller.signal
+        }
+      );
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch feature flags: ${response.status} ${response.statusText}`
+        );
+      }
+      const json = await response.json();
+      if (!json || typeof json !== "object") {
+        throw new Error("Invalid API response: expected JSON object");
+      }
+      if (!json.data) {
+        throw new Error("Invalid API response: missing data property");
+      }
+      const data = json.data;
+      if (!Array.isArray(data)) {
+        throw new Error("Invalid API response: data must be an array");
+      }
+      this.flags = data.filter(this.isValidFeatureFlag);
+      if (data.length > 0 && this.flags.length === 0) {
+        console.warn(
+          "All feature flags in API response were invalid and filtered out"
+        );
+      }
+      this.lastFetch = Date.now();
+      this.failureCount = 0;
+      this.saveToCache();
+    } catch (error) {
+      this.failureCount += 1;
+      const err = error;
+      if (this.config.onError) {
+        this.config.onError(err);
+      }
+      if (err.name === "AbortError") {
+        console.warn("Feature flag fetch timed out");
+        return;
+      }
+      console.error("Error fetching feature flags:", err);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  initialize() {
+    if (this.hasCachedFlags()) {
+      return Promise.resolve();
+    }
+    if (!this.shouldFetch()) {
+      return Promise.resolve();
+    }
+    const timeoutMs = 2e3;
+    return Promise.race([
+      this.fetchFlags(),
+      new Promise((resolve) => {
+        setTimeout(resolve, timeoutMs);
+      })
+    ]);
+  }
+  isEnabled(flagName, defaultValue = false) {
+    if (this.shouldFetch() && !this.isFetching) {
+      this.fetchFlags();
+    }
+    const flag = this.flags.find((f) => f.key === flagName);
+    if (!flag) {
+      return defaultValue;
+    }
+    switch (this.environment) {
+      case "production":
+        return flag.enabled_production;
+      case "staging":
+        return flag.enabled_staging;
+      case "development":
+        return flag.enabled_development;
+      default:
+        return defaultValue;
+    }
+  }
+  getFlag(flagName) {
+    if (this.shouldFetch() && !this.isFetching) {
+      this.fetchFlags();
+    }
+    return this.flags.find((f) => f.key === flagName);
+  }
+  getAllFlags() {
+    return [...this.flags];
+  }
+  clearCache() {
+    this.storage.clear("feature-flags");
+    this.flags = [];
+  }
+  // Set custom storage adapter (useful for testing or custom implementations)
+  setStorageAdapter(adapter) {
+    this.storage = adapter;
+    this.loadFromCache();
+  }
+};
+var globalClient = null;
+function flaggy(config) {
+  if (globalClient) return globalClient;
+  globalClient = new FeatureFlagClient(config);
+  return globalClient;
+}
+
+export { flaggy };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["export interface FeatureFlag {\n  key: string;\n  enabled_production: boolean;\n  enabled_staging: boolean;\n  enabled_development: boolean;\n}\n\nexport interface FeatureFlagConfig {\n  apiKey: string;\n  environment?: \"production\" | \"staging\" | \"development\" | string;\n  onError?: (error: Error) => void;\n}\n\n// Storage adapter interface for custom implementations\nexport interface StorageAdapter {\n  get(key: string): CachedData | null;\n  set(key: string, value: CachedData): void;\n  clear(key: string): void;\n}\n\n// Storage adapter interface\ninterface CachedData {\n  flags: FeatureFlag[];\n  timestamp: number;\n}\n\n// LocalStorage adapter for browser\nclass LocalStorageAdapter implements StorageAdapter {\n  get(key: string): CachedData | null {\n    if (typeof window === \"undefined\" || !window.localStorage) {\n      return null;\n    }\n    try {\n      const data = window.localStorage.getItem(key);\n      return data ? JSON.parse(data) : null;\n    } catch (error) {\n      console.error(\"Error reading from localStorage:\", error);\n      return null;\n    }\n  }\n\n  set(key: string, value: CachedData): void {\n    if (typeof window === \"undefined\" || !window.localStorage) {\n      return;\n    }\n    try {\n      window.localStorage.setItem(key, JSON.stringify(value));\n    } catch (error) {\n      console.error(\"Error writing to localStorage:\", error);\n    }\n  }\n\n  clear(key: string): void {\n    if (typeof window === \"undefined\" || !window.localStorage) {\n      return;\n    }\n    try {\n      window.localStorage.removeItem(key);\n    } catch (error) {\n      console.error(\"Error clearing localStorage:\", error);\n    }\n  }\n}\n\n// In-memory adapter for server-side\nclass InMemoryStorageAdapter implements StorageAdapter {\n  private store: Map<string, CachedData> = new Map();\n\n  get(key: string): CachedData | null {\n    return this.store.get(key) || null;\n  }\n\n  set(key: string, value: CachedData): void {\n    this.store.set(key, value);\n  }\n\n  clear(key: string): void {\n    this.store.delete(key);\n  }\n}\n\nclass FeatureFlagClient {\n  private config: FeatureFlagConfig;\n  private storage: StorageAdapter;\n  private flags: FeatureFlag[] = [];\n  private lastFetch: number = 0;\n  private isFetching: boolean = false;\n  private fetchPromise: Promise<void> | null = null;\n  private environment: \"production\" | \"staging\" | \"development\";\n  private failureCount: number = 0;\n  private readonly baseRefreshMs: number = 60000;\n  private readonly maxRefreshMs: number = 15 * 60 * 1000;\n\n  constructor(config: FeatureFlagConfig) {\n    // Validate API key\n    if (!config.apiKey || typeof config.apiKey !== \"string\") {\n      throw new Error(\"API key is required and must be a non-empty string\");\n    }\n\n    if (config.apiKey.trim().length === 0) {\n      throw new Error(\"API key cannot be empty or whitespace\");\n    }\n\n    this.config = config;\n    this.environment =\n      config.environment === \"production\" ||\n      config.environment === \"staging\" ||\n      config.environment === \"development\"\n        ? config.environment\n        : \"production\";\n\n    // Auto-detect environment and use appropriate storage\n    this.storage = this.detectEnvironment()\n      ? new LocalStorageAdapter()\n      : new InMemoryStorageAdapter();\n\n    // Load cached flags on initialization\n    this.loadFromCache();\n\n    // Auto-fetch flags in background (fire and forget)\n    this.fetchFlags();\n  }\n\n  private detectEnvironment(): boolean {\n    return (\n      typeof window !== \"undefined\" &&\n      typeof window.localStorage !== \"undefined\"\n    );\n  }\n\n  private loadFromCache(): void {\n    const cached = this.storage.get(\"feature-flags\");\n    if (cached && this.isValidCachedData(cached)) {\n      this.flags = cached.flags;\n      this.lastFetch = cached.timestamp || 0;\n    }\n  }\n\n  private isValidCachedData(data: any): data is CachedData {\n    return (\n      data &&\n      typeof data === \"object\" &&\n      Array.isArray(data.flags) &&\n      data.flags.every(this.isValidFeatureFlag) &&\n      typeof data.timestamp === \"number\"\n    );\n  }\n\n  private isValidFeatureFlag(flag: any): flag is FeatureFlag {\n    return (\n      flag &&\n      typeof flag === \"object\" &&\n      typeof flag.key === \"string\" &&\n      typeof flag.enabled_production === \"boolean\" &&\n      typeof flag.enabled_staging === \"boolean\" &&\n      typeof flag.enabled_development === \"boolean\"\n    );\n  }\n\n  private saveToCache(): void {\n    this.storage.set(\"feature-flags\", {\n      flags: this.flags,\n      timestamp: this.lastFetch,\n    });\n  }\n\n  // Check if valid flags exist in cache\n  private hasCachedFlags(): boolean {\n    const cached = this.storage.get(\"feature-flags\");\n    return cached ? this.isValidCachedData(cached) : false;\n  }\n\n  // Check if cache interval has elapsed and a fetch is needed\n  private shouldFetch(): boolean {\n    const now = Date.now();\n    return now - this.lastFetch > this.getRefreshIntervalMs();\n  }\n\n  // Exponential backoff: base * 2^failureCount (capped)\n  getRefreshIntervalMs(): number {\n    const backoffMs = this.baseRefreshMs * Math.pow(2, this.failureCount);\n    return Math.min(backoffMs, this.maxRefreshMs);\n  }\n\n  async fetchFlags(): Promise<void> {\n    if (!this.shouldFetch()) {\n      return;\n    }\n\n    // If already fetching, return the existing promise\n    if (this.isFetching && this.fetchPromise) {\n      return this.fetchPromise;\n    }\n\n    this.isFetching = true;\n    this.fetchPromise = this.doFetch();\n\n    try {\n      await this.fetchPromise;\n    } finally {\n      this.isFetching = false;\n      this.fetchPromise = null;\n    }\n  }\n\n  private async doFetch(): Promise<void> {\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), 2000);\n\n    try {\n      const response = await fetch(\n        \"https://api.flaggy.io/public/feature-flags\",\n        {\n          method: \"GET\",\n          headers: {\n            \"x-api-key\": this.config.apiKey,\n            \"Content-Type\": \"application/json\",\n          },\n          signal: controller.signal,\n        },\n      );\n\n      if (!response.ok) {\n        throw new Error(\n          `Failed to fetch feature flags: ${response.status} ${response.statusText}`,\n        );\n      }\n\n      const json = await response.json();\n\n      // Validate response structure\n      if (!json || typeof json !== \"object\") {\n        throw new Error(\"Invalid API response: expected JSON object\");\n      }\n\n      if (!json.data) {\n        throw new Error(\"Invalid API response: missing data property\");\n      }\n\n      const data = json.data;\n\n      // Validate and filter feature flags\n      if (!Array.isArray(data)) {\n        throw new Error(\"Invalid API response: data must be an array\");\n      }\n\n      // Filter out invalid flags and keep only valid ones\n      this.flags = data.filter(this.isValidFeatureFlag);\n\n      if (data.length > 0 && this.flags.length === 0) {\n        console.warn(\n          \"All feature flags in API response were invalid and filtered out\",\n        );\n      }\n\n      this.lastFetch = Date.now();\n      this.failureCount = 0;\n      this.saveToCache();\n    } catch (error) {\n      this.failureCount += 1;\n      const err = error as Error;\n      if (this.config.onError) {\n        this.config.onError(err);\n      }\n      if (err.name === \"AbortError\") {\n        console.warn(\"Feature flag fetch timed out\");\n        return;\n      }\n      console.error(\"Error fetching feature flags:\", err);\n    } finally {\n      clearTimeout(timeoutId);\n    }\n  }\n\n  initialize(): Promise<void> {\n    if (this.hasCachedFlags()) {\n      return Promise.resolve();\n    }\n\n    if (!this.shouldFetch()) {\n      return Promise.resolve();\n    }\n\n    const timeoutMs = 2000;\n    return Promise.race([\n      this.fetchFlags(),\n      new Promise<void>((resolve) => {\n        setTimeout(resolve, timeoutMs);\n      }),\n    ]);\n  }\n\n  isEnabled(flagName: string, defaultValue: boolean = false): boolean {\n    // Auto-refresh if needed\n    if (this.shouldFetch() && !this.isFetching) {\n      this.fetchFlags(); // Fire and forget\n    }\n\n    const flag = this.flags.find((f) => f.key === flagName);\n    if (!flag) {\n      return defaultValue; // Return provided default for unknown flags\n    }\n\n    // Check the environment-specific enabled field\n    switch (this.environment) {\n      case \"production\":\n        return flag.enabled_production;\n      case \"staging\":\n        return flag.enabled_staging;\n      case \"development\":\n        return flag.enabled_development;\n      default:\n        return defaultValue;\n    }\n  }\n\n  getFlag(flagName: string): FeatureFlag | undefined {\n    // Auto-refresh if needed\n    if (this.shouldFetch() && !this.isFetching) {\n      this.fetchFlags(); // Fire and forget\n    }\n\n    return this.flags.find((f) => f.key === flagName);\n  }\n\n  getAllFlags(): FeatureFlag[] {\n    return [...this.flags];\n  }\n\n  clearCache(): void {\n    this.storage.clear(\"feature-flags\");\n    this.flags = [];\n  }\n\n  // Set custom storage adapter (useful for testing or custom implementations)\n  setStorageAdapter(adapter: StorageAdapter): void {\n    this.storage = adapter;\n    this.loadFromCache();\n  }\n}\n\nlet globalClient: FeatureFlagClient | null = null;\n\nexport function flaggy(config: FeatureFlagConfig): FeatureFlagClient {\n  if (globalClient) return globalClient;\n\n  globalClient = new FeatureFlagClient(config);\n  return globalClient;\n}\n"]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@flaggy.io/sdk-js",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for Flaggy.io feature flag management",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "flaggy",
+    "typescript",
+    "sdk"
+  ],
+  "author": "Flaggy.io",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flaggy-io/sdk-js"
+  },
+  "homepage": "https://flaggy.io",
+  "bugs": {
+    "url": "https://github.com/flaggy-io/sdk-js/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}