flowgrid-sdk 1.2.1 → 1.3.0

package/dist/lib/features/core/experiment.d.ts

@@ -38,7 +38,8 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { DateRangeFilter, TimeSeriesData } from "../../types";
+import { TimeSeriesData } from "../../types";
+import { ServerCookieReader } from "../../utils/identity";
 /**
  * Configuration for tracking an experiment-related event.
  *
@@ -65,14 +66,19 @@ export interface ExperimentDefinition {
     name: string;
     /** Optional description of experiment purpose */
     description?: string;
-    /** Variants participating in the experiment */
+    /**
+     * Variants participating in the experiment.
+     *
+     * Shape matches the verify endpoint and the client-side engine:
+     * `{ id, weight }` (with optional human-readable `name`).
+     */
     variants: Array<{
         /** Unique identifier for the variant */
-        variantId: string;
-        /** Human-readable variant name */
-        name: string;
+        id: string;
         /** Traffic allocation weight (relative distribution) */
         weight: number;
+        /** Optional human-readable variant name */
+        name?: string;
     }>;
     /**
      * Optional audience configuration.
@@ -339,6 +345,18 @@ export declare class Experiment extends FlowGridTransport {
     private experiments;
     /** Local variant assignments: { [experiment_id]: variant_id } */
     private assignments;
+    /**
+     * Decode the cookie’s URL-encoded JSON payload into an assignment map.
+     * Returns `{}` on any parse failure so a stale cookie never throws.
+     */
+    private parseAssignmentCookie;
+    private readAssignmentCookie;
+    /**
+     * Persist `this.assignments` to a first-party cookie so SSR requests on
+     * subsequent navigations see the same variant. Best-effort — no-op in
+     * non-browser contexts or when document.cookie is unavailable.
+     */
+    private writeAssignmentCookie;
     private loadAssignments;
     private saveAssignments;
     /**
@@ -351,6 +369,34 @@ export declare class Experiment extends FlowGridTransport {
      * Returns all current assignments (for SSR hydration).
      */
     getAssignments(): Record<string, string>;
+    /**
+     * Hydrate assignments from a server-side cookie reader
+     * (Next.js `cookies()`, Nuxt `useCookie()`, Hono ctx, etc.).
+     *
+     * @example
+     * ```ts
+     * import { cookies } from "next/headers";
+     * fg.experiments.client.hydrateFromCookies(cookies());
+     * const variant = fg.experiments.variant("checkout_v2");
+     * ```
+     */
+    hydrateFromCookies(reader: ServerCookieReader): void;
+    /**
+     * Hydrate assignments from a raw `Cookie` request header string.
+     * Useful for runtimes without a structured cookie reader (Workers, Bun, etc.).
+     */
+    hydrateFromCookieHeader(cookieHeader: string | null | undefined): void;
+    /**
+     * Serialise current assignments as a `Set-Cookie` header value.
+     * Use server-side after a server-only assignment so the response can
+     * seed the visitor’s browser with the same variant.
+     */
+    serializeAssignmentCookie(): string;
+    /**
+     * Clear all locally cached assignments (cookie + localStorage + memory).
+     * Useful for logout flows or test resets.
+     */
+    clearAssignments(): void;
     private static readonly ANON_ID_KEY;
     /**
      * Returns a stable anonymous ID. Generates a UUID on first call and
@@ -389,10 +435,8 @@ export declare class Experiment extends FlowGridTransport {
      */
     trackLocalConversion(experimentId: string, metricName?: string, metricValue?: number): Promise<void>;
     /**
-     * @deprecated Use `assign()`, `trackExposure()`, or `trackConversion()` instead.
-     * The generic `track()` method sends events without a subtype, which the
-     * backend handler rejects. It is retained only for backwards compatibility
-     * and will be removed in a future major version.
+     * @deprecated Prefer `assign()`, `trackExposure()`, or `trackConversion()`.
+     * Retained as a write-only compatibility shim for generic experiment events.
      */
     track(config: ExperimentConfig): Promise<ExperimentResponse>;
     /**
@@ -411,17 +455,5 @@ export declare class Experiment extends FlowGridTransport {
      * Records that a user was exposed to a variant.
      */
     trackExposure(experimentId: string, userId: string, variantId: string): Promise<ExperimentResponse>;
-    /**
-     * Retrieves statistical results for an experiment.
-     */
-    getResults(experimentId: string): Promise<ExperimentResultsData>;
-    /**
-     * Gets experiment analytics overview.
-     */
-    getAnalytics(filter?: DateRangeFilter): Promise<ExperimentAnalyticsData>;
-    /**
-     * Retrieves the variant assigned to a user for a specific experiment (server-side).
-     */
-    getVariant(experimentId: string, userId: string): Promise<VariantResponse | null>;
 }
 export default Experiment;

package/dist/lib/features/core/experiment.js

@@ -0,0 +1,554 @@
+/**
+ * @fileoverview Core - A/B Testing & Experiments
+ * @module features/core/experiment
+ *
+ * @description
+ * Track A/B tests, experiments, and variant assignments
+ * to measure impact and optimize product decisions.
+ *
+ * @useCases
+ * - Run A/B tests on features
+ * - Track variant assignments
+ * - Measure experiment impact
+ * - Statistical significance analysis
+ * - Multi-variant testing
+ *
+ * @metrics
+ * - Conversion by variant
+ * - Statistical significance
+ * - Sample size per variant
+ * - Experiment duration
+ * - Impact on key metrics
+ *
+ * @chartData
+ * - Bar chart: Conversion by variant
+ * - Line chart: Metric trends by variant
+ * - Table: Experiment results summary
+ * - Confidence interval visualization
+ *
+ * @example
+ * ```typescript
+ * const experiment = new Experiment(webId, endpoint, apiKey);
+ *
+ * await experiment.track({
+ *   eventName: 'checkout_flow_test',
+ *   variant: 'simplified_v2',
+ *   properties: { userId: 'user_123' }
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+import { getCookie } from "../../utils/storage";
+// ============================================================================
+// HASHING UTILITY (FNV-1a)
+// ============================================================================
+/**
+ * FNV-1a 32-bit hash — lightweight deterministic hash for variant assignment.
+ * Ensures the same user always gets the same variant regardless of device.
+ */
+function fnv1a(input) {
+    let hash = 0x811c9dc5; // FNV offset basis
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = (hash * 0x01000193) >>> 0; // FNV prime, unsigned 32-bit
+    }
+    return hash;
+}
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const ASSIGNMENT_STORAGE_KEY = 'fg_exp_assignments';
+const ASSIGNMENT_COOKIE_KEY = 'fg_exp_assignments';
+const ASSIGNMENT_COOKIE_MAX_AGE_DAYS = 365;
+// ============================================================================
+// EXPERIMENT CLASS
+// ============================================================================
+/**
+ * Experiment - A/B Testing & Experimentation SDK
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides structured experiment lifecycle management including:
+ * - Experiment definition
+ * - Deterministic or server-based variant assignment
+ * - Exposure tracking
+ * - Conversion tracking
+ * - Statistical results & analysis
+ *
+ * This class enforces correct HTTP semantics:
+ *
+ * Exposure and conversion events are strictly POST to preserve:
+ * - Statistical validity
+ * - Unique participant counting
+ * - Accurate conversion attribution
+ * - Idempotent replay safety
+ *
+ * @lifecycle
+ * 1. Define experiment
+ * 2. Assign user to variant
+ * 3. Track exposure (when user actually sees variant)
+ * 4. Track conversions (primary/secondary metrics)
+ * 5. Query results & statistical analysis
+ *
+ * @statistical_model
+ * - Variant-level sample sizes tracked independently
+ * - Conversion rates calculated per variant
+ * - Confidence intervals computed server-side
+ * - Statistical significance evaluated against control
+ *
+ * @guarantees
+ * - Assignment is explicitly recorded
+ * - Exposure tracking is immutable
+ * - Conversion events are attributable to assigned variant
+ * - Results queries never mutate experiment state
+ *
+ * @example
+ * ```typescript
+ * const experiment = new Experiment(webId, endpoint, apiKey);
+ *
+ * // 1. Define experiment
+ * await experiment.define({
+ *   experimentId: 'checkout_v2',
+ *   name: 'Simplified Checkout',
+ *   variants: [
+ *     { variantId: 'control', name: 'Current', weight: 50 },
+ *     { variantId: 'treatment', name: 'Simplified', weight: 50 }
+ *   ],
+ *   primaryMetric: 'checkout_completed'
+ * });
+ *
+ * // 2. Assign user
+ * await experiment.assign({
+ *   experimentId: 'checkout_v2',
+ *   userId: 'user_123',
+ *   variantId: 'treatment'
+ * });
+ *
+ * // 3. Track exposure
+ * await experiment.trackExposure('checkout_v2', 'user_123', 'treatment');
+ *
+ * // 4. Track conversion
+ * await experiment.trackConversion({
+ *   experimentId: 'checkout_v2',
+ *   userId: 'user_123',
+ *   variantId: 'treatment',
+ *   metricName: 'checkout_completed',
+ *   value: 1
+ * });
+ *
+ * // 5. Fetch results
+ * const results = await experiment.getResults('checkout_v2');
+ * ```
+ */
+export class Experiment extends FlowGridTransport {
+    constructor() {
+        // ---------------------------------------------------------------------------
+        // CLIENT-SIDE EXPERIMENT ENGINE STATE
+        // ---------------------------------------------------------------------------
+        super(...arguments);
+        /** Verified experiment configs: { [experiment_id]: { variants, properties, verified } } */
+        this.experiments = {};
+        /** Local variant assignments: { [experiment_id]: variant_id } */
+        this.assignments = {};
+    }
+    // ---------------------------------------------------------------------------
+    // CLIENT-SIDE ENGINE — SSR-safe persistence (localStorage + cookie mirror)
+    // ---------------------------------------------------------------------------
+    /**
+     * Decode the cookie’s URL-encoded JSON payload into an assignment map.
+     * Returns `{}` on any parse failure so a stale cookie never throws.
+     */
+    parseAssignmentCookie(raw) {
+        if (!raw)
+            return {};
+        try {
+            const decoded = decodeURIComponent(raw);
+            const parsed = JSON.parse(decoded);
+            return parsed && typeof parsed === 'object' ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    readAssignmentCookie() {
+        return this.parseAssignmentCookie(getCookie(ASSIGNMENT_COOKIE_KEY));
+    }
+    /**
+     * Persist `this.assignments` to a first-party cookie so SSR requests on
+     * subsequent navigations see the same variant. Best-effort — no-op in
+     * non-browser contexts or when document.cookie is unavailable.
+     */
+    writeAssignmentCookie() {
+        try {
+            if (typeof document === 'undefined')
+                return;
+            const value = encodeURIComponent(JSON.stringify(this.assignments));
+            const maxAge = ASSIGNMENT_COOKIE_MAX_AGE_DAYS * 24 * 60 * 60;
+            const sameSite = 'Lax';
+            const secure = typeof location !== 'undefined' && location.protocol === 'https:'
+                ? '; Secure'
+                : '';
+            document.cookie = `${ASSIGNMENT_COOKIE_KEY}=${value}; Path=/; Max-Age=${maxAge}; SameSite=${sameSite}${secure}`;
+        }
+        catch { /* SSR or restricted env */ }
+    }
+    loadAssignments() {
+        // 1. localStorage — authoritative on the client
+        try {
+            if (typeof localStorage !== 'undefined') {
+                const stored = localStorage.getItem(ASSIGNMENT_STORAGE_KEY);
+                if (stored) {
+                    const parsed = JSON.parse(stored);
+                    if (parsed && typeof parsed === 'object')
+                        return parsed;
+                }
+            }
+        }
+        catch { /* SSR or privacy mode */ }
+        // 2. Cookie fallback — lets SSR + first-paint resolve a variant
+        const cookieAssignments = this.readAssignmentCookie();
+        if (Object.keys(cookieAssignments).length > 0)
+            return cookieAssignments;
+        return {};
+    }
+    saveAssignments() {
+        try {
+            if (typeof localStorage !== 'undefined') {
+                localStorage.setItem(ASSIGNMENT_STORAGE_KEY, JSON.stringify(this.assignments));
+            }
+        }
+        catch { /* SSR or privacy mode */ }
+        // Mirror to cookie so the next SSR request can hydrate without flashing.
+        this.writeAssignmentCookie();
+    }
+    /**
+     * Inject assignments from server context (SSR/Node).
+     * Use this when assignments were resolved server-side and need to be
+     * available before localStorage is accessible.
+     */
+    injectAssignments(assignments) {
+        this.assignments = { ...this.assignments, ...assignments };
+    }
+    /**
+     * Returns all current assignments (for SSR hydration).
+     */
+    getAssignments() {
+        return { ...this.assignments };
+    }
+    /**
+     * Hydrate assignments from a server-side cookie reader
+     * (Next.js `cookies()`, Nuxt `useCookie()`, Hono ctx, etc.).
+     *
+     * @example
+     * ```ts
+     * import { cookies } from "next/headers";
+     * fg.experiments.client.hydrateFromCookies(cookies());
+     * const variant = fg.experiments.variant("checkout_v2");
+     * ```
+     */
+    hydrateFromCookies(reader) {
+        const raw = reader.get(ASSIGNMENT_COOKIE_KEY);
+        const value = typeof raw === 'string' ? raw : raw?.value ?? null;
+        const parsed = this.parseAssignmentCookie(value ?? null);
+        if (Object.keys(parsed).length > 0)
+            this.injectAssignments(parsed);
+    }
+    /**
+     * Hydrate assignments from a raw `Cookie` request header string.
+     * Useful for runtimes without a structured cookie reader (Workers, Bun, etc.).
+     */
+    hydrateFromCookieHeader(cookieHeader) {
+        if (!cookieHeader)
+            return;
+        const parts = cookieHeader.split(/;\s*/);
+        const prefix = `${ASSIGNMENT_COOKIE_KEY}=`;
+        const match = parts.find(p => p.startsWith(prefix));
+        if (!match)
+            return;
+        const parsed = this.parseAssignmentCookie(match.slice(prefix.length));
+        if (Object.keys(parsed).length > 0)
+            this.injectAssignments(parsed);
+    }
+    /**
+     * Serialise current assignments as a `Set-Cookie` header value.
+     * Use server-side after a server-only assignment so the response can
+     * seed the visitor’s browser with the same variant.
+     */
+    serializeAssignmentCookie() {
+        const value = encodeURIComponent(JSON.stringify(this.assignments));
+        const maxAge = ASSIGNMENT_COOKIE_MAX_AGE_DAYS * 24 * 60 * 60;
+        return `${ASSIGNMENT_COOKIE_KEY}=${value}; Path=/; Max-Age=${maxAge}; SameSite=Lax`;
+    }
+    /**
+     * Clear all locally cached assignments (cookie + localStorage + memory).
+     * Useful for logout flows or test resets.
+     */
+    clearAssignments() {
+        this.assignments = {};
+        try {
+            if (typeof localStorage !== 'undefined')
+                localStorage.removeItem(ASSIGNMENT_STORAGE_KEY);
+        }
+        catch { /* noop */ }
+        try {
+            if (typeof document !== 'undefined') {
+                document.cookie = `${ASSIGNMENT_COOKIE_KEY}=; Path=/; Max-Age=0; SameSite=Lax`;
+            }
+        }
+        catch { /* noop */ }
+    }
+    /**
+     * Returns a stable anonymous ID. Generates a UUID on first call and
+     * persists it in localStorage so the same anonymous visitor always
+     * receives a consistent variant assignment.
+     */
+    getOrCreateAnonId() {
+        try {
+            if (typeof localStorage !== 'undefined') {
+                const existing = localStorage.getItem(Experiment.ANON_ID_KEY);
+                if (existing)
+                    return existing;
+                const id = typeof crypto !== 'undefined' && crypto.randomUUID
+                    ? crypto.randomUUID()
+                    : 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+                        const r = (Math.random() * 16) | 0;
+                        return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+                    });
+                localStorage.setItem(Experiment.ANON_ID_KEY, id);
+                return id;
+            }
+        }
+        catch { /* SSR or privacy mode */ }
+        // Non-browser fallback — still deterministic within process lifetime
+        return 'anon_' + fnv1a(String(Math.random())).toString(36);
+    }
+    // ---------------------------------------------------------------------------
+    // CLIENT-SIDE ENGINE — deterministic hash-based assignment
+    // ---------------------------------------------------------------------------
+    /**
+     * Deterministic variant assignment using FNV-1a hash.
+     * Same userId + experimentId always produces the same variant.
+     */
+    deterministicAssign(userId, experimentId, variants) {
+        const hashValue = fnv1a(userId + experimentId);
+        let totalWeight = 0;
+        for (const v of variants)
+            totalWeight += v.weight;
+        const bucket = (hashValue % 10000) / 10000 * totalWeight;
+        let cumulative = 0;
+        for (const v of variants) {
+            cumulative += v.weight;
+            if (bucket < cumulative)
+                return v.id;
+        }
+        return variants[variants.length - 1].id;
+    }
+    assignVariant(experimentId, variants) {
+        // Reload from localStorage to handle cross-tab race conditions
+        this.assignments = this.loadAssignments();
+        const existing = this.assignments[experimentId];
+        if (existing && variants.some(v => v.id === existing)) {
+            // Existing assignment still valid — keep it
+            return;
+        }
+        // Resolve a userId for the hash: prefer identityManager's visitorId, then fall back
+        const userId = this.identityManager?.getVisitorId?.()
+            || this.visitorId
+            || this.getOrCreateAnonId();
+        // Deterministic assignment via hash
+        const assignedVariantId = this.deterministicAssign(userId, experimentId, variants);
+        this.assignments[experimentId] = assignedVariantId;
+        this.saveAssignments();
+        // Fire-and-forget assignment event.
+        // The backend AssignmentHandlerNode requires `userId` in properties.
+        this.init('experiment_assignment', {
+            type: 'experiment',
+            subtype: 'assignment',
+            experimentId,
+            userId,
+            variantId: assignedVariantId,
+            source: 'random',
+            assignmentSource: 'sdk_init',
+            timestamp: new Date().toISOString(),
+        }).catch(() => { });
+    }
+    // ---------------------------------------------------------------------------
+    // CLIENT-SIDE ENGINE — server verification
+    // ---------------------------------------------------------------------------
+    async verifyExperiments(configs) {
+        const payload = {
+            web_id: this.webId,
+            experiments: configs.map(exp => ({
+                experiment_id: exp.id,
+                variants: exp.variants,
+                properties: exp.properties || {},
+            })),
+        };
+        try {
+            const res = await fetch(`${this.endpoint}/api/v1/experiments/verify`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+            });
+            const response = await res.json();
+            if (response.ok && Array.isArray(response.data)) {
+                for (const item of response.data) {
+                    if (item.action !== 'error') {
+                        this.experiments[item.experiment_id] = {
+                            variants: item.variants,
+                            properties: item.properties ?? {},
+                            verified: true,
+                        };
+                        this.assignVariant(item.experiment_id, item.variants);
+                    }
+                }
+            }
+        }
+        catch {
+            // Network failure — fall back to local config
+            for (const exp of configs) {
+                this.experiments[exp.id] = {
+                    variants: exp.variants,
+                    properties: exp.properties || {},
+                    verified: false,
+                };
+                this.assignVariant(exp.id, exp.variants);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // CLIENT-SIDE ENGINE — public init
+    // ---------------------------------------------------------------------------
+    /**
+     * Initialise the client-side experiment engine.
+     *
+     * Verifies experiment configs against the API, assigns variants using
+     * weighted random allocation, and persists assignments in localStorage
+     * under `fg_exp_assignments`.
+     *
+     * @param experiments - Array of experiment configs to register
+     */
+    async initExperiments(experiments) {
+        this.assignments = this.loadAssignments();
+        if (experiments.length > 0) {
+            await this.verifyExperiments(experiments);
+        }
+    }
+    /**
+     * Returns the locally assigned variant for an experiment.
+     *
+     * Reads from the in-memory assignment map (backed by localStorage).
+     * Returns `null` if no assignment exists.
+     */
+    getLocalVariant(experimentId) {
+        // Re-read from storage to stay in sync with other tabs
+        this.assignments = this.loadAssignments();
+        return this.assignments[experimentId] ?? null;
+    }
+    /**
+     * Track a conversion against the locally assigned variant.
+     *
+     * No-op if the visitor has no assignment for this experiment.
+     */
+    async trackLocalConversion(experimentId, metricName = 'conversion', metricValue = 1) {
+        const variantId = this.getLocalVariant(experimentId);
+        if (!variantId)
+            return;
+        // Backend ConversionHandlerNode requires `userId` — resolve from
+        // identity manager or the persisted anonymous ID.
+        const userId = this.identityManager?.getVisitorId?.()
+            || this.visitorId
+            || this.getOrCreateAnonId();
+        await this.init('experiment_conversion', {
+            type: 'experiment',
+            subtype: 'conversion',
+            experimentId,
+            userId,
+            variantId,
+            metricName,
+            value: metricValue,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // SERVER-SIDE EXPERIMENT METHODS
+    //
+    // Backend supports write events only: definition, assignment, conversion,
+    // exposure, plus the deprecated generic custom shim below. Read endpoints
+    // (results / analytics / variant lookup) are not exposed via the SDK
+    // functions router.
+    // ---------------------------------------------------------------------------
+    /**
+     * @deprecated Prefer `assign()`, `trackExposure()`, or `trackConversion()`.
+     * Retained as a write-only compatibility shim for generic experiment events.
+     */
+    async track(config) {
+        return await this.init(config.eventName, {
+            ...config.properties,
+            type: "experiment",
+            subtype: "custom",
+            variant: config.variant,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Defines a new experiment.
+     */
+    async define(definition) {
+        return await this.init("experiment_definition", {
+            type: "experiment",
+            subtype: "definition",
+            ...definition,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Assigns a user to a variant.
+     */
+    async assign(config) {
+        return await this.init("experiment_assignment", {
+            type: "experiment",
+            subtype: "assignment",
+            experimentId: config.experimentId,
+            userId: config.userId,
+            variantId: config.variantId,
+            source: config.source || "random",
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Records a conversion event for an experiment.
+     */
+    async trackConversion(config) {
+        return await this.init("experiment_conversion", {
+            type: "experiment",
+            subtype: "conversion",
+            experimentId: config.experimentId,
+            userId: config.userId,
+            variantId: config.variantId,
+            metricName: config.metricName,
+            value: config.value,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Records that a user was exposed to a variant.
+     */
+    async trackExposure(experimentId, userId, variantId) {
+        return await this.init("experiment_exposure", {
+            type: "experiment",
+            subtype: "exposure",
+            experimentId,
+            userId,
+            variantId,
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// CLIENT-SIDE ENGINE — stable anonymous ID
+// ---------------------------------------------------------------------------
+Experiment.ANON_ID_KEY = 'fg_anon_id';
+export default Experiment;
+//# sourceMappingURL=experiment.js.map