@fett/synology-api 0.0.1-beta.9 → 0.0.2-beta.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,87 @@
-# Synology Api
+<p align="center">
+  <a >
+    <img width="100" src="assets/logo.png">
+  </a>
+</p>
+<h1 align="center">Javascript Synology Api</h1>
 
-nodejs synology api wrapper
+⚠️ The project is under development ...
 
-## Usage
+Synology Api Javascript 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 or Node.js
+
+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';
 
-// 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
 ```
 
-## API
+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
+```
+
+then you can use it and exec command
+
+```bash
+syno config use newConnetionName
+
+syno fs getInfo --pretty # print file system info
+
+```
 
-### FileStation
+## License
 
-### AudioStation
+[MIT](https://github.com/ChrisSong1994/synology-api/blob/main/LICENSE)

package/lib/cli/apis.d.ts

@@ -0,0 +1,7 @@
+export type MethodOptions = {
+    params?: string;
+    pretty?: boolean;
+    list?: boolean;
+};
+export declare const onMethodCall: (module: string) => (method: string, options: MethodOptions) => Promise<void>;
+export declare const apiCmdRegister: () => void;

package/lib/cli/apis.js

@@ -0,0 +1,57 @@
+import { program } from "commander";
+import chalk from "chalk";
+import { loadConfig } from "./config.js";
+import { SynologyApi } from "../core.js";
+import { SynologyApiModules, SynologyApiMethods } from "../modules/index.js";
+import { printMessages } from "./helper.js";
+export const onMethodCall = (module) => async (method, options) => {
+    const config = await loadConfig();
+    const params = JSON.parse(options.params || "{}");
+    const pretty = options.pretty;
+    const connection = config.connections?.[config.used];
+    if (!connection) {
+        throw new Error("Connection undefined");
+    }
+    if (!SynologyApiMethods[module]) {
+        throw new Error(`Module ${module} not found`);
+    }
+    // list all module methods
+    if (!method && options.list) {
+        const methods = SynologyApiMethods[module];
+        console.log(chalk.greenBright(`${module} methods list:`));
+        return printMessages(Object.keys(methods));
+    }
+    if (!SynologyApiMethods[module]?.[method]) {
+        throw new Error(`Module method ${module} not found`);
+    }
+    if (typeof SynologyApiMethods[module][method] !== "function") {
+        throw new Error(`Module method ${module} is not a function`);
+    }
+    const synologyApi = new SynologyApi(connection);
+    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 = SynologyApiModules.map((module) => ({
+    cmd: module.KEY,
+    alias: module.ALIAS_KEY,
+}));
+export const apiCmdRegister = () => {
+    apisCmdRegisterInfo.forEach((info) => {
+        program
+            .command(`${info.cmd} [method]`)
+            .alias(info.alias)
+            .option("-p,--params <params>", `${info.cmd} method params`)
+            .option("--pretty", "Prettyprint JSON Output")
+            .option("-l,--list", `list all ${info.cmd} methods`)
+            .description(`Synology ${info.cmd} method call`)
+            .action(onMethodCall(info.cmd));
+    });
+};

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

@@ -9,5 +9,4 @@ export type Config = {
 };
 export declare const loadConfig: () => Promise<Config>;
 export declare const updateConfig: (config: Config) => Promise<void>;
-export declare const checkConfig: () => Promise<void>;
 export declare const configCmdRegister: () => void;

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

@@ -1,47 +1,36 @@
-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);
-});
-// check config
-export const checkConfig = () => __awaiter(void 0, void 0, void 0, function* () { });
+export const updateConfig = async (config) => {
+    await fse.writeJSON(CONFIG_FILE_PATH, config);
+};
 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,32 +46,38 @@ export const configCmdRegister = () => {
                 connection.password);
         });
         printMessages(messages);
-    }));
+    });
     // add connection
     configCmd
-        .command("add [name]")
+        .command("add <name>")
         .description("Add connection config")
         .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 = {
+            used: config.used || name,
+            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]")
+        .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 +85,15 @@ export const configCmdRegister = () => {
             return;
         }
         config.used = name;
-        yield updateConfig(config);
-    }));
+        await updateConfig(config);
+    });
     // del connection
     configCmd
-        .command("del [name]")
+        .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 +103,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 +120,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.d.ts

@@ -0,0 +1,5 @@
+/**
+ * bind methods to BaseSynologyApi prototype
+ * @param source
+ */
+export declare function BindMethods<T extends object>(source: T): ClassDecorator;

package/lib/decorators/bindMethods.js

@@ -0,0 +1,29 @@
+// bind methods to  context
+function methodsBundler(cxt, methods) {
+    const output = {};
+    for (const key in methods) {
+        output[key] = methods[key].bind(cxt);
+    }
+    return output;
+}
+/**
+ * bind methods to BaseSynologyApi prototype
+ * @param source
+ */
+export function BindMethods(source) {
+    return function (target) {
+        const modulesKeys = Object.getOwnPropertyNames(source);
+        modulesKeys.forEach((moduleName) => {
+            const methods = source[moduleName];
+            const descriptor = {
+                configurable: false,
+                enumerable: true,
+                get() {
+                    return methodsBundler(this, methods);
+                },
+                set() { },
+            };
+            Object.defineProperty(target.prototype, moduleName, descriptor);
+        });
+    };
+}

package/lib/decorators/index.d.ts

@@ -0,0 +1 @@
+export * from "./bindMethods.js";

package/lib/decorators/index.js

@@ -0,0 +1 @@
+export * from "./bindMethods.js";

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",
+        },
+    };
 };