From 734b2691c895d2a15cbc05d365689a829d614a4b Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Mon, 4 Aug 2025 11:08:00 -1000
Subject: [PATCH] [api] Add helpful compile-time errors for Custom API Device
 methods

---
 esphome/components/api/custom_api_device.h | 46 ++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/esphome/components/api/custom_api_device.h b/esphome/components/api/custom_api_device.h
index a39947e725..f67a0832be 100644
--- a/esphome/components/api/custom_api_device.h
+++ b/esphome/components/api/custom_api_device.h
@@ -56,6 +56,13 @@ class CustomAPIDevice {
     auto *service = new CustomAPIDeviceService<T, Ts...>(name, arg_names, (T *) this, callback);  // NOLINT
     global_api_server->register_user_service(service);
   }
+#else
+  template<typename T, typename... Ts>
+  void register_service(void (T::*callback)(Ts...), const std::string &name,
+                        const std::array<std::string, sizeof...(Ts)> &arg_names) {
+    static_assert(
+        false, "register_service() requires 'custom_services: true' in the 'api:' section of your YAML configuration");
+  }
 #endif
 
   /** Register a custom native API service that will show up in Home Assistant.
@@ -81,6 +88,11 @@ class CustomAPIDevice {
     auto *service = new CustomAPIDeviceService<T>(name, {}, (T *) this, callback);  // NOLINT
     global_api_server->register_user_service(service);
   }
+#else
+  template<typename T> void register_service(void (T::*callback)(), const std::string &name) {
+    static_assert(
+        false, "register_service() requires 'custom_services: true' in the 'api:' section of your YAML configuration");
+  }
 #endif
 
 #ifdef USE_API_HOMEASSISTANT_STATES
@@ -135,6 +147,20 @@ class CustomAPIDevice {
     auto f = std::bind(callback, (T *) this, entity_id, std::placeholders::_1);
     global_api_server->subscribe_home_assistant_state(entity_id, optional<std::string>(attribute), f);
   }
+#else
+  template<typename T>
+  void subscribe_homeassistant_state(void (T::*callback)(std::string), const std::string &entity_id,
+                                     const std::string &attribute = "") {
+    static_assert(false, "subscribe_homeassistant_state() requires 'homeassistant_states: true' in the 'api:' section "
+                         "of your YAML configuration");
+  }
+
+  template<typename T>
+  void subscribe_homeassistant_state(void (T::*callback)(std::string, std::string), const std::string &entity_id,
+                                     const std::string &attribute = "") {
+    static_assert(false, "subscribe_homeassistant_state() requires 'homeassistant_states: true' in the 'api:' section "
+                         "of your YAML configuration");
+  }
 #endif
 
 #ifdef USE_API_HOMEASSISTANT_SERVICES
@@ -222,6 +248,26 @@ class CustomAPIDevice {
     }
     global_api_server->send_homeassistant_service_call(resp);
   }
+#else
+  void call_homeassistant_service(const std::string &service_name) {
+    static_assert(false, "call_homeassistant_service() requires 'homeassistant_services: true' in the 'api:' section "
+                         "of your YAML configuration");
+  }
+
+  void call_homeassistant_service(const std::string &service_name, const std::map<std::string, std::string> &data) {
+    static_assert(false, "call_homeassistant_service() requires 'homeassistant_services: true' in the 'api:' section "
+                         "of your YAML configuration");
+  }
+
+  void fire_homeassistant_event(const std::string &event_name) {
+    static_assert(false, "fire_homeassistant_event() requires 'homeassistant_services: true' in the 'api:' section of "
+                         "your YAML configuration");
+  }
+
+  void fire_homeassistant_event(const std::string &service_name, const std::map<std::string, std::string> &data) {
+    static_assert(false, "fire_homeassistant_event() requires 'homeassistant_services: true' in the 'api:' section of "
+                         "your YAML configuration");
+  }
 #endif
 };