@guidelytech/react 0.6.2 → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guidely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -33,7 +33,40 @@ function HelpMenu() {
 | `useGuidelyEvent(event, handler)` | Subscribes for the component lifetime (latest handler is used). |
 | `useChecklistProgress(idOrKey)` | Live `{ completedTaskIds, completedAt, dismissedAt }`. |
 | `useGuideState(idOrKey)` | Live `{ active, completed, stepId, stepIndex, guide }`. |
-| `noopClient` | The no-op client instance. |
+| `noopClient` | The no-op client instance (flag getters return their fallbacks). |
+| `useFlag(key, fallback = false)` | Is the boolean flag on? |
+| `useFeatureValue(key, fallback)` | A flag's value (string, number, JSON); `fallback` when missing or of another type. |
+| `useFlagDetails(key, fallback)` | Value plus `reason`, `ruleId`, `variationId`, `experiment`. |
+| `useFlags()` / `useFlagsReady()` / `useFlagsClient()` | Every flag's value / loaded yet / the flags client (`null` on the server). |
+| `<Feature flag="x" fallback={…}>` (alias `<FeatureFlag>`) | Renders children when the flag is on, else `fallback`. |
+| `<FeatureValue flag="x" value="green" fallback={…}>` | Renders children when the flag's value equals `value`. |
+| `<FlagsProvider sdkKey="pk_…" attributes={…} payload={…}>` | Flags only, without guides or analytics (accepts every flags client option). |
+
+## Feature flags
+
+```tsx
+import { Feature, useFeatureValue, useFlag } from "@guidelytech/react";
+
+function Checkout() {
+  const newCheckout = useFlag("new-checkout");
+  const color = useFeatureValue("checkout-button-color", "blue");
+  return (
+    <Feature flag="new-dashboard-banner" fallback={<OldBanner />}>
+      <NewBanner />
+    </Feature>
+  );
+}
+```
+
+The hooks read the `GuidelyProvider`'s client (`client.flags`, same public key, identity/page/device
+attributes maintained for you) or a `<FlagsProvider>`. They subscribe with `useSyncExternalStore`
+and re-render only when a value changes. Before the client exists (server rendering, hydration)
+they read the bootstrap payload — `<GuidelyProvider flagsPayload={…} flagAttributes={…}>` or
+`<FlagsProvider payload={…}>` — evaluated with `flagAttributes` plus the `user` prop (`id`, traits,
+`account`), so server HTML and hydration match; without a payload they return fallbacks.
+`GuidelyProvider` also accepts `flags={false}` to turn flags off or `flags={{ … }}` for client options.
 
 Types re-exported: `GuidelyClient`, `GuidelyOptions`, `GuidelyEvents`, `GuidelyUser`,
-`ChecklistProgressState`, `PublishedGuide`, `GuideState`, `GuidelyProviderProps`.
+`ChecklistProgressState`, `PublishedGuide`, `GuideState`, `GuidelyProviderProps`, and from
+`@guidelytech/flags`: `FlagsClient`, `FlagsClientOptions`, `FlagDetails`, `FlagsBootstrap`,
+`FlagsPayload`, `Attributes`, `JsonValue`, `EvaluationResult`.

package/dist/index.cjs

@@ -21,9 +21,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.tsx
 var index_exports = {};
 __export(index_exports, {
+  Feature: () => Feature,
+  FeatureFlag: () => FeatureFlag,
+  FeatureValue: () => FeatureValue,
+  FlagsProvider: () => FlagsProvider,
   GuidelyProvider: () => GuidelyProvider,
   noopClient: () => noopClient,
   useChecklistProgress: () => useChecklistProgress,
+  useFeatureValue: () => useFeatureValue,
+  useFlag: () => useFlag,
+  useFlagDetails: () => useFlagDetails,
+  useFlags: () => useFlags,
+  useFlagsClient: () => useFlagsClient,
+  useFlagsReady: () => useFlagsReady,
   useGuideState: () => useGuideState,
   useGuidely: () => useGuidely,
   useGuidelyEvent: () => useGuidelyEvent,
@@ -31,27 +41,133 @@ __export(index_exports, {
   useGuidelyReady: () => useGuidelyReady
 });
 module.exports = __toCommonJS(index_exports);
+var import_flags2 = require("@guidelytech/flags");
 var import_sdk_core = require("@guidelytech/sdk-core");
+var import_react2 = require("react");
+
+// src/flags.tsx
+var import_flags = require("@guidelytech/flags");
 var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
-var GuidelyContext = (0, import_react.createContext)(null);
-function GuidelyProvider({ children, user, ...options }) {
-  const [client, setClient] = (0, import_react.useState)(null);
+var FlagsContext = (0, import_react.createContext)(null);
+var EMPTY = (0, import_flags.createStaticFlags)();
+function useReader() {
+  const src = (0, import_react.useContext)(FlagsContext);
+  return src?.client ?? src?.bootstrap ?? EMPTY;
+}
+function useFlagsValue(select) {
+  const reader = useReader();
+  const cache = (0, import_react.useRef)(null);
+  const get = () => {
+    const value = select(reader);
+    const c = cache.current;
+    if (c && c.reader === reader && (0, import_flags.jsonEquals)(c.value, value)) return c.value;
+    cache.current = { reader, value };
+    return value;
+  };
+  return (0, import_react.useSyncExternalStore)(reader.subscribe, get, get);
+}
+function useFlag(key, fallback = false) {
+  return useFlagsValue((r) => r.isEnabled(key, fallback));
+}
+function useFeatureValue(key, fallback) {
+  return useFlagsValue((r) => r.getValue(key, fallback));
+}
+function useFlagDetails(key, fallback) {
+  return useFlagsValue((r) => r.getDetails(key, fallback));
+}
+function useFlags() {
+  return useFlagsValue((r) => r.getAll());
+}
+function useFlagsReady() {
+  return useFlagsValue((r) => r.isReady());
+}
+function useFlagsClient() {
+  return (0, import_react.useContext)(FlagsContext)?.client ?? null;
+}
+function Feature({ flag, children, fallback = null }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: useFlag(flag) ? children : fallback });
+}
+var FeatureFlag = Feature;
+function FeatureValue({ flag, value, children, fallback = null }) {
+  const current = useFeatureValue(flag, null);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: (0, import_flags.jsonEquals)(current, value) ? children : fallback });
+}
+function useBootstrap(payload, attributes) {
+  const key = (0, import_flags.stableStringify)(attributes);
+  return (0, import_react.useMemo)(() => payload ? (0, import_flags.createStaticFlags)({ payload, attributes }) : EMPTY, [payload, key]);
+}
+function FlagsProvider({ children, client: external, payload, ...options }) {
+  const [created, setCreated] = (0, import_react.useState)(null);
   const optionsRef = (0, import_react.useRef)(options);
   optionsRef.current = options;
-  const { projectId, environment, apiUrl } = options;
+  const sdkKey = options.sdkKey ?? options.projectId;
+  const { apiUrl, environment } = options;
+  const payloadRef = (0, import_react.useRef)(payload);
+  payloadRef.current = payload;
   (0, import_react.useEffect)(() => {
+    if (external || !sdkKey || typeof window === "undefined") return;
+    let c;
+    try {
+      c = (0, import_flags.createFlagsClient)({ ...optionsRef.current, sdkKey, payload: payloadRef.current ?? void 0 });
+    } catch (err) {
+      optionsRef.current.onError?.(err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+    setCreated(c);
+    return () => {
+      c.destroy();
+      setCreated((cur) => cur === c ? null : cur);
+    };
+  }, [external, sdkKey, apiUrl, environment]);
+  const client = external ?? created;
+  const attributes = options.attributes ?? {};
+  const attrsKey = (0, import_flags.stableStringify)(attributes);
+  (0, import_react.useEffect)(() => {
+    if (client && options.attributes) client.setAttributes(options.attributes);
+  }, [client, attrsKey]);
+  const bootstrap = useBootstrap(payload, attributes);
+  const value = (0, import_react.useMemo)(() => ({ client, bootstrap }), [client, bootstrap]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FlagsContext.Provider, { value, children });
+}
+
+// src/index.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var GuidelyContext = (0, import_react2.createContext)(null);
+function userAttributes(user) {
+  if (!user?.id) return {};
+  return { ...user.traits ?? {}, id: user.id, ...user.account ? { account: { ...user.account.traits ?? {}, id: user.account.id } } : {} };
+}
+function GuidelyProvider({ children, user, flagsPayload, flagAttributes, ...options }) {
+  const [client, setClient] = (0, import_react2.useState)(null);
+  const optionsRef = (0, import_react2.useRef)(options);
+  optionsRef.current = options;
+  const userRef = (0, import_react2.useRef)(user);
+  userRef.current = user;
+  const flagsOpts = options.flags === false ? null : options.flags ?? {};
+  const payload = flagsPayload ?? flagsOpts?.payload ?? null;
+  const payloadRef = (0, import_react2.useRef)(payload);
+  payloadRef.current = payload;
+  const appAttributes = (0, import_react2.useMemo)(() => ({ ...flagsOpts?.attributes ?? {}, ...flagAttributes ?? {} }), [(0, import_flags2.stableStringify)(flagsOpts?.attributes ?? {}), (0, import_flags2.stableStringify)(flagAttributes ?? {})]);
+  const appAttributesRef = (0, import_react2.useRef)(appAttributes);
+  appAttributesRef.current = appAttributes;
+  const { projectId, environment, apiUrl } = options;
+  (0, import_react2.useEffect)(() => {
     if (typeof window === "undefined" || !projectId) return;
-    const c = (0, import_sdk_core.createGuidely)({ ...optionsRef.current, projectId, environment, apiUrl });
+    const o = optionsRef.current;
+    const c = (0, import_sdk_core.createGuidely)({ ...o, projectId, environment, apiUrl, user: userRef.current?.id ? userRef.current : void 0, flags: o.flags === false ? false : { ...o.flags ?? {}, payload: payloadRef.current ?? void 0, attributes: appAttributesRef.current } });
     setClient(c);
     return () => {
       c.destroy();
       setClient((cur) => cur === c ? null : cur);
     };
   }, [projectId, environment, apiUrl]);
+  (0, import_react2.useEffect)(() => {
+    client?.flags.setAttributes(appAttributes);
+  }, [client, appAttributes]);
   const userKey = user ? JSON.stringify([user.id, user.traits ?? null, user.account ?? null]) : "";
-  const hadUser = (0, import_react.useRef)(false);
-  (0, import_react.useEffect)(() => {
+  const hadUser = (0, import_react2.useRef)(false);
+  (0, import_react2.useEffect)(() => {
     if (!client) return;
     if (user && user.id) {
       hadUser.current = true;
@@ -61,7 +177,9 @@ function GuidelyProvider({ children, user, ...options }) {
       client.reset();
     }
   }, [client, userKey]);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(GuidelyContext.Provider, { value: client, children });
+  const bootstrap = useBootstrap(payload, { ...userAttributes(user), ...appAttributes });
+  const flags = (0, import_react2.useMemo)(() => ({ client: client?.flags ?? null, bootstrap }), [client, bootstrap]);
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(GuidelyContext.Provider, { value: client, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(FlagsContext.Provider, { value: flags, children }) });
 }
 var NOOP_RESULTS = {
   init: Promise.resolve(),
@@ -82,20 +200,38 @@ var NOOP_RESULTS = {
   getSessionId: "",
   isRecording: false
 };
+var noopFlags = new Proxy((0, import_flags2.createStaticFlags)(), {
+  get(target, prop, receiver) {
+    if (prop in target) return Reflect.get(target, prop, receiver);
+    if (prop === "ready" || prop === "refresh" || prop === "flush") return () => Promise.resolve();
+    if (prop === "getPayload") return () => null;
+    if (prop === "forUser") return () => target;
+    return typeof prop === "string" ? () => void 0 : void 0;
+  }
+});
+var missing = (key, fallback) => ({ key, value: fallback, reason: "FLAG_NOT_FOUND", inExperiment: false, usedFallback: true });
+var NOOP_FUNCTIONS = {
+  isFeatureEnabled: (_key, fallback = false) => fallback,
+  getFeatureValue: (_key, fallback) => fallback,
+  getFeatureDetails: (key, fallback) => missing(key, fallback),
+  onFlagsChange: () => () => {
+  }
+};
 var noopClient = new Proxy({}, {
   get(_target, prop) {
     if (prop === "options") return { projectId: "" };
+    if (prop === "flags") return noopFlags;
     if (typeof prop !== "string") return void 0;
-    return () => NOOP_RESULTS[prop];
+    return NOOP_FUNCTIONS[prop] ?? (() => NOOP_RESULTS[prop]);
   }
 });
 function useGuidely() {
-  return (0, import_react.useContext)(GuidelyContext) ?? noopClient;
+  return (0, import_react2.useContext)(GuidelyContext) ?? noopClient;
 }
 function useGuidelyReady() {
-  const client = (0, import_react.useContext)(GuidelyContext);
-  const [ready, setReady] = (0, import_react.useState)(false);
-  (0, import_react.useEffect)(() => {
+  const client = (0, import_react2.useContext)(GuidelyContext);
+  const [ready, setReady] = (0, import_react2.useState)(false);
+  (0, import_react2.useEffect)(() => {
     if (!client) {
       setReady(false);
       return;
@@ -106,27 +242,27 @@ function useGuidelyReady() {
   return ready;
 }
 function useGuidelyIdentify(userId, traits, account) {
-  const client = (0, import_react.useContext)(GuidelyContext);
+  const client = (0, import_react2.useContext)(GuidelyContext);
   const key = JSON.stringify([userId ?? null, traits ?? null, account ?? null]);
-  (0, import_react.useEffect)(() => {
+  (0, import_react2.useEffect)(() => {
     if (!client || !userId) return;
     void client.identify(userId, traits, account);
   }, [client, key]);
 }
 function useGuidelyEvent(event, handler) {
-  const client = (0, import_react.useContext)(GuidelyContext);
-  const ref = (0, import_react.useRef)(handler);
+  const client = (0, import_react2.useContext)(GuidelyContext);
+  const ref = (0, import_react2.useRef)(handler);
   ref.current = handler;
-  (0, import_react.useEffect)(() => {
+  (0, import_react2.useEffect)(() => {
     if (!client) return;
     const cb = ((...args) => ref.current(...args));
     return client.on(event, cb);
   }, [client, event]);
 }
 function useChecklistProgress(idOrKey) {
-  const client = (0, import_react.useContext)(GuidelyContext);
-  const [progress, setProgress] = (0, import_react.useState)({ completedTaskIds: [], completedAt: null, dismissedAt: null });
-  (0, import_react.useEffect)(() => {
+  const client = (0, import_react2.useContext)(GuidelyContext);
+  const [progress, setProgress] = (0, import_react2.useState)({ completedTaskIds: [], completedAt: null, dismissedAt: null });
+  (0, import_react2.useEffect)(() => {
     if (!client) return;
     const update = () => setProgress(client.getChecklistProgress(idOrKey));
     update();
@@ -136,9 +272,9 @@ function useChecklistProgress(idOrKey) {
   return progress;
 }
 function useGuideState(idOrKey) {
-  const client = (0, import_react.useContext)(GuidelyContext);
-  const [state, setState] = (0, import_react.useState)({ active: false, completed: false, stepId: null, stepIndex: -1, guide: null });
-  (0, import_react.useEffect)(() => {
+  const client = (0, import_react2.useContext)(GuidelyContext);
+  const [state, setState] = (0, import_react2.useState)({ active: false, completed: false, stepId: null, stepIndex: -1, guide: null });
+  (0, import_react2.useEffect)(() => {
     if (!client) return;
     const matches = (g) => g.id === idOrKey || g.key === idOrKey;
     const compute = () => {
@@ -155,9 +291,19 @@ function useGuideState(idOrKey) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Feature,
+  FeatureFlag,
+  FeatureValue,
+  FlagsProvider,
   GuidelyProvider,
   noopClient,
   useChecklistProgress,
+  useFeatureValue,
+  useFlag,
+  useFlagDetails,
+  useFlags,
+  useFlagsClient,
+  useFlagsReady,
   useGuideState,
   useGuidely,
   useGuidelyEvent,

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.tsx"],"sourcesContent":["import { createGuidely, type ChecklistProgressState, type GuidelyClient, type GuidelyEvents, type GuidelyOptions, type GuidelyUser, type PublishedGuide } from \"@guidelytech/sdk-core\";\nimport { createContext, useContext, useEffect, useRef, useState, type ReactNode } from \"react\";\n\nexport type { GuidelyClient, GuidelyOptions, GuidelyEvents, GuidelyUser, ChecklistProgressState, PublishedGuide } from \"@guidelytech/sdk-core\";\n\nconst GuidelyContext = createContext<GuidelyClient | null>(null);\n\nexport interface GuidelyProviderProps extends Omit<GuidelyOptions, \"user\"> {\n  /** Identify this user as soon as the client is ready; `undefined` resets the identity. */\n  user?: GuidelyUser | null;\n  children?: ReactNode;\n}\n\n/**\n * Creates one Guidely client for the subtree. The client is created inside an effect (never\n * during SSR) and destroyed on unmount, so React Strict Mode's double-invoke is harmless.\n */\nexport function GuidelyProvider({ children, user, ...options }: GuidelyProviderProps) {\n  const [client, setClient] = useState<GuidelyClient | null>(null);\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n  const { projectId, environment, apiUrl } = options;\n\n  useEffect(() => {\n    if (typeof window === \"undefined\" || !projectId) return;\n    const c = createGuidely({ ...optionsRef.current, projectId, environment, apiUrl });\n    setClient(c);\n    return () => {\n      c.destroy();\n      setClient((cur) => (cur === c ? null : cur));\n    };\n  }, [projectId, environment, apiUrl]);\n\n  const userKey = user ? JSON.stringify([user.id, user.traits ?? null, user.account ?? null]) : \"\";\n  const hadUser = useRef(false);\n  useEffect(() => {\n    if (!client) return;\n    if (user && user.id) {\n      hadUser.current = true;\n      void client.identify(user.id, user.traits, user.account);\n    } else if (hadUser.current) {\n      hadUser.current = false;\n      client.reset();\n    }\n  }, [client, userKey]);\n\n  return <GuidelyContext.Provider value={client}>{children}</GuidelyContext.Provider>;\n}\n\nconst NOOP_RESULTS: Record<string, unknown> = {\n  init: Promise.resolve(),\n  ready: Promise.resolve(),\n  identify: Promise.resolve(),\n  setAccount: Promise.resolve(),\n  updateTraits: Promise.resolve(),\n  refresh: Promise.resolve(),\n  startGuide: false,\n  getActiveGuide: null,\n  getGuides: [],\n  getChecklistProgress: { completedTaskIds: [], completedAt: null, dismissedAt: null },\n  isGuideCompleted: false,\n  on: () => {},\n  getState: { ready: false, destroyed: false },\n  getContext: null,\n  getSessionId: \"\",\n  isRecording: false,\n};\n\n/** A client that ignores every call; returned by `useGuidely()` on the server and before the provider mounts. */\nexport const noopClient: GuidelyClient = new Proxy({} as GuidelyClient, {\n  get(_target, prop) {\n    if (prop === \"options\") return { projectId: \"\" };\n    if (typeof prop !== \"string\") return undefined;\n    return () => NOOP_RESULTS[prop];\n  },\n});\n\n/** The Guidely client, or a no-op client during SSR / before the provider has mounted. */\nexport function useGuidely(): GuidelyClient {\n  return useContext(GuidelyContext) ?? noopClient;\n}\n\n/** True once the client has loaded its configuration. */\nexport function useGuidelyReady(): boolean {\n  const client = useContext(GuidelyContext);\n  const [ready, setReady] = useState(false);\n  useEffect(() => {\n    if (!client) {\n      setReady(false);\n      return;\n    }\n    if (client.getState().ready) setReady(true);\n    return client.on(\"ready\", () => setReady(true));\n  }, [client]);\n  return ready;\n}\n\n/** Identifies the user whenever the arguments change. */\nexport function useGuidelyIdentify(userId: string | null | undefined, traits?: Record<string, unknown>, account?: GuidelyUser[\"account\"]): void {\n  const client = useContext(GuidelyContext);\n  const key = JSON.stringify([userId ?? null, traits ?? null, account ?? null]);\n  useEffect(() => {\n    if (!client || !userId) return;\n    void client.identify(userId, traits, account);\n  }, [client, key]);\n}\n\n/** Subscribes to a client event for the lifetime of the component. */\nexport function useGuidelyEvent<K extends keyof GuidelyEvents>(event: K, handler: GuidelyEvents[K]): void {\n  const client = useContext(GuidelyContext);\n  const ref = useRef(handler);\n  ref.current = handler;\n  useEffect(() => {\n    if (!client) return;\n    const cb = ((...args: unknown[]) => (ref.current as (...a: unknown[]) => void)(...args)) as GuidelyEvents[K];\n    return client.on(event, cb);\n  }, [client, event]);\n}\n\n/** Live checklist progress for a checklist guide (by id or key). */\nexport function useChecklistProgress(idOrKey: string): ChecklistProgressState {\n  const client = useContext(GuidelyContext);\n  const [progress, setProgress] = useState<ChecklistProgressState>({ completedTaskIds: [], completedAt: null, dismissedAt: null });\n  useEffect(() => {\n    if (!client) return;\n    const update = () => setProgress(client.getChecklistProgress(idOrKey));\n    update();\n    const offs = [client.on(\"ready\", update), client.on(\"identify\", update), client.on(\"checklist:task\", update), client.on(\"checklist:complete\", update)];\n    return () => offs.forEach((off) => off());\n  }, [client, idOrKey]);\n  return progress;\n}\n\nexport interface GuideState {\n  /** The guide is currently showing. */\n  active: boolean;\n  completed: boolean;\n  stepId: string | null;\n  stepIndex: number;\n  guide: PublishedGuide | null;\n}\n\n/** Live state of a guide (by id or key): active, completed, current step. */\nexport function useGuideState(idOrKey: string): GuideState {\n  const client = useContext(GuidelyContext);\n  const [state, setState] = useState<GuideState>({ active: false, completed: false, stepId: null, stepIndex: -1, guide: null });\n  useEffect(() => {\n    if (!client) return;\n    const matches = (g: PublishedGuide) => g.id === idOrKey || g.key === idOrKey;\n    const compute = () => {\n      const guide = client.getGuides().find(matches) ?? null;\n      const active = client.getActiveGuide();\n      const s = client.getState().activeGuide;\n      setState({ active: !!active && matches(active), completed: client.isGuideCompleted(idOrKey), stepId: active && matches(active) ? ((s as { stepId?: string | null } | null)?.stepId ?? null) : null, stepIndex: active && matches(active) ? ((s as { stepIndex?: number } | null)?.stepIndex ?? -1) : -1, guide });\n    };\n    compute();\n    const offs = ([\"ready\", \"identify\", \"guide:start\", \"guide:step\", \"guide:complete\", \"guide:dismiss\", \"guide:skip\"] as const).map((e) => client.on(e, compute));\n    return () => offs.forEach((off) => off());\n  }, [client, idOrKey]);\n  return state;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.tsx","../src/flags.tsx"],"sourcesContent":["import { createStaticFlags, stableStringify, type Attributes, type FlagDetails, type FlagsBootstrap, type FlagsClient } from \"@guidelytech/flags\";\nimport { createGuidely, type ChecklistProgressState, type GuidelyClient, type GuidelyEvents, type GuidelyOptions, type GuidelyUser, type PublishedGuide } from \"@guidelytech/sdk-core\";\nimport { createContext, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from \"react\";\nimport { FlagsContext, useBootstrap, type FlagsSource } from \"./flags\";\n\nexport type { GuidelyClient, GuidelyOptions, GuidelyEvents, GuidelyUser, ChecklistProgressState, PublishedGuide } from \"@guidelytech/sdk-core\";\nexport { useFlag, useFeatureValue, useFlagDetails, useFlags, useFlagsReady, useFlagsClient, Feature, FeatureFlag, FeatureValue, FlagsProvider } from \"./flags\";\nexport type { FeatureProps, FeatureValueProps, FlagsProviderProps } from \"./flags\";\nexport type { FlagsClient, FlagsClientOptions, FlagDetails, FlagsBootstrap, FlagsPayload, Attributes, JsonValue, EvaluationResult } from \"@guidelytech/flags\";\n\nconst GuidelyContext = createContext<GuidelyClient | null>(null);\n\nexport interface GuidelyProviderProps extends Omit<GuidelyOptions, \"user\"> {\n  /** Identify this user as soon as the client is ready; `undefined` resets the identity. */\n  user?: GuidelyUser | null;\n  /**\n   * Flags bootstrap from the server (`getFlagsBootstrap()` / `client.getPayload()`): flag hooks\n   * render the same values on the server, during hydration and after.\n   */\n  flagsPayload?: FlagsBootstrap | null;\n  /** Extra flag attributes (merged over the automatic identity, page and device attributes). */\n  flagAttributes?: Attributes;\n  children?: ReactNode;\n}\n\n/** The attributes the server knows about a user: what bootstrap snapshots evaluate with. */\nfunction userAttributes(user: GuidelyUser | null | undefined): Attributes {\n  if (!user?.id) return {};\n  return { ...(user.traits ?? {}), id: user.id, ...(user.account ? { account: { ...(user.account.traits ?? {}), id: user.account.id } } : {}) };\n}\n\n/**\n * Creates one Guidely client for the subtree. The client is created inside an effect (never\n * during SSR) and destroyed on unmount, so React Strict Mode's double-invoke is harmless.\n */\nexport function GuidelyProvider({ children, user, flagsPayload, flagAttributes, ...options }: GuidelyProviderProps) {\n  const [client, setClient] = useState<GuidelyClient | null>(null);\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n  const userRef = useRef(user);\n  userRef.current = user;\n  const flagsOpts = options.flags === false ? null : (options.flags ?? {});\n  const payload = flagsPayload ?? flagsOpts?.payload ?? null;\n  const payloadRef = useRef(payload);\n  payloadRef.current = payload;\n  const appAttributes = useMemo(() => ({ ...(flagsOpts?.attributes ?? {}), ...(flagAttributes ?? {}) }), [stableStringify(flagsOpts?.attributes ?? {}), stableStringify(flagAttributes ?? {})]);\n  const appAttributesRef = useRef(appAttributes);\n  appAttributesRef.current = appAttributes;\n  const { projectId, environment, apiUrl } = options;\n\n  useEffect(() => {\n    if (typeof window === \"undefined\" || !projectId) return;\n    const o = optionsRef.current;\n    // The user is known up front so flags evaluate for them from the first render (no flicker).\n    const c = createGuidely({ ...o, projectId, environment, apiUrl, user: userRef.current?.id ? userRef.current : undefined, flags: o.flags === false ? false : { ...(o.flags ?? {}), payload: payloadRef.current ?? undefined, attributes: appAttributesRef.current } });\n    setClient(c);\n    return () => {\n      c.destroy();\n      setClient((cur) => (cur === c ? null : cur));\n    };\n  }, [projectId, environment, apiUrl]);\n\n  useEffect(() => {\n    client?.flags.setAttributes(appAttributes);\n  }, [client, appAttributes]);\n\n  const userKey = user ? JSON.stringify([user.id, user.traits ?? null, user.account ?? null]) : \"\";\n  const hadUser = useRef(false);\n  useEffect(() => {\n    if (!client) return;\n    if (user && user.id) {\n      hadUser.current = true;\n      void client.identify(user.id, user.traits, user.account);\n    } else if (hadUser.current) {\n      hadUser.current = false;\n      client.reset();\n    }\n  }, [client, userKey]);\n\n  const bootstrap = useBootstrap(payload, { ...userAttributes(user), ...appAttributes });\n  const flags = useMemo<FlagsSource>(() => ({ client: client?.flags ?? null, bootstrap }), [client, bootstrap]);\n  return (\n    <GuidelyContext.Provider value={client}>\n      <FlagsContext.Provider value={flags}>{children}</FlagsContext.Provider>\n    </GuidelyContext.Provider>\n  );\n}\n\nconst NOOP_RESULTS: Record<string, unknown> = {\n  init: Promise.resolve(),\n  ready: Promise.resolve(),\n  identify: Promise.resolve(),\n  setAccount: Promise.resolve(),\n  updateTraits: Promise.resolve(),\n  refresh: Promise.resolve(),\n  startGuide: false,\n  getActiveGuide: null,\n  getGuides: [],\n  getChecklistProgress: { completedTaskIds: [], completedAt: null, dismissedAt: null },\n  isGuideCompleted: false,\n  on: () => {},\n  getState: { ready: false, destroyed: false },\n  getContext: null,\n  getSessionId: \"\",\n  isRecording: false,\n};\n\n/** Flags that serve every fallback; `useGuidely().flags` before the provider has a client. */\nconst noopFlags = new Proxy(createStaticFlags() as unknown as FlagsClient, {\n  get(target, prop, receiver) {\n    if (prop in target) return Reflect.get(target, prop, receiver);\n    if (prop === \"ready\" || prop === \"refresh\" || prop === \"flush\") return () => Promise.resolve();\n    if (prop === \"getPayload\") return () => null;\n    if (prop === \"forUser\") return () => target;\n    return typeof prop === \"string\" ? () => undefined : undefined;\n  },\n});\n\nconst missing = <T,>(key: string, fallback: T): FlagDetails<T> => ({ key, value: fallback, reason: \"FLAG_NOT_FOUND\", inExperiment: false, usedFallback: true });\n\n/** Methods whose no-op answer depends on the arguments (flag getters return the fallback). */\nconst NOOP_FUNCTIONS: Record<string, (...args: any[]) => unknown> = {\n  isFeatureEnabled: (_key: string, fallback = false) => fallback,\n  getFeatureValue: (_key: string, fallback: unknown) => fallback,\n  getFeatureDetails: (key: string, fallback: unknown) => missing(key, fallback),\n  onFlagsChange: () => () => {},\n};\n\n/** A client that ignores every call; returned by `useGuidely()` on the server and before the provider mounts. */\nexport const noopClient: GuidelyClient = new Proxy({} as GuidelyClient, {\n  get(_target, prop) {\n    if (prop === \"options\") return { projectId: \"\" };\n    if (prop === \"flags\") return noopFlags;\n    if (typeof prop !== \"string\") return undefined;\n    return NOOP_FUNCTIONS[prop] ?? (() => NOOP_RESULTS[prop]);\n  },\n});\n\n/** The Guidely client, or a no-op client during SSR / before the provider has mounted. */\nexport function useGuidely(): GuidelyClient {\n  return useContext(GuidelyContext) ?? noopClient;\n}\n\n/** True once the client has loaded its configuration. */\nexport function useGuidelyReady(): boolean {\n  const client = useContext(GuidelyContext);\n  const [ready, setReady] = useState(false);\n  useEffect(() => {\n    if (!client) {\n      setReady(false);\n      return;\n    }\n    if (client.getState().ready) setReady(true);\n    return client.on(\"ready\", () => setReady(true));\n  }, [client]);\n  return ready;\n}\n\n/** Identifies the user whenever the arguments change. */\nexport function useGuidelyIdentify(userId: string | null | undefined, traits?: Record<string, unknown>, account?: GuidelyUser[\"account\"]): void {\n  const client = useContext(GuidelyContext);\n  const key = JSON.stringify([userId ?? null, traits ?? null, account ?? null]);\n  useEffect(() => {\n    if (!client || !userId) return;\n    void client.identify(userId, traits, account);\n  }, [client, key]);\n}\n\n/** Subscribes to a client event for the lifetime of the component. */\nexport function useGuidelyEvent<K extends keyof GuidelyEvents>(event: K, handler: GuidelyEvents[K]): void {\n  const client = useContext(GuidelyContext);\n  const ref = useRef(handler);\n  ref.current = handler;\n  useEffect(() => {\n    if (!client) return;\n    const cb = ((...args: unknown[]) => (ref.current as (...a: unknown[]) => void)(...args)) as GuidelyEvents[K];\n    return client.on(event, cb);\n  }, [client, event]);\n}\n\n/** Live checklist progress for a checklist guide (by id or key). */\nexport function useChecklistProgress(idOrKey: string): ChecklistProgressState {\n  const client = useContext(GuidelyContext);\n  const [progress, setProgress] = useState<ChecklistProgressState>({ completedTaskIds: [], completedAt: null, dismissedAt: null });\n  useEffect(() => {\n    if (!client) return;\n    const update = () => setProgress(client.getChecklistProgress(idOrKey));\n    update();\n    const offs = [client.on(\"ready\", update), client.on(\"identify\", update), client.on(\"checklist:task\", update), client.on(\"checklist:complete\", update)];\n    return () => offs.forEach((off) => off());\n  }, [client, idOrKey]);\n  return progress;\n}\n\nexport interface GuideState {\n  /** The guide is currently showing. */\n  active: boolean;\n  completed: boolean;\n  stepId: string | null;\n  stepIndex: number;\n  guide: PublishedGuide | null;\n}\n\n/** Live state of a guide (by id or key): active, completed, current step. */\nexport function useGuideState(idOrKey: string): GuideState {\n  const client = useContext(GuidelyContext);\n  const [state, setState] = useState<GuideState>({ active: false, completed: false, stepId: null, stepIndex: -1, guide: null });\n  useEffect(() => {\n    if (!client) return;\n    const matches = (g: PublishedGuide) => g.id === idOrKey || g.key === idOrKey;\n    const compute = () => {\n      const guide = client.getGuides().find(matches) ?? null;\n      const active = client.getActiveGuide();\n      const s = client.getState().activeGuide;\n      setState({ active: !!active && matches(active), completed: client.isGuideCompleted(idOrKey), stepId: active && matches(active) ? ((s as { stepId?: string | null } | null)?.stepId ?? null) : null, stepIndex: active && matches(active) ? ((s as { stepIndex?: number } | null)?.stepIndex ?? -1) : -1, guide });\n    };\n    compute();\n    const offs = ([\"ready\", \"identify\", \"guide:start\", \"guide:step\", \"guide:complete\", \"guide:dismiss\", \"guide:skip\"] as const).map((e) => client.on(e, compute));\n    return () => offs.forEach((off) => off());\n  }, [client, idOrKey]);\n  return state;\n}\n","import { createFlagsClient, createStaticFlags, jsonEquals, stableStringify, type Attributes, type FlagDetails, type FlagValue, type FlagsBootstrap, type FlagsClient, type FlagsClientOptions, type FlagsReader, type JsonValue } from \"@guidelytech/flags\";\nimport { createContext, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, type ReactNode } from \"react\";\n\n/** What the flag hooks read: the live client once created, else a static snapshot of the bootstrap payload. */\nexport interface FlagsSource {\n  client: FlagsClient | null;\n  bootstrap: FlagsReader;\n}\n\nexport const FlagsContext = createContext<FlagsSource | null>(null);\n\nconst EMPTY = createStaticFlags();\n\nfunction useReader(): FlagsReader {\n  const src = useContext(FlagsContext);\n  return src?.client ?? src?.bootstrap ?? EMPTY;\n}\n\n/**\n * Subscribes to the flags with `useSyncExternalStore`. Values are compared deeply so object\n * flags keep their identity between renders. The server snapshot is the bootstrap payload, so\n * server-rendered HTML and hydration agree.\n */\nfunction useFlagsValue<T>(select: (reader: FlagsReader) => T): T {\n  const reader = useReader();\n  const cache = useRef<{ reader: FlagsReader; value: T } | null>(null);\n  const get = () => {\n    const value = select(reader);\n    const c = cache.current;\n    if (c && c.reader === reader && jsonEquals(c.value, value)) return c.value;\n    cache.current = { reader, value };\n    return value;\n  };\n  return useSyncExternalStore(reader.subscribe, get, get);\n}\n\n/** Is the boolean flag on? `fallback` (default `false`) until flags load, or when missing. */\nexport function useFlag(key: string, fallback = false): boolean {\n  return useFlagsValue((r) => r.isEnabled(key, fallback));\n}\n\n/** A flag's value (string, number, JSON…); `fallback` when missing or of a different type. */\nexport function useFeatureValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T> {\n  return useFlagsValue((r) => r.getValue(key, fallback));\n}\n\n/** A flag's value plus why it was served (reason, rule, variation, experiment). */\nexport function useFlagDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>> {\n  return useFlagsValue((r) => r.getDetails(key, fallback));\n}\n\n/** Every flag's value (records no exposures). */\nexport function useFlags(): Record<string, JsonValue> {\n  return useFlagsValue((r) => r.getAll());\n}\n\n/** True once flags have loaded (or failed to and serve fallbacks); true from the start with a bootstrap payload. */\nexport function useFlagsReady(): boolean {\n  return useFlagsValue((r) => r.isReady());\n}\n\n/** The flags client (`null` on the server and before the provider has created it). */\nexport function useFlagsClient(): FlagsClient | null {\n  return useContext(FlagsContext)?.client ?? null;\n}\n\nexport interface FeatureProps {\n  flag: string;\n  children?: ReactNode;\n  /** Rendered while the flag is off (default: nothing). */\n  fallback?: ReactNode;\n}\n\n/** Renders `children` when the boolean flag is on, else `fallback`. */\nexport function Feature({ flag, children, fallback = null }: FeatureProps) {\n  return <>{useFlag(flag) ? children : fallback}</>;\n}\n\n/** Alias of {@link Feature}. */\nexport const FeatureFlag = Feature;\n\nexport interface FeatureValueProps extends FeatureProps {\n  /** Renders `children` when the flag's value equals this (deep equality). */\n  value: JsonValue;\n}\n\n/** Renders `children` when the flag's value equals `value` (e.g. an experiment variation), else `fallback`. */\nexport function FeatureValue({ flag, value, children, fallback = null }: FeatureValueProps) {\n  const current = useFeatureValue<JsonValue>(flag, null);\n  return <>{jsonEquals(current, value) ? children : fallback}</>;\n}\n\n/** A static snapshot for SSR and hydration, rebuilt only when the payload or attributes change. */\nexport function useBootstrap(payload: FlagsBootstrap | null | undefined, attributes: Attributes): FlagsReader {\n  const key = stableStringify(attributes);\n  return useMemo(() => (payload ? createStaticFlags({ payload, attributes }) : EMPTY), [payload, key]);\n}\n\nexport interface FlagsProviderProps extends Omit<FlagsClientOptions, \"payload\"> {\n  /** Bootstrap from the server (`getPayload()`): renders the same values on the server and in the browser. */\n  payload?: FlagsBootstrap | null;\n  /** Use an existing client instead of creating one. */\n  client?: FlagsClient;\n  children?: ReactNode;\n}\n\n/**\n * Feature flags only (no guides or analytics). Creates a flags client in an effect (never during\n * SSR) and destroys it on unmount; until then hooks read the `payload` snapshot. Changing\n * `attributes` re-evaluates without recreating the client.\n *\n * ```tsx\n * <FlagsProvider sdkKey=\"pk_prod_…\" attributes={{ id: user.id, plan: user.plan }} payload={bootstrap}>\n * ```\n */\nexport function FlagsProvider({ children, client: external, payload, ...options }: FlagsProviderProps) {\n  const [created, setCreated] = useState<FlagsClient | null>(null);\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n  const sdkKey = options.sdkKey ?? options.projectId;\n  const { apiUrl, environment } = options;\n  const payloadRef = useRef(payload);\n  payloadRef.current = payload;\n\n  useEffect(() => {\n    if (external || !sdkKey || typeof window === \"undefined\") return;\n    let c: FlagsClient;\n    try {\n      c = createFlagsClient({ ...optionsRef.current, sdkKey, payload: payloadRef.current ?? undefined });\n    } catch (err) {\n      optionsRef.current.onError?.(err instanceof Error ? err : new Error(String(err)));\n      return;\n    }\n    setCreated(c);\n    return () => {\n      c.destroy();\n      setCreated((cur) => (cur === c ? null : cur));\n    };\n  }, [external, sdkKey, apiUrl, environment]);\n\n  const client = external ?? created;\n  const attributes = options.attributes ?? {};\n  const attrsKey = stableStringify(attributes);\n  useEffect(() => {\n    if (client && options.attributes) client.setAttributes(options.attributes);\n  }, [client, attrsKey]);\n\n  const bootstrap = useBootstrap(payload, attributes);\n  const value = useMemo<FlagsSource>(() => ({ client, bootstrap }), [client, bootstrap]);\n  return <FlagsContext.Provider value={value}>{children}</FlagsContext.Provider>;\n}\n"],"mappings":"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","names":["import_flags","import_react","import_jsx_runtime"]}

package/dist/index.d.cts

@@ -1,18 +1,73 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
+import { JsonValue, FlagsClientOptions, FlagsBootstrap, FlagsClient, FlagValue, FlagDetails, Attributes } from '@guidelytech/flags';
+export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, JsonValue } from '@guidelytech/flags';
 import { PublishedGuide, GuidelyOptions, GuidelyUser, GuidelyClient, ChecklistProgressState, GuidelyEvents } from '@guidelytech/sdk-core';
 export { ChecklistProgressState, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, PublishedGuide } from '@guidelytech/sdk-core';
 
+/** Is the boolean flag on? `fallback` (default `false`) until flags load, or when missing. */
+declare function useFlag(key: string, fallback?: boolean): boolean;
+/** A flag's value (string, number, JSON…); `fallback` when missing or of a different type. */
+declare function useFeatureValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T>;
+/** A flag's value plus why it was served (reason, rule, variation, experiment). */
+declare function useFlagDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
+/** Every flag's value (records no exposures). */
+declare function useFlags(): Record<string, JsonValue>;
+/** True once flags have loaded (or failed to and serve fallbacks); true from the start with a bootstrap payload. */
+declare function useFlagsReady(): boolean;
+/** The flags client (`null` on the server and before the provider has created it). */
+declare function useFlagsClient(): FlagsClient | null;
+interface FeatureProps {
+    flag: string;
+    children?: ReactNode;
+    /** Rendered while the flag is off (default: nothing). */
+    fallback?: ReactNode;
+}
+/** Renders `children` when the boolean flag is on, else `fallback`. */
+declare function Feature({ flag, children, fallback }: FeatureProps): react.JSX.Element;
+/** Alias of {@link Feature}. */
+declare const FeatureFlag: typeof Feature;
+interface FeatureValueProps extends FeatureProps {
+    /** Renders `children` when the flag's value equals this (deep equality). */
+    value: JsonValue;
+}
+/** Renders `children` when the flag's value equals `value` (e.g. an experiment variation), else `fallback`. */
+declare function FeatureValue({ flag, value, children, fallback }: FeatureValueProps): react.JSX.Element;
+interface FlagsProviderProps extends Omit<FlagsClientOptions, "payload"> {
+    /** Bootstrap from the server (`getPayload()`): renders the same values on the server and in the browser. */
+    payload?: FlagsBootstrap | null;
+    /** Use an existing client instead of creating one. */
+    client?: FlagsClient;
+    children?: ReactNode;
+}
+/**
+ * Feature flags only (no guides or analytics). Creates a flags client in an effect (never during
+ * SSR) and destroys it on unmount; until then hooks read the `payload` snapshot. Changing
+ * `attributes` re-evaluates without recreating the client.
+ *
+ * ```tsx
+ * <FlagsProvider sdkKey="pk_prod_…" attributes={{ id: user.id, plan: user.plan }} payload={bootstrap}>
+ * ```
+ */
+declare function FlagsProvider({ children, client: external, payload, ...options }: FlagsProviderProps): react.JSX.Element;
+
 interface GuidelyProviderProps extends Omit<GuidelyOptions, "user"> {
     /** Identify this user as soon as the client is ready; `undefined` resets the identity. */
     user?: GuidelyUser | null;
+    /**
+     * Flags bootstrap from the server (`getFlagsBootstrap()` / `client.getPayload()`): flag hooks
+     * render the same values on the server, during hydration and after.
+     */
+    flagsPayload?: FlagsBootstrap | null;
+    /** Extra flag attributes (merged over the automatic identity, page and device attributes). */
+    flagAttributes?: Attributes;
     children?: ReactNode;
 }
 /**
  * Creates one Guidely client for the subtree. The client is created inside an effect (never
  * during SSR) and destroyed on unmount, so React Strict Mode's double-invoke is harmless.
  */
-declare function GuidelyProvider({ children, user, ...options }: GuidelyProviderProps): react.JSX.Element;
+declare function GuidelyProvider({ children, user, flagsPayload, flagAttributes, ...options }: GuidelyProviderProps): react.JSX.Element;
 /** A client that ignores every call; returned by `useGuidely()` on the server and before the provider mounts. */
 declare const noopClient: GuidelyClient;
 /** The Guidely client, or a no-op client during SSR / before the provider has mounted. */
@@ -36,4 +91,4 @@ interface GuideState {
 /** Live state of a guide (by id or key): active, completed, current step. */
 declare function useGuideState(idOrKey: string): GuideState;
 
-export { type GuideState, GuidelyProvider, type GuidelyProviderProps, noopClient, useChecklistProgress, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyReady };
+export { Feature, FeatureFlag, type FeatureProps, FeatureValue, type FeatureValueProps, FlagsProvider, type FlagsProviderProps, type GuideState, GuidelyProvider, type GuidelyProviderProps, noopClient, useChecklistProgress, useFeatureValue, useFlag, useFlagDetails, useFlags, useFlagsClient, useFlagsReady, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyReady };

package/dist/index.d.ts

@@ -1,18 +1,73 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
+import { JsonValue, FlagsClientOptions, FlagsBootstrap, FlagsClient, FlagValue, FlagDetails, Attributes } from '@guidelytech/flags';
+export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, JsonValue } from '@guidelytech/flags';
 import { PublishedGuide, GuidelyOptions, GuidelyUser, GuidelyClient, ChecklistProgressState, GuidelyEvents } from '@guidelytech/sdk-core';
 export { ChecklistProgressState, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, PublishedGuide } from '@guidelytech/sdk-core';
 
+/** Is the boolean flag on? `fallback` (default `false`) until flags load, or when missing. */
+declare function useFlag(key: string, fallback?: boolean): boolean;
+/** A flag's value (string, number, JSON…); `fallback` when missing or of a different type. */
+declare function useFeatureValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T>;
+/** A flag's value plus why it was served (reason, rule, variation, experiment). */
+declare function useFlagDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
+/** Every flag's value (records no exposures). */
+declare function useFlags(): Record<string, JsonValue>;
+/** True once flags have loaded (or failed to and serve fallbacks); true from the start with a bootstrap payload. */
+declare function useFlagsReady(): boolean;
+/** The flags client (`null` on the server and before the provider has created it). */
+declare function useFlagsClient(): FlagsClient | null;
+interface FeatureProps {
+    flag: string;
+    children?: ReactNode;
+    /** Rendered while the flag is off (default: nothing). */
+    fallback?: ReactNode;
+}
+/** Renders `children` when the boolean flag is on, else `fallback`. */
+declare function Feature({ flag, children, fallback }: FeatureProps): react.JSX.Element;
+/** Alias of {@link Feature}. */
+declare const FeatureFlag: typeof Feature;
+interface FeatureValueProps extends FeatureProps {
+    /** Renders `children` when the flag's value equals this (deep equality). */
+    value: JsonValue;
+}
+/** Renders `children` when the flag's value equals `value` (e.g. an experiment variation), else `fallback`. */
+declare function FeatureValue({ flag, value, children, fallback }: FeatureValueProps): react.JSX.Element;
+interface FlagsProviderProps extends Omit<FlagsClientOptions, "payload"> {
+    /** Bootstrap from the server (`getPayload()`): renders the same values on the server and in the browser. */
+    payload?: FlagsBootstrap | null;
+    /** Use an existing client instead of creating one. */
+    client?: FlagsClient;
+    children?: ReactNode;
+}
+/**
+ * Feature flags only (no guides or analytics). Creates a flags client in an effect (never during
+ * SSR) and destroys it on unmount; until then hooks read the `payload` snapshot. Changing
+ * `attributes` re-evaluates without recreating the client.
+ *
+ * ```tsx
+ * <FlagsProvider sdkKey="pk_prod_…" attributes={{ id: user.id, plan: user.plan }} payload={bootstrap}>
+ * ```
+ */
+declare function FlagsProvider({ children, client: external, payload, ...options }: FlagsProviderProps): react.JSX.Element;
+
 interface GuidelyProviderProps extends Omit<GuidelyOptions, "user"> {
     /** Identify this user as soon as the client is ready; `undefined` resets the identity. */
     user?: GuidelyUser | null;
+    /**
+     * Flags bootstrap from the server (`getFlagsBootstrap()` / `client.getPayload()`): flag hooks
+     * render the same values on the server, during hydration and after.
+     */
+    flagsPayload?: FlagsBootstrap | null;
+    /** Extra flag attributes (merged over the automatic identity, page and device attributes). */
+    flagAttributes?: Attributes;
     children?: ReactNode;
 }
 /**
  * Creates one Guidely client for the subtree. The client is created inside an effect (never
  * during SSR) and destroyed on unmount, so React Strict Mode's double-invoke is harmless.
  */
-declare function GuidelyProvider({ children, user, ...options }: GuidelyProviderProps): react.JSX.Element;
+declare function GuidelyProvider({ children, user, flagsPayload, flagAttributes, ...options }: GuidelyProviderProps): react.JSX.Element;
 /** A client that ignores every call; returned by `useGuidely()` on the server and before the provider mounts. */
 declare const noopClient: GuidelyClient;
 /** The Guidely client, or a no-op client during SSR / before the provider has mounted. */
@@ -36,4 +91,4 @@ interface GuideState {
 /** Live state of a guide (by id or key): active, completed, current step. */
 declare function useGuideState(idOrKey: string): GuideState;
 
-export { type GuideState, GuidelyProvider, type GuidelyProviderProps, noopClient, useChecklistProgress, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyReady };
+export { Feature, FeatureFlag, type FeatureProps, FeatureValue, type FeatureValueProps, FlagsProvider, type FlagsProviderProps, type GuideState, GuidelyProvider, type GuidelyProviderProps, noopClient, useChecklistProgress, useFeatureValue, useFlag, useFlagDetails, useFlags, useFlagsClient, useFlagsReady, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyReady };

package/dist/index.js

@@ -1,27 +1,133 @@
 "use client";
 
 // src/index.tsx
+import { createStaticFlags as createStaticFlags2, stableStringify as stableStringify2 } from "@guidelytech/flags";
 import { createGuidely } from "@guidelytech/sdk-core";
-import { createContext, useContext, useEffect, useRef, useState } from "react";
-import { jsx } from "react/jsx-runtime";
-var GuidelyContext = createContext(null);
-function GuidelyProvider({ children, user, ...options }) {
-  const [client, setClient] = useState(null);
+import { createContext as createContext2, useContext as useContext2, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2, useState as useState2 } from "react";
+
+// src/flags.tsx
+import { createFlagsClient, createStaticFlags, jsonEquals, stableStringify } from "@guidelytech/flags";
+import { createContext, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { Fragment, jsx } from "react/jsx-runtime";
+var FlagsContext = createContext(null);
+var EMPTY = createStaticFlags();
+function useReader() {
+  const src = useContext(FlagsContext);
+  return src?.client ?? src?.bootstrap ?? EMPTY;
+}
+function useFlagsValue(select) {
+  const reader = useReader();
+  const cache = useRef(null);
+  const get = () => {
+    const value = select(reader);
+    const c = cache.current;
+    if (c && c.reader === reader && jsonEquals(c.value, value)) return c.value;
+    cache.current = { reader, value };
+    return value;
+  };
+  return useSyncExternalStore(reader.subscribe, get, get);
+}
+function useFlag(key, fallback = false) {
+  return useFlagsValue((r) => r.isEnabled(key, fallback));
+}
+function useFeatureValue(key, fallback) {
+  return useFlagsValue((r) => r.getValue(key, fallback));
+}
+function useFlagDetails(key, fallback) {
+  return useFlagsValue((r) => r.getDetails(key, fallback));
+}
+function useFlags() {
+  return useFlagsValue((r) => r.getAll());
+}
+function useFlagsReady() {
+  return useFlagsValue((r) => r.isReady());
+}
+function useFlagsClient() {
+  return useContext(FlagsContext)?.client ?? null;
+}
+function Feature({ flag, children, fallback = null }) {
+  return /* @__PURE__ */ jsx(Fragment, { children: useFlag(flag) ? children : fallback });
+}
+var FeatureFlag = Feature;
+function FeatureValue({ flag, value, children, fallback = null }) {
+  const current = useFeatureValue(flag, null);
+  return /* @__PURE__ */ jsx(Fragment, { children: jsonEquals(current, value) ? children : fallback });
+}
+function useBootstrap(payload, attributes) {
+  const key = stableStringify(attributes);
+  return useMemo(() => payload ? createStaticFlags({ payload, attributes }) : EMPTY, [payload, key]);
+}
+function FlagsProvider({ children, client: external, payload, ...options }) {
+  const [created, setCreated] = useState(null);
   const optionsRef = useRef(options);
   optionsRef.current = options;
-  const { projectId, environment, apiUrl } = options;
+  const sdkKey = options.sdkKey ?? options.projectId;
+  const { apiUrl, environment } = options;
+  const payloadRef = useRef(payload);
+  payloadRef.current = payload;
   useEffect(() => {
+    if (external || !sdkKey || typeof window === "undefined") return;
+    let c;
+    try {
+      c = createFlagsClient({ ...optionsRef.current, sdkKey, payload: payloadRef.current ?? void 0 });
+    } catch (err) {
+      optionsRef.current.onError?.(err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+    setCreated(c);
+    return () => {
+      c.destroy();
+      setCreated((cur) => cur === c ? null : cur);
+    };
+  }, [external, sdkKey, apiUrl, environment]);
+  const client = external ?? created;
+  const attributes = options.attributes ?? {};
+  const attrsKey = stableStringify(attributes);
+  useEffect(() => {
+    if (client && options.attributes) client.setAttributes(options.attributes);
+  }, [client, attrsKey]);
+  const bootstrap = useBootstrap(payload, attributes);
+  const value = useMemo(() => ({ client, bootstrap }), [client, bootstrap]);
+  return /* @__PURE__ */ jsx(FlagsContext.Provider, { value, children });
+}
+
+// src/index.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var GuidelyContext = createContext2(null);
+function userAttributes(user) {
+  if (!user?.id) return {};
+  return { ...user.traits ?? {}, id: user.id, ...user.account ? { account: { ...user.account.traits ?? {}, id: user.account.id } } : {} };
+}
+function GuidelyProvider({ children, user, flagsPayload, flagAttributes, ...options }) {
+  const [client, setClient] = useState2(null);
+  const optionsRef = useRef2(options);
+  optionsRef.current = options;
+  const userRef = useRef2(user);
+  userRef.current = user;
+  const flagsOpts = options.flags === false ? null : options.flags ?? {};
+  const payload = flagsPayload ?? flagsOpts?.payload ?? null;
+  const payloadRef = useRef2(payload);
+  payloadRef.current = payload;
+  const appAttributes = useMemo2(() => ({ ...flagsOpts?.attributes ?? {}, ...flagAttributes ?? {} }), [stableStringify2(flagsOpts?.attributes ?? {}), stableStringify2(flagAttributes ?? {})]);
+  const appAttributesRef = useRef2(appAttributes);
+  appAttributesRef.current = appAttributes;
+  const { projectId, environment, apiUrl } = options;
+  useEffect2(() => {
     if (typeof window === "undefined" || !projectId) return;
-    const c = createGuidely({ ...optionsRef.current, projectId, environment, apiUrl });
+    const o = optionsRef.current;
+    const c = createGuidely({ ...o, projectId, environment, apiUrl, user: userRef.current?.id ? userRef.current : void 0, flags: o.flags === false ? false : { ...o.flags ?? {}, payload: payloadRef.current ?? void 0, attributes: appAttributesRef.current } });
     setClient(c);
     return () => {
       c.destroy();
       setClient((cur) => cur === c ? null : cur);
     };
   }, [projectId, environment, apiUrl]);
+  useEffect2(() => {
+    client?.flags.setAttributes(appAttributes);
+  }, [client, appAttributes]);
   const userKey = user ? JSON.stringify([user.id, user.traits ?? null, user.account ?? null]) : "";
-  const hadUser = useRef(false);
-  useEffect(() => {
+  const hadUser = useRef2(false);
+  useEffect2(() => {
     if (!client) return;
     if (user && user.id) {
       hadUser.current = true;
@@ -31,7 +137,9 @@ function GuidelyProvider({ children, user, ...options }) {
       client.reset();
     }
   }, [client, userKey]);
-  return /* @__PURE__ */ jsx(GuidelyContext.Provider, { value: client, children });
+  const bootstrap = useBootstrap(payload, { ...userAttributes(user), ...appAttributes });
+  const flags = useMemo2(() => ({ client: client?.flags ?? null, bootstrap }), [client, bootstrap]);
+  return /* @__PURE__ */ jsx2(GuidelyContext.Provider, { value: client, children: /* @__PURE__ */ jsx2(FlagsContext.Provider, { value: flags, children }) });
 }
 var NOOP_RESULTS = {
   init: Promise.resolve(),
@@ -52,20 +160,38 @@ var NOOP_RESULTS = {
   getSessionId: "",
   isRecording: false
 };
+var noopFlags = new Proxy(createStaticFlags2(), {
+  get(target, prop, receiver) {
+    if (prop in target) return Reflect.get(target, prop, receiver);
+    if (prop === "ready" || prop === "refresh" || prop === "flush") return () => Promise.resolve();
+    if (prop === "getPayload") return () => null;
+    if (prop === "forUser") return () => target;
+    return typeof prop === "string" ? () => void 0 : void 0;
+  }
+});
+var missing = (key, fallback) => ({ key, value: fallback, reason: "FLAG_NOT_FOUND", inExperiment: false, usedFallback: true });
+var NOOP_FUNCTIONS = {
+  isFeatureEnabled: (_key, fallback = false) => fallback,
+  getFeatureValue: (_key, fallback) => fallback,
+  getFeatureDetails: (key, fallback) => missing(key, fallback),
+  onFlagsChange: () => () => {
+  }
+};
 var noopClient = new Proxy({}, {
   get(_target, prop) {
     if (prop === "options") return { projectId: "" };
+    if (prop === "flags") return noopFlags;
     if (typeof prop !== "string") return void 0;
-    return () => NOOP_RESULTS[prop];
+    return NOOP_FUNCTIONS[prop] ?? (() => NOOP_RESULTS[prop]);
   }
 });
 function useGuidely() {
-  return useContext(GuidelyContext) ?? noopClient;
+  return useContext2(GuidelyContext) ?? noopClient;
 }
 function useGuidelyReady() {
-  const client = useContext(GuidelyContext);
-  const [ready, setReady] = useState(false);
-  useEffect(() => {
+  const client = useContext2(GuidelyContext);
+  const [ready, setReady] = useState2(false);
+  useEffect2(() => {
     if (!client) {
       setReady(false);
       return;
@@ -76,27 +202,27 @@ function useGuidelyReady() {
   return ready;
 }
 function useGuidelyIdentify(userId, traits, account) {
-  const client = useContext(GuidelyContext);
+  const client = useContext2(GuidelyContext);
   const key = JSON.stringify([userId ?? null, traits ?? null, account ?? null]);
-  useEffect(() => {
+  useEffect2(() => {
     if (!client || !userId) return;
     void client.identify(userId, traits, account);
   }, [client, key]);
 }
 function useGuidelyEvent(event, handler) {
-  const client = useContext(GuidelyContext);
-  const ref = useRef(handler);
+  const client = useContext2(GuidelyContext);
+  const ref = useRef2(handler);
   ref.current = handler;
-  useEffect(() => {
+  useEffect2(() => {
     if (!client) return;
     const cb = ((...args) => ref.current(...args));
     return client.on(event, cb);
   }, [client, event]);
 }
 function useChecklistProgress(idOrKey) {
-  const client = useContext(GuidelyContext);
-  const [progress, setProgress] = useState({ completedTaskIds: [], completedAt: null, dismissedAt: null });
-  useEffect(() => {
+  const client = useContext2(GuidelyContext);
+  const [progress, setProgress] = useState2({ completedTaskIds: [], completedAt: null, dismissedAt: null });
+  useEffect2(() => {
     if (!client) return;
     const update = () => setProgress(client.getChecklistProgress(idOrKey));
     update();
@@ -106,9 +232,9 @@ function useChecklistProgress(idOrKey) {
   return progress;
 }
 function useGuideState(idOrKey) {
-  const client = useContext(GuidelyContext);
-  const [state, setState] = useState({ active: false, completed: false, stepId: null, stepIndex: -1, guide: null });
-  useEffect(() => {
+  const client = useContext2(GuidelyContext);
+  const [state, setState] = useState2({ active: false, completed: false, stepId: null, stepIndex: -1, guide: null });
+  useEffect2(() => {
     if (!client) return;
     const matches = (g) => g.id === idOrKey || g.key === idOrKey;
     const compute = () => {
@@ -124,9 +250,19 @@ function useGuideState(idOrKey) {
   return state;
 }
 export {
+  Feature,
+  FeatureFlag,
+  FeatureValue,
+  FlagsProvider,
   GuidelyProvider,
   noopClient,
   useChecklistProgress,
+  useFeatureValue,
+  useFlag,
+  useFlagDetails,
+  useFlags,
+  useFlagsClient,
+  useFlagsReady,
   useGuideState,
   useGuidely,
   useGuidelyEvent,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.tsx"],"sourcesContent":["import { createGuidely, type ChecklistProgressState, type GuidelyClient, type GuidelyEvents, type GuidelyOptions, type GuidelyUser, type PublishedGuide } from \"@guidelytech/sdk-core\";\nimport { createContext, useContext, useEffect, useRef, useState, type ReactNode } from \"react\";\n\nexport type { GuidelyClient, GuidelyOptions, GuidelyEvents, GuidelyUser, ChecklistProgressState, PublishedGuide } from \"@guidelytech/sdk-core\";\n\nconst GuidelyContext = createContext<GuidelyClient | null>(null);\n\nexport interface GuidelyProviderProps extends Omit<GuidelyOptions, \"user\"> {\n  /** Identify this user as soon as the client is ready; `undefined` resets the identity. */\n  user?: GuidelyUser | null;\n  children?: ReactNode;\n}\n\n/**\n * Creates one Guidely client for the subtree. The client is created inside an effect (never\n * during SSR) and destroyed on unmount, so React Strict Mode's double-invoke is harmless.\n */\nexport function GuidelyProvider({ children, user, ...options }: GuidelyProviderProps) {\n  const [client, setClient] = useState<GuidelyClient | null>(null);\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n  const { projectId, environment, apiUrl } = options;\n\n  useEffect(() => {\n    if (typeof window === \"undefined\" || !projectId) return;\n    const c = createGuidely({ ...optionsRef.current, projectId, environment, apiUrl });\n    setClient(c);\n    return () => {\n      c.destroy();\n      setClient((cur) => (cur === c ? null : cur));\n    };\n  }, [projectId, environment, apiUrl]);\n\n  const userKey = user ? JSON.stringify([user.id, user.traits ?? null, user.account ?? null]) : \"\";\n  const hadUser = useRef(false);\n  useEffect(() => {\n    if (!client) return;\n    if (user && user.id) {\n      hadUser.current = true;\n      void client.identify(user.id, user.traits, user.account);\n    } else if (hadUser.current) {\n      hadUser.current = false;\n      client.reset();\n    }\n  }, [client, userKey]);\n\n  return <GuidelyContext.Provider value={client}>{children}</GuidelyContext.Provider>;\n}\n\nconst NOOP_RESULTS: Record<string, unknown> = {\n  init: Promise.resolve(),\n  ready: Promise.resolve(),\n  identify: Promise.resolve(),\n  setAccount: Promise.resolve(),\n  updateTraits: Promise.resolve(),\n  refresh: Promise.resolve(),\n  startGuide: false,\n  getActiveGuide: null,\n  getGuides: [],\n  getChecklistProgress: { completedTaskIds: [], completedAt: null, dismissedAt: null },\n  isGuideCompleted: false,\n  on: () => {},\n  getState: { ready: false, destroyed: false },\n  getContext: null,\n  getSessionId: \"\",\n  isRecording: false,\n};\n\n/** A client that ignores every call; returned by `useGuidely()` on the server and before the provider mounts. */\nexport const noopClient: GuidelyClient = new Proxy({} as GuidelyClient, {\n  get(_target, prop) {\n    if (prop === \"options\") return { projectId: \"\" };\n    if (typeof prop !== \"string\") return undefined;\n    return () => NOOP_RESULTS[prop];\n  },\n});\n\n/** The Guidely client, or a no-op client during SSR / before the provider has mounted. */\nexport function useGuidely(): GuidelyClient {\n  return useContext(GuidelyContext) ?? noopClient;\n}\n\n/** True once the client has loaded its configuration. */\nexport function useGuidelyReady(): boolean {\n  const client = useContext(GuidelyContext);\n  const [ready, setReady] = useState(false);\n  useEffect(() => {\n    if (!client) {\n      setReady(false);\n      return;\n    }\n    if (client.getState().ready) setReady(true);\n    return client.on(\"ready\", () => setReady(true));\n  }, [client]);\n  return ready;\n}\n\n/** Identifies the user whenever the arguments change. */\nexport function useGuidelyIdentify(userId: string | null | undefined, traits?: Record<string, unknown>, account?: GuidelyUser[\"account\"]): void {\n  const client = useContext(GuidelyContext);\n  const key = JSON.stringify([userId ?? null, traits ?? null, account ?? null]);\n  useEffect(() => {\n    if (!client || !userId) return;\n    void client.identify(userId, traits, account);\n  }, [client, key]);\n}\n\n/** Subscribes to a client event for the lifetime of the component. */\nexport function useGuidelyEvent<K extends keyof GuidelyEvents>(event: K, handler: GuidelyEvents[K]): void {\n  const client = useContext(GuidelyContext);\n  const ref = useRef(handler);\n  ref.current = handler;\n  useEffect(() => {\n    if (!client) return;\n    const cb = ((...args: unknown[]) => (ref.current as (...a: unknown[]) => void)(...args)) as GuidelyEvents[K];\n    return client.on(event, cb);\n  }, [client, event]);\n}\n\n/** Live checklist progress for a checklist guide (by id or key). */\nexport function useChecklistProgress(idOrKey: string): ChecklistProgressState {\n  const client = useContext(GuidelyContext);\n  const [progress, setProgress] = useState<ChecklistProgressState>({ completedTaskIds: [], completedAt: null, dismissedAt: null });\n  useEffect(() => {\n    if (!client) return;\n    const update = () => setProgress(client.getChecklistProgress(idOrKey));\n    update();\n    const offs = [client.on(\"ready\", update), client.on(\"identify\", update), client.on(\"checklist:task\", update), client.on(\"checklist:complete\", update)];\n    return () => offs.forEach((off) => off());\n  }, [client, idOrKey]);\n  return progress;\n}\n\nexport interface GuideState {\n  /** The guide is currently showing. */\n  active: boolean;\n  completed: boolean;\n  stepId: string | null;\n  stepIndex: number;\n  guide: PublishedGuide | null;\n}\n\n/** Live state of a guide (by id or key): active, completed, current step. */\nexport function useGuideState(idOrKey: string): GuideState {\n  const client = useContext(GuidelyContext);\n  const [state, setState] = useState<GuideState>({ active: false, completed: false, stepId: null, stepIndex: -1, guide: null });\n  useEffect(() => {\n    if (!client) return;\n    const matches = (g: PublishedGuide) => g.id === idOrKey || g.key === idOrKey;\n    const compute = () => {\n      const guide = client.getGuides().find(matches) ?? null;\n      const active = client.getActiveGuide();\n      const s = client.getState().activeGuide;\n      setState({ active: !!active && matches(active), completed: client.isGuideCompleted(idOrKey), stepId: active && matches(active) ? ((s as { stepId?: string | null } | null)?.stepId ?? null) : null, stepIndex: active && matches(active) ? ((s as { stepIndex?: number } | null)?.stepIndex ?? -1) : -1, guide });\n    };\n    compute();\n    const offs = ([\"ready\", \"identify\", \"guide:start\", \"guide:step\", \"guide:complete\", \"guide:dismiss\", \"guide:skip\"] as const).map((e) => client.on(e, compute));\n    return () => offs.forEach((off) => off());\n  }, [client, idOrKey]);\n  return state;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.tsx","../src/flags.tsx"],"sourcesContent":["import { createStaticFlags, stableStringify, type Attributes, type FlagDetails, type FlagsBootstrap, type FlagsClient } from \"@guidelytech/flags\";\nimport { createGuidely, type ChecklistProgressState, type GuidelyClient, type GuidelyEvents, type GuidelyOptions, type GuidelyUser, type PublishedGuide } from \"@guidelytech/sdk-core\";\nimport { createContext, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from \"react\";\nimport { FlagsContext, useBootstrap, type FlagsSource } from \"./flags\";\n\nexport type { GuidelyClient, GuidelyOptions, GuidelyEvents, GuidelyUser, ChecklistProgressState, PublishedGuide } from \"@guidelytech/sdk-core\";\nexport { useFlag, useFeatureValue, useFlagDetails, useFlags, useFlagsReady, useFlagsClient, Feature, FeatureFlag, FeatureValue, FlagsProvider } from \"./flags\";\nexport type { FeatureProps, FeatureValueProps, FlagsProviderProps } from \"./flags\";\nexport type { FlagsClient, FlagsClientOptions, FlagDetails, FlagsBootstrap, FlagsPayload, Attributes, JsonValue, EvaluationResult } from \"@guidelytech/flags\";\n\nconst GuidelyContext = createContext<GuidelyClient | null>(null);\n\nexport interface GuidelyProviderProps extends Omit<GuidelyOptions, \"user\"> {\n  /** Identify this user as soon as the client is ready; `undefined` resets the identity. */\n  user?: GuidelyUser | null;\n  /**\n   * Flags bootstrap from the server (`getFlagsBootstrap()` / `client.getPayload()`): flag hooks\n   * render the same values on the server, during hydration and after.\n   */\n  flagsPayload?: FlagsBootstrap | null;\n  /** Extra flag attributes (merged over the automatic identity, page and device attributes). */\n  flagAttributes?: Attributes;\n  children?: ReactNode;\n}\n\n/** The attributes the server knows about a user: what bootstrap snapshots evaluate with. */\nfunction userAttributes(user: GuidelyUser | null | undefined): Attributes {\n  if (!user?.id) return {};\n  return { ...(user.traits ?? {}), id: user.id, ...(user.account ? { account: { ...(user.account.traits ?? {}), id: user.account.id } } : {}) };\n}\n\n/**\n * Creates one Guidely client for the subtree. The client is created inside an effect (never\n * during SSR) and destroyed on unmount, so React Strict Mode's double-invoke is harmless.\n */\nexport function GuidelyProvider({ children, user, flagsPayload, flagAttributes, ...options }: GuidelyProviderProps) {\n  const [client, setClient] = useState<GuidelyClient | null>(null);\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n  const userRef = useRef(user);\n  userRef.current = user;\n  const flagsOpts = options.flags === false ? null : (options.flags ?? {});\n  const payload = flagsPayload ?? flagsOpts?.payload ?? null;\n  const payloadRef = useRef(payload);\n  payloadRef.current = payload;\n  const appAttributes = useMemo(() => ({ ...(flagsOpts?.attributes ?? {}), ...(flagAttributes ?? {}) }), [stableStringify(flagsOpts?.attributes ?? {}), stableStringify(flagAttributes ?? {})]);\n  const appAttributesRef = useRef(appAttributes);\n  appAttributesRef.current = appAttributes;\n  const { projectId, environment, apiUrl } = options;\n\n  useEffect(() => {\n    if (typeof window === \"undefined\" || !projectId) return;\n    const o = optionsRef.current;\n    // The user is known up front so flags evaluate for them from the first render (no flicker).\n    const c = createGuidely({ ...o, projectId, environment, apiUrl, user: userRef.current?.id ? userRef.current : undefined, flags: o.flags === false ? false : { ...(o.flags ?? {}), payload: payloadRef.current ?? undefined, attributes: appAttributesRef.current } });\n    setClient(c);\n    return () => {\n      c.destroy();\n      setClient((cur) => (cur === c ? null : cur));\n    };\n  }, [projectId, environment, apiUrl]);\n\n  useEffect(() => {\n    client?.flags.setAttributes(appAttributes);\n  }, [client, appAttributes]);\n\n  const userKey = user ? JSON.stringify([user.id, user.traits ?? null, user.account ?? null]) : \"\";\n  const hadUser = useRef(false);\n  useEffect(() => {\n    if (!client) return;\n    if (user && user.id) {\n      hadUser.current = true;\n      void client.identify(user.id, user.traits, user.account);\n    } else if (hadUser.current) {\n      hadUser.current = false;\n      client.reset();\n    }\n  }, [client, userKey]);\n\n  const bootstrap = useBootstrap(payload, { ...userAttributes(user), ...appAttributes });\n  const flags = useMemo<FlagsSource>(() => ({ client: client?.flags ?? null, bootstrap }), [client, bootstrap]);\n  return (\n    <GuidelyContext.Provider value={client}>\n      <FlagsContext.Provider value={flags}>{children}</FlagsContext.Provider>\n    </GuidelyContext.Provider>\n  );\n}\n\nconst NOOP_RESULTS: Record<string, unknown> = {\n  init: Promise.resolve(),\n  ready: Promise.resolve(),\n  identify: Promise.resolve(),\n  setAccount: Promise.resolve(),\n  updateTraits: Promise.resolve(),\n  refresh: Promise.resolve(),\n  startGuide: false,\n  getActiveGuide: null,\n  getGuides: [],\n  getChecklistProgress: { completedTaskIds: [], completedAt: null, dismissedAt: null },\n  isGuideCompleted: false,\n  on: () => {},\n  getState: { ready: false, destroyed: false },\n  getContext: null,\n  getSessionId: \"\",\n  isRecording: false,\n};\n\n/** Flags that serve every fallback; `useGuidely().flags` before the provider has a client. */\nconst noopFlags = new Proxy(createStaticFlags() as unknown as FlagsClient, {\n  get(target, prop, receiver) {\n    if (prop in target) return Reflect.get(target, prop, receiver);\n    if (prop === \"ready\" || prop === \"refresh\" || prop === \"flush\") return () => Promise.resolve();\n    if (prop === \"getPayload\") return () => null;\n    if (prop === \"forUser\") return () => target;\n    return typeof prop === \"string\" ? () => undefined : undefined;\n  },\n});\n\nconst missing = <T,>(key: string, fallback: T): FlagDetails<T> => ({ key, value: fallback, reason: \"FLAG_NOT_FOUND\", inExperiment: false, usedFallback: true });\n\n/** Methods whose no-op answer depends on the arguments (flag getters return the fallback). */\nconst NOOP_FUNCTIONS: Record<string, (...args: any[]) => unknown> = {\n  isFeatureEnabled: (_key: string, fallback = false) => fallback,\n  getFeatureValue: (_key: string, fallback: unknown) => fallback,\n  getFeatureDetails: (key: string, fallback: unknown) => missing(key, fallback),\n  onFlagsChange: () => () => {},\n};\n\n/** A client that ignores every call; returned by `useGuidely()` on the server and before the provider mounts. */\nexport const noopClient: GuidelyClient = new Proxy({} as GuidelyClient, {\n  get(_target, prop) {\n    if (prop === \"options\") return { projectId: \"\" };\n    if (prop === \"flags\") return noopFlags;\n    if (typeof prop !== \"string\") return undefined;\n    return NOOP_FUNCTIONS[prop] ?? (() => NOOP_RESULTS[prop]);\n  },\n});\n\n/** The Guidely client, or a no-op client during SSR / before the provider has mounted. */\nexport function useGuidely(): GuidelyClient {\n  return useContext(GuidelyContext) ?? noopClient;\n}\n\n/** True once the client has loaded its configuration. */\nexport function useGuidelyReady(): boolean {\n  const client = useContext(GuidelyContext);\n  const [ready, setReady] = useState(false);\n  useEffect(() => {\n    if (!client) {\n      setReady(false);\n      return;\n    }\n    if (client.getState().ready) setReady(true);\n    return client.on(\"ready\", () => setReady(true));\n  }, [client]);\n  return ready;\n}\n\n/** Identifies the user whenever the arguments change. */\nexport function useGuidelyIdentify(userId: string | null | undefined, traits?: Record<string, unknown>, account?: GuidelyUser[\"account\"]): void {\n  const client = useContext(GuidelyContext);\n  const key = JSON.stringify([userId ?? null, traits ?? null, account ?? null]);\n  useEffect(() => {\n    if (!client || !userId) return;\n    void client.identify(userId, traits, account);\n  }, [client, key]);\n}\n\n/** Subscribes to a client event for the lifetime of the component. */\nexport function useGuidelyEvent<K extends keyof GuidelyEvents>(event: K, handler: GuidelyEvents[K]): void {\n  const client = useContext(GuidelyContext);\n  const ref = useRef(handler);\n  ref.current = handler;\n  useEffect(() => {\n    if (!client) return;\n    const cb = ((...args: unknown[]) => (ref.current as (...a: unknown[]) => void)(...args)) as GuidelyEvents[K];\n    return client.on(event, cb);\n  }, [client, event]);\n}\n\n/** Live checklist progress for a checklist guide (by id or key). */\nexport function useChecklistProgress(idOrKey: string): ChecklistProgressState {\n  const client = useContext(GuidelyContext);\n  const [progress, setProgress] = useState<ChecklistProgressState>({ completedTaskIds: [], completedAt: null, dismissedAt: null });\n  useEffect(() => {\n    if (!client) return;\n    const update = () => setProgress(client.getChecklistProgress(idOrKey));\n    update();\n    const offs = [client.on(\"ready\", update), client.on(\"identify\", update), client.on(\"checklist:task\", update), client.on(\"checklist:complete\", update)];\n    return () => offs.forEach((off) => off());\n  }, [client, idOrKey]);\n  return progress;\n}\n\nexport interface GuideState {\n  /** The guide is currently showing. */\n  active: boolean;\n  completed: boolean;\n  stepId: string | null;\n  stepIndex: number;\n  guide: PublishedGuide | null;\n}\n\n/** Live state of a guide (by id or key): active, completed, current step. */\nexport function useGuideState(idOrKey: string): GuideState {\n  const client = useContext(GuidelyContext);\n  const [state, setState] = useState<GuideState>({ active: false, completed: false, stepId: null, stepIndex: -1, guide: null });\n  useEffect(() => {\n    if (!client) return;\n    const matches = (g: PublishedGuide) => g.id === idOrKey || g.key === idOrKey;\n    const compute = () => {\n      const guide = client.getGuides().find(matches) ?? null;\n      const active = client.getActiveGuide();\n      const s = client.getState().activeGuide;\n      setState({ active: !!active && matches(active), completed: client.isGuideCompleted(idOrKey), stepId: active && matches(active) ? ((s as { stepId?: string | null } | null)?.stepId ?? null) : null, stepIndex: active && matches(active) ? ((s as { stepIndex?: number } | null)?.stepIndex ?? -1) : -1, guide });\n    };\n    compute();\n    const offs = ([\"ready\", \"identify\", \"guide:start\", \"guide:step\", \"guide:complete\", \"guide:dismiss\", \"guide:skip\"] as const).map((e) => client.on(e, compute));\n    return () => offs.forEach((off) => off());\n  }, [client, idOrKey]);\n  return state;\n}\n","import { createFlagsClient, createStaticFlags, jsonEquals, stableStringify, type Attributes, type FlagDetails, type FlagValue, type FlagsBootstrap, type FlagsClient, type FlagsClientOptions, type FlagsReader, type JsonValue } from \"@guidelytech/flags\";\nimport { createContext, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, type ReactNode } from \"react\";\n\n/** What the flag hooks read: the live client once created, else a static snapshot of the bootstrap payload. */\nexport interface FlagsSource {\n  client: FlagsClient | null;\n  bootstrap: FlagsReader;\n}\n\nexport const FlagsContext = createContext<FlagsSource | null>(null);\n\nconst EMPTY = createStaticFlags();\n\nfunction useReader(): FlagsReader {\n  const src = useContext(FlagsContext);\n  return src?.client ?? src?.bootstrap ?? EMPTY;\n}\n\n/**\n * Subscribes to the flags with `useSyncExternalStore`. Values are compared deeply so object\n * flags keep their identity between renders. The server snapshot is the bootstrap payload, so\n * server-rendered HTML and hydration agree.\n */\nfunction useFlagsValue<T>(select: (reader: FlagsReader) => T): T {\n  const reader = useReader();\n  const cache = useRef<{ reader: FlagsReader; value: T } | null>(null);\n  const get = () => {\n    const value = select(reader);\n    const c = cache.current;\n    if (c && c.reader === reader && jsonEquals(c.value, value)) return c.value;\n    cache.current = { reader, value };\n    return value;\n  };\n  return useSyncExternalStore(reader.subscribe, get, get);\n}\n\n/** Is the boolean flag on? `fallback` (default `false`) until flags load, or when missing. */\nexport function useFlag(key: string, fallback = false): boolean {\n  return useFlagsValue((r) => r.isEnabled(key, fallback));\n}\n\n/** A flag's value (string, number, JSON…); `fallback` when missing or of a different type. */\nexport function useFeatureValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T> {\n  return useFlagsValue((r) => r.getValue(key, fallback));\n}\n\n/** A flag's value plus why it was served (reason, rule, variation, experiment). */\nexport function useFlagDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>> {\n  return useFlagsValue((r) => r.getDetails(key, fallback));\n}\n\n/** Every flag's value (records no exposures). */\nexport function useFlags(): Record<string, JsonValue> {\n  return useFlagsValue((r) => r.getAll());\n}\n\n/** True once flags have loaded (or failed to and serve fallbacks); true from the start with a bootstrap payload. */\nexport function useFlagsReady(): boolean {\n  return useFlagsValue((r) => r.isReady());\n}\n\n/** The flags client (`null` on the server and before the provider has created it). */\nexport function useFlagsClient(): FlagsClient | null {\n  return useContext(FlagsContext)?.client ?? null;\n}\n\nexport interface FeatureProps {\n  flag: string;\n  children?: ReactNode;\n  /** Rendered while the flag is off (default: nothing). */\n  fallback?: ReactNode;\n}\n\n/** Renders `children` when the boolean flag is on, else `fallback`. */\nexport function Feature({ flag, children, fallback = null }: FeatureProps) {\n  return <>{useFlag(flag) ? children : fallback}</>;\n}\n\n/** Alias of {@link Feature}. */\nexport const FeatureFlag = Feature;\n\nexport interface FeatureValueProps extends FeatureProps {\n  /** Renders `children` when the flag's value equals this (deep equality). */\n  value: JsonValue;\n}\n\n/** Renders `children` when the flag's value equals `value` (e.g. an experiment variation), else `fallback`. */\nexport function FeatureValue({ flag, value, children, fallback = null }: FeatureValueProps) {\n  const current = useFeatureValue<JsonValue>(flag, null);\n  return <>{jsonEquals(current, value) ? children : fallback}</>;\n}\n\n/** A static snapshot for SSR and hydration, rebuilt only when the payload or attributes change. */\nexport function useBootstrap(payload: FlagsBootstrap | null | undefined, attributes: Attributes): FlagsReader {\n  const key = stableStringify(attributes);\n  return useMemo(() => (payload ? createStaticFlags({ payload, attributes }) : EMPTY), [payload, key]);\n}\n\nexport interface FlagsProviderProps extends Omit<FlagsClientOptions, \"payload\"> {\n  /** Bootstrap from the server (`getPayload()`): renders the same values on the server and in the browser. */\n  payload?: FlagsBootstrap | null;\n  /** Use an existing client instead of creating one. */\n  client?: FlagsClient;\n  children?: ReactNode;\n}\n\n/**\n * Feature flags only (no guides or analytics). Creates a flags client in an effect (never during\n * SSR) and destroys it on unmount; until then hooks read the `payload` snapshot. Changing\n * `attributes` re-evaluates without recreating the client.\n *\n * ```tsx\n * <FlagsProvider sdkKey=\"pk_prod_…\" attributes={{ id: user.id, plan: user.plan }} payload={bootstrap}>\n * ```\n */\nexport function FlagsProvider({ children, client: external, payload, ...options }: FlagsProviderProps) {\n  const [created, setCreated] = useState<FlagsClient | null>(null);\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n  const sdkKey = options.sdkKey ?? options.projectId;\n  const { apiUrl, environment } = options;\n  const payloadRef = useRef(payload);\n  payloadRef.current = payload;\n\n  useEffect(() => {\n    if (external || !sdkKey || typeof window === \"undefined\") return;\n    let c: FlagsClient;\n    try {\n      c = createFlagsClient({ ...optionsRef.current, sdkKey, payload: payloadRef.current ?? undefined });\n    } catch (err) {\n      optionsRef.current.onError?.(err instanceof Error ? err : new Error(String(err)));\n      return;\n    }\n    setCreated(c);\n    return () => {\n      c.destroy();\n      setCreated((cur) => (cur === c ? null : cur));\n    };\n  }, [external, sdkKey, apiUrl, environment]);\n\n  const client = external ?? created;\n  const attributes = options.attributes ?? {};\n  const attrsKey = stableStringify(attributes);\n  useEffect(() => {\n    if (client && options.attributes) client.setAttributes(options.attributes);\n  }, [client, attrsKey]);\n\n  const bootstrap = useBootstrap(payload, attributes);\n  const value = useMemo<FlagsSource>(() => ({ client, bootstrap }), [client, bootstrap]);\n  return <FlagsContext.Provider value={value}>{children}</FlagsContext.Provider>;\n}\n"],"mappings":"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","names":["createStaticFlags","stableStringify","createContext","useContext","useEffect","useMemo","useRef","useState","jsx","createContext","useState","useRef","useMemo","stableStringify","useEffect","createStaticFlags","useContext"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidelytech/react",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "React provider and hooks for Guidely",
   "license": "MIT",
   "type": "module",
@@ -20,8 +20,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@guidelytech/sdk-core": "0.6.2",
-    "@guidelytech/shared": "0.6.2"
+    "@guidelytech/flags": "0.8.0",
+    "@guidelytech/shared": "0.8.0",
+    "@guidelytech/sdk-core": "0.8.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",