@rific/updater 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Deaton
+
+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,165 @@
+# @rific/updater
+
+OTA update hook for Expo apps. Silently stages updates in the background when the app is foregrounded, and exposes a manual `check()` for settings screens. No surprise restarts — the user always confirms before the app reloads.
+
+---
+
+## Install
+
+```sh
+npm install @rific/updater
+```
+
+**Peer dependencies:** `expo-updates`, `react`, `react-native`
+
+---
+
+## Usage
+
+### Basic
+
+```tsx
+import { useUpdater } from '@rific/updater'
+
+const { check, checking, updateReady } = useUpdater()
+```
+
+Call `check()` from a "Check for Updates" button. The `updateReady` flag goes `true` after a silent background fetch — use it to show a badge on your settings icon.
+
+### Settings screen
+
+```tsx
+const { check, checking, updateReady } = useUpdater({
+  onError: (msg) => toast(msg),
+})
+
+<MenuItem
+  title="Check for Update"
+  caption={`v${release.otaVersion}${updateReady ? ' — update ready' : ''}`}
+  loading={checking}
+  onPress={check}
+/>
+```
+
+### With a custom confirm dialog
+
+```tsx
+const { check, checking } = useUpdater({
+  onConfirm: async (manifest) => {
+    // return true to proceed with reload, false to cancel
+    return myCustomDialog(manifest)
+  },
+})
+```
+
+### Disable automatic foreground check
+
+```tsx
+const { check, checking } = useUpdater({ autoCheck: false })
+```
+
+---
+
+## API
+
+### `useUpdater(options?)`
+
+```ts
+interface UseUpdaterOptions {
+  autoCheck?: boolean                                    // default: true
+  onConfirm?: (manifest: UpdateManifest) => Promise<boolean>
+  onError?: (message: string) => void
+}
+
+interface UseUpdaterReturn {
+  check: () => Promise<void>
+  checking: boolean
+  updateReady: boolean
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `autoCheck` | `true` | Registers an `AppState` listener that silently fetches available updates whenever the app comes to the foreground. Disable for games or apps that want full manual control. |
+| `onConfirm` | — | Custom confirmation dialog. Receives the update manifest, must return `Promise<boolean>` — `true` to reload, `false` to cancel. Defaults to a native `Alert` showing the release date and metadata message. |
+| `onError` | — | Called with an error message string if `check()` throws. Defaults to `Alert.alert`. |
+
+| Return | Description |
+|--------|-------------|
+| `check()` | Manual update check. Shows a dev/web guard alert if unsupported. If a background fetch already staged an update, uses that manifest directly (no extra network call). Clears `updateReady` on completion regardless of whether the user confirmed. |
+| `checking` | `true` while `check()` is in flight. Safe to drive a loading spinner. Concurrent calls are ignored via a ref guard. |
+| `updateReady` | `true` after the background fetch successfully staged an update. Cleared when `check()` completes. Use to show a badge on a settings button. |
+
+---
+
+## How updates work
+
+**Automatic (foreground):** When `autoCheck` is `true`, the hook registers an `AppState` listener. Each time the app returns from background/inactive to active, it calls `checkForUpdateAsync()` + `fetchUpdateAsync()` silently. The downloaded bundle sits on disk — no prompt, no restart. The **next cold launch** automatically runs it.
+
+**Manual (`check()`):** Runs the full flow — check (or reuse staged manifest) → confirmation dialog → `reloadAsync()`. The user sees what was released and chooses whether to restart now.
+
+**Web / DEV:** Both are no-ops. `check()` shows an informational alert explaining why. The foreground listener is never registered.
+
+---
+
+## OTA version constant
+
+Each app maintains a local integer version displayed to users (separate from the semver app version). Bump it before pushing an OTA:
+
+```sh
+# from your app's root
+npx rific-bump-ota src/constants/release.ts
+```
+
+Or add to your app's `package.json`:
+
+```json
+"scripts": {
+  "update:bump": "rific-bump-ota src/constants/release.ts"
+}
+```
+
+The script:
+- Verifies git working directory is clean
+- Increments `otaVersion` in the target file
+- Auto-commits `"otaVersion N -> N+1"`
+
+File format expected (TypeScript or JS object literal):
+
+```ts
+export const release = {
+  otaVersion: 1
+}
+```
+
+The path argument defaults to `src/constants/release.ts` if omitted.
+
+---
+
+## Context / design notes
+
+- Named `@rific/updater` (not `expo-updater`) to avoid confusion with the `expo-updates` peer dependency
+- `check()` uses a ref guard (`checkingRef`) rather than the `checking` state to prevent concurrent calls — state batching means a second call could see stale `false` before the first render commits
+- `updateReady` and the staged manifest ref are cleared in `finally` so they reset on both confirm and cancel
+- `onConfirm` replaces the default `Alert` entirely — useful in apps that have their own dialog primitive (e.g. a `select()` utility or bottom sheet)
+- No Provider or context required — the hook is self-contained
+
+---
+
+## Consuming apps
+
+- **Lumber** (`../Lumber`) — account screen, shows version + update badge
+- **CashierFu-Utility** (`../CashierFu-Utility`) — settings modal, uses `@rific/toaster` for `onError`
+- Games (Setter, Hangman, Crumby, HexFleet, etc.) — use `autoCheck: true`, no manual check needed
+
+### Local development (yalc)
+
+```sh
+# in this repo
+yalc publish
+
+# in the consuming app
+yalc add @rific/updater
+```
+
+Use `yalc` not `npm link` — Metro doesn't resolve symlinks reliably.

package/dist/index.d.mts

@@ -0,0 +1,18 @@
+interface UpdateManifest {
+    createdAt: string;
+    metadata?: Record<string, string | undefined>;
+}
+
+interface UseUpdaterOptions {
+    autoCheck?: boolean;
+    onConfirm?: (manifest: UpdateManifest) => Promise<boolean>;
+    onError?: (message: string) => void;
+}
+interface UseUpdaterReturn {
+    check: () => Promise<void>;
+    checking: boolean;
+    updateReady: boolean;
+}
+declare const useUpdater: (options?: UseUpdaterOptions) => UseUpdaterReturn;
+
+export { type UpdateManifest, type UseUpdaterOptions, type UseUpdaterReturn, useUpdater };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+interface UpdateManifest {
+    createdAt: string;
+    metadata?: Record<string, string | undefined>;
+}
+
+interface UseUpdaterOptions {
+    autoCheck?: boolean;
+    onConfirm?: (manifest: UpdateManifest) => Promise<boolean>;
+    onError?: (message: string) => void;
+}
+interface UseUpdaterReturn {
+    check: () => Promise<void>;
+    checking: boolean;
+    updateReady: boolean;
+}
+declare const useUpdater: (options?: UseUpdaterOptions) => UseUpdaterReturn;
+
+export { type UpdateManifest, type UseUpdaterOptions, type UseUpdaterReturn, useUpdater };

package/dist/index.js

@@ -0,0 +1,121 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useUpdater: () => useUpdater
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useUpdater.ts
+var import_expo_updates2 = require("expo-updates");
+var import_react = require("react");
+var import_react_native2 = require("react-native");
+
+// src/checkForUpdate.ts
+var import_expo_updates = require("expo-updates");
+var checkForUpdate = async () => {
+  const { isAvailable } = await (0, import_expo_updates.checkForUpdateAsync)();
+  if (!isAvailable) return null;
+  const { manifest } = await (0, import_expo_updates.fetchUpdateAsync)();
+  return manifest ? manifest : null;
+};
+
+// src/getUpdateConfirmation.ts
+var import_react_native = require("react-native");
+var getUpdateConfirmation = (manifest) => {
+  const date = new Date(manifest.createdAt);
+  let info = `A new update was released on ${date.toLocaleDateString()} at ${date.toLocaleTimeString()}.`;
+  if (manifest.metadata?.message) info += `
+
+Message: ${manifest.metadata.message}.`;
+  info += "\n\nRestart app to update.";
+  return new Promise((resolve) => {
+    import_react_native.Alert.alert("Update available", info, [
+      { text: "Cancel", style: "cancel", onPress: () => resolve(false) },
+      { text: "Restart", onPress: () => resolve(true) }
+    ]);
+  });
+};
+
+// src/useUpdater.ts
+var isUnsupported = () => __DEV__ || import_react_native2.Platform.OS === "web";
+var useUpdater = (options = {}) => {
+  const { autoCheck = true, onConfirm, onError } = options;
+  const [checking, setChecking] = (0, import_react.useState)(false);
+  const [updateReady, setUpdateReady] = (0, import_react.useState)(false);
+  const checkingRef = (0, import_react.useRef)(false);
+  const appState = (0, import_react.useRef)(import_react_native2.AppState.currentState);
+  const stagedManifest = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    if (!autoCheck || isUnsupported()) return;
+    const subscription = import_react_native2.AppState.addEventListener("change", (nextState) => {
+      if (/inactive|background/.test(appState.current) && nextState === "active") {
+        checkForUpdate().then((manifest) => {
+          if (manifest) {
+            stagedManifest.current = manifest;
+            setUpdateReady(true);
+          }
+        }).catch(() => {
+        });
+      }
+      appState.current = nextState;
+    });
+    return () => subscription.remove();
+  }, [autoCheck]);
+  const check = async () => {
+    if (__DEV__) {
+      import_react_native2.Alert.alert("Updates unavailable", "Update checks are disabled in development mode.");
+      return;
+    }
+    if (import_react_native2.Platform.OS === "web") {
+      import_react_native2.Alert.alert("Updates unavailable", "Update checks are not supported on web.");
+      return;
+    }
+    if (checkingRef.current) return;
+    checkingRef.current = true;
+    setChecking(true);
+    try {
+      const manifest = stagedManifest.current ?? await checkForUpdate();
+      if (!manifest) {
+        import_react_native2.Alert.alert("No update", "You are on the most recent version.");
+        return;
+      }
+      const confirmFn = onConfirm ?? getUpdateConfirmation;
+      const confirmed = await confirmFn(manifest);
+      if (!confirmed) return;
+      await (0, import_expo_updates2.reloadAsync)();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Could not check for updates.";
+      if (onError) onError(message);
+      else import_react_native2.Alert.alert("Update error", message);
+    } finally {
+      stagedManifest.current = null;
+      setUpdateReady(false);
+      checkingRef.current = false;
+      setChecking(false);
+    }
+  };
+  return { check, checking, updateReady };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useUpdater
+});

package/dist/index.mjs

@@ -0,0 +1,94 @@
+// src/useUpdater.ts
+import { reloadAsync } from "expo-updates";
+import { useEffect, useRef, useState } from "react";
+import { Alert as Alert2, AppState, Platform } from "react-native";
+
+// src/checkForUpdate.ts
+import { checkForUpdateAsync, fetchUpdateAsync } from "expo-updates";
+var checkForUpdate = async () => {
+  const { isAvailable } = await checkForUpdateAsync();
+  if (!isAvailable) return null;
+  const { manifest } = await fetchUpdateAsync();
+  return manifest ? manifest : null;
+};
+
+// src/getUpdateConfirmation.ts
+import { Alert } from "react-native";
+var getUpdateConfirmation = (manifest) => {
+  const date = new Date(manifest.createdAt);
+  let info = `A new update was released on ${date.toLocaleDateString()} at ${date.toLocaleTimeString()}.`;
+  if (manifest.metadata?.message) info += `
+
+Message: ${manifest.metadata.message}.`;
+  info += "\n\nRestart app to update.";
+  return new Promise((resolve) => {
+    Alert.alert("Update available", info, [
+      { text: "Cancel", style: "cancel", onPress: () => resolve(false) },
+      { text: "Restart", onPress: () => resolve(true) }
+    ]);
+  });
+};
+
+// src/useUpdater.ts
+var isUnsupported = () => __DEV__ || Platform.OS === "web";
+var useUpdater = (options = {}) => {
+  const { autoCheck = true, onConfirm, onError } = options;
+  const [checking, setChecking] = useState(false);
+  const [updateReady, setUpdateReady] = useState(false);
+  const checkingRef = useRef(false);
+  const appState = useRef(AppState.currentState);
+  const stagedManifest = useRef(null);
+  useEffect(() => {
+    if (!autoCheck || isUnsupported()) return;
+    const subscription = AppState.addEventListener("change", (nextState) => {
+      if (/inactive|background/.test(appState.current) && nextState === "active") {
+        checkForUpdate().then((manifest) => {
+          if (manifest) {
+            stagedManifest.current = manifest;
+            setUpdateReady(true);
+          }
+        }).catch(() => {
+        });
+      }
+      appState.current = nextState;
+    });
+    return () => subscription.remove();
+  }, [autoCheck]);
+  const check = async () => {
+    if (__DEV__) {
+      Alert2.alert("Updates unavailable", "Update checks are disabled in development mode.");
+      return;
+    }
+    if (Platform.OS === "web") {
+      Alert2.alert("Updates unavailable", "Update checks are not supported on web.");
+      return;
+    }
+    if (checkingRef.current) return;
+    checkingRef.current = true;
+    setChecking(true);
+    try {
+      const manifest = stagedManifest.current ?? await checkForUpdate();
+      if (!manifest) {
+        Alert2.alert("No update", "You are on the most recent version.");
+        return;
+      }
+      const confirmFn = onConfirm ?? getUpdateConfirmation;
+      const confirmed = await confirmFn(manifest);
+      if (!confirmed) return;
+      await reloadAsync();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Could not check for updates.";
+      if (onError) onError(message);
+      else Alert2.alert("Update error", message);
+    } finally {
+      stagedManifest.current = null;
+      setUpdateReady(false);
+      checkingRef.current = false;
+      setChecking(false);
+    }
+  };
+  return { check, checking, updateReady };
+};
+export {
+  useUpdater
+};

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@rific/updater",
+  "version": "0.1.0",
+  "description": "OTA update hook for Expo apps — silent background fetch on foreground, manual check with confirmation dialog",
+  "keywords": [
+    "expo",
+    "expo-updates",
+    "ota",
+    "react-native",
+    "update"
+  ],
+  "homepage": "https://github.com/jayrdeaton/expo-updater#readme",
+  "bugs": {
+    "url": "https://github.com/jayrdeaton/expo-updater/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayrdeaton/expo-updater.git"
+  },
+  "license": "MIT",
+  "author": "Jay Deaton",
+  "sideEffects": false,
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "rific-bump-ota": "./scripts/bump-ota-version.mjs"
+  },
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "fix": "eslint --fix",
+    "lint": "eslint",
+    "prepublishOnly": "npm run build",
+    "release": "git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "test": "jest",
+    "test:watch": "jest --watchAll",
+    "typecheck": "tsc --noEmit",
+    "preversion": "npm run lint && npm test"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.0.0",
+    "@typescript-eslint/parser": "^8.59.3",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-package-json": "^1.0.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-react-native": "^5.0.0",
+    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "expo-updates": ">=0.25.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
+    "prettier": "^3.8.3",
+    "react": "^19.2.6",
+    "react-native": "^0.85.3",
+    "ts-jest": "^29.4.9",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.59.3"
+  },
+  "peerDependencies": {
+    "expo-updates": ">=0.25.0",
+    "react": ">=17.0.0",
+    "react-native": ">=0.70.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/bump-ota-version.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import { execSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const filePath = process.argv[2] ?? 'src/constants/release.ts'
+const configPath = path.resolve(process.cwd(), filePath)
+
+if (!fs.existsSync(configPath)) {
+  console.error(`File not found: ${configPath}`)
+  process.exit(1)
+}
+
+try {
+  const status = execSync('git status --porcelain').toString().trim()
+  if (status) {
+    console.error('Git working directory is not clean. Please commit or stash your changes first.')
+    process.exit(1)
+  }
+} catch (err) {
+  console.error('Failed to check git status:', err.message)
+  process.exit(1)
+}
+
+const source = fs.readFileSync(configPath, 'utf8')
+const match = source.match(/(otaVersion:\s*)(\d+)/)
+
+if (!match) {
+  console.error(`Could not find otaVersion in ${filePath}`)
+  process.exit(1)
+}
+
+const current = Number.parseInt(match[2], 10)
+const next = current + 1
+const updated = source.replace(/(otaVersion:\s*)(\d+)/, `$1${next}`)
+
+fs.writeFileSync(configPath, updated)
+
+try {
+  execSync(`git add ${configPath}`)
+  execSync(`git commit -m "otaVersion ${current} -> ${next}"`)
+} catch (err) {
+  console.error('Auto-commit failed:', err.message)
+}
+
+console.log(`otaVersion bumped: ${current} -> ${next}`)