Integration developers: update for Gladys 4.86 (SDK 0.12.0 + store categories) 🚀

Development
1

Gladys 4.86 is out, and it brings two new features that directly concern your integrations. The update takes 5 minutes with Claude Code — the prompt is at the bottom of this post :wink:

1. The store now has categories :card_index_dividers:

The integrations catalog now has category navigation, filters, and a « Most recent Â» sort. To have your integration appear in the right sections, you need to declare a new categories field in your gladys-assistant-integration.json:

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

The rules:

  • 1 to 3 categories, from the official vocabulary: climate, lighting, energy, security, multimedia, appliances, environment, protocols, network, notifications, assistants, services.
  • gladys_version must be set to ">=4.86.0" as soon as you declare the field: older versions of Gladys reject any unknown field in the manifest, so the store validator refuses a manifest that declares categories with a lower minimum. Both go together.
  • Without the field, your integration remains visible under « All Â» and in search, but it doesn’t appear in any section.

Existing integrations have been categorized for the first time via a mapping file on the store side, but your manifest takes precedence as soon as you declare the field — this is a good opportunity to check that the categories suit you (and adjust them if not!).

2. SDK 0.12.0 :package:

Version 0.12.0 of the JavaScript SDK is purely additive (no breaking changes, the bump is risk-free) and brings:

  • PTZ camera control: move / preset / absolute positions features to control motorized cameras;
  • Wake-on-LAN: gladys.wakeOnLan(mac) + the network_wake field in the manifest — the core sends the magic packet from the host’s network (the container in bridge mode cannot broadcast on the LAN);
  • account_link config field: the « Connect Â» button for providers that never redirect to Gladys (connection via QR code validated in the manufacturer’s app, like Xiaomi Home);
  • Dynamic select type (category text): a list of choices discovered on the device itself (TV apps, vacuum cleaner rooms, native scenes
) declared via supported_options;
  • New device categories: grid-sensor (electricity network exchange), home-output-sensor (output from an inverter/battery), maintenance (consumables: brushes, bags, filters
), and gas sensors no2 / o3 / so2 — to better cover solar, batteries, and robot vacuums.

If your integration deals with energy, cameras, or home appliances, there’s surely a new feature for you in there.

How to update? Ask Claude :robot:

All your integrations were developed with Claude Code — the update is done the same way. Open Claude Code in your integration’s repository and paste this prompt:

Update my Gladys integration for 4.86:

1. Update @gladysassistant/integration-sdk to ^0.12.0 (purely
   additive changes, nothing to adapt in the existing code).
2. Add the `categories` field in gladys-assistant-integration.json:
   1 to 3 values from climate, lighting, energy, security, multimedia,
   appliances, environment, protocols, network, notifications, assistants,
   services — choose those that match what the integration does.
3. Set `gladys_version` to ">=4.86.0" (required as soon as we declare
   `categories`).
4. Check that everything passes: format, lint, tests, then the store
   validator locally: npx github:GladysAssistant/integration-store .

The official template has already made this update, take inspiration from its
last two PRs: https://github.com/GladysAssistant/integration-template-js

Then review the diff, launch a release as usual (workflow Release on GitHub), and the store indexer picks up the new version within the hour.

The official template just went through both updates (PRs #14 and #15): they serve as a reference if you want to see the exact diff.

Questions about the migration? This is the thread for that :backhand_index_pointing_down:

2

Shouldn’t we wait 24 hours for the instances to be updated to avoid publishing an integration that might not (yet) be compatible?

Are users at risk of ending up with a blocking update?

3

Good question, but no, the mechanism was designed for this, there is no blocking scenario:

  1. No integration update is automatic: it’s always an explicit click from the admin. Publishing does not trigger anything on its own on the instances.

  2. On an instance < 4.86, a new installation is properly blocked: the catalog compares the Gladys version to the gladys_version of the manifest, the Install button is disabled with a message « requires Gladys ≄ 4.86 Â». Nothing breaks.

  3. For an integration already installed on a < 4.86, if the user clicks « Update Â»: the old version of Gladys rejects the new manifest (unknown categories field for it), silently discards it, and falls back to the already installed manifest. It simply re-pulls the current image, and the user stays on their working version, without errors or broken state. This is exactly to turn a cryptic error into a simple compatibility filter that the store validator enforces gladys_version >= 4.86.0 as soon as you declare categories.

The only side effect is cosmetic: on an instance not yet updated, the « update available Â» badge may appear even though the update will only be taken after the move to 4.86. If you want to avoid this for your users, waiting a day or two for most instances to move to 4.86 is a kindness, but it’s not a security issue: at worst, they stay on the current version until their Gladys update, and everything realigns itself afterwards.

4

I am now completely reassured :wink:

Edit: Done! From my jacuzzi :sweat_smile: