2.0 Version (#230)

* Add .npmrc * 2.0.0-alpha.0 * Fix parser error tracking (#137) - Move VAST test files to /test/vastfiles/ - Add unit tests to check error scenarios that can happen while parsing VAST files - Add Extensions data to Parser error events - Update Parser doc * Merge `v1.6.0` into `v2.x` (#144) * Add setExpand() documentation * Add macros RANDOM/TIMESTAMP/ASSETURI * Remove empty #text/ #comments from parsed extensions * Add unit test for #text extension * rework resolveURLTemplates() * leftpad cachebusting macro * Bundle last changes * 1.6.0 * Bundle last changes * 2.0.0-alpha.1 * 2.0.0-alpha.2 * Remove duration restriction for parser * Bundle last changes * 2.0.0-alpha.3 * Merge 1.7.0 into v2.x (#162) * Add setExpand() documentation * Add macros RANDOM/TIMESTAMP/ASSETURI * Remove empty #text/ #comments from parsed extensions * Add unit test for #text extension * rework resolveURLTemplates() * leftpad cachebusting macro * Bundle last changes * 1.6.0 * Add Common-tasks.md (#148) * Added NonLinear AdParameter Parsing with adequate test in sample.xml #152 (#153) * changes to parse altText fixes #154 (#155) * Wrapper limit handling (#157) * Added wrapperLimit to options * Fixed error forwarding inside wrappers * VAST parser returns creative id, adId, sequence and apiFramework attributes * Parse VAST Duration tag with number instead of HH:MM:SS * Parse all nonlinear attributes * Parse nonlinear click tracking urls * Parser - handle click/clickthrough event for nonlinear/companion ads * Bundle last changes * 1.7.0 * 2.0.0-alpha.4 * Merge 1.7.1 into v2.x (#164) * Handle VAST2/3/4 creative adId format * Bundle last changes * 2.0.0-alpha.5 * Merge 1.7.2 into v2.x (#171) * Bundle last changes * 2.0.0-alpha.6 * Merge 1.7.3 into v2.x (#173) * Bundle last changes * 2.0.0-alpha.7 * Merge 1.8.0 into v2.x (#183) * Add new events resolving/resolved while parsing VastAdTagUri * Bundle last changes * 2.0.0-alpha.8 * Add ERRORMESSAGE & system on error (#191) * Use webpack for boundle * Use single string for require * Split VASTParser into multiple components * Remove old parser * Add decaffeinate tools * [ES6] move extension.coffee * [ES6] convert extension.coffee * [ES6] move icon.coffee * [ES6] convert icon.coffee * [ES6] move extensionchild.coffee * [ES6] convert extensionchild.coffee * [ES6] move ad.coffee * [ES6] convert ad.coffee * [ES6] move mediafile.coffee * [ES6] convert mediafile.coffee * [ES6] move nonlinear.coffee * [ES6] convert nonlinear.coffee * [ES6] move response.coffee * [ES6] convert response.coffee * [ES6] move companionad.coffee * [ES6] convert companionad.coffee * [ES6] move creative.coffee * [ES6] convert creative.coffee * Make properties and methods of VASTUtil non static * [ES6] move util.coffee * [ES6] convert util.coffee * Refactoring fixes after VASTUtil es6 conversion * Make properties and methods of urlhandlers non static * [ES6] move urlhandler.coffee * [ES6] convert urlhandler.coffee * Refactoring fixes after URLHAndler es6 conversion * [ES6] move node.coffee * [ES6] convert node.coffee * Refactoring fixes after NodeUrlHandler es6 conversion * [ES6] move xmlhttprequest.coffee * [ES6] convert xmlhttprequest.coffee * Refactoring fixes after XHRUrlHandler es6 conversion * [ES6] move flash.coffee * [ES6] convert flash.coffee * Refactoring fixes after FlashUrlHandler es6 conversion * [ES6] move parser_utils.coffee * [ES6] convert parser_utils.coffee * Refactoring fixes after ParserUtils es6 conversion * [ES6] move ad_parser.coffee * [ES6] convert ad_parser.coffee * Refactoring fixes after AdParser es6 conversion * [ES6] move creative_companion_parser.coffee * [ES6] convert creative_companion_parser.coffee * Refactoring fixes after CreativeCompanionParser es6 conversion * [ES6] move creative_linear_parser.coffee * [ES6] convert creative_linear_parser.coffee * Refactoring fixes after CreativeLinearParser es6 conversion * Fix CreativeNonLinearParser indentation * [ES6] move creative_non_linear_parser.coffee * [ES6] convert creative_non_linear_parser.coffee * Refactoring fixes after CreativeNonLinearParser es6 conversion * [ES6] move tracker.coffee * [ES6] convert tracker.coffee * Refactoring fixes after VASTTracker es6 conversion * [ES6] move index.coffee * [ES6] convert index.coffee * Make properties and methods of VASTParser non static * [ES6] move parser.coffee * [ES6] convert parser.coffee * Refactoring fixes after VASTParser es6 conversion * Make properties and methods of VASTClient non static * [ES6] move client.coffee * [ES6] convert client.coffee * Refactoring fixes after VASTClient es6 conversion * Fixes after decaffeination * [ES6] move util.coffee * [ES6] convert util.coffee * Refactoring fixes after test/util.coffee es6 conversion * [ES6] move urlhandler.coffee * [ES6] convert urlhandler.coffee * Refactoring fixes after test/urlhandler.coffee es6 conversion * [ES6] move tracker.coffee * [ES6] convert tracker.coffee * Refactoring fixes after test/tracker.coffee es6 conversion * [ES6] move storage.coffee * [ES6] convert storage.coffee * Refactoring fixes after test/storage.coffee es6 conversion * [ES6] move parser.coffee * [ES6] convert parser.coffee * Refactoring fixes after test/parser.coffee es6 conversion * Conversion fixes * Remove decaffeinate tools * Use es6 modules * Remove coffeescript tools/support * Update documentation * Prettify code with Prettier * Update bundling options * Fix util track * Remove var variables * Fix static usage of VASTClient in VASTTracker * Api improvements for VASTClient (and tests) * Separate Storage logic and provide option for custom storage * Improve documentation comments and Storage * Add tests for custom storage * Fix tests and improve Storage * Rename client.js to vast_client.js * Keep comment about disabled storage, better Date usage * Improve parser API (methods and logic splitting and renaming) * Add jsdoc comments for VASTParser methods * Rename parser.js to vast_parser.js * Use array.forEach instead than for of loops * Add JsDoc to all the parsing classes * Use forEach in vast parser loops * Improve VASTTracker API and documentation comments * Rename tracker.js to vast_tracker.js * Use Date.now() and simpler boolean check * Update documentation for 2.0 version * Documentation fixes * Fix index.js imports and use a single file for webpack config * Remove bower file * Quartile Fix: If ads seeked (IOS fullscreen) be sure to trigger all quartile regarding progress time * Use better null checks in if conditions * Use shorter if conditions * Update potentially vulnreable old libraries * Update webpack version after npm audit * Back port work from @Walkerflocker to 2.x branch to convert coffee script to JavaScript to apply sequence to single wrapped ads and fix testing * Bundle last changes * 2.0.0-alpha.9 * Use promises to handle wrapper resolving * Update vast parser jsdoc * Update vast parser documentation * Update migration documentation * Add tests for ad pod * Fix storage initialization * Method to get parser from VASTClient * Allow usage of custom urlHandler * Safe check to merge wrapper data * Code review fixes * Update documentation for client and parser * Update bundled version * 2.0.0-alpha.10 * Return Promise for client and parser (#224) * Return Promise for client and parser * Add Promises documentation * Merge 1.8.4 into v2.x (#225) * Update mocha to latest version * Update node version * 1.8.4 * Bundle last changes * 2.0.0-alpha.11 * [parser] Resolve VAST wrappers by adPod * [parser] Automatically resolve the following groups of ads if the first returns no ads * [parser] Provide methods to access and resolve remaining ads * [client] Pass false as default value for resolveAll in get method * Fixing 2x docs (#227) * [parser] update parser docs * [tracker] fix 2.x docs * [client] fix 2.x docs * [parser] Add method to split a VAST response into Ad and AdPods * [parser] Split VAST only once * [client] Add methods to get next ads * [parser] Fix typo in resolveAds jsdoc * [client] Update documentation for get method * [client] Update documentation for new remaining ads methods * [parser] add splitVAST unit test * [parser][test] remove unused module * [client] Update documentation for resolveAll * [parser] Delete incorrect ad.sequence * [parser] Return error url templates based on the ad * [client][test] Add test for resolveAll param, fix encountered issues * [client][test] Remove wrong describe.only * [client][parser] Split vast code review fixes * [parser] Removed unused splittedVAST property * [docs] Add commit guidelines * [docs] Add PR labeling guidelines * [tools] Bundle last changes * 2.0.0-alpha.12 * [parser] When resolveAll is false parsing breaks on no ad VAST response
dailymotion · Jul 18, 2018 · 1f5360e · 1f5360e
1 parent 6031526
commit 1f5360e
Show file tree

Hide file tree

Showing 98 changed files with 14,539 additions and 5,807 deletions.
diff --git a/.babelrc b/.babelrc
@@ -0,0 +1,7 @@
+{
+    "presets": [
+      [
+        "es2015"
+      ]
+    ]
+}
diff --git a/.editorconfig b/.editorconfig
@@ -1,16 +1,26 @@
-# EditorConfig is awesome: http://EditorConfig.org
+# editorconfig.org
 
-# top-most EditorConfig file
+# This allow you to have a ~/.editorconfig that defines missing properties (e.g. indent_size)
 root = true
 
 [*]
+indent_style = space
+indent_size = 2
 end_of_line = lf
-insert_final_newline = false
+charset = utf-8
+
+# On save, removes trailing whitespace
 trim_trailing_whitespace = true
-indent_style = space
-indent_size = 4
 
-# Matches the exact file .travis.yml
-[{.travis.yml}]
+# On save, adds the final newline character.
+# It's required for some unix command to work:
+# % echo 'toto' | wc -l
+# 1
+# % echo -n 'toto' | wc -l
+# 0
+# In a git diff, no final newline generates the "No newline at end of file" message
+# This is not a bug, just a message by git.
+insert_final_newline = true
+
+[*.md]
 indent_style = space
-indent_size = 2
diff --git a/.npmrc b/.npmrc
@@ -0,0 +1 @@
+tag-version-prefix = ""
diff --git a/.prettierignore b/.prettierignore
@@ -0,0 +1,9 @@
+node_modules
+*.md
+*.json
+.travis.yml
+.babelrc
+.prettierrc
+.gitignore
+test/*.xml
+vast-client.js
diff --git a/.prettierrc b/.prettierrc
@@ -0,0 +1,7 @@
+{
+    "printWidth": 80,
+    "tabWidth": 2,
+    "semi": true,
+    "singleQuote": true,
+    "parser": "flow"
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/README.md b/README.md
@@ -1,27 +1,88 @@
 [![Build Status](https://travis-ci.org/dailymotion/vast-client-js.png)](https://travis-ci.org/dailymotion/vast-client-js)
-[![npm version](https://img.shields.io/npm/v/vast-client.svg)](https://www.npmjs.com/package/vast-client)
-[![Dependency Status](https://david-dm.org/dailymotion/vast-client-js.svg)](https://david-dm.org/dailymotion/vast-client-js)
-[![devDependency Status](https://david-dm.org/dailymotion/vast-client-js/dev-status.svg)](https://david-dm.org/dailymotion/vast-client-js#info=devDependencies)
+[![npm version](https://badge.fury.io/js/vast-client.svg)](https://badge.fury.io/js/vast-client)
 
-# VAST Javascript Client
-Vast Client JS is a Javascript library for parsing Digital Video Ad Serving Template (VAST) documents as close as possible to the Interactive Advertising Bureau (IAB) specification.
+# VAST Client JS
+Vast Client JS is a JavaScript library to fetch and parse Digital Video Ad Serving Template (VAST) documents.
 
-This library provides:
+This library provides three components:
 
- * A VAST parser, which validates the XML and translates it into a JS object.
- * A VAST tracker, which batches the tracking urls and provides methods for calling them.
+ * A **VAST Client** to fetch and parse VAST XML resources into JavaScript Objects.
+ * A **VAST Parser** to directly parse a VAST XML.
+ * A **VAST Tracker** to batch and call tracking URLs.
 
+For the full API documentation go [here](#api).
 
-Complies with [VAST 3.0 spec](https://www.iab.com/wp-content/uploads/2015/06/VASTv3_0.pdf).
+Complies with the [VAST 3.0 specification](https://www.iab.com/wp-content/uploads/2015/06/VASTv3_0.pdf) provided by the [Interactive Advertising Bureau (IAB)](https://www.iab.com/).
 
-## Documentation
-The [client](docs/client.md) documentation contains the basic information to parse a VAST URL/Document. For more advanced use of the parser, see the [parser](docs/parser.md) documentation.
+## Get Started
+VAST Client JS is available as an NPM package and can be easily installed with:
+```Bash
+npm i vast-client
+```
+Then import the components you need.
 
-All information about the tracking part can be found in the [tracker](docs/tracker.md) documentation.
+### VASTClient
+If you need to fetch and parse VAST documents, you can use the **VASTClient**:
+```javascript
+import { VASTClient } from 'vast-client'
 
-## Support
-If you need to support legacy browsers (e.g. IE8+), don't forget to include [es5.js](/~https://github.com/inexorabletash/polyfill/blob/master/es5.js)
+const vastClient = new VASTClient();
+
+vastClient.get('https://www.examplevast.com/vast.xml')
+  .then(res => {
+    // Do something with the parsed VAST response
+  })
+  .catch(err => {
+    // Deal with the error
+  })
+});
+```
+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**.
+
+### VASTParser
+To directly parse a VAST XML you can use the **VASTParser**:
+```Javascript
+import { VASTParser } from 'vast-client'
+
+const vastParser = new VASTParser();
+
+vastParser.parseVAST(vastXml, (err, res) => {
+  .then(res => {
+    // Do something with the parsed VAST response
+  })
+  .catch(err => {
+    // Deal with the error
+  })
+});
+```
+
+### VASTTracker
+To track the execution of an ad use the **VASTTracker**:
+```Javascript
+import { VASTTracker } from 'vast-client'
+
+const vastTracker = new VASTTracker(vastClient, ad, creative);
+
+// Track an impression for the given ad
+vastTracker.trackImpression();
+```
+
+## API Documentation<a name="api"></a>
+The API documentation is organized by components:
+
+ * [VASTClient](docs/api/vast-client.md)
+ * [VASTParser](docs/api/vast-parser.md)
+ * [VASTTracker](docs/api/vast-tracker.md)
+
+**:warning: IMPORTANT :warning:** : the release of the `2.0` version of the library introduced many breaking changes in the API.
+
+Read the [**2.0 migration guide**](docs/api/2.0-migration.md) to update your project or follow the [**1.x API documentation**](docs/api/1.x) if you're still using the old version.
+
+## Support and compatibility
+The library is 100% written in JavaScript and the source code uses modern features like `es6 modules`. Make sure your environment supports these features, or transpile the library when bundling your project.
+
+A pre-bundled version of VAST Client JS is available: [`vast-client.js`](vast-client.js). You can add the script directly to your page and access the library's components through the `VAST` object.
 
 ## Build / Contribute
 
-See [CONTRIBUTING](CONTRIBUTING.md)
+See [CONTRIBUTING](docs/CONTRIBUTING.md)
diff --git a/bower.json b/bower.json
diff --git a/common-tasks.md b/common-tasks.md
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,90 @@
+# Contributing
+
+:tada: Thanks for being here :tada:
+
+We appreciate any kind of contribution: bug reports, feature requests and pull requests.
+
+Please read the following sections before making your contribution.
+
+## Report a bug / Request a feature
+To report a bug or request a feature, please [create an issue on GitHub](/~https://github.com/dailymotion/vast-client-js/issues/new) and follow the guidelines below.
+
+### Report a bug
+ * Explain the expected behaviour with a simple sentence
+ * Label the issue as a `bug`
+ * Provide the **steps** to reproduce your problem (if possible) or a simple **example** of code
+ * Report the **version** of the library you are using
+ * Is it a regression from a previous version?
+
+### Request a feature or suggest an enhancement
+If you see something that's missing or can be improved, please let us know!
+
+ * Explain which feature/improvement you would like to be added to the library.
+ * Label the issue as `feature`, `enhancement` or `discussion`
+ * If you can, suggest how you would do that :sunglasses:
+ * If you already coded it, feel free to open and link a pull request :man_technologist: :woman_technologist:
+
+## Pull requests
+Pull requests are welcome. Here is a quick guide on how to start.
+
+ * Develop in a dedicated branch, not directly on master
+ * If you add some logic, add some tests too
+ * Make sure test are passing (`npm test`)
+ * If you bundle the project, please don't commit the updated `vast-client.js` file in your PR. We'll take care of generating an updated build right before releasing a new tagged version.
+ * Follow the commit guidelines below 👇
+ * Label your PR with one of these three tags (Maintainers will then make the right release according to that)
+    * `breaking-change`
+    * `enhancement`
+    * `fix`
+
+## Commit messages
+In order to keep a clean and clear commit history, please commit to the repo following these guidelines:
+
+ * Mark each commit with one of the following tags:
+    * `[client]` for commits involving `VASTClient` logic
+    * `[parser]` for commits involving `VASTParser` logic
+    * `[tracker]` for commits involving `VASTTracker` logic
+    * `[util]` for commits involving utility components logic
+    * `[test]` for commits adding or fixing tests
+    * `[docs]` for commits involving documentation
+    * `[tools]` for commits involving tooling
+ * Add a short description of the changes made in the commit
+ * If needed add a longer description in the following lines
+
+Example:
+```
+[tag][subtag] short commit message
+optional longer description of
+what happens in this commit
+```
+```
+[client][test] add tests for new get method parameters
+This commit adds some tests for some new optional parameter
+which have been added to the get method of the VASTClient component
+```
+
+## Setup the project
+
+Clone the repository :
+```Bash
+git clone git@github.com:dailymotion/vast-client-js.git
+```
+
+Setup your environment :
+```Bash
+cd vast-client-js
+
+npm install
+```
+
+Run the tests :
+```Bash
+npm test
+```
+
+### Bundle
+
+The project uses webpack to bundle the assets (output will be `vast-client.js`):
+```Bash
+npm run build
+```
diff --git a/docs/RELEASE-TASKS.md b/docs/RELEASE-TASKS.md
@@ -0,0 +1,17 @@
+# Release tasks
+
+This document describes release tasks used during the project life-cycle.
+We might want to automate some of them in a near future (e.g via Travis).
+For now, let's use this document to make sure everyone is on the same page.
+
+## Release a new version
+
+``` Bash
+git checkout master
+npm run test
+npm run Build
+git add . && git commit -m "Bundle release [release version number]"
+npm version <major|minor|patch> # depending on the changes
+npm publish
+git push --tags origin master
+```
diff --git a/docs/client.md → docs/api/1.x/client.md b/docs/client.md → docs/api/1.x/client.md
@@ -10,7 +10,7 @@ Used for ignoring the first `n` calls. Automatically reset 1 hour after the 1st
 // Ignore the first 2 calls
 DMVAST.client.cappingFreeLunch = 2;
 
-// Those following DMVAST.client.get calls won't be done
+// The following DMVAST.client.get calls won't be done
 DMVAST.client.get(VASTUrl, cb);
 DMVAST.client.get(VASTUrl, cb);
 

diff --git a/docs/parser.md → docs/api/1.x/parser.md b/docs/parser.md → docs/api/1.x/parser.md
diff --git a/docs/tracker.md → docs/api/1.x/tracker.md b/docs/tracker.md → docs/api/1.x/tracker.md
@@ -1,6 +1,6 @@
 # VASTTracker
 
-The VAST tracker constructor will process the tracking URLs of the selected ad/creative and returns an instance of `VASTTracker`. You can create an instance with `new DMVAST.tracker( ad , creative [, variation] )`.
+The VAST tracker constructor will process the tracking URLs of the selected ad/creative and return an instance of `VASTTracker`. You can create an instance with `new DMVAST.tracker( ad , creative [, variation] )`.
 
 - `Object` *ad* – Reference to the `<Ad>` element of the selected creative.
 - `Object` *creative* – Reference to the `<Creative>` element of the selected creative.