@dr-sentry/react 1.0.0

package/README.md

@@ -0,0 +1,258 @@
+# @deploysentry/react
+
+Official React SDK for the DeploySentry feature flag platform. Provides React hooks and a context provider for evaluating feature flags with real-time SSE updates.
+
+## Installation
+
+```bash
+npm install @deploysentry/react
+```
+
+React 18 or later is required as a peer dependency.
+
+## Quick Start
+
+Wrap your application with `DeploySentryProvider` and use hooks anywhere in the tree:
+
+```tsx
+import { DeploySentryProvider, useFlag } from '@deploysentry/react';
+
+function App() {
+  return (
+    <DeploySentryProvider
+      apiKey="ds_live_abc123"
+      baseURL="https://api.dr-sentry.com"
+      environment="production"
+      project="my-app"
+      application="my-web-app"
+      user={{ id: 'user-42' }}
+    >
+      <MyComponent />
+    </DeploySentryProvider>
+  );
+}
+
+function MyComponent() {
+  const showBanner = useFlag('show-banner', false);
+
+  if (!showBanner) return null;
+  return <div>New feature banner!</div>;
+}
+```
+
+## Provider Props
+
+| Prop          | Type         | Required | Description                                      |
+|---------------|--------------|----------|--------------------------------------------------|
+| `apiKey`      | `string`     | Yes      | API key for authenticating with DeploySentry.     |
+| `baseURL`     | `string`     | Yes      | Base URL of the DeploySentry API.                 |
+| `environment` | `string`     | Yes      | Environment identifier (e.g. `"production"`).     |
+| `project`     | `string`     | Yes      | Project identifier.                               |
+| `application` | `string`      | Yes      | Application identifier                     |
+| `user`        | `UserContext` | No      | User context for targeting rules.                 |
+| `children`    | `ReactNode`  | Yes      | React children.                                   |
+| `mode`        | `string`     | No       | SDK mode: `server`, `file`, or `server-with-fallback`. |
+| `flagData`    | `object`     | No       | Pre-loaded flag config for file/fallback mode.    |
+
+## Offline / File Mode
+
+For offline use or testing, pass pre-loaded flag config via the `flagData` prop:
+
+```tsx
+import flagConfig from './.deploysentry/flags.json';
+
+<DeploySentryProvider
+  apiKey="not-used"
+  baseURL=""
+  environment="staging"
+  project="my-project"
+  application="my-web-app"
+  mode="file"
+  flagData={flagConfig}
+>
+  <App />
+</DeploySentryProvider>
+```
+
+### Modes
+
+| Mode | Behavior |
+| --- | --- |
+| `server` (default) | API calls + SSE streaming |
+| `file` | Use `flagData` prop, evaluate locally. No server contact. |
+| `server-with-fallback` | Try server first. If unavailable, use `flagData` as fallback. |
+
+Export the config from the dashboard (App Settings → Export flags.yaml), then convert to JSON or import with a YAML plugin.
+
+## Hooks
+
+### `useFlag(key, defaultValue)`
+
+Returns the resolved flag value. Falls back to `defaultValue` while loading or if the flag does not exist.
+
+```tsx
+const isEnabled = useFlag('dark-mode', false);
+const variant = useFlag('checkout-flow', 'control');
+```
+
+### `useFlagDetail(key)`
+
+Returns detailed evaluation information including metadata.
+
+```tsx
+const { value, enabled, metadata, loading } = useFlagDetail('new-checkout');
+
+// metadata contains: category, purpose, owners, isPermanent, expiresAt, tags
+```
+
+### `useFlagsByCategory(category)`
+
+Returns all flags matching the given category.
+
+```tsx
+const experiments = useFlagsByCategory('experiment');
+const releases = useFlagsByCategory('release');
+```
+
+Categories: `'release'` | `'feature'` | `'experiment'` | `'ops'` | `'permission'`
+
+### `useExpiredFlags()`
+
+Returns all non-permanent flags whose `expiresAt` date is in the past. Useful for admin dashboards.
+
+```tsx
+const expired = useExpiredFlags();
+```
+
+### `useDispatch(operation)`
+
+Returns the resolved handler for a registered operation based on current flag state. See [Register / Dispatch Pattern](#register--dispatch-pattern) below.
+
+```tsx
+const checkout = useDispatch<() => Promise<void>>('checkout');
+await checkout();
+```
+
+### `useDeploySentry()`
+
+Returns the raw `DeploySentryClient` instance for advanced use-cases.
+
+```tsx
+const client = useDeploySentry();
+```
+
+## Register / Dispatch Pattern
+
+The register/dispatch pattern centralizes all flag-gated behavior in one place instead of scattering `if/else` checks across components.
+
+### Setup (single-point registration)
+
+Create one registration file that runs at app initialization:
+
+```typescript
+// src/flags/registrations.ts
+import type { DeploySentryClient } from '@deploysentry/react';
+import { legacySearch, vectorSearch } from '../search';
+import { classicCheckout, newCheckout } from '../checkout';
+
+export function registerFlags(client: DeploySentryClient) {
+  // Search — default handler, then flag-gated override
+  client.register('search', legacySearch);
+  client.register('search', vectorSearch, 'vector-search-v2');
+
+  // Checkout
+  client.register('checkout', classicCheckout);
+  client.register('checkout', newCheckout, 'new-checkout-flow');
+}
+```
+
+Call `registerFlags(client)` after the client initializes (e.g. in the provider setup or an app-level effect).
+
+### Usage in components
+
+```tsx
+import { useDispatch } from '@deploysentry/react';
+
+function SearchBar() {
+  const search = useDispatch<(query: string) => Promise<Results>>('search');
+
+  return (
+    <input onChange={(e) => search(e.target.value).then(setResults)} />
+  );
+}
+```
+
+### How it works
+
+1. **`client.register(operation, handler, flagKey?)`** — Register a handler for a named operation. With `flagKey`, it's only selected when that flag is enabled. Without `flagKey`, it's the default fallback.
+2. **`useDispatch(operation)`** — Returns the first registered handler whose flag is enabled, or the default handler. The component never knows about flags.
+
+### Why single-point registration
+
+- One file shows every flag-gated behavior in the app
+- Easy auditing — search for a flag key and find every behavior it controls
+- Simple cleanup when a flag is retired (remove the registration, keep the handler)
+- LLMs and code review tools can read one file to understand all flag-gated behavior
+
+## Real-Time Updates
+
+The provider automatically opens an SSE connection to receive flag updates in real time. When a flag changes on the server, all components consuming that flag re-render immediately. The connection reconnects automatically with exponential backoff if it drops.
+
+## SSR Compatibility
+
+Hooks return default/empty values during server-side rendering. Flags are fetched client-side after the provider mounts.
+
+## Types
+
+All types are exported from the package:
+
+```tsx
+import type {
+  Flag,
+  FlagCategory,
+  FlagDetail,
+  FlagMetadata,
+  ProviderProps,
+  UserContext,
+} from '@deploysentry/react';
+```
+
+## Authentication
+
+All requests use an API key passed in the `Authorization` header:
+
+```
+Authorization: ApiKey <your-api-key>
+```
+
+Pass the key via the provider's `apiKey` prop. The SDK sets the header automatically.
+
+### Session Consistency
+
+Bind evaluations to a session so the server caches results for a consistent user experience:
+
+```tsx
+<DeploySentryProvider
+  apiKey="ds_key_xxxxxxxxxxxx"
+  baseURL="https://api.dr-sentry.com"
+  environment="production"
+  project="my-app"
+  application="my-web-app"
+  sessionId={`user:${userId}`}
+>
+  <App />
+</DeploySentryProvider>
+```
+
+```tsx
+const client = useDeploySentry();
+await client.refreshSession();
+```
+
+- The session ID is sent as an `X-DeploySentry-Session` header on every request.
+- The server caches evaluation results per session for 30 minutes (sliding TTL).
+- Omit the session ID to always get fresh evaluations on each request.
+
+## License
+
+Apache-2.0

package/dist/cjs/client.d.ts

@@ -0,0 +1,121 @@
+import type { EvaluationContext, Flag, FlagConfig, FlagDetail, FlagMetadata, UserContext } from './types';
+/** Listener callback invoked whenever the flag store is updated. */
+export type FlagChangeListener = () => void;
+/**
+ * Lightweight HTTP + SSE client that manages the local flag store.
+ *
+ * This client is designed for browser environments. It uses the native
+ * `fetch` and `EventSource` APIs, so no polyfills are required in modern
+ * browsers.
+ */
+export declare class DeploySentryClient {
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly environment;
+    private readonly project;
+    private readonly application;
+    private readonly sessionId;
+    private readonly mode;
+    private flagConfig;
+    private user;
+    /** In-memory flag store keyed by flag key. */
+    private readonly flags;
+    /** Registry of operation handlers for the register/dispatch pattern. */
+    private registry;
+    /** Subscribed listeners notified on any flag change. */
+    private readonly listeners;
+    /** Active SSE connection, if any. */
+    private eventSource;
+    /** Whether the initial fetch has completed at least once. */
+    private initialised;
+    /** Whether the client has been destroyed. */
+    private destroyed;
+    /** Retry state for SSE reconnection. */
+    private sseRetryTimer;
+    private sseRetryCount;
+    private static readonly SSE_MAX_RETRY_DELAY_MS;
+    constructor(options: {
+        apiKey: string;
+        baseURL: string;
+        environment: string;
+        project: string;
+        application: string;
+        user?: UserContext;
+        sessionId?: string;
+        mode?: 'server' | 'file' | 'server-with-fallback';
+        flagConfig?: FlagConfig;
+    });
+    /** Fetch all flags from the API and start listening for SSE updates. */
+    init(): Promise<void>;
+    /** Stop the SSE connection and release resources. */
+    destroy(): void;
+    /** Clear the local flag store and re-fetch all flags from the API. */
+    refreshSession(): Promise<void>;
+    /** Update the user context and re-fetch flags. */
+    identify(user: UserContext | undefined): Promise<void>;
+    /** Subscribe to flag changes. Returns an unsubscribe function. */
+    subscribe(listener: FlagChangeListener): () => void;
+    /** True once the first successful fetch has completed. */
+    get isInitialised(): boolean;
+    /** Return the stored {@link Flag} for the given key, or `undefined`. */
+    getFlag(key: string): Flag | undefined;
+    /** Return all stored flags. */
+    getAllFlags(): Flag[];
+    /** Build a {@link FlagMetadata} object for a stored flag. */
+    getFlagMetadata(key: string): FlagMetadata | undefined;
+    /**
+     * Register a handler for the given operation name.
+     *
+     * When `flagKey` is provided the handler is used only when that flag is
+     * enabled. Omit `flagKey` to register the default (fallback) handler.
+     */
+    register<T extends (...args: any[]) => any>(operation: string, handler: T, flagKey?: string): void;
+    /**
+     * Dispatch the appropriate handler for the given operation.
+     *
+     * Returns the first registered handler whose flag is enabled. Falls back
+     * to the default (no-flagKey) handler if no flagged handler matches.
+     *
+     * @throws If no handlers are registered for the operation.
+     * @throws If no flagged handler matches and no default is registered.
+     */
+    dispatch<T extends (...args: any[]) => any>(operation: string, _context?: EvaluationContext): T;
+    /**
+     * Evaluate a boolean flag from the in-memory store.
+     *
+     * No API call is made -- the value comes from the flags already fetched
+     * via {@link init} and kept up-to-date by SSE.
+     */
+    boolValue(key: string, defaultValue: boolean): boolean;
+    /**
+     * Evaluate a string flag from the in-memory store.
+     */
+    stringValue(key: string, defaultValue: string): string;
+    /**
+     * Evaluate a number flag from the in-memory store.
+     *
+     * TypeScript has no separate `int` type -- this returns `number` and is
+     * the idiomatic equivalent of `intValue` / `floatValue` in other SDKs.
+     */
+    numberValue(key: string, defaultValue: number): number;
+    /**
+     * Evaluate a JSON (object) flag from the in-memory store.
+     */
+    jsonValue<T extends object = object>(key: string, defaultValue: T): T;
+    /**
+     * Return the full evaluation detail for a flag from the in-memory store.
+     *
+     * Returns `{ value, enabled, metadata, loading }` matching the
+     * {@link FlagDetail} interface used by the `useFlagDetail` hook.
+     */
+    detail(key: string): FlagDetail;
+    private get headers();
+    private buildQueryParams;
+    private fetchFlags;
+    private connectSSE;
+    private handleSSEMessage;
+    private disconnectSSE;
+    private scheduleReconnect;
+    private emit;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}