@drip-apex/sdk 0.1.0 → 0.3.0

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

@@ -5,6 +5,7 @@ import { mountQaAssistantView, QA_ASSISTANT_HOST_ID } from "./qa-assistant-view"
 
 function state(subline = "Showing Variant B"): QaAssistantState {
   return {
+    storeVersion: 0,
     experiments: [{
       id: "exp_products", name: "Product CTA", variationId: "var_b", variationName: "Variant B",
       applied: true, forced: false, subline,
@@ -19,7 +20,7 @@ function state(subline = "Showing Variant B"): QaAssistantState {
         { id: "var_b", name: "Variant B", isControl: false, isCurrent: true, isReal: true },
       ],
     }],
-    events: [], transactions: { kind: "unsupported" }, forcedSummary: null,
+    events: [], goalScopes: [], pageActivation: [], transactions: { kind: "unsupported" }, forcedSummary: null, forcedUnavailable: [], edgeDeviceAudienceUnsupported: [],
   };
 }
 
@@ -31,7 +32,13 @@ function fakeStore(initial: QaAssistantState) {
     subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
     forceVariation: vi.fn(), resetForce: vi.fn(), exitQa: vi.fn(),
   };
-  return { store, emit(next: QaAssistantState) { current = next; listeners.forEach((listener) => listener(next)); } };
+  return {
+    store,
+    emit(next: QaAssistantState) {
+      current = { ...next, storeVersion: current.storeVersion + 1 };
+      listeners.forEach((listener) => listener(current));
+    },
+  };
 }
 
 afterEach(() => {
@@ -40,6 +47,217 @@ afterEach(() => {
 });
 
 describe("mountQaAssistantView", () => {
+  it("gives the empty shadow host defensive inline styles", () => {
+    const view = mountQaAssistantView(fakeStore(state()).store);
+    const host = document.getElementById(QA_ASSISTANT_HOST_ID)!;
+
+    expect(host.childElementCount).toBe(0);
+    expect(host.style.position).toBe("fixed");
+    expect(host.style.zIndex).toBe("2147483647");
+    expect(host.style.display).toBe("block");
+    expect(host.style.top).toBe("0px");
+    expect(host.style.left).toBe("0px");
+    expect(host.style.width).toBe("0px");
+    expect(host.style.height).toBe("0px");
+    expect(host.style.overflow).toBe("visible");
+    expect(host.style.contain).toBe("none");
+    expect(host.getAttribute("style")).toContain("display: block !important");
+    view.destroy();
+  });
+
+  it("keeps the host displayed when storefront CSS hides empty divs", () => {
+    const storefrontStyle = document.createElement("style");
+    storefrontStyle.textContent = "div:empty { display: none; }";
+    document.head.appendChild(storefrontStyle);
+    const view = mountQaAssistantView(fakeStore(state()).store);
+    const host = document.getElementById(QA_ASSISTANT_HOST_ID)!;
+
+    expect(getComputedStyle(host).display).toBe("block");
+
+    view.destroy();
+    storefrontStyle.remove();
+  });
+
+  it("humanizes a skipped unresolved signal as an audience rule", () => {
+    const current = state();
+    current.experiments[0]!.conditions.push({
+      id: "segment:device:1",
+      group: "audience",
+      state: "skip",
+      text: "Desktop visitors",
+      detail: "Skipped — signal_unresolved failed first",
+      rawCode: null,
+    });
+    const source = fakeStore(current);
+    const view = mountQaAssistantView(source.store);
+    const shadow = document.getElementById(QA_ASSISTANT_HOST_ID)!.shadowRoot!;
+    (shadow.querySelector('[data-action="toggle-exp"]') as HTMLElement).click();
+
+    expect(shadow.textContent).toContain("Skipped — the audience rule failed first");
+    view.destroy();
+  });
+
+  it("re-renders when Page activation is the only diagnostic change", () => {
+    vi.useFakeTimers();
+    const initial = {
+      ...state(),
+      pageActivation: [{
+        pageId: "page-products",
+        pageName: "Product pages",
+        active: true,
+        lastTransitionMode: null,
+        isolationFallback: null,
+      }],
+    };
+    const source = fakeStore(initial);
+    const view = mountQaAssistantView(source.store);
+    const shadow = document.getElementById(QA_ASSISTANT_HOST_ID)!.shadowRoot!;
+
+    expect(shadow.querySelector('.scope-row[data-status="active"] .scope-status')?.textContent)
+      .toBe("Active");
+    source.emit({
+      ...initial,
+      pageActivation: [{
+        ...initial.pageActivation[0]!,
+        active: false,
+        lastTransitionMode: "deactivate",
+      }],
+    });
+    vi.advanceTimersByTime(100);
+
+    expect(shadow.querySelector('.scope-row[data-status="inactive"] .scope-status')?.textContent)
+      .toBe("Inactive");
+    expect(shadow.textContent).toContain("Last transition · Deactivate");
+    view.destroy();
+  });
+
+  it("shows per-Page active state and the last transition mode", () => {
+    const source = fakeStore({
+      ...state(),
+      pageActivation: [
+        {
+          pageId: "page-products",
+          pageName: "Product pages",
+          active: false,
+          lastTransitionMode: "deactivate",
+          isolationFallback: null,
+        },
+        {
+          pageId: "page-cart",
+          pageName: "Cart",
+          active: true,
+          lastTransitionMode: "reset",
+          isolationFallback: "whole_experiment",
+        },
+      ],
+    });
+    const view = mountQaAssistantView(source.store);
+    const shadow = document.getElementById(QA_ASSISTANT_HOST_ID)!.shadowRoot!;
+
+    expect(shadow.textContent).toContain("Page activation");
+    expect(shadow.textContent).toContain("Product pages");
+    expect(shadow.textContent).toContain("Last transition · Deactivate");
+    expect(shadow.textContent).toContain("whole-experiment fallback");
+    view.destroy();
+  });
+
+  it("announces an unavailable forced experiment with its reason", () => {
+    const source = fakeStore({
+      ...state(),
+      forcedUnavailable: [{ experimentId: "exp_archived_123456", reason: "archived" }],
+    });
+    const view = mountQaAssistantView(source.store);
+    const shadow = document.getElementById(QA_ASSISTANT_HOST_ID)!.shadowRoot!;
+
+    expect(shadow.querySelector('[role="alert"]')?.textContent).toContain(
+      "Forced experiment not available (archived): exp_arch…",
+    );
+    view.destroy();
+  });
+
+  it("names a device audience that falls back from edge to browser evaluation", () => {
+    const source = fakeStore({
+      ...state(),
+      edgeDeviceAudienceUnsupported: [{
+        experimentId: "exp_redirect",
+        audienceName: "Mobile shoppers",
+      }],
+    });
+    const view = mountQaAssistantView(source.store);
+    const shadow = document.getElementById(QA_ASSISTANT_HOST_ID)!.shadowRoot!;
+
+    expect(shadow.querySelector('[role="alert"]')?.textContent).toContain(
+      "Audience “Mobile shoppers” cannot be evaluated at the edge. Apex falls back to evaluating it in the browser.",
+    );
+    view.destroy();
+  });
+
+  it("keeps resolved force summaries visible alongside unavailable force warnings", () => {
+    const source = fakeStore({
+      ...state(),
+      forcedSummary: "Product CTA: Variant B",
+      forcedUnavailable: [{ experimentId: "exp_archived_123456", reason: "archived" }],
+    });
+    const view = mountQaAssistantView(source.store);
+    const shadow = document.getElementById(QA_ASSISTANT_HOST_ID)!.shadowRoot!;
+
+    expect(shadow.querySelector('[role="alert"]')?.textContent).toContain("exp_arch…");
+    expect(shadow.textContent).toContain("Product CTA: Variant B");
+    view.destroy();
+  });
+
+  it("does not render an unavailable warning when every force resolves", () => {
+    const source = fakeStore({ ...state(), forcedSummary: "Product CTA: Variant B" });
+    const view = mountQaAssistantView(source.store);
+    const shadow = document.getElementById(QA_ASSISTANT_HOST_ID)!.shadowRoot!;
+
+    expect(shadow.querySelector('[role="alert"]')).toBeNull();
+    expect(shadow.textContent).toContain("Product CTA: Variant B");
+    view.destroy();
+  });
+
+  it("updates the unavailable warning when it is the only state change", () => {
+    vi.useFakeTimers();
+    const initial = state();
+    const source = fakeStore(initial);
+    const view = mountQaAssistantView(source.store);
+    const shadow = document.getElementById(QA_ASSISTANT_HOST_ID)!.shadowRoot!;
+
+    source.emit({
+      ...initial,
+      forcedUnavailable: [{ experimentId: "exp_archived_123456", reason: "archived" }],
+    });
+    vi.advanceTimersByTime(100);
+    expect(shadow.querySelector('[role="alert"]')?.textContent).toContain(
+      "Forced experiment not available (archived): exp_arch…",
+    );
+
+    source.emit(initial);
+    vi.advanceTimersByTime(100);
+    expect(shadow.querySelector('[role="alert"]')).toBeNull();
+    view.destroy();
+  });
+
+  it("shows active, inactive, and not-wired goal scopes in Events", () => {
+    const source = fakeStore({
+      ...state(),
+      goalScopes: [
+        { id: "goal-active", name: "Add to cart", pageId: "page-products", pageLabel: "product", status: "active" },
+        { id: "goal-inactive", name: "Checkout click", pageId: "page-checkout", pageLabel: "checkout", status: "inactive" },
+        { id: "goal-unwired", name: "Signup", pageId: null, pageLabel: null, status: "not_wired" },
+      ],
+    });
+    const view = mountQaAssistantView(source.store);
+    const shadow = document.getElementById(QA_ASSISTANT_HOST_ID)!.shadowRoot!;
+    (shadow.querySelector('[data-action="tab"][data-tab="ev"]') as HTMLElement).click();
+
+    expect(shadow.textContent).toContain("Page · product");
+    expect(shadow.textContent).toContain("Wired · page active");
+    expect(shadow.textContent).toContain("Wired · page inactive");
+    expect(shadow.textContent).toContain("Not wired");
+    view.destroy();
+  });
+
   it("coalesces refresh bursts while preserving the panel, expanded rows, and scroll", () => {
     vi.useFakeTimers();
     const source = fakeStore(state());

package/src/qa-assistant-view.ts

@@ -27,6 +27,20 @@ type ViewState = {
 
 const MINIMIZED_KEY = "drip_qa_assistant_min";
 
+const HOST_STYLES: ReadonlyArray<readonly [string, string]> = [
+  ["position", "fixed"],
+  ["z-index", "2147483647"],
+  ["display", "block"],
+  ["top", "0px"],
+  ["left", "0px"],
+  ["width", "0px"],
+  ["height", "0px"],
+  ["overflow", "visible"],
+  ["contain", "none"],
+  ["visibility", "visible"],
+  ["opacity", "1"],
+];
+
 /* ── icons (Lucide-style paths from the design's icon set) ─────────────── */
 const P = {
   check: "M5 13l4 4L19 7",
@@ -72,6 +86,8 @@ const REASON_WORDS: Record<string, string> = {
   url_exclude_matched: "page rules",
   page_rule_failed: "page rules",
   segment_mismatch: "the audience rule",
+  segments_unexpanded: "the unexpanded audience segments",
+  signal_unresolved: "the audience rule",
   segment_and_failed: "the audience rule",
   attribute_mismatch: "the audience rule",
   js_false: "the custom JS trigger",
@@ -138,6 +154,7 @@ button { font-family: inherit; background: none; border: 0; padding: 0; color: i
   border-bottom: 1px solid var(--p-bd); flex-shrink: 0; color: var(--p200); }
 .forced-bar .txt { font-size: 11px; font-weight: 600; flex: 1; min-width: 0; }
 .forced-bar .reset { font-size: 11px; font-weight: 600; color: var(--t1); white-space: nowrap; }
+.forced-bar.warning { background: var(--warn-soft); border-color: var(--warn-bd); color: var(--warn); }
 .tabs { display: flex; padding: 0 8px; border-bottom: 1px solid var(--bd); background: rgba(255,255,255,0.015); flex-shrink: 0; }
 .tab { display: inline-flex; align-items: center; gap: 6px; padding: 10px 9px 9px; font-size: 12px; font-weight: 600;
   color: var(--t3); white-space: nowrap; }
@@ -199,6 +216,19 @@ button { font-family: inherit; background: none; border: 0; padding: 0; color: i
 .live .dot { width: 6px; height: 6px; border-radius: 50%; background: var(--pos); box-shadow: 0 0 6px var(--pos); }
 .live .t { font-size: 11px; color: var(--t3); }
 .live .clear { margin-left: auto; font-size: 11px; color: var(--t4); font-weight: 600; }
+.scope-list { padding: 0 14px 8px; border-bottom: 1px solid var(--bd); }
+.scope-row { display: flex; align-items: center; gap: 10px; padding: 7px 9px; border: 1px solid var(--bd); background: var(--inset); }
+.scope-row + .scope-row { border-top: 0; }
+.scope-row:first-child { border-radius: 8px 8px 0 0; }
+.scope-row:last-child { border-radius: 0 0 8px 8px; }
+.scope-row:only-child { border-radius: 8px; }
+.scope-copy { display: grid; flex: 1; min-width: 0; }
+.scope-name { overflow: hidden; font-size: 11.5px; font-weight: 600; text-overflow: ellipsis; white-space: nowrap; }
+.scope-page { overflow: hidden; margin-top: 1px; color: var(--t3); font-size: 10.5px; text-overflow: ellipsis; white-space: nowrap; }
+.scope-status { flex-shrink: 0; color: var(--t3); font-size: 10.5px; font-weight: 600; }
+.scope-row[data-status="active"] .scope-status { color: var(--pos); }
+.scope-row[data-status="inactive"] { box-shadow: inset 2px 0 0 var(--warn); }
+.scope-row[data-status="inactive"] .scope-status { color: var(--warn); }
 .ev { padding: 8px 14px; border-bottom: 1px solid var(--bd); }
 .ev:last-child { border-bottom: 0; }
 .ev[data-dup="true"] { background: rgba(245,158,11,0.05); box-shadow: inset 2px 0 0 var(--warn); }
@@ -368,6 +398,28 @@ function experimentsBody(state: QaAssistantState, view: ViewState): string {
     <select data-action="status-filter"><option value="all">All</option><option value="accepted" ${view.statusFilter === "accepted" ? "selected" : ""}>Applied</option><option value="rejected" ${view.statusFilter === "rejected" ? "selected" : ""}>Not applied</option><option value="forced" ${view.statusFilter === "forced" ? "selected" : ""}>Forced</option></select>
     <input data-action="search" aria-label="Search campaigns" placeholder="Search name or ID" value="${esc(view.search)}">
   </div>`;
+  const transitionLabels = {
+    reset: "Reset",
+    deactivate: "Deactivate",
+    force_reset: "Force-reset",
+    persistent: "Persistent",
+  } as const;
+  const pageActivation = state.pageActivation.length
+    ? `<div class="grp"><span class="l">Page activation</span><span class="n">${state.pageActivation.length}</span></div>` +
+      `<div class="scope-list">${state.pageActivation.map((page) => {
+        const transition = page.lastTransitionMode
+          ? `Last transition · ${transitionLabels[page.lastTransitionMode]}`
+          : "No transition yet";
+        const fallback = page.isolationFallback === "whole_experiment"
+          ? " · whole-experiment fallback"
+          : "";
+        const pollAttempts = page.triggerPollAttempts ?? 0;
+        const trigger = page.triggerDetector
+          ? ` · ${page.triggerDetector} detector · ${pollAttempts} poll attempt${pollAttempts === 1 ? "" : "s"} · ${page.triggerOutcome ?? "pending"} · ${page.triggerElapsedMs ?? 0} ms`
+          : "";
+        return `<div class="scope-row" data-status="${page.active ? "active" : "inactive"}"><span class="scope-copy"><span class="scope-name">${esc(page.pageName)}</span><span class="scope-page">${esc(transition + fallback + trigger)}</span></span><span class="scope-status">${page.active ? "Active" : "Inactive"}</span></div>`;
+      }).join("")}</div>`
+    : "";
   // Summary lines describe the whole campaign set, never the filtered view —
   // a filter that hides rejected rows must not make "all apply" claims.
   const totalRejected = state.experiments.filter((e) => !e.applied && !e.forced).length;
@@ -377,7 +429,7 @@ function experimentsBody(state: QaAssistantState, view: ViewState): string {
   } else if (state.experiments.length > 0 && totalRejected === state.experiments.length) {
     summary = `<div class="sumline" style="color:var(--t2)"><span style="color:var(--warn);display:inline-flex">${svg(P.alert, 12)}</span>Nothing runs on this page — every experiment was rejected.</div>`;
   } else if (state.experiments.length === 0) {
-    return filters + `<div class="empty">
+    return pageActivation + filters + `<div class="empty">
       <div class="icon">${svg(P.target, 16)}</div>
       <div class="h">No experiments on this shop yet</div>
       <div class="s">Running and draft experiments show up here when the QA link opens a page they could target.</div>
@@ -391,7 +443,7 @@ function experimentsBody(state: QaAssistantState, view: ViewState): string {
     ? `<div class="grp"><span class="l">Not applied</span><span class="n">${rejected.length}</span></div>` +
       rejected.map((e) => experimentRow(e, view)).join("")
     : "";
-  return filters + summary + appliedHtml + rejectedHtml;
+  return pageActivation + filters + summary + appliedHtml + rejectedHtml;
 }
 
 function eventRow(ev: QaEventModel): string {
@@ -417,6 +469,22 @@ function eventRow(ev: QaEventModel): string {
 }
 
 function eventsBody(state: QaAssistantState): string {
+  const goalScopes = state.goalScopes.length
+    ? `<div class="grp"><span class="l">Goal wiring</span><span class="n">${state.goalScopes.length}</span></div>` +
+      `<div class="scope-list">${state.goalScopes.map((goal) => {
+        const status = goal.status === "active"
+          ? goal.assignmentPageActive === false ? "Wired · page active · treatment off-target" : "Wired · page active"
+          : goal.status === "inactive"
+            ? goal.assignmentPageActive === false ? "Wired · page inactive · treatment off-target" : "Wired · page inactive"
+            : "Not wired";
+        const scope = goal.pageLabel
+          ? `Page · ${goal.pageLabel}`
+          : goal.urlPattern
+            ? `URL · ${goal.urlPattern}`
+            : "Project-wide";
+        return `<div class="scope-row" data-status="${goal.status}"><span class="scope-copy"><span class="scope-name">${esc(goal.name)}</span><span class="scope-page">${esc(scope)}</span></span><span class="scope-status">${status}</span></div>`;
+      }).join("")}</div>`
+    : "";
   const live = `
     <div class="live">
       <span class="dot"></span>
@@ -425,7 +493,7 @@ function eventsBody(state: QaAssistantState): string {
     </div>`;
   if (state.events.length === 0) {
     return (
-      live +
+      goalScopes + live +
       `<div class="empty">
         <div class="icon">${svg(P.activity, 16)}</div>
         <div class="h">No events yet</div>
@@ -438,7 +506,7 @@ function eventsBody(state: QaAssistantState): string {
     .slice(0, 80)
     .map(eventRow)
     .join("");
-  return live + rows;
+  return goalScopes + live + rows;
 }
 
 function attributionRows(list: Array<{ experimentName: string; variationName: string | null }>): string {
@@ -549,9 +617,31 @@ function panelHtml(state: QaAssistantState, view: ViewState): string {
 }
 
 function forcedBarHtml(state: QaAssistantState): string {
-  return state.forcedSummary
+  let unavailableHtml = "";
+  if (state.forcedUnavailable.length > 0) {
+    const reasonLabels = {
+      archived: "archived",
+      runtime_disabled: "runtime-disabled",
+      not_found: "not found on this shop",
+      environment_mismatch: "scoped to another environment",
+      not_in_config: "not in served config",
+    } as const;
+    const warnings = state.forcedUnavailable.map(({ experimentId, reason }) =>
+      `Forced experiment not available (${reasonLabels[reason]}): ${shortId(experimentId)}`,
+    ).join(", ");
+    unavailableHtml = `<div class="forced-bar warning" role="alert">${svg(P.alert, 12)}<span class="txt">${esc(warnings)}</span><button class="reset" data-action="reset-force">Reset</button></div>`;
+  }
+  const summaryHtml = state.forcedSummary
     ? `<div class="forced-bar">${svg(P.bolt, 12)}<span class="txt">${esc(state.forcedSummary)}</span><button class="reset" data-action="reset-force">Reset</button></div>`
     : "";
+  const edgeAudienceHtml = state.edgeDeviceAudienceUnsupported.map(({ audienceName }) =>
+    `<div class="forced-bar warning" role="alert">${svg(P.alert, 12)}<span class="txt">${esc(`Audience “${audienceName}” cannot be evaluated at the edge. Apex falls back to evaluating it in the browser.`)}</span></div>`,
+  ).join("");
+  return unavailableHtml + edgeAudienceHtml + summaryHtml;
+}
+
+function shortId(id: string): string {
+  return id.length > 12 ? `${id.slice(0, 8)}…` : id;
 }
 
 function pillHtml(state: QaAssistantState): string {
@@ -581,6 +671,9 @@ export function mountQaAssistantView(store: QaAssistantStore): QaAssistantView {
 
   const host = document.createElement("div");
   host.id = QA_ASSISTANT_HOST_ID;
+  for (const [property, value] of HOST_STYLES) {
+    host.style.setProperty(property, value, "important");
+  }
   const shadow = host.attachShadow({ mode: "open" });
   const style = document.createElement("style");
   style.textContent = CSS;
@@ -615,10 +708,14 @@ export function mountQaAssistantView(store: QaAssistantStore): QaAssistantView {
   };
 
   const signature = (state: QaAssistantState): string => JSON.stringify({
+    storeVersion: state.storeVersion,
     experiments: state.experiments,
     forcedSummary: state.forcedSummary,
+    forcedUnavailable: state.forcedUnavailable.map(({ experimentId, reason }) => [experimentId, reason]),
+    edgeDeviceAudienceUnsupported: state.edgeDeviceAudienceUnsupported.map(({ experimentId, audienceName }) => [experimentId, audienceName]),
     transactions: state.transactions,
     events: view.tab === "ev" ? state.events : undefined,
+    goalScopes: view.tab === "ev" ? state.goalScopes : undefined,
     view: [view.tab, view.minimized, [...view.expanded], [...view.codeOpen], view.pageFilter, view.statusFilter, view.search],
   });
 

package/src/react/index.test.tsx

@@ -6,6 +6,7 @@ import type { Assignment, Experiment } from "../types";
 import {
   DripProvider,
   useFeatureFlag,
+  useGetCartMetafields,
   useTrackGoal,
   useVariation,
 } from "./index";
@@ -17,6 +18,7 @@ const sdkMock = vi.hoisted(() => ({
   trackGoal: vi.fn(),
   track: vi.fn(),
   trackRevenue: vi.fn(),
+  getCartMetafields: vi.fn(),
 }));
 
 vi.mock("../index", () => sdkMock);
@@ -29,6 +31,7 @@ function assignment(
   return {
     experimentId,
     variationId,
+    pageActive: true,
     index: 0,
     mutations: [],
     isControl,
@@ -43,6 +46,7 @@ function resetSdkMock() {
   sdkMock.trackGoal.mockReset();
   sdkMock.track.mockReset();
   sdkMock.trackRevenue.mockReset();
+  sdkMock.getCartMetafields.mockReset();
   sdkMock.init.mockReturnValue([]);
   sdkMock.getAssignments.mockReturnValue([]);
   sdkMock.getExperiments.mockReturnValue([]);
@@ -70,6 +74,18 @@ function GoalButton() {
   );
 }
 
+function CartMetafieldsButton() {
+  const getCartMetafields = useGetCartMetafields();
+  return (
+    <button
+      type="button"
+      onClick={() => getCartMetafields({ namespace: "merchant_bi" })}
+    >
+      Build cart metafields
+    </button>
+  );
+}
+
 describe("React bindings", () => {
   beforeEach(() => {
     resetSdkMock();
@@ -174,4 +190,25 @@ describe("React bindings", () => {
       expect(sdkMock.trackGoal).toHaveBeenCalledWith("signup", { plan: "pro" });
     });
   });
+
+  it("exposes the cart-metafield callback through a public hook", async () => {
+    sdkMock.getCartMetafields.mockReturnValue([{
+      key: "merchant_bi.apex_assignments",
+      type: "json",
+      value: "[]",
+    }]);
+
+    render(
+      <DripProvider shopId="shop_123">
+        <CartMetafieldsButton />
+      </DripProvider>,
+    );
+
+    await waitFor(() => expect(sdkMock.init).toHaveBeenCalled());
+    fireEvent.click(screen.getByRole("button", { name: "Build cart metafields" }));
+
+    await waitFor(() => {
+      expect(sdkMock.getCartMetafields).toHaveBeenCalledWith({ namespace: "merchant_bi" });
+    });
+  });
 });

package/src/react/index.tsx

@@ -2,7 +2,7 @@
  * React bindings for Drip SDK.
  *
  * Usage:
- *   import { DripProvider, useExperiment, useVariation, useFeatureFlag, useFeatureFlagValue, useTrackGoal } from "@drip-apex/sdk/react";
+ *   import { DripProvider, useExperiment, useVariation, useFeatureFlag, useFeatureFlagValue, useTrackGoal, useGetCartMetafields } from "@drip-apex/sdk/react";
  *
  *   function App() {
  *     return (
@@ -40,6 +40,7 @@ import {
 } from "react";
 import type { Assignment, Experiment, InitConfig, Variation } from "../types";
 import type { RevenueEventData } from "../index";
+import type { CartMetafieldInput } from "../shopify-cart";
 
 // ---------------------------------------------------------------------------
 // Context
@@ -58,6 +59,8 @@ interface DripContextValue {
   track: (type: string, data?: Record<string, unknown>) => void;
   /** Track revenue. */
   trackRevenue: (revenue: number, data?: RevenueEventData) => void;
+  /** Build headless Shopify cart metafields from the current attribution stamp. */
+  getCartMetafields: (options?: { namespace?: string }) => Promise<CartMetafieldInput[]>;
 }
 
 const DripContext = createContext<DripContextValue | null>(null);
@@ -140,9 +143,13 @@ export function DripProvider({
     import("../index").then((sdk) => sdk.trackRevenue(revenue, data));
   }, []);
 
+  const getCartMetafields = useCallback((options?: { namespace?: string }) => {
+    return import("../index").then((sdk) => sdk.getCartMetafields(options));
+  }, []);
+
   const value = useMemo<DripContextValue>(
-    () => ({ assignments, experiments, loading, trackGoal, track, trackRevenue }),
-    [assignments, experiments, loading, trackGoal, track, trackRevenue],
+    () => ({ assignments, experiments, loading, trackGoal, track, trackRevenue, getCartMetafields }),
+    [assignments, experiments, loading, trackGoal, track, trackRevenue, getCartMetafields],
   );
 
   return <DripContext.Provider value={value}>{children}</DripContext.Provider>;
@@ -232,6 +239,14 @@ export function useTrackRevenue(): (revenue: number, data?: Record<string, unkno
   return trackRevenue;
 }
 
+/**
+ * Returns a function that builds the current Shopify cart-metafield mirror.
+ */
+export function useGetCartMetafields(): DripContextValue["getCartMetafields"] {
+  const { getCartMetafields } = useDrip();
+  return getCartMetafields;
+}
+
 /**
  * Get all current assignments.
  */
@@ -250,3 +265,4 @@ export function useLoading(): boolean {
 
 // Re-export types for convenience
 export type { Assignment, Experiment, Variation, InitConfig } from "../types";
+export type { CartMetafieldInput } from "../shopify-cart";