@flagged-dev/sdk

TypeScript SDK for Flagged — Feature Flags for Indie Devs.

Zero dependencies. Works in browsers, Node.js 18+, and edge runtimes.

Install

npm install @flagged-dev/sdk

Quick Start

import { Flagged } from "@flagged-dev/sdk";

const fg = new Flagged({
  apiKey: "fg_your_api_key",
  defaults: {
    new_checkout: false,
    dark_mode: true,
  },
});

await fg.init();

if (fg.isEnabled("new_checkout")) {
  // New feature code
}

Options

new Flagged({
  apiKey: string;               // Required
  defaults?: Record<string, boolean>;  // Fallback values
  pollInterval?: number;        // Default: 60000 (ms). 0 = no polling
  timeout?: number;             // Default: 3000 (ms)
  staleWhileRevalidate?: boolean;  // Default: true
  storageKey?: string | null;   // Default: "flagged". null = disable localStorage
  baseUrl?: string;             // Override API endpoint
});

API

Core

fg.isEnabled(key: string): boolean   // Always returns boolean, never undefined
fg.getFlags(): Record<string, boolean>

Events

fg.on("change", (flags) => {
  console.log("Flags updated:", flags);
});

fg.on("error", (error) => {
  console.warn("Flagged fetch failed:", error);
});

fg.on("source", (source) => {
  // "api" | "memory" | "storage" | "defaults"
  console.log("Flags served from:", source);
});

fg.off("change", listener);  // Remove listener

Lifecycle

fg.stop();          // Stop polling
await fg.refresh(); // Manual one-shot fetch
fg.destroy();       // Stop + cleanup

Fallback Strategy

Flagged is designed so your app never breaks, even if the API is down:

1. Memory cache — instant, always checked first
2. localStorage — survives page reloads (browser only)
3. defaults — your safety net, defined in code

License

MIT