@bravemobile/react-native-code-push 13.2.0 → 13.3.0

package/README.md

@@ -501,6 +501,8 @@ npx code-push release --framework expo --binary-version 1.0.0 --app-version 1.0.
 > `--app-version` should be greater than `--binary-version` (SemVer comparison).
 
 - `--rollout`: The rollout percentage for the update. (0~100, inclusive)
+- `--minimum-background-duration`: The number of seconds the app must have been in the background before this update is applied on resume, for `ON_NEXT_RESUME` and `ON_NEXT_SUSPEND` installs only. (whole seconds, 0 or greater)
+  - The value set on the release takes precedence over the `minimumBackgroundDuration` passed to `sync`, and `0` applies the update on the next resume.
 
 #### `update-history`
 
@@ -509,6 +511,8 @@ Update the release history for a specific CodePush update.
 - Use the `--mandatory` option to make the update as mandatory or optional.
 - Use the `--rollout` option to change the rollout percentage of the update. (0~100, inclusive)
   - If the rollout percentage is reduced, users who fall outside the new target will have their rollout canceled and rollback to the previous latest version.
+- Use the `--minimum-background-duration` option to change how many seconds the app must have been in the background before the update is applied on resume, for `ON_NEXT_RESUME` and `ON_NEXT_SUSPEND` installs only. (whole seconds, 0 or greater)
+  - It can be lowered after a release has gone out - setting it to `0`, for example, applies the update on the next resume instead of waiting.
 
 **Example:**
 - Rollback the CodePush update `1.0.1` (targeting the binary app version `1.0.0`).

package/cli/commands/createHistoryCommand/createReleaseHistory.test.ts

@@ -96,8 +96,8 @@ describe("staging the release history a config is handed", () => {
         };
 
         await Promise.all([
-            updateReleaseHistory("1.0.1", BINARY_VERSION, getReleaseHistory, setReleaseHistory, "ios", "RN0840", undefined, false, undefined),
-            updateReleaseHistory("1.0.1", BINARY_VERSION, getReleaseHistory, setReleaseHistory, "android", "RN0840", undefined, false, undefined),
+            updateReleaseHistory("1.0.1", BINARY_VERSION, getReleaseHistory, setReleaseHistory, "ios", "RN0840", undefined, false, undefined, undefined),
+            updateReleaseHistory("1.0.1", BINARY_VERSION, getReleaseHistory, setReleaseHistory, "android", "RN0840", undefined, false, undefined, undefined),
         ]);
 
         expect(staged.ios).toContain("ios-url");

package/cli/commands/releaseCommand/addToReleaseHistory.ts

@@ -15,6 +15,7 @@ export async function addToReleaseHistory(
     enable: boolean,
     rollout: number | undefined,
     diffPackages: Record<string, string> | undefined,
+    minimumBackgroundDuration: number | undefined,
 ): Promise<void> {
     const releaseHistory = await getReleaseHistory(binaryVersion, platform, identifier);
 
@@ -49,6 +50,11 @@ export async function addToReleaseHistory(
         newReleaseHistory[appVersion].rollout = rollout;
     }
 
+    // An entry without it leaves the wait to the sync option, so 0 has to be written.
+    if (typeof minimumBackgroundDuration === 'number') {
+        newReleaseHistory[appVersion].minimumBackgroundDuration = minimumBackgroundDuration;
+    }
+
     try {
         await stageReleaseHistoryFile(binaryVersion, newReleaseHistory, platform, (jsonFilePath) =>
             setReleaseHistory(binaryVersion, jsonFilePath, newReleaseHistory, platform, identifier));

package/cli/commands/releaseCommand/index.test.ts

@@ -32,6 +32,7 @@ const ARG_INDEX = {
     onOversizedPatch: 20,
     bundleDownloader: 21,
     diffBaseCount: 22,
+    minimumBackgroundDuration: 23,
 } as const;
 
 /**
@@ -147,4 +148,32 @@ describe("release command options", () => {
         const { release } = await import("./release.js");
         expect(jest.mocked(release)).not.toHaveBeenCalled();
     });
+
+    it("passes the chosen minimum background duration through to the release", async () => {
+        const args = await runReleaseCommand(['-b', '1.0.0', '-v', '1.0.1', '--minimum-background-duration', '600']);
+
+        expect(args[ARG_INDEX.minimumBackgroundDuration]).toBe(600);
+    });
+
+    it("leaves the minimum background duration unset when the option is not given, so the sync option decides", async () => {
+        const args = await runReleaseCommand(['-b', '1.0.0', '-v', '1.0.1']);
+
+        expect(args[ARG_INDEX.minimumBackgroundDuration]).toBeUndefined();
+    });
+
+    it.each([
+        ['is negative', '-1'],
+        ['is not a number at all', 'soon'],
+    ])("rejects a minimum background duration that %s", async (_caseName, value) => {
+        jest.spyOn(console, 'error').mockImplementation(() => {});
+        jest.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+            throw new Error(`process.exit(${code})`);
+        }) as never);
+
+        await expect(parseReleaseCommand(['-b', '1.0.0', '-v', '1.0.1', '--minimum-background-duration', value]))
+            .rejects.toThrow('process.exit(1)');
+
+        const { release } = await import("./release.js");
+        expect(jest.mocked(release)).not.toHaveBeenCalled();
+    });
 });

package/cli/commands/releaseCommand/index.ts

@@ -31,6 +31,7 @@ type Options = {
     binaryBundlePath?: string;
     onOversizedPatch: OversizedPatchPolicy;
     diffBaseCount: number;
+    minimumBackgroundDuration?: number;
 }
 
 program.command('release')
@@ -57,6 +58,7 @@ program.command('release')
         .choices(OVERSIZED_PATCH_POLICIES)
         .default(DEFAULT_OVERSIZED_PATCH_POLICY))
     .option('--diff-base-count <number>', 'how many recent releases to build asset diff archives against (0 disables). Requires `bundleDownloader` in the config file.', parseDecimalInt, DEFAULT_DIFF_BASE_COUNT)
+    .option('--minimum-background-duration <seconds>', 'seconds the app must have been in the background before this update is applied on resume. Overrides the minimumBackgroundDuration sync option.', parseDecimalInt)
     .action(async (options: Options) => {
         const config = findAndReadConfigFile(process.cwd(), options.config);
 
@@ -70,6 +72,12 @@ program.command('release')
             process.exit(1);
         }
 
+        if (options.minimumBackgroundDuration !== undefined
+            && (!Number.isInteger(options.minimumBackgroundDuration) || options.minimumBackgroundDuration < 0)) {
+            console.error('--minimum-background-duration must be a whole number of seconds, 0 or greater.');
+            process.exit(1);
+        }
+
         if (options.hashCalc && !options.skipBundle) {
             console.error('--hash-calc option can be used only when --skip-bundle is set to true.');
             process.exit(1);
@@ -102,6 +110,7 @@ program.command('release')
             options.onOversizedPatch,
             config.bundleDownloader,
             options.diffBaseCount,
+            options.minimumBackgroundDuration,
         )
 
         console.log('🚀 Release completed.')

package/cli/commands/releaseCommand/release.test.ts

@@ -142,6 +142,7 @@ type ReleaseOverrides = {
     releaseHistory?: ReleaseHistoryInterface;
     bundleDownloader?: CliConfigInterface['bundleDownloader'];
     diffBaseCount?: number;
+    minimumBackgroundDuration?: number;
 };
 
 async function runRelease(staged: StagedBundle, overrides: ReleaseOverrides = {}) {
@@ -176,6 +177,7 @@ async function runRelease(staged: StagedBundle, overrides: ReleaseOverrides = {}
         overrides.onOversizedPatch,
         overrides.bundleDownloader,
         overrides.diffBaseCount,
+        overrides.minimumBackgroundDuration,
     );
 
     return { uploads, releaseHistories: history.saved, uploadCountsWhenHistorySaved };
@@ -829,3 +831,29 @@ describe("release with asset diff bases", () => {
         expect(path.basename(uploads[0].filePath)).toBe(staged.bundleFileName);
     });
 });
+
+describe("release --minimum-background-duration", () => {
+    it("records the background wait on the release it publishes", async () => {
+        const staged = await stageBundleOutput("minimum-background-duration");
+
+        const { releaseHistories } = await runRelease(staged, { minimumBackgroundDuration: 600 });
+
+        expect(releaseHistories[0][APP_VERSION].minimumBackgroundDuration).toBe(600);
+    });
+
+    it("releases a background wait of zero seconds as zero, not as an unset option", async () => {
+        const staged = await stageBundleOutput("zero-minimum-background-duration");
+
+        const { releaseHistories } = await runRelease(staged, { minimumBackgroundDuration: 0 });
+
+        expect(releaseHistories[0][APP_VERSION].minimumBackgroundDuration).toBe(0);
+    });
+
+    it("leaves the release saying nothing about the background wait when the option is not given", async () => {
+        const staged = await stageBundleOutput("no-minimum-background-duration");
+
+        const { releaseHistories } = await runRelease(staged);
+
+        expect(releaseHistories[0][APP_VERSION]).not.toHaveProperty('minimumBackgroundDuration');
+    });
+});

package/cli/commands/releaseCommand/release.ts

@@ -49,6 +49,7 @@ export async function release(
     onOversizedPatch: OversizedPatchPolicy = DEFAULT_OVERSIZED_PATCH_POLICY,
     bundleDownloader?: CliConfigInterface['bundleDownloader'],
     diffBaseCount: number = DEFAULT_DIFF_BASE_COUNT,
+    minimumBackgroundDuration?: number,
 ): Promise<void> {
     if (baseBundlePath) {
         // Checked before the bundler runs, so the wrong base bundle costs a second rather
@@ -167,6 +168,7 @@ export async function release(
         enable,
         rollout,
         Object.keys(diffPackages).length > 0 ? diffPackages : undefined,
+        minimumBackgroundDuration,
     )
 
     if (!skipCleanup) {

package/cli/commands/updateHistoryCommand/index.test.ts

@@ -0,0 +1,129 @@
+import fs from "fs";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it, jest } from "@jest/globals";
+import type { CliConfigInterface, ReleaseHistoryInterface } from "../../../typings/react-native-code-push.d.ts";
+
+/**
+ * Checks the command definition against the entry it saves. Everything this command does
+ * ends up in the release history the config is handed, so an option that never reaches it
+ * leaves the release exactly as it was - which the command still reports as a success.
+ */
+
+const BINARY_VERSION = '1.0.0';
+const APP_VERSION = '1.0.1';
+
+let mockConfig: CliConfigInterface;
+
+jest.mock("../../utils/fsUtils.js", () => ({
+    findAndReadConfigFile: () => mockConfig,
+}));
+
+/**
+ * Puts one released version in the config's history and records every history it is
+ * handed back, so a case can read the entry as the consumer would store it.
+ */
+function stageReleaseHistory(): ReleaseHistoryInterface[] {
+    const releaseHistory: ReleaseHistoryInterface = {
+        [APP_VERSION]: {
+            enabled: true,
+            mandatory: false,
+            downloadUrl: 'https://cdn.example.com/bundle',
+            packageHash: 'a3f1c0',
+        },
+    };
+    const saved: ReleaseHistoryInterface[] = [];
+
+    mockConfig = {
+        bundleUploader: async () => ({ downloadUrl: 'https://cdn.example.com/bundle' }),
+        getReleaseHistory: async () => releaseHistory,
+        // The command edits the history in place, so what it saved is copied out here.
+        setReleaseHistory: async (_binaryVersion, _jsonFilePath, releaseInfo) => {
+            saved.push(structuredClone(releaseInfo));
+        },
+    };
+
+    return saved;
+}
+
+/**
+ * Parses an `update-history` invocation against the real command definition. Commander is
+ * asked to throw instead of exiting, and to keep its diagnostics to itself, so a rejected
+ * option can be asserted on without ending the worker or the output.
+ */
+async function parseUpdateHistoryCommand(args: string[]): Promise<void> {
+    const { program } = await import("commander");
+    await import("./index.js");
+
+    const updateHistoryCommand = program.commands.find((command) => command.name() === 'update-history');
+    updateHistoryCommand?.exitOverride();
+    updateHistoryCommand?.configureOutput({ writeErr: () => {} });
+
+    await program.parseAsync(['update-history', ...args], { from: 'user' });
+}
+
+async function runUpdateHistoryCommand(args: string[]): Promise<void> {
+    await parseUpdateHistoryCommand(['-b', BINARY_VERSION, '-v', APP_VERSION, ...args]);
+}
+
+let saved: ReleaseHistoryInterface[];
+
+beforeEach(() => {
+    jest.resetModules();
+    saved = stageReleaseHistory();
+    jest.spyOn(console, 'log').mockImplementation(() => {});
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    jest.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+        throw new Error(`process.exit(${code})`);
+    }) as never);
+});
+
+afterEach(() => {
+    jest.restoreAllMocks();
+    // The command writes its JSON under the directory it was invoked in.
+    fs.rmSync(path.resolve(process.cwd(), "codepush-release-history"), { recursive: true, force: true });
+});
+
+describe("update-history command options", () => {
+    it("lowers the background wait of a release that is already out to zero seconds", async () => {
+        await runUpdateHistoryCommand(['--minimum-background-duration', '0']);
+
+        expect(saved).toHaveLength(1);
+        expect(saved[0][APP_VERSION].minimumBackgroundDuration).toBe(0);
+    });
+
+    it("leaves the entry saying nothing about the background wait when only --enable is given", async () => {
+        await runUpdateHistoryCommand(['--enable', 'false']);
+
+        expect(saved[0][APP_VERSION].enabled).toBe(false);
+        expect(saved[0][APP_VERSION]).not.toHaveProperty('minimumBackgroundDuration');
+    });
+
+    it("saves the rollout percentage when --rollout is the only option given", async () => {
+        await runUpdateHistoryCommand(['--rollout', '50']);
+
+        expect(saved[0][APP_VERSION].rollout).toBe(50);
+    });
+
+    it("exits without saving anything when no option says what to change", async () => {
+        await expect(runUpdateHistoryCommand([])).rejects.toThrow('process.exit(1)');
+
+        expect(saved).toHaveLength(0);
+    });
+
+    it("rejects a negative background wait and saves nothing", async () => {
+        await expect(runUpdateHistoryCommand(['--minimum-background-duration', '-1']))
+            .rejects.toThrow('process.exit(1)');
+
+        expect(saved).toHaveLength(0);
+    });
+
+    it.each([
+        ['a percentage above 100', '150'],
+        ['a percentage that is not a number', 'abc'],
+    ])("rejects %s and saves nothing", async (_scenario, rollout) => {
+        await expect(runUpdateHistoryCommand(['--rollout', rollout]))
+            .rejects.toThrow('process.exit(1)');
+
+        expect(saved).toHaveLength(0);
+    });
+});

package/cli/commands/updateHistoryCommand/index.ts

@@ -12,6 +12,7 @@ type Options = {
     mandatory?: boolean;
     enable?: boolean;
     rollout?: number;
+    minimumBackgroundDuration?: number;
 }
 
 program.command('update-history')
@@ -24,14 +25,32 @@ program.command('update-history')
     .option('-m, --mandatory <bool>', 'make the release to be mandatory', parseBoolean, undefined)
     .option('-e, --enable <bool>', 'make the release to be enabled', parseBoolean, undefined)
     .option('--rollout <number>', 'rollout percentage (0-100)', parseFloat, undefined)
+    .option('--minimum-background-duration <seconds>', 'seconds the app must have been in the background before this update is applied on resume. Overrides the minimumBackgroundDuration sync option.', parseDecimalInt, undefined)
     .action(async (options: Options) => {
         const config = findAndReadConfigFile(process.cwd(), options.config);
 
-        if (typeof options.mandatory !== "boolean" && typeof options.enable !== "boolean") {
+        if (typeof options.mandatory !== "boolean"
+            && typeof options.enable !== "boolean"
+            && typeof options.rollout !== "number"
+            && typeof options.minimumBackgroundDuration !== "number") {
             console.error('No options specified. Exiting the program.')
             process.exit(1)
         }
 
+        // `Number.isFinite` is what rejects a non-numeric `--rollout`: `parseFloat` turns it into
+        // NaN, and both `NaN < 0` and `NaN > 100` are false.
+        if (options.rollout !== undefined
+            && (!Number.isFinite(options.rollout) || options.rollout < 0 || options.rollout > 100)) {
+            console.error('Rollout percentage number must be between 0 and 100 (inclusive).');
+            process.exit(1);
+        }
+
+        if (options.minimumBackgroundDuration !== undefined
+            && (!Number.isInteger(options.minimumBackgroundDuration) || options.minimumBackgroundDuration < 0)) {
+            console.error('--minimum-background-duration must be a whole number of seconds, 0 or greater.');
+            process.exit(1);
+        }
+
         await updateReleaseHistory(
             options.appVersion,
             options.binaryVersion,
@@ -41,10 +60,17 @@ program.command('update-history')
             options.identifier,
             options.mandatory,
             options.enable,
-            options.rollout
+            options.rollout,
+            options.minimumBackgroundDuration
         )
     });
 
+// Not `parseInt` itself: commander hands a coercion function the current value as its
+// second argument, which `parseInt` reads as the radix.
+function parseDecimalInt(value: string): number {
+    return parseInt(value, 10);
+}
+
 function parseBoolean(value: string) {
     if (value === 'true') return true;
     if (value === 'false') return false;

package/cli/commands/updateHistoryCommand/updateReleaseHistory.ts

@@ -11,6 +11,7 @@ export async function updateReleaseHistory(
     mandatory: boolean | undefined,
     enable: boolean | undefined,
     rollout: number | undefined,
+    minimumBackgroundDuration: number | undefined,
 ): Promise<void> {
     const releaseHistory = await getReleaseHistory(binaryVersion, platform, identifier);
 
@@ -20,6 +21,8 @@ export async function updateReleaseHistory(
     if (typeof mandatory === "boolean") updateInfo.mandatory = mandatory;
     if (typeof enable === "boolean") updateInfo.enabled = enable;
     if (typeof rollout === "number") updateInfo.rollout = rollout;
+    // 0 is what lowers the wait to "apply on the next resume", so truthiness cannot decide here.
+    if (typeof minimumBackgroundDuration === "number") updateInfo.minimumBackgroundDuration = minimumBackgroundDuration;
 
     try {
         await stageReleaseHistoryFile(binaryVersion, releaseHistory, platform, (jsonFilePath) =>

package/cli/dist/commands/createHistoryCommand/createReleaseHistory.test.js

@@ -68,8 +68,8 @@ describe("staging the release history a config is handed", () => {
             staged[platform] = fs.readFileSync(jsonFilePath, "utf8");
         };
         await Promise.all([
-            updateReleaseHistory("1.0.1", BINARY_VERSION, getReleaseHistory, setReleaseHistory, "ios", "RN0840", undefined, false, undefined),
-            updateReleaseHistory("1.0.1", BINARY_VERSION, getReleaseHistory, setReleaseHistory, "android", "RN0840", undefined, false, undefined),
+            updateReleaseHistory("1.0.1", BINARY_VERSION, getReleaseHistory, setReleaseHistory, "ios", "RN0840", undefined, false, undefined, undefined),
+            updateReleaseHistory("1.0.1", BINARY_VERSION, getReleaseHistory, setReleaseHistory, "android", "RN0840", undefined, false, undefined, undefined),
         ]);
         expect(staged.ios).toContain("ios-url");
         expect(staged.ios).not.toContain("android-url");

package/cli/dist/commands/releaseCommand/addToReleaseHistory.js

@@ -1,5 +1,5 @@
 import { stageReleaseHistoryFile } from "../../functions/stageReleaseHistoryFile.js";
-export async function addToReleaseHistory(appVersion, binaryVersion, bundleDownloadUrl, binaryPatchDownloadUrl, packageHash, getReleaseHistory, setReleaseHistory, platform, identifier, mandatory, enable, rollout, diffPackages) {
+export async function addToReleaseHistory(appVersion, binaryVersion, bundleDownloadUrl, binaryPatchDownloadUrl, packageHash, getReleaseHistory, setReleaseHistory, platform, identifier, mandatory, enable, rollout, diffPackages, minimumBackgroundDuration) {
     const releaseHistory = await getReleaseHistory(binaryVersion, platform, identifier);
     const updateInfo = releaseHistory[appVersion];
     if (updateInfo) {
@@ -26,6 +26,10 @@ export async function addToReleaseHistory(appVersion, binaryVersion, bundleDownl
     if (typeof rollout === 'number') {
         newReleaseHistory[appVersion].rollout = rollout;
     }
+    // An entry without it leaves the wait to the sync option, so 0 has to be written.
+    if (typeof minimumBackgroundDuration === 'number') {
+        newReleaseHistory[appVersion].minimumBackgroundDuration = minimumBackgroundDuration;
+    }
     try {
         await stageReleaseHistoryFile(binaryVersion, newReleaseHistory, platform, (jsonFilePath) => setReleaseHistory(binaryVersion, jsonFilePath, newReleaseHistory, platform, identifier));
     }

package/cli/dist/commands/releaseCommand/index.js

@@ -27,6 +27,7 @@ program.command('release')
     .choices(OVERSIZED_PATCH_POLICIES)
     .default(DEFAULT_OVERSIZED_PATCH_POLICY))
     .option('--diff-base-count <number>', 'how many recent releases to build asset diff archives against (0 disables). Requires `bundleDownloader` in the config file.', parseDecimalInt, DEFAULT_DIFF_BASE_COUNT)
+    .option('--minimum-background-duration <seconds>', 'seconds the app must have been in the background before this update is applied on resume. Overrides the minimumBackgroundDuration sync option.', parseDecimalInt)
     .action(async (options) => {
     const config = findAndReadConfigFile(process.cwd(), options.config);
     if (typeof options.rollout === 'number' && (options.rollout < 0 || options.rollout > 100)) {
@@ -37,13 +38,18 @@ program.command('release')
         console.error('--diff-base-count must be a whole number of releases, 0 or greater.');
         process.exit(1);
     }
+    if (options.minimumBackgroundDuration !== undefined
+        && (!Number.isInteger(options.minimumBackgroundDuration) || options.minimumBackgroundDuration < 0)) {
+        console.error('--minimum-background-duration must be a whole number of seconds, 0 or greater.');
+        process.exit(1);
+    }
     if (options.hashCalc && !options.skipBundle) {
         console.error('--hash-calc option can be used only when --skip-bundle is set to true.');
         process.exit(1);
     }
     // Resolved before bundling so a wrong path fails now rather than after a build.
     const baseBundlePath = resolveBinaryBundlePathOption(options.binaryBundlePath);
-    await release(config.bundleUploader, config.getReleaseHistory, config.setReleaseHistory, options.binaryVersion, options.appVersion, options.framework, options.platform, options.identifier, options.outputPath, options.entryFile, options.jsBundleName, options.mandatory, options.enable, options.rollout, options.skipBundle, options.skipCleanup, `${options.outputPath}/${options.outputBundleDir}`, options.outputMetroDir, options.hashCalc, baseBundlePath, options.onOversizedPatch, config.bundleDownloader, options.diffBaseCount);
+    await release(config.bundleUploader, config.getReleaseHistory, config.setReleaseHistory, options.binaryVersion, options.appVersion, options.framework, options.platform, options.identifier, options.outputPath, options.entryFile, options.jsBundleName, options.mandatory, options.enable, options.rollout, options.skipBundle, options.skipCleanup, `${options.outputPath}/${options.outputBundleDir}`, options.outputMetroDir, options.hashCalc, baseBundlePath, options.onOversizedPatch, config.bundleDownloader, options.diffBaseCount, options.minimumBackgroundDuration);
     console.log('🚀 Release completed.');
 });
 // Not `parseInt` itself: commander hands a coercion function the current value as its

package/cli/dist/commands/releaseCommand/index.test.js

@@ -29,6 +29,7 @@ const ARG_INDEX = {
     onOversizedPatch: 20,
     bundleDownloader: 21,
     diffBaseCount: 22,
+    minimumBackgroundDuration: 23,
 };
 /**
  * Parses a `release` invocation against the real command definition. Commander is asked
@@ -118,4 +119,25 @@ describe("release command options", () => {
         const { release } = await import("./release.js");
         expect(jest.mocked(release)).not.toHaveBeenCalled();
     });
+    it("passes the chosen minimum background duration through to the release", async () => {
+        const args = await runReleaseCommand(['-b', '1.0.0', '-v', '1.0.1', '--minimum-background-duration', '600']);
+        expect(args[ARG_INDEX.minimumBackgroundDuration]).toBe(600);
+    });
+    it("leaves the minimum background duration unset when the option is not given, so the sync option decides", async () => {
+        const args = await runReleaseCommand(['-b', '1.0.0', '-v', '1.0.1']);
+        expect(args[ARG_INDEX.minimumBackgroundDuration]).toBeUndefined();
+    });
+    it.each([
+        ['is negative', '-1'],
+        ['is not a number at all', 'soon'],
+    ])("rejects a minimum background duration that %s", async (_caseName, value) => {
+        jest.spyOn(console, 'error').mockImplementation(() => { });
+        jest.spyOn(process, 'exit').mockImplementation(((code) => {
+            throw new Error(`process.exit(${code})`);
+        }));
+        await expect(parseReleaseCommand(['-b', '1.0.0', '-v', '1.0.1', '--minimum-background-duration', value]))
+            .rejects.toThrow('process.exit(1)');
+        const { release } = await import("./release.js");
+        expect(jest.mocked(release)).not.toHaveBeenCalled();
+    });
 });

package/cli/dist/commands/releaseCommand/release.js

@@ -9,7 +9,7 @@ import { resolveAssetDiffBases } from "../../functions/resolveAssetDiffBases.js"
 import { BINARY_PATCH_ARCHIVE_SUFFIX, BINARY_PATCH_BASE_RECORD_NAME, DEFAULT_OVERSIZED_PATCH_POLICY, extractCodePushBundleContents, formatBinaryPatchSummary, hashBundleFile, isPatchArchiveOversized, makeBinaryPatchBundle, readBinaryPatchBaseRecord, } from "../../functions/makeBinaryPatchBundle.js";
 /** How many of the most recent releases a release builds asset diff archives against. */
 export const DEFAULT_DIFF_BASE_COUNT = 3;
-export async function release(bundleUploader, getReleaseHistory, setReleaseHistory, binaryVersion, appVersion, framework, platform, identifier, outputPath, entryFile, jsBundleName, mandatory, enable, rollout, skipBundle, skipCleanup, bundleDirectory, outputMetroDir, hashCalc, baseBundlePath, onOversizedPatch = DEFAULT_OVERSIZED_PATCH_POLICY, bundleDownloader, diffBaseCount = DEFAULT_DIFF_BASE_COUNT) {
+export async function release(bundleUploader, getReleaseHistory, setReleaseHistory, binaryVersion, appVersion, framework, platform, identifier, outputPath, entryFile, jsBundleName, mandatory, enable, rollout, skipBundle, skipCleanup, bundleDirectory, outputMetroDir, hashCalc, baseBundlePath, onOversizedPatch = DEFAULT_OVERSIZED_PATCH_POLICY, bundleDownloader, diffBaseCount = DEFAULT_DIFF_BASE_COUNT, minimumBackgroundDuration) {
     if (baseBundlePath) {
         // Checked before the bundler runs, so the wrong base bundle costs a second rather
         // than a full build.
@@ -92,7 +92,7 @@ export async function release(bundleUploader, getReleaseHistory, setReleaseHisto
                 `(${error instanceof Error ? error.message : String(error)}).`);
         }
     }
-    await addToReleaseHistory(appVersion, binaryVersion, downloadUrl, patchDownloadUrl, packageHash, getReleaseHistory, setReleaseHistory, platform, identifier, mandatory, enable, rollout, Object.keys(diffPackages).length > 0 ? diffPackages : undefined);
+    await addToReleaseHistory(appVersion, binaryVersion, downloadUrl, patchDownloadUrl, packageHash, getReleaseHistory, setReleaseHistory, platform, identifier, mandatory, enable, rollout, Object.keys(diffPackages).length > 0 ? diffPackages : undefined, minimumBackgroundDuration);
     if (!skipCleanup) {
         cleanUpOutputs(outputPath);
     }

package/cli/dist/commands/releaseCommand/release.test.js

@@ -95,7 +95,7 @@ async function runRelease(staged, overrides = {}) {
     await release(recordingUploader(uploads, overrides.uploadFailsFor), history.getReleaseHistory, history.setReleaseHistory, BINARY_VERSION, APP_VERSION, undefined, overrides.platform ?? 'ios', undefined, staged.outputPath, 'index.ts', 
     // Left unset unless the case is about -j, the way commander leaves it.
     overrides.jsBundleName, false, true, undefined, true, // skipBundle
-    overrides.skipCleanup ?? true, staged.bundleDirectory, undefined, undefined, overrides.binaryBundlePath, overrides.onOversizedPatch, overrides.bundleDownloader, overrides.diffBaseCount);
+    overrides.skipCleanup ?? true, staged.bundleDirectory, undefined, undefined, overrides.binaryBundlePath, overrides.onOversizedPatch, overrides.bundleDownloader, overrides.diffBaseCount, overrides.minimumBackgroundDuration);
     return { uploads, releaseHistories: history.saved, uploadCountsWhenHistorySaved };
 }
 let logs;
@@ -563,3 +563,20 @@ describe("release with asset diff bases", () => {
         expect(path.basename(uploads[0].filePath)).toBe(staged.bundleFileName);
     });
 });
+describe("release --minimum-background-duration", () => {
+    it("records the background wait on the release it publishes", async () => {
+        const staged = await stageBundleOutput("minimum-background-duration");
+        const { releaseHistories } = await runRelease(staged, { minimumBackgroundDuration: 600 });
+        expect(releaseHistories[0][APP_VERSION].minimumBackgroundDuration).toBe(600);
+    });
+    it("releases a background wait of zero seconds as zero, not as an unset option", async () => {
+        const staged = await stageBundleOutput("zero-minimum-background-duration");
+        const { releaseHistories } = await runRelease(staged, { minimumBackgroundDuration: 0 });
+        expect(releaseHistories[0][APP_VERSION].minimumBackgroundDuration).toBe(0);
+    });
+    it("leaves the release saying nothing about the background wait when the option is not given", async () => {
+        const staged = await stageBundleOutput("no-minimum-background-duration");
+        const { releaseHistories } = await runRelease(staged);
+        expect(releaseHistories[0][APP_VERSION]).not.toHaveProperty('minimumBackgroundDuration');
+    });
+});

package/cli/dist/commands/updateHistoryCommand/index.js

@@ -12,14 +12,35 @@ program.command('update-history')
     .option('-m, --mandatory <bool>', 'make the release to be mandatory', parseBoolean, undefined)
     .option('-e, --enable <bool>', 'make the release to be enabled', parseBoolean, undefined)
     .option('--rollout <number>', 'rollout percentage (0-100)', parseFloat, undefined)
+    .option('--minimum-background-duration <seconds>', 'seconds the app must have been in the background before this update is applied on resume. Overrides the minimumBackgroundDuration sync option.', parseDecimalInt, undefined)
     .action(async (options) => {
     const config = findAndReadConfigFile(process.cwd(), options.config);
-    if (typeof options.mandatory !== "boolean" && typeof options.enable !== "boolean") {
+    if (typeof options.mandatory !== "boolean"
+        && typeof options.enable !== "boolean"
+        && typeof options.rollout !== "number"
+        && typeof options.minimumBackgroundDuration !== "number") {
         console.error('No options specified. Exiting the program.');
         process.exit(1);
     }
-    await updateReleaseHistory(options.appVersion, options.binaryVersion, config.getReleaseHistory, config.setReleaseHistory, options.platform, options.identifier, options.mandatory, options.enable, options.rollout);
+    // `Number.isFinite` is what rejects a non-numeric `--rollout`: `parseFloat` turns it into
+    // NaN, and both `NaN < 0` and `NaN > 100` are false.
+    if (options.rollout !== undefined
+        && (!Number.isFinite(options.rollout) || options.rollout < 0 || options.rollout > 100)) {
+        console.error('Rollout percentage number must be between 0 and 100 (inclusive).');
+        process.exit(1);
+    }
+    if (options.minimumBackgroundDuration !== undefined
+        && (!Number.isInteger(options.minimumBackgroundDuration) || options.minimumBackgroundDuration < 0)) {
+        console.error('--minimum-background-duration must be a whole number of seconds, 0 or greater.');
+        process.exit(1);
+    }
+    await updateReleaseHistory(options.appVersion, options.binaryVersion, config.getReleaseHistory, config.setReleaseHistory, options.platform, options.identifier, options.mandatory, options.enable, options.rollout, options.minimumBackgroundDuration);
 });
+// Not `parseInt` itself: commander hands a coercion function the current value as its
+// second argument, which `parseInt` reads as the radix.
+function parseDecimalInt(value) {
+    return parseInt(value, 10);
+}
 function parseBoolean(value) {
     if (value === 'true')
         return true;

package/cli/dist/commands/updateHistoryCommand/index.test.js

@@ -0,0 +1,102 @@
+import fs from "fs";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it, jest } from "@jest/globals";
+/**
+ * Checks the command definition against the entry it saves. Everything this command does
+ * ends up in the release history the config is handed, so an option that never reaches it
+ * leaves the release exactly as it was - which the command still reports as a success.
+ */
+const BINARY_VERSION = '1.0.0';
+const APP_VERSION = '1.0.1';
+let mockConfig;
+jest.mock("../../utils/fsUtils.js", () => ({
+    findAndReadConfigFile: () => mockConfig,
+}));
+/**
+ * Puts one released version in the config's history and records every history it is
+ * handed back, so a case can read the entry as the consumer would store it.
+ */
+function stageReleaseHistory() {
+    const releaseHistory = {
+        [APP_VERSION]: {
+            enabled: true,
+            mandatory: false,
+            downloadUrl: 'https://cdn.example.com/bundle',
+            packageHash: 'a3f1c0',
+        },
+    };
+    const saved = [];
+    mockConfig = {
+        bundleUploader: async () => ({ downloadUrl: 'https://cdn.example.com/bundle' }),
+        getReleaseHistory: async () => releaseHistory,
+        // The command edits the history in place, so what it saved is copied out here.
+        setReleaseHistory: async (_binaryVersion, _jsonFilePath, releaseInfo) => {
+            saved.push(structuredClone(releaseInfo));
+        },
+    };
+    return saved;
+}
+/**
+ * Parses an `update-history` invocation against the real command definition. Commander is
+ * asked to throw instead of exiting, and to keep its diagnostics to itself, so a rejected
+ * option can be asserted on without ending the worker or the output.
+ */
+async function parseUpdateHistoryCommand(args) {
+    const { program } = await import("commander");
+    await import("./index.js");
+    const updateHistoryCommand = program.commands.find((command) => command.name() === 'update-history');
+    updateHistoryCommand?.exitOverride();
+    updateHistoryCommand?.configureOutput({ writeErr: () => { } });
+    await program.parseAsync(['update-history', ...args], { from: 'user' });
+}
+async function runUpdateHistoryCommand(args) {
+    await parseUpdateHistoryCommand(['-b', BINARY_VERSION, '-v', APP_VERSION, ...args]);
+}
+let saved;
+beforeEach(() => {
+    jest.resetModules();
+    saved = stageReleaseHistory();
+    jest.spyOn(console, 'log').mockImplementation(() => { });
+    jest.spyOn(console, 'error').mockImplementation(() => { });
+    jest.spyOn(process, 'exit').mockImplementation(((code) => {
+        throw new Error(`process.exit(${code})`);
+    }));
+});
+afterEach(() => {
+    jest.restoreAllMocks();
+    // The command writes its JSON under the directory it was invoked in.
+    fs.rmSync(path.resolve(process.cwd(), "codepush-release-history"), { recursive: true, force: true });
+});
+describe("update-history command options", () => {
+    it("lowers the background wait of a release that is already out to zero seconds", async () => {
+        await runUpdateHistoryCommand(['--minimum-background-duration', '0']);
+        expect(saved).toHaveLength(1);
+        expect(saved[0][APP_VERSION].minimumBackgroundDuration).toBe(0);
+    });
+    it("leaves the entry saying nothing about the background wait when only --enable is given", async () => {
+        await runUpdateHistoryCommand(['--enable', 'false']);
+        expect(saved[0][APP_VERSION].enabled).toBe(false);
+        expect(saved[0][APP_VERSION]).not.toHaveProperty('minimumBackgroundDuration');
+    });
+    it("saves the rollout percentage when --rollout is the only option given", async () => {
+        await runUpdateHistoryCommand(['--rollout', '50']);
+        expect(saved[0][APP_VERSION].rollout).toBe(50);
+    });
+    it("exits without saving anything when no option says what to change", async () => {
+        await expect(runUpdateHistoryCommand([])).rejects.toThrow('process.exit(1)');
+        expect(saved).toHaveLength(0);
+    });
+    it("rejects a negative background wait and saves nothing", async () => {
+        await expect(runUpdateHistoryCommand(['--minimum-background-duration', '-1']))
+            .rejects.toThrow('process.exit(1)');
+        expect(saved).toHaveLength(0);
+    });
+    it.each([
+        ['a percentage above 100', '150'],
+        ['a percentage that is not a number', 'abc'],
+    ])("rejects %s and saves nothing", async (_scenario, rollout) => {
+        await expect(runUpdateHistoryCommand(['--rollout', rollout]))
+            .rejects.toThrow('process.exit(1)');
+        expect(saved).toHaveLength(0);
+    });
+});

package/cli/dist/commands/updateHistoryCommand/updateReleaseHistory.js

@@ -1,5 +1,5 @@
 import { stageReleaseHistoryFile } from "../../functions/stageReleaseHistoryFile.js";
-export async function updateReleaseHistory(appVersion, binaryVersion, getReleaseHistory, setReleaseHistory, platform, identifier, mandatory, enable, rollout) {
+export async function updateReleaseHistory(appVersion, binaryVersion, getReleaseHistory, setReleaseHistory, platform, identifier, mandatory, enable, rollout, minimumBackgroundDuration) {
     const releaseHistory = await getReleaseHistory(binaryVersion, platform, identifier);
     const updateInfo = releaseHistory[appVersion];
     if (!updateInfo)
@@ -10,6 +10,9 @@ export async function updateReleaseHistory(appVersion, binaryVersion, getRelease
         updateInfo.enabled = enable;
     if (typeof rollout === "number")
         updateInfo.rollout = rollout;
+    // 0 is what lowers the wait to "apply on the next resume", so truthiness cannot decide here.
+    if (typeof minimumBackgroundDuration === "number")
+        updateInfo.minimumBackgroundDuration = minimumBackgroundDuration;
     try {
         await stageReleaseHistoryFile(binaryVersion, releaseHistory, platform, (jsonFilePath) => setReleaseHistory(binaryVersion, jsonFilePath, releaseHistory, platform, identifier));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bravemobile/react-native-code-push",
-  "version": "13.2.0",
+  "version": "13.3.0",
   "description": "React Native plugin for the CodePush service",
   "main": "src/CodePush.js",
   "react-native": "src/CodePush.js",

package/src/CodePush.js

@@ -200,6 +200,11 @@ async function checkForUpdate(handleBinaryVersionMismatchCallback = null) {
            * back on when the diff fails on its asset side.
            */
           asset_diff_download_url: diffPackageDownloadUrl,
+          /**
+           * Only present when the release asked for a background duration of its own, which
+           * then wins over the one the `sync` call passes.
+           */
+          minimum_background_duration: latestReleaseInfo.minimumBackgroundDuration,
           // (`enabled` will always be true in the release information obtained from the previous process.)
           is_available: latestReleaseInfo.enabled,
           package_hash: latestReleaseInfo.packageHash,
@@ -309,6 +314,11 @@ function mapToRemotePackageMetadata(updateInfo) {
     ...(updateInfo.asset_diff_download_url
       ? { assetDiffDownloadUrl: updateInfo.asset_diff_download_url }
       : {}),
+    // Presence is read off the type, not off truthiness, so that a release asking for `0`
+    // seconds keeps its own value instead of looking like a release that asked for nothing.
+    ...(typeof updateInfo.minimum_background_duration === 'number'
+      ? { minimumBackgroundDuration: updateInfo.minimum_background_duration }
+      : {}),
   };
 }
 
@@ -552,6 +562,7 @@ const sync = (() => {
  */
 async function syncInternal(options = {}, syncStatusChangeCallback, downloadProgressCallback, handleBinaryVersionMismatchCallback) {
   let resolvedInstallMode;
+  let resolvedMinimumBackgroundDuration;
   const syncOptions = {
     deploymentKey: null,
     ignoreFailedUpdates: true,
@@ -596,8 +607,8 @@ async function syncInternal(options = {}, syncStatusChangeCallback, downloadProg
           if (resolvedInstallMode == CodePush.InstallMode.ON_NEXT_RESTART) {
             log("Update is installed and will be run on the next app restart.");
           } else if (resolvedInstallMode == CodePush.InstallMode.ON_NEXT_RESUME) {
-            if (syncOptions.minimumBackgroundDuration > 0) {
-              log(`Update is installed and will be run after the app has been in the background for at least ${syncOptions.minimumBackgroundDuration} seconds.`);
+            if (resolvedMinimumBackgroundDuration > 0) {
+              log(`Update is installed and will be run after the app has been in the background for at least ${resolvedMinimumBackgroundDuration} seconds.`);
             } else {
               log("Update is installed and will be run when the app next resumes.");
             }
@@ -630,9 +641,11 @@ async function syncInternal(options = {}, syncStatusChangeCallback, downloadProg
 
       // Determine the correct install mode based on whether the update is mandatory or not.
       resolvedInstallMode = localPackage.isMandatory ? syncOptions.mandatoryInstallMode : syncOptions.installMode;
+      // `??` rather than `||`, so a release asking for `0` seconds keeps its own value.
+      resolvedMinimumBackgroundDuration = remotePackage.minimumBackgroundDuration ?? syncOptions.minimumBackgroundDuration;
 
       syncStatusChangeCallback(CodePush.SyncStatus.INSTALLING_UPDATE);
-      await localPackage.install(resolvedInstallMode, syncOptions.minimumBackgroundDuration, () => {
+      await localPackage.install(resolvedInstallMode, resolvedMinimumBackgroundDuration, () => {
         syncStatusChangeCallback(CodePush.SyncStatus.UPDATE_INSTALLED);
       });
 

package/src/CodePush.test.js

@@ -649,3 +649,60 @@ describe('telemetry callback errors', () => {
     expect(nativeBridge.saveStatusReportForRetry).not.toHaveBeenCalled();
   });
 });
+
+/**
+ * A release can ask for its own minimum background duration - how long the app has to have
+ * been in the background before an update installed with `ON_NEXT_RESUME` is applied. The
+ * app passes a duration to `sync` for the releases that ask for nothing, and whichever of
+ * the two wins is what the native module is given when the update is installed.
+ */
+describe('the minimum background duration an update is installed with', () => {
+  /** The release the CLI writes when the release carries its own background duration. */
+  function releaseAskingFor(minimumBackgroundDuration) {
+    const history = fullOnlyRelease();
+    history[LABEL].minimumBackgroundDuration = minimumBackgroundDuration;
+    return history;
+  }
+
+  /** The background duration the native module is given, in seconds. */
+  function installedMinimumBackgroundDuration(nativeBridge) {
+    expect(nativeBridge.installUpdate).toHaveBeenCalledTimes(1);
+    return nativeBridge.installUpdate.mock.calls[0][2];
+  }
+
+  it('takes the one the release history entry asks for over the one the sync call passes', async () => {
+    const { CodePush, nativeBridge } = loadCodePush({ releaseHistory: releaseAskingFor(600) });
+
+    const syncStatus = await CodePush.sync({
+      installMode: InstallMode.ON_NEXT_RESUME,
+      minimumBackgroundDuration: 3600,
+    });
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(installedMinimumBackgroundDuration(nativeBridge)).toBe(600);
+  });
+
+  it('keeps the one the sync call passes when the release history entry asks for none', async () => {
+    const { CodePush, nativeBridge } = loadCodePush({ releaseHistory: fullOnlyRelease() });
+
+    const syncStatus = await CodePush.sync({
+      installMode: InstallMode.ON_NEXT_RESUME,
+      minimumBackgroundDuration: 3600,
+    });
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(installedMinimumBackgroundDuration(nativeBridge)).toBe(3600);
+  });
+
+  it('runs a release that asks for zero seconds on the next resume, however long the sync call would have waited', async () => {
+    const { CodePush, nativeBridge } = loadCodePush({ releaseHistory: releaseAskingFor(0) });
+
+    const syncStatus = await CodePush.sync({
+      installMode: InstallMode.ON_NEXT_RESUME,
+      minimumBackgroundDuration: 3600,
+    });
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(installedMinimumBackgroundDuration(nativeBridge)).toBe(0);
+  });
+});

package/typings/react-native-code-push.d.ts

@@ -44,6 +44,13 @@ export interface ReleaseInfo {
      */
     diffPackages?: Record<string, string>;
     packageHash: string;
+    /**
+     * The minimum number of seconds the app has to have been in the background before this
+     * release is applied, with the same meaning as `SyncOptions.minimumBackgroundDuration`.
+     * When it is present it takes precedence over the value passed to `sync`, so a single
+     * release can be applied sooner or later than the app asks for by default.
+     */
+    minimumBackgroundDuration?: number;
     rollout?: number;
 }
 
@@ -73,6 +80,11 @@ export interface UpdateCheckResponse {
     should_run_binary_version?: boolean;
     update_app_version?: boolean;
     is_mandatory?: boolean;
+    /**
+     * The minimum number of seconds the app has to have been in the background before this
+     * update is applied. It is only present when the release asked for one of its own.
+     */
+    minimum_background_duration?: number;
 }
 
 /**
@@ -345,6 +357,13 @@ export interface RemotePackage extends Package {
      * `UpdateArchiveResult`.
      */
     assetDiffDownloadUrl?: string;
+
+    /**
+     * The minimum number of seconds the app has to have been in the background before this
+     * update is applied. It is only present when the release history entry set it, and it
+     * then takes precedence over the `minimumBackgroundDuration` passed to `sync`.
+     */
+    minimumBackgroundDuration?: number;
 }
 
 export interface SyncOptions {
@@ -372,6 +391,7 @@ export interface SyncOptions {
      * only applies to updates which are installed using `InstallMode.ON_NEXT_RESUME` or `InstallMode.ON_NEXT_SUSPEND`, and can be useful
      * for getting your update in front of end users sooner, without being too obtrusive. Defaults to `0`, which has the effect of applying
      * the update immediately after a resume or unless the app suspension is long enough to not matter, regardless how long it was in the background.
+     * A `minimumBackgroundDuration` set on the release history entry of the update being installed takes precedence over this option.
      */
     minimumBackgroundDuration?: number;