edilkamin 1.6.1 → 1.7.2

package/src/library.ts

@@ -1,10 +1,18 @@
 import { strict as assert } from "assert";
 import { Amplify } from "aws-amplify";
 import * as amplifyAuth from "aws-amplify/auth";
+import { cognitoUserPoolsTokenProvider } from "aws-amplify/auth/cognito";
 import axios, { AxiosInstance } from "axios";
 
+import { processResponse } from "./buffer-utils";
 import { API_URL } from "./constants";
-import { DeviceInfoType } from "./types";
+import {
+  DeviceAssociationBody,
+  DeviceAssociationResponse,
+  DeviceInfoRawType,
+  DeviceInfoType,
+  EditDeviceAssociationBody,
+} from "./types";
 
 const amplifyconfiguration = {
   aws_project_region: "eu-central-1",
@@ -19,14 +27,25 @@ const amplifyconfiguration = {
  */
 const headers = (jwtToken: string) => ({ Authorization: `Bearer ${jwtToken}` });
 
+let amplifyConfigured = false;
+
 /**
  * Configures Amplify if not already configured.
- * Ensures the configuration is only applied once.
+ * Uses a local flag to avoid calling getConfig() which prints a warning.
+ * @param {object} [storage] - Optional custom storage adapter for token persistence
  */
-const configureAmplify = () => {
-  const currentConfig = Amplify.getConfig();
-  if (Object.keys(currentConfig).length !== 0) return;
+const configureAmplify = (storage?: {
+  setItem: (key: string, value: string) => Promise<void>;
+  getItem: (key: string) => Promise<string | null>;
+  removeItem: (key: string) => Promise<void>;
+  clear: () => Promise<void>;
+}) => {
+  if (amplifyConfigured) return;
   Amplify.configure(amplifyconfiguration);
+  if (storage) {
+    cognitoUserPoolsTokenProvider.setKeyValueStorage(storage);
+  }
+  amplifyConfigured = true;
 };
 
 /**
@@ -39,12 +58,14 @@ const createAuthService = (auth: typeof amplifyAuth) => {
    * Signs in a user with the provided credentials.
    * @param {string} username - The username of the user.
    * @param {string} password - The password of the user.
+   * @param {boolean} [legacy=false] - If true, returns accessToken for legacy API.
    * @returns {Promise<string>} - The JWT token of the signed-in user.
    * @throws {Error} - If sign-in fails or no tokens are retrieved.
    */
   const signIn = async (
     username: string,
-    password: string
+    password: string,
+    legacy: boolean = false,
   ): Promise<string> => {
     configureAmplify();
     await auth.signOut(); // Ensure the user is signed out first
@@ -52,32 +73,62 @@ const createAuthService = (auth: typeof amplifyAuth) => {
     assert.ok(isSignedIn, "Sign-in failed");
     const { tokens } = await auth.fetchAuthSession();
     assert.ok(tokens, "No tokens found");
+    if (legacy) {
+      assert.ok(tokens.accessToken, "No access token found");
+      return tokens.accessToken.toString();
+    }
     assert.ok(tokens.idToken, "No ID token found");
     return tokens.idToken.toString();
   };
-  return { signIn };
+
+  /**
+   * Retrieves the current session, refreshing tokens if necessary.
+   * Requires a prior successful signIn() call.
+   * @param {boolean} [forceRefresh=false] - Force token refresh even if valid
+   * @param {boolean} [legacy=false] - If true, returns accessToken for legacy API
+   * @returns {Promise<string>} - The JWT token (idToken or accessToken)
+   * @throws {Error} - If no session exists (user needs to sign in)
+   */
+  const getSession = async (
+    forceRefresh: boolean = false,
+    legacy: boolean = false,
+  ): Promise<string> => {
+    configureAmplify();
+    const { tokens } = await auth.fetchAuthSession({ forceRefresh });
+    assert.ok(tokens, "No session found - please sign in first");
+    if (legacy) {
+      assert.ok(tokens.accessToken, "No access token found");
+      return tokens.accessToken.toString();
+    }
+    assert.ok(tokens.idToken, "No ID token found");
+    return tokens.idToken.toString();
+  };
+
+  return { signIn, getSession };
 };
 
 // Create the default auth service using amplifyAuth
-const { signIn } = createAuthService(amplifyAuth);
+const { signIn, getSession } = createAuthService(amplifyAuth);
 
 const deviceInfo =
   (axiosInstance: AxiosInstance) =>
   /**
    * Retrieves information about a device by its MAC address.
+   * Automatically decompresses any gzip-compressed Buffer fields in the response.
    *
    * @param {string} jwtToken - The JWT token for authentication.
    * @param {string} macAddress - The MAC address of the device.
    * @returns {Promise<DeviceInfoType>} - A promise that resolves to the device info.
    */
-  async (jwtToken: string, macAddress: string) => {
-    const response = await axiosInstance.get<DeviceInfoType>(
+  async (jwtToken: string, macAddress: string): Promise<DeviceInfoType> => {
+    const response = await axiosInstance.get<DeviceInfoRawType>(
       `device/${macAddress}/info`,
       {
         headers: headers(jwtToken),
-      }
+      },
     );
-    return response.data;
+    // Process response to decompress any gzipped Buffer fields
+    return processResponse(response.data) as DeviceInfoType;
   };
 
 const mqttCommand =
@@ -87,7 +138,7 @@ const mqttCommand =
     axiosInstance.put(
       "mqtt/command",
       { mac_address: macAddress, ...payload },
-      { headers: headers(jwtToken) }
+      { headers: headers(jwtToken) },
     );
 
 const setPower =
@@ -193,6 +244,70 @@ const setTargetTemperature =
       value: temperature,
     });
 
+const registerDevice =
+  (axiosInstance: AxiosInstance) =>
+  /**
+   * Registers a device with the user's account.
+   * This must be called before other device operations will work on the new API.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device (colons optional).
+   * @param {string} serialNumber - The device serial number.
+   * @param {string} deviceName - User-friendly name for the device (default: empty string).
+   * @param {string} deviceRoom - Room name for the device (default: empty string).
+   * @returns {Promise<DeviceAssociationResponse>} - A promise that resolves to the registration response.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+    serialNumber: string,
+    deviceName: string = "",
+    deviceRoom: string = "",
+  ): Promise<DeviceAssociationResponse> => {
+    const body: DeviceAssociationBody = {
+      macAddress: macAddress.replace(/:/g, ""),
+      deviceName,
+      deviceRoom,
+      serialNumber,
+    };
+    const response = await axiosInstance.post<DeviceAssociationResponse>(
+      "device",
+      body,
+      { headers: headers(jwtToken) },
+    );
+    return response.data;
+  };
+
+const editDevice =
+  (axiosInstance: AxiosInstance) =>
+  /**
+   * Updates a device's name and room.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device (colons optional).
+   * @param {string} deviceName - New name for the device (default: empty string).
+   * @param {string} deviceRoom - New room for the device (default: empty string).
+   * @returns {Promise<DeviceAssociationResponse>} - A promise that resolves to the update response.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+    deviceName: string = "",
+    deviceRoom: string = "",
+  ): Promise<DeviceAssociationResponse> => {
+    const normalizedMac = macAddress.replace(/:/g, "");
+    const body: EditDeviceAssociationBody = {
+      deviceName,
+      deviceRoom,
+    };
+    const response = await axiosInstance.put<DeviceAssociationResponse>(
+      `device/${normalizedMac}`,
+      body,
+      { headers: headers(jwtToken) },
+    );
+    return response.data;
+  };
+
 /**
  * Configures the library for API interactions.
  * Initializes API methods with a specified base URL.
@@ -207,6 +322,8 @@ const setTargetTemperature =
 const configure = (baseURL: string = API_URL) => {
   const axiosInstance = axios.create({ baseURL });
   const deviceInfoInstance = deviceInfo(axiosInstance);
+  const registerDeviceInstance = registerDevice(axiosInstance);
+  const editDeviceInstance = editDevice(axiosInstance);
   const setPowerInstance = setPower(axiosInstance);
   const setPowerOffInstance = setPowerOff(axiosInstance);
   const setPowerOnInstance = setPowerOn(axiosInstance);
@@ -217,6 +334,8 @@ const configure = (baseURL: string = API_URL) => {
   const setTargetTemperatureInstance = setTargetTemperature(axiosInstance);
   return {
     deviceInfo: deviceInfoInstance,
+    registerDevice: registerDeviceInstance,
+    editDevice: editDeviceInstance,
     setPower: setPowerInstance,
     setPowerOff: setPowerOffInstance,
     setPowerOn: setPowerOnInstance,
@@ -227,4 +346,11 @@ const configure = (baseURL: string = API_URL) => {
   };
 };
 
-export { configure, createAuthService, headers, signIn };
+export {
+  configure,
+  configureAmplify,
+  createAuthService,
+  getSession,
+  headers,
+  signIn,
+};

package/src/serial-utils.test.ts

@@ -0,0 +1,64 @@
+import { strict as assert } from "assert";
+
+import {
+  serialNumberDisplay,
+  serialNumberFromHex,
+  serialNumberToHex,
+} from "./serial-utils";
+
+describe("serial-utils", () => {
+  describe("serialNumberToHex", () => {
+    it("should convert ASCII string to hex", () => {
+      assert.equal(serialNumberToHex("EDK123"), "45444b313233");
+    });
+
+    it("should handle empty string", () => {
+      assert.equal(serialNumberToHex(""), "");
+    });
+
+    it("should convert string with non-printable chars", () => {
+      const input = "EDK\x00123";
+      const hex = serialNumberToHex(input);
+      assert.equal(hex, "45444b00313233");
+    });
+  });
+
+  describe("serialNumberFromHex", () => {
+    it("should convert hex back to ASCII string", () => {
+      assert.equal(serialNumberFromHex("45444b313233"), "EDK123");
+    });
+
+    it("should handle empty string", () => {
+      assert.equal(serialNumberFromHex(""), "");
+    });
+
+    it("should round-trip with toHex", () => {
+      const original = "EDK\x00123\x1F";
+      const hex = serialNumberToHex(original);
+      const restored = serialNumberFromHex(hex);
+      assert.equal(restored, original);
+    });
+  });
+
+  describe("serialNumberDisplay", () => {
+    it("should remove non-printable characters", () => {
+      assert.equal(serialNumberDisplay("EDK\x00123\x1F"), "EDK123");
+    });
+
+    it("should collapse whitespace", () => {
+      assert.equal(serialNumberDisplay("EDK  123"), "EDK 123");
+    });
+
+    it("should trim leading and trailing whitespace", () => {
+      assert.equal(serialNumberDisplay("  EDK123  "), "EDK123");
+    });
+
+    it("should handle empty string", () => {
+      assert.equal(serialNumberDisplay(""), "");
+    });
+
+    it("should preserve normal serial numbers", () => {
+      assert.equal(serialNumberDisplay("EDK12345678"), "EDK12345678");
+    });
+  });
+});

package/src/serial-utils.ts

@@ -0,0 +1,50 @@
+/**
+ * Converts a raw serial number string to hex-encoded format.
+ * This is useful when serial numbers contain non-printable characters.
+ *
+ * @param serial - The raw serial number string
+ * @returns Hex-encoded string representation
+ *
+ * @example
+ * serialNumberToHex("EDK123") // returns "45444b313233"
+ */
+const serialNumberToHex = (serial: string): string => {
+  return Buffer.from(serial, "utf-8").toString("hex");
+};
+
+/**
+ * Converts a hex-encoded serial number back to raw string format.
+ *
+ * @param hex - The hex-encoded serial number
+ * @returns Raw serial number string
+ *
+ * @example
+ * serialNumberFromHex("45444b313233") // returns "EDK123"
+ */
+const serialNumberFromHex = (hex: string): string => {
+  return Buffer.from(hex, "hex").toString("utf-8");
+};
+
+/**
+ * Produces a display-friendly version of a serial number by removing
+ * non-printable characters and collapsing whitespace.
+ *
+ * @param serial - The raw serial number string
+ * @returns Display-friendly serial number
+ *
+ * @example
+ * serialNumberDisplay("EDK\x00123\x1F") // returns "EDK123"
+ */
+const serialNumberDisplay = (serial: string): string => {
+  // Remove non-printable characters (ASCII 0-31, 127)
+  // Keep printable ASCII (32-126) and extended characters
+  return (
+    serial
+      // eslint-disable-next-line no-control-regex
+      .replace(/[\x00-\x1F\x7F]/g, "")
+      .replace(/\s+/g, " ")
+      .trim()
+  );
+};
+
+export { serialNumberDisplay, serialNumberFromHex, serialNumberToHex };

package/src/token-storage.ts

@@ -0,0 +1,78 @@
+import { promises as fs } from "fs";
+import * as os from "os";
+import * as path from "path";
+
+const TOKEN_DIR = path.join(os.homedir(), ".edilkamin");
+const TOKEN_FILE = path.join(TOKEN_DIR, "session.json");
+
+interface StoredData {
+  [key: string]: string;
+}
+
+/**
+ * Custom storage adapter for AWS Amplify that persists to file system.
+ * Used for CLI to maintain sessions between invocations.
+ */
+export const createFileStorage = () => {
+  let cache: StoredData = {};
+  let loaded = false;
+
+  const ensureDir = async (): Promise<void> => {
+    try {
+      await fs.mkdir(TOKEN_DIR, { recursive: true, mode: 0o700 });
+    } catch {
+      // Directory may already exist
+    }
+  };
+
+  const load = async (): Promise<void> => {
+    if (loaded) return;
+    try {
+      const data = await fs.readFile(TOKEN_FILE, "utf-8");
+      cache = JSON.parse(data);
+    } catch {
+      cache = {};
+    }
+    loaded = true;
+  };
+
+  const save = async (): Promise<void> => {
+    await ensureDir();
+    await fs.writeFile(TOKEN_FILE, JSON.stringify(cache), {
+      encoding: "utf-8",
+      mode: 0o600,
+    });
+  };
+
+  return {
+    setItem: async (key: string, value: string): Promise<void> => {
+      await load();
+      cache[key] = value;
+      await save();
+    },
+    getItem: async (key: string): Promise<string | null> => {
+      await load();
+      return cache[key] ?? null;
+    },
+    removeItem: async (key: string): Promise<void> => {
+      await load();
+      delete cache[key];
+      await save();
+    },
+    clear: async (): Promise<void> => {
+      cache = {};
+      await save();
+    },
+  };
+};
+
+/**
+ * Clears all stored session data.
+ */
+export const clearSession = async (): Promise<void> => {
+  try {
+    await fs.unlink(TOKEN_FILE);
+  } catch {
+    // File may not exist
+  }
+};

package/src/types.ts

@@ -1,3 +1,12 @@
+/**
+ * Represents a Node.js Buffer object serialized to JSON.
+ * This format is used by the Edilkamin API for gzip-compressed fields.
+ */
+interface BufferEncodedType {
+  type: "Buffer";
+  data: number[];
+}
+
 interface CommandsType {
   power: boolean;
 }
@@ -27,9 +36,60 @@ interface DeviceInfoType {
   };
 }
 
+/**
+ * Raw device info response that may contain Buffer-encoded compressed fields.
+ * Used internally before processing; external callers receive DeviceInfoType.
+ */
+interface DeviceInfoRawType {
+  status: StatusType | BufferEncodedType;
+  nvm:
+    | {
+        user_parameters: UserParametersType;
+      }
+    | BufferEncodedType;
+  component_info?: BufferEncodedType | Record<string, unknown>;
+}
+
+/**
+ * Request body for registering a device with a user account.
+ * All fields are required by the API.
+ */
+interface DeviceAssociationBody {
+  macAddress: string;
+  deviceName: string;
+  deviceRoom: string;
+  serialNumber: string;
+}
+
+/**
+ * Request body for editing a device's name and room.
+ * MAC address is specified in the URL path, not the body.
+ * Serial number cannot be changed after registration.
+ */
+interface EditDeviceAssociationBody {
+  deviceName: string;
+  deviceRoom: string;
+}
+
+/**
+ * Response from device registration endpoint.
+ * Structure based on Android app behavior - may need adjustment after testing.
+ */
+interface DeviceAssociationResponse {
+  macAddress: string;
+  deviceName: string;
+  deviceRoom: string;
+  serialNumber: string;
+}
+
 export type {
+  BufferEncodedType,
   CommandsType,
+  DeviceAssociationBody,
+  DeviceAssociationResponse,
+  DeviceInfoRawType,
   DeviceInfoType,
+  EditDeviceAssociationBody,
   StatusType,
   TemperaturesType,
   UserParametersType,