@sessionsight/split-testing 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sessionsight/split-testing",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A/B and split testing SDK for SessionSight.",
   "author": "SessionSight",
   "license": "MIT",
@@ -19,6 +19,9 @@
     "experiments",
     "sessionsight"
   ],
+  "files": [
+    "dist"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/bunfig.toml

@@ -1,2 +0,0 @@
-[test]
-preload = ["./test/setup.ts"]

package/src/cache.ts

@@ -1,95 +0,0 @@
-import type { SplitTestConfigResponse, Assignment } from './types.js';
-
-export { getOrCreateVisitorId } from '@sessionsight/sdk-shared';
-
-const CONFIG_PREFIX = 'ss-split-config:';
-const ASSIGNMENTS_PREFIX = 'ss-split-assignments:';
-
-interface CachedConfig {
-  data: SplitTestConfigResponse;
-  fetchedAt: number;
-}
-
-function hasLocalStorage(): boolean {
-  try {
-    const key = '__ss_test__';
-    localStorage.setItem(key, '1');
-    localStorage.removeItem(key);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-const canUseStorage = typeof window !== 'undefined' && hasLocalStorage();
-
-// ── Config Cache ────────────────────────────────────────────────────
-
-export function getCachedConfig(propertyId: string): CachedConfig | null {
-  if (!canUseStorage) return null;
-  try {
-    const raw = localStorage.getItem(CONFIG_PREFIX + propertyId);
-    if (!raw) return null;
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-export function setCachedConfig(propertyId: string, data: SplitTestConfigResponse): void {
-  if (!canUseStorage) return;
-  try {
-    const cached: CachedConfig = { data, fetchedAt: Date.now() };
-    localStorage.setItem(CONFIG_PREFIX + propertyId, JSON.stringify(cached));
-  } catch {
-    // Storage full or unavailable
-  }
-}
-
-// ── Assignment Cache ────────────────────────────────────────────────
-
-export function getCachedAssignments(propertyId: string, visitorId: string): Record<string, Assignment> | null {
-  if (!canUseStorage) return null;
-  try {
-    const raw = localStorage.getItem(ASSIGNMENTS_PREFIX + propertyId + ':' + visitorId);
-    if (!raw) return null;
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-export function setCachedAssignments(
-  propertyId: string,
-  visitorId: string,
-  assignments: Record<string, Assignment>,
-): void {
-  if (!canUseStorage) return;
-  try {
-    localStorage.setItem(
-      ASSIGNMENTS_PREFIX + propertyId + ':' + visitorId,
-      JSON.stringify(assignments),
-    );
-  } catch {
-    // Storage full or unavailable
-  }
-}
-
-// ── Cleanup ─────────────────────────────────────────────────────────
-
-export function clearCache(propertyId: string): void {
-  if (!canUseStorage) return;
-  try {
-    // Remove all keys with our prefix for this property
-    const keysToRemove: string[] = [];
-    for (let i = 0; i < localStorage.length; i++) {
-      const key = localStorage.key(i);
-      if (key && (key.startsWith(CONFIG_PREFIX + propertyId) || key.startsWith(ASSIGNMENTS_PREFIX + propertyId))) {
-        keysToRemove.push(key);
-      }
-    }
-    keysToRemove.forEach((k) => localStorage.removeItem(k));
-  } catch {
-    // Ignore
-  }
-}

package/src/client.ts

@@ -1,370 +0,0 @@
-import type {
-  SplitTestConfig,
-  SplitTestConfigResponse,
-  SplitTestConfigEntry,
-  Assignment,
-  AssignedVariation,
-  GetOptions,
-} from './types.js';
-import { splitTestHash, assignVariation } from './hash.js';
-import {
-  getOrCreateVisitorId,
-  getCachedConfig,
-  setCachedConfig,
-  getCachedAssignments,
-  setCachedAssignments,
-  clearCache,
-} from './cache.js';
-
-const FETCH_TIMEOUT_MS = 10_000;
-
-function fetchWithTimeout(url: string, options: RequestInit): Promise<Response> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-  return fetch(url, { ...options, signal: controller.signal }).finally(() => clearTimeout(timer));
-}
-
-import { normalizeApiUrl } from '@sessionsight/sdk-shared';
-
-const DEFAULT_STALE_TTL = 0;
-const DEFAULT_MAX_AGE = 86_400_000; // 24 hours
-
-export class SplitTestingClient {
-  private apiUrl: string;
-  private publicApiKey: string;
-  private propertyId: string;
-  private visitorId: string;
-  private attributes: Record<string, string | number | boolean>;
-  private bootstrap: Record<string, number> | null;
-  private antiFlicker: boolean;
-  private staleTTL: number;
-  private maxAge: number;
-  private onAssignment: ((testKey: string, variation: AssignedVariation) => void) | null;
-
-  private config: SplitTestConfigResponse | null = null;
-  private assignments: Record<string, Assignment> = {};
-  private initialized = false;
-  private antiFlickerStyle: HTMLStyleElement | null = null;
-  private flushTimer: ReturnType<typeof setTimeout> | null = null;
-  private pendingExposures: Array<{
-    splitTestKey: string;
-    variationKey: string;
-    visitorId: string;
-    timestamp: number;
-    attributes: Record<string, string | number | boolean>;
-  }> = [];
-
-  constructor(config: SplitTestConfig) {
-    this.publicApiKey = config.publicApiKey;
-    this.propertyId = config.propertyId;
-    this.apiUrl = normalizeApiUrl(config.apiUrl || '');
-    this.visitorId = getOrCreateVisitorId(config.visitorId);
-    this.attributes = config.attributes || {};
-    this.bootstrap = config.bootstrap || null;
-    this.antiFlicker = config.antiFlicker || false;
-    this.staleTTL = config.staleTTL ?? DEFAULT_STALE_TTL;
-    this.maxAge = config.maxAge ?? DEFAULT_MAX_AGE;
-    this.onAssignment = config.onAssignment || null;
-  }
-
-  async init(): Promise<void> {
-    // Step 1: Anti-flicker
-    if (this.antiFlicker && typeof document !== 'undefined') {
-      this.injectAntiFlicker();
-    }
-
-    try {
-      // Step 2: Bootstrap (highest priority, zero-flicker)
-      if (this.bootstrap) {
-        // We still need config to know the test metadata (type, variations)
-        // Try cache first, then fetch
-        const cached = getCachedConfig(this.propertyId);
-        if (cached) {
-          this.config = cached.data;
-          this.evaluateFromBootstrap();
-          this.initialized = true;
-          // Refresh in background
-          this.fetchConfigInBackground();
-          return;
-        }
-        // Must fetch to know test structure
-        await this.fetchConfig();
-        this.evaluateFromBootstrap();
-        this.initialized = true;
-        return;
-      }
-
-      // Step 3: Try cached assignments
-      const cachedAssignments = getCachedAssignments(this.propertyId, this.visitorId);
-      if (cachedAssignments) {
-        this.assignments = cachedAssignments;
-      }
-
-      // Step 4: Check cached config
-      const cachedConfig = getCachedConfig(this.propertyId);
-      const now = Date.now();
-
-      if (cachedConfig) {
-        const age = now - cachedConfig.fetchedAt;
-
-        if (age < this.maxAge) {
-          this.config = cachedConfig.data;
-
-          // Re-evaluate assignments from cached config (to ensure consistency)
-          this.evaluateAssignments();
-          this.initialized = true;
-
-          // If stale, fetch in background
-          if (age >= this.staleTTL) {
-            this.fetchConfigInBackground();
-          }
-          return;
-        }
-      }
-
-      // Step 5: No usable cache. Fetch fresh.
-      await this.fetchConfig();
-      this.evaluateAssignments();
-      this.initialized = true;
-    } finally {
-      this.removeAntiFlicker();
-    }
-  }
-
-  get(testKey: string, defaultValue: any, _options?: GetOptions): any {
-    if (!this.initialized) {
-      console.warn('[SessionSight SplitTesting] Not initialized. Call init() first.');
-      return defaultValue;
-    }
-
-    const assignment = this.assignments[testKey];
-    if (!assignment) return defaultValue;
-
-    // Track exposure (fire-and-forget)
-    if (assignment.inTest) {
-      this.trackExposure(testKey, assignment.variationKey);
-    }
-
-    switch (assignment.type) {
-      case 'id':
-        return assignment.variationKey;
-      case 'text':
-        return assignment.value || defaultValue;
-      case 'json':
-        try {
-          return JSON.parse(assignment.value);
-        } catch {
-          return defaultValue;
-        }
-      default:
-        return defaultValue;
-    }
-  }
-
-  trackConversion(goalId: string, options?: { value?: number; currency?: string }): void {
-    if (!this.initialized) return;
-
-    const body = {
-      propertyId: this.propertyId,
-      visitorId: this.visitorId,
-      goalId,
-      ...(options?.value != null ? { value: options.value } : {}),
-      ...(options?.currency ? { currency: options.currency } : {}),
-    };
-
-    this.sendBeacon(`${this.apiUrl}/v1/split-testing/convert`, body);
-  }
-
-  setAttributes(attrs: Record<string, string | number | boolean>): void {
-    Object.assign(this.attributes, attrs);
-  }
-
-  getAssignments(): Record<string, number> {
-    const result: Record<string, number> = {};
-    for (const [key, assignment] of Object.entries(this.assignments)) {
-      result[key] = assignment.variationIndex;
-    }
-    return result;
-  }
-
-  async refresh(): Promise<void> {
-    await this.fetchConfig();
-    this.evaluateAssignments();
-  }
-
-  clearCache(): void {
-    clearCache(this.propertyId);
-  }
-
-  destroy(): void {
-    if (this.flushTimer) {
-      clearTimeout(this.flushTimer);
-      this.flushTimer = null;
-    }
-    this.flushExposures();
-    this.removeAntiFlicker();
-    this.config = null;
-    this.assignments = {};
-    this.initialized = false;
-    this.pendingExposures = [];
-  }
-
-  // ── Private ─────────────────────────────────────────────────────
-
-  private evaluateFromBootstrap(): void {
-    if (!this.config || !this.bootstrap) return;
-
-    for (const test of this.config.tests) {
-      const variationIndex = this.bootstrap[test.key];
-      if (variationIndex === undefined) continue;
-
-      const variation = test.variations[variationIndex];
-      if (!variation) continue;
-
-      this.assignments[test.key] = {
-        testKey: test.key,
-        variationIndex,
-        variationKey: variation.key,
-        value: variation.value,
-        type: test.type,
-        inTest: true,
-      };
-
-      if (this.onAssignment) {
-        this.onAssignment(test.key, { key: variation.key, value: variation.value });
-      }
-    }
-
-    setCachedAssignments(this.propertyId, this.visitorId, this.assignments);
-  }
-
-  private evaluateAssignments(): void {
-    if (!this.config) return;
-
-    for (const test of this.config.tests) {
-      const hash = splitTestHash(test.hashSeed, this.visitorId);
-      const result = assignVariation(hash, test.trafficAllocation, test.variations);
-      const variation = test.variations[result.variationIndex];
-
-      if (!variation) continue;
-
-      this.assignments[test.key] = {
-        testKey: test.key,
-        variationIndex: result.variationIndex,
-        variationKey: variation.key,
-        value: variation.value,
-        type: test.type,
-        inTest: result.inTest,
-      };
-
-      if (this.onAssignment) {
-        this.onAssignment(test.key, { key: variation.key, value: variation.value });
-      }
-    }
-
-    setCachedAssignments(this.propertyId, this.visitorId, this.assignments);
-  }
-
-  private async fetchConfig(): Promise<void> {
-    try {
-      const url = `${this.apiUrl}/v1/split-testing/config?propertyId=${encodeURIComponent(this.propertyId)}`;
-      const res = await fetchWithTimeout(url, {
-        headers: { 'x-api-key': this.publicApiKey },
-      });
-
-      if (!res.ok) {
-        console.warn(`[SessionSight SplitTesting] Failed to fetch config: ${res.status}`);
-        return;
-      }
-
-      const data = await res.json();
-      if (!data || !Array.isArray(data.tests)) {
-        console.warn('[SessionSight SplitTesting] Invalid config response');
-        return;
-      }
-      this.config = data as SplitTestConfigResponse;
-      setCachedConfig(this.propertyId, data);
-    } catch (err) {
-      console.warn('[SessionSight SplitTesting] Failed to fetch config:', err);
-    }
-  }
-
-  private fetchConfigInBackground(): void {
-    this.fetchConfig().then(() => {
-      if (this.config) {
-        this.evaluateAssignments();
-      }
-    });
-  }
-
-  private trackExposure(testKey: string, variationKey: string): void {
-    // Deduplicate: only track once per test per session
-    if (this.pendingExposures.some((e) => e.splitTestKey === testKey)) return;
-
-    this.pendingExposures.push({
-      splitTestKey: testKey,
-      variationKey,
-      visitorId: this.visitorId,
-      timestamp: Date.now(),
-      attributes: this.attributes,
-    });
-
-    // Flush after a short delay to batch exposures
-    if (this.pendingExposures.length === 1) {
-      this.flushTimer = setTimeout(() => this.flushExposures(), 1000);
-    }
-  }
-
-  private flushExposures(): void {
-    if (this.pendingExposures.length === 0) return;
-
-    const exposures = [...this.pendingExposures];
-    this.pendingExposures = [];
-
-    const body = {
-      propertyId: this.propertyId,
-      exposures,
-    };
-
-    this.sendBeacon(`${this.apiUrl}/v1/split-testing/expose`, body);
-  }
-
-  private sendBeacon(url: string, body: any): void {
-    const json = JSON.stringify(body);
-
-    // Try sendBeacon first (works during page unload)
-    if (typeof navigator !== 'undefined' && navigator.sendBeacon) {
-      const blob = new Blob([json], { type: 'application/json' });
-      if (navigator.sendBeacon(url, blob)) return;
-    }
-
-    // Fallback to fetch with keepalive
-    fetch(url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'x-api-key': this.publicApiKey,
-      },
-      body: json,
-      keepalive: true,
-    }).catch(() => {
-      // Fire-and-forget
-    });
-  }
-
-  private injectAntiFlicker(): void {
-    if (typeof document === 'undefined') return;
-    const style = document.createElement('style');
-    style.id = 'ss-split-anti-flicker';
-    style.textContent = '[data-ss-split]{visibility:hidden!important}';
-    document.head.appendChild(style);
-    this.antiFlickerStyle = style;
-  }
-
-  private removeAntiFlicker(): void {
-    if (this.antiFlickerStyle) {
-      this.antiFlickerStyle.remove();
-      this.antiFlickerStyle = null;
-    }
-  }
-}

package/src/hash.ts

@@ -1,44 +0,0 @@
-/**
- * djb2 hash producing 0-9999 for fine-grained traffic allocation.
- * Same algorithm family as the flag-evaluation service.
- */
-export function splitTestHash(seed: string, visitorId: string): number {
-  const str = `${seed}:${visitorId}`;
-  let hash = 5381;
-  for (let i = 0; i < str.length; i++) {
-    hash = ((hash << 5) + hash + str.charCodeAt(i)) >>> 0;
-  }
-  return hash % 10000;
-}
-
-/**
- * Given a hash bucket, traffic allocation, and variation weights,
- * determine which variation the visitor gets.
- */
-export function assignVariation(
-  hashValue: number,
-  trafficAllocation: number,
-  variations: Array<{ key: string; weight: number }>,
-): { variationIndex: number; inTest: boolean } {
-  // trafficAllocation is 0-100, scale to 0-10000
-  const trafficThreshold = trafficAllocation * 100;
-
-  if (hashValue >= trafficThreshold) {
-    // Outside traffic allocation: gets control (index 0), not tracked
-    return { variationIndex: 0, inTest: false };
-  }
-
-  // Bucket within traffic allocation
-  const totalWeight = variations.reduce((s, v) => s + v.weight, 0);
-  if (totalWeight === 0) return { variationIndex: 0, inTest: true };
-
-  let cumulative = 0;
-  for (let i = 0; i < variations.length; i++) {
-    cumulative += (variations[i]!.weight / totalWeight) * trafficThreshold;
-    if (hashValue < cumulative) {
-      return { variationIndex: i, inTest: true };
-    }
-  }
-
-  return { variationIndex: variations.length - 1, inTest: true };
-}

package/src/iife.ts

@@ -1,2 +0,0 @@
-import SplitTesting from './index.js';
-(window as any).SessionSightSplitTesting = SplitTesting;

package/src/index.ts

@@ -1,75 +0,0 @@
-import { SplitTestingClient } from './client.js';
-import type { SplitTestConfig, GetOptions, AssignedVariation } from './types.js';
-
-export { SplitTestingClient };
-export type { SplitTestConfig, GetOptions, AssignedVariation, Assignment, SplitTestConfigResponse } from './types.js';
-
-let instance: SplitTestingClient | null = null;
-
-const SplitTesting = {
-  async init(config: SplitTestConfig): Promise<void> {
-    if (instance) {
-      console.warn('[SessionSight SplitTesting] Already initialized. Call destroy() first.');
-      return;
-    }
-    instance = new SplitTestingClient(config);
-    await instance.init();
-  },
-
-  get(testKey: string, defaultValue: any, options?: GetOptions): any {
-    if (!instance) {
-      console.warn('[SessionSight SplitTesting] Not initialized. Call init() first.');
-      return defaultValue;
-    }
-    return instance.get(testKey, defaultValue, options);
-  },
-
-  trackConversion(goalId: string, options?: { value?: number; currency?: string }): void {
-    if (!instance) {
-      console.warn('[SessionSight SplitTesting] Not initialized. Call init() first.');
-      return;
-    }
-    instance.trackConversion(goalId, options);
-  },
-
-  setAttributes(attrs: Record<string, string | number | boolean>): void {
-    if (!instance) {
-      console.warn('[SessionSight SplitTesting] Not initialized. Call init() first.');
-      return;
-    }
-    instance.setAttributes(attrs);
-  },
-
-  getAssignments(): Record<string, number> {
-    if (!instance) {
-      console.warn('[SessionSight SplitTesting] Not initialized. Call init() first.');
-      return {};
-    }
-    return instance.getAssignments();
-  },
-
-  async refresh(): Promise<void> {
-    if (!instance) {
-      console.warn('[SessionSight SplitTesting] Not initialized. Call init() first.');
-      return;
-    }
-    await instance.refresh();
-  },
-
-  clearCache(): void {
-    if (!instance) {
-      console.warn('[SessionSight SplitTesting] Not initialized. Call init() first.');
-      return;
-    }
-    instance.clearCache();
-  },
-
-  destroy(): void {
-    if (instance) {
-      instance.destroy();
-      instance = null;
-    }
-  },
-};
-
-export default SplitTesting;

package/src/types.ts

@@ -1,50 +0,0 @@
-export interface SplitTestConfig {
-  publicApiKey: string;
-  propertyId: string;
-  apiUrl?: string;
-  visitorId?: string;
-  attributes?: Record<string, string | number | boolean>;
-  bootstrap?: Record<string, number>;
-  antiFlicker?: boolean;
-  staleTTL?: number;
-  maxAge?: number;
-  onAssignment?: (testKey: string, variation: AssignedVariation) => void;
-}
-
-export interface AssignedVariation {
-  key: string;
-  value: string;
-}
-
-export interface SplitTestConfigEntry {
-  key: string;
-  id: string;
-  type: 'id' | 'text' | 'json';
-  status: string;
-  hashSeed: string;
-  trafficAllocation: number;
-  variations: Array<{
-    key: string;
-    weight: number;
-    value: string;
-  }>;
-}
-
-export interface SplitTestConfigResponse {
-  tests: SplitTestConfigEntry[];
-  ttl: number;
-}
-
-export interface Assignment {
-  testKey: string;
-  variationIndex: number;
-  variationKey: string;
-  value: string;
-  type: 'id' | 'text' | 'json';
-  inTest: boolean;
-}
-
-export interface GetOptions {
-  // Reserved for future use
-  [key: string]: any;
-}