expo-release 2.3.1 → 2.4.0

package/dist/operate.d.ts

@@ -1,4 +1,5 @@
 import type { DeployType, Operation, ReleasePlatform } from './args';
+import { type EASBuild } from './decide';
 import { type CommandRunner } from './run';
 export type { Operation };
 export type OperationInput = {
@@ -18,16 +19,22 @@ export type OperationInput = {
     updateExtraArgs?: string;
     exportSourceMaps?: boolean;
     dryRun?: boolean;
+    /** Called with the native build `eas build` queued, when it printed one. */
+    onQueuedBuild?: (build: EASBuild) => void;
     readPackageJson?: () => Promise<unknown>;
     hasSourceMaps?: () => Promise<boolean>;
 };
 export type OperationResult = 'skipped' | 'ota' | 'native-build' | 'recovery';
+/** Splits like a shell: whitespace separates, single or double quotes group. */
+export declare function splitArgs(value: string | undefined): string[];
 export declare function updateMessage(input: {
     profile: string;
     fingerprint?: string;
     message?: string;
 }): string;
 export declare function parseExpoSdkMajor(version: string | undefined): number | null;
+/** The Expo SDK major from package.json, or null when it is not a version. */
+export declare function readExpoSdkMajor(readPackageJson?: () => Promise<unknown>): Promise<number | null>;
 export declare function requireEnvironmentIfNeeded(input: Pick<OperationInput, 'environment' | 'readPackageJson'>): Promise<void>;
 export declare function operateRelease(input: OperationInput, commandRunner?: CommandRunner): Promise<OperationResult>;
-export declare function writeOperateGitHubOutput(result: OperationResult): Promise<void>;
+export declare function writeOperateGitHubOutput(result: OperationResult, queuedBuild?: EASBuild): Promise<void>;

package/dist/run.d.ts

@@ -1,17 +1,57 @@
 export type CommandRunner = (command: string[]) => Promise<string>;
+/**
+ * The app's own eas-cli (node_modules/.bin, searched up to the repository
+ * root) wins over PATH: its lockfile pins the version. `EAS_BIN` wins over both.
+ */
 export declare function easCommand(...args: string[]): string[];
+/** `node_modules/.bin/<name>` from the working directory up to the repository root. */
+export declare function localBin(name: string): string | null;
+/** A failed command. `tail` holds its last non-empty output lines. */
+export declare class CommandError extends Error {
+    readonly tail: string[];
+    constructor(message: string, tail: string[]);
+}
+/** Runs a command for its stdout. stderr streams to the log. */
 export declare function runCaptured(command: string[]): Promise<string>;
+/** Like runCaptured, but prints nothing: for checks that quote the error. */
+export declare function runSilent(command: string[]): Promise<string>;
+/** Runs a command with its output in the log. Resolves its stdout. */
+export declare function runInherited(command: string[]): Promise<string>;
 export declare function describeFailure(command: string[], exitCode: number, output: {
     stderr: string;
     stdout: string;
 }): string;
-export declare function runInherited(command: string[]): Promise<string>;
+/**
+ * Parses the last JSON document in `output`. `preamble` is whatever came
+ * before it: eas-cli prints warnings to stdout before it switches to JSON-only
+ * output, for example when `npx expo config` failed and it fell back.
+ */
+export declare function parseJsonDocument(output: string): {
+    value: unknown;
+    preamble: string;
+};
+/** Parses JSON output, logging any text printed before it. */
 export declare function parseJson(output: string): unknown;
 export declare function getRecord(value: unknown, context: string): Record<string, unknown>;
 export declare function parseFingerprintHash(output: string): string;
 export declare function quoteCommand(command: string[]): string;
 export declare function dryRunCommand(command: string[]): void;
+export type Stage = 'doctor' | 'diff' | 'fingerprint' | 'build list' | 'errored build' | 'fingerprint diff' | 'native build' | 'ota export' | 'ota update' | 'pre-update' | 'post-update' | 'recovery';
+/** A failed release step: what ran, and the last lines it printed. */
+export declare class StageError extends Error {
+    readonly stage: Stage;
+    readonly tail: string[];
+    constructor(stage: Stage, message: string, tail?: string[]);
+}
+/** Runs one release step, logs how long it took, and names it on failure. */
+export declare function stage<T>(name: Stage, run: () => Promise<T>): Promise<T>;
+/**
+ * The fingerprint fails when eas-cli printed anything before its JSON: that
+ * means the app config did not load and eas-cli fell back to its bundled
+ * `@expo/config`, whose fingerprint may not be the one EAS builds with.
+ * `explainConfig` runs `expo config` to surface the real error.
+ */
 export declare function generateFingerprint(input: {
     platform: string;
     profile: string;
-}, commandRunner: CommandRunner): Promise<string>;
+}, commandRunner: CommandRunner, explainConfig?: () => Promise<string>): Promise<string>;

package/dist/runtime/index.d.ts

@@ -1,3 +1,3 @@
 export { ErrorBoundary, type ErrorBoundaryFallbackProps, type ErrorBoundaryProps } from './error-boundary';
-export { checkForOTAUpdate, type ReloadApp, type UseOTAUpdatesOptions, useOTAUpdates } from './ota';
+export { checkForOTAUpdate, getReleaseInfo, type ReleaseInfo, type ReloadApp, type UseOTAUpdatesOptions, useOTAUpdates } from './ota';
 export { createPushNotifications, type KeyValueStorage, type NotificationListeners, type PushNotifications, type PushNotificationsOptions, type UsePushNotificationsOptions, usePushNotifications } from './push';

package/dist/runtime/index.js

@@ -21,29 +21,76 @@ class ErrorBoundary extends Component {
 // src/runtime/ota.ts
 import * as Updates from "expo-updates";
 import { useEffect, useRef } from "react";
-async function checkForOTAUpdate(onUpdateReady) {
+import { AppState } from "react-native";
+function getReleaseInfo() {
+  return {
+    updateId: Updates.updateId ?? null,
+    runtimeVersion: Updates.runtimeVersion ?? null,
+    channel: Updates.channel ?? null,
+    createdAt: Updates.createdAt ?? null,
+    isEmbeddedLaunch: Updates.isEmbeddedLaunch === true
+  };
+}
+async function downloadUpdate() {
   const update = await Updates.checkForUpdateAsync();
   if (!update.isAvailable)
-    return false;
+    return null;
   const result = await Updates.fetchUpdateAsync();
   if (!result.isNew)
+    return null;
+  const id = result.manifest?.id;
+  return typeof id === "string" ? id : "";
+}
+async function checkForOTAUpdate(onUpdateReady) {
+  if (await downloadUpdate() === null)
     return false;
   onUpdateReady(() => Updates.reloadAsync());
   return true;
 }
 function useOTAUpdates(onUpdateReady, options = {}) {
   const {
-    enabled = Updates.isEnabled && !(typeof __DEV__ !== "undefined" && __DEV__)
+    enabled = Updates.isEnabled && !(typeof __DEV__ !== "undefined" && __DEV__),
+    recheckOnForeground
   } = options;
   const callbacks = useRef({ onUpdateReady, onError: options.onError });
   callbacks.current = { onUpdateReady, onError: options.onError };
-  const checked = useRef(false);
+  const state = useRef({
+    checked: false,
+    running: false,
+    lastCheck: 0,
+    readyId: null
+  });
   useEffect(() => {
-    if (!enabled || checked.current)
+    if (!enabled)
+      return;
+    const check = () => {
+      const current = state.current;
+      if (current.running)
+        return;
+      current.running = true;
+      current.lastCheck = Date.now();
+      downloadUpdate().then((id) => {
+        if (id === null || id !== "" && id === current.readyId)
+          return;
+        current.readyId = id;
+        callbacks.current.onUpdateReady(() => Updates.reloadAsync());
+      }).catch((error) => (callbacks.current.onError ?? ((e) => console.warn("OTA update check failed", e)))(error)).finally(() => {
+        current.running = false;
+      });
+    };
+    if (!state.current.checked) {
+      state.current.checked = true;
+      check();
+    }
+    if (recheckOnForeground === undefined)
       return;
-    checked.current = true;
-    checkForOTAUpdate((reload) => callbacks.current.onUpdateReady(reload)).catch((error) => callbacks.current.onError?.(error));
-  }, [enabled]);
+    const subscription = AppState.addEventListener("change", (next) => {
+      if (next === "active" && Date.now() - state.current.lastCheck >= recheckOnForeground * 60000) {
+        check();
+      }
+    });
+    return () => subscription.remove();
+  }, [enabled, recheckOnForeground]);
 }
 // src/runtime/push.ts
 import * as Device from "expo-device";
@@ -68,12 +115,19 @@ function createPushNotifications(options) {
       shouldSetBadge: false
     }
   });
-  Notifications.setNotificationChannelAsync("default", options.androidChannel ?? {
+  function setAndroidChannel(channel = {
     name: "Default",
     importance: Notifications.AndroidImportance.HIGH,
     vibrationPattern: [0, 250, 250, 250]
-  }).catch((error) => onError("Failed to create the notification channel", error));
+  }) {
+    return Notifications.setNotificationChannelAsync("default", channel).then(() => {
+      return;
+    }).catch((error) => onError("Failed to create the notification channel", error));
+  }
+  setAndroidChannel(options.androidChannel);
   let pendingPrompt = null;
+  const deliveredResponses = new Set;
+  const responseKey = (response) => `${response.notification?.request?.identifier}:${response.notification?.date}:${response.actionIdentifier}`;
   const getPermissionStatus = () => Notifications.getPermissionsAsync();
   async function read(key) {
     try {
@@ -163,6 +217,7 @@ function createPushNotifications(options) {
     requestPermissions,
     getPushToken,
     syncToken,
+    setAndroidChannel,
     prompt() {
       pendingPrompt ??= runPrompt().catch((error) => {
         onError("Failed to prompt for notifications", error);
@@ -185,14 +240,18 @@ function createPushNotifications(options) {
     listen({ onReceived, onResponse } = {}) {
       const refresh = (devicePushToken) => refreshToken(devicePushToken).catch((error) => onError("Failed to refresh the push token", error));
       refresh();
+      const deliver = onResponse && ((response) => {
+        deliveredResponses.add(responseKey(response));
+        onResponse(response);
+      });
       const subscriptions = [
         Notifications.addPushTokenListener(refresh),
         onReceived && Notifications.addNotificationReceivedListener(onReceived),
-        onResponse && Notifications.addNotificationResponseReceivedListener(onResponse)
+        deliver && Notifications.addNotificationResponseReceivedListener(deliver)
       ];
-      const launchResponse = onResponse ? Notifications.getLastNotificationResponse() : null;
-      if (launchResponse)
-        onResponse?.(launchResponse);
+      const launchResponse = deliver ? Notifications.getLastNotificationResponse() : null;
+      if (launchResponse && !deliveredResponses.has(responseKey(launchResponse)))
+        deliver?.(launchResponse);
       return () => {
         for (const subscription of subscriptions)
           subscription?.remove();
@@ -254,6 +313,7 @@ export {
   ErrorBoundary,
   checkForOTAUpdate,
   createPushNotifications,
+  getReleaseInfo,
   useOTAUpdates,
   usePushNotifications
 };

package/dist/runtime/ota.d.ts

@@ -1,5 +1,17 @@
 /** Restarts the app on the downloaded update. */
 export type ReloadApp = () => Promise<void>;
+/** Which release is running, for crash reports and a version screen. */
+export interface ReleaseInfo {
+    /** The running EAS update; null for the build's embedded bundle and in Expo Go. */
+    updateId: string | null;
+    runtimeVersion: string | null;
+    channel: string | null;
+    /** When the running update (or the embedded bundle) was published. */
+    createdAt: Date | null;
+    isEmbeddedLaunch: boolean;
+}
+/** The running release, read from expo-updates. Safe in Expo Go and development. */
+export declare function getReleaseInfo(): ReleaseInfo;
 /**
  * Checks for an EAS update and downloads it. Calls `onUpdateReady` once a new
  * update is on disk; show a "Restart" prompt there and call `reload` to apply.
@@ -9,11 +21,19 @@ export declare function checkForOTAUpdate(onUpdateReady: (reload: ReloadApp) =>
 export interface UseOTAUpdatesOptions {
     /** Defaults to off in development and wherever expo-updates is disabled (Expo Go). */
     enabled?: boolean;
-    /** A failed check is retried on the next launch; defaults to ignoring it. */
+    /**
+     * Check again when the app returns to the foreground, at most once per this
+     * many minutes. Off by default: an app kept open for days then gets a fix
+     * only after the OS kills it.
+     */
+    recheckOnForeground?: number;
+    /** A failed check is retried on the next launch or foreground. Defaults to console.warn. */
     onError?: (error: unknown) => void;
 }
 /**
- * Checks for an update once per mount. The callbacks are read through refs, so
- * an unstable toast function never re-runs the check or stacks prompts.
+ * Checks for an update once per mount, and on foreground with
+ * `recheckOnForeground`. `onUpdateReady` runs once per downloaded update. The
+ * callbacks are read through refs, so an unstable toast function never re-runs
+ * the check or stacks prompts.
  */
 export declare function useOTAUpdates(onUpdateReady: (reload: ReloadApp) => void, options?: UseOTAUpdatesOptions): void;

package/dist/runtime/push.d.ts

@@ -19,7 +19,10 @@ export interface PushNotificationsOptions {
     onError?: (message: string, error: unknown) => void;
     /** Defaults to what expo-notifications reads from the app config. */
     projectId?: string;
-    /** Android channel `default`, needed for heads-up notifications. */
+    /**
+     * Android channel `default`, needed for heads-up notifications. Call
+     * `setAndroidChannel` again when its texts depend on the locale.
+     */
     androidChannel?: Notifications.NotificationChannelInput;
     /** How notifications show while the app is in the foreground. */
     foregroundBehavior?: Notifications.NotificationBehavior;
@@ -29,7 +32,10 @@ export interface PushNotificationsOptions {
 }
 export interface NotificationListeners {
     onReceived?: (notification: Notifications.Notification) => void;
-    /** Also called with the response that launched the app, if any. */
+    /**
+     * Also called with the response that launched the app, if any. Each
+     * response is delivered once per app start, however often `listen` runs.
+     */
     onResponse?: (response: Notifications.NotificationResponse) => void;
 }
 export type PushNotifications = ReturnType<typeof createPushNotifications>;
@@ -43,6 +49,8 @@ export declare function createPushNotifications(options: PushNotificationsOption
     requestPermissions: () => Promise<boolean>;
     getPushToken: (devicePushToken?: Notifications.DevicePushToken) => Promise<string | null>;
     syncToken: () => Promise<boolean>;
+    /** Recreates the Android `default` channel, for example after a locale change. */
+    setAndroidChannel: (channel?: Notifications.NotificationChannelInput) => Promise<void | undefined>;
     /**
      * Asks for push once per install (after sign-in, say), then registers the
      * token. Never throws; concurrent calls share one dialog.
@@ -50,7 +58,11 @@ export declare function createPushNotifications(options: PushNotificationsOption
     prompt(): Promise<boolean>;
     /** Turns push on from settings. Resolves whether it is on. */
     enable(): Promise<boolean>;
-    /** Removes this device's token from your backend. */
+    /**
+     * Removes this device's token from your backend, and stops `listen` from
+     * re-registering it. Rejects when `registerDevice(null)` does, so a
+     * settings screen can show the failure; catch it on sign-out.
+     */
     disable(): Promise<void>;
     /**
      * Subscribes to notifications and keeps the registered token current: on

package/dist/source-maps.d.ts

@@ -1,5 +1,6 @@
 import type { ReleasePlatform } from './args';
 export declare const SOURCE_MAP_OUTPUT_DIR = "dist";
+/** `EXPO_BIN`, else the app's own expo CLI, else `bunx expo`. */
 export declare function expoCommand(...args: string[]): string[];
 export declare function sourceMapExportCommand(platform: ReleasePlatform): string[];
 export declare function sourceMapUpdateArgs(): string[];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "expo-release",
-	"version": "2.3.1",
+	"version": "2.4.0",
 	"description": "Fingerprint-driven Expo EAS release: OTA update or native store build, plus app runtime helpers",
 	"type": "module",
 	"module": "./dist/index.js",
@@ -58,14 +58,15 @@
 		"verify:package": "node scripts/verify-package.mjs"
 	},
 	"dependencies": {
-		"hanzio": "^3.1.0",
+		"hanzio": "^3.4.0",
 		"zod": "^4.3.6"
 	},
 	"peerDependencies": {
 		"expo-device": ">=55",
 		"expo-notifications": ">=55",
 		"expo-updates": ">=55",
-		"react": ">=19"
+		"react": ">=19",
+		"react-native": ">=0.79"
 	},
 	"peerDependenciesMeta": {
 		"expo-device": {
@@ -79,6 +80,9 @@
 		},
 		"react": {
 			"optional": true
+		},
+		"react-native": {
+			"optional": true
 		}
 	},
 	"devDependencies": {

package/src/args.ts

@@ -1,11 +1,12 @@
 import type { CommandContext } from 'hanzio/cli'
 import { z } from 'zod'
+import type { BuildProfile } from './eas-json'
 
 export const DEFAULT_IMPACT_PATHS = ['apps/expo/'] as const
 
 export type ReleasePlatform = 'ios' | 'android'
 
-export type CommandName = 'release' | 'decide' | 'operate'
+export type CommandName = 'release' | 'decide' | 'operate' | 'doctor'
 
 export type Operation =
 	| 'deploy'
@@ -48,10 +49,16 @@ const text = (env: string) =>
 		.optional()
 		.meta({ env: `EXPO_RELEASE_${env}` })
 
+// hanzio/cli skips blank env values but keeps padding (`platform: |` in YAML adds a newline).
+const trimmed = <T extends z.ZodType>(schema: T) =>
+	z.preprocess(
+		(value) => (typeof value === 'string' ? value.trim() : value),
+		schema
+	)
+
 // `--auto-submit false` takes a value, so these are not boolean switches.
 const trueFalse = (env: string, fallback: 'true' | 'false') =>
-	z
-		.enum(['true', 'false'])
+	trimmed(z.enum(['true', 'false']))
 		.default(fallback)
 		.transform((value) => value === 'true')
 		.meta({ env: `EXPO_RELEASE_${env}` })
@@ -65,13 +72,12 @@ export const releaseFlags = z
 			.meta({ env: 'EXPO_RELEASE_PROFILE' })
 			.describe('EAS build profile, also the default update channel'),
 		base: text('BASE').describe(
-			'Git base SHA for the impact diff (falls back to GITHUB_EVENT_BEFORE)'
-		),
-		head: text('HEAD').describe(
-			'Git head SHA for the impact diff (falls back to GITHUB_SHA)'
+			'Git base SHA for the impact diff (default: the merge base on a pull request, else github.event.before)'
 		),
-		platform: z
-			.enum(['ios', 'android'])
+		head: text('HEAD')
+			.meta({ env: ['EXPO_RELEASE_HEAD', 'GITHUB_SHA'] })
+			.describe('Git head SHA for the impact diff'),
+		platform: trimmed(z.enum(['ios', 'android']))
 			.default('ios')
 			.meta({ env: 'EXPO_RELEASE_PLATFORM' })
 			.describe('Native platform'),
@@ -95,27 +101,27 @@ export const releaseFlags = z
 		ignoreExpoImpact: trueFalse('IGNORE_EXPO_IMPACT', 'false').describe(
 			'Check the fingerprint even when no impact path changed'
 		),
-		operation: z
-			.enum([
+		operation: trimmed(
+			z.enum([
 				'deploy',
 				'force-native',
 				'retry-ota',
 				'republish',
 				'rollback-embedded'
 			])
+		)
 			.default('deploy')
 			.meta({ env: 'EXPO_RELEASE_OPERATION' })
 			.describe('What to run'),
-		deployType: z
-			.enum(['none', 'ota', 'native'])
+		deployType: trimmed(z.enum(['none', 'ota', 'native']))
 			.default('none')
 			.meta({ env: 'EXPO_RELEASE_DEPLOY_TYPE' })
 			.describe('Decision type for operate'),
 		channel: text('CHANNEL').describe(
-			'EAS Update channel (default: the profile)'
+			'EAS Update channel (default: the eas.json profile channel, else the profile name)'
 		),
 		environment: text('ENVIRONMENT').describe(
-			'EAS environment for eas update (required for Expo SDK 55+)'
+			'EAS environment for eas update (required for Expo SDK 55+, where it defaults to the eas.json profile environment)'
 		),
 		autoSubmit: trueFalse('AUTO_SUBMIT', 'true').describe(
 			'Pass --auto-submit on native builds'
@@ -141,7 +147,14 @@ export const releaseFlags = z
 			'Fingerprint hash to use instead of generating one'
 		),
 		dryRun: z
-			.boolean()
+			.preprocess(
+				// hanzio/cli makes booleans of exact `true`/`false`; this takes padded ones too.
+				(value) =>
+					typeof value === 'string' && /^\s*(true|false)\s*$/.test(value)
+						? value.trim() === 'true'
+						: value,
+				z.boolean()
+			)
 			.meta({ env: 'EXPO_RELEASE_DRY_RUN' })
 			.describe('Print mutating EAS commands without running them')
 	})
@@ -156,16 +169,18 @@ export const releaseFlags = z
 
 export type ReleaseFlags = z.output<typeof releaseFlags>
 
+/** Flags win over the eas.json build profile, which wins over the profile name. */
 export function toReleaseOptions(
 	command: CommandName,
-	{ context: flags, env }: CommandContext<ReleaseFlags>
+	{ context: flags }: Pick<CommandContext<ReleaseFlags>, 'context'>,
+	buildProfile: BuildProfile | null = null
 ): ReleaseOptions {
+	const environment = flags.environment ?? buildProfile?.environment
 	return {
 		...flags,
 		command,
-		base: flags.base ?? env.GITHUB_EVENT_BEFORE,
-		head: flags.head ?? env.GITHUB_SHA,
-		channel: flags.channel ?? flags.profile
+		channel: flags.channel ?? buildProfile?.channel ?? flags.profile,
+		...(environment ? { environment } : {})
 	}
 }