@drip-apex/sdk 0.1.0 → 0.3.0

package/src/edge-adoption.test.ts

@@ -0,0 +1,435 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { decideAssignments } from "./decide-assignments";
+
+const experiment = {
+  id: "exp_edge_identity",
+  name: "Edge identity",
+  status: "running" as const,
+  trafficAllocation: 1,
+  variations: [
+    { id: "var_a", weight: 0.5, mutations: [] },
+    { id: "var_b", weight: 0.5, mutations: [] },
+  ],
+};
+
+const hashAttributeExperiment = {
+  id: "exp_edge_attribute",
+  kind: "feature_flag" as const,
+  featureFlag: { key: "edge_attribute" },
+  name: "Edge attribute",
+  status: "running" as const,
+  hashAttribute: "account_id",
+  trafficAllocation: 1,
+  variations: [
+    { id: "var_attribute_a", weight: 0.5, mutations: [] },
+    {
+      id: "var_attribute_b",
+      weight: 0.5,
+      mutations: [{
+        selector: "#edge-target",
+        action: "insertAfter" as const,
+        html: '<span data-testid="edge-insert">Edge choice</span>',
+      }],
+    },
+  ],
+};
+
+const idempotentEdgeExperiment = {
+  id: "exp_edge_text",
+  name: "Edge text",
+  status: "running" as const,
+  trafficAllocation: 1,
+  variations: [
+    { id: "var_text_a", weight: 0.5, mutations: [] },
+    {
+      id: "var_text_b",
+      weight: 0.5,
+      mutations: [{ selector: "#edge-text", action: "text" as const, text: "Edge choice" }],
+    },
+  ],
+};
+
+function variationFor(visitorId: string): string {
+  return decideAssignments({
+    experiments: [experiment],
+    visitorId,
+    now: 1,
+    url: location.href,
+  })[0].variationId;
+}
+
+function visitorFor(prefix: string, variationId: string): string {
+  const visitorId = Array.from({ length: 100 }, (_, index) => `${prefix}-${index}`)
+    .find((candidate) => variationFor(candidate) === variationId);
+  if (!visitorId) throw new Error(`Could not find ${variationId} visitor`);
+  return visitorId;
+}
+
+function attributeFor(variationId: string): string {
+  const attribute = Array.from({ length: 100 }, (_, index) => `account-${index}`)
+    .find((candidate) => decideAssignments({
+      experiments: [hashAttributeExperiment],
+      visitorId: candidate,
+      now: 1,
+      url: location.href,
+    })[0]?.variationId === variationId);
+  if (!attribute) throw new Error(`Could not find ${variationId} attribute`);
+  return attribute;
+}
+
+function installCookieJar(initial: Record<string, string>) {
+  const cookies = new Map(Object.entries(initial));
+  const writes: string[] = [];
+  Object.defineProperty(document, "cookie", {
+    configurable: true,
+    get: () => Array.from(cookies, ([name, value]) => `${name}=${value}`).join("; "),
+    set: (raw: string) => {
+      writes.push(raw);
+      const [pair] = raw.split(";");
+      const separator = pair.indexOf("=");
+      if (separator < 0) return;
+      cookies.set(pair.slice(0, separator).trim(), pair.slice(separator + 1));
+    },
+  });
+  return { cookies, writes };
+}
+
+describe("edge visitor identity adoption", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    localStorage.clear();
+    sessionStorage.clear();
+    delete (globalThis as Record<string, unknown>).__drip;
+    delete (globalThis as Record<string, unknown>).__dripEdgeInit;
+    delete (globalThis as Record<string, unknown>).__dripEdgeAssignments;
+    history.replaceState({}, "", "/");
+    document.body.innerHTML = "";
+    globalThis.fetch = vi.fn(async () => new Response("ok", { status: 202 })) as typeof fetch;
+  });
+
+  afterEach(async () => {
+    await vi.dynamicImportSettled();
+    vi.restoreAllMocks();
+    delete (globalThis as Record<string, unknown>).__drip;
+    delete (globalThis as Record<string, unknown>).__dripEdgeInit;
+    delete (globalThis as Record<string, unknown>).__dripEdgeAssignments;
+  });
+
+  it("adopts the edge drip_uid for an anonymous visitor and buckets with it", async () => {
+    const edgeVisitorId = visitorFor("edge", "var_a");
+    const staleVisitorId = visitorFor("stale", "var_b");
+    const cookieJar = installCookieJar({ drip_uid: edgeVisitorId });
+    localStorage.setItem("drip_uid", staleVisitorId);
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = [{
+      experimentId: experiment.id,
+      variationId: variationFor(edgeVisitorId),
+      index: experiment.variations.findIndex((variation) => variation.id === variationFor(edgeVisitorId)),
+    }];
+    const { getRuntimeValue, init } = await import("./index");
+
+    const assignments = init({ antiFlickerMode: "off", experiments: [experiment] });
+
+    expect(getRuntimeValue("orderAttribution")).toMatchObject({ visitorId: edgeVisitorId });
+    expect(assignments).toEqual([
+      expect.objectContaining({ experimentId: experiment.id, variationId: variationFor(edgeVisitorId) }),
+    ]);
+    expect(localStorage.getItem("drip_uid")).toBe(edgeVisitorId);
+    expect(cookieJar.cookies.get("drip_uid")).toBe(edgeVisitorId);
+    expect(cookieJar.writes.filter((write) => write.startsWith("drip_uid="))).toEqual([]);
+  });
+
+  it("uses an explicit config userId and ignores the edge cookie", async () => {
+    const explicitVisitorId = visitorFor("explicit", "var_a");
+    const edgeVisitorId = visitorFor("edge", "var_b");
+    const cookieJar = installCookieJar({ drip_uid: edgeVisitorId });
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = [{
+      experimentId: experiment.id,
+      variationId: variationFor(edgeVisitorId),
+      index: experiment.variations.findIndex((variation) => variation.id === variationFor(edgeVisitorId)),
+    }];
+    const { getRuntimeValue, init } = await import("./index");
+
+    const assignments = init({
+      antiFlickerMode: "off",
+      experiments: [experiment],
+      userId: explicitVisitorId,
+    });
+
+    expect(getRuntimeValue("orderAttribution")).toMatchObject({ visitorId: explicitVisitorId });
+    expect(assignments).toEqual([
+      expect.objectContaining({ experimentId: experiment.id, variationId: variationFor(explicitVisitorId) }),
+    ]);
+    expect(cookieJar.cookies.get("drip_uid")).toBe(edgeVisitorId);
+  });
+
+  it("assigns an experiment that is absent from the edge assignment payload normally", async () => {
+    const edgeVisitorId = visitorFor("edge", "var_b");
+    const sdkAttribute = attributeFor("var_attribute_a");
+    installCookieJar({ drip_uid: edgeVisitorId });
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = [{
+      experimentId: experiment.id,
+      variationId: "var_b",
+      index: 1,
+    }];
+    const { init } = await import("./index");
+
+    const assignments = init({
+      antiFlickerMode: "off",
+      attributes: { account_id: sdkAttribute },
+      experiments: [experiment, hashAttributeExperiment],
+    });
+
+    expect(assignments).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        experimentId: experiment.id,
+        variationId: "var_b",
+        index: 1,
+      }),
+      expect.objectContaining({
+        experimentId: hashAttributeExperiment.id,
+        variationId: "var_attribute_a",
+        index: 0,
+      }),
+    ]));
+  });
+
+  it("fails closed when the active edge assignment payload is malformed", async () => {
+    installCookieJar({ drip_uid: "edge-visitor" });
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = { malformed: true };
+    const { init } = await import("./index");
+
+    const assignments = init({ antiFlickerMode: "off", experiments: [experiment] });
+
+    expect(assignments).toEqual([]);
+  });
+
+  it("fails closed when an edge assignment does not match a real variation index", async () => {
+    installCookieJar({ drip_uid: "edge-visitor" });
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = [{
+      experimentId: experiment.id,
+      variationId: "var_missing",
+      index: 0,
+    }];
+    const { init } = await import("./index");
+
+    const assignments = init({ antiFlickerMode: "off", experiments: [experiment] });
+
+    expect(assignments).toEqual([]);
+  });
+
+  it("applies an edge insert exactly once in the SDK", async () => {
+    const sdkAttribute = attributeFor("var_attribute_a");
+    installCookieJar({ drip_uid: "edge-visitor" });
+    document.body.innerHTML = '<button id="edge-target">Target</button>';
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = [{
+      experimentId: hashAttributeExperiment.id,
+      variationId: "var_attribute_b",
+      index: 1,
+    }];
+    const { init } = await import("./index");
+
+    init({
+      antiFlickerMode: "off",
+      attributes: { account_id: sdkAttribute },
+      experiments: [hashAttributeExperiment],
+      spa: { activationMode: "manual" },
+    });
+
+    expect(document.querySelectorAll('[data-testid="edge-insert"]')).toHaveLength(1);
+  });
+
+  it("retains an edge-adopted hashAttribute assignment across SPA re-evaluation and applies its insert exactly once", async () => {
+    const sdkAttribute = attributeFor("var_attribute_a");
+    installCookieJar({ drip_uid: "edge-visitor" });
+    document.body.innerHTML = '<button id="edge-target">Target</button>';
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = [{
+      experimentId: hashAttributeExperiment.id,
+      variationId: "var_attribute_b",
+      index: 1,
+    }];
+    const { init, reInit } = await import("./index");
+
+    const assignments = init({
+      antiFlickerMode: "off",
+      attributes: { account_id: sdkAttribute },
+      experiments: [hashAttributeExperiment],
+      spa: { activationMode: "manual" },
+    });
+
+    expect(decideAssignments({
+      experiments: [hashAttributeExperiment],
+      visitorId: sdkAttribute,
+      now: 1,
+      url: location.href,
+    })[0]?.variationId).toBe("var_attribute_a");
+    expect(assignments).toEqual([
+      expect.objectContaining({
+        experimentId: hashAttributeExperiment.id,
+        variationId: "var_attribute_b",
+        index: 1,
+      }),
+    ]);
+    expect(document.querySelectorAll('[data-testid="edge-insert"]')).toHaveLength(1);
+
+    const spaAssignments = reInit(true);
+
+    expect(spaAssignments).toEqual([
+      expect.objectContaining({
+        experimentId: hashAttributeExperiment.id,
+        variationId: "var_attribute_b",
+        index: 1,
+      }),
+    ]);
+    expect(document.querySelectorAll('[data-testid="edge-insert"]')).toHaveLength(1);
+  });
+
+  it("re-applies an idempotent edge text mutation without changing the rendered result", async () => {
+    installCookieJar({ drip_uid: "edge-visitor" });
+    document.body.innerHTML = '<p id="edge-text">Edge choice</p>';
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = [{
+      experimentId: idempotentEdgeExperiment.id,
+      variationId: "var_text_b",
+      index: 1,
+    }];
+    const { init } = await import("./index");
+
+    const assignments = init({
+      antiFlickerMode: "off",
+      experiments: [idempotentEdgeExperiment],
+      spa: { activationMode: "manual" },
+    });
+
+    expect(assignments).toEqual([
+      expect.objectContaining({
+        experimentId: idempotentEdgeExperiment.id,
+        variationId: "var_text_b",
+        index: 1,
+      }),
+    ]);
+    expect(document.querySelectorAll("#edge-text")).toHaveLength(1);
+    expect(document.querySelector("#edge-text")?.textContent).toBe("Edge choice");
+  });
+
+  it("keeps an edge assignment ahead of a client fallback in the same exclusion group", async () => {
+    const fallbackExperiment = {
+      id: "exp_edge_fallback",
+      name: "Edge fallback conflict",
+      status: "running" as const,
+      trafficAllocation: 1,
+      variations: [{ id: "var_fallback", weight: 1, mutations: [] }],
+    };
+    installCookieJar({ drip_uid: "edge-visitor" });
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = [{
+      experimentId: experiment.id,
+      variationId: "var_a",
+      index: 0,
+    }];
+    const { getDiagnostics, init } = await import("./index");
+
+    const assignments = init({
+      antiFlickerMode: "off",
+      experiments: [experiment, fallbackExperiment],
+      exclusionGroups: [{
+        id: "edge-group",
+        members: [
+          { experimentId: experiment.id, share: 0.5 },
+          { experimentId: fallbackExperiment.id, share: 0.5 },
+        ],
+      }],
+    });
+
+    expect(assignments).toEqual([
+      expect.objectContaining({ experimentId: experiment.id, variationId: "var_a" }),
+    ]);
+    expect(getDiagnostics().activation.experiments.find(
+      (diagnostic) => diagnostic.experimentId === fallbackExperiment.id,
+    )).toMatchObject({ status: "failed", reason: "exclusion_group_overlap_lost" });
+  });
+
+  it("deactivates an edge assignment after an SPA route becomes ineligible", async () => {
+    const targetedExperiment = {
+      ...hashAttributeExperiment,
+      id: "exp_edge_targeted",
+      targeting: {
+        url: [{ type: "simple" as const, pattern: "/eligible", include: true }],
+      },
+    };
+    history.replaceState({}, "", "/eligible");
+    installCookieJar({ drip_uid: "edge-visitor" });
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = [{
+      experimentId: targetedExperiment.id,
+      variationId: "var_attribute_b",
+      index: 1,
+    }];
+    const { init, reInit } = await import("./index");
+
+    expect(init({
+      antiFlickerMode: "off",
+      experiments: [targetedExperiment],
+      spa: { activationMode: "manual" },
+    })).toEqual([
+      expect.objectContaining({ experimentId: targetedExperiment.id, pageActive: true }),
+    ]);
+
+    history.replaceState({}, "", "/ineligible");
+    const spaAssignments = reInit(true);
+
+    expect(spaAssignments).toEqual([]);
+  });
+
+  it("does not activate an edge assignment on an ineligible initial route", async () => {
+    const targetedExperiment = {
+      ...hashAttributeExperiment,
+      id: "exp_edge_initial_targeted",
+      targeting: {
+        url: [{ type: "simple" as const, pattern: "/eligible", include: true }],
+      },
+    };
+    history.replaceState({}, "", "/ineligible");
+    installCookieJar({ drip_uid: "edge-visitor" });
+    document.body.innerHTML = '<button id="edge-target">Target</button>';
+    (globalThis as Record<string, unknown>).__dripEdgeInit = true;
+    (globalThis as Record<string, unknown>).__dripEdgeAssignments = [{
+      experimentId: targetedExperiment.id,
+      variationId: "var_attribute_b",
+      index: 1,
+    }];
+    const { init } = await import("./index");
+
+    const assignments = init({
+      antiFlickerMode: "off",
+      experiments: [targetedExperiment],
+      spa: { activationMode: "manual" },
+    });
+
+    expect(assignments).toEqual([]);
+    expect(document.querySelectorAll('[data-testid="edge-insert"]')).toHaveLength(0);
+  });
+
+  it("keeps existing identity precedence when the edge runtime is inactive", async () => {
+    const storedVisitorId = visitorFor("stored", "var_a");
+    const cookieVisitorId = visitorFor("cookie", "var_b");
+    installCookieJar({ drip_uid: cookieVisitorId });
+    localStorage.setItem("drip_uid", storedVisitorId);
+    const { getRuntimeValue, init } = await import("./index");
+
+    const assignments = init({ antiFlickerMode: "off", experiments: [experiment] });
+
+    expect(getRuntimeValue("orderAttribution")).toMatchObject({ visitorId: storedVisitorId });
+    expect(assignments).toEqual([
+      expect.objectContaining({ experimentId: experiment.id, variationId: variationFor(storedVisitorId) }),
+    ]);
+    expect(localStorage.getItem("drip_uid")).toBe(storedVisitorId);
+  });
+});

package/src/edge-runtime.ts

@@ -0,0 +1,30 @@
+export type EdgeRuntimeAssignment = {
+  experimentId: string;
+  variationId: string;
+  index: number;
+};
+
+type EdgeRuntimeGlobals = Record<string, unknown>;
+
+export function edgeRuntimeActive(): boolean {
+  return (globalThis as EdgeRuntimeGlobals).__dripEdgeInit === true;
+}
+
+/**
+ * Reads the edge worker's authoritative assignment set.
+ * The adoption evaluator validates each selected variation and index.
+ */
+export function readEdgeRuntimeAssignments(): Map<string, EdgeRuntimeAssignment> | null {
+  if (!edgeRuntimeActive()) return null;
+  const raw = (globalThis as EdgeRuntimeGlobals).__dripEdgeAssignments;
+  if (!Array.isArray(raw)) return new Map();
+  const assignments = new Map<string, EdgeRuntimeAssignment>();
+  for (const value of raw) {
+    if (!value || typeof value !== "object") return new Map();
+    const assignment = value as EdgeRuntimeAssignment;
+    const { experimentId } = assignment;
+    if (typeof experimentId !== "string") return new Map();
+    assignments.set(experimentId, assignment);
+  }
+  return assignments;
+}

package/src/editor/api.test.ts

@@ -97,6 +97,115 @@ describe("EditorApi", () => {
     );
   });
 
+  it("parses a saved-but-pending publication response", async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        ok: true,
+        saved: true,
+        artifact_hash: "hash-2",
+        publication: {
+          status: "pending",
+          code: "storefront_publication_pending",
+          message: "Saved, but publication is pending.",
+        },
+        reviewStatus: "approved",
+        warningIssues: [{ message: "Saved, but publication is pending." }],
+        artifacts: { mutations: [], customCss: "", customJs: "" },
+      }),
+    })) as unknown as typeof fetch;
+    const api = new EditorApi("https://app.example", session, fetchMock);
+
+    await expect(
+      api.saveArtifacts(
+        "variation-1",
+        { mutations: [], customCss: "", customJs: "" },
+        "hash-1",
+      ),
+    ).resolves.toMatchObject({
+      outcome: {
+        saved: true,
+        artifactHash: "hash-2",
+        publication: { status: "pending" },
+      },
+    });
+  });
+
+  it("maps a legacy successful save response to an OK publication outcome", async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        ok: true,
+        artifactHash: "legacy-hash-2",
+        reviewStatus: "approved",
+        artifacts: { mutations: [], customCss: "", customJs: "" },
+      }),
+    })) as unknown as typeof fetch;
+    const api = new EditorApi("https://app.example", session, fetchMock);
+
+    await expect(
+      api.saveArtifacts(
+        "variation-1",
+        { mutations: [], customCss: "", customJs: "" },
+        "hash-1",
+      ),
+    ).resolves.toMatchObject({
+      artifactHash: "legacy-hash-2",
+      outcome: {
+        saved: true,
+        artifactHash: "legacy-hash-2",
+        publication: { status: "ok" },
+      },
+    });
+  });
+
+  it("retains a committed publication failure payload on a 502", async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: false,
+      status: 502,
+      json: async () => ({
+        ok: false,
+        saved: true,
+        artifact_hash: "hash-2",
+        publication: {
+          status: "failed",
+          code: "storefront_publication_failed",
+          message: "Saved, but storefront publication failed.",
+        },
+        error: "Saved, but storefront publication failed.",
+      }),
+    })) as unknown as typeof fetch;
+    const api = new EditorApi("https://app.example", session, fetchMock);
+
+    await expect(
+      api.saveArtifacts(
+        "variation-1",
+        { mutations: [], customCss: "", customJs: "" },
+        "hash-1",
+      ),
+    ).rejects.toMatchObject<Partial<EditorApiError>>({
+      status: 502,
+      payload: {
+        ok: false,
+        saved: true,
+        artifact_hash: "hash-2",
+        publication: {
+          status: "failed",
+          code: "storefront_publication_failed",
+          message: "Saved, but storefront publication failed.",
+        },
+        error: "Saved, but storefront publication failed.",
+      },
+      outcome: {
+        saved: true,
+        artifactHash: "hash-2",
+        publication: { status: "failed" },
+      },
+    });
+  });
+
   it("rejects load responses without the required optimistic artifact hash", async () => {
     const fetchMock = vi.fn(async () => ({
       ok: true,

package/src/editor/api.ts

@@ -5,14 +5,21 @@ import type {
   EditorBrowserCommand,
   EditorVariation,
 } from "./types";
+import {
+  parseVariationSaveOutcome,
+  type VariationSaveOutcome,
+} from "./publication-result";
 
 export class EditorApiError extends Error {
+  readonly outcome: VariationSaveOutcome | null;
+
   constructor(
     message: string,
     readonly status: number,
     readonly payload?: Record<string, unknown> | null,
   ) {
     super(message);
+    this.outcome = parseVariationSaveOutcome(payload);
   }
 }
 
@@ -108,6 +115,7 @@ export class EditorApi {
   ): Promise<{
     artifactHash: string;
     reviewStatus: string | null;
+    outcome: VariationSaveOutcome;
     warningIssues: Array<{ code?: string; message?: string }>;
     artifacts: EditorArtifacts;
   }> {
@@ -118,12 +126,35 @@ export class EditorApi {
         body: JSON.stringify({ ...artifacts, expectedPriorHash }),
       },
     );
-    if (typeof payload.artifactHash !== "string") {
-      throw new EditorApiError("Editor save response did not include an artifact hash", 500, payload);
+    const parsedOutcome = parseVariationSaveOutcome(payload);
+    const hasPublicationOutcomeFields =
+      Object.prototype.hasOwnProperty.call(payload, "saved") ||
+      Object.prototype.hasOwnProperty.call(payload, "artifact_hash") ||
+      Object.prototype.hasOwnProperty.call(payload, "publication");
+    const legacyArtifactHash =
+      typeof payload.artifactHash === "string" && payload.artifactHash.trim()
+        ? payload.artifactHash
+        : null;
+    const outcome =
+      parsedOutcome ??
+      (!hasPublicationOutcomeFields
+        ? {
+            saved: true,
+            artifactHash: legacyArtifactHash,
+            publication: {
+              status: "ok" as const,
+              code: "variation_saved",
+              message: "Saved",
+            },
+          }
+        : null);
+    if (!outcome?.saved || !outcome.artifactHash) {
+      throw new EditorApiError("Editor save response did not include a complete publication outcome", 500, payload);
     }
     return {
-      artifactHash: payload.artifactHash,
+      artifactHash: outcome.artifactHash,
       reviewStatus: typeof payload.reviewStatus === "string" ? payload.reviewStatus : null,
+      outcome,
       warningIssues: Array.isArray(payload.warningIssues)
         ? payload.warningIssues as Array<{ code?: string; message?: string }>
         : [],