audienceforge-js

Official JavaScript/TypeScript SDK for AudienceForge — feature flags and A/B testing.

• Zero production dependencies (uses native fetch).
• In-memory cache with configurable TTL.
• Silent fallback: API errors never throw to your code — you always get a safe default.
• Works in modern browsers and Node.js 18+. Ships ESM + CJS + type definitions.

Install

pnpm add audienceforge-js
# or: npm i audienceforge-js / yarn add audienceforge-js

Quick start

import { AudienceForge } from 'audienceforge-js';

const client = AudienceForge.init({ apiKey: 'sdk-key-xxxxx' });

if (await client.isEnabled('checkout-v2', { userId: 'u123', attributes: { plan: 'pro' } })) {
  // feature on
}

API

AudienceForge.init(config)

| Option | Type | Default | Description | |---------------|-----------------------|----------------------------------|----------------------------------------------| | apiKey | string (required) | — | SDK Key da organização (Bearer). | | apiUrl | string | https://api.audienceforge.dev | URL base da API. | | environment | string | production | Ambiente avaliado. | | cacheTtlMs | number | 30000 | TTL do cache local (0 desabilita). | | timeoutMs | number | 1000 | Timeout por request antes do fallback. | | fetchImpl | typeof fetch | globalThis.fetch | Implementação de fetch (Node < 18 / testes). |

client.isEnabled(flagKey, userContext): Promise<boolean>

Avalia se a flag está habilitada. Fallback: false.

client.getVariant(flagKey, userContext): Promise<string>

Retorna a variante ativa da flag. Fallback: 'control'.

client.evaluateExperiment(experimentKey, userContext): Promise<{ variant: string }>

Atribui a variante de um experimento A/B. Fallback: { variant: 'control' }.

Nota de backend (jun/2026): o método evaluateExperiment depende da implementação determinística de avaliação no experiments-service (DT-06). Até esse fix estar em produção, o backend pode retornar sempre control.

UserContext: { userId: string; attributes?: Record<string, string | number | boolean> }.

Behavior

• Cache: avaliações idênticas (mesma flag/experimento + userId + environment + atributos) dentro do TTL não geram nova chamada HTTP.
• Fallback silencioso: timeout, erro de rede, 4xx/5xx ou JSON inválido resolvem com o valor padrão; nenhuma exceção é propagada.

Endpoints usados

• Flags: POST {apiUrl}/flags/api/v1/evaluate
• Experiments: POST {apiUrl}/experiments/api/v1/experiments/evaluate

Development

pnpm install
pnpm test        # vitest (sem rede — fetch mockado)
pnpm run build   # tsup → dist (ESM + CJS + d.ts)
pnpm run typecheck

License

MIT