Migrar a la 5.0

De component-limbo 4.x (API legacy) a 5.0.0 (/api/v1), paso a paso. Limbo.configure() no cambia; lo que cambia es la clave, sus scopes y de dónde se carga el componente.

Antes de empezar

Los dos canales conviven: la 4.x sigue en /cdn/component-limbo/ y la 5.x vive en /cdnv1/component-limbo/, así que migrar es cambiar una URL (o un paquete) cuando tu clave esté lista, no una actualización forzada. Las versiones y la caché de cada canal están en Instalación.

1. La clave y sus scopes

  • Usa la pk_ de una API key. La clave pública del portal, que la legacy aceptaba, da 401 invalid_credentials en v1. Si hoy usas la del portal, crea o localiza una API key y pon su pk_ en publicKey.
  • La key necesita los scopes de las pestañas que uses. La v1 exige además folder:read, folder:write y external:read, que la legacy no pedía. Sin el scope de una pestaña, esa pestaña recibe 403 Missing required scope: ….
Función del componenteScopes de la key
Galería, subida, edición y borrado de assets; etiquetasasset:read, asset:write, asset:delete
Recortes y variantesvariant:read, variant:write, variant:delete
Carpetasfolder:read, folder:write
Portales externosexternal:read
Imágenes y vídeo con IAai:read, ai:generate
Banco de imágenes (stock)stock:search, stock:download

Pide solo los de las pestañas que uses. Un administrador concede un scope a una key con php bin/console limbo:grant-scope <api-key-id> <scope>.

2. El token desde tu backend

Con authMode: 'jwt' y un tokenProvider, cambia la petición de tu backend de POST /auth/token a POST /api/v1/auth/token con { "public_key": "pk_de_la_api_key" }, y lee el token de data.token (la v1 envuelve la respuesta en { success, data }). El código completo está en la receta.

El sk_ no hace falta para el componente (solo para emitir portal:admin) y nunca debe llegar al navegador: con una cabecera Origin da 403 sk_not_allowed_from_browser. Los detalles del token y de sus 403 están en Migrar a v1.

Con authMode: 'session' no tocas nada en tu backend: si la pk_ sigue siendo la del portal, el componente obtiene el token con un único reintento contra la legacy y lo avisa por consola con console.warn. Es un puente hasta que cambies la clave, no una configuración final: la ruta legacy tiene fecha de retirada.

3. Cambiar la URL o el paquete

HTML 
<!-- Antes (4.x, API legacy) -->
<link rel="stylesheet" href="https://limbo.lefebvre.es/cdn/component-limbo/latest/limbo.css">
<script src="https://limbo.lefebvre.es/cdn/component-limbo/latest/limbo.min.js"></script>

<!-- Ahora (5.x, /api/v1), versión exacta -->
<link rel="stylesheet" href="https://limbo.lefebvre.es/cdnv1/component-limbo/v5.0.0/limbo.css">
<script src="https://limbo.lefebvre.es/cdnv1/component-limbo/v5.0.0/limbo.min.js"></script>

Con npm: cambia la dependencia limbo-component por limbo-component-v5 (npm install limbo-component-v5, o "limbo-component-v5": "^5.0.0" en package.json) y los imports a 'limbo-component-v5' y 'limbo-component-v5/css'. limbo-component se queda en la 4.x. En ESM y CommonJS el componente no empaqueta React, React DOM ni cropperjs: tu aplicación aporta los dos primeros (18 o superior) y npm instala el tercero.

4. Qué cambia para ti

  • Errores. La API responde application/problem+json; el componente lo entiende y los mensajes que muestra salen de ahí. Si interceptas las peticiones, el formato de error es el de Migrar a v1.
  • Proxies firmados. Las miniaturas de portales externos, stock e IA pasan por POST /api/v1/proxy/sign y GET /api/v1/proxy, sin credenciales en el fetch. No configuras nada más que el scope; si bloqueas esas rutas en un proxy o en la CSP, ábrelas (detalle).
  • apiBaseUrl. Opción nueva de Limbo.configure(): URL absoluta http(s), sin barra final, de otra instancia de la API (un entorno de pruebas). Manda sobre prod; un valor no válido lanza un error de configuración.
  • Vídeo con IA. Un parámetro no declarado por el modelo, disabled o de tipo array no se pinta ni se envía.
JavaScript 
Limbo.configure({
  publicKey: 'pk_de_la_api_key',
  prod: false,
  apiBaseUrl: 'https://tu-entorno-de-pruebas.example'   // opcional
});

5. Comprobar en PRE

Con prod: false, abre el selector y recorre las pestañas que uses (galería, subida, recorte, carpetas, externos, IA, stock). La consola del navegador debe quedar sin el aviso de reintento legacy y sin 401 ni 403; cada 403 Missing required scope nombra el scope que falta en la key.

6. Volver atrás

Restaura la URL (o la versión de npm) y la clave que usabas: el canal legacy sigue sirviendo la 4.x contra /api/*. Es la única acción necesaria; no hay nada que revertir en la API.