@drip-apex/sdk 0.1.0

package/src/editor/api.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it, vi } from "vitest";
+import { EditorApi, EditorApiError } from "./api";
+import type { ActiveEditorSession } from "./types";
+
+const session: ActiveEditorSession = {
+  sid: "session/a",
+  bearer: "secret-bearer",
+  expiresAt: new Date(Date.now() + 60_000).toISOString(),
+  shopId: "shop-1",
+  experimentId: "experiment-1",
+  initialVariationId: "variation 1",
+  targetUrl: "https://shop.example/products/one",
+  targetOrigin: "https://shop.example",
+  variations: [],
+};
+
+describe("EditorApi", () => {
+  it("uses the browser fetch receiver safely when no implementation is injected", async () => {
+    const originalFetch = globalThis.fetch;
+    const fetchMock = vi.fn(async () =>
+      Response.json({
+        ok: true,
+        variation: {
+          id: "variation-1",
+          name: "Treatment",
+          artifactHash: "hash-1",
+          reviewStatus: null,
+        },
+        artifacts: { mutations: [], customCss: "", customJs: "" },
+      }),
+    );
+    globalThis.fetch = fetchMock as typeof fetch;
+    try {
+      const api = new EditorApi("https://app.test", session);
+      await api.loadArtifacts("variation-1");
+      expect(fetchMock).toHaveBeenCalledOnce();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+  it("loads artifacts with bearer auth and encoded scope", async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        ok: true,
+        variation: { id: "variation 1", name: "Treatment", artifactHash: "hash-1", reviewStatus: "approved" },
+        artifacts: { mutations: [], customCss: "", customJs: "" },
+      }),
+    })) as unknown as typeof fetch;
+    const api = new EditorApi("https://app.example", session, fetchMock);
+    await api.loadArtifacts("variation 1");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://app.example/api/editor-sessions/session%2Fa/artifacts?variationId=variation+1",
+      expect.objectContaining({
+        method: "GET",
+        credentials: "omit",
+        headers: expect.objectContaining({ Authorization: "Bearer secret-bearer" }),
+      }),
+    );
+  });
+
+  it("extends the session and returns the new expiry", async () => {
+    const later = new Date(Date.now() + 3_600_000).toISOString();
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ ok: true, session: { sid: "session/a", expiresAt: later } }),
+    })) as unknown as typeof fetch;
+    const api = new EditorApi("https://app.example", session, fetchMock);
+    await expect(api.extendSession()).resolves.toBe(later);
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://app.example/api/editor-sessions/session%2Fa/extend",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({ Authorization: "Bearer secret-bearer" }),
+      }),
+    );
+  });
+
+  it("sends a full optimistic snapshot and surfaces conflicts", async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: false,
+      status: 409,
+      json: async () => ({ ok: false, error: "Artifact hash conflict", artifactHash: "new-hash" }),
+    })) as unknown as typeof fetch;
+    const api = new EditorApi("https://app.example", session, fetchMock);
+    await expect(api.saveArtifacts("variation-1", {
+      mutations: [], customCss: "h1{color:red}", customJs: "",
+    }, "old-hash")).rejects.toMatchObject<Partial<EditorApiError>>({ status: 409 });
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.stringContaining("variationId=variation-1"),
+      expect.objectContaining({
+        method: "PATCH",
+        body: JSON.stringify({ mutations: [], customCss: "h1{color:red}", customJs: "", expectedPriorHash: "old-hash" }),
+      }),
+    );
+  });
+
+  it("rejects load responses without the required optimistic artifact hash", async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        ok: true,
+        variation: { id: "variation 1", name: "Treatment" },
+        artifacts: { mutations: [], customCss: "", customJs: "" },
+      }),
+    })) as unknown as typeof fetch;
+    const api = new EditorApi("https://app.example", session, fetchMock);
+    await expect(api.loadArtifacts("variation 1")).rejects.toThrow(
+      "Editor load response did not include an artifact hash",
+    );
+  });
+
+  it("claims and completes durable browser commands with bearer auth", async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          ok: true,
+          commands: [{
+            commandId: "command-1",
+            command: "snapshot",
+            args: {},
+            expiresAt: new Date(Date.now() + 10_000).toISOString(),
+          }],
+        }),
+      })
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({ ok: true }) }) as typeof fetch;
+    const api = new EditorApi("https://app.example", session, fetchMock);
+
+    await expect(api.claimCommands()).resolves.toEqual([
+      expect.objectContaining({ commandId: "command-1", command: "snapshot" }),
+    ]);
+    await api.completeCommand("command-1", { result: { ok: true } });
+
+    expect(fetchMock).toHaveBeenNthCalledWith(1,
+      "https://app.example/api/editor-sessions/session%2Fa/commands?limit=10",
+      expect.objectContaining({
+        method: "GET",
+        headers: expect.objectContaining({ Authorization: "Bearer secret-bearer" }),
+      }),
+    );
+    expect(fetchMock).toHaveBeenNthCalledWith(2,
+      "https://app.example/api/editor-sessions/session%2Fa/commands",
+      expect.objectContaining({
+        method: "PATCH",
+        body: JSON.stringify({ commandId: "command-1", result: { ok: true } }),
+      }),
+    );
+  });
+});

package/src/editor/api.ts

@@ -0,0 +1,185 @@
+import type {
+  ActiveEditorSession,
+  ClaimedEditorCommand,
+  EditorArtifacts,
+  EditorBrowserCommand,
+  EditorVariation,
+} from "./types";
+
+export class EditorApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly payload?: Record<string, unknown> | null,
+  ) {
+    super(message);
+  }
+}
+
+type FetchLike = typeof fetch;
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function parseArtifacts(value: unknown): EditorArtifacts {
+  const input = record(value) ?? {};
+  return {
+    mutations: Array.isArray(input.mutations) ? input.mutations as EditorArtifacts["mutations"] : [],
+    customCss: typeof input.customCss === "string" ? input.customCss : "",
+    customJs: typeof input.customJs === "string" ? input.customJs : "",
+  };
+}
+
+const EDITOR_COMMANDS = new Set<EditorBrowserCommand>([
+  "navigate", "reload", "back", "forward", "click", "type", "wait_for",
+  "snapshot", "screenshot", "eval_readonly", "console_logs", "network_logs",
+  "network_probe", "current_url", "select_element", "apply_artifacts",
+]);
+
+export class EditorApi {
+  constructor(
+    private readonly apiOrigin: string,
+    private readonly session: ActiveEditorSession,
+    private readonly fetchImpl: FetchLike = (...args) => fetch(...args),
+  ) {}
+
+  private url(path: string, variationId?: string): string {
+    const url = new URL(path, this.apiOrigin);
+    if (variationId) url.searchParams.set("variationId", variationId);
+    return url.toString();
+  }
+
+  private async request(
+    url: string,
+    init: RequestInit,
+  ): Promise<Record<string, unknown>> {
+    const response = await this.fetchImpl(url, {
+      ...init,
+      credentials: "omit",
+      cache: "no-store",
+      referrerPolicy: "no-referrer",
+      headers: {
+        Authorization: `Bearer ${this.session.bearer}`,
+        ...(init.body ? { "Content-Type": "application/json" } : {}),
+        ...(init.headers ?? {}),
+      },
+    });
+    const payload = record(await response.json().catch(() => null));
+    if (!response.ok || payload?.ok === false) {
+      throw new EditorApiError(
+        typeof payload?.error === "string" ? payload.error : `Editor API failed (${response.status})`,
+        response.status,
+        payload,
+      );
+    }
+    return payload ?? {};
+  }
+
+  async loadArtifacts(variationId: string): Promise<{
+    variation: EditorVariation;
+    artifacts: EditorArtifacts;
+  }> {
+    const payload = await this.request(
+      this.url(`/api/editor-sessions/${encodeURIComponent(this.session.sid)}/artifacts`, variationId),
+      { method: "GET" },
+    );
+    const variation = record(payload.variation) ?? {};
+    if (typeof variation.artifactHash !== "string" || !variation.artifactHash) {
+      throw new EditorApiError("Editor load response did not include an artifact hash", 500, payload);
+    }
+    return {
+      variation: {
+        id: typeof variation.id === "string" ? variation.id : variationId,
+        name: typeof variation.name === "string" ? variation.name : "Variation",
+        artifactHash: variation.artifactHash,
+        reviewStatus: typeof variation.reviewStatus === "string" ? variation.reviewStatus : null,
+      },
+      artifacts: parseArtifacts(payload.artifacts),
+    };
+  }
+
+  async saveArtifacts(
+    variationId: string,
+    artifacts: EditorArtifacts,
+    expectedPriorHash: string,
+  ): Promise<{
+    artifactHash: string;
+    reviewStatus: string | null;
+    warningIssues: Array<{ code?: string; message?: string }>;
+    artifacts: EditorArtifacts;
+  }> {
+    const payload = await this.request(
+      this.url(`/api/editor-sessions/${encodeURIComponent(this.session.sid)}/artifacts`, variationId),
+      {
+        method: "PATCH",
+        body: JSON.stringify({ ...artifacts, expectedPriorHash }),
+      },
+    );
+    if (typeof payload.artifactHash !== "string") {
+      throw new EditorApiError("Editor save response did not include an artifact hash", 500, payload);
+    }
+    return {
+      artifactHash: payload.artifactHash,
+      reviewStatus: typeof payload.reviewStatus === "string" ? payload.reviewStatus : null,
+      warningIssues: Array.isArray(payload.warningIssues)
+        ? payload.warningIssues as Array<{ code?: string; message?: string }>
+        : [],
+      artifacts: parseArtifacts(payload.artifacts),
+    };
+  }
+
+  async extendSession(): Promise<string | null> {
+    const payload = await this.request(
+      this.url(`/api/editor-sessions/${encodeURIComponent(this.session.sid)}/extend`),
+      { method: "POST" },
+    );
+    const session = record(payload.session);
+    return typeof session?.expiresAt === "string" ? session.expiresAt : null;
+  }
+
+  async revoke(): Promise<void> {
+    await this.request(
+      this.url(`/api/editor-sessions/${encodeURIComponent(this.session.sid)}`),
+      { method: "DELETE" },
+    );
+  }
+
+
+  async claimCommands(limit = 10): Promise<ClaimedEditorCommand[]> {
+    const url = this.url(`/api/editor-sessions/${encodeURIComponent(this.session.sid)}/commands`);
+    const commandUrl = new URL(url);
+    commandUrl.searchParams.set("limit", String(Math.max(1, Math.min(limit, 20))));
+    const payload = await this.request(commandUrl.toString(), { method: "GET" });
+    if (!Array.isArray(payload.commands)) return [];
+    const commands: ClaimedEditorCommand[] = [];
+    for (const value of payload.commands) {
+      const command = record(value);
+      const commandId = typeof command?.commandId === "string" ? command.commandId : "";
+      const commandName = typeof command?.command === "string" ? command.command : "";
+      if (!commandId || !EDITOR_COMMANDS.has(commandName as EditorBrowserCommand)) continue;
+      commands.push({
+        commandId,
+        command: commandName as EditorBrowserCommand,
+        args: record(command?.args) ?? {},
+        expiresAt: typeof command?.expiresAt === "string" ? command.expiresAt : null,
+      });
+    }
+    return commands;
+  }
+
+  async completeCommand(
+    commandId: string,
+    completion: { result: Record<string, unknown> } | { error: string },
+  ): Promise<void> {
+    await this.request(
+      this.url(`/api/editor-sessions/${encodeURIComponent(this.session.sid)}/commands`),
+      {
+        method: "PATCH",
+        body: JSON.stringify({ commandId, ...completion }),
+      },
+    );
+  }
+}

package/src/editor/artifacts.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { ArtifactHistory, upsertMutation } from "./artifacts";
+import type { EditorArtifacts } from "./types";
+
+const empty = (): EditorArtifacts => ({ mutations: [], customCss: "", customJs: "" });
+
+describe("artifact mutation upsert", () => {
+  it("replaces the content slot and merges style properties", () => {
+    let artifacts = upsertMutation(empty(), { selector: "h1", action: "text", text: "First" });
+    artifacts = upsertMutation(artifacts, { selector: "h1", action: "setText", text: "Second" });
+    artifacts = upsertMutation(artifacts, { selector: "h1", action: "style", styles: { color: "red" } });
+    artifacts = upsertMutation(artifacts, { selector: "h1", action: "setStyle", styles: { margin: "8px" } });
+
+    expect(artifacts.mutations).toEqual([
+      { selector: "h1", action: "setText", text: "Second" },
+      { selector: "h1", action: "setStyle", styles: { color: "red", margin: "8px" } },
+    ]);
+  });
+
+  it("normalizes and merges attribute forms", () => {
+    let artifacts = upsertMutation(empty(), {
+      selector: "img",
+      action: "attribute",
+      attribute: { name: "src", value: "/one.jpg" },
+    });
+    artifacts = upsertMutation(artifacts, {
+      selector: "img",
+      action: "attribute",
+      attributes: { alt: "Treatment" },
+    });
+    expect(artifacts.mutations[0]).toMatchObject({
+      selector: "img",
+      action: "attribute",
+      attributes: { src: "/one.jpg", alt: "Treatment" },
+    });
+  });
+
+  it("makes remove terminal for the selector", () => {
+    let artifacts = upsertMutation(empty(), { selector: ".promo", action: "setText", text: "Offer" });
+    artifacts = upsertMutation(artifacts, { selector: ".promo", action: "setStyle", styles: { color: "red" } });
+    artifacts = upsertMutation(artifacts, { selector: ".promo", action: "remove" });
+    expect(artifacts.mutations).toEqual([{ selector: ".promo", action: "remove" }]);
+  });
+});
+
+describe("ArtifactHistory", () => {
+  it("supports immutable undo, redo, and redo invalidation", () => {
+    const history = new ArtifactHistory();
+    const initial = empty();
+    const changed = { ...empty(), customCss: "h1{color:red}" };
+    history.push(initial);
+    expect(history.undo(changed)).toEqual(initial);
+    expect(history.redo(initial)).toEqual(changed);
+    history.push(changed);
+    expect(history.canRedo).toBe(false);
+  });
+});

package/src/editor/artifacts.ts

@@ -0,0 +1,115 @@
+import type { Mutation } from "../types";
+import { cloneArtifacts, type EditorArtifacts } from "./types";
+
+function sameMutationSlot(left: Mutation, right: Mutation): boolean {
+  if (left.selector !== right.selector) return false;
+  const textActions = new Set(["text", "setText", "html"]);
+  const styleActions = new Set(["style", "setStyle"]);
+  if (textActions.has(left.action) && textActions.has(right.action)) return true;
+  if (styleActions.has(left.action) && styleActions.has(right.action)) return true;
+  return left.action === right.action;
+}
+
+export function upsertMutation(
+  artifacts: EditorArtifacts,
+  mutation: Mutation,
+): EditorArtifacts {
+  if (mutation.action === "remove") {
+    return {
+      ...artifacts,
+      mutations: [
+        ...artifacts.mutations.filter((item) => item.selector !== mutation.selector),
+        mutation,
+      ],
+    };
+  }
+  const mutations = artifacts.mutations
+    .filter((item) => !(item.selector === mutation.selector && item.action === "remove"))
+    .map((item) => ({ ...item }));
+  const index = mutations.findIndex((item) => sameMutationSlot(item, mutation));
+  if (index < 0) mutations.push(mutation);
+  else if ((mutation.action === "style" || mutation.action === "setStyle") && mutations[index].styles) {
+    mutations[index] = {
+      ...mutations[index],
+      ...mutation,
+      styles: { ...mutations[index].styles, ...mutation.styles },
+    };
+  } else if (mutation.action === "attribute") {
+    const previous = mutations[index];
+    const previousAttributes = {
+      ...(previous.attribute ? { [previous.attribute.name]: previous.attribute.value } : {}),
+      ...(previous.attributes ?? {}),
+    };
+    const nextAttributes = {
+      ...(mutation.attribute ? { [mutation.attribute.name]: mutation.attribute.value } : {}),
+      ...(mutation.attributes ?? {}),
+    };
+    mutations[index] = {
+      ...previous,
+      ...mutation,
+      attribute: undefined,
+      attributes: { ...previousAttributes, ...nextAttributes },
+    };
+  } else {
+    mutations[index] = mutation;
+  }
+  return { ...artifacts, mutations };
+}
+
+export function removeSelectorMutations(
+  artifacts: EditorArtifacts,
+  selector: string,
+): EditorArtifacts {
+  return {
+    ...artifacts,
+    mutations: artifacts.mutations.filter((mutation) => mutation.selector !== selector),
+  };
+}
+
+export function removeMutationAt(
+  artifacts: EditorArtifacts,
+  index: number,
+): EditorArtifacts {
+  return {
+    ...artifacts,
+    mutations: artifacts.mutations.filter((_, mutationIndex) => mutationIndex !== index),
+  };
+}
+
+export class ArtifactHistory {
+  private undoStack: EditorArtifacts[] = [];
+  private redoStack: EditorArtifacts[] = [];
+
+  push(current: EditorArtifacts): void {
+    this.undoStack.push(cloneArtifacts(current));
+    this.undoStack = this.undoStack.slice(-50);
+    this.redoStack = [];
+  }
+
+  undo(current: EditorArtifacts): EditorArtifacts | null {
+    const previous = this.undoStack.pop();
+    if (!previous) return null;
+    this.redoStack.push(cloneArtifacts(current));
+    return cloneArtifacts(previous);
+  }
+
+  redo(current: EditorArtifacts): EditorArtifacts | null {
+    const next = this.redoStack.pop();
+    if (!next) return null;
+    this.undoStack.push(cloneArtifacts(current));
+    return cloneArtifacts(next);
+  }
+
+  reset(): void {
+    this.undoStack = [];
+    this.redoStack = [];
+  }
+
+  get canUndo(): boolean {
+    return this.undoStack.length > 0;
+  }
+
+  get canRedo(): boolean {
+    return this.redoStack.length > 0;
+  }
+}