@flagdown/react 0.0.3 → 0.0.5

package/README.md

@@ -1,32 +1,50 @@
 # @flagdown/react
 
-Read boolean feature flags from a Flagdown project in React 18+.
+Use the `Feature` component to switch between new UI and a fallback in React 18+.
+
+```sh
+npm install @flagdown/react@0.0.5
+```
 
 ```tsx
-import { FlagdownProvider, useFlag } from '@flagdown/react';
+import { Feature } from '@flagdown/react';
 
-function Checkout() {
-  const enabled = useFlag('new-checkout');
-  return enabled ? <NewCheckout /> : <CurrentCheckout />;
+export function Checkout() {
+  return (
+    <Feature
+      flag="new-checkout"
+      fallback={<OldCheckout />}
+    >
+      <NewCheckout />
+    </Feature>
+  );
 }
+```
+
+`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.
+
+Configure the project once at your app root:
+
+```tsx
+import { FlagdownProvider } from '@flagdown/react';
 
 <FlagdownProvider
-  apiUrl="https://your-flagdown-api.example.com"
+  apiUrl="https://api.flagdown.dev"
   clientToken="COPY_PUBLIC_CLIENT_TOKEN_FROM_DASHBOARD"
 >
-  <Checkout />
+  <App />
 </FlagdownProvider>
 ```
 
-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.
+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 `false`;
+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.
@@ -35,14 +53,17 @@ 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:
+`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.
 
-```tsx
-<FlagdownProvider evaluator={{ isEnabled: key => key === 'new-checkout' }}>
-  <Checkout />
-</FlagdownProvider>
-```
+API transport types are generated from `openapi/flagdown-api.json` with
+`openapi-typescript` before SDK typechecking and building. They stay internal;
+the public exports remain `Feature`, `FlagdownProvider` and their prop types.
+The runtime still rejects malformed or non-boolean flag values.
 
-An explicit evaluator takes precedence over remote configuration. A provider
-without either configuration evaluates every flag off. `useFlag` must be called
-inside a provider.
+For SDK development, run `npm run --workspace @flagdown/react generate:types`
+to regenerate `src/generated/api.d.ts`. This file is ignored by git and is never
+the source of truth. Backend CI checks candidate contracts against the current
+SDK before publishing the generated specification to this repository.

package/dist/index.d.ts

@@ -1,20 +1,15 @@
 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 {
-    evaluator?: FlagEvaluator;
     apiUrl?: string;
     /** Public, read-only project token copied from the dashboard. */
     clientToken?: string;
@@ -22,8 +17,6 @@ interface FlagdownProviderProps extends PropsWithChildren {
     refreshIntervalMs?: number;
     onError?: (error: Error) => void;
 }
-declare function FlagdownProvider({ children, evaluator, apiUrl, clientToken, refreshIntervalMs, onError }: 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,47 +1,60 @@
-// src/FlagdownProvider.tsx
-import { useEffect, useMemo, useState, useRef } from "react";
+// 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/api-types.ts
+var clientFlagsPath = "/v1/client/flags";
+
 // src/remote.ts
 async function fetchFlagState(apiUrl, clientToken, signal) {
-  const response = await fetch(apiUrl.replace(/\/$/, "") + "/v1/client/flags", {
-    headers: { "x-flagdown-client-token": clientToken },
+  const headers = { "x-flagdown-client-token": clientToken };
+  const response = await fetch(apiUrl.replace(/\/$/, "") + clientFlagsPath, {
+    headers,
     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")) {
+  if (!data || typeof data !== "object" || !("flags" in data) || !data.flags || typeof data.flags !== "object" || Array.isArray(data.flags)) {
     throw new Error("Invalid Flagdown response");
   }
-  return data.flags;
+  const flags = Object.fromEntries(Object.entries(data.flags).map(([key, enabled]) => {
+    if (typeof enabled !== "boolean") throw new Error("Invalid Flagdown response");
+    return [key, enabled];
+  }));
+  const result = { flags };
+  return result.flags;
 }
 
 // src/FlagdownProvider.tsx
-import { jsx } from "react/jsx-runtime";
-function FlagdownProvider({ children, evaluator, apiUrl, clientToken, refreshIntervalMs = 1e4, onError }) {
+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 (evaluator || !apiUrl || !clientToken) return;
+    if (!apiUrl || !clientToken) return;
     let active = true;
     let timer;
     let controller;
@@ -70,12 +83,11 @@ function FlagdownProvider({ children, evaluator, apiUrl, clientToken, refreshInt
       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 });
+  }, [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.3",
+  "version": "0.0.5",
   "license": "MIT",
   "type": "module",
   "description": "React SDK for evaluating Flagdown feature flags.",
@@ -28,9 +28,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "generate:types": "node scripts/generate-api-types.mjs",
+    "build": "node scripts/generate-api-types.mjs && tsup src/index.ts --format esm --dts --clean",
     "test": "bun test",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "node scripts/generate-api-types.mjs && tsc --noEmit"
   },
   "peerDependencies": {
     "react": ">=18",
@@ -38,6 +39,7 @@
   },
   "devDependencies": {
     "@types/react": "^18",
+    "openapi-typescript": "7.13.0",
     "react": "^18",
     "react-dom": "^18",
     "tsup": "^8",