@lucidaquarian/app-version-checker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lucidaquarian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# @lucidaquarian/app-version-checker
+
+[![npm version](https://img.shields.io/npm/v/@lucidaquarian/app-version-checker.svg)](https://www.npmjs.com/package/@lucidaquarian/app-version-checker)
+[![downloads](https://img.shields.io/npm/dm/@lucidaquarian/app-version-checker.svg)](https://www.npmjs.com/package/@lucidaquarian/app-version-checker)
+[![license](https://img.shields.io/npm/l/@lucidaquarian/app-version-checker.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/@lucidaquarian/app-version-checker.svg)](https://nodejs.org)
+
+> Detect when your **Cordova** or **Capacitor** app is out of date and prompt users to update.
+
+`@lucidaquarian/app-version-checker` reads the version installed on the device, compares it against the latest published version — from the **Apple App Store**, **Google Play**, or **your own API** — and hands back a single, actionable result: is an update available, what kind (major / minor / patch), and should it be forced?
+
+```js
+const result = await checker.checkForUpdate();
+// {
+//   currentVersion: '1.2.0',
+//   latestVersion:  '1.3.1',
+//   updateAvailable: true,
+//   updateType: 'minor',
+//   forceUpdate: false,
+//   storeUrl: 'https://apps.apple.com/…',
+//   releaseNotes: 'Bug fixes and improvements',
+//   platform: 'capacitor',
+//   devicePlatform: 'ios'
+// }
+```
+
+## Why
+
+Mobile users routinely run months-old builds. Shipping a fix doesn't help anyone still on the old version. This library gives you the one signal you need at launch — *"is this device behind, and by how much?"* — so you can show an optional nudge or a hard "update required" gate.
+
+## Features
+
+- **Dual platform** — works with both Cordova (`cordova-plugin-app-version`) and Capacitor (`@capacitor/app`)
+- **Auto-detection** — picks the right platform at runtime, or set it explicitly
+- **Multiple version sources** — Apple App Store (iTunes Lookup API), Google Play, or a custom endpoint
+- **Forced updates** — define a minimum supported version locally or from your server
+- **Semantic versioning** — built-in, spec-compliant semver parser and comparator (including prerelease ordering)
+- **Network timeouts** — every remote lookup is bounded so a check can never hang
+- **TypeScript ready** — ships with full `.d.ts` declarations
+- **Zero runtime dependencies**
+
+## Installation
+
+```bash
+npm install @lucidaquarian/app-version-checker
+```
+
+### Platform prerequisites
+
+**Cordova:**
+```bash
+cordova plugin add cordova-plugin-app-version
+```
+
+**Capacitor:**
+```bash
+npm install @capacitor/app
+npx cap sync
+```
+
+> Requires **Node.js ≥ 18** (the store lookups use the global `fetch` API).
+
+## Quick start
+
+```js
+import { AppVersionChecker } from '@lucidaquarian/app-version-checker';
+
+const checker = new AppVersionChecker({
+  platform: 'auto',                            // 'cordova' | 'capacitor' | 'auto'
+  iosBundleId: 'com.yourcompany.yourapp',
+  androidPackageName: 'com.yourcompany.yourapp',
+});
+
+const result = await checker.checkForUpdate();
+
+if (result.forceUpdate) {
+  // Block the user — they must update to continue
+} else if (result.updateAvailable) {
+  // Show an optional "update available" prompt
+}
+```
+
+## How it works
+
+1. **Detect the platform** — Capacitor is preferred when both are present; override with `platform`.
+2. **Read the installed version** from the native plugin.
+3. **Fetch the latest version**, chosen by device platform:
+   - `ios` → Apple App Store (needs `iosBundleId`)
+   - `android` → Google Play (needs `androidPackageName`)
+   - any platform → your `customEndpoint`, if configured (takes priority over the stores)
+4. **Compare** the two with the built-in semver engine and return the result.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `platform` | `'cordova' \| 'capacitor' \| 'auto'` | `'auto'` | Which platform provider to use |
+| `iosBundleId` | `string` | `''` | iOS bundle ID for App Store lookups |
+| `androidPackageName` | `string` | `''` | Android package name for Play Store lookups |
+| `country` | `string` | `'us'` | Two-letter country code for the App Store region |
+| `customEndpoint` | `string` | `''` | URL to your own version API (skips store lookups) |
+| `customEndpointOptions` | `RequestInit` | `{}` | Extra `fetch` options for the custom endpoint |
+| `minVersion` | `string` | `''` | Local minimum supported version for forced updates |
+| `timeout` | `number` | `10000` | Network timeout (ms) for store / custom-endpoint requests |
+
+## Result shape
+
+`checkForUpdate()` resolves to:
+
+```ts
+{
+  currentVersion: string;    // installed version, e.g. "1.2.0"
+  latestVersion: string;     // latest available, e.g. "1.3.1"
+  updateAvailable: boolean;  // true if latest > current
+  updateType: 'major' | 'minor' | 'patch' | 'prerelease' | 'none';
+  forceUpdate: boolean;      // true if current is below the minimum supported version
+  storeUrl: string;          // link to the store listing (if available)
+  releaseNotes: string;      // release notes (if available)
+  platform: string;          // 'cordova' | 'capacitor'
+  devicePlatform: string;    // 'ios' | 'android' | 'web'
+}
+```
+
+### Forced updates
+
+An update is marked `forceUpdate: true` when the installed version is below the effective minimum. The minimum is resolved as **remote `minVersion` (from your custom endpoint) → local `minVersion` config**, and a remote `forceUpdate: true` flag also forces it.
+
+## API reference
+
+### `new AppVersionChecker(config?)`
+Create a checker instance. See [Configuration](#configuration).
+
+### `checker.checkForUpdate(): Promise<VersionCheckResult>`
+Run a full check — reads the installed version and the latest remote version, compares them, and returns the [result](#result-shape).
+
+### `checker.getCurrentVersion(): Promise<string>`
+The installed version string.
+
+### `checker.getAppInfo(): Promise<AppInfo>`
+Full app info: `{ versionName, versionCode, packageName, appName }`.
+
+### `checker.getLatestVersion(): Promise<object>`
+Just the remote version info from the store or custom endpoint.
+
+### `checker.getDevicePlatform(): string`
+The current OS platform — `'ios'`, `'android'`, or `'web'`.
+
+### `AppVersionChecker.compareVersions(current, latest)` *(static)*
+Compare two version strings without any device dependency:
+
+```js
+AppVersionChecker.compareVersions('1.0.0', '2.0.0');
+// { updateAvailable: true, updateType: 'major' }
+```
+
+### `SemVer`
+
+Standalone, spec-compliant semver utilities:
+
+```js
+import { SemVer } from '@lucidaquarian/app-version-checker';
+
+SemVer.parse('1.2.3');                 // { major: 1, minor: 2, patch: 3, prerelease: '' }
+SemVer.compare('1.0.0', '2.0.0');      // -1
+SemVer.gt('2.0.0', '1.0.0');           // true
+SemVer.lt('1.0.0', '2.0.0');           // true
+SemVer.eq('1.0.0', '1.0.0');           // true
+SemVer.gte('1.0.0', '1.0.0');          // true
+SemVer.updateType('1.0.0', '2.0.0');   // 'major'
+SemVer.isValid('1.2.3');               // true
+SemVer.isValid('not-a-version');       // false
+```
+
+Prerelease identifiers are compared per the SemVer spec (numeric identifiers compared numerically, ranked below alphanumeric), so `1.0.0-alpha.2 < 1.0.0-alpha.10`.
+
+### Store lookups
+
+The store functions are also exported directly:
+
+```js
+import {
+  fetchAppStoreVersion,   // (bundleId, country?, timeoutMs?)
+  fetchPlayStoreVersion,  // (packageName, timeoutMs?)
+  fetchCustomEndpoint,    // (url, options?, timeoutMs?)
+} from '@lucidaquarian/app-version-checker';
+```
+
+> **Google Play note:** Google has no official public version API, so `fetchPlayStoreVersion` scrapes the store page and can break if Google changes their markup. For production Android checks, prefer a `customEndpoint` backed by your server or the Google Play Developer API.
+
+## Custom endpoint
+
+Set `customEndpoint` and the checker fetches from your URL instead of the stores. Your endpoint should return JSON:
+
+```json
+{
+  "version": "2.1.0",
+  "minVersion": "1.5.0",
+  "releaseNotes": "Performance improvements and bug fixes.",
+  "storeUrl": "https://apps.apple.com/app/id123456789",
+  "forceUpdate": false
+}
+```
+
+Only `version` is required; all other fields are optional. Any extra fields you include are passed through on the result.
+
+```js
+const checker = new AppVersionChecker({
+  customEndpoint: 'https://api.example.com/app/version',
+  customEndpointOptions: {
+    headers: { Authorization: 'Bearer TOKEN' },
+  },
+  timeout: 8000,
+});
+```
+
+## Framework examples
+
+See the [`examples/`](./examples) directory for complete integration examples:
+
+- [`cordova-usage.js`](./examples/cordova-usage.js) — Cordova with native dialogs
+- [`capacitor-usage.js`](./examples/capacitor-usage.js) — Capacitor with Ionic Angular and a React hook
+
+## TypeScript
+
+Type declarations ship with the package — no `@types` install needed:
+
+```ts
+import { AppVersionChecker, VersionCheckResult } from '@lucidaquarian/app-version-checker';
+```
+
+## Running tests
+
+```bash
+npm test      # unit tests (no network — fetch and native globals are mocked)
+npm run lint  # zero-dependency syntax check over src/
+```
+
+## License
+
+[MIT](./LICENSE)

package/examples/capacitor-usage.js

@@ -0,0 +1,149 @@
+/**
+ * Example: Using @lucidaquarian/app-version-checker in a Capacitor application.
+ *
+ * Prerequisites:
+ *   npm install @capacitor/app
+ *   npm install @lucidaquarian/app-version-checker
+ *
+ * Works with Capacitor 4+ / 5+ and Ionic frameworks.
+ */
+
+const { AppVersionChecker } = require('@lucidaquarian/app-version-checker');
+
+// ─── Option A: Store-based lookup ────────────────────────────────────
+
+const checker = new AppVersionChecker({
+  platform: 'capacitor',                        // explicitly use Capacitor provider
+  iosBundleId: 'com.yourcompany.yourapp',
+  androidPackageName: 'com.yourcompany.yourapp',
+  country: 'us',
+});
+
+// ─── Option B: Custom API endpoint ───────────────────────────────────
+
+const checkerWithCustomEndpoint = new AppVersionChecker({
+  platform: 'capacitor',
+  customEndpoint: 'https://api.yourcompany.com/app/version',
+  customEndpointOptions: {
+    headers: { 'Authorization': 'Bearer YOUR_TOKEN' },
+  },
+  minVersion: '1.5.0',  // force-update below this version
+});
+
+// ─── Run the Check ───────────────────────────────────────────────────
+
+async function performVersionCheck() {
+  try {
+    const result = await checker.checkForUpdate();
+
+    console.log(JSON.stringify(result, null, 2));
+    // {
+    //   currentVersion: "1.2.0",
+    //   latestVersion: "1.3.1",
+    //   updateAvailable: true,
+    //   updateType: "minor",
+    //   forceUpdate: false,
+    //   storeUrl: "https://apps.apple.com/...",
+    //   releaseNotes: "Bug fixes and improvements",
+    //   platform: "capacitor",
+    //   devicePlatform: "ios"
+    // }
+
+    return result;
+  } catch (err) {
+    console.warn('Version check failed:', err.message);
+    return null;
+  }
+}
+
+// ─── Ionic / Angular Integration Example ─────────────────────────────
+
+/*
+  // In an Ionic Angular service (version-check.service.ts):
+
+  import { Injectable } from '@angular/core';
+  import { AlertController } from '@ionic/angular';
+  import { AppVersionChecker } from '@lucidaquarian/app-version-checker';
+  import { Browser } from '@capacitor/browser';
+
+  @Injectable({ providedIn: 'root' })
+  export class VersionCheckService {
+    private checker = new AppVersionChecker({
+      platform: 'capacitor',
+      iosBundleId: 'com.yourcompany.yourapp',
+      androidPackageName: 'com.yourcompany.yourapp',
+    });
+
+    constructor(private alertCtrl: AlertController) {}
+
+    async checkOnLaunch(): Promise<void> {
+      try {
+        const result = await this.checker.checkForUpdate();
+
+        if (result.forceUpdate) {
+          await this.showForceUpdate(result);
+        } else if (result.updateAvailable) {
+          await this.showOptionalUpdate(result);
+        }
+      } catch {
+        // Silently fail — don't block the user
+      }
+    }
+
+    private async showForceUpdate(result) {
+      const alert = await this.alertCtrl.create({
+        header: 'Update Required',
+        message: `Please update to version ${result.latestVersion} to continue.`,
+        backdropDismiss: false,
+        buttons: [{
+          text: 'Update Now',
+          handler: () => Browser.open({ url: result.storeUrl }),
+        }],
+      });
+      await alert.present();
+    }
+
+    private async showOptionalUpdate(result) {
+      const alert = await this.alertCtrl.create({
+        header: 'Update Available',
+        message: `Version ${result.latestVersion} is available. ${result.releaseNotes}`,
+        buttons: [
+          { text: 'Later', role: 'cancel' },
+          { text: 'Update', handler: () => Browser.open({ url: result.storeUrl }) },
+        ],
+      });
+      await alert.present();
+    }
+  }
+*/
+
+// ─── React / Capacitor Integration Example ───────────────────────────
+
+/*
+  // In a React component (useVersionCheck.ts):
+
+  import { useEffect, useState } from 'react';
+  import { AppVersionChecker, VersionCheckResult } from '@lucidaquarian/app-version-checker';
+
+  const checker = new AppVersionChecker({
+    platform: 'auto',
+    iosBundleId: 'com.yourcompany.yourapp',
+    androidPackageName: 'com.yourcompany.yourapp',
+  });
+
+  export function useVersionCheck() {
+    const [result, setResult] = useState<VersionCheckResult | null>(null);
+    const [loading, setLoading] = useState(true);
+
+    useEffect(() => {
+      checker.checkForUpdate()
+        .then(setResult)
+        .catch(() => setResult(null))
+        .finally(() => setLoading(false));
+    }, []);
+
+    return { result, loading };
+  }
+*/
+
+module.exports = { performVersionCheck };

package/examples/cordova-usage.js

@@ -0,0 +1,75 @@
+/**
+ * Example: Using @lucidaquarian/app-version-checker in a Cordova application.
+ *
+ * Prerequisites:
+ *   cordova plugin add cordova-plugin-app-version
+ *   npm install @lucidaquarian/app-version-checker
+ */
+
+const { AppVersionChecker } = require('@lucidaquarian/app-version-checker');
+
+// ─── Basic Setup ─────────────────────────────────────────────────────
+
+const checker = new AppVersionChecker({
+  platform: 'cordova',                         // explicitly use Cordova provider
+  iosBundleId: 'com.yourcompany.yourapp',       // for iOS App Store lookup
+  androidPackageName: 'com.yourcompany.yourapp', // for Google Play lookup
+  country: 'us',                                // App Store region
+});
+
+// ─── Check on App Launch ─────────────────────────────────────────────
+
+document.addEventListener('deviceready', async () => {
+  try {
+    const result = await checker.checkForUpdate();
+
+    console.log('Current version:', result.currentVersion);
+    console.log('Latest version:', result.latestVersion);
+    console.log('Update available:', result.updateAvailable);
+    console.log('Update type:', result.updateType);
+    console.log('Force update:', result.forceUpdate);
+
+    if (result.forceUpdate) {
+      // Show a blocking dialog – user MUST update
+      showForceUpdateDialog(result);
+    } else if (result.updateAvailable) {
+      // Show a dismissible prompt
+      showOptionalUpdateDialog(result);
+    }
+  } catch (err) {
+    console.warn('Version check failed:', err.message);
+    // Gracefully continue — don't block the user
+  }
+});
+
+// ─── UI Helpers (replace with your framework's dialogs) ──────────────
+
+function showForceUpdateDialog(result) {
+  if (navigator.notification) {
+    navigator.notification.alert(
+      `Version ${result.latestVersion} is required to continue.\n\n${result.releaseNotes}`,
+      () => openStore(result.storeUrl),
+      'Update Required',
+      'Update Now'
+    );
+  }
+}
+
+function showOptionalUpdateDialog(result) {
+  if (navigator.notification) {
+    navigator.notification.confirm(
+      `Version ${result.latestVersion} is available!\n\n${result.releaseNotes}`,
+      (buttonIndex) => {
+        if (buttonIndex === 1) openStore(result.storeUrl);
+      },
+      'Update Available',
+      ['Update', 'Later']
+    );
+  }
+}
+
+function openStore(url) {
+  if (url && window.cordova?.InAppBrowser) {
+    window.cordova.InAppBrowser.open(url, '_system');
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@lucidaquarian/app-version-checker",
+  "version": "1.0.0",
+  "description": "A cross-platform version checker plugin for Cordova and Capacitor-based mobile applications. Compare local app versions against remote sources and prompt users to update.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "examples/"
+  ],
+  "scripts": {
+    "test": "node test/test.js && node test/providers.test.js && node test/stores.test.js",
+    "lint": "node scripts/lint.js",
+    "prepublishOnly": "npm run lint && npm test",
+    "example:cordova": "node examples/cordova-usage.js",
+    "example:capacitor": "node examples/capacitor-usage.js"
+  },
+  "keywords": [
+    "cordova",
+    "capacitor",
+    "version-check",
+    "app-update",
+    "mobile",
+    "ionic",
+    "hybrid-app",
+    "app-store",
+    "play-store",
+    "version-compare"
+  ],
+  "author": "lucidaquarian",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucidaquarian/app-version-check.git"
+  },
+  "homepage": "https://github.com/lucidaquarian/app-version-check#readme",
+  "bugs": {
+    "url": "https://github.com/lucidaquarian/app-version-check/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {}
+}

package/src/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @lucidaquarian/app-version-checker
+ * Cross-platform version checker for Cordova and Capacitor mobile applications.
+ */
+
+// ─── SemVer ──────────────────────────────────────────────────────────
+
+export interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: string;
+}
+
+export class SemVer {
+  static parse(version: string): ParsedVersion;
+  static compare(versionA: string, versionB: string): -1 | 0 | 1;
+  static gt(versionA: string, versionB: string): boolean;
+  static lt(versionA: string, versionB: string): boolean;
+  static eq(versionA: string, versionB: string): boolean;
+  static gte(versionA: string, versionB: string): boolean;
+  static lte(versionA: string, versionB: string): boolean;
+  static updateType(
+    currentVersion: string,
+    latestVersion: string
+  ): 'major' | 'minor' | 'patch' | 'prerelease' | 'none';
+  static isValid(version: string): boolean;
+}
+
+// ─── Providers ───────────────────────────────────────────────────────
+
+export interface AppInfo {
+  versionName: string;
+  versionCode: string | number;
+  packageName: string;
+  appName: string;
+}
+
+export class CordovaProvider {
+  readonly name: 'cordova';
+  isAvailable(): boolean;
+  getAppInfo(): Promise<AppInfo>;
+  getVersion(): Promise<string>;
+  getBuildNumber(): Promise<string | number>;
+  getPlatform(): string;
+}
+
+export class CapacitorProvider {
+  readonly name: 'capacitor';
+  isAvailable(): boolean;
+  isNative(): boolean;
+  getAppInfo(): Promise<AppInfo>;
+  getVersion(): Promise<string>;
+  getBuildNumber(): Promise<string>;
+  getPlatform(): string;
+  getDeviceInfo(): Promise<object | null>;
+}
+
+// ─── Store Lookups ───────────────────────────────────────────────────
+
+export interface AppStoreResult {
+  version: string;
+  releaseNotes: string;
+  storeUrl: string;
+  releaseDate: string;
+  minimumOsVersion: string;
+}
+
+export interface PlayStoreResult {
+  version: string;
+  storeUrl: string;
+}
+
+export interface CustomEndpointResult {
+  version: string;
+  minVersion: string | null;
+  releaseNotes: string;
+  storeUrl: string;
+  forceUpdate: boolean;
+  [key: string]: any;
+}
+
+export function fetchAppStoreVersion(
+  bundleId: string,
+  country?: string,
+  timeoutMs?: number
+): Promise<AppStoreResult>;
+
+export function fetchPlayStoreVersion(
+  packageName: string,
+  timeoutMs?: number
+): Promise<PlayStoreResult>;
+
+export function fetchCustomEndpoint(
+  url: string,
+  options?: RequestInit,
+  timeoutMs?: number
+): Promise<CustomEndpointResult>;
+
+// ─── Main Checker ────────────────────────────────────────────────────
+
+export interface AppVersionCheckerConfig {
+  /** Platform to use. Defaults to 'auto'. */
+  platform?: 'cordova' | 'capacitor' | 'auto';
+
+  /** iOS bundle identifier for App Store lookup. */
+  iosBundleId?: string;
+
+  /** Android package name for Play Store lookup. */
+  androidPackageName?: string;
+
+  /** Two-letter country code for App Store. Defaults to 'us'. */
+  country?: string;
+
+  /** Custom endpoint URL returning JSON with a `version` field. */
+  customEndpoint?: string;
+
+  /** Extra fetch options for the custom endpoint. */
+  customEndpointOptions?: RequestInit;
+
+  /** Local minimum supported version override. */
+  minVersion?: string;
+
+  /** Network timeout (ms) for store / custom-endpoint requests. Defaults to 10000. */
+  timeout?: number;
+}
+
+export interface VersionCheckResult {
+  currentVersion: string;
+  latestVersion: string;
+  updateAvailable: boolean;
+  updateType: 'major' | 'minor' | 'patch' | 'prerelease' | 'none';
+  forceUpdate: boolean;
+  storeUrl: string;
+  releaseNotes: string;
+  platform: string;
+  devicePlatform: string;
+}
+
+export interface StaticCompareResult {
+  updateAvailable: boolean;
+  updateType: 'major' | 'minor' | 'patch' | 'prerelease' | 'none';
+}
+
+export class AppVersionChecker {
+  constructor(config?: AppVersionCheckerConfig);
+
+  getProvider(): CordovaProvider | CapacitorProvider;
+  getPlatformName(): string;
+  getCurrentVersion(): Promise<string>;
+  getAppInfo(): Promise<AppInfo>;
+  getDevicePlatform(): string;
+  getLatestVersion(): Promise<AppStoreResult | PlayStoreResult | CustomEndpointResult>;
+  checkForUpdate(): Promise<VersionCheckResult>;
+
+  static compareVersions(
+    currentVersion: string,
+    latestVersion: string
+  ): StaticCompareResult;
+}