react-native-rollout-updater 1.0.0

package/README.md

@@ -0,0 +1,130 @@
+# react-native-rollout-updater
+
+Check a React Native app's version against the `version.json` published by
+[Rollout](../../README.md), and send the user to download the new APK. No native setup,
+no extra permissions — it just uses `fetch` and React Native's built-in `Linking`.
+
+## Install
+
+This package isn't published to npm — use it straight from this repo, either by copying the
+`react-native-rollout-updater` folder into your app, or by pointing your app's
+`package.json` at it:
+
+```json
+{
+  "dependencies": {
+    "react-native-rollout-updater": "file:../rollout/packages/react-native-rollout-updater"
+  }
+}
+```
+
+Then run `npm install` (or `yarn install`) in your app.
+
+## Find your `versionUrl`
+
+It's the **raw** URL of the `version.json` file in your GitHub repo:
+
+```
+https://raw.githubusercontent.com/<owner>/<repo>/<branch>/version.json
+```
+
+For example, for the `moohhiit/stamploop_apk` repo on `main`:
+
+```
+https://raw.githubusercontent.com/moohhiit/stamploop_apk/main/version.json
+```
+
+## Usage
+
+### Plain function
+
+```js
+import { checkForUpdate, openUpdate } from 'react-native-rollout-updater';
+import DeviceInfo from 'react-native-device-info'; // or however you track your app's version
+
+async function checkAppUpdate() {
+  const result = await checkForUpdate({
+    versionUrl: 'https://raw.githubusercontent.com/moohhiit/stamploop_apk/main/version.json',
+    currentVersion: DeviceInfo.getVersion(), // e.g. "2.4.5"
+  });
+
+  if (result.updateAvailable) {
+    // show your own UI with result.latestVersion / result.releaseNotes, then:
+    await openUpdate(result.apkUrl); // opens the APK URL — user downloads & installs it
+  }
+}
+```
+
+### React hook
+
+```jsx
+import { useUpdateChecker, openUpdate } from 'react-native-rollout-updater';
+import DeviceInfo from 'react-native-device-info';
+import { Alert } from 'react-native';
+
+function UpdateGate() {
+  const { loading, result } = useUpdateChecker({
+    versionUrl: 'https://raw.githubusercontent.com/moohhiit/stamploop_apk/main/version.json',
+    currentVersion: DeviceInfo.getVersion(),
+  });
+
+  useEffect(() => {
+    if (result?.updateAvailable) {
+      Alert.alert(
+        `Update available: v${result.latestVersion}`,
+        result.releaseNotes || 'A new version is available.',
+        [
+          { text: 'Later', style: 'cancel' },
+          { text: 'Update', onPress: () => openUpdate(result.apkUrl) },
+        ]
+      );
+    }
+  }, [result]);
+
+  return null;
+}
+```
+
+## API
+
+### `checkForUpdate(options)`
+
+| Option            | Required | Default          | Notes                                                        |
+|--------------------|----------|-------------------|----------------------------------------------------------------|
+| `versionUrl`       | yes      | —                 | Raw URL to `version.json`                                     |
+| `currentVersion`   | yes      | —                 | The app's currently running version                           |
+| `versionKey`       | no       | `"version"`       | JSON key for the version string                                |
+| `apkUrlKey`        | no       | `"apkUrl"`        | JSON key for the APK download URL                              |
+| `releaseNotesKey`  | no       | `"releaseNotes"`  | JSON key for the release notes                                 |
+| `bypassCache`      | no       | `true`            | Appends `?t=<timestamp>` since raw.githubusercontent.com is CDN-cached for a few minutes |
+
+Returns a promise resolving to:
+
+```ts
+{
+  updateAvailable: boolean,
+  currentVersion: string,
+  latestVersion: string | null,
+  apkUrl: string | null,
+  releaseNotes: string | string[] | null,
+  raw: object // the full parsed version.json
+}
+```
+
+### `openUpdate(apkUrl)`
+
+Opens the APK URL via `Linking.openURL`. The device's browser/downloader takes over from there;
+the user taps the downloaded file to install (Android will prompt to enable "install unknown
+apps" for that source the first time, same as any APK downloaded from a browser).
+
+### `useUpdateChecker(options, deps?)`
+
+Runs `checkForUpdate` on mount and returns `{ loading, result, error, recheck }`. Pass a `deps`
+array (like `useEffect`) if you want it to re-check when something changes; call `recheck()` to
+run it again manually.
+
+### `compareVersions(a, b)`
+
+Exported in case you want to compare versions yourself. Returns `1` if `a > b`, `-1` if `a < b`,
+`0` if equal. Compares dot-separated numeric segments (`"1.9.0"` < `"1.10.0"`), and tolerates a
+leading `v`.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "react-native-rollout-updater",
+  "version": "1.0.0",
+  "description": "Check a React Native app's version against a Rollout version.json and prompt an APK update.",
+  "main": "src/index.js",
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "react-native",
+    "apk",
+    "update",
+    "in-app-update",
+    "rollout"
+  ],
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "license": "UNLICENSED"
+}

package/src/checkForUpdate.js

@@ -0,0 +1,66 @@
+const { compareVersions } = require('./compareVersions');
+
+/**
+ * @typedef {Object} CheckForUpdateOptions
+ * @property {string} versionUrl - Raw URL to the version.json published by Rollout,
+ *   e.g. "https://raw.githubusercontent.com/<owner>/<repo>/<branch>/version.json".
+ * @property {string} currentVersion - The running app's version (e.g. from `react-native-device-info`
+ *   `DeviceInfo.getVersion()`, or your own constant).
+ * @property {string} [versionKey] - JSON key holding the version string. Defaults to "version".
+ * @property {string} [apkUrlKey] - JSON key holding the APK download URL. Defaults to "apkUrl".
+ * @property {string} [releaseNotesKey] - JSON key holding the release notes. Defaults to "releaseNotes".
+ * @property {boolean} [bypassCache] - Appends a cache-busting query param. Useful because
+ *   raw.githubusercontent.com is CDN-cached for a few minutes after a deploy. Defaults to true.
+ */
+
+/**
+ * @typedef {Object} UpdateCheckResult
+ * @property {boolean} updateAvailable
+ * @property {string} currentVersion
+ * @property {string|null} latestVersion
+ * @property {string|null} apkUrl
+ * @property {string|string[]|null} releaseNotes
+ * @property {Object} raw - The full parsed version.json.
+ */
+
+/**
+ * Fetches version.json and compares it against the app's current version.
+ * @param {CheckForUpdateOptions} options
+ * @returns {Promise<UpdateCheckResult>}
+ */
+async function checkForUpdate(options) {
+  const {
+    versionUrl,
+    currentVersion,
+    versionKey = 'version',
+    apkUrlKey = 'apkUrl',
+    releaseNotesKey = 'releaseNotes',
+    bypassCache = true
+  } = options || {};
+
+  if (!versionUrl) throw new Error('checkForUpdate: "versionUrl" is required.');
+  if (!currentVersion) throw new Error('checkForUpdate: "currentVersion" is required.');
+
+  const url = bypassCache
+    ? `${versionUrl}${versionUrl.includes('?') ? '&' : '?'}t=${Date.now()}`
+    : versionUrl;
+
+  const res = await fetch(url, { headers: { 'Cache-Control': 'no-cache' } });
+  if (!res.ok) throw new Error(`checkForUpdate: request failed with status ${res.status}`);
+  const raw = await res.json();
+
+  const latestVersion = raw[versionKey] || null;
+  const apkUrl = raw[apkUrlKey] || null;
+  const releaseNotes = raw[releaseNotesKey] || null;
+
+  return {
+    updateAvailable: latestVersion ? compareVersions(latestVersion, currentVersion) > 0 : false,
+    currentVersion,
+    latestVersion,
+    apkUrl,
+    releaseNotes,
+    raw
+  };
+}
+
+module.exports = { checkForUpdate };

package/src/compareVersions.js

@@ -0,0 +1,19 @@
+/**
+ * Compares two dot-separated version strings numerically, e.g. "1.9.0" vs "1.10.0".
+ * Returns 1 if a > b, -1 if a < b, 0 if equal. Non-numeric/missing parts count as 0.
+ */
+function compareVersions(a, b) {
+  const partsA = String(a || '0').replace(/^v/i, '').split('.');
+  const partsB = String(b || '0').replace(/^v/i, '').split('.');
+  const len = Math.max(partsA.length, partsB.length);
+
+  for (let i = 0; i < len; i++) {
+    const numA = parseInt(partsA[i], 10) || 0;
+    const numB = parseInt(partsB[i], 10) || 0;
+    if (numA > numB) return 1;
+    if (numA < numB) return -1;
+  }
+  return 0;
+}
+
+module.exports = { compareVersions };

package/src/index.js

@@ -0,0 +1,6 @@
+const { checkForUpdate } = require('./checkForUpdate');
+const { openUpdate } = require('./openUpdate');
+const { useUpdateChecker } = require('./useUpdateChecker');
+const { compareVersions } = require('./compareVersions');
+
+module.exports = { checkForUpdate, openUpdate, useUpdateChecker, compareVersions };

package/src/openUpdate.js

@@ -0,0 +1,15 @@
+const { Linking } = require('react-native');
+
+/**
+ * Opens the APK download URL with the system handler (browser/downloader).
+ * The user finishes the install manually — this requires no extra native setup.
+ * @param {string} apkUrl
+ */
+async function openUpdate(apkUrl) {
+  if (!apkUrl) throw new Error('openUpdate: "apkUrl" is required.');
+  const supported = await Linking.canOpenURL(apkUrl);
+  if (!supported) throw new Error(`openUpdate: cannot open URL "${apkUrl}"`);
+  await Linking.openURL(apkUrl);
+}
+
+module.exports = { openUpdate };

package/src/useUpdateChecker.js

@@ -0,0 +1,35 @@
+const { useEffect, useState, useCallback } = require('react');
+const { checkForUpdate } = require('./checkForUpdate');
+
+/**
+ * React hook that runs checkForUpdate on mount (and whenever `deps` change).
+ * @param {import('./checkForUpdate').CheckForUpdateOptions} options
+ * @param {any[]} [deps]
+ * @returns {{ loading: boolean, result: import('./checkForUpdate').UpdateCheckResult|null, error: Error|null, recheck: () => void }}
+ */
+function useUpdateChecker(options, deps = []) {
+  const [loading, setLoading] = useState(true);
+  const [result, setResult] = useState(null);
+  const [error, setError] = useState(null);
+  const [tick, setTick] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+
+    checkForUpdate(options)
+      .then((r) => { if (!cancelled) setResult(r); })
+      .catch((e) => { if (!cancelled) setError(e); })
+      .finally(() => { if (!cancelled) setLoading(false); });
+
+    return () => { cancelled = true; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tick, ...deps]);
+
+  const recheck = useCallback(() => setTick((t) => t + 1), []);
+
+  return { loading, result, error, recheck };
+}
+
+module.exports = { useUpdateChecker };