@fett/synology-api 0.0.2 → 0.0.3

package/README.md

@@ -7,7 +7,9 @@
 
 ⚠️ The project is under development ...
 
-Synology Api Javascript wrapper, can be used in Browser、CLI or Nodejs to interact with Synology NAS.
+**API Document:** [chrissong1994.github.io/synology-api/](chrissong1994.github.io/synology-api/)
+
+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)
 
@@ -17,21 +19,58 @@ All apis from [https://kb.synology.cn](https://kb.synology.cn/zh-cn/search?query
 npm install @fett/synology-api
 ```
 
+## Configuration
+
+`SynologyApi` instance parameters description
+
+|       Parameter        |        Type         | Description                                                  | Default |
+| :--------------------: | :-----------------: | :----------------------------------------------------------- | :-----: |
+|         server         |       string        | Synology NAS address or QuickConnectId                       |    -    |
+| quickConnectServerType | proxy \| wan \| lan | QuickConnect server type when connecting via QuickConnect ID |  proxy  |
+|        username        |       string        | Synology NAS username                                        |    -    |
+|        password        |       string        | Synology NAS password                                        |    -    |
+
+You can choose to connect to the Synology server using either a **QuickConnectId** or **Synology server address**, for example:
+
+### Connect via QuickConnectId
+
+```js
+const synologyApi = new SynologyApi({
+  server: "QuickConnectId",
+  quickConnectServerType: "lan", // my server is in LAN
+  username: "username",
+  password: "password",
+});
+```
+
+### Connect via Synology server address
+
+```js
+const synologyApi = new SynologyApi({
+  server: "https://192.168.1.1:5001",
+  username: "username",
+  password: "password",
+});
+```
+
 ## Use In Browser or Node.js
 
+```bash
+npm install @fett/synology-api
+```
+
 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';
 
 const synologyApi = new SynologyApi(
-    server: "https://192.168.1.1:5001",
+  server: "https://192.168.1.1:5001", // or QuickConnectId
   username: "username",
   password: "password",
 );
 
 const info = await synologyApi.FileStation.getInfo();
-console.log(info);
 ```
 
 ## Use In CLI
@@ -70,13 +109,13 @@ Commands:
 add a connect configuration
 
 ```bash
-syno config add newConnetionName --server=https://192.168.1.1:5001 --username=admin --password=password
+syno config add ConnetionName --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 config use ConnetionName
 
 syno fs getInfo --pretty # print file system info
 

package/lib/core.d.ts

@@ -1,5 +1,6 @@
 import { AxiosRequestConfig } from "axios";
 import { BaseSynologyApi } from "./modules/index.js";
+import { QuickConnectServerType } from "./types/index.js";
 interface Agent {
     http?: {
         host: string;
@@ -14,6 +15,7 @@ export interface SynologyApiOptions {
     server: string;
     username: string;
     password: string;
+    quickConnectServerType?: QuickConnectServerType;
     agent?: Agent;
 }
 export interface SynologyApiInfoData {
@@ -35,6 +37,7 @@ export declare class SynologyApi extends BaseSynologyApi {
     agent?: Agent;
     baseUrl: string;
     isConnecting: boolean;
+    quickConnectServerType?: QuickConnectServerType;
     private authInfo;
     private apiInfo;
     constructor(options: SynologyApiOptions);

package/lib/core.js

@@ -6,6 +6,7 @@ import { isHttpUrl, getApiKey, isUndfined } from "./utils/index.js";
 import { getServerInfo } from "./helpers.js";
 import { login, logout, getApiInfo } from "./modules/Api/index.js";
 import { resWithErrorCode } from "./errorcodes.js";
+import { QuickConnectServerType } from "./types/index.js";
 export class SynologyApi extends BaseSynologyApi {
     constructor(options) {
         super();
@@ -15,13 +16,14 @@ export class SynologyApi extends BaseSynologyApi {
         this.server = options.server;
         this.username = options.username;
         this.password = options.password;
+        this.quickConnectServerType = options.quickConnectServerType ?? QuickConnectServerType.proxy;
         this.baseUrl = `${this.server}/webapi/`;
         this.agent = options.agent ?? undefined;
     }
     async connect() {
         // if quickconnect id
         if (!isHttpUrl(this.server)) {
-            this.server = await getServerInfo(this.server);
+            this.server = await getServerInfo(this.server, this.quickConnectServerType);
             this.baseUrl = `${this.server}/webapi/`;
         }
         try {

package/lib/helpers.d.ts

@@ -1,3 +1,4 @@
+import { QuickConnectServerType } from "./types/index.js";
 export type ServerInfo = {
     env: {
         control_host: string;
@@ -15,5 +16,5 @@ export type ServerInfo = {
         relay_port: number;
     };
 };
-export declare const getServerInfo: (quickConnectId: string) => Promise<string>;
+export declare const getServerInfo: (quickConnectId: string, quickConnectServerType: QuickConnectServerType) => Promise<any>;
 export declare const pingpang: (server: string) => Promise<boolean>;

package/lib/helpers.js

@@ -1,33 +1,40 @@
 import Axios from "axios";
 import { GLOBAL_QUICK_CONNECT_URL, QUICK_CONNECT_PINGPANG_API } from "./constants.js";
-const getServersFromServerInfo = async (serverInfo) => {
-    // first lan ip
-    // lan ip
-    if (serverInfo?.server?.interface?.[0]) {
-        const server = `http://${serverInfo.server.interface?.[0].ip}:${serverInfo.service.port}`;
-        const res = await pingpang(server);
-        if (res) {
-            return server;
-        }
+import { QuickConnectServerType } from "./types/index.js";
+const getServersFromServerInfo = async (serverInfo, quickConnectServerType) => {
+    const serverMap = {
+        [QuickConnectServerType.proxy]: undefined,
+        [QuickConnectServerType.lan]: undefined,
+        [QuickConnectServerType.wan]: undefined,
+    };
+    // proxy server
+    if (serverInfo?.service?.relay_ip) {
+        serverMap[QuickConnectServerType.proxy] =
+            `http://${serverInfo.service.relay_ip}:${serverInfo.service.relay_port}`;
     }
     // WAN IP
     if (serverInfo?.server?.external?.ip) {
-        const server = `http://${serverInfo.server.external.ip}:${serverInfo.service.port}`;
-        const res = await pingpang(server);
-        if (res) {
-            return server;
-        }
+        serverMap[QuickConnectServerType.wan] =
+            `http://${serverInfo.server.external.ip}:${serverInfo.service.port}`;
     }
-    // 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]) {
+        serverMap[QuickConnectServerType.lan] =
+            `http://${serverInfo.server.interface?.[0].ip}:${serverInfo.service.port}`;
+    }
+    const server = serverMap[quickConnectServerType];
+    if (!server) {
+        return Promise.reject(`${quickConnectServerType} server not found`);
+    }
+    const res = await pingpang(server);
+    if (!res) {
+        return Promise.reject(`${server} server can not connect`);
+    }
+    if (res) {
+        return server;
     }
 };
-export const getServerInfo = async (quickConnectId) => {
+export const getServerInfo = async (quickConnectId, quickConnectServerType) => {
     const params = {
         version: 1,
         id: "dsm",
@@ -44,11 +51,12 @@ export const getServerInfo = async (quickConnectId) => {
             platform: "web",
             command: "request_tunnel",
         };
+        // get replay tunnel
         const result = (await Axios.post(`https://${serverInfo.env.control_host}/Serv.php`, relayRequestParams)).data;
-        return getServersFromServerInfo(result);
+        return getServersFromServerInfo(result, quickConnectServerType);
     }
     else {
-        return getServersFromServerInfo(serverInfo);
+        return getServersFromServerInfo(serverInfo, quickConnectServerType);
     }
 };
 // pingpang

package/lib/types/core.d.ts

@@ -0,0 +1,8 @@
+/**
+ * quick connect server type
+ * */
+export declare enum QuickConnectServerType {
+    proxy = "proxy",// proxy server
+    wan = "wan",// wan server
+    lan = "lan"
+}

package/lib/types/core.js

@@ -0,0 +1,9 @@
+/**
+ * quick connect server type
+ * */
+export var QuickConnectServerType;
+(function (QuickConnectServerType) {
+    QuickConnectServerType["proxy"] = "proxy";
+    QuickConnectServerType["wan"] = "wan";
+    QuickConnectServerType["lan"] = "lan";
+})(QuickConnectServerType || (QuickConnectServerType = {}));

package/lib/types/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./request.js";
 export * from "./apiInfo.js";
+export * from "./core.js";

package/lib/types/index.js

@@ -1,2 +1,3 @@
 export * from "./request.js";
 export * from "./apiInfo.js";
+export * from "./core.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fett/synology-api",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "synology api for nodejs",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",