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

package/dist/server.cjs

@@ -2,10 +2,10 @@
 
 var togglyHooksTypes = require('@ops-ai/toggly-hooks-types');
 var togglyEval = require('@ops-ai/toggly-eval');
+var togglySignedDefs = require('@ops-ai/toggly-signed-defs');
 var async_hooks = require('async_hooks');
 var togglyLocalGates = require('@ops-ai/toggly-local-gates');
 var WebSocket = require('ws');
-var togglySignedDefs = require('@ops-ai/toggly-signed-defs');
 var module$1 = require('module');
 var fs = require('fs');
 var path = require('path');
@@ -62,28 +62,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;
   togglyHooksTypes.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 togglySignedDefs.asVariantDefsRecord(togglySignedDefs.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;
@@ -566,7 +587,7 @@ var MetricsBatcher = class {
 
 // src/core/sdk-identity.ts
 var SDK_ID = "react-router";
-var SDK_VERSION = "1.1.0";
+var SDK_VERSION = "1.2.0";
 function sdkUserAgent() {
   return `toggly-${SDK_ID}/${SDK_VERSION}`;
 }
@@ -1086,7 +1107,7 @@ async function extractEvalContext(request, providers = {}) {
 
 // src/server/sdk-identity.ts
 var SDK_ID2 = "react-router";
-var SDK_VERSION2 = "1.1.0";
+var SDK_VERSION2 = "1.2.0";
 var SDK_HEADER_ID = "X-Toggly-Sdk";
 var SDK_HEADER_VERSION = "X-Toggly-Sdk-Version";
 function sdkUserAgent2() {
@@ -1378,12 +1399,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;
@@ -1403,7 +1431,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"
     });
@@ -1447,12 +1475,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() {
@@ -1564,6 +1592,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 ?? {},
       ...togglyEval.snapshotEvaluatedBooleans(
@@ -1573,12 +1604,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 togglyLocalGates.applyLocalGate(evaluated, featureKey, this.localGates, this.localGateIndex);
   }
   getDefinitionsRevision() {
@@ -1655,13 +1692,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) {
@@ -1705,38 +1785,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 = togglyEval.parseDefinitionsPayload(parsed);
+    this.flags = {
+      ...this.config.featureDefaults,
+      ...togglyEval.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(
@@ -1749,35 +1889,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 = togglyEval.parseDefinitionsPayload(parsed);
-      this.flags = {
-        ...this.config.featureDefaults ?? {},
-        ...togglyEval.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);
     }
   }
   /**
@@ -1786,6 +1906,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 = togglyLocalGates.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
    */