Referencia de tipos

Referencia exhaustiva de todas las interfaces y tipos públicos del SDK. Los tipos se exportan desde @vto/core.

---

InitOptions

Parámetros de OBVto.init().

campo	tipo	default	descripción
modules	string[]	—	Módulos a activar, p.ej. ['hair-color']. Requerido.
licenseKey	string?	undefined	Clave de licencia para modo prod. Sin ella el SDK corre en modo dev permisivo.
configEndpoint	string?	undefined	URL del endpoint que devuelve LicenseConfig (GET ?key=).
licenseProvider	LicenseProvider?	undefined	Provider explícito (mockeable); tiene prioridad sobre configEndpoint.
container	string | HTMLElement | undefined	undefined	Selector CSS o elemento donde montar el visor. Sin él se usa overlay.
moduleConfig	Record<string, Record<string, unknown>>?	undefined	Opciones por módulo, pasadas a la factory de cada uno.
experience	ExperienceConfig?	undefined	Config de la pantalla de inicio (selector de experiencias, HU7). Sin este campo init es headless.
start	StartOptions?	undefined	Opciones de arranque automático al elegir modo en el selector de inicio.

---

StartOptions

Parámetros de OBVto.start() (o del campo start en InitOptions).

campo	tipo	default	descripción
module	string	—	Módulo a arrancar, p.ej. 'hair-color'. Requerido.
colors	Color[]	—	Paleta de tonos disponibles. Requerido.
source	'camera' | 'photo'	'camera'	Fuente de imagen: cámara en vivo o foto subida.
image	HTMLImageElement?	undefined	Imagen requerida cuando source === 'photo'.
defaultIntensity	number?	0.7	Intensidad inicial del efecto (0–1).
ui	ViewerUIConfig?	undefined	Si está presente, el SDK monta el chrome del visor. Sin él el modo es headless.
nps	NpsConfig?	undefined	Si está, el cierre muestra el formulario NPS antes del mensaje de gracias.
thanks	ThanksConfig | false | undefined	undefined	Mensaje de gracias al cerrar. false cierra de inmediato sin overlay.
products	Record<string, Product>?	undefined	Mapa estático { [colorId]: Product } para la card por tono.
resolveProduct	(color: Color) => Product | null | undefined | Promise<...>?	undefined	Resolución dinámica del producto por tono (prioridad sobre products y color.product).
palette	ShadeGroup[]?	undefined	Familias de tonos en 2 niveles (nivel 1 = grupo, nivel 2 = shades). Si está, el SDK monta el selector acordeón.
resolveShades	(group: ShadeGroup) => Color[] | Promise<Color[]>?	undefined	Carga on-demand de sub-tonos de un grupo (API del cliente).
favoritesStorageKey	string?	'vto:favorites'	Clave de localStorage para persistir favoritos. Cadena vacía o null desactiva la persistencia.
initialFavorites	Product[]?	undefined	Semilla de favoritos desde la API del cliente, usada si localStorage está vacío.
onReady	() => void?	undefined	El visor está listo y procesando frames.
onError	(err: Error) => void?	undefined	Error durante el arranque o el procesamiento.
onCapture	(dataUrl: string) => void?	undefined	El usuario capturó una foto; recibe el data URL en base64.
onAddToCart	(color: Color) => void?	undefined	El usuario pulsó "Añadir al carrito".
onClose	() => void?	undefined	El usuario cerró el visor (botón ✕ o flujo de cierre completo).
onHome	() => void?	undefined	El usuario pulsó el botón de inicio (HU6).
onProductClick	(p: Product) => void?	undefined	El usuario pulsó "VER EL PRODUCTO" en la card.
onFavorite	(p: Product) => void?	undefined	El usuario añadió un producto a favoritos.
onUnfavorite	(p: Product) => void?	undefined	El usuario quitó un producto de favoritos.
onNps	(result: NpsResult) => void?	undefined	Reporte de NPS al enviar el formulario (no al omitir).

---

ViewerUIConfig

Config de la capa de UI del visor (barra, card, favoritos, ayuda, NPS).

campo	tipo	default	descripción
branding	ViewerBranding?	undefined	Marca y colores del visor.
product	Product?	undefined	Producto del tono inicial (antes de que el usuario elija).
controls	ViewerControls?	undefined	Visibilidad de controles de la barra. Sin este campo todos son visibles.

---

ViewerBranding

Personalización visual del SDK. Aplica a la pantalla de inicio y al visor.

campo	tipo	default	descripción
name	string?	'VTO'	Nombre de marca mostrado.
logoSvg	string?	undefined	Markup SVG del logo (pantalla de inicio, HU7).
primaryColor	string?	undefined	Color de CTAs y acentos (variable CSS --vto-primary).

---

ViewerControls

Visibilidad de cada botón de la barra del visor. Omitir un campo o pasar true lo muestra; false lo oculta.

campo	tipo	default	descripción
home	boolean?	true	Botón de inicio (volver al selector de experiencias).
help	boolean?	true	Botón de ayuda.
compare	boolean?	true	Botón de comparación antes/después.
download	boolean?	true	Botón de descarga de captura.
favorites	boolean?	true	Botón de favoritos.
close	boolean?	true	Botón de cierre (✕).

---

ExperienceConfig

Config de la pantalla de inicio (selector de experiencias). Pasada en InitOptions.experience.

campo	tipo	default	descripción
branding	ViewerBranding?	undefined	Logo, marca y color primario del selector de inicio.
tagline	string?	'Prueba tu color'	Subtítulo mostrado bajo el logo.
modes	ExperienceMode[]?	['selfie', 'photo']	Modos visibles en el selector.

ExperienceMode

type ExperienceMode = 'selfie' | 'photo'

valor	descripción
'selfie'	Usa la cámara del dispositivo en tiempo real.
'photo'	El usuario sube o elige una foto.

---

Color

Un tono de la paleta de colores.

Nota sobre HSL: el campo h usa el rango CSS estándar 0–360 (no 0–100 como indica el comentario en el código fuente, que es un bug pre-existente). Los campos s y l usan 0–100.

campo	tipo	default	descripción
id	string	—	Identificador único del tono. Requerido.
name	string	—	Nombre legible del tono. Requerido.
h	number	—	Matiz HSL, rango 0–360. Requerido.
s	number	—	Saturación HSL, rango 0–100. Requerido.
l	number	—	Luminosidad HSL, rango 0–100. Requerido.
sku	string?	undefined	SKU del producto asociado (clave de favorito).
product	Product?	undefined	Producto asociado a este tono (card + favoritos). Menor prioridad que products[id] y resolveProduct.
swatchImageUrl	string?	undefined	URL de imagen para el swatch. Si falta, se dibuja un círculo con el color HSL.

---

Product

Producto asociado a un tono activo (card del visor + favoritos).

campo	tipo	default	descripción
name	string	—	Nombre del producto, p.ej. 'NUTRISSE COLORISSIMO'. Requerido.
tone	string?	undefined	Descripción del tono, p.ej. '6646 Cobrizo Rubí'.
imageUrl	string?	undefined	URL de la miniatura del producto.
url	string?	undefined	URL de destino del enlace "VER EL PRODUCTO".
sku	string?	undefined	SKU del producto.

---

ShadeGroup

Grupo de tonos en 2 niveles (estilo Garnier). El nivel 1 es el grupo (familia); el nivel 2 son los sub-tonos (shades).

campo	tipo	default	descripción
id	string	—	Identificador único del grupo. Requerido.
name	string	—	Nombre del grupo, p.ej. 'Rubio'. Requerido.
swatch	{ h: number; s: number; l: number }?	undefined	Color raíz del grupo. Si falta, se usa el primer shade.
swatchImageUrl	string?	undefined	Imagen raíz del grupo (tiene prioridad visual sobre swatch).
shades	Color[]?	undefined	Sub-tonos del grupo. Puede omitirse si se cargan por API con resolveShades.
product	Product?	undefined	Producto del color principal (para grupos sin sub-tonos: el color se aplica y favorita directo).
sku	string?	undefined	SKU del color principal (clave de favorito para grupos sin sub-tonos).

---

NpsConfig

Config del formulario NPS que se muestra al cerrar el visor (si se pasa nps en StartOptions).

campo	tipo	default	descripción
question	string?	'¿Qué tan probable es que nos recomiendes?'	Pregunta principal del formulario.
min	number?	0	Valor mínimo de la escala.
max	number?	10	Valor máximo de la escala.
minLabel	string?	''	Etiqueta del extremo bajo. Cadena vacía = no se muestra.
maxLabel	string?	''	Etiqueta del extremo alto. Cadena vacía = no se muestra.
comment	boolean?	false	Si true, muestra un campo de comentario opcional.
commentLabel	string?	'Cuéntanos más (opcional)'	Placeholder del campo de comentario.
submitLabel	string?	'Enviar'	Etiqueta del botón de envío.
skipLabel	string?	'Omitir'	Etiqueta del botón de omitir.

---

NpsResult

Resultado del formulario NPS reportado vía onNps. Solo se emite cuando el usuario pulsa "Enviar" (no al omitir).

campo	tipo	default	descripción
score	number	—	Puntuación elegida por el usuario. Requerido.
comment	string?	undefined	Comentario del usuario. Presente solo si NpsConfig.comment es true y el usuario escribió algo.

---

ThanksConfig

Mensaje de gracias mostrado al finalizar el flujo de cierre.

campo	tipo	default	descripción
title	string?	'Gracias'	Título del overlay de gracias.
message	string?	'Gracias por probar tu color.'	Cuerpo del mensaje.
doneLabel	string?	'Listo'	Etiqueta del botón de confirmación.

---

LicenseConfig

Configuración resuelta a partir de la licencia (devuelta por el endpoint o el licenseProvider).

campo	tipo	default	descripción
enabledModules	string[]	—	Módulos habilitados. ['*'] habilita todos. Requerido.
watermark	boolean?	undefined	Si true, capture() estampa una marca de agua en la imagen capturada.
branding	{ name?: string; logoUrl?: string }?	undefined	Branding forzado por la licencia: nombre y URL de logo.
colors	Color[]?	undefined	Paleta cerrada de tonos impuesta por la licencia.