@forthtilliath/expo-release-updates 0.2.0 → 0.4.0

package/README.md

@@ -22,18 +22,40 @@ Or, from within this monorepo, as a workspace dependency:
 
 ## Usage
 
-Each function is its own module — import the file you need directly:
+Each function is its own module — import the file you need directly, or use
+the barrel to pull everything from a single import:
 
 ```ts
 import { compareVersions } from "@forthtilliath/expo-release-updates/compareVersions";
+import { isUpdateAvailable } from "@forthtilliath/expo-release-updates/isUpdateAvailable";
 import {
   fetchLatestRelease,
   fetchReleaseHistory,
 } from "@forthtilliath/expo-release-updates/githubReleases";
 import { downloadAndInstallApk } from "@forthtilliath/expo-release-updates/downloadAndInstallApk";
 import { parseChangelogNotes } from "@forthtilliath/expo-release-updates/parseChangelogNotes";
+
+// Or, everything at once:
+import {
+  compareVersions,
+  isUpdateAvailable,
+  fetchLatestRelease,
+  fetchReleaseHistory,
+  downloadAndInstallApk,
+  parseChangelogNotes,
+} from "@forthtilliath/expo-release-updates";
 ```
 
+**Avoid the barrel under Jest (or any other CommonJS `require` consumer).**
+`export * from` re-exports are evaluated eagerly on `require()` — unlike
+Metro's ESM bundling, there's no tree-shaking to skip the unused ones.
+Requiring the barrel from _any_ file, even one that only wants
+`compareVersions`, pulls in `downloadAndInstallApk`'s module graph too,
+including native-module imports (`expo-file-system`, `expo-intent-launcher`)
+that don't exist in a Jest environment — this throws at require time, not
+just at runtime for unused code. Deep imports only ever load the one module
+you asked for, so they don't have this problem in any environment.
+
 ### `compareVersions(a, b)`
 
 Compares two `"x.y.z"` version strings, segment by segment. Returns `-1` if `a < b`, `0` if equal, `1` if `a > b`.
@@ -44,18 +66,28 @@ compareVersions("2.0.0", "1.9.9"); // 1
 compareVersions("1.2.3", "1.2.3"); // 0
 ```
 
-### `fetchLatestRelease({ owner, repo })`
+### `isUpdateAvailable(currentVersion, latestVersion)`
+
+Named wrapper around `compareVersions` for the common "should I show the update prompt?" check — reads as intent instead of a bare `compareVersions(a, b) > 0` repeated at every call site.
+
+```ts
+if (release && isUpdateAvailable(currentVersion, release.version)) {
+  // an update is available
+}
+```
+
+### `fetchLatestRelease({ owner, repo, token? })`
 
-Fetches the latest GitHub release and its `.apk` asset. Returns `null` if the latest release has no `.apk` attached; throws if the GitHub API request fails.
+Fetches the latest GitHub release and its `.apk` asset. Returns `null` if the latest release has no `.apk` attached; throws if the GitHub API request fails. Pass `token` (a GitHub personal access token or `GITHUB_TOKEN`) for private repos, or to raise the API rate limit from 60 to 5000 requests/hour on public ones.
 
 ```ts
 const release = await fetchLatestRelease({ owner: "acme", repo: "app" });
-if (release && compareVersions(release.version, currentVersion) > 0) {
+if (release && isUpdateAvailable(currentVersion, release.version)) {
   // an update is available: release.version, release.notes, release.apkUrl
 }
 ```
 
-### `fetchReleaseHistory({ owner, repo, limit? })`
+### `fetchReleaseHistory({ owner, repo, limit?, token? })`
 
 Fetches the most recent releases (version, notes, publish date), most recent first. `limit` defaults to `10` — useful for a "release history" / "what's new" screen.
 
@@ -68,15 +100,16 @@ const history = await fetchReleaseHistory({
 // [{ version: "1.11.0", notes: "### Added\n- ...", publishedAt: "2026-07-30T..." }, ...]
 ```
 
-### `downloadAndInstallApk({ apkUrl, fileName, onProgress? })`
+### `downloadAndInstallApk({ apkUrl, fileName, onProgress?, expectedMd5? })`
 
-Downloads an APK to the app's cache directory and triggers the Android install-package intent. **Android only** — there is no iOS equivalent (sideloading isn't possible there).
+Downloads an APK to the app's cache directory and triggers the Android install-package intent. **Android only** — there is no iOS equivalent (sideloading isn't possible there). Pass `expectedMd5` to verify the downloaded file's integrity before installing — a mismatch deletes the file and throws instead. GitHub Releases has no built-in signature check the way an app store does, so this is the standard safeguard against a corrupted or tampered download; publish the checksum alongside the release (e.g. in the release notes or a `.md5` asset).
 
 ```ts
 await downloadAndInstallApk({
   apkUrl: release.apkUrl,
   fileName: "myapp-update.apk",
   onProgress: (fraction) => setProgress(fraction),
+  expectedMd5: release.apkMd5,
 });
 ```
 

package/dist/downloadAndInstallApk.d.ts

@@ -3,11 +3,22 @@ export interface DownloadAndInstallApkOptions {
     /** Temp filename in the cache directory, e.g. "myapp-update.apk". */
     fileName: string;
     onProgress?: (fraction: number) => void;
+    /**
+     * MD5 checksum the downloaded file is expected to match (case-insensitive),
+     * e.g. one published alongside the release. When set, a mismatch deletes
+     * the file and rejects instead of installing it — standard integrity check
+     * before running a sideloaded binary, since GitHub Releases has no
+     * built-in signature verification the way an app store does.
+     */
+    expectedMd5?: string;
 }
 /**
  * Downloads an APK to the cache directory and triggers the Android
  * install-package intent. Android only — there is no equivalent flow on iOS,
  * which doesn't allow installing a downloaded package outside the App Store.
+ *
+ * @throws if the download fails, or if `expectedMd5` is set and doesn't
+ * match the downloaded file.
  */
-export declare function downloadAndInstallApk({ apkUrl, fileName, onProgress, }: DownloadAndInstallApkOptions): Promise<void>;
+export declare function downloadAndInstallApk({ apkUrl, fileName, onProgress, expectedMd5, }: DownloadAndInstallApkOptions): Promise<void>;
 //# sourceMappingURL=downloadAndInstallApk.d.ts.map

package/dist/downloadAndInstallApk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"downloadAndInstallApk.d.ts","sourceRoot":"","sources":["../src/downloadAndInstallApk.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,MAAM,EACN,QAAQ,EACR,UAAU,GACX,EAAE,4BAA4B,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB9C"}
+{"version":3,"file":"downloadAndInstallApk.d.ts","sourceRoot":"","sources":["../src/downloadAndInstallApk.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,MAAM,EACN,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,EAAE,4BAA4B,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B9C"}

package/dist/downloadAndInstallApk.js

@@ -4,8 +4,11 @@ import * as IntentLauncher from "expo-intent-launcher";
  * Downloads an APK to the cache directory and triggers the Android
  * install-package intent. Android only — there is no equivalent flow on iOS,
  * which doesn't allow installing a downloaded package outside the App Store.
+ *
+ * @throws if the download fails, or if `expectedMd5` is set and doesn't
+ * match the downloaded file.
  */
-export async function downloadAndInstallApk({ apkUrl, fileName, onProgress, }) {
+export async function downloadAndInstallApk({ apkUrl, fileName, onProgress, expectedMd5, }) {
     const destination = new File(Paths.cache, fileName);
     if (destination.exists)
         destination.delete();
@@ -18,6 +21,13 @@ export async function downloadAndInstallApk({ apkUrl, fileName, onProgress, }) {
     const file = await task.downloadAsync();
     if (!file)
         throw new Error("The download failed.");
+    if (expectedMd5) {
+        const actualMd5 = file.info({ md5: true }).md5;
+        if (actualMd5?.toLowerCase() !== expectedMd5.toLowerCase()) {
+            file.delete();
+            throw new Error(`APK checksum mismatch: expected ${expectedMd5}, got ${actualMd5 ?? "none"}.`);
+        }
+    }
     await IntentLauncher.startActivityAsync("android.intent.action.VIEW", {
         data: file.contentUri,
         flags: 1,

package/dist/githubReleases.d.ts

@@ -1,6 +1,12 @@
 export interface GithubRepoRef {
     owner: string;
     repo: string;
+    /**
+     * A GitHub personal access token (or `GITHUB_TOKEN` in CI), sent as a
+     * `Bearer` token. Required for private repos; also raises the API rate
+     * limit from 60 to 5000 requests/hour for public ones.
+     */
+    token?: string;
 }
 export interface LatestRelease {
     version: string;

package/dist/githubReleases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"githubReleases.d.ts","sourceRoot":"","sources":["../src/githubReleases.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAkBD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAkB/B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,aAAa,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAiBhC"}
+{"version":3,"file":"githubReleases.d.ts","sourceRoot":"","sources":["../src/githubReleases.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAyBD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAkB/B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,aAAa,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAehC"}

package/dist/githubReleases.js

@@ -1,6 +1,12 @@
 function releasesUrl({ owner, repo }) {
     return `https://api.github.com/repos/${owner}/${repo}/releases`;
 }
+function githubHeaders({ token }) {
+    return {
+        Accept: "application/vnd.github+json",
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    };
+}
 /**
  * Fetches the latest GitHub release for a repo, along with its `.apk` asset.
  *
@@ -9,7 +15,7 @@ function releasesUrl({ owner, repo }) {
  */
 export async function fetchLatestRelease(ref) {
     const response = await fetch(`${releasesUrl(ref)}/latest`, {
-        headers: { Accept: "application/vnd.github+json" },
+        headers: githubHeaders(ref),
     });
     if (!response.ok)
         throw new Error(`GitHub responded with ${String(response.status)}`);
@@ -29,9 +35,7 @@ export async function fetchLatestRelease(ref) {
  */
 export async function fetchReleaseHistory(ref) {
     const { limit = 10 } = ref;
-    const response = await fetch(`${releasesUrl(ref)}?per_page=${String(limit)}`, {
-        headers: { Accept: "application/vnd.github+json" },
-    });
+    const response = await fetch(`${releasesUrl(ref)}?per_page=${String(limit)}`, { headers: githubHeaders(ref) });
     if (!response.ok)
         throw new Error(`GitHub responded with ${String(response.status)}`);
     const data = (await response.json());

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./compareVersions.js";
+export * from "./downloadAndInstallApk.js";
+export * from "./githubReleases.js";
+export * from "./isUpdateAvailable.js";
+export * from "./parseChangelogNotes.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// Convenience barrel re-exporting everything below one import path. Deep
+// imports (`@forthtilliath/expo-release-updates/downloadAndInstallApk`, etc.)
+// remain the recommended default for apps that want to avoid pulling in the
+// Expo peer deps they don't have installed — see the README.
+export * from "./compareVersions.js";
+export * from "./downloadAndInstallApk.js";
+export * from "./githubReleases.js";
+export * from "./isUpdateAvailable.js";
+export * from "./parseChangelogNotes.js";

package/dist/isUpdateAvailable.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Whether `latestVersion` is strictly newer than `currentVersion`.
+ *
+ * Thin, named wrapper around `compareVersions` for the common "should I show
+ * the update prompt?" check, so call sites read as intent rather than a bare
+ * `compareVersions(a, b) > 0` comparison repeated at every call site.
+ *
+ * @example
+ * isUpdateAvailable("1.2.0", "1.10.0"); // true
+ * isUpdateAvailable("1.2.0", "1.2.0"); // false
+ */
+export declare function isUpdateAvailable(currentVersion: string, latestVersion: string): boolean;
+//# sourceMappingURL=isUpdateAvailable.d.ts.map

package/dist/isUpdateAvailable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isUpdateAvailable.d.ts","sourceRoot":"","sources":["../src/isUpdateAvailable.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,GACpB,OAAO,CAET"}

package/dist/isUpdateAvailable.js

@@ -0,0 +1,15 @@
+import { compareVersions } from "./compareVersions.js";
+/**
+ * Whether `latestVersion` is strictly newer than `currentVersion`.
+ *
+ * Thin, named wrapper around `compareVersions` for the common "should I show
+ * the update prompt?" check, so call sites read as intent rather than a bare
+ * `compareVersions(a, b) > 0` comparison repeated at every call site.
+ *
+ * @example
+ * isUpdateAvailable("1.2.0", "1.10.0"); // true
+ * isUpdateAvailable("1.2.0", "1.2.0"); // false
+ */
+export function isUpdateAvailable(currentVersion, latestVersion) {
+    return compareVersions(latestVersion, currentVersion) > 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/expo-release-updates",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -8,15 +8,16 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Forthtilliath/turborepo.git",
+    "url": "https://github.com/Forthtilliath/forthtilliath-packages.git",
     "directory": "packages/expo-release-updates"
   },
-  "homepage": "https://github.com/Forthtilliath/turborepo/tree/main/packages/expo-release-updates#readme",
-  "bugs": "https://github.com/Forthtilliath/turborepo/issues",
+  "homepage": "https://github.com/Forthtilliath/forthtilliath-packages/tree/main/packages/expo-release-updates#readme",
+  "bugs": "https://github.com/Forthtilliath/forthtilliath-packages/issues",
   "files": [
     "dist"
   ],
   "exports": {
+    ".": "./dist/index.js",
     "./*": "./dist/*.js"
   },
   "peerDependencies": {
@@ -25,11 +26,11 @@
   },
   "devDependencies": {
     "eslint": "10.7.0",
-    "expo-file-system": "~57.0.1",
+    "expo-file-system": "~57.0.2",
     "expo-intent-launcher": "~57.0.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@forthtilliath/eslint-config": "0.0.0",
+    "@forthtilliath/eslint-config": "0.4.2",
     "@forthtilliath/typescript-config": "0.0.0"
   },
   "scripts": {