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

package/dist/server.d.cts

@@ -62,6 +62,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') */
@@ -96,6 +100,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 */
@@ -152,6 +166,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 */
@@ -171,6 +187,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
  */
@@ -347,12 +370,19 @@ declare class TogglyServerClient {
     private flags;
     /** Raw definitions-signed models keyed by featureKey. */
     private definitions;
+    /** Evaluated-variants-signed defs when `enableVariants`; otherwise null. */
+    private variants;
     private hooks;
     private initialized;
     /** Dedupes concurrent cold-start definition fetches. */
     private definitionsLoadPromise;
     /** Single-flight for definition GET so concurrent joiners are not double-counted. */
     private definitionsFetchInFlight;
+    /**
+     * Serializes variants-mode init so concurrent identities cannot interleave
+     * shared `this.variants` / `this.flags` mutations.
+     */
+    private variantsInitChain;
     private ws;
     private wsConnected;
     private wsReconnectTimer;
@@ -412,24 +442,46 @@ declare class TogglyServerClient {
      */
     get isWsConnected(): boolean;
     /**
-     * Initialize the client by fetching feature definitions.
-     * When already initialized, rebinds identity (including clearing it) and
-     * re-snapshots flags without re-fetching (definitions are identity-agnostic).
-     * Concurrent cold starts share one fetch; each caller still receives a
-     * request-local snapshot for its identity.
+     * Initialize the client and optionally bind identity.
+     * Local mode: concurrent cold starts share one definitions fetch; each caller
+     * still receives a request-local snapshot for its identity.
+     * Variants mode: inits are serialized so concurrent identities cannot
+     * interleave remote variant assignments on the shared client.
      */
     init(identity?: string): Promise<FeatureFlags>;
+    /**
+     * Variants are remote-evaluated; identity must be bound before fetch so
+     * `/evaluated-variants-signed` receives the correct `userId`.
+     */
+    private initWithVariants;
+    private initWithLocalDefinitions;
     /**
      * Fetch feature definitions from the API (definitions-signed; no identity query).
      * Counts one definition-refresh hit/miss per performed attempt; concurrent
      * in-flight joiners await the same fetch and are not counted.
      */
     fetchFlags(identity?: string): Promise<FeatureFlags>;
+    private applyNoAppKeyDefaults;
+    private applyParsedDefinitionsBody;
+    private hasLastKnownGoodDefinitions;
+    private buildDefinitionsFetchUrl;
+    private noteNotModifiedResponse;
+    private noteAppliedDefinitionsRevision;
+    private recoverDefinitionsFetchError;
     private performDefinitionsFetch;
     /**
      * Get all flags
      */
     getFlags(): FeatureFlags;
+    /**
+     * Current variant assignment for a feature (requires `enableVariants`).
+     * Soft-null when disabled, the feature is off/local-gated, or no variant is assigned.
+     */
+    getVariant(featureKey: string): VariantResult | null;
+    /**
+     * Configuration payload for the assigned variant, if any.
+     */
+    getVariantValue<T = unknown>(featureKey: string, isT?: (v: unknown) => v is T): T | null;
     /**
      * Check if a feature is enabled
      */

package/dist/server.d.ts

@@ -62,6 +62,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') */
@@ -96,6 +100,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 */
@@ -152,6 +166,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 */
@@ -171,6 +187,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
  */
@@ -347,12 +370,19 @@ declare class TogglyServerClient {
     private flags;
     /** Raw definitions-signed models keyed by featureKey. */
     private definitions;
+    /** Evaluated-variants-signed defs when `enableVariants`; otherwise null. */
+    private variants;
     private hooks;
     private initialized;
     /** Dedupes concurrent cold-start definition fetches. */
     private definitionsLoadPromise;
     /** Single-flight for definition GET so concurrent joiners are not double-counted. */
     private definitionsFetchInFlight;
+    /**
+     * Serializes variants-mode init so concurrent identities cannot interleave
+     * shared `this.variants` / `this.flags` mutations.
+     */
+    private variantsInitChain;
     private ws;
     private wsConnected;
     private wsReconnectTimer;
@@ -412,24 +442,46 @@ declare class TogglyServerClient {
      */
     get isWsConnected(): boolean;
     /**
-     * Initialize the client by fetching feature definitions.
-     * When already initialized, rebinds identity (including clearing it) and
-     * re-snapshots flags without re-fetching (definitions are identity-agnostic).
-     * Concurrent cold starts share one fetch; each caller still receives a
-     * request-local snapshot for its identity.
+     * Initialize the client and optionally bind identity.
+     * Local mode: concurrent cold starts share one definitions fetch; each caller
+     * still receives a request-local snapshot for its identity.
+     * Variants mode: inits are serialized so concurrent identities cannot
+     * interleave remote variant assignments on the shared client.
      */
     init(identity?: string): Promise<FeatureFlags>;
+    /**
+     * Variants are remote-evaluated; identity must be bound before fetch so
+     * `/evaluated-variants-signed` receives the correct `userId`.
+     */
+    private initWithVariants;
+    private initWithLocalDefinitions;
     /**
      * Fetch feature definitions from the API (definitions-signed; no identity query).
      * Counts one definition-refresh hit/miss per performed attempt; concurrent
      * in-flight joiners await the same fetch and are not counted.
      */
     fetchFlags(identity?: string): Promise<FeatureFlags>;
+    private applyNoAppKeyDefaults;
+    private applyParsedDefinitionsBody;
+    private hasLastKnownGoodDefinitions;
+    private buildDefinitionsFetchUrl;
+    private noteNotModifiedResponse;
+    private noteAppliedDefinitionsRevision;
+    private recoverDefinitionsFetchError;
     private performDefinitionsFetch;
     /**
      * Get all flags
      */
     getFlags(): FeatureFlags;
+    /**
+     * Current variant assignment for a feature (requires `enableVariants`).
+     * Soft-null when disabled, the feature is off/local-gated, or no variant is assigned.
+     */
+    getVariant(featureKey: string): VariantResult | null;
+    /**
+     * Configuration payload for the assigned variant, if any.
+     */
+    getVariantValue<T = unknown>(featureKey: string, isT?: (v: unknown) => v is T): T | null;
     /**
      * Check if a feature is enabled
      */

package/dist/server.js

@@ -1,10 +1,10 @@
 import { normalizeEntityContext, registerContext, appendEvaluationContext } from '@ops-ai/toggly-hooks-types';
 import { fromHttpRequest, snapshotEvaluatedBooleans, parseDefinitionsPayload, evaluateDefinitions } from '@ops-ai/toggly-eval';
 export { fromHttpRequest } from '@ops-ai/toggly-eval';
+import { readResponseBody, parseEvaluatedResponseBody, asVariantDefsRecord, unwrapDefsPayload } from '@ops-ai/toggly-signed-defs';
 import { AsyncLocalStorage } from 'async_hooks';
 import { buildFlagGateIndex, applyLocalGate } from '@ops-ai/toggly-local-gates';
 import WebSocket from 'ws';
-import { readResponseBody, parseEvaluatedResponseBody } from '@ops-ai/toggly-signed-defs';
 import { createRequire } from 'module';
 import fs from 'fs';
 import path from 'path';
@@ -54,28 +54,49 @@ 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();
   }
-  const fromParam = context;
+  const fromParam = typeof context === "string" ? { identity: context } : context;
   appendEvaluationContext(
     url,
     {
       identity: fromParam?.identity,
-      groups: groups,
-      claims: claims
+      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 isFeatureEnabledLocal(defsByKey, featureKey, evalCtx = {}, defaultValue = false) {
   if (!defsByKey || defsByKey.size === 0) {
     return defaultValue;
@@ -558,7 +579,7 @@ var MetricsBatcher = class {
 
 // src/core/sdk-identity.ts
 var SDK_ID = "react-router";
-var SDK_VERSION = "1.0.1";
+var SDK_VERSION = "1.2.0";
 function sdkUserAgent() {
   return `toggly-${SDK_ID}/${SDK_VERSION}`;
 }
@@ -1078,7 +1099,7 @@ async function extractEvalContext(request, providers = {}) {
 
 // src/server/sdk-identity.ts
 var SDK_ID2 = "react-router";
-var SDK_VERSION2 = "1.0.1";
+var SDK_VERSION2 = "1.2.0";
 var SDK_HEADER_ID = "X-Toggly-Sdk";
 var SDK_HEADER_VERSION = "X-Toggly-Sdk-Version";
 function sdkUserAgent2() {
@@ -1370,12 +1391,19 @@ var TogglyServerClient = class {
     this.flags = {};
     /** Raw definitions-signed models keyed by featureKey. */
     this.definitions = /* @__PURE__ */ new Map();
+    /** Evaluated-variants-signed defs when `enableVariants`; otherwise null. */
+    this.variants = null;
     this.hooks = [];
     this.initialized = false;
     /** Dedupes concurrent cold-start definition fetches. */
     this.definitionsLoadPromise = null;
     /** Single-flight for definition GET so concurrent joiners are not double-counted. */
     this.definitionsFetchInFlight = null;
+    /**
+     * Serializes variants-mode init so concurrent identities cannot interleave
+     * shared `this.variants` / `this.flags` mutations.
+     */
+    this.variantsInitChain = Promise.resolve();
     // WebSocket live updates
     this.ws = null;
     this.wsConnected = false;
@@ -1395,7 +1423,7 @@ var TogglyServerClient = class {
       ...config,
       ...telemetryFlags,
       ...grpcClients,
-      evaluationMode: "local",
+      evaluationMode: config.enableVariants ? "remote" : "local",
       telemetryTransport: config.telemetryTransport ?? "grpc",
       telemetryAttachProcessHandlers: config.telemetryAttachProcessHandlers ?? (config.telemetryTransport ?? "grpc") === "grpc"
     });
@@ -1439,12 +1467,12 @@ var TogglyServerClient = class {
     });
     this.telemetry.start();
   }
-  recordCheckForKey(featureKey, enabled, identityOverride) {
+  recordCheckForKey(featureKey, enabled, identityOverride, variant) {
     if (!this.telemetry?.usageEnabled) {
       return;
     }
     const identity = identityOverride?.identity ?? this.identity;
-    this.telemetry.recordCheck(featureKey, enabled, identity);
+    this.telemetry.recordCheck(featureKey, enabled, identity, variant);
   }
   /** Soft-fail wrapper — definition refresh must not throw from telemetry. */
   noteDefinitionCacheHit() {
@@ -1556,6 +1584,9 @@ var TogglyServerClient = class {
    * shared mutable `this.flags` / `this.identity` (safe under concurrency).
    */
   snapshotFlags(identityOverride) {
+    if (this.config.enableVariants) {
+      return { ...this.flags };
+    }
     return {
       ...this.config.featureDefaults ?? {},
       ...snapshotEvaluatedBooleans(
@@ -1565,12 +1596,18 @@ var TogglyServerClient = class {
     };
   }
   getEffectiveFlag(featureKey, defaultValue = false, entityContext, identityOverride) {
-    const evaluated = isFeatureEnabledLocal(
-      this.definitions,
-      featureKey,
-      this.buildEvalContext(identityOverride, entityContext),
-      this.config.featureDefaults?.[featureKey] ?? defaultValue
-    );
+    let evaluated;
+    if (this.config.enableVariants) {
+      const raw = this.flags[featureKey];
+      evaluated = typeof raw === "boolean" ? raw : this.config.featureDefaults?.[featureKey] ?? defaultValue;
+    } else {
+      evaluated = isFeatureEnabledLocal(
+        this.definitions,
+        featureKey,
+        this.buildEvalContext(identityOverride, entityContext),
+        this.config.featureDefaults?.[featureKey] ?? defaultValue
+      );
+    }
     return applyLocalGate(evaluated, featureKey, this.localGates, this.localGateIndex);
   }
   getDefinitionsRevision() {
@@ -1647,13 +1684,56 @@ var TogglyServerClient = class {
     return this.wsConnected;
   }
   /**
-   * Initialize the client by fetching feature definitions.
-   * When already initialized, rebinds identity (including clearing it) and
-   * re-snapshots flags without re-fetching (definitions are identity-agnostic).
-   * Concurrent cold starts share one fetch; each caller still receives a
-   * request-local snapshot for its identity.
+   * Initialize the client and optionally bind identity.
+   * Local mode: concurrent cold starts share one definitions fetch; each caller
+   * still receives a request-local snapshot for its identity.
+   * Variants mode: inits are serialized so concurrent identities cannot
+   * interleave remote variant assignments on the shared client.
    */
   async init(identity) {
+    if (this.config.enableVariants) {
+      return this.initWithVariants(identity);
+    }
+    return this.initWithLocalDefinitions(identity);
+  }
+  /**
+   * Variants are remote-evaluated; identity must be bound before fetch so
+   * `/evaluated-variants-signed` receives the correct `userId`.
+   */
+  async initWithVariants(identity) {
+    const run = async () => {
+      const previousIdentity = this.identity;
+      const wasWarm = this.initialized && this.variants !== null;
+      const identityChanged = previousIdentity !== identity;
+      this.identity = identity;
+      if (!wasWarm || identityChanged) {
+        if (identityChanged && this.definitionsFetchInFlight) {
+          await this.definitionsFetchInFlight.catch(() => void 0);
+        }
+        await this.fetchFlags();
+        this.initialized = true;
+        if (!wasWarm) {
+          this.startWebSocket();
+          if (identity) {
+            await this.executeBeforeIdentify(identity);
+            await this.executeAfterIdentify(identity);
+          }
+        }
+      }
+      this.flags = this.snapshotFlags({ identity });
+      if (wasWarm && !identityChanged) {
+        this.logger.debug("Client already initialized; re-snapshotted for identity.");
+      }
+      return { ...this.flags };
+    };
+    const result = this.variantsInitChain.then(run, run);
+    this.variantsInitChain = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  }
+  async initWithLocalDefinitions(identity) {
     const wasWarm = this.initialized && this.definitions.size > 0;
     if (!wasWarm) {
       if (!this.definitionsLoadPromise) {
@@ -1697,38 +1777,98 @@ var TogglyServerClient = class {
       this.definitionsFetchInFlight = null;
     }
   }
-  async performDefinitionsFetch() {
-    if (!this.config.appKey) {
-      this.logger.debug("No appKey, using featureDefaults.");
+  applyNoAppKeyDefaults() {
+    this.logger.debug("No appKey, using featureDefaults.");
+    this.definitions = /* @__PURE__ */ new Map();
+    this.variants = this.config.enableVariants ? {} : null;
+    this.flags = this.config.featureDefaults ?? {};
+    return this.flags;
+  }
+  applyParsedDefinitionsBody(parsed, useVariants) {
+    if (useVariants) {
+      this.variants = parseVariantDefsPayload(parsed);
       this.definitions = /* @__PURE__ */ new Map();
+      this.flags = {
+        ...this.config.featureDefaults,
+        ...variantDefsToFlags(this.variants)
+      };
+      this.logger.debug(`Fetched ${Object.keys(this.variants).length} variant defs.`);
+      return;
+    }
+    this.variants = null;
+    this.definitions = parseDefinitionsPayload(parsed);
+    this.flags = {
+      ...this.config.featureDefaults,
+      ...snapshotEvaluatedBooleans(this.definitions, this.buildEvalContext())
+    };
+    this.logger.debug(`Fetched ${this.definitions.size} definitions.`);
+  }
+  hasLastKnownGoodDefinitions(useVariants) {
+    if (this.definitions.size > 0) {
+      return true;
+    }
+    return Boolean(useVariants && this.variants && Object.keys(this.variants).length > 0);
+  }
+  buildDefinitionsFetchUrl(useVariants, pin) {
+    const identityContext = useVariants && this.identity ? { identity: this.identity } : void 0;
+    return appendDefinitionsRevisionParam(
+      buildDefinitionsUrl(this.config, identityContext),
+      pin
+    );
+  }
+  noteNotModifiedResponse(responseRevision) {
+    if (responseRevision) {
+      this.cacheDefinitionsRevision(responseRevision);
+    }
+    this.noteDefinitionCacheHit();
+    this.logger.debug("Definitions unchanged (304)");
+    return this.flags;
+  }
+  noteAppliedDefinitionsRevision(previousRevision, responseRevision) {
+    if (responseRevision) {
+      this.cacheDefinitionsRevision(responseRevision);
+    }
+    if (this.definitionsRevisionsMatch(previousRevision, responseRevision)) {
+      this.noteDefinitionCacheHit();
+    } else {
+      this.noteDefinitionCacheMiss();
+    }
+  }
+  recoverDefinitionsFetchError(error, outcomeRecorded, useVariants) {
+    this.logger.warn(
+      "Failed to fetch flags, preserving last-known-good flags when available.",
+      error
+    );
+    this.config.onError?.("Error fetching feature flags", error);
+    if (!outcomeRecorded && this.hasLastKnownGoodDefinitions(useVariants)) {
+      this.noteDefinitionCacheHit();
+    }
+    if (Object.keys(this.flags).length === 0) {
       this.flags = this.config.featureDefaults ?? {};
-      return this.flags;
+    }
+    return this.flags;
+  }
+  async performDefinitionsFetch() {
+    if (!this.config.appKey) {
+      return this.applyNoAppKeyDefaults();
     }
     let outcomeRecorded = false;
+    const useVariants = this.config.enableVariants === true;
     try {
       const pin = this.pendingDefinitionsPin;
       this.pendingDefinitionsPin = null;
-      const url = appendDefinitionsRevisionParam(
-        buildDefinitionsUrl(this.config),
-        pin
-      );
+      const url = this.buildDefinitionsFetchUrl(useVariants, pin);
       this.logger.debug(`Fetching definitions from: ${url}`);
       const previousRevision = pin ? null : this.getDefinitionsRevision();
-      const headers = buildDefinitionFetchHeaders(
-        previousRevision ? { "If-None-Match": previousRevision } : {}
-      );
+      const conditionalHeaders = previousRevision ? { "If-None-Match": previousRevision } : void 0;
+      const headers = buildDefinitionFetchHeaders(conditionalHeaders);
       const response = await fetchWithTimeout(url, { headers }, this.config.timeout);
       const responseRevision = this.normalizeDefinitionsRevision(
         extractDefinitionsRevision(response)
       );
       if (response.status === 304) {
-        if (responseRevision) {
-          this.cacheDefinitionsRevision(responseRevision);
-        }
-        this.noteDefinitionCacheHit();
         outcomeRecorded = true;
-        this.logger.debug("Definitions unchanged (304)");
-        return this.flags;
+        return this.noteNotModifiedResponse(responseRevision);
       }
       if (!response.ok) {
         throw new TogglyNetworkError(
@@ -1741,35 +1881,15 @@ var TogglyServerClient = class {
         baseUrl: this.config.baseUrl ?? "https://definitions.toggly.io",
         allowedKeyIds: this.config.allowedKeyIds,
         maxSignatureAgeSeconds: this.config.maxSignatureAgeSeconds,
-        headers: buildDefinitionFetchHeaders({})
+        headers: buildDefinitionFetchHeaders()
       });
-      this.definitions = parseDefinitionsPayload(parsed);
-      this.flags = {
-        ...this.config.featureDefaults ?? {},
-        ...snapshotEvaluatedBooleans(this.definitions, this.buildEvalContext())
-      };
-      if (responseRevision) {
-        this.cacheDefinitionsRevision(responseRevision);
-      }
-      this.logger.debug(`Fetched ${this.definitions.size} definitions.`);
-      if (this.definitionsRevisionsMatch(previousRevision, responseRevision)) {
-        this.noteDefinitionCacheHit();
-      } else {
-        this.noteDefinitionCacheMiss();
-      }
+      this.applyParsedDefinitionsBody(parsed, useVariants);
+      this.noteAppliedDefinitionsRevision(previousRevision, responseRevision);
       outcomeRecorded = true;
       await this.executeAfterRefresh(this.flags);
       return this.flags;
     } catch (error) {
-      this.logger.warn("Failed to fetch flags, preserving last-known-good flags when available.", error);
-      this.config.onError?.("Error fetching feature flags", error);
-      if (!outcomeRecorded && this.definitions.size > 0) {
-        this.noteDefinitionCacheHit();
-      }
-      if (Object.keys(this.flags).length === 0) {
-        this.flags = this.config.featureDefaults ?? {};
-      }
-      return this.flags;
+      return this.recoverDefinitionsFetchError(error, outcomeRecorded, useVariants);
     }
   }
   /**
@@ -1778,6 +1898,34 @@ var TogglyServerClient = class {
   getFlags() {
     return { ...this.flags };
   }
+  /**
+   * Current variant assignment for a feature (requires `enableVariants`).
+   * Soft-null when disabled, the feature is off/local-gated, or no variant is assigned.
+   */
+  getVariant(featureKey) {
+    if (!this.config.enableVariants) return null;
+    const entry = this.variants?.[featureKey];
+    const enabled = applyLocalGate(
+      entry?.enabled === true,
+      featureKey,
+      this.localGates,
+      this.localGateIndex
+    );
+    this.recordCheckForKey(
+      featureKey,
+      enabled,
+      void 0,
+      enabled && entry?.variant ? entry.variant : "disabled"
+    );
+    if (!enabled || !entry?.variant) return null;
+    return { name: entry.variant, configurationValue: entry.configurationValue };
+  }
+  /**
+   * Configuration payload for the assigned variant, if any.
+   */
+  getVariantValue(featureKey, isT) {
+    return decodeVariantValue(this.getVariant(featureKey)?.configurationValue, isT);
+  }
   /**
    * Check if a feature is enabled
    */