feat: Adds feature flags runtime client with local evaluation

[stanleyphu]

Description

• Adds FeatureFlagsRuntimeClient, a polling-based client that fetches all flag configurations from /sdk/feature-flags and evaluates them locally in-memory. Targeting rules (org-level and user-level) are resolved client-side with zero per-request API overhead.
• Exposed via workos.featureFlags.createRuntimeClient(options?).

Implementation Details

• InMemoryStore — atomic-swap key/value store for flag data
• Evaluator — stateless evaluation: flag enabled → org target → user target → default value
• FeatureFlagsRuntimeClient — orchestrates polling, caching, and evaluation
  • Configurable polling interval (default 30s, min 5s) with jitter
  • Exponential backoff on consecutive errors (capped at 60s)
  • Stops polling on 401 and emits 'failed' event
  • waitUntilReady() with optional timeout
  • Bootstrap flags for instant availability before first poll
  • 'change' events when flags are added, modified, or removed
  • getStats() for observability

Usage

Basic usage

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_test_...');
const client = workos.featureFlags.createRuntimeClient();

await client.waitUntilReady();

if (client.isEnabled('new-dashboard')) {
  // serve new dashboard
}

With targeting context

// User-level targeting
client.isEnabled('beta-feature', { userId: 'user_123' });

// Org-level targeting
client.isEnabled('enterprise-feature', { organizationId: 'org_456' });

// Both
client.isEnabled('rollout-feature', {
  userId: 'user_123',
  organizationId: 'org_456',
});

// Custom default when flag doesn't exist
client.isEnabled('unknown-flag', {}, true); // returns true instead of false

Configuration options

const client = workos.featureFlags.createRuntimeClient({
  pollingIntervalMs: 10000,    // poll every 10s (min 5s)
  requestTimeoutMs: 5000,      // timeout per poll request
  bootstrapFlags: cachedFlags,  // pre-populate store for instant reads
  logger: console,              // any object with debug/info/warn/error
});

Reacting to changes

client.on('change', ({ key, previous, current }) => {
  console.log(`Flag ${key} changed`, { previous, current });
});

client.on('error', (err) => {
  console.error('Poll failed, will retry:', err.message);
});

client.on('failed', (err) => {
  // Unrecoverable (e.g. 401) — client has stopped polling
  console.error('Client stopped:', err.message);
});

Evaluating all flags at once

const flags = client.getAllFlags({ userId: 'user_123' });
// { 'new-dashboard': true, 'beta-feature': false, ... }

Observability

const stats = client.getStats();
// { pollCount: 42, pollErrorCount: 1, cacheAge: 12340, flagCount: 5, ... }

Cleanup

client.close(); // stops polling, removes listeners

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.