feat: enhance feature flag handling with variants and impression data

Author: Starefossen

AGENTS.md

@@ -171,17 +171,30 @@ FeatureFlags.isEnabled(FeatureFlags.QUOTES_SUBMIT)
 
 // Kotlin: error injection flag, default false (opt-in)
 FeatureFlags.isEnabled(FeatureFlags.QUOTES_ERRORS, default = false)
+
+// Kotlin: get variant for A/B testing
+val variant = FeatureFlags.getVariant(FeatureFlags.QUOTES_SUBMIT)
+if (variant.name != "disabled") { /* use variant */ }
 ```
 
 ```typescript
 // TypeScript (server-side API routes): check flag
-import { isEnabled, FEATURE_FLAGS } from '@/utils/unleash';
+import { isEnabled, getVariant, FEATURE_FLAGS } from '@/utils/unleash';
 isEnabled(FEATURE_FLAGS.QUOTES_SUBMIT);
+
+// TypeScript: get variant
+const variant = getVariant(FEATURE_FLAGS.QUOTES_SUBMIT);
 ```
 
+**Impression data:**
+
+- Impression data and usage metrics are sent to Unleash automatically by the SDK
+- Enable impression data per-toggle in the Unleash admin UI — metrics appear in the Unleash "Metrics" tab
+- `GET /api/features` returns `{ "flag": { "enabled": true, "variant": { "name": "..." } } }`
+
 **Rules:**
 
 - Register flag names as constants in `FeatureFlags.kt` / `unleash.ts`
 - Define per-flag defaults (e.g., `quotes.submit` defaults `true`, `quotes.errors` defaults `false`)
-- Use `GET /api/features` (backend or frontend) to inspect flag states
+- Use `GET /api/features` (backend or frontend) to inspect flag states and variants
 - Local Unleash admin UI: `http://localhost:4242` (started via `mise run infra:up`)

quotes-backend/src/main/kotlin/io/nais/quotesbackend/FeatureFlags.kt

@@ -2,7 +2,10 @@ package io.nais.quotesbackend
 
 import io.getunleash.DefaultUnleash
 import io.getunleash.Unleash
+import io.getunleash.event.UnleashReady
+import io.getunleash.event.UnleashSubscriber
 import io.getunleash.util.UnleashConfig
+import io.getunleash.variant.Variant
 import org.slf4j.LoggerFactory
 
 object FeatureFlags {
@@ -21,9 +24,17 @@ object FeatureFlags {
         try {
             val config = UnleashConfig.builder()
                 .appName(appName)
-                .unleashAPI("$apiUrl/")
+                .unleashAPI("$apiUrl/api/")
                 .apiKey(apiToken)
                 .environment(environment)
+                .subscriber(object : UnleashSubscriber {
+                    override fun onReady(ready: UnleashReady) {
+                        log.info("Unleash client ready")
+                    }
+                    override fun onError(unleashException: io.getunleash.UnleashException) {
+                        log.warn("Unleash error: {}", unleashException.message)
+                    }
+                })
                 .build()
 
             unleash = DefaultUnleash(config)
@@ -37,13 +48,34 @@ object FeatureFlags {
         return unleash?.isEnabled(flag, default) ?: default
     }
 
-    fun allFlags(): Map<String, Boolean> {
+    fun getVariant(flag: String): Variant {
+        return unleash?.getVariant(flag) ?: Variant.DISABLED_VARIANT
+    }
+
+    fun allFlags(): Map<String, Any> {
         return mapOf(
-            QUOTES_SUBMIT to isEnabled(QUOTES_SUBMIT),
-            QUOTES_ERRORS to isEnabled(QUOTES_ERRORS, default = false),
+            QUOTES_SUBMIT to flagDetail(QUOTES_SUBMIT),
+            QUOTES_ERRORS to flagDetail(QUOTES_ERRORS, default = false),
         )
     }
 
+    private fun flagDetail(flag: String, default: Boolean = true): Map<String, Any> {
+        val enabled = isEnabled(flag, default)
+        val variant = getVariant(flag)
+        val detail = mutableMapOf<String, Any>("enabled" to enabled)
+        if (variant.name != "disabled") {
+            val variantMap = mutableMapOf<String, Any>(
+                "name" to variant.name,
+                "enabled" to variant.isEnabled
+            )
+            variant.payload.ifPresent { payload ->
+                variantMap["payload"] = mapOf("type" to payload.type, "value" to payload.value)
+            }
+            detail["variant"] = variantMap
+        }
+        return detail
+    }
+
     fun shutdown() {
         unleash?.shutdown()
     }

quotes-frontend/src/__tests__/utils/unleash.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const mockIsEnabled = vi.fn();
+const mockGetVariant = vi.fn();
+const mockOn = vi.fn();
+const mockInitialize = vi.fn(() => ({
+  isEnabled: mockIsEnabled,
+  getVariant: mockGetVariant,
+  on: mockOn,
+}));
+
+vi.mock('unleash-client', () => ({
+  initialize: mockInitialize,
+}));
+
+vi.mock('@/utils/logger', () => ({
+  default: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+describe('unleash', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+    delete process.env.UNLEASH_SERVER_API_URL;
+    delete process.env.UNLEASH_SERVER_API_TOKEN;
+    delete process.env.UNLEASH_SERVER_API_ENVIRONMENT;
+  });
+
+  it('returns default when env vars are missing', async () => {
+    const { isEnabled, FEATURE_FLAGS } = await import('@/utils/unleash');
+    expect(isEnabled(FEATURE_FLAGS.QUOTES_SUBMIT)).toBe(true);
+    expect(isEnabled(FEATURE_FLAGS.QUOTES_ERRORS)).toBe(false);
+    expect(mockInitialize).not.toHaveBeenCalled();
+  });
+
+  it('initializes client and checks flags', async () => {
+    process.env.UNLEASH_SERVER_API_URL = 'http://unleash';
+    process.env.UNLEASH_SERVER_API_TOKEN = 'test-token';
+    mockIsEnabled.mockReturnValue(true);
+
+    const { isEnabled, FEATURE_FLAGS } = await import('@/utils/unleash');
+    const result = isEnabled(FEATURE_FLAGS.QUOTES_SUBMIT);
+
+    expect(mockInitialize).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: 'http://unleash/',
+        appName: 'quotes-frontend',
+      })
+    );
+    expect(result).toBe(true);
+  });
+
+  it('registers lifecycle listeners', async () => {
+    process.env.UNLEASH_SERVER_API_URL = 'http://unleash';
+    process.env.UNLEASH_SERVER_API_TOKEN = 'test-token';
+    mockIsEnabled.mockReturnValue(true);
+
+    const { isEnabled, FEATURE_FLAGS } = await import('@/utils/unleash');
+    isEnabled(FEATURE_FLAGS.QUOTES_SUBMIT);
+
+    const registeredEvents = mockOn.mock.calls.map((call: unknown[]) => call[0]);
+    expect(registeredEvents).not.toContain('impression');
+    expect(registeredEvents).toContain('ready');
+    expect(registeredEvents).toContain('error');
+  });
+
+  it('getVariant returns disabled when no client', async () => {
+    const { getVariant, FEATURE_FLAGS } = await import('@/utils/unleash');
+    const variant = getVariant(FEATURE_FLAGS.QUOTES_SUBMIT);
+    expect(variant).toEqual({ name: 'disabled', enabled: false });
+  });
+
+  it('getVariant delegates to client when initialized', async () => {
+    process.env.UNLEASH_SERVER_API_URL = 'http://unleash';
+    process.env.UNLEASH_SERVER_API_TOKEN = 'test-token';
+    mockGetVariant.mockReturnValue({ name: 'variantA', enabled: true, payload: { type: 'string', value: 'hello' } });
+    mockIsEnabled.mockReturnValue(true);
+
+    const { getVariant, isEnabled, FEATURE_FLAGS } = await import('@/utils/unleash');
+    isEnabled(FEATURE_FLAGS.QUOTES_SUBMIT); // trigger init
+    const variant = getVariant(FEATURE_FLAGS.QUOTES_SUBMIT);
+
+    expect(variant.name).toBe('variantA');
+    expect(variant.enabled).toBe(true);
+  });
+});

quotes-frontend/src/app/api/features/route.ts

@@ -1,12 +1,17 @@
 import { NextResponse } from 'next/server';
-import { isEnabled, FEATURE_FLAGS } from '@/utils/unleash';
+import { isEnabled, getVariant, FEATURE_FLAGS } from '@/utils/unleash';
 
 export async function GET() {
   const features = Object.fromEntries(
-    Object.entries(FEATURE_FLAGS).map(([, flag]) => [
-      flag,
-      isEnabled(flag as (typeof FEATURE_FLAGS)[keyof typeof FEATURE_FLAGS]),
-    ])
+    Object.entries(FEATURE_FLAGS).map(([, flag]) => {
+      const flagKey = flag as (typeof FEATURE_FLAGS)[keyof typeof FEATURE_FLAGS];
+      const variant = getVariant(flagKey);
+      const detail: Record<string, unknown> = { enabled: isEnabled(flagKey) };
+      if (variant.name !== 'disabled') {
+        detail.variant = variant;
+      }
+      return [flag, detail];
+    })
   );
   return NextResponse.json(features);
 }

quotes-frontend/src/app/submit-quote/page.tsx

@@ -14,7 +14,8 @@ export default function SubmitQuote() {
     fetch('/api/features')
       .then((res) => res.json())
       .then((features) => {
-        const enabled = features['quotes.submit'] ?? true;
+        const flag = features['quotes.submit'];
+        const enabled = typeof flag === 'object' ? flag.enabled : (flag ?? true);
         setSubmitEnabled(enabled);
         if (!enabled) setMessage("Submitting new quotes is currently disabled.");
       })

quotes-frontend/src/utils/unleash.ts

@@ -1,4 +1,5 @@
 import { initialize, Unleash } from 'unleash-client';
+import logger from '@/utils/logger';
 
 let unleash: Unleash | null = null;
 
@@ -10,12 +11,20 @@ export function getUnleash(): Unleash | null {
   if (!url || !token) return null;
 
   unleash = initialize({
-    url: `${url}/`,
+    url: `${url}/api/`,
     appName: 'quotes-frontend',
     customHeaders: { Authorization: token },
     environment: process.env.UNLEASH_SERVER_API_ENVIRONMENT || 'development',
   });
 
+  unleash.on('ready', () => {
+    logger.info('Unleash client ready');
+  });
+
+  unleash.on('error', (err: Error) => {
+    logger.warn({ err: err.message }, 'Unleash error');
+  });
+
   return unleash;
 }
 
@@ -39,3 +48,9 @@ export function isEnabled(flag: FeatureFlag, defaultValue?: boolean): boolean {
   if (!client) return effectiveDefault;
   return client.isEnabled(flag, undefined, effectiveDefault);
 }
+
+export function getVariant(flag: FeatureFlag) {
+  const client = getUnleash();
+  if (!client) return { name: 'disabled', enabled: false };
+  return client.getVariant(flag);
+}