@featureflare/react 0.0.5 → 0.0.6-beta.259

package/README.md

@@ -12,150 +12,186 @@ pnpm add @featureflare/react
 yarn add @featureflare/react
 ```
 
-**Peer Dependencies:**
-
-- `react >= 18`
-- `react-dom >= 18`
-
 ## Usage
 
-### Setup Provider
-
-Wrap your app with `FeatureFlareProvider`:
+### Minimal Setup
 
 ```typescript
-import { FeatureFlareProvider } from '@featureflare/react';
+import { FeatureFlareProvider, resolveFeatureFlareBrowserConfig, useFlags } from '@featureflare/react';
+
+function FlagsBootstrap() {
+  useFlags({
+    user: { id: 'user-123', email: 'dev@company.com' },
+    defaultValue: false,
+    refreshIntervalMs: 10000,
+    pauseWhenHidden: true,
+  });
+
+  return null;
+}
 
 export function App() {
+  const config = resolveFeatureFlareBrowserConfig();
+
+  if (!config.sdkKey) {
+    return <div>Feature flags disabled</div>;
+  }
+
   return (
     <FeatureFlareProvider
       config={{
-        // Optional: explicit FeatureFlare API URL
-        apiBaseUrl: 'https://flags.your-company.com',
-        // SDK defaults to FeatureFlare Cloud Run unless overridden
-        sdkKey: 'your-client-key-here' // Client key for browser
+        ...config,
+        bootstrap: {
+          flags: { 'new-nav': true }
+        }
       }}
-      initialUser={{ id: 'user-123' }}
+      initialUser={{ id: 'user-123', key: 'user-123' }}
     >
-      {/* Your app */}
+      <FlagsBootstrap />
+      {/* app */}
     </FeatureFlareProvider>
   );
 }
 ```
 
-### Read Flags
-
-Use the `useBoolFlag` hook to read boolean flags:
+### Read One Flag
 
 ```typescript
-import { useBoolFlag } from '@featureflare/react';
+import { useFlag } from '@featureflare/react';
 
 export function NewNav() {
-  const { value, loading, error } = useBoolFlag('new-nav', false);
-  
+  const { value, loading, error } = useFlag('new-nav', false);
+
   if (loading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  
+  if (error) return <div>Error: {error}</div>;
+
   return value ? <div>New nav ON</div> : <div>New nav OFF</div>;
 }
 ```
 
-### Update User
+### SSR/HTML Bootstrap (anti-flicker working flow)
+
+Server-side (example in Next.js `getServerSideProps`):
+
+```typescript
+import { FeatureFlareClient } from '@featureflare/sdk-js';
+
+export async function getServerSideProps() {
+  const user = { id: 'user-123', key: 'user-123' };
+  const sdk = new FeatureFlareClient({
+    apiBaseUrl: process.env.FEATUREFLARE_API_BASE_URL,
+    sdkKey: process.env.FEATUREFLARE_SERVER_SDK_KEY
+  });
+
+  const nav = await sdk.bool('new-nav', user, false);
+
+  return {
+    props: {
+      user,
+      ffBootstrap: {
+        flags: { 'new-nav': nav }
+      }
+    }
+  };
+}
+```
 
-Use the `useFeatureFlareUser` hook to get and update the current user:
+Client-side provider wiring:
 
 ```typescript
-import { useFeatureFlareUser } from '@featureflare/react';
+import { FeatureFlareProvider, resolveFeatureFlareBrowserConfig } from '@featureflare/react';
 
-export function UserSwitcher() {
-  const [user, setUser] = useFeatureFlareUser();
+export default function Page({ user, ffBootstrap }) {
+  const config = resolveFeatureFlareBrowserConfig();
 
   return (
-    <button
-      onClick={() =>
-        setUser({
-          ...(user ?? { id: 'user-123' }),
-          meta: { ...(user?.meta ?? {}), companyId: 'northwind' }
-        })
-      }
+    <FeatureFlareProvider
+      config={{
+        ...config,
+        bootstrap: ffBootstrap
+      }}
+      initialUser={user}
     >
-      Switch user
-    </button>
+      {/* First render uses bootstrap synchronously; no loading flicker for these flags */}
+      <App />
+    </FeatureFlareProvider>
   );
 }
 ```
 
-## API Reference
+For non-SSR apps, inject a bootstrap JSON payload into HTML before app startup and pass it to `config.bootstrap` the same way.
+
+## API
 
 ### `FeatureFlareProvider`
 
-Provider component that wraps your app and provides the FeatureFlare client context.
+Props:
+
+- `config: FeatureFlareReactConfig`
+- `initialUser: FeatureFlareUserPayload`
+- `user?: FeatureFlareUserPayload` (controlled mode)
+- `onUserChange?: (user: FeatureFlareUserPayload) => void` (required in controlled mode)
+- `children: React.ReactNode`
 
-#### Props
+### `resolveFeatureFlareBrowserConfig(input?)`
 
-- `config: FeatureFlareReactConfig` - Configuration object
-  - `apiBaseUrl?: string` - Optional explicit FeatureFlare API base URL.
-  - `sdkKey?: string` - Client SDK key (recommended). If not provided, reads from `FEATUREFLARE_CLIENT_KEY` env var.
-  - `projectKey?: string` - Legacy: project key (requires `envKey`). Not recommended.
-  - `envKey?: string` - Environment key (default: `'production'`). Only used with `projectKey`.
-- `initialUser: FeatureFlareUserPayload` - Initial user payload
-- `user?: FeatureFlareUserPayload` - Controlled user (requires `onUserChange`)
-- `onUserChange?: (user: FeatureFlareUserPayload) => void` - Callback for user changes (required if using controlled `user`)
-- `children: React.ReactNode` - Your app components
+Builds provider config from common `NEXT_PUBLIC_FEATUREFLARE_*` vars.
 
-### `useBoolFlag(flagKey: string, defaultValue: boolean)`
+Returns:
 
-Hook to evaluate a boolean feature flag.
+- `apiBaseUrl?: string`
+- `envKey: 'development' | 'staging' | 'production'`
+- `sdkKey?: string`
 
-**Returns:**
+### `useFeatureFlareUser()`
 
-- `value: boolean` - The flag value
-- `loading: boolean` - Whether the evaluation is in progress
-- `error: Error | null` - Error if evaluation failed
+Returns:
 
-**Example:**
+- `[user, setUser]`
 
-```typescript
-const { value, loading, error } = useBoolFlag('feature-flag', false);
-```
+### `useFlags(...)`
 
-### `useFeatureFlareUser()`
+Signatures:
 
-Hook to get and update the current user.
+- `useFlags(keys: string[], defaultValue?: boolean)` → `{ values, loading, errors }`
+- `useFlags(input?: { user?: FeatureFlareUserPayload; defaultValue?: boolean; refreshIntervalMs?: number; hiddenRefreshIntervalMs?: number; pauseWhenHidden?: boolean; enabled?: boolean })`
+- `useFlags(defaultValue?: boolean, options?: { refreshIntervalMs?: number; hiddenRefreshIntervalMs?: number; pauseWhenHidden?: boolean; enabled?: boolean })`
 
-**Returns:**
+### `useBoolFlags(...)`
 
-`[user: FeatureFlareUserPayload | null, setUser: (user: FeatureFlareUserPayload) => void]`
+Signatures:
 
-**Example:**
+- `useBoolFlags(keys: string[], defaultValue?: boolean)` → `{ values, loading, errors }`
+- `useBoolFlags(defaultValue?: boolean, options?: { refreshIntervalMs?: number; hiddenRefreshIntervalMs?: number; pauseWhenHidden?: boolean; enabled?: boolean })` → `{ values, loading, errors }` (all flags)
 
-```typescript
-const [user, setUser] = useFeatureFlareUser();
-```
+Returns:
 
-## Environment Variables
+- `flags: Array<{ key: string; value: boolean }>`
+- `loading: boolean`
+- `error: string | null`
 
-The SDK automatically reads from environment variables if `sdkKey` is not provided:
+### `useFlag(key, defaultValue?)`
 
-- `FEATUREFLARE_CLIENT_KEY` - Client SDK key
+Selector-based single-flag subscription. Components only re-render when that flag changes.
 
-```typescript
-// This will use FEATUREFLARE_CLIENT_KEY from env if sdkKey is not provided
-<FeatureFlareProvider config={{}} initialUser={{ id: 'user-123' }}>
-  {/* ... */}
-</FeatureFlareProvider>
-```
+### `useFlagDiagnostics(key)`
 
-## API Base URL
+Returns per-flag runtime diagnostics (source, stale state, cache timestamps, latency).
 
-The SDK automatically uses `window.location.origin` in the browser (assumes API is on same origin). The API URL cannot be overridden.
+Behavior:
 
-## SDK Keys
+- Immediate fetch on mount/user change.
+- Shared polling via provider context (multiple consumers do not duplicate requests).
+- Optional polling controls with hidden-tab awareness.
+- If `user` is provided in input form, hook syncs provider user automatically.
 
-Use **client keys** for browser/mobile applications. Client keys are not secret and will be visible in your JavaScript bundle.
+## Notes
 
-Get your SDK keys from your FeatureFlare Console → Environments.
+- Use client SDK keys in browser apps.
+- If `config.sdkKey` is missing, skip initializing the provider.
 
-## License
+## Security: Client-side flags are not authorization
 
-MIT
+Client keys can be extracted from your frontend bundle. **Never gate truly sensitive operations solely with client-evaluated flags**—enforce authorization on your backend.
+- `config.bootstrap?: { flags, killSwitches }` for SSR/HTML bootstrap to avoid first-render flicker
+- `config.timeoutMs | maxRetries | backoffMs | jitter | cacheTtlMs | staleTtlMs | realtime` are forwarded to the SDK client