feat: add preliminary tadoX support

Author: mattdavis90

src/index.ts

@@ -67,6 +67,7 @@ const EXPIRATION_WINDOW_IN_SECONDS = 300;
 
 const tado_auth_url = "https://auth.tado.com";
 const tado_url = "https://my.tado.com";
+const tado_x_url = "https://hops.tado.com";
 const tado_config = {
   client: {
     id: "tado-web-app",
@@ -111,11 +112,15 @@ export class Tado {
   #accessToken?: AccessToken | undefined;
   #username?: string;
   #password?: string;
+  #firstLogin: boolean;
+  #isX: boolean;
 
   constructor(username?: string, password?: string) {
     this.#username = username;
     this.#password = password;
     this.#httpsAgent = new Agent({ keepAlive: true });
+    this.#firstLogin = true;
+    this.#isX = false;
   }
 
   async #login(): Promise<void> {
@@ -130,6 +135,20 @@ export class Tado {
     };
 
     this.#accessToken = await client.getToken(tokenParams);
+
+    if (this.#firstLogin) {
+      try {
+        const me = await this.getMe();
+        if (me.homes.length > 0) {
+          const home_id = me.homes[0].id;
+          const home = await this.getHome(home_id);
+          this.#isX = home.generation == "LINE_X";
+        }
+      } catch (err) {
+        console.error(`Could not determine TadoX status: ${err}`);
+      }
+      this.#firstLogin = false;
+    }
   }
 
   /**
@@ -168,6 +187,10 @@ export class Tado {
     return this.#accessToken;
   }
 
+  get isX(): boolean {
+    return this.#isX;
+  }
+
   /**
    * Authenticates a user using the provided public client credentials, username and password.
    * For more information see
@@ -217,6 +240,21 @@ export class Tado {
     return response.data as R;
   }
 
+  /**
+   * Makes an API call to the provided TadoX URL with the specified method and data.
+   *
+   * @typeParam R - The type of the response
+   * @typeParam T - The type of the request body
+   * @param url - The endpoint to which the request is sent. If the URL contains "https", it will be used as is.
+   * @param method - The HTTP method to use for the request (e.g., "get", "post").
+   * @param data - The payload to send with the request, if applicable.
+   * @returns A promise that resolves to the response data.
+   */
+  async apiCallX<R, T = unknown>(url: string, method: Method = "get", data?: T): Promise<R> {
+    const callUrl = tado_x_url + url;
+    return this.apiCall(callUrl, method, data);
+  }
+
   /**
    * Fetches the current user data.
    *
@@ -315,7 +353,11 @@ export class Tado {
    * @returns A promise that resolves to an array of Device objects.
    */
   getDevices(home_id: number): Promise<Device[]> {
-    return this.apiCall(`/api/v2/homes/${home_id}/devices`);
+    if (this.#isX) {
+      return this.apiCallX(`/homes/${home_id}/roomsAndDevices`);
+    } else {
+      return this.apiCall(`/api/v2/homes/${home_id}/devices`);
+    }
   }
 
   /**
@@ -542,7 +584,11 @@ export class Tado {
    * @returns A promise that resolves to an array of Zone objects.
    */
   getZones(home_id: number): Promise<Zone[]> {
-    return this.apiCall(`/api/v2/homes/${home_id}/zones`);
+    if (this.#isX) {
+      return this.apiCallX(`/homes/${home_id}/rooms`);
+    } else {
+      return this.apiCall(`/api/v2/homes/${home_id}/zones`);
+    }
   }
 
   /**
@@ -553,7 +599,11 @@ export class Tado {
    * @returns  A promise that resolves to the state of the specified zone.
    */
   getZoneState(home_id: number, zone_id: number): Promise<ZoneState> {
-    return this.apiCall(`/api/v2/homes/${home_id}/zones/${zone_id}/state`);
+    if (this.#isX) {
+      return this.apiCallX(`/homes/${home_id}/rooms/${zone_id}`);
+    } else {
+      return this.apiCall(`/api/v2/homes/${home_id}/zones/${zone_id}/state`);
+    }
   }
 
   /**
@@ -785,7 +835,11 @@ export class Tado {
    * @deprecated Use {@link clearZoneOverlays} instead.
    */
   clearZoneOverlay(home_id: number, zone_id: number): Promise<void> {
-    return this.apiCall(`/api/v2/homes/${home_id}/zones/${zone_id}/overlay`, "delete");
+    if (this.#isX) {
+      return this.apiCallX(`/homes/${home_id}/rooms/${zone_id}/resumeSchedule`, "post", {});
+    } else {
+      return this.apiCall(`/api/v2/homes/${home_id}/zones/${zone_id}/overlay`, "delete");
+    }
   }
 
   /**
@@ -903,7 +957,15 @@ export class Tado {
       };
     }
 
-    return this.apiCall(`/api/v2/homes/${home_id}/zones/${zone_id}/overlay`, "put", config);
+    if (this.#isX) {
+      return this.apiCallX(
+        `/api/v2/homes/${home_id}/rooms/${zone_id}/manualControl`,
+        "post",
+        config,
+      );
+    } else {
+      return this.apiCall(`/api/v2/homes/${home_id}/zones/${zone_id}/overlay`, "put", config);
+    }
   }
 
   /**
@@ -914,8 +976,14 @@ export class Tado {
    * @returns A promise that resolves when the overlays are cleared.
    */
   async clearZoneOverlays(home_id: number, zone_ids: number[]): Promise<void> {
-    const rooms = zone_ids.join(",");
-    return this.apiCall(`/api/v2/homes/${home_id}/overlay?rooms=${rooms}`, "delete");
+    if (this.#isX) {
+      for (const zone_id of zone_ids) {
+        return this.apiCallX(`/homes/${home_id}/rooms/${zone_id}/resumeSchedule`, "post", {});
+      }
+    } else {
+      const rooms = zone_ids.join(",");
+      return this.apiCall(`/api/v2/homes/${home_id}/overlay?rooms=${rooms}`, "delete");
+    }
   }
 
   /**
@@ -1054,7 +1122,17 @@ export class Tado {
       config.push(overlay_config);
     }
 
-    return this.apiCall(`/api/v2/homes/${home_id}/overlay`, "post", { overlays: config });
+    if (this.#isX) {
+      for (const c of config) {
+        return this.apiCallX(
+          `/api/v2/homes/${home_id}/rooms/${c.room}/manualControl`,
+          "post",
+          c.overlay,
+        );
+      }
+    } else {
+      return this.apiCall(`/api/v2/homes/${home_id}/overlay`, "post", { overlays: config });
+    }
   }
 
   /**

test/index.ts

@@ -17,6 +17,7 @@ import eneryIQ_savings_response from "./response.eneryIQ.savings.json";
 import eneryIQ_tariff_response from "./response.eneryIQ.tariff.json";
 import heating_system_response from "./response.heatingSystem.json";
 import home_response from "./response.home.json";
+import home_response_x from "./response.home.x.json";
 import incident_detection_response from "./response.incidentDetection.json";
 import installations_response from "./response.installations.json";
 import invitations_response from "./response.invitations.json";
@@ -40,13 +41,14 @@ import zones_response from "./response.zones.json";
 chai.use(chaiAsPromised);
 const expect = chai.expect;
 
-describe("OAuth2 tests", () => {
-  beforeEach(() => {
+describe("OAuth2 tests", async () => {
+  afterEach(async () => {
     nock.cleanAll();
   });
 
   it("Should login", async () => {
     nock("https://auth.tado.com").post("/oauth/token").reply(200, auth_response);
+    nock("https://my.tado.com", { allowUnmocked: false });
 
     const tado = new Tado();
     await tado.login("username", "password");
@@ -64,14 +66,20 @@ describe("OAuth2 tests", () => {
   });
 });
 
-describe("Low-level API tests", () => {
-  beforeEach(() => {
+describe("Low-level API tests", async () => {
+  afterEach(async () => {
     nock.cleanAll();
   });
 
   it('Login and get "me"', async () => {
     nock("https://auth.tado.com").post("/oauth/token").reply(200, auth_response);
-    nock("https://my.tado.com").get("/api/v2/me").reply(200, me_response);
+    nock("https://my.tado.com")
+      .get("/api/v2/me")
+      .reply(200, me_response)
+      .get("/api/v2/me")
+      .reply(200, me_response) // Needed twice otherwise consumed by login
+      .get("/api/v2/homes/1907")
+      .reply(200, home_response);
 
     const tado = new Tado();
     await tado.login("username", "password");
@@ -98,15 +106,24 @@ describe("Low-level API tests", () => {
   });
 });
 
-describe("High-level API tests", () => {
+describe("High-level API tests (v2)", async () => {
   let tado: Tado;
 
   beforeEach(async () => {
-    nock.cleanAll();
     nock("https://auth.tado.com").post("/oauth/token").reply(200, auth_response);
+    nock("https://my.tado.com")
+      .get("/api/v2/me")
+      .reply(200, me_response)
+      .get("/api/v2/homes/1907")
+      .reply(200, home_response);
 
     tado = new Tado();
     await tado.login("username", "password");
+    expect(tado.isX).to.equal(false);
+  });
+
+  afterEach(async () => {
+    nock.cleanAll();
   });
 
   it("Should get the current user", async () => {
@@ -818,3 +835,72 @@ describe("High-level API tests", () => {
     expect(response.manufacturers[0].name).to.equal("Junkers");
   });
 });
+
+describe("High-level API tests (TadoX)", async () => {
+  let tado: Tado;
+
+  beforeEach(async () => {
+    nock("https://auth.tado.com").post("/oauth/token").reply(200, auth_response);
+    nock("https://my.tado.com")
+      .get("/api/v2/me")
+      .reply(200, me_response)
+      .get("/api/v2/homes/1907")
+      .reply(200, home_response_x);
+
+    tado = new Tado();
+    await tado.login("username", "password");
+    expect(tado.isX).to.equal(true);
+  });
+
+  afterEach(async () => {
+    nock.cleanAll();
+  });
+
+  it("Should get the user's devices", async () => {
+    nock("https://hops.tado.com").get("/homes/1907/roomsAndDevices").reply(200, me_response);
+
+    const response = await tado.getDevices(1907);
+
+    expect(typeof response).to.equal("object");
+  });
+
+  it("Should get zones", async () => {
+    nock("https://hops.tado.com").get("/homes/1907/rooms").reply(200, zones_response);
+
+    const response = await tado.getZones(1907);
+
+    expect(typeof response).to.equal("object");
+  });
+
+  it("Should get a zone's state", async () => {
+    nock("https://hops.tado.com").get("/homes/1907/rooms/1").reply(200, zone_state_response);
+
+    const response = await tado.getZoneState(1907, 1);
+
+    expect(typeof response).to.equal("object");
+  });
+
+  it("Should clear a zone's overlay", async () => {
+    nock("https://hops.tado.com").post("/homes/1907/rooms/1/resumeSchedule").reply(200, {});
+
+    const response = await tado.clearZoneOverlay(1907, 1);
+
+    expect(typeof response).to.equal("object");
+  });
+
+  it("Should set a zone's overlay to Off", async () => {
+    nock("https://my.tado.com")
+      .get("/api/v2/homes/1907/zones/1/capabilities")
+      .reply(200, zone_capabilities_response);
+
+    nock("https://hops.tado.com")
+      .post("/api/v2/homes/1907/rooms/1/manualControl")
+      .reply(200, (_uri, req) => {
+        return req;
+      });
+
+    const response = await tado.setZoneOverlay(1907, 1, "OFF");
+
+    expect(typeof response).to.equal("object");
+  });
+});

test/response.home.x.json

@@ -0,0 +1,57 @@
+{
+  "id": 1907,
+  "name": "Dummy Home",
+  "dateTimeZone": "Europe/Amsterdam",
+  "dateCreated": "2021-11-15T12:27:24.825Z",
+  "temperatureUnit": "CELSIUS",
+  "partner": null,
+  "simpleSmartScheduleEnabled": true,
+  "awayRadiusInMeters": 500,
+  "installationCompleted": true,
+  "incidentDetection": {
+    "supported": true,
+    "enabled": true
+  },
+  "generation": "LINE_X",
+  "zonesCount": 8,
+  "language": "en",
+  "skills": ["AUTO_ASSIST"],
+  "christmasModeEnabled": true,
+  "showAutoAssistReminders": true,
+  "contactDetails": {
+    "name": "Tado User",
+    "email": "tado.user@tado.com",
+    "phone": "+3112115194351"
+  },
+  "address": {
+    "addressLine1": "Museumplein 6",
+    "addressLine2": null,
+    "zipCode": "1071",
+    "city": "Amsterdam",
+    "state": null,
+    "country": "NLD"
+  },
+  "geolocation": {
+    "latitude": 51.2993,
+    "longitude": 9.491
+  },
+  "consentGrantSkippable": true,
+  "enabledFeatures": [
+    "DARK_MODE",
+    "EIQ_SETTINGS_AS_WEBVIEW",
+    "HIDE_BOILER_REPAIR_SERVICE",
+    "HOME_DETAILS_AS_WEBVIEW",
+    "MORE_AS_WEBVIEW",
+    "OFFLINE_SCHEDULE_ENABLED",
+    "OWD_SETTINGS_AS_WEBVIEW",
+    "PEOPLE_AS_WEBVIEW",
+    "SETTINGS_OVERVIEW_AS_WEBVIEW"
+  ],
+  "isAirComfortEligible": true,
+  "isBalanceAcEligible": false,
+  "isEnergyIqEligible": true,
+  "isHeatSourceInstalled": false,
+  "isHeatPumpInstalled": false,
+  "isBalanceHpEligible": false,
+  "supportsFlowTemperatureOptimization": false
+}