@revido-ff/sdk

TypeScript/JavaScript SDK pro Revido Feature Flags. Obsahuje dva klienty:

| Entry | Prostředí | Klíč | Jak vyhodnocuje | | --- | --- | --- | --- | | @revido-ff/sdk | backend (Node) | ffp_server_… (tajný) | local eval — stáhne celý stav prostředí, vyhodnocuje lokálně | | @revido-ff/sdk/react (příp. /browser) | veřejný frontend | ffp_client_… (public-safe) | remote eval — POST /api/v1/evaluate, dostává jen výsledky |

Server-side klíč je tajný (obsahuje pravidla + override emaily) → jen do backendů, nikdy do veřejného frontendu. Frontendy používají client-side klíč — ten smí být v bundlu i v env souborech v repu (stejně jako dnes VITE_FLAGSMITH_ENV_ID).

Browser / React (@revido-ff/sdk/react)

import { RevidoFlagsProvider } from '@revido-ff/sdk/react';

root.render(
  <RevidoFlagsProvider
    options={{
      apiUrl: import.meta.env.VITE_REVIDO_FF_API,   // https://flags.savingstech.cz
      clientKey: import.meta.env.VITE_REVIDO_FF_KEY, // ffp_client_…
    }}
  >
    <App />
  </RevidoFlagsProvider>,
);

import {
  useRevidoFlag,
  useRevidoFlagValue,
  useRevidoFlagsReady,
  useRevidoIdentity,
} from '@revido-ff/sdk/react';

const enabled = useRevidoFlag('new-onboarding');        // boolean
const message = useRevidoFlagValue('status-bar');       // remote config hodnota (FlagValue)
const ready = useRevidoFlagsReady();                    // pro kritické gaty (maintenance, disable_sso)

const { identify, reset } = useRevidoIdentity();
await identify({ email: '[email protected]', role: 'advisor' }); // po loginu
await reset();                                                 // po logoutu

Chování

• Cache + stale-while-revalidate — výsledky se drží v localStorage a při startu se synchronně hydratují: při opakované návštěvě jsou flagy k dispozici hned v prvním renderu, čerstvý stav se stáhne na pozadí. Úplně první návštěva má flagy OFF do doletu fetche — kritické gaty obal přes useRevidoFlagsReady().
• Identita se cachuje spolu s výsledky — po reloadu se první fetch ptá s poslední známou identitou (žádné anonymní „probliknutí" mezi cache a identify). Souběžné požadavky řeší AbortController, poslední vyhrává.
• Refetch — mount + identify()/reset() + návrat do tabu (focus, throttle 60 s). Polling je opt-in přes pollIntervalMs.
• Fail-safe — chybějící apiUrl/clientKey → vypnutý režim (vše false, ready: true); chyba sítě/timeout/nevalidní odpověď → drží se poslední známý stav. Nikdy neshodí aplikaci.

Options (BrowserFlagClientOptions)

| Option | Default | Popis | | --- | --- | --- | | apiUrl | — | Základ URL flag serveru bez /api, např. https://flags.savingstech.cz. | | clientKey | — | Client-side klíč prostředí (ffp_client_…). | | identity | — | Výchozí identita při startu (jinak poslední z cache, jinak anonymní). | | cache | true | localStorage cache pro okamžitou hydrataci. | | timeoutMs | 5000 | Timeout jednoho požadavku. | | refetchOnFocus | true | Refetch při návratu do tabu (throttle focusThrottleMs, default 60 s). | | pollIntervalMs | vypnuto | Periodický refetch. | | deviceIdentifier | false | Vygeneruje a uloží stabilní anonymní identifier → percentage rollout funguje i bez loginu. | | onError | — | Callback při chybě. Appku neshazuje. |

Server / Node (@revido-ff/sdk)

SDK se inicializuje server-side environment klíčem (ffp_server_…), při startu (a pak periodicky) stáhne kompletní stav prostředí a drží ho v paměti. Evaluace pak probíhá lokálně — žádný network call na každý isEnabled(). Stejná evaluační logika jako na serveru (sdílená z @revido-ff/shared), takže výsledky sedí 1:1.

import { createFlagClient } from '@revido-ff/sdk';

const client = await createFlagClient({
  apiKey: 'ffp_server_xxx',
  apiUrl: 'https://flags.savingstech.cz/api',
  pollingIntervalSeconds: 30, // volitelné, default 30
});

// kdekoliv v aplikaci — synchronní, lokální vyhodnocení
if (client.isEnabled('deap.catalog.new-flow', { email: '[email protected]', role: 'advisor' })) {
  // …
}

// remote config hodnota (V1: boolean flagy → value je null)
const value = client.getValue('deap.some.config', { email: '[email protected]' }, /* fallback */ null);

client.stop(); // zastaví polling (např. při shutdownu)

| Metoda | Popis | | --- | --- | | isEnabled(key, identity, fallback = false) | true/false pro danou identitu. Neznámý flag / chybějící stav → fallback. | | getValue(key, identity, fallback = null) | Hodnota flagu (remote config). | | refresh() | Ručně přenačte stav prostředí. | | stop() | Zastaví polling. |

Identita je celá volitelná — bez ní projede jen master vypínač (pro anonymní frontendy). identifier je stabilní klíč pro percentage rollout (anonymní ID nebo user ID), email slouží pro user overrides (a jako fallback rollout klíč), ostatní atributy pro segmenty (role, city, …). Bez klíče (identifier ani email) se partial rollout bere jako OFF (projede jen 100 %).

| Option | Default | Popis | | --- | --- | --- | | apiKey | — | Server-side environment klíč (ffp_server_…). | | apiUrl | — | Základ API, např. https://flags.savingstech.cz/api. | | pollingIntervalSeconds | 30 | Interval obnovy stavu. | | fetchImpl | globalThis.fetch | Vlastní fetch (Node < 18, testy). | | onError | — | Callback při chybě (fetch/parse). Appku neshazuje. |

Failure modes (fail-safe)

Oba klienti nikdy neshodí aplikaci:

• Fetch při startu selže → není stav → vrací se fallback/false (browser navíc zkusí cache).
• Výpadek za běhu → drží poslední známý stav dál, jen zavolá onError.
• Nevalidní payload → zahodí, onError, ponechá předchozí stav.

Release na npm

Balíček se publikuje na veřejné npm přes GitHub Actions (.github/workflows/publish-sdk.yml):

1. Zvedni version v packages/sdk/package.json (semver).
2. Commit + tag: git tag sdk-v0.1.0 && git push origin main --tags.
3. Workflow ověří shodu tagu s verzí, spustí build + testy a publikuje.

Autentizace: trusted publishing (OIDC) — na npmjs je nastavený Trusted Publisher pro tento repozitář a workflow, GitHub Actions se prokazuje přímo svou identitou. Žádné tokeny, žádné secrets, nic k rotaci.