Merge pull request #458 from dailymotion/modularization

Modularization

.gitignore

@@ -3,3 +3,6 @@
 node_modules/*
 npm-debug.log
 dist_old
+examples/node_modules/*
+examples/.parcel-cache/*
+examples/dist/*

README.md

@@ -15,7 +15,9 @@ This library provides three components:
 For the full API documentation go [here](#api).
 For the full Class reference go [here](https://github.com/dailymotion/vast-client-js/blob/master/docs/api/class-reference.md)
 
-Complies with the [VAST 4.2 specification](https://iabtechlab.com/wp-content/uploads/2019/06/VAST_4.2_final_june26.pdf) provided by the [Interactive Advertising Bureau (IAB)](https://www.iab.com/).
+To explore a practical example of how the vast client can be implemented, please visit this [link](https://githubbox.com/dailymotion/vast-client-js/tree/master/examples).
+
+Complies with the [VAST 4.3 specification](https://iabtechlab.com/wp-content/uploads/2022/09/VAST_4.3.pdf) provided by the [Interactive Advertising Bureau (IAB)](https://www.iab.com/).
 
 ## Get Started
 
@@ -29,7 +31,7 @@ Then import the components you need.
 
 ### VASTClient
 
-If you need to fetch and parse VAST documents, you can use the **VASTClient**:
+If you need to fetch and parse VAST documents, you can use the `get` method from the **VASTClient**:
 
 ```javascript
 import { VASTClient } from '@dailymotion/vast-client'
@@ -47,9 +49,25 @@ vastClient.get('https://www.examplevast.com/vast.xml')
 
 In addition to fetching and parsing a VAST resource, **VASTClient** provides options to filter a sequence of calls based on count and time of execution, together with the possibility to track URLs using **VASTTracker**.
 
+If you need to directly parse a VAST XML and also follow any wrappers chain, you can use the  `parseVAST` method from the  **VASTClient** :
+
+```javascript
+import { VASTClient } from '@dailymotion/vast-client'
+
+const vastClient = new VASTClient();
+
+vastClient.parseVAST(vastXml)
+  .then(parsedVAST => {
+    // Do something with the parsed VAST response
+  })
+  .catch(err => {
+    // Deal with the error
+  });
+```
 ### VASTParser
 
 To directly parse a VAST XML you can use the **VASTParser**:
+The **VASTParser** will make no fetching, the final response will only contain the first VAST encountered.
 
 ```Javascript
 import { VASTParser } from '@dailymotion/vast-client'
@@ -110,18 +128,21 @@ const vastTracker = new VASTTracker();
 
 #### Browser script
 
-A pre-bundled version of VAST Client JS is available: [`vast-client-browser.min.js`](dist/vast-client-browser.min.js) [minified].
+A pre-bundled version of VAST Client JS is available: [`vast-client.min.js`](dist/vast-client.min.js) [minified].
 
-You can add the script directly to your page and access the library's components through the `VAST` object.
+To use it, either host it on your CDN or locally in your project. If you're using a script tag make sure to set the type property to module like below.
 
+_your index.html_
 ```html
-<script src="vast-client-browser.min.js"></script>
+<script type="module" src="your-main-file.js"></script>
 ```
-
+_main.js_
 ```javascript
-const vastClient = new VAST.VASTClient();
-const vastParser = new VAST.VASTParser();
-const vastTracker = new VAST.VASTTracker();
+import {VASTClient, VASTParser, VASTTracker} from "vast-client.min.js"
+
+const vastClient = new VASTClient();
+const vastParser = new VASTParser();
+const vastTracker = new VASTTracker();
 ```
 
 #### Node

bundle_size.js

@@ -1,12 +1,14 @@
 const fs = require('fs');
-const path = require('path');
 
 const newDistPath = './dist';
 const oldDistPath = './dist_old';
 
 const getFileSizes = (folderPath) => {
   return fs.readdirSync(folderPath).reduce((res, fileName) => {
-    res[fileName] = fs.readFileSync(path.join(folderPath, fileName)).byteLength;
+    const stats = fs.statSync(`${folderPath}/${fileName}`);
+    if (stats.isFile()) {
+      res[fileName] = stats.size;
+    }
     return res;
   }, {});
 };

docs/api/vast-client.md

@@ -1,6 +1,6 @@
 # VASTClient
 
-The `VASTClient` class provides a client to manage the fetching and parsing of VAST documents.
+The `VASTClient` class provides a client to manage the fetching and parsing of VAST documents. It provides methods for fetching VAST resources by resolving the wrapper chain (recursive fetching and parsing) by using the `VASTParser` parsing methods.
 
 - [Constructor](#constructor)
 - [Properties](#properties)
@@ -147,6 +147,62 @@ vastClient.get('http://example.dailymotion.com/vast.xml', options)
     // Deal with the error
   });
 ```
+### parseVAST(vastXml, options)<a name="parse"></a>
+
+Parses the given xml Object into a [VASTResponse](https://github.com/dailymotion/vast-client-js/blob/master/docs/api/class-reference.md#vastresponse).
+Returns a `Promise` which either resolves with the fully parsed `VASTResponse` or rejects with an `Error`.
+
+By using this method, you will be able to perform fetching in case you want to parse a VAST document and follow a wrappers chain.
+If you just need to parse an inline VAST or you want to parse the first VAST document encountered, you should use the **parseVAST** method from the **VASTParser**.
+
+#### Parameters
+
+- **`vastXml: Object`** - An object representing an xml document
+- **`options: Object`** - An optional Object of parameters to be used in the parsing process
+  - `timeout: Number` - A custom timeout for the possible wrapper resolving requests (default `120000`)
+  - `withCredentials: Boolean` - A boolean to enable the withCredentials options for the XHR URLHandler (default `false`)
+  - `wrapperLimit: Number` - A number of Wrapper responses that can be received with no InLine response (default `10`)
+  - `urlHandler: URLHandler` - Custom urlhandler to be used instead of the default ones [`urlhandlers`](../../src/urlhandlers)
+  - `urlhandler: URLHandler` - Fulfills the same purpose as `urlHandler`, which is the preferred parameter to use
+  - `allowMultipleAds: Boolean` - A boolean value that identifies whether multiple ads are allowed in the requested VAST response. This will override any value of allowMultipleAds attribute set in the VAST
+  - `followAdditionalWrappers: Boolean` - A boolean value that identifies whether subsequent Wrappers after a requested VAST response is allowed. This will override any value of followAdditionalWrappers attribute set in the VAST
+  - `requestDuration: Number` - The fetching time of the XML in ms. Provide it with byteLength to have a more accurate estimated bitrate.
+  - `byteLength: Number`- The size of the request in bytes. Provide it with requestDuration to have a more accurate estimated bitrate.
+
+#### Events emitted
+
+- **`VAST-resolved`**
+- **`VAST-resolving`**
+- **`VAST-warning`**
+
+#### Example
+
+```Javascript
+const vastXml = (new window.DOMParser()).parseFromString(xmlStr, "text/xml");
+
+vastParser.parseVAST(vastXml)
+  .then(res => {
+    // Do something with the parsed VAST response
+  })
+  .catch(err => {
+    // Deal with the error
+  });
+
+// Or with some options
+const options = {
+  timeout: 5000,
+  withCredentials: true,
+  wrapperLimit: 7
+}
+vastParser.parseVAST(vastXml, options)
+  .then(res => {
+    // Do something with the parsed VAST response
+  })
+  .catch(err => {
+    // Deal with the error
+  });
+```
+
 
 #### How does resolveAll work
 
@@ -304,3 +360,72 @@ const vastParser = vastClient.getParser();
 // Clear the url template filters used
 vastParser.clearUrlTemplateFilters();
 ```
+
+### addURLTemplateFilter(filter)
+
+Adds a filter function to the array of filters which are called before fetching a VAST document.
+
+#### Parameters
+
+- **`filter: function`** - The filter function to be added at the end of the array
+
+#### Example
+
+```Javascript
+vastClient.addURLTemplateFilter( vastUrl => {
+    return url.replace('[DOMAIN]', 'mywebsite.com')
+});
+
+/*
+For a VASTAdTagURI defined as :
+<VASTAdTagURI>http://example.dailymotion.com/vast.php?domain=[DOMAIN]</VASTAdTagURI>
+HTTP request will be:
+http://example.dailymotion.com/vast.php?domain=mywebsite.com
+*/
+```
+
+### removeLastURLTemplateFilter()
+
+Removes the last element of the url templates filters array.
+
+#### Example
+
+```Javascript
+const replaceDomain = () => {
+    return url.replace('[DOMAIN]', 'mywebsite.com')
+};
+
+vastClient.addURLTemplateFilter(replaceDomain);
+// ...
+vastClient.removeURLTemplateFilter(replaceDomain);
+// [DOMAIN] placeholder is no longer replaced
+```
+### countURLTemplateFilters()
+
+Returns the number of filters of the url templates filters array.
+
+#### Example
+
+```Javascript
+vastClient.addURLTemplateFilter( vastUrl => {
+    return url.replace('[DOMAIN]', 'mywebsite.com')
+});
+
+vastClient.countUrlTemplateFilters();
+// returns 1
+```
+
+### clearURLTemplateFilters()
+
+Removes all the filter functions from the url templates filters array.
+
+#### Example
+
+```Javascript
+vastClient.addURLTemplateFilter( vastUrl => {
+    return url.replace('[DOMAIN]', 'mywebsite.com')
+});
+
+vastClient.clearUrlTemplateFilters();
+// [DOMAIN] placeholder is no longer replaced
+```