veo-sdk 0.4.2 → 0.5.0

package/dist/{guide-preview-D_xhRVLe.d.cts → guide-preview-B912Y6UY.d.cts}

@@ -34,8 +34,8 @@ interface CustomPlacement {
     height?: number | string;
 }
 type UrlMatchType = 'exact' | 'prefix' | 'regex';
-type ActivationTrigger = 'immediate' | 'on_element' | 'on_event' | 'delayed';
-type CtaAction = 'dismiss' | 'next' | 'url';
+type ActivationTrigger = 'immediate' | 'on_element' | 'on_event' | 'delayed' | 'on_click' | 'on_hover';
+type CtaAction = 'dismiss' | 'next' | 'url' | 'guide';
 interface UrlMatcher {
     type: UrlMatchType;
     pattern: string;
@@ -76,6 +76,8 @@ interface StepBlock {
     url?: string | null;
     /** button: qué hace al hacer click. */
     action?: CtaAction | null;
+    /** button con acción `guide`: id de la guía que abre (encadenado). */
+    targetGuideId?: string | null;
     /** Estilo por-bloque (align/color/fontSize/margin…). Se aplica inline. */
     style?: Record<string, unknown> | null;
 }

package/dist/{guide-preview-D_xhRVLe.d.ts → guide-preview-B912Y6UY.d.ts}

@@ -34,8 +34,8 @@ interface CustomPlacement {
     height?: number | string;
 }
 type UrlMatchType = 'exact' | 'prefix' | 'regex';
-type ActivationTrigger = 'immediate' | 'on_element' | 'on_event' | 'delayed';
-type CtaAction = 'dismiss' | 'next' | 'url';
+type ActivationTrigger = 'immediate' | 'on_element' | 'on_event' | 'delayed' | 'on_click' | 'on_hover';
+type CtaAction = 'dismiss' | 'next' | 'url' | 'guide';
 interface UrlMatcher {
     type: UrlMatchType;
     pattern: string;
@@ -76,6 +76,8 @@ interface StepBlock {
     url?: string | null;
     /** button: qué hace al hacer click. */
     action?: CtaAction | null;
+    /** button con acción `guide`: id de la guía que abre (encadenado). */
+    targetGuideId?: string | null;
     /** Estilo por-bloque (align/color/fontSize/margin…). Se aplica inline. */
     style?: Record<string, unknown> | null;
 }

package/dist/index.cjs

@@ -615,12 +615,12 @@ function buildButtonBlock(block, doc, callbacks) {
   applyBlockStyle(btn, block.style, "button");
   btn.addEventListener("click", () => {
     const action = block.action ?? "dismiss";
-    const url = action === "url" && typeof block.url === "string" && isSafeUrl(block.url) ? block.url : void 0;
+    const target = action === "url" && typeof block.url === "string" && isSafeUrl(block.url) ? block.url : action === "guide" && typeof block.targetGuideId === "string" && block.targetGuideId ? block.targetGuideId : void 0;
     const meta = {
       ...typeof block.id === "string" && block.id ? { buttonId: block.id } : {},
       ...typeof block.text === "string" && block.text ? { buttonText: block.text } : {}
     };
-    callbacks.onCtaClick(action, url, Object.keys(meta).length ? meta : void 0);
+    callbacks.onCtaClick(action, target, Object.keys(meta).length ? meta : void 0);
   });
   return btn;
 }
@@ -1554,15 +1554,16 @@ var init_badge_renderer = __esm({
           });
         };
         const buildTooltipContent = (s) => buildStepContent(s, ownerDocument, {
-          onCtaClick: (action, url, meta) => {
+          onCtaClick: (action, target, meta) => {
             emit("cta_clicked", meta);
-            if (action === "url" && url) window.open(url, "_blank", "noopener,noreferrer");
+            if (action === "url" && target) window.open(target, "_blank", "noopener,noreferrer");
             if (action === "dismiss") {
               emit("dismissed");
               context.onClose();
               return;
             }
             this.closeTooltip();
+            if (action === "guide" && target) context.onOpenGuide?.(target);
           },
           onDismiss: () => {
             emit("dismissed");
@@ -1820,7 +1821,10 @@ var init_banner_renderer = __esm({
           ownerDocument,
           context.nav.callbacks
         ) : buildStepContent(step, ownerDocument, {
-          onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
+          },
           onDismiss: () => dismiss("dismissed")
         });
         banner.appendChild(content);
@@ -1835,7 +1839,10 @@ var init_banner_renderer = __esm({
           this.liveContainer = banner;
           this.liveContent = content;
           this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-            onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+            onCtaClick: (action, target, meta) => {
+              dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+              if (action === "guide" && target) context.onOpenGuide?.(target);
+            },
             onDismiss: () => dismiss("dismissed")
           });
           this.liveKey = this.liveKeyOf(step);
@@ -2496,7 +2503,10 @@ var init_inline_renderer = __esm({
           context.onClose();
         };
         const content = buildStepContent(step, ownerDocument, {
-          onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
+          },
           onDismiss: () => dismiss("dismissed")
         });
         card.appendChild(content);
@@ -2505,7 +2515,10 @@ var init_inline_renderer = __esm({
         this.liveContent = content;
         this.liveKey = `${selector}|${position}`;
         this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-          onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
+          },
           onDismiss: () => dismiss("dismissed")
         });
         context.onInteraction({ guideId: context.guide.guideId, stepIndex: 0, action: "shown" });
@@ -2565,7 +2578,10 @@ var init_modal_renderer = __esm({
           ownerDocument,
           context.nav.callbacks
         ) : buildStepContent(step, ownerDocument, {
-          onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
+          },
           onDismiss: () => dismiss("dismissed")
         });
         card.appendChild(content);
@@ -2575,7 +2591,10 @@ var init_modal_renderer = __esm({
           this.liveContainer = card;
           this.liveContent = content;
           this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-            onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+            onCtaClick: (action, target, meta) => {
+              dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+              if (action === "guide" && target) context.onOpenGuide?.(target);
+            },
             onDismiss: () => dismiss("dismissed")
           });
         }
@@ -2640,8 +2659,9 @@ var init_tooltip_renderer = __esm({
           context.onClose();
         };
         const content = buildStepContent(step, ownerDocument, {
-          onCtaClick: (action, url, meta) => {
-            dismiss("cta_clicked", action === "url" ? url : void 0, meta);
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
           },
           onDismiss: () => dismiss("dismissed")
         });
@@ -2674,7 +2694,10 @@ var init_tooltip_renderer = __esm({
         this.liveContent = content;
         this.liveKey = selector;
         this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-          onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
+          },
           onDismiss: () => dismiss("dismissed")
         });
         context.onInteraction({
@@ -2891,6 +2914,10 @@ var init_guide_preview = __esm({
             onClose: () => this.close(),
             onTrack: () => {
             },
+            // Encadenado en preview: no-op — el editor no puede montar otra guía
+            // guardada; el click igual cierra la preview actual (vía onCtaClick).
+            onOpenGuide: () => {
+            },
             // Preview de forms: por defecto simula el envío SIN escribir props;
             // el caller puede pasar `formSubmit` real (link de preview).
             onFormSubmit: this.input?.formSubmit ?? (() => Promise.resolve(true)),
@@ -5333,6 +5360,12 @@ var GuidesController = class {
     this.resolveCache = null;
     /** Resolución idéntica en vuelo, para coalescer llamadas concurrentes. */
     this.inflightResolve = null;
+    /**
+     * Disparadores por interacción armados (`on_click`/`on_hover`): guideId →
+     * desarme del listener. Se re-arman desde cero en cada `checkGuides` (el
+     * resolve fresco manda) y se limpian en `destroy()`.
+     */
+    this.armedTriggers = /* @__PURE__ */ new Map();
     this.debug = config.debug === true;
     this.apiUrl = config.apiUrl;
     this.apiKey = config.apiKey;
@@ -5390,26 +5423,80 @@ var GuidesController = class {
       return;
     }
     if (this.debug) console.log(`[veo] guides: ${guides.length} eligible at ${pageUrl}`);
+    this.disarmTriggers();
     for (const guide of guides) {
-      if (this.frequencyCache.shouldFilter(guide.guideId, guide.displayFrequency)) {
-        if (this.debug) console.log(`[veo] guides: filtered locally guideId=${guide.guideId}`);
-        continue;
-      }
-      if (this.activeByGuideId.has(guide.guideId)) {
-        if (this.debug) console.log(`[veo] guides: already shown guideId=${guide.guideId}`);
+      const trigger = guide.activationRules.trigger;
+      if ((trigger === "on_click" || trigger === "on_hover") && guide.activationRules.selector) {
+        this.armInteractionTrigger(guide, endUserId, sessionId, pageUrl);
         continue;
       }
-      if (guide.guideType === "walkthrough" && guide.guideSteps.length > 1) {
-        if (this.walkthroughState.hasActive()) {
-          if (this.debug)
-            console.log(`[veo] guides: walkthrough ${guide.guideId} skipped (another active)`);
-          continue;
-        }
-        await this.startWalkthrough(guide, endUserId, sessionId, pageUrl);
-        continue;
+      await this.showGuide(guide, endUserId, sessionId, pageUrl);
+    }
+  }
+  /**
+   * Muestra una guía elegible (filtro de frecuencia + dedupe + dispatch por
+   * tipo). Cuerpo original del loop de `checkGuides`, extraído para que los
+   * disparadores por interacción pasen por LOS MISMOS chequeos al disparar.
+   */
+  async showGuide(guide, endUserId, sessionId, pageUrl) {
+    if (this.frequencyCache.shouldFilter(guide.guideId, guide.displayFrequency)) {
+      if (this.debug) console.log(`[veo] guides: filtered locally guideId=${guide.guideId}`);
+      return;
+    }
+    if (this.activeByGuideId.has(guide.guideId)) {
+      if (this.debug) console.log(`[veo] guides: already shown guideId=${guide.guideId}`);
+      return;
+    }
+    if (guide.guideType === "walkthrough" && guide.guideSteps.length > 1) {
+      if (this.walkthroughState.hasActive()) {
+        if (this.debug)
+          console.log(`[veo] guides: walkthrough ${guide.guideId} skipped (another active)`);
+        return;
       }
-      this.runSingleStepRender(guide, sessionId, pageUrl);
+      await this.startWalkthrough(guide, endUserId, sessionId, pageUrl);
+      return;
     }
+    this.runSingleStepRender(guide, sessionId, pageUrl);
+  }
+  /**
+   * Arma un disparador por interacción: la guía NO se muestra al cargar, sino
+   * cuando el usuario hace click / pasa el mouse sobre `activationRules.selector`.
+   * Listener DELEGADO en `document` (fase captura, sin preventDefault — el click
+   * original de la app sigue funcionando). Al disparar se desarma y la guía pasa
+   * por `showGuide` (mismos chequeos de frecuencia/dedupe). Tras cerrarse, el
+   * próximo pageview/identify la re-arma — hover/click vuelve a mostrarla
+   * mientras la frecuencia lo permita.
+   */
+  armInteractionTrigger(guide, endUserId, sessionId, pageUrl) {
+    if (this.frequencyCache.shouldFilter(guide.guideId, guide.displayFrequency)) return;
+    if (this.activeByGuideId.has(guide.guideId)) return;
+    if (this.armedTriggers.has(guide.guideId)) return;
+    const selector = guide.activationRules.selector;
+    const eventName = guide.activationRules.trigger === "on_hover" ? "mouseover" : "click";
+    const onFire = (e) => {
+      const target = e.target;
+      if (!(target instanceof Element)) return;
+      try {
+        if (!target.closest(selector)) return;
+      } catch {
+        return;
+      }
+      disarm();
+      void this.showGuide(guide, endUserId, sessionId, pageUrl);
+    };
+    const disarm = () => {
+      document.removeEventListener(eventName, onFire, true);
+      this.armedTriggers.delete(guide.guideId);
+    };
+    document.addEventListener(eventName, onFire, true);
+    this.armedTriggers.set(guide.guideId, disarm);
+    if (this.debug)
+      console.log(`[veo] guides: armed ${eventName} trigger for ${guide.guideId} on ${selector}`);
+  }
+  /** Desarma todos los disparadores por interacción pendientes. */
+  disarmTriggers() {
+    for (const disarm of this.armedTriggers.values()) disarm();
+    this.armedTriggers.clear();
   }
   /**
    * `resolve` con cache de corta duración + coalescing:
@@ -5460,6 +5547,7 @@ ${pageUrl}`;
       this.activeWalkthroughRenderer = null;
       this.activeWalkthroughGuide = null;
     }
+    this.disarmTriggers();
     this.dispatched.clear();
     this.resolveCache = null;
     this.inflightResolve = null;
@@ -5492,8 +5580,11 @@ ${pageUrl}`;
       this.client.track(eventName, properties);
     };
     const onFormSubmit = (answers) => this.submitFormResponse(guide.guideId, answers);
+    const onOpenGuide = (targetGuideId) => {
+      void this.openGuideById(targetGuideId, sessionId, pageUrl);
+    };
     try {
-      void renderer.render({ guide, onInteraction, onClose, onTrack, onFormSubmit });
+      void renderer.render({ guide, onInteraction, onClose, onTrack, onFormSubmit, onOpenGuide });
     } catch (err) {
       if (this.debug) console.error("[veo] renderer.render threw:", err);
       this.activeRenderers.delete(renderer);
@@ -5502,6 +5593,28 @@ ${pageUrl}`;
       }
     }
   }
+  /**
+   * Abre una guía POR ID, disparada desde el botón de otra guía (encadenado).
+   * Ignora las URL rules y el trigger (el autor lo pidió explícitamente desde
+   * un botón); respeta el dedupe de guías activas y el flujo normal de
+   * tracking. 404/red → no-op (la guía destino pudo borrarse).
+   */
+  async openGuideById(guideId, sessionId, pageUrl) {
+    if (this.activeByGuideId.has(guideId)) return;
+    const guide = await this.resolver.fetchById(guideId);
+    if (!guide) {
+      if (this.debug) console.warn(`[veo] guides: chained guide ${guideId} not found`);
+      return;
+    }
+    const endUserId = this.client.getEndUserId() ?? this.client.getAnonymousId();
+    if (guide.guideType === "walkthrough" && guide.guideSteps.length > 1) {
+      if (!this.walkthroughState.hasActive()) {
+        await this.startWalkthrough(guide, endUserId, sessionId, pageUrl);
+      }
+      return;
+    }
+    this.runSingleStepRender(guide, sessionId, pageUrl);
+  }
   /**
    * Si hay un walkthrough persistido, intenta pintar el step actual en
    * la página actual. Retorna `true` si lo intentó (sea éxito o cancel),