@drip-apex/sdk 0.1.0

package/src/editor/device-preview.ts

@@ -0,0 +1,120 @@
+import { createMutationApplicationContext, type MutationApplicationContext } from "../mutate";
+import type { EditorArtifacts, EditorDeviceState } from "./types";
+
+const FRAME_TIMEOUT_MS = 5_000;
+const DEVICE_STYLE_ID = "apex-editor-device-css";
+
+export type DevicePreviewSize = { width: number; height: number };
+
+export class DevicePreview {
+  private context: MutationApplicationContext | null = null;
+  private hiddenChildren: Array<{ element: HTMLElement; visibility: string }> = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private artifacts: EditorArtifacts | null = null;
+
+  constructor(
+    private readonly frame: HTMLIFrameElement,
+    private readonly onState: (state: EditorDeviceState) => void,
+  ) {}
+
+  open(artifacts: EditorArtifacts): void {
+    this.close(false);
+    this.artifacts = artifacts;
+    this.hideStorePage();
+    this.onState("loading");
+    this.frame.hidden = false;
+    this.frame.onload = () => this.handleLoad();
+    this.frame.onerror = () => this.blocked();
+    const url = new URL(location.href);
+    url.hash = "";
+    this.frame.src = url.toString();
+    this.timer = setTimeout(() => this.blocked(), FRAME_TIMEOUT_MS);
+  }
+
+  update(artifacts: EditorArtifacts, enabled = true): void {
+    this.artifacts = enabled ? artifacts : { mutations: [], customCss: "", customJs: "" };
+    const doc = this.readDocument();
+    if (doc) this.apply(doc, this.artifacts);
+  }
+
+  close(notify = true): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.context?.rollback();
+    this.context = null;
+    this.frame.onload = null;
+    this.frame.onerror = null;
+    this.frame.hidden = true;
+    this.frame.removeAttribute("src");
+    for (const item of this.hiddenChildren) {
+      item.element.style.visibility = item.visibility;
+    }
+    this.hiddenChildren = [];
+    if (notify) this.onState("closed");
+  }
+
+  private handleLoad(): void {
+    const doc = this.readDocument();
+    if (!doc?.body || !this.artifacts) {
+      this.blocked();
+      return;
+    }
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.apply(doc, this.artifacts);
+    this.onState("active");
+  }
+
+  private readDocument(): Document | null {
+    try {
+      const doc = this.frame.contentDocument;
+      const frameUrl = this.frame.contentWindow?.location.href ?? "";
+      if (!doc || !frameUrl || frameUrl === "about:blank") return null;
+      return doc;
+    } catch {
+      return null;
+    }
+  }
+
+  private apply(doc: Document, artifacts: EditorArtifacts): void {
+    this.context?.rollback();
+    this.context = createMutationApplicationContext();
+    doc.getElementById(DEVICE_STYLE_ID)?.remove();
+    if (artifacts.customCss.trim()) {
+      const style = doc.createElement("style");
+      style.id = DEVICE_STYLE_ID;
+      style.textContent = artifacts.customCss;
+      (doc.head || doc.documentElement).appendChild(style);
+    }
+    this.context.apply(artifacts.mutations, { root: doc });
+  }
+
+  private hideStorePage(): void {
+    const editorHost = document.getElementById("apex-editor-host");
+    this.hiddenChildren = Array.from(document.body?.children ?? [])
+      .filter((element): element is HTMLElement => element instanceof HTMLElement && element !== editorHost)
+      .map((element) => {
+        const visibility = element.style.visibility;
+        element.style.visibility = "hidden";
+        return { element, visibility };
+      });
+  }
+
+  private blocked(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.frame.onload = null;
+    this.frame.onerror = null;
+    this.frame.hidden = true;
+    this.frame.removeAttribute("src");
+    this.restoreStorePage();
+    this.onState("blocked");
+  }
+
+  private restoreStorePage(): void {
+    for (const item of this.hiddenChildren) {
+      item.element.style.visibility = item.visibility;
+    }
+    this.hiddenChildren = [];
+  }
+}

package/src/editor/index.test.ts

@@ -0,0 +1,161 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { __test, getActiveEditorSession, start } from "./index";
+
+const controllerMocks = vi.hoisted(() => ({
+  initialize: vi.fn(async () => undefined),
+  addCleanup: vi.fn(() => vi.fn()),
+  destroy: vi.fn(),
+}));
+
+vi.mock("./controller", () => ({
+  EditorController: class EditorController {
+    session = {
+      targetOrigin: "https://shop.example",
+    };
+    initialize = controllerMocks.initialize;
+    addCleanup = controllerMocks.addCleanup;
+    destroy = controllerMocks.destroy;
+  },
+}));
+vi.mock("./view", () => ({
+  mountEditorView: vi.fn(() => ({ destroy: vi.fn() })),
+}));
+
+function installDocumentStub() {
+  const elements = new Map<string, Record<string, unknown>>();
+  const appendChild = vi.fn((element: Record<string, unknown>) => {
+    if (typeof element.id === "string" && element.id) elements.set(element.id, element);
+    return element;
+  });
+  const documentStub = {
+    body: { appendChild },
+    documentElement: { appendChild },
+    getElementById: vi.fn((id: string) => elements.get(id) ?? null),
+    createElement: vi.fn((tag: string) => {
+      const element: Record<string, unknown> = {
+        id: "",
+        remove: vi.fn(() => {
+          if (typeof element.id === "string") elements.delete(element.id);
+        }),
+        setAttribute: vi.fn(),
+      };
+      if (tag === "div") {
+        element.attachShadow = vi.fn(() => ({ appendChild: vi.fn() }));
+      }
+      return element;
+    }),
+  };
+  vi.stubGlobal("document", documentStub);
+  vi.stubGlobal("location", { origin: "https://shop.example" });
+  const postMessage = vi.fn();
+  vi.stubGlobal("window", { opener: { postMessage } });
+  return { appendChild, documentStub, postMessage };
+}
+
+const launch = {
+  token: "payload.signature",
+  sid: "editor-session-1",
+  apiOrigin: "https://app.drip-apex.com",
+};
+
+beforeEach(() => {
+  controllerMocks.initialize.mockReset().mockResolvedValue(undefined);
+  controllerMocks.addCleanup.mockClear();
+  controllerMocks.destroy.mockClear();
+});
+
+afterEach(() => {
+  try {
+    __test.reset();
+  } catch {}
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("editor session exchange", () => {
+  it("mounts only after a successful scoped session exchange", async () => {
+    const { documentStub, postMessage } = installDocumentStub();
+    const expiresAt = new Date(Date.now() + 60_000).toISOString();
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        ok: true,
+        session: {
+          sid: launch.sid,
+          bearer: "editor-bearer",
+          expiresAt,
+          shopId: "shop-1",
+          experimentId: "experiment-1",
+          initialVariationId: "variation-1",
+          targetUrl: "https://shop.example/products/one",
+          targetOrigin: "https://shop.example",
+          variations: [{ id: "variation-1", name: "Treatment" }],
+        },
+      }),
+    }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(start(launch)).resolves.toBe(true);
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://app.drip-apex.com/api/editor-sessions/exchange?sid=editor-session-1",
+      expect.objectContaining({
+        method: "POST",
+        body: JSON.stringify({ token: launch.token }),
+        credentials: "omit",
+      }),
+    );
+    expect(documentStub.getElementById).toHaveBeenCalledWith("apex-editor-host");
+    expect(getActiveEditorSession()).toMatchObject({
+      sid: launch.sid,
+      bearer: "editor-bearer",
+      initialVariationId: "variation-1",
+    });
+    expect(postMessage).toHaveBeenCalledWith(
+      {
+        type: "apex:editor-connected",
+        sid: launch.sid,
+        experimentId: "experiment-1",
+        variationId: "variation-1",
+      },
+      "https://app.drip-apex.com",
+    );
+  });
+
+  it("does not mount when exchange is rejected", async () => {
+    const { appendChild } = installDocumentStub();
+    vi.stubGlobal("fetch", vi.fn(async () => ({ ok: false })));
+
+    await expect(start(launch)).resolves.toBe(false);
+    expect(appendChild).not.toHaveBeenCalled();
+    expect(getActiveEditorSession()).toBeNull();
+  });
+
+  it("cleans the host and scoped state when startup fails after mounting", async () => {
+    const { documentStub } = installDocumentStub();
+    const expiresAt = new Date(Date.now() + 60_000).toISOString();
+    vi.stubGlobal("fetch", vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        ok: true,
+        session: {
+          sid: launch.sid,
+          bearer: "editor-bearer",
+          expiresAt,
+          shopId: "shop-1",
+          experimentId: "experiment-1",
+          initialVariationId: "variation-1",
+          targetUrl: "https://shop.example/products/one",
+          targetOrigin: "https://shop.example",
+          variations: [{ id: "variation-1", name: "Treatment" }],
+        },
+      }),
+    })));
+    controllerMocks.initialize.mockRejectedValueOnce(new Error("load failed"));
+
+    await expect(start(launch)).resolves.toBe(false);
+
+    expect(getActiveEditorSession()).toBeNull();
+    expect(documentStub.getElementById("apex-editor-host")).toBeNull();
+    expect(controllerMocks.destroy).toHaveBeenCalledOnce();
+  });
+});

package/src/editor/index.ts

@@ -0,0 +1,169 @@
+import type { EditorLaunchHint } from "../editor-bootstrap";
+import type { ActiveEditorSession } from "./types";
+import { EditorApi } from "./api";
+import { EditorCommandExecutor, EditorCommandPoller } from "./command-runtime";
+import { EditorController } from "./controller";
+import { mountEditorView, type EditorView } from "./view";
+
+const EDITOR_HOST_ID = "apex-editor-host";
+const EXCHANGE_TIMEOUT_MS = 10_000;
+
+export type { ActiveEditorSession } from "./types";
+
+let activeSession: ActiveEditorSession | null = null;
+let activeController: EditorController | null = null;
+let activeView: EditorView | null = null;
+let activeCommandPoller: EditorCommandPoller | null = null;
+
+function cleanupActiveEditor(): void {
+  activeCommandPoller?.stop();
+  activeView?.destroy();
+  activeController?.destroy();
+  activeView = null;
+  activeCommandPoller = null;
+  activeController = null;
+  activeSession = null;
+  document.getElementById(EDITOR_HOST_ID)?.remove();
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function parseSession(value: unknown, sid: string): ActiveEditorSession | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  const parsed = {
+    sid: readString(record.sid),
+    bearer: readString(record.bearer),
+    expiresAt: readString(record.expiresAt),
+    shopId: readString(record.shopId),
+    experimentId: readString(record.experimentId),
+    initialVariationId: readString(record.initialVariationId),
+    targetUrl: readString(record.targetUrl),
+    targetOrigin: readString(record.targetOrigin),
+  };
+  if (
+    parsed.sid !== sid ||
+    !parsed.bearer ||
+    !parsed.expiresAt ||
+    !parsed.shopId ||
+    !parsed.experimentId ||
+    !parsed.initialVariationId ||
+    !parsed.targetUrl ||
+    !parsed.targetOrigin ||
+    !Number.isFinite(Date.parse(parsed.expiresAt)) ||
+    Date.parse(parsed.expiresAt) <= Date.now()
+  ) {
+    return null;
+  }
+  const variations: ActiveEditorSession["variations"] = [];
+  if (Array.isArray(record.variations)) {
+    for (const item of record.variations) {
+      if (!item || typeof item !== "object") continue;
+      const variation = item as Record<string, unknown>;
+      const id = readString(variation.id);
+      if (id) {
+        variations.push({
+          id,
+          name: readString(variation.name),
+          slug: readString(variation.slug),
+        });
+      }
+    }
+  }
+  return {
+    sid,
+    bearer: parsed.bearer,
+    expiresAt: parsed.expiresAt,
+    shopId: parsed.shopId,
+    experimentId: parsed.experimentId,
+    experimentName: readString(record.experimentName),
+    initialVariationId: parsed.initialVariationId,
+    targetUrl: parsed.targetUrl,
+    targetOrigin: parsed.targetOrigin,
+    variations,
+  };
+}
+
+function mountEditorHost(controller: EditorController): void {
+  document.getElementById(EDITOR_HOST_ID)?.remove();
+  const host = document.createElement("div");
+  host.id = EDITOR_HOST_ID;
+  host.setAttribute("data-apex-editor-state", "connected");
+  const shadow = host.attachShadow({ mode: "closed" });
+  (document.body || document.documentElement).appendChild(host);
+  activeView = mountEditorView(shadow, controller);
+}
+
+export async function start(launch: EditorLaunchHint): Promise<boolean> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), EXCHANGE_TIMEOUT_MS);
+  let ownsActiveEditor = false;
+  try {
+    const exchangeUrl = new URL("/api/editor-sessions/exchange", launch.apiOrigin);
+    exchangeUrl.searchParams.set("sid", launch.sid);
+    const response = await fetch(exchangeUrl.toString(), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ token: launch.token }),
+      cache: "no-store",
+      credentials: "omit",
+      referrerPolicy: "no-referrer",
+      signal: controller.signal,
+    });
+    if (!response.ok) return false;
+    const payload = (await response.json().catch(() => null)) as
+      | { ok?: unknown; session?: unknown }
+      | null;
+    if (payload?.ok !== true) return false;
+    const session = parseSession(payload.session, launch.sid);
+    if (!session) return false;
+    if (
+      typeof location !== "undefined" &&
+      session.targetOrigin !== location.origin
+    ) {
+      return false;
+    }
+    activeSession = session;
+    ownsActiveEditor = true;
+    const api = new EditorApi(launch.apiOrigin, session);
+    activeController = new EditorController(session, launch.apiOrigin, api);
+    mountEditorHost(activeController);
+    await activeController.initialize();
+    activeCommandPoller = new EditorCommandPoller(
+      api,
+      new EditorCommandExecutor(activeController),
+    );
+    activeController.addCleanup(() => {
+      activeCommandPoller?.stop();
+      activeCommandPoller = null;
+    });
+    activeCommandPoller.start();
+    try {
+      window.opener?.postMessage(
+        {
+          type: "apex:editor-connected",
+          sid: session.sid,
+          experimentId: session.experimentId,
+          variationId: session.initialVariationId,
+        },
+        launch.apiOrigin,
+      );
+    } catch {}
+    return true;
+  } catch {
+    if (ownsActiveEditor) cleanupActiveEditor();
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function getActiveEditorSession(): ActiveEditorSession | null {
+  return activeSession;
+}
+
+export const __test = {
+  reset: cleanupActiveEditor,
+};

package/src/editor/operator.test.ts

@@ -0,0 +1,148 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  collectEditorDomContext,
+  mergeEditorOperatorArtifacts,
+  runEditorOperatorTurn,
+} from "./operator";
+import type { ActiveEditorSession } from "./types";
+
+const session: ActiveEditorSession = {
+  sid: "session_1",
+  bearer: "secret_bearer",
+  expiresAt: "2099-01-01T00:00:00.000Z",
+  shopId: "shop_1",
+  experimentId: "experiment_1",
+  initialVariationId: "variation_1",
+  targetUrl: "https://shop.test/products/one?preview_token=secret#private",
+  targetOrigin: "https://shop.test",
+  variations: [{ id: "variation_1", name: "Treatment" }],
+};
+
+describe("editor operator client", () => {
+  beforeEach(() => {
+    document.title = "Product one";
+    document.body.innerHTML = `
+      <main id="product"><h1>Original title</h1>
+      <input name="email" value="customer@example.com">
+      <a href="/account?token=secret-link#private">Account</a>
+      <img src="https://cdn.test/product.jpg?signature=secret-image" alt="Product">
+      <button data-testid="buy">Add to cart</button></main>`;
+  });
+
+  it("collects structural page context without form values", () => {
+    const context = collectEditorDomContext();
+    expect(context).toContain("Original title");
+    expect(context).toContain('data-testid="buy"');
+    expect(context).not.toContain("customer@example.com");
+    expect(context).not.toContain("secret-link");
+    expect(context).not.toContain("secret-image");
+    expect(context).toContain('href="http://localhost:3000/account"');
+    expect(context).toContain('src="https://cdn.test/product.jpg"');
+  });
+
+  it("upserts append results and replaces complete artifact sets", () => {
+    const current = {
+      mutations: [
+        { selector: "h1", action: "setText" as const, text: "First" },
+      ],
+      customCss: "h1 { color: red; }",
+      customJs: "",
+    };
+    const appended = mergeEditorOperatorArtifacts({
+      current,
+      generatedMutations: [
+        { selector: "h1", action: "setText", text: "Second" },
+      ],
+      generatedCss: ".new { display: block; }",
+      generatedJs: "",
+      mergeStrategy: "append",
+    });
+    expect(appended.mutations).toEqual([
+      { selector: "h1", action: "setText", text: "Second" },
+    ]);
+    expect(appended.customCss).toContain("h1 { color: red; }");
+    expect(appended.customCss).toContain(".new { display: block; }");
+
+    expect(
+      mergeEditorOperatorArtifacts({
+        current,
+        generatedMutations: [
+          { selector: "button", action: "setText", text: "Buy now" },
+        ],
+        generatedCss: "",
+        generatedJs: "",
+        mergeStrategy: "replace",
+      }).mutations,
+    ).toEqual([{ selector: "button", action: "setText", text: "Buy now" }]);
+  });
+
+  it("sends the scoped bearer and returns merged artifacts", async () => {
+    const fetchImpl = vi.fn(async (_url: URL, init?: RequestInit) =>
+      Response.json({
+        mutations: [
+          { selector: "h1", action: "setText", text: "Generated title" },
+        ],
+        customCss: "h1 { color: blue; }",
+        customJs: "",
+        mergeStrategy: "append",
+        explanation: "Updated the heading.",
+      }),
+    ) as unknown as typeof fetch;
+    const result = await runEditorOperatorTurn({
+      apiOrigin: "https://app.test",
+      session,
+      variationId: "variation_1",
+      prompt: "Make the title clearer",
+      artifacts: { mutations: [], customCss: "", customJs: "" },
+      conversation: [],
+      selectedElement: {
+        selector: "button[data-testid=buy]",
+        tag: "button",
+        textPreview: "Add to cart",
+        alternatives: ["#product button"],
+      },
+      fetchImpl,
+    });
+    expect(result.artifactCount).toBe(2);
+    expect(result.explanation).toBe("Updated the heading.");
+    const [url, init] = fetchImpl.mock.calls[0];
+    expect(String(url)).toBe(
+      "https://app.test/api/editor-sessions/session_1/operator",
+    );
+    expect(new Headers(init?.headers).get("Authorization")).toBe(
+      "Bearer secret_bearer",
+    );
+    const requestBody = JSON.parse(String(init?.body));
+    expect(requestBody).toMatchObject({
+      prompt: "Make the title clearer",
+      variationId: "variation_1",
+      existingMutations: [],
+      pageContext: "Live merchant page: https://shop.test/products/one",
+      selectedElement: {
+        selector: "button[data-testid=buy]",
+        tag: "button",
+        textPreview: "Add to cart",
+        alternatives: ["#product button"],
+      },
+    });
+    expect(String(init?.body)).not.toContain("preview_token");
+    expect(String(init?.body)).not.toContain("secret");
+  });
+
+  it("surfaces API failures", async () => {
+    await expect(
+      runEditorOperatorTurn({
+        apiOrigin: "https://app.test",
+        session,
+        variationId: "variation_1",
+        prompt: "Change it",
+        artifacts: { mutations: [], customCss: "", customJs: "" },
+        conversation: [],
+        fetchImpl: vi.fn(async () =>
+          Response.json({ error: "Operator is disabled" }, { status: 403 }),
+        ) as unknown as typeof fetch,
+      }),
+    ).rejects.toThrow("Operator is disabled");
+  });
+});