@lucidaquarian/app-version-checker 1.0.0

package/src/index.js

@@ -0,0 +1,265 @@
+/**
+ * @lucidaquarian/app-version-checker
+ *
+ * A cross-platform version checker for Cordova and Capacitor mobile applications.
+ * Detects the current app version, compares it against the latest published version
+ * (from the App Store, Google Play, or a custom endpoint), and returns actionable
+ * update information.
+ *
+ * @example
+ *   const { AppVersionChecker } = require('@lucidaquarian/app-version-checker');
+ *
+ *   const checker = new AppVersionChecker({
+ *     platform: 'auto',                          // 'cordova' | 'capacitor' | 'auto'
+ *     iosBundleId: 'com.example.myapp',           // for App Store lookup
+ *     androidPackageName: 'com.example.myapp',    // for Play Store lookup
+ *     country: 'us',                              // App Store region
+ *   });
+ *
+ *   const result = await checker.checkForUpdate();
+ *   if (result.updateAvailable) {
+ *     console.log(`New version ${result.latestVersion} available!`);
+ *   }
+ */
+
+const SemVer = require('./semver');
+const CordovaProvider = require('./providers/cordova');
+const CapacitorProvider = require('./providers/capacitor');
+const {
+  fetchAppStoreVersion,
+  fetchPlayStoreVersion,
+  fetchCustomEndpoint,
+} = require('./stores');
+
+// ─── Default Configuration ───────────────────────────────────────────
+
+const DEFAULT_CONFIG = {
+  /** @type {'cordova' | 'capacitor' | 'auto'} */
+  platform: 'auto',
+
+  /** iOS bundle identifier for App Store lookup */
+  iosBundleId: '',
+
+  /** Android package name for Play Store lookup */
+  androidPackageName: '',
+
+  /** Two-letter country code for App Store */
+  country: 'us',
+
+  /**
+   * Optional custom endpoint URL that returns JSON with a `version` field.
+   * When set, the store lookup is skipped in favor of this endpoint.
+   */
+  customEndpoint: '',
+
+  /** Extra fetch options passed to the custom endpoint request */
+  customEndpointOptions: {},
+
+  /**
+   * If set, any installed version below this is treated as a forced update,
+   * regardless of what the store says. Overridden by the remote `minVersion`.
+   */
+  minVersion: '',
+
+  /** Network timeout (ms) for store / custom-endpoint requests. */
+  timeout: 10000,
+};
+
+// ─── Main Class ──────────────────────────────────────────────────────
+
+class AppVersionChecker {
+  /**
+   * @param {Partial<typeof DEFAULT_CONFIG>} config
+   */
+  constructor(config = {}) {
+    /** @type {typeof DEFAULT_CONFIG} */
+    this.config = { ...DEFAULT_CONFIG, ...config };
+
+    this._cordova = new CordovaProvider();
+    this._capacitor = new CapacitorProvider();
+    this._provider = null;
+  }
+
+  // ── Provider Detection ─────────────────────────────────────────────
+
+  /**
+   * Detect and return the appropriate platform provider.
+   * @returns {CordovaProvider | CapacitorProvider}
+   */
+  getProvider() {
+    if (this._provider) return this._provider;
+
+    const { platform } = this.config;
+
+    if (platform === 'cordova') {
+      this._provider = this._cordova;
+    } else if (platform === 'capacitor') {
+      this._provider = this._capacitor;
+    } else {
+      // Auto-detect: prefer Capacitor (newer), fall back to Cordova
+      if (this._capacitor.isAvailable()) {
+        this._provider = this._capacitor;
+      } else if (this._cordova.isAvailable()) {
+        this._provider = this._cordova;
+      } else {
+        throw new Error(
+          'No mobile platform detected. ' +
+          'Ensure Cordova or Capacitor is initialized, or set the "platform" config explicitly.'
+        );
+      }
+    }
+
+    return this._provider;
+  }
+
+  /**
+   * Get the name of the detected platform.
+   * @returns {string}
+   */
+  getPlatformName() {
+    return this.getProvider().name;
+  }
+
+  // ── Local Version ──────────────────────────────────────────────────
+
+  /**
+   * Get the currently installed app version.
+   * @returns {Promise<string>}
+   */
+  async getCurrentVersion() {
+    return this.getProvider().getVersion();
+  }
+
+  /**
+   * Get the full app info object from the platform.
+   * @returns {Promise<object>}
+   */
+  async getAppInfo() {
+    return this.getProvider().getAppInfo();
+  }
+
+  /**
+   * Get the current OS-level platform (ios / android / web).
+   * @returns {string}
+   */
+  getDevicePlatform() {
+    return this.getProvider().getPlatform();
+  }
+
+  // ── Remote Version Lookup ──────────────────────────────────────────
+
+  /**
+   * Fetch the latest version info from the appropriate store or custom endpoint.
+   * @returns {Promise<{ version: string, storeUrl?: string, releaseNotes?: string, minVersion?: string, forceUpdate?: boolean }>}
+   */
+  async getLatestVersion() {
+    const { timeout } = this.config;
+
+    // Prefer custom endpoint if configured
+    if (this.config.customEndpoint) {
+      return fetchCustomEndpoint(
+        this.config.customEndpoint,
+        this.config.customEndpointOptions,
+        timeout
+      );
+    }
+
+    const devicePlatform = this.getDevicePlatform();
+
+    if (devicePlatform === 'ios') {
+      const bundleId = this.config.iosBundleId;
+      if (!bundleId) {
+        throw new Error('iosBundleId must be set in config for App Store lookups.');
+      }
+      return fetchAppStoreVersion(bundleId, this.config.country, timeout);
+    }
+
+    if (devicePlatform === 'android') {
+      const packageName = this.config.androidPackageName;
+      if (!packageName) {
+        throw new Error('androidPackageName must be set in config for Play Store lookups.');
+      }
+      return fetchPlayStoreVersion(packageName, timeout);
+    }
+
+    throw new Error(
+      `Unsupported device platform "${devicePlatform}". Use a customEndpoint for web-based checks.`
+    );
+  }
+
+  // ── Update Check ───────────────────────────────────────────────────
+
+  /**
+   * Perform a full version check: compare local version against latest remote version.
+   *
+   * @returns {Promise<VersionCheckResult>}
+   *
+   * @typedef {Object} VersionCheckResult
+   * @property {string}  currentVersion   - The installed app version
+   * @property {string}  latestVersion    - The latest available version
+   * @property {boolean} updateAvailable  - True if a newer version exists
+   * @property {'major'|'minor'|'patch'|'prerelease'|'none'} updateType - Kind of update
+   * @property {boolean} forceUpdate      - True if the current version is below the minimum
+   * @property {string}  storeUrl         - URL to the store listing (if available)
+   * @property {string}  releaseNotes     - Release notes (if available)
+   * @property {string}  platform         - Detected platform name
+   */
+  async checkForUpdate() {
+    const [currentVersion, remoteInfo] = await Promise.all([
+      this.getCurrentVersion(),
+      this.getLatestVersion(),
+    ]);
+
+    const latestVersion = remoteInfo.version;
+    const updateAvailable = SemVer.lt(currentVersion, latestVersion);
+    const updateType = SemVer.updateType(currentVersion, latestVersion);
+
+    // Determine forced update: use remote minVersion if provided, else local config
+    const effectiveMinVersion = remoteInfo.minVersion || this.config.minVersion || '';
+    let forceUpdate = remoteInfo.forceUpdate || false;
+    if (effectiveMinVersion && SemVer.lt(currentVersion, effectiveMinVersion)) {
+      forceUpdate = true;
+    }
+
+    return {
+      currentVersion,
+      latestVersion,
+      updateAvailable,
+      updateType,
+      forceUpdate,
+      storeUrl: remoteInfo.storeUrl || '',
+      releaseNotes: remoteInfo.releaseNotes || '',
+      platform: this.getPlatformName(),
+      devicePlatform: this.getDevicePlatform(),
+    };
+  }
+
+  // ── Static Convenience ─────────────────────────────────────────────
+
+  /**
+   * Compare two arbitrary version strings without any platform dependency.
+   * Useful for quick checks or unit tests.
+   *
+   * @param {string} currentVersion
+   * @param {string} latestVersion
+   * @returns {{ updateAvailable: boolean, updateType: string }}
+   */
+  static compareVersions(currentVersion, latestVersion) {
+    return {
+      updateAvailable: SemVer.lt(currentVersion, latestVersion),
+      updateType: SemVer.updateType(currentVersion, latestVersion),
+    };
+  }
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────
+
+module.exports = {
+  AppVersionChecker,
+  SemVer,
+  CordovaProvider,
+  CapacitorProvider,
+  fetchAppStoreVersion,
+  fetchPlayStoreVersion,
+  fetchCustomEndpoint,
+};

package/src/providers/capacitor.js

@@ -0,0 +1,143 @@
+/**
+ * Capacitor platform provider.
+ * Retrieves the current app version using @capacitor/app or @capacitor/device APIs.
+ */
+
+class CapacitorProvider {
+  constructor() {
+    this.name = 'capacitor';
+    this._appPlugin = null;
+    this._devicePlugin = null;
+  }
+
+  /**
+   * Check if we are running inside a Capacitor environment.
+   * @returns {boolean}
+   */
+  isAvailable() {
+    return (
+      typeof window !== 'undefined' &&
+      typeof window.Capacitor !== 'undefined' &&
+      window.Capacitor.isNativePlatform !== undefined
+    );
+  }
+
+  /**
+   * Check if the app is running on a native device (not web).
+   * @returns {boolean}
+   */
+  isNative() {
+    return this.isAvailable() && window.Capacitor.isNativePlatform();
+  }
+
+  /**
+   * Dynamically import the @capacitor/app plugin.
+   * @returns {Promise<any>}
+   * @private
+   */
+  async _getAppPlugin() {
+    if (this._appPlugin) return this._appPlugin;
+
+    try {
+      // Try Capacitor 4+ / 5+ dynamic import
+      const mod = await import('@capacitor/app');
+      this._appPlugin = mod.App;
+      return this._appPlugin;
+    } catch {
+      // Fallback: check global Capacitor Plugins
+      if (window.Capacitor?.Plugins?.App) {
+        this._appPlugin = window.Capacitor.Plugins.App;
+        return this._appPlugin;
+      }
+      throw new Error(
+        '@capacitor/app plugin is not installed. ' +
+        'Install it with: npm install @capacitor/app'
+      );
+    }
+  }
+
+  /**
+   * Dynamically import the @capacitor/device plugin.
+   * @returns {Promise<any>}
+   * @private
+   */
+  async _getDevicePlugin() {
+    if (this._devicePlugin) return this._devicePlugin;
+
+    try {
+      const mod = await import('@capacitor/device');
+      this._devicePlugin = mod.Device;
+      return this._devicePlugin;
+    } catch {
+      if (window.Capacitor?.Plugins?.Device) {
+        this._devicePlugin = window.Capacitor.Plugins.Device;
+        return this._devicePlugin;
+      }
+      // Device plugin is optional, return null
+      return null;
+    }
+  }
+
+  /**
+   * Get the current app version info from Capacitor.
+   *
+   * @returns {Promise<{ versionName: string, versionCode: string, platform: string }>}
+   */
+  async getAppInfo() {
+    if (!this.isAvailable()) {
+      throw new Error(
+        'Capacitor is not available. Ensure this is running inside a Capacitor app.'
+      );
+    }
+
+    const App = await this._getAppPlugin();
+    const info = await App.getInfo();
+
+    return {
+      versionName: info.version,       // e.g. "1.2.3"
+      versionCode: info.build,         // e.g. "42"
+      packageName: info.id,            // e.g. "com.example.app"
+      appName: info.name,              // e.g. "My App"
+    };
+  }
+
+  /**
+   * Get only the version string (e.g. "1.2.3").
+   * @returns {Promise<string>}
+   */
+  async getVersion() {
+    const info = await this.getAppInfo();
+    return info.versionName;
+  }
+
+  /**
+   * Get the build/version code.
+   * @returns {Promise<string>}
+   */
+  async getBuildNumber() {
+    const info = await this.getAppInfo();
+    return info.versionCode;
+  }
+
+  /**
+   * Get the current platform ("ios", "android", or "web").
+   * @returns {string}
+   */
+  getPlatform() {
+    if (!this.isAvailable()) return 'unknown';
+    return window.Capacitor.getPlatform();
+  }
+
+  /**
+   * Get device information (OS version, model, etc.).
+   * Requires @capacitor/device plugin.
+   * @returns {Promise<object|null>}
+   */
+  async getDeviceInfo() {
+    const Device = await this._getDevicePlugin();
+    if (!Device) return null;
+    return Device.getInfo();
+  }
+}
+
+module.exports = CapacitorProvider;

package/src/providers/cordova.js

@@ -0,0 +1,143 @@
+/**
+ * Cordova platform provider.
+ * Retrieves the current app version using the cordova-plugin-app-version API.
+ */
+
+class CordovaProvider {
+  constructor() {
+    this.name = 'cordova';
+  }
+
+  /**
+   * Check if we are running inside a Cordova environment.
+   * @returns {boolean}
+   */
+  isAvailable() {
+    return (
+      typeof window !== 'undefined' &&
+      typeof window.cordova !== 'undefined'
+    );
+  }
+
+  /**
+   * Get the current app version from Cordova.
+   * Requires `cordova-plugin-app-version` to be installed.
+   *
+   * @returns {Promise<{ versionName: string, versionCode: string|number, packageName: string, appName: string }>}
+   */
+  async getAppInfo() {
+    if (!this.isAvailable()) {
+      throw new Error(
+        'Cordova is not available. Ensure this is running inside a Cordova app.'
+      );
+    }
+
+    await this._waitForDeviceReady();
+
+    const cordova = window.cordova;
+
+    // Check for cordova-plugin-app-version
+    if (
+      typeof cordova.getAppVersion === 'undefined' &&
+      typeof window.AppVersion === 'undefined'
+    ) {
+      throw new Error(
+        'cordova-plugin-app-version is not installed. ' +
+        'Install it with: cordova plugin add cordova-plugin-app-version'
+      );
+    }
+
+    const appVersion = cordova.getAppVersion || window.AppVersion;
+
+    // Bind each method to the plugin object so callers that rely on `this`
+    // inside the plugin keep working when the function is passed to _promisify.
+    const [versionName, versionCode, packageName, appName] = await Promise.all([
+      this._promisify(appVersion.getVersionNumber.bind(appVersion)),
+      this._promisify(appVersion.getVersionCode.bind(appVersion)),
+      this._promisify(appVersion.getPackageName.bind(appVersion)),
+      this._promisify(appVersion.getAppName.bind(appVersion)),
+    ]);
+
+    return { versionName, versionCode, packageName, appName };
+  }
+
+  /**
+   * Get only the version string (e.g. "1.2.3").
+   * @returns {Promise<string>}
+   */
+  async getVersion() {
+    const info = await this.getAppInfo();
+    return info.versionName;
+  }
+
+  /**
+   * Get the build/version code (e.g. 42).
+   * @returns {Promise<string|number>}
+   */
+  async getBuildNumber() {
+    const info = await this.getAppInfo();
+    return info.versionCode;
+  }
+
+  /**
+   * Get the current platform (ios or android).
+   * @returns {string}
+   */
+  getPlatform() {
+    if (!this.isAvailable()) return 'unknown';
+    return window.cordova.platformId || window.device?.platform?.toLowerCase() || 'unknown';
+  }
+
+  /**
+   * Wait for the Cordova deviceready event.
+   * @returns {Promise<void>}
+   * @private
+   */
+  _waitForDeviceReady() {
+    return new Promise((resolve) => {
+      if (
+        typeof document === 'undefined' ||
+        document.readyState === 'complete' ||
+        window.cordova?.plugins
+      ) {
+        resolve();
+        return;
+      }
+
+      let settled = false;
+      let timerId = null;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        if (timerId !== null) clearTimeout(timerId);
+        document.removeEventListener('deviceready', done, false);
+        resolve();
+      };
+
+      document.addEventListener('deviceready', done, false);
+
+      // Safety net: `deviceready` fires only once, so if it already fired
+      // before this listener was attached we would wait forever. Resolve
+      // after a bounded delay rather than hang the update check.
+      timerId = setTimeout(done, 5000);
+    });
+  }
+
+  /**
+   * Convert a Cordova callback-style function to a Promise.
+   * @param {Function} fn
+   * @returns {Promise<any>}
+   * @private
+   */
+  _promisify(fn) {
+    return new Promise((resolve, reject) => {
+      try {
+        fn(resolve, reject);
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+}
+
+module.exports = CordovaProvider;