@drip-apex/sdk 0.1.0

package/src/qa-assistant.ts

@@ -0,0 +1,40 @@
+import { createQaAssistantStore, type QaAssistantStore } from "./qa-assistant-state";
+import { mountQaAssistantView, type QaAssistantView } from "./qa-assistant-view";
+
+let qaAssistantStore: QaAssistantStore | null = null;
+let qaAssistantView: QaAssistantView | null = null;
+
+/**
+ * Mounts the QA Assistant panel (store + shadow-DOM view). QA-only module:
+ * live/heatmap builds stub this file out entirely (see build.mjs), and the
+ * caller in index.ts additionally gates on QA mode.
+ */
+export function mountQaAssistant(): QaAssistantView | null {
+  if (typeof document === "undefined") return null;
+  qaAssistantStore = qaAssistantStore ?? createQaAssistantStore();
+  if (qaAssistantView) return qaAssistantView;
+
+  const mount = () => {
+    if (!qaAssistantStore) return;
+    qaAssistantView = mountQaAssistantView(qaAssistantStore);
+  };
+  if (document.body) {
+    mount();
+    return qaAssistantView;
+  }
+  // Body not parsed yet — mounting is scheduled, which still counts as
+  // available (callers use null to fall back to the legacy toolbar).
+  document.addEventListener("DOMContentLoaded", mount, { once: true });
+  return {
+    destroy() {
+      document.removeEventListener("DOMContentLoaded", mount);
+      qaAssistantView?.destroy();
+      qaAssistantView = null;
+    },
+  };
+}
+
+export function getQaAssistantStore(): QaAssistantStore {
+  qaAssistantStore = qaAssistantStore ?? createQaAssistantStore();
+  return qaAssistantStore;
+}

package/src/qa-toolbar.ts

@@ -0,0 +1,444 @@
+/**
+ * QA Toolbar — floating in-page toolbar for QA preview sessions.
+ *
+ * Renders inside a Shadow DOM to avoid style interference with the host page.
+ * Shows active experiments, variation switcher, and exit QA button.
+ */
+
+import { Assignment, Experiment } from "./types";
+
+export interface QaToolbarOptions {
+  experiments: Experiment[];
+  assignments: Assignment[];
+  forceMap: Record<string, string> | null;
+  qaSessionId?: string;
+  onSwitchVariation: (experimentId: string, variationId: string) => void;
+  onExitQa: () => void;
+  onReloadLatest?: () => void;
+  onExitHarness?: () => void;
+}
+
+const TOOLBAR_ID = "drip-qa-toolbar";
+
+function serializeForceMap(forceMap: Record<string, string>): string {
+  return Object.entries(forceMap)
+    .map(([experimentId, variationId]) => `${experimentId}:${variationId}`)
+    .join(",");
+}
+
+function currentForceMap(options: QaToolbarOptions): Record<string, string> {
+  const map: Record<string, string> = { ...(options.forceMap ?? {}) };
+  for (const assignment of options.assignments) {
+    if (!map[assignment.experimentId]) {
+      map[assignment.experimentId] = assignment.variationId;
+    }
+  }
+  return map;
+}
+
+function buildQaDebugUrl(forceMap: Record<string, string>, qaSessionId?: string): string {
+  const url = new URL(location.href);
+  const entries = Object.entries(forceMap).filter(
+    ([experimentId, variationId]) => experimentId && variationId,
+  );
+  const filteredForceMap: Record<string, string> = {};
+  for (const [experimentId, variationId] of entries) {
+    filteredForceMap[experimentId] = variationId;
+  }
+  const force = serializeForceMap(filteredForceMap);
+  if (force) url.searchParams.set("drip_force", force);
+  if (entries.length === 1) {
+    url.searchParams.set("drip_experiment_id", entries[0][0]);
+    url.searchParams.set("drip_variation_id", entries[0][1]);
+  } else {
+    url.searchParams.delete("drip_experiment_id");
+    url.searchParams.delete("drip_variation_id");
+  }
+  url.searchParams.set("drip_qa", "1");
+  url.searchParams.set("drip_debug", "1");
+  if (qaSessionId) url.searchParams.set("drip_qa_session", qaSessionId);
+  return url.toString();
+}
+
+function replaceQaUrl(forceMap: Record<string, string>, qaSessionId?: string): void {
+  try {
+    history.replaceState(null, "", buildQaDebugUrl(forceMap, qaSessionId));
+  } catch {}
+}
+
+async function copyText(value: string): Promise<void> {
+  if (navigator.clipboard?.writeText) {
+    await navigator.clipboard.writeText(value);
+    return;
+  }
+  const textarea = document.createElement("textarea");
+  textarea.value = value;
+  textarea.style.position = "fixed";
+  textarea.style.opacity = "0";
+  document.body.appendChild(textarea);
+  textarea.select();
+  document.execCommand("copy");
+  document.body.removeChild(textarea);
+}
+
+const TOOLBAR_STYLES = `
+  :host {
+    all: initial;
+    position: fixed;
+    bottom: 16px;
+    right: 16px;
+    z-index: 2147483647;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  }
+  .toolbar {
+    background: #1a1a2e;
+    border: 1px solid rgba(139, 92, 246, 0.4);
+    border-radius: 12px;
+    padding: 12px 16px;
+    color: #e2e8f0;
+    font-size: 13px;
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+    min-width: 260px;
+    max-width: 360px;
+  }
+  .header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 10px;
+    padding-bottom: 8px;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+  }
+  .badge {
+    background: #8b5cf6;
+    color: #fff;
+    font-size: 10px;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    padding: 3px 8px;
+    border-radius: 4px;
+  }
+  .exit-btn {
+    background: rgba(239, 68, 68, 0.15);
+    color: #ef4444;
+    border: 1px solid rgba(239, 68, 68, 0.3);
+    border-radius: 6px;
+    padding: 4px 10px;
+    font-size: 11px;
+    font-weight: 600;
+    cursor: pointer;
+    transition: background 0.15s;
+  }
+  .exit-btn:hover {
+    background: rgba(239, 68, 68, 0.25);
+  }
+  .tool-btn {
+    background: rgba(83, 193, 222, 0.12);
+    color: #7dd3fc;
+    border: 1px solid rgba(125, 211, 252, 0.25);
+    border-radius: 6px;
+    padding: 4px 8px;
+    font-size: 11px;
+    font-weight: 600;
+    cursor: pointer;
+  }
+  .debug-actions {
+    display: flex;
+    gap: 6px;
+    margin-bottom: 10px;
+  }
+  .debug-actions .tool-btn {
+    flex: 1;
+    min-width: 0;
+  }
+  .harness {
+    border: 1px solid rgba(125, 211, 252, 0.25);
+    border-radius: 8px;
+    padding: 8px;
+    margin-bottom: 10px;
+    color: #bae6fd;
+    background: rgba(14, 116, 144, 0.12);
+  }
+  .harness-title {
+    font-size: 11px;
+    font-weight: 700;
+    margin-bottom: 6px;
+    text-transform: uppercase;
+  }
+  .harness-actions {
+    display: flex;
+    gap: 6px;
+  }
+  .session {
+    border: 1px solid rgba(255, 255, 255, 0.1);
+    border-radius: 8px;
+    padding: 7px 8px;
+    margin-bottom: 10px;
+    background: rgba(255, 255, 255, 0.04);
+  }
+  .session-label {
+    color: #94a3b8;
+    font-size: 10px;
+    font-weight: 700;
+    letter-spacing: 0.04em;
+    margin-bottom: 3px;
+    text-transform: uppercase;
+  }
+  .session-id {
+    color: #e2e8f0;
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    font-size: 11px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .experiment {
+    margin-bottom: 8px;
+  }
+  .experiment:last-child {
+    margin-bottom: 0;
+  }
+  .exp-name {
+    font-size: 12px;
+    color: #94a3b8;
+    margin-bottom: 4px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  .var-select {
+    width: 100%;
+    background: rgba(255, 255, 255, 0.06);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    border-radius: 6px;
+    color: #e2e8f0;
+    font-size: 13px;
+    padding: 6px 8px;
+    cursor: pointer;
+    outline: none;
+    appearance: none;
+    -webkit-appearance: none;
+  }
+  .var-select:focus {
+    border-color: #8b5cf6;
+  }
+  .var-select option {
+    background: #1a1a2e;
+    color: #e2e8f0;
+  }
+  .no-experiments {
+    color: #64748b;
+    font-size: 12px;
+    font-style: italic;
+  }
+  .collapse-btn {
+    background: none;
+    border: none;
+    color: #94a3b8;
+    cursor: pointer;
+    font-size: 16px;
+    padding: 0 4px;
+    line-height: 1;
+  }
+  .collapsed .body {
+    display: none;
+  }
+  .collapsed .toolbar {
+    min-width: auto;
+  }
+`;
+
+export function mountQaToolbar(options: QaToolbarOptions): void {
+  // Don't mount twice
+  if (document.getElementById(TOOLBAR_ID)) return;
+
+  const host = document.createElement("div");
+  host.id = TOOLBAR_ID;
+  const shadow = host.attachShadow({ mode: "closed" });
+
+  const style = document.createElement("style");
+  style.textContent = TOOLBAR_STYLES;
+  shadow.appendChild(style);
+
+  const toolbar = document.createElement("div");
+  toolbar.className = "toolbar";
+
+  // Header
+  const header = document.createElement("div");
+  header.className = "header";
+
+  const badge = document.createElement("span");
+  badge.className = "badge";
+  badge.textContent = "QA Preview";
+
+  const actions = document.createElement("div");
+  actions.style.cssText = "display:flex;gap:6px;align-items:center;";
+
+  const collapseBtn = document.createElement("button");
+  collapseBtn.className = "collapse-btn";
+  collapseBtn.textContent = "\u2212";
+  collapseBtn.title = "Collapse";
+  let collapsed = false;
+  collapseBtn.addEventListener("click", () => {
+    collapsed = !collapsed;
+    toolbar.classList.toggle("collapsed", collapsed);
+    collapseBtn.textContent = collapsed ? "+" : "\u2212";
+  });
+
+  const exitBtn = document.createElement("button");
+  exitBtn.className = "exit-btn";
+  exitBtn.textContent = "Exit QA";
+  exitBtn.addEventListener("click", options.onExitQa);
+
+  actions.appendChild(collapseBtn);
+  actions.appendChild(exitBtn);
+  header.appendChild(badge);
+  header.appendChild(actions);
+  toolbar.appendChild(header);
+
+  // Body
+  const body = document.createElement("div");
+  body.className = "body";
+  const activeForceMap = currentForceMap(options);
+
+  const harnessAssignment = options.assignments.find((assignment) => assignment.harnessSession);
+  if (harnessAssignment?.harnessSession) {
+    const harness = document.createElement("div");
+    harness.className = "harness";
+    const title = document.createElement("div");
+    title.className = "harness-title";
+    title.textContent = `Harness v${harnessAssignment.harnessSession.version ?? 0}`;
+    harness.appendChild(title);
+    const harnessActions = document.createElement("div");
+    harnessActions.className = "harness-actions";
+    const reload = document.createElement("button");
+    reload.className = "tool-btn";
+    reload.textContent = "Reload latest";
+    reload.addEventListener("click", () => options.onReloadLatest?.());
+    const exitHarness = document.createElement("button");
+    exitHarness.className = "tool-btn";
+    exitHarness.textContent = "Exit harness";
+    exitHarness.addEventListener("click", () => options.onExitHarness?.());
+    harnessActions.appendChild(reload);
+    harnessActions.appendChild(exitHarness);
+    harness.appendChild(harnessActions);
+    body.appendChild(harness);
+  }
+
+  if (options.experiments.length === 0) {
+    const noExp = document.createElement("div");
+    noExp.className = "no-experiments";
+    noExp.textContent = "No experiments on this page";
+    body.appendChild(noExp);
+  } else {
+    const debugActions = document.createElement("div");
+    debugActions.className = "debug-actions";
+    const copyDebugLink = document.createElement("button");
+    copyDebugLink.className = "tool-btn";
+    copyDebugLink.type = "button";
+    copyDebugLink.textContent = "Copy debug link";
+    copyDebugLink.title = "Copy a forced QA URL with experiment and variation ids";
+    copyDebugLink.addEventListener("click", () => {
+      const originalLabel = copyDebugLink.textContent;
+      copyText(buildQaDebugUrl(activeForceMap, options.qaSessionId))
+        .then(() => {
+          copyDebugLink.textContent = "Copied";
+          window.setTimeout(() => {
+            copyDebugLink.textContent = originalLabel;
+          }, 1600);
+        })
+        .catch(() => {
+          copyDebugLink.textContent = "Copy failed";
+          window.setTimeout(() => {
+            copyDebugLink.textContent = originalLabel;
+          }, 1600);
+        });
+    });
+
+    const openDebugPanel = document.createElement("button");
+    openDebugPanel.className = "tool-btn";
+    openDebugPanel.type = "button";
+    openDebugPanel.textContent = "Open debug panel";
+    openDebugPanel.title = "Enable Apex debug tools and reload this forced variation";
+    openDebugPanel.addEventListener("click", () => {
+      try {
+        localStorage.setItem("drip_devtools", "1");
+      } catch {}
+      replaceQaUrl(activeForceMap, options.qaSessionId);
+      location.reload();
+    });
+
+    debugActions.appendChild(copyDebugLink);
+    debugActions.appendChild(openDebugPanel);
+    body.appendChild(debugActions);
+
+    if (options.qaSessionId) {
+      const session = document.createElement("div");
+      session.className = "session";
+      const sessionLabel = document.createElement("div");
+      sessionLabel.className = "session-label";
+      sessionLabel.textContent = "QA session";
+      const sessionId = document.createElement("div");
+      sessionId.className = "session-id";
+      sessionId.textContent = options.qaSessionId;
+      sessionId.title = options.qaSessionId;
+      session.appendChild(sessionLabel);
+      session.appendChild(sessionId);
+      body.appendChild(session);
+    }
+
+    for (const exp of options.experiments) {
+      const expDiv = document.createElement("div");
+      expDiv.className = "experiment";
+
+      const nameEl = document.createElement("div");
+      nameEl.className = "exp-name";
+      nameEl.textContent = exp.id;
+      nameEl.title = exp.id;
+      expDiv.appendChild(nameEl);
+
+      const select = document.createElement("select");
+      select.className = "var-select";
+
+      const currentForced = options.forceMap?.[exp.id];
+      const activeForced = activeForceMap[exp.id];
+      const currentAssignment = options.assignments.find(
+        (a) => a.experimentId === exp.id,
+      );
+
+      for (const v of exp.variations) {
+        const opt = document.createElement("option");
+        opt.value = v.id;
+        const label = v.isControl ? "(Control)" : `Variation`;
+        opt.textContent = `${label} — ${v.id.slice(0, 8)}`;
+        if (
+          activeForced === v.id ||
+          currentForced === v.id ||
+          (!activeForced && !currentForced && currentAssignment?.variationId === v.id)
+        ) {
+          opt.selected = true;
+        }
+        select.appendChild(opt);
+      }
+
+      select.addEventListener("change", () => {
+        activeForceMap[exp.id] = select.value;
+        replaceQaUrl(activeForceMap, options.qaSessionId);
+        options.onSwitchVariation(exp.id, select.value);
+      });
+
+      expDiv.appendChild(select);
+      body.appendChild(expDiv);
+    }
+  }
+
+  toolbar.appendChild(body);
+  shadow.appendChild(toolbar);
+  document.body.appendChild(host);
+}
+
+export function unmountQaToolbar(): void {
+  const el = document.getElementById(TOOLBAR_ID);
+  if (el) el.remove();
+}

package/src/react/index.test.tsx

@@ -0,0 +1,177 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Assignment, Experiment } from "../types";
+import {
+  DripProvider,
+  useFeatureFlag,
+  useTrackGoal,
+  useVariation,
+} from "./index";
+
+const sdkMock = vi.hoisted(() => ({
+  init: vi.fn(),
+  getAssignments: vi.fn(),
+  getExperiments: vi.fn(),
+  trackGoal: vi.fn(),
+  track: vi.fn(),
+  trackRevenue: vi.fn(),
+}));
+
+vi.mock("../index", () => sdkMock);
+
+function assignment(
+  experimentId: string,
+  variationId: string,
+  isControl = false,
+): Assignment {
+  return {
+    experimentId,
+    variationId,
+    index: 0,
+    mutations: [],
+    isControl,
+    hashValue: `${experimentId}:${variationId}`,
+  };
+}
+
+function resetSdkMock() {
+  sdkMock.init.mockReset();
+  sdkMock.getAssignments.mockReset();
+  sdkMock.getExperiments.mockReset();
+  sdkMock.trackGoal.mockReset();
+  sdkMock.track.mockReset();
+  sdkMock.trackRevenue.mockReset();
+  sdkMock.init.mockReturnValue([]);
+  sdkMock.getAssignments.mockReturnValue([]);
+  sdkMock.getExperiments.mockReturnValue([]);
+}
+
+function VariationLabel({ experimentId }: { experimentId: string }) {
+  const variation = useVariation(experimentId);
+  return <div data-testid="variation">{variation?.id ?? "none"}</div>;
+}
+
+function FlagLabel({ flagId }: { flagId: string }) {
+  const enabled = useFeatureFlag(flagId);
+  return <div data-testid={flagId}>{enabled ? "on" : "off"}</div>;
+}
+
+function GoalButton() {
+  const trackGoal = useTrackGoal();
+  return (
+    <button
+      type="button"
+      onClick={() => trackGoal("signup", { plan: "pro" })}
+    >
+      Track
+    </button>
+  );
+}
+
+describe("React bindings", () => {
+  beforeEach(() => {
+    resetSdkMock();
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+  });
+
+  it("renders children and initializes the SDK", async () => {
+    const experiments: Experiment[] = [
+      {
+        id: "hero",
+        variations: [{ id: "control", weight: 1, mutations: [], isControl: true }],
+      },
+    ];
+    sdkMock.getExperiments.mockReturnValue(experiments);
+
+    render(
+      <DripProvider shopId="shop_123" endpoint="https://events.example.test">
+        <div>Storefront</div>
+      </DripProvider>,
+    );
+
+    expect(screen.getByText("Storefront")).toBeTruthy();
+    await waitFor(() => {
+      expect(sdkMock.init).toHaveBeenCalledWith(
+        expect.objectContaining({
+          shopId: "shop_123",
+          endpoint: "https://events.example.test",
+        }),
+      );
+    });
+    expect(sdkMock.getExperiments).toHaveBeenCalled();
+  });
+
+  it("returns null before assignments and updates variation after the initialized event", async () => {
+    const variant = assignment("hero-test", "variant-a");
+    sdkMock.getAssignments.mockReturnValue([]);
+
+    render(
+      <DripProvider shopId="shop_123">
+        <VariationLabel experimentId="hero-test" />
+      </DripProvider>,
+    );
+
+    expect(screen.getByTestId("variation").textContent).toBe("none");
+    await waitFor(() => expect(sdkMock.init).toHaveBeenCalled());
+
+    sdkMock.getAssignments.mockReturnValue([variant]);
+    await act(async () => {
+      document.dispatchEvent(new Event("drip_initialized"));
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId("variation").textContent).toBe("variant-a");
+    });
+  });
+
+  it("enables feature flags only for non-control assignments", async () => {
+    sdkMock.init.mockReturnValue([
+      assignment("flag-enabled", "enabled"),
+      assignment("flag-control", "control", true),
+    ]);
+
+    render(
+      <DripProvider shopId="shop_123">
+        <FlagLabel flagId="flag-enabled" />
+        <FlagLabel flagId="flag-control" />
+        <FlagLabel flagId="flag-missing" />
+      </DripProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("flag-enabled").textContent).toBe("on");
+      expect(screen.getByTestId("flag-control").textContent).toBe("off");
+      expect(screen.getByTestId("flag-missing").textContent).toBe("off");
+    });
+  });
+
+  it("throws when hooks are used outside DripProvider", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => render(<VariationLabel experimentId="hero-test" />)).toThrow(
+      "useDrip must be used within a <DripProvider>",
+    );
+    spy.mockRestore();
+  });
+
+  it("proxies goal tracking to the SDK", async () => {
+    render(
+      <DripProvider shopId="shop_123">
+        <GoalButton />
+      </DripProvider>,
+    );
+
+    await waitFor(() => expect(sdkMock.init).toHaveBeenCalled());
+    fireEvent.click(screen.getByRole("button", { name: "Track" }));
+
+    await waitFor(() => {
+      expect(sdkMock.trackGoal).toHaveBeenCalledWith("signup", { plan: "pro" });
+    });
+  });
+});