Reference · Modelos de datos

Esta página enumera los DTOs públicos de Neuroon: el contrato que firma el widget contra la API. Los tipos canónicos del widget están en y los del backend en api/src/main/java/.../dto/.

`Product`

Producto tal como lo recibe el widget desde SearchResponse.results[].

Campo	Tipo	Requerido	Notas
`id`	string	sí	UUID Neuroon.
`shopId`	string	sí	UUID del shop.
`shopName`	string	sí	Nombre del shop.
`name`	string	sí	Nombre del producto.
`description`	string	no
`price`	number	sí	Precio regular.
`salePrice`	number	no	Si presente, calcula descuento.
`currency`	string	sí	ISO 4217.
`url`	string	sí	URL final (host).
`imageUrl`	string	no
`categories`	string[]	sí
`tags`	string[]	sí
`brands`	string[]	sí
`inStock`	boolean	sí
`score`	number	no	Score interno de relevancia (debug).
`rating`	number	no	0-5.
`reviewCount`	number	no
`stockCount`	number	no	Si ≤ 5, el widget muestra badge "Pocas unidades".
`externalId`	string	no	ID del host (WC `post_id`, etc.) usado para conversion tracking.
`badge`	enum	no	`BESTSELLER` \| `TRENDING` \| `TOP_RATED`.
`aiReason`	string	no	Razón conversacional ("ideal para asfalto").
`aiScore`	number	no	Score IA del re-ranker.

`SearchResponse`

Respuesta canónica de GET /api/widget/search y POST /api/widget/search. Tipo.

Campo	Tipo	Requerido	Notas
`query`	string	sí	Query normalizada tras post-process.
`results`	Product[]	sí
`total`	number	sí	Total de productos que cumplen filtros.
`searchLogId`	string	sí	Identificador del turno (attribution).
`queryTimeMs`	number	sí	Latencia del backend.
`intentId`	string	no	Detección de intent.
`conversationId`	string	no	Continuación entre turnos.
`isNewConversation`	boolean	no	`true` si arrancó conversación.
`turnNumber`	number	no	1, 2, 3…
`filtersApplied`	FiltersApplied	no	Filtros aplicados al ranking.
`availableFilters`	AvailableFilters	no	Drawer de filtros.
`guidedFilters`	GuidedFilter[]	no	Preguntas dinámicas.
`querySuggestions`	QuerySuggestion[]	no	Refinamientos sugeridos.
`topProducts`	TopProduct[]	no	Carrusel destacado.
`aiResponse`	string	no	Texto conversacional.
`comparison`	ComparisonResponse	no
`clarification`	ClarificationResult	no
`buyersGuide`	BuyersGuide	no
`kit`	ProductKit	no
`followUp`	FollowUpResponse	no
`recommendations`	RecommendationsResponse	no
`cartAction`	CartAction	no	Acción solicitada al widget.
`quickReplies`	QuickReply[]	no	Chips de respuesta rápida.
`responseLanguage`	string	no	ISO del idioma del agente (es, en…).

`CartState`

interface CartState {
  items: CartItem[]
  totalItems: number
  subtotal: string   // formateado por el host: "232,48 €"
  total: string      // formateado por el host
  currency: string   // ISO 4217
  shipping?: CartShippingInfo
}

Campo `CartItem`	Tipo	Requerido	Notas
`key`	string	sí	Identificador único del item en el carrito.
`id`	string	sí	productId Neuroon.
`externalId`	string	no	ID del host (WC `post_id`).
`name`	string	sí
`price`	string	sí	Formateado por el host.
`quantity`	number	sí
`image`	string	no
`url`	string	no
`variant`	string	no	"Talla: 42, Color: Negro".
`maxQuantity`	number	no

CartShippingInfo añade freeShippingThreshold, currentAmount, delta, thresholdMet, destinationCountry, availableCountries[], formattedThreshold y formattedDelta. Ver cart-integration para el flujo.

`Event` (analytics)

Campo	Tipo	Requerido	Notas
`type`	string	sí	snake_case (`category_click`, `kit_view`…).
`searchLogId`	string	recomendado	Vincula con turno de búsqueda.
`metadata`	object	no	Pares libres (sin PII).
`timestamp`	string ISO-8601	no	Si se omite, lo pone el backend.

`CartAction`

type CartActionType = 'REMOVE' | 'UPDATE_QUANTITY' | 'ADD_SUGGESTION' | 'CLEAR' | 'SET_DESTINATION_COUNTRY'

interface CartAction {
  type: CartActionType
  productId?: string
  externalProductId?: string
  externalId?: string             // alias legacy
  itemKey?: string
  newQuantity?: number
  countryCode?: string             // ISO-3166-1 alpha-2 mayúsculas
  confirmationPrompt?: string
  product?: CartActionProduct      // sólo en ADD_SUGGESTION
}

`Suggestion`

interface Suggestion {
  type: 'query' | 'category' | 'brand' | 'product'
  text: string
  count?: number
  icon?: string
  product?: Product
}

`GuidedFilter`

interface GuidedFilter {
  id: string
  question: string
  type: 'SINGLE_CHOICE' | 'MULTI_CHOICE' | 'RANGE'
  priority: number
  options: FilterOptionDTO[]
}

interface FilterOptionDTO {
  label: string
  filter: Record<string, unknown>
  count?: number
  isSelected?: boolean
  isRecommended?: boolean
  detectionSource?: 'QUERY_ANALYSIS' | 'TRENDING' | 'INTENT_BASED'
  detectionReason?: string
}

Product​

SearchResponse​

CartState​

Event (analytics)​

CartAction​

Suggestion​

GuidedFilter​

Próximas lecturas​