@drip-apex/sdk 0.1.0

package/src/react/index.tsx

@@ -0,0 +1,252 @@
+/**
+ * React bindings for Drip SDK.
+ *
+ * Usage:
+ *   import { DripProvider, useExperiment, useVariation, useFeatureFlag, useFeatureFlagValue, useTrackGoal } from "@drip-apex/sdk/react";
+ *
+ *   function App() {
+ *     return (
+ *       <DripProvider shopId="shop_xxx" endpoint="https://events.drip-apex.com">
+ *         <HeroSection />
+ *       </DripProvider>
+ *     );
+ *   }
+ *
+ *   function HeroSection() {
+ *     const assignment = useExperiment("hero-test");
+ *     const variation = useVariation("hero-test");
+ *     const isDarkMode = useFeatureFlag("dark-mode-rollout");
+ *     const offerCopy = useFeatureFlagValue("offer-copy", "Default offer");
+ *     const trackGoal = useTrackGoal();
+ *
+ *     return (
+ *       <div>
+ *         <h1>{variation?.id === "variant-a" ? "New headline" : "Default headline"}</h1>
+ *         <button onClick={() => trackGoal("cta-click")}>CTA</button>
+ *       </div>
+ *     );
+ *   }
+ */
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  useCallback,
+  useRef,
+  type ReactNode,
+} from "react";
+import type { Assignment, Experiment, InitConfig, Variation } from "../types";
+import type { RevenueEventData } from "../index";
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+interface DripContextValue {
+  /** Current experiment assignments. */
+  assignments: Assignment[];
+  /** Loaded experiment configs. */
+  experiments: Experiment[];
+  /** Whether the SDK is still loading config. */
+  loading: boolean;
+  /** Track a goal by goalId with optional data. */
+  trackGoal: (goalId: string, data?: Record<string, unknown>) => void;
+  /** Track a custom event. */
+  track: (type: string, data?: Record<string, unknown>) => void;
+  /** Track revenue. */
+  trackRevenue: (revenue: number, data?: RevenueEventData) => void;
+}
+
+const DripContext = createContext<DripContextValue | null>(null);
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export interface DripProviderProps extends Omit<InitConfig, "onExperimentViewed"> {
+  children: ReactNode;
+  /** Callback when an experiment is viewed (assignment applied). */
+  onExperimentViewed?: (assignment: Assignment) => void;
+}
+
+/**
+ * Drip SDK provider for React applications.
+ *
+ * Initializes the SDK, fetches experiment config (if shopId provided),
+ * and provides assignment context to child components.
+ */
+export function DripProvider({
+  children,
+  onExperimentViewed,
+  ...config
+}: DripProviderProps) {
+  const [assignments, setAssignments] = useState<Assignment[]>([]);
+  const [experiments, setExperiments] = useState<Experiment[]>(config.experiments ?? []);
+  const [loading, setLoading] = useState(!config.experiments?.length);
+  const initRef = useRef(false);
+
+  useEffect(() => {
+    if (initRef.current) return;
+    initRef.current = true;
+    let mounted = true;
+
+    const syncFromSdk = () => {
+      // Dynamic import to avoid SSR issues (SDK accesses DOM/window)
+      import("../index").then((sdk) => {
+        if (!mounted) return;
+        setAssignments(sdk.getAssignments());
+        setExperiments(sdk.getExperiments());
+        setLoading(false);
+      });
+    };
+
+    const onInitialized = () => {
+      syncFromSdk();
+    };
+
+    document.addEventListener("drip_initialized", onInitialized as EventListener);
+
+    import("../index").then((sdk) => {
+      if (!mounted) return;
+      const result = sdk.init({
+        ...config,
+        onExperimentViewed: (a) => {
+          onExperimentViewed?.(a);
+        },
+      });
+      setAssignments(result);
+      setExperiments(config.experiments ?? sdk.getExperiments());
+      setLoading(false);
+    });
+
+    return () => {
+      mounted = false;
+      document.removeEventListener("drip_initialized", onInitialized as EventListener);
+    };
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const trackGoal = useCallback((goalId: string, data?: Record<string, unknown>) => {
+    import("../index").then((sdk) => sdk.trackGoal(goalId, data));
+  }, []);
+
+  const track = useCallback((type: string, data?: Record<string, unknown>) => {
+    import("../index").then((sdk) => sdk.track(type, data));
+  }, []);
+
+  const trackRevenue = useCallback((revenue: number, data?: RevenueEventData) => {
+    import("../index").then((sdk) => sdk.trackRevenue(revenue, data));
+  }, []);
+
+  const value = useMemo<DripContextValue>(
+    () => ({ assignments, experiments, loading, trackGoal, track, trackRevenue }),
+    [assignments, experiments, loading, trackGoal, track, trackRevenue],
+  );
+
+  return <DripContext.Provider value={value}>{children}</DripContext.Provider>;
+}
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+function useDrip(): DripContextValue {
+  const ctx = useContext(DripContext);
+  if (!ctx) {
+    throw new Error("useDrip must be used within a <DripProvider>");
+  }
+  return ctx;
+}
+
+/**
+ * Get the assignment for a specific experiment by ID or slug.
+ * Returns `null` if the user is not assigned to this experiment.
+ */
+export function useExperiment(experimentId: string): Assignment | null {
+  const { assignments } = useDrip();
+  return useMemo(
+    () => assignments.find((a) => a.experimentId === experimentId) ?? null,
+    [assignments, experimentId],
+  );
+}
+
+/**
+ * Get the assigned variation for a specific experiment.
+ * Returns `null` if the user is not assigned.
+ */
+export function useVariation(experimentId: string): Pick<Variation, "id" | "isControl"> | null {
+  const assignment = useExperiment(experimentId);
+  return useMemo(() => {
+    if (!assignment) return null;
+    return { id: assignment.variationId, isControl: assignment.isControl };
+  }, [assignment]);
+}
+
+/**
+ * Evaluate a feature flag (experiment-backed).
+ * Returns `true` if the user is bucketed into a non-control variation.
+ */
+export function useFeatureFlag(flagId: string): boolean {
+  const { assignments } = useDrip();
+  return useMemo(() => {
+    const a = assignments.find((a) => a.experimentId === flagId);
+    return a ? !a.isControl : false;
+  }, [assignments, flagId]);
+}
+
+/**
+ * Read the typed value assigned by a feature flag.
+ * Returns the fallback when the visitor is not assigned or the flag is missing.
+ */
+export function useFeatureFlagValue<T = unknown>(flagId: string, fallback: T): T | unknown {
+  const { assignments } = useDrip();
+  return useMemo(() => {
+    const assignment = assignments.find((assignment) => assignment.experimentId === flagId);
+    return assignment?.value === undefined ? fallback : assignment.value;
+  }, [assignments, fallback, flagId]);
+}
+
+/**
+ * Returns a function to track goals.
+ */
+export function useTrackGoal(): (goalId: string, data?: Record<string, unknown>) => void {
+  const { trackGoal } = useDrip();
+  return trackGoal;
+}
+
+/**
+ * Returns a function to track custom events.
+ */
+export function useTrack(): (type: string, data?: Record<string, unknown>) => void {
+  const { track } = useDrip();
+  return track;
+}
+
+/**
+ * Returns a function to track revenue.
+ */
+export function useTrackRevenue(): (revenue: number, data?: Record<string, unknown>) => void {
+  const { trackRevenue } = useDrip();
+  return trackRevenue;
+}
+
+/**
+ * Get all current assignments.
+ */
+export function useAssignments(): Assignment[] {
+  const { assignments } = useDrip();
+  return assignments;
+}
+
+/**
+ * Whether the SDK is still loading experiment config.
+ */
+export function useLoading(): boolean {
+  const { loading } = useDrip();
+  return loading;
+}
+
+// Re-export types for convenience
+export type { Assignment, Experiment, Variation, InitConfig } from "../types";

package/src/reassert-sentinel.test.ts

@@ -0,0 +1,314 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { applyToElement, applyTrackedMutation, resetAppliedMutations } from "./mutate";
+import { runMuted } from "./observer-mute";
+import { resetReassertSentinel, trackAppliedMutation } from "./reassert-sentinel";
+import type { Mutation } from "./types";
+
+let frames: FrameRequestCallback[] = [];
+
+async function deliverMutations(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+async function runNextFrame(): Promise<void> {
+  await deliverMutations();
+  const callback = frames.shift();
+  callback?.(performance.now());
+  await deliverMutations();
+}
+
+function applyAndTrack(element: Element, mutation: Mutation, context = {}) {
+  // The tracked apply captures the pre-treatment snapshot the sentinel uses
+  // to attribute in-place framework reverts (matching the production path).
+  runMuted(() => applyTrackedMutation(mutation, element));
+  trackAppliedMutation(element, mutation, context, (target, applied) => applyToElement(applied, target));
+}
+
+describe("reassert sentinel", () => {
+  beforeEach(() => {
+    frames = [];
+    vi.stubGlobal("requestAnimationFrame", vi.fn((callback: FrameRequestCallback) => {
+      frames.push(callback);
+      return frames.length;
+    }));
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+    resetAppliedMutations();
+    document.body.innerHTML = "";
+    delete (window as Window & { __dripPerf?: unknown }).__dripPerf;
+  });
+
+  afterEach(() => {
+    resetReassertSentinel();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it.each([
+    ["text", { selector: "#target", action: "text", text: "Variant" } as Mutation, (element: Element) => { element.textContent = "Control"; }, (element: Element) => element.textContent],
+    ["attribute", { selector: "#target", action: "attribute", attributes: { "aria-label": "Variant" } } as Mutation, (element: Element) => { element.setAttribute("aria-label", "Control"); }, (element: Element) => element.getAttribute("aria-label")],
+    ["html", { selector: "#target", action: "html", html: "<strong>Variant</strong>" } as Mutation, (element: Element) => { element.innerHTML = "<em>Control</em>"; }, (element: Element) => element.textContent],
+  ])("re-applies an external %s overwrite on the next animation frame", async (_label, mutation, overwrite, read) => {
+    const element = document.createElement("div");
+    element.id = "target";
+    document.body.appendChild(element);
+    applyAndTrack(element, mutation);
+
+    overwrite(element);
+    await runNextFrame();
+
+    expect(read(element)).toBe("Variant");
+  });
+
+  it("re-applies an in-place hydration revert to the original content", async () => {
+    const element = document.createElement("div");
+    element.id = "target";
+    element.innerHTML = "<strong>Control</strong>";
+    document.body.appendChild(element);
+    const mutation = { selector: "#target", action: "html", html: "<strong>Variant</strong>" } as Mutation;
+    applyAndTrack(element, mutation);
+
+    // React/Vue reconciliation patches the same node back to the original
+    // server-rendered content instead of replacing the subtree.
+    element.querySelector("strong")!.textContent = "Control";
+    await runNextFrame();
+
+    expect(element.textContent).toBe("Variant");
+  });
+
+  it("re-applies a descendant attribute-only hydration revert in an html treatment", async () => {
+    const element = document.createElement("div");
+    element.id = "target";
+    element.innerHTML = '<img class="control" aria-label="Product">';
+    document.body.appendChild(element);
+    const mutation = {
+      selector: "#target",
+      action: "html",
+      html: '<img class="variant" aria-label="Product">',
+    } as Mutation;
+    applyAndTrack(element, mutation);
+
+    // Hydration keeps the descendant node but restores only its attribute.
+    element.querySelector("img")!.className = "control";
+    await runNextFrame();
+
+    expect(element.querySelector("img")!.className).toBe("variant");
+  });
+
+  it("re-applies an added-only restore of removed original html", async () => {
+    const element = document.createElement("div");
+    element.id = "target";
+    element.innerHTML = "<span>Shared</span><i>Control only</i>";
+    document.body.appendChild(element);
+    const mutation = { selector: "#target", action: "html", html: "<span>Shared</span>" } as Mutation;
+    applyAndTrack(element, mutation);
+
+    const restored = document.createElement("i");
+    restored.textContent = "Control only";
+    element.appendChild(restored);
+    await runNextFrame();
+
+    expect(element.innerHTML).toBe("<span>Shared</span>");
+  });
+
+  it("leaves variant-owned html subtree changes alone within the revert window", async () => {
+    const element = document.createElement("div");
+    element.id = "target";
+    document.body.appendChild(element);
+    const mutation = { selector: "#target", action: "html", html: '<div class="widget"><span>slide-1</span></div>' } as Mutation;
+    applyAndTrack(element, mutation);
+
+    // Variation JS initializes a widget right after apply: the evolved
+    // content is nothing the original ever had, so it must not be erased.
+    element.querySelector(".widget")!.appendChild(document.createElement("span"));
+    await runNextFrame();
+
+    expect(element.querySelectorAll(".widget span")).toHaveLength(2);
+  });
+
+  it("leaves surviving subtree changes alone after the revert window", async () => {
+    const element = document.createElement("div");
+    element.id = "target";
+    document.body.appendChild(element);
+    const mutation = { selector: "#target", action: "html", html: '<div class="widget"><span>slide-1</span></div>' } as Mutation;
+    applyAndTrack(element, mutation);
+    vi.spyOn(Date, "now").mockReturnValue(Date.now() + 11_000);
+
+    element.querySelector(".widget")!.appendChild(document.createElement("span"));
+    await runNextFrame();
+
+    expect(element.querySelectorAll(".widget span")).toHaveLength(2);
+  });
+
+  it("re-applies a wholesale framework replace even after widget activity", async () => {
+    const element = document.createElement("div");
+    element.id = "target";
+    document.body.appendChild(element);
+    const mutation = { selector: "#target", action: "html", html: '<div class="widget">v</div>' } as Mutation;
+    applyAndTrack(element, mutation);
+
+    element.querySelector(".widget")!.appendChild(document.createElement("span"));
+    await runNextFrame();
+    // Framework hydration restores the original content wholesale.
+    element.innerHTML = "<em>Control</em>";
+    await runNextFrame();
+
+    expect(element.querySelector(".widget")).not.toBeNull();
+  });
+
+  it("does not schedule a re-apply for SDK writes", async () => {
+    const element = document.createElement("div");
+    document.body.appendChild(element);
+    const mutation = { selector: "div", action: "text", text: "Variant" } as Mutation;
+    applyAndTrack(element, mutation);
+
+    runMuted(() => applyToElement(mutation, element));
+    await deliverMutations();
+
+    expect(frames).toHaveLength(0);
+  });
+
+  it("does no sentinel work for mutations outside treated subtrees", async () => {
+    const treated = document.createElement("div");
+    const outside = document.createElement("div");
+    document.body.append(treated, outside);
+    const mutation = { selector: "#treated", action: "text", text: "Variant" } as Mutation;
+    runMuted(() => applyTrackedMutation(mutation, treated));
+    const apply = vi.fn((target: Element, applied: Mutation) => applyToElement(applied, target));
+    trackAppliedMutation(treated, mutation, {}, apply);
+
+    outside.textContent = "Unrelated storefront update";
+    await deliverMutations();
+
+    expect(frames).toHaveLength(0);
+    expect(apply).not.toHaveBeenCalled();
+  });
+
+  it("accepts browser-canonical style values after unrelated style mutations", async () => {
+    const element = document.createElement("div");
+    document.body.appendChild(element);
+    const mutation = { selector: "div", action: "style", styles: { backgroundColor: "#ffa04c" } } as Mutation;
+    applyAndTrack(element, mutation);
+
+    expect(element.style.getPropertyValue("background-color")).not.toBe("#ffa04c");
+    element.style.setProperty("padding", "1px");
+    await deliverMutations();
+
+    expect(frames).toHaveLength(0);
+  });
+
+  it("re-attaches observation when a treated root is replaced and registered again", async () => {
+    const original = document.createElement("div");
+    document.body.appendChild(original);
+    const mutation = { selector: "#target", action: "text", text: "Variant" } as Mutation;
+    applyAndTrack(original, mutation);
+
+    const replacement = document.createElement("div");
+    original.replaceWith(replacement);
+    applyAndTrack(replacement, mutation);
+    replacement.textContent = "Control";
+    await runNextFrame();
+
+    expect(replacement.textContent).toBe("Variant");
+  });
+
+  it("disconnects and unregisters a replaced treated root", () => {
+    const instances: Array<{
+      disconnected: boolean;
+      takeRecordCalls: number;
+    }> = [];
+    class TestMutationObserver {
+      disconnected = false;
+      takeRecordCalls = 0;
+
+      constructor(_callback: MutationCallback) {
+        instances.push(this);
+      }
+
+      observe(): void {}
+
+      disconnect(): void {
+        this.disconnected = true;
+      }
+
+      takeRecords(): MutationRecord[] {
+        this.takeRecordCalls += 1;
+        return [];
+      }
+    }
+    vi.stubGlobal("MutationObserver", TestMutationObserver);
+
+    const original = document.createElement("div");
+    document.body.appendChild(original);
+    const mutation = { selector: "#target", action: "text", text: "Variant" } as Mutation;
+    applyAndTrack(original, mutation);
+
+    const replacement = document.createElement("div");
+    original.replaceWith(replacement);
+    applyAndTrack(replacement, mutation);
+
+    expect(instances).toHaveLength(2);
+    expect(instances[0]?.disconnected).toBe(true);
+    const oldTakeRecordCalls = instances[0]?.takeRecordCalls;
+    runMuted(() => {});
+    expect(instances[0]?.takeRecordCalls).toBe(oldTakeRecordCalls);
+    expect(instances[1]?.takeRecordCalls).toBeGreaterThan(0);
+  });
+
+  it("stops after twelve re-applies in ten seconds and marks the loop", async () => {
+    const element = document.createElement("div");
+    document.body.appendChild(element);
+    const mutation = { selector: "div", action: "text", text: "Variant" } as Mutation;
+    applyAndTrack(element, mutation);
+
+    for (let index = 0; index < 12; index += 1) {
+      element.textContent = `Control ${index}`;
+      await runNextFrame();
+      expect(element.textContent).toBe("Variant");
+    }
+    element.textContent = "Framework still owns this";
+    await runNextFrame();
+
+    expect(element.textContent).toBe("Framework still owns this");
+    expect((window as Window & { __dripPerf?: Record<string, unknown> }).__dripPerf).toMatchObject({
+      reapply_count: 12,
+      reassert_loop_detected: true,
+    });
+  });
+
+  it("fires the HTML re-init event with assignment detail", async () => {
+    const listener = vi.fn();
+    document.addEventListener("drip:mutation-reapplied", listener);
+    const element = document.createElement("div");
+    document.body.appendChild(element);
+    const mutation = { selector: ".carousel", action: "html", html: "<div>Slides</div>" } as Mutation;
+    applyAndTrack(element, mutation, { experimentId: "exp_1", variationId: "var_1" });
+
+    element.innerHTML = "<div>Server slides</div>";
+    await runNextFrame();
+
+    expect(listener).toHaveBeenCalledWith(expect.objectContaining({
+      detail: {
+        experimentId: "exp_1",
+        variationId: "var_1",
+        selector: ".carousel",
+        action: "html",
+      },
+    }));
+    document.removeEventListener("drip:mutation-reapplied", listener);
+  });
+
+  it("disconnects and forgets tracked entries when applied mutations reset", async () => {
+    const element = document.createElement("div");
+    document.body.appendChild(element);
+    const mutation = { selector: "div", action: "text", text: "Variant" } as Mutation;
+    applyAndTrack(element, mutation);
+
+    resetAppliedMutations();
+    element.textContent = "Control";
+    await deliverMutations();
+
+    expect(frames).toHaveLength(0);
+  });
+});