Browser SDK

type ModaEmbedMessage<TPayload = unknown> = {
  channel: "moda.embed";
  version: "2026-05-27";
  sessionId: string;
  requestId?: string;
  type: string;
  payload?: TPayload;
};

<iframe
  src="EMBED_URL"
  title="Moda canvas"
  allow="clipboard-read; clipboard-write; fullscreen"
  referrerpolicy="strict-origin-when-cross-origin"
  style="width: 100%; height: 100%; border: 0"
></iframe>

client.on("ready", (payload) => {
  console.log("Moda embed ready", payload);
  // payload includes { page, pageCount, category, pages } when this `ready`
  // is a host.hello reply sent after the canvas became interactive.
});

// Poll host.hello until the first `ready`, then clear the interval.
const helloTimer = setInterval(() => {
  client.post("host.hello", { parentOrigin: window.location.origin });
}, 250);
client.on("ready", () => clearInterval(helloTimer));

client.post("save");

client.post("export", { format: "png", page: 1 });
client.post("export", { format: "pdf" });
client.post("export", { format: "pptx" });

client.post("export", { format: "pdf", flatten: true });

client.on("export:completed", async (payload: any) => {
  const a = document.createElement("a");
  a.href = payload.downloadUrl;
  a.download = payload.filename;
  a.click();
});

client.post("focusPage", { page: 2 });

client.post("setReadonly", { readonly: true });
client.post("setReadonly", { readonly: false });

client.post("insertText", {
  text: "Approved by legal",
  x: 120,
  y: 120,
  width: 360,
  height: 80,
});

client.post("insertImage", {
  file,
  filename: file.name,
  mimeType: file.type,
  x: 160,
  y: 220,
  width: 400,
});

client.post("insertImage", {
  url: "https://cdn.example.com/generated/product-shot.png",
  x: 160,
  y: 220,
  width: 400,
});

client.post("chat.send", {
  message: "Make this design more concise and on-brand.",
});
client.post("chat.stop");
client.post("chat.newThread");

type ChatMessagePayload = {
  id: string; // stable per message — use as your render key
  sender: "user" | "ai" | "system";
  text: string; // full message text (NOT a delta)
  timestamp: string; // ISO 8601
};

client.on("chat:message", (payload: ChatMessagePayload) => {
  appendChatBubble(payload.sender, payload.text); // no `?? message ?? delta ?? content`
});

client.on("session:refresh_requested", async () => {
  const refreshed = await refreshEmbedSession();

  client.post("session.refresh", {
    token: new URL(refreshed.embed_url).searchParams.get("token"),
    expiresAt: refreshed.expires_at,
    browserToken: refreshed.browser_token,
    browserTokenExpiresAt: refreshed.browser_token_expires_at,
  });
});

// Assumes your setup used a reassignable reference: `let client = new ModaEmbedClient(...)`.
let recovering = false;

function attachSessionRecovery(target: ModaEmbedClient) {
  const recover = async (payload: { scope?: string }) => {
    if (recovering) return; // expired + revoked for the same session → ONE recovery
    recovering = true;
    try {
      // Browser-token-scope expiry: the outer session may still be live —
      // a refresh keeps the iframe (and any unflushed edits) intact.
      if (payload?.scope === "browser_token") {
        const response = await fetch("/api/moda-embed/refresh", {
          method: "POST",
          body: JSON.stringify({ sessionId: target.sessionId }),
        });
        if (response.ok) {
          const refreshed = await response.json();
          target.post("session.refresh", {
            token: new URL(refreshed.embed_url).searchParams.get("token"),
            expiresAt: refreshed.expires_at,
            browserToken: refreshed.browser_token,
            browserTokenExpiresAt: refreshed.browser_token_expires_at,
          });
          return;
        }
        // ONLY 404/409/410 prove the session is dead (create is the recovery);
        // 410 is the terminal "stop refreshing this id" answer. Anything else —
        // 5xx, 429, network hiccups — is transient: keep the iframe and let the
        // next expiry signal (or your own retry) re-attempt, instead of
        // destroying a session a refresh might still save.
        if (![404, 409, 410].includes(response.status)) return;
      }

      // Mint a brand-NEW session (POST /v1/embed/sessions — the same call as
      // your initial mount; NOT .../refresh, which 404s on a dead session).
      const response = await fetch("/api/moda-embed/create", {
        method: "POST",
        body: JSON.stringify({ canvasId }),
      });
      if (!response.ok) return; // transient create failure — keep the old client, retry later
      const session = await response.json();
      if (!session?.session_id || !session?.embed_url) return; // malformed — do not destroy

      // Only NOW destroy the old client: the replacement is proven mintable.
      // Re-key to the new session id and swap the iframe over (the old client
      // filters on the old sessionId, so it must be replaced).
      target.destroy();
      client = new ModaEmbedClient(
        iframe,
        session.session_id,
        session.embed_url,
      );
      attachSessionRecovery(client); // re-attach your listeners, including this one
      iframe.src = session.embed_url;
    } finally {
      recovering = false;
    }
  };

  target.on("session:expired", recover);
  target.on("session:revoked", recover); // or tear down on deliberate revocations
}