cronapp-cordova-plugin-contentsync 4.4.0-RC.8

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2013 Adobe Systems Incorporated.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,11 @@
+PhoneGap GUI
+Copyright 2013 Adobe Systems Incorporated
+
+This software is licensed under the Apache License, Version 2.0 (see
+LICENSE file).
+
+This software uses the following third party libraries that may have
+licenses differing from that of the software itself. You can find the
+libraries and their respective licenses below.
+
+PhoneGap is a registered trademark or trademark of Adobe Systems Incorporated.

package/README.md

@@ -0,0 +1,372 @@
+# CronApp/cronapp-cordova-plugin-contentsync [![Build Status](https://travis-ci.org/phonegap/phonegap-plugin-contentsync.svg?branch=master)](https://travis-ci.org/phonegap/phonegap-plugin-contentsync) [![bitHound Score][bithound-img]][bithound-url]
+
+> Download and cache remotely hosted zipped content bundles, unzipping automatically.
+
+## Installation
+
+This requires phonegap 5.0+ ( current stable v1.2.0 )
+
+```
+phonegap plugin add cronapp-cordova-plugin-contentsync
+```
+
+It is also possible to install via repo url directly ( unstable )
+
+```
+phonegap plugin add https://github.com/CronApp/cronapp-cordova-plugin-contentsync
+```
+
+## Supported Platforms
+
+- Android
+- iOS
+- WP8
+
+
+## Quick Example
+
+```javascript
+// Create a new instance of ContentSync pointing to zipped resource 'movie-1.zip' - note
+// that the url need not end in zip - it just needs to point to something producing
+// a application/octet-stream mime type
+var sync = ContentSync.sync({
+        src: 'https://myserver/assets/movie-1.zip',
+        id: 'movie-1'
+});
+
+sync.on('progress', function(data) {
+    // data.progress
+});
+
+sync.on('complete', function(data) {
+    // data.localPath
+});
+
+sync.on('error', function(e) {
+    // e
+});
+
+sync.on('cancel', function() {
+    // triggered if event is cancelled
+});
+```
+
+#### Security note:
+
+For updating a production app using `ContentSync.sync`, **always** use HTTPS. [Other Updaters](https://sparkle-project.github.io/documentation/security/#http-mitm-vulnerability) have had vulnerabilities exposed when updating over insecure HTTP.
+
+## API
+
+### ContentSync.sync(options)
+
+Parameter | Description
+--------- | ------------
+`options.src` | `String` URL to the remotely hosted content. For updates in production, this URL should *always* use HTTPS
+`options.id` | `String` Unique identifer to reference the cached content.
+`options.type` | `String` _(Optional)_ Defines the copy strategy for the cached content.<br/>The type `replace` is the default behaviour that deletes the old content and caches the new content.<br/> The type `merge` will add the new content to the existing content. This will replace existing files, add new files, but never delete files.<br/>The type `local` returns the full path to the cached content if it exists or downloads it from `options.src` if it doesn't. `options.src` is not required if cached content actually exists.
+`options.headers` | `Object` _(Optional)_ Set of headers to use when requesting the remote content from `options.src`.
+`options.copyCordovaAssets` | `Boolean` _(Optional)_ Copies `cordova.js`, `cordova_plugins.js` and `plugins/` to sync'd folder. This operation happens after the source content has been cached, so it will override any existing Cordova assets. Default is `false`.
+`options.copyRootApp` | `Boolean` _(Optional)_ Copies the `www` folder to sync'd folder. This operation happens before the source content has been cached, then the source content is cached and finally it copies `cordova.js`, `cordova_plugins.js` and `plugins/` to sync'd folder to remain consistent with the installed plugins. Default is `false`.
+`options.timeout` | `Double` _(Optional)_ Request timeout. Default is 15 seconds.
+`options.trustHost` | `Boolean` _(Optional)_ Trust SSL host. Host defined in `options.src` will be trusted. Ignored if `options.src` is undefined. Not supported on Android.
+`options.manifest` | `String` _(Optional)_ If specified the `copyRootApp` functionality will use the list of files contained in the manifest file during it's initial copy. {Android only}
+`options.validateSrc` | `Boolean` _(Optional)_ Whether to validate src url with a HEAD request before download (ios only, default true).
+
+#### Returns
+
+- Instance of `ContentSync`.
+
+#### Example
+
+```javascript
+var sync = ContentSync.sync({
+        src: 'https://myserver/app/1',
+        id: 'app-1'
+});
+```
+
+### sync.on(event, callback)
+
+Parameter | Description
+--------- | ------------
+`event` | `String` Name of the event to listen to. See below for all the event names.
+`callback` | `Function` is called when the event is triggered.
+
+### sync.on('progress', callback)
+
+The event `progress` will be triggered on each update as the native platform downloads and caches the content.
+
+Callback Parameter | Description
+------------------ | -----------
+`data.progress` | `Integer` Progress percentage between `0 - 100`. The progress includes all actions required to cache the remote content locally. This is different on each platform, but often includes requesting, downloading, and extracting the cached content along with any system cleanup tasks.
+`data.status` | `Integer` Enumeration of `PROGRESS_STATE` to describe the current progress state.
+
+#### Example
+
+```javascript
+sync.on('progress', function(data) {
+    // data.progress
+    // data.status
+});
+```
+
+### sync.on('complete', callback)
+
+The event `complete` will be triggered when the content has been successfully cached onto the device.
+
+Callback Parameter | Description
+------------------ | -----------
+`data.localPath` | `String` The file path to the cached content. The file path will be different on each platform and may be relative or absolute. However, it is guaraneteed to be a compatible reference in the browser.
+`data.cached` | `Boolean` Set to `true` if options.type is set to `local` and cached content exists. Set to `false` otherwise.
+
+#### Example
+
+```javascript
+sync.on('complete', function(data) {
+    // data.localPath
+    // data.cached
+});
+```
+
+### sync.on('error', callback)
+
+The event `error` will trigger when an internal error occurs and the cache is aborted.
+
+Callback Parameter | Description
+------------------ | -----------
+`e.type` | `Integer` Enumeration of `ERROR_STATE` to describe the current error
+`e.responseCode` | `Integer` HTTP error code if available, `-1` otherwise
+
+#### Example
+
+```javascript
+sync.on('error', function(e) {
+    // e
+});
+```
+
+### sync.on('cancel', callback)
+
+The event `cancel` will trigger when `sync.cancel` is called.
+
+Callback Parameter | Description
+------------------ | -----------
+`no parameters` |
+
+#### Example
+
+```javascript
+sync.on('cancel', function() {
+    // user cancelled the sync operation
+});
+```
+
+### sync.cancel()
+
+Cancels the content sync operation and triggers the cancel callback.
+
+```javascript
+var sync = ContentSync.sync({
+        src: 'https://myserver/app/1',
+        id: 'app-1'
+});
+
+sync.on('cancel', function() {
+    console.log('content sync was cancelled');
+});
+
+sync.cancel();
+```
+
+### ContentSync.PROGRESS_STATE
+
+An enumeration that describes the current progress state. The mapped `String`
+values can be customized for the user's app.
+
+Integer | Description
+------- | -----------
+`0`     | `STOPPED`
+`1`     | `DOWNLOADING`
+`2`     | `EXTRACTING`
+`3`     | `COMPLETE`
+
+### ContentSync.ERROR_STATE
+
+An enumeration that describes the received error. The mapped `String`
+values can be customized for the user's app.
+
+Error Code | Description
+------------------ | -----------
+`1` | `INVALID_URL_ERR`
+`2` | `CONNECTION_ERR`
+`3` | `UNZIP_ERR`
+
+### ContentSync.unzip || Zip.unzip - ContentSync.download
+
+If you are using the [Chromium Zip plugin](https://github.com/MobileChromeApps/zip) this plugin won't work for you on iOS. However, it supports the same interface so you don't have to install both.
+
+```javascript
+
+zip.unzip(<source zip>, <destination dir>, <callback>, [<progressCallback>]);
+
+```
+
+There is also an extra convenience method that can be used to download an archive
+
+```javascript
+
+ContentSync.download(url, headers, cb)
+
+```
+
+The progress events described above also apply for these methods.
+
+#### Example
+
+```javascript
+ContentSync.PROGRESS_STATE[1] = 'Downloading the media content...';
+```
+
+### ContentSync.loadUrl (cordova-ios > 4.x with cordova-plugin-wkwebview-engine)
+
+Use this API to load assets after extraction on **cordova-ios > 4.x** and **cordova-plugin-wkwebview-engine**. Do not use `document.location` as it probably won't work. Make sure to prefix your url with `file://`
+
+```javascript
+var sync = ContentSync.sync({
+        src: 'https://myserver/app/1',
+        id: 'app-1'
+});
+
+sync.on('complete', function(data) {
+    ContentSync.loadUrl('file://' + data.localPath, function() {
+        console.log('success');
+    });
+});
+```
+
+## Working with the Native File System
+
+One of the main benefits of the content sync plugin is that it does not depend on the File or FileTransfer plugins. As a result the end user should not care where the ContentSync plugin stores it's files as long as it fills the requirements that it is private and removed when it's associated app is uninstalled.
+
+However, if you do need to use the File plugin to navigate the data downloaded by ContentSync you can use the following code snippet to get a [DirectoryEntry](https://cordova.apache.org/docs/en/3.0.0/cordova_file_file.md.html#DirectoryEntry) for the synced content.
+
+```javascript
+var sync = ContentSync.sync({
+        src: 'https://myserver/app/1',
+        id: 'app-1'
+});
+
+sync.on('complete', function(data) {
+    window.resolveLocalFileSystemURL("file://" + data.localPath, function(entry) {
+        // entry is a DirectoryEntry object
+    }, function(error) {
+        console.log("Error: " + error.code);
+    });
+});
+```
+
+As of version 1.2.0 of the plugin the location in which the plugin stores the synched content is equivaltent to the `cordova.file.dataDirectory` path from the `cordova-plugin-file` package. This is a change from previous versions so please be aware you may need to do a full sync after upgrading to version 1.2.0.
+
+Platform | Path
+------------------ | -----------
+Android | `/data/data/<app-id>/files/<options.id>`
+iOS | `/var/mobile/Applications/<UUID>/Library/NoCloud/<options.id>`
+
+## Copy Root App
+
+The asset file system is pretty slow on Android so in order to speed up the initial copy of your app to the content sync location you can specify a manifest file on Android. The file must be in the format:
+
+```javascript
+{
+    'files': [
+        'img/logo.png',
+        'index.html',
+        'js/index.js'
+   ]
+}
+```
+
+and if the file is placed in your apps `www` folder you would invoke it via:
+
+```javascript
+var sync = ContentSync.sync({
+        src: 'https://myserver/app/1',
+        id: 'app-1',
+        copyRootApp: true,
+        manifest: 'manifest.json'
+});
+```
+
+This results in the `copyRootApp` taking about a third of the time as when a manifest file is not specified.
+
+## Persistence of Synced Content
+
+Content downloaded via this plugin persists between runs of the application or reboots of the phone. The content will only be removed if the application is uninstalled or you use the File API to remove the location of the synched content.
+
+## Native Requirements
+
+- There should be no dependency on the existing File or FileTransfer plugins.
+- The native cached file path should be uniquely identifiable with the `id` parameter. This will allow the Content Sync plugin to lookup the file path at a later time using the `id` parameter.
+- The first version of the plugin assumes that all cached content is downloaded as a compressed ZIP. The native implementation must properly extract content and clean up any temporary files, such as the downloaded zip.
+- The locally compiled Cordova web assets should be copied to the cached content. This includes `cordova.js`, `cordova_plugins.js`, and `plugins/**/*`.
+- Multiple syncs should be supported at the same time.
+
+## Running Tests ( static tests against source code )
+
+```
+npm test
+```
+
+## Emulator Testing
+
+The emulator tests use cordova-paramedic and the cordova-plugin-test-framework.
+To run them you will need cordova-paramedic installed:
+
+    npm install -g cordova-paramedic
+
+Some of the tests require a simple HTTP server to host .zip payloads:
+
+    ./tests/scripts/start-server.sh
+
+Run the tests:
+
+    // From the root of this repo
+    // test ios :
+    cordova-paramedic --platform ios --plugin .
+
+    // test android :
+    cordova-paramedic --platform android --plugin .
+
+Once complete, the simple HTTP server can be stopped:
+
+    ./tests/scripts/stop-server.sh
+
+## Contributing
+
+### Editor Config
+
+The project uses [.editorconfig](http://editorconfig.org/) to define the coding
+style of each file. We recommend that you install the Editor Config extension
+for your preferred IDE.
+
+### JSHint
+
+The project uses [.jshint](http://jshint.com/docs) to define the JavaScript
+coding conventions. Most editors now have a JSHint add-on to provide on-save
+or on-edit linting.
+
+#### Install JSHint for vim
+
+1. Install [jshint](https://www.npmjs.com/package/jshint).
+1. Install [jshint.vim](https://github.com/wookiehangover/jshint.vim).
+
+#### Install JSHint for Sublime
+
+1. Install [Package Control](https://packagecontrol.io/installation)
+1. Restart Sublime
+1. Type `CMD+SHIFT+P`
+1. Type _Install Package_
+1. Type _JSHint Gutter_
+1. Sublime -> Preferences -> Package Settings -> JSHint Gutter
+1. Set `lint_on_load` and `lint_on_save` to `true`
+