feat: update documentation

proohit · Nov 19, 2022 · fdd2689 · fdd2689
1 parent c80fe20
commit fdd2689
Show file tree

Hide file tree

Showing 3 changed files with 150 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -57,9 +57,11 @@ After logging in to [Netcup CCP](https://www.customercontrolpanel.de/), navigate
 
 The default exported `NetcupApi` is a wrapper around the actual api. It handles authentication and passes parameters to the implemented api.
 
+#### ESM
+
 ```javascript
 import NetcupApi from 'netcup-node';
-const api = await new Netcup().init({
+const api = await new NetcupApi().init({
   apikey: 'YOUR_API_KEY',
   apipassword: 'YOUR_API_PASSWORD',
   customernumber: 'YOUR_CUSTOMER_NUMBER',
@@ -84,3 +86,95 @@ const dnsRecords = await api.infoDnsRecords({
   domainname: 'YOUR.DOMAIN',
 });
 ```
+
+#### CJS
+
+```javascript
+const NetcupApi = require('netcup-node').default;
+// or const { NetcupApi } = require('netcup-node');
+
+const api = await new NetcupApi().init({
+  apikey: 'YOUR_API_KEY',
+  apipassword: 'YOUR_API_PASSWORD',
+  customernumber: 'YOUR_CUSTOMER_NUMBER',
+});
+const dnsInfo = await api.infoDnsZone({ domainname: 'YOUR.DOMAIN' });
+```
+
+### Reference
+
+```javascript
+/**
+ * Initializes authentication parameters
+ */
+NetcupApi.init({
+  apikey: 'YOUR_API_KEY',
+  apipassword: 'YOUR_API_PASSWORD',
+  customernumber: 'YOUR_CUSTOMER_NUMBER',
+});
+
+/**
+ * Retrieves information about a DNS zone
+ * */
+NetcupApi.infoDnsZone({
+  domainname: 'YOUR.DOMAIN',
+});
+
+/**
+ * Retrieves information about DNS records of a domain
+ * */
+NetcupApi.infoDnsRecords({
+  domainname: 'YOUR.DOMAIN',
+});
+
+/**
+ * Updates DNS records of a domain and only those that are specified.
+ */
+NetcupApi.updateDnsRecords({
+  domainname: 'example.com',
+  dnsrecordset: {
+    dnsrecords: [{ name: 'www', type: 'A', destination: 'some-ip' }],
+  },
+});
+// can also be used for deletion
+NetcupApi.updateDnsRecords({
+  domainname: 'example.com',
+  dnsrecordset: {
+    dnsrecords: [
+      { name: 'www', type: 'A', destination: 'some-ip', deleterecord: true },
+    ],
+  },
+});
+
+/**
+ * Updates DNS records of a domain with the current public ip.
+ * @example
+ * // update ipv4 only
+ * await api.updateDnsRecordsWithCurrentIp({ domainname: 'example.com', dnsrecords: [{ hostname: 'www' }] })
+ * @example
+ *  // update ipv4 and ipv6
+ *  await api.updateDnsRecordsWithCurrentIp({ domainname: 'example.com', dnsrecords: [{ hostname: 'www' }], useIpv4AndIpv6: true })
+ * @example
+ * // update ipv6 only
+ * await api.updateDnsRecordsWithCurrentIp({ domainname: 'example.com', dnsrecords: [{ hostname: 'www' }], useIpv6Only: true })
+ */
+// update ipv4 only
+NetcupApi.updateDnsRecordWithCurrentIp({
+  domainname: 'example.com',
+  dnsrecordset: { dnsrecords: [{ hostname: 'www' }] },
+});
+
+// update ipv4 and ipv6
+NetcupApi.updateDnsRecordWithCurrentIp({
+  domainname: 'example.com',
+  dnsrecordset: { dnsrecords: [{ hostname: 'www' }] },
+  useIpv4AndIpv6: true,
+});
+
+// update ipv6 only
+NetcupApi.updateDnsRecordWithCurrentIp({
+  domainname: 'example.com',
+  dnsrecordset: { dnsrecords: [{ hostname: 'www' }] },
+  useIpv6Only: true,
+});
+```
diff --git a/src/index.ts b/src/index.ts
@@ -40,6 +40,9 @@ class NetcupApi {
     }
   }
 
+  /**
+   * Initializes authentication parameters
+   */
   public async init(params: InitParams): Promise<NetcupApi> {
     if (params.format && !Object.values(Formats).includes(params.format)) {
       throw new Error(INVALID_FORMAT_ERROR);
@@ -53,6 +56,10 @@ class NetcupApi {
     return this;
   }
 
+  /**
+   * Returns information about the DNS zone of a domain
+   * @example await api.infoDnsZone({ domainname: 'example.com' })
+   */
   public async infoDnsZone(
     params: Pick<InfoDNSZoneParam, 'domainname'>,
   ): Promise<InfoDNSZoneResponse> {
@@ -65,6 +72,10 @@ class NetcupApi {
     });
   }
 
+  /**
+   * Returns information about the DNS records of a domain
+   * @example await api.infoDnsRecords({ domainname: 'example.com' })
+   */
   public async infoDnsRecords(
     params: Pick<InfoDNSRecordsParam, 'domainname'>,
   ): Promise<InfoDNSRecordsResponse> {
@@ -77,6 +88,26 @@ class NetcupApi {
     });
   }
 
+  /**
+   * Updates DNS records of a domain and only those that are specified.
+   * @example
+   *  await api.updateDnsRecords({
+        domainname: 'example.com',
+        dnsrecordset: {
+          dnsrecords: [{ name: 'www', type: 'A', destination: 'some-ip' }],
+        },
+      })
+   * @example
+   * // can also be used to delete records
+   * await api.updateDnsRecords({
+      domainname: 'example.com',
+      dnsrecordset: {
+        dnsrecords: [
+          { name: 'www', type: 'A', destination: 'some-ip', deleterecord: true },
+        ],
+      },
+    })
+   */
   public async updateDnsRecords(
     params: Pick<UpdateDNSRecordsParam, 'dnsrecordset' | 'domainname'>,
   ): Promise<UpdateDNSRecordsResponse> {
@@ -89,6 +120,29 @@ class NetcupApi {
     });
   }
 
+  /**
+   * Updates DNS records of a domain with the current public ip.
+   * @example
+   * // update ipv4 only
+   * await api.updateDnsRecordsWithCurrentIp({
+      domainname: 'example.com',
+      dnsrecordset: { dnsrecords: [{ hostname: 'www' }] },
+    })
+   * @example
+   *  // update ipv4 and ipv6
+   *  await api.updateDnsRecordsWithCurrentIp({
+      domainname: 'example.com',
+      dnsrecordset: { dnsrecords: [{ hostname: 'www' }] },
+      useIpv4AndIpv6: true,
+    })
+   * @example
+   * // update ipv6 only
+   * await api.updateDnsRecordsWithCurrentIp({
+      domainname: 'example.com',
+      dnsrecordset: { dnsrecords: [{ hostname: 'www' }] },
+      useIpv6Only: true,
+    })
+   */
   public async updateDnsRecordWithCurrentIp(
     params: UpdateDnsRecordWithCurrentIpParams,
   ): Promise<UpdateDNSRecordsResponse> {
@@ -137,8 +191,6 @@ class NetcupApi {
   }
 }
 
-// EXPORTS
-
 export * from './@types';
 export { NetcupRestApi, NetcupApi };
 

diff --git a/tsconfig.json b/tsconfig.json
@@ -9,6 +9,7 @@
     "declarationDir": "lib/types",
     "importHelpers": true,
     "alwaysStrict": true,
+    "removeComments": false,
     "forceConsistentCasingInFileNames": true,
     "noFallthroughCasesInSwitch": true,
     "noImplicitReturns": false,