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

package/dist/server.d.cts

@@ -100,6 +100,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. */
@@ -179,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
  */
@@ -355,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;
@@ -420,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

@@ -100,6 +100,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. */
@@ -179,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
  */
@@ -355,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;
@@ -420,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
      */