@drip-apex/sdk 0.1.0

package/src/personalization.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { evaluate } from "./index";
+import type { Experiment } from "./types";
+
+function personalizationRule(id: string, ruleId: string, stopAfterMatch: boolean): Experiment {
+  return {
+    id,
+    kind: "personalization",
+    status: "running",
+    trafficAllocation: 1,
+    personalization: {
+      id: "personalization_1",
+      key: "homepage-banner",
+      ruleId,
+      experienceId: `${ruleId}_experience`,
+      surface: "home",
+      templateKey: "hero",
+      priority: ruleId === "rule_first" ? 10 : 20,
+      stopAfterMatch,
+    },
+    variations: [
+      {
+        id: `${ruleId}_variant`,
+        weight: 1,
+        mutations: [],
+        value: { ruleId },
+      },
+    ],
+  };
+}
+
+describe("personalization assignment ordering", () => {
+  it("keeps the first matching rule when stopAfterMatch is enabled", () => {
+    const assignments = evaluate(
+      [
+        personalizationRule("personalization:homepage-banner:rule_first", "rule_first", true),
+        personalizationRule("personalization:homepage-banner:rule_second", "rule_second", true),
+      ],
+      {
+        url: "https://shop.test/",
+        attributes: { "page.type": "home" },
+        userId: "visitor-1",
+      },
+    );
+
+    expect(assignments).toHaveLength(1);
+    expect(assignments[0]?.personalization?.ruleId).toBe("rule_first");
+  });
+
+  it("allows lower-priority rules when the earlier rule does not stop matching", () => {
+    const assignments = evaluate(
+      [
+        personalizationRule("personalization:homepage-banner:rule_first", "rule_first", false),
+        personalizationRule("personalization:homepage-banner:rule_second", "rule_second", true),
+      ],
+      {
+        url: "https://shop.test/",
+        attributes: { "page.type": "home" },
+        userId: "visitor-1",
+      },
+    );
+
+    expect(assignments.map((assignment) => assignment.personalization?.ruleId)).toEqual([
+      "rule_first",
+      "rule_second",
+    ]);
+  });
+});

package/src/pii-keys.ts

@@ -0,0 +1,17 @@
+const PII_KEY_TOKENS = new Set([
+  "email", "mail", "phone", "tel", "mobile", "fax",
+  "address", "street", "zip", "postal", "postcode",
+  "firstname", "lastname", "fullname", "surname", "username", "name",
+  "birth", "birthday", "birthdate", "dob", "gender",
+  "ssn", "vat", "iban", "bic", "card", "cvv", "cvc",
+  "password", "passwd", "secret", "token", "auth", "session",
+  "ip", "latitude", "longitude", "lat", "lng", "lon",
+]);
+
+export function containsPiiToken(key: string): boolean {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .some((token) => PII_KEY_TOKENS.has(token));
+}

package/src/prerequisites.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { buildPrerequisiteContext, evaluateProjectPrerequisite } from "./prerequisites";
+
+const baseConfig = {
+  experiments: [],
+  requireConsent: true,
+  hasConsent: false,
+  url: "https://example.com/products/a",
+};
+
+describe("project prerequisites", () => {
+  it("evaluates built-in rules without using dynamic code execution", () => {
+    const context = buildPrerequisiteContext(baseConfig, "visitor_1", true, false, "start_tracking");
+    const OriginalFunction = globalThis.Function;
+    try {
+      (globalThis as any).Function = function Function() {
+        throw new Error("unsafe-eval blocked");
+      };
+
+      expect(evaluateProjectPrerequisite("return true;", context, false)).toBe(true);
+      expect(evaluateProjectPrerequisite("return false;", context, true)).toBe(false);
+      expect(evaluateProjectPrerequisite("return drip.get('trackingConsentEnabled');", context, true)).toBe(false);
+      expect(evaluateProjectPrerequisite("return context.consentGranted;", context, true)).toBe(false);
+    } finally {
+      (globalThis as any).Function = OriginalFunction;
+    }
+  });
+
+  it("still supports custom rules when dynamic execution is available", () => {
+    const context = buildPrerequisiteContext(baseConfig, "visitor_1", true, true, "show_variations");
+    expect(
+      evaluateProjectPrerequisite(
+        "return drip.get('url').includes('/products/') && drip.get('consentGranted');",
+        context,
+        false,
+      ),
+    ).toBe(true);
+  });
+});

package/src/prerequisites.ts

@@ -0,0 +1,94 @@
+import { debugWarn } from "./debug";
+import type { InitConfig } from "./types";
+
+declare const __DRIP_FEATURE_DEVTOOLS__: boolean;
+
+type PrerequisiteContext = {
+  type: "show_variations" | "start_tracking";
+  url: string;
+  attributes: Record<string, unknown>;
+  userId: string | null;
+  consentRequired: boolean;
+  consentGranted: boolean;
+};
+
+function getWindowValue(key: string): unknown {
+  const w = globalThis as Record<string, unknown>;
+  return w[key] ?? (w.__drip as Record<string, unknown> | undefined)?.[key];
+}
+
+function buildRuleApi(context: PrerequisiteContext) {
+  return {
+    get(key: string): unknown {
+      if (key === "trackingConsentEnabled") {
+        return !context.consentRequired || context.consentGranted;
+      }
+      if (key === "consentGranted") return context.consentGranted;
+      if (key === "url") return context.url;
+      if (key === "userId") return context.userId;
+      return getWindowValue(key);
+    },
+    context,
+  };
+}
+
+function normalizeSimpleRule(code: string): string {
+  return code.trim().replace(/\s+/g, " ").replace(/;+$/, "");
+}
+
+function evaluateKnownRule(code: string, context: PrerequisiteContext): boolean | null {
+  const normalized = normalizeSimpleRule(code);
+  if (normalized === "return true") return true;
+  if (normalized === "return false") return false;
+  if (normalized === "return context.consentGranted") return context.consentGranted;
+  if (normalized === "return !context.consentRequired || context.consentGranted") {
+    return !context.consentRequired || context.consentGranted;
+  }
+
+  const getterMatch = normalized.match(/^return\s+(?:drip|Drip)\.get\(['"]([a-zA-Z0-9_.-]+)['"]\)$/);
+  if (getterMatch) {
+    const api = buildRuleApi(context);
+    return api.get(getterMatch[1]) === true;
+  }
+
+  return null;
+}
+
+export function evaluateProjectPrerequisite(
+  rule: string | undefined,
+  context: PrerequisiteContext,
+  fallback: boolean,
+): boolean {
+  const code = (rule ?? "").trim();
+  if (!code) return fallback;
+  const knownResult = evaluateKnownRule(code, context);
+  if (knownResult != null) return knownResult;
+  try {
+    const api = buildRuleApi(context);
+    const fn = new Function("context", "drip", "Drip", code);
+    const result = fn.call(globalThis, context, api, api);
+    return result === true;
+  } catch (err) {
+    __DRIP_FEATURE_DEVTOOLS__ && debugWarn("prerequisite", `${context.type} rule failed; failing closed`, {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return false;
+  }
+}
+
+export function buildPrerequisiteContext(
+  config: InitConfig,
+  userId: string | null,
+  consentRequired: boolean,
+  consentGranted: boolean,
+  type: PrerequisiteContext["type"],
+): PrerequisiteContext {
+  return {
+    type,
+    url: config.url ?? location.href,
+    attributes: config.attributes ?? {},
+    userId,
+    consentRequired,
+    consentGranted,
+  };
+}

package/src/qa-assistant-state.test.ts

@@ -0,0 +1,471 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { QaAssistantStore } from "./qa-assistant-state";
+
+type RuntimeSnapshot = ReturnType<typeof baseSnapshot>;
+
+let snapshot: RuntimeSnapshot;
+let runtimeListener: (() => void) | null = null;
+let devtoolsListener: ((event: { ts: number; type: string; label: string; detail?: Record<string, unknown> }) => void) | null = null;
+let forceMock: ReturnType<typeof vi.fn>;
+let resetMock: ReturnType<typeof vi.fn>;
+
+function baseSnapshot() {
+  return {
+    config: {
+      profile: { platform: "spa" as const, version: 1 as const },
+      experiments: [
+        {
+          id: "exp_123456789",
+          name: "Checkout CTA",
+          status: "running",
+          variations: [
+            { id: "var_control", name: "Control", weight: 0.5, mutations: [], isControl: true },
+            { id: "var_b", name: "Variant B", weight: 0.5, mutations: [] },
+          ],
+        },
+      ],
+    },
+    assignments: [
+      {
+        experimentId: "exp_123456789",
+        experimentName: "Checkout CTA",
+        variationId: "var_b",
+        index: 1,
+        mutations: [],
+        isControl: false,
+        hashValue: "visitor_1",
+      },
+    ],
+    activationDiagnostics: {
+      project: { gates: [] },
+      experiments: [
+        {
+          experimentId: "exp_123456789",
+          experimentName: "Checkout CTA",
+          status: "passed" as const,
+          assignedVariationId: "var_b",
+          assignedVariationIndex: 1,
+          forced: false,
+          gates: [],
+          targetingConditions: [],
+        },
+      ],
+    },
+    forceMap: null as Record<string, string> | null,
+    platform: "spa" as const,
+    qaMode: true,
+    orderIdentity: null as {
+      platform: "shopify" | "shopware" | "woocommerce" | "centra" | "custom";
+      platformOrderId: string | null;
+      orderNumber: string | null;
+    } | null,
+  };
+}
+
+async function loadStore(): Promise<QaAssistantStore> {
+  vi.resetModules();
+  snapshot = baseSnapshot();
+  runtimeListener = null;
+  devtoolsListener = null;
+  forceMock = vi.fn((experimentId: string, variationId: string) => {
+    snapshot.forceMap = { ...(snapshot.forceMap ?? {}), [experimentId]: variationId };
+    snapshot.assignments = snapshot.assignments.map((assignment) =>
+      assignment.experimentId === experimentId ? { ...assignment, variationId } : assignment
+    );
+    snapshot.activationDiagnostics.experiments = snapshot.activationDiagnostics.experiments.map(
+      (diagnostic) => diagnostic.experimentId === experimentId
+        ? {
+            ...diagnostic,
+            assignedVariationId: variationId,
+            forced: true,
+            reason: "forced_variation",
+          }
+        : diagnostic,
+    );
+    runtimeListener?.();
+  });
+  resetMock = vi.fn((experimentId?: string) => {
+    if (!experimentId) {
+      snapshot.forceMap = null;
+    } else if (snapshot.forceMap) {
+      const next = { ...snapshot.forceMap };
+      delete next[experimentId];
+      snapshot.forceMap = Object.keys(next).length ? next : null;
+    }
+    runtimeListener?.();
+  });
+
+  vi.doMock("./index", () => ({
+    __getQaAssistantRuntimeSnapshot: () => snapshot,
+    __subscribeQaAssistantRuntime: (listener: () => void) => {
+      runtimeListener = listener;
+      return () => {
+        runtimeListener = null;
+      };
+    },
+    __forceQaAssistantVariation: forceMock,
+    __resetQaAssistantForce: resetMock,
+  }));
+  vi.doMock("./devtools", () => ({
+    subscribeDevtoolsEvents: (listener: typeof devtoolsListener) => {
+      devtoolsListener = listener;
+      return () => {
+        devtoolsListener = null;
+      };
+    },
+  }));
+  vi.doMock("./guards", () => ({
+    exitQaMode: vi.fn(),
+  }));
+
+  const { createQaAssistantStore } = await import("./qa-assistant-state");
+  return createQaAssistantStore();
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.resetModules();
+  vi.unstubAllGlobals();
+});
+
+describe("createQaAssistantStore", () => {
+  it("maps condition diagnostics to pass, fail, skip, and error rows with raw JS", async () => {
+    const store = await loadStore();
+    snapshot.assignments = [];
+    snapshot.activationDiagnostics.experiments = [
+      {
+        experimentId: "exp_123456789",
+        experimentName: "Checkout CTA",
+        status: "failed",
+        reason: "targeting_mismatch",
+        forced: false,
+        gates: [],
+        targetingConditions: [
+          {
+            id: "url:0",
+            label: "URL include rule",
+            status: "passed",
+            expected: "/products/*",
+            actual: "https://shop.test/products/book",
+            source: "/products/*",
+            sourceType: "url",
+          },
+          {
+            id: "attribute:visitor_type:0",
+            label: "Attribute rule: visitor_type",
+            status: "failed",
+            reason: "attribute_mismatch",
+            expected: "returning",
+            actual: "new",
+            source: "visitor_type",
+            sourceType: "attribute",
+          },
+          {
+            id: "segment:vip:1",
+            label: "VIP segment: spend",
+            status: "skipped",
+            reason: "segment_and_failed",
+            source: "vip",
+            sourceType: "segment",
+          },
+          {
+            id: "page:js_rule",
+            label: "JS gate",
+            status: "failed",
+            reason: "js_error: bad trigger",
+            actual: false,
+            source: "throw new Error('bad trigger')",
+            sourceType: "js",
+          },
+        ],
+      },
+    ];
+    runtimeListener?.();
+
+    const experiment = store.getState().experiments[0]!;
+    expect(experiment.applied).toBe(false);
+    expect(experiment.conditions).toEqual([
+      expect.objectContaining({
+        id: "url:0",
+        state: "pass",
+        text: "URL include rule",
+        detail: "Expected: /products/* · Actual: https://shop.test/products/book",
+        rawCode: null,
+      }),
+      expect.objectContaining({
+        id: "attribute:visitor_type:0",
+        state: "fail",
+        text: "Attribute rule: visitor_type",
+        detail: "Expected: returning · Actual: new",
+      }),
+      expect.objectContaining({
+        id: "segment:vip:1",
+        state: "skip",
+        detail: "Skipped — segment_and_failed failed first",
+      }),
+      expect.objectContaining({
+        id: "page:js_rule",
+        state: "error",
+        text: "Custom JS trigger",
+        detail: "bad trigger",
+        rawCode: "throw new Error('bad trigger')",
+      }),
+    ]);
+  });
+
+  it("maps trigger, segment, and display-frequency pills without raw reason codes", async () => {
+    const store = await loadStore();
+    snapshot.assignments = [];
+    snapshot.activationDiagnostics.experiments[0] = {
+      ...snapshot.activationDiagnostics.experiments[0],
+      status: "failed",
+      reason: "outside_allocation",
+      targetingConditions: [
+        { id: "url:0", label: "Product pages", status: "passed", sourceType: "url" },
+        { id: "segment:vip:0", label: "VIP", status: "failed", sourceType: "segment" },
+      ],
+    };
+    runtimeListener?.();
+    expect(store.getState().experiments[0]).toMatchObject({
+      triggerPill: "accepted",
+      segmentPill: "rejected",
+      displayFrequencyPill: "outside traffic %",
+    });
+
+    for (const [reason, expected] of [
+      ["personalization_stopped_after_prior_match", "personalization stop"],
+      ["exclusion_group_overlap_lost", "excluded by overlap"],
+      ["exclusion_group_sticky_other", "excluded by overlap"],
+      ["status_paused", "not running"],
+    ] as const) {
+      snapshot.activationDiagnostics.experiments[0].reason = reason;
+      runtimeListener?.();
+      expect(store.getState().experiments[0].displayFrequencyPill).toBe(expected);
+    }
+    // A mere force REQUEST is not enough — the pill needs evidence the force
+    // took effect (forced diagnostic); a targeting-blocked force stays honest.
+    snapshot.forceMap = { exp_123456789: "var_b" };
+    runtimeListener?.();
+    expect(store.getState().experiments[0].displayFrequencyPill).not.toBe("forced");
+    snapshot.activationDiagnostics.experiments[0] = {
+      ...snapshot.activationDiagnostics.experiments[0],
+      forced: true,
+      reason: "forced_variation",
+    };
+    runtimeListener?.();
+    expect(store.getState().experiments[0].displayFrequencyPill).toBe("forced");
+  });
+
+  it("marks unevaluated campaigns and skipped display checks as not evaluated", async () => {
+    const store = await loadStore();
+    // Paused / no-variations: evaluation returns before targeting and traffic
+    // gates exist — configured rules were never checked.
+    snapshot.assignments = [];
+    snapshot.activationDiagnostics.experiments[0] = {
+      ...snapshot.activationDiagnostics.experiments[0],
+      status: "failed",
+      reason: "status_paused",
+      gates: [],
+      targetingConditions: [],
+    };
+    runtimeListener?.();
+    expect(store.getState().experiments[0]).toMatchObject({
+      triggerPill: "not evaluated",
+      segmentPill: "not evaluated",
+      displayFrequencyPill: "not running",
+    });
+
+    // Targeting rejection: the traffic gate never ran, so display frequency
+    // must not claim acceptance.
+    snapshot.activationDiagnostics.experiments[0] = {
+      ...snapshot.activationDiagnostics.experiments[0],
+      reason: "url_mismatch",
+      gates: [
+        { id: "page", label: "Page check", status: "failed", reason: "url_mismatch" },
+        { id: "audience", label: "Audience check", status: "skipped", reason: "page_mismatch" },
+      ],
+    };
+    runtimeListener?.();
+    expect(store.getState().experiments[0].displayFrequencyPill).toBe("not evaluated");
+
+    snapshot.activationDiagnostics.experiments[0].gates = [
+      { id: "page", label: "Page check", status: "passed", reason: "url_matched" },
+      { id: "traffic", label: "Traffic allocation", status: "passed", reason: "included" },
+    ];
+    snapshot.activationDiagnostics.experiments[0].reason = undefined;
+    runtimeListener?.();
+    expect(store.getState().experiments[0].displayFrequencyPill).toBe("accepted");
+  });
+
+  it("derives targeting pills from aggregate OR gates and preserves no-rules labels", async () => {
+    const store = await loadStore();
+    snapshot.activationDiagnostics.experiments[0] = {
+      ...snapshot.activationDiagnostics.experiments[0],
+      gates: [
+        { id: "page", label: "Page check", status: "passed", reason: "url_matched" },
+        { id: "audience", label: "Audience check", status: "passed", reason: "audience_matched" },
+      ],
+      targetingConditions: [
+        { id: "url:0", label: "First alternative", status: "failed", sourceType: "url" },
+        { id: "url:1", label: "Second alternative", status: "passed", sourceType: "url" },
+        { id: "segment:vip:0", label: "VIP", status: "failed", sourceType: "segment" },
+        { id: "segment:local:1", label: "Local", status: "passed", sourceType: "segment" },
+      ],
+    };
+    runtimeListener?.();
+    expect(store.getState().experiments[0]).toMatchObject({
+      triggerPill: "accepted",
+      segmentPill: "accepted",
+    });
+
+    snapshot.activationDiagnostics.experiments[0].gates = [
+      { id: "page", label: "Page check", status: "skipped", reason: "no_page_rules" },
+      { id: "audience", label: "Audience check", status: "skipped", reason: "no_audience_rules" },
+    ];
+    snapshot.activationDiagnostics.experiments[0].targetingConditions = [];
+    runtimeListener?.();
+    expect(store.getState().experiments[0]).toMatchObject({
+      triggerPill: "all pages",
+      segmentPill: "all visitors",
+    });
+  });
+
+  it("marks skipped targeting as not evaluated when an earlier gate prevented evaluation", async () => {
+    const store = await loadStore();
+    snapshot.activationDiagnostics.experiments[0] = {
+      ...snapshot.activationDiagnostics.experiments[0],
+      gates: [
+        { id: "page", label: "Page check", status: "failed", reason: "page_mismatch" },
+        { id: "audience", label: "Audience check", status: "skipped", reason: "page_mismatch" },
+      ],
+      targetingConditions: [
+        { id: "url:0", label: "Product pages", status: "failed", sourceType: "url" },
+        { id: "segment:vip:0", label: "VIP", status: "skipped", sourceType: "segment", reason: "page_mismatch" },
+      ],
+    };
+    runtimeListener?.();
+    expect(store.getState().experiments[0].segmentPill).toBe("not evaluated");
+
+    snapshot.activationDiagnostics.experiments[0].gates = [];
+    runtimeListener?.();
+    expect(store.getState().experiments[0].segmentPill).toBe("not evaluated");
+  });
+
+  it("shows page patterns alongside raw JS without relabeling plain JS", async () => {
+    const store = await loadStore();
+    const patterns = JSON.stringify([{ include: true, matchType: "simple", pattern: "/products/*" }]);
+    snapshot.activationDiagnostics.experiments[0].targetingConditions = [{
+      id: "page:products",
+      label: "Products",
+      status: "passed",
+      sourceType: "js",
+      source: "return true;",
+      expected: patterns,
+      actual: true,
+    }];
+    runtimeListener?.();
+    expect(store.getState().experiments[0].conditions[0]).toMatchObject({
+      detail: `Rules: ${patterns} · Actual: true`,
+      rawCode: "return true;",
+    });
+  });
+
+  it("marks the newer duplicate event within 1500ms", async () => {
+    const store = await loadStore();
+
+    devtoolsListener?.({
+      ts: 1000,
+      type: "track",
+      label: "goal",
+      detail: { goalId: "signup" },
+    });
+    devtoolsListener?.({
+      ts: 2200,
+      type: "track",
+      label: "goal",
+      detail: { goalId: "signup" },
+    });
+
+    expect(store.getState().events).toEqual([
+      { at: 1000, type: "goal", label: "signup", value: null },
+      { at: 2200, type: "goal", label: "signup", value: null, duplicateOf: 1000 },
+    ]);
+  });
+
+  it("chooses unsupported, shopify, and order transaction models from runtime signals", async () => {
+    const store = await loadStore();
+    expect(store.getState().transactions).toEqual({ kind: "unsupported" });
+
+    vi.stubGlobal("window", { Shopify: {} });
+    vi.stubGlobal("fetch", vi.fn(async () => Response.json({
+      attributes: {
+        apex_assignments: JSON.stringify([{ e: "exp_123456789", v: "var_b" }]),
+      },
+    })) as unknown as typeof fetch);
+    snapshot.platform = "shopify";
+    snapshot.config.profile = { platform: "shopify", version: 1 };
+    runtimeListener?.();
+    await vi.waitFor(() => {
+      expect(store.getState().transactions).toEqual({
+        kind: "shopify",
+        cartStamped: true,
+        variationName: "Variant B",
+        stampedAt: null,
+        attribution: [{ experimentName: "Checkout CTA", variationName: "Variant B" }],
+      });
+    });
+
+    snapshot.orderIdentity = {
+      platform: "shopware",
+      platformOrderId: "order_123",
+      orderNumber: "1001",
+    };
+    runtimeListener?.();
+    expect(store.getState().transactions).toEqual({
+      kind: "order",
+      orderNumber: "1001",
+      attribution: [{ experimentName: "Checkout CTA", variationName: "Variant B" }],
+      serverReceipt: "unknown",
+    });
+  });
+
+  it("forces a variation through the runtime bridge and reflects forced state", async () => {
+    const store = await loadStore();
+
+    store.forceVariation("exp_123456789", "var_control");
+
+    expect(forceMock).toHaveBeenCalledWith("exp_123456789", "var_control");
+    expect(store.getState().forcedSummary).toBe("Checkout CTA: Control");
+    expect(store.getState().experiments[0]).toMatchObject({
+      variationId: "var_control",
+      forced: true,
+      subline: "Forced to Control",
+    });
+  });
+
+  it("keeps a targeting-rejected force request non-forced in the experiment model", async () => {
+    const store = await loadStore();
+    snapshot.forceMap = { exp_123456789: "var_b" };
+    snapshot.assignments = [];
+    snapshot.activationDiagnostics.experiments = [{
+      experimentId: "exp_123456789",
+      experimentName: "Checkout CTA",
+      status: "failed",
+      reason: "url_mismatch",
+      forced: false,
+      gates: [
+        { id: "page", label: "Page check", status: "failed", reason: "url_mismatch" },
+      ],
+      targetingConditions: [],
+    }];
+    runtimeListener?.();
+
+    expect(store.getState().forcedSummary).toBe("Checkout CTA: Variant B");
+    expect(store.getState().experiments[0]).toMatchObject({
+      applied: false,
+      forced: false,
+      triggerPill: "rejected",
+      displayFrequencyPill: "not evaluated",
+    });
+  });
+});