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

package/dist/client.d.ts

@@ -65,6 +65,14 @@ 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. */
@@ -144,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
  */
@@ -276,6 +291,17 @@ interface TogglyContextValue extends FrontendTelemetry {
     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 */

package/dist/client.js

@@ -1,6 +1,7 @@
 import { registerContext, normalizeEntityContext, serializeJsonForInlineScript, resolveEvaluatedDefinition, appendEvaluationContext } from '@ops-ai/toggly-hooks-types';
 export { normalizeEntityContext, registerContext } from '@ops-ai/toggly-hooks-types';
 import '@ops-ai/toggly-eval';
+import { asVariantDefsRecord, unwrapDefsPayload } from '@ops-ai/toggly-signed-defs';
 import { createContext, useRef, useMemo, useState, useEffect, useCallback, useContext, useLayoutEffect } from 'react';
 import { createTelemetryReporter } from '@ops-ai/toggly-client-telemetry';
 import { attachBrowserLifecycle } from '@ops-ai/toggly-client-telemetry/browser';
@@ -51,12 +52,18 @@ function mergeConfig(config) {
   };
 }
 function buildDefinitionsUrl(config, context) {
-  const { baseUrl, appKey, environment, groups, claims, evaluationMode } = mergeConfig(config);
+  const { baseUrl, appKey, environment, groups, claims, evaluationMode, enableVariants } = mergeConfig(config);
   if (!appKey) {
     throw new Error("appKey is required");
   }
   const mode = evaluationMode ?? "remote";
-  const pathSegment = mode === "local" ? "definitions-signed" : "evaluated-signed";
+  const useVariants = mode !== "local" && enableVariants === true;
+  let pathSegment = "evaluated-signed";
+  if (mode === "local") {
+    pathSegment = "definitions-signed";
+  } else if (useVariants) {
+    pathSegment = "evaluated-variants-signed";
+  }
   const url = new URL(`${baseUrl}/${pathSegment}/${appKey}/${environment}`);
   if (mode === "local") {
     return url.toString();
@@ -69,10 +76,25 @@ function buildDefinitionsUrl(config, context) {
       groups: fromParam?.groups ?? groups,
       claims: fromParam?.claims ?? claims
     },
-    "evaluated"
+    useVariants ? "variants" : "evaluated"
   );
   return url.toString();
 }
+function parseVariantDefsPayload(parsed) {
+  return asVariantDefsRecord(unwrapDefsPayload(parsed));
+}
+function variantDefsToFlags(defs) {
+  const out = {};
+  for (const key of Object.keys(defs)) {
+    out[key] = defs[key]?.enabled === true;
+  }
+  return out;
+}
+function decodeVariantValue(value, isT) {
+  if (value === null || value === void 0) return null;
+  if (isT) return isT(value) ? value : null;
+  return value;
+}
 function isFeatureEnabled(flags, featureKey, defaultValue = false, entityContext) {
   if (!flags || Object.keys(flags).length === 0) {
     return defaultValue;
@@ -137,6 +159,12 @@ var HEADERS = {
   CACHE_CONTROL: "cache-control"
 };
 var TOGGLY_LOADER_KEY = "__toggly";
+function checkVariantLabel(result) {
+  if (typeof result === "string") {
+    return result;
+  }
+  return result ? "enabled" : "disabled";
+}
 function createBrowserTelemetry(config) {
   const enabled = globalThis.window !== void 0 && typeof document !== "undefined" && !!config.appKey?.trim() && config.enableTelemetry !== false;
   const usage = enabled && config.enableUsageTracking !== false;
@@ -265,13 +293,13 @@ function createBrowserTelemetry(config) {
       };
       if (active) {
         const record = getReporter().captureCheck();
-        return (key, result) => record(key, result ? "enabled" : "disabled");
+        return (key, result) => record(key, checkVariantLabel(result));
       }
       const attribution = context;
       const capturedPartition = partition;
-      return (key, result) => feature(key, result ? "enabled" : "disabled", 0, attribution, capturedPartition);
+      return (key, result) => feature(key, checkVariantLabel(result), 0, attribution, capturedPartition);
     },
-    recordCheck: (key, result) => feature(key, result ? "enabled" : "disabled", 0),
+    recordCheck: (key, result) => feature(key, checkVariantLabel(result), 0),
     activate() {
       if (disposed || active) return;
       active = true;
@@ -291,7 +319,7 @@ function createBrowserTelemetry(config) {
 
 // src/client/sdk-identity.ts
 var SDK_ID = "react-router";
-var SDK_VERSION = "1.1.0";
+var SDK_VERSION = "1.2.0";
 function appendSdkQueryParams(params) {
   params.set("sdk", SDK_ID);
   params.set("sdkVersion", SDK_VERSION);
@@ -345,6 +373,7 @@ function TogglyProviderOwner({
     claims: { ...mergedConfig?.claims }
   });
   const flagsRef = useRef(serverContext?.flags ?? mergedConfig?.featureDefaults ?? {});
+  const variantsRef = useRef(null);
   const generationRef = useRef(0);
   const updateRevisionRef = useRef(0);
   const [telemetry] = useState(() => createBrowserTelemetry({ ...config, ...contextRef.current }));
@@ -482,6 +511,14 @@ function TogglyProviderOwner({
           throw new Error(`HTTP ${response.status}: ${response.statusText}`);
         }
         const payload = await response.json();
+        if (mergedConfig.enableVariants === true) {
+          const defs = parseVariantDefsPayload(payload);
+          variantsRef.current = defs;
+          const newFlags2 = variantDefsToFlags(defs);
+          logger.debug(`Fetched ${Object.keys(newFlags2).length} flags (variants).`);
+          return newFlags2;
+        }
+        variantsRef.current = null;
         const newFlags = payload && typeof payload === "object" ? payload : {};
         logger.debug(`Fetched ${Object.keys(newFlags).length} flags.`);
         return newFlags;
@@ -541,10 +578,34 @@ function TogglyProviderOwner({
     },
     [captureEvaluation]
   );
+  const getVariant = useCallback(
+    (featureKey) => {
+      if (!mergedConfig?.enableVariants) return null;
+      const entry = variantsRef.current?.[featureKey];
+      const enabled = applyLocalGate(
+        entry?.enabled === true,
+        featureKey,
+        localGatesRef.current,
+        localGateIndexRef.current
+      );
+      const record = telemetry.captureCheck();
+      record(featureKey, enabled && entry?.variant ? entry.variant : "disabled");
+      if (!enabled || !entry?.variant) return null;
+      return { name: entry.variant, configurationValue: entry.configurationValue };
+    },
+    [mergedConfig?.enableVariants, localGatesRevision, telemetry, flags]
+  );
+  const getVariantValue = useCallback(
+    (featureKey, isT) => {
+      return decodeVariantValue(getVariant(featureKey)?.configurationValue, isT);
+    },
+    [getVariant]
+  );
   const installContext = useCallback((target) => {
     contextRef.current = target;
     telemetry.setContext(target);
     flagsRef.current = mergedConfig?.featureDefaults ?? {};
+    variantsRef.current = null;
     setFlags(flagsRef.current);
     setIdentity(target.identity);
   }, [mergedConfig?.featureDefaults, telemetry]);
@@ -815,6 +876,8 @@ function TogglyProviderOwner({
       isDisabled,
       evaluateGate,
       registerContext: registerContext2,
+      getVariant,
+      getVariantValue,
       identify,
       reset,
       refresh,
@@ -833,6 +896,8 @@ function TogglyProviderOwner({
       isDisabled,
       evaluateGate,
       registerContext2,
+      getVariant,
+      getVariantValue,
       identify,
       reset,
       refresh,