JavaScript / TypeScript

// flags.ts — create one client at startup and reuse it for the process lifetime.
// The client holds an in-memory flag cache and (optionally) a background
// analytics buffer, so constructing one per request throws both away.
import { ShipSilentlyClient } from '@shipsilently/node';

export const flags = new ShipSilentlyClient({
  apiKey: process.env.SHIPSILENTLY_KEY!,
});

// One flag, one network call. The third argument is both the fallback AND the
// type source — `useNewFlow` is `boolean`, `heroVariant` is `string`, inferred
// with no generics to write out.
import { flags } from './client';

interface User {
  id: string;
  plan: string;
  country: string;
}

export async function renderCheckout(user: User) {
  const useNewFlow = await flags.evaluate(
    'new-checkout-v2',
    { userId: user.id, plan: user.plan, country: user.country },
    false,
  );

  const heroVariant = await flags.evaluate('hero-variant', { userId: user.id }, 'control');

  return { useNewFlow, heroVariant };
}

// Fetch every flag once at the request boundary, then read synchronously.
// This is the pattern you want on a hot path: one round trip, then `get()`
// calls that never touch the network.
import { flags } from './client';

export async function handleRequest(userId: string, plan: string) {
  // One call hydrates the in-memory cache for this context.
  await flags.evaluateAll({ userId, plan });

  // Synchronous reads — no await, served from cache.
  const showBanner = flags.get('promo-banner', false);
  const tier = flags.get('pricing-tier', 'standard');
  const limits = flags.get('rate-limits', { rpm: 60 });

  // Full snapshot, including each flag's `reason` and matched `ruleId`.
  const snapshot = flags.getAll();

  return { showBanner, tier, limits, snapshot };
}

// Long-running services should stream. The client opens an SSE connection and
// keeps the local cache warm, so `get()` always reflects the current config
// without polling.
import type { StreamConnectionState } from '@shipsilently/node';
import { flags } from './client';

const unsubscribe = flags.stream(
  { userId: 'system' },
  (updated) => {
    console.log('flags refreshed:', Object.keys(updated));
  },
  {
    // Cadence used whenever SSE is unavailable. Default: 30_000.
    pollingIntervalMs: 30_000,

    // Observe the transport. `reconnecting` means SSE dropped but polling is
    // keeping data fresh — it is not an outage, and not worth paging on.
    onStateChange: (state: StreamConnectionState) => {
      console.log('[shipsilently] transport:', state);
    },
  },
);

// On shutdown: stop the stream, then flush any buffered analytics.
process.on('SIGTERM', async () => {
  unsubscribe();
  await flags.flushAnalytics();
  flags.close();
});

// Evaluation analytics are ON by default. Every `get()` and every locally
// served fallback is buffered and flushed in the background — that is what
// powers stale-flag detection in the dashboard.
//
// Networked `evaluate()` successes are NOT double-counted: the server already
// recorded those, so the client only reports what only it can see.
import { ShipSilentlyClient } from '@shipsilently/node';

export const flags = new ShipSilentlyClient({
  apiKey: process.env.SHIPSILENTLY_KEY!,

  analytics: {
    enabled: true,
    flushIntervalMs: 30_000, // default 30s, floor 1s
    maxBatchSize: 100, // force a flush at this many buffered events
    maxBufferSize: 5_000, // drop events past this (back-pressure guard)
    samplingRate: 1.0, // 1.0 = every evaluation; 0.1 = 10%
  },
});

// Opt out entirely — no buffer, no timers, no analytics requests.
export const quiet = new ShipSilentlyClient({
  apiKey: process.env.SHIPSILENTLY_KEY!,
  analytics: { enabled: false },
});

// Serverless / short-lived processes should flush before the runtime freezes,
// otherwise buffered events die with the isolate. Returns the count sent.
export async function beforeExit(): Promise<number> {
  return flags.flushAnalytics();
}

// Reconnection and backoff. Defaults are sensible; tune only if you have a
// reason. The stream reconnects with full-jitter exponential backoff and never
// gives up, so a flag outage never requires an app restart.
import { ShipSilentlyClient } from '@shipsilently/node';

export const flags = new ShipSilentlyClient({
  apiKey: process.env.SHIPSILENTLY_KEY!,

  retry: {
    enabled: true, // false = one failure downgrades to polling permanently
    baseDelayMs: 1_000, // first reconnect delay
    maxDelayMs: 60_000, // backoff ceiling
    heartbeatTimeoutMs: 90_000, // server beats every 30s; tolerate two misses
  },
});

// Inject fetch to test failure paths without a network.
export const offline = new ShipSilentlyClient({
  apiKey: 'sk_live_test',
  fetch: async () => new Response('boom', { status: 500 }),
});

export type FlagValue = boolean | string | number | Record<string, unknown>;

export interface UserContext {
  userId?: string;
  email?: string;
  country?: string;
  plan?: string;
  [key: string]: string | number | boolean | undefined;
}

export interface EvaluationResult {
  flagKey: string;
  value: FlagValue;
  reason: 'default' | 'rule_match' | 'rollout' | 'flag_disabled' | 'flag_not_found';
  ruleId?: string;
}

export type StreamConnectionState = 'streaming' | 'polling' | 'reconnecting';

// Your server holds the key and returns only resolved values.
import { flags } from '@/lib/flags';

export async function GET(request: Request) {
  const user = await getSession(request);

  const resolved = await flags.evaluateAll({ userId: user.id, plan: user.plan });

  // Send values only — never the rules that produced them.
  return Response.json(
    Object.fromEntries(Object.entries(resolved).map(([key, r]) => [key, r.value])),
  );
}