veo-sdk 0.1.0 → 0.2.1

package/dist/guide-preview-CO5ShtNf.d.cts

@@ -0,0 +1,137 @@
+/**
+ * Tipos consumidos por el plugin de guides. Reflejan el shape que devuelve
+ * `GET /v1/guides/resolve` en el backend — debe mantenerse en sync con
+ * `veo-backend/src/modules/guides/types/guide-content.types.ts` y
+ * `guide.response.ts`.
+ */
+type GuideType = 'modal' | 'banner' | 'tooltip' | 'walkthrough' | 'custom' | 'inline' | 'inline-custom' | 'form' | 'inline-form';
+type FormFieldType = 'text' | 'textarea' | 'number' | 'select' | 'multiselect' | 'radio' | 'checkbox' | 'yesno' | 'nps' | 'rating';
+/**
+ * Un campo de una guía `form`. `key` es el nombre de la PROPIEDAD que se
+ * escribe en los traits del usuario que responde (encuesta/NPS estilo Pendo).
+ */
+interface FormField {
+    key: string;
+    label: string;
+    type: FormFieldType;
+    /** Para select/radio: opciones visibles (el valor guardado es el texto). */
+    options?: string[] | null;
+    required?: boolean | null;
+    placeholder?: string | null;
+}
+type CustomPlacementMode = 'floating' | 'anchored';
+type CustomFloatingPosition = 'top-left' | 'top-center' | 'top-right' | 'center' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+type CustomAnchorSide = 'top' | 'bottom' | 'left' | 'right';
+/** Dónde se monta una guía `custom`. Ver backend `guide-content.types.ts`. */
+interface CustomPlacement {
+    mode: CustomPlacementMode;
+    position?: CustomFloatingPosition;
+    offsetX?: number;
+    offsetY?: number;
+    selector?: string;
+    side?: CustomAnchorSide;
+    width?: number | string;
+    height?: number | string;
+}
+type UrlMatchType = 'exact' | 'prefix' | 'regex';
+type ActivationTrigger = 'immediate' | 'on_element' | 'on_event' | 'delayed';
+type CtaAction = 'dismiss' | 'next' | 'url';
+interface UrlMatcher {
+    type: UrlMatchType;
+    pattern: string;
+}
+interface ActivationRules {
+    url: UrlMatcher;
+    trigger: ActivationTrigger;
+    selector?: string;
+    eventName?: string;
+    delayMs?: number;
+}
+interface GuideStep {
+    title: string;
+    content: string;
+    ctaText?: string | null;
+    ctaAction?: CtaAction | null;
+    imageUrl?: string | null;
+    selector?: string | null;
+    /**
+     * Free-form JSONB. Convención: si `ctaAction === 'url'`, la URL destino
+     * se lee de `style.ctaUrl`. Otras keys que puede traer: `position`
+     * (`top` | `bottom` para banners), `theme`.
+     */
+    style?: Record<string, unknown> | null;
+    /** Solo guías `custom`: código a renderizar en un iframe sandbox + ubicación. */
+    html?: string | null;
+    css?: string | null;
+    js?: string | null;
+    placement?: CustomPlacement | null;
+    /** Solo guías `form`: los campos del formulario. */
+    fields?: FormField[] | null;
+}
+
+/** Entrada mínima para previsualizar una guía. */
+interface PreviewGuideInput {
+    guideType: GuideType;
+    guideSteps: GuideStep[];
+    /**
+     * Opcional. Solo se usa `activationRules.selector` como fallback del
+     * ancla para tooltip/walkthrough cuando el step no trae su propio
+     * `selector`. El resto de reglas (url/trigger/delay) se ignoran.
+     */
+    activationRules?: Partial<ActivationRules>;
+    /** Nombre mostrado (p.ej. en el `title` del iframe de guías `custom`). */
+    guideName?: string;
+    /**
+     * Solo walkthrough: paso inicial a mostrar (default 0). Lo usa el editor del
+     * dashboard para que la preview salte al paso que se está editando.
+     */
+    startStepIndex?: number;
+    /**
+     * Solo guías form: envío REAL de respuestas. Sin esto, el submit en preview
+     * 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>;
+    /** Nota bajo el "¡Gracias!" cuando hay `formSubmit` propio. */
+    formSubmitNote?: string;
+}
+/** Resultado del primer render de una preview. */
+interface PreviewResult {
+    /**
+     * `false` cuando la guía no pudo pintarse — típicamente un
+     * tooltip/walkthrough cuyo `selector` no existe en la página de preview.
+     */
+    rendered: boolean;
+}
+/** Handle de una preview activa. */
+interface PreviewHandle {
+    /** Cierra y limpia la preview. Idempotente. */
+    close(): void;
+    /** Resuelve cuando el primer render terminó. */
+    ready: Promise<PreviewResult>;
+}
+/**
+ * Previsualiza una guía en la página actual usando los renderers reales
+ * del SDK. Devuelve un handle con `close()` y una promesa `ready`.
+ *
+ * Pensado para el builder no-code: no necesita `init()` ni apiKey. Abrir
+ * una nueva preview cierra automáticamente la anterior.
+ *
+ * @example
+ * ```ts
+ * import { previewGuide } from '@veo/sdk';
+ *
+ * const preview = previewGuide({
+ *   guideType: 'modal',
+ *   guideSteps: [{ title: 'Hola', content: 'Esto es una preview' }],
+ * });
+ * const { rendered } = await preview.ready;
+ * // ...más tarde:
+ * preview.close();
+ * ```
+ */
+declare function previewGuide(input: PreviewGuideInput): PreviewHandle;
+/** Cierra la preview activa, si la hay. Idempotente. */
+declare function closeGuidePreview(): void;
+
+export { type PreviewGuideInput as P, type PreviewHandle as a, type PreviewResult as b, closeGuidePreview as c, previewGuide as p };

package/dist/guide-preview-CO5ShtNf.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Tipos consumidos por el plugin de guides. Reflejan el shape que devuelve
+ * `GET /v1/guides/resolve` en el backend — debe mantenerse en sync con
+ * `veo-backend/src/modules/guides/types/guide-content.types.ts` y
+ * `guide.response.ts`.
+ */
+type GuideType = 'modal' | 'banner' | 'tooltip' | 'walkthrough' | 'custom' | 'inline' | 'inline-custom' | 'form' | 'inline-form';
+type FormFieldType = 'text' | 'textarea' | 'number' | 'select' | 'multiselect' | 'radio' | 'checkbox' | 'yesno' | 'nps' | 'rating';
+/**
+ * Un campo de una guía `form`. `key` es el nombre de la PROPIEDAD que se
+ * escribe en los traits del usuario que responde (encuesta/NPS estilo Pendo).
+ */
+interface FormField {
+    key: string;
+    label: string;
+    type: FormFieldType;
+    /** Para select/radio: opciones visibles (el valor guardado es el texto). */
+    options?: string[] | null;
+    required?: boolean | null;
+    placeholder?: string | null;
+}
+type CustomPlacementMode = 'floating' | 'anchored';
+type CustomFloatingPosition = 'top-left' | 'top-center' | 'top-right' | 'center' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+type CustomAnchorSide = 'top' | 'bottom' | 'left' | 'right';
+/** Dónde se monta una guía `custom`. Ver backend `guide-content.types.ts`. */
+interface CustomPlacement {
+    mode: CustomPlacementMode;
+    position?: CustomFloatingPosition;
+    offsetX?: number;
+    offsetY?: number;
+    selector?: string;
+    side?: CustomAnchorSide;
+    width?: number | string;
+    height?: number | string;
+}
+type UrlMatchType = 'exact' | 'prefix' | 'regex';
+type ActivationTrigger = 'immediate' | 'on_element' | 'on_event' | 'delayed';
+type CtaAction = 'dismiss' | 'next' | 'url';
+interface UrlMatcher {
+    type: UrlMatchType;
+    pattern: string;
+}
+interface ActivationRules {
+    url: UrlMatcher;
+    trigger: ActivationTrigger;
+    selector?: string;
+    eventName?: string;
+    delayMs?: number;
+}
+interface GuideStep {
+    title: string;
+    content: string;
+    ctaText?: string | null;
+    ctaAction?: CtaAction | null;
+    imageUrl?: string | null;
+    selector?: string | null;
+    /**
+     * Free-form JSONB. Convención: si `ctaAction === 'url'`, la URL destino
+     * se lee de `style.ctaUrl`. Otras keys que puede traer: `position`
+     * (`top` | `bottom` para banners), `theme`.
+     */
+    style?: Record<string, unknown> | null;
+    /** Solo guías `custom`: código a renderizar en un iframe sandbox + ubicación. */
+    html?: string | null;
+    css?: string | null;
+    js?: string | null;
+    placement?: CustomPlacement | null;
+    /** Solo guías `form`: los campos del formulario. */
+    fields?: FormField[] | null;
+}
+
+/** Entrada mínima para previsualizar una guía. */
+interface PreviewGuideInput {
+    guideType: GuideType;
+    guideSteps: GuideStep[];
+    /**
+     * Opcional. Solo se usa `activationRules.selector` como fallback del
+     * ancla para tooltip/walkthrough cuando el step no trae su propio
+     * `selector`. El resto de reglas (url/trigger/delay) se ignoran.
+     */
+    activationRules?: Partial<ActivationRules>;
+    /** Nombre mostrado (p.ej. en el `title` del iframe de guías `custom`). */
+    guideName?: string;
+    /**
+     * Solo walkthrough: paso inicial a mostrar (default 0). Lo usa el editor del
+     * dashboard para que la preview salte al paso que se está editando.
+     */
+    startStepIndex?: number;
+    /**
+     * Solo guías form: envío REAL de respuestas. Sin esto, el submit en preview
+     * 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>;
+    /** Nota bajo el "¡Gracias!" cuando hay `formSubmit` propio. */
+    formSubmitNote?: string;
+}
+/** Resultado del primer render de una preview. */
+interface PreviewResult {
+    /**
+     * `false` cuando la guía no pudo pintarse — típicamente un
+     * tooltip/walkthrough cuyo `selector` no existe en la página de preview.
+     */
+    rendered: boolean;
+}
+/** Handle de una preview activa. */
+interface PreviewHandle {
+    /** Cierra y limpia la preview. Idempotente. */
+    close(): void;
+    /** Resuelve cuando el primer render terminó. */
+    ready: Promise<PreviewResult>;
+}
+/**
+ * Previsualiza una guía en la página actual usando los renderers reales
+ * del SDK. Devuelve un handle con `close()` y una promesa `ready`.
+ *
+ * Pensado para el builder no-code: no necesita `init()` ni apiKey. Abrir
+ * una nueva preview cierra automáticamente la anterior.
+ *
+ * @example
+ * ```ts
+ * import { previewGuide } from '@veo/sdk';
+ *
+ * const preview = previewGuide({
+ *   guideType: 'modal',
+ *   guideSteps: [{ title: 'Hola', content: 'Esto es una preview' }],
+ * });
+ * const { rendered } = await preview.ready;
+ * // ...más tarde:
+ * preview.close();
+ * ```
+ */
+declare function previewGuide(input: PreviewGuideInput): PreviewHandle;
+/** Cierra la preview activa, si la hay. Idempotente. */
+declare function closeGuidePreview(): void;
+
+export { type PreviewGuideInput as P, type PreviewHandle as a, type PreviewResult as b, closeGuidePreview as c, previewGuide as p };