feature-flags

name	feature-flags
description	Evaluate feature flags from a self-hosted ffs server. Use when you need to check whether a feature is enabled, get a variant value for an A/B test, or batch-evaluate multiple flags for a user. Triggers include "check feature flag", "is feature enabled", "evaluate flag", "feature toggle", "ffs evaluate", or any task that needs to gate behavior behind a flag.

feature-flags

Evaluate feature flags from a self-hosted feature-flag-server instance.

When to use

• Checking whether a feature is enabled for a specific user
• Getting a variant value for an A/B test or multivariate experiment
• Batch-evaluating multiple flags in a single request
• Gating code paths behind flags before deploying

Prerequisites

1. A running feature-flag-server instance
2. An API key (ffs_...) from the server admin
3. The @ffs/js-sdk installed, or use the REST API directly

Installation (JS SDK)

pnpm add @ffs/js-sdk

Quick Start

import { FlagClient } from '@ffs/js-sdk';

const client = new FlagClient({
  baseUrl: 'http://localhost:7777',
  apiKey: process.env.FFS_API_KEY!,
  environment: 'production',
  cacheTtl: 30_000,
});

// Check a boolean flag
const enabled = await client.isEnabled('new-checkout-flow', { userId: 'user_123' });

// Get a variant
const variant = await client.getVariant('button-color-test', {
  userId: 'user_123',
  plan: 'beta',
});
// variant.value => "#10B981"

// Batch evaluate
const flags = await client.evaluateAll(
  ['new-checkout-flow', 'dark-mode'],
  { userId: 'user_123' }
);

REST API (direct HTTP)

# Single flag evaluation
curl -s -X POST http://localhost:7777/api/evaluate \
  -H "Authorization: Bearer ffs_..." \
  -H "Content-Type: application/json" \
  -d '{ "flagKey": "new-checkout-flow", "userId": "user_123", "environmentId": "production" }'
# Response:
# { "value": true, "variant": "control", "reason": "enabled", "flagKey": "new-checkout-flow" }

# Batch evaluation
curl -s -X POST http://localhost:7777/api/evaluate/batch \
  -H "Authorization: Bearer ffs_..." \
  -H "Content-Type: application/json" \
  -d '{ "flags": ["new-checkout-flow", "dark-mode"], "userId": "user_123", "environmentId": "production" }'

# Simple GET (boolean flags)
curl -s "http://localhost:7777/api/evaluate/new-checkout-flow?userId=user_123&env=production&key=ffs_..."

Evaluation Response

Field	Type	Description
value	boolean | string | number	The evaluated flag value
variant	string	Variant key for segment/percentage flags
reason	string	Why this value was returned
flagKey	string	Echo of the requested flag key

Reason values:

• enabled - flag is on in this environment
• disabled - flag is off in this environment
• percentage - user fell within the rollout percentage
• segment_match - user matched a targeting segment
• default - flag not found or evaluation error

Environment Variables

Variable	Description
FFS_API_KEY	API key for the ffs server
FFS_BASE_URL	Server URL (default: http://localhost:7777)
FFS_ENVIRONMENT	Environment name (default: production)
FFS_CACHE_TTL	Client-side cache TTL in ms (default: 30000)

Behavior

• Caching: SDK caches evaluation results for cacheTtl ms. A cache hit returns instantly with no HTTP call.
• Context: Any key-value pairs in the context object are available to segment rules (e.g., user.plan, user.country).
• Consistency: Percentage flags use deterministic hashing of flagKey:userId, so the same user always gets the same result for a given flag.

Troubleshooting

"401 Unauthorized"

API key is missing or invalid. Check FFS_API_KEY and verify the key exists on the server with ffs-server key list.

"404 Not Found" on /api/evaluate

The flag key does not exist. Create it in the dashboard or via POST /api/flags.

SDK returns stale values

Cache TTL has not expired. Call client.cache.invalidate('flag-key') to force a fresh evaluation, or reduce cacheTtl in the client config.