@ops-ai/react-router-toggly 1.0.1 → 1.2.0

package/dist/client.d.ts

@@ -27,6 +27,10 @@ type EvaluationMode = 'local' | 'remote';
  * Configuration options for Toggly
  */
 interface TogglyConfig {
+    /** Enable compact browser telemetry (default: true with an app key). */
+    enableTelemetry?: boolean;
+    /** Browser telemetry interval, 30000–60000 ms (default: 45000). */
+    telemetryFlushIntervalMs?: number;
     /** Toggly application key */
     appKey?: string;
     /** Environment name (e.g., 'Production', 'Staging') */
@@ -61,6 +65,16 @@ interface TogglyConfig {
     localGates?: LocalGate[];
     /** Optional SDK error callback for reporting fetch/evaluation failures. */
     onError?: (message: string, error?: unknown) => void;
+    /**
+     * Use `/evaluated-variants-signed` and expose {@link TogglyContextValue.getVariant} /
+     * `getVariantValue` (client) or the equivalent {@link TogglyServerClient} methods
+     * (server). Only applies in `remote` evaluationMode client-side; the server
+     * package forces `remote` when this is set (mirrors the Nuxt/Astro OPS-825
+     * override — server otherwise defaults to `definitions-signed` + local eval).
+     */
+    enableVariants?: boolean;
+    /** Host-minted browser capability; takes precedence over client identity targeting. */
+    instanceId?: string;
     /** Initial browser identity; hydrated server identity takes precedence. */
     identity?: string;
     /** User groups for targeting */
@@ -117,6 +131,8 @@ interface TogglyConfig {
  * User identity context for feature targeting
  */
 interface IdentityContext {
+    /** Browser capability. An empty value clears the token; omitted identity updates use client targeting. */
+    instanceId?: string;
     /** Unique user identifier */
     identity?: string;
     /** User groups for targeting */
@@ -136,6 +152,13 @@ interface IdentityContext {
  * Feature flags state (boolean or entity gate per flag)
  */
 type FeatureFlags = EvaluatedDefinitions;
+/**
+ * Assigned variant for a feature (aligned with @ops-ai/feature-flags-toggly).
+ */
+interface VariantResult {
+    name: string;
+    configurationValue?: unknown;
+}
 /**
  * Feature evaluation result
  */
@@ -242,10 +265,18 @@ declare const HEADERS: {
 /** Meta key for loader data */
 declare const TOGGLY_LOADER_KEY: "__toggly";
 
+interface FrontendTelemetry {
+    recordUsage(featureKey: string, variant?: string): void;
+    recordView(featureKey: string, variant?: string): void;
+    incrementCounter(metricKey: string, value?: number): void;
+    setGauge(metricKey: string, value: number): void;
+    flushTelemetry(): Promise<void>;
+}
+
 /**
  * Toggly context value
  */
-interface TogglyContextValue {
+interface TogglyContextValue extends FrontendTelemetry {
     /** Current feature flags */
     flags: FeatureFlags;
     /** Whether the client is initialized */
@@ -260,6 +291,17 @@ interface TogglyContextValue {
     evaluateGate: (featureKeys: string[], requirement?: 'all' | 'any', negate?: boolean, entity?: TogglyEntityContext | Record<string, unknown> | null, kind?: string) => boolean;
     /** Register a domain-object mapper for entity-context evaluation */
     registerContext: <T>(kind: string, mapper: (entity: T) => TogglyEntityContext) => void;
+    /**
+     * Current variant assignment for a feature (requires `enableVariants` in the
+     * provider config). Soft-null when variants are disabled, unassigned, or the
+     * effective flag is off — never throws.
+     */
+    getVariant: (featureKey: string) => VariantResult | null;
+    /**
+     * Configuration payload for the assigned variant, if any.
+     * Optional `isT` type guard soft-fails to null on mismatch.
+     */
+    getVariantValue: <T = unknown>(featureKey: string, isT?: (v: unknown) => v is T) => T | null;
     /** Set user identity */
     identify: (identity: string, context?: IdentityContext) => Promise<void>;
     /** Clear user identity */
@@ -298,7 +340,7 @@ declare const TogglyContext: react.Context<TogglyContextValue | undefined>;
 /**
  * Toggly Provider component
  */
-declare function TogglyProvider({ children, serverContext, config, enableRefresh, refreshInterval, onFlagsChange, }: TogglyProviderProps): ReactElement;
+declare function TogglyProvider(props: Readonly<TogglyProviderProps>): ReactElement;
 /**
  * Hook to access Toggly context
  */
@@ -600,4 +642,4 @@ declare function TogglyScript({ serverContext, nonce, }: {
  */
 declare function getWindowTogglyData(): ServerFeatureContext | undefined;
 
-export { type EvaluationResult, type EvaluationSeriesData, Feature, FeatureDisabled, type FeatureDisabledProps, FeatureEnabled, type FeatureEnabledProps, type FeatureFlags, FeatureGate, type FeatureGateProps, type FeatureProps, type FeatureRequirement, FeatureSwitch, type FeatureSwitchProps, HEADERS, type HookMetadata, type IdentityContext, type IdentitySeriesData, type LoaderDataWithToggly, RouterTogglyProvider, type RouterTogglyProviderProps, STORAGE_KEYS, type ServerFeatureContext, TOGGLY_LOADER_KEY, type TogglyConfig, TogglyConfigError, TogglyContext, type TogglyContextValue, TogglyError, type TogglyHook, TogglyNetworkError, TogglyProvider, type TogglyProviderProps, TogglyScript, TogglyTimeoutError, extractServerContext, getWindowTogglyData, hasTogglyContext, useABTest, useFeature, useFeatureCallback, useFeatureChange, useFeatureDisabled, useFeatureFlags, useFeatureGate, useFeatureRender, useFeatureValue, useFeatureWithLoading, useFeatures, useIdentity, useRefreshFlags, useToggly, useTogglyContext, useTogglyLoaderData, useTogglyReady, useTogglyRouteLoaderData };
+export { type EvaluationResult, type EvaluationSeriesData, Feature, FeatureDisabled, type FeatureDisabledProps, FeatureEnabled, type FeatureEnabledProps, type FeatureFlags, FeatureGate, type FeatureGateProps, type FeatureProps, type FeatureRequirement, FeatureSwitch, type FeatureSwitchProps, type FrontendTelemetry, HEADERS, type HookMetadata, type IdentityContext, type IdentitySeriesData, type LoaderDataWithToggly, RouterTogglyProvider, type RouterTogglyProviderProps, STORAGE_KEYS, type ServerFeatureContext, TOGGLY_LOADER_KEY, type TogglyConfig, TogglyConfigError, TogglyContext, type TogglyContextValue, TogglyError, type TogglyHook, TogglyNetworkError, TogglyProvider, type TogglyProviderProps, TogglyScript, TogglyTimeoutError, extractServerContext, getWindowTogglyData, hasTogglyContext, useABTest, useFeature, useFeatureCallback, useFeatureChange, useFeatureDisabled, useFeatureFlags, useFeatureGate, useFeatureRender, useFeatureValue, useFeatureWithLoading, useFeatures, useIdentity, useRefreshFlags, useToggly, useTogglyContext, useTogglyLoaderData, useTogglyReady, useTogglyRouteLoaderData };