tempest-react-sdk 0.1.2 → 0.1.4

package/README.md

@@ -168,8 +168,8 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `theme`                                    | `ThemeProvider`, `useTheme`, `getInitialTheme`, `themeInitScript`, types: `ThemeMode`, `ResolvedTheme`                                                                                                                                                                                                                                                                                                                                                                             |
 | `i18n`                                     | `createI18n`, `I18nProvider`, `useI18n`, `useTranslate`, types: `Catalog`, `Messages`, `I18n`, `InterpolationValues`                                                                                                                                                                                                                                                                                                                                                               |
 | `logger`                                   | `createLogger`, `consoleSink`, types: `Logger`, `LogEntry`, `LogLevel`, `LoggerSink`                                                                                                                                                                                                                                                                                                                                                                                               |
-| `telemetry`                                | `TelemetryProvider`, `useTelemetry`, `consoleTelemetryAdapter`, types: `TelemetryAdapter`, `TelemetryEvent`, `TelemetryUser`                                                                                                                                                                                                                                                                                                                                                       |
-| `feature-flags`                            | `FeatureFlagsProvider`, `useFeatureFlag`, `useFlagValue`, `createInMemoryFlags`, types: `FeatureFlagsAdapter`, `FlagValue`                                                                                                                                                                                                                                                                                                                                                         |
+| `telemetry`                                | `TelemetryProvider`, `useTelemetry`, `consoleTelemetryAdapter`, `createSentryTelemetryAdapter`, `createPostHogTelemetryAdapter`, types: `TelemetryAdapter`, `TelemetryEvent`, `TelemetryUser`, `CreateSentryTelemetryAdapterOptions`, `SentryLike`, `CreatePostHogTelemetryAdapterOptions`, `PostHogLike`                                                                                                                                                                          |
+| `feature-flags`                            | `FeatureFlagsProvider`, `useFeatureFlag`, `useFlagValue`, `createInMemoryFlags`, `createGrowthBookFeatureFlagsAdapter`, `createLaunchDarklyFeatureFlagsAdapter`, types: `FeatureFlagsAdapter`, `FlagValue`, `GrowthBookLike`, `LDClientLike`                                                                                                                                                                                                                                       |
 | `share`                                    | `share`, `isShareSupported`, types: `SharePayload`, `ShareResult`                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `utils`                                    | `cn`, `formatCurrency`, `formatDate`, `formatDateTime`, `formatPhone`, `formatCPF`, `formatPercent`, `storage`                                                                                                                                                                                                                                                                                                                                                                     |
 
@@ -1241,7 +1241,7 @@ function Header() {
 
 ### Feature flags recipe
 
-`FeatureFlagsProvider` takes an `adapter` matching the `FeatureFlagsAdapter` interface (`isEnabled`, `get`, `subscribe`). Ship the `InMemory` adapter while you build, swap for GrowthBook / LaunchDarkly when you're ready.
+`FeatureFlagsProvider` takes an `adapter` matching the `FeatureFlagsAdapter` interface (`isEnabled`, `get`, `onChange?`). Ship the `InMemory` adapter while you build, swap for GrowthBook / LaunchDarkly when you're ready.
 
 ```tsx
 import {
@@ -1252,7 +1252,7 @@ import {
 } from "tempest-react-sdk";
 
 const flags = createInMemoryFlags({
-  flags: { "new-checkout": true, "max-items": 10 },
+  initial: { "new-checkout": true, "max-items": 10 },
 });
 
 <FeatureFlagsProvider adapter={flags}>
@@ -1266,16 +1266,61 @@ function CheckoutButton() {
 }
 ```
 
-The interface is intentionally tiny — any third-party SDK can be wrapped into an adapter in ~20 lines.
+**GrowthBook adapter** — wraps a `GrowthBook` instance. The app initialises GrowthBook (so it controls `apiHost`, `clientKey`, attributes, `loadFeatures()`), the adapter only routes lookups.
+
+```ts
+import { GrowthBook } from "@growthbook/growthbook";
+import { FeatureFlagsProvider, createGrowthBookFeatureFlagsAdapter } from "tempest-react-sdk";
+
+const gb = new GrowthBook({
+    apiHost: import.meta.env.VITE_GROWTHBOOK_API_HOST,
+    clientKey: import.meta.env.VITE_GROWTHBOOK_KEY,
+    attributes: { id: userId },
+});
+await gb.loadFeatures();
+
+const adapter = createGrowthBookFeatureFlagsAdapter({ growthbook: gb });
+
+<FeatureFlagsProvider adapter={adapter}>
+    <App />
+</FeatureFlagsProvider>;
+```
+
+Mapping: `isEnabled(key)` → `growthbook.isOn(key)`; `get(key, default)` → `growthbook.getFeatureValue(key, default)`; `onChange(listener)` → `growthbook.setRenderer(...)` (installed lazily on first subscription, multiplexes to all listeners).
+
+**LaunchDarkly adapter** — wraps `launchdarkly-js-client-sdk`.
+
+```ts
+import * as LDClient from "launchdarkly-js-client-sdk";
+import { FeatureFlagsProvider, createLaunchDarklyFeatureFlagsAdapter } from "tempest-react-sdk";
+
+const client = LDClient.initialize(import.meta.env.VITE_LD_CLIENT_ID, {
+    kind: "user",
+    key: userId,
+});
+await client.waitUntilReady();
+
+const adapter = createLaunchDarklyFeatureFlagsAdapter({ client });
+
+<FeatureFlagsProvider adapter={adapter}>
+    <App />
+</FeatureFlagsProvider>;
+```
+
+Mapping: `isEnabled(key)` → `client.variation(key, default) === true`; `get(key, default)` → `client.variation(key, default)`; `onChange(listener)` → `client.on("change", listener)` + `client.off` on unsubscribe.
+
+Neither `@growthbook/growthbook` nor `launchdarkly-js-client-sdk` is declared as a peer dep — the adapter only touches the instance you hand it. Install whichever you opt into: `npm install @growthbook/growthbook` or `npm install launchdarkly-js-client-sdk`.
+
+The `FeatureFlagsAdapter` interface is intentionally tiny — any third-party SDK can be wrapped into an adapter in ~20 lines.
 
 ### Telemetry recipe
 
-`TelemetryProvider` accepts an adapter matching `TelemetryAdapter` (`identify`, `track`, `captureException`, `flush`). The default `consoleTelemetryAdapter` logs every event — useful for dev and tests.
+`TelemetryProvider` accepts an adapter matching `TelemetryAdapter` (`init?`, `identify`, `track`, `captureException`, `flush?`). The bundled `consoleTelemetryAdapter` logs every event — useful for dev and tests.
 
 ```tsx
 import { TelemetryProvider, useTelemetry, consoleTelemetryAdapter } from "tempest-react-sdk";
 
-<TelemetryProvider adapter={consoleTelemetryAdapter()}>
+<TelemetryProvider adapter={consoleTelemetryAdapter}>
   <App />
 </TelemetryProvider>;
 
@@ -1284,7 +1329,7 @@ function CheckoutForm() {
   return (
     <Button
       onClick={() => {
-        telemetry.track("checkout.completed", { total: 100 });
+        telemetry?.track({ name: "checkout.completed", properties: { total: 100 } });
       }}
     >
       Pagar
@@ -1293,7 +1338,74 @@ function CheckoutForm() {
 }
 ```
 
-Concrete adapters for Sentry / PostHog / Datadog are part of the v0.2 roadmap — for now you can write one in ~20 lines (see [`docs/telemetry.md`](./docs/telemetry.md)).
+`useTelemetry()` returns `null` when no provider is mounted — call sites should optional-chain (`telemetry?.track(...)`).
+
+**Sentry adapter** — wraps `@sentry/browser` so the SDK never depends on Sentry directly. The Sentry namespace is supplied by the caller; if the app already initialises Sentry at startup, just pass that instance.
+
+```ts
+import * as Sentry from "@sentry/browser";
+import { createSentryTelemetryAdapter, TelemetryProvider } from "tempest-react-sdk";
+
+const adapter = createSentryTelemetryAdapter({
+    sentry: Sentry,
+    initOptions: {
+        dsn: import.meta.env.VITE_SENTRY_DSN,
+        environment: import.meta.env.MODE,
+        tracesSampleRate: 0.1,
+    },
+    flushTimeout: 2000,
+    breadcrumbCategory: "app",
+});
+
+<TelemetryProvider adapter={adapter}>
+    <App />
+</TelemetryProvider>;
+```
+
+Mapping:
+
+| `TelemetryAdapter` call          | `@sentry/browser` API                                              |
+| -------------------------------- | ------------------------------------------------------------------ |
+| `init()`                         | `Sentry.init(initOptions)` (only when `initOptions` is provided)   |
+| `identify(user)`                 | `Sentry.setUser({ id, email, username, ...traits })`               |
+| `track({ name, properties })`    | `Sentry.addBreadcrumb({ category, message, level: "info", data })` |
+| `captureException(err, context)` | `Sentry.captureException(err, { extra: context })`                 |
+| `flush()`                        | `Sentry.flush(flushTimeout)`                                       |
+
+`@sentry/browser` is **not** declared as a peer dep — the adapter only ever touches the namespace you hand it, so apps that don't use Sentry never pay for it. Install Sentry yourself when you opt in: `npm install @sentry/browser`.
+
+**PostHog adapter** — wraps `posthog-js`.
+
+```ts
+import posthog from "posthog-js";
+import { createPostHogTelemetryAdapter, TelemetryProvider } from "tempest-react-sdk";
+
+const adapter = createPostHogTelemetryAdapter({
+    posthog,
+    init: {
+        apiKey: import.meta.env.VITE_POSTHOG_KEY,
+        options: { api_host: "https://us.i.posthog.com" },
+    },
+});
+
+<TelemetryProvider adapter={adapter}>
+    <App />
+</TelemetryProvider>;
+```
+
+Mapping:
+
+| `TelemetryAdapter` call       | `posthog-js` API                                                                                 |
+| ----------------------------- | ------------------------------------------------------------------------------------------------ |
+| `init()`                      | `posthog.init(apiKey, options)` (only when `init` is provided)                                   |
+| `identify({id, ...})`         | `posthog.identify(id, { email, name, ...traits })`                                               |
+| `identify(null)`              | `posthog.reset()`                                                                                |
+| `track({ name, properties })` | `posthog.capture(name, properties)`                                                              |
+| `captureException(err, ctx)`  | `posthog.captureException(err, ctx)` when available, else `posthog.capture("$exception", { … })` |
+
+`posthog-js` is **not** declared as a peer dep — install only when you opt in: `npm install posthog-js`.
+
+Concrete adapters for Datadog / Amplitude / others are part of the v0.2 roadmap — for now you can write one in ~20 lines following the Sentry / PostHog adapters as templates.
 
 ### Logger recipe
 

package/dist/index.d.ts

@@ -376,6 +376,33 @@ export declare interface CreateEventStreamOptions<T> {
     onStatusChange?: (status: EventStreamStatus) => void;
 }
 
+/**
+ * Build a [[FeatureFlagsAdapter]] backed by a GrowthBook instance. Apps
+ * initialise GrowthBook themselves (so they can load features over the
+ * network, set attributes, etc.) — the adapter just routes lookups.
+ *
+ * Mapping:
+ * - `isEnabled(key, default)` → `growthbook.isOn(key)` (falls back to `default` if no value)
+ * - `get(key, default)` → `growthbook.getFeatureValue(key, default)`
+ * - `onChange(listener)` → `growthbook.setRenderer(listener)` (single-renderer SDK constraint)
+ *
+ * @example
+ * import { GrowthBook } from "@growthbook/growthbook";
+ * import { FeatureFlagsProvider, createGrowthBookFeatureFlagsAdapter } from "tempest-react-sdk";
+ *
+ * const gb = new GrowthBook({ apiHost: "...", clientKey: "..." });
+ * await gb.loadFeatures();
+ * const adapter = createGrowthBookFeatureFlagsAdapter({ growthbook: gb });
+ *
+ * <FeatureFlagsProvider adapter={adapter}><App /></FeatureFlagsProvider>;
+ */
+export declare function createGrowthBookFeatureFlagsAdapter(options: CreateGrowthBookFeatureFlagsAdapterOptions): FeatureFlagsAdapter;
+
+export declare interface CreateGrowthBookFeatureFlagsAdapterOptions {
+    /** The GrowthBook instance. Required. */
+    growthbook: GrowthBookLike;
+}
+
 /**
  * Create an i18n object with translation, pluralization and Intl helpers.
  *
@@ -418,6 +445,33 @@ export declare function createInMemoryFlags(options?: InMemoryFlagsOptions): Fea
     set: (key: string, value: FlagValue) => void;
 };
 
+/**
+ * Build a [[FeatureFlagsAdapter]] backed by a LaunchDarkly JS client. Apps
+ * initialise the client themselves (`LDClient.initialize(envKey, ctx)`) and
+ * pass it in.
+ *
+ * Mapping:
+ * - `isEnabled(key, default)` → `client.variation(key, default) === true`
+ * - `get(key, default)` → `client.variation(key, default)`
+ * - `onChange(listener)` → `client.on("change", listener)` / `client.off("change", listener)`
+ *
+ * @example
+ * import * as LDClient from "launchdarkly-js-client-sdk";
+ * import { FeatureFlagsProvider, createLaunchDarklyFeatureFlagsAdapter } from "tempest-react-sdk";
+ *
+ * const client = LDClient.initialize(import.meta.env.VITE_LD_CLIENT_ID, { kind: "user", key: userId });
+ * await client.waitUntilReady();
+ * const adapter = createLaunchDarklyFeatureFlagsAdapter({ client });
+ *
+ * <FeatureFlagsProvider adapter={adapter}><App /></FeatureFlagsProvider>;
+ */
+export declare function createLaunchDarklyFeatureFlagsAdapter(options: CreateLaunchDarklyFeatureFlagsAdapterOptions): FeatureFlagsAdapter;
+
+export declare interface CreateLaunchDarklyFeatureFlagsAdapterOptions {
+    /** The LaunchDarkly JS client. Required. */
+    client: LDClientLike;
+}
+
 /**
  * Create a structured leveled logger. Plug arbitrary sinks (Sentry, Datadog,
  * remote ingestion) by implementing the `LoggerSink` interface.
@@ -455,6 +509,39 @@ export declare interface CreateLoggerOptions {
  */
 export declare function createOfflineStore<TItem, TKey extends string | number = string>(config: OfflineStoreConfig<TItem>): OfflineStore<TItem, TKey>;
 
+/**
+ * Build a [[TelemetryAdapter]] backed by [`posthog-js`](https://posthog.com/docs/libraries/js).
+ * The PostHog client is supplied by the caller (not bundled).
+ *
+ * Mapping:
+ * - `identify(user)` → `posthog.identify(user.id, { email, name, ...traits })` (or `posthog.reset()` when `null`)
+ * - `track({ name, properties })` → `posthog.capture(name, properties)`
+ * - `captureException(err, ctx)` → `posthog.captureException(err, ctx)` when available, otherwise `posthog.capture("$exception", { …err, …ctx })`
+ * - `flush()` → no-op (PostHog batches automatically)
+ *
+ * @example
+ * import posthog from "posthog-js";
+ * import { createPostHogTelemetryAdapter, TelemetryProvider } from "tempest-react-sdk";
+ *
+ * const adapter = createPostHogTelemetryAdapter({
+ *     posthog,
+ *     init: { apiKey: import.meta.env.VITE_POSTHOG_KEY, options: { api_host: "https://us.i.posthog.com" } },
+ * });
+ *
+ * <TelemetryProvider adapter={adapter}><App /></TelemetryProvider>;
+ */
+export declare function createPostHogTelemetryAdapter(options: CreatePostHogTelemetryAdapterOptions): TelemetryAdapter;
+
+export declare interface CreatePostHogTelemetryAdapterOptions {
+    /** The PostHog JS client (the default export of `posthog-js`). Required. */
+    posthog: PostHogLike;
+    /** Project API key + options. When provided, `Provider.init` calls `posthog.init(apiKey, options)`. */
+    init?: {
+        apiKey: string;
+        options?: Record<string, unknown>;
+    };
+}
+
 /**
  * Build a typed query-key factory for a domain. Each entry can be a static
  * tuple or a function returning a tuple. The returned object is `as const`
@@ -486,6 +573,42 @@ export declare function createQueryKeys<TKey extends string, TEntries extends Re
  */
 export declare function createRefreshQueue(refresh: () => Promise<void>): () => Promise<void>;
 
+/**
+ * Build a [[TelemetryAdapter]] backed by `@sentry/browser`. The Sentry SDK
+ * is supplied by the caller (not bundled) so apps that already initialise
+ * Sentry at startup can share that instance — and apps that don't use
+ * Sentry never pay for it.
+ *
+ * Mapping:
+ * - `identify(user)` → `Sentry.setUser`
+ * - `track(event)` → `Sentry.addBreadcrumb({ category, message: event.name, data })`
+ * - `captureException(err, ctx)` → `Sentry.captureException(err, { extra: ctx })`
+ * - `flush()` → `Sentry.flush(flushTimeout)`
+ *
+ * @example
+ * import * as Sentry from "@sentry/browser";
+ * import { createSentryTelemetryAdapter, TelemetryProvider } from "tempest-react-sdk";
+ *
+ * const adapter = createSentryTelemetryAdapter({
+ *     sentry: Sentry,
+ *     initOptions: { dsn: import.meta.env.VITE_SENTRY_DSN, tracesSampleRate: 0.1 },
+ * });
+ *
+ * <TelemetryProvider adapter={adapter}><App /></TelemetryProvider>;
+ */
+export declare function createSentryTelemetryAdapter(options: CreateSentryTelemetryAdapterOptions): TelemetryAdapter;
+
+export declare interface CreateSentryTelemetryAdapterOptions {
+    /** The Sentry browser SDK namespace. Required. */
+    sentry: SentryLike;
+    /** Optional init payload — passed verbatim to `Sentry.init` when the provider mounts. */
+    initOptions?: Record<string, unknown>;
+    /** Flush timeout in ms (default `2000`). */
+    flushTimeout?: number;
+    /** Breadcrumb category for `track` events (default `"app"`). */
+    breadcrumbCategory?: string;
+}
+
 /**
  * Open a WebSocket with automatic exponential-backoff reconnect, optional
  * heartbeat pings, and typed JSON parsing.
@@ -909,6 +1032,17 @@ export declare interface GridProps extends HTMLAttributes<HTMLDivElement> {
     children?: ReactNode;
 }
 
+/**
+ * Minimal subset of [`@growthbook/growthbook`](https://docs.growthbook.io/lib/js)
+ * used by the adapter. Pass a `GrowthBook` instance directly.
+ */
+export declare interface GrowthBookLike {
+    isOn: (key: string) => boolean;
+    getFeatureValue: <T>(key: string, defaultValue: T) => T;
+    /** Registers a renderer fired whenever GrowthBook re-evaluates features. */
+    setRenderer?: (renderer: () => void) => void;
+}
+
 export declare interface I18n {
     /** Currently active locale. */
     locale: string;
@@ -1080,6 +1214,16 @@ export declare interface LazyWithRetryOptions {
     reloadOnFinalFailure?: boolean;
 }
 
+/**
+ * Minimal subset of [`launchdarkly-js-client-sdk`](https://docs.launchdarkly.com/sdk/client-side/javascript)
+ * used by the adapter. Pass an existing `LDClient`.
+ */
+export declare interface LDClientLike {
+    variation: <T = unknown>(key: string, defaultValue: T) => T;
+    on?: (event: string, handler: () => void) => void;
+    off?: (event: string, handler: () => void) => void;
+}
+
 export declare interface ListOptions<TItem> {
     /** Property to order by. Default: `keyPath`. */
     orderBy?: keyof TItem & string;
@@ -1262,6 +1406,19 @@ export declare interface PlayAudioOptions {
     onError?: (error: unknown) => void;
 }
 
+/**
+ * Minimal subset of `posthog-js` used by the adapter. Pass either the real
+ * default export (`import posthog from "posthog-js"`) or a stubbed object
+ * in tests.
+ */
+export declare interface PostHogLike {
+    init?: (apiKey: string, options?: Record<string, unknown>) => void;
+    identify: (distinctId: string, properties?: Record<string, unknown>) => void;
+    capture: (eventName: string, properties?: Record<string, unknown>) => void;
+    captureException?: (error: unknown, properties?: Record<string, unknown>) => void;
+    reset?: () => void;
+}
+
 /** Linear progress bar with determinate / indeterminate modes. */
 export declare function Progress({ value, max, variant, indeterminate, showLabel, label, className, }: ProgressProps): JSX.Element;
 
@@ -1478,6 +1635,27 @@ export declare interface SelectProps extends SelectHTMLAttributes<HTMLSelectElem
     wrapperClassName?: string;
 }
 
+/**
+ * Minimal subset of `@sentry/browser` used by the adapter. Lets you pass
+ * either the real SDK module (`import * as Sentry from "@sentry/browser"`)
+ * or a stubbed object in tests.
+ */
+export declare interface SentryLike {
+    init?: (options: Record<string, unknown>) => void;
+    setUser: (user: Record<string, unknown> | null) => void;
+    addBreadcrumb: (breadcrumb: {
+        category?: string;
+        message?: string;
+        level?: string;
+        data?: Record<string, unknown>;
+    }) => void;
+    captureException: (error: unknown, hint?: {
+        extra?: Record<string, unknown>;
+        contexts?: Record<string, unknown>;
+    }) => void;
+    flush?: (timeout?: number) => Promise<boolean>;
+}
+
 /**
  * Wrap the Web Share API with a uniform result object. Falls through to
  * `unsupported: true` when the browser lacks `navigator.share`, leaving the