Avalie sua primeira flag com o sdk-js

Este tutorial cobre a configuração mínima do @rollfuse/sdk-js em um serviço Node.js: instalar o pacote, construir um client, iniciá-lo e ler o valor de uma flag com evaluate().

Instale o pacote

npm install @rollfuse/sdk-js

Construa e inicie o client

O RollfuseClient exige duas opções: baseUrl e credential. A credential é um bearer token emitido para uma Service Credential vinculada a um ambiente específico.

import { RollfuseClient } from "@rollfuse/sdk-js";

const client = new RollfuseClient({
  baseUrl: "https://api.rollfuse.com",
  credential: process.env.ROLLFUSE_CREDENTIAL!, // set before running
});

await client.start();

O start() inicia o polling em segundo plano em GET /v1/config e resolve assim que a primeira Configuration chega. Se o seu serviço não quiser bloquear a inicialização nessa chamada de rede, chame start() sem aguardar e conte com a opção fallback de evaluate() enquanto isso.

Avalie uma flag

Assim que uma Configuration está em cache, evaluate() a lê de forma síncrona: nenhuma chamada de rede acontece nesse caminho.

const subjectKey = "user-42";

const result = client.evaluate(subjectKey, "checkout-redesign", {
  attributes: { plan: "pro" },
  fallback: false,
});

if (result.value === true) {
  // serve o novo fluxo de checkout
} else {
  // serve o fluxo de checkout atual
}

O result traz o value resolvido, o reason que explica como se chegou nesse valor e o variation_key selecionado. Se nenhuma Configuration foi carregada ainda e nenhum fallback foi informado, evaluate() lança ConfigNotReadyError. Se a flag não existir na Configuration e nenhum fallback foi informado, o erro é FlagNotFoundError. Informar fallback transforma os dois casos em um valor padrão seguro em vez de uma exceção.

Avalie todas as flags de uma vez

O evaluateAll() roda a mesma avaliação síncrona para todas as flags da Configuration em cache, para um único subject:

const results = client.evaluateAll(subjectKey, {
  attributes: { plan: "pro" },
});

console.log(results.find((r) => r.flag_key === "checkout-redesign")?.value);

O evaluateAll() retorna um array de EvaluationResult, um por flag da Configuration, não um objeto indexado pela chave da flag; encontre a que você quer pelo flag_key.

É a mesma chamada que uma página renderizada no servidor usa para passar um conjunto completo de EvaluationResults para o RollfuseProvider do @rollfuse/sdk-react.

Encerrando corretamente

await client.close();

O close() para o polling, envia qualquer exposure event que ainda esteja na fila e libera as conexões abertas. Use stop() se quiser interromper o polling e o flush imediatamente, sem enviar o que estiver pendente, por exemplo dentro de um teste.

Com o client iniciado e a primeira flag avaliada, o próximo passo é decidir qual credential usar em cada ambiente: veja Emita e revogue credenciais de ambiente.