feat!: consolidate API to VersionCheck object with consistent options

BREAKING CHANGE: All standalone function exports removed. Use VersionCheck object.

- API consolidation: getCountry, getStoreUrl, getLatestVersion, needsUpdate now VersionCheck methods
- Consistent options: all async methods use object-based parameters { countryCode?, level? }
- compareVersions now part of VersionCheck object
- Country code support: optional region override for store lookups (iOS)
- Made getStoreUrl async for consistency
- 52 comprehensive tests with 87%+ coverage (exceeds 70% thresholds)
- Jest setup with TypeScript support, test files excluded from build
- GitHub Actions CI with coverage enforcement and codecov upload
- Updated iOS/Android native implementations with country code parameter
- All documentation updated (api-reference, migration-guide, usage-examples)

Migration: getCountry() → VersionCheck.getCountry()
          getLatestVersion() → VersionCheck.getLatestVersion({ countryCode: 'US' })
          compareVersions() → VersionCheck.compareVersions('1.0.0', '2.0.0')

Author: AlshehriAli0

.github/workflows/ci.yml

@@ -20,3 +20,22 @@ jobs:
       - run: bun run lint
 
       - run: bun run typecheck
+
+  test:
+    name: Test Suite
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - run: bun install --frozen-lockfile
+
+      - run: bun run test:coverage
+
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./package/coverage/lcov.info
+          flags: unittests
+          name: codecov-umbrella

.gitignore

@@ -64,6 +64,14 @@ lib/
 .cache
 *.tsbuildinfo
 
+# Test coverage and Jest
+coverage/
+package/coverage/
+.jest-cache/
+
+# Claude Code
+.claude/
+
 # Docusaurus
 docs/.docusaurus/
 docs/build/

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"
@@ -24,8 +24,8 @@ VersionCheck.packageName   // "com.example.app"
 VersionCheck.installSource // "appstore" | "testflight" | "playstore" | undefined
 
 // Check for updates
-if (await needsUpdate()) {
-  Linking.openURL(await getStoreUrl())
+if (await VersionCheck.needsUpdate()) {
+  Linking.openURL(await VersionCheck.getStoreUrl())
 }
 ```
 

biome.json

@@ -103,7 +103,7 @@
         "useGetterReturn": "error"
       }
     },
-    "includes": ["package/src/**", "example/**", "!**/*.d.ts", "!**/node_modules/**"]
+    "includes": ["package/src/**", "example/**", "!**/*.d.ts", "!**/node_modules/**", "!**/__tests__/**"]
   },
   "javascript": {
     "formatter": {
@@ -120,6 +120,39 @@
   },
   "html": { "formatter": { "selfCloseVoidElements": "always" } },
   "overrides": [
+    {
+      "includes": ["**/__tests__/**/*.{js,jsx,ts,tsx}"],
+      "javascript": {
+        "globals": [
+          "require",
+          "console",
+          "setTimeout",
+          "requestAnimationFrame",
+          "setInterval",
+          "process",
+          "__DEV__",
+          "cancelAnimationFrame",
+          "fetch",
+          "clearTimeout",
+          "clearInterval",
+          "jest",
+          "describe",
+          "it",
+          "expect",
+          "beforeEach",
+          "afterEach",
+          "beforeAll",
+          "afterAll"
+        ]
+      },
+      "linter": {
+        "rules": {
+          "correctness": {
+            "noUnusedVariables": "off"
+          }
+        }
+      }
+    },
     {
       "includes": ["**/*.{js,jsx,ts,tsx}"],
       "javascript": {

bun.lock

@@ -27,62 +27,62 @@ import { VersionCheck } from 'react-native-nitro-version-check'
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `getCountry()` | `string` | Device's 2-letter ISO country code (sync) |
-| `getStoreUrl()` | `Promise<string>` | App Store / Play Store URL |
-| `getLatestVersion()` | `Promise<string>` | Latest version available in the store |
-| `needsUpdate()` | `Promise<boolean>` | Whether an update is available |
+| `getStoreUrl(options?)` | `Promise<string>` | App Store / Play Store URL with optional country code |
+| `getLatestVersion(options?)` | `Promise<string>` | Latest version available in the store with optional country code |
+| `needsUpdate(options?)` | `Promise<boolean>` | Whether an update is available with optional level filtering |
 
-## Standalone Exports
-
-All methods are also available as individual named exports:
-
-```ts
-import {
-  getCountry,
-  getStoreUrl,
-  getLatestVersion,
-  needsUpdate,
-  compareVersions,
-} from 'react-native-nitro-version-check'
-```
-
-### `getCountry()`
+### `VersionCheck.getCountry()`
 
 Returns the device's current 2-letter ISO country code. This is a **synchronous** call.
 
 ```ts
-const country = getCountry() // "US"
+const country = VersionCheck.getCountry() // "US"
 ```
 
-### `getStoreUrl()`
+### `VersionCheck.getStoreUrl(options?)`
 
 Returns the store URL for this app. Automatically resolves to the App Store on iOS and Play Store on Android.
 
 ```ts
-const url = await getStoreUrl()
+const url = await VersionCheck.getStoreUrl()
+const urlUS = await VersionCheck.getStoreUrl({ countryCode: 'US' })
 Linking.openURL(url)
 ```
 
-### `getLatestVersion()`
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `countryCode` | `string` | device country | 2-letter ISO country code (iOS only, ignored on Android) |
+
+### `VersionCheck.getLatestVersion(options?)`
 
 Fetches the latest version of this app available in the store. Queries the iTunes API on iOS and the Play Store on Android.
 
 ```ts
-const latest = await getLatestVersion() // "1.3.0"
+const latest = await VersionCheck.getLatestVersion() // "1.3.0"
+const latestUS = await VersionCheck.getLatestVersion({ countryCode: 'US' })
 ```
 
-### `needsUpdate(options?)`
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `countryCode` | `string` | device country | 2-letter ISO country code (iOS only, ignored on Android) |
+
+### `VersionCheck.needsUpdate(options?)`
 
 Checks whether an app update is available using semantic version comparison.
 
 ```ts
 // Any version increase
-if (await needsUpdate()) {
-  const url = await getStoreUrl()
+if (await VersionCheck.needsUpdate()) {
+  const url = await VersionCheck.getStoreUrl()
   Linking.openURL(url)
 }
 
 // Only prompt for major updates (1.x → 2.x)
-if (await needsUpdate({ level: 'major' })) {
+if (await VersionCheck.needsUpdate({ level: 'major' })) {
   // ...
 }
 ```
@@ -97,16 +97,14 @@ if (await needsUpdate({ level: 'major' })) {
 - `"minor"` — returns `true` for major or minor bumps
 - `"patch"` — returns `true` for any version increase (default)
 
-### `compareVersions(v1, v2)`
+### `VersionCheck.compareVersions(v1, v2)`
 
-Compare two semver strings. Returns `-1`, `0`, or `1`.
+Compare two semantic version strings. Returns `-1` (first is older), `0` (equal), or `1` (first is newer).
 
 ```ts
-import { compareVersions } from 'react-native-nitro-version-check'
-
-compareVersions('1.0.0', '1.0.1') // -1
-compareVersions('2.0.0', '2.0.0') //  0
-compareVersions('3.0.0', '2.9.9') //  1
+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
 ```
 
 ## Types

docs/docs/api-reference.md

@@ -34,28 +34,28 @@ Benchmarked against [`react-native-version-check`](https://github.com/kimxogus/r
 First, [install the package](/docs/installation).
 
 ```ts
-import {
-  VersionCheck,
-  getCountry,
-  getStoreUrl,
-  getLatestVersion,
-  needsUpdate,
-} from 'react-native-nitro-version-check'
-
-// Sync properties — no await needed
+import { VersionCheck } from 'react-native-nitro-version-check'
+
+// Direct access
 console.log(VersionCheck.version)       // "1.2.0"
 console.log(VersionCheck.buildNumber)   // "42"
 console.log(VersionCheck.packageName)   // "com.example.app"
 console.log(VersionCheck.installSource) // "appstore" | "testflight" | "playstore" | undefined
-console.log(getCountry())              // "US"
+console.log(VersionCheck.getCountry())  // "US"
+
+// Or destructure properties
+const { version, buildNumber, packageName, installSource } = VersionCheck
 
 // Async operations
-const url    = await getStoreUrl()       // App Store / Play Store URL
-const latest = await getLatestVersion()  // "1.3.0"
+const url    = await VersionCheck.getStoreUrl()       // App Store / Play Store URL
+const latest = await VersionCheck.getLatestVersion()  // "1.3.0" (uses device country)
+
+// Specify a different region for version lookup (iOS only)
+const latestUS = await VersionCheck.getLatestVersion({ countryCode: 'US' })
 
 // Check for updates
-if (await needsUpdate()) {
-  Linking.openURL(await getStoreUrl())
+if (await VersionCheck.needsUpdate()) {
+  Linking.openURL(await VersionCheck.getStoreUrl())
 }
 ```
 

docs/docs/getting-started.md

@@ -61,11 +61,11 @@ const update = await VersionCheck.needUpdate()
 // diff-remove
 if (update.isNeeded) { ... }
 // diff-add
-if (await needsUpdate()) { ... }
+if (await VersionCheck.needsUpdate()) { ... }
 
 // Granular update level (new!)
 // diff-add
-if (await needsUpdate({ level: 'major' })) { ... }
+if (await VersionCheck.needsUpdate({ level: 'major' })) { ... }
 ```
 
 ### Country code
@@ -74,7 +74,7 @@ if (await needsUpdate({ level: 'major' })) { ... }
 // diff-remove
 const country = await VersionCheck.getCountry()
 // diff-add
-const country = getCountry() // sync!
+const country = VersionCheck.getCountry() // sync!
 ```
 
 ## 4. New features
@@ -85,6 +85,7 @@ These are new and have no equivalent in the old library:
 |---------|-----|
 | Install source detection | `VersionCheck.installSource` |
 | Granular update levels | `needsUpdate({ level: 'major' })` |
+| Region-specific version lookups | `getLatestVersion({ countryCode: 'US' })` |
 | Version comparison utility | `compareVersions(v1, v2)` |
 
 ## 5. Rebuild