tempest-react-sdk 0.1.3 → 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`, `createSentryTelemetryAdapter`, types: `TelemetryAdapter`, `TelemetryEvent`, `TelemetryUser`, `CreateSentryTelemetryAdapterOptions`, `SentryLike`                                                                                                                                                                                                                                                                  |
-| `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,7 +1266,52 @@ 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
 
@@ -1329,7 +1374,38 @@ Mapping:
 
 `@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`.
 
-Concrete adapters for PostHog / Datadog / GrowthBook are part of the v0.2 roadmap — for now you can write one in ~20 lines following the Sentry adapter as a template.
+**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`
@@ -945,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;
@@ -1116,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;
@@ -1298,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;