@capgo/capacitor-updater 3.3.12 → 4.0.0-alpha.11

package/README.md

@@ -1,11 +1,11 @@
 # capacitor-updater
 
-Update capacitor app without store review.
+Update Ionic Capacitor apps without App/Play Store review (Code-push / hot-code updates).
 
-You have 3 ways possible :
-- use [capgo.app](https://capgo.app) a full featured auto update system in 5 min Setup, to manage version, update, revert and see stats.
-- use your own server update with auto update system
-- use manual methods to zip, upload, download, from JS to do it when you want.
+Usage options:
+- use [capgo.app](https://capgo.app), a full featured auto update system. (5 min Setup, easily manage versions, update, revert, and see detailed stats.)
+- integrate your own API with this plugin's auto update system.
+- use manual methods to zip, upload, download, from application code - you have full control.
 
 
 ## Community
@@ -14,20 +14,20 @@ Join the [discord](https://discord.gg/VnYRvBfgA6) to get help.
 ## Documentation
 I maintain a more user friendly and complete [documentation](https://github.com/Cap-go/capacitor-updater/wiki) in GitHub wiki.
 
-## install plugin
+## Installation
 
 ```bash
 npm install @capgo/capacitor-updater
 npx cap sync
 ```
 
-## Auto update setup
+## Auto-update setup
 
 Create account in [capgo.app](https://capgo.app) and get your [API key](https://capgo.app/app/apikeys)
-- Login to CLI `npx @capgo/cli login API_KEY`
-- Add app with CLI `npx @capgo/cli add`
-- Upload app to channel production `npx @capgo/cli upload -c production`
-- Set channel production public `npx @capgo/cli set -c production -s public`
+- Download the CLI `npm i -g @capgo/cli`
+- Add app from CLI `capgo add -a API_KEY`
+- Upload app `capgo upload -a API_KEY`
+- Upload app `capgo set -a API_KEY -s public`
 - Edit your `capacitor.config.json` like below, set `autoUpdate` to true.
 ```json
 // capacitor.config.json
@@ -45,92 +45,96 @@ Create account in [capgo.app](https://capgo.app) and get your [API key](https://
 ```javascript
   import { CapacitorUpdater } from '@capgo/capacitor-updater'
   CapacitorUpdater.notifyAppReady()
-  // To let auto update know you app boot well.
 ```
+This tells Capacitor Updator that the current update bundle has loaded succesfully. Failing to call this method will cause your application to be rolled back to the previously successful version (or built-in bundle).
 
 - Do `npm run build && npx cap copy` to copy the build to capacitor.
 - Run the app and see app auto update after each backgrounding.
-- If update fail it will roolback to previous version.
+- Failed updates will automatically roll back to the last successful version.
 
-See more there in the [Auto update](
-https://github.com/Cap-go/capacitor-updater/wiki) documentation.
+See more details in the [Auto update](https://github.com/Cap-go/capacitor-updater/wiki) documentation.
 
 
 ## Manual setup
 
-Download app update from url when user enter the app
-install it when user background the app.
-
-In your main code :
+Download update distribution zipfiles from a custom url. Manually control the entire update process.
 
+- Add to your main code
 ```javascript
   import { CapacitorUpdater } from '@capgo/capacitor-updater'
+  CapacitorUpdater.notifyAppReady()
+```
+This informs Capacitor Updator that the current update bundle has loaded succesfully. Failing to call this method will cause your application to be rolled back to the previously successful version (or built-in bundle).
+- Add this to your application.
+```javascript
+  const version = await CapacitorUpdater.download({
+    url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
+  })
+  await CapacitorUpdater.set(version); // sets the new version, and reloads the app
+```
+- Failed updates will automatically roll back to the last successful version.
+- Example: Using App-state to control updates, with SplashScreen:
+You might also consider performing auto-update when application state changes, and using the Splash Screen to improve user experience.
+```javascript
+  import { CapacitorUpdater, VersionInfo } from '@capgo/capacitor-updater'
   import { SplashScreen } from '@capacitor/splash-screen'
   import { App } from '@capacitor/app'
 
-  let version = ""
-  App.addListener('appStateChange', async(state) => {
+  let version: VersionInfo;
+  App.addListener('appStateChange', async (state) => {
       if (state.isActive) {
-        // Do the download during user active app time to prevent failed download
+        // Ensure download occurs while the app is active, or download may fail
         version = await CapacitorUpdater.download({
-        url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
+          url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
         })
       }
-      if (!state.isActive && version !== "") {
-        // Do the switch when user leave app
+
+      if (!state.isActive && version) {
+        // Activate the update when the application is sent to background
         SplashScreen.show()
         try {
-          await CapacitorUpdater.set(version)
+          await CapacitorUpdater.set(version);
+          // At this point, the new version should be active, and will need to hide the splash screen
         } catch () {
-          SplashScreen.hide() // in case the set fail, otherwise the new app will have to hide it
+          SplashScreen.hide() // Hide the splash screen again if something went wrong
         }
       }
   })
 
-  // or do it when click on button
-  const updateNow = async () => {
-    const version = await CapacitorUpdater.download({
-      url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
-    })
-    // show the splashscreen to let the update happen
-    SplashScreen.show()
-    await CapacitorUpdater.set(version)
-    SplashScreen.hide() // in case the set fail, otherwise the new app will have to hide it
-  }
 ```
 
-*Be extra careful for your update* if you send a broken update, the app will crash until the user reinstalls it.
-
-If you need more secure way to update your app, you can use Auto update system.
-
-You can list the version and manage it with the command below.
+TIP: If you prefer a secure and automated way to update your app, you can use [capgo.app](https://capgo.app) - a full-featured, auto update system.
 
-### Packaging `dist.zip`
+### Packaging `dist.zip` update bundles
 
-Whatever you choose to name the file you download from your release/update server URL, the zip file should contain the full contents of your production Capacitor build output folder, usually `{project directory}/dist/` or `{project directory}/www/`. This is where `index.html` will be located, and it should also contain all bundled JavaScript, CSS, and web resources necessary for your app to run.
+Capacitor Updator works by unzipping a compiled app bundle to the native device filesystem. Whatever you choose to name the file you upload/download from your release/update server URL (via either manual or automatic updating), this `.zip` bundle must meet the following requirements:
 
-Do not password encrypt this file, or it will fail to unpack.
+- The zip file should contain the full contents of your production Capacitor build output folder, usually `{project directory}/dist/` or `{project directory}/www/`. This is where `index.html` will be located, and it should also contain all bundled JavaScript, CSS, and web resources necessary for your app to run.
+- Do not password encrypt the bundle zip file, or it will fail to unpack.
+- Make sure the bundle does not contain any extra hidden files or folders, or it may fail to unpack.
 
 ## API
 
 <docgen-index>
 
+* [`notifyAppReady()`](#notifyappready)
 * [`download(...)`](#download)
+* [`next(...)`](#next)
 * [`set(...)`](#set)
-* [`getId()`](#getid)
-* [`getPluginVersion()`](#getpluginversion)
 * [`delete(...)`](#delete)
 * [`list()`](#list)
 * [`reset(...)`](#reset)
 * [`current()`](#current)
 * [`reload()`](#reload)
-* [`versionName()`](#versionname)
-* [`notifyAppReady()`](#notifyappready)
-* [`delayUpdate()`](#delayupdate)
-* [`cancelDelay()`](#canceldelay)
+* [`setDelay(...)`](#setdelay)
+* [`getLatest(...)`](#getlatest)
 * [`addListener('download', ...)`](#addlistenerdownload)
+* [`addListener('downloadComplete', ...)`](#addlistenerdownloadcomplete)
 * [`addListener('majorAvailable', ...)`](#addlistenermajoravailable)
-* [`addListener('updateAvailable', ...)`](#addlistenerupdateavailable)
+* [`addListener('updateFailed', ...)`](#addlistenerupdatefailed)
+* [`getId()`](#getid)
+* [`getPluginVersion()`](#getpluginversion)
+* [`isAutoUpdateEnabled()`](#isautoupdateenabled)
 * [`addListener(string, ...)`](#addlistenerstring)
 * [`removeAllListeners()`](#removealllisteners)
 * [Interfaces](#interfaces)
@@ -141,60 +145,64 @@ Do not password encrypt this file, or it will fail to unpack.
 <docgen-api>
 <!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
 
-### download(...)
+### notifyAppReady()
 
 ```typescript
-download(options: { url: string; }) => Promise<{ version: string; }>
+notifyAppReady() => Promise<BundleInfo>
 ```
 
-Download a new version from the provided URL, it should be a zip file, with files inside or with a unique folder inside with all your files
-
-| Param         | Type                          |
-| ------------- | ----------------------------- |
-| **`options`** | <code>{ url: string; }</code> |
+Notify Capacitor Updater that the current bundle is working (a rollback will occur of this method is not called on every app launch)
 
-**Returns:** <code>Promise&lt;{ version: string; }&gt;</code>
+**Returns:** <code>Promise&lt;<a href="#bundleinfo">BundleInfo</a>&gt;</code>
 
 --------------------
 
 
-### set(...)
+### download(...)
 
 ```typescript
-set(options: { version: string; versionName?: string; }) => Promise<void>
+download(options: { url: string; version?: string; }) => Promise<BundleInfo>
 ```
 
-Set version as current version, set will return an error if there are is no index.html file inside the version folder. `versionName` is optional and it's a custom value that will be saved for you
+Download a new version from the provided URL, it should be a zip file, with files inside or with a unique id inside with all your files
+
+| Param         | Type                                            |
+| ------------- | ----------------------------------------------- |
+| **`options`** | <code>{ url: string; version?: string; }</code> |
 
-| Param         | Type                                                    |
-| ------------- | ------------------------------------------------------- |
-| **`options`** | <code>{ version: string; versionName?: string; }</code> |
+**Returns:** <code>Promise&lt;<a href="#bundleinfo">BundleInfo</a>&gt;</code>
 
 --------------------
 
 
-### getId()
+### next(...)
 
 ```typescript
-getId() => Promise<{ id: string; }>
+next(options: { id: string; }) => Promise<BundleInfo>
 ```
 
-Get unique ID used to identify device into auto update server
+Set the next bundle to be used when the app is reloaded.
 
-**Returns:** <code>Promise&lt;{ id: string; }&gt;</code>
+| Param         | Type                         |
+| ------------- | ---------------------------- |
+| **`options`** | <code>{ id: string; }</code> |
+
+**Returns:** <code>Promise&lt;<a href="#bundleinfo">BundleInfo</a>&gt;</code>
 
 --------------------
 
 
-### getPluginVersion()
+### set(...)
 
 ```typescript
-getPluginVersion() => Promise<{ version: string; }>
+set(options: { id: string; }) => Promise<void>
 ```
 
-Get plugin version used in native code
+Set the current bundle and immediately reloads the app.
 
-**Returns:** <code>Promise&lt;{ version: string; }&gt;</code>
+| Param         | Type                         |
+| ------------- | ---------------------------- |
+| **`options`** | <code>{ id: string; }</code> |
 
 --------------------
 
@@ -202,14 +210,14 @@ Get plugin version used in native code
 ### delete(...)
 
 ```typescript
-delete(options: { version: string; }) => Promise<void>
+delete(options: { id: string; }) => Promise<void>
 ```
 
-Delete version in storage
+Delete bundle in storage
 
-| Param         | Type                              |
-| ------------- | --------------------------------- |
-| **`options`** | <code>{ version: string; }</code> |
+| Param         | Type                         |
+| ------------- | ---------------------------- |
+| **`options`** | <code>{ id: string; }</code> |
 
 --------------------
 
@@ -217,12 +225,12 @@ Delete version in storage
 ### list()
 
 ```typescript
-list() => Promise<{ versions: string[]; }>
+list() => Promise<{ bundles: BundleInfo[]; }>
 ```
 
 Get all available versions
 
-**Returns:** <code>Promise&lt;{ versions: string[]; }&gt;</code>
+**Returns:** <code>Promise&lt;{ bundles: BundleInfo[]; }&gt;</code>
 
 --------------------
 
@@ -230,14 +238,14 @@ Get all available versions
 ### reset(...)
 
 ```typescript
-reset(options?: { toAutoUpdate?: boolean | undefined; } | undefined) => Promise<void>
+reset(options?: { toLastSuccessful?: boolean | undefined; } | undefined) => Promise<void>
 ```
 
 Set the `builtin` version (the one sent to Apple store / Google play store ) as current version
 
-| Param         | Type                                     |
-| ------------- | ---------------------------------------- |
-| **`options`** | <code>{ toAutoUpdate?: boolean; }</code> |
+| Param         | Type                                         |
+| ------------- | -------------------------------------------- |
+| **`options`** | <code>{ toLastSuccessful?: boolean; }</code> |
 
 --------------------
 
@@ -245,12 +253,12 @@ Set the `builtin` version (the one sent to Apple store / Google play store ) as
 ### current()
 
 ```typescript
-current() => Promise<{ current: string; currentNative: string; }>
+current() => Promise<{ bundle: BundleInfo; native: string; }>
 ```
 
-Get the current version, if none are set it returns `builtin`, currentNative is the original version install on the device
+Get the current bundle, if none are set it returns `builtin`, currentNative is the original bundle installed on the device
 
-**Returns:** <code>Promise&lt;{ current: string; currentNative: string; }&gt;</code>
+**Returns:** <code>Promise&lt;{ bundle: <a href="#bundleinfo">BundleInfo</a>; native: string; }&gt;</code>
 
 --------------------
 
@@ -266,48 +274,38 @@ Reload the view
 --------------------
 
 
-### versionName()
+### setDelay(...)
 
 ```typescript
-versionName() => Promise<{ versionName: string; }>
+setDelay(options: { delay: boolean; }) => Promise<void>
 ```
 
-Get the version name, if it was set during the set phase
-
-**Returns:** <code>Promise&lt;{ versionName: string; }&gt;</code>
+Set delay to skip updates in the next time the app goes into the background
 
---------------------
-
-
-### notifyAppReady()
-
-```typescript
-notifyAppReady() => Promise<void>
-```
+| Param         | Type                             |
+| ------------- | -------------------------------- |
+| **`options`** | <code>{ delay: boolean; }</code> |
 
-Notify native plugin that the update is working, only in auto-update
+**Since:** 4.0.0
 
 --------------------
 
 
-### delayUpdate()
+### getLatest(...)
 
 ```typescript
-delayUpdate() => Promise<void>
+getLatest(options: { delay: boolean; }) => Promise<latestVersion>
 ```
 
-Skip updates in the next time the app goes into the background, only in auto-update
-
---------------------
+Get Latest version available from update Url
 
+| Param         | Type                             |
+| ------------- | -------------------------------- |
+| **`options`** | <code>{ delay: boolean; }</code> |
 
-### cancelDelay()
+**Returns:** <code>Promise&lt;<a href="#latestversion">latestVersion</a>&gt;</code>
 
-```typescript
-cancelDelay() => Promise<void>
-```
-
-allow update in the next time the app goes into the background, only in auto-update
+**Since:** 4.0.0
 
 --------------------
 
@@ -332,6 +330,26 @@ Listen for download event in the App, let you know when the download is started,
 --------------------
 
 
+### addListener('downloadComplete', ...)
+
+```typescript
+addListener(eventName: 'downloadComplete', listenerFunc: DownloadCompleteListener) => Promise<PluginListenerHandle> & PluginListenerHandle
+```
+
+Listen for download event in the App, let you know when the download is started, loading and finished
+
+| Param              | Type                                                                          |
+| ------------------ | ----------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'downloadComplete'</code>                                               |
+| **`listenerFunc`** | <code><a href="#downloadcompletelistener">DownloadCompleteListener</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt; & <a href="#pluginlistenerhandle">PluginListenerHandle</a></code>
+
+**Since:** 4.0.0
+
+--------------------
+
+
 ### addListener('majorAvailable', ...)
 
 ```typescript
@@ -352,18 +370,18 @@ Listen for Major update event in the App, let you know when major update is bloc
 --------------------
 
 
-### addListener('updateAvailable', ...)
+### addListener('updateFailed', ...)
 
 ```typescript
-addListener(eventName: 'updateAvailable', listenerFunc: UpdateAvailableListener) => Promise<PluginListenerHandle> & PluginListenerHandle
+addListener(eventName: 'updateFailed', listenerFunc: UpdateFailedListener) => Promise<PluginListenerHandle> & PluginListenerHandle
 ```
 
 Listen for update event in the App, let you know when update is ready to install at next app start
 
-| Param              | Type                                                                        |
-| ------------------ | --------------------------------------------------------------------------- |
-| **`eventName`**    | <code>'updateAvailable'</code>                                              |
-| **`listenerFunc`** | <code><a href="#updateavailablelistener">UpdateAvailableListener</a></code> |
+| Param              | Type                                                                  |
+| ------------------ | --------------------------------------------------------------------- |
+| **`eventName`**    | <code>'updateFailed'</code>                                           |
+| **`listenerFunc`** | <code><a href="#updatefailedlistener">UpdateFailedListener</a></code> |
 
 **Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt; & <a href="#pluginlistenerhandle">PluginListenerHandle</a></code>
 
@@ -372,6 +390,45 @@ Listen for update event in the App, let you know when update is ready to install
 --------------------
 
 
+### getId()
+
+```typescript
+getId() => Promise<{ id: string; }>
+```
+
+Get unique ID used to identify device (sent to auto update server)
+
+**Returns:** <code>Promise&lt;{ id: string; }&gt;</code>
+
+--------------------
+
+
+### getPluginVersion()
+
+```typescript
+getPluginVersion() => Promise<{ version: string; }>
+```
+
+Get the native Capacitor Updater plugin version (sent to auto update server)
+
+**Returns:** <code>Promise&lt;{ version: string; }&gt;</code>
+
+--------------------
+
+
+### isAutoUpdateEnabled()
+
+```typescript
+isAutoUpdateEnabled() => Promise<{ enabled: boolean; }>
+```
+
+Get the state of auto update config. This will return `false` in manual mode.
+
+**Returns:** <code>Promise&lt;{ enabled: boolean; }&gt;</code>
+
+--------------------
+
+
 ### addListener(string, ...)
 
 ```typescript
@@ -400,6 +457,27 @@ removeAllListeners() => Promise<void>
 ### Interfaces
 
 
+#### BundleInfo
+
+| Prop             | Type                                                  |
+| ---------------- | ----------------------------------------------------- |
+| **`id`**         | <code>string</code>                                   |
+| **`version`**    | <code>string</code>                                   |
+| **`downloaded`** | <code>string</code>                                   |
+| **`status`**     | <code><a href="#bundlestatus">BundleStatus</a></code> |
+
+
+#### latestVersion
+
+| Prop          | Type                 | Description             | Since |
+| ------------- | -------------------- | ----------------------- | ----- |
+| **`version`** | <code>string</code>  | Res of getLatest method | 4.0.0 |
+| **`major`**   | <code>boolean</code> |                         |       |
+| **`message`** | <code>string</code>  |                         |       |
+| **`old`**     | <code>string</code>  |                         |       |
+| **`url`**     | <code>string</code>  |                         |       |
+
+
 #### PluginListenerHandle
 
 | Prop         | Type                                      |
@@ -409,41 +487,59 @@ removeAllListeners() => Promise<void>
 
 #### DownloadEvent
 
-| Prop          | Type                | Description                                    | Since  |
-| ------------- | ------------------- | ---------------------------------------------- | ------ |
-| **`percent`** | <code>number</code> | Current status of download, between 0 and 100. | 2.0.11 |
+| Prop          | Type                                              | Description                                    | Since |
+| ------------- | ------------------------------------------------- | ---------------------------------------------- | ----- |
+| **`percent`** | <code>number</code>                               | Current status of download, between 0 and 100. | 4.0.0 |
+| **`bundle`**  | <code><a href="#bundleinfo">BundleInfo</a></code> |                                                |       |
+
+
+#### DownloadCompleteEvent
+
+| Prop         | Type                                              | Description                          | Since |
+| ------------ | ------------------------------------------------- | ------------------------------------ | ----- |
+| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emit when a new update is available. | 4.0.0 |
 
 
 #### MajorAvailableEvent
 
 | Prop          | Type                | Description                                 | Since |
 | ------------- | ------------------- | ------------------------------------------- | ----- |
-| **`version`** | <code>string</code> | Emit when a new major version is available. | 2.3.0 |
+| **`version`** | <code>string</code> | Emit when a new major version is available. | 4.0.0 |
 
 
-#### UpdateAvailableEvent
+#### UpdateFailedEvent
 
-| Prop          | Type                | Description                          | Since |
-| ------------- | ------------------- | ------------------------------------ | ----- |
-| **`version`** | <code>string</code> | Emit when a new update is available. | 3.0.0 |
+| Prop         | Type                                              | Description                           | Since |
+| ------------ | ------------------------------------------------- | ------------------------------------- | ----- |
+| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emit when a update failed to install. | 4.0.0 |
 
 
 ### Type Aliases
 
 
+#### BundleStatus
+
+<code>'success' | 'error' | 'pending' | 'downloading'</code>
+
+
 #### DownloadChangeListener
 
 <code>(state: <a href="#downloadevent">DownloadEvent</a>): void</code>
 
 
+#### DownloadCompleteListener
+
+<code>(state: <a href="#downloadcompleteevent">DownloadCompleteEvent</a>): void</code>
+
+
 #### MajorAvailableListener
 
 <code>(state: <a href="#majoravailableevent">MajorAvailableEvent</a>): void</code>
 
 
-#### UpdateAvailableListener
+#### UpdateFailedListener
 
-<code>(state: <a href="#updateavailableevent">UpdateAvailableEvent</a>): void</code>
+<code>(state: <a href="#updatefailedevent">UpdateFailedEvent</a>): void</code>
 
 </docgen-api>