feature-flags

# 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)

```bash
pnpm add @ffs/js-sdk
```

## Quick Start

```typescript
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)

```bash
# 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.