matterbridge-roborock-vacuum-plugin-regions 1.1.1-jb.1

package/src/roborockCommunication/RESTAPI/roborockAuthenticateApi.ts

@@ -0,0 +1,302 @@
+import axios, { AxiosInstance, AxiosStatic } from 'axios';
+import crypto from 'node:crypto';
+import { AnsiLogger } from 'matterbridge/logger';
+import { URLSearchParams } from 'node:url';
+import { AuthenticateResponse } from '../Zmodel/authenticateResponse.js';
+import { BaseUrl } from '../Zmodel/baseURL.js';
+import { HomeInfo } from '../Zmodel/homeInfo.js';
+import { UserData } from '../Zmodel/userData.js';
+import { AuthenticateResponseCode } from '../Zenum/authenticateResponseCode.js';
+
+export class RoborockAuthenticateApi {
+  private readonly logger: AnsiLogger;
+  private axiosFactory: AxiosStatic;
+  private deviceId: string;
+  private username?: string;
+  private authToken?: string;
+  // Cached values from base URL lookup for v4 login
+  private cachedBaseUrl?: string;
+  private cachedCountry?: string;
+  private cachedCountryCode?: string;
+  private configRegion?: string;
+
+  constructor(logger: AnsiLogger, axiosFactory: AxiosStatic = axios, deviceId?: string, configRegion?: string) {
+    this.deviceId = deviceId ?? crypto.randomUUID();
+    this.axiosFactory = axiosFactory;
+    this.logger = logger;
+    this.configRegion = configRegion;
+  }
+
+  public async loginWithUserData(username: string, userData: UserData): Promise<UserData> {
+    this.loginWithAuthToken(username, userData.token);
+    return userData;
+  }
+
+  /**
+   * @deprecated Use requestCodeV4 and loginWithCodeV4 instead
+   */
+  public async loginWithPassword(username: string, password: string): Promise<UserData> {
+    const api = await this.getAPIFor(username);
+    const response = await api.post(
+      'api/v1/login',
+      new URLSearchParams({
+        username: username,
+        password: password,
+        needtwostepauth: 'false',
+      }).toString(),
+    );
+    return this.auth(username, response.data);
+  }
+
+  /**
+   * Request a verification code to be sent to the user's email
+   * @param email - The user's email address
+   * @throws Error if the account is not found, rate limited, or other API error
+   */
+  public async requestCodeV4(email: string): Promise<void> {
+    const api = await this.getAPIFor(email);
+    const response = await api.post(
+      'api/v4/email/code/send',
+      new URLSearchParams({
+        email: email,
+        type: 'login',
+        platform: '',
+      }),
+      {
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+      },
+    );
+
+    const apiResponse: AuthenticateResponse<unknown> = response.data;
+
+    if (apiResponse.code === AuthenticateResponseCode.AccountNotFound) {
+      throw new Error(`Account not found for email: ${email}`);
+    }
+    if (apiResponse.code === AuthenticateResponseCode.RateLimited) {
+      throw new Error('Rate limited. Please wait before requesting another code.');
+    }
+    if (apiResponse.code !== AuthenticateResponseCode.Success && apiResponse.code !== undefined) {
+      throw new Error(`Failed to send verification code: ${apiResponse.msg} (code: ${apiResponse.code})`);
+    }
+
+    this.logger.debug('Verification code requested successfully');
+  }
+
+  /**
+   * Login with a verification code received via email
+   * @param email - The user's email address
+   * @param code - The 6-digit verification code
+   * @returns UserData on successful authentication
+   * @throws Error if the code is invalid, rate limited, or other API error
+   */
+  public async loginWithCodeV4(email: string, code: string): Promise<UserData> {
+    const api = await this.getAPIFor(email);
+
+    // Generate x_mercy_ks (random 16-char alphanumeric string)
+    const xMercyKs = this.generateRandomString(16);
+
+    // Get signed key from API
+    const xMercyK = await this.signKeyV3(api, xMercyKs);
+
+    const response = await api.post('api/v4/auth/email/login/code', null, {
+      params: {
+        email: email,
+        code: code,
+        country: this.cachedCountry ?? '',
+        countryCode: this.cachedCountryCode ?? '',
+        majorVersion: '14',
+        minorVersion: '0',
+      },
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'x-mercy-ks': xMercyKs,
+        'x-mercy-k': xMercyK,
+        header_appversion: '4.54.02',
+        header_phonesystem: 'iOS',
+        header_phonemodel: 'iPhone16,1',
+      },
+    });
+
+    return this.authV4(email, response.data);
+  }
+
+  public async getHomeDetails(): Promise<HomeInfo | undefined> {
+    if (!this.username || !this.authToken) {
+      return undefined;
+    }
+
+    const api = await this.getAPIFor(this.username);
+    const response = await api.get('api/v1/getHomeDetail');
+
+    const apiResponse: AuthenticateResponse<HomeInfo> = response.data;
+    if (!apiResponse.data) {
+      throw new Error('Failed to retrieve the home details');
+    }
+    return apiResponse.data;
+  }
+
+  /**
+   * Get cached country info from the last base URL lookup
+   */
+  public getCachedCountryInfo(): { country?: string; countryCode?: string } {
+    return {
+      country: this.cachedCountry,
+      countryCode: this.cachedCountryCode,
+    };
+  }
+
+  private async getAPIFor(username: string): Promise<AxiosInstance> {
+    let baseUrl: string;
+
+    // Check if region is manually configured
+    if (this.configRegion) {
+      baseUrl = this.getBaseUrlForRegion(this.configRegion);
+      this.logger.info(`Using configured region: ${this.configRegion}`);
+    } else {
+      // Fall back to auto-detection
+      baseUrl = await this.getBaseUrl(username);
+      this.logger.info(`Auto-detected region from email`);
+    }
+
+    return this.apiForUser(username, baseUrl);
+  }
+
+  private async getBaseUrl(username: string): Promise<string> {
+    if (this.cachedBaseUrl && this.username === username) {
+      return this.cachedBaseUrl;
+    }
+
+    const api = await this.apiForUser(username);
+    const response = await api.post(
+      'api/v1/getUrlByEmail',
+      new URLSearchParams({
+        email: username,
+        needtwostepauth: 'false',
+      }).toString(),
+    );
+
+    const apiResponse: AuthenticateResponse<BaseUrl> = response.data;
+    if (!apiResponse.data) {
+      throw new Error('Failed to retrieve base URL: ' + apiResponse.msg);
+    }
+
+    this.cachedBaseUrl = apiResponse.data.url;
+    this.cachedCountry = apiResponse.data.country;
+    this.cachedCountryCode = apiResponse.data.countrycode;
+    this.username = username;
+
+    return apiResponse.data.url;
+  }
+
+  private getBaseUrlForRegion(region: string): string {
+    const regionUrls: { [key: string]: string } = {
+      'eu': 'https://euiot.roborock.com',
+      'us': 'https://usiot.roborock.com',
+      'cn': 'https://iotcn.roborock.com',
+    };
+    return regionUrls[region.toLowerCase()] || regionUrls['us'];
+  }
+
+  private async apiForUser(username: string, baseUrl = 'https://usiot.roborock.com'): Promise<AxiosInstance> {
+    const instance = this.axiosFactory.create({
+      baseURL: baseUrl,
+      headers: {
+        header_clientid: crypto.createHash('md5').update(username).update(this.deviceId).digest('base64'),
+        Authorization: this.authToken,
+        header_clientlang: 'en',
+      },
+    });
+
+    instance.interceptors.request.use((config) => {
+      this.logger.debug('=== HTTP Request ===');
+      this.logger.debug(`URL: ${config.baseURL}/${config.url}`);
+      this.logger.debug(`Method: ${config.method?.toUpperCase()}`);
+      this.logger.debug(`Params: ${JSON.stringify(config.params)}`);
+      this.logger.debug(`Data: ${JSON.stringify(config.data)}`);
+      this.logger.debug(`Headers: ${JSON.stringify(config.headers)}`);
+      return config;
+    });
+
+    instance.interceptors.response.use(
+      (response) => {
+        this.logger.debug('=== HTTP Response ===');
+        this.logger.debug(`Status: ${response.status}`);
+        this.logger.debug(`Data: ${JSON.stringify(response.data)}`);
+        return response;
+      },
+      (error) => {
+        this.logger.debug('=== HTTP Error ===');
+        this.logger.debug(`Error: ${JSON.stringify(error.response?.data ?? error.message)}`);
+        return Promise.reject(error);
+      },
+    );
+
+    return instance;
+  }
+
+  private auth(username: string, response: AuthenticateResponse<UserData>): UserData {
+    const userdata = response.data;
+    if (!userdata || !userdata.token) {
+      throw new Error('Authentication failed: ' + response.msg + ' code: ' + response.code);
+    }
+
+    this.loginWithAuthToken(username, userdata.token);
+    return userdata;
+  }
+
+  /**
+   * Handle v4 authentication response with specific error code handling
+   */
+  private authV4(email: string, response: AuthenticateResponse<UserData>): UserData {
+    if (response.code === AuthenticateResponseCode.InvalidCode) {
+      throw new Error('Invalid verification code. Please check and try again.');
+    }
+    if (response.code === AuthenticateResponseCode.RateLimited) {
+      throw new Error('Rate limited. Please wait before trying again.');
+    }
+
+    const userdata = response.data;
+    if (!userdata || !userdata.token) {
+      throw new Error('Authentication failed: ' + response.msg + ' code: ' + response.code);
+    }
+
+    this.loginWithAuthToken(email, userdata.token);
+    return userdata;
+  }
+
+  private loginWithAuthToken(username: string, token: string): void {
+    this.username = username;
+    this.authToken = token;
+  }
+
+  /**
+   * Generate a random alphanumeric string of specified length
+   */
+  private generateRandomString(length: number): string {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    let result = '';
+    const randomBytes = crypto.randomBytes(length);
+    for (let i = 0; i < length; i++) {
+      result += chars[randomBytes[i] % chars.length];
+    }
+    return result;
+  }
+
+  /**
+   * Sign a key using the v3 API endpoint
+   */
+  private async signKeyV3(api: AxiosInstance, s: string): Promise<string> {
+    const response = await api.post('api/v3/key/sign', null, {
+      params: { s },
+    });
+
+    const apiResponse: AuthenticateResponse<{ k: string }> = response.data;
+    if (!apiResponse.data?.k) {
+      throw new Error('Failed to sign key: ' + apiResponse.msg);
+    }
+
+    return apiResponse.data.k;
+  }
+}

package/src/roborockCommunication/RESTAPI/roborockIoTApi.ts

@@ -0,0 +1,107 @@
+import axios, { AxiosInstance } from 'axios';
+import crypto from 'node:crypto';
+import { AnsiLogger, debugStringify } from 'matterbridge/logger';
+import { ApiResponse } from '../Zmodel/apiResponse.js';
+import { Home } from '../Zmodel/home.js';
+import { UserData } from '../Zmodel/userData.js';
+import { Scene } from '../Zmodel/scene.js';
+
+export class RoborockIoTApi {
+  logger: AnsiLogger;
+  private readonly api: AxiosInstance;
+
+  constructor(userdata: UserData, logger: AnsiLogger) {
+    this.logger = logger;
+
+    this.api = axios.create({ baseURL: userdata.rriot.r.a });
+    this.api.interceptors.request.use((config) => {
+      try {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const nonce = crypto
+          .randomBytes(6)
+          .toString('base64')
+          .substring(0, 6)
+          .replace(/[+/]/g, (m) => (m === '+' ? 'X' : 'Y'));
+        const url = this.api ? new URL(this.api.getUri(config)).pathname : '';
+        const data = [userdata.rriot.u, userdata.rriot.s, nonce, timestamp, crypto.createHash('md5').update(url).digest('hex'), '', ''].join(':');
+        const hmac = crypto.createHmac('sha256', userdata.rriot.h).update(data).digest('base64');
+        config.headers['Authorization'] = `Hawk id="${userdata.rriot.u}", s="${userdata.rriot.s}", ts="${timestamp}", nonce="${nonce}", mac="${hmac}"`;
+      } catch (error) {
+        this.logger.error(`Failed to initialize RESTAPI ${error ? debugStringify(error) : 'undefined'}`);
+      }
+      return config;
+    });
+  }
+
+  public async getHome(homeId: number): Promise<Home | undefined> {
+    const result = await this.api.get(`user/homes/${homeId}`);
+
+    const apiResponse: ApiResponse<Home> = result.data;
+    if (apiResponse.result) {
+      return apiResponse.result;
+    } else {
+      this.logger.error('Failed to retrieve the home data');
+      return undefined;
+    }
+  }
+
+  public async getHomev2(homeId: number): Promise<Home | undefined> {
+    const result = await this.api.get('v2/user/homes/' + homeId);
+
+    const apiResponse: ApiResponse<Home> = result.data;
+    if (apiResponse.result) {
+      return apiResponse.result;
+    } else {
+      this.logger.error('Failed to retrieve the home data');
+      return undefined;
+    }
+  }
+
+  public async getHomev3(homeId: number): Promise<Home | undefined> {
+    const result = await this.api.get('v3/user/homes/' + homeId); // can be v3 also
+
+    const apiResponse: ApiResponse<Home> = result.data;
+    if (apiResponse.result) {
+      return apiResponse.result;
+    } else {
+      this.logger.error('Failed to retrieve the home data');
+      return undefined;
+    }
+  }
+
+  public async getScenes(homeId: number): Promise<Scene[] | undefined> {
+    const result = await this.api.get('user/scene/home/' + homeId);
+
+    const apiResponse: ApiResponse<Scene[]> = result.data;
+    if (apiResponse.result) {
+      return apiResponse.result;
+    } else {
+      this.logger.error('Failed to retrieve scene');
+      return undefined;
+    }
+  }
+
+  public async startScene(sceneId: number): Promise<unknown> {
+    const result = await this.api.post(`user/scene/${sceneId}/execute`);
+    const apiResponse: ApiResponse<unknown> = result.data;
+
+    if (apiResponse.result) {
+      return apiResponse.result;
+    } else {
+      this.logger.error('Failed to execute scene');
+      return undefined;
+    }
+  }
+
+  public async getCustom(url: string): Promise<unknown> {
+    const result = await this.api.get(url);
+    const apiResponse: ApiResponse<unknown> = result.data;
+
+    if (apiResponse.result) {
+      return apiResponse.result;
+    } else {
+      this.logger.error('Failed to execute scene');
+      return undefined;
+    }
+  }
+}

package/src/roborockCommunication/Zenum/additionalPropCode.ts

@@ -0,0 +1,3 @@
+export enum AdditionalPropCode {
+  map_change = 4,
+}

package/src/roborockCommunication/Zenum/authenticateResponseCode.ts

@@ -0,0 +1,6 @@
+export enum AuthenticateResponseCode {
+  Success = 200,
+  AccountNotFound = 2008,
+  InvalidCode = 2018,
+  RateLimited = 9002,
+}

package/src/roborockCommunication/Zenum/dockType.ts

@@ -0,0 +1,3 @@
+export enum DockType {
+  qrevo_curv_dock = 17,
+}

package/src/roborockCommunication/Zenum/operationStatusCode.ts

@@ -0,0 +1,43 @@
+export enum OperationStatusCode {
+  Unknown = 0,
+  Initiating = 1,
+  Sleeping = 2, // or ChargerDisconnected
+  Idle = 3,
+  RemoteControl = 4,
+  Cleaning = 5,
+  ReturningDock = 6,
+  ManualMode = 7,
+  Charging = 8,
+  ChargingError = 9,
+  Paused = 10,
+  SpotCleaning = 11,
+  InError = 12,
+  ShuttingDown = 13,
+  Updating = 14,
+  ReturnToDock = 15,
+  GoTo = 16,
+  ZoneClean = 17,
+  RoomClean = 18,
+  EmptyingDustContainer = 22,
+  WashingTheMop = 23,
+  WashingTheMop2 = 25,
+  GoingToWashTheMop = 26,
+  InCall = 28,
+  Mapping = 29,
+  SOMETHING_NEED_TO_FIGUREOUT = 30,
+  Patrol = 32,
+  FullyCharged = 100,
+  DeviceOffline = 101,
+  Locked = 103,
+  AirDryingStopping = 202,
+  RobotStatusMopping = 6301,
+  CleanMopCleaning = 6302,
+  CleanMopMopping = 6303,
+  RoomMopping = 6304,
+  RoomCleanMopCleaning = 6305,
+  RoomCleanMopMopping = 6306,
+  ZoneMopping = 6307,
+  ZoneCleanMopCleaning = 6308,
+  ZoneCleanMopMopping = 6309,
+  BackToDockWashingDuster = 6310,
+}

package/src/roborockCommunication/Zenum/vacuumAndDockErrorCode.ts

@@ -0,0 +1,68 @@
+export enum VacuumErrorCode {
+  None = 0,
+  LidarBlocked = 1,
+  BumperStuck = 2,
+  WheelsSuspended = 3,
+  CliffSensorError = 4,
+  MainBrushJammed = 5,
+  SideBrushJammed = 6,
+  WheelsJammed = 7,
+  RobotTrapped = 8,
+  NoDustbin = 9,
+  StrainerError = 10,
+  CompassError = 11,
+  LowBattery = 12,
+  ChargingError = 13,
+  BatteryError = 14,
+  WallSensorDirty = 15,
+  RobotTilted = 16,
+  SideBrushError = 17,
+  FanError = 18,
+  DockNotConnectedToPower = 19,
+  OpticalFlowSensorDirt = 20,
+  VerticalBumperPressed = 21,
+  DockLocatorError = 22,
+  ReturnToDockFail = 23,
+  NogoZoneDetected = 24,
+  CameraError = 25,
+  WallSensorError = 26,
+  VibrariseJammed = 27,
+  RobotOnCarpet = 28,
+  FilterBlocked = 29,
+  InvisibleWallDetected = 30,
+  CannotCrossCarpet = 31,
+  InternalError = 32,
+  CleanAutoEmptyDock = 34,
+  AutoEmptyDockVoltage = 35,
+  MoppingRollerJammed = 36, // Wash roller may be jammed
+  MoppingRollerNotLowered = 37, // wash roller not lowered properly
+  ClearWaterBoxHoare = 38,
+  DirtyWaterBoxHoare = 39,
+  SinkStrainerHoare = 40,
+  ClearWaterTankEmpty = 41,
+  ClearBrushInstalledProperly = 42, // Check that the water filter has been correctly installed
+  ClearBrushPositioningError = 43,
+  FilterScreenException = 44, // Clean the dock water filter
+  MoppingRollerJammed2 = 45, // Wash roller may be jammed
+  UpWaterException = 48,
+  DrainWaterException = 49,
+  TemperatureProtection = 51,
+  CleanCarouselException = 52,
+  CleanCarouselWaterFull = 53,
+  WaterCarriageDrop = 54,
+  CheckCleanCarouse = 55,
+  AudioError = 56,
+}
+
+export enum DockErrorCode {
+  None = 0,
+  DuctBlockage = 34, // Duct blockage detected
+  WaterEmpty = 38, // Clean water tank empty
+  WasteWaterTankFull = 39, // Waste water tank full
+  MaintenanceBrushJammed = 42, // Maintenance brush jammed
+  DirtyTankLatchOpen = 44, // Dirty tank latch open
+  NoDustbin = 46, // No dustbin detected
+  CleaningTankFullOrBlocked = 53, // Cleaning tank full or blocked
+}
+
+export const SUPPORTED_ATTACHMENTS = ['WATERTANK', 'MOP'];

package/src/roborockCommunication/Zmodel/apiResponse.ts

@@ -0,0 +1,3 @@
+export interface ApiResponse<T> {
+  result?: T;
+}

package/src/roborockCommunication/Zmodel/authenticateFlowState.ts

@@ -0,0 +1,6 @@
+export interface AuthenticateFlowState {
+  email: string;
+  codeRequestedAt?: number;
+  country?: string;
+  countryCode?: string;
+}

package/src/roborockCommunication/Zmodel/authenticateResponse.ts

@@ -0,0 +1,5 @@
+export interface AuthenticateResponse<T> {
+  msg?: string;
+  data?: T;
+  code?: number;
+}

package/src/roborockCommunication/Zmodel/baseURL.ts

@@ -0,0 +1,5 @@
+export interface BaseUrl {
+  url: string;
+  country: string;
+  countrycode: string;
+}

package/src/roborockCommunication/Zmodel/batteryMessage.ts

@@ -0,0 +1,16 @@
+import { DeviceStatus, VacuumErrorCode } from '../index.js';
+import { CloudMessageResult } from './messageResult.js';
+
+export interface BatteryMessage {
+  duid: string;
+  percentage: number;
+}
+
+export interface DeviceErrorMessage {
+  duid: string;
+  errorCode: VacuumErrorCode;
+}
+
+export interface DeviceStatusNotify extends DeviceStatus, CloudMessageResult {
+  duid: string;
+}

package/src/roborockCommunication/Zmodel/device.ts

@@ -0,0 +1,50 @@
+import { DeviceSchema } from './deviceSchema.js';
+import { Room } from './room.js';
+import { Scene } from './scene.js';
+import { UserData } from './userData.js';
+
+export interface DeviceData {
+  id: string;
+  firmwareVersion: string;
+  serialNumber: string;
+  model: string;
+  category: string;
+  batteryLevel: number;
+}
+
+interface DeviceInformation {
+  userData: UserData;
+  localKey: string;
+  pv: string;
+  model?: string;
+}
+
+export interface Device {
+  duid: string;
+  name: string;
+  sn: string;
+  serialNumber: string;
+
+  featureSet?: string;
+  newFeatureSet?: string;
+  silentOtaSwitch?: boolean;
+
+  activeTime: number;
+  createTime: number;
+  localKey: string;
+
+  /** The protocol version of the robot. */
+  pv: string;
+  online: boolean;
+  productId: string;
+  rrHomeId: number;
+  /** The firmware version of the robot. */
+  fv: string;
+
+  deviceStatus: Record<string, number>;
+  rooms: Room[];
+  schema: DeviceSchema[];
+  data: DeviceData;
+  store?: DeviceInformation;
+  scenes?: Scene[];
+}

package/src/roborockCommunication/Zmodel/deviceModel.ts

@@ -0,0 +1,27 @@
+export enum DeviceModel {
+  Q5 = 'roborock.vacuum.a34',
+  Q5_PRO = 'roborock.vacuum.a72',
+  S5 = 'roborock.vacuum.s5',
+  S5_MAX = 'roborock.vacuum.s5e',
+  S6 = 'roborock.vacuum.s6',
+  S6_MAXV = 'roborock.vacuum.a10',
+  S6_PURE = 'roborock.vacuum.a08',
+  Q7 = 'roborock.vacuum.a40',
+  Q7_PLUS = 'roborock.vacuum.axx', // TODO
+  Q7_MAX = 'roborock.vacuum.a38',
+  S7 = 'roborock.vacuum.a15',
+  S7_MAXV = 'roborock.vacuum.a27',
+  S7_MAXV_ULTRA = 'roborock.vacuum.a65',
+  S7_PRO_ULTRA = 'roborock.vacuum.a62',
+  Q8_MAX = 'roborock.vacuum.a73',
+  S8 = 'roborock.vacuum.a51',
+  S8_PRO_ULTRA = 'roborock.vacuum.a70',
+  S8_MAXV_ULTRA = 'roborock.vacuum.a97',
+  QREVO_MASTER = 'roborock.vacuum.a117',
+  QREVO_CURV = 'roborock.vacuum.a135',
+  QREVO_S = 'roborock.vacuum.a104',
+  QREVO_PRO = 'roborock.vacuum.a101',
+  QREVO_MAXV = 'roborock.vacuum.a87',
+  QREVO_EDGE_5V1 = 'roborock.vacuum.a187',
+  QREVO_EDGE_5AE = 'roborock.vacuum.xxxx',
+}

package/src/roborockCommunication/Zmodel/deviceSchema.ts

@@ -0,0 +1,8 @@
+export interface DeviceSchema {
+  id: number;
+  name: string;
+  code: string;
+  mode: string;
+  type: string;
+  property: unknown;
+}