@flagdown/react 0.0.2 → 0.0.3

package/README.md

@@ -1,42 +1,48 @@
 # @flagdown/react
 
-React bindings for [Flagdown](https://github.com/flagdown/flagdown) feature
-flags.
-
-## Installation
-
-```bash
-npm install @flagdown/react
-```
-
-## Current bootstrap API
-
-Wrap the part of the React tree that reads flags in `FlagdownProvider`, then
-read a flag with `useFlag`:
+Read boolean feature flags from a Flagdown project in React 18+.
 
 ```tsx
-import { FlagdownProvider, useFlag } from "@flagdown/react";
+import { FlagdownProvider, useFlag } from '@flagdown/react';
 
-function BetaFeature() {
-  return useFlag("beta-feature") ? <p>Enabled</p> : null;
+function Checkout() {
+  const enabled = useFlag('new-checkout');
+  return enabled ? <NewCheckout /> : <CurrentCheckout />;
 }
 
-export function App() {
-  return (
-    <FlagdownProvider>
-      <BetaFeature />
-    </FlagdownProvider>
-  );
-}
+<FlagdownProvider
+  apiUrl="https://your-flagdown-api.example.com"
+  clientToken="COPY_PUBLIC_CLIENT_TOKEN_FROM_DASHBOARD"
+>
+  <Checkout />
+</FlagdownProvider>
 ```
 
-This initial provider returns `false` for every flag. A future release will
-provide an adapter generated from Flagdown's OpenAPI contract.
+Create a project and flag in the dashboard, then copy the generated integration
+snippet. `apiUrl` is the Worker base URL without `/v1`. Install the SDK build that
+includes the remote adapter; the previously published 0.0.2 build only provides
+an injectable evaluator. This source must be released before registry installs
+can use remote reads.
+
+Flags refresh every 10 seconds, without reloading the page. Set
+`refreshIntervalMs` to change this (minimum 1000ms). Requests time out after 10
+seconds. Initial values, unknown flags and refresh failures evaluate `false`;
+a successful later refresh restores values. An optional `onError(error)` callback
+can report failures. Changing project configuration immediately discards the
+previous project's values. Unmounting cancels in-flight work and future refreshes.
 
-For tests or custom adapters, supply a `FlagEvaluator` implementation:
+Client tokens are public, project-scoped read configuration. They cannot manage
+flags. Replacing a token in the dashboard invalidates the previous token; update
+apps using it. Client-side flags are not an authorization boundary.
+
+For tests or local values, the existing evaluator port remains available:
 
 ```tsx
-<FlagdownProvider evaluator={{ isEnabled: (key) => key === "beta-feature" }}>
-  <BetaFeature />
+<FlagdownProvider evaluator={{ isEnabled: key => key === 'new-checkout' }}>
+  <Checkout />
 </FlagdownProvider>
 ```
+
+An explicit evaluator takes precedence over remote configuration. A provider
+without either configuration evaluates every flag off. `useFlag` must be called
+inside a provider.

package/dist/index.d.ts

@@ -14,13 +14,15 @@ interface FlagEvaluator {
 declare const disabledFlagEvaluator: FlagEvaluator;
 
 interface FlagdownProviderProps extends PropsWithChildren {
-    /**
-     * Optional evaluation port. This enables a future Flagdown API adapter and
-     * keeps consumers independent from the transport that supplies flag values.
-     */
     evaluator?: FlagEvaluator;
+    apiUrl?: string;
+    /** Public, read-only project token copied from the dashboard. */
+    clientToken?: string;
+    /** Refresh interval; minimum 1 second, default 10 seconds. */
+    refreshIntervalMs?: number;
+    onError?: (error: Error) => void;
 }
-declare function FlagdownProvider({ children, evaluator, }: FlagdownProviderProps): react.JSX.Element;
+declare function FlagdownProvider({ children, evaluator, apiUrl, clientToken, refreshIntervalMs, onError }: FlagdownProviderProps): react.JSX.Element;
 
 declare function useFlag(flagKey: string): boolean;
 

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/FlagdownProvider.tsx
+import { useEffect, useMemo, useState, useRef } from "react";
+
 // src/FlagdownContext.tsx
 import { createContext, useContext } from "react";
 var FlagdownContext = createContext(void 0);
@@ -14,13 +17,62 @@ var disabledFlagEvaluator = {
   isEnabled: () => false
 };
 
+// src/remote.ts
+async function fetchFlagState(apiUrl, clientToken, signal) {
+  const response = await fetch(apiUrl.replace(/\/$/, "") + "/v1/client/flags", {
+    headers: { "x-flagdown-client-token": clientToken },
+    cache: "no-store",
+    signal
+  });
+  if (!response.ok) throw new Error(`Flagdown request failed (${response.status})`);
+  const data = await response.json();
+  if (!data || typeof data !== "object" || !("flags" in data) || !data.flags || typeof data.flags !== "object" || Array.isArray(data.flags) || Object.values(data.flags).some((value) => typeof value !== "boolean")) {
+    throw new Error("Invalid Flagdown response");
+  }
+  return data.flags;
+}
+
 // src/FlagdownProvider.tsx
 import { jsx } from "react/jsx-runtime";
-function FlagdownProvider({
-  children,
-  evaluator = disabledFlagEvaluator
-}) {
-  return /* @__PURE__ */ jsx(FlagdownContext.Provider, { value: evaluator, children });
+function FlagdownProvider({ children, evaluator, apiUrl, clientToken, refreshIntervalMs = 1e4, onError }) {
+  const errorHandler = useRef(onError);
+  useEffect(() => {
+    errorHandler.current = onError;
+  }, [onError]);
+  const [snapshot, setSnapshot] = useState();
+  useEffect(() => {
+    if (evaluator || !apiUrl || !clientToken) return;
+    let active = true;
+    let timer;
+    let controller;
+    async function refresh() {
+      controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 1e4);
+      try {
+        const flags = await fetchFlagState(apiUrl, clientToken, controller.signal);
+        if (active) setSnapshot({ apiUrl, clientToken, flags });
+      } catch (error) {
+        if (active) {
+          setSnapshot(void 0);
+          try {
+            errorHandler.current?.(error instanceof Error ? error : new Error("Flagdown request failed"));
+          } catch {
+          }
+        }
+      } finally {
+        clearTimeout(timeout);
+        if (active) timer = setTimeout(() => void refresh(), Number.isFinite(refreshIntervalMs) ? Math.max(1e3, refreshIntervalMs) : 1e4);
+      }
+    }
+    void refresh();
+    return () => {
+      active = false;
+      clearTimeout(timer);
+      controller?.abort();
+    };
+  }, [apiUrl, clientToken, evaluator, refreshIntervalMs]);
+  const value = useMemo(() => evaluator || (snapshot && snapshot.apiUrl === apiUrl && snapshot.clientToken === clientToken ? { isEnabled: (key) => Object.hasOwn(snapshot.flags, key) && snapshot.flags[key] === true } : disabledFlagEvaluator), [evaluator, snapshot, apiUrl, clientToken]);
+  return /* @__PURE__ */ jsx(FlagdownContext.Provider, { value, children });
 }
 export {
   FlagdownProvider,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flagdown/react",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "license": "MIT",
   "type": "module",
   "description": "React SDK for evaluating Flagdown feature flags.",
@@ -22,7 +22,11 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",
     "test": "bun test",