JSDoc improvements

src/VerifaliaRestClient.ts

@@ -1,3 +1,35 @@
+/**
+ * @license
+ * Verifalia - Email list cleaning and real-time email verification service
+ * https://verifalia.com/
+ * [email protected]
+ * 
+ * Copyright (c) 2005-2021 Cobisi Research
+ * 
+ * Cobisi Research
+ * Via Della Costituzione, 31
+ * 35010 Vigonza
+ * Italy - European Union
+ * 
+ * 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.
+ */
+
 import { EmailValidationsRestClient } from "./email-validations/EmailValidationsRestClient";
 import { RestClientFactory } from "./rest/RestClientFactory";
 import { CreditsRestClient } from "./credits/CreditsRestClient";
@@ -14,25 +46,14 @@ const logger = new Logger('verifalia');
 
 /**
  * HTTPS-based REST client for Verifalia. This is the starting point to every other operation against
- * the Verifalia API, it allows to easily validate email addresses, manage submitted email validation
+ * the Verifalia API, it allows to easily verify email addresses, manage submitted email validation
  * jobs and operate on the credits of the account.
  * 
  * To submit and manage email validations, use the methods exposed by the `emailValidations` field.
  * To manage the credits for the Verifalia account, use the methods exposed by the `credits` field.
  * 
- * This class constructor accepts the credentials of your root Verifalia account or of one of its users
- * (previously known as sub-accounts): if you don't have a Verifalia account, just register for a free
- * one at https://verifalia.com/sign-up/free. For security reasons, it is always advisable to create
- * and use a dedicated user for accessing the API, as doing so will allow to assign only the specific
- * needed permissions to it.
- * 
- * Here is how to create an instance of this class:
- * ```ts
- * const verifalia = new VerifaliaRestClient({
- *   username: 'johndoe',
- *   password: 'mysecretpa$$word'
- * });
- * ```
+ * Using this class requires to have a Verifalia account: if you don't yet have one, just register
+ * for free at https://verifalia.com/sign-up/free
  */
 export class VerifaliaRestClient {
     /**
@@ -67,6 +88,38 @@ export class VerifaliaRestClient {
 
     /**
      * Initializes a new HTTPS-based REST client for Verifalia with the specified configuration.
+     * 
+     * This constructor accepts either the user-name and password credentials of your root
+     * Verifalia account, those of a Verifalia user (previously known as sub-accounts) or a Verifalia
+     * browser app's key. As an alternative to the above, it is also possible to specify an X.509
+     * client certificate for mutual TLS client authentication (only available in Node.js).
+     * 
+     * For security reasons, it is always advisable to create and use a dedicated user for accessing
+     * the Verifalia API, as doing so will allow to assign only the specific needed permissions to it.
+     * 
+     * Here is how to create an instance of this class with a user-name and password pair:
+     * ```ts
+     * const verifalia = new VerifaliaRestClient({
+     *   username: 'johndoe',
+     *   password: 'mysecretpa$$word'
+     * });
+     * ```
+     * 
+     * To use a browser app, pass its app key through the `username` field:
+     * ```ts
+     * const verifalia = new VerifaliaRestClient({
+     *   username: '0a0321de08f54d3caff43951311bf958'
+     * });
+     * ```
+     * 
+     * To authenticate using an X.509 client certificate (only available in Node.js), specify its public
+     * key using the `cert` field and its private key with the `key` field:
+     * ```ts
+     * const verifalia = new VerifaliaRestClient({
+     *   cert: fs.readFileSync('/home/rmontagnani/my-client-certificate.pem'),
+     *   key: fs.readFileSync('/home/rmontagnani/my-client-certificate.key')
+     * });
+     * ```
      *
      * @param config Contains the configuration for the Verifalia API client, including the credentials
      * to use while authenticating to the Verifalia service.

src/VerifaliaRestClientConfiguration.ts

@@ -1,10 +1,43 @@
+/**
+ * @license
+ * Verifalia - Email list cleaning and real-time email verification service
+ * https://verifalia.com/
+ * [email protected]
+ * 
+ * Copyright (c) 2005-2021 Cobisi Research
+ * 
+ * Cobisi Research
+ * Via Della Costituzione, 31
+ * 35010 Vigonza
+ * Italy - European Union
+ * 
+ * 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.
+ */
+
 /* @if TARGET='node' */
 import { KeyObject } from "tls";
 /* @endif */
 
 export interface VerifaliaRestClientConfiguration {
     /**
-     * The username to use while authenticating to the Verifalia API. While using your Verifalia
+     * The username or the browser app key to use while authenticating to the Verifalia API, if
+     * you are authenticating using a Verifalia browser app. While using your Verifalia
      * main account credentials is possible, it is strongly advised to create one or more users
      * (formerly known as sub-accounts) with just the required permissions, for improved security.
      * To create a new user or manage existing ones, please visit https://verifalia.com/client-area#/users
@@ -20,14 +53,15 @@ export interface VerifaliaRestClientConfiguration {
     password: string;
 
     /**
-     * The base API endpoints for the Verifalia service: do not set these unless you are instructed
+     * The base API endpoints for the Verifalia service: do NOT set these unless you are instructed
      * to do so by the Verifalia support team.
      */
     baseUris: string[];
 
     /* @if TARGET='node' */
 
     /**
+     * This field is used only for client-certificate authentication.
      * Cert chains in PEM format. One cert chain should be provided per private key. Each cert chain should
      * consist of the PEM formatted certificate for a provided private key, followed by the PEM formatted
      * intermediate certificates (if any), in order, and not including the root CA (the root CA must be
@@ -38,6 +72,7 @@ export interface VerifaliaRestClientConfiguration {
     cert: string | Buffer | (string | Buffer)[];
 
     /**
+     * This field is used only for client-certificate authentication.
      * Private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted keys will
      * be decrypted with options.passphrase. Multiple keys using different algorithms can be provided either
      * as an array of unencrypted key strings or buffers, or an array of objects in the form {pem: <string|buffer>[, passphrase: ]}.
@@ -47,6 +82,7 @@ export interface VerifaliaRestClientConfiguration {
     key: string | Buffer | (Buffer | KeyObject)[];
 
     /**
+     * This field is used only for client-certificate authentication.
      * Shared passphrase used for a single private key and/or a PFX.
      */
     passphrase: string

src/common/CancellationToken.ts

@@ -1,3 +1,35 @@
+/**
+ * @license
+ * Verifalia - Email list cleaning and real-time email verification service
+ * https://verifalia.com/
+ * [email protected]
+ * 
+ * Copyright (c) 2005-2021 Cobisi Research
+ * 
+ * Cobisi Research
+ * Via Della Costituzione, 31
+ * 35010 Vigonza
+ * Italy - European Union
+ * 
+ * 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.
+ */
+
 import { OperationCanceledError } from "../errors/OperationCanceledError";
 
 export class CancellationToken {

src/common/DateUtils.ts

@@ -1,3 +1,35 @@
+/**
+ * @license
+ * Verifalia - Email list cleaning and real-time email verification service
+ * https://verifalia.com/
+ * [email protected]
+ * 
+ * Copyright (c) 2005-2021 Cobisi Research
+ * 
+ * Cobisi Research
+ * Via Della Costituzione, 31
+ * 35010 Vigonza
+ * Italy - European Union
+ * 
+ * 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.
+ */
+
 // Adapted from https://stackoverflow.com/a/23593099/904178
 
 export const formatDateToIso8601 = (date: Date): string => {

src/common/filters/DateBetweenPredicate.ts

@@ -1,3 +1,35 @@
+/**
+ * @license
+ * Verifalia - Email list cleaning and real-time email verification service
+ * https://verifalia.com/
+ * [email protected]
+ * 
+ * Copyright (c) 2005-2021 Cobisi Research
+ * 
+ * Cobisi Research
+ * Via Della Costituzione, 31
+ * 35010 Vigonza
+ * Italy - European Union
+ * 
+ * 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.
+ */
+
 import { FilterPredicateFragment } from './FilterPredicateFragment';
 import { DateFilterPredicate } from './DateFilterPredicate';
 import { formatDateToIso8601 } from '../DateUtils';

src/common/filters/DateEqualityPredicate.ts

@@ -1,3 +1,35 @@
+/**
+ * @license
+ * Verifalia - Email list cleaning and real-time email verification service
+ * https://verifalia.com/
+ * [email protected]
+ * 
+ * Copyright (c) 2005-2021 Cobisi Research
+ * 
+ * Cobisi Research
+ * Via Della Costituzione, 31
+ * 35010 Vigonza
+ * Italy - European Union
+ * 
+ * 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.
+ */
+
 import { FilterPredicateFragment } from './FilterPredicateFragment';
 import { DateFilterPredicate } from './DateFilterPredicate';
 import { formatDateToIso8601 } from '../DateUtils';

src/common/filters/DateFilterPredicate.ts

@@ -1,3 +1,35 @@
+/**
+ * @license
+ * Verifalia - Email list cleaning and real-time email verification service
+ * https://verifalia.com/
+ * [email protected]
+ * 
+ * Copyright (c) 2005-2021 Cobisi Research
+ * 
+ * Cobisi Research
+ * Via Della Costituzione, 31
+ * 35010 Vigonza
+ * Italy - European Union
+ * 
+ * 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.
+ */
+
 import { FilterPredicate } from "./FilterPredicate";
 
 export abstract class DateFilterPredicate extends FilterPredicate {