@drip-apex/sdk 0.1.0 → 0.2.0

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

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { QaAssistantStore } from "./qa-assistant-state";
+import type { PageActivationDiagnostic } from "./types";
 
 type RuntimeSnapshot = ReturnType<typeof baseSnapshot>;
 
@@ -22,6 +23,12 @@ function baseSnapshot() {
             { id: "var_control", name: "Control", weight: 0.5, mutations: [], isControl: true },
             { id: "var_b", name: "Variant B", weight: 0.5, mutations: [] },
           ],
+          goals: [
+            { id: "goal_named", name: "Completed checkout", type: "custom" as const, eventName: "checkout_completed" },
+            { id: "goal_event", type: "custom" as const, eventName: "signup" },
+            { id: "goal_a", name: "Conversion", type: "custom" as const, eventName: "conversion_a" },
+            { id: "goal_b", name: "Conversion", type: "custom" as const, eventName: "conversion_b" },
+          ],
         },
       ],
     },
@@ -51,7 +58,17 @@ function baseSnapshot() {
         },
       ],
     },
+    pageActivation: [] as PageActivationDiagnostic[],
+    goalScopeUrl: null as string | null,
     forceMap: null as Record<string, string> | null,
+    forcedUnavailable: [] as Array<{
+      experimentId: string;
+      reason: "archived" | "runtime_disabled" | "not_found" | "not_in_config";
+    }>,
+    edgeDeviceAudienceUnsupported: [] as Array<{
+      experimentId: string;
+      audienceName: string;
+    }>,
     platform: "spa" as const,
     qaMode: true,
     orderIdentity: null as {
@@ -129,6 +146,131 @@ afterEach(() => {
 });
 
 describe("createQaAssistantStore", () => {
+  it("increments the store version on every state write", async () => {
+    const store = await loadStore();
+    const initialVersion = store.getState().storeVersion;
+
+    runtimeListener?.();
+    expect(store.getState().storeVersion).toBe(initialVersion + 1);
+
+    devtoolsListener?.({ ts: 1, type: "track", label: "pageview", detail: { path: "/next" } });
+    expect(store.getState().storeVersion).toBe(initialVersion + 2);
+  });
+
+  it("reports a configured Page-scoped goal as active or inactive", async () => {
+    vi.stubGlobal("location", { href: "https://shop.test/products/shirt" });
+    const store = await loadStore();
+    const experiment = snapshot.config.experiments[0] as typeof snapshot.config.experiments[0] & {
+      targeting?: unknown;
+    };
+    experiment.targeting = {
+      pageRules: [{
+        id: "page-products",
+        name: "product",
+        includeRules: [{ type: "simple", pattern: "shop.test/products/*" }],
+      }],
+    };
+    experiment.goals.push({
+      id: "goal-scoped",
+      name: "Add to cart",
+      type: "click",
+      pageId: "page-products",
+    } as never);
+    snapshot.pageActivation = [{
+      pageId: "page-products",
+      pageName: "product",
+      active: true,
+      appliedArtifactCount: 1,
+    }];
+    runtimeListener?.();
+
+    expect(store.getState().goalScopes).toContainEqual({
+      id: "goal-scoped",
+      name: "Add to cart",
+      pageId: "page-products",
+      pageLabel: "product",
+      urlPattern: null,
+      status: "active",
+      assignmentPageActive: null,
+    });
+
+    vi.stubGlobal("location", { href: "https://shop.test/collections/sale" });
+    snapshot.pageActivation[0]!.active = false;
+    runtimeListener?.();
+    expect(
+      store.getState().goalScopes.find((goal) => goal.id === "goal-scoped")?.status,
+    ).toBe("inactive");
+  });
+
+  it("uses the configured URL and normalized attributes for goal scope status", async () => {
+    vi.stubGlobal("location", { href: "https://shop.test/collections/sale" });
+    const store = await loadStore();
+    Object.assign(snapshot.config, {
+      url: "https://shop.test/products/shirt",
+      attributes: { device: "Mobile" },
+    });
+    const experiment = snapshot.config.experiments[0] as typeof snapshot.config.experiments[0] & {
+      targeting?: unknown;
+    };
+    experiment.targeting = {
+      pageRules: [{
+        id: "page-mobile-products",
+        name: "mobile product",
+        includeRules: [{ type: "simple", pattern: "shop.test/products/*" }],
+        advancedCondition: {
+          code: 'return attributes["device.type"] === "mobile";',
+        },
+      }],
+    };
+    experiment.goals.push({
+      id: "goal-mobile-product",
+      name: "Mobile add to cart",
+      type: "click",
+      pageId: "page-mobile-products",
+    } as never);
+    snapshot.pageActivation = [{
+      pageId: "page-mobile-products",
+      pageName: "mobile product",
+      active: true,
+      appliedArtifactCount: 1,
+    }];
+    runtimeListener?.();
+
+    expect(
+      store.getState().goalScopes.find((goal) => goal.id === "goal-mobile-product")?.status,
+    ).toBe("active");
+  });
+
+  it("uses the URL that current goal wiring used instead of the configured URL", async () => {
+    vi.stubGlobal("location", { href: "https://shop.test/collections/sale" });
+    const store = await loadStore();
+    Object.assign(snapshot.config, {
+      url: "https://shop.test/products/shirt",
+    });
+    snapshot.goalScopeUrl = "https://shop.test/collections/sale";
+    const experiment = snapshot.config.experiments[0] as typeof snapshot.config.experiments[0] & {
+      targeting?: unknown;
+    };
+    experiment.targeting = {
+      pageRules: [{
+        id: "page-products",
+        name: "product",
+        includeRules: [{ type: "simple", pattern: "shop.test/products/*" }],
+      }],
+    };
+    experiment.goals.push({
+      id: "goal-scoped",
+      name: "Add to cart",
+      type: "click",
+      pageId: "page-products",
+    } as never);
+    runtimeListener?.();
+
+    expect(
+      store.getState().goalScopes.find((goal) => goal.id === "goal-scoped")?.status,
+    ).toBe("inactive");
+  });
+
   it("maps condition diagnostics to pass, fail, skip, and error rows with raw JS", async () => {
     const store = await loadStore();
     snapshot.assignments = [];
@@ -370,7 +512,79 @@ describe("createQaAssistantStore", () => {
     });
   });
 
-  it("marks the newer duplicate event within 1500ms", async () => {
+  it("shows required and detected device values for audience failures", async () => {
+    const store = await loadStore();
+    snapshot.activationDiagnostics.experiments[0].targetingConditions = [{
+      id: "segment:device:0",
+      label: "Device audience",
+      status: "failed",
+      reason: "segment_mismatch",
+      sourceType: "segment",
+      signal: "device.type",
+      operator: "equals",
+      expected: "Mobile",
+      actual: "Desktop",
+    }];
+    runtimeListener?.();
+    expect(store.getState().experiments[0].conditions[0]?.detail).toBe(
+      "Required: Mobile · Detected: Desktop",
+    );
+  });
+
+  it("shows an unknown detected device when the signal is unresolved", async () => {
+    const store = await loadStore();
+    snapshot.activationDiagnostics.experiments[0].targetingConditions = [{
+      id: "segment:device:0",
+      label: "Device audience",
+      status: "failed",
+      reason: "signal_unresolved",
+      sourceType: "segment",
+      signal: "device.type",
+      operator: "equals",
+      expected: "Mobile",
+    }];
+    runtimeListener?.();
+    expect(store.getState().experiments[0].conditions[0]?.detail).toBe(
+      "Required: Mobile · Detected: unknown",
+    );
+  });
+
+  it("resolves goal labels by configured name, event name, and short id", async () => {
+    const store = await loadStore();
+
+    devtoolsListener?.({
+      ts: 1000,
+      type: "track",
+      label: "goal",
+      detail: { goalId: "goal_named" },
+    });
+    devtoolsListener?.({
+      ts: 3000,
+      type: "track",
+      label: "goal",
+      detail: { goalId: "signup" },
+    });
+    devtoolsListener?.({
+      ts: 5000,
+      type: "track",
+      label: "goal",
+      detail: { goalId: "b6f8724b-1111-4222-8333-123456789abc" },
+    });
+
+    expect(store.getState().events).toEqual([
+      { at: 1000, type: "goal", label: "Completed checkout", value: null, goalId: "goal_named" },
+      { at: 3000, type: "goal", label: "signup", value: null, goalId: "signup" },
+      {
+        at: 5000,
+        type: "goal",
+        label: "b6f8724b",
+        value: null,
+        goalId: "b6f8724b-1111-4222-8333-123456789abc",
+      },
+    ]);
+  });
+
+  it("marks the newer duplicate goal event within 1500ms", async () => {
     const store = await loadStore();
 
     devtoolsListener?.({
@@ -387,8 +601,30 @@ describe("createQaAssistantStore", () => {
     });
 
     expect(store.getState().events).toEqual([
-      { at: 1000, type: "goal", label: "signup", value: null },
-      { at: 2200, type: "goal", label: "signup", value: null, duplicateOf: 1000 },
+      { at: 1000, type: "goal", label: "signup", value: null, goalId: "signup" },
+      { at: 2200, type: "goal", label: "signup", value: null, goalId: "signup", duplicateOf: 1000 },
+    ]);
+  });
+
+  it("does not merge distinct goal events with the same configured name", async () => {
+    const store = await loadStore();
+
+    devtoolsListener?.({
+      ts: 1000,
+      type: "track",
+      label: "goal",
+      detail: { goalId: "goal_a" },
+    });
+    devtoolsListener?.({
+      ts: 1200,
+      type: "track",
+      label: "goal",
+      detail: { goalId: "goal_b" },
+    });
+
+    expect(store.getState().events).toEqual([
+      { at: 1000, type: "goal", label: "Conversion", value: null, goalId: "goal_a" },
+      { at: 1200, type: "goal", label: "Conversion", value: null, goalId: "goal_b" },
     ]);
   });
 
@@ -443,6 +679,16 @@ describe("createQaAssistantStore", () => {
     });
   });
 
+  it("surfaces an unavailable forced experiment from the runtime", async () => {
+    const store = await loadStore();
+    snapshot.forcedUnavailable = [{ experimentId: "exp_archived", reason: "archived" }];
+    runtimeListener?.();
+
+    expect(store.getState().forcedUnavailable).toEqual([
+      { experimentId: "exp_archived", reason: "archived" },
+    ]);
+  });
+
   it("keeps a targeting-rejected force request non-forced in the experiment model", async () => {
     const store = await loadStore();
     snapshot.forceMap = { exp_123456789: "var_b" };

package/src/qa-assistant-state.ts

@@ -8,6 +8,8 @@ import type {
 import { exitQaMode } from "./guards";
 import type { DevtoolsEvent } from "./devtools";
 import { subscribeDevtoolsEvents } from "./devtools";
+import { safeRegexTest } from "./safe-regex";
+import { normalizeEventName } from "@drip/event-schema/event-name";
 import {
   __forceQaAssistantVariation,
   __getQaAssistantRuntimeSnapshot,
@@ -26,12 +28,40 @@ export type QaExperimentModel = {
   conditions: Array<{ id: string; group: "pages" | "audience"; state: "pass"|"fail"|"skip"|"error"; text: string; detail: string | null; rawCode: string | null }>;
   variations: Array<{ id: string; name: string; isControl: boolean; isCurrent: boolean; isReal: boolean }>;
 };
-export type QaEventModel = { at: number; type: "exposure"|"goal"|"revenue"|"pageview"; label: string; value: string | null; duplicateOf?: number };
+export type QaEventModel = { at: number; type: "exposure"|"goal"|"revenue"|"pageview"; label: string; value: string | null; goalId?: string; duplicateOf?: number };
+export type QaGoalScopeModel = {
+  id: string;
+  name: string;
+  pageId: string | null;
+  pageLabel: string | null;
+  urlPattern?: string | null;
+  status: "active" | "inactive" | "not_wired";
+  assignmentPageActive?: boolean | null;
+};
 export type QaTransactionsModel =
   | { kind: "unsupported" }
   | { kind: "shopify"; cartStamped: boolean; variationName: string | null; stampedAt: number | null; attribution: Array<{ experimentName: string; variationName: string | null }> }
   | { kind: "order"; orderNumber: string | null; attribution: Array<{ experimentName: string; variationName: string | null }>; serverReceipt: "pending"|"confirmed"|"unknown" };
-export type QaAssistantState = { experiments: QaExperimentModel[]; events: QaEventModel[]; transactions: QaTransactionsModel; forcedSummary: string | null };
+export type ForcedUnavailable = {
+  experimentId: string;
+  reason: "archived" | "runtime_disabled" | "not_found" | "environment_mismatch" | "not_in_config";
+};
+export type EdgeDeviceAudienceUnsupported = {
+  experimentId: string;
+  audienceName: string;
+};
+export type QaPageActivationModel = {
+  pageId: string;
+  pageName: string;
+  active: boolean;
+  lastTransitionMode: "reset" | "deactivate" | "force_reset" | "persistent" | null;
+  isolationFallback: "whole_experiment" | null;
+  triggerDetector?: "history" | "polling" | "dom" | null;
+  triggerPollAttempts?: number;
+  triggerOutcome?: "activated" | "condition_failed" | "window_expired" | null;
+  triggerElapsedMs?: number;
+};
+export type QaAssistantState = { storeVersion: number; experiments: QaExperimentModel[]; events: QaEventModel[]; goalScopes: QaGoalScopeModel[]; pageActivation: QaPageActivationModel[]; transactions: QaTransactionsModel; forcedSummary: string | null; forcedUnavailable: ForcedUnavailable[]; edgeDeviceAudienceUnsupported: EdgeDeviceAudienceUnsupported[] };
 export type QaAssistantStore = {
   getState(): QaAssistantState;
   subscribe(listener: (s: QaAssistantState) => void): () => void;
@@ -41,6 +71,7 @@ export type QaAssistantStore = {
 };
 export function createQaAssistantStore(): QaAssistantStore {
   let state = buildState([], { kind: "unsupported" });
+  let storeVersion = state.storeVersion;
   const listeners = new Set<(s: QaAssistantState) => void>();
   let cartFetchSignature: string | null = null;
   let disposed = false;
@@ -52,7 +83,8 @@ export function createQaAssistantStore(): QaAssistantStore {
   }
 
   function setState(next: QaAssistantState): void {
-    state = next;
+    storeVersion += 1;
+    state = { ...next, storeVersion };
     emit();
   }
 
@@ -119,18 +151,95 @@ export function createQaAssistantStore(): QaAssistantStore {
 
 function buildState(events: QaEventModel[], transactions: QaTransactionsModel): QaAssistantState {
   const runtime = __getQaAssistantRuntimeSnapshot();
+  const experiments = runtime.config?.experiments ?? [];
   return {
+    storeVersion: 0,
     experiments: mapExperiments(
-      runtime.config?.experiments ?? [],
+      experiments,
       runtime.assignments,
       runtime.activationDiagnostics.experiments,
     ),
     events,
+    goalScopes: mapGoalScopes(
+      experiments,
+      runtime.assignments,
+      runtime.goalScopeUrl ?? runtime.config?.url,
+      new Set(
+        runtime.pageActivation
+          .filter((page) => page.active)
+          .map((page) => page.pageId),
+      ),
+    ),
+    pageActivation: runtime.pageActivation.map((page) => ({
+      pageId: page.pageId,
+      pageName: page.pageName || shortId(page.pageId),
+      active: page.active,
+      lastTransitionMode: page.lastTransitionMode ?? null,
+      isolationFallback: page.isolationFallback ?? null,
+      triggerDetector: page.triggerDetector ?? null,
+      triggerPollAttempts: page.triggerPollAttempts ?? 0,
+      triggerOutcome: page.triggerOutcome ?? null,
+      triggerElapsedMs: page.triggerElapsedMs ?? 0,
+    })),
     transactions,
     forcedSummary: forcedSummary(runtime.config?.experiments ?? [], runtime.forceMap),
+    forcedUnavailable: runtime.forcedUnavailable,
+    edgeDeviceAudienceUnsupported: runtime.edgeDeviceAudienceUnsupported,
   };
 }
 
+function mapGoalScopes(
+  experiments: Experiment[],
+  assignments: Assignment[],
+  configuredUrl?: string,
+  activePageIds: ReadonlySet<string> = new Set(),
+): QaGoalScopeModel[] {
+  const url = configuredUrl ??
+    (typeof location !== "undefined" ? location.href : "https://_");
+  const pageRules = experiments.flatMap((experiment) => [...(experiment.targeting?.pageRules ?? []), ...(experiment.goalPageRules ?? [])]);
+  const pageLabels = new Map(
+    pageRules.map((rule) => [rule.id, rule.name || shortId(rule.id)]),
+  );
+  const assignmentByExperiment = new Map(assignments.map((assignment) => [assignment.experimentId, assignment]));
+  const byGoal = new Map<string, QaGoalScopeModel>();
+
+  for (const experiment of experiments) {
+    for (const goal of experiment.goals ?? []) {
+      const assignment = assignmentByExperiment.get(experiment.id);
+      const wired = Boolean(assignment);
+      const active = wired && (goal.pageId
+        ? activePageIds.has(goal.pageId)
+        : !goal.urlPattern || safeRegexTest(goal.urlPattern, url));
+      const status: QaGoalScopeModel["status"] = active
+        ? "active"
+        : wired
+          ? "inactive"
+          : "not_wired";
+      const existing = byGoal.get(goal.id);
+      if (
+        existing &&
+        (existing.status === "active" ||
+          (existing.status === "inactive" && status === "not_wired"))
+      ) {
+        continue;
+      }
+      byGoal.set(goal.id, {
+        id: goal.id,
+        name: goal.name || goal.eventName || shortId(goal.id),
+        pageId: goal.pageId ?? null,
+        pageLabel: goal.pageId
+          ? pageLabels.get(goal.pageId) ?? shortId(goal.pageId)
+          : null,
+        urlPattern: goal.urlPattern ?? null,
+        status,
+        assignmentPageActive: assignment?.pageActive ?? null,
+      });
+    }
+  }
+
+  return Array.from(byGoal.values());
+}
+
 function mapExperiments(
   experiments: Experiment[],
   assignments: Assignment[],
@@ -216,6 +325,15 @@ function conditionDetail(condition: ConditionDiagnostic, isJsError: boolean): st
   if (condition.status === "skipped") {
     return `Skipped — ${condition.reason || "an earlier gate"} failed first`;
   }
+  if (condition.signal === "device.type" && condition.status === "failed") {
+    const detected =
+      condition.actual === undefined ||
+      condition.actual === null ||
+      (typeof condition.actual === "string" && condition.actual.trim() === "")
+        ? "unknown"
+        : formatValue(condition.actual);
+    return `Required: ${formatValue(condition.expected)} · Detected: ${detected}`;
+  }
   const parts: string[] = [];
   if (condition.signal) parts.push(`Signal: ${condition.signal}`);
   if (condition.operator) parts.push(`Operator: ${condition.operator}`);
@@ -409,6 +527,16 @@ function variationNameById(experiments: Experiment[], experimentId: string, vari
   return variation ? variationDisplayName(variation, index) : shortId(variationId);
 }
 
+function goalNameById(experiments: Experiment[], goalId: string): string {
+  const goals = experiments.flatMap((experiment) => experiment.goals ?? []);
+  const normalizedGoalId = normalizeEventName(goalId);
+  const goal = goals.find((item) => item.id === goalId)
+    ?? goals.find(
+      (item) => item.eventName && normalizeEventName(item.eventName) === normalizedGoalId,
+    );
+  return goal?.name || goal?.eventName || shortId(goalId);
+}
+
 function variationDisplayName(variation: Variation, index: number): string {
   return variation.name || (variation.isControl ? "Control" : shortId(variation.id || `variation-${index + 1}`));
 }
@@ -427,6 +555,9 @@ function mapDevtoolsEvent(event: DevtoolsEvent): QaEventModel | null {
     type,
     label: eventLabel(type, event.label, detail),
     value: eventValue(type, detail),
+    ...(type === "goal" && typeof detail.goalId === "string"
+      ? { goalId: detail.goalId }
+      : {}),
   };
 }
 
@@ -438,7 +569,11 @@ function eventType(label: string, detail: Record<string, unknown>): QaEventModel
 }
 
 function eventLabel(type: QaEventModel["type"], label: string, detail: Record<string, unknown>): string {
-  if (type === "goal") return typeof detail.goalId === "string" ? detail.goalId : "Goal";
+  if (type === "goal") {
+    if (typeof detail.goalId !== "string") return "Goal";
+    const runtime = __getQaAssistantRuntimeSnapshot();
+    return goalNameById(runtime.config?.experiments ?? [], detail.goalId);
+  }
   if (type === "revenue") return "Revenue";
   if (type === "pageview") return typeof detail.path === "string" ? detail.path : "Pageview";
   const runtime = __getQaAssistantRuntimeSnapshot();
@@ -465,9 +600,14 @@ function appendEvent(events: QaEventModel[], event: QaEventModel): QaEventModel[
   let duplicate: QaEventModel | undefined;
   for (let index = events.length - 1; index >= 0; index -= 1) {
     const candidate = events[index];
+    const sameIdentity = event.type === "goal" && candidate.type === "goal"
+      ? event.goalId != null && candidate.goalId != null
+        ? candidate.goalId === event.goalId
+        : candidate.label === event.label
+      : candidate.label === event.label;
     if (
       candidate.type === event.type &&
-      candidate.label === event.label &&
+      sameIdentity &&
       event.at - candidate.at <= 1500
     ) {
       duplicate = candidate;