@drip-apex/sdk 0.1.0

package/src/flags.ts

@@ -0,0 +1,201 @@
+/**
+ * Feature flags — thin wrapper over experiment assignments.
+ *
+ * A feature flag is simply a two-variation experiment where:
+ *   - control = flag OFF
+ *   - variant = flag ON
+ *
+ * Usage:
+ *   import { evaluateFlag, defineFlagExperiment } from "@drip-apex/sdk/flags";
+ *
+ *   const darkMode = defineFlagExperiment({
+ *     slug: "dark-mode-rollout",
+ *     name: "Dark Mode Rollout",
+ *     rolloutPercent: 25,
+ *   });
+ *
+ *   const isEnabled = evaluateFlag("dark-mode-rollout", [darkMode], { userId: "user-123" });
+ */
+
+import { chooseVariation, inTrafficAllocation } from "./bucket";
+import { defineExperiment } from "./define";
+import type { Experiment, Assignment } from "./types";
+import { getUserId, hashToFloat, variationHashToFloat } from "./hash";
+import { buildTargetingAttributes, matchesTargeting } from "./targeting";
+
+// ---------------------------------------------------------------------------
+// evaluateFlag — check if a flag is ON for a given user
+// ---------------------------------------------------------------------------
+
+export interface FlagContext {
+  url?: string;
+  attributes?: Record<string, unknown>;
+  userId?: string;
+}
+
+/**
+ * Evaluate whether a feature flag is enabled.
+ *
+ * @param flagId - The experiment slug/id of the flag experiment.
+ * @param experiments - Array of experiment configs to search (from init or defineExperiment).
+ * @param context - Optional user context for targeting/bucketing.
+ * @returns `true` if the user is bucketed into a non-control variation.
+ */
+export function evaluateFlag(
+  flagId: string,
+  experiments: Experiment[],
+  context?: FlagContext,
+): boolean {
+  const experiment = experiments.find((e) => e.id === flagId);
+  if (!experiment) return false;
+
+  const url = context?.url ?? (typeof location !== "undefined" ? location.href : "");
+  const attributes = buildTargetingAttributes(context?.attributes ?? {}, url);
+
+  if (!matchesTargeting(experiment.targeting, { url, attributes })) {
+    return false;
+  }
+
+  const userId = getUserId(context?.userId);
+  const hashValue = hashToFloat(experiment.id, userId);
+
+  if (!inTrafficAllocation(hashValue, experiment.trafficAllocation ?? 1)) {
+    return false;
+  }
+
+  const allocation = experiment.trafficAllocation ?? 1;
+  const variationHashValue =
+    allocation >= 1 ? hashValue : variationHashToFloat(experiment.id, userId);
+  const weights = experiment.variations.map((v) => v.weight);
+  const index = chooseVariation(variationHashValue, weights);
+  if (index < 0 || index >= experiment.variations.length) return false;
+
+  const variation = experiment.variations[index];
+  return !variation.isControl;
+}
+
+/**
+ * Evaluate a flag and return the full assignment (or null if flag is off / not found).
+ */
+export function evaluateFlagAssignment(
+  flagId: string,
+  experiments: Experiment[],
+  context?: FlagContext,
+): Assignment | null {
+  const experiment = experiments.find((e) => e.id === flagId);
+  if (!experiment) return null;
+
+  const url = context?.url ?? (typeof location !== "undefined" ? location.href : "");
+  const attributes = buildTargetingAttributes(context?.attributes ?? {}, url);
+
+  if (!matchesTargeting(experiment.targeting, { url, attributes })) {
+    return null;
+  }
+
+  const userId = getUserId(context?.userId);
+  const hashValue = hashToFloat(experiment.id, userId);
+
+  if (!inTrafficAllocation(hashValue, experiment.trafficAllocation ?? 1)) {
+    return null;
+  }
+
+  const allocation = experiment.trafficAllocation ?? 1;
+  const variationHashValue =
+    allocation >= 1 ? hashValue : variationHashToFloat(experiment.id, userId);
+  const weights = experiment.variations.map((v) => v.weight);
+  const index = chooseVariation(variationHashValue, weights);
+  if (index < 0 || index >= experiment.variations.length) return null;
+
+  const variation = experiment.variations[index];
+
+  return {
+    experimentId: experiment.id,
+    experimentName: undefined,
+    variationId: variation.id,
+    index,
+    mutations: variation.mutations ?? [],
+    value: variation.value,
+    featureFlag: experiment.featureFlag,
+    kind: experiment.kind ?? (experiment.featureFlag ? "feature_flag" : "experiment"),
+    css: variation.css,
+    js: variation.js,
+    resetJs: variation.resetJs,
+    externalCssUrl: variation.externalCssUrl,
+    externalJsUrl: variation.externalJsUrl,
+    harnessSession: variation.harnessSession,
+    isControl: Boolean(variation.isControl),
+    hashValue: userId,
+  };
+}
+
+/**
+ * Evaluate a typed feature flag value.
+ *
+ * Returns the assigned variation value for boolean, string, number, or JSON
+ * flags. If the visitor is not eligible, the flag is missing, or no assignment
+ * can be made, the fallback is returned.
+ */
+export function evaluateFlagValue<T = unknown>(
+  flagId: string,
+  experiments: Experiment[],
+  context?: FlagContext,
+  fallback?: T,
+): T | unknown {
+  const assignment = evaluateFlagAssignment(flagId, experiments, context);
+  if (!assignment) return fallback;
+  return assignment.value === undefined ? fallback : assignment.value;
+}
+
+// ---------------------------------------------------------------------------
+// defineFlagExperiment — convenience for creating flag-style experiments
+// ---------------------------------------------------------------------------
+
+export interface FlagDefinition {
+  /** Unique slug for the flag. */
+  slug: string;
+  /** Human-readable name. */
+  name: string;
+  /** Percentage of traffic to enable the flag for (0–100). Default: 0 (off). */
+  rolloutPercent?: number;
+  /** Targeting rules. */
+  targeting?: Experiment["targeting"];
+  /** Value returned when the flag is disabled. Default: false. */
+  offValue?: unknown;
+  /** Value returned when the flag is enabled. Default: true. */
+  onValue?: unknown;
+}
+
+/**
+ * Create a flag-style experiment with two variations: control (OFF) and enabled (ON).
+ */
+export function defineFlagExperiment(def: FlagDefinition): Experiment & { slug: string } {
+  const rollout = Math.max(0, Math.min(100, def.rolloutPercent ?? 0)) / 100;
+
+  const flag = defineExperiment({
+    slug: def.slug,
+    name: def.name,
+    trafficAllocation: 1,
+    targeting: def.targeting,
+    variations: [
+      {
+        id: "control",
+        weight: 1 - rollout,
+        mutations: [],
+        isControl: true,
+        value: def.offValue ?? false,
+      },
+      {
+        id: "enabled",
+        weight: rollout,
+        mutations: [],
+        value: def.onValue ?? true,
+      },
+    ],
+  });
+
+  return {
+    ...flag,
+    variations: flag.variations.map((variation) => ({ ...variation })),
+    featureFlag: { key: def.slug },
+  };
+}

package/src/goals.test.ts

@@ -0,0 +1,42 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { setupGoals } from "./goals";
+import { setJsPolicy } from "./js";
+
+const assignment = { experimentId: "exp", variationId: "var" } as const;
+const experiment = {
+  id: "exp",
+  goals: [{
+    id: "goal", type: "click" as const, selector: "button",
+    capture: [
+      { property: "customer_email", source: "attribute" as const, attribute: "data-email" },
+      { property: "product_id", source: "dataset" as const, attribute: "data-product-id" },
+    ],
+  }],
+};
+
+describe("goal capture policy", () => {
+  afterEach(() => {
+    setupGoals([], [], vi.fn());
+    setJsPolicy("hybrid");
+    document.body.innerHTML = "";
+  });
+
+  it("drops PII-shaped captures only under strict policy", () => {
+    document.body.innerHTML = '<button data-email="person@example.com" data-product-id="123">Buy</button>';
+    const button = document.querySelector("button")!;
+    const strictCallback = vi.fn();
+    setJsPolicy("strict");
+    setupGoals([assignment], [experiment], strictCallback);
+    button.click();
+    expect(strictCallback).toHaveBeenCalledWith("goal", assignment, { product_id: "123" });
+
+    const legacyCallback = vi.fn();
+    setJsPolicy("hybrid");
+    setupGoals([assignment], [experiment], legacyCallback);
+    button.click();
+    expect(legacyCallback).toHaveBeenCalledWith("goal", assignment, {
+      customer_email: "person@example.com", product_id: "123",
+    });
+  });
+});

package/src/goals.ts

@@ -0,0 +1,200 @@
+import { Goal, Assignment, CaptureRule } from "./types";
+import { safeRegexTest } from "./safe-regex";
+import { containsPiiToken } from "./pii-keys";
+import { isStrictJsPolicy } from "./js";
+
+type GoalCallback = (
+  goalId: string,
+  assignment: Assignment,
+  data?: Record<string, unknown>,
+) => void;
+
+const STORAGE_KEY = "drip_goals";
+let onGoal: GoalCallback | null = null;
+let clickListener: ((e: Event) => void) | null = null;
+let activeClickGoals: { goal: Goal; assignment: Assignment }[] = [];
+
+function getFiredGoals(): Record<string, string[]> {
+  try {
+    return JSON.parse(localStorage.getItem(STORAGE_KEY) || "{}");
+  } catch {
+    return {};
+  }
+}
+
+function markFired(goalId: string, variationId: string): void {
+  const fired = getFiredGoals();
+  const list = fired[goalId] || [];
+  if (!list.includes(variationId)) {
+    list.push(variationId);
+    fired[goalId] = list;
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(fired));
+    } catch {}
+  }
+}
+
+function alreadyFired(goalId: string, variationId: string): boolean {
+  const fired = getFiredGoals();
+  return (fired[goalId] || []).includes(variationId);
+}
+
+function fireGoal(
+  goal: Goal,
+  assignment: Assignment,
+  data?: Record<string, unknown>,
+): void {
+  if (goal.countOnce && alreadyFired(goal.id, assignment.variationId)) return;
+  if (goal.countOnce) markFired(goal.id, assignment.variationId);
+  if (onGoal) onGoal(goal.id, assignment, data);
+}
+
+/**
+ * Extract captured values from a matched element based on capture rules.
+ * Values are sent as event properties alongside the goal event.
+ */
+function extractCapturedValues(
+  el: Element,
+  capture?: CaptureRule[],
+): Record<string, unknown> {
+  if (!capture?.length) return {};
+  const data: Record<string, unknown> = {};
+  for (const rule of capture) {
+    if (isStrictJsPolicy() && (containsPiiToken(rule.property) ||
+        (rule.attribute && containsPiiToken(rule.attribute)))) continue;
+    if (rule.source === "attribute" && rule.attribute) {
+      data[rule.property] = el.getAttribute(rule.attribute);
+    } else if (rule.source === "textContent") {
+      data[rule.property] = (el.textContent || "").trim().slice(0, 500);
+    } else if (rule.source === "dataset" && rule.attribute) {
+      // Convert "data-product-id" → "productId" for dataset access
+      const key = rule.attribute
+        .replace(/^data-/, "")
+        .replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+      data[rule.property] = (el as HTMLElement).dataset?.[key] ?? null;
+    }
+  }
+  return data;
+}
+
+function textMatches(el: Element, text: string): boolean {
+  return (el.textContent || "")
+    .trim()
+    .toLowerCase()
+    .includes(text.trim().toLowerCase());
+}
+
+function findByText(start: Element, text: string): Element | null {
+  let el: Element | null = start;
+  const needle = text.trim().toLowerCase();
+  while (el && el !== document.documentElement) {
+    if ((el.textContent || "").trim().toLowerCase().includes(needle)) return el;
+    el = el.parentElement;
+  }
+  return null;
+}
+
+function handleClick(e: Event): void {
+  const target = e.target as Element;
+  if (!target?.closest) return;
+  for (const entry of activeClickGoals) {
+    const { selector, textMatch } = entry.goal;
+    if (!selector && !textMatch) continue;
+
+    let matched: Element | null = null;
+
+    if (selector) {
+      matched = target.closest(selector);
+      if (!matched) continue;
+      // If textMatch is also set, verify the text
+      if (textMatch && !textMatches(matched, textMatch)) continue;
+    } else if (textMatch) {
+      // No CSS selector — walk up from target checking text
+      matched = findByText(target, textMatch);
+      if (!matched) continue;
+    }
+
+    const captured = extractCapturedValues(matched!, entry.goal.capture);
+    fireGoal(entry.goal, entry.assignment, captured);
+  }
+}
+
+export function setupGoals(
+  assignments: Assignment[],
+  experiments: { id: string; goals?: Goal[] }[],
+  callback: GoalCallback,
+): void {
+  onGoal = callback;
+  activeClickGoals = [];
+
+  if (clickListener) {
+    document.removeEventListener("click", clickListener, true);
+    clickListener = null;
+  }
+
+  const expMap = new Map(experiments.map((e) => [e.id, e]));
+  let hasClickGoals = false;
+
+  for (const assignment of assignments) {
+    const exp = expMap.get(assignment.experimentId);
+    if (!exp?.goals) continue;
+    for (const goal of exp.goals) {
+      if (goal.type === "click" && (goal.selector || goal.textMatch)) {
+        activeClickGoals.push({ goal, assignment });
+        hasClickGoals = true;
+      }
+      if (goal.type === "pageview") {
+        if (!goal.urlPattern || safeRegexTest(goal.urlPattern, location.href)) {
+          fireGoal(goal, assignment);
+        }
+      }
+    }
+  }
+
+  if (hasClickGoals) {
+    clickListener = handleClick;
+    document.addEventListener("click", clickListener, true);
+  }
+}
+
+export function triggerGoal(
+  goalId: string,
+  assignments: Assignment[],
+  experiments: { id: string; goals?: Goal[] }[],
+  data?: Record<string, unknown>,
+): void {
+  const expMap = new Map(experiments.map((e) => [e.id, e]));
+  for (const assignment of assignments) {
+    const exp = expMap.get(assignment.experimentId);
+    if (!exp?.goals) continue;
+    const goal = exp.goals.find((g) => g.id === goalId);
+    if (goal) fireGoal(goal, assignment, data);
+  }
+}
+
+export function triggerGoalsForEvent(
+  eventName: string,
+  assignments: Assignment[],
+  experiments: { id: string; goals?: Goal[] }[],
+  data?: Record<string, unknown>,
+): void {
+  if (!eventName) return;
+  const expMap = new Map(experiments.map((e) => [e.id, e]));
+  for (const assignment of assignments) {
+    const exp = expMap.get(assignment.experimentId);
+    if (!exp?.goals) continue;
+    for (const goal of exp.goals) {
+      if (goal.type === "custom" && goal.eventName === eventName) {
+        fireGoal(goal, assignment, data);
+      }
+    }
+  }
+}
+
+export function cleanupGoals(): void {
+  activeClickGoals = [];
+  if (clickListener) {
+    document.removeEventListener("click", clickListener, true);
+    clickListener = null;
+  }
+}

package/src/guards.test.ts

@@ -0,0 +1,249 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { __test, getQaSessionId, isQaMode, isScreenshotMode } from "./guards";
+
+const { parseForceString, parseForceParams, sanitizeQaSessionId, BOT_RE } = __test;
+
+describe("parseForceString", () => {
+  it("parses a single pair", () => {
+    expect(parseForceString("exp1:var1")).toEqual({ exp1: "var1" });
+  });
+
+  it("parses multiple comma-separated pairs", () => {
+    expect(parseForceString("exp1:var1,exp2:var2")).toEqual({
+      exp1: "var1",
+      exp2: "var2",
+    });
+  });
+
+  it("returns null for empty string", () => {
+    expect(parseForceString("")).toBeNull();
+  });
+
+  it("returns null for malformed input without colon", () => {
+    expect(parseForceString("nocolon")).toBeNull();
+  });
+
+  it("parses valid pairs even with trailing comma", () => {
+    const result = parseForceString("exp1:var1,");
+    expect(result).toEqual({ exp1: "var1" });
+  });
+
+  it("returns null for only commas", () => {
+    expect(parseForceString(",,")).toBeNull();
+  });
+
+  it("returns null when colon only (both expId and varId are empty)", () => {
+    // ":" → split by "," gives [":"], split ":" gives ["", ""]
+    // expId = "" is falsy, so it's skipped → empty map → null
+    expect(parseForceString(":")).toBeNull();
+  });
+});
+
+describe("parseForceParams", () => {
+  it("keeps supporting canonical drip_force pairs", () => {
+    expect(
+      parseForceParams(
+        new URLSearchParams("drip_force=exp_1%3Avar_1%2Cexp_2%3Avar_2"),
+      ),
+    ).toEqual({
+      exp_1: "var_1",
+      exp_2: "var_2",
+    });
+  });
+
+  it("accepts direct experiment and variation id params", () => {
+    expect(
+      parseForceParams(
+        new URLSearchParams("drip_experiment_id=exp_1&drip_variation_id=var_1"),
+      ),
+    ).toEqual({ exp_1: "var_1" });
+  });
+
+  it("prefers canonical drip_force over aliased ids", () => {
+    expect(
+      parseForceParams(
+        new URLSearchParams(
+          "drip_force=exp_canonical%3Avar_canonical&drip_experiment_id=exp_alias&drip_variation_id=var_alias",
+        ),
+      ),
+    ).toEqual({ exp_canonical: "var_canonical" });
+  });
+});
+
+describe("BOT_RE", () => {
+  it("detects googlebot", () => {
+    expect(BOT_RE.test("Mozilla/5.0 (compatible; Googlebot/2.1)")).toBe(true);
+  });
+
+  it("detects bingpreview", () => {
+    expect(BOT_RE.test("Mozilla/5.0 BingPreview/1.0b")).toBe(true);
+  });
+
+  it("detects facebookexternalhit", () => {
+    expect(BOT_RE.test("facebookexternalhit/1.1")).toBe(true);
+  });
+
+  it("detects slurp", () => {
+    expect(BOT_RE.test("Mozilla/5.0 (compatible; Yahoo! Slurp)")).toBe(true);
+  });
+
+  it("detects crawler", () => {
+    expect(BOT_RE.test("my-crawler/1.0")).toBe(true);
+  });
+
+  it("rejects normal Chrome UA", () => {
+    expect(
+      BOT_RE.test(
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/120.0.0.0 Safari/537.36",
+      ),
+    ).toBe(false);
+  });
+
+  it("rejects empty string", () => {
+    expect(BOT_RE.test("")).toBe(false);
+  });
+
+  it("is case insensitive", () => {
+    expect(BOT_RE.test("GOOGLEBOT")).toBe(true);
+  });
+
+  it("detects spider", () => {
+    expect(BOT_RE.test("Mozilla/5.0 (compatible; spider/1.0)")).toBe(true);
+  });
+
+  it("detects robot", () => {
+    expect(BOT_RE.test("my-robot/2.0")).toBe(true);
+  });
+
+  it("detects crawling", () => {
+    expect(BOT_RE.test("web-crawling-agent")).toBe(true);
+  });
+});
+
+describe("isScreenshotMode", () => {
+  const originalLocation = Object.getOwnPropertyDescriptor(globalThis, "location");
+
+  function setSearch(search: string) {
+    Object.defineProperty(globalThis, "location", {
+      configurable: true,
+      value: { search },
+    });
+  }
+
+  afterEach(() => {
+    if (originalLocation) {
+      Object.defineProperty(globalThis, "location", originalLocation);
+    } else {
+      delete (globalThis as any).location;
+    }
+  });
+
+  it("accepts drip_screenshot=1", () => {
+    setSearch("?drip_screenshot=1");
+    expect(isScreenshotMode()).toBe(true);
+  });
+
+  it("accepts drip_screenshot=true", () => {
+    setSearch("?drip_screenshot=true");
+    expect(isScreenshotMode()).toBe(true);
+  });
+
+  it("is off by default", () => {
+    setSearch("?drip_qa=1");
+    expect(isScreenshotMode()).toBe(false);
+  });
+});
+
+describe("isQaMode", () => {
+  const originalLocation = Object.getOwnPropertyDescriptor(globalThis, "location");
+  const originalDocument = Object.getOwnPropertyDescriptor(globalThis, "document");
+
+  function setSearch(search: string) {
+    Object.defineProperty(globalThis, "location", {
+      configurable: true,
+      value: { search },
+    });
+  }
+
+  afterEach(() => {
+    if (originalDocument) {
+      Object.defineProperty(globalThis, "document", originalDocument);
+    } else {
+      delete (globalThis as any).document;
+    }
+    if (originalLocation) {
+      Object.defineProperty(globalThis, "location", originalLocation);
+    } else {
+      delete (globalThis as any).location;
+    }
+  });
+
+  it("lets screenshot mode override a persisted QA force cookie", () => {
+    Object.defineProperty(globalThis, "document", {
+      configurable: true,
+      value: { cookie: "drip_qa_force=exp_1%3Avar_1" },
+    });
+    setSearch("?drip_screenshot=1");
+
+    expect(isScreenshotMode()).toBe(true);
+    expect(isQaMode()).toBe(false);
+  });
+});
+
+describe("QA session IDs", () => {
+  const originalLocation = Object.getOwnPropertyDescriptor(globalThis, "location");
+  const originalSessionStorage = Object.getOwnPropertyDescriptor(globalThis, "sessionStorage");
+
+  function setSearch(search: string) {
+    Object.defineProperty(globalThis, "location", {
+      configurable: true,
+      value: { search },
+    });
+  }
+
+  function installSessionStorage() {
+    const values = new Map<string, string>();
+    Object.defineProperty(globalThis, "sessionStorage", {
+      configurable: true,
+      value: {
+        getItem: (key: string) => values.get(key) ?? null,
+        setItem: (key: string, value: string) => {
+          values.set(key, value);
+        },
+        removeItem: (key: string) => {
+          values.delete(key);
+        },
+      },
+    });
+  }
+
+  afterEach(() => {
+    if (originalLocation) {
+      Object.defineProperty(globalThis, "location", originalLocation);
+    } else {
+      delete (globalThis as any).location;
+    }
+    if (originalSessionStorage) {
+      Object.defineProperty(globalThis, "sessionStorage", originalSessionStorage);
+    } else {
+      delete (globalThis as any).sessionStorage;
+    }
+  });
+
+  it("accepts safe run IDs from the URL", () => {
+    setSearch("?drip_qa_session=run_123-abc");
+    installSessionStorage();
+    expect(getQaSessionId(() => "generated")).toBe("run_123-abc");
+  });
+
+  it("falls back for unsafe run IDs", () => {
+    setSearch("?drip_qa_session=<script>");
+    installSessionStorage();
+    expect(getQaSessionId(() => "generated")).toBe("generated");
+  });
+
+  it("sanitizes QA session IDs", () => {
+    expect(sanitizeQaSessionId("abc_123-xyz")).toBe("abc_123-xyz");
+    expect(sanitizeQaSessionId("no spaces")).toBeNull();
+  });
+});