@capgo/capacitor-updater 7.37.0 → 7.39.0

package/dist/docs.json

@@ -1289,6 +1289,179 @@
           "SetAppIdOptions"
         ],
         "slug": "setappid"
+      },
+      {
+        "name": "getAppUpdateInfo",
+        "signature": "(options?: GetAppUpdateInfoOptions | undefined) => Promise<AppUpdateInfo>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "Optional {@link GetAppUpdateInfoOptions} with country code for iOS.",
+            "type": "GetAppUpdateInfoOptions | undefined"
+          }
+        ],
+        "returns": "Promise<AppUpdateInfo>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options Optional {@link GetAppUpdateInfoOptions} with country code for iOS."
+          },
+          {
+            "name": "returns",
+            "text": "Information about the current and available app versions."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If the operation fails or store information is unavailable."
+          },
+          {
+            "name": "since",
+            "text": "8.0.0"
+          }
+        ],
+        "docs": "Get information about the app's availability in the App Store or Play Store.\n\nThis method checks the native app stores to see if a newer version of the app\nis available for download. This is different from Capgo's OTA updates - this\nchecks for native app updates that require going through the app stores.\n\n**Platform differences:**\n- **Android**: Uses Play Store's In-App Updates API for accurate update information\n- **iOS**: Queries the App Store lookup API (requires country code for accurate results)\n\n**Returns information about:**\n- Current installed version\n- Available version in the store (if any)\n- Whether an update is available\n- Update priority (Android only)\n- Whether immediate/flexible updates are allowed (Android only)\n\nUse this to:\n- Check if users need to update from the app store\n- Show \"Update Available\" prompts for native updates\n- Implement version gating (require minimum native version)\n- Combine with Capgo OTA updates for a complete update strategy",
+        "complexTypes": [
+          "AppUpdateInfo",
+          "GetAppUpdateInfoOptions"
+        ],
+        "slug": "getappupdateinfo"
+      },
+      {
+        "name": "openAppStore",
+        "signature": "(options?: OpenAppStoreOptions | undefined) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "Optional {@link OpenAppStoreOptions} to customize which app's store page to open.",
+            "type": "OpenAppStoreOptions | undefined"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options Optional {@link OpenAppStoreOptions} to customize which app's store page to open."
+          },
+          {
+            "name": "returns",
+            "text": "Resolves when the store is opened."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If the store cannot be opened."
+          },
+          {
+            "name": "since",
+            "text": "8.0.0"
+          }
+        ],
+        "docs": "Open the app's page in the App Store or Play Store.\n\nThis navigates the user to your app's store listing where they can manually\nupdate the app. Use this as a fallback when in-app updates are not available\nor when the user needs to update on iOS.\n\n**Platform behavior:**\n- **Android**: Opens Play Store to the app's page\n- **iOS**: Opens App Store to the app's page\n\n**Customization options:**\n- `appId`: Specify a custom App Store ID (iOS) - useful for opening a different app's page\n- `packageName`: Specify a custom package name (Android) - useful for opening a different app's page",
+        "complexTypes": [
+          "OpenAppStoreOptions"
+        ],
+        "slug": "openappstore"
+      },
+      {
+        "name": "performImmediateUpdate",
+        "signature": "() => Promise<AppUpdateResult>",
+        "parameters": [],
+        "returns": "Promise<AppUpdateResult>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "Result indicating success, cancellation, or failure."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If not on Android, no update is available, or immediate updates not allowed."
+          },
+          {
+            "name": "since",
+            "text": "8.0.0"
+          }
+        ],
+        "docs": "Perform an immediate in-app update on Android.\n\nThis triggers Google Play's immediate update flow, which:\n1. Shows a full-screen update UI\n2. Downloads and installs the update\n3. Restarts the app automatically\n\nThe user cannot continue using the app until the update is complete.\nThis is ideal for critical updates that must be installed immediately.\n\n**Requirements:**\n- Android only (throws error on iOS)\n- An update must be available (check with {@link getAppUpdateInfo} first)\n- The update must allow immediate updates (`immediateUpdateAllowed: true`)\n\n**User experience:**\n- Full-screen blocking UI\n- Progress shown during download\n- App automatically restarts after installation",
+        "complexTypes": [
+          "AppUpdateResult"
+        ],
+        "slug": "performimmediateupdate"
+      },
+      {
+        "name": "startFlexibleUpdate",
+        "signature": "() => Promise<AppUpdateResult>",
+        "parameters": [],
+        "returns": "Promise<AppUpdateResult>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "Result indicating the update was started, cancelled, or failed."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If not on Android, no update is available, or flexible updates not allowed."
+          },
+          {
+            "name": "since",
+            "text": "8.0.0"
+          }
+        ],
+        "docs": "Start a flexible in-app update on Android.\n\nThis triggers Google Play's flexible update flow, which:\n1. Downloads the update in the background\n2. Allows the user to continue using the app\n3. Notifies when download is complete\n4. Requires calling {@link completeFlexibleUpdate} to install\n\nMonitor the download progress using the `onFlexibleUpdateStateChange` listener.\n\n**Requirements:**\n- Android only (throws error on iOS)\n- An update must be available (check with {@link getAppUpdateInfo} first)\n- The update must allow flexible updates (`flexibleUpdateAllowed: true`)\n\n**Typical flow:**\n1. Call `startFlexibleUpdate()` to begin download\n2. Listen to `onFlexibleUpdateStateChange` for progress\n3. When status is `DOWNLOADED`, prompt user to restart\n4. Call `completeFlexibleUpdate()` to install and restart",
+        "complexTypes": [
+          "AppUpdateResult"
+        ],
+        "slug": "startflexibleupdate"
+      },
+      {
+        "name": "completeFlexibleUpdate",
+        "signature": "() => Promise<void>",
+        "parameters": [],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "Resolves when the update installation begins (app will restart)."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If not on Android or no downloaded update is pending."
+          },
+          {
+            "name": "since",
+            "text": "8.0.0"
+          }
+        ],
+        "docs": "Complete a flexible in-app update on Android.\n\nAfter a flexible update has been downloaded (status `DOWNLOADED` in\n`onFlexibleUpdateStateChange`), call this method to install the update\nand restart the app.\n\n**Important:** This will immediately restart the app. Make sure to:\n- Save any user data before calling\n- Prompt the user before restarting\n- Only call when the download status is `DOWNLOADED`",
+        "complexTypes": [],
+        "slug": "completeflexibleupdate"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'onFlexibleUpdateStateChange', listenerFunc: (state: FlexibleUpdateState) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'onFlexibleUpdateStateChange'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(state: FlexibleUpdateState) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "8.0.0"
+          }
+        ],
+        "docs": "Listen for flexible update state changes on Android.\n\nThis event fires during the flexible update download process, providing:\n- Download progress (bytes downloaded / total bytes)\n- Installation status changes\n\n**Install status values:**\n- `UNKNOWN` (0): Unknown status\n- `PENDING` (1): Download pending\n- `DOWNLOADING` (2): Download in progress\n- `INSTALLING` (3): Installing the update\n- `INSTALLED` (4): Update installed (app restart needed)\n- `FAILED` (5): Update failed\n- `CANCELED` (6): Update was canceled\n- `DOWNLOADED` (11): Download complete, ready to install\n\nWhen status is `DOWNLOADED`, you should prompt the user and call\n{@link completeFlexibleUpdate} to finish the installation.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "FlexibleUpdateState"
+        ],
+        "slug": "addlisteneronflexibleupdatestatechange-"
       }
     ],
     "properties": []
@@ -2420,9 +2593,442 @@
           "type": "string"
         }
       ]
+    },
+    {
+      "name": "AppUpdateInfo",
+      "slug": "appupdateinfo",
+      "docs": "Information about app updates available in the App Store or Play Store.",
+      "tags": [
+        {
+          "text": "8.0.0",
+          "name": "since"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "currentVersionName",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The currently installed version name (e.g., \"1.2.3\").",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "availableVersionName",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The version name available in the store, if an update is available.\nMay be undefined if no update information is available.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "currentVersionCode",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The currently installed version code (Android) or build number (iOS).",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "availableVersionCode",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The version code available in the store (Android only).\nOn iOS, this will be the same as `availableVersionName`.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "availableVersionReleaseDate",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The release date of the available version (iOS only).\nFormat: ISO 8601 date string.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "updateAvailability",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The current update availability status.",
+          "complexTypes": [
+            "AppUpdateAvailability"
+          ],
+          "type": "AppUpdateAvailability"
+        },
+        {
+          "name": "updatePriority",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The priority of the update as set by the developer in Play Console (Android only).\nValues range from 0 (default/lowest) to 5 (highest priority).\n\nUse this to decide whether to show an update prompt or force an update.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "immediateUpdateAllowed",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Whether an immediate update is allowed (Android only).\n\nIf `true`, you can call {@link CapacitorUpdaterPlugin.performImmediateUpdate}.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
+        {
+          "name": "flexibleUpdateAllowed",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Whether a flexible update is allowed (Android only).\n\nIf `true`, you can call {@link CapacitorUpdaterPlugin.startFlexibleUpdate}.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
+        {
+          "name": "clientVersionStalenessDays",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Number of days since the update became available (Android only).\n\nUse this to implement \"update nagging\" - remind users more frequently\nas the update ages.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "installStatus",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The current install status of a flexible update (Android only).",
+          "complexTypes": [
+            "FlexibleUpdateInstallStatus"
+          ],
+          "type": "FlexibleUpdateInstallStatus"
+        },
+        {
+          "name": "minimumOsVersion",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The minimum OS version required for the available update (iOS only).",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
+    },
+    {
+      "name": "GetAppUpdateInfoOptions",
+      "slug": "getappupdateinfooptions",
+      "docs": "Options for {@link CapacitorUpdaterPlugin.getAppUpdateInfo}.",
+      "tags": [
+        {
+          "text": "8.0.0",
+          "name": "since"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "country",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Two-letter country code (ISO 3166-1 alpha-2) for the App Store lookup.\n\nThis is required on iOS to get accurate App Store information, as app\navailability and versions can vary by country.\n\nExamples: \"US\", \"GB\", \"DE\", \"JP\", \"FR\"\n\nOn Android, this option is ignored as the Play Store handles region\ndetection automatically.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
+    },
+    {
+      "name": "OpenAppStoreOptions",
+      "slug": "openappstoreoptions",
+      "docs": "Options for {@link CapacitorUpdaterPlugin.openAppStore}.",
+      "tags": [
+        {
+          "text": "8.0.0",
+          "name": "since"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "packageName",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The Android package name to open in the Play Store.\n\nIf not specified, uses the current app's package name.\nUse this to open a different app's store page.\n\nOnly used on Android.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "appId",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The iOS App Store ID to open.\n\nIf not specified, uses the current app's bundle identifier to look up the app.\nUse this to open a different app's store page or when automatic lookup fails.\n\nOnly used on iOS.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
+    },
+    {
+      "name": "AppUpdateResult",
+      "slug": "appupdateresult",
+      "docs": "Result of an app update operation.",
+      "tags": [
+        {
+          "text": "8.0.0",
+          "name": "since"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "code",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The result code of the update operation.",
+          "complexTypes": [
+            "AppUpdateResultCode"
+          ],
+          "type": "AppUpdateResultCode"
+        }
+      ]
+    },
+    {
+      "name": "FlexibleUpdateState",
+      "slug": "flexibleupdatestate",
+      "docs": "State information for flexible update progress (Android only).",
+      "tags": [
+        {
+          "text": "8.0.0",
+          "name": "since"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "installStatus",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The current installation status.",
+          "complexTypes": [
+            "FlexibleUpdateInstallStatus"
+          ],
+          "type": "FlexibleUpdateInstallStatus"
+        },
+        {
+          "name": "bytesDownloaded",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Number of bytes downloaded so far.\nOnly available during the `DOWNLOADING` status.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "totalBytesToDownload",
+          "tags": [
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Total number of bytes to download.\nOnly available during the `DOWNLOADING` status.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        }
+      ]
+    }
+  ],
+  "enums": [
+    {
+      "name": "AppUpdateAvailability",
+      "slug": "appupdateavailability",
+      "members": [
+        {
+          "name": "UNKNOWN",
+          "value": "0",
+          "tags": [],
+          "docs": "Update availability is unknown.\nThis typically means the check hasn't completed or failed."
+        },
+        {
+          "name": "UPDATE_NOT_AVAILABLE",
+          "value": "1",
+          "tags": [],
+          "docs": "No update is available.\nThe installed version is the latest."
+        },
+        {
+          "name": "UPDATE_AVAILABLE",
+          "value": "2",
+          "tags": [],
+          "docs": "An update is available for download."
+        },
+        {
+          "name": "UPDATE_IN_PROGRESS",
+          "value": "3",
+          "tags": [],
+          "docs": "An update is currently being downloaded or installed."
+        }
+      ]
+    },
+    {
+      "name": "FlexibleUpdateInstallStatus",
+      "slug": "flexibleupdateinstallstatus",
+      "members": [
+        {
+          "name": "UNKNOWN",
+          "value": "0",
+          "tags": [],
+          "docs": "Unknown install status."
+        },
+        {
+          "name": "PENDING",
+          "value": "1",
+          "tags": [],
+          "docs": "Download is pending and will start soon."
+        },
+        {
+          "name": "DOWNLOADING",
+          "value": "2",
+          "tags": [],
+          "docs": "Download is in progress.\nCheck `bytesDownloaded` and `totalBytesToDownload` for progress."
+        },
+        {
+          "name": "INSTALLING",
+          "value": "3",
+          "tags": [],
+          "docs": "The update is being installed."
+        },
+        {
+          "name": "INSTALLED",
+          "value": "4",
+          "tags": [],
+          "docs": "The update has been installed.\nThe app needs to be restarted to use the new version."
+        },
+        {
+          "name": "FAILED",
+          "value": "5",
+          "tags": [],
+          "docs": "The update failed to download or install."
+        },
+        {
+          "name": "CANCELED",
+          "value": "6",
+          "tags": [],
+          "docs": "The update was canceled by the user."
+        },
+        {
+          "name": "DOWNLOADED",
+          "value": "11",
+          "tags": [],
+          "docs": "The update has been downloaded and is ready to install.\nCall {@link CapacitorUpdaterPlugin.completeFlexibleUpdate} to install."
+        }
+      ]
+    },
+    {
+      "name": "AppUpdateResultCode",
+      "slug": "appupdateresultcode",
+      "members": [
+        {
+          "name": "OK",
+          "value": "0",
+          "tags": [],
+          "docs": "The update completed successfully."
+        },
+        {
+          "name": "CANCELED",
+          "value": "1",
+          "tags": [],
+          "docs": "The user canceled the update."
+        },
+        {
+          "name": "FAILED",
+          "value": "2",
+          "tags": [],
+          "docs": "The update failed."
+        },
+        {
+          "name": "NOT_AVAILABLE",
+          "value": "3",
+          "tags": [],
+          "docs": "No update is available."
+        },
+        {
+          "name": "NOT_ALLOWED",
+          "value": "4",
+          "tags": [],
+          "docs": "The requested update type is not allowed.\nFor example, trying to perform an immediate update when only flexible is allowed."
+        },
+        {
+          "name": "INFO_MISSING",
+          "value": "5",
+          "tags": [],
+          "docs": "Required information is missing.\nThis can happen if {@link CapacitorUpdaterPlugin.getAppUpdateInfo} wasn't called first."
+        }
+      ]
     }
   ],
-  "enums": [],
   "typeAliases": [
     {
       "name": "BundleStatus",