@forthtilliath/expo-release-updates 0.4.7 → 0.5.0

package/README.md

@@ -76,9 +76,13 @@ if (release && isUpdateAvailable(currentVersion, release.version)) {
 }
 ```
 
-### `fetchLatestRelease({ owner, repo, token? })`
+### `fetchLatestRelease({ owner, repo, token?, timeoutMs?, signal? })`
 
-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.
+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` for private repos, or to raise the API rate limit from 60 to 5000 requests/hour on public ones.
+
+The request gives up after `timeoutMs` (default `15000`) instead of hanging on a bad network, and can be cancelled with `signal` (an `AbortSignal`) — both also apply to `fetchReleaseHistory`.
+
+> **Security — the token ships inside your app.** Anything bundled in an APK can be extracted from it, so treat the token as public: use a [fine-grained token](https://github.com/settings/personal-access-tokens) with **read-only "Contents" access to this one repository** and nothing else, never a classic token or one with write scopes. For a public repo, prefer no token at all.
 
 ```ts
 const release = await fetchLatestRelease({ owner: "acme", repo: "app" });
@@ -87,9 +91,9 @@ if (release && isUpdateAvailable(currentVersion, release.version)) {
 }
 ```
 
-### `fetchReleaseHistory({ owner, repo, limit?, token? })`
+### `fetchReleaseHistory({ owner, repo, limit?, token?, timeoutMs?, signal? })`
 
-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.
+Fetches the most recent published releases (version, notes, publish date), most recent first — draft releases, visible with a token, are left out. `limit` defaults to `10` (clamped to GitHub's 1–100) — useful for a "release history" / "what's new" screen.
 
 ```ts
 const history = await fetchReleaseHistory({
@@ -102,20 +106,25 @@ const history = await fetchReleaseHistory({
 
 ### `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). 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).
+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 before installing — a mismatch deletes the file and throws instead. Publish the checksum alongside the release (e.g. in the release notes or a `.md5` asset) and read it yourself: `fetchLatestRelease` doesn't return it.
+
+What `expectedMd5` does and doesn't protect against:
+
+- ✅ a corrupted or truncated download;
+- ❌ a malicious release — whoever can publish the APK can publish its checksum too. The real safeguard there is Android itself: it refuses to install an update that isn't signed with the same key as the installed app. **Keep that signing key out of the repo and CI logs**, and restrict who can publish releases.
 
 ```ts
 await downloadAndInstallApk({
   apkUrl: release.apkUrl,
   fileName: "myapp-update.apk",
   onProgress: (fraction) => setProgress(fraction),
-  expectedMd5: release.apkMd5,
+  expectedMd5, // read from the release notes or a .md5 asset
 });
 ```
 
 ### `parseChangelogNotes(notes)`
 
-Parses a small subset of Markdown (`### heading`, `- item`, `**bold**`) commonly found in GitHub release notes into a list of typed blocks (`heading` / `item` / `text`, each with `bold`-aware segments), ready for a UI layer to render without a full Markdown dependency. Pair it with `@forthtilliath/react-native-kit`'s `ChangelogNotes` component to render the result directly.
+Parses a small subset of Markdown (`### heading`, `- item`, `**bold**`) commonly found in GitHub release notes into a list of typed blocks (`heading` / `item` / `text`, each with `bold`-aware segments), ready for a UI layer to render without a full Markdown dependency. Pair it with `@forthtilliath/expo-release-updates-ui`'s `ChangelogNotes` component to render the result directly.
 
 ```ts
 parseChangelogNotes("### Added\n- **Auto-backup**: saves every 5 minutes.");

package/dist/downloadAndInstallApk.d.ts

@@ -6,9 +6,10 @@ export interface DownloadAndInstallApkOptions {
     /**
      * 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.
+     * the file and rejects instead of installing it. This catches a corrupted
+     * or truncated download — not a malicious release: whoever can publish the
+     * APK can publish its checksum too. Android's own check that an update is
+     * signed with the same key as the installed app is what guards against that.
      */
     expectedMd5?: string;
 }

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;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"}
+{"version":3,"file":"downloadAndInstallApk.d.ts","sourceRoot":"","sources":["../src/downloadAndInstallApk.ts"],"names":[],"mappings":"AASA,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;;;;;;;OAOG;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

@@ -1,5 +1,10 @@
 import { File, Paths } from "expo-file-system";
 import * as IntentLauncher from "expo-intent-launcher";
+/**
+ * Android's `Intent.FLAG_GRANT_READ_URI_PERMISSION`: lets the package
+ * installer read the APK through its `content://` URI.
+ */
+const FLAG_GRANT_READ_URI_PERMISSION = 1;
 /**
  * Downloads an APK to the cache directory and triggers the Android
  * install-package intent. Android only — there is no equivalent flow on iOS,
@@ -30,7 +35,7 @@ export async function downloadAndInstallApk({ apkUrl, fileName, onProgress, expe
     }
     await IntentLauncher.startActivityAsync("android.intent.action.VIEW", {
         data: file.contentUri,
-        flags: 1,
+        flags: FLAG_GRANT_READ_URI_PERMISSION,
         type: "application/vnd.android.package-archive",
     });
 }

package/dist/githubReleases.d.ts

@@ -2,11 +2,19 @@ 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.
+     * A GitHub token, sent as a `Bearer` token. Required for private repos;
+     * also raises the API rate limit from 60 to 5000 requests/hour for public
+     * ones. **Anything bundled in an app can be extracted from the APK**: only
+     * ever ship a fine-grained, read-only token scoped to this one repo.
      */
     token?: string;
+    /**
+     * Gives up (rejects) if GitHub hasn't answered within this delay, instead
+     * of leaving the check hanging on a bad network. Defaults to 15 s.
+     */
+    timeoutMs?: number;
+    /** Aborts the request (e.g. when the screen that asked for it unmounts). */
+    signal?: AbortSignal;
 }
 export interface LatestRelease {
     version: string;
@@ -22,12 +30,13 @@ export interface ReleaseHistoryEntry {
  * Fetches the latest GitHub release for a repo, along with its `.apk` asset.
  *
  * @returns `null` if the latest release has no `.apk` asset attached.
- * @throws if the GitHub API request fails.
+ * @throws if the GitHub API request fails or times out.
  */
 export declare function fetchLatestRelease(ref: GithubRepoRef): Promise<LatestRelease | null>;
 /**
- * Fetches the most recent releases for a repo (version, notes, publish
- * date), most recent first — useful for a "release history" screen.
+ * Fetches the most recent published releases for a repo (version, notes,
+ * publish date), most recent first — useful for a "release history" screen.
+ * Draft releases (only visible with a token) are left out.
  */
 export declare function fetchReleaseHistory(ref: GithubRepoRef & {
     limit?: number;

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;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"}
+{"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;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;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;AAqED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAe/B;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,aAAa,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAchC"}

package/dist/githubReleases.js

@@ -1,3 +1,6 @@
+const DEFAULT_TIMEOUT_MS = 15_000;
+/** GitHub's own max for `per_page`. */
+const MAX_PER_PAGE = 100;
 function releasesUrl({ owner, repo }) {
     return `https://api.github.com/repos/${owner}/${repo}/releases`;
 }
@@ -7,19 +10,54 @@ function githubHeaders({ token }) {
         ...(token ? { Authorization: `Bearer ${token}` } : {}),
     };
 }
+/**
+ * GETs a GitHub API URL and parses its JSON body, rejecting on an error
+ * status or once `timeoutMs` has elapsed (body download included).
+ */
+async function fetchGithubJson(url, ref) {
+    const { timeoutMs = DEFAULT_TIMEOUT_MS, signal } = ref;
+    const controller = new AbortController();
+    // An object rather than `abort(reason)`: some React Native AbortController
+    // polyfills drop the reason.
+    const timeout = { expired: false };
+    const timer = setTimeout(() => {
+        timeout.expired = true;
+        controller.abort();
+    }, timeoutMs);
+    const abortFromCaller = () => {
+        controller.abort();
+    };
+    if (signal?.aborted)
+        controller.abort();
+    signal?.addEventListener("abort", abortFromCaller);
+    try {
+        const response = await fetch(url, {
+            headers: githubHeaders(ref),
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            throw new Error(`GitHub responded with ${String(response.status)}`);
+        return (await response.json());
+    }
+    catch (error) {
+        if (timeout.expired) {
+            throw new Error(`GitHub did not respond within ${String(timeoutMs)} ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abortFromCaller);
+    }
+}
 /**
  * Fetches the latest GitHub release for a repo, along with its `.apk` asset.
  *
  * @returns `null` if the latest release has no `.apk` asset attached.
- * @throws if the GitHub API request fails.
+ * @throws if the GitHub API request fails or times out.
  */
 export async function fetchLatestRelease(ref) {
-    const response = await fetch(`${releasesUrl(ref)}/latest`, {
-        headers: githubHeaders(ref),
-    });
-    if (!response.ok)
-        throw new Error(`GitHub responded with ${String(response.status)}`);
-    const data = (await response.json());
+    const data = await fetchGithubJson(`${releasesUrl(ref)}/latest`, ref);
     const apkAsset = (data.assets ?? []).find((asset) => asset.name.endsWith(".apk"));
     if (!apkAsset)
         return null;
@@ -30,16 +68,17 @@ export async function fetchLatestRelease(ref) {
     };
 }
 /**
- * Fetches the most recent releases for a repo (version, notes, publish
- * date), most recent first — useful for a "release history" screen.
+ * Fetches the most recent published releases for a repo (version, notes,
+ * publish date), most recent first — useful for a "release history" screen.
+ * Draft releases (only visible with a token) are left out.
  */
 export async function fetchReleaseHistory(ref) {
     const { limit = 10 } = ref;
-    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());
-    return data.map((release) => ({
+    const perPage = Math.min(Math.max(Math.trunc(limit), 1), MAX_PER_PAGE);
+    const data = await fetchGithubJson(`${releasesUrl(ref)}?per_page=${String(perPage)}`, ref);
+    return data
+        .filter((release) => !release.draft)
+        .map((release) => ({
         version: (release.tag_name ?? "").replace(/^v/, ""),
         notes: release.body ?? "",
         publishedAt: release.published_at ?? "",

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@forthtilliath/expo-release-updates",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "type": "module",
+  "sideEffects": false,
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -25,23 +26,23 @@
     "expo-intent-launcher": ">=12.0.0"
   },
   "dependencies": {
-    "@forthtilliath/ts-kit": "0.10.0"
+    "@forthtilliath/ts-kit": "^0.11.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/coverage-v8": "5.0.2",
     "eslint": "10.7.0",
     "expo-file-system": "~57.0.2",
     "expo-intent-launcher": "~57.0.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.10",
-    "@forthtilliath/eslint-config": "0.7.0",
-    "@forthtilliath/test-kit": "0.2.0",
+    "vitest": "^5.0.2",
+    "@forthtilliath/eslint-config": "0.8.0",
+    "@forthtilliath/test-kit": "0.3.0",
     "@forthtilliath/typescript-config": "0.1.1"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",
     "check-types": "tsc --noEmit",
-    "clean": "rm -rf dist",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "dev": "tsc --watch -p tsconfig.build.json",
     "build": "pnpm run clean && tsc -p tsconfig.build.json",
     "test": "vitest run",