@simplysm/capacitor-plugin-auto-update 13.0.72 → 13.0.74

package/README.md

@@ -2,27 +2,154 @@
 
 Simplysm Package - Capacitor Auto Update Plugin
 
+Provides Android APK auto-update capabilities for Capacitor apps. Includes APK installation via native Android intent and automated update flows from either a remote server or external storage.
+
 ## Installation
 
+```bash
 pnpm add @simplysm/capacitor-plugin-auto-update
+```
 
-**Peer Dependencies:** `@capacitor/core ^7.4.4`
-
-## Source Index
+## Main Modules
 
 ### APK Installer
 
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/ApkInstaller.ts` | `ApkInstaller` | Static class to check/request install permission and trigger APK installation | - |
-| `src/IApkInstallerPlugin.ts` | `IVersionInfo`, `IApkInstallerPlugin` | Interfaces for app version info and the native APK installer plugin contract | - |
+#### `ApkInstaller`
+
+Abstract class with static methods that wrap the native `ApkInstaller` Capacitor plugin.
+
+- Android: executes APK install intent and manages `REQUEST_INSTALL_PACKAGES` permission.
+- Browser (web fallback): shows an alert message and returns normally.
+
+```ts
+import { ApkInstaller } from "@simplysm/capacitor-plugin-auto-update";
+
+// Check whether REQUEST_INSTALL_PACKAGES is declared in the manifest
+const declared = await ApkInstaller.hasPermissionManifest();
+
+// Check whether REQUEST_INSTALL_PACKAGES is currently granted
+const granted = await ApkInstaller.hasPermission();
+
+// Navigate the user to the settings page to grant the permission
+await ApkInstaller.requestPermission();
+
+// Install an APK given a content:// FileProvider URI
+await ApkInstaller.install("content://com.example/files/latest.apk");
+
+// Get the running app's version information
+const info = await ApkInstaller.getVersionInfo();
+// info.versionName  →  e.g. "1.2.3"
+// info.versionCode  →  e.g. "10203"
+```
+
+**Static methods**
+
+| Method | Signature | Description |
+|---|---|---|
+| `hasPermissionManifest` | `() => Promise<boolean>` | Returns `true` if `REQUEST_INSTALL_PACKAGES` is declared in the manifest. |
+| `hasPermission` | `() => Promise<boolean>` | Returns `true` if `REQUEST_INSTALL_PACKAGES` is currently granted. |
+| `requestPermission` | `() => Promise<void>` | Opens the system settings screen for the user to grant the permission. |
+| `install` | `(apkUri: string) => Promise<void>` | Fires the install intent for the given `content://` URI. |
+| `getVersionInfo` | `() => Promise<IVersionInfo>` | Returns the running app's `versionName` and `versionCode`. |
+
+---
 
 ### Auto Update
 
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/AutoUpdate.ts` | `AutoUpdate` | Downloads and installs the latest APK from a server or external storage | - |
+#### `AutoUpdate`
+
+Abstract class with static methods that orchestrate the full auto-update flow.
+
+**`AutoUpdate.run`**
+
+Downloads the latest APK from a remote server using a `ServiceClient` connection and installs it.
+
+1. Queries the server for the latest version via `AutoUpdateService.getLastVersion("android")`.
+2. Checks and requests install permission if needed.
+3. Compares the server version against the installed version using semver.
+4. Downloads the APK to app cache storage and triggers installation.
+5. Freezes the app (waits indefinitely) after install to prevent further execution.
+6. On any error the log callback is called with an HTML error message and the app is frozen.
+
+```ts
+import { AutoUpdate } from "@simplysm/capacitor-plugin-auto-update";
+import type { ServiceClient } from "@simplysm/service-client";
+
+declare const serviceClient: ServiceClient;
+
+await AutoUpdate.run({
+  log: (messageHtml) => {
+    document.getElementById("status")!.innerHTML = messageHtml;
+  },
+  serviceClient,
+});
+```
+
+**Options**
+
+| Property | Type | Description |
+|---|---|---|
+| `log` | `(messageHtml: string) => void` | Callback that receives HTML status messages to display to the user. |
+| `serviceClient` | `ServiceClient` | Connected service client used to reach `AutoUpdateService` on the server. |
+
+---
+
+**`AutoUpdate.runByExternalStorage`**
+
+Finds the newest APK file stored in a directory on the device's external storage and installs it.
+
+1. Checks and requests install permission if needed.
+2. Reads the specified directory on external storage, selecting `.apk` files whose basenames are valid semver strings.
+3. Picks the highest version using `semver.maxSatisfying`.
+4. Compares it against the installed version; skips if already up-to-date.
+5. Triggers installation and freezes the app.
+6. On any error the log callback is called with an HTML error message and the app is frozen.
+
+```ts
+import { AutoUpdate } from "@simplysm/capacitor-plugin-auto-update";
+
+await AutoUpdate.runByExternalStorage({
+  log: (messageHtml) => {
+    document.getElementById("status")!.innerHTML = messageHtml;
+  },
+  dirPath: "MyApp/updates",
+});
+```
+
+**Options**
+
+| Property | Type | Description |
+|---|---|---|
+| `log` | `(messageHtml: string) => void` | Callback that receives HTML status messages to display to the user. |
+| `dirPath` | `string` | Path relative to the external storage root where APK files are located. |
+
+## Types
+
+### `IVersionInfo`
+
+Version information returned by `ApkInstaller.getVersionInfo()`.
+
+```ts
+import type { IVersionInfo } from "@simplysm/capacitor-plugin-auto-update";
+
+interface IVersionInfo {
+  versionName: string; // Human-readable version string, e.g. "1.2.3"
+  versionCode: string; // Integer build number as a string, e.g. "10203"
+}
+```
+
+### `IApkInstallerPlugin`
+
+Low-level interface implemented by the native Capacitor plugin. Use `ApkInstaller` (the abstract class) instead of this interface directly.
 
-## License
+```ts
+import type { IApkInstallerPlugin } from "@simplysm/capacitor-plugin-auto-update";
 
-Apache-2.0
+interface IApkInstallerPlugin {
+  install(options: { uri: string }): Promise<void>;
+  hasPermission(): Promise<{ granted: boolean }>;
+  requestPermission(): Promise<void>;
+  hasPermissionManifest(): Promise<{ declared: boolean }>;
+  getVersionInfo(): Promise<IVersionInfo>;
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-auto-update",
-  "version": "13.0.72",
+  "version": "13.0.74",
   "description": "Simplysm Package - Capacitor Auto Update Plugin",
   "author": "simplysm",
   "license": "MIT",
@@ -19,11 +19,11 @@
   ],
   "dependencies": {
     "semver": "^7.7.4",
-    "@simplysm/capacitor-plugin-file-system": "13.0.72",
-    "@simplysm/core-common": "13.0.72",
-    "@simplysm/core-browser": "13.0.72",
-    "@simplysm/service-client": "13.0.72",
-    "@simplysm/service-common": "13.0.72"
+    "@simplysm/core-common": "13.0.74",
+    "@simplysm/capacitor-plugin-file-system": "13.0.74",
+    "@simplysm/core-browser": "13.0.74",
+    "@simplysm/service-common": "13.0.74",
+    "@simplysm/service-client": "13.0.74"
   },
   "devDependencies": {
     "@capacitor/core": "^7.5.0",