@flagdown/react 0.0.4 → 0.0.6

package/README.md

@@ -3,7 +3,7 @@
 Use the `Feature` component to switch between new UI and a fallback in React 18+.
 
 ```sh
-npm install @flagdown/react@0.0.4
+npm install @flagdown/react@0.0.6
 ```
 
 ```tsx
@@ -49,11 +49,47 @@ a successful later refresh restores values. An optional `onError(error)` callbac
 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
+Client tokens are public and project-scoped. They read flags and submit feature
+error reports; they cannot manage flags or read error reports. Replacing a token in the dashboard invalidates the previous token; update
 apps using it. Client-side flags are not an authorization boundary.
 
+### Feature errors
+
+`Feature` catches errors thrown by its enabled descendants during rendering,
+constructors and React lifecycle/effect work. It renders `fallback` (or nothing)
+and submits one best-effort error report, including the flag key, bounded error
+message, JavaScript stack, React component stack and SDK version. Read reports in
+the dashboard's **Recent feature errors** section. Errors do not change the flag
+for other users. Repeated polls keep a crashed feature on its fallback. Remount
+the feature, toggle it off then on, or change project configuration to retry it.
+
+`onError` receives both flag-read failures and caught feature errors. Reporting
+failures never recurse or prevent the fallback from rendering. Uploads time out
+after five seconds and are not retried. Set `captureErrors={false}` on the provider
+to disable uploads while retaining fallback behavior and the `onError` callback.
+
+Only the enabled subtree is covered. Errors in event handlers, asynchronous
+callbacks/promises, server rendering, and the fallback itself are not caught.
+Nested features use the nearest boundary. No global browser listeners, cookies,
+user identity or page URL are collected. URL queries/fragments and the configured
+client token are removed from report text. Error messages and stacks can still
+contain application data; disable uploads if those strings contain sensitive data.
+
+The API accepts up to 60 new reports per project per minute, retains the latest
+100 reports, and returns the newest 50 to authenticated project members. Client
+reports are untrusted diagnostic data, not evidence for automatic rollback.
+
 `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.
+
+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.
+
+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

@@ -4,19 +4,22 @@ import { PropsWithChildren, ReactNode } from 'react';
 type FeatureProps = PropsWithChildren<{
     /** Key of the flag controlling this feature. */
     flag: string;
-    /** Rendered while the flag is off, unknown, loading, or unavailable. */
+    /** Rendered while the flag is off, unavailable, or its enabled UI has crashed. */
     fallback?: ReactNode;
 }>;
 declare function Feature({ flag, fallback, children }: FeatureProps): react.JSX.Element;
 
 interface FlagdownProviderProps extends PropsWithChildren {
     apiUrl?: string;
-    /** Public, read-only project token copied from the dashboard. */
+    /** Public project token for flag reads and feature error reports. */
     clientToken?: string;
     /** Refresh interval; minimum 1 second, default 10 seconds. */
     refreshIntervalMs?: number;
+    /** Send errors caught by Feature to the project's recent error list. Default true. */
+    captureErrors?: boolean;
+    /** Called for flag-read failures and errors caught by Feature. */
     onError?: (error: Error) => void;
 }
-declare function FlagdownProvider({ children, apiUrl, clientToken, refreshIntervalMs, onError }: FlagdownProviderProps): react.JSX.Element;
+declare function FlagdownProvider({ children, apiUrl, clientToken, refreshIntervalMs, captureErrors, onError }: FlagdownProviderProps): react.JSX.Element;
 
 export { Feature, type FeatureProps, FlagdownProvider, type FlagdownProviderProps };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/Feature.tsx
-import { useContext } from "react";
+import { Component, useContext } from "react";
 
 // src/FlagdownContext.tsx
 import { createContext } from "react";
@@ -7,42 +7,130 @@ var FlagdownContext = createContext(void 0);
 
 // src/Feature.tsx
 import { Fragment, jsx } from "react/jsx-runtime";
+var FeatureBoundary = class extends Component {
+  state = { failed: false, scope: this.props.scope };
+  static getDerivedStateFromProps(props, state) {
+    return props.scope === state.scope ? null : { failed: false, scope: props.scope };
+  }
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  componentDidCatch(error, info) {
+    try {
+      this.props.reportError?.(this.props.flag, error, info.componentStack ?? "");
+    } catch {
+    }
+  }
+  render() {
+    return this.state.failed ? this.props.fallback : this.props.children;
+  }
+};
 function Feature({ flag, fallback = null, children }) {
   const evaluator = useContext(FlagdownContext);
   if (!evaluator) throw new Error("Feature must be used within a FlagdownProvider");
-  return /* @__PURE__ */ jsx(Fragment, { children: evaluator.isEnabled(flag) ? children : fallback });
+  if (!evaluator.isEnabled(flag)) return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+  return /* @__PURE__ */ jsx(FeatureBoundary, { flag, fallback, scope: evaluator.scope, reportError: evaluator.reportError, children }, flag);
 }
 
 // src/FlagdownProvider.tsx
-import { useEffect, useMemo, useState, useRef } from "react";
+import { useCallback, useEffect, useMemo, useState, useRef } from "react";
 
 // src/flags.ts
 var disabledFlagEvaluator = {
   isEnabled: () => false
 };
 
+// src/api-types.ts
+var clientFlagsPath = "/v1/client/flags";
+var clientErrorsPath = "/v1/client/errors";
+
 // 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;
+}
+
+// package.json
+var version = "0.0.6";
+
+// src/errors.ts
+function normalizeFeatureError(value) {
+  try {
+    return value instanceof Error ? value : new Error(String(value));
+  } catch {
+    return new Error("Unknown feature error");
+  }
+}
+async function reportFeatureError(apiUrl, clientToken, flagKey, error, componentStack) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5e3);
+  try {
+    const clean = (text, limit) => text.replaceAll(clientToken, "[client token]").replace(/https?:\/\/[^\s)]+/g, (url) => url.replace(/[?#].*$/, "")).slice(0, limit);
+    const report = {
+      eventId: crypto.randomUUID(),
+      flagKey,
+      name: clean(error.name || "Error", 100),
+      message: clean(error.message, 1e3),
+      stack: error.stack ? clean(error.stack, 4e3) : void 0,
+      componentStack: clean(componentStack, 2e3),
+      sdkVersion: version
+    };
+    let body = JSON.stringify(report);
+    if (new TextEncoder().encode(body).byteLength > 16384) {
+      delete report.stack;
+      delete report.componentStack;
+      body = JSON.stringify(report);
+    }
+    const headers = {
+      "x-flagdown-client-token": clientToken,
+      "Content-Type": "application/json"
+    };
+    await fetch(apiUrl.replace(/\/$/, "") + clientErrorsPath, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal,
+      keepalive: true,
+      credentials: "omit",
+      cache: "no-store"
+    });
+  } catch {
+  } finally {
+    clearTimeout(timeout);
+  }
 }
 
 // src/FlagdownProvider.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
-function FlagdownProvider({ children, apiUrl, clientToken, refreshIntervalMs = 1e4, onError }) {
+function FlagdownProvider({ children, apiUrl, clientToken, refreshIntervalMs = 1e4, captureErrors = true, onError }) {
   const errorHandler = useRef(onError);
   useEffect(() => {
     errorHandler.current = onError;
   }, [onError]);
+  const scope = useMemo(() => ({}), [apiUrl, clientToken]);
+  const reportError = useCallback((flagKey, value2, componentStack) => {
+    const error = normalizeFeatureError(value2);
+    if (captureErrors && apiUrl && clientToken) void reportFeatureError(apiUrl, clientToken, flagKey, error, componentStack);
+    try {
+      errorHandler.current?.(error);
+    } catch {
+    }
+  }, [apiUrl, clientToken, captureErrors]);
   const [snapshot, setSnapshot] = useState();
   useEffect(() => {
     if (!apiUrl || !clientToken) return;
@@ -75,7 +163,11 @@ function FlagdownProvider({ children, apiUrl, clientToken, refreshIntervalMs = 1
       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]);
+  const value = useMemo(() => ({
+    scope,
+    reportError,
+    ...snapshot && snapshot.apiUrl === apiUrl && snapshot.clientToken === clientToken ? { isEnabled: (key) => Object.hasOwn(snapshot.flags, key) && snapshot.flags[key] === true } : disabledFlagEvaluator
+  }), [snapshot, apiUrl, clientToken, scope, reportError]);
   return /* @__PURE__ */ jsx2(FlagdownContext.Provider, { value, children });
 }
 export {

package/package.json

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