react-native-nitro-version-check 1.0.2 → 1.1.1

package/README.md

@@ -15,7 +15,7 @@
 ## Example
 
 ```ts
-import { VersionCheck, needsUpdate, getStoreUrl } from 'react-native-nitro-version-check'
+import { VersionCheck } from 'react-native-nitro-version-check'
 
 // Sync — no bridge, no async
 VersionCheck.version       // "1.2.0"
@@ -23,9 +23,12 @@ VersionCheck.buildNumber   // "42"
 VersionCheck.packageName   // "com.example.app"
 VersionCheck.installSource // "appstore" | "testflight" | "playstore" | undefined
 
+// Or destructure properties
+const { version, buildNumber, packageName, installSource } = VersionCheck
+
 // Check for updates
-if (await needsUpdate()) {
-  Linking.openURL(await getStoreUrl())
+if (await VersionCheck.needsUpdate()) {
+  Linking.openURL(await VersionCheck.getStoreUrl())
 }
 ```
 
@@ -35,6 +38,8 @@ if (await needsUpdate()) {
 bun add react-native-nitro-version-check
 ```
 
+> Check the [full installation guide](https://alshehriali0.github.io/react-native-nitro-version-check/docs/installation) for platform setup and additional dependencies.
+
 ## Documentation
 
 - [**Nitro Version Check** docs 📚](https://alshehriali0.github.io/react-native-nitro-version-check/)

package/android/src/main/java/com/margelo/nitro/nitroversioncheck/HybridVersionCheck.kt

@@ -36,15 +36,17 @@ class HybridVersionCheck : HybridVersionCheckSpec() {
         return java.util.Locale.getDefault().country ?: "unknown"
     }
 
-    override fun getStoreUrl(): Promise<String> {
+    override fun getStoreUrl(countryCode: String?): Promise<String> {
         return Promise.async {
+            // Country code is not used on Android Play Store, but parameter is kept for API consistency
             "https://play.google.com/store/apps/details?id=$packageName"
         }
     }
 
-    override fun getLatestVersion(): Promise<String> {
+    override fun getLatestVersion(countryCode: String?): Promise<String> {
         return Promise.async {
             try {
+                // Country code is not used on Android Play Store, but parameter is kept for API consistency
                 val url = URL("https://play.google.com/store/apps/details?id=$packageName&hl=en")
                 val connection = url.openConnection() as HttpURLConnection
                 connection.connectTimeout = TIMEOUT_MS

package/ios/HybridVersionCheck.swift

@@ -30,10 +30,12 @@ class HybridVersionCheck: HybridVersionCheckSpec {
         return Locale.current.regionCode ?? "unknown"
     }
 
-    func getStoreUrl() throws -> Promise<String> {
-        return Promise.async {
+    func getStoreUrl(countryCode: String? = nil) throws -> Promise<String> {
+        return Promise.async { [self] in
             let bundleId = Bundle.main.bundleIdentifier ?? ""
-            let url = URL(string: "https://itunes.apple.com/lookup?bundleId=\(bundleId)")!
+            let country = countryCode ?? (try? self.getCountry()) ?? "US"
+            let urlString = "https://itunes.apple.com/\(country.lowercased())/lookup?bundleId=\(bundleId)"
+            let url = URL(string: urlString)!
             let (data, _) = try await HybridVersionCheck.session.data(from: url)
             guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any],
                   let results = json["results"] as? [[String: Any]],
@@ -44,10 +46,12 @@ class HybridVersionCheck: HybridVersionCheckSpec {
         }
     }
 
-    func getLatestVersion() throws -> Promise<String> {
-        return Promise.async {
+    func getLatestVersion(countryCode: String? = nil) throws -> Promise<String> {
+        return Promise.async { [self] in
             let bundleId = Bundle.main.bundleIdentifier ?? ""
-            let url = URL(string: "https://itunes.apple.com/lookup?bundleId=\(bundleId)")!
+            let country = countryCode ?? (try? self.getCountry()) ?? "US"
+            let urlString = "https://itunes.apple.com/\(country.lowercased())/lookup?bundleId=\(bundleId)"
+            let url = URL(string: urlString)!
             let (data, _) = try await HybridVersionCheck.session.data(from: url)
             guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any],
                   let results = json["results"] as? [[String: Any]],

package/lib/index.d.ts

@@ -1,62 +1,11 @@
 import type { UpdateLevel } from "./semver";
 import { compareVersions } from "./semver";
-/**
- * Returns the device's current 2-letter ISO country code.
- *
- * @example
- * ```ts
- * getCountry() // "US"
- * ```
- */
-export declare const getCountry: () => string;
-/**
- * Returns the store URL for this app.
- *
- * Automatically resolves to the App Store on iOS and Play Store on Android.
- *
- * @example
- * ```ts
- * const url = await getStoreUrl();
- * Linking.openURL(url);
- * ```
- */
-export declare const getStoreUrl: () => Promise<string>;
-/**
- * Fetches the latest version of this app available in the store.
- *
- * @example
- * ```ts
- * const latest = await getLatestVersion(); // "1.3.0"
- * ```
- */
-export declare const getLatestVersion: () => Promise<string>;
-/**
- * Checks whether an app update is available.
- *
- * Uses semantic version comparison. By default checks for any version
- * increase, but you can filter by granularity:
- *
- * - `"major"` — only returns `true` for major bumps (1.x → 2.x)
- * - `"minor"` — returns `true` for major or minor bumps
- * - `"patch"` — returns `true` for any version increase (default)
- *
- * @example
- * ```ts
- * if (await needsUpdate()) {
- *   const url = await getStoreUrl();
- *   Linking.openURL(url);
- * }
- *
- * // Only prompt for major updates
- * const majorUpdate = await needsUpdate({ level: "major" });
- * ```
- */
-export declare const needsUpdate: (options?: {
-    level?: UpdateLevel;
-}) => Promise<boolean>;
 /**
  * All version-check APIs in one object.
  *
+ * Provides access to app version information, store URLs, and update checking.
+ * Sync properties are cached at module init for zero native overhead.
+ *
  * @example
  * ```ts
  * VersionCheck.version      // "1.2.0"
@@ -65,6 +14,9 @@ export declare const needsUpdate: (options?: {
  * VersionCheck.getCountry() // "US"
  *
  * const url = await VersionCheck.getStoreUrl();
+ * if (await VersionCheck.needsUpdate()) {
+ *   Linking.openURL(url);
+ * }
  * ```
  */
 export declare const VersionCheck: {
@@ -132,37 +84,84 @@ export declare const VersionCheck: {
     /**
      * Returns the App Store (iOS) or Play Store (Android) URL for this app.
      *
+     * @param options - Optional configuration
+     * @param options.countryCode - 2-letter ISO country code (e.g., "US", "GB")
+     *   Defaults to the device's current country from `getCountry()`.
+     *   Only used on iOS; ignored on Android.
+     *
      * @example
      * ```ts
      * const url = await VersionCheck.getStoreUrl();
+     * const urlUS = await VersionCheck.getStoreUrl({ countryCode: "US" });
      * Linking.openURL(url);
      * ```
      */
-    readonly getStoreUrl: () => Promise<string>;
+    readonly getStoreUrl: (options?: {
+        countryCode?: string;
+    }) => Promise<string>;
     /**
      * Fetches the latest version of this app available in the store.
      *
      * Queries the iTunes API on iOS and the Play Store on Android.
+     * On iOS, uses the device's current country code by default but can be overridden.
+     *
+     * @param options - Optional configuration
+     * @param options.countryCode - 2-letter ISO country code (e.g., "US", "GB")
+     *   Defaults to the device's current country from `getCountry()`.
+     *   If the device region changes, the next call will use the new country.
+     *   Only used on iOS; ignored on Android.
      *
      * @example
      * ```ts
-     * const latest = await VersionCheck.getLatestVersion(); // "1.3.0"
+     * const latest = await VersionCheck.getLatestVersion(); // Uses current device country
+     * const latestUS = await VersionCheck.getLatestVersion({ countryCode: "US" });
+     * const latestGB = await VersionCheck.getLatestVersion({ countryCode: "GB" });
      * ```
      */
-    readonly getLatestVersion: () => Promise<string>;
+    readonly getLatestVersion: (options?: {
+        countryCode?: string;
+    }) => Promise<string>;
     /**
      * Checks whether an app update is available by comparing the current
      * version against the latest store version.
      *
+     * Uses semantic version comparison. By default checks for any version
+     * increase, but you can filter by granularity:
+     *
+     * - `"major"` — only returns `true` for major bumps (1.x → 2.x)
+     * - `"minor"` — returns `true` for major or minor bumps
+     * - `"patch"` — returns `true` for any version increase (default)
+     *
      * @example
      * ```ts
      * if (await VersionCheck.needsUpdate()) {
      *   const url = await VersionCheck.getStoreUrl();
      *   Linking.openURL(url);
      * }
+     *
+     * // Only prompt for major updates
+     * const majorUpdate = await VersionCheck.needsUpdate({ level: "major" });
+     * ```
+     */
+    readonly needsUpdate: (options?: {
+        level?: UpdateLevel;
+    }) => Promise<boolean>;
+    /**
+     * Compares two semantic version strings.
+     *
+     * @returns -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
+     *
+     * @example
+     * ```ts
+     * VersionCheck.compareVersions('1.0.0', '1.0.1') // -1
+     * VersionCheck.compareVersions('2.0.0', '2.0.0') //  0
+     * VersionCheck.compareVersions('3.0.0', '2.9.9') //  1
+     *
+     * if (VersionCheck.compareVersions(currentVersion, minimumVersion) < 0) {
+     *   // Current version is below minimum — force update
+     * }
      * ```
      */
-    readonly needsUpdate: () => Promise<boolean>;
+    readonly compareVersions: typeof compareVersions;
 };
-export { compareVersions };
 export type { UpdateLevel };

package/lib/index.js

@@ -6,64 +6,12 @@ const version = HybridVersionCheck.version;
 const buildNumber = HybridVersionCheck.buildNumber;
 const packageName = HybridVersionCheck.packageName;
 const installSource = HybridVersionCheck.installSource;
-/**
- * Returns the device's current 2-letter ISO country code.
- *
- * @example
- * ```ts
- * getCountry() // "US"
- * ```
- */
-export const getCountry = () => HybridVersionCheck.getCountry();
-/**
- * Returns the store URL for this app.
- *
- * Automatically resolves to the App Store on iOS and Play Store on Android.
- *
- * @example
- * ```ts
- * const url = await getStoreUrl();
- * Linking.openURL(url);
- * ```
- */
-export const getStoreUrl = () => HybridVersionCheck.getStoreUrl();
-/**
- * Fetches the latest version of this app available in the store.
- *
- * @example
- * ```ts
- * const latest = await getLatestVersion(); // "1.3.0"
- * ```
- */
-export const getLatestVersion = () => HybridVersionCheck.getLatestVersion();
-/**
- * Checks whether an app update is available.
- *
- * Uses semantic version comparison. By default checks for any version
- * increase, but you can filter by granularity:
- *
- * - `"major"` — only returns `true` for major bumps (1.x → 2.x)
- * - `"minor"` — returns `true` for major or minor bumps
- * - `"patch"` — returns `true` for any version increase (default)
- *
- * @example
- * ```ts
- * if (await needsUpdate()) {
- *   const url = await getStoreUrl();
- *   Linking.openURL(url);
- * }
- *
- * // Only prompt for major updates
- * const majorUpdate = await needsUpdate({ level: "major" });
- * ```
- */
-export const needsUpdate = async (options) => {
-    const latest = await HybridVersionCheck.getLatestVersion();
-    return isNewerVersion(version, latest, options?.level ?? "patch");
-};
 /**
  * All version-check APIs in one object.
  *
+ * Provides access to app version information, store URLs, and update checking.
+ * Sync properties are cached at module init for zero native overhead.
+ *
  * @example
  * ```ts
  * VersionCheck.version      // "1.2.0"
@@ -72,6 +20,9 @@ export const needsUpdate = async (options) => {
  * VersionCheck.getCountry() // "US"
  *
  * const url = await VersionCheck.getStoreUrl();
+ * if (await VersionCheck.needsUpdate()) {
+ *   Linking.openURL(url);
+ * }
  * ```
  */
 export const VersionCheck = {
@@ -135,40 +86,88 @@ export const VersionCheck = {
      * VersionCheck.getCountry() // "US"
      * ```
      */
-    getCountry,
+    getCountry: () => HybridVersionCheck.getCountry(),
     /**
      * Returns the App Store (iOS) or Play Store (Android) URL for this app.
      *
+     * @param options - Optional configuration
+     * @param options.countryCode - 2-letter ISO country code (e.g., "US", "GB")
+     *   Defaults to the device's current country from `getCountry()`.
+     *   Only used on iOS; ignored on Android.
+     *
      * @example
      * ```ts
      * const url = await VersionCheck.getStoreUrl();
+     * const urlUS = await VersionCheck.getStoreUrl({ countryCode: "US" });
      * Linking.openURL(url);
      * ```
      */
-    getStoreUrl,
+    getStoreUrl: async (options) => {
+        return HybridVersionCheck.getStoreUrl(options?.countryCode);
+    },
     /**
      * Fetches the latest version of this app available in the store.
      *
      * Queries the iTunes API on iOS and the Play Store on Android.
+     * On iOS, uses the device's current country code by default but can be overridden.
+     *
+     * @param options - Optional configuration
+     * @param options.countryCode - 2-letter ISO country code (e.g., "US", "GB")
+     *   Defaults to the device's current country from `getCountry()`.
+     *   If the device region changes, the next call will use the new country.
+     *   Only used on iOS; ignored on Android.
      *
      * @example
      * ```ts
-     * const latest = await VersionCheck.getLatestVersion(); // "1.3.0"
+     * const latest = await VersionCheck.getLatestVersion(); // Uses current device country
+     * const latestUS = await VersionCheck.getLatestVersion({ countryCode: "US" });
+     * const latestGB = await VersionCheck.getLatestVersion({ countryCode: "GB" });
      * ```
      */
-    getLatestVersion,
+    getLatestVersion: async (options) => {
+        return HybridVersionCheck.getLatestVersion(options?.countryCode);
+    },
     /**
      * Checks whether an app update is available by comparing the current
      * version against the latest store version.
      *
+     * Uses semantic version comparison. By default checks for any version
+     * increase, but you can filter by granularity:
+     *
+     * - `"major"` — only returns `true` for major bumps (1.x → 2.x)
+     * - `"minor"` — returns `true` for major or minor bumps
+     * - `"patch"` — returns `true` for any version increase (default)
+     *
      * @example
      * ```ts
      * if (await VersionCheck.needsUpdate()) {
      *   const url = await VersionCheck.getStoreUrl();
      *   Linking.openURL(url);
      * }
+     *
+     * // Only prompt for major updates
+     * const majorUpdate = await VersionCheck.needsUpdate({ level: "major" });
+     * ```
+     */
+    needsUpdate: async (options) => {
+        const latest = await HybridVersionCheck.getLatestVersion();
+        return isNewerVersion(version, latest, options?.level ?? "patch");
+    },
+    /**
+     * Compares two semantic version strings.
+     *
+     * @returns -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
+     *
+     * @example
+     * ```ts
+     * VersionCheck.compareVersions('1.0.0', '1.0.1') // -1
+     * VersionCheck.compareVersions('2.0.0', '2.0.0') //  0
+     * VersionCheck.compareVersions('3.0.0', '2.9.9') //  1
+     *
+     * if (VersionCheck.compareVersions(currentVersion, minimumVersion) < 0) {
+     *   // Current version is below minimum — force update
+     * }
      * ```
      */
-    needsUpdate: () => HybridVersionCheck.needsUpdate(),
+    compareVersions,
 };
-export { compareVersions };

package/lib/specs/Version.nitro.d.ts

@@ -8,7 +8,7 @@ export interface VersionCheck extends HybridObject<{
     readonly packageName: string;
     readonly installSource: string | undefined;
     getCountry(): string;
-    getStoreUrl(): Promise<string>;
-    getLatestVersion(): Promise<string>;
+    getStoreUrl(countryCode?: string): Promise<string>;
+    getLatestVersion(countryCode?: string): Promise<string>;
     needsUpdate(): Promise<boolean>;
 }

package/nitrogen/generated/android/c++/JHybridVersionCheckSpec.cpp

@@ -77,9 +77,9 @@ namespace margelo::nitro::nitroversioncheck {
     auto __result = method(_javaPart);
     return __result->toStdString();
   }
-  std::shared_ptr<Promise<std::string>> JHybridVersionCheckSpec::getStoreUrl() {
-    static const auto method = javaClassStatic()->getMethod<jni::local_ref<JPromise::javaobject>()>("getStoreUrl");
-    auto __result = method(_javaPart);
+  std::shared_ptr<Promise<std::string>> JHybridVersionCheckSpec::getStoreUrl(const std::optional<std::string>& countryCode) {
+    static const auto method = javaClassStatic()->getMethod<jni::local_ref<JPromise::javaobject>(jni::alias_ref<jni::JString> /* countryCode */)>("getStoreUrl");
+    auto __result = method(_javaPart, countryCode.has_value() ? jni::make_jstring(countryCode.value()) : nullptr);
     return [&]() {
       auto __promise = Promise<std::string>::create();
       __result->cthis()->addOnResolvedListener([=](const jni::alias_ref<jni::JObject>& __boxedResult) {
@@ -93,9 +93,9 @@ namespace margelo::nitro::nitroversioncheck {
       return __promise;
     }();
   }
-  std::shared_ptr<Promise<std::string>> JHybridVersionCheckSpec::getLatestVersion() {
-    static const auto method = javaClassStatic()->getMethod<jni::local_ref<JPromise::javaobject>()>("getLatestVersion");
-    auto __result = method(_javaPart);
+  std::shared_ptr<Promise<std::string>> JHybridVersionCheckSpec::getLatestVersion(const std::optional<std::string>& countryCode) {
+    static const auto method = javaClassStatic()->getMethod<jni::local_ref<JPromise::javaobject>(jni::alias_ref<jni::JString> /* countryCode */)>("getLatestVersion");
+    auto __result = method(_javaPart, countryCode.has_value() ? jni::make_jstring(countryCode.value()) : nullptr);
     return [&]() {
       auto __promise = Promise<std::string>::create();
       __result->cthis()->addOnResolvedListener([=](const jni::alias_ref<jni::JObject>& __boxedResult) {

package/nitrogen/generated/android/c++/JHybridVersionCheckSpec.hpp

@@ -59,8 +59,8 @@ namespace margelo::nitro::nitroversioncheck {
   public:
     // Methods
     std::string getCountry() override;
-    std::shared_ptr<Promise<std::string>> getStoreUrl() override;
-    std::shared_ptr<Promise<std::string>> getLatestVersion() override;
+    std::shared_ptr<Promise<std::string>> getStoreUrl(const std::optional<std::string>& countryCode) override;
+    std::shared_ptr<Promise<std::string>> getLatestVersion(const std::optional<std::string>& countryCode) override;
     std::shared_ptr<Promise<bool>> needsUpdate() override;
 
   private:

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nitroversioncheck/HybridVersionCheckSpec.kt

@@ -66,11 +66,11 @@ abstract class HybridVersionCheckSpec: HybridObject() {
   
   @DoNotStrip
   @Keep
-  abstract fun getStoreUrl(): Promise<String>
+  abstract fun getStoreUrl(countryCode: String?): Promise<String>
   
   @DoNotStrip
   @Keep
-  abstract fun getLatestVersion(): Promise<String>
+  abstract fun getLatestVersion(countryCode: String?): Promise<String>
   
   @DoNotStrip
   @Keep

package/nitrogen/generated/ios/c++/HybridVersionCheckSpecSwift.hpp

@@ -91,16 +91,16 @@ namespace margelo::nitro::nitroversioncheck {
       auto __value = std::move(__result.value());
       return __value;
     }
-    inline std::shared_ptr<Promise<std::string>> getStoreUrl() override {
-      auto __result = _swiftPart.getStoreUrl();
+    inline std::shared_ptr<Promise<std::string>> getStoreUrl(const std::optional<std::string>& countryCode) override {
+      auto __result = _swiftPart.getStoreUrl(countryCode);
       if (__result.hasError()) [[unlikely]] {
         std::rethrow_exception(__result.error());
       }
       auto __value = std::move(__result.value());
       return __value;
     }
-    inline std::shared_ptr<Promise<std::string>> getLatestVersion() override {
-      auto __result = _swiftPart.getLatestVersion();
+    inline std::shared_ptr<Promise<std::string>> getLatestVersion(const std::optional<std::string>& countryCode) override {
+      auto __result = _swiftPart.getLatestVersion(countryCode);
       if (__result.hasError()) [[unlikely]] {
         std::rethrow_exception(__result.error());
       }

package/nitrogen/generated/ios/swift/HybridVersionCheckSpec.swift

@@ -17,8 +17,8 @@ public protocol HybridVersionCheckSpec_protocol: HybridObject {
 
   // Methods
   func getCountry() throws -> String
-  func getStoreUrl() throws -> Promise<String>
-  func getLatestVersion() throws -> Promise<String>
+  func getStoreUrl(countryCode: String?) throws -> Promise<String>
+  func getLatestVersion(countryCode: String?) throws -> Promise<String>
   func needsUpdate() throws -> Promise<Bool>
 }
 

package/nitrogen/generated/ios/swift/HybridVersionCheckSpec_cxx.swift

@@ -169,9 +169,16 @@ open class HybridVersionCheckSpec_cxx {
   }
   
   @inline(__always)
-  public final func getStoreUrl() -> bridge.Result_std__shared_ptr_Promise_std__string___ {
+  public final func getStoreUrl(countryCode: bridge.std__optional_std__string_) -> bridge.Result_std__shared_ptr_Promise_std__string___ {
     do {
-      let __result = try self.__implementation.getStoreUrl()
+      let __result = try self.__implementation.getStoreUrl(countryCode: { () -> String? in
+        if bridge.has_value_std__optional_std__string_(countryCode) {
+          let __unwrapped = bridge.get_std__optional_std__string_(countryCode)
+          return String(__unwrapped)
+        } else {
+          return nil
+        }
+      }())
       let __resultCpp = { () -> bridge.std__shared_ptr_Promise_std__string__ in
         let __promise = bridge.create_std__shared_ptr_Promise_std__string__()
         let __promiseHolder = bridge.wrap_std__shared_ptr_Promise_std__string__(__promise)
@@ -188,9 +195,16 @@ open class HybridVersionCheckSpec_cxx {
   }
   
   @inline(__always)
-  public final func getLatestVersion() -> bridge.Result_std__shared_ptr_Promise_std__string___ {
+  public final func getLatestVersion(countryCode: bridge.std__optional_std__string_) -> bridge.Result_std__shared_ptr_Promise_std__string___ {
     do {
-      let __result = try self.__implementation.getLatestVersion()
+      let __result = try self.__implementation.getLatestVersion(countryCode: { () -> String? in
+        if bridge.has_value_std__optional_std__string_(countryCode) {
+          let __unwrapped = bridge.get_std__optional_std__string_(countryCode)
+          return String(__unwrapped)
+        } else {
+          return nil
+        }
+      }())
       let __resultCpp = { () -> bridge.std__shared_ptr_Promise_std__string__ in
         let __promise = bridge.create_std__shared_ptr_Promise_std__string__()
         let __promiseHolder = bridge.wrap_std__shared_ptr_Promise_std__string__(__promise)

package/nitrogen/generated/shared/c++/HybridVersionCheckSpec.hpp

@@ -54,8 +54,8 @@ namespace margelo::nitro::nitroversioncheck {
     public:
       // Methods
       virtual std::string getCountry() = 0;
-      virtual std::shared_ptr<Promise<std::string>> getStoreUrl() = 0;
-      virtual std::shared_ptr<Promise<std::string>> getLatestVersion() = 0;
+      virtual std::shared_ptr<Promise<std::string>> getStoreUrl(const std::optional<std::string>& countryCode) = 0;
+      virtual std::shared_ptr<Promise<std::string>> getLatestVersion(const std::optional<std::string>& countryCode) = 0;
       virtual std::shared_ptr<Promise<bool>> needsUpdate() = 0;
 
     protected:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-version-check",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "A lightweight, fast version-checking library for React Native, powered by Nitro Modules",
   "main": "lib/index",
   "module": "lib/index",
@@ -9,8 +9,8 @@
   "source": "src/index",
   "files": [
     "src",
-    "react-native.config.js",
     "lib",
+    "react-native.config.js",
     "nitrogen",
     "android/build.gradle",
     "android/gradle.properties",
@@ -34,6 +34,9 @@
     "release": "release-it",
     "build": "tsc",
     "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
@@ -149,12 +152,15 @@
   },
   "devDependencies": {
     "@release-it/conventional-changelog": "^10.0.5",
+    "@types/jest": "^29.5.12",
     "@types/react": "^19.1.03",
+    "jest": "^29.7.0",
     "nitrogen": "*",
     "react": "19.2.0",
     "react-native": "0.83.0",
     "react-native-nitro-modules": "*",
     "release-it": "^19.2.4",
+    "ts-jest": "^29.1.2",
     "typescript": "^5.8.3"
   },
   "peerDependencies": {

package/src/__tests__/index.test.ts

@@ -0,0 +1,283 @@
+import { type UpdateLevel, VersionCheck } from "../index";
+
+// Mock the NitroModules
+jest.mock("react-native-nitro-modules", () => ({
+  NitroModules: {
+    createHybridObject: jest.fn(() => ({
+      version: "1.2.0",
+      buildNumber: "42",
+      packageName: "com.example.app",
+      installSource: "appstore",
+      getCountry: jest.fn(() => "US"),
+      getStoreUrl: jest.fn(() => Promise.resolve("https://apps.apple.com/app/example")),
+      getLatestVersion: jest.fn(() => Promise.resolve("1.3.0")),
+    })),
+  },
+}));
+
+describe("VersionCheck API", () => {
+  describe("structure", () => {
+    it("should export VersionCheck object with all required properties", () => {
+      expect(VersionCheck).toBeDefined();
+      expect(typeof VersionCheck).toBe("object");
+    });
+
+    it("should have sync properties", () => {
+      expect(VersionCheck.version).toBeDefined();
+      expect(typeof VersionCheck.version).toBe("string");
+
+      expect(VersionCheck.buildNumber).toBeDefined();
+      expect(typeof VersionCheck.buildNumber).toBe("string");
+
+      expect(VersionCheck.packageName).toBeDefined();
+      expect(typeof VersionCheck.packageName).toBe("string");
+    });
+
+    it("should have optional installSource property", () => {
+      expect(VersionCheck.installSource).toBeDefined();
+      expect(
+        VersionCheck.installSource === undefined ||
+          VersionCheck.installSource === "appstore" ||
+          VersionCheck.installSource === "testflight" ||
+          VersionCheck.installSource === "playstore"
+      ).toBe(true);
+    });
+
+    it("should have sync method getCountry", () => {
+      expect(typeof VersionCheck.getCountry).toBe("function");
+      expect(VersionCheck.getCountry()).toBeDefined();
+    });
+
+    it("should have async method getStoreUrl", () => {
+      expect(typeof VersionCheck.getStoreUrl).toBe("function");
+      const result = VersionCheck.getStoreUrl();
+      expect(result).toBeInstanceOf(Promise);
+    });
+
+    it("should have async method getLatestVersion", () => {
+      expect(typeof VersionCheck.getLatestVersion).toBe("function");
+      const result = VersionCheck.getLatestVersion();
+      expect(result).toBeInstanceOf(Promise);
+    });
+
+    it("should have async method needsUpdate", () => {
+      expect(typeof VersionCheck.needsUpdate).toBe("function");
+      const result = VersionCheck.needsUpdate();
+      expect(result).toBeInstanceOf(Promise);
+    });
+  });
+
+  describe("property access", () => {
+    it("should return string values for sync properties", () => {
+      expect(typeof VersionCheck.version).toBe("string");
+      expect(typeof VersionCheck.buildNumber).toBe("string");
+      expect(typeof VersionCheck.packageName).toBe("string");
+    });
+
+    it("should have consistent version format", () => {
+      const version = VersionCheck.version;
+      // Should be a semantic version like "1.2.0"
+      expect(version).toMatch(/^\d+\.\d+\.\d+$/);
+    });
+
+    it("should return a valid country code for getCountry()", () => {
+      const country = VersionCheck.getCountry();
+      // Should be a 2-letter ISO country code (uppercase letters)
+      expect(country).toMatch(/^[A-Z]{2}$/);
+    });
+  });
+
+  describe("needsUpdate", () => {
+    it("should return a Promise<boolean>", async () => {
+      const result = VersionCheck.needsUpdate();
+      expect(result).toBeInstanceOf(Promise);
+      const resolved = await result;
+      expect(typeof resolved).toBe("boolean");
+    });
+
+    it("should accept options with level parameter", async () => {
+      const levels: UpdateLevel[] = ["major", "minor", "patch"];
+      for (const level of levels) {
+        const result = VersionCheck.needsUpdate({ level });
+        expect(result).toBeInstanceOf(Promise);
+        const resolved = await result;
+        expect(typeof resolved).toBe("boolean");
+      }
+    });
+
+    it("should default to patch level when no options provided", async () => {
+      const result = await VersionCheck.needsUpdate();
+      expect(typeof result).toBe("boolean");
+    });
+
+    it("should compare current version with latest", async () => {
+      // With mocked latest version as '1.3.0' and current as '1.2.0'
+      const needsUpdate = await VersionCheck.needsUpdate();
+      expect(typeof needsUpdate).toBe("boolean");
+    });
+  });
+
+  describe("API consistency", () => {
+    it("should provide consistent property access across multiple calls", () => {
+      expect(VersionCheck.version).toBe(VersionCheck.version);
+      expect(VersionCheck.buildNumber).toBe(VersionCheck.buildNumber);
+      expect(VersionCheck.packageName).toBe(VersionCheck.packageName);
+      expect(VersionCheck.getCountry()).toBe(VersionCheck.getCountry());
+    });
+
+    it("should have readonly type signature", () => {
+      // Type checking ensures VersionCheck object is readonly
+      // This test verifies all methods and properties exist as expected
+      expect(VersionCheck).toBeDefined();
+      expect(Object.keys(VersionCheck).length > 0).toBe(true);
+    });
+  });
+
+  describe("async operations", () => {
+    it("should fetch store URL", async () => {
+      const url = await VersionCheck.getStoreUrl();
+      expect(url).toMatch(/^https?:\/\//);
+      expect(url).toMatch(/apps\.apple\.com|play\.google\.com/);
+    });
+
+    it("should fetch store URL with custom country code", async () => {
+      const urlUS = await VersionCheck.getStoreUrl({ countryCode: "US" });
+      const urlGB = await VersionCheck.getStoreUrl({ countryCode: "GB" });
+      expect(urlUS).toMatch(/^https?:\/\//);
+      expect(urlGB).toMatch(/^https?:\/\//);
+      expect(urlUS).toMatch(/apps\.apple\.com|play\.google\.com/);
+      expect(urlGB).toMatch(/apps\.apple\.com|play\.google\.com/);
+    });
+
+    it("should fetch store URL with undefined country code", async () => {
+      const url = await VersionCheck.getStoreUrl({ countryCode: undefined });
+      expect(url).toMatch(/^https?:\/\//);
+      expect(url).toMatch(/apps\.apple\.com|play\.google\.com/);
+    });
+
+    it("should fetch latest version", async () => {
+      const latest = await VersionCheck.getLatestVersion();
+      expect(typeof latest).toBe("string");
+      // Should be a semantic version
+      expect(latest).toMatch(/^\d+\.\d+\.\d+$/);
+    });
+
+    it("should fetch latest version with custom country code", async () => {
+      const latestUS = await VersionCheck.getLatestVersion({ countryCode: "US" });
+      const latestGB = await VersionCheck.getLatestVersion({ countryCode: "GB" });
+      expect(typeof latestUS).toBe("string");
+      expect(typeof latestGB).toBe("string");
+      expect(latestUS).toMatch(/^\d+\.\d+\.\d+$/);
+      expect(latestGB).toMatch(/^\d+\.\d+\.\d+$/);
+    });
+
+    it("should use device country code by default", async () => {
+      const latest = await VersionCheck.getLatestVersion();
+      const latestWithDefault = await VersionCheck.getLatestVersion({ countryCode: undefined });
+      expect(typeof latest).toBe("string");
+      expect(typeof latestWithDefault).toBe("string");
+    });
+
+    it("should handle getLatestVersion and needsUpdate in parallel", async () => {
+      const [latest, needsUpdate] = await Promise.all([VersionCheck.getLatestVersion(), VersionCheck.needsUpdate()]);
+      expect(typeof latest).toBe("string");
+      expect(typeof needsUpdate).toBe("boolean");
+    });
+
+    it("should handle all async operations in parallel", async () => {
+      const [storeUrl, latestVersion, needsUpdate] = await Promise.all([
+        VersionCheck.getStoreUrl(),
+        VersionCheck.getLatestVersion(),
+        VersionCheck.needsUpdate(),
+      ]);
+      expect(typeof storeUrl).toBe("string");
+      expect(typeof latestVersion).toBe("string");
+      expect(typeof needsUpdate).toBe("boolean");
+    });
+  });
+
+  describe("common usage patterns", () => {
+    it("should support destructuring", () => {
+      const { version, buildNumber, packageName, installSource } = VersionCheck;
+      expect(typeof version).toBe("string");
+      expect(typeof buildNumber).toBe("string");
+      expect(typeof packageName).toBe("string");
+      expect(installSource === undefined || typeof installSource === "string").toBe(true);
+    });
+
+    it("should support destructuring with getCountry", () => {
+      const { getCountry } = VersionCheck;
+      expect(typeof getCountry).toBe("function");
+      expect(getCountry()).toBeDefined();
+    });
+
+    it("should support common update flow", async () => {
+      const url = await VersionCheck.getStoreUrl();
+      const needsUpdate = await VersionCheck.needsUpdate();
+
+      expect(url).toMatch(/^https?:\/\//);
+      expect(url).toMatch(/apps\.apple\.com|play\.google\.com/);
+      expect(typeof needsUpdate).toBe("boolean");
+
+      if (needsUpdate) {
+        expect(url).toBeTruthy();
+      }
+    });
+
+    it("should support granular update checks", async () => {
+      const majorUpdate = await VersionCheck.needsUpdate({ level: "major" });
+      const minorUpdate = await VersionCheck.needsUpdate({ level: "minor" });
+      const patchUpdate = await VersionCheck.needsUpdate({ level: "patch" });
+
+      // All should return boolean values
+      expect([majorUpdate, minorUpdate, patchUpdate]).toEqual(
+        expect.arrayContaining([true, false].includes(majorUpdate) ? [majorUpdate] : [])
+      );
+      expect(typeof majorUpdate).toBe("boolean");
+      expect(typeof minorUpdate).toBe("boolean");
+      expect(typeof patchUpdate).toBe("boolean");
+
+      // Logical consistency: granular checks have semantic ordering
+      // If major update, then minor and patch should also be true
+      if (majorUpdate) {
+        expect(minorUpdate).toBe(true);
+        expect(patchUpdate).toBe(true);
+      }
+      // If minor but not major, patch should still be true
+      if (minorUpdate && !majorUpdate) {
+        expect(patchUpdate).toBe(true);
+      }
+    });
+
+    it("should support install source detection", () => {
+      const source = VersionCheck.installSource;
+
+      if (source !== undefined) {
+        expect(["appstore", "testflight", "playstore"]).toContain(source);
+      }
+    });
+
+    it("should support region-specific store URLs", async () => {
+      const urlUS = await VersionCheck.getStoreUrl({ countryCode: "US" });
+      const urlGB = await VersionCheck.getStoreUrl({ countryCode: "GB" });
+      const urlJP = await VersionCheck.getStoreUrl({ countryCode: "JP" });
+
+      expect(urlUS).toMatch(/^https?:\/\//);
+      expect(urlGB).toMatch(/^https?:\/\//);
+      expect(urlJP).toMatch(/^https?:\/\//);
+      expect(urlUS).toMatch(/apps\.apple\.com|play\.google\.com/);
+      expect(urlGB).toMatch(/apps\.apple\.com|play\.google\.com/);
+      expect(urlJP).toMatch(/apps\.apple\.com|play\.google\.com/);
+    });
+
+    it("should support region-specific version checks", async () => {
+      const latestUS = await VersionCheck.getLatestVersion({ countryCode: "US" });
+      const latestGB = await VersionCheck.getLatestVersion({ countryCode: "GB" });
+      const latestJP = await VersionCheck.getLatestVersion({ countryCode: "JP" });
+
+      expect(typeof latestUS).toBe("string");
+      expect(typeof latestGB).toBe("string");
+      expect(typeof latestJP).toBe("string");
+    });
+  });
+});

package/src/__tests__/semver.test.ts

@@ -0,0 +1,145 @@
+import { compareVersions, isNewerVersion } from "../semver";
+
+describe("semver", () => {
+  describe("compareVersions", () => {
+    it("should return -1 when first version is older", () => {
+      expect(compareVersions("1.2.0", "1.3.0")).toBe(-1);
+      expect(compareVersions("1.2.0", "2.0.0")).toBe(-1);
+      expect(compareVersions("1.2.3", "1.2.4")).toBe(-1);
+    });
+
+    it("should return 1 when first version is newer", () => {
+      expect(compareVersions("2.0.0", "1.9.9")).toBe(1);
+      expect(compareVersions("1.3.0", "1.2.0")).toBe(1);
+      expect(compareVersions("1.2.4", "1.2.3")).toBe(1);
+    });
+
+    it("should return 0 when versions are equal", () => {
+      expect(compareVersions("1.0.0", "1.0.0")).toBe(0);
+      expect(compareVersions("2.5.10", "2.5.10")).toBe(0);
+    });
+
+    it("should handle major version differences", () => {
+      expect(compareVersions("1.0.0", "2.0.0")).toBe(-1);
+      expect(compareVersions("3.0.0", "2.0.0")).toBe(1);
+    });
+
+    it("should handle minor version differences", () => {
+      expect(compareVersions("1.2.0", "1.3.0")).toBe(-1);
+      expect(compareVersions("1.5.0", "1.3.0")).toBe(1);
+    });
+
+    it("should handle patch version differences", () => {
+      expect(compareVersions("1.0.5", "1.0.10")).toBe(-1);
+      expect(compareVersions("1.0.10", "1.0.5")).toBe(1);
+    });
+
+    it("should handle versions with leading zeros", () => {
+      expect(compareVersions("01.02.03", "1.2.3")).toBe(0);
+    });
+
+    it("should handle malformed versions gracefully", () => {
+      // Missing parts should be treated as 0
+      expect(compareVersions("1", "1.0.0")).toBe(0);
+      expect(compareVersions("1.2", "1.2.0")).toBe(0);
+    });
+
+    it("should handle real-world version scenarios", () => {
+      // Bug fix scenario
+      expect(compareVersions("2.2.0", "2.0.22")).toBe(1); // 2.2.0 is newer than 2.0.22
+      expect(compareVersions("2.0.22", "2.2.0")).toBe(-1);
+
+      // Update checks
+      expect(compareVersions("1.0.0", "1.0.1")).toBe(-1);
+      expect(compareVersions("1.0.0", "1.1.0")).toBe(-1);
+      expect(compareVersions("1.0.0", "2.0.0")).toBe(-1);
+    });
+  });
+
+  describe("isNewerVersion", () => {
+    describe("with patch level (default)", () => {
+      it("should return true for any version increase", () => {
+        expect(isNewerVersion("1.0.0", "1.0.1", "patch")).toBe(true);
+        expect(isNewerVersion("1.0.0", "1.1.0", "patch")).toBe(true);
+        expect(isNewerVersion("1.0.0", "2.0.0", "patch")).toBe(true);
+      });
+
+      it("should return false when current is same or newer", () => {
+        expect(isNewerVersion("1.0.0", "1.0.0", "patch")).toBe(false);
+        expect(isNewerVersion("1.0.1", "1.0.0", "patch")).toBe(false);
+        expect(isNewerVersion("2.0.0", "1.0.0", "patch")).toBe(false);
+      });
+
+      it("should use patch level as default", () => {
+        expect(isNewerVersion("1.0.0", "1.0.1")).toBe(true);
+        expect(isNewerVersion("1.0.0", "1.0.0")).toBe(false);
+      });
+    });
+
+    describe("with minor level", () => {
+      it("should return true for major or minor bumps", () => {
+        expect(isNewerVersion("1.0.0", "1.1.0", "minor")).toBe(true);
+        expect(isNewerVersion("1.0.0", "2.0.0", "minor")).toBe(true);
+      });
+
+      it("should return false for patch-only bumps", () => {
+        expect(isNewerVersion("1.0.0", "1.0.1", "minor")).toBe(false);
+      });
+
+      it("should return false when current is same or newer", () => {
+        expect(isNewerVersion("1.1.0", "1.1.0", "minor")).toBe(false);
+        expect(isNewerVersion("1.1.0", "1.0.0", "minor")).toBe(false);
+        expect(isNewerVersion("2.0.0", "1.5.0", "minor")).toBe(false);
+      });
+    });
+
+    describe("with major level", () => {
+      it("should return true only for major bumps", () => {
+        expect(isNewerVersion("1.0.0", "2.0.0", "major")).toBe(true);
+        expect(isNewerVersion("1.5.9", "2.0.0", "major")).toBe(true);
+      });
+
+      it("should return false for minor or patch bumps", () => {
+        expect(isNewerVersion("1.0.0", "1.1.0", "major")).toBe(false);
+        expect(isNewerVersion("1.0.0", "1.0.1", "major")).toBe(false);
+      });
+
+      it("should return false when current is same or newer", () => {
+        expect(isNewerVersion("1.0.0", "1.0.0", "major")).toBe(false);
+        expect(isNewerVersion("2.0.0", "1.0.0", "major")).toBe(false);
+      });
+    });
+
+    describe("real-world scenarios", () => {
+      it("should handle the GitHub issue scenario", () => {
+        // From the issue: latest is 2.0.22, current is 2.2.0
+        expect(isNewerVersion("2.2.0", "2.0.22", "patch")).toBe(false);
+        expect(isNewerVersion("2.2.0", "2.0.22", "minor")).toBe(false);
+        expect(isNewerVersion("2.2.0", "2.0.22", "major")).toBe(false);
+      });
+
+      it("should handle typical update scenarios", () => {
+        // App is on 1.2.0, store has 1.2.1
+        expect(isNewerVersion("1.2.0", "1.2.1", "patch")).toBe(true);
+        expect(isNewerVersion("1.2.0", "1.2.1", "minor")).toBe(false);
+        expect(isNewerVersion("1.2.0", "1.2.1", "major")).toBe(false);
+
+        // App is on 1.2.0, store has 1.3.0
+        expect(isNewerVersion("1.2.0", "1.3.0", "patch")).toBe(true);
+        expect(isNewerVersion("1.2.0", "1.3.0", "minor")).toBe(true);
+        expect(isNewerVersion("1.2.0", "1.3.0", "major")).toBe(false);
+
+        // App is on 1.2.0, store has 2.0.0
+        expect(isNewerVersion("1.2.0", "2.0.0", "patch")).toBe(true);
+        expect(isNewerVersion("1.2.0", "2.0.0", "minor")).toBe(true);
+        expect(isNewerVersion("1.2.0", "2.0.0", "major")).toBe(true);
+      });
+
+      it("should correctly identify when app is already up to date", () => {
+        expect(isNewerVersion("1.5.0", "1.4.0")).toBe(false);
+        expect(isNewerVersion("2.0.0", "1.9.9")).toBe(false);
+        expect(isNewerVersion("3.0.0", "2.99.99")).toBe(false);
+      });
+    });
+  });
+});

package/src/index.ts

@@ -11,68 +11,12 @@ const buildNumber = HybridVersionCheck.buildNumber;
 const packageName = HybridVersionCheck.packageName;
 const installSource = HybridVersionCheck.installSource;
 
-/**
- * Returns the device's current 2-letter ISO country code.
- *
- * @example
- * ```ts
- * getCountry() // "US"
- * ```
- */
-export const getCountry = () => HybridVersionCheck.getCountry();
-
-/**
- * Returns the store URL for this app.
- *
- * Automatically resolves to the App Store on iOS and Play Store on Android.
- *
- * @example
- * ```ts
- * const url = await getStoreUrl();
- * Linking.openURL(url);
- * ```
- */
-export const getStoreUrl = () => HybridVersionCheck.getStoreUrl();
-
-/**
- * Fetches the latest version of this app available in the store.
- *
- * @example
- * ```ts
- * const latest = await getLatestVersion(); // "1.3.0"
- * ```
- */
-export const getLatestVersion = () => HybridVersionCheck.getLatestVersion();
-
-/**
- * Checks whether an app update is available.
- *
- * Uses semantic version comparison. By default checks for any version
- * increase, but you can filter by granularity:
- *
- * - `"major"` — only returns `true` for major bumps (1.x → 2.x)
- * - `"minor"` — returns `true` for major or minor bumps
- * - `"patch"` — returns `true` for any version increase (default)
- *
- * @example
- * ```ts
- * if (await needsUpdate()) {
- *   const url = await getStoreUrl();
- *   Linking.openURL(url);
- * }
- *
- * // Only prompt for major updates
- * const majorUpdate = await needsUpdate({ level: "major" });
- * ```
- */
-export const needsUpdate = async (options?: { level?: UpdateLevel }): Promise<boolean> => {
-  const latest = await HybridVersionCheck.getLatestVersion();
-  return isNewerVersion(version, latest, options?.level ?? "patch");
-};
-
 /**
  * All version-check APIs in one object.
  *
+ * Provides access to app version information, store URLs, and update checking.
+ * Sync properties are cached at module init for zero native overhead.
+ *
  * @example
  * ```ts
  * VersionCheck.version      // "1.2.0"
@@ -81,6 +25,9 @@ export const needsUpdate = async (options?: { level?: UpdateLevel }): Promise<bo
  * VersionCheck.getCountry() // "US"
  *
  * const url = await VersionCheck.getStoreUrl();
+ * if (await VersionCheck.needsUpdate()) {
+ *   Linking.openURL(url);
+ * }
  * ```
  */
 export const VersionCheck = {
@@ -144,42 +91,89 @@ export const VersionCheck = {
    * VersionCheck.getCountry() // "US"
    * ```
    */
-  getCountry,
+  getCountry: () => HybridVersionCheck.getCountry(),
   /**
    * Returns the App Store (iOS) or Play Store (Android) URL for this app.
    *
+   * @param options - Optional configuration
+   * @param options.countryCode - 2-letter ISO country code (e.g., "US", "GB")
+   *   Defaults to the device's current country from `getCountry()`.
+   *   Only used on iOS; ignored on Android.
+   *
    * @example
    * ```ts
    * const url = await VersionCheck.getStoreUrl();
+   * const urlUS = await VersionCheck.getStoreUrl({ countryCode: "US" });
    * Linking.openURL(url);
    * ```
    */
-  getStoreUrl,
+  getStoreUrl: async (options?: { countryCode?: string }): Promise<string> => {
+    return HybridVersionCheck.getStoreUrl(options?.countryCode);
+  },
   /**
    * Fetches the latest version of this app available in the store.
    *
    * Queries the iTunes API on iOS and the Play Store on Android.
+   * On iOS, uses the device's current country code by default but can be overridden.
+   *
+   * @param options - Optional configuration
+   * @param options.countryCode - 2-letter ISO country code (e.g., "US", "GB")
+   *   Defaults to the device's current country from `getCountry()`.
+   *   If the device region changes, the next call will use the new country.
+   *   Only used on iOS; ignored on Android.
    *
    * @example
    * ```ts
-   * const latest = await VersionCheck.getLatestVersion(); // "1.3.0"
+   * const latest = await VersionCheck.getLatestVersion(); // Uses current device country
+   * const latestUS = await VersionCheck.getLatestVersion({ countryCode: "US" });
+   * const latestGB = await VersionCheck.getLatestVersion({ countryCode: "GB" });
    * ```
    */
-  getLatestVersion,
+  getLatestVersion: async (options?: { countryCode?: string }): Promise<string> => {
+    return HybridVersionCheck.getLatestVersion(options?.countryCode);
+  },
   /**
    * Checks whether an app update is available by comparing the current
    * version against the latest store version.
    *
+   * Uses semantic version comparison. By default checks for any version
+   * increase, but you can filter by granularity:
+   *
+   * - `"major"` — only returns `true` for major bumps (1.x → 2.x)
+   * - `"minor"` — returns `true` for major or minor bumps
+   * - `"patch"` — returns `true` for any version increase (default)
+   *
    * @example
    * ```ts
    * if (await VersionCheck.needsUpdate()) {
    *   const url = await VersionCheck.getStoreUrl();
    *   Linking.openURL(url);
    * }
+   *
+   * // Only prompt for major updates
+   * const majorUpdate = await VersionCheck.needsUpdate({ level: "major" });
    * ```
    */
-  needsUpdate: () => HybridVersionCheck.needsUpdate(),
+  needsUpdate: async (options?: { level?: UpdateLevel }): Promise<boolean> => {
+    const latest = await HybridVersionCheck.getLatestVersion();
+    return isNewerVersion(version, latest, options?.level ?? "patch");
+  },
+  /**
+   * Compares two semantic version strings.
+   *
+   * @returns -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
+   *
+   * @example
+   * ```ts
+   * VersionCheck.compareVersions('1.0.0', '1.0.1') // -1
+   * VersionCheck.compareVersions('2.0.0', '2.0.0') //  0
+   * VersionCheck.compareVersions('3.0.0', '2.9.9') //  1
+   *
+   * if (VersionCheck.compareVersions(currentVersion, minimumVersion) < 0) {
+   *   // Current version is below minimum — force update
+   * }
+   * ```
+   */
+  compareVersions,
 } as const;
-
-export { compareVersions };
 export type { UpdateLevel };

package/src/specs/Version.nitro.ts

@@ -10,7 +10,7 @@ export interface VersionCheck
   readonly packageName: string;
   readonly installSource: string | undefined;
   getCountry(): string;
-  getStoreUrl(): Promise<string>;
-  getLatestVersion(): Promise<string>;
+  getStoreUrl(countryCode?: string): Promise<string>;
+  getLatestVersion(countryCode?: string): Promise<string>;
   needsUpdate(): Promise<boolean>;
 }