Migración al contrato v1.6 — prompt para Claude Code

Este fichero contiene un prompt listo para ejecutar que migra automáticamente tu integración con la API de Tarno (api.tarno.cl) al contrato v1.6. Está pensado para que tú, consumidor de la API, lo pegues en Claude Code (u otro agente) abierto en tu propio repositorio de integración.

Cómo usarlo

1. Abre Claude Code en la raíz del repositorio donde consumes la API de Tarno (REST api.tarno.cl y/o el servidor MCP).
2. Copia todo el bloque de abajo (entre las líneas ─────) y pégalo como mensaje.
3. Revisa el diff que proponga, corre tus tests y haz commit.

Nada se rompe hoy: los parámetros viejos siguen funcionando hasta que Tarno active el flag estricto (te avisaremos con ≥90 días). Este prompt te deja por delante de esa fecha. Los cambios de comportamiento (nuevo 429, ranking de similares) sí están activos ya.

---

Eres un ingeniero migrando la integración de ESTE repositorio con la API de marcas de Tarno
(REST base `https://api.tarno.cl`, contrato `/v1`, y/o el servidor MCP de Tarno) al contrato v1.6.

OBJETIVO: dejar el código preparado para el contrato v1.6 SIN cambiar la lógica de negocio, solo los
nombres de parámetros deprecados y el manejo de dos cambios de comportamiento. Es aditivo y seguro.

PASO 1 — LOCALIZAR. Busca en todo el repo los puntos donde se llama a la API de Tarno:
  - Peticiones HTTP a `api.tarno.cl` o a rutas `/v1/brands`, `/v1/brands/similar`, `/v1/insights/*`,
    `/v1/oppositions/*`, `/v1/watch*`, `/v1/freshness`, `/v1/sync-runs`.
  - Llamadas a herramientas MCP de Tarno: `search_brands`, `find_similar_brands`, los `insights_*`,
    `get_open_oppositions`, `get_brand_*`, `watch_*`.
  - Cabeceras de API key (`x-api-key`) y construcción de query-strings / cuerpos JSON.
Lista los ficheros y líneas encontrados antes de tocar nada.

PASO 2 — RENOMBRAR PARÁMETROS DEPRECADOS (cambios que romperán cuando Tarno active el modo estricto;
migrar AHORA para estar a salvo). Aplica SOLO donde uses estos parámetros:

  (BR-1) En `GET /v1/brands` y en el tool MCP `search_brands`:
         `denominacion`  →  `nombre`
         (Son equivalentes: buscan por el nombre de la marca. `nombre` es el canónico. NO toques `q`,
          que es la búsqueda general de todos los campos — es un parámetro distinto y se mantiene.)

  (BR-2) En `GET /v1/brands`:
         `fechaDesde`  →  `fechaPresentacionDesde`
         `fechaHasta`  →  `fechaPresentacionHasta`

  (BR-3) En las 5 agregaciones `GET /v1/insights/*` (filings-over-time, by-estado, by-class,
         by-holder, by-representante) y sus tools MCP `insights_*`:
         `fechaDesde`  →  `fechaPresentacionDesde`
         `fechaHasta`  →  `fechaPresentacionHasta`

  NOTA: en `GET /v1/brands/similar` y `GET /v1/oppositions/open` los parámetros `fechaDesde`/`fechaHasta`
  se MANTIENEN (no tienen equivalente canónico todavía). No los renombres ahí.

PASO 3 — VOCABULARIO DE `estado` (BR-4). Si envías el parámetro `estado` (en `/v1/brands` como array o
  en `/v1/insights/*` como escalar), asegúrate de que TODO valor pertenece a este vocabulario cerrado de
  14 códigos (con el modo estricto, un valor fuera devuelve `400 validation_error`):
    abandonada, anulada, caducado, concedida, denegada, desistida, en_tramite,
    esperando_renovacion, observacion_de_fondo, oposicion, publicada, rechazada,
    registrada, vencida
  Corrige cualquier literal de estado que no esté en la lista (p.ej. mayúsculas, sinónimos, typos).

PASO 4 — MANEJO DEL NUEVO 429 (cambio de comportamiento, YA activo). La API ahora aplica un límite de
  ráfaga por API-key (además del límite por IP). Cuando se supera, responde:
    HTTP 429, cuerpo `{ "error": { "code": "rate_limited", ... } }`, cabecera `Retry-After` (segundos).
  Es DISTINTO del `429 quota_exceeded` (cuota mensual). Asegúrate de que tu cliente:
    - Reintenta con backoff respetando `Retry-After` en ambos casos de 429.
    - No trata `rate_limited` como un error fatal permanente.
  Si ya manejas 429 genéricamente con Retry-After, no hay nada que cambiar; solo verifícalo.

PASO 5 — RANKING DE SIMILARES (cambio de comportamiento, YA activo, SIN cambio de código). El orden de
  resultados de `find_similar_brands` / `GET /v1/brands/similar` se ha afinado (motor BM25). El esquema
  de respuesta es idéntico. Si tienes tests que fijan un ORDEN EXACTO de resultados de similares,
  re-baselínalos conscientemente; si solo compruebas que hay resultados o campos, no toques nada.

PASO 6 — VERIFICAR. Corre los tests/typecheck del repo. Revisa que:
    - No queda ningún `denominacion`, `fechaDesde` ni `fechaHasta` en llamadas a `/v1/brands` o
      `/v1/insights/*` (sí pueden quedar en /similar y /oppositions/open).
    - Los valores de `estado` están en el vocabulario.
    - El manejo de 429 respeta `Retry-After`.

PASO 7 — RESUMEN. Devuelve una tabla de ficheros cambiados con el mapeo aplicado por línea, y una lista
  de puntos que requieran decisión humana (p.ej. un `estado` ambiguo, o un test de orden de similares).

RESTRICCIONES: no cambies la lógica de negocio ni añadas dependencias; cambios mínimos y mecánicos;
no toques `q`, ni los `fechaDesde/Hasta` de /similar y /oppositions/open. No inventes endpoints ni
parámetros que no uses ya.

---

Referencia rápida (para revisión humana)

Cambio	Antes	Ahora (canónico)	Dónde	Tipo
BR-1	denominacion	nombre	/v1/brands, search_brands	rompe con flag ON
BR-2	fechaDesde/fechaHasta	fechaPresentacionDesde/Hasta	/v1/brands	rompe con flag ON
BR-3	fechaDesde/fechaHasta	fechaPresentacionDesde/Hasta	/v1/insights/*	rompe con flag ON
BR-4	estado libre	estado ∈ 14 códigos	/v1/brands, /v1/insights/*	rompe con flag ON
BEH	—	429 rate_limited + Retry-After	todo	activo ya
BEH	—	ranking similares afinado (BM25)	/similar	activo ya

Guía completa (no-prompt): migracion-v1.6.md.