@experiwall/react 0.2.0 → 0.3.0

package/README.md

@@ -6,10 +6,9 @@
     alt="Experiwall React SDK"
     title="Experiwall React SDK"
   />
-  <h1 align="center">💙🥽 Experiwall React SDK ⚛️🧪</h1>
+  <h1 align="center">Experiwall React SDK</h1>
 </p>
 
-
 <p align="center">
   <img
     src=".github/preview.png"
@@ -20,5 +19,164 @@
 </p>
 
 <p align="center">
-  💙 Find what your users love with social experiments 🥽
+  Code-first A/B testing for React. Define experiments inline, track conversions, and let the dashboard show you what wins.
 </p>
+
+---
+
+## Install
+
+```bash
+npm install @experiwall/react
+```
+
+## Quick start
+
+### 1. Wrap your app with the provider
+
+```tsx
+import { ExperiwallProvider } from "@experiwall/react";
+
+export default function App() {
+  return (
+    <ExperiwallProvider
+      apiKey="your-api-key"
+      userId={currentUser.id}
+      environment={process.env.NODE_ENV === "production" ? "production" : "development"}
+    >
+      <YourApp />
+    </ExperiwallProvider>
+  );
+}
+```
+
+### 2. Run an experiment
+
+```tsx
+import { useExperiment } from "@experiwall/react";
+
+function CheckoutButton() {
+  const variant = useExperiment("checkout-flow", ["control", "new-checkout"]);
+
+  if (variant === null) return null; // loading
+
+  if (variant === "new-checkout") {
+    return <NewCheckoutButton />;
+  }
+
+  return <OriginalCheckoutButton />;
+}
+```
+
+That's it. The hook automatically:
+- Assigns the user to a variant (deterministic, based on their seed)
+- Tracks an `$exposure` event once per mount
+- Registers the assignment with the server
+
+### 3. Track conversions
+
+```tsx
+import { useTrack } from "@experiwall/react";
+
+function PurchaseConfirmation({ amount }: { amount: number }) {
+  const track = useTrack();
+
+  useEffect(() => {
+    track("purchase", { revenue: amount });
+  }, []);
+
+  return <p>Thanks for your order!</p>;
+}
+```
+
+Events are batched (flushed every 30s) and automatically flushed when the user leaves the page.
+
+## API
+
+### `<ExperiwallProvider>`
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | Yes | Your project API key |
+| `userId` | `string` | No | Stable user identifier for consistent bucketing |
+| `aliasId` | `string` | No | Alternative identifier (e.g. anonymous ID) |
+| `environment` | `string` | No | `"production"` (default) or `"development"` — segments traffic in the dashboard |
+| `overrides` | `Record<string, string>` | No | Force specific variants for QA (skips tracking) |
+| `baseUrl` | `string` | No | Custom API URL (defaults to `https://experiwall.com`) |
+
+### `useExperiment(flagKey, variants, options?)`
+
+Returns the assigned variant (`string`) or `null` while loading.
+
+```tsx
+const variant = useExperiment("hero-banner", ["control", "large-cta", "video"]);
+```
+
+**Options:**
+
+| Option | Type | Description |
+|---|---|---|
+| `force` | `string` | Override the variant for this hook only (skips tracking) |
+
+### `useTrack()`
+
+Returns a `track(eventName, properties?)` function.
+
+```tsx
+const track = useTrack();
+track("signup", { plan: "pro" });
+```
+
+### `useExperiwall()`
+
+Low-level access to the full SDK context.
+
+| Field | Type | Description |
+|---|---|---|
+| `userSeed` | `number \| null` | Server-provided seed for deterministic bucketing. `null` while loading. |
+| `assignments` | `Record<string, string>` | Map of flag key to assigned variant key |
+| `experiments` | `Record<string, { variants: { key: string; weight: number }[] }> \| undefined` | Server-provided experiment definitions with variant weights |
+| `overrides` | `Record<string, string>` | Provider-level forced variants |
+| `isLoading` | `boolean` | `true` during the initial `/init` fetch |
+| `error` | `Error \| null` | Error object if the `/init` fetch failed |
+| `trackEvent` | `(event: ExperiwallEvent) => void` | Queue a raw event for batching |
+| `registerLocalFlag` | `(flagKey, variants, assignedVariant) => void` | Register a client-side flag assignment with the server |
+
+## QA and testing
+
+Use `overrides` to force variants without contaminating experiment data:
+
+```tsx
+<ExperiwallProvider
+  apiKey="your-api-key"
+  userId={currentUser.id}
+  overrides={{ "checkout-flow": "new-checkout" }}
+>
+```
+
+Or per-hook:
+
+```tsx
+const variant = useExperiment("checkout-flow", ["control", "new-checkout"], {
+  force: "new-checkout", etc.
+});
+```
+
+Both skip exposure tracking and server registration entirely.
+
+## Environment separation
+
+Pass `environment` to keep development traffic out of your production results:
+
+```tsx
+<ExperiwallProvider
+  apiKey="your-api-key"
+  environment={process.env.NODE_ENV === "production" ? "production" : "development"}
+>
+```
+
+The dashboard lets you toggle between Production and Development to view metrics separately.
+
+## License
+
+MIT

package/dist/index.js

@@ -31,7 +31,7 @@ module.exports = __toCommonJS(index_exports);
 var import_react = require("react");
 
 // src/lib/api-client.ts
-var DEFAULT_BASE_URL = "https://experiwall.com";
+var DEFAULT_BASE_URL = "https://www.experiwall.com";
 async function fetchInit(apiKey, options) {
   const base = options?.baseUrl ?? DEFAULT_BASE_URL;
   const url = new URL("/api/sdk/init", base);
@@ -191,6 +191,18 @@ function setCache(key, data) {
 
 // src/provider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
+var ANON_ID_KEY = "experiwall_anon_id";
+function getOrCreateAnonId() {
+  try {
+    const existing = localStorage.getItem(ANON_ID_KEY);
+    if (existing) return existing;
+    const id = crypto.randomUUID();
+    localStorage.setItem(ANON_ID_KEY, id);
+    return id;
+  } catch {
+    return crypto.randomUUID();
+  }
+}
 function getCacheKey(userId, aliasId, environment) {
   const identity = userId || aliasId || "anon";
   const env = environment || "production";
@@ -203,6 +215,10 @@ function ExperiwallProvider({
   children,
   ...config
 }) {
+  const [anonId] = (0, import_react.useState)(
+    () => !config.userId && !config.aliasId ? getOrCreateAnonId() : void 0
+  );
+  const effectiveAliasId = config.aliasId ?? anonId;
   const [userSeed, setUserSeed] = (0, import_react.useState)(null);
   const [assignments, setAssignments] = (0, import_react.useState)({});
   const [experiments, setExperiments] = (0, import_react.useState)();
@@ -214,7 +230,7 @@ function ExperiwallProvider({
     const load = async () => {
       setIsLoading(true);
       setError(null);
-      const cacheKey = getCacheKey(config.userId, config.aliasId, config.environment);
+      const cacheKey = getCacheKey(config.userId, effectiveAliasId, config.environment);
       const cached = getCached(cacheKey);
       if (cached) {
         setUserSeed(cached.user_seed);
@@ -228,7 +244,7 @@ function ExperiwallProvider({
         const data = await fetchInit(config.apiKey, {
           baseUrl: config.baseUrl,
           userId: config.userId,
-          aliasId: config.aliasId,
+          aliasId: effectiveAliasId,
           environment
         });
         if (!cancelled) {
@@ -254,7 +270,7 @@ function ExperiwallProvider({
       apiKey: config.apiKey,
       baseUrl: config.baseUrl,
       userId: config.userId,
-      aliasId: config.aliasId,
+      aliasId: effectiveAliasId,
       environment: config.environment ?? "production"
     });
     batcher.start();
@@ -273,7 +289,7 @@ function ExperiwallProvider({
       window.removeEventListener("beforeunload", handleBeforeUnload);
       batcher.stop();
     };
-  }, [config.apiKey, config.userId, config.aliasId, config.environment]);
+  }, [config.apiKey, config.userId, effectiveAliasId, config.environment]);
   const trackEvent = (0, import_react.useCallback)((event) => {
     batcherRef.current?.push(event);
   }, []);
@@ -287,13 +303,13 @@ function ExperiwallProvider({
           variants,
           assigned_variant: assignedVariant,
           user_id: config.userId,
-          alias_id: config.aliasId
+          alias_id: effectiveAliasId
         },
         { baseUrl: config.baseUrl, environment: config.environment ?? "production" }
       ).catch(() => {
       });
     },
-    [config.apiKey, config.baseUrl, config.userId, config.aliasId, config.environment]
+    [config.apiKey, config.baseUrl, config.userId, effectiveAliasId, config.environment]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
     ExperiwallContext.Provider,

package/dist/index.mjs

@@ -8,7 +8,7 @@ import {
 } from "react";
 
 // src/lib/api-client.ts
-var DEFAULT_BASE_URL = "https://experiwall.com";
+var DEFAULT_BASE_URL = "https://www.experiwall.com";
 async function fetchInit(apiKey, options) {
   const base = options?.baseUrl ?? DEFAULT_BASE_URL;
   const url = new URL("/api/sdk/init", base);
@@ -168,6 +168,18 @@ function setCache(key, data) {
 
 // src/provider.tsx
 import { jsx } from "react/jsx-runtime";
+var ANON_ID_KEY = "experiwall_anon_id";
+function getOrCreateAnonId() {
+  try {
+    const existing = localStorage.getItem(ANON_ID_KEY);
+    if (existing) return existing;
+    const id = crypto.randomUUID();
+    localStorage.setItem(ANON_ID_KEY, id);
+    return id;
+  } catch {
+    return crypto.randomUUID();
+  }
+}
 function getCacheKey(userId, aliasId, environment) {
   const identity = userId || aliasId || "anon";
   const env = environment || "production";
@@ -180,6 +192,10 @@ function ExperiwallProvider({
   children,
   ...config
 }) {
+  const [anonId] = useState(
+    () => !config.userId && !config.aliasId ? getOrCreateAnonId() : void 0
+  );
+  const effectiveAliasId = config.aliasId ?? anonId;
   const [userSeed, setUserSeed] = useState(null);
   const [assignments, setAssignments] = useState({});
   const [experiments, setExperiments] = useState();
@@ -191,7 +207,7 @@ function ExperiwallProvider({
     const load = async () => {
       setIsLoading(true);
       setError(null);
-      const cacheKey = getCacheKey(config.userId, config.aliasId, config.environment);
+      const cacheKey = getCacheKey(config.userId, effectiveAliasId, config.environment);
       const cached = getCached(cacheKey);
       if (cached) {
         setUserSeed(cached.user_seed);
@@ -205,7 +221,7 @@ function ExperiwallProvider({
         const data = await fetchInit(config.apiKey, {
           baseUrl: config.baseUrl,
           userId: config.userId,
-          aliasId: config.aliasId,
+          aliasId: effectiveAliasId,
           environment
         });
         if (!cancelled) {
@@ -231,7 +247,7 @@ function ExperiwallProvider({
       apiKey: config.apiKey,
       baseUrl: config.baseUrl,
       userId: config.userId,
-      aliasId: config.aliasId,
+      aliasId: effectiveAliasId,
       environment: config.environment ?? "production"
     });
     batcher.start();
@@ -250,7 +266,7 @@ function ExperiwallProvider({
       window.removeEventListener("beforeunload", handleBeforeUnload);
       batcher.stop();
     };
-  }, [config.apiKey, config.userId, config.aliasId, config.environment]);
+  }, [config.apiKey, config.userId, effectiveAliasId, config.environment]);
   const trackEvent = useCallback((event) => {
     batcherRef.current?.push(event);
   }, []);
@@ -264,13 +280,13 @@ function ExperiwallProvider({
           variants,
           assigned_variant: assignedVariant,
           user_id: config.userId,
-          alias_id: config.aliasId
+          alias_id: effectiveAliasId
         },
         { baseUrl: config.baseUrl, environment: config.environment ?? "production" }
       ).catch(() => {
       });
     },
-    [config.apiKey, config.baseUrl, config.userId, config.aliasId, config.environment]
+    [config.apiKey, config.baseUrl, config.userId, effectiveAliasId, config.environment]
   );
   return /* @__PURE__ */ jsx(
     ExperiwallContext.Provider,

package/dist/server.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Server-side helpers for Experiwall.
+ *
+ * Use this module in Next.js server components, Route Handlers,
+ * or any server runtime to resolve experiments during SSR —
+ * the variant is in the initial HTML with zero loading state.
+ *
+ * ```ts
+ * import { fetchExperiments } from "@experiwall/react/server";
+ *
+ * // In a server component:
+ * const { assignments } = await fetchExperiments({
+ *   apiKey: "ew_pub_...",
+ *   aliasId: cookies().get("ew_anon_id")?.value,
+ * });
+ * const variant = assignments["my-experiment"] ?? "control";
+ * ```
+ */
+interface ServerConfig {
+    apiKey: string;
+    baseUrl?: string;
+    userId?: string;
+    aliasId?: string;
+    environment?: string;
+}
+interface ExperimentsResponse {
+    user_seed: number;
+    assignments: Record<string, string>;
+    experiments?: Record<string, {
+        variants: {
+            key: string;
+            weight: number;
+        }[];
+    }>;
+}
+/**
+ * Fetch experiment assignments from the Experiwall API.
+ *
+ * Call this from server components to resolve variants at SSR time.
+ * Pass a `userId` or `aliasId` to identify the visitor (e.g. from a cookie).
+ */
+declare function fetchExperiments(config: ServerConfig): Promise<ExperimentsResponse>;
+
+export { type ExperimentsResponse, type ServerConfig, fetchExperiments };

package/dist/server.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Server-side helpers for Experiwall.
+ *
+ * Use this module in Next.js server components, Route Handlers,
+ * or any server runtime to resolve experiments during SSR —
+ * the variant is in the initial HTML with zero loading state.
+ *
+ * ```ts
+ * import { fetchExperiments } from "@experiwall/react/server";
+ *
+ * // In a server component:
+ * const { assignments } = await fetchExperiments({
+ *   apiKey: "ew_pub_...",
+ *   aliasId: cookies().get("ew_anon_id")?.value,
+ * });
+ * const variant = assignments["my-experiment"] ?? "control";
+ * ```
+ */
+interface ServerConfig {
+    apiKey: string;
+    baseUrl?: string;
+    userId?: string;
+    aliasId?: string;
+    environment?: string;
+}
+interface ExperimentsResponse {
+    user_seed: number;
+    assignments: Record<string, string>;
+    experiments?: Record<string, {
+        variants: {
+            key: string;
+            weight: number;
+        }[];
+    }>;
+}
+/**
+ * Fetch experiment assignments from the Experiwall API.
+ *
+ * Call this from server components to resolve variants at SSR time.
+ * Pass a `userId` or `aliasId` to identify the visitor (e.g. from a cookie).
+ */
+declare function fetchExperiments(config: ServerConfig): Promise<ExperimentsResponse>;
+
+export { type ExperimentsResponse, type ServerConfig, fetchExperiments };

package/dist/server.js

@@ -0,0 +1,45 @@
+"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/server.ts
+var server_exports = {};
+__export(server_exports, {
+  fetchExperiments: () => fetchExperiments
+});
+module.exports = __toCommonJS(server_exports);
+var DEFAULT_BASE_URL = "https://www.experiwall.com";
+async function fetchExperiments(config) {
+  const base = config.baseUrl ?? DEFAULT_BASE_URL;
+  const url = new URL("/api/sdk/init", base);
+  if (config.userId) url.searchParams.set("user_id", config.userId);
+  if (config.aliasId) url.searchParams.set("alias_id", config.aliasId);
+  if (config.environment) url.searchParams.set("environment", config.environment);
+  const res = await fetch(url.toString(), {
+    headers: { "x-api-key": config.apiKey },
+    cache: "no-store"
+  });
+  if (!res.ok) {
+    throw new Error(`Experiwall API error: ${res.status}`);
+  }
+  return res.json();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchExperiments
+});

package/dist/server.mjs

@@ -0,0 +1,20 @@
+// src/server.ts
+var DEFAULT_BASE_URL = "https://www.experiwall.com";
+async function fetchExperiments(config) {
+  const base = config.baseUrl ?? DEFAULT_BASE_URL;
+  const url = new URL("/api/sdk/init", base);
+  if (config.userId) url.searchParams.set("user_id", config.userId);
+  if (config.aliasId) url.searchParams.set("alias_id", config.aliasId);
+  if (config.environment) url.searchParams.set("environment", config.environment);
+  const res = await fetch(url.toString(), {
+    headers: { "x-api-key": config.apiKey },
+    cache: "no-store"
+  });
+  if (!res.ok) {
+    throw new Error(`Experiwall API error: ${res.status}`);
+  }
+  return res.json();
+}
+export {
+  fetchExperiments
+};

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "@experiwall/react",
-  "version": "0.2.0",
+  "version": "0.3.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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.js"
+    }
+  },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+    "build": "tsup src/index.ts src/server.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts src/server.ts --format cjs,esm --dts --watch"
   },
   "peerDependencies": {
     "react": ">=18",