@drip-apex/sdk 0.1.0

package/src/editor-bootstrap.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  __test,
+  consumeEditorLaunchFragment,
+  interceptEditorLaunch,
+  isEditorDevicePreview,
+  resolveEditorBundleUrl,
+} from "./editor-bootstrap";
+
+function launchToken(overrides: Record<string, unknown> = {}): string {
+  const payload = {
+    aud: "apex-editor-exchange",
+    sid: "editor-session-1",
+    apiOrigin: "https://app.drip-apex.com",
+    ...overrides,
+  };
+  return `${btoa(JSON.stringify(payload)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")}.signature`;
+}
+
+function launchLocation(token: string) {
+  return {
+    hash: `#section=details&apex-editor=${encodeURIComponent(token)}`,
+    href: `https://shop.example/products/one#section=details&apex-editor=${encodeURIComponent(token)}`,
+  };
+}
+
+afterEach(() => {
+  __test.resetState();
+  vi.restoreAllMocks();
+});
+
+describe("editor launch bootstrap", () => {
+  it("does no work when the editor fragment is absent", () => {
+    const replaceState = vi.fn();
+    const loadBundle = vi.fn();
+    const intercepted = interceptEditorLaunch({
+      locationLike: { hash: "#details", href: "https://shop.example/#details" },
+      historyLike: { state: null, replaceState },
+      scriptSrc: "https://events.drip-apex.com/s/shop.js",
+      loadBundle,
+      onFailure: vi.fn(),
+    });
+
+    expect(intercepted).toBe(false);
+    expect(replaceState).not.toHaveBeenCalled();
+    expect(loadBundle).not.toHaveBeenCalled();
+  });
+
+  it("strips the token immediately and preserves unrelated fragment state", () => {
+    const token = launchToken();
+    const replaceState = vi.fn();
+    const launch = consumeEditorLaunchFragment(
+      launchLocation(token),
+      { state: { page: 1 }, replaceState },
+    );
+
+    expect(launch).toEqual({
+      token,
+      sid: "editor-session-1",
+      apiOrigin: "https://app.drip-apex.com",
+    });
+    expect(replaceState).toHaveBeenCalledWith(
+      { page: 1 },
+      "",
+      "https://shop.example/products/one#section=details",
+    );
+  });
+
+  it("suppresses repeated initialization while exchange is pending and restores after failure", async () => {
+    const token = launchToken();
+    let rejectLoad!: (error: Error) => void;
+    const loadBundle = vi.fn(() => new Promise<never>((_resolve, reject) => {
+      rejectLoad = reject;
+    }));
+    const onFailure = vi.fn();
+    const common = {
+      scriptSrc: "https://events.drip-apex.com/s/shop.js",
+      pageUrl: "https://shop.example/products/one",
+      loadBundle,
+      onFailure,
+    };
+
+    expect(interceptEditorLaunch({
+      ...common,
+      locationLike: launchLocation(token),
+      historyLike: { state: null, replaceState: vi.fn() },
+    })).toBe(true);
+    expect(__test.getState()).toBe("starting");
+    expect(interceptEditorLaunch({
+      ...common,
+      locationLike: { hash: "", href: "https://shop.example/products/one" },
+      historyLike: { state: null, replaceState: vi.fn() },
+    })).toBe(true);
+
+    rejectLoad(new Error("blocked by CSP"));
+    await vi.waitFor(() => expect(onFailure).toHaveBeenCalledOnce());
+    expect(__test.getState()).toBe("idle");
+    expect(interceptEditorLaunch({
+      ...common,
+      locationLike: { hash: "", href: "https://shop.example/products/one" },
+      historyLike: { state: null, replaceState: vi.fn() },
+    })).toBe(false);
+  });
+
+  it("uses the versioned sibling editor asset for versioned SDK scripts", () => {
+    expect(resolveEditorBundleUrl({
+      scriptSrc: "https://events.drip-apex.com/sdk/0.1.0%2Babc/drip.live.js",
+      pageUrl: "https://shop.example/",
+    })).toBe("https://events.drip-apex.com/sdk/0.1.0%2Babc/editor.js");
+  });
+
+  it("identifies isolated device-preview frames", () => {
+    expect(isEditorDevicePreview({ name: "apex-editor-device-preview" } as Window)).toBe(true);
+    expect(isEditorDevicePreview({ name: "storefront" } as Window)).toBe(false);
+  });
+});

package/src/editor-bootstrap.ts

@@ -0,0 +1,213 @@
+export const EDITOR_FRAGMENT_KEY = "apex-editor";
+export const EDITOR_BUNDLE_FILENAME = "editor.js";
+export const EDITOR_DEVICE_FRAME_NAME = "apex-editor-device-preview";
+const EDITOR_SCRIPT_ID = "drip-editor-bundle";
+const EDITOR_LOAD_TIMEOUT_MS = 10_000;
+
+export type EditorLaunchHint = {
+  token: string;
+  sid: string;
+  apiOrigin: string;
+};
+
+type LocationLike = Pick<Location, "hash" | "href">;
+type HistoryLike = Pick<History, "replaceState" | "state">;
+
+export type EditorBundleApi = {
+  start: (launch: EditorLaunchHint) => boolean | Promise<boolean>;
+};
+
+type EditorGlobal = typeof globalThis & {
+  ApexEditor?: EditorBundleApi;
+};
+
+let editorState: "idle" | "starting" | "active" = "idle";
+
+export function isEditorDevicePreview(windowLike: Pick<Window, "name"> = window): boolean {
+  return windowLike.name === EDITOR_DEVICE_FRAME_NAME;
+}
+
+function decodeBase64Url(value: string): string | null {
+  try {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+    return atob(padded);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeApiOrigin(value: unknown): string | null {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+
+export function decodeEditorLaunchToken(token: string): Omit<EditorLaunchHint, "token"> | null {
+  const encodedPayload = token.split(".", 1)[0];
+  if (!encodedPayload) return null;
+  const decoded = decodeBase64Url(encodedPayload);
+  if (!decoded) return null;
+  try {
+    const payload = JSON.parse(decoded) as Record<string, unknown>;
+    const sid = typeof payload.sid === "string" ? payload.sid.trim() : "";
+    const apiOrigin = normalizeApiOrigin(payload.apiOrigin ?? payload.api_origin);
+    if (payload.aud !== "apex-editor-exchange" || !sid || !apiOrigin) return null;
+    return { sid, apiOrigin };
+  } catch {
+    return null;
+  }
+}
+
+export function consumeEditorLaunchFragment(
+  locationLike: LocationLike = location,
+  historyLike: HistoryLike = history,
+): EditorLaunchHint | null {
+  if (!locationLike.hash || locationLike.hash.length < 2) return null;
+  const params = new URLSearchParams(locationLike.hash.slice(1));
+  const encodedToken = params.get(EDITOR_FRAGMENT_KEY);
+  if (!encodedToken) return null;
+
+  const token = encodedToken.trim();
+  const hint = decodeEditorLaunchToken(token);
+  params.delete(EDITOR_FRAGMENT_KEY);
+
+  try {
+    const cleanUrl = new URL(locationLike.href);
+    const remainingHash = params.toString();
+    cleanUrl.hash = remainingHash ? `#${remainingHash}` : "";
+    historyLike.replaceState(historyLike.state ?? null, "", cleanUrl.toString());
+  } catch {
+    return null;
+  }
+
+  return hint ? { token, ...hint } : null;
+}
+
+export function resolveEditorBundleUrl(input: {
+  configuredUrl?: string;
+  scriptSrc?: string;
+  pageUrl?: string;
+}): string | null {
+  const baseUrl = input.scriptSrc || input.pageUrl;
+  if (input.configuredUrl) {
+    try {
+      const url = new URL(input.configuredUrl, baseUrl);
+      return url.protocol === "https:" || url.protocol === "http:" ? url.toString() : null;
+    } catch {
+      return null;
+    }
+  }
+  if (!input.scriptSrc) return null;
+  try {
+    const scriptUrl = new URL(input.scriptSrc, input.pageUrl);
+    if (/^\/sdk\/[^/]+\/[^/]+\.js$/.test(scriptUrl.pathname)) {
+      scriptUrl.pathname = scriptUrl.pathname.replace(/[^/]+\.js$/, EDITOR_BUNDLE_FILENAME);
+    } else if (/\/drip(?:\.live|\.heatmap|\.debug)?\.js$/.test(scriptUrl.pathname)) {
+      scriptUrl.pathname = scriptUrl.pathname.replace(/[^/]+\.js$/, EDITOR_BUNDLE_FILENAME);
+    } else {
+      scriptUrl.pathname = `/${EDITOR_BUNDLE_FILENAME}`;
+    }
+    scriptUrl.search = "";
+    scriptUrl.hash = "";
+    return scriptUrl.toString();
+  } catch {
+    return null;
+  }
+}
+
+export function loadEditorBundle(
+  bundleUrl: string,
+  documentLike: Document = document,
+  timeoutMs = EDITOR_LOAD_TIMEOUT_MS,
+): Promise<EditorBundleApi> {
+  return new Promise((resolve, reject) => {
+    const existing = documentLike.getElementById(EDITOR_SCRIPT_ID);
+    existing?.remove();
+
+    const script = documentLike.createElement("script");
+    script.id = EDITOR_SCRIPT_ID;
+    script.src = bundleUrl;
+    script.async = true;
+    script.crossOrigin = "anonymous";
+
+    const timeout = setTimeout(() => {
+      script.remove();
+      reject(new Error("Editor bundle load timed out"));
+    }, timeoutMs);
+    const finish = (error?: Error) => {
+      clearTimeout(timeout);
+      if (error) {
+        script.remove();
+        reject(error);
+        return;
+      }
+      const editorGlobal = globalThis as EditorGlobal;
+      const api = editorGlobal.ApexEditor;
+      try {
+        editorGlobal.ApexEditor = undefined;
+      } catch {}
+      if (!api || typeof api.start !== "function") {
+        reject(new Error("Editor bundle did not expose a start function"));
+        return;
+      }
+      resolve(api);
+    };
+    script.onload = () => finish();
+    script.onerror = () => finish(new Error("Editor bundle failed to load"));
+    (documentLike.head || documentLike.documentElement).appendChild(script);
+  });
+}
+
+export function interceptEditorLaunch(input: {
+  configuredBundleUrl?: string;
+  scriptSrc?: string;
+  pageUrl?: string;
+  onBeforeLoad?: () => void;
+  onFailure: () => void;
+  loadBundle?: (url: string) => Promise<EditorBundleApi>;
+  locationLike?: LocationLike;
+  historyLike?: HistoryLike;
+}): boolean {
+  if (editorState !== "idle") return true;
+  const launch = consumeEditorLaunchFragment(input.locationLike, input.historyLike);
+  if (!launch) return false;
+
+  editorState = "starting";
+  input.onBeforeLoad?.();
+  const bundleUrl = resolveEditorBundleUrl({
+    configuredUrl: input.configuredBundleUrl,
+    scriptSrc: input.scriptSrc,
+    pageUrl: input.pageUrl,
+  });
+  const fail = () => {
+    editorState = "idle";
+    input.onFailure();
+  };
+  if (!bundleUrl) {
+    Promise.resolve().then(fail);
+    return true;
+  }
+
+  const loader = input.loadBundle ?? ((url: string) => loadEditorBundle(url));
+  loader(bundleUrl)
+    .then((api) => api.start(launch))
+    .then((active) => {
+      if (active) editorState = "active";
+      else fail();
+    })
+    .catch(fail);
+  return true;
+}
+
+export const __test = {
+  getState: () => editorState,
+  resetState: () => {
+    editorState = "idle";
+  },
+};

package/src/event-schema-contract.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import {
+  incomingEventSchema,
+  type IncomingEvent,
+} from "@drip/event-schema";
+import type { TrackEvent } from "./types";
+
+describe("event schema contract", () => {
+  it("keeps SDK TrackEvent assignable to the shared incoming event contract", () => {
+    expectTypeOf<TrackEvent>().toMatchTypeOf<IncomingEvent>();
+  });
+
+  it("parses a fully populated TrackEvent literal as a shared incoming event", () => {
+    const event: TrackEvent = {
+      type: "drip:goal.click-1",
+      data: {
+        revenue: 19.99,
+        goalId: "goal_123",
+        utmSource: "newsletter",
+      },
+      experimentId: "exp_123",
+      variationId: "var_123",
+      shopId: "shop_123",
+      visitorId: "visitor_123",
+      sessionId: "session_123",
+      url: "https://example.com/products/coffee",
+      ts: 1783170000000,
+      event_id: "evt_123",
+      qa_mode: true,
+      qa_session_id: "qa_123",
+    };
+
+    expect(incomingEventSchema.parse(event)).toEqual(event);
+  });
+});