veo-sdk 0.5.33 → 0.6.0

package/dist/{guide-preview-C73rKO0u.d.cts → guide-preview-DylsEhrg.d.cts}

@@ -18,6 +18,13 @@ interface FormField {
     options?: string[] | null;
     required?: boolean | null;
     placeholder?: string | null;
+    /** Escala numérica (`nps`): rango de valores (default 0..10, máx. 11 valores). */
+    min?: number | null;
+    max?: number | null;
+    /** Escala: etiqueta por valor (índice = valor − min); vacías se omiten. */
+    scaleLabels?: string[] | null;
+    /** Escala: mostrar las etiquetas de los extremos bajo las casillas (default true). */
+    showLabels?: boolean | null;
 }
 type CustomPlacementMode = 'floating' | 'anchored';
 type CustomFloatingPosition = 'top-left' | 'top-center' | 'top-right' | 'center' | 'bottom-left' | 'bottom-center' | 'bottom-right';
@@ -34,13 +41,28 @@ interface CustomPlacement {
     height?: number | string;
 }
 type UrlMatchType = 'exact' | 'prefix' | 'regex';
-type ActivationTrigger = 'immediate' | 'on_element' | 'on_event' | 'delayed' | 'on_click' | 'on_hover';
+type ActivationTrigger = 'immediate' | 'on_element' | 'on_event' | 'delayed' | 'on_click' | 'on_hover' | 'manual';
 type CtaAction = 'dismiss' | 'next' | 'url' | 'guide';
 /**
  * Acciones de un bloque `button` en el modelo unificado (estilo Pendo). Superset
  * de `CtaAction`: agrega navegación (prev) y envío de formularios del paso.
  */
-type ButtonAction = 'dismiss' | 'next' | 'prev' | 'url' | 'guide' | 'submit-forms' | 'submit-forms-advance' | 'submit-forms-goto';
+type ButtonAction = 'dismiss' | 'next' | 'prev'
+/** Ir a un paso concreto (`targetStep`). */
+ | 'goto'
+/** Posponer la guía `snoozeEvery` `snoozeUnit`: se cierra y no vuelve hasta entonces. */
+ | 'snooze' | 'url' | 'guide' | 'submit-forms' | 'submit-forms-advance' | 'submit-forms-goto';
+type SnoozeUnit = 'hour' | 'day' | 'week';
+/** Configuración de una acción de botón (la principal vive en el bloque; `secondAction` es otra igual). */
+interface ButtonActionSpec {
+    action?: ButtonAction | null;
+    url?: string | null;
+    newTab?: boolean | null;
+    targetGuideId?: string | null;
+    targetStep?: number | null;
+    snoozeEvery?: number | null;
+    snoozeUnit?: SnoozeUnit | null;
+}
 interface UrlMatcher {
     type: UrlMatchType;
     pattern: string;
@@ -68,6 +90,12 @@ interface ActivationRules {
     selector?: string;
     eventName?: string;
     delayMs?: number;
+    /**
+     * Con `on_click`/`on_hover`: además de abrirse al interactuar con el
+     * elemento objetivo, la guía arranca sola al cargar (Automático + Elemento
+     * objetivo). `delayMs` aplica a ese arranque automático.
+     */
+    autoShow?: boolean | null;
     repeat?: ActivationRepeat | null;
     /** En qué dispositivos se muestra; lo filtra el SDK (`isDeviceAllowed`). */
     devices?: ActivationDevices | null;
@@ -77,7 +105,30 @@ interface ActivationRules {
     targetBase?: string | null;
 }
 /** Tipo de un bloque de contenido (para pasos con varios títulos/textos/botones). */
-type StepBlockType = 'title' | 'text' | 'button' | 'image' | 'code' | 'form';
+type StepBlockType = 'title' | 'text' | 'button' | 'image' | 'video' | 'divider' | 'code' | 'form' | 'checklist';
+/** Ítem de una lista de tareas (bloque `checklist`): cada tarea ES una guía. */
+interface ChecklistItem {
+    guideId: string;
+    /** Texto visible (default: nombre de la guía). */
+    text?: string | null;
+}
+/** Progreso de un usuario en una guía (`GET /v1/guides/progress`). */
+interface GuideProgressItem {
+    guideId: string;
+    guideName: string;
+    totalSteps: number;
+    /** Pasos hechos (un paso visto cuenta como hecho). */
+    currentStep: number;
+    completed: boolean;
+    /** `false` solo en preview del editor (guía aún no publicada). */
+    published?: boolean;
+}
+/** `file` = video subido al almacenamiento de OnUser: se reproduce con <video>, no con iframe. */
+/**
+ * Proveedores del bloque video. `msstream` = Microsoft Stream (clásico),
+ * `sharepoint` = Microsoft Stream (SharePoint); `file` = archivo propio (R2).
+ */
+type VideoProvider = 'youtube' | 'vimeo' | 'wistia' | 'msstream' | 'sharepoint' | 'brightcove' | 'vidyard' | 'loom' | 'kaltura' | 'file';
 /**
  * Un bloque de contenido dentro de un paso. Permite componer un paso con VARIOS
  * títulos/textos/botones/imágenes en orden (no solo un título + un texto + un
@@ -95,7 +146,8 @@ interface StepBlock {
     /** title/text/button: el texto. En bloques `text` es el FALLBACK de `html`. */
     text?: string | null;
     /**
-     * Solo bloques `text`: rich text con subset whitelisted (negrita/cursiva/
+     * Bloques `text` (contenido) y `form` (la pregunta de la encuesta): rich text
+     * con subset whitelisted (negrita/cursiva/
      * links/listas). El backend lo guarda sanitizado; el SDK lo re-valida al
      * renderizar con `renderRichText` (DOMParser inerte + rebuild manual — nunca
      * innerHTML sobre DOM vivo). Si está presente, manda sobre `text`.
@@ -110,18 +162,50 @@ interface StepBlock {
      * sancionada a la regla no-eval (ver CLAUDE.md).
      */
     sandboxed?: boolean | null;
+    /** Bloques `image`: texto alternativo. Bloques `video`: título accesible del reproductor. */
+    alt?: string | null;
+    /** Bloques `video`: proveedor (la `url` es la del video en ese proveedor). */
+    provider?: VideoProvider | null;
     /** Bloques `form`: los campos del formulario (desacoplado del botón). */
     fields?: FormField[] | null;
+    /** Bloques `checklist`: las guías de la lista, en orden. */
+    items?: ChecklistItem[] | null;
+    /**
+     * Bloques `form` (encuestas): botón de envío PROPIO del bloque. Es un botón
+     * normal (texto/estilo/acciones) que primero envía las respuestas de ESTE
+     * bloque y, si el envío fue bien, ejecuta su acción (cerrar, siguiente…).
+     * La pregunta va en `html`/`text` del bloque (rich text, como `text`).
+     */
+    submit?: StepBlock | null;
     /** image: la URL; button con acción `url`: el destino. */
     url?: string | null;
+    /** button `url`: `false` → misma pestaña; default (ausente/true) → pestaña nueva. */
+    newTab?: boolean | null;
+    /**
+     * Layout del paso: fila y columna del bloque. Sin `row`, cada bloque va en su
+     * propia fila (apilado). Misma fila + distinta columna = lado a lado.
+     */
+    row?: number | null;
+    col?: number | null;
     /** button: qué hace al hacer click (composite: `ButtonAction`). */
     action?: ButtonAction | null;
     /** button con acción `guide`: id de la guía que abre (encadenado). */
     targetGuideId?: string | null;
-    /** button con acción `submit-forms-goto`: índice del paso destino. */
+    /** button con acción `goto` / `submit-forms-goto`: índice del paso destino. */
     targetStep?: number | null;
+    /** button con acción `snooze`: cuánto posponer (cantidad + unidad). */
+    snoozeEvery?: number | null;
+    snoozeUnit?: SnoozeUnit | null;
+    /** Segunda acción del botón (máximo dos): se ejecuta después de la principal. */
+    secondAction?: ButtonActionSpec | null;
     /** Estilo por-bloque (align/color/fontSize/margin…). Se aplica inline. */
     style?: Record<string, unknown> | null;
+    /**
+     * Solo editor (preview in-app): id local del bloque en el panel. El renderer
+     * lo pone en `data-veo-block-id` para que el builder pueda seleccionar el
+     * bloque en la app y el panel abra su editor. No se persiste.
+     */
+    editorId?: string | null;
 }
 interface GuideStep {
     title: string;
@@ -150,6 +234,15 @@ interface GuideStep {
     /** Solo guías `form`: los campos del formulario. */
     fields?: FormField[] | null;
 }
+/**
+ * De dónde salen las respuestas enviadas: la encuesta (id del bloque `form`,
+ * si todas las respuestas son de un mismo bloque) y el paso. El backend guarda
+ * las respuestas de guías composite POR GUÍA y POR ENCUESTA con este dato.
+ */
+interface FormSubmitMeta {
+    pollId?: string;
+    stepIndex: number;
+}
 
 /** Entrada mínima para previsualizar una guía. */
 interface PreviewGuideInput {
@@ -173,10 +266,20 @@ interface PreviewGuideInput {
      * es un no-op (no escribe props). Lo usa el modo preview-por-link, que sí
      * guarda en el usuario que responde.
      */
-    formSubmit?: (answers: Record<string, unknown>) => Promise<boolean>;
+    formSubmit?: (answers: Record<string, unknown>, meta?: FormSubmitMeta) => Promise<boolean>;
+    /**
+     * Lista de tareas en preview: progreso de las guías de la lista (el editor
+     * lo pide al backend con un usuario de preview: nombres y pasos reales,
+     * progreso en cero). Sin esto la lista se ve sin subtítulos ni barra.
+     */
+    fetchProgress?: (guideIds: string[]) => Promise<GuideProgressItem[]>;
     /** Nota bajo el "¡Gracias!" cuando hay `formSubmit` propio. */
     formSubmitNote?: string;
     /** Modo badge: montar con el tooltip ABIERTO (toggle del editor). */
+    /**
+     * Badge: tooltip abierto (true) o cerrado (false). Sin definir, se abre si la
+     * activación es automática (igual que el runtime).
+     */
     badgeOpen?: boolean;
     /**
      * Se llama cuando el USUARIO cierra la preview (✕ / descartar), no cuando el

package/dist/{guide-preview-C73rKO0u.d.ts → guide-preview-DylsEhrg.d.ts}

@@ -18,6 +18,13 @@ interface FormField {
     options?: string[] | null;
     required?: boolean | null;
     placeholder?: string | null;
+    /** Escala numérica (`nps`): rango de valores (default 0..10, máx. 11 valores). */
+    min?: number | null;
+    max?: number | null;
+    /** Escala: etiqueta por valor (índice = valor − min); vacías se omiten. */
+    scaleLabels?: string[] | null;
+    /** Escala: mostrar las etiquetas de los extremos bajo las casillas (default true). */
+    showLabels?: boolean | null;
 }
 type CustomPlacementMode = 'floating' | 'anchored';
 type CustomFloatingPosition = 'top-left' | 'top-center' | 'top-right' | 'center' | 'bottom-left' | 'bottom-center' | 'bottom-right';
@@ -34,13 +41,28 @@ interface CustomPlacement {
     height?: number | string;
 }
 type UrlMatchType = 'exact' | 'prefix' | 'regex';
-type ActivationTrigger = 'immediate' | 'on_element' | 'on_event' | 'delayed' | 'on_click' | 'on_hover';
+type ActivationTrigger = 'immediate' | 'on_element' | 'on_event' | 'delayed' | 'on_click' | 'on_hover' | 'manual';
 type CtaAction = 'dismiss' | 'next' | 'url' | 'guide';
 /**
  * Acciones de un bloque `button` en el modelo unificado (estilo Pendo). Superset
  * de `CtaAction`: agrega navegación (prev) y envío de formularios del paso.
  */
-type ButtonAction = 'dismiss' | 'next' | 'prev' | 'url' | 'guide' | 'submit-forms' | 'submit-forms-advance' | 'submit-forms-goto';
+type ButtonAction = 'dismiss' | 'next' | 'prev'
+/** Ir a un paso concreto (`targetStep`). */
+ | 'goto'
+/** Posponer la guía `snoozeEvery` `snoozeUnit`: se cierra y no vuelve hasta entonces. */
+ | 'snooze' | 'url' | 'guide' | 'submit-forms' | 'submit-forms-advance' | 'submit-forms-goto';
+type SnoozeUnit = 'hour' | 'day' | 'week';
+/** Configuración de una acción de botón (la principal vive en el bloque; `secondAction` es otra igual). */
+interface ButtonActionSpec {
+    action?: ButtonAction | null;
+    url?: string | null;
+    newTab?: boolean | null;
+    targetGuideId?: string | null;
+    targetStep?: number | null;
+    snoozeEvery?: number | null;
+    snoozeUnit?: SnoozeUnit | null;
+}
 interface UrlMatcher {
     type: UrlMatchType;
     pattern: string;
@@ -68,6 +90,12 @@ interface ActivationRules {
     selector?: string;
     eventName?: string;
     delayMs?: number;
+    /**
+     * Con `on_click`/`on_hover`: además de abrirse al interactuar con el
+     * elemento objetivo, la guía arranca sola al cargar (Automático + Elemento
+     * objetivo). `delayMs` aplica a ese arranque automático.
+     */
+    autoShow?: boolean | null;
     repeat?: ActivationRepeat | null;
     /** En qué dispositivos se muestra; lo filtra el SDK (`isDeviceAllowed`). */
     devices?: ActivationDevices | null;
@@ -77,7 +105,30 @@ interface ActivationRules {
     targetBase?: string | null;
 }
 /** Tipo de un bloque de contenido (para pasos con varios títulos/textos/botones). */
-type StepBlockType = 'title' | 'text' | 'button' | 'image' | 'code' | 'form';
+type StepBlockType = 'title' | 'text' | 'button' | 'image' | 'video' | 'divider' | 'code' | 'form' | 'checklist';
+/** Ítem de una lista de tareas (bloque `checklist`): cada tarea ES una guía. */
+interface ChecklistItem {
+    guideId: string;
+    /** Texto visible (default: nombre de la guía). */
+    text?: string | null;
+}
+/** Progreso de un usuario en una guía (`GET /v1/guides/progress`). */
+interface GuideProgressItem {
+    guideId: string;
+    guideName: string;
+    totalSteps: number;
+    /** Pasos hechos (un paso visto cuenta como hecho). */
+    currentStep: number;
+    completed: boolean;
+    /** `false` solo en preview del editor (guía aún no publicada). */
+    published?: boolean;
+}
+/** `file` = video subido al almacenamiento de OnUser: se reproduce con <video>, no con iframe. */
+/**
+ * Proveedores del bloque video. `msstream` = Microsoft Stream (clásico),
+ * `sharepoint` = Microsoft Stream (SharePoint); `file` = archivo propio (R2).
+ */
+type VideoProvider = 'youtube' | 'vimeo' | 'wistia' | 'msstream' | 'sharepoint' | 'brightcove' | 'vidyard' | 'loom' | 'kaltura' | 'file';
 /**
  * Un bloque de contenido dentro de un paso. Permite componer un paso con VARIOS
  * títulos/textos/botones/imágenes en orden (no solo un título + un texto + un
@@ -95,7 +146,8 @@ interface StepBlock {
     /** title/text/button: el texto. En bloques `text` es el FALLBACK de `html`. */
     text?: string | null;
     /**
-     * Solo bloques `text`: rich text con subset whitelisted (negrita/cursiva/
+     * Bloques `text` (contenido) y `form` (la pregunta de la encuesta): rich text
+     * con subset whitelisted (negrita/cursiva/
      * links/listas). El backend lo guarda sanitizado; el SDK lo re-valida al
      * renderizar con `renderRichText` (DOMParser inerte + rebuild manual — nunca
      * innerHTML sobre DOM vivo). Si está presente, manda sobre `text`.
@@ -110,18 +162,50 @@ interface StepBlock {
      * sancionada a la regla no-eval (ver CLAUDE.md).
      */
     sandboxed?: boolean | null;
+    /** Bloques `image`: texto alternativo. Bloques `video`: título accesible del reproductor. */
+    alt?: string | null;
+    /** Bloques `video`: proveedor (la `url` es la del video en ese proveedor). */
+    provider?: VideoProvider | null;
     /** Bloques `form`: los campos del formulario (desacoplado del botón). */
     fields?: FormField[] | null;
+    /** Bloques `checklist`: las guías de la lista, en orden. */
+    items?: ChecklistItem[] | null;
+    /**
+     * Bloques `form` (encuestas): botón de envío PROPIO del bloque. Es un botón
+     * normal (texto/estilo/acciones) que primero envía las respuestas de ESTE
+     * bloque y, si el envío fue bien, ejecuta su acción (cerrar, siguiente…).
+     * La pregunta va en `html`/`text` del bloque (rich text, como `text`).
+     */
+    submit?: StepBlock | null;
     /** image: la URL; button con acción `url`: el destino. */
     url?: string | null;
+    /** button `url`: `false` → misma pestaña; default (ausente/true) → pestaña nueva. */
+    newTab?: boolean | null;
+    /**
+     * Layout del paso: fila y columna del bloque. Sin `row`, cada bloque va en su
+     * propia fila (apilado). Misma fila + distinta columna = lado a lado.
+     */
+    row?: number | null;
+    col?: number | null;
     /** button: qué hace al hacer click (composite: `ButtonAction`). */
     action?: ButtonAction | null;
     /** button con acción `guide`: id de la guía que abre (encadenado). */
     targetGuideId?: string | null;
-    /** button con acción `submit-forms-goto`: índice del paso destino. */
+    /** button con acción `goto` / `submit-forms-goto`: índice del paso destino. */
     targetStep?: number | null;
+    /** button con acción `snooze`: cuánto posponer (cantidad + unidad). */
+    snoozeEvery?: number | null;
+    snoozeUnit?: SnoozeUnit | null;
+    /** Segunda acción del botón (máximo dos): se ejecuta después de la principal. */
+    secondAction?: ButtonActionSpec | null;
     /** Estilo por-bloque (align/color/fontSize/margin…). Se aplica inline. */
     style?: Record<string, unknown> | null;
+    /**
+     * Solo editor (preview in-app): id local del bloque en el panel. El renderer
+     * lo pone en `data-veo-block-id` para que el builder pueda seleccionar el
+     * bloque en la app y el panel abra su editor. No se persiste.
+     */
+    editorId?: string | null;
 }
 interface GuideStep {
     title: string;
@@ -150,6 +234,15 @@ interface GuideStep {
     /** Solo guías `form`: los campos del formulario. */
     fields?: FormField[] | null;
 }
+/**
+ * De dónde salen las respuestas enviadas: la encuesta (id del bloque `form`,
+ * si todas las respuestas son de un mismo bloque) y el paso. El backend guarda
+ * las respuestas de guías composite POR GUÍA y POR ENCUESTA con este dato.
+ */
+interface FormSubmitMeta {
+    pollId?: string;
+    stepIndex: number;
+}
 
 /** Entrada mínima para previsualizar una guía. */
 interface PreviewGuideInput {
@@ -173,10 +266,20 @@ interface PreviewGuideInput {
      * es un no-op (no escribe props). Lo usa el modo preview-por-link, que sí
      * guarda en el usuario que responde.
      */
-    formSubmit?: (answers: Record<string, unknown>) => Promise<boolean>;
+    formSubmit?: (answers: Record<string, unknown>, meta?: FormSubmitMeta) => Promise<boolean>;
+    /**
+     * Lista de tareas en preview: progreso de las guías de la lista (el editor
+     * lo pide al backend con un usuario de preview: nombres y pasos reales,
+     * progreso en cero). Sin esto la lista se ve sin subtítulos ni barra.
+     */
+    fetchProgress?: (guideIds: string[]) => Promise<GuideProgressItem[]>;
     /** Nota bajo el "¡Gracias!" cuando hay `formSubmit` propio. */
     formSubmitNote?: string;
     /** Modo badge: montar con el tooltip ABIERTO (toggle del editor). */
+    /**
+     * Badge: tooltip abierto (true) o cerrado (false). Sin definir, se abre si la
+     * activación es automática (igual que el runtime).
+     */
     badgeOpen?: boolean;
     /**
      * Se llama cuando el USUARIO cierra la preview (✕ / descartar), no cuando el