@guidelytech/react-native 0.6.1 → 0.7.0

package/dist/index.d.cts

@@ -2,6 +2,8 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import { SelectorStrategy, MessengerConfig, MessengerMessage, MessengerConversation, SdkArticlesResponse, ResourceCenterArticle, PublishedGuide, ProjectTheme, GuideStep, SdkConfigResponse, ChecklistTask, SdkEvent, TargetingContext, StepButton, ResourceCenterConfig, Placement } from '@guidelytech/shared';
 export { GuideStep, PublishedGuide, SdkConfigResponse } from '@guidelytech/shared';
+import { FlagsClientOptions, FlagsClient, JsonValue, FlagValue, FlagDetails, FlagsBootstrap, Attributes } from '@guidelytech/flags';
+export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, InMemoryStickyBucketStore, JsonValue, createFlagsClient } from '@guidelytech/flags';
 import { KeyValueStore, ChecklistProgressState, GuidelyEnvironment, ConsentState, GuidelyUser, GuidelyAccount, GuideLocalState, SessionState } from '@guidelytech/sdk-core/headless';
 export { ChecklistProgressState, ConsentState, GuidelyAccount, GuidelyEnvironment, GuidelyUser } from '@guidelytech/sdk-core/headless';
 import { ViewProps, StyleProp, ViewStyle, View, GestureResponderEvent } from 'react-native';
@@ -241,6 +243,12 @@ interface GuidelyOptions {
     showResourceCenterLauncher?: boolean;
     /** Show the Scout chat bubble when the messenger is on for this platform (default `true`). */
     showMessengerLauncher?: boolean;
+    /**
+     * Feature flags (on by default, same key and API URL; the last payload is kept in `storage` so
+     * flags work offline at cold start). `false` turns them off; an object passes options to the
+     * flags client (`attributes`, `payload`, `remoteEval`, `pollingMode`…).
+     */
+    flags?: false | Partial<FlagsClientOptions>;
 }
 interface GuideStepInfo {
     guide: PublishedGuide;
@@ -280,6 +288,10 @@ interface GuidelyEvents {
         userId: string | null;
         anonymousId: string;
     }) => void;
+    /** Feature flags loaded (bootstrap, storage or network) — or failed to and serve fallbacks. */
+    "flags:ready": () => void;
+    /** New flag rules arrived. */
+    "flags:change": () => void;
 }
 type GuidelyEventName = keyof GuidelyEvents;
 /** A rendered step, as the overlay sees it. */
@@ -319,7 +331,7 @@ interface UiState {
 }
 
 declare const SDK_NAME = "@guidelytech/react-native";
-declare const SDK_VERSION = "0.6.1";
+declare const SDK_VERSION = "0.7.0";
 declare const DEFAULT_API_URL = "https://guidelytech.com";
 /** Host-platform services the engine needs; the provider supplies React Native implementations. */
 interface PlatformBridge {
@@ -382,9 +394,14 @@ declare class GuidelyClient {
     private messenger;
     private ui;
     private uiListeners;
+    /** Feature flags for this environment: `guidely.flags.isEnabled("new-checkout")`. */
+    readonly flags: FlagsClient;
+    /** Experiments already reported this session (`experiment_viewed` is sent once per session). */
+    private exposures;
     private readonly customListeners;
     private readonly eventBus;
     constructor(options: GuidelyOptions, bridge: PlatformBridge);
+    private createFlags;
     /** Loads persisted state and config, identifies the stored user and evaluates triggers. Idempotent. */
     init(): Promise<void>;
     ready(): Promise<void>;
@@ -509,6 +526,19 @@ declare class GuidelyClient {
     closeMessenger(): void;
     /** Opens a new messenger conversation, optionally pre-filling the message. */
     showNewMessage(text?: string): void;
+    /** Boolean flag value for the current user; `fallback` (default `false`) until loaded or when missing. */
+    isFeatureEnabled(key: string, fallback?: boolean): boolean;
+    /** Flag value for the current user; `fallback` when missing or of a different type. */
+    getFeatureValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T>;
+    /** Flag value plus why it was served (reason, rule, variation, experiment). */
+    getFeatureDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
+    /** Calls `cb` whenever flag values may have changed. Returns an unsubscribe function. */
+    onFlagsChange(cb: () => void): () => void;
+    /** Attributes flags are evaluated with: identity, traits, account, audiences, screen and device. */
+    private flagContext;
+    private syncFlagAttributes;
+    /** `experiment_viewed`, once per session and assignment, through the event queue (consent applies). */
+    private trackExposure;
     on<K extends keyof GuidelyEvents>(event: K, cb: GuidelyEvents[K]): () => void;
     off<K extends keyof GuidelyEvents>(event: K, cb: GuidelyEvents[K]): void;
     isClientReady(): boolean;
@@ -545,6 +575,7 @@ declare class GuidelyClient {
         session: MobileSession;
         pendingEvents: number;
         targets: string[];
+        flagsReady: boolean;
     };
     private persistState;
     private persistSession;
@@ -678,6 +709,51 @@ declare function parseHtml(html: string): TextBlock[];
 /** Plain-text rendering of an HTML body (accessibility labels, previews). */
 declare function htmlToText(html: string): string;
 
+/** 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 (bootstrap, storage or network) or failed to and serve fallbacks. */
+declare function useFlagsReady(): boolean;
+/** The flags client (`null` 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 payload (or remote results) used until the client has loaded. */
+    payload?: FlagsBootstrap | null;
+    /** Use an existing client instead of creating one. */
+    client?: FlagsClient;
+    children?: ReactNode;
+}
+/**
+ * Feature flags only (no guides or analytics). Pass AsyncStorage as `storage` so the last flags
+ * serve offline at cold start. Refreshes when the app returns to the foreground.
+ *
+ * ```tsx
+ * <FlagsProvider sdkKey="pk_prod_…" apiUrl="https://guidelytech.com" storage={AsyncStorage} attributes={{ id: user.id }}>
+ * ```
+ */
+declare function FlagsProvider({ children, client: external, payload, ...options }: FlagsProviderProps): react.JSX.Element;
+
 interface GuidelyProviderProps extends Omit<GuidelyOptions, "user"> {
     /** Identify this user once the client is ready; changing to `null` resets the identity (logout). */
     user?: GuidelyUser | null;
@@ -685,13 +761,17 @@ interface GuidelyProviderProps extends Omit<GuidelyOptions, "user"> {
     insets?: Partial<Insets>;
     /** How far above the bottom inset the checklist launcher sits, to clear tab bars (default 72). */
     launcherOffset?: number;
+    /** Flags bootstrap (a payload or remote results) served until the client has loaded. */
+    flagsPayload?: FlagsBootstrap | null;
+    /** Extra flag attributes (merged over the automatic identity, screen and device attributes). */
+    flagAttributes?: Attributes;
     children?: ReactNode;
 }
 /**
  * Creates one Guidely client for the app and renders guide UI above `children`. Place it at the
  * root of the app (outside navigators) so the overlay covers every screen.
  */
-declare function GuidelyProvider({ children, user, insets, launcherOffset, ...options }: GuidelyProviderProps): react.JSX.Element;
+declare function GuidelyProvider({ children, user, insets, launcherOffset, flagsPayload, flagAttributes, ...options }: GuidelyProviderProps): react.JSX.Element;
 /** A client that ignores every call; returned by `useGuidely()` before the provider has created one. */
 declare const noopClient: GuidelyClient;
 /** The Guidely client (a no-op stand-in until the provider has created it). */
@@ -737,4 +817,4 @@ declare function useGuideState(idOrKey: string): {
 /** The guide currently running exclusively (flow, modal, survey…), or null. */
 declare function useActiveGuide(): PublishedGuide | null;
 
-export { type ChecklistView, DEFAULT_API_URL, type DeviceEnvironment, type GuideStepInfo, GuidelyClient, type GuidelyEventName, type GuidelyEvents, type GuidelyOptions, GuidelyOverlay, GuidelyProvider, type GuidelyProviderProps, GuidelyScreenScope, type GuidelyStorage, GuidelyTarget, type GuidelyTargetProps, type Insets, Messenger, type MessengerSnapshot, type MessengerTab, type MessengerThread, type MessengerView, type PlatformBridge, SDK_NAME, SDK_VERSION, type StepView, type SurveyView, TargetRegistry, type UiState, createSseParser, guidelyScreenLayout, htmlToText, noopClient, parseHtml, positionCard, targetIdsFor, useActiveGuide, useChecklistProgress, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyNavigation, useGuidelyReady, useGuidelyScreen, useGuidelyTarget };
+export { type ChecklistView, DEFAULT_API_URL, type DeviceEnvironment, Feature, FeatureFlag, type FeatureProps, FeatureValue, type FeatureValueProps, FlagsProvider, type FlagsProviderProps, type GuideStepInfo, GuidelyClient, type GuidelyEventName, type GuidelyEvents, type GuidelyOptions, GuidelyOverlay, GuidelyProvider, type GuidelyProviderProps, GuidelyScreenScope, type GuidelyStorage, GuidelyTarget, type GuidelyTargetProps, type Insets, Messenger, type MessengerSnapshot, type MessengerTab, type MessengerThread, type MessengerView, type PlatformBridge, SDK_NAME, SDK_VERSION, type StepView, type SurveyView, TargetRegistry, type UiState, createSseParser, guidelyScreenLayout, htmlToText, noopClient, parseHtml, positionCard, targetIdsFor, useActiveGuide, useChecklistProgress, useFeatureValue, useFlag, useFlagDetails, useFlags, useFlagsClient, useFlagsReady, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyNavigation, useGuidelyReady, useGuidelyScreen, useGuidelyTarget };

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import { SelectorStrategy, MessengerConfig, MessengerMessage, MessengerConversation, SdkArticlesResponse, ResourceCenterArticle, PublishedGuide, ProjectTheme, GuideStep, SdkConfigResponse, ChecklistTask, SdkEvent, TargetingContext, StepButton, ResourceCenterConfig, Placement } from '@guidelytech/shared';
 export { GuideStep, PublishedGuide, SdkConfigResponse } from '@guidelytech/shared';
+import { FlagsClientOptions, FlagsClient, JsonValue, FlagValue, FlagDetails, FlagsBootstrap, Attributes } from '@guidelytech/flags';
+export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, InMemoryStickyBucketStore, JsonValue, createFlagsClient } from '@guidelytech/flags';
 import { KeyValueStore, ChecklistProgressState, GuidelyEnvironment, ConsentState, GuidelyUser, GuidelyAccount, GuideLocalState, SessionState } from '@guidelytech/sdk-core/headless';
 export { ChecklistProgressState, ConsentState, GuidelyAccount, GuidelyEnvironment, GuidelyUser } from '@guidelytech/sdk-core/headless';
 import { ViewProps, StyleProp, ViewStyle, View, GestureResponderEvent } from 'react-native';
@@ -241,6 +243,12 @@ interface GuidelyOptions {
     showResourceCenterLauncher?: boolean;
     /** Show the Scout chat bubble when the messenger is on for this platform (default `true`). */
     showMessengerLauncher?: boolean;
+    /**
+     * Feature flags (on by default, same key and API URL; the last payload is kept in `storage` so
+     * flags work offline at cold start). `false` turns them off; an object passes options to the
+     * flags client (`attributes`, `payload`, `remoteEval`, `pollingMode`…).
+     */
+    flags?: false | Partial<FlagsClientOptions>;
 }
 interface GuideStepInfo {
     guide: PublishedGuide;
@@ -280,6 +288,10 @@ interface GuidelyEvents {
         userId: string | null;
         anonymousId: string;
     }) => void;
+    /** Feature flags loaded (bootstrap, storage or network) — or failed to and serve fallbacks. */
+    "flags:ready": () => void;
+    /** New flag rules arrived. */
+    "flags:change": () => void;
 }
 type GuidelyEventName = keyof GuidelyEvents;
 /** A rendered step, as the overlay sees it. */
@@ -319,7 +331,7 @@ interface UiState {
 }
 
 declare const SDK_NAME = "@guidelytech/react-native";
-declare const SDK_VERSION = "0.6.1";
+declare const SDK_VERSION = "0.7.0";
 declare const DEFAULT_API_URL = "https://guidelytech.com";
 /** Host-platform services the engine needs; the provider supplies React Native implementations. */
 interface PlatformBridge {
@@ -382,9 +394,14 @@ declare class GuidelyClient {
     private messenger;
     private ui;
     private uiListeners;
+    /** Feature flags for this environment: `guidely.flags.isEnabled("new-checkout")`. */
+    readonly flags: FlagsClient;
+    /** Experiments already reported this session (`experiment_viewed` is sent once per session). */
+    private exposures;
     private readonly customListeners;
     private readonly eventBus;
     constructor(options: GuidelyOptions, bridge: PlatformBridge);
+    private createFlags;
     /** Loads persisted state and config, identifies the stored user and evaluates triggers. Idempotent. */
     init(): Promise<void>;
     ready(): Promise<void>;
@@ -509,6 +526,19 @@ declare class GuidelyClient {
     closeMessenger(): void;
     /** Opens a new messenger conversation, optionally pre-filling the message. */
     showNewMessage(text?: string): void;
+    /** Boolean flag value for the current user; `fallback` (default `false`) until loaded or when missing. */
+    isFeatureEnabled(key: string, fallback?: boolean): boolean;
+    /** Flag value for the current user; `fallback` when missing or of a different type. */
+    getFeatureValue<T extends JsonValue>(key: string, fallback: T): FlagValue<T>;
+    /** Flag value plus why it was served (reason, rule, variation, experiment). */
+    getFeatureDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
+    /** Calls `cb` whenever flag values may have changed. Returns an unsubscribe function. */
+    onFlagsChange(cb: () => void): () => void;
+    /** Attributes flags are evaluated with: identity, traits, account, audiences, screen and device. */
+    private flagContext;
+    private syncFlagAttributes;
+    /** `experiment_viewed`, once per session and assignment, through the event queue (consent applies). */
+    private trackExposure;
     on<K extends keyof GuidelyEvents>(event: K, cb: GuidelyEvents[K]): () => void;
     off<K extends keyof GuidelyEvents>(event: K, cb: GuidelyEvents[K]): void;
     isClientReady(): boolean;
@@ -545,6 +575,7 @@ declare class GuidelyClient {
         session: MobileSession;
         pendingEvents: number;
         targets: string[];
+        flagsReady: boolean;
     };
     private persistState;
     private persistSession;
@@ -678,6 +709,51 @@ declare function parseHtml(html: string): TextBlock[];
 /** Plain-text rendering of an HTML body (accessibility labels, previews). */
 declare function htmlToText(html: string): string;
 
+/** 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 (bootstrap, storage or network) or failed to and serve fallbacks. */
+declare function useFlagsReady(): boolean;
+/** The flags client (`null` 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 payload (or remote results) used until the client has loaded. */
+    payload?: FlagsBootstrap | null;
+    /** Use an existing client instead of creating one. */
+    client?: FlagsClient;
+    children?: ReactNode;
+}
+/**
+ * Feature flags only (no guides or analytics). Pass AsyncStorage as `storage` so the last flags
+ * serve offline at cold start. Refreshes when the app returns to the foreground.
+ *
+ * ```tsx
+ * <FlagsProvider sdkKey="pk_prod_…" apiUrl="https://guidelytech.com" storage={AsyncStorage} attributes={{ id: user.id }}>
+ * ```
+ */
+declare function FlagsProvider({ children, client: external, payload, ...options }: FlagsProviderProps): react.JSX.Element;
+
 interface GuidelyProviderProps extends Omit<GuidelyOptions, "user"> {
     /** Identify this user once the client is ready; changing to `null` resets the identity (logout). */
     user?: GuidelyUser | null;
@@ -685,13 +761,17 @@ interface GuidelyProviderProps extends Omit<GuidelyOptions, "user"> {
     insets?: Partial<Insets>;
     /** How far above the bottom inset the checklist launcher sits, to clear tab bars (default 72). */
     launcherOffset?: number;
+    /** Flags bootstrap (a payload or remote results) served until the client has loaded. */
+    flagsPayload?: FlagsBootstrap | null;
+    /** Extra flag attributes (merged over the automatic identity, screen and device attributes). */
+    flagAttributes?: Attributes;
     children?: ReactNode;
 }
 /**
  * Creates one Guidely client for the app and renders guide UI above `children`. Place it at the
  * root of the app (outside navigators) so the overlay covers every screen.
  */
-declare function GuidelyProvider({ children, user, insets, launcherOffset, ...options }: GuidelyProviderProps): react.JSX.Element;
+declare function GuidelyProvider({ children, user, insets, launcherOffset, flagsPayload, flagAttributes, ...options }: GuidelyProviderProps): react.JSX.Element;
 /** A client that ignores every call; returned by `useGuidely()` before the provider has created one. */
 declare const noopClient: GuidelyClient;
 /** The Guidely client (a no-op stand-in until the provider has created it). */
@@ -737,4 +817,4 @@ declare function useGuideState(idOrKey: string): {
 /** The guide currently running exclusively (flow, modal, survey…), or null. */
 declare function useActiveGuide(): PublishedGuide | null;
 
-export { type ChecklistView, DEFAULT_API_URL, type DeviceEnvironment, type GuideStepInfo, GuidelyClient, type GuidelyEventName, type GuidelyEvents, type GuidelyOptions, GuidelyOverlay, GuidelyProvider, type GuidelyProviderProps, GuidelyScreenScope, type GuidelyStorage, GuidelyTarget, type GuidelyTargetProps, type Insets, Messenger, type MessengerSnapshot, type MessengerTab, type MessengerThread, type MessengerView, type PlatformBridge, SDK_NAME, SDK_VERSION, type StepView, type SurveyView, TargetRegistry, type UiState, createSseParser, guidelyScreenLayout, htmlToText, noopClient, parseHtml, positionCard, targetIdsFor, useActiveGuide, useChecklistProgress, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyNavigation, useGuidelyReady, useGuidelyScreen, useGuidelyTarget };
+export { type ChecklistView, DEFAULT_API_URL, type DeviceEnvironment, Feature, FeatureFlag, type FeatureProps, FeatureValue, type FeatureValueProps, FlagsProvider, type FlagsProviderProps, type GuideStepInfo, GuidelyClient, type GuidelyEventName, type GuidelyEvents, type GuidelyOptions, GuidelyOverlay, GuidelyProvider, type GuidelyProviderProps, GuidelyScreenScope, type GuidelyStorage, GuidelyTarget, type GuidelyTargetProps, type Insets, Messenger, type MessengerSnapshot, type MessengerTab, type MessengerThread, type MessengerView, type PlatformBridge, SDK_NAME, SDK_VERSION, type StepView, type SurveyView, TargetRegistry, type UiState, createSseParser, guidelyScreenLayout, htmlToText, noopClient, parseHtml, positionCard, targetIdsFor, useActiveGuide, useChecklistProgress, useFeatureValue, useFlag, useFlagDetails, useFlags, useFlagsClient, useFlagsReady, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyNavigation, useGuidelyReady, useGuidelyScreen, useGuidelyTarget };