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

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;
@@ -304,10 +325,7 @@ var UsageBatcher = class {
   featureCount() {
     return this.perFeature.size;
   }
-  buildAndReset() {
-    if (this.isEmpty()) {
-      return null;
-    }
+  buildPayload() {
     const payload = {
       appKey: this.appKey,
       environment: this.environment,
@@ -317,57 +335,60 @@ var UsageBatcher = class {
       uniqueUserHashes: [...this.appUnique],
       processStartTime: toProtobufTimestamp(this.processStartTime)
     };
-    if (this.instanceName) {
-      payload.instanceName = this.instanceName;
-    }
-    if (this.appVersion) {
-      payload.appVersion = this.appVersion;
-    }
-    if (this.definitionCacheHits > 0) {
-      payload.definitionCacheHits = this.definitionCacheHits;
-    }
-    if (this.definitionCacheMisses > 0) {
-      payload.definitionCacheMisses = this.definitionCacheMisses;
+    if (this.instanceName) payload.instanceName = this.instanceName;
+    if (this.appVersion) payload.appVersion = this.appVersion;
+    if (this.definitionCacheHits > 0) payload.definitionCacheHits = this.definitionCacheHits;
+    if (this.definitionCacheMisses > 0) payload.definitionCacheMisses = this.definitionCacheMisses;
+    return payload;
+  }
+  appendFeatureStat(payload, snapshots, feature, agg) {
+    const variantStats = {};
+    for (const [name, stats] of agg.variantStats) {
+      if (stats.checkCount > 0 || stats.requestCount > 0 || stats.usedCount > 0 || stats.viewedCount > 0) {
+        variantStats[name] = { ...stats };
+      }
     }
-    const uniqueUsersEnabled = {};
-    const uniqueUsersDisabled = {};
-    const uniqueUsersUsed = {};
+    if (agg.uniqueUsersEnabled.size > 0) snapshots.uniqueUsersEnabled[feature] = [...agg.uniqueUsersEnabled];
+    if (agg.uniqueUsersDisabled.size > 0) snapshots.uniqueUsersDisabled[feature] = [...agg.uniqueUsersDisabled];
+    if (agg.uniqueUsersUsed.size > 0) snapshots.uniqueUsersUsed[feature] = [...agg.uniqueUsersUsed];
+    payload.stats.push({
+      feature,
+      uniqueContextIdentifierEnabledCount: agg.uniqueUsersEnabled.size,
+      uniqueContextIdentifierDisabledCount: agg.uniqueUsersDisabled.size,
+      uniqueUsersUsedCount: agg.uniqueUsersUsed.size,
+      uniqueUserHashes: [...agg.uniqueUserHashes],
+      uniqueViewedUserHashes: [...agg.uniqueViewedUserHashes],
+      variantStats
+    });
+  }
+  buildIdentitySnapshots(payload) {
+    const snapshots = {
+      uniqueUsersEnabled: {},
+      uniqueUsersDisabled: {},
+      uniqueUsersUsed: {}
+    };
     for (const [feature, agg] of this.perFeature) {
-      const variantStats = {};
-      for (const [name, stats] of agg.variantStats) {
-        if (stats.checkCount > 0 || stats.requestCount > 0 || stats.usedCount > 0 || stats.viewedCount > 0) {
-          variantStats[name] = { ...stats };
-        }
-      }
-      if (agg.uniqueUsersEnabled.size > 0) {
-        uniqueUsersEnabled[feature] = [...agg.uniqueUsersEnabled];
-      }
-      if (agg.uniqueUsersDisabled.size > 0) {
-        uniqueUsersDisabled[feature] = [...agg.uniqueUsersDisabled];
-      }
-      if (agg.uniqueUsersUsed.size > 0) {
-        uniqueUsersUsed[feature] = [...agg.uniqueUsersUsed];
-      }
-      payload.stats.push({
-        feature,
-        uniqueContextIdentifierEnabledCount: agg.uniqueUsersEnabled.size,
-        uniqueContextIdentifierDisabledCount: agg.uniqueUsersDisabled.size,
-        uniqueUsersUsedCount: agg.uniqueUsersUsed.size,
-        uniqueUserHashes: [...agg.uniqueUserHashes],
-        uniqueViewedUserHashes: [...agg.uniqueViewedUserHashes],
-        variantStats
-      });
+      this.appendFeatureStat(payload, snapshots, feature, agg);
     }
+    return snapshots;
+  }
+  reset() {
     this.perFeature = /* @__PURE__ */ new Map();
     this.appUnique = /* @__PURE__ */ new Set();
     this.droppedFeatures = false;
     this.definitionCacheHits = 0;
     this.definitionCacheMisses = 0;
+  }
+  buildAndReset() {
+    if (this.isEmpty()) {
+      return null;
+    }
+    const payload = this.buildPayload();
+    const snapshots = this.buildIdentitySnapshots(payload);
+    this.reset();
     return {
       payload,
-      uniqueUsersEnabled,
-      uniqueUsersDisabled,
-      uniqueUsersUsed
+      ...snapshots
     };
   }
   restoreFromBundle(bundle) {
@@ -558,7 +579,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.1";
 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.1.0";
+var SDK_VERSION2 = "1.2.1";
 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
    */