veo-sdk 0.2.0 → 0.3.0

package/README.md

@@ -24,8 +24,9 @@ import { init } from 'veo-sdk';
 // Solo en el navegador (usa localStorage/DOM). En Next: client component.
 const veo = init({
   apiKey: 'pk_xxx',
-  apiUrl: 'https://TU-BACKEND',   // URL pública del veo-backend
-  guides: true,                   // opt-in: renderiza guías in-app
+  guides: true,   // opt-in: renderiza guías in-app
+  // apiUrl es OPCIONAL: por defecto apunta al backend gestionado de Veo.
+  // Solo se pasa para self-hosted / otra región.
 });
 
 veo.identify({ visitor: { id: 'user_123', traits: { email: 'a@b.com' } } });
@@ -39,14 +40,51 @@ Cargá `veo.js` desde unpkg y llamá `init` en el `onload` del `<script>`
 
 ```html
 <script
-  src="https://unpkg.com/veo-sdk@0.2.0/dist/veo.js"
-  onload="window.veo.init({ apiKey: 'pk_xxx', apiUrl: 'https://TU-BACKEND', guides: true });
+  src="https://unpkg.com/veo-sdk@0.2.1/dist/veo.js"
+  onload="window.veo.init({ apiKey: 'pk_xxx', guides: true });
           window.veo.identify({ visitor: { id: 'user_123' } });">
 </script>
 ```
 
-Fijá la versión (`@0.2.0`) para no romperte con un release futuro. También
-disponible por jsDelivr: `https://cdn.jsdelivr.net/npm/veo-sdk@0.2.0/dist/veo.js`.
+`apiUrl` es opcional (default = backend gestionado). Fijá la versión (`@0.2.1`)
+para no romperte con un release futuro. También por jsDelivr:
+`https://cdn.jsdelivr.net/npm/veo-sdk@0.2.1/dist/veo.js`.
+
+## Editor visual de guías (modo builder)
+
+El dashboard de Veo puede abrir tu app en un editor visual para diseñar guías
+sobre ella (elegir el elemento ancla, previsualizar). Para eso abre tu app en un
+`<iframe>` con `?veoBuilder=<token>` y necesita cargar el bundle del builder
+(`veo-builder.js`) para hacer el handshake. Solo se descarga cuando la URL trae
+ese token: **tus usuarios finales nunca lo cargan**.
+
+### CDN (`<script>`)
+
+Funciona sin configurar nada: el SDK deriva la URL de `veo-builder.js` a partir
+del `<script>` que cargó `veo.js`.
+
+### Bundler (Next / Vite / React)
+
+Funciona sin configurar nada: con `init({ guides: true })` el SDK carga el
+builder con un `import()` dinámico cuando la app se abre con `?veoBuilder`. Tu
+bundler lo code-splitea, así que **no se descarga para tus usuarios finales** y
+**no tenés que copiar `veo-builder.js` ni setear `builderUrl`**.
+
+```ts
+init({ apiKey: 'pk_xxx', guides: true });
+```
+
+> `builderUrl` sigue disponible como override manual (CDN propio, CSP estricto),
+> pero ya no hace falta.
+
+### App con login (Supabase, Clerk, …)
+
+Si tu app tiene login, el editor no puede autenticarse dentro del iframe (Google
+OAuth = 403, cookies de terceros). Para diseñar sobre páginas protegidas hace
+falta un **"modo diseño"** en tu app: dejar que Veo la embeba + entrar como
+usuario demo. El SDK trae los helpers (`veoBuilderProxy`, `ensureVeoDesignSession`
+en `veo-sdk/next`) y la **receta completa con Supabase** (2 archivos, copiable)
+está en **[`docs/integrations/visual-editor-embed.md`](./docs/integrations/visual-editor-embed.md)**.
 
 ## API
 

package/dist/builder-UEGKG2UR.mjs

@@ -0,0 +1,5 @@
+export { createBuilderSession, initBuilderMode, startElementPicker, stopElementPicker } from './chunk-66UQ474G.mjs';
+import './chunk-CI7NWEH2.mjs';
+import './chunk-JIU5JLI3.mjs';
+//# sourceMappingURL=builder-UEGKG2UR.mjs.map
+//# sourceMappingURL=builder-UEGKG2UR.mjs.map

package/dist/builder-UEGKG2UR.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"builder-UEGKG2UR.mjs"}

package/dist/builder.cjs

@@ -10,6 +10,67 @@ function hasDocument() {
   return typeof document !== "undefined";
 }
 
+// src/core/builder-constants.ts
+var BUILDER_TOKEN_PARAM = "veoBuilder";
+var BUILDER_ORIGIN_PARAM = "veoBuilderOrigin";
+
+// src/core/builder-token.ts
+var TOKEN_KEY = "veo:builder_token";
+var ORIGIN_KEY = "veo:builder_origin";
+function session() {
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function urlParams() {
+  try {
+    return new URLSearchParams(window.location.search);
+  } catch {
+    return null;
+  }
+}
+function resolveBuilderToken() {
+  if (!hasWindow()) return null;
+  const params = urlParams();
+  const fromUrl = params?.get(BUILDER_TOKEN_PARAM);
+  if (fromUrl) {
+    const store = session();
+    try {
+      store?.setItem(TOKEN_KEY, fromUrl);
+      const origin = params?.get(BUILDER_ORIGIN_PARAM);
+      if (origin) store?.setItem(ORIGIN_KEY, origin);
+    } catch {
+    }
+    return fromUrl;
+  }
+  try {
+    return session()?.getItem(TOKEN_KEY) ?? null;
+  } catch {
+    return null;
+  }
+}
+function resolveBuilderOrigin() {
+  if (!hasWindow()) return null;
+  const fromUrl = urlParams()?.get(BUILDER_ORIGIN_PARAM);
+  if (fromUrl) return fromUrl;
+  try {
+    return session()?.getItem(ORIGIN_KEY) ?? null;
+  } catch {
+    return null;
+  }
+}
+function clearBuilderToken() {
+  if (!hasWindow()) return;
+  try {
+    const store = session();
+    store?.removeItem(TOKEN_KEY);
+    store?.removeItem(ORIGIN_KEY);
+  } catch {
+  }
+}
+
 // src/plugins/guides/constants.ts
 var GUIDE_Z_INDEX = 2147483640;
 var DEFAULT_ANCHOR_WAIT_MS = 5e3;
@@ -1535,8 +1596,6 @@ function safeDestroy(renderer) {
 
 // src/plugins/builder/bridge-protocol.ts
 var VEO_BUILDER_SOURCE = "veo-builder";
-var BUILDER_TOKEN_PARAM = "veoBuilder";
-var BUILDER_ORIGIN_PARAM = "veoBuilderOrigin";
 
 // src/plugins/autocapture/constants.ts
 var HASHED_CLASS_PATTERNS = [
@@ -1822,15 +1881,9 @@ function stopElementPicker() {
 // src/plugins/builder/builder-mode.ts
 function initBuilderMode() {
   if (!hasWindow() || !hasDocument()) return null;
-  let params;
-  try {
-    params = new URLSearchParams(window.location.search);
-  } catch {
-    return null;
-  }
-  const token = params.get(BUILDER_TOKEN_PARAM);
+  const token = resolveBuilderToken();
   if (!token) return null;
-  const dashboardOrigin = resolveDashboardOrigin(params);
+  const dashboardOrigin = resolveDashboardOrigin();
   if (!dashboardOrigin) return null;
   const target = resolveTarget();
   if (!target) return null;
@@ -1883,6 +1936,7 @@ function initBuilderMode() {
     picker?.stop();
     picker = null;
     closeGuidePreview();
+    clearBuilderToken();
     post({ type: "closed" });
   };
   const activate = () => {
@@ -1921,16 +1975,16 @@ function resolveTarget() {
   if (window.parent && window.parent !== window) return window.parent;
   return null;
 }
-function resolveDashboardOrigin(params) {
-  const explicit = params.get(BUILDER_ORIGIN_PARAM);
-  if (explicit) {
+function resolveDashboardOrigin() {
+  const stored = resolveBuilderOrigin();
+  if (stored) {
     try {
-      return new URL(explicit).origin;
+      return new URL(stored).origin;
     } catch {
       return null;
     }
   }
-  if (document.referrer) {
+  if (hasDocument() && document.referrer) {
     try {
       return new URL(document.referrer).origin;
     } catch {