@fett/synology-api 0.0.1-beta.9 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris Song
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,26 +1,97 @@
 # Synology Api
 
-nodejs synology api wrapper
+⚠️ The project is under development ...
 
-## Usage
+[中文文档](./README-zh_CN.md)
+Synology Api Node.js wrapper, can be used in Browser、CLI or Nodejs to interact with Synology NAS.
+You can use domain or ip address, also supports Synology Quick Connect connect Synology server.
+All apis from [https://kb.synology.cn](https://kb.synology.cn/zh-cn/search?query=API&services%5B%5D=File_Station)
+
+## Install
+
+```
+npm install @fett/synology-api
+```
+
+## Use In Browser
+
+First you need to confirm that you can access across domains,for example in the React Native environment
+
+```js
+import { SynologyApi } from "@fett/synology-api/browser";
+// Create a new instance
+const api = new SynologyApi({
+  server: "https://192.168.1.1:5001",
+  username: "username",
+  password: "password",
+});
+// you can now use the api by calling the methods
+const info = await api.fs.getInfo();
+console.log(info);
+```
+
+## Use In Node.js
 
 ```js
 import SynologyApi from '@fett/synology-api';
 
-// Create a new instance
 const synologyApi = new SynologyApi(
-     server: "https:192.168.1.1:5001",
-    username: "admin",
-    password: "password",
+    server: "https://192.168.1.1:5001",
+  username: "username",
+  password: "password",
 );
 
-// you can now use the api by calling the methods
 const info = await synologyApi.FileStation.getInfo();
+console.log(info);
+```
+
+## Use In CLI
 
+First install the package globally
+
+```bash
+npm i -g @fett/synology-api
+```
+
+Then run cmd help message
+
+```bash
+syno --help
+```
+
+run `syno config -h` you will see the help message
+
+```bash
+Usage: synology config [options] [command]
+
+synology api config management
+
+Options:
+  -h, --help               display help for command
+
+Commands:
+  ls                       List all the connection config
+  add [options] [name]     Add connection config
+  use [name]               Change current connection
+  del [name]               Remove a connection
+  rename <name> <newName>  Change connection name
+  help [command]           display help for command
+```
+
+add a connect configuration
+
+```bash
+syno config add newConnetionName --server=https://192.168.1.1:5001 --username=admin --password=password
 ```
 
-## API
+then you can use it and exec command
+
+```bash
+syno config use newConnetionName
 
-### FileStation
+syno fs getInfo --pretty # print file system info
+
+```
 
-### AudioStation
+## License
+[MIT](https://github.com/ChrisSong1994/synology-api/blob/main/LICENSE)

package/lib/cli/apis.js

@@ -0,0 +1,47 @@
+import { program } from "commander";
+import { loadConfig } from "./config.js";
+import { SynologyApi } from "../core.js";
+import { SynologyApiKeys } from "../modules/index.js";
+export const onMethodsCall = (module) => async (method, options) => {
+    const config = await loadConfig();
+    const params = JSON.parse(options.params || "{}");
+    const pretty = options.pretty;
+    const synologyApi = new SynologyApi(config.connections[config.used]);
+    if (synologyApi[module]?.[method]) {
+        const result = await synologyApi[module]?.[method](params);
+        if (pretty) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(JSON.stringify(result));
+        }
+    }
+    synologyApi.disconnect();
+    process.exit(0);
+};
+// register all modules
+const apisCmdRegisterInfo = [
+    {
+        cmd: SynologyApiKeys.FileStation,
+        alias: SynologyApiKeys.fs,
+    },
+    {
+        cmd: SynologyApiKeys.AudioStation,
+        alias: SynologyApiKeys.as,
+    },
+    {
+        cmd: SynologyApiKeys.VideoStation,
+        alias: SynologyApiKeys.vs,
+    },
+];
+export const apiCmdRegister = () => {
+    apisCmdRegisterInfo.forEach((info) => {
+        program
+            .command(`${info.cmd} [methods]`)
+            .alias(info.alias)
+            .option("-p,--params <params>", `${info.cmd} methods params`)
+            .option("--pretty", "Prettyprint JSON Output")
+            .description(`Synology ${info.cmd} method call`)
+            .action(onMethodsCall(info.cmd));
+    });
+};

package/lib/{esm/cli → cli}/config.js

@@ -1,47 +1,38 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 import fse from "fs-extra";
 import path from "path";
 import os from "os";
 import { program } from "commander";
 import chalk from "chalk";
-import { isLowerCaseEqual, printMessages, geneDashLine } from "./helper";
+import { isLowerCaseEqual, printMessages, geneDashLine } from "./helper.js";
 const CONFIG_FILE_PATH = process.env.NODE_ENV === "development"
     ? path.join(process.cwd(), "./.userdata/.synology-api.json") // development
     : path.join(os.homedir(), "./.synology-api.json");
 // load config
-export const loadConfig = () => __awaiter(void 0, void 0, void 0, function* () {
-    if (!(yield fse.pathExists(CONFIG_FILE_PATH))) {
-        yield fse.ensureFile(CONFIG_FILE_PATH);
-        yield fse.writeJSON(CONFIG_FILE_PATH, {
+export const loadConfig = async () => {
+    if (!(await fse.pathExists(CONFIG_FILE_PATH))) {
+        await fse.ensureFile(CONFIG_FILE_PATH);
+        await fse.writeJSON(CONFIG_FILE_PATH, {
             used: "",
             connections: {},
         });
     }
-    const config = yield fse.readJSON(CONFIG_FILE_PATH);
+    const config = await fse.readJSON(CONFIG_FILE_PATH);
     return config;
-});
+};
 // update config
-export const updateConfig = (config) => __awaiter(void 0, void 0, void 0, function* () {
-    yield fse.writeJSON(CONFIG_FILE_PATH, config);
-});
+export const updateConfig = async (config) => {
+    await fse.writeJSON(CONFIG_FILE_PATH, config);
+};
 // check config
-export const checkConfig = () => __awaiter(void 0, void 0, void 0, function* () { });
+export const checkConfig = async () => { };
 export const configCmdRegister = () => {
     const configCmd = program.command("config").description("synology api config management");
     // list connection config
     configCmd
         .command("ls")
         .description("List all the connection config")
-        .action(() => __awaiter(void 0, void 0, void 0, function* () {
-        const config = yield loadConfig();
+        .action(async () => {
+        const config = await loadConfig();
         const keys = Object.keys(config.connections);
         const dashLineLength = Math.max(...keys.map((key) => key.length)) + 3;
         const messages = keys.map((key) => {
@@ -57,7 +48,7 @@ export const configCmdRegister = () => {
                 connection.password);
         });
         printMessages(messages);
-    }));
+    });
     // add connection
     configCmd
         .command("add [name]")
@@ -65,24 +56,30 @@ export const configCmdRegister = () => {
         .requiredOption("-s, --server <server>", "Synology server domain  or QuickConnect ID ")
         .requiredOption("-u, --username <username>", "username")
         .requiredOption("-p,  --password <password>", "password")
-        .action((name, options) => __awaiter(void 0, void 0, void 0, function* () {
+        .action(async (name, options) => {
         if (!name.trim())
             throw new Error("Plaease input connection name");
         // 实际代码中应保存配置到文件
-        const config = yield loadConfig();
-        const newConfig = Object.assign(Object.assign({}, config), { connections: Object.assign(Object.assign({}, config.connections), { [name]: {
+        const config = await loadConfig();
+        const newConfig = {
+            ...config,
+            connections: {
+                ...config.connections,
+                [name]: {
                     server: options.server,
                     username: options.username,
                     password: options.password,
-                } }) });
-        yield updateConfig(newConfig);
-    }));
+                },
+            },
+        };
+        await updateConfig(newConfig);
+    });
     // use  connection
     configCmd
         .command("use [name]")
         .description("Change current connection")
-        .action((name) => __awaiter(void 0, void 0, void 0, function* () {
-        const config = yield loadConfig();
+        .action(async (name) => {
+        const config = await loadConfig();
         if (config.used === name)
             return;
         if (!config.connections[name]) {
@@ -90,15 +87,15 @@ export const configCmdRegister = () => {
             return;
         }
         config.used = name;
-        yield updateConfig(config);
-    }));
+        await updateConfig(config);
+    });
     // del connection
     configCmd
         .command("del [name]")
         .description("Remove a connection")
-        .action((name) => __awaiter(void 0, void 0, void 0, function* () {
+        .action(async (name) => {
         console.log("Remove a connection", name);
-        const config = yield loadConfig();
+        const config = await loadConfig();
         // 删除配置
         if (!config.connections[name]) {
             console.log("Connection not found");
@@ -108,14 +105,14 @@ export const configCmdRegister = () => {
         if (config.used === name) {
             config.used = "";
         }
-        yield updateConfig(config);
-    }));
+        await updateConfig(config);
+    });
     // Change connection name
     configCmd
         .command("rename <name> <newName>")
         .description("Change connection name")
-        .action((name, newName) => __awaiter(void 0, void 0, void 0, function* () {
-        const config = yield loadConfig();
+        .action(async (name, newName) => {
+        const config = await loadConfig();
         if (!config.connections[name]) {
             console.log("Connection not found");
             return;
@@ -125,6 +122,6 @@ export const configCmdRegister = () => {
         if (config.used === name) {
             config.used = newName;
         }
-        yield updateConfig(config);
-    }));
+        await updateConfig(config);
+    });
 };

package/lib/cli/core.js

@@ -0,0 +1,20 @@
+import fse from "fs-extra";
+import path from "path";
+import { program } from "commander";
+import { configCmdRegister } from "./config.js";
+import { apiCmdRegister } from "./apis.js";
+import { __dirname } from "./helper.js";
+export async function loadCli() {
+    // git program info
+    const pkg = await fse.readJSON(path.join(__dirname(), "../../package.json"));
+    // command
+    program
+        .name("synology")
+        .usage("<command> [options]")
+        .description("synology api cli tool")
+        .version(pkg.version, "-v, --version", "output the version number");
+    // register commands
+    configCmdRegister();
+    apiCmdRegister();
+    program.parse(process.argv);
+}

package/lib/{types/cli → cli}/helper.d.ts

@@ -1,3 +1,4 @@
+export declare const __dirname: () => string;
 export declare function printMessages(messages: string[]): void;
 export declare function isLowerCaseEqual(str1: string, str2: string): boolean;
 export declare function padding(message?: string, before?: number, after?: number): string;

package/lib/{esm/cli → cli}/helper.js

@@ -1,4 +1,10 @@
 import chalk from "chalk";
+import { fileURLToPath } from "url";
+import { dirname } from "path";
+export const __dirname = () => {
+    const __filename = fileURLToPath(import.meta.url);
+    return dirname(__filename);
+};
 export function printMessages(messages) {
     console.log(messages.join("\n"));
 }
@@ -8,12 +14,10 @@ export function isLowerCaseEqual(str1, str2) {
     }
     return !str1 && !str2;
 }
-export function padding(message = '', before = 1, after = 1) {
-    return (new Array(before).fill(' ').join('') +
-        message +
-        new Array(after).fill(' ').join(''));
+export function padding(message = "", before = 1, after = 1) {
+    return new Array(before).fill(" ").join("") + message + new Array(after).fill(" ").join("");
 }
 export function geneDashLine(message, length) {
-    const finalMessage = new Array(Math.max(2, length - message.length + 2)).join('-');
+    const finalMessage = new Array(Math.max(2, length - message.length + 2)).join("-");
     return padding(chalk.dim(finalMessage));
 }

package/lib/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/cli/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { loadCli } from "./core.js";
+(async () => {
+    await loadCli();
+})();

package/lib/{types/core.d.ts → core.d.ts}

@@ -1,4 +1,4 @@
-import { BaseSynologyApi } from "./modules";
+import { BaseSynologyApi } from "./modules/index.js";
 export interface SynologyApiOptions {
     server: string;
     username: string;

package/lib/core.js

@@ -0,0 +1,99 @@
+// reference: https://kb.synology.com/zh-tw/DSM/tutorial/What_websites_does_Synology_NAS_connect_to_when_running_services_or_updating_software
+import ky from "ky";
+import { BaseSynologyApi } from "./modules/index.js";
+import { isHttpUrl, getApiKey, isUndfined } from "./utils.js";
+import { getServerInfo } from "./helpers.js";
+import { login, logout, getApiInfo } from "./modules/Api/index.js";
+import { resWithErrorCode } from "./errorcodes.js";
+export class SynologyApi extends BaseSynologyApi {
+    constructor(options) {
+        super();
+        this.isConnecting = false;
+        this.authInfo = null;
+        this.apiInfo = {};
+        this.server = options.server;
+        this.username = options.username;
+        this.password = options.password;
+        this.baseUrl = `${this.server}/webapi/`;
+    }
+    async connect() {
+        // if quickconnect id
+        if (!isHttpUrl(this.server)) {
+            this.server = await getServerInfo(this.server);
+            // reset base url
+            this.baseUrl = `${this.server}/webapi/`;
+        }
+        try {
+            const result = await login(this);
+            this.authInfo = result.data;
+            this.isConnecting = true;
+            await this._getApiInfo();
+            return true;
+        }
+        catch (err) {
+            console.error(err);
+            return false;
+        }
+    }
+    async disconnect() {
+        try {
+            await logout(this);
+            this.authInfo = null;
+            this.apiInfo = {};
+            this.isConnecting = false;
+            return true;
+        }
+        catch (err) {
+            console.error(err);
+            return false;
+        }
+    }
+    async _getApiInfo() {
+        try {
+            const result = await getApiInfo(this);
+            this.apiInfo = result.data;
+        }
+        catch (err) {
+            console.error(err);
+        }
+    }
+    hasApi(apiName) {
+        if (!this.isConnecting) {
+            throw new Error("Not connected");
+        }
+        return Object.prototype.hasOwnProperty.call(this.apiInfo, apiName);
+    }
+    async run(apiName, options) {
+        if (!this.isConnecting) {
+            const res = await this.connect();
+            if (!res) {
+                throw new Error("Not connected");
+            }
+        }
+        if (!this.hasApi(apiName)) {
+            throw new Error(`${apiName} not found`);
+        }
+        const { method = "get", params, data, headers } = options;
+        const api = this.apiInfo[apiName];
+        const url = `${this.baseUrl}${api.path}`;
+        const externalParams = {
+            api: apiName,
+            version: api.maxVersion,
+            _sid: this.authInfo.sid,
+            ...params,
+        };
+        let result = null;
+        if (method === "get") {
+            result = await ky.get(url, { searchParams: externalParams, headers }).json();
+        }
+        if (method === "post") {
+            result = await ky.post(url, { searchParams: externalParams, json: data, headers }).json();
+        }
+        // match error code msg
+        const apiKey = getApiKey(apiName);
+        if (!isUndfined(apiKey)) {
+            result = resWithErrorCode(apiKey, result);
+        }
+        return result;
+    }
+}

package/lib/decorators/bindMethods.js

@@ -0,0 +1,45 @@
+// export type Method = (...args: any[]) => Promise<any>;
+// type MethodKeys<T> = {
+//   [K in keyof T]: {
+//     [M in keyof T[K]]: Method;
+//   };
+// }[keyof T];
+// /**
+//  * 将源对象的方法绑定到目标类的原型上，并确保方法的 this 指向类实例
+//  * @param source 包含要绑定方法的对象
+//  */
+// export function BindMethods<T extends object>(source: T): ClassDecorator {
+//   return function (target: { prototype: any }) {
+//     // 获取源对象的所有方法键
+//     const methodKeys = Object.getOwnPropertyNames(source).filter(
+//       (key): key is MethodKeys<T> => typeof source[key] === "function"
+//     );
+//     // 为每个方法创建绑定版本并定义到原型上
+//     methodKeys.forEach((methodName) => {
+//       const originalMethod = source[methodName] as Function;
+//       // 创建绑定方法的描述符
+//       const descriptor: PropertyDescriptor = {
+//         configurable: true,
+//         enumerable: false, // 使方法不可枚举
+//         // 使用 getter 确保每个实例都有自己的绑定函数
+//         get() {
+//           // 跳过原型访问，直接返回原始方法
+//           if (this === target.prototype || this === undefined) {
+//             return originalMethod;
+//           }
+//           // 为实例创建绑定方法并缓存
+//           const boundMethod = originalMethod.bind(this);
+//           Object.defineProperty(this, methodName, {
+//             value: boundMethod,
+//             configurable: true,
+//             writable: true,
+//             enumerable: false,
+//           });
+//           return boundMethod;
+//         },
+//       };
+//       // 将绑定方法定义到类原型上
+//       Object.defineProperty(target.prototype, methodName, descriptor);
+//     });
+//   };
+// }

package/lib/{types/errorcodes.d.ts → errorcodes.d.ts}

@@ -1,5 +1,5 @@
-import { SynologyApiKeys } from "./modules";
-import { SynologyApiResponse } from "./types";
+import { SynologyApiKeys } from "./modules/index.js";
+import { SynologyApiResponse } from "./types/index.js";
 export declare const SYNOLOGY_ERROR_CODES: {
     [SynologyApiKeys.FileStation]: {
         400: string;

package/lib/{esm/errorcodes.js → errorcodes.js}

@@ -1,5 +1,5 @@
-import { SynologyApiKeys } from "./modules";
-import { isUndfined } from "./utils";
+import { SynologyApiKeys } from "./modules/index.js";
+import { isUndfined } from "./utils.js";
 const CODE_SUCCESS = 0;
 const CODE_UNKNOWN = 9999;
 export const SYNOLOGY_ERROR_CODES = {
@@ -88,10 +88,15 @@ export const SYNOLOGY_ERROR_CODES = {
     },
 };
 export const resWithErrorCode = (apiKey, res) => {
-    var _a, _b;
     const errorCodes = SYNOLOGY_ERROR_CODES[apiKey];
-    const code = (_a = res === null || res === void 0 ? void 0 : res.error) === null || _a === void 0 ? void 0 : _a.code;
+    const code = res?.error?.code;
     if (isUndfined(code))
         return res;
-    return Object.assign(Object.assign({}, res), { error: Object.assign(Object.assign({}, res.error), { message: ((_b = res === null || res === void 0 ? void 0 : res.error) === null || _b === void 0 ? void 0 : _b.message) || (errorCodes === null || errorCodes === void 0 ? void 0 : errorCodes[code]) || "Unknown error" }) });
+    return {
+        ...res,
+        error: {
+            ...res.error,
+            message: res?.error?.message || errorCodes?.[code] || "Unknown error",
+        },
+    };
 };

package/lib/helpers.js

@@ -0,0 +1,70 @@
+import ky from "ky";
+import { GLOBAL_QUICK_CONNECT_URL, QUICK_CONNECT_PINGPANG_API } from "./constants.js";
+const getServersFromServerInfo = async (serverInfo) => {
+    // WAN IP
+    if (serverInfo?.server?.external?.ip) {
+        const server = `http://${serverInfo.server.external.ip}:${serverInfo.service.port}`;
+        if (await pingpang(server)) {
+            return server;
+        }
+    }
+    // proxy server
+    if (serverInfo?.service?.relay_ip) {
+        const server = `http://${serverInfo.service.relay_ip}:${serverInfo.service.relay_port}`;
+        const res = await pingpang(server);
+        if (res) {
+            return server;
+        }
+    }
+    // lan ip
+    if (serverInfo?.server?.interface?.[0]) {
+        const server = `http://${serverInfo.server.interface?.[0].ip}:${serverInfo.service.port}`;
+        if (await pingpang(server)) {
+            return server;
+        }
+    }
+};
+export const getServerInfo = async (quickConnectId) => {
+    const params = {
+        version: 1,
+        id: "dsm",
+        serverID: quickConnectId,
+        get_ca_fingerprints: true,
+        command: "get_server_info",
+    };
+    const serverInfo = await ky.post(GLOBAL_QUICK_CONNECT_URL, { json: params }).json();
+    if (!serverInfo?.service?.relay_ip && !serverInfo?.service?.relay_port) {
+        const relayRequestParams = {
+            version: 1,
+            id: "dsm",
+            serverID: quickConnectId,
+            platform: "web",
+            command: "request_tunnel",
+        };
+        const result = await ky
+            .post(`https://${serverInfo.env.control_host}/Serv.php`, { json: relayRequestParams })
+            .json();
+        return getServersFromServerInfo(result);
+    }
+    else {
+        return getServersFromServerInfo(serverInfo);
+    }
+};
+// pingpang
+export const pingpang = async (server) => {
+    try {
+        const result = await ky
+            .get(`${server}/${QUICK_CONNECT_PINGPANG_API}`)
+            .json();
+        if (result.success) {
+            return true;
+        }
+        else {
+            return false;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    }
+    catch (_err) {
+        return false;
+    }
+};

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+import { SynologyApi } from "./core.js";
+export * from "./types/index.js";
+export * from "./core.js";
+export default SynologyApi;

package/lib/index.js

@@ -0,0 +1,4 @@
+import { SynologyApi } from "./core.js";
+export * from "./types/index.js";
+export * from "./core.js";
+export default SynologyApi;