Fixed repository url, for npm docs

Aligned package version to the public release version Improved documentation
verifalia · Mar 2, 2023 · ff57a98 · ff57a98
1 parent cb9bf92
commit ff57a98
Show file tree

Hide file tree

Showing 42 changed files with 1,955 additions and 1,767 deletions.
diff --git a/README.md b/README.md
@@ -677,7 +677,7 @@ please see the [project releases](https://github.com/verifalia/verifalia-js-sdk/
 
 ## v4.0
 
-Released on March 3<sup>rd</sup>, 2023
+Released on March 2<sup>nd</sup>, 2023
 
 - Added support for API v2.4
 - Added support for new completion callback options

diff --git a/browser/amd/verifalia.js b/browser/amd/verifalia.js
diff --git a/browser/cjs/index.js b/browser/cjs/index.js
diff --git a/browser/esm/VerifaliaRestClient.d.ts.map b/browser/esm/VerifaliaRestClient.d.ts.map
diff --git a/browser/esm/credits/CreditsRestClient.d.ts b/browser/esm/credits/CreditsRestClient.d.ts
@@ -40,28 +40,19 @@ export declare class CreditsRestClient {
     /**
      * Returns the current credits balance for the Verifalia account.
      *
+     * This method returns a `Promise` which can be consumed using the async/await pattern (or through the
+     * classic `then()` / `catch()` functions) and can be cancelled through a `CancellationToken`.
+     *
      * Here is an example:
      * ```ts
-     * // Option 1 - async/await
-     *
      * const verifalia = new VerifaliaRestClient(...);
+     *
      * const balance = await verifalia
      *     .credits
      *     .getBalance();
      *
      * console.log(`Credit packs: ${balance.creditPacks}, free credits: ${balance.freeCredits}`);
      * // 'Credit packs: 507.23, free credits: 10.86'
-     *
-     * // Option 2 - callback
-     *
-     * const verifalia = new VerifaliaRestClient(...);
-     * verifalia
-     *     .credits
-     *     .getBalance()
-     *     .then(balance => {
-     *         console.log(`Credit packs: ${balance.creditPacks}, free credits: ${balance.freeCredits}`);
-     *         // 'Credit packs: 507.23, free credits: 10.86'
-     *     });
      * ```
      *
      * @param cancellationToken An optional token used to cancel the asynchronous request.
@@ -71,26 +62,27 @@ export declare class CreditsRestClient {
      * Lists the daily usages of the credits for the Verifalia account, according to the specified
      * listing options.
      *
+     * This method returns a `Promise` which can be consumed using the async/await pattern (or through the
+     * classic `then()` / `catch()` functions) and can be cancelled through a `CancellationToken`.
+     *
      * Here is how to list the credit daily usages between two dates:
      * ```ts
      * const verifalia = new VerifaliaRestClient(...);
      * const dailyUsages = verifalia
      *     .credits
      *     .listDailyUsages({
-     *         dateFilter: new DateBetweenPredicate(new Date(2020, 10, 15), new Date(2020, 10, 23))
+     *         dateFilter: new DateBetweenPredicate(new Date(2023, 2, 15), new Date(2023, 3, 1))
      *     });
      *
      * for await (const dailyUsage of dailyUsages) {
      *     console.log(`Date: ${dailyUsage.date}, credit packs: ${dailyUsage.creditPacks}, free credits: ${dailyUsage.freeCredits}`);
-     *     // 'Date: 2020-10-15, credit packs: 98.85, free credits: 50'
-     *     // 'Date: 2020-10-16, credit packs: 0, free credits: 19.26'
+     *     // 'Date: 2023-02-15, credit packs: 98.85, free credits: 50'
+     *     // 'Date: 2023-02-16, credit packs: 0, free credits: 19.26'
      *     // ...
-     *     // 'Date: 2020-10-23, credit packs: 1.565, free credits: 50'
+     *     // 'Date: 2023-03-01, credit packs: 1.565, free credits: 50'
      * }
      * ```
      *
-     * This method returns a `Promise` which can be awaited and can be cancelled through a `CancellationToken`.
-     *
      * @param options A `DailyUsageListingOptions` with the options for the listing operation.
      * @param cancellationToken An optional token used to cancel the asynchronous request.
      */

diff --git a/browser/esm/credits/CreditsRestClient.d.ts.map b/browser/esm/credits/CreditsRestClient.d.ts.map
diff --git a/browser/esm/diagnostics/Logger.d.ts b/browser/esm/diagnostics/Logger.d.ts
@@ -30,7 +30,6 @@
  * THE SOFTWARE.
  */
 export declare class Logger {
-    private _debugger;
     constructor(namespace: string);
     log(formatter: any, ...args: any[]): void;
 }

diff --git a/browser/esm/diagnostics/Logger.d.ts.map b/browser/esm/diagnostics/Logger.d.ts.map
diff --git a/browser/esm/email-validations/EmailValidationsRestClient.d.ts b/browser/esm/email-validations/EmailValidationsRestClient.d.ts
@@ -46,63 +46,189 @@ export declare class EmailValidationsRestClient {
     constructor(restClientFactory: RestClientFactory);
     /**
      * Submits one or more email addresses for validation.
+     *
+     * This method accepts a wide range of input types, including:
+     * - `string` and `string[]`, useful to submit only the email address(es) to verify, using the default
+     * processing options;
+     * - `ValidationRequestEntry` and `ValidationRequestEntry[]`, allowing to specify an optional custom
+     * string (such as a customer ID) along with each email address under test;
+     * - `ValidationRequest`, used to fully customize the email verification process;
+     * - `FileValidationRequest`, used to import and verify files containing lists of email addresses.
+     *
      * By default, this method waits for the completion of the email validation job: pass a `WaitOptions`
      * to request a different waiting behavior.
-     * This method accepts a wide range of input types, including:
-     * - `string` and `string[]`
-     * - `ValidationRequestEntry` and `ValidationRequestEntry[]`
-     * - `ValidationRequest`
-     * - `FileValidationRequest`
      *
-     * Here is the simplest case, showing how to verify an email address:
-     * ```ts
-     * // Option 1 - async/await
+     * This method returns a `Promise` which can be consumed using the async/await pattern (or through the
+     * classic `then()` / `catch()` functions) and can be cancelled through a `CancellationToken`.
      *
+     * ## How to verify an email address
+     *
+     * Here is the simplest case, showing how to verify a single email address, using the default processing
+     * options:
+     *
+     * ```ts
      * const verifalia = new VerifaliaRestClient(...);
+     *
      * const result = await verifalia
      *     .emailValidations
      *     .submit('[email protected]');
      *
      * console.log(result.entries[0].classification); // 'Deliverable'
+     * ```
+     * It is also possible to pass a `ValidationRequest` to specify any supported processing option, including the
+     * desired result quality level and data retention policy:
      *
-     * // Option 2 - callback
-     *
+     * ```ts
      * const verifalia = new VerifaliaRestClient(...);
-     * verifalia
+     *
+     * const result = await verifalia
      *     .emailValidations
-     *     .submit('[email protected]')
-     *     .then(result => {
-     *         console.log(result.entries[0].classification); // 'Deliverable'
+     *     .submit({
+     *         entries: [
+     *             {
+     *                 inputData: 'scottgu@gmail.com',
+     *                 // custom: 'foobar123'
+     *             }
+     *         ],
+     *         quality: 'High',
+     *         retention: '0:5:0' // 5 minutes
      *     });
+     *
+     * console.log(result.entries[0].classification); // 'Deliverable'
      * ```
      *
+     * ## How to verify multiple email addresses at once
+     *
      * To validate multiple email addresses at once, just submit an array of strings:
      * ```ts
-     * // Option 1 - async/await
-     *
      * const verifalia = new VerifaliaRestClient(...);
+     *
      * const result = await verifalia
      *     .emailValidations
      *     .submit([ '[email protected]', '[email protected]' ]);
      *
      * result.entries.forEach((item) => {
      *     console.log(`${item.inputData}: ${item.classification}`);
      * }); // '[email protected]: Deliverable' '[email protected]: Undeliverable'
+     * ```
      *
-     * // Option 2 - callback
+     * As seen in the section above, it is also possible to pass a `ValidationRequest` to specify
+     * any supported processing option, including the desired result quality level and data retention
+     * policy:
      *
+     * ```ts
      * const verifalia = new VerifaliaRestClient(...);
-     * verifalia
+     *
+     * const result = await verifalia
      *     .emailValidations
-     *     .submit([ '[email protected]', '[email protected]' ]);
-     *     .then(result => {
-     *         result.entries.forEach((item) => {
-     *             console.log(`${item.inputData}: ${item.classification}`);
-     *         }); // '[email protected]: Deliverable' '[email protected]: Undeliverable'
+     *     .submit({
+     *         entries: [
+     *             {
+     *                 inputData: 'scottgu@gmail.com',
+     *                 // custom: 'foobar'
+     *             },
+     *             {
+     *                 inputData: 'robin1940@yahoo.com',
+     *                 // custom: '42'
+     *             },
+     *         ],
+     *         quality: 'Extreme',
+     *         retention: '1:30:0' // 1 hour and 30 minutes
+     *     });
+     *
+     * result.entries.forEach((item) => {
+     *     console.log(`${item.inputData}: ${item.classification}`);
+     * }); // '[email protected]: Deliverable' '[email protected]: Undeliverable'
+     * ```
+     *
+     * ## Import and verify a list of email addresses
+     *
+     * To import and submit a file with the email addresses to verify, pass a `FileValidationRequest`
+     * to this method, with the `file` field assigned to an instance of one of these supported types:
+     * - `ReadStream` or a `Buffer` (Node.js), or;
+     * - `Blob` or a `File` (browser).
+     *
+     * Here is how to import and verify a list in the CSV file format, in Node.js, using a `ReadStream`:
+     * ```ts
+     * const fs = require('fs');
+     *
+     * const verifalia = new VerifaliaRestClient(...);
+     * const fileStream = fs.createReadStream('./my-list.csv');
+     *
+     * const result = await verifalia
+     *     .emailValidations
+     *     .submit({
+     *         file: fileStream,
+     *         contentType: 'text/csv',
+     *         column: 0,
+     *         startingRow: 1
      *     });
+     *
+     * result.entries.forEach((item) => {
+     *     console.log(`${item.inputData}: ${item.classification}`);
+     * });
+     * ```
+     *
+     * While importing and submitting a file for email verification, it is possible to specify any processing
+     * option through the passed `FileValidationRequest` instance, similarly to how one can do that with the
+     * `ValidationRequest` class.
+     *
+     * ```ts
+     * const fs = require('fs');
+     *
+     * const verifalia = new VerifaliaRestClient(...);
+     * const fileStream = fs.createReadStream('./my-list.csv');
+     *
+     * const result = await verifalia
+     *     .emailValidations
+     *     .submit({
+     *         file: fileStream,
+     *         contentType: 'text/csv',
+     *         column: 0,
+     *         startingRow: 1,
+     *         quality: 'High',
+     *         retention: '0:10:0', // 10 minutes
+     *         callback: {
+     *             url: 'https://your-website-here/foo/bar'
+     *         }
+     *     });
+     *
+     * result.entries.forEach((item) => {
+     *     console.log(`${item.inputData}: ${item.classification}`);
+     * });
+     * ```
+     *
+     * ## Custom waiting
+     *
+     * As mentioned, `submit()` automatically waits for the completion of the submitted email
+     * verification job. It is however possible, through the `waitOptions` parameter, to customize
+     * the waiting behavior of the method.
+     *
+     * Here is how, for instance, one can enqueue a possibly large email verification job, **without**
+     * waiting for its completion:
+     *
+     * ```ts
+     * const job = await verifalia
+     *     .emailValidations
+     *     .submit(TODO, WaitOptions.noWait);
+     *
+     * console.log(`${job.overview.status}`); // InProgress
      * ```
      *
-     * This method returns a `Promise` which can be awaited and can be cancelled through a `CancellationToken`.
+     * And here is how to **track the progress** of an email verification job through a custom `WaitOptions` and
+     * a `progress` function lambda:
+     *
+     * ```ts
+     * const job = await verifalia
+     *     .emailValidations
+     *     .submit(TODO,
+     *         {
+     *             ...new WaitOptions(),
+     *             progress: jobOverview => {
+     *                 console.log(`% completed: ${jobOverview.progress?.percentage * 100}`);
+     *             }
+     *         });
+     * ```
      *
      * @param request An object with one or more email addresses to validate. Can be of type `string`, `string[]`,
      * `ValidationRequestEntry`, `ValidationRequestEntry[]`, `ValidationRequest`, `FileValidationRequest`.
@@ -113,9 +239,13 @@ export declare class EmailValidationsRestClient {
     submit(request: FileValidationRequest | NonFileValidationRequest, waitOptions?: WaitOptions | null, cancellationToken?: CancellationToken): Promise<Validation | null>;
     /**
      * Returns an email validation job previously submitted for processing.
+     *
      * By default, this method waits for the completion of the email validation job: pass a `WaitOptions`
      * to request a different waiting behavior.
      *
+     * This method returns a `Promise` which can be consumed using the async/await pattern (or through the
+     * classic `then()` / `catch()` functions) and can be cancelled through a `CancellationToken`.
+     *
      * Here is how to retrieve an email validation job, given its ID:
      * ```ts
      * const verifalia = new VerifaliaRestClient(...);
@@ -124,8 +254,6 @@ export declare class EmailValidationsRestClient {
      *     .get('JOB-ID-HERE'); // validation.id (returned by submit() or list())
      * ```
      *
-     * This method returns a `Promise` which can be awaited and can be cancelled through a `CancellationToken`.
-     *
      * @param id The ID of the email validation job to retrieve.
      * @param waitOptions Optional configuration settings for waiting on the completion of an email validation job.
      * Can be `undefined` (or `null`) to wait for the completion using the default settings, `WaitOptions.noWait` to
@@ -135,6 +263,9 @@ export declare class EmailValidationsRestClient {
     /**
      * Deletes an email validation job previously submitted for processing.
      *
+     * This method returns a `Promise` which can be consumed using the async/await pattern (or through the
+     * classic `then()` / `catch()` functions) and can be cancelled through a `CancellationToken`.
+     *
      * Here is how to delete an email validation job:
      * ```ts
      * const verifalia = new VerifaliaRestClient(...);
@@ -143,14 +274,15 @@ export declare class EmailValidationsRestClient {
      *     .delete('JOB-ID-HERE'); // validation.id (returned by submit(), get() or list())
      * ```
      *
-     * This method returns a `Promise` which can be awaited and can be cancelled through a `CancellationToken`.
-     *
      * @param id The ID of the email validation job to delete.
      */
     delete(id: string, cancellationToken?: CancellationToken): Promise<void>;
     /**
      * Lists all the email validation jobs, according to the specified listing options.
      *
+     * This method returns a `Promise` which can be consumed using the async/await pattern (or through the
+     * classic `then()` / `catch()` functions) and can be cancelled through a `CancellationToken`.
+     *
      * Here is how to list all the jobs submitted on a specific date:
      * ```ts
      * const verifalia = new VerifaliaRestClient(...);
@@ -165,8 +297,6 @@ export declare class EmailValidationsRestClient {
      * }
      * ```
      *
-     * This method returns a `Promise` which can be awaited and can be cancelled through a `CancellationToken`.
-     *
      * @param options The options for the listing operation.
      * @param cancellationToken An optional token used to cancel the asynchronous request.
      */
@@ -177,6 +307,9 @@ export declare class EmailValidationsRestClient {
      * file format. While the output schema (columns / labels / data format) is fairly complete, you
      * should always consider it as subject to change.
      *
+     * This method returns a `Promise` which can be consumed using the async/await pattern (or through the
+     * classic `then()` / `catch()` functions) and can be cancelled through a `CancellationToken`.
+     *
      * Here is how to export a job in Microsoft Excel format:
      * ```ts
      * const verifalia = new VerifaliaRestClient(...);
@@ -196,8 +329,6 @@ export declare class EmailValidationsRestClient {
      *     .src = exportedData.toBlobURL(MimeContentType_ExcelXlsx);
      * ```
      *
-     * This method returns a `Promise` which can be awaited and can be cancelled through a `CancellationToken`.
-     *
      * @param id The ID of the email validation job to retrieve.
      * @param contentType The MIME content-type of output file format. Acceptable values:
      * - text/csv for comma-separated values files - CSV