Desarrolladores de integraciones: actualicen para Gladys 4.86 (SDK 0.12.0 + categorías de la tienda) 🚀

Desarrollo
1

Gladys 4.86 ha sido lanzado, y trae dos novedades que afectan directamente a tus integraciones. La actualización tarda 5 minutos con Claude Code — el prompt está al final de este post :wink:

1. La tienda ahora tiene categorías :card_index_dividers:

El catálogo de integraciones gana una navegación por categorías, filtros y un orden « Más recientes ». Para que tu integración aparezca en los estantes correctos, debes declarar un nuevo campo categories en tu gladys-assistant-integration.json:

"categories": ["lighting", "energy"],
"gladys_version": ">=4.86.0",

Las reglas:

  • 1 a 3 categorías, entre el vocabulario oficial: climate, lighting, energy, security, multimedia, appliances, environment, protocols, network, notifications, assistants, services.
  • gladys_version debe cambiar a ">=4.86.0" tan pronto como declares el campo: las versiones anteriores de Gladys rechazan cualquier campo desconocido en el manifiesto, por lo que el validador de la tienda rechaza un manifiesto que declara categories con un mínimo más bajo. Las dos van juntas.
  • Sin el campo, tu integración sigue siendo visible bajo « Todas » y en la búsqueda, pero no aparece en ningún estante.

Las integraciones existentes han sido categorizadas por primera vez a través de un archivo de correspondencia en el lado de la tienda, pero es tu manifiesto el que tiene la última palabra tan pronto como declares el campo — es una oportunidad para verificar que las categorías te convienen (¡y ajustarlas si no!).

2. SDK 0.12.0 :package:

La versión 0.12.0 del SDK de JavaScript es puramente aditiva (sin cambios disruptivos, el bump es seguro) y trae:

  • Control PTZ de cámaras: las características move / preset / posiciones absolutas para controlar cámaras motorizadas;
  • Wake-on-LAN: gladys.wakeOnLan(mac) + el campo network_wake del manifiesto — el núcleo emite el paquete mágico desde la red del host (el contenedor en bridge no puede transmitir en el LAN);
  • Campo de configuración account_link: el botón « Conectar » para proveedores que nunca redirigen a Gladys (conexión por código QR validada en la aplicación del fabricante, estilo Xiaomi Home);
  • Tipo select dinámico (categoría text): una lista de opciones descubierta en el propio dispositivo (aplicaciones de una TV, habitaciones de un aspirador, escenas nativas…) declarada a través de supported_options;
  • Nuevas categorías de dispositivos: grid-sensor (intercambio con la red eléctrica), home-output-sensor (salida de un inversor/batería), maintenance (consumibles: cepillos, bolsas, filtros…), y los sensores de gas no2 / o3 / so2 — para cubrir mejor el solar, las baterías y los aspiradores robot.

Si tu integración se relaciona con la energía, las cámaras o los electrodomésticos, hay algo nuevo para ti aquí.

¿Cómo actualizar? Pregúntale a Claude :robot:

Todas tus integraciones se han desarrollado con Claude Code — la actualización se hace igual. Abre Claude Code en el repositorio de tu integración y pega este prompt:

Actualiza mi integración Gladys para la 4.86:

1. Cambia @gladysassistant/integration-sdk a ^0.12.0 (cambios puramente
   aditivos, nada que adaptar en el código existente).
2. Añade el campo `categories` en gladys-assistant-integration.json:
   1 a 3 valores entre climate, lighting, energy, security, multimedia,
   appliances, environment, protocols, network, notifications, assistants,
   services — elige los que correspondan a lo que hace la integración.
3. Cambia `gladys_version` a ">=4.86.0" (obligatorio tan pronto como
   se declara `categories`).
4. Verifica que todo pase: formato, lint, pruebas, luego el validador de
   la tienda en local: npx github:GladysAssistant/integration-store .

El template oficial ya ha realizado esta actualización, inspírate en sus
últimas 2 PRs: https://github.com/GladysAssistant/integration-template-js

Luego, revisa el diff, lanza una versión como de costumbre (flujo de trabajo Release en GitHub), y el indexador de la tienda recupera la nueva versión en una hora.

El template oficial acaba de realizar las dos actualizaciones (PRs #14 y #15): sirven de referencia si quieres ver el diff exacto.

¿Preguntas sobre la migración? Este es el hilo para eso :backhand_index_pointing_down:

2

¿No hay que esperar 24 horas a que las instancias estén actualizadas para evitar publicar una integración que no sea (todavía) compatible?

¿Los usuarios podrían terminar con una actualización bloqueante?

3

Buena pregunta, pero no, el mecanismo está diseñado para eso, no hay ningún escenario bloqueante:

  1. Ninguna actualización de integración es automática: siempre es un clic explícito del administrador. Publicar no desencadena nada solo en las instancias.

  2. En una instancia < 4.86, una nueva instalación está bloqueada correctamente: el catálogo compara la versión de Gladys con el gladys_version del manifiesto, el botón Instalar está desactivado con un mensaje « requiere Gladys ≥ 4.86 ». Nada se rompe.

  3. Para una integración ya instalada en una < 4.86, si el usuario hace clic en « Actualizar »: la versión antigua de Gladys rechaza el nuevo manifiesto (el campo categories es desconocido para ella), lo descarta silenciosamente y vuelve al manifiesto ya instalado. Simplemente vuelve a descargar la imagen actual, y el usuario se queda con su versión que funciona, sin errores ni estado roto. De hecho, es exactamente para transformar un error críptico en un simple filtro de compatibilidad que el validador de la tienda exige gladys_version >= 4.86.0 tan pronto como se declara categories.

El único efecto secundario es estético: en una instancia que aún no se ha actualizado, la insignia « actualización disponible » puede aparecer aunque la actualización solo se aplicará realmente después de la transición a 4.86. Si quieres evitar esto a tus usuarios, esperar un día o dos a que la mayoría de las instancias pasen a 4.86 es un gesto amable, pero no es una cuestión de seguridad: en el peor de los casos, se quedan con la versión actual hasta su actualización de Gladys, y todo se ajusta solo después.

4

¡Ahora estoy completamente tranquilo! :wink:

Edición: ¡Hecho! Desde mi jacuzzi :sweat_smile:

5

Hecho para todas las integraciones que he publicado :slight_smile: