@barricador/react-client 0.2.0

package/README.md

@@ -0,0 +1,69 @@
+# barricador-react-client
+
+[![npm](https://img.shields.io/npm/v/@barricador/react-client?label=npm)](https://www.npmjs.com/package/@barricador/react-client)
+
+Client-side **React SDK** for Barricador. TypeScript, React 18+.
+
+## Install
+
+```bash
+npm install @barricador/react-client
+# peer dependency: react >= 18
+```
+
+## Security model
+
+Browsers are untrusted, so the SDK never downloads rulesets. It POSTs the `UserContext` to the
+backend `/api/v1/flags/eval` with a low-privilege **client key**; the server evaluates targeting
+internally and returns a flattened `key → value` map. An SSE connection signals environment changes,
+prompting a re-fetch. Telemetry is buffered and flushed asynchronously.
+
+## Usage
+
+```tsx
+import {
+  BarricadorProvider,
+  BarricadorErrorBoundary,
+  useFeatureFlag,
+  useFeatureFlagEnabled,
+} from "@barricador/react-client";
+
+function App() {
+  return (
+    <BarricadorProvider
+      clientKey="sdk-cli-..."
+      user={{ key: "user-123", email: "user@enterprise.com", custom: { plan: "pro" } }}
+      baseUrl="https://app.barricador.com"
+    >
+      <BarricadorErrorBoundary fallback={<Classic />}>
+        <Home />
+      </BarricadorErrorBoundary>
+    </BarricadorProvider>
+  );
+}
+
+function Home() {
+  const newCheckout = useFeatureFlagEnabled("new-checkout", false);
+  const theme = useFeatureFlag<string>("homepage-theme", "control");
+  return newCheckout ? <NewCheckout theme={theme} /> : <Classic />;
+}
+```
+
+## Re-render discipline
+
+`useFeatureFlag` uses `useSyncExternalStore` with a **per-key subscription**, so a component
+re-renders only when *its* flag value changes — not on every flag update.
+
+## Resilience
+
+Network/eval failures never throw: the SDK keeps the last values and unknown flags return the
+provided fallback. `BarricadorErrorBoundary` guarantees the UI still renders a safe default if
+flag-driven rendering throws. `useBarricadorStatus()` exposes `initializing | ready | offline`.
+
+## Build
+
+```bash
+npm install
+npm run build      # emits dist/ (.js + .d.ts)
+npm run typecheck
+```

package/dist/BarricadorErrorBoundary.d.ts

@@ -0,0 +1,22 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+export interface BarricadorErrorBoundaryProps {
+    /** Rendered if a descendant throws during render. */
+    fallback: ReactNode;
+    onError?: (error: Error, info: ErrorInfo) => void;
+    children: ReactNode;
+}
+interface State {
+    hasError: boolean;
+}
+/**
+ * Guarantees the UI degrades gracefully: if flag-driven rendering throws, the boundary shows the
+ * provided fallback instead of crashing the tree. Combined with `useFeatureFlag`'s fallback values
+ * (returned on any network/eval failure), the app always has a safe default to render.
+ */
+export declare class BarricadorErrorBoundary extends Component<BarricadorErrorBoundaryProps, State> {
+    constructor(props: BarricadorErrorBoundaryProps);
+    static getDerivedStateFromError(): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};

package/dist/BarricadorErrorBoundary.js

@@ -0,0 +1,21 @@
+import { Component } from "react";
+/**
+ * Guarantees the UI degrades gracefully: if flag-driven rendering throws, the boundary shows the
+ * provided fallback instead of crashing the tree. Combined with `useFeatureFlag`'s fallback values
+ * (returned on any network/eval failure), the app always has a safe default to render.
+ */
+export class BarricadorErrorBoundary extends Component {
+    constructor(props) {
+        super(props);
+        this.state = { hasError: false };
+    }
+    static getDerivedStateFromError() {
+        return { hasError: true };
+    }
+    componentDidCatch(error, info) {
+        this.props.onError?.(error, info);
+    }
+    render() {
+        return this.state.hasError ? this.props.fallback : this.props.children;
+    }
+}

package/dist/BarricadorProvider.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from "react";
+import type { UserContext } from "./types";
+export interface BarricadorProviderProps {
+    clientKey: string;
+    user: UserContext;
+    baseUrl?: string;
+    streaming?: boolean;
+    telemetry?: boolean;
+    flushIntervalMs?: number;
+    /** Optionally gate children until the first evaluation completes. */
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * Wraps the app, owns the {@link BarricadorStore} lifecycle, and re-evaluates when the user identity
+ * changes. Establishes the SSE connection and telemetry flushing. Never blocks rendering: children
+ * render immediately and flags resolve to their fallbacks until the first eval lands (unless a
+ * `fallback` node is provided to gate on readiness).
+ */
+export declare function BarricadorProvider({ clientKey, user, baseUrl, streaming, telemetry, flushIntervalMs, fallback, children, }: BarricadorProviderProps): import("react").JSX.Element;

package/dist/BarricadorProvider.js

@@ -0,0 +1,42 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { BarricadorContext } from "./context";
+import { BarricadorStore } from "./store";
+/**
+ * Wraps the app, owns the {@link BarricadorStore} lifecycle, and re-evaluates when the user identity
+ * changes. Establishes the SSE connection and telemetry flushing. Never blocks rendering: children
+ * render immediately and flags resolve to their fallbacks until the first eval lands (unless a
+ * `fallback` node is provided to gate on readiness).
+ */
+export function BarricadorProvider({ clientKey, user, baseUrl, streaming, telemetry, flushIntervalMs, fallback, children, }) {
+    const storeRef = useRef(null);
+    if (storeRef.current === null) {
+        storeRef.current = new BarricadorStore({
+            clientKey,
+            user,
+            baseUrl,
+            streaming,
+            telemetry,
+            flushIntervalMs,
+        });
+    }
+    const [ready, setReady] = useState(false);
+    useEffect(() => {
+        const store = storeRef.current;
+        void store.start().finally(() => setReady(true));
+        return () => store.close();
+        // Intentionally run once; identity changes are handled by the effect below.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Re-evaluate when the user identity (key) changes — e.g. after login/logout.
+    const userKey = user.key;
+    useEffect(() => {
+        if (ready)
+            void storeRef.current.identify(user);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [userKey]);
+    if (fallback !== undefined && !ready) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    return (_jsx(BarricadorContext.Provider, { value: storeRef.current, children: children }));
+}

package/dist/context.d.ts

@@ -0,0 +1,3 @@
+import type { BarricadorStore } from "./store";
+/** Internal context carrying the singleton {@link BarricadorStore}. */
+export declare const BarricadorContext: import("react").Context<BarricadorStore | null>;

package/dist/context.js

@@ -0,0 +1,3 @@
+import { createContext } from "react";
+/** Internal context carrying the singleton {@link BarricadorStore}. */
+export const BarricadorContext = createContext(null);

package/dist/hooks.d.ts

@@ -0,0 +1,11 @@
+import type { ConnectionStatus, FlagValue } from "./types";
+/**
+ * Read a single flag's evaluated value. Backed by {@link useSyncExternalStore} with a per-key
+ * subscription, so a component using this hook re-renders ONLY when this flag's value changes — not
+ * when any other flag updates. Returns `fallback` until the value is known (or on any failure).
+ */
+export declare function useFeatureFlag<T extends FlagValue>(key: string, fallback: T): T;
+/** Convenience boolean variant. */
+export declare function useFeatureFlagEnabled(key: string, fallback?: boolean): boolean;
+/** Observe the SDK connection status (initializing / ready / offline). */
+export declare function useBarricadorStatus(): ConnectionStatus;

package/dist/hooks.js

@@ -0,0 +1,32 @@
+import { useCallback, useContext, useSyncExternalStore } from "react";
+import { BarricadorContext } from "./context";
+function useStore() {
+    const store = useContext(BarricadorContext);
+    if (!store) {
+        throw new Error("useFeatureFlag must be used within a <BarricadorProvider>");
+    }
+    return store;
+}
+/**
+ * Read a single flag's evaluated value. Backed by {@link useSyncExternalStore} with a per-key
+ * subscription, so a component using this hook re-renders ONLY when this flag's value changes — not
+ * when any other flag updates. Returns `fallback` until the value is known (or on any failure).
+ */
+export function useFeatureFlag(key, fallback) {
+    const store = useStore();
+    const subscribe = useCallback((cb) => store.subscribeKey(key, cb), [store, key]);
+    const getSnapshot = useCallback(() => store.getValue(key, fallback), [store, key, fallback]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/** Convenience boolean variant. */
+export function useFeatureFlagEnabled(key, fallback = false) {
+    const value = useFeatureFlag(key, fallback);
+    return typeof value === "boolean" ? value : fallback;
+}
+/** Observe the SDK connection status (initializing / ready / offline). */
+export function useBarricadorStatus() {
+    const store = useStore();
+    const subscribe = useCallback((cb) => store.subscribeStatus(cb), [store]);
+    const getSnapshot = useCallback(() => store.getStatus(), [store]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { BarricadorProvider } from "./BarricadorProvider";
+export type { BarricadorProviderProps } from "./BarricadorProvider";
+export { BarricadorErrorBoundary } from "./BarricadorErrorBoundary";
+export type { BarricadorErrorBoundaryProps } from "./BarricadorErrorBoundary";
+export { useFeatureFlag, useFeatureFlagEnabled, useBarricadorStatus } from "./hooks";
+export { BarricadorStore } from "./store";
+export type { BarricadorClientOptions, ConnectionStatus, EvalResponse, FlagValue, UserContext, } from "./types";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { BarricadorProvider } from "./BarricadorProvider";
+export { BarricadorErrorBoundary } from "./BarricadorErrorBoundary";
+export { useFeatureFlag, useFeatureFlagEnabled, useBarricadorStatus } from "./hooks";
+export { BarricadorStore } from "./store";

package/dist/store.d.ts

@@ -0,0 +1,46 @@
+import type { BarricadorClientOptions, ConnectionStatus, FlagValue, UserContext } from "./types";
+type Listener = () => void;
+/**
+ * Framework-agnostic core of the client SDK.
+ *
+ * Security model: the browser holds a low-privilege `clientKey` and POSTs the {@link UserContext} to
+ * the backend's `/api/v1/flags/eval`. The server resolves all targeting internally and returns a
+ * flattened `key -> value` map — raw rules never reach the client. An SSE connection signals when the
+ * environment changes so the SDK re-fetches the evaluated map. Telemetry is buffered and flushed
+ * asynchronously. Reads are O(1) and never throw: on any failure the SDK keeps the last values, and
+ * unknown flags fall back to the caller-provided default in {@link getValue}.
+ */
+export declare class BarricadorStore {
+    private readonly baseUrl;
+    private readonly clientKey;
+    private user;
+    private readonly streaming;
+    private readonly telemetry;
+    private readonly flushIntervalMs;
+    private values;
+    private status;
+    /** Per-key listeners so a component only re-renders when *its* flag changes. */
+    private readonly keyListeners;
+    private readonly statusListeners;
+    private readonly evalCounts;
+    private eventSource;
+    private flushTimer;
+    private closed;
+    constructor(options: BarricadorClientOptions);
+    start(): Promise<void>;
+    /** Re-post the user context and swap in the freshly evaluated values. */
+    refresh(): Promise<void>;
+    /** Update the identified user and re-evaluate (e.g. after login). */
+    identify(user: UserContext): Promise<void>;
+    getValue(key: string, fallback: FlagValue): FlagValue;
+    getStatus(): ConnectionStatus;
+    subscribeKey(key: string, listener: Listener): () => void;
+    subscribeStatus(listener: Listener): () => void;
+    private applyValues;
+    private notifyKey;
+    private setStatus;
+    private connectStream;
+    flush(): Promise<void>;
+    close(): void;
+}
+export {};

package/dist/store.js

@@ -0,0 +1,167 @@
+/**
+ * Framework-agnostic core of the client SDK.
+ *
+ * Security model: the browser holds a low-privilege `clientKey` and POSTs the {@link UserContext} to
+ * the backend's `/api/v1/flags/eval`. The server resolves all targeting internally and returns a
+ * flattened `key -> value` map — raw rules never reach the client. An SSE connection signals when the
+ * environment changes so the SDK re-fetches the evaluated map. Telemetry is buffered and flushed
+ * asynchronously. Reads are O(1) and never throw: on any failure the SDK keeps the last values, and
+ * unknown flags fall back to the caller-provided default in {@link getValue}.
+ */
+export class BarricadorStore {
+    constructor(options) {
+        this.values = {};
+        this.status = "initializing";
+        /** Per-key listeners so a component only re-renders when *its* flag changes. */
+        this.keyListeners = new Map();
+        this.statusListeners = new Set();
+        this.evalCounts = new Map();
+        this.eventSource = null;
+        this.flushTimer = null;
+        this.closed = false;
+        if (!options.clientKey)
+            throw new Error("clientKey is required");
+        if (!options.user?.key)
+            throw new Error("user.key is required");
+        this.clientKey = options.clientKey;
+        this.user = options.user;
+        this.baseUrl = (options.baseUrl ?? "https://app.barricador.com").replace(/\/$/, "");
+        this.streaming = options.streaming ?? true;
+        this.telemetry = options.telemetry ?? true;
+        this.flushIntervalMs = options.flushIntervalMs ?? 30000;
+    }
+    async start() {
+        await this.refresh();
+        if (this.streaming)
+            this.connectStream();
+        if (this.telemetry && typeof setInterval !== "undefined") {
+            this.flushTimer = setInterval(() => void this.flush(), this.flushIntervalMs);
+        }
+    }
+    /** Re-post the user context and swap in the freshly evaluated values. */
+    async refresh() {
+        try {
+            const res = await fetch(`${this.baseUrl}/api/v1/flags/eval`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.clientKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(this.user),
+            });
+            if (!res.ok)
+                throw new Error(`eval failed: HTTP ${res.status}`);
+            const body = (await res.json());
+            this.applyValues(body.values ?? {});
+            this.setStatus("ready");
+        }
+        catch {
+            // Network/eval failure: keep last values; hooks fall back to defaults. Never throw.
+            this.setStatus(this.status === "initializing" ? "offline" : this.status);
+        }
+    }
+    /** Update the identified user and re-evaluate (e.g. after login). */
+    async identify(user) {
+        this.user = user;
+        await this.refresh();
+    }
+    getValue(key, fallback) {
+        if (this.telemetry)
+            this.evalCounts.set(key, (this.evalCounts.get(key) ?? 0) + 1);
+        return key in this.values ? this.values[key] : fallback;
+    }
+    getStatus() {
+        return this.status;
+    }
+    // --- subscriptions (drive useSyncExternalStore) ---
+    subscribeKey(key, listener) {
+        let set = this.keyListeners.get(key);
+        if (!set) {
+            set = new Set();
+            this.keyListeners.set(key, set);
+        }
+        set.add(listener);
+        return () => set.delete(listener);
+    }
+    subscribeStatus(listener) {
+        this.statusListeners.add(listener);
+        return () => this.statusListeners.delete(listener);
+    }
+    // --- internals ---
+    applyValues(next) {
+        const previous = this.values;
+        this.values = next;
+        const changed = new Set([...Object.keys(previous), ...Object.keys(next)]);
+        for (const key of changed) {
+            if (!shallowEqual(previous[key], next[key]))
+                this.notifyKey(key);
+        }
+    }
+    notifyKey(key) {
+        this.keyListeners.get(key)?.forEach((l) => l());
+    }
+    setStatus(status) {
+        if (this.status !== status) {
+            this.status = status;
+            this.statusListeners.forEach((l) => l());
+        }
+    }
+    connectStream() {
+        if (typeof EventSource === "undefined" || this.closed)
+            return;
+        // EventSource cannot set Authorization headers, so the client key travels as a query param.
+        const url = `${this.baseUrl}/api/v1/flags/stream?clientKey=${encodeURIComponent(this.clientKey)}`;
+        try {
+            const es = new EventSource(url);
+            this.eventSource = es;
+            // On any flag change in the environment, re-fetch the pre-evaluated map for this user.
+            es.addEventListener("flag-change", () => void this.refresh());
+            es.addEventListener("connected", () => this.setStatus("ready"));
+            es.onerror = () => {
+                // EventSource auto-reconnects with its own backoff; reflect the transient outage.
+                this.setStatus("offline");
+            };
+        }
+        catch {
+            this.setStatus("offline");
+        }
+    }
+    async flush() {
+        if (!this.telemetry || this.evalCounts.size === 0)
+            return;
+        const events = [...this.evalCounts.entries()].map(([flagKey, count]) => ({
+            flagKey,
+            count,
+            defaulted: !(flagKey in this.values),
+        }));
+        this.evalCounts.clear();
+        try {
+            await fetch(`${this.baseUrl}/api/v1/metrics/flush`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.clientKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ events }),
+                keepalive: true,
+            });
+        }
+        catch {
+            // Telemetry is best-effort; drop on failure.
+        }
+    }
+    close() {
+        this.closed = true;
+        if (this.flushTimer)
+            clearInterval(this.flushTimer);
+        this.eventSource?.close();
+        void this.flush();
+    }
+}
+function shallowEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    return JSON.stringify(a) === JSON.stringify(b);
+}

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+/** Public types for the Barricador React client SDK. */
+export type FlagValue = boolean | string | number | Record<string, unknown> | unknown[] | null;
+/** The evaluation subject. `key` must be stable per subject for consistent rollouts. */
+export interface UserContext {
+    key: string;
+    name?: string;
+    email?: string;
+    country?: string;
+    anonymous?: boolean;
+    custom?: Record<string, unknown>;
+}
+export interface BarricadorClientOptions {
+    clientKey: string;
+    user: UserContext;
+    baseUrl?: string;
+    /** Enable the live SSE connection (default true). */
+    streaming?: boolean;
+    /** Enable async telemetry flushing (default true). */
+    telemetry?: boolean;
+    /** Telemetry flush cadence in ms (default 30000). */
+    flushIntervalMs?: number;
+}
+/** Server response from POST /api/v1/flags/eval — only pre-evaluated values, never raw rules. */
+export interface EvalResponse {
+    environmentId: string;
+    rulesVersion: number;
+    values: Record<string, FlagValue>;
+    details?: Record<string, {
+        variationId?: string;
+        reason?: string;
+        version?: number;
+    }>;
+}
+export type ConnectionStatus = "initializing" | "ready" | "offline";

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Public types for the Barricador React client SDK. */
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@barricador/react-client",
+  "version": "0.2.0",
+  "description": "Barricador client-side React SDK (pre-evaluated context model, SSE sync, telemetry)",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "feature-flags",
+    "barricador",
+    "react",
+    "sdk",
+    "rollout",
+    "ab-testing"
+  ],
+  "homepage": "https://github.com/barricador/barricador-react-client",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/barricador/barricador-react-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/barricador/barricador-react-client/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "react": "^18.3.1",
+    "typescript": "^5.5.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "license": "Apache-2.0"
+}