@forthtilliath/expo-release-updates 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forthtilliath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @forthtilliath/expo-release-updates
+
+Self-update a sideloaded Android Expo app from its GitHub Releases: check the latest release, show a release history, download and trigger the install of a new APK. No backend needed — just a GitHub repo that publishes an `.apk` asset on each release.
+
+## Install
+
+```bash
+npm install @forthtilliath/expo-release-updates expo-file-system expo-intent-launcher
+```
+
+Or, from within this monorepo, as a workspace dependency:
+
+```json
+{
+  "dependencies": {
+    "@forthtilliath/expo-release-updates": "workspace:*"
+  }
+}
+```
+
+`expo-file-system` and `expo-intent-launcher` are peer dependencies — install them in the consuming app if not already present.
+
+## Usage
+
+Each function is its own module — import the file you need directly:
+
+```ts
+import { compareVersions } from "@forthtilliath/expo-release-updates/compareVersions";
+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";
+```
+
+### `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`.
+
+```ts
+compareVersions("1.2.0", "1.10.0"); // -1 (numeric, not lexicographic)
+compareVersions("2.0.0", "1.9.9"); // 1
+compareVersions("1.2.3", "1.2.3"); // 0
+```
+
+### `fetchLatestRelease({ owner, repo })`
+
+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.
+
+```ts
+const release = await fetchLatestRelease({ owner: "acme", repo: "app" });
+if (release && compareVersions(release.version, currentVersion) > 0) {
+  // an update is available: release.version, release.notes, release.apkUrl
+}
+```
+
+### `fetchReleaseHistory({ owner, repo, limit? })`
+
+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.
+
+```ts
+const history = await fetchReleaseHistory({
+  owner: "acme",
+  repo: "app",
+  limit: 5,
+});
+// [{ version: "1.11.0", notes: "### Added\n- ...", publishedAt: "2026-07-30T..." }, ...]
+```
+
+### `downloadAndInstallApk({ apkUrl, fileName, onProgress? })`
+
+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).
+
+```ts
+await downloadAndInstallApk({
+  apkUrl: release.apkUrl,
+  fileName: "myapp-update.apk",
+  onProgress: (fraction) => setProgress(fraction),
+});
+```
+
+### `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.
+
+```ts
+parseChangelogNotes("### Added\n- **Auto-backup**: saves every 5 minutes.");
+// [
+//   { type: "heading", text: "Added" },
+//   {
+//     type: "item",
+//     segments: [
+//       { text: "Auto-backup", bold: true },
+//       { text: ": saves every 5 minutes.", bold: false },
+//     ],
+//   },
+// ]
+```
+
+## Scripts
+
+```bash
+pnpm run dev            # tsc --watch -> dist/
+pnpm run build          # tsc -> dist/
+pnpm run check-types    # tsc --noEmit
+pnpm run lint           # eslint
+pnpm run test           # vitest run
+pnpm run test:watch     # vitest
+```
+
+Built to `dist/` (see the `exports` field in `package.json`), so run `pnpm run build` (or `dev`) after source changes for consumers to see them.

package/dist/compareVersions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compares two "x.y.z" version strings, segment by segment.
+ *
+ * @returns -1 if `a` < `b`, 0 if they're equal, 1 if `a` > `b`.
+ */
+export declare function compareVersions(a: string, b: string): number;
+//# sourceMappingURL=compareVersions.d.ts.map

package/dist/compareVersions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compareVersions.d.ts","sourceRoot":"","sources":["../src/compareVersions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAU5D"}

package/dist/compareVersions.js

@@ -0,0 +1,17 @@
+/**
+ * Compares two "x.y.z" version strings, segment by segment.
+ *
+ * @returns -1 if `a` < `b`, 0 if they're equal, 1 if `a` > `b`.
+ */
+export function compareVersions(a, b) {
+    const partsA = a.split(".").map(Number);
+    const partsB = b.split(".").map(Number);
+    const length = Math.max(partsA.length, partsB.length);
+    for (let i = 0; i < length; i++) {
+        const numA = partsA[i] ?? 0;
+        const numB = partsB[i] ?? 0;
+        if (numA !== numB)
+            return numA > numB ? 1 : -1;
+    }
+    return 0;
+}

package/dist/downloadAndInstallApk.d.ts

@@ -0,0 +1,13 @@
+export interface DownloadAndInstallApkOptions {
+    apkUrl: string;
+    /** Temp filename in the cache directory, e.g. "myapp-update.apk". */
+    fileName: string;
+    onProgress?: (fraction: number) => void;
+}
+/**
+ * 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.
+ */
+export declare function downloadAndInstallApk({ apkUrl, fileName, onProgress, }: DownloadAndInstallApkOptions): Promise<void>;
+//# sourceMappingURL=downloadAndInstallApk.d.ts.map

package/dist/downloadAndInstallApk.d.ts.map

@@ -0,0 +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"}

package/dist/downloadAndInstallApk.js

@@ -0,0 +1,26 @@
+import { File, Paths } from "expo-file-system";
+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.
+ */
+export async function downloadAndInstallApk({ apkUrl, fileName, onProgress, }) {
+    const destination = new File(Paths.cache, fileName);
+    if (destination.exists)
+        destination.delete();
+    const task = File.createDownloadTask(apkUrl, destination, {
+        onProgress: ({ bytesWritten, totalBytes }) => {
+            if (totalBytes > 0)
+                onProgress?.(bytesWritten / totalBytes);
+        },
+    });
+    const file = await task.downloadAsync();
+    if (!file)
+        throw new Error("The download failed.");
+    await IntentLauncher.startActivityAsync("android.intent.action.VIEW", {
+        data: file.contentUri,
+        flags: 1,
+        type: "application/vnd.android.package-archive",
+    });
+}

package/dist/githubReleases.d.ts

@@ -0,0 +1,29 @@
+export interface GithubRepoRef {
+    owner: string;
+    repo: string;
+}
+export interface LatestRelease {
+    version: string;
+    notes: string;
+    apkUrl: string;
+}
+export interface ReleaseHistoryEntry {
+    version: string;
+    notes: string;
+    publishedAt: string;
+}
+/**
+ * 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.
+ */
+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.
+ */
+export declare function fetchReleaseHistory(ref: GithubRepoRef & {
+    limit?: number;
+}): Promise<ReleaseHistoryEntry[]>;
+//# sourceMappingURL=githubReleases.d.ts.map

package/dist/githubReleases.d.ts.map

@@ -0,0 +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"}

package/dist/githubReleases.js

@@ -0,0 +1,43 @@
+function releasesUrl({ owner, repo }) {
+    return `https://api.github.com/repos/${owner}/${repo}/releases`;
+}
+/**
+ * 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.
+ */
+export async function fetchLatestRelease(ref) {
+    const response = await fetch(`${releasesUrl(ref)}/latest`, {
+        headers: { Accept: "application/vnd.github+json" },
+    });
+    if (!response.ok)
+        throw new Error(`GitHub responded with ${String(response.status)}`);
+    const data = (await response.json());
+    const apkAsset = (data.assets ?? []).find((asset) => asset.name.endsWith(".apk"));
+    if (!apkAsset)
+        return null;
+    return {
+        version: (data.tag_name ?? "").replace(/^v/, ""),
+        notes: data.body ?? "",
+        apkUrl: apkAsset.browser_download_url,
+    };
+}
+/**
+ * Fetches the most recent releases for a repo (version, notes, publish
+ * date), most recent first — useful for a "release history" screen.
+ */
+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" },
+    });
+    if (!response.ok)
+        throw new Error(`GitHub responded with ${String(response.status)}`);
+    const data = (await response.json());
+    return data.map((release) => ({
+        version: (release.tag_name ?? "").replace(/^v/, ""),
+        notes: release.body ?? "",
+        publishedAt: release.published_at ?? "",
+    }));
+}

package/dist/parseChangelogNotes.d.ts

@@ -0,0 +1,16 @@
+export interface ChangelogSegment {
+    text: string;
+    bold: boolean;
+}
+export type ChangelogBlock = {
+    type: "heading";
+    text: string;
+} | {
+    type: "item";
+    segments: ChangelogSegment[];
+} | {
+    type: "text";
+    segments: ChangelogSegment[];
+};
+export declare function parseChangelogNotes(notes: string): ChangelogBlock[];
+//# sourceMappingURL=parseChangelogNotes.d.ts.map

package/dist/parseChangelogNotes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseChangelogNotes.d.ts","sourceRoot":"","sources":["../src/parseChangelogNotes.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC;AAsBnD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,CAiBnE"}

package/dist/parseChangelogNotes.js

@@ -0,0 +1,43 @@
+// GitHub release notes are usually written in a small subset of Markdown
+// ("### Heading", "- item", "**bold**"). Rendered as-is in a plain <Text>,
+// the raw syntax shows up unstyled — this parser turns it into a small set
+// of typed blocks a UI layer can render (heading / bullet item / plain
+// text), without pulling in a full Markdown dependency for this narrow use
+// case.
+function parseInlineSegments(text) {
+    const segments = [];
+    const boldPattern = /\*\*(.+?)\*\*/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = boldPattern.exec(text)) !== null) {
+        if (match.index > lastIndex) {
+            segments.push({ text: text.slice(lastIndex, match.index), bold: false });
+        }
+        // The capture group is mandatory in the pattern, so it always matches —
+        // the `?? ""` fallback is only here to satisfy `noUncheckedIndexedAccess`.
+        segments.push({ text: match[1] ?? "", bold: true });
+        lastIndex = boldPattern.lastIndex;
+    }
+    if (lastIndex < text.length) {
+        segments.push({ text: text.slice(lastIndex), bold: false });
+    }
+    return segments;
+}
+export function parseChangelogNotes(notes) {
+    return notes
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        if (line.startsWith("### ")) {
+            return { type: "heading", text: line.slice(4).trim() };
+        }
+        if (line.startsWith("- ")) {
+            return {
+                type: "item",
+                segments: parseInlineSegments(line.slice(2).trim()),
+            };
+        }
+        return { type: "text", segments: parseInlineSegments(line) };
+    });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@forthtilliath/expo-release-updates",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Forthtilliath/turborepo.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",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./*": "./dist/*.js"
+  },
+  "peerDependencies": {
+    "expo-file-system": ">=54.0.0",
+    "expo-intent-launcher": ">=12.0.0"
+  },
+  "devDependencies": {
+    "eslint": "10.7.0",
+    "expo-file-system": "~57.0.1",
+    "expo-intent-launcher": "~57.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@forthtilliath/eslint-config": "0.0.0",
+    "@forthtilliath/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch -p tsconfig.build.json",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}