@vitra/image-creator-embed

Framework-agnostic browser iframe mounter for the Vitra Image Creation Platform. ~6 KB gzipped, zero dependencies.

For React, use @vitra/image-creator-react instead — it wraps this package with a typed component.

Install

npm install @vitra/image-creator-embed

Usage

import { VitraEmbed } from "@vitra/image-creator-embed";

const embed = VitraEmbed.mount(document.getElementById("creator")!, {
  sessionEndpoint: "/api/vitra/session",
  theme: { "--brand-500": "#D4512C", "--bg": "#14110F" },
  onReady: () => console.log("mounted"),
  onAssetReady: (e) => downloadAndSave(e.signed_url),
  onError: (e) => console.error(e.reason, e.detail),
});

// Later:
embed.setTheme({ "--brand-500": "#2A6E4E" });
embed.unmount();

How it works

1. You wire up a sessionEndpoint on your host backend that returns a bootstrap token (use @vitra/image-creator-node).
2. On mount(), the SDK fetches a bootstrap token from that endpoint.
3. It sets iframe.src = https://image-creator.vitra.ai/embed#bt=<token>. The token lives in the URL fragment (not query) so it never hits server logs or Referer headers.
4. Inside the iframe, the Image Creator exchanges the one-time bootstrap for a short-lived session JWT (5 min). The parent NEVER sees that JWT.
5. If the session expires and the Partitioned cookie fallback didn't survive, the iframe posts {type: "session.expired"} — the SDK silently fetches a fresh bootstrap and re-mounts. Invisible to the user.

Security model

The SDK enforces three checks on every inbound postMessage:

• event.origin matches the baseUrl origin
• event.source matches the iframe's contentWindow
• the message shape contains a known type field

These checks are internal and cannot be overridden. Messages that fail are silently dropped (with a console.warn at dev time). This is the Codex F2 mitigation against iframe spoofing.

Events

| Event | When | |-------|------| | onReady() | Iframe finished bootstrap exchange | | onAssetReady(e) | A generated asset is available — signed URL + metadata | | onAssetFailed(e) | Generation failed after reserve | | onCreditUsed(e) | Credits captured — use for live "spent" UI | | onResize(e) | Iframe requested a height change | | onError(e) | Unrecoverable error |

The session.expired event is handled by the SDK automatically — no public callback; observe via the iframe's behavior rather than wiring it manually.

License

Apache-2.0.