@flagdown/react 0.0.2 → 0.0.4

package/README.md

@@ -1,42 +1,59 @@
 # @flagdown/react
 
-React bindings for [Flagdown](https://github.com/flagdown/flagdown) feature
-flags.
+Use the `Feature` component to switch between new UI and a fallback in React 18+.
 
-## Installation
-
-```bash
-npm install @flagdown/react
+```sh
+npm install @flagdown/react@0.0.4
 ```
 
-## Current bootstrap API
-
-Wrap the part of the React tree that reads flags in `FlagdownProvider`, then
-read a flag with `useFlag`:
-
 ```tsx
-import { FlagdownProvider, useFlag } from "@flagdown/react";
-
-function BetaFeature() {
-  return useFlag("beta-feature") ? <p>Enabled</p> : null;
-}
+import { Feature } from '@flagdown/react';
 
-export function App() {
+export function Checkout() {
   return (
-    <FlagdownProvider>
-      <BetaFeature />
-    </FlagdownProvider>
+    <Feature
+      flag="new-checkout"
+      fallback={<OldCheckout />}
+    >
+      <NewCheckout />
+    </Feature>
   );
 }
 ```
 
-This initial provider returns `false` for every flag. A future release will
-provide an adapter generated from Flagdown's OpenAPI contract.
+`Feature` renders its children when the named flag is on. When it is off, unknown,
+still loading, or unavailable, it renders `fallback`. Omit `fallback` to render
+nothing in those cases. Only the selected branch mounts; `Feature` adds no DOM
+wrapper.
 
-For tests or custom adapters, supply a `FlagEvaluator` implementation:
+Configure the project once at your app root:
 
 ```tsx
-<FlagdownProvider evaluator={{ isEnabled: (key) => key === "beta-feature" }}>
-  <BetaFeature />
+import { FlagdownProvider } from '@flagdown/react';
+
+<FlagdownProvider
+  apiUrl="https://api.flagdown.dev"
+  clientToken="COPY_PUBLIC_CLIENT_TOKEN_FROM_DASHBOARD"
+>
+  <App />
 </FlagdownProvider>
 ```
+
+Create a project and flag in the dashboard, then copy its integration snippet.
+`apiUrl` is the API base URL without `/v1`. `Feature` must be inside the provider.
+
+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 off;
+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.
+
+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.
+
+`Feature` is the SDK's flag consumption API. The evaluation context and evaluator
+are internal; the package exposes no flag hooks or direct evaluation functions.
+Use `FlagdownProvider` to configure your project. A provider without project
+configuration renders each feature's fallback.

package/dist/index.d.ts

@@ -1,27 +1,22 @@
 import * as react from 'react';
-import { PropsWithChildren } from 'react';
+import { PropsWithChildren, ReactNode } from 'react';
 
-/** A port for resolving a feature flag's enabled state. */
-interface FlagEvaluator {
-    isEnabled(flagKey: string): boolean;
-}
-/**
- * Temporary adapter used until the SDK is connected to the Flagdown API.
- *
- * It deliberately keeps every flag disabled so applications can install the
- * provider and hook safely before remote evaluation is available.
- */
-declare const disabledFlagEvaluator: FlagEvaluator;
+type FeatureProps = PropsWithChildren<{
+    /** Key of the flag controlling this feature. */
+    flag: string;
+    /** Rendered while the flag is off, unknown, loading, or unavailable. */
+    fallback?: ReactNode;
+}>;
+declare function Feature({ flag, fallback, children }: FeatureProps): react.JSX.Element;
 
 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 useFlag(flagKey: string): boolean;
+declare function FlagdownProvider({ children, apiUrl, clientToken, refreshIntervalMs, onError }: FlagdownProviderProps): react.JSX.Element;
 
-export { type FlagEvaluator, FlagdownProvider, type FlagdownProviderProps, disabledFlagEvaluator, useFlag };
+export { Feature, type FeatureProps, FlagdownProvider, type FlagdownProviderProps };

package/dist/index.js

@@ -1,29 +1,84 @@
+// src/Feature.tsx
+import { useContext } from "react";
+
 // src/FlagdownContext.tsx
-import { createContext, useContext } from "react";
+import { createContext } from "react";
 var FlagdownContext = createContext(void 0);
-function useFlag(flagKey) {
+
+// src/Feature.tsx
+import { Fragment, jsx } from "react/jsx-runtime";
+function Feature({ flag, fallback = null, children }) {
   const evaluator = useContext(FlagdownContext);
-  if (!evaluator) {
-    throw new Error("useFlag must be used within a FlagdownProvider");
-  }
-  return evaluator.isEnabled(flagKey);
+  if (!evaluator) throw new Error("Feature must be used within a FlagdownProvider");
+  return /* @__PURE__ */ jsx(Fragment, { children: evaluator.isEnabled(flag) ? children : fallback });
 }
 
+// src/FlagdownProvider.tsx
+import { useEffect, useMemo, useState, useRef } from "react";
+
 // src/flags.ts
 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 });
+import { jsx as jsx2 } from "react/jsx-runtime";
+function FlagdownProvider({ children, apiUrl, clientToken, refreshIntervalMs = 1e4, onError }) {
+  const errorHandler = useRef(onError);
+  useEffect(() => {
+    errorHandler.current = onError;
+  }, [onError]);
+  const [snapshot, setSnapshot] = useState();
+  useEffect(() => {
+    if (!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, refreshIntervalMs]);
+  const value = useMemo(() => snapshot && snapshot.apiUrl === apiUrl && snapshot.clientToken === clientToken ? { isEnabled: (key) => Object.hasOwn(snapshot.flags, key) && snapshot.flags[key] === true } : disabledFlagEvaluator, [snapshot, apiUrl, clientToken]);
+  return /* @__PURE__ */ jsx2(FlagdownContext.Provider, { value, children });
 }
 export {
-  FlagdownProvider,
-  disabledFlagEvaluator,
-  useFlag
+  Feature,
+  FlagdownProvider
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flagdown/react",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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",