Développeurs d'intégrations : mettez à jour pour Gladys 4.86 (SDK 0.12.0 + catégories du store) 🚀

Développement
1

Gladys 4.86 est sortie, et elle apporte deux nouveautés qui concernent directement vos intégrations. La mise à jour prend 5 minutes avec Claude Code — le prompt est en bas de ce post :wink:

1. Le store a maintenant des catégories :card_index_dividers:

Le catalogue des intégrations gagne une navigation par catégories, des filtres, et un tri « Plus récentes ». Pour que votre intégration apparaisse dans les bons rayons, il faut déclarer un nouveau champ categories dans votre gladys-assistant-integration.json :

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

Les règles :

  • 1 à 3 catégories, parmi le vocabulaire officiel : climate, lighting, energy, security, multimedia, appliances, environment, protocols, network, notifications, assistants, services.
  • gladys_version doit passer à ">=4.86.0" dès que vous déclarez le champ : les versions plus anciennes de Gladys rejettent tout champ inconnu dans le manifeste, donc le validateur du store refuse un manifeste qui déclare categories avec un minimum plus bas. Les deux vont ensemble.
  • Sans le champ, votre intégration reste visible sous « Toutes » et dans la recherche, mais elle n’apparaît sur aucun rayon.

Les intégrations existantes ont été catégorisées une première fois via un fichier de correspondance côté store, mais c’est votre manifeste qui fait foi dès que vous déclarez le champ — c’est l’occasion de vérifier que les catégories vous conviennent (et de les ajuster si non !).

2. SDK 0.12.0 :package:

La version 0.12.0 du SDK JavaScript est purement additive (aucun changement cassant, le bump est sans risque) et apporte :

  • Contrôle PTZ des caméras : les features move / preset / positions absolues pour piloter les caméras motorisées ;
  • Wake-on-LAN : gladys.wakeOnLan(mac) + le champ network_wake du manifeste — le core émet le magic packet depuis le réseau de l’hôte (le conteneur en bridge ne peut pas broadcaster sur le LAN) ;
  • Champ de config account_link : le bouton « Connecter » pour les fournisseurs qui ne redirigent jamais vers Gladys (connexion par QR code validée dans l’app du fabricant, style Xiaomi Home) ;
  • Type select dynamique (catégorie text) : une liste de choix découverte sur l’appareil lui-même (apps d’une TV, pièces d’un aspirateur, scènes natives…) déclarée via supported_options ;
  • Nouvelles catégories d’appareils : grid-sensor (échange avec le réseau électrique), home-output-sensor (sortie d’un onduleur/batterie), maintenance (consommables : brosses, sacs, filtres…), et les capteurs de gaz no2 / o3 / so2 — de quoi mieux couvrir le solaire, les batteries et les aspirateurs robots.

Si votre intégration touche à l’énergie, aux caméras ou à l’électroménager, il y a sûrement une nouveauté pour vous là-dedans.

Comment mettre à jour ? Demandez à Claude :robot:

Vos intégrations ont toutes été développées avec Claude Code — la mise à jour se fait pareil. Ouvrez Claude Code dans le dépôt de votre intégration et collez ce prompt :

Mets à jour mon intégration Gladys pour la 4.86 :

1. Passe @gladysassistant/integration-sdk en ^0.12.0 (changements purement
   additifs, rien à adapter dans le code existant).
2. Ajoute le champ `categories` dans gladys-assistant-integration.json :
   1 à 3 valeurs parmi climate, lighting, energy, security, multimedia,
   appliances, environment, protocols, network, notifications, assistants,
   services — choisis celles qui correspondent à ce que fait l'intégration.
3. Passe `gladys_version` à ">=4.86.0" (obligatoire dès qu'on déclare
   `categories`).
4. Vérifie que tout passe : format, lint, tests, puis le validateur du
   store en local : npx github:GladysAssistant/integration-store .

Le template officiel a déjà fait cette mise à jour, inspire-toi de ses
deux dernières PRs : https://github.com/GladysAssistant/integration-template-js

Ensuite, relisez le diff, lancez une release comme d’habitude (workflow Release sur GitHub), et l’indexeur du store récupère la nouvelle version dans l’heure.

Le template officiel vient de passer les deux mises à jour (PRs #14 et #15) : elles servent de référence si vous voulez voir le diff exact.

Des questions sur la migration ? C’est le fil pour ça :backhand_index_pointing_down:

2

Ne faut-il pas attendre 24h que les instances soient à jour afin d’éviter de publier une intégration qui ne serait pas (encore) compatible ?

Les utilisateurs risquent-ils de se retrouver avec une mise à jour bloquante ?

3

Bonne question, mais non, le mécanisme a été pensé pour ça, il n’y a pas de scénario bloquant :

  1. Aucune mise à jour d’intégration n’est automatique : c’est toujours un clic explicite de l’admin. Publier ne déclenche rien tout seul sur les instances.

  2. Sur une instance < 4.86, une nouvelle installation est bloquée proprement : le catalogue compare la version de Gladys au gladys_version du manifeste, le bouton Installer est désactivé avec un message « nécessite Gladys ≥ 4.86 ». Rien ne casse.

  3. Pour une intégration déjà installée sur une < 4.86, si l’utilisateur clique « Mettre à jour » : l’ancienne version de Gladys rejette le nouveau manifeste (champ categories inconnu pour elle), l’écarte silencieusement, et retombe sur le manifeste déjà installé. Elle re-pull simplement l’image actuelle, et l’utilisateur reste sur sa version qui fonctionne, sans erreur ni état cassé. C’est d’ailleurs exactement pour transformer une erreur cryptique en simple filtre de compatibilité que le validateur du store impose gladys_version >= 4.86.0 dès qu’on déclare categories.

Le seul effet de bord est cosmétique : sur une instance pas encore à jour, le badge « mise à jour disponible » peut s’afficher alors que la mise à jour ne sera réellement prise qu’après le passage en 4.86. Si vous voulez éviter ça à vos utilisateurs, attendre un jour ou deux que le gros des instances soit passé en 4.86 est une gentillesse, mais ce n’est pas une question de sécurité : au pire, ils restent sur la version actuelle jusqu’à leur mise à jour de Gladys, et tout se recale tout seul ensuite.

4

Me voilà entièrement rassuré :wink:

Édit : Fait ! Depuis mon jacuzzi :sweat_smile: