@drip-apex/sdk 0.1.0

package/src/qa-assistant-state.ts

@@ -0,0 +1,505 @@
+import type {
+  Assignment,
+  ConditionDiagnostic,
+  Experiment,
+  ExperimentActivationDiagnostic,
+  Variation,
+} from "./types";
+import { exitQaMode } from "./guards";
+import type { DevtoolsEvent } from "./devtools";
+import { subscribeDevtoolsEvents } from "./devtools";
+import {
+  __forceQaAssistantVariation,
+  __getQaAssistantRuntimeSnapshot,
+  __resetQaAssistantForce,
+  __subscribeQaAssistantRuntime,
+} from "./index";
+
+export type QaExperimentModel = {
+  id: string; name: string;
+  variationId: string | null; variationName: string | null;
+  applied: boolean; forced: boolean;
+  subline: string;
+  triggerPill: "accepted" | "rejected" | "not evaluated" | "all pages";
+  segmentPill: "accepted" | "rejected" | "not evaluated" | "all visitors";
+  displayFrequencyPill: "accepted" | "outside traffic %" | "personalization stop" | "excluded by overlap" | "not running" | "not evaluated" | "forced";
+  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 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 QaAssistantStore = {
+  getState(): QaAssistantState;
+  subscribe(listener: (s: QaAssistantState) => void): () => void;
+  forceVariation(experimentId: string, variationId: string): void;
+  resetForce(experimentId?: string): void;
+  exitQa(): void;
+};
+export function createQaAssistantStore(): QaAssistantStore {
+  let state = buildState([], { kind: "unsupported" });
+  const listeners = new Set<(s: QaAssistantState) => void>();
+  let cartFetchSignature: string | null = null;
+  let disposed = false;
+
+  function emit(): void {
+    for (const listener of listeners) {
+      listener(state);
+    }
+  }
+
+  function setState(next: QaAssistantState): void {
+    state = next;
+    emit();
+  }
+
+  function refresh(): void {
+    const baseTransactions = transactionShell();
+    setState(buildState(state.events, baseTransactions));
+    void refreshShopifyCart(baseTransactions);
+  }
+
+  async function refreshShopifyCart(baseTransactions: QaTransactionsModel): Promise<void> {
+    if (baseTransactions.kind !== "shopify") return;
+    const runtime = __getQaAssistantRuntimeSnapshot();
+    const signature = runtime.assignments
+      .map((assignment) => `${assignment.experimentId}:${assignment.variationId}`)
+      .sort()
+      .join("|");
+    if (cartFetchSignature === signature) return;
+    cartFetchSignature = signature;
+    const cart = await readShopifyCart();
+    if (disposed || cartFetchSignature !== signature) return;
+    setState(buildState(state.events, {
+      ...baseTransactions,
+      cartStamped: cartMatchesAssignments(cart, runtime.assignments),
+      variationName: primaryStampedVariationName(cart, runtime.config?.experiments ?? []),
+      stampedAt: null,
+    }));
+  }
+
+  const unsubscribeRuntime = __subscribeQaAssistantRuntime(refresh);
+  const unsubscribeEvents = subscribeDevtoolsEvents((event) => {
+    const mapped = mapDevtoolsEvent(event);
+    if (!mapped) return;
+    const events = appendEvent(state.events, mapped);
+    setState(buildState(events, state.transactions));
+  });
+
+  refresh();
+
+  return {
+    getState() {
+      return state;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    forceVariation(experimentId, variationId) {
+      __forceQaAssistantVariation(experimentId, variationId);
+    },
+    resetForce(experimentId) {
+      __resetQaAssistantForce(experimentId);
+    },
+    exitQa() {
+      disposed = true;
+      unsubscribeRuntime();
+      unsubscribeEvents();
+      exitQaMode();
+      removeAssistantHost();
+    },
+  };
+}
+
+function buildState(events: QaEventModel[], transactions: QaTransactionsModel): QaAssistantState {
+  const runtime = __getQaAssistantRuntimeSnapshot();
+  return {
+    experiments: mapExperiments(
+      runtime.config?.experiments ?? [],
+      runtime.assignments,
+      runtime.activationDiagnostics.experiments,
+    ),
+    events,
+    transactions,
+    forcedSummary: forcedSummary(runtime.config?.experiments ?? [], runtime.forceMap),
+  };
+}
+
+function mapExperiments(
+  experiments: Experiment[],
+  assignments: Assignment[],
+  diagnostics: ExperimentActivationDiagnostic[],
+): QaExperimentModel[] {
+  const assignmentByExperiment = new Map(assignments.map((assignment) => [assignment.experimentId, assignment]));
+  const diagnosticByExperiment = new Map(diagnostics.map((diagnostic) => [diagnostic.experimentId, diagnostic]));
+  return experiments.map((experiment) => {
+    const assignment = assignmentByExperiment.get(experiment.id) ?? null;
+    const diagnostic = diagnosticByExperiment.get(experiment.id) ?? null;
+    const variation = assignment
+      ? experiment.variations.find((item) => item.id === assignment.variationId) ?? null
+      : null;
+    const variationName = variation ? variationDisplayName(variation, experiment.variations.indexOf(variation)) : null;
+    // "Forced" in the model requires the force to be in effect: overlap
+    // resolution / stop-after-match remove the assignment while preserving
+    // diagnostic.forced, and a non-displayed campaign must not group as forced.
+    const forced = Boolean(diagnostic?.forced) && Boolean(assignment);
+    const conditions = (diagnostic?.targetingConditions ?? []).map(mapCondition);
+    const pageConditions = conditions.filter((condition) => condition.group === "pages");
+    const audienceConditions = conditions.filter((condition) => condition.group === "audience");
+    return {
+      id: experiment.id,
+      name: experiment.name || shortId(experiment.id),
+      variationId: assignment?.variationId ?? null,
+      variationName,
+      applied: Boolean(assignment),
+      forced,
+      triggerPill: targetingPill(pageConditions, "all pages", diagnostic?.gates.find((gate) => gate.id === "page")),
+      segmentPill: targetingPill(audienceConditions, "all visitors", diagnostic?.gates.find((gate) => gate.id === "audience")),
+      displayFrequencyPill: displayFrequencyPill(diagnostic),
+      subline: experimentSubline(Boolean(assignment), forced, variationName, conditions, diagnostic),
+      conditions,
+      variations: experiment.variations.map((item, index) => ({
+        id: item.id,
+        name: variationDisplayName(item, index),
+        isControl: Boolean(item.isControl),
+        isCurrent: item.id === assignment?.variationId,
+        isReal: true,
+      })),
+    };
+  });
+}
+
+function experimentSubline(
+  applied: boolean,
+  forced: boolean,
+  variationName: string | null,
+  conditions: QaExperimentModel["conditions"],
+  diagnostic: ExperimentActivationDiagnostic | null,
+): string {
+  if (applied) return `${forced ? "Forced to" : "Showing"} ${variationName ?? "variation"}`;
+  const firstFailed = conditions.find((condition) => condition.state === "fail" || condition.state === "error");
+  if (firstFailed) return firstFailed.text;
+  return diagnostic?.reason || "Not applied";
+}
+
+function mapCondition(condition: ConditionDiagnostic): QaExperimentModel["conditions"][number] {
+  const reason = condition.reason ?? "";
+  const isJsError = condition.sourceType === "js" && reason.startsWith("js_error");
+  return {
+    id: condition.id,
+    group: condition.sourceType === "attribute" || condition.sourceType === "segment" || condition.id.startsWith("segment:") || condition.id.startsWith("attribute:") ? "audience" : "pages",
+    state: isJsError ? "error" : condition.status === "passed" ? "pass" : condition.status === "failed" ? "fail" : "skip",
+    text: conditionText(condition),
+    detail: conditionDetail(condition, isJsError),
+    rawCode: condition.sourceType === "js" ? condition.source ?? null : null,
+  };
+}
+
+function conditionText(condition: ConditionDiagnostic): string {
+  if (condition.sourceType === "js") return "Custom JS trigger";
+  if (condition.sourceType === "attribute" || condition.sourceType === "segment") {
+    return condition.signal
+      ? `${condition.signal} ${condition.operator ?? "matches"}`
+      : condition.label || condition.source || condition.id;
+  }
+  return condition.label || condition.source || condition.id;
+}
+
+function conditionDetail(condition: ConditionDiagnostic, isJsError: boolean): string | null {
+  if (isJsError) return (condition.reason ?? "").replace(/^js_error:\s*/, "") || "JavaScript error";
+  if (condition.status === "skipped") {
+    return `Skipped — ${condition.reason || "an earlier gate"} failed first`;
+  }
+  const parts: string[] = [];
+  if (condition.signal) parts.push(`Signal: ${condition.signal}`);
+  if (condition.operator) parts.push(`Operator: ${condition.operator}`);
+  if (condition.sourceType === "page_rule" && condition.source) parts.push(`Rules: ${condition.source}`);
+  const jsPatternSummary = condition.sourceType === "js" && isPageRulePatternSummary(condition.expected);
+  if (jsPatternSummary) parts.push(`Rules: ${formatValue(condition.expected)}`);
+  else if (condition.expected !== undefined) parts.push(`Expected: ${formatValue(condition.expected)}`);
+  if (condition.actual !== undefined) parts.push(`Actual: ${formatValue(condition.actual)}`);
+  return parts.length ? parts.join(" · ") : condition.reason ?? null;
+}
+
+function targetingPill(conditions: QaExperimentModel["conditions"], empty: "all pages", gate?: ExperimentActivationDiagnostic["gates"][number]): QaExperimentModel["triggerPill"];
+function targetingPill(conditions: QaExperimentModel["conditions"], empty: "all visitors", gate?: ExperimentActivationDiagnostic["gates"][number]): QaExperimentModel["segmentPill"];
+function targetingPill(
+  conditions: QaExperimentModel["conditions"],
+  empty: "all pages" | "all visitors",
+  gate?: ExperimentActivationDiagnostic["gates"][number],
+): "accepted" | "rejected" | "not evaluated" | "all pages" | "all visitors" {
+  const noRulesReason = empty === "all pages" ? "no_page_rules" : "no_audience_rules";
+  if (gate?.status === "skipped" && gate.reason === noRulesReason) return empty;
+  if (gate?.status === "skipped") return "not evaluated";
+  if (gate?.status === "passed") return "accepted";
+  if (gate?.status === "failed") return "rejected";
+  // No page/audience gate at all means evaluation returned before targeting
+  // ran (paused campaign, no variations) — configured rules were never
+  // checked, so neither the no-rules labels nor acceptance apply.
+  if (conditions.length === 0) return "not evaluated";
+  if (conditions.every((condition) => condition.state === "skip")) return "not evaluated";
+  return conditions.some((condition) => condition.state === "fail" || condition.state === "error")
+    ? "rejected"
+    : "accepted";
+}
+
+function isPageRulePatternSummary(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  try {
+    const rules = JSON.parse(value) as unknown;
+    return Array.isArray(rules) && rules.length > 0 && rules.every((rule) =>
+      typeof rule === "object" && rule !== null && "pattern" in rule
+    );
+  } catch {
+    return false;
+  }
+}
+
+function displayFrequencyPill(
+  diagnostic: ExperimentActivationDiagnostic | null,
+): QaExperimentModel["displayFrequencyPill"] {
+  // Suppression reasons outrank the forced flag: a forced lower-priority
+  // personalization removed by stop-after-match keeps diagnostic.forced but
+  // has no active assignment.
+  if (diagnostic?.reason === "personalization_stopped_after_prior_match") return "personalization stop";
+  // Exclusion-group suppression ALSO outranks forced: forcing multiple
+  // experiments in one exclusion group removes the losers' assignments and
+  // sets an overlap reason while preserving diagnostic.forced — labeling
+  // the suppressed campaign "forced" would falsely claim it is displayed.
+  if (diagnostic?.reason === "exclusion_group_overlap_lost" || diagnostic?.reason === "exclusion_group_sticky_other") return "excluded by overlap";
+  // "forced" requires evidence the force actually took effect — a force
+  // request that targeting blocked leaves no forced diagnostic and must not
+  // render as displayed.
+  if (diagnostic?.forced || diagnostic?.reason === "forced_variation") return "forced";
+  if (diagnostic?.reason === "outside_allocation") return "outside traffic %";
+  if (diagnostic?.reason?.startsWith("status_")) return "not running";
+  // Derive from the traffic gate: when targeting rejected the campaign,
+  // evaluation returns before the traffic gate runs — display frequency was
+  // never checked, so "accepted" would be a false claim.
+  const trafficGate = diagnostic?.gates.find((gate) => gate.id === "traffic");
+  if (trafficGate?.status === "passed") return "accepted";
+  if (trafficGate?.status === "failed") return "outside traffic %";
+  if (trafficGate?.status === "skipped" && trafficGate.reason === "forced_variation") return "forced";
+  return "not evaluated";
+}
+
+function transactionShell(): QaTransactionsModel {
+  const runtime = __getQaAssistantRuntimeSnapshot();
+  const attribution = attributionFromAssignments(runtime.config?.experiments ?? [], runtime.assignments);
+  if (runtime.orderIdentity) {
+    return {
+      kind: "order",
+      orderNumber: runtime.orderIdentity.orderNumber ?? runtime.orderIdentity.platformOrderId,
+      attribution,
+      serverReceipt: "unknown",
+    };
+  }
+  const shopifyConfigured =
+    runtime.platform === "shopify" ||
+    runtime.config?.platformHint === "shopify" ||
+    runtime.config?.profile?.platform === "shopify";
+  const shopifyRuntime = typeof window !== "undefined" && Boolean((window as unknown as { Shopify?: unknown }).Shopify);
+  if (shopifyConfigured && shopifyRuntime) {
+    return {
+      kind: "shopify",
+      cartStamped: false,
+      variationName: primaryAssignmentVariationName(runtime.config?.experiments ?? [], runtime.assignments),
+      stampedAt: null,
+      attribution,
+    };
+  }
+  return { kind: "unsupported" };
+}
+
+async function readShopifyCart(): Promise<Record<string, unknown> | null> {
+  if (typeof fetch !== "function") return null;
+  try {
+    const response = await fetch("/cart.js", { headers: { Accept: "application/json" } });
+    if (!response.ok) return null;
+    const cart = await response.json();
+    return cart && typeof cart === "object" && !Array.isArray(cart)
+      ? cart as Record<string, unknown>
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function readCartAttributes(cart: Record<string, unknown> | null): Record<string, unknown> {
+  const attributes = cart?.attributes;
+  return attributes && typeof attributes === "object" && !Array.isArray(attributes)
+    ? attributes as Record<string, unknown>
+    : {};
+}
+
+function parseCartAssignments(cart: Record<string, unknown> | null): Array<{ experimentId: string; variationId: string }> {
+  const attributes = readCartAttributes(cart);
+  const raw = attributes.apex_assignments;
+  if (typeof raw === "string") {
+    try {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) {
+        return parsed
+          .map((item) => ({
+            experimentId: typeof item?.e === "string" ? item.e : "",
+            variationId: typeof item?.v === "string" ? item.v : "",
+          }))
+          .filter((item) => item.experimentId && item.variationId);
+      }
+    } catch {}
+  }
+  const experimentId = typeof attributes.apex_experiment_id === "string" ? attributes.apex_experiment_id : "";
+  const variationId = typeof attributes.apex_variation_id === "string" ? attributes.apex_variation_id : "";
+  return experimentId && variationId ? [{ experimentId, variationId }] : [];
+}
+
+function cartMatchesAssignments(cart: Record<string, unknown> | null, assignments: Assignment[]): boolean {
+  const stamped = parseCartAssignments(cart);
+  if (!stamped.length || !assignments.length) return false;
+  const active = new Set(assignments.map((assignment) => `${assignment.experimentId}:${assignment.variationId}`));
+  return stamped.some((assignment) => active.has(`${assignment.experimentId}:${assignment.variationId}`));
+}
+
+function primaryStampedVariationName(cart: Record<string, unknown> | null, experiments: Experiment[]): string | null {
+  const [primary] = parseCartAssignments(cart);
+  if (!primary) return null;
+  return variationNameById(experiments, primary.experimentId, primary.variationId);
+}
+
+function attributionFromAssignments(
+  experiments: Experiment[],
+  assignments: Assignment[],
+): Array<{ experimentName: string; variationName: string | null }> {
+  return assignments.map((assignment) => ({
+    experimentName: experimentNameById(experiments, assignment.experimentId),
+    variationName: variationNameById(experiments, assignment.experimentId, assignment.variationId),
+  }));
+}
+
+function forcedSummary(experiments: Experiment[], forceMap: Record<string, string> | null): string | null {
+  const entries = Object.entries(forceMap ?? {});
+  if (!entries.length) return null;
+  return entries.map(([experimentId, variationId]) => {
+    const experimentName = experimentNameById(experiments, experimentId);
+    const variationName = variationNameById(experiments, experimentId, variationId) ?? shortId(variationId);
+    return `${experimentName}: ${variationName}`;
+  }).join(", ");
+}
+
+function primaryAssignmentVariationName(experiments: Experiment[], assignments: Assignment[]): string | null {
+  const [assignment] = assignments;
+  return assignment ? variationNameById(experiments, assignment.experimentId, assignment.variationId) : null;
+}
+
+function experimentNameById(experiments: Experiment[], experimentId: string): string {
+  const experiment = experiments.find((item) => item.id === experimentId);
+  return experiment?.name || shortId(experimentId);
+}
+
+function variationNameById(experiments: Experiment[], experimentId: string, variationId: string): string | null {
+  const experiment = experiments.find((item) => item.id === experimentId);
+  const index = experiment?.variations.findIndex((item) => item.id === variationId) ?? -1;
+  const variation = index >= 0 ? experiment?.variations[index] : null;
+  return variation ? variationDisplayName(variation, index) : shortId(variationId);
+}
+
+function variationDisplayName(variation: Variation, index: number): string {
+  return variation.name || (variation.isControl ? "Control" : shortId(variation.id || `variation-${index + 1}`));
+}
+
+function shortId(id: string): string {
+  return id.length > 12 ? id.slice(0, 8) : id;
+}
+
+function mapDevtoolsEvent(event: DevtoolsEvent): QaEventModel | null {
+  if (event.type !== "track") return null;
+  const detail = event.detail ?? {};
+  const type = eventType(event.label, detail);
+  if (!type) return null;
+  return {
+    at: event.ts,
+    type,
+    label: eventLabel(type, event.label, detail),
+    value: eventValue(type, detail),
+  };
+}
+
+function eventType(label: string, detail: Record<string, unknown>): QaEventModel["type"] | null {
+  if (label === "experiment_viewed" || label === "personalization_rendered") return "exposure";
+  if (label === "pageview" || label === "experiment_pageview") return "pageview";
+  if (label === "goal") return detail.goalId === "__revenue__" || detail.revenue !== undefined ? "revenue" : "goal";
+  return null;
+}
+
+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 === "revenue") return "Revenue";
+  if (type === "pageview") return typeof detail.path === "string" ? detail.path : "Pageview";
+  const runtime = __getQaAssistantRuntimeSnapshot();
+  const experimentId = typeof detail.experimentId === "string" ? detail.experimentId : "";
+  const variationId = typeof detail.variationId === "string" ? detail.variationId : "";
+  const experimentName = experimentId ? experimentNameById(runtime.config?.experiments ?? [], experimentId) : "Exposure";
+  const variationName = experimentId && variationId
+    ? variationNameById(runtime.config?.experiments ?? [], experimentId, variationId)
+    : null;
+  return variationName ? `${experimentName} / ${variationName}` : experimentName || label;
+}
+
+function eventValue(type: QaEventModel["type"], detail: Record<string, unknown>): string | null {
+  if (type !== "revenue") return null;
+  const revenue = detail.revenue;
+  const currency = typeof detail.currency === "string" ? detail.currency.trim().toUpperCase() : "";
+  if (typeof revenue === "number" && Number.isFinite(revenue)) {
+    return currency ? `${formatNumber(revenue)} ${currency}` : formatNumber(revenue);
+  }
+  return currency && revenue != null ? `${String(revenue)} ${currency}` : revenue == null ? null : String(revenue);
+}
+
+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];
+    if (
+      candidate.type === event.type &&
+      candidate.label === event.label &&
+      event.at - candidate.at <= 1500
+    ) {
+      duplicate = candidate;
+      break;
+    }
+  }
+  return [...events, duplicate ? { ...event, duplicateOf: duplicate.at } : event].slice(-100);
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (value == null) return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function formatNumber(value: number): string {
+  return Number.isInteger(value) ? String(value) : value.toFixed(2);
+}
+
+function removeAssistantHost(): void {
+  if (typeof document === "undefined") return;
+  const selectors = [
+    "#drip-qa-assistant-host",
+    "#apex-qa-assistant-host",
+    "[data-drip-qa-assistant-host]",
+  ];
+  for (const selector of selectors) {
+    document.querySelectorAll(selector).forEach((element) => element.remove());
+  }
+}