@experiwall/react 0.2.0

package/README.md

@@ -0,0 +1,24 @@
+<p align="center">
+  <img
+    src=".github/experiwall.svg"
+    align="center"
+    width="100"
+    alt="Experiwall React SDK"
+    title="Experiwall React SDK"
+  />
+  <h1 align="center">💙🥽 Experiwall React SDK ⚛️🧪</h1>
+</p>
+
+
+<p align="center">
+  <img
+    src=".github/preview.png"
+    align="center"
+    alt="Experiwall React SDK"
+    title="Experiwall React SDK"
+  />
+</p>
+
+<p align="center">
+  💙 Find what your users love with social experiments 🥽
+</p>

package/dist/index.d.mts

@@ -0,0 +1,120 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface InitResponse {
+    user_seed: number;
+    assignments: Record<string, string>;
+    experiments?: Record<string, {
+        variants: {
+            key: string;
+            weight: number;
+        }[];
+    }>;
+}
+interface FlagRegistration {
+    flag_key: string;
+    variants: string[];
+    assigned_variant: string;
+    user_id?: string;
+    alias_id?: string;
+}
+interface FlagRegistrationResponse {
+    variant: string;
+}
+interface ExperiwallEvent {
+    event_name: string;
+    experiment_key?: string;
+    variant_key?: string;
+    timestamp?: string;
+    properties?: Record<string, unknown>;
+}
+interface ExperiwallConfig {
+    apiKey: string;
+    baseUrl?: string;
+    userId?: string;
+    aliasId?: string;
+    /**
+     * Force specific variants for QA and testing.
+     * Overridden flags skip exposure tracking, server registration,
+     * and bucketing — no experiment data is contaminated.
+     *
+     * ```tsx
+     * <ExperiwallProvider
+     *   apiKey="..."
+     *   overrides={{ "checkout-flow": "new-checkout" }}
+     * >
+     * ```
+     */
+    overrides?: Record<string, string>;
+    /**
+     * Tag events with an environment label so the dashboard can
+     * segment dev traffic from production experiment results.
+     * Defaults to `"production"` if omitted.
+     *
+     * ```tsx
+     * <ExperiwallProvider
+     *   apiKey="..."
+     *   environment={process.env.NODE_ENV === "production" ? "production" : "development"}
+     * >
+     * ```
+     */
+    environment?: string;
+}
+interface UseExperimentOptions {
+    /**
+     * Force this hook to return a specific variant.
+     * Takes precedence over provider-level overrides.
+     * Skips exposure tracking and server registration.
+     */
+    force?: string;
+}
+
+interface ExperiwallContextValue {
+    userSeed: number | null;
+    assignments: Record<string, string>;
+    experiments: InitResponse["experiments"];
+    overrides: Record<string, string>;
+    isLoading: boolean;
+    error: Error | null;
+    trackEvent: (event: ExperiwallEvent) => void;
+    registerLocalFlag: (flagKey: string, variants: string[], assignedVariant: string) => void;
+    providerConfig: ExperiwallConfig;
+}
+declare function ExperiwallProvider({ children, ...config }: ExperiwallConfig & {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Access the Experiwall SDK context.
+ * Must be used within an <ExperiwallProvider>.
+ */
+declare function useExperiwall(): ExperiwallContextValue;
+
+/**
+ * Get the assigned variant for an experiment flag.
+ *
+ * - Returns the variant string synchronously if the flag is known
+ *   (either from /init or a previous call).
+ * - Returns `null` only during the initial /init fetch.
+ * - For unknown flags, buckets locally (sync) and registers with
+ *   the server async.
+ * - Automatically tracks a `$exposure` event once per mount.
+ *
+ * Forced variants (via `options.force` or provider-level `overrides`)
+ * bypass exposure tracking, server registration, and bucketing
+ * entirely — no experiment data is contaminated.
+ */
+declare function useExperiment(flagKey: string, variants: string[], options?: UseExperimentOptions): string | null;
+
+/**
+ * Returns a `track` function for sending custom events.
+ *
+ * Usage:
+ * ```tsx
+ * const track = useTrack();
+ * track('purchase', { revenue: 9.99 });
+ * ```
+ */
+declare function useTrack(): (eventName: string, properties?: Record<string, unknown>) => void;
+
+export { type ExperiwallConfig, type ExperiwallContextValue, type ExperiwallEvent, ExperiwallProvider, type FlagRegistration, type FlagRegistrationResponse, type InitResponse, type UseExperimentOptions, useExperiment, useExperiwall, useTrack };

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface InitResponse {
+    user_seed: number;
+    assignments: Record<string, string>;
+    experiments?: Record<string, {
+        variants: {
+            key: string;
+            weight: number;
+        }[];
+    }>;
+}
+interface FlagRegistration {
+    flag_key: string;
+    variants: string[];
+    assigned_variant: string;
+    user_id?: string;
+    alias_id?: string;
+}
+interface FlagRegistrationResponse {
+    variant: string;
+}
+interface ExperiwallEvent {
+    event_name: string;
+    experiment_key?: string;
+    variant_key?: string;
+    timestamp?: string;
+    properties?: Record<string, unknown>;
+}
+interface ExperiwallConfig {
+    apiKey: string;
+    baseUrl?: string;
+    userId?: string;
+    aliasId?: string;
+    /**
+     * Force specific variants for QA and testing.
+     * Overridden flags skip exposure tracking, server registration,
+     * and bucketing — no experiment data is contaminated.
+     *
+     * ```tsx
+     * <ExperiwallProvider
+     *   apiKey="..."
+     *   overrides={{ "checkout-flow": "new-checkout" }}
+     * >
+     * ```
+     */
+    overrides?: Record<string, string>;
+    /**
+     * Tag events with an environment label so the dashboard can
+     * segment dev traffic from production experiment results.
+     * Defaults to `"production"` if omitted.
+     *
+     * ```tsx
+     * <ExperiwallProvider
+     *   apiKey="..."
+     *   environment={process.env.NODE_ENV === "production" ? "production" : "development"}
+     * >
+     * ```
+     */
+    environment?: string;
+}
+interface UseExperimentOptions {
+    /**
+     * Force this hook to return a specific variant.
+     * Takes precedence over provider-level overrides.
+     * Skips exposure tracking and server registration.
+     */
+    force?: string;
+}
+
+interface ExperiwallContextValue {
+    userSeed: number | null;
+    assignments: Record<string, string>;
+    experiments: InitResponse["experiments"];
+    overrides: Record<string, string>;
+    isLoading: boolean;
+    error: Error | null;
+    trackEvent: (event: ExperiwallEvent) => void;
+    registerLocalFlag: (flagKey: string, variants: string[], assignedVariant: string) => void;
+    providerConfig: ExperiwallConfig;
+}
+declare function ExperiwallProvider({ children, ...config }: ExperiwallConfig & {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Access the Experiwall SDK context.
+ * Must be used within an <ExperiwallProvider>.
+ */
+declare function useExperiwall(): ExperiwallContextValue;
+
+/**
+ * Get the assigned variant for an experiment flag.
+ *
+ * - Returns the variant string synchronously if the flag is known
+ *   (either from /init or a previous call).
+ * - Returns `null` only during the initial /init fetch.
+ * - For unknown flags, buckets locally (sync) and registers with
+ *   the server async.
+ * - Automatically tracks a `$exposure` event once per mount.
+ *
+ * Forced variants (via `options.force` or provider-level `overrides`)
+ * bypass exposure tracking, server registration, and bucketing
+ * entirely — no experiment data is contaminated.
+ */
+declare function useExperiment(flagKey: string, variants: string[], options?: UseExperimentOptions): string | null;
+
+/**
+ * Returns a `track` function for sending custom events.
+ *
+ * Usage:
+ * ```tsx
+ * const track = useTrack();
+ * track('purchase', { revenue: 9.99 });
+ * ```
+ */
+declare function useTrack(): (eventName: string, properties?: Record<string, unknown>) => void;
+
+export { type ExperiwallConfig, type ExperiwallContextValue, type ExperiwallEvent, ExperiwallProvider, type FlagRegistration, type FlagRegistrationResponse, type InitResponse, type UseExperimentOptions, useExperiment, useExperiwall, useTrack };

package/dist/index.js

@@ -0,0 +1,418 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ExperiwallProvider: () => ExperiwallProvider,
+  useExperiment: () => useExperiment,
+  useExperiwall: () => useExperiwall,
+  useTrack: () => useTrack
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/provider.tsx
+var import_react = require("react");
+
+// src/lib/api-client.ts
+var DEFAULT_BASE_URL = "https://experiwall.com";
+async function fetchInit(apiKey, options) {
+  const base = options?.baseUrl ?? DEFAULT_BASE_URL;
+  const url = new URL("/api/sdk/init", base);
+  if (options?.userId) url.searchParams.set("user_id", options.userId);
+  if (options?.aliasId) url.searchParams.set("alias_id", options.aliasId);
+  if (options?.environment) url.searchParams.set("environment", options.environment);
+  const res = await fetch(url.toString(), {
+    headers: { "x-api-key": apiKey }
+  });
+  if (!res.ok) {
+    throw new Error(`Experiwall API error: ${res.status}`);
+  }
+  return res.json();
+}
+async function registerFlag(apiKey, registration, options) {
+  const base = options?.baseUrl ?? DEFAULT_BASE_URL;
+  const url = new URL("/api/sdk/flags", base);
+  const res = await fetch(url.toString(), {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ ...registration, environment: options?.environment })
+  });
+  if (!res.ok) {
+    throw new Error(`Experiwall API error: ${res.status}`);
+  }
+  return res.json();
+}
+async function sendEvents(apiKey, events, options) {
+  const base = options?.baseUrl ?? DEFAULT_BASE_URL;
+  const url = new URL("/api/sdk/events", base);
+  const res = await fetch(url.toString(), {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      events,
+      user_id: options?.userId,
+      alias_id: options?.aliasId,
+      environment: options?.environment
+    }),
+    keepalive: options?.keepalive
+  });
+  if (!res.ok) {
+    const err = new Error(`Experiwall API error: ${res.status}`);
+    err.status = res.status;
+    throw err;
+  }
+}
+
+// src/lib/event-batcher.ts
+var FLUSH_INTERVAL_MS = 3e4;
+var MAX_QUEUE_SIZE = 1e3;
+var MAX_BACKOFF_MS = 6e4;
+var EventBatcher = class {
+  constructor(opts) {
+    this.queue = [];
+    this.timer = null;
+    this.backoffMs = 0;
+    this.backoffTimer = null;
+    this.flushing = false;
+    this.apiKey = opts.apiKey;
+    this.baseUrl = opts.baseUrl;
+    this.userId = opts.userId;
+    this.aliasId = opts.aliasId;
+    this.environment = opts.environment;
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      if (this.backoffMs > 0) return;
+      this.flush();
+    }, FLUSH_INTERVAL_MS);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.backoffTimer) {
+      clearTimeout(this.backoffTimer);
+      this.backoffTimer = null;
+    }
+    this.flush(true);
+  }
+  push(event) {
+    if (this.queue.length >= MAX_QUEUE_SIZE) {
+      this.queue.shift();
+    }
+    this.queue.push({
+      ...event,
+      timestamp: event.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  async flush(keepalive = false) {
+    if (this.flushing || this.queue.length === 0) return;
+    this.flushing = true;
+    const batch = this.queue.splice(0);
+    try {
+      await sendEvents(this.apiKey, batch, {
+        baseUrl: this.baseUrl,
+        userId: this.userId,
+        aliasId: this.aliasId,
+        keepalive,
+        environment: this.environment
+      });
+      this.backoffMs = 0;
+    } catch (err) {
+      this.queue.unshift(...batch);
+      if (this.queue.length > MAX_QUEUE_SIZE) {
+        this.queue.splice(0, this.queue.length - MAX_QUEUE_SIZE);
+      }
+      const status = err.status;
+      if (status === 429) {
+        this.backoffMs = Math.min(
+          this.backoffMs === 0 ? 1e3 : this.backoffMs * 2,
+          MAX_BACKOFF_MS
+        );
+        this.backoffTimer = setTimeout(() => {
+          this.backoffTimer = null;
+          this.flush();
+        }, this.backoffMs);
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+};
+
+// src/lib/cache.ts
+var TTL_MS = 5 * 60 * 1e3;
+function getCached(key) {
+  try {
+    const raw = localStorage.getItem(key);
+    if (!raw) return null;
+    const entry = JSON.parse(raw);
+    if (Date.now() - entry.timestamp > TTL_MS) {
+      localStorage.removeItem(key);
+      return null;
+    }
+    return entry.data;
+  } catch {
+    return null;
+  }
+}
+function setCache(key, data) {
+  try {
+    const entry = { data, timestamp: Date.now() };
+    localStorage.setItem(key, JSON.stringify(entry));
+  } catch {
+  }
+}
+
+// src/provider.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function getCacheKey(userId, aliasId, environment) {
+  const identity = userId || aliasId || "anon";
+  const env = environment || "production";
+  return `experiwall_init_${identity}_${env}`;
+}
+var ExperiwallContext = (0, import_react.createContext)(
+  null
+);
+function ExperiwallProvider({
+  children,
+  ...config
+}) {
+  const [userSeed, setUserSeed] = (0, import_react.useState)(null);
+  const [assignments, setAssignments] = (0, import_react.useState)({});
+  const [experiments, setExperiments] = (0, import_react.useState)();
+  const [isLoading, setIsLoading] = (0, import_react.useState)(true);
+  const [error, setError] = (0, import_react.useState)(null);
+  const batcherRef = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    let cancelled = false;
+    const load = async () => {
+      setIsLoading(true);
+      setError(null);
+      const cacheKey = getCacheKey(config.userId, config.aliasId, config.environment);
+      const cached = getCached(cacheKey);
+      if (cached) {
+        setUserSeed(cached.user_seed);
+        setAssignments(cached.assignments);
+        setExperiments(cached.experiments);
+        setIsLoading(false);
+        return;
+      }
+      try {
+        const environment = config.environment ?? "production";
+        const data = await fetchInit(config.apiKey, {
+          baseUrl: config.baseUrl,
+          userId: config.userId,
+          aliasId: config.aliasId,
+          environment
+        });
+        if (!cancelled) {
+          setUserSeed(data.user_seed);
+          setAssignments(data.assignments);
+          setExperiments(data.experiments);
+          setCache(cacheKey, data);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(
+            err instanceof Error ? err : new Error("Failed to fetch init")
+          );
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    };
+    load();
+    const batcher = new EventBatcher({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+      userId: config.userId,
+      aliasId: config.aliasId,
+      environment: config.environment ?? "production"
+    });
+    batcher.start();
+    batcherRef.current = batcher;
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === "hidden") {
+        batcher.flush(true);
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    const handleBeforeUnload = () => batcher.flush(true);
+    window.addEventListener("beforeunload", handleBeforeUnload);
+    return () => {
+      cancelled = true;
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      window.removeEventListener("beforeunload", handleBeforeUnload);
+      batcher.stop();
+    };
+  }, [config.apiKey, config.userId, config.aliasId, config.environment]);
+  const trackEvent = (0, import_react.useCallback)((event) => {
+    batcherRef.current?.push(event);
+  }, []);
+  const registerLocalFlag = (0, import_react.useCallback)(
+    (flagKey, variants, assignedVariant) => {
+      setAssignments((prev) => ({ ...prev, [flagKey]: assignedVariant }));
+      registerFlag(
+        config.apiKey,
+        {
+          flag_key: flagKey,
+          variants,
+          assigned_variant: assignedVariant,
+          user_id: config.userId,
+          alias_id: config.aliasId
+        },
+        { baseUrl: config.baseUrl, environment: config.environment ?? "production" }
+      ).catch(() => {
+      });
+    },
+    [config.apiKey, config.baseUrl, config.userId, config.aliasId, config.environment]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    ExperiwallContext.Provider,
+    {
+      value: {
+        userSeed,
+        assignments,
+        experiments,
+        overrides: config.overrides ?? {},
+        isLoading,
+        error,
+        trackEvent,
+        registerLocalFlag,
+        providerConfig: config
+      },
+      children
+    }
+  );
+}
+
+// src/hooks/use-experiwall.ts
+var import_react2 = require("react");
+function useExperiwall() {
+  const ctx = (0, import_react2.useContext)(ExperiwallContext);
+  if (!ctx) {
+    throw new Error("useExperiwall must be used within <ExperiwallProvider>");
+  }
+  return ctx;
+}
+
+// src/hooks/use-experiment.ts
+var import_react3 = require("react");
+
+// src/lib/bucketing.ts
+function bucketLocally(variants, userSeed, weights) {
+  if (variants.length === 0) return null;
+  const count = variants.length;
+  if (weights && weights.length === count) {
+    let cumulative2 = 0;
+    for (let i = 0; i < count; i++) {
+      cumulative2 += weights[i];
+      if (userSeed < cumulative2) {
+        return variants[i];
+      }
+    }
+    return null;
+  }
+  const baseWeight = Math.floor(100 / count);
+  let cumulative = 0;
+  for (let i = 0; i < count; i++) {
+    const weight = i === count - 1 ? 100 - baseWeight * (count - 1) : baseWeight;
+    cumulative += weight;
+    if (userSeed < cumulative) {
+      return variants[i];
+    }
+  }
+  return null;
+}
+
+// src/hooks/use-experiment.ts
+function useExperiment(flagKey, variants, options) {
+  const {
+    userSeed,
+    assignments,
+    experiments,
+    overrides,
+    trackEvent,
+    registerLocalFlag
+  } = useExperiwall();
+  const exposureTrackedRef = (0, import_react3.useRef)(false);
+  const registeredRef = (0, import_react3.useRef)(false);
+  const forced = options?.force ?? overrides[flagKey];
+  const isOverridden = forced !== void 0;
+  let variant = null;
+  if (isOverridden) {
+    variant = forced;
+  } else if (assignments[flagKey]) {
+    variant = assignments[flagKey];
+  } else if (userSeed !== null) {
+    const expData = experiments?.[flagKey];
+    const weights = expData?.variants.map((v) => v.weight);
+    variant = bucketLocally(variants, userSeed, weights);
+    if (variant && !registeredRef.current) {
+      registeredRef.current = true;
+      registerLocalFlag(flagKey, variants, variant);
+    }
+  }
+  (0, import_react3.useEffect)(() => {
+    if (isOverridden) return;
+    if (variant && !exposureTrackedRef.current) {
+      exposureTrackedRef.current = true;
+      trackEvent({
+        event_name: "$exposure",
+        experiment_key: flagKey,
+        variant_key: variant
+      });
+    }
+  }, [variant, flagKey, trackEvent, isOverridden]);
+  return variant;
+}
+
+// src/hooks/use-track.ts
+var import_react4 = require("react");
+function useTrack() {
+  const { trackEvent } = useExperiwall();
+  return (0, import_react4.useCallback)(
+    (eventName, properties) => {
+      trackEvent({
+        event_name: eventName,
+        properties
+      });
+    },
+    [trackEvent]
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExperiwallProvider,
+  useExperiment,
+  useExperiwall,
+  useTrack
+});

package/dist/index.mjs

@@ -0,0 +1,394 @@
+// src/provider.tsx
+import {
+  createContext,
+  useCallback,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+
+// src/lib/api-client.ts
+var DEFAULT_BASE_URL = "https://experiwall.com";
+async function fetchInit(apiKey, options) {
+  const base = options?.baseUrl ?? DEFAULT_BASE_URL;
+  const url = new URL("/api/sdk/init", base);
+  if (options?.userId) url.searchParams.set("user_id", options.userId);
+  if (options?.aliasId) url.searchParams.set("alias_id", options.aliasId);
+  if (options?.environment) url.searchParams.set("environment", options.environment);
+  const res = await fetch(url.toString(), {
+    headers: { "x-api-key": apiKey }
+  });
+  if (!res.ok) {
+    throw new Error(`Experiwall API error: ${res.status}`);
+  }
+  return res.json();
+}
+async function registerFlag(apiKey, registration, options) {
+  const base = options?.baseUrl ?? DEFAULT_BASE_URL;
+  const url = new URL("/api/sdk/flags", base);
+  const res = await fetch(url.toString(), {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ ...registration, environment: options?.environment })
+  });
+  if (!res.ok) {
+    throw new Error(`Experiwall API error: ${res.status}`);
+  }
+  return res.json();
+}
+async function sendEvents(apiKey, events, options) {
+  const base = options?.baseUrl ?? DEFAULT_BASE_URL;
+  const url = new URL("/api/sdk/events", base);
+  const res = await fetch(url.toString(), {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      events,
+      user_id: options?.userId,
+      alias_id: options?.aliasId,
+      environment: options?.environment
+    }),
+    keepalive: options?.keepalive
+  });
+  if (!res.ok) {
+    const err = new Error(`Experiwall API error: ${res.status}`);
+    err.status = res.status;
+    throw err;
+  }
+}
+
+// src/lib/event-batcher.ts
+var FLUSH_INTERVAL_MS = 3e4;
+var MAX_QUEUE_SIZE = 1e3;
+var MAX_BACKOFF_MS = 6e4;
+var EventBatcher = class {
+  constructor(opts) {
+    this.queue = [];
+    this.timer = null;
+    this.backoffMs = 0;
+    this.backoffTimer = null;
+    this.flushing = false;
+    this.apiKey = opts.apiKey;
+    this.baseUrl = opts.baseUrl;
+    this.userId = opts.userId;
+    this.aliasId = opts.aliasId;
+    this.environment = opts.environment;
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      if (this.backoffMs > 0) return;
+      this.flush();
+    }, FLUSH_INTERVAL_MS);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.backoffTimer) {
+      clearTimeout(this.backoffTimer);
+      this.backoffTimer = null;
+    }
+    this.flush(true);
+  }
+  push(event) {
+    if (this.queue.length >= MAX_QUEUE_SIZE) {
+      this.queue.shift();
+    }
+    this.queue.push({
+      ...event,
+      timestamp: event.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  async flush(keepalive = false) {
+    if (this.flushing || this.queue.length === 0) return;
+    this.flushing = true;
+    const batch = this.queue.splice(0);
+    try {
+      await sendEvents(this.apiKey, batch, {
+        baseUrl: this.baseUrl,
+        userId: this.userId,
+        aliasId: this.aliasId,
+        keepalive,
+        environment: this.environment
+      });
+      this.backoffMs = 0;
+    } catch (err) {
+      this.queue.unshift(...batch);
+      if (this.queue.length > MAX_QUEUE_SIZE) {
+        this.queue.splice(0, this.queue.length - MAX_QUEUE_SIZE);
+      }
+      const status = err.status;
+      if (status === 429) {
+        this.backoffMs = Math.min(
+          this.backoffMs === 0 ? 1e3 : this.backoffMs * 2,
+          MAX_BACKOFF_MS
+        );
+        this.backoffTimer = setTimeout(() => {
+          this.backoffTimer = null;
+          this.flush();
+        }, this.backoffMs);
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+};
+
+// src/lib/cache.ts
+var TTL_MS = 5 * 60 * 1e3;
+function getCached(key) {
+  try {
+    const raw = localStorage.getItem(key);
+    if (!raw) return null;
+    const entry = JSON.parse(raw);
+    if (Date.now() - entry.timestamp > TTL_MS) {
+      localStorage.removeItem(key);
+      return null;
+    }
+    return entry.data;
+  } catch {
+    return null;
+  }
+}
+function setCache(key, data) {
+  try {
+    const entry = { data, timestamp: Date.now() };
+    localStorage.setItem(key, JSON.stringify(entry));
+  } catch {
+  }
+}
+
+// src/provider.tsx
+import { jsx } from "react/jsx-runtime";
+function getCacheKey(userId, aliasId, environment) {
+  const identity = userId || aliasId || "anon";
+  const env = environment || "production";
+  return `experiwall_init_${identity}_${env}`;
+}
+var ExperiwallContext = createContext(
+  null
+);
+function ExperiwallProvider({
+  children,
+  ...config
+}) {
+  const [userSeed, setUserSeed] = useState(null);
+  const [assignments, setAssignments] = useState({});
+  const [experiments, setExperiments] = useState();
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const batcherRef = useRef(null);
+  useEffect(() => {
+    let cancelled = false;
+    const load = async () => {
+      setIsLoading(true);
+      setError(null);
+      const cacheKey = getCacheKey(config.userId, config.aliasId, config.environment);
+      const cached = getCached(cacheKey);
+      if (cached) {
+        setUserSeed(cached.user_seed);
+        setAssignments(cached.assignments);
+        setExperiments(cached.experiments);
+        setIsLoading(false);
+        return;
+      }
+      try {
+        const environment = config.environment ?? "production";
+        const data = await fetchInit(config.apiKey, {
+          baseUrl: config.baseUrl,
+          userId: config.userId,
+          aliasId: config.aliasId,
+          environment
+        });
+        if (!cancelled) {
+          setUserSeed(data.user_seed);
+          setAssignments(data.assignments);
+          setExperiments(data.experiments);
+          setCache(cacheKey, data);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(
+            err instanceof Error ? err : new Error("Failed to fetch init")
+          );
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    };
+    load();
+    const batcher = new EventBatcher({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+      userId: config.userId,
+      aliasId: config.aliasId,
+      environment: config.environment ?? "production"
+    });
+    batcher.start();
+    batcherRef.current = batcher;
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === "hidden") {
+        batcher.flush(true);
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    const handleBeforeUnload = () => batcher.flush(true);
+    window.addEventListener("beforeunload", handleBeforeUnload);
+    return () => {
+      cancelled = true;
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      window.removeEventListener("beforeunload", handleBeforeUnload);
+      batcher.stop();
+    };
+  }, [config.apiKey, config.userId, config.aliasId, config.environment]);
+  const trackEvent = useCallback((event) => {
+    batcherRef.current?.push(event);
+  }, []);
+  const registerLocalFlag = useCallback(
+    (flagKey, variants, assignedVariant) => {
+      setAssignments((prev) => ({ ...prev, [flagKey]: assignedVariant }));
+      registerFlag(
+        config.apiKey,
+        {
+          flag_key: flagKey,
+          variants,
+          assigned_variant: assignedVariant,
+          user_id: config.userId,
+          alias_id: config.aliasId
+        },
+        { baseUrl: config.baseUrl, environment: config.environment ?? "production" }
+      ).catch(() => {
+      });
+    },
+    [config.apiKey, config.baseUrl, config.userId, config.aliasId, config.environment]
+  );
+  return /* @__PURE__ */ jsx(
+    ExperiwallContext.Provider,
+    {
+      value: {
+        userSeed,
+        assignments,
+        experiments,
+        overrides: config.overrides ?? {},
+        isLoading,
+        error,
+        trackEvent,
+        registerLocalFlag,
+        providerConfig: config
+      },
+      children
+    }
+  );
+}
+
+// src/hooks/use-experiwall.ts
+import { useContext } from "react";
+function useExperiwall() {
+  const ctx = useContext(ExperiwallContext);
+  if (!ctx) {
+    throw new Error("useExperiwall must be used within <ExperiwallProvider>");
+  }
+  return ctx;
+}
+
+// src/hooks/use-experiment.ts
+import { useEffect as useEffect2, useRef as useRef2 } from "react";
+
+// src/lib/bucketing.ts
+function bucketLocally(variants, userSeed, weights) {
+  if (variants.length === 0) return null;
+  const count = variants.length;
+  if (weights && weights.length === count) {
+    let cumulative2 = 0;
+    for (let i = 0; i < count; i++) {
+      cumulative2 += weights[i];
+      if (userSeed < cumulative2) {
+        return variants[i];
+      }
+    }
+    return null;
+  }
+  const baseWeight = Math.floor(100 / count);
+  let cumulative = 0;
+  for (let i = 0; i < count; i++) {
+    const weight = i === count - 1 ? 100 - baseWeight * (count - 1) : baseWeight;
+    cumulative += weight;
+    if (userSeed < cumulative) {
+      return variants[i];
+    }
+  }
+  return null;
+}
+
+// src/hooks/use-experiment.ts
+function useExperiment(flagKey, variants, options) {
+  const {
+    userSeed,
+    assignments,
+    experiments,
+    overrides,
+    trackEvent,
+    registerLocalFlag
+  } = useExperiwall();
+  const exposureTrackedRef = useRef2(false);
+  const registeredRef = useRef2(false);
+  const forced = options?.force ?? overrides[flagKey];
+  const isOverridden = forced !== void 0;
+  let variant = null;
+  if (isOverridden) {
+    variant = forced;
+  } else if (assignments[flagKey]) {
+    variant = assignments[flagKey];
+  } else if (userSeed !== null) {
+    const expData = experiments?.[flagKey];
+    const weights = expData?.variants.map((v) => v.weight);
+    variant = bucketLocally(variants, userSeed, weights);
+    if (variant && !registeredRef.current) {
+      registeredRef.current = true;
+      registerLocalFlag(flagKey, variants, variant);
+    }
+  }
+  useEffect2(() => {
+    if (isOverridden) return;
+    if (variant && !exposureTrackedRef.current) {
+      exposureTrackedRef.current = true;
+      trackEvent({
+        event_name: "$exposure",
+        experiment_key: flagKey,
+        variant_key: variant
+      });
+    }
+  }, [variant, flagKey, trackEvent, isOverridden]);
+  return variant;
+}
+
+// src/hooks/use-track.ts
+import { useCallback as useCallback2 } from "react";
+function useTrack() {
+  const { trackEvent } = useExperiwall();
+  return useCallback2(
+    (eventName, properties) => {
+      trackEvent({
+        event_name: eventName,
+        properties
+      });
+    },
+    [trackEvent]
+  );
+}
+export {
+  ExperiwallProvider,
+  useExperiment,
+  useExperiwall,
+  useTrack
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@experiwall/react",
+  "version": "0.2.0",
+  "description": "Experiwall React SDK — code-first experimentation and A/B testing",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "experiwall",
+    "ui-experimentation",
+    "a-b-testing",
+    "remote-ui",
+    "screen-builder",
+    "react"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marcelo-earth/experiwall-react"
+  }
+}