v0.5.0

Added

• MQTT on_connect callback (OA3C-9j0). MQTTConnection and MqttChannel now accept an on_connect: Callable[[], None] | None constructor parameter. The callback fires on every successful CONNACK — both the initial connect and every subsequent reconnect — and is plumbed through to ebus_mqtt_client.MqttClient's on_connect_callback. Consumers that need to distinguish first-connect from reconnect must maintain their own counter in the callback body. Motivated by the openadr3-ven-hass OA3V-31n / OA3V-xdr reconnect work (commit 20399d3): without this hook, MQTT consumers can't re-fetch topics or re-snapshot REST state on reconnect.
• MQTT subscription-set management (OA3C-2hz). MQTTConnection now tracks the current subscription set (exposed as subscribed_topics: set[str]) and adds two new methods: unsubscribe(topics) (cleans up ebus_mqtt_client recovery bookkeeping so the topic stays unsubscribed across reconnects) and replace_subscriptions(topics) (applies the minimal subscribe/unsubscribe diff against the current set). Mirrored on MqttChannel as unsubscribe_topics(topics) and replace_topics(topics). Designed to compose with the on_connect callback for reconnect-time topic refresh: re-fetch topics in the callback, then call replace_topics(new) without bouncing the broker connection.
• VenClient.poll_events accepts an explicit date window (OA3C-2q6). New date_start / date_end parameters (pendulum.DateTime | None). When unset, defaults to a sliding window of now - 1 day to now + 4 days in UTC. This is wider than the spec-permitted VTN default of today→tomorrow UTC and prevents the UTC-rollover gap that bit openadr3-ven-hass 0.2.x (OA3V-yny, commit a06402c) — where locally-active events dropped out of the spec-default window after midnight UTC (e.g. after 5pm Pacific). Explicit values are converted to UTC and formatted as ISO 8601 with Z suffix.

Changed

• Breaking (security): MQTT TLS certificate verification is now on by default (OA3C-k5a). New tls_verify: bool = True parameter on MQTTConnection and MqttChannel. Previously tls_insecure=True was hardcoded, silently shipping no-cert-verification against any mqtts:// broker. Consumers using self-signed brokers (e.g. the URPX dev broker) must now explicitly pass tls_verify=False to keep the previous behaviour. For production deployments with valid certificates this change is transparent and security-correct.
• VenClient.poll_events now passes dateStart / dateEnd query params by default (see Added above). Previously called events() with only programID, inheriting whatever date window the VTN defaulted to. The new default window (now - 1d to now + 4d UTC) is opinionated and is wider than the VTN-side default; consumers wanting different windowing should pass explicit date_start / date_end. Consumers wanting no date filter at all can drop down to the underlying client.events(programID=...) (available via BaseClient.__getattr__ delegation).
• subscribe() is now idempotent on already-subscribed topics. Previously each call re-issued the subscription regardless. Behavioural change is benign for consumers that previously relied on the idempotent broker-side semantics; redundant ebus_mqtt_client.subscribe calls are now suppressed.
• NotificationChannel Protocol gained unsubscribe_topics(topics) and replace_topics(topics). WebhookChannel implements both as no-ops (HTTP webhooks are managed via VTN REST subscriptions, not channel-side).
• Dependency floor raised: openadr3>=0.4.0 (OA3C-yrf). openadr3 0.4.0 fixes a payload-type case-mismatch bug where Payload.type was lowercased during coercion while EventPayloadDescriptor.payload_type / ReportPayloadDescriptor.payload_type passed the wire value through unchanged — see the openadr3 0.4.0 CHANGELOG. This repo's own source does not read .type on coerced openadr3 entities (MQTT/webhook payloads are shuttled through as bytes/Any), so no in-repo code change was required. The bump is purely about the dep floor so transitive consumers (e.g. openadr3-ven-hass) pick up the case fix when they pin against python-oa3-client.
• CI: pinned GitHub Actions runtimes updated past the Node.js 20 deprecation. actions/checkout v4.2.2 → v6.0.2, actions/setup-python v5.6.0 → v6.2.0. Both now run on node24 (OA3C-tlh).