feat: allow servcies to return data (#65)

* feat: allow servcies to return data

Fixes #34

* feat: add weather forecasts type

* feat: add warning message when trying to call a return_response service over REST

* feat: fix lint errors and format JSDoc

cspell.config.yaml

@@ -30,5 +30,7 @@ words:
   - systype
   - tvshow
   - zeroconf
+  - templow
+  - partlycloudy
 ignoreWords: []
 import: []

src/extensions/call-proxy.extension.ts

@@ -48,15 +48,15 @@ export function CallProxy({
             parameters: object,
           ) => {
             const data = value.services[key];
-            if (is.boolean(data?.response?.optional)) {
-              // https://github.com/Digital-Alchemy-TS/hass/issues/34
-              logger.warn(`calling services with responses not supported`);
-            }
 
             const service = `${value.domain}.${key}` as SERVICE;
-            await sendMessage(service, {
-              ...parameters,
-            } as PICK_SERVICE_PARAMETERS<ALL_SERVICE_DOMAINS, SERVICE>);
+            return await sendMessage(
+              service,
+              {
+                ...parameters,
+              } as PICK_SERVICE_PARAMETERS<ALL_SERVICE_DOMAINS, SERVICE>,
+              is.boolean(data?.response?.optional),
+            );
           },
         ]),
       );
@@ -77,6 +77,7 @@ export function CallProxy({
   >(
     serviceName: SERVICE,
     service_data: PICK_SERVICE_PARAMETERS<DOMAIN, SERVICE>,
+    return_response: boolean,
   ) {
     // pause for rest also
     if (hass.socket.pauseMessages) {
@@ -86,6 +87,14 @@ export function CallProxy({
       (config.hass.CALL_PROXY_ALLOW_REST === "allow" &&
         hass.socket.connectionState !== "connected") ||
       config.hass.CALL_PROXY_ALLOW_REST === "prefer";
+    if (sendViaRest && return_response) {
+      // See https://github.com/home-assistant/core/issues/106379#issuecomment-1878548124 for the reason for this warning
+      logger.warn(
+        { name: sendMessage },
+        "Services that require a return_response are not allowed to be sent via REST, they must use WebSockets",
+      );
+    }
+
     if (sendViaRest) {
       return await hass.fetch.callService(serviceName, service_data);
     }
@@ -94,7 +103,13 @@ export function CallProxy({
     // User can just not await this call if they don't care about the "waitForChange"
 
     return await hass.socket.sendMessage(
-      { domain, service, service_data, type: "call_service" },
+      {
+        domain,
+        return_response,
+        service,
+        service_data,
+        type: "call_service",
+      },
       true,
     );
   }

src/helpers/fetch/index.ts

@@ -2,3 +2,4 @@ export * from "./calendar";
 export * from "./configuration";
 export * from "./server-log";
 export * from "./service-list";
+export * from "./weather-forecasts";

src/helpers/fetch/weather-forecasts.ts

@@ -0,0 +1,86 @@
+// Comes from https://www.home-assistant.io/integrations/weather/#action-weatherget_forecasts
+
+export type WeatherCondition =
+  | "clear-night"
+  | "cloudy"
+  | "fog"
+  | "hail"
+  | "lightning"
+  | "lightning-rainy"
+  | "partlycloudy"
+  | "pouring"
+  | "rainy"
+  | "snowy"
+  | "snowy-rainy"
+  | "sunny"
+  | "windy"
+  | "windy-variant"
+  | "exceptional";
+
+export interface WeatherGetForecasts {
+  /**
+   * Time of the forecasted conditions.
+   * Format is YYYY-MM-DDTHH:mm:ss+zz:zz
+   */
+  datetime: string;
+  /**
+   * Only set for `twice_daily` forecasts
+   */
+  is_daytime: boolean;
+  /**
+   * The apparent (feels-like) temperature in the unit indicated by the `temperature_unite` state attribute.
+   */
+  apparent_temperature: number;
+  /**
+   * The cloud coverage in %.
+   */
+  cloud_coverage: number;
+  /**
+   * The weather condition
+   */
+  condition: WeatherCondition;
+  /**
+   * The dew point temperature in the unit indicated by the `temperature_unite` state attribute.
+   */
+  dew_point: number;
+  /**
+   * The relative humidity in %.
+   */
+  humidity: number;
+  /**
+   * The probability of precipitation in %;
+   */
+  precipitation_probability: number;
+  /**
+   * The precipitation amount in the unit indicated by the `precipitation_unit` state attribute.
+   */
+  precipitation: number;
+  /**
+   * The air pressure in the unit indicated by the `pressure_unit` state attribute.
+   */
+  pressure: number;
+  /**
+   * The temperature in the unit indicated by the `temperature_unite` state attribute. If `templow` is also provided this is the higher temperature.
+   */
+  temperature: number;
+  /**
+   * The lower temperature in the unit indicated by the `temperature_unite` state attribute.
+   */
+  templow: number;
+  /**
+   * The UV index.
+   */
+  uv_index: number;
+  /**
+   * The wind bearing in azimuth angle (degrees) or 1-3 letter cardinal direction
+   */
+  wind_bearing: number | string;
+  /**
+   * The wind gust speed in the unit indicated by the `wind_speed_unit` state attribute.
+   */
+  wind_gust_speed: number;
+  /**
+   * The wind speed in the unit indicated by the `wind_speed_unit` state attribute.
+   */
+  wind_speed: number;
+}