react-native-nitro-version-check 2.0.0 → 2.0.2

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

@@ -66,7 +66,7 @@ class HybridVersionCheck : HybridVersionCheckSpec() {
     override fun needsUpdate(): Promise<Boolean> {
         return Promise.async {
             try {
-                val latest = getLatestVersion().await()
+                val latest = getLatestVersion(null).await()
                 version != latest
             } catch (e: Exception) {
                 throw Exception("Failed to check for updates: ${e.message}", e)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-version-check",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "A lightweight, fast version-checking library for React Native, powered by Nitro Modules",
   "main": "lib/index",
   "module": "lib/index",
@@ -8,6 +8,7 @@
   "react-native": "src/index",
   "source": "src/index",
   "files": [
+    "src",
     "lib",
     "react-native.config.js",
     "nitrogen",
@@ -157,7 +158,7 @@
     "nitrogen": "^0.35.0",
     "react": "19.2.0",
     "react-native": "0.83.0",
-    "react-native-nitro-modules": "*",
+    "react-native-nitro-modules": ">=0.35.0",
     "release-it": "^19.2.4",
     "ts-jest": "^29.1.2",
     "typescript": "^5.8.3"
@@ -165,6 +166,6 @@
   "peerDependencies": {
     "react": "*",
     "react-native": "*",
-    "react-native-nitro-modules": ">=35.0"
+    "react-native-nitro-modules": ">=0.35.0"
   }
 }

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

@@ -0,0 +1,179 @@
+import { NitroModules } from "react-native-nitro-modules";
+import type { UpdateLevel } from "./semver";
+import { compareVersions, isNewerVersion } from "./semver";
+import type { VersionCheck as VersionCheckType } from "./specs/Version.nitro";
+
+const HybridVersionCheck = NitroModules.createHybridObject<VersionCheckType>("VersionCheck");
+
+// Cached at module init — plain JS values, no JSI overhead on repeated access.
+const version = HybridVersionCheck.version;
+const buildNumber = HybridVersionCheck.buildNumber;
+const packageName = HybridVersionCheck.packageName;
+const installSource = HybridVersionCheck.installSource;
+
+/**
+ * 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"
+ * VersionCheck.buildNumber  // "42"
+ * VersionCheck.packageName  // "com.example.app"
+ * VersionCheck.getCountry() // "US"
+ *
+ * const url = await VersionCheck.getStoreUrl();
+ * if (await VersionCheck.needsUpdate()) {
+ *   Linking.openURL(url);
+ * }
+ * ```
+ */
+export const VersionCheck = {
+  /**
+   * The current app version string.
+   *
+   * Read from `CFBundleShortVersionString` on iOS and `versionName` on Android.
+   * Cached at module init, so repeated reads have zero native overhead.
+   *
+   * @example
+   * ```ts
+   * VersionCheck.version // "1.2.0"
+   * ```
+   */
+  version,
+  /**
+   * The current build number.
+   *
+   * Read from `CFBundleVersion` on iOS and `versionCode` on Android.
+   * Cached at module init.
+   *
+   * @example
+   * ```ts
+   * VersionCheck.buildNumber // "42"
+   * ```
+   */
+  buildNumber,
+  /**
+   * The app's unique identifier.
+   *
+   * This is the Bundle ID on iOS and the Application ID on Android.
+   * Cached at module init.
+   *
+   * @example
+   * ```ts
+   * VersionCheck.packageName // "com.example.app"
+   * ```
+   */
+  packageName,
+  /**
+   * Where the app was installed from, or `undefined` for dev/sideloaded builds.
+   *
+   * - iOS: `"appstore"` | `"testflight"` | `undefined`
+   * - Android: `"playstore"` | `undefined`
+   *
+   * @example
+   * ```ts
+   * if (VersionCheck.installSource === "testflight") {
+   *   // running a TestFlight build
+   * }
+   * ```
+   */
+  installSource,
+  /**
+   * Returns the device's current 2-letter ISO country code.
+   *
+   * This is a synchronous Nitro call, no `await` needed.
+   *
+   * @example
+   * ```ts
+   * VersionCheck.getCountry() // "US"
+   * ```
+   */
+  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: 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(); // Uses current device country
+   * const latestUS = await VersionCheck.getLatestVersion({ countryCode: "US" });
+   * const latestGB = await VersionCheck.getLatestVersion({ countryCode: "GB" });
+   * ```
+   */
+  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: 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 type { UpdateLevel };

package/src/semver.ts

@@ -0,0 +1,54 @@
+export type UpdateLevel = "major" | "minor" | "patch";
+
+type SemVer = [major: number, minor: number, patch: number];
+
+function parseVersion(version: string): SemVer {
+  const parts = version.split(".");
+  return [Number(parts[0]) || 0, Number(parts[1]) || 0, Number(parts[2]) || 0];
+}
+
+/**
+ * Compares two version strings.
+ *
+ * @returns `-1` if `v1 < v2`, `0` if equal, `1` if `v1 > v2`
+ *
+ * @example
+ * ```ts
+ * compareVersions("1.2.0", "1.3.0") // -1
+ * compareVersions("2.0.0", "1.9.9") //  1
+ * compareVersions("1.0.0", "1.0.0") //  0
+ * ```
+ */
+export function compareVersions(v1: string, v2: string): -1 | 0 | 1 {
+  const a = parseVersion(v1);
+  const b = parseVersion(v2);
+
+  for (let i = 0; i < 3; i++) {
+    if (a[i]! > b[i]!) return 1;
+    if (a[i]! < b[i]!) return -1;
+  }
+
+  return 0;
+}
+
+/**
+ * Checks whether `latest` is newer than `current` at the given 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)
+ */
+export function isNewerVersion(current: string, latest: string, level: UpdateLevel = "patch"): boolean {
+  const [curMajor, curMinor, curPatch] = parseVersion(current);
+  const [latMajor, latMinor, latPatch] = parseVersion(latest);
+
+  if (latMajor > curMajor) return true;
+  if (latMajor < curMajor) return false;
+  if (level === "major") return false;
+
+  if (latMinor > curMinor) return true;
+  if (latMinor < curMinor) return false;
+  if (level === "minor") return false;
+
+  return latPatch > curPatch;
+}

package/src/specs/Version.nitro.ts

@@ -0,0 +1,16 @@
+import type { HybridObject } from "react-native-nitro-modules";
+
+export interface VersionCheck
+  extends HybridObject<{
+    ios: "swift";
+    android: "kotlin";
+  }> {
+  readonly version: string;
+  readonly buildNumber: string;
+  readonly packageName: string;
+  readonly installSource: string | undefined;
+  getCountry(): string;
+  getStoreUrl(countryCode?: string): Promise<string>;
+  getLatestVersion(countryCode?: string): Promise<string>;
+  needsUpdate(): Promise<boolean>;
+}