@flagify/node 1.0.0

package/README.md

@@ -0,0 +1,246 @@
+<p align="center">
+  <a href="https://flagify.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://flagify.dev/logo-white.svg" />
+      <source media="(prefers-color-scheme: light)" srcset="https://flagify.dev/logo-color.svg" />
+      <img alt="Flagify" src="https://flagify.dev/logo-color.svg" width="280" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <strong>Feature flags for modern teams</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@flagify/node"><img src="https://img.shields.io/npm/v/@flagify/node.svg?style=flat-square&color=0D80F9" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@flagify/node"><img src="https://img.shields.io/npm/dm/@flagify/node.svg?style=flat-square&color=0D80F9" alt="npm downloads" /></a>
+  <a href="https://github.com/flagifyhq/node-sdk/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@flagify/node.svg?style=flat-square&color=0D80F9" alt="license" /></a>
+  <a href="https://github.com/flagifyhq/node-sdk"><img src="https://img.shields.io/github/stars/flagifyhq/node-sdk?style=flat-square&color=0D80F9" alt="github stars" /></a>
+</p>
+
+<p align="center">
+  <a href="https://flagify.dev/docs">Documentation</a> &middot;
+  <a href="https://flagify.dev/docs/sdks/node">SDK Reference</a> &middot;
+  <a href="https://github.com/flagifyhq/node-sdk/issues">Issues</a> &middot;
+  <a href="https://flagify.dev">Website</a>
+</p>
+
+---
+
+## Overview
+
+`@flagify/node` is the official Node.js SDK for [Flagify](https://flagify.dev). TypeScript-first, with in-memory caching and sub-millisecond flag evaluation.
+
+- **TypeScript-first** -- Full type safety with generics support
+- **In-memory cache** -- Sub-millisecond evaluations after initial sync
+- **Stale-while-revalidate** -- Serves cached values while refreshing in the background
+- **Lightweight** -- Zero runtime dependencies (except `dotenv`)
+- **Isomorphic** -- ESM and CommonJS output
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [API reference](#api-reference)
+- [How it works](#how-it-works)
+- [Environment variables](#environment-variables)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+```bash
+# pnpm
+pnpm add @flagify/node
+
+# npm
+npm install @flagify/node
+
+# yarn
+yarn add @flagify/node
+```
+
+## Quick start
+
+```typescript
+import { Flagify } from '@flagify/node'
+
+const flagify = new Flagify({
+  projectKey: 'proj_xxx',
+  publicKey: 'pk_xxx',
+})
+
+// Boolean flag
+if (flagify.isEnabled('new-checkout')) {
+  showNewCheckout()
+}
+
+// Typed value
+const limit = flagify.getValue<number>('rate-limit')
+```
+
+## Configuration
+
+```typescript
+import { Flagify } from '@flagify/node'
+
+const flagify = new Flagify({
+  // Required
+  projectKey: 'proj_xxx',
+  publicKey: 'pk_xxx',
+
+  // Optional -- server-side only, never expose in client bundles
+  secretKey: 'sk_xxx',
+
+  options: {
+    // Custom API endpoint (defaults to https://api.flagify.dev)
+    apiUrl: 'https://api.flagify.dev',
+
+    // Cache TTL in ms (default: 5 minutes)
+    staleTimeMs: 300_000,
+
+    // Real-time updates via SSE (coming soon)
+    realtime: false,
+
+    // User context for targeting rules
+    user: {
+      id: 'user_123',
+      email: 'mario@example.com',
+      role: 'admin',
+      group: 'engineering',
+      geolocation: {
+        country: 'US',
+        region: 'CA',
+        city: 'San Francisco',
+      },
+      // Custom attributes
+      plan: 'enterprise',
+      companySize: 50,
+    },
+  },
+})
+```
+
+### Configuration options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `projectKey` | `string` | Yes | -- | Project identifier from your Flagify workspace |
+| `publicKey` | `string` | Yes | -- | Client-safe publishable API key |
+| `secretKey` | `string` | No | -- | Server-side secret key |
+| `options.apiUrl` | `string` | No | `https://api.flagify.dev` | Custom API base URL |
+| `options.staleTimeMs` | `number` | No | `300000` | Cache staleness threshold in ms |
+| `options.realtime` | `boolean` | No | `false` | Enable real-time SSE updates |
+| `options.user` | `FlagifyUser` | No | -- | User context for targeting |
+
+## API reference
+
+### `new Flagify(config: FlagifyOptions)`
+
+Creates a new Flagify client. Immediately fetches all flags and populates the local cache.
+
+```typescript
+const flagify = new Flagify({
+  projectKey: 'proj_xxx',
+  publicKey: 'pk_xxx',
+})
+```
+
+---
+
+### `flagify.isEnabled(flagKey: string): boolean`
+
+Evaluates a boolean feature flag.
+
+Returns `false` when:
+- The flag does not exist
+- The flag is disabled
+- The flag type is not `boolean`
+
+```typescript
+if (flagify.isEnabled('dark-mode')) {
+  applyDarkTheme()
+}
+```
+
+---
+
+### `flagify.getValue<T>(flagKey: string): T`
+
+Returns the resolved value of a feature flag with TypeScript generics.
+
+```typescript
+// String variant
+const variant = flagify.getValue<string>('checkout-flow')
+
+// Number
+const limit = flagify.getValue<number>('rate-limit')
+
+// JSON object
+const config = flagify.getValue<{ maxRetries: number; timeout: number }>('api-config')
+```
+
+## How it works
+
+```
+  Init                    Evaluate               Stale?
+  ----                    --------               ------
+  GET /v1/flags    -->    Read from cache   -->  Background refetch
+  Cache all flags         Sub-ms response        GET /v1/flags/:key
+                                                 Return stale value immediately
+```
+
+1. On initialization, the client syncs all flags from `GET /v1/flags`
+2. All evaluations read from the in-memory `Map` cache -- sub-millisecond
+3. When a flag exceeds `staleTimeMs`, the stale value is returned immediately while a background `GET /v1/flags/:key` refreshes the cache
+4. If the API is unreachable, the client falls back to cached defaults
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `FLAGIFY_API_URL` | Override the default API base URL |
+
+## Types
+
+All types are exported for convenience:
+
+```typescript
+import type {
+  FlagifyOptions,
+  FlagifyUser,
+  FlagifyFlaggy,
+  IFlagifyClient,
+} from '@flagify/node'
+```
+
+## Contributing
+
+We welcome contributions. Please open an issue first to discuss what you'd like to change.
+
+```bash
+# Clone
+git clone https://github.com/flagifyhq/node-sdk.git
+cd node-sdk
+
+# Install
+pnpm install
+
+# Development
+pnpm run dev
+
+# Build
+pnpm run build
+```
+
+## License
+
+MIT -- see [LICENSE](./LICENSE) for details.
+
+---
+
+<p align="center">
+  <sub>Built with care by the <a href="https://flagify.dev">Flagify</a> team</sub>
+</p>

package/dist/index.d.mts

@@ -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 };