Added sync operation.

bin/www/codePush.js

@@ -12,12 +12,14 @@
 /// <reference path="../typings/fileSystem.d.ts" />
 /// <reference path="../typings/fileTransfer.d.ts" />
 /// <reference path="../typings/cordova.d.ts" />
+/// <reference path="../typings/dialogs.d.ts" />
 "use strict";
 var LocalPackage = require("./localPackage");
 var RemotePackage = require("./remotePackage");
 var CodePushUtil = require("./codePushUtil");
 var NativeAppInfo = require("./nativeAppInfo");
 var Sdk = require("./sdk");
+var SyncStatus = require("./syncStatus");
 var CodePush = (function () {
     function CodePush() {
     }
@@ -82,6 +84,76 @@ var CodePush = (function () {
             CodePushUtil.invokeErrorCallback(new Error("An error ocurred while querying for updates." + CodePushUtil.getErrorMessage(e)), queryError);
         }
     };
+    CodePush.prototype.sync = function (syncCallback, syncOptions) {
+        if (!syncOptions) {
+            syncOptions = this.getDefaultSyncOptions();
+        }
+        if (syncOptions.mandatoryUpdateMessage) {
+            syncOptions.mandatoryUpdateContinueButtonLabel = syncOptions.mandatoryUpdateContinueButtonLabel || this.getDefaultSyncOptions().mandatoryUpdateContinueButtonLabel;
+            syncOptions.dialogTitle = syncOptions.dialogTitle || this.getDefaultSyncOptions().dialogTitle;
+        }
+        if (syncOptions.optionalUpdateMessage) {
+            syncOptions.optionalUpdateConfirmButtonLabel = syncOptions.optionalUpdateConfirmButtonLabel || this.getDefaultSyncOptions().optionalUpdateConfirmButtonLabel;
+            syncOptions.optionalUpdateCancelButtonLabel = syncOptions.optionalUpdateCancelButtonLabel || this.getDefaultSyncOptions().optionalUpdateCancelButtonLabel;
+            syncOptions.dialogTitle = syncOptions.dialogTitle || this.getDefaultSyncOptions().dialogTitle;
+        }
+        window.codePush.notifyApplicationReady();
+        var onError = function (error) {
+            CodePushUtil.logError("An error ocurred during sync.", error);
+            syncCallback && syncCallback(SyncStatus.ERROR);
+        };
+        var onApplySuccess = function () {
+            syncCallback && syncCallback(SyncStatus.APPLY_SUCCESS);
+        };
+        var onDownloadSuccess = function (localPackage) {
+            localPackage.apply(onApplySuccess, onError, syncOptions.rollbackTimeout);
+        };
+        var downloadAndInstallUpdate = function (remotePackage) {
+            remotePackage.download(onDownloadSuccess, onError);
+        };
+        var onUpdate = function (remotePackage) {
+            if (!remotePackage) {
+                syncCallback && syncCallback(SyncStatus.UP_TO_DATE);
+            }
+            else {
+                if (remotePackage.isMandatory && syncOptions.mandatoryUpdateMessage) {
+                    navigator.notification.alert(syncOptions.mandatoryUpdateMessage, function () { downloadAndInstallUpdate(remotePackage); }, syncOptions.dialogTitle, syncOptions.mandatoryUpdateContinueButtonLabel);
+                }
+                else if (!remotePackage.isMandatory && syncOptions && syncOptions.optionalUpdateMessage) {
+                    var optionalUpdateCallback = function (buttonIndex) {
+                        switch (buttonIndex) {
+                            case 1:
+                                downloadAndInstallUpdate(remotePackage);
+                                break;
+                            case 2:
+                            default:
+                                syncCallback && syncCallback(SyncStatus.USER_DECLINED);
+                                break;
+                        }
+                    };
+                    navigator.notification.confirm(syncOptions.optionalUpdateMessage, optionalUpdateCallback, syncOptions.dialogTitle, [syncOptions.optionalUpdateConfirmButtonLabel, syncOptions.optionalUpdateCancelButtonLabel]);
+                }
+                else {
+                    downloadAndInstallUpdate(remotePackage);
+                }
+            }
+        };
+        window.codePush.checkForUpdate(onUpdate, onError);
+    };
+    CodePush.prototype.getDefaultSyncOptions = function () {
+        if (!CodePush.DefaultSyncOptions) {
+            CodePush.DefaultSyncOptions = {
+                dialogTitle: "Update",
+                mandatoryUpdateMessage: "You will be updated to the latest version.",
+                mandatoryUpdateContinueButtonLabel: "Continue",
+                optionalUpdateMessage: "An update is available. Would you like to install it?",
+                optionalUpdateConfirmButtonLabel: "Install",
+                optionalUpdateCancelButtonLabel: "Cancel",
+                rollbackTimeout: 0
+            };
+        }
+        return CodePush.DefaultSyncOptions;
+    };
     return CodePush;
 })();
 var instance = new CodePush();

bin/www/syncStatus.js

@@ -0,0 +1,20 @@
+
+ /******************************************************************************************** 
+ 	 THIS FILE HAS BEEN COMPILED FROM TYPESCRIPT SOURCES. 
+ 	 PLEASE DO NOT MODIFY THIS FILE AS YOU WILL LOSE YOUR CHANGES WHEN RECOMPILING. 
+ 	 ALSO, PLEASE DO NOT SUBMIT PULL REQUESTS WITH CHANGES TO THIS FILE. 
+ 	 INSTEAD, EDIT THE TYPESCRIPT SOURCES UNDER THE WWW FOLDER. 
+ 	 FOR MORE INFORMATION, PLEASE SEE CONTRIBUTING.md. 
+ *********************************************************************************************/ 
+
+
+/// <reference path="../typings/codePush.d.ts" />
+"use strict";
+var SyncStatus;
+(function (SyncStatus) {
+    SyncStatus[SyncStatus["UP_TO_DATE"] = 0] = "UP_TO_DATE";
+    SyncStatus[SyncStatus["APPLY_SUCCESS"] = 1] = "APPLY_SUCCESS";
+    SyncStatus[SyncStatus["USER_DECLINED"] = 2] = "USER_DECLINED";
+    SyncStatus[SyncStatus["ERROR"] = 3] = "ERROR";
+})(SyncStatus || (SyncStatus = {}));
+module.exports = SyncStatus;

plugin.xml

@@ -10,6 +10,7 @@
         <dependency id="cordova-plugin-file-transfer" version=">=1.3.0" />
         <dependency id="cordova-plugin-file" version=">=3.0.0" />
         <dependency id="cordova-plugin-zip" version=">=3.0.0" />
+        <dependency id="cordova-plugin-dialogs" version=">=1.1.1" />
 
         <js-module src="bin/www/codePush.js" name="codePush">
             <clobbers target="codePush" />
@@ -23,6 +24,10 @@
             <clobbers target="RemotePackage" />
         </js-module>
 
+        <js-module src="bin/www/syncStatus.js" name="syncStatus">
+            <clobbers target="SyncStatus" />
+        </js-module>
+
         <js-module src="bin/www/codePushUtil.js" name="codePushUtil">
             <runs/>
         </js-module>

typings/codePush.d.ts

@@ -148,7 +148,7 @@ declare class AcquisitionStatus {
 
 declare class AcquisitionManager {
     constructor(httpRequester: Http.Requester, configuration: Configuration);
-    public queryUpdateWithCurrentPackage(currentPackage: IPackage, callback?: Callback<IRemotePackage|NativeUpdateNotification>): void;
+    public queryUpdateWithCurrentPackage(currentPackage: IPackage, callback?: Callback<IRemotePackage | NativeUpdateNotification>): void;
     public reportStatus(status: string, message?: string, callback?: Callback<void>): void;
 }
 
@@ -181,6 +181,99 @@ interface CodePushCordovaPlugin {
      * @param notifyFailed Optional callback invoked in case of an error during notifying the plugin.
      */
     notifyApplicationReady(notifySucceeded?: SuccessCallback<void>, notifyFailed?: ErrorCallback): void;
+
+    /**
+     * Convenience method for installing updates in one method call.
+     * This method is provided for simplicity, and its behavior can be replicated by using window.codePush.checkForUpdate(), RemotePackage's download() and LocalPackage's apply() methods.
+     *  
+     * The algorithm of this method is the following:
+     * - Checks for an update on the CodePush server.
+     * - If an update is available
+     *         - If the update is mandatory and the alertMessage is set in options, the user will be informed that the application will be updated to the latest version.
+     *           The update package will then be downloaded and applied. 
+     *         - If the update is not mandatory and the confirmMessage is set in options, the user will be asked if they want to update to the latest version.
+     *           If they decline, the syncCallback will be invoked with SyncStatus.USER_DECLINED. 
+     *         - Otherwise, the update package will be downloaded and applied with no user interaction.
+     * - If no update is available on the server, the syncCallback will be invoked with the SyncStatus.UP_TO_DATE.
+     * - If an error ocurrs during checking for update, downloading or applying it, the syncCallback will be invoked with the SyncStatus.ERROR.
+     * 
+     * @param syncCallback Optional callback to be called with the status of the sync operation.
+     *                     The callback will be called only once, and the possible statuses are defined by the SyncStatus enum. 
+     * @param syncOptions Optional SyncOptions parameter configuring the behavior of the sync operation.
+     * 
+     */
+    sync(syncCallback?: SuccessCallback<SyncStatus>, syncOptions?: SyncOptions): void;
+}
+
+/**
+ * Defines the possible result statuses of the window.codePush.sync operation.
+ */
+declare enum SyncStatus {
+    /**
+     * The application is up to date.
+     */
+    UP_TO_DATE,
+    
+    /**
+     * An update is available, it has been downloaded, unzipped and copied to the deployment folder.
+     * After the completion of the callback invoked with SyncStatus.APPLY_SUCCESS, the application will be reloaded with the updated code and resources.
+     */
+    APPLY_SUCCESS,
+    
+    /**
+     * An optional update is available, but the user declined to install it. The update was not downloaded.
+     */
+    USER_DECLINED,
+    
+    /**
+     * An error happened during the sync operation. This might be an error while communicating with the server, downloading or unziping the update.
+     * The console logs should contain more information about what happened. No update has been applied in this case.
+     */
+    ERROR
+}
+
+/**
+ * Defines the sync operation options.
+ */
+interface SyncOptions {
+    /**
+     * Optional time interval, in milliseconds, to wait for a notifyApplicationReady() call before marking the apply as failed and reverting to the previous version.
+     * This is the rollbackTimeout parameter used for LocalPackage's apply() method call.
+     */
+    rollbackTimeout?: number;
+    
+    /**
+     * If a mandatory update is available and this option is set, the message will be displayed to the user in an alert dialog before downloading and installing the update.
+     * The user will not be able to cancel the operation, since the update is mandatory.
+     */
+    mandatoryUpdateMessage?: string;
+    
+    /**
+     * If an optional update is available and this option is set, the message will be displayed to the user in a confirmation dialog.
+     * If the user confirms the update, it will be downloaded and installed. Otherwise, the update update is not downloaded.
+     */
+    optionalUpdateMessage?: string;
+    
+    /**
+     * The title of the dialog box used for interacting with the user in case of a mandatory or optional update.
+     * This title will only be used if at least one of mandatoryUpdateMessage or optionalUpdateMessage options are set.
+     */
+    dialogTitle?: string;
+
+    /**
+     * The label of the confirmation button in case of an optional update.
+     */
+    optionalUpdateConfirmButtonLabel?: string;
+    
+    /**
+     * The label of the cancel button in case of an optional update.
+     */
+    optionalUpdateCancelButtonLabel?: string;
+    
+    /**
+     * The label of the continue button in case of a mandatory update.
+     */
+    mandatoryUpdateContinueButtonLabel?:string
 }
 
 /**

typings/dialogs.d.ts

@@ -0,0 +1,69 @@
+// Type definitions for Apache Cordova Dialogs plugin.
+// Project: https://github.com/apache/cordova-plugin-dialogs
+// Definitions by: Microsoft Open Technologies, Inc. <http://msopentech.com>
+// Definitions: https://github.com/borisyankov/DefinitelyTyped
+// 
+// Copyright (c) Microsoft Open Technologies, Inc.
+// Licensed under the MIT license. 
+
+interface Navigator {
+    /** This plugin provides access to some native dialog UI elements. */
+    notification: Notification
+}
+
+/** This plugin provides access to some native dialog UI elements. */
+interface Notification {
+    /**
+     * Shows a custom alert or dialog box. Most Cordova implementations use a native dialog box for this feature,
+     * but some platforms use the browser's alert function, which is typically less customizable.
+     * @param message       Dialog message.
+     * @param alertCallback Callback to invoke when alert dialog is dismissed.
+     * @param title         Dialog title, defaults to 'Alert'.
+     * @param buttonName    Button name, defaults to OK.
+     */
+    alert(message: string,
+        alertCallback: () => void,
+        title?: string,
+        buttonName?: string): void;
+    /**
+     * The device plays a beep sound.
+     * @param times The number of times to repeat the beep. 
+     */
+    beep(times: number): void;
+    /**
+     * Displays a customizable confirmation dialog box.
+     * @param message           Dialog message.
+     * @param confirmCallback   Callback to invoke with index of button pressed (1, 2, or 3)
+     *                                   or when the dialog is dismissed without a button press (0).
+     * @param title             Dialog title, defaults to Confirm.
+     * @param buttonLabels      Array of strings specifying button labels, defaults to [OK,Cancel].
+     */
+    confirm(message: string,
+        confirmCallback: (choice: number) => void,
+        title?: string,
+        buttonLabels?: string[]): void;
+    /**
+     * Displays a native dialog box that is more customizable than the browser's prompt function.
+     * @param message           Dialog message.
+     * @param promptCallback    Callback to invoke when a button is pressed.
+     * @param title             Dialog title, defaults to "Prompt".
+     * @param buttonLabels      Array of strings specifying button labels, defaults to ["OK","Cancel"].
+     * @param defaultText       Default textbox input value, default: "".
+     */
+    prompt(message: string,
+        promptCallback: (result: NotificationPromptResult) => void,
+        title?: string,
+        buttonLabels?: string[],
+        defaultText?: string): void;
+}
+
+/** Object, passed to promptCallback */
+interface NotificationPromptResult {
+    /**
+     * The index of the pressed button. Note that the index uses one-based indexing, so the value is 1, 2, 3, etc.
+     * 0 is the result when the dialog is dismissed without a button press.
+     */
+    buttonIndex: number;
+    /** The text entered in the prompt dialog box. */
+    input1: string;
+}

www/codePush.ts

@@ -2,6 +2,7 @@
 /// <reference path="../typings/fileSystem.d.ts" />
 /// <reference path="../typings/fileTransfer.d.ts" />
 /// <reference path="../typings/cordova.d.ts" />
+/// <reference path="../typings/dialogs.d.ts" />
 
 "use strict";
 
@@ -13,6 +14,7 @@ import RemotePackage = require("./remotePackage");
 import CodePushUtil = require("./codePushUtil");
 import NativeAppInfo = require("./nativeAppInfo");
 import Sdk = require("./sdk");
+import SyncStatus = require("./syncStatus");
 
 /**
  * This is the entry point to Cordova CodePush SDK.
@@ -108,6 +110,120 @@ class CodePush implements CodePushCordovaPlugin {
             CodePushUtil.invokeErrorCallback(new Error("An error ocurred while querying for updates." + CodePushUtil.getErrorMessage(e)), queryError);
         }
     }
+    
+    /**
+     * Convenience method for installing updates in one method call.
+     * This method is provided for simplicity, and its behavior can be replicated by using window.codePush.checkForUpdate(), RemotePackage's download() and LocalPackage's apply() methods.
+     *  
+     * The algorithm of this method is the following:
+     * - Checks for an update on the CodePush server.
+     * - If an update is available
+     *         - If the update is mandatory and the alertMessage is set in options, the user will be informed that the application will be updated to the latest version.
+     *           The update package will then be downloaded and applied. 
+     *         - If the update is not mandatory and the confirmMessage is set in options, the user will be asked if they want to update to the latest version.
+     *           If they decline, the syncCallback will be invoked with SyncStatus.USER_DECLINED. 
+     *         - Otherwise, the update package will be downloaded and applied with no user interaction.
+     * - If no update is available on the server, the syncCallback will be invoked with the SyncStatus.UP_TO_DATE.
+     * - If an error ocurrs during checking for update, downloading or applying it, the syncCallback will be invoked with the SyncStatus.ERROR.
+     * 
+     * @param syncCallback Optional callback to be called with the status of the sync operation.
+     *                     The callback will be called only once, and the possible statuses are defined by the SyncStatus enum. 
+     * @param syncOptions Optional SyncOptions parameter configuring the behavior of the sync operation.
+     * 
+     */
+    public sync(syncCallback?: SuccessCallback<any>, syncOptions?: SyncOptions): void {
+
+        /* No options were specified, use default */
+        if (!syncOptions) {
+            syncOptions = this.getDefaultSyncOptions();
+        }
+
+        /* Some options were specified */
+        if (syncOptions.mandatoryUpdateMessage) {
+            syncOptions.mandatoryUpdateContinueButtonLabel = syncOptions.mandatoryUpdateContinueButtonLabel || this.getDefaultSyncOptions().mandatoryUpdateContinueButtonLabel;
+            syncOptions.dialogTitle = syncOptions.dialogTitle || this.getDefaultSyncOptions().dialogTitle;
+        }
+        if (syncOptions.optionalUpdateMessage) {
+            syncOptions.optionalUpdateConfirmButtonLabel = syncOptions.optionalUpdateConfirmButtonLabel || this.getDefaultSyncOptions().optionalUpdateConfirmButtonLabel;
+            syncOptions.optionalUpdateCancelButtonLabel = syncOptions.optionalUpdateCancelButtonLabel || this.getDefaultSyncOptions().optionalUpdateCancelButtonLabel;
+            syncOptions.dialogTitle = syncOptions.dialogTitle || this.getDefaultSyncOptions().dialogTitle;
+        }
+
+        window.codePush.notifyApplicationReady();
+
+        var onError = (error: Error) => {
+            CodePushUtil.logError("An error ocurred during sync.", error);
+            syncCallback && syncCallback(SyncStatus.ERROR);
+        };
+
+        var onApplySuccess = () => {
+            syncCallback && syncCallback(SyncStatus.APPLY_SUCCESS);
+        };
+
+        var onDownloadSuccess = (localPackage: ILocalPackage) => {
+            localPackage.apply(onApplySuccess, onError, syncOptions.rollbackTimeout);
+        };
+
+        var downloadAndInstallUpdate = (remotePackage: RemotePackage) => {
+            remotePackage.download(onDownloadSuccess, onError);
+        };
+
+        var onUpdate = (remotePackage: RemotePackage) => {
+            if (!remotePackage) {
+                syncCallback && syncCallback(SyncStatus.UP_TO_DATE);
+            } else {
+                if (remotePackage.isMandatory && syncOptions.mandatoryUpdateMessage) {
+                    /* Alert user */
+                    navigator.notification.alert(syncOptions.mandatoryUpdateMessage, () => { downloadAndInstallUpdate(remotePackage); }, syncOptions.dialogTitle, syncOptions.mandatoryUpdateContinueButtonLabel);
+                } else if (!remotePackage.isMandatory && syncOptions && syncOptions.optionalUpdateMessage) {
+                    /* Confirm update with user */
+                    var optionalUpdateCallback = (buttonIndex: number) => {
+                        switch (buttonIndex) {
+                            case 1:
+                                /* Install */
+                                downloadAndInstallUpdate(remotePackage);
+                                break;
+                            case 2:
+                            default:
+                                /* Cancel */
+                                syncCallback && syncCallback(SyncStatus.USER_DECLINED);
+                                break;
+                        }
+                    };
+
+                    navigator.notification.confirm(syncOptions.optionalUpdateMessage, optionalUpdateCallback, syncOptions.dialogTitle, [syncOptions.optionalUpdateConfirmButtonLabel, syncOptions.optionalUpdateCancelButtonLabel]);
+                } else {
+                    /* No user interaction */
+                    downloadAndInstallUpdate(remotePackage);
+                }
+            }
+        };
+
+        window.codePush.checkForUpdate(onUpdate, onError);
+    }
+
+    private static DefaultSyncOptions: SyncOptions;
+
+    /**
+     * Returns the default options for the CodePush sync operation.
+     * If the options are not defined yet, the static DefaultSyncOptions member will be instantiated.
+     */
+    private getDefaultSyncOptions(): SyncOptions {
+        if (!CodePush.DefaultSyncOptions) {
+            CodePush.DefaultSyncOptions = {
+                dialogTitle: "Update",
+                mandatoryUpdateMessage: "You will be updated to the latest version.",
+                mandatoryUpdateContinueButtonLabel: "Continue",
+                optionalUpdateMessage: "An update is available. Would you like to install it?",
+                optionalUpdateConfirmButtonLabel: "Install",
+                optionalUpdateCancelButtonLabel: "Cancel",
+                rollbackTimeout: 0
+            };
+        }
+
+        return CodePush.DefaultSyncOptions;
+    }
+
 }
 
 var instance = new CodePush();

www/syncStatus.ts

@@ -0,0 +1,32 @@
+/// <reference path="../typings/codePush.d.ts" />
+
+"use strict";
+
+/**
+ * Defines the possible result statuses of the window.codePush.sync operation.
+ */
+enum SyncStatus {
+    /**
+     * The application is up to date.
+     */
+    UP_TO_DATE,
+    
+    /**
+     * An update is available, it has been downloaded, unzipped and copied to the deployment folder.
+     * After the completion of the callback invoked with SyncStatus.APPLY_SUCCESS, the application will be reloaded with the updated code and resources.
+     */
+    APPLY_SUCCESS,
+    
+    /**
+     * An optional update is available, but the user declined to install it. The update was not downloaded.
+     */
+    USER_DECLINED,
+    
+    /**
+     * An error happened during the sync operation. This might be an error while communicating with the server, downloading or unziping the update.
+     * The console logs should contain more information about what happened. No update has been applied in this case.
+     */
+    ERROR
+}
+
+export = SyncStatus;