feat(octopus): try new Power Down join service, fall back to deprecated one

Bottle Cap Dave's Octopus Energy integration renamed
join_octoplus_saving_session_event to
join_octoplus_power_down_session_event (ADR-0004). Both remain
registered until the old one is retired in January 2027, so try
the new name first and fall back to the old one on failure.

Part of #4548 (point 3). TODO(#4599) tracks removing the fallback
once the old service name is gone upstream.

Author: chalfontchubby

apps/predbat/octopus.py

@@ -2987,11 +2987,21 @@ def fetch_octopus_sessions(self, axle_sessions=None):
                             self.log("Octopus: Joining Octopus saving event code {} {}-{} at rate {} p/kWh".format(code, start_time.strftime("%a %d/%m %H:%M"), end_time.strftime("%H:%M"), saving_rate))
                             entity_id_join = self.get_arg("octopus_saving_session_join", indirect=False)
                             if entity_id_join:
-                                # Join via selector
+                                # Join via selector (Octopus Energy Direct, or any other integration wired
+                                # up this way) - unaffected by which Bottle Cap Dave service name is current
                                 self.call_service_wrapper("select/select_option", entity_id=entity_id_join, option=code)
                             else:
-                                # Join via octopus event (Bottle Cap Dave)
-                                self.call_service_wrapper("octopus_energy/join_octoplus_saving_session_event", event_code=code, entity_id=entity_id)
+                                # Join via Bottle Cap Dave's Octopus Energy HA integration. Try the current
+                                # service name first (join_octoplus_power_down_session_event, which
+                                # superseded join_octoplus_saving_session_event - see the integration's
+                                # ADR-0004), falling back to the old name for anyone on an integration
+                                # version that predates the rename. Both remain registered until the old
+                                # one is removed in January 2027, so this fallback is a temporary bridge,
+                                # not a permanent branch.
+                                # TODO(#4599): remove this fallback once the old service name is retired upstream.
+                                if not self.call_service_wrapper("octopus_energy/join_octoplus_power_down_session_event", event_code=code, entity_id=entity_id):
+                                    self.log("Note: octopus_energy/join_octoplus_power_down_session_event not available, falling back to the deprecated join_octoplus_saving_session_event service")
+                                    self.call_service_wrapper("octopus_energy/join_octoplus_saving_session_event", event_code=code, entity_id=entity_id)
                             if self.get_arg("set_event_notify"):
                                 self.call_notify("Predbat: Joined Octopus saving event {}-{}, {} p/kWh".format(start_time.strftime("%a %d/%m %H:%M"), end_time.strftime("%H:%M"), saving_rate))
                             self.octopus_last_joined_try = self.now_utc

apps/predbat/tests/test_infra.py

@@ -146,6 +146,7 @@ def __init__(self):
         self.dummy_items = {}
         self.service_store_enable = False
         self.service_store = []
+        self.service_store_fail = set()
         self.db_primary = False
 
     def get_service_store(self):
@@ -189,7 +190,10 @@ def call_service(self, service, **kwargs):
         print("Calling service: {} {}".format(service, kwargs))
         if self.service_store_enable:
             self.service_store.append([service, kwargs])
-            return None
+            # Services in service_store_fail simulate a service that doesn't exist (e.g. testing a
+            # try-new-service-then-fall-back-to-old caller) - everything else succeeds, matching real
+            # HA behaviour for a registered service call.
+            return None if service in self.service_store_fail else True
 
         if service == "number/set_value":
             entity_id = kwargs.get("entity_id", None)

apps/predbat/tests/test_saving_session.py

@@ -105,7 +105,7 @@ def test_saving_session(my_predbat):
     # Example format Sat 25/01
     date_today_service = datetime.now().strftime("%a %d/%m")
     expected_service = [
-        ["octopus_energy/join_octoplus_saving_session_event", {"event_code": 987654, "entity_id": "event.octopus_energy_a_12345678_octoplus_saving_session_event"}],
+        ["octopus_energy/join_octoplus_power_down_session_event", {"event_code": 987654, "entity_id": "event.octopus_energy_a_12345678_octoplus_saving_session_event"}],
         ["notify/notify", {"message": "Predbat: Joined Octopus saving event {} 18:30-19:30, 50.0 p/kWh".format(date_today_service)}],
     ]
 
@@ -494,6 +494,111 @@ def setup_items():
     return failed
 
 
+def test_saving_session_join_service_fallback(my_predbat):
+    """
+    Test that auto-join tries the current Bottle Cap Dave join service
+    (join_octoplus_power_down_session_event) first, falling back to the deprecated
+    join_octoplus_saving_session_event only when the current one is unavailable (e.g. an
+    integration version that predates the Power Down rename). Covers GitHub issue #4548 point 3.
+    """
+    print("Test saving session join service fallback (issue #4548 point 3)")
+    ha = my_predbat.ha_interface
+    failed = False
+    date_today = datetime.now().strftime("%Y-%m-%d")
+    tz_offset = int(my_predbat.midnight_utc.tzinfo.utcoffset(my_predbat.midnight_utc).total_seconds() / 3600)
+    tz_offset = f"{tz_offset:02d}"
+
+    session_binary = """
+state: off
+current_joined_event_start: null
+current_joined_event_end: null
+current_joined_event_duration_in_minutes: null
+next_joined_event_start: null
+next_joined_event_end: null
+next_joined_event_duration_in_minutes: null
+icon: mdi:leaf
+friendly_name: Octoplus Saving Session
+"""
+
+    session_sensor = f"""
+state: '2025-01-23T12:10:11.108+{tz_offset}:00'
+event_types: octopus_energy_all_octoplus_saving_sessions
+event_type: octopus_energy_all_octoplus_saving_sessions
+account_id: A-4DD6C5EE
+available_events:
+    - id: 9999
+      start: '{date_today}T18:30:00+{tz_offset}:00'
+      end: '{date_today}T19:30:00+{tz_offset}:00'
+      duration_in_minutes: 60
+      rewarded_octopoints: null
+      octopoints_per_kwh: 500
+      code: TEST123
+joined_events: []
+friendly_name: Octoplus Saving Session Events
+"""
+
+    def setup_items():
+        ha.dummy_items.clear()
+        ha.dummy_items["binary_sensor.octopus_energy_test_octoplus_saving_sessions"] = yaml.safe_load(session_binary)
+        ha.dummy_items["event.octopus_energy_test_octoplus_saving_session_event"] = yaml.safe_load(session_sensor)
+        ha.dummy_items["sensor.octopus_free_session"] = {}
+        my_predbat.args["octopus_saving_session"] = "event.octopus_energy_test_octoplus_saving_session_event"
+        my_predbat.args["octopus_free_session"] = "sensor.octopus_free_session"
+        if "octopus_free_url" in my_predbat.args:
+            del my_predbat.args["octopus_free_url"]
+        my_predbat.args["octopus_saving_session_octopoints_per_penny"] = 10
+        # No octopus_saving_session_join configured, so this exercises the Bottle Cap Dave service
+        # branch, not the select-entity branch (Octopus Energy Direct or similar)
+        if "octopus_saving_session_join" in my_predbat.args:
+            del my_predbat.args["octopus_saving_session_join"]
+        my_predbat.octopus_last_joined_try = None
+
+    # Test 1: current service available -> used directly, no fallback
+    print("  Test 1: Current service used when available")
+    setup_items()
+    ha.service_store_fail = set()
+    ha.service_store_enable = True
+    ha.service_store = []
+    my_predbat.fetch_octopus_sessions()
+    service_result = ha.get_service_store()
+    ha.service_store_enable = False
+
+    services_called = [svc[0] for svc in service_result]
+    if "octopus_energy/join_octoplus_power_down_session_event" not in services_called:
+        print(f"ERROR: Expected the current service to be called, got {services_called}")
+        failed = True
+    elif "octopus_energy/join_octoplus_saving_session_event" in services_called:
+        print(f"ERROR: Deprecated service should not be called when the current one succeeds, got {services_called}")
+        failed = True
+    else:
+        print("  PASS: Current service called, no fallback")
+
+    # Test 2: current service unavailable (older integration) -> falls back to the deprecated one
+    print("  Test 2: Falls back to deprecated service when the current one is unavailable")
+    setup_items()
+    ha.service_store_fail = {"octopus_energy/join_octoplus_power_down_session_event"}
+    ha.service_store_enable = True
+    ha.service_store = []
+    my_predbat.fetch_octopus_sessions()
+    service_result = ha.get_service_store()
+    ha.service_store_enable = False
+    ha.service_store_fail = set()
+
+    services_called = [svc[0] for svc in service_result]
+    if "octopus_energy/join_octoplus_saving_session_event" not in services_called:
+        print(f"ERROR: Expected fallback to the deprecated service, got {services_called}")
+        failed = True
+    else:
+        print("  PASS: Fell back to the deprecated service")
+
+    if not failed:
+        print("PASS: All join service fallback tests passed")
+
+    my_predbat.octopus_last_joined_try = None
+
+    return failed
+
+
 def test_saving_session_auto_join_toggle(my_predbat):
     """
     Test that the octopus_saving_auto_join switch controls whether available saving sessions are auto-joined

apps/predbat/unit_test.py

@@ -70,6 +70,7 @@
     test_saving_session_notify_config,
     test_saving_session_default_rate,
     test_saving_session_axle_conflict,
+    test_saving_session_join_service_fallback,
     test_saving_session_auto_join_toggle,
     test_saving_session_custom_entity_no_rewrite_match,
 )
@@ -443,6 +444,7 @@ def main():
         ("saving_session_notify", test_saving_session_notify_config, "Saving session notification config tests", False),
         ("saving_session_default_rate", test_saving_session_default_rate, "Saving session default rate injection test", False),
         ("saving_session_axle_conflict", test_saving_session_axle_conflict, "Saving session Axle conflict avoidance test (issue #4120)", False),
+        ("saving_session_join_service_fallback", test_saving_session_join_service_fallback, "Saving session join service fallback test (issue #4548 point 3)", False),
         ("saving_session_auto_join_toggle", test_saving_session_auto_join_toggle, "Saving session auto-join toggle test (issue #4120)", False),
         ("saving_session_custom_entity_no_rewrite_match", test_saving_session_custom_entity_no_rewrite_match, "Saving session custom entity no rewrite match test (issue #4573)", False),
         ("alert_feed", test_alert_feed, "Alert feed tests", False),