@drip-apex/sdk 0.1.0 → 0.2.0

package/src/editor/controller.test.ts

@@ -11,6 +11,7 @@ const session: ActiveEditorSession = {
   expiresAt: new Date(Date.now() + 60_000).toISOString(),
   shopId: "shop-1",
   experimentId: "experiment-1",
+  experimentStatus: "draft",
   initialVariationId: "variation-1",
   targetUrl: "https://shop.example/",
   targetOrigin: "https://shop.example",
@@ -26,6 +27,15 @@ function fakeApi(artifacts: EditorArtifacts = { mutations: [], customCss: "", cu
     saveArtifacts: vi.fn(async (_variationId: string, next: EditorArtifacts) => ({
       artifactHash: "hash-2",
       reviewStatus: "approved",
+      outcome: {
+        saved: true as const,
+        artifactHash: "hash-2",
+        publication: {
+          status: "ok" as const,
+          code: "variation_saved",
+          message: "The treatment was saved.",
+        },
+      },
       warningIssues: [],
       artifacts: next,
     })),
@@ -102,18 +112,12 @@ describe("EditorController", () => {
   });
 
   it("serializes autosaves and sends the latest draft with the newest hash", async () => {
-    let resolveFirst!: (value: {
-      artifactHash: string;
-      reviewStatus: string;
-      warningIssues: never[];
-      artifacts: EditorArtifacts;
-    }) => void;
-    const firstSave = new Promise<{
-      artifactHash: string;
-      reviewStatus: string;
-      warningIssues: never[];
-      artifacts: EditorArtifacts;
-    }>((resolve) => { resolveFirst = resolve; });
+    let resolveFirst!: (
+      value: Awaited<ReturnType<EditorApi["saveArtifacts"]>>,
+    ) => void;
+    const firstSave = new Promise<
+      Awaited<ReturnType<EditorApi["saveArtifacts"]>>
+    >((resolve) => { resolveFirst = resolve; });
     const api = fakeApi();
     api.saveArtifacts.mockImplementationOnce(() => firstSave);
     const controller = new EditorController(session, "https://app.example", api as unknown as EditorApi);
@@ -130,6 +134,15 @@ describe("EditorController", () => {
     resolveFirst({
       artifactHash: "hash-2",
       reviewStatus: "approved",
+      outcome: {
+        saved: true,
+        artifactHash: "hash-2",
+        publication: {
+          status: "ok",
+          code: "variation_saved",
+          message: "The treatment was saved.",
+        },
+      },
       warningIssues: [],
       artifacts: { mutations: [], customCss: "h1{color:blue}", customJs: "" },
     });
@@ -146,6 +159,238 @@ describe("EditorController", () => {
     controller.destroy();
   });
 
+  it("confirms a running save once and keeps publication contention distinct", async () => {
+    const api = fakeApi();
+    api.saveArtifacts.mockResolvedValue({
+      artifactHash: "hash-2",
+      reviewStatus: "approved",
+      outcome: {
+        saved: true,
+        artifactHash: "hash-2",
+        publication: {
+          status: "pending",
+          code: "storefront_publication_pending",
+          message: "Saved, but publication is pending.",
+        },
+      },
+      warningIssues: [{ message: "Saved, but publication is pending." }],
+      artifacts: { mutations: [], customCss: "h1{color:blue}", customJs: "" },
+    });
+    const confirmLiveSave = vi.fn(() => true);
+    const controller = new EditorController(
+      { ...session, experimentStatus: "running" },
+      "https://app.example",
+      api as unknown as EditorApi,
+      () => undefined,
+      confirmLiveSave,
+    );
+    await controller.initialize();
+
+    controller.setCustomCss("h1{color:blue}");
+    await vi.advanceTimersByTimeAsync(700);
+    expect(controller.getState()).toMatchObject({
+      saveState: "pending",
+      saveMessage: "Saved, but publication is pending.",
+    });
+
+    controller.setCustomCss("h1{color:green}");
+    await vi.advanceTimersByTimeAsync(700);
+    expect(confirmLiveSave).toHaveBeenCalledOnce();
+    expect(api.saveArtifacts).toHaveBeenCalledTimes(2);
+    controller.destroy();
+  });
+
+  it("renders a soft publication warning as a distinct saved state", async () => {
+    const api = fakeApi();
+    api.saveArtifacts.mockResolvedValue({
+      artifactHash: "hash-2",
+      reviewStatus: "approved",
+      outcome: {
+        saved: true,
+        artifactHash: "hash-2",
+        publication: {
+          status: "warning",
+          code: "storefront_publication_incomplete",
+          message: "Saved and published, but Shopify synchronization is incomplete.",
+        },
+      },
+      warningIssues: [],
+      artifacts: { mutations: [], customCss: "h1{color:blue}", customJs: "" },
+    });
+    const controller = new EditorController(
+      session,
+      "https://app.example",
+      api as unknown as EditorApi,
+    );
+    await controller.initialize();
+
+    controller.setCustomCss("h1{color:blue}");
+    await vi.advanceTimersByTimeAsync(700);
+
+    expect(controller.getState()).toMatchObject({
+      saveState: "warning",
+      saveMessage: "Saved and published, but Shopify synchronization is incomplete.",
+    });
+    controller.destroy();
+  });
+
+  it("requires a new live confirmation after the active variation changes", async () => {
+    const api = fakeApi();
+    api.loadArtifacts.mockImplementation(async (variationId: string) => ({
+      variation: {
+        id: variationId,
+        name: variationId,
+        artifactHash: `hash-${variationId}`,
+        reviewStatus: "approved",
+      },
+      artifacts: { mutations: [], customCss: "", customJs: "" },
+    }));
+    const confirmLiveSave = vi.fn(() => true);
+    const controller = new EditorController(
+      {
+        ...session,
+        experimentStatus: "running",
+        variations: [
+          { id: "variation-1", name: "First" },
+          { id: "variation-2", name: "Second" },
+        ],
+      },
+      "https://app.example",
+      api as unknown as EditorApi,
+      () => undefined,
+      confirmLiveSave,
+    );
+    await controller.initialize();
+
+    controller.setCustomCss("h1{color:blue}");
+    await vi.advanceTimersByTimeAsync(700);
+    await controller.selectVariation("variation-2");
+    controller.setCustomCss("h1{color:green}");
+    await vi.advanceTimersByTimeAsync(700);
+
+    expect(confirmLiveSave).toHaveBeenCalledTimes(2);
+    controller.destroy();
+  });
+
+  it("adopts a committed error hash and retries from the new hash", async () => {
+    const api = fakeApi();
+    api.saveArtifacts.mockRejectedValueOnce(
+      new EditorApiError(
+        "Saved, but storefront publication failed.",
+        400,
+        {
+          ok: false,
+          saved: true,
+          artifact_hash: "hash-after-save",
+          publication: {
+            status: "failed",
+            code: "storefront_publication_failed",
+            message: "Saved, but storefront publication failed.",
+          },
+          reviewStatus: "needs_review",
+        },
+      ),
+    );
+    const controller = new EditorController(
+      session,
+      "https://app.example",
+      api as unknown as EditorApi,
+    );
+    await controller.initialize();
+
+    controller.setCustomCss("h1{color:blue}");
+    await vi.advanceTimersByTimeAsync(700);
+    expect(controller.getState()).toMatchObject({
+      variation: {
+        artifactHash: "hash-after-save",
+        reviewStatus: "needs_review",
+      },
+      saveState: "publication_failed",
+      saveMessage: "Saved, but storefront publication failed.",
+    });
+
+    controller.setCustomCss("h1{color:green}");
+    await vi.advanceTimersByTimeAsync(700);
+    expect(api.saveArtifacts).toHaveBeenNthCalledWith(
+      2,
+      "variation-1",
+      expect.objectContaining({ customCss: "h1{color:green}" }),
+      "hash-after-save",
+    );
+    expect(controller.getState().saveState).toBe("saved");
+    controller.destroy();
+  });
+
+  it("does not write when the first running save confirmation is declined", async () => {
+    const api = fakeApi();
+    const controller = new EditorController(
+      { ...session, experimentStatus: "running" },
+      "https://app.example",
+      api as unknown as EditorApi,
+      () => undefined,
+      () => false,
+    );
+    await controller.initialize();
+
+    controller.setCustomCss("h1{color:blue}");
+    await vi.advanceTimersByTimeAsync(700);
+
+    expect(api.saveArtifacts).not.toHaveBeenCalled();
+    expect(controller.getState()).toMatchObject({
+      saveState: "idle",
+      saveMessage: "Live save cancelled. Your changes are still unsaved.",
+    });
+    controller.destroy();
+  });
+
+  it("saves an on-store QA experiment without a live-save confirmation", async () => {
+    const api = fakeApi();
+    const confirmLiveSave = vi.fn(() => false);
+    const controller = new EditorController(
+      { ...session, experimentStatus: "qa" },
+      "https://app.example",
+      api as unknown as EditorApi,
+      () => undefined,
+      confirmLiveSave,
+    );
+    await controller.initialize();
+
+    controller.setCustomCss("h1{color:blue}");
+    await vi.advanceTimersByTimeAsync(700);
+
+    expect(confirmLiveSave).not.toHaveBeenCalled();
+    expect(api.saveArtifacts).toHaveBeenCalledOnce();
+    expect(controller.getState().saveState).toBe("saved");
+    controller.destroy();
+  });
+
+  it.each([null, undefined, "unknown"])(
+    "fails closed when the experiment status is %s",
+    async (experimentStatus) => {
+      const api = fakeApi();
+      const confirmLiveSave = vi.fn(() => false);
+      const controller = new EditorController(
+        { ...session, experimentStatus },
+        "https://app.example",
+        api as unknown as EditorApi,
+        () => undefined,
+        confirmLiveSave,
+      );
+      await controller.initialize();
+
+      controller.setCustomCss("h1{color:blue}");
+      await vi.advanceTimersByTimeAsync(700);
+
+      expect(confirmLiveSave).toHaveBeenCalledOnce();
+      expect(api.saveArtifacts).not.toHaveBeenCalled();
+      expect(controller.getState()).toMatchObject({
+        saveState: "idle",
+        saveMessage: "Live save cancelled. Your changes are still unsaved.",
+      });
+      controller.destroy();
+    },
+  );
+
   it("ignores a stale variation response after a faster switch", async () => {
     let resolveFirst!: (value: Awaited<ReturnType<EditorApi["loadArtifacts"]>>) => void;
     const first = new Promise<Awaited<ReturnType<EditorApi["loadArtifacts"]>>>((resolve) => {
@@ -249,16 +494,54 @@ describe("EditorController", () => {
     const mutation = {
       selector: "#title",
       action: "html" as const,
-      html: `<strong onclick="steal()">Expected</strong><script>steal()</script>`,
+      html: `<strong onclick="steal()">Expected</strong><iframe srcdoc="steal()"></iframe><a href="data:text/html,steal()">link</a><script>steal()</script>`,
     };
 
     title.innerHTML = `<em>Different non-empty HTML</em>`;
     expect(verify(mutation, 1, 1)).toBe(false);
-    title.innerHTML = `<strong>Expected</strong>`;
+    title.innerHTML = `<strong>Expected</strong><iframe></iframe><a>link</a>`;
     expect(verify(mutation, 1, 1)).toBe(true);
     controller.destroy();
   });
 
+  it("verifies only safe attribute writes and dangerous attribute removals", async () => {
+    const api = fakeApi();
+    const controller = new EditorController(session, "https://app.example", api as unknown as EditorApi);
+    await controller.initialize();
+    const title = document.getElementById("title")!;
+
+    const mixedAudit = controller.applyCommandArtifacts({
+      mutations: [{
+        selector: "#title",
+        action: "attribute",
+        attributes: { class: "badge", onclick: "steal()" },
+      }],
+      customCss: "",
+      customJs: "",
+    });
+
+    expect(title.getAttribute("class")).toBe("badge");
+    expect(title.hasAttribute("onclick")).toBe(false);
+    expect(mixedAudit).toMatchObject({ ok: true });
+    expect(mixedAudit.mutationAudit[0]).toMatchObject({ effectVerified: true });
+
+    title.setAttribute("onclick", "existingHandler()");
+    const removalAudit = controller.applyCommandArtifacts({
+      mutations: [{
+        selector: "#title",
+        action: "attribute",
+        attributes: { onclick: null },
+      }],
+      customCss: "",
+      customJs: "",
+    });
+
+    expect(title.hasAttribute("onclick")).toBe(false);
+    expect(removalAudit).toMatchObject({ ok: true });
+    expect(removalAudit.mutationAudit[0]).toMatchObject({ effectVerified: true });
+    controller.destroy();
+  });
+
   it("bounds session revocation before reloading on exit", async () => {
     const api = fakeApi();
     api.revoke.mockImplementationOnce(() => new Promise<void>(() => {}));

package/src/editor/controller.ts

@@ -1,5 +1,5 @@
 import { createMutationApplicationContext, type MutationApplicationContext } from "../mutate";
-import { sanitizeHtml } from "../sanitize";
+import { isSafeMutationAttribute, sanitizeHtml } from "../sanitize";
 import type { Mutation } from "../types";
 import { EditorApi, EditorApiError } from "./api";
 import { ArtifactHistory, removeMutationAt, removeSelectorMutations, upsertMutation } from "./artifacts";
@@ -16,6 +16,7 @@ import {
 const EDITOR_CSS_ID = "apex-editor-draft-css";
 const AUTOSAVE_MS = 700;
 const EXIT_REVOKE_TIMEOUT_MS = 1_500;
+const NON_LIVE_EDITOR_STATUSES = new Set(["draft", "awaiting_client_approval", "changes_requested", "client_approved", "qa", "ready_to_launch", "paused", "completed"]);
 
 export type ArtifactCommandAudit = {
   ok: boolean;
@@ -68,6 +69,7 @@ export class EditorController {
   private saveQueue: Promise<void> = Promise.resolve();
   private revision = 0;
   private variationRequest = 0;
+  private liveSaveConfirmed = false;
   private readonly cleanups = new Set<() => void>();
 
   constructor(
@@ -75,6 +77,7 @@ export class EditorController {
     readonly apiOrigin: string,
     private readonly api = new EditorApi(apiOrigin, session),
     private readonly reload = () => location.reload(),
+    private readonly confirmLiveSave = (message: string) => window.confirm(message),
   ) {}
 
   getState(): EditorState {
@@ -92,6 +95,9 @@ export class EditorController {
   }
 
   async selectVariation(variationId: string): Promise<void> {
+    if (this.state.variation?.id !== variationId) {
+      this.liveSaveConfirmed = false;
+    }
     const request = ++this.variationRequest;
     this.cancelSave();
     this.patch({ saveState: "idle", saveMessage: "Loading draft..." });
@@ -368,6 +374,22 @@ export class EditorController {
     const expectedHash = this.state.variation.artifactHash;
     const snapshot = cloneArtifacts(this.state.artifacts);
     const saveRevision = this.revision;
+    if (
+      !NON_LIVE_EDITOR_STATUSES.has(this.session.experimentStatus ?? "") &&
+      !this.liveSaveConfirmed
+    ) {
+      const confirmed = this.confirmLiveSave(
+        "This test is live. Saving publishes this treatment to real visitors, and the result will span both treatment versions. Save now?",
+      );
+      if (!confirmed) {
+        this.patch({
+          saveState: "idle",
+          saveMessage: "Live save cancelled. Your changes are still unsaved.",
+        });
+        return;
+      }
+      this.liveSaveConfirmed = true;
+    }
     this.patch({ saveState: "saving", saveMessage: "Saving..." });
     try {
       const result = await this.api.saveArtifacts(variationId, snapshot, expectedHash);
@@ -381,15 +403,50 @@ export class EditorController {
           reviewStatus: result.reviewStatus,
         },
         artifacts: changedDuringSave ? this.state.artifacts : cloneArtifacts(result.artifacts),
-        saveState: changedDuringSave ? "idle" : "saved",
+        saveState: changedDuringSave
+          ? "idle"
+          : result.outcome.publication?.status === "pending"
+            ? "pending"
+            : result.outcome.publication?.status === "warning"
+              ? "warning"
+            : "saved",
         saveMessage: changedDuringSave
           ? "Saving latest changes..."
-          : result.warningIssues[0]?.message ?? "Saved",
+          : result.outcome.publication?.status === "pending"
+            ? result.warningIssues[0]?.message ??
+              "Saved. Storefront publication is pending and will retry automatically."
+            : result.outcome.publication?.status === "warning"
+              ? result.outcome.publication.message
+            : result.warningIssues[0]?.message ?? "Saved",
       };
       this.emit();
     } catch (error) {
       if (saveVariationRequest !== this.variationRequest || this.state.variation?.id !== variationId) return;
-      if (error instanceof EditorApiError && error.status === 409) {
+      if (
+        error instanceof EditorApiError &&
+        error.outcome?.saved === true &&
+        error.outcome.artifactHash
+      ) {
+        this.state = {
+          ...this.state,
+          variation: {
+            ...this.state.variation!,
+            artifactHash: error.outcome.artifactHash,
+            reviewStatus:
+              typeof error.payload?.reviewStatus === "string"
+                ? error.payload.reviewStatus
+                : this.state.variation!.reviewStatus,
+          },
+          saveState:
+            error.outcome.publication?.status === "pending"
+              ? "pending"
+              : error.outcome.publication?.status === "warning"
+                ? "warning"
+                : "publication_failed",
+          saveMessage: error.outcome.publication?.message ?? error.message,
+        };
+        this.emit();
+      } else if (error instanceof EditorApiError && error.status === 409) {
         this.patch({
           saveState: "conflict",
           saveMessage: "Draft changed elsewhere. Reload this variation before saving.",
@@ -559,7 +616,14 @@ export class EditorController {
         ...(mutation.attribute ? { [mutation.attribute.name]: mutation.attribute.value } : {}),
         ...(mutation.attributes ?? {}),
       };
-      return elements.every((element) => Object.entries(attributes).every(
+      const requestedAttributes = Object.entries(attributes);
+      const safeAttributes = requestedAttributes.filter(
+        ([name, value]) => isSafeMutationAttribute(name, value),
+      );
+      // A mutation whose every requested attribute was dropped as unsafe wrote
+      // nothing — it must not verify as success vacuously.
+      if (requestedAttributes.length > 0 && safeAttributes.length === 0) return false;
+      return elements.every((element) => safeAttributes.every(
         ([name, value]) => value === null
           ? !element.hasAttribute(name)
           : element.getAttribute(name) === value,

package/src/editor/index.test.ts

@@ -86,6 +86,7 @@ describe("editor session exchange", () => {
           expiresAt,
           shopId: "shop-1",
           experimentId: "experiment-1",
+          experimentStatus: "running",
           initialVariationId: "variation-1",
           targetUrl: "https://shop.example/products/one",
           targetOrigin: "https://shop.example",
@@ -109,6 +110,7 @@ describe("editor session exchange", () => {
       sid: launch.sid,
       bearer: "editor-bearer",
       initialVariationId: "variation-1",
+      experimentStatus: "running",
     });
     expect(postMessage).toHaveBeenCalledWith(
       {

package/src/editor/index.ts

@@ -79,6 +79,7 @@ function parseSession(value: unknown, sid: string): ActiveEditorSession | null {
     shopId: parsed.shopId,
     experimentId: parsed.experimentId,
     experimentName: readString(record.experimentName),
+    experimentStatus: readString(record.experimentStatus),
     initialVariationId: parsed.initialVariationId,
     targetUrl: parsed.targetUrl,
     targetOrigin: parsed.targetOrigin,

package/src/editor/publication-result.ts

@@ -0,0 +1,58 @@
+export type PublicationStatus = "ok" | "pending" | "warning" | "failed";
+
+export type VariationSaveOutcome = {
+  saved: boolean;
+  artifactHash: string | null;
+  publication: {
+    status: PublicationStatus;
+    code: string;
+    message: string;
+  } | null;
+};
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+export function parseVariationSaveOutcome(
+  value: unknown,
+): VariationSaveOutcome | null {
+  const payload = record(value);
+  if (!payload || typeof payload.saved !== "boolean") return null;
+  if (!payload.saved) {
+    return payload.publication === null
+      ? { saved: false, artifactHash: null, publication: null }
+      : null;
+  }
+  if (
+    typeof payload.artifact_hash !== "string" ||
+    !payload.artifact_hash.trim()
+  ) {
+    return null;
+  }
+  const publication = record(payload.publication);
+  if (
+    !publication ||
+    (publication.status !== "ok" &&
+      publication.status !== "pending" &&
+      publication.status !== "warning" &&
+      publication.status !== "failed") ||
+    typeof publication.code !== "string" ||
+    !publication.code ||
+    typeof publication.message !== "string" ||
+    !publication.message
+  ) {
+    return null;
+  }
+  return {
+    saved: true,
+    artifactHash: payload.artifact_hash,
+    publication: {
+      status: publication.status,
+      code: publication.code,
+      message: publication.message,
+    },
+  };
+}

package/src/editor/types.ts

@@ -7,6 +7,7 @@ export type ActiveEditorSession = {
   shopId: string;
   experimentId: string;
   experimentName?: string | null;
+  experimentStatus?: string | null;
   initialVariationId: string;
   targetUrl: string;
   targetOrigin: string;
@@ -51,7 +52,15 @@ export type ClaimedEditorCommand = {
   expiresAt: string | null;
 };
 
-export type EditorSaveState = "idle" | "saving" | "saved" | "conflict" | "error";
+export type EditorSaveState =
+  | "idle"
+  | "saving"
+  | "saved"
+  | "pending"
+  | "warning"
+  | "publication_failed"
+  | "conflict"
+  | "error";
 
 export type EditorDeviceState = "closed" | "loading" | "active" | "blocked";
 

package/src/editor/view-kit.ts

@@ -109,7 +109,8 @@ button:disabled{cursor:not-allowed}
 .save-chip.unsaved{color:var(--warning)}
 .save-chip.saving{color:var(--purple200)}
 .save-chip.saved{color:var(--positive)}
-.save-chip.failed,.save-chip.conflict{color:var(--negative-soft);background:rgba(235,82,82,0.10);border-color:rgba(235,82,82,0.25)}
+.save-chip.pending,.save-chip.warning{color:var(--warning);background:rgba(245,166,35,0.10);border-color:rgba(245,166,35,0.25)}
+.save-chip.failed,.save-chip.publication-failed,.save-chip.conflict{color:var(--negative-soft);background:rgba(235,82,82,0.10);border-color:rgba(235,82,82,0.25)}
 .save-chip .retry{border:none;background:rgba(255,255,255,0.1);color:#fff;font-size:11.5px;font-weight:600;border-radius:5px;padding:2px 7px;margin-left:2px;pointer-events:auto}
 
 /* Segmented control */