@sessionsight/split-testing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SessionSight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @sessionsight/split-testing
+
+Split testing SDK for SessionSight. Framework-agnostic, zero-flicker, server-driven.
+
+## Installation
+
+```bash
+npm install @sessionsight/split-testing
+```
+
+Or use via script tag:
+
+```html
+<script src="https://cdn.sessionsight.com/split-testing.js"></script>
+```
+
+## Quick Start
+
+```typescript
+import SplitTesting from '@sessionsight/split-testing';
+
+await SplitTesting.init({
+  publicApiKey: 'sessionsight_pub_...',
+  propertyId: 'your-property-id',
+});
+
+// ID-based test (component branching)
+const checkout = SplitTesting.get('checkout-flow', 'control');
+if (checkout === 'single-page') {
+  renderSinglePageCheckout();
+} else {
+  renderDefaultCheckout();
+}
+
+// Text test (copy testing)
+const headline = SplitTesting.get('hero-headline', 'Welcome');
+
+// JSON test (structured data)
+const layout = SplitTesting.get('pricing-layout', { columns: 3 });
+
+// Track conversions
+SplitTesting.trackConversion('signup-goal');
+SplitTesting.trackConversion('purchase-goal', { value: 99.99, currency: 'USD' });
+```
+
+## Configuration
+
+```typescript
+await SplitTesting.init({
+  // Required
+  publicApiKey: 'sessionsight_pub_...',
+  propertyId: 'your-property-id',
+
+  // Optional
+  apiUrl: 'https://api.sessionsight.com',  // Custom API URL
+  visitorId: 'user-123',                    // Stable visitor ID (auto-generated if omitted)
+  attributes: { plan: 'pro' },              // Visitor attributes for targeting
+  bootstrap: { 'hero-headline': 1 },        // SSR: pre-resolved assignments
+  antiFlicker: true,                         // Hide [data-ss-split] elements until ready
+  staleTTL: 0,                              // ms before cached config triggers background refresh (default: 0)
+  maxAge: 86400000,                          // ms before cached config is expired (default: 24h)
+  onAssignment: (key, variation) => {},      // Callback when a variation is assigned
+});
+```
+
+## Anti-Flicker
+
+The SDK uses a three-tier approach to prevent content flashing:
+
+1. **localStorage cache**: On repeat visits, cached assignments are used instantly (synchronous, no network call).
+2. **SSR bootstrap**: Pass pre-evaluated assignments from the server. Zero network calls, zero flicker.
+3. **Anti-flicker snippet**: Set `antiFlicker: true` to hide `[data-ss-split]` elements until assignments resolve.
+
+### SSR Bootstrap Example
+
+```typescript
+// Server-side
+import SplitTesting from '@sessionsight/split-testing';
+await SplitTesting.init({ publicApiKey: 'sessionsight_pub_...', propertyId: '...' });
+const bootstrap = SplitTesting.getAssignments();
+
+// Client-side (pass bootstrap from server)
+await SplitTesting.init({
+  publicApiKey: 'sessionsight_pub_...',
+  propertyId: '...',
+  bootstrap,
+});
+```
+
+## API
+
+### `SplitTesting.init(config)`
+
+Initialize the SDK. Fetches test configuration and assigns variations. Returns a Promise that resolves when ready.
+
+### `SplitTesting.get(testKey, defaultValue, options?)`
+
+Get the assigned value for a split test. Returns synchronously after init.
+
+- **ID tests**: Returns the variation key string (e.g., `"control"`, `"variant-a"`)
+- **Text tests**: Returns the variation text string
+- **JSON tests**: Returns the parsed JSON object
+
+Returns `defaultValue` if the test is not found or the visitor is not in the test.
+
+### `SplitTesting.trackConversion(goalId, options?)`
+
+Track a conversion event. The backend automatically attributes it to all relevant split tests the visitor is participating in.
+
+### `SplitTesting.setAttributes(attrs)`
+
+Update visitor attributes for targeting.
+
+### `SplitTesting.getAssignments()`
+
+Get all current assignments as `{ testKey: variationIndex }`. Use this for SSR bootstrap.
+
+### `SplitTesting.refresh()`
+
+Force refresh the test configuration from the server.
+
+### `SplitTesting.clearCache()`
+
+Clear locally cached test assignments and configuration. The next call to `get()` will use fresh data from the server after a `refresh()`.
+
+### `SplitTesting.destroy()`
+
+Clean up the SDK instance and flush pending events.
+
+## Script Tag Usage
+
+```html
+<script src="https://cdn.sessionsight.com/split-testing.js"></script>
+<script>
+  SessionSightSplitTesting.init({
+    publicApiKey: 'sessionsight_pub_...',
+    propertyId: '...',
+  }).then(function() {
+    var headline = SessionSightSplitTesting.get('hero-headline', 'Welcome');
+    document.getElementById('hero').textContent = headline;
+  });
+</script>
+```

package/bunfig.toml

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sessionsight/split-testing",
+  "version": "1.0.0",
+  "description": "A/B and split testing SDK for SessionSight.",
+  "author": "SessionSight",
+  "license": "MIT",
+  "homepage": "https://sessionsight.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SessionSight/sdks.git",
+    "directory": "packages/split-testing"
+  },
+  "bugs": {
+    "url": "https://github.com/SessionSight/sdks/issues"
+  },
+  "keywords": [
+    "ab-testing",
+    "split-testing",
+    "experiments",
+    "sessionsight"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun run build:esm && bun run build:iife",
+    "build:esm": "bun build src/index.ts --outdir dist --format esm && bun x tsc --emitDeclarationOnly --declaration --outDir dist",
+    "build:iife": "bun build src/iife.ts --outfile dist/sessionsight-split-testing.js --format iife --minify"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@sessionsight/sdk-shared": "workspace:*"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,95 @@
+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

@@ -0,0 +1,370 @@
+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

@@ -0,0 +1,44 @@
+/**
+ * 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

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

package/src/index.ts

@@ -0,0 +1,75 @@
+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

@@ -0,0 +1,50 @@
+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;
+}

package/test/client.test.ts

@@ -0,0 +1,224 @@
+import { test, expect, beforeEach, mock } from 'bun:test';
+import {
+  getCachedConfig,
+  setCachedConfig,
+  getCachedAssignments,
+  setCachedAssignments,
+  clearCache,
+} from '../src/cache';
+import { SplitTestingClient } from '../src/client';
+import type { SplitTestConfigResponse, Assignment } from '../src/types';
+
+// Storage map injected by test/setup.ts preload
+const storage: Map<string, string> = (globalThis as any).__testStorage;
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+const PROPERTY = 'prop-1';
+const VISITOR = 'visitor-1';
+
+const fakeConfigResponse: SplitTestConfigResponse = {
+  tests: [
+    {
+      key: 'hero-test',
+      id: 'test-id-1',
+      type: 'text',
+      status: 'running',
+      hashSeed: 'seed-abc',
+      trafficAllocation: 100,
+      variations: [
+        { key: 'control', weight: 50, value: 'Hello' },
+        { key: 'variant-a', weight: 50, value: 'Hey there' },
+      ],
+    },
+  ],
+  ttl: 300,
+};
+
+function makeClient(overrides: Record<string, any> = {}): SplitTestingClient {
+  return new SplitTestingClient({
+    publicApiKey: 'pk_test',
+    propertyId: PROPERTY,
+    apiUrl: 'https://api.test.com',
+    visitorId: VISITOR,
+    ...overrides,
+  });
+}
+
+beforeEach(() => {
+  storage.clear();
+});
+
+// ════════════════════════════════════════════════════════════════════
+//  Cache tests
+// ════════════════════════════════════════════════════════════════════
+
+test('setCachedConfig / getCachedConfig round trip', () => {
+  setCachedConfig(PROPERTY, fakeConfigResponse);
+  const cached = getCachedConfig(PROPERTY);
+  expect(cached).not.toBeNull();
+  expect(cached!.data.tests[0].key).toBe('hero-test');
+  expect(typeof cached!.fetchedAt).toBe('number');
+});
+
+test('getCachedConfig returns null when nothing is stored', () => {
+  expect(getCachedConfig('nonexistent')).toBeNull();
+});
+
+test('setCachedAssignments / getCachedAssignments round trip', () => {
+  const assignments: Record<string, Assignment> = {
+    'hero-test': {
+      testKey: 'hero-test',
+      variationIndex: 1,
+      variationKey: 'variant-a',
+      value: 'Hey there',
+      type: 'text',
+      inTest: true,
+    },
+  };
+  setCachedAssignments(PROPERTY, VISITOR, assignments);
+  const cached = getCachedAssignments(PROPERTY, VISITOR);
+  expect(cached).not.toBeNull();
+  expect(cached!['hero-test'].variationKey).toBe('variant-a');
+});
+
+test('clearCache removes config and assignment entries for the property', () => {
+  setCachedConfig(PROPERTY, fakeConfigResponse);
+  setCachedAssignments(PROPERTY, VISITOR, {
+    'hero-test': {
+      testKey: 'hero-test',
+      variationIndex: 0,
+      variationKey: 'control',
+      value: 'Hello',
+      type: 'text',
+      inTest: true,
+    },
+  });
+  expect(storage.size).toBeGreaterThan(0);
+
+  clearCache(PROPERTY);
+
+  expect(getCachedConfig(PROPERTY)).toBeNull();
+  expect(getCachedAssignments(PROPERTY, VISITOR)).toBeNull();
+});
+
+test('clearCache does not remove entries for a different property', () => {
+  setCachedConfig('prop-other', fakeConfigResponse);
+  setCachedConfig(PROPERTY, fakeConfigResponse);
+
+  clearCache(PROPERTY);
+
+  expect(getCachedConfig(PROPERTY)).toBeNull();
+  expect(getCachedConfig('prop-other')).not.toBeNull();
+});
+
+// ════════════════════════════════════════════════════════════════════
+//  Client tests
+// ════════════════════════════════════════════════════════════════════
+
+test('get() returns default value before init', () => {
+  const client = makeClient();
+  expect(client.get('hero-test', 'fallback')).toBe('fallback');
+});
+
+test('get() returns cached assignment after init with pre-cached config', async () => {
+  // Pre-populate cache so no fetch is needed
+  setCachedConfig(PROPERTY, fakeConfigResponse);
+
+  const client = makeClient({ maxAge: 999_999_999, staleTTL: 999_999_999 });
+  await client.init();
+
+  const value = client.get('hero-test', 'fallback');
+  // Should be one of the variation values, not the fallback
+  expect(['Hello', 'Hey there']).toContain(value);
+});
+
+test('get() fetches config from API when cache is empty', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = mock(async (url: string | URL | Request) => {
+    const urlStr = typeof url === 'string' ? url : url.toString();
+    if (urlStr.includes('/v1/split-testing/config')) {
+      return new Response(JSON.stringify(fakeConfigResponse), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    return new Response('{}', { status: 200 });
+  }) as any;
+
+  try {
+    const client = makeClient();
+    await client.init();
+
+    const value = client.get('hero-test', 'fallback');
+    expect(['Hello', 'Hey there']).toContain(value);
+    // Config should now be cached
+    expect(getCachedConfig(PROPERTY)).not.toBeNull();
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('trackConversion sends POST with correct payload', async () => {
+  const calls: Array<{ url: string; body: any }> = [];
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = mock(async (url: string | URL | Request, init?: RequestInit) => {
+    const urlStr = typeof url === 'string' ? url : url.toString();
+    if (init?.body) {
+      calls.push({ url: urlStr, body: JSON.parse(init.body as string) });
+    }
+    if (urlStr.includes('/v1/split-testing/config')) {
+      return new Response(JSON.stringify(fakeConfigResponse), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    return new Response('{}', { status: 200 });
+  }) as any;
+
+  // Disable sendBeacon so it falls through to fetch
+  const origBeacon = globalThis.navigator.sendBeacon;
+  globalThis.navigator.sendBeacon = (() => false) as any;
+
+  try {
+    const client = makeClient();
+    await client.init();
+
+    client.trackConversion('goal-signup', { value: 42, currency: 'USD' });
+
+    // Find the conversion call
+    const conversionCall = calls.find((c) => c.url.includes('/convert'));
+    expect(conversionCall).toBeDefined();
+    expect(conversionCall!.body.goalId).toBe('goal-signup');
+    expect(conversionCall!.body.propertyId).toBe(PROPERTY);
+    expect(conversionCall!.body.visitorId).toBe(VISITOR);
+    expect(conversionCall!.body.value).toBe(42);
+    expect(conversionCall!.body.currency).toBe('USD');
+  } finally {
+    globalThis.fetch = originalFetch;
+    globalThis.navigator.sendBeacon = origBeacon;
+  }
+});
+
+test('getAssignments returns variation indices keyed by test key', async () => {
+  setCachedConfig(PROPERTY, fakeConfigResponse);
+
+  const client = makeClient({ maxAge: 999_999_999, staleTTL: 999_999_999 });
+  await client.init();
+
+  const assignments = client.getAssignments();
+  expect(assignments).toHaveProperty('hero-test');
+  expect(typeof assignments['hero-test']).toBe('number');
+});
+
+test('destroy clears internal state', async () => {
+  setCachedConfig(PROPERTY, fakeConfigResponse);
+
+  const client = makeClient({ maxAge: 999_999_999, staleTTL: 999_999_999 });
+  await client.init();
+
+  client.destroy();
+
+  // After destroy, get() should return default
+  expect(client.get('hero-test', 'fallback')).toBe('fallback');
+});

package/test/hash.test.ts

@@ -0,0 +1,85 @@
+import { test, expect } from 'bun:test';
+import { splitTestHash, assignVariation } from '../src/hash';
+
+test('splitTestHash returns consistent results', () => {
+  const h1 = splitTestHash('seed-abc', 'visitor-123');
+  const h2 = splitTestHash('seed-abc', 'visitor-123');
+  expect(h1).toBe(h2);
+});
+
+test('splitTestHash returns values in 0-9999', () => {
+  for (let i = 0; i < 100; i++) {
+    const h = splitTestHash(`seed-${i}`, `visitor-${i}`);
+    expect(h).toBeGreaterThanOrEqual(0);
+    expect(h).toBeLessThan(10000);
+  }
+});
+
+test('splitTestHash produces different values for different visitors', () => {
+  const h1 = splitTestHash('seed', 'visitor-1');
+  const h2 = splitTestHash('seed', 'visitor-2');
+  expect(h1).not.toBe(h2);
+});
+
+test('splitTestHash produces different values for different seeds', () => {
+  const h1 = splitTestHash('seed-a', 'visitor');
+  const h2 = splitTestHash('seed-b', 'visitor');
+  expect(h1).not.toBe(h2);
+});
+
+test('assignVariation puts visitor in test when within traffic allocation', () => {
+  const result = assignVariation(500, 100, [
+    { key: 'control', weight: 50 },
+    { key: 'variant-a', weight: 50 },
+  ]);
+  expect(result.inTest).toBe(true);
+});
+
+test('assignVariation excludes visitor when outside traffic allocation', () => {
+  const result = assignVariation(9500, 50, [
+    { key: 'control', weight: 50 },
+    { key: 'variant-a', weight: 50 },
+  ]);
+  expect(result.inTest).toBe(false);
+  expect(result.variationIndex).toBe(0); // defaults to control
+});
+
+test('assignVariation distributes evenly with equal weights', () => {
+  const counts = [0, 0];
+  for (let i = 0; i < 10000; i++) {
+    const result = assignVariation(i, 100, [
+      { key: 'control', weight: 50 },
+      { key: 'variant-a', weight: 50 },
+    ]);
+    counts[result.variationIndex]!++;
+  }
+  // Should be roughly 50/50
+  expect(counts[0]).toBeGreaterThan(4000);
+  expect(counts[0]).toBeLessThan(6000);
+  expect(counts[1]).toBeGreaterThan(4000);
+  expect(counts[1]).toBeLessThan(6000);
+});
+
+test('assignVariation respects unequal weights', () => {
+  const counts = [0, 0, 0];
+  for (let i = 0; i < 10000; i++) {
+    const result = assignVariation(i, 100, [
+      { key: 'control', weight: 70 },
+      { key: 'variant-a', weight: 20 },
+      { key: 'variant-b', weight: 10 },
+    ]);
+    counts[result.variationIndex]!++;
+  }
+  // control ~70%, variant-a ~20%, variant-b ~10%
+  expect(counts[0]).toBeGreaterThan(6000);
+  expect(counts[1]).toBeGreaterThan(1000);
+  expect(counts[2]).toBeGreaterThan(500);
+});
+
+test('assignVariation handles zero traffic allocation', () => {
+  const result = assignVariation(500, 0, [
+    { key: 'control', weight: 50 },
+    { key: 'variant-a', weight: 50 },
+  ]);
+  expect(result.inTest).toBe(false);
+});

package/test/setup.ts

@@ -0,0 +1,21 @@
+// Preload: set up browser globals before any module evaluates canUseStorage
+
+const storage = new Map<string, string>();
+globalThis.localStorage = {
+  getItem: (key: string) => storage.get(key) ?? null,
+  setItem: (key: string, value: string) => { storage.set(key, value); },
+  removeItem: (key: string) => { storage.delete(key); },
+  clear: () => storage.clear(),
+  get length() { return storage.size; },
+  key: (i: number) => [...storage.keys()][i] ?? null,
+} as any;
+
+globalThis.window = globalThis as any;
+globalThis.document = {
+  createElement: () => ({ id: '', textContent: '', remove() {} }),
+  head: { appendChild() {} },
+} as any;
+globalThis.navigator = { sendBeacon: () => true } as any;
+
+// Export storage so tests can access it for clearing
+(globalThis as any).__testStorage = storage;

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true,
+    "noEmit": false,
+    "rootDir": "./src",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  },
+  "include": ["src/**/*.ts"]
+}