@simplysm/capacitor-plugin-auto-update 14.0.48 → 14.0.51

package/README.md

@@ -14,104 +14,15 @@ npm install @simplysm/capacitor-plugin-auto-update
 
 ### APK 설치
 
-| API | Type | Description |
-|-----|------|-------------|
-| `VersionInfo` | interface | 앱 버전 정보 (versionName, versionCode) |
-| `ApkInstallerPlugin` | interface | Capacitor 네이티브 플러그인 인터페이스 (직접 사용하지 않음) |
-| `ApkInstaller` | abstract class | APK 설치 플러그인 정적 파사드 — 권한 확인/요청, 설치, 버전 조회 |
+| Entry | Kind | Description |
+|-------|------|-------------|
+| [`ApkInstaller`](./docs/apk-installer/apk-installer.md) | abstract class | APK 설치 플러그인 정적 파사드 — 권한 확인/요청, 설치, 버전 조회. `VersionInfo`, `ApkInstallerPlugin` 타입 포함. |
 
 ### 자동 업데이트
 
-| API | Type | Description |
-|-----|------|-------------|
-| `AutoUpdate` | abstract class | 자동 업데이트 오케스트레이터 — 서버 또는 외부 저장소에서 최신 APK를 확인하고 설치 |
-
----
-
-## `VersionInfo`
-
-앱 버전 정보를 나타내는 인터페이스.
-
-```typescript
-export interface VersionInfo {
-  versionName: string;
-  versionCode: string;
-}
-```
-
-| Field | Type | Description |
+| Entry | Kind | Description |
 |-------|------|-------------|
-| `versionName` | `string` | 앱 버전 이름. semver 형식 (예: `"1.2.3"`). `AutoUpdate`의 버전 비교에 사용된다. |
-| `versionCode` | `string` | 앱 버전 코드. 정수를 문자열로 표현 (예: `"42"`). |
-
-## `ApkInstallerPlugin`
-
-Capacitor 네이티브 플러그인 인터페이스. 직접 사용하지 않고 `ApkInstaller` 파사드를 통해 접근한다. 타입 참조 목적으로만 export된다.
-
-```typescript
-export interface ApkInstallerPlugin {
-  install(options: { uri: string }): Promise<void>;
-  checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>;
-  requestPermissions(): Promise<void>;
-  getVersionInfo(): Promise<VersionInfo>;
-}
-```
-
-| Method | Return | Description |
-|--------|--------|-------------|
-| `install(options: { uri: string })` | `Promise<void>` | `content://` URI(FileProvider URI)로 APK 설치 인텐트 실행 |
-| `checkPermissions()` | `Promise<{ granted: boolean; manifest: boolean }>` | 설치 권한 승인 여부(`granted`)와 AndroidManifest 선언 여부(`manifest`) 동시 확인 |
-| `requestPermissions()` | `Promise<void>` | `REQUEST_INSTALL_PACKAGES` 권한 요청 — 시스템 설정 화면으로 이동 |
-| `getVersionInfo()` | `Promise<VersionInfo>` | PackageManager에서 현재 앱 버전 정보 조회 |
-
-## `ApkInstaller`
-
-APK 설치 플러그인 정적 파사드 클래스. Android에서는 네이티브 플러그인을 실행하고, 브라우저 환경에서는 `ApkInstallerWeb`으로 폴백한다. 브라우저 폴백: `install()`은 `alert()` 표시 후 반환, `checkPermissions()`는 항상 `{ granted: true, manifest: true }` 반환, `requestPermissions()`는 무동작, `getVersionInfo()`는 `env("__VER__") ?? "0.0.0"`을 `versionName`으로 반환.
-
-```typescript
-export abstract class ApkInstaller {
-  static async checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>;
-  static async requestPermissions(): Promise<void>;
-  static async install(apkUri: string): Promise<void>;
-  static async getVersionInfo(): Promise<VersionInfo>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `checkPermissions` | 없음 | `Promise<{ granted: boolean; manifest: boolean }>` | 설치 권한 승인 여부와 AndroidManifest 선언 여부 확인. `manifest: false`이면 APK를 재설치해야 한다. |
-| `requestPermissions` | 없음 | `Promise<void>` | `REQUEST_INSTALL_PACKAGES` 권한 요청. 시스템 설정 화면으로 이동하므로 이후 `checkPermissions`로 결과를 폴링해야 한다. |
-| `install` | `apkUri: string` | `Promise<void>` | `content://` URI(FileProvider URI)로 APK 설치. `FileSystem.getUri(filePath)`로 URI를 얻는다. |
-| `getVersionInfo` | 없음 | `Promise<VersionInfo>` | 현재 설치된 앱의 버전 정보 조회. 브라우저 환경에서는 `env("__VER__") ?? "0.0.0"`을 `versionName`으로 반환한다. |
-
-## `AutoUpdate`
-
-자동 업데이트 오케스트레이터. 서버 또는 외부 저장소에서 최신 APK를 확인하고 설치한다. 모든 메서드가 `static`이며 인스턴스화하지 않는다. Android 환경 전용이며, 비-Android에서 호출하면 에러를 표시하고 앱을 무한 대기 상태로 전환한다.
-
-```typescript
-export abstract class AutoUpdate {
-  static async run(opt: {
-    log: (messageHtml: string) => void;
-    serviceClient: ServiceClient;
-  }): Promise<void>;
-
-  static async runByExternalStorage(opt: {
-    log: (messageHtml: string) => void;
-    dirPath: string;
-  }): Promise<void>;
-}
-```
-
-| Method | Parameters | Description |
-|--------|-----------|-------------|
-| `run` | `opt.log: (messageHtml: string) => void`, `opt.serviceClient: ServiceClient` | `AutoUpdateService.getLastVersion("android")`로 서버에서 최신 버전 정보를 조회한 뒤, 현재 버전보다 높으면 APK를 다운로드하여 설치한다. 업데이트 후 `_freezeApp()`으로 앱을 무한 대기 상태로 전환한다. |
-| `runByExternalStorage` | `opt.log: (messageHtml: string) => void`, `opt.dirPath: string` | 외부 저장소의 `opt.dirPath` 디렉토리에서 `{semver}.apk` 패턴 파일 중 최신 버전을 찾아 설치한다. 현재 버전보다 높은 경우에만 업데이트한다. |
-
-**`opt.log` 콜백**: HTML 문자열을 받아 사용자에게 진행 상황을 표시한다. 버튼(`<button>`) 등 인터랙티브 HTML이 포함될 수 있다. 에러 발생 시에도 `log`로 에러 메시지를 표시한 뒤 `_freezeApp()`으로 전환한다.
-
-**권한 처리**: 두 메서드 모두 내부적으로 `_checkPermission()`을 호출한다. `manifest: false`이면 재설치 에러를 throw하고, `granted: false`이면 권한 요청 후 최대 300초간 폴링한다.
-
-**버전 비교**: `semver` 라이브러리를 사용한다. `versionName`이 유효한 semver 형식이 아니면 업데이트 확인을 건너뛴다.
+| [`AutoUpdate`](./docs/auto-update/auto-update.md) | abstract class | 자동 업데이트 오케스트레이터 — 서버 또는 외부 저장소에서 최신 APK를 확인하고 설치 |
 
 ## Usage Examples
 
@@ -133,7 +44,8 @@ async function checkForUpdate(serviceClient: ServiceClient) {
     serviceClient,
   });
 
-  // 업데이트가 없거나 업데이트가 완료되면(무한 대기 전환 전) 이 줄에 도달한다.
+  // 업데이트가 없을 때만 이 줄에 도달한다.
+  // 업데이트가 실행되면 _freezeApp()으로 무한 대기 전환되므로 이 줄에 도달하지 않는다.
   statusEl.innerHTML = "";
 }
 ```
@@ -161,22 +73,10 @@ await AutoUpdate.runByExternalStorage({
 import { ApkInstaller } from "@simplysm/capacitor-plugin-auto-update";
 import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
 
-// 권한 확인
 const { granted, manifest } = await ApkInstaller.checkPermissions();
-if (!manifest) {
-  // AndroidManifest.xml에 REQUEST_INSTALL_PACKAGES 미선언 → APK 재설치 필요
-  throw new Error("앱을 재설치해야 합니다.");
-}
-if (!granted) {
-  await ApkInstaller.requestPermissions();
-}
-
-// 현재 버전 확인
-const versionInfo = await ApkInstaller.getVersionInfo();
-// versionInfo.versionName → "1.2.3"
-// versionInfo.versionCode → "42"
+if (!manifest) throw new Error("앱을 재설치해야 합니다.");
+if (!granted) await ApkInstaller.requestPermissions();
 
-// APK 설치 (filePath는 FileSystem으로 저장한 경로)
 const apkUri = await FileSystem.getUri("/path/to/latest.apk");
 await ApkInstaller.install(apkUri);
 ```

package/docs/apk-installer/apk-installer.md

@@ -0,0 +1,91 @@
+# ApkInstaller
+
+APK 설치 플러그인 정적 파사드 클래스. Android에서는 네이티브 플러그인을 실행하고, 브라우저 환경에서는 `ApkInstallerWeb`으로 폴백한다.
+
+```typescript
+export abstract class ApkInstaller {
+  static async checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>;
+  static async requestPermissions(): Promise<void>;
+  static async install(apkUri: string): Promise<void>;
+  static async getVersionInfo(): Promise<VersionInfo>;
+}
+```
+
+## Members
+
+| Member | Kind | Parameters | Return | Description |
+|--------|------|-----------|--------|-------------|
+| `checkPermissions` | static method | 없음 | `Promise<{ granted: boolean; manifest: boolean }>` | 설치 권한 승인 여부(`granted`)와 AndroidManifest 선언 여부(`manifest`) 동시 확인. `manifest: false`이면 APK를 재설치해야 한다. |
+| `requestPermissions` | static method | 없음 | `Promise<void>` | `REQUEST_INSTALL_PACKAGES` 권한 요청. 시스템 설정 화면으로 이동하므로 이후 `checkPermissions`로 결과를 폴링해야 한다. |
+| `install` | static method | `apkUri: string` | `Promise<void>` | `content://` URI(FileProvider URI)로 APK 설치 인텐트 실행. `FileSystem.getUri(filePath)`로 URI를 얻는다. |
+| `getVersionInfo` | static method | 없음 | `Promise<VersionInfo>` | 현재 설치된 앱의 버전 정보 조회. 브라우저 환경에서는 `env("__VER__") ?? "0.0.0"`을 `versionName`으로 반환한다. |
+
+**브라우저 폴백 동작:**
+- `install()` — `alert()` 메시지 표시 후 반환
+- `checkPermissions()` — 항상 `{ granted: true, manifest: true }` 반환
+- `requestPermissions()` — 무동작
+- `getVersionInfo()` — `versionName: env("__VER__") ?? "0.0.0"`, `versionCode: "0"` 반환
+
+## Related Types
+
+### `ApkInstallerPlugin`
+
+Capacitor 네이티브 플러그인 인터페이스. 직접 사용하지 않고 `ApkInstaller` 파사드를 통해 접근한다. 타입 참조 목적으로만 export된다.
+
+```typescript
+export interface ApkInstallerPlugin {
+  install(options: { uri: string }): Promise<void>;
+  checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>;
+  requestPermissions(): Promise<void>;
+  getVersionInfo(): Promise<VersionInfo>;
+}
+```
+
+| Method | Return | Description |
+|--------|--------|-------------|
+| `install(options: { uri: string })` | `Promise<void>` | `content://` URI(FileProvider URI)로 APK 설치 인텐트 실행 |
+| `checkPermissions()` | `Promise<{ granted: boolean; manifest: boolean }>` | 설치 권한 승인 여부(`granted`)와 AndroidManifest 선언 여부(`manifest`) 동시 확인 |
+| `requestPermissions()` | `Promise<void>` | `REQUEST_INSTALL_PACKAGES` 권한 요청 — 시스템 설정 화면으로 이동 |
+| `getVersionInfo()` | `Promise<VersionInfo>` | PackageManager에서 현재 앱 버전 정보 조회 |
+
+### `VersionInfo`
+
+앱 버전 정보를 나타내는 인터페이스.
+
+```typescript
+export interface VersionInfo {
+  versionName: string;
+  versionCode: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `versionName` | `string` | 앱 버전 이름. semver 형식 (예: `"1.2.3"`). `AutoUpdate`의 버전 비교에 사용된다. |
+| `versionCode` | `string` | 앱 버전 코드. 정수를 문자열로 표현 (예: `"42"`). |
+
+## Usage
+
+```typescript
+import { ApkInstaller } from "@simplysm/capacitor-plugin-auto-update";
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+// 권한 확인
+const { granted, manifest } = await ApkInstaller.checkPermissions();
+if (!manifest) {
+  // AndroidManifest.xml에 REQUEST_INSTALL_PACKAGES 미선언 → APK 재설치 필요
+  throw new Error("앱을 재설치해야 합니다.");
+}
+if (!granted) {
+  await ApkInstaller.requestPermissions();
+}
+
+// 현재 버전 확인
+const versionInfo = await ApkInstaller.getVersionInfo();
+// versionInfo.versionName → "1.2.3"
+// versionInfo.versionCode → "42"
+
+// APK 설치 (filePath는 FileSystem으로 저장한 경로)
+const apkUri = await FileSystem.getUri("/path/to/latest.apk");
+await ApkInstaller.install(apkUri);
+```

package/docs/auto-update/auto-update.md

@@ -0,0 +1,95 @@
+# AutoUpdate
+
+자동 업데이트 오케스트레이터. 서버 또는 외부 저장소에서 최신 APK를 확인하고 설치한다. 모든 메서드가 `static`이며 인스턴스화하지 않는다. Android 환경 전용이며, 비-Android에서 호출하면 에러를 표시하고 앱을 무한 대기 상태로 전환한다.
+
+```typescript
+export abstract class AutoUpdate {
+  static async run(opt: {
+    log: (messageHtml: string) => void;
+    serviceClient: ServiceClient;
+  }): Promise<void>;
+
+  static async runByExternalStorage(opt: {
+    log: (messageHtml: string) => void;
+    dirPath: string;
+  }): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Parameters | Description |
+|--------|------|-----------|-------------|
+| `run` | static method | `opt.log`, `opt.serviceClient` | `AutoUpdateService.getLastVersion("android")`로 서버에서 최신 버전 정보를 조회한 뒤, 현재 버전보다 높으면 APK를 다운로드하여 설치한다. 업데이트 후 앱을 무한 대기 상태로 전환한다. |
+| `runByExternalStorage` | static method | `opt.log`, `opt.dirPath` | 외부 저장소의 `opt.dirPath` 디렉토리에서 숫자와 점으로만 구성된 이름의 `.apk` 파일(예: `1.2.3.apk`) 중 최신 semver 버전을 찾아 설치한다. 현재 버전보다 높은 경우에만 업데이트한다. |
+
+## Parameters
+
+### `run` opt
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `log` | `(messageHtml: string) => void` | 진행 상황 HTML을 받아 사용자에게 표시하는 콜백. 버튼 등 인터랙티브 HTML이 포함될 수 있다. |
+| `serviceClient` | `ServiceClient` | `@simplysm/service-client`의 `ServiceClient` 인스턴스. 서버에서 버전 정보를 조회하는 데 사용된다. |
+
+### `runByExternalStorage` opt
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `log` | `(messageHtml: string) => void` | 진행 상황 HTML을 받아 사용자에게 표시하는 콜백. |
+| `dirPath` | `string` | 외부 저장소 루트(`FileSystem.getStoragePath("external")`) 기준 상대 경로. 해당 경로에 `1.2.3.apk` 형식 파일이 있어야 한다. |
+
+## 동작 설명
+
+**권한 처리**: 두 메서드 모두 내부적으로 권한 확인을 수행한다.
+- `manifest: false` → 재설치 에러를 throw하고 앱을 무한 대기로 전환한다.
+- `granted: false` → 권한 요청 후 최대 300초(1초 간격)간 승인을 폴링한다.
+
+**버전 비교**: `semver` 라이브러리를 사용한다. `versionName`이 유효한 semver 형식이 아니면 업데이트 확인을 건너뛴다.
+
+**업데이트 후 동작**: 업데이트가 실행되면 `new Promise(() => {})` 무한 대기로 전환된다. 사용자가 앱을 재시작해야 새 버전이 적용된다. 업데이트가 필요 없을 때는 정상 반환한다.
+
+**에러 처리**: `try/catch`로 전체를 감싸며, 에러 발생 시 `opt.log()`로 HTML 에러 메시지를 표시한 뒤 무한 대기로 전환한다.
+
+**`run` APK 저장 경로**: `FileSystem.getStoragePath("appCache")`에 `latest.apk`로 저장한다.
+
+## Usage
+
+### 서버 기반 자동 업데이트
+
+앱 부트스트랩 시 `AutoUpdate.run()`을 호출한다. `AutoUpdateService`는 `@simplysm/service-common`의 서비스 인터페이스다.
+
+```typescript
+import { AutoUpdate } from "@simplysm/capacitor-plugin-auto-update";
+import type { ServiceClient } from "@simplysm/service-client";
+
+async function checkForUpdate(serviceClient: ServiceClient) {
+  const statusEl = document.getElementById("status")!;
+
+  await AutoUpdate.run({
+    log: (messageHtml) => {
+      statusEl.innerHTML = messageHtml;
+    },
+    serviceClient,
+  });
+
+  // 업데이트가 없을 때만 이 줄에 도달한다.
+  // 업데이트가 실행되면 무한 대기 전환되므로 이 줄에 도달하지 않는다.
+  statusEl.innerHTML = "";
+}
+```
+
+### 외부 저장소(USB) 기반 업데이트
+
+`opt.dirPath`는 외부 저장소 루트 기준 상대 경로다. 해당 경로에 `1.2.3.apk` 형식 파일이 있어야 한다.
+
+```typescript
+import { AutoUpdate } from "@simplysm/capacitor-plugin-auto-update";
+
+await AutoUpdate.runByExternalStorage({
+  log: (messageHtml) => {
+    document.getElementById("status")!.innerHTML = messageHtml;
+  },
+  dirPath: "updates/my-app",
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/capacitor-plugin-auto-update",
-  "version": "14.0.48",
+  "version": "14.0.51",
   "description": "심플리즘 패키지 - Capacitor 자동 업데이트 플러그인",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -15,15 +15,16 @@
   "files": [
     "dist",
     "src",
-    "android"
+    "android",
+    "docs"
   ],
   "dependencies": {
     "semver": "^7.7.4",
-    "@simplysm/capacitor-plugin-file-system": "14.0.48",
-    "@simplysm/core-browser": "14.0.48",
-    "@simplysm/service-client": "14.0.48",
-    "@simplysm/core-common": "14.0.48",
-    "@simplysm/service-common": "14.0.48"
+    "@simplysm/capacitor-plugin-file-system": "14.0.51",
+    "@simplysm/core-browser": "14.0.51",
+    "@simplysm/service-client": "14.0.51",
+    "@simplysm/core-common": "14.0.51",
+    "@simplysm/service-common": "14.0.51"
   },
   "devDependencies": {
     "@capacitor/core": "^7.6.2",