@bravemobile/react-native-code-push 13.1.0-beta.4 → 13.1.0-beta.6

package/src/CodePush.test.js

@@ -60,16 +60,16 @@ function diffRelease() {
 }
 
 /**
- * @param binaryPatchResult what the native side reports the patch attempt ended in, which
- *        only a download that had a patch to try comes back with.
+ * @param updateArchiveResult what the native side reports the archive attempts ended in,
+ *        which only a download that had an archive to try comes back with.
  * @param installedPackage the CodePush update the app is running, if any.
  */
-function createNativeBridge({ binaryPatchResult, installedPackage } = {}) {
+function createNativeBridge({ updateArchiveResult, installedPackage } = {}) {
   return {
     addDownloadProgressListener: jest.fn(() => ({ remove: jest.fn() })),
     downloadUpdate: jest.fn(async (updatePackage) => ({
       ...updatePackage,
-      ...(binaryPatchResult ? { binaryPatchResult } : {}),
+      ...(updateArchiveResult ? { updateArchiveResult } : {}),
     })),
     // Without an installed CodePush update, the app runs the bundle of its binary.
     getUpdateMetadata: jest.fn(async () => installedPackage ?? null),
@@ -89,13 +89,13 @@ function createNativeBridge({ binaryPatchResult, installedPackage } = {}) {
  * native bridge live on the module itself - configured the way an app configures it: the
  * decorator registers the app-wide options, and every sync below is one the app asks for.
  *
- * @param onBinaryPatchResult a callback the app registers on the decorator, as opposed to
+ * @param onUpdateArchiveResult a callback the app registers on the decorator, as opposed to
  *        one it passes to a single `sync()` call.
  */
-function loadCodePush({ releaseHistory = {}, updateChecker, binaryPatchResult, onBinaryPatchResult, installedPackage } = {}) {
+function loadCodePush({ releaseHistory = {}, updateChecker, updateArchiveResult, onUpdateArchiveResult, installedPackage } = {}) {
   jest.resetModules();
   const CodePush = require('./CodePush');
-  const nativeBridge = createNativeBridge({ binaryPatchResult, installedPackage });
+  const nativeBridge = createNativeBridge({ updateArchiveResult, installedPackage });
 
   CodePush.setUpTestDependencies(
     null,
@@ -106,7 +106,7 @@ function loadCodePush({ releaseHistory = {}, updateChecker, binaryPatchResult, o
     checkFrequency: CodePush.CheckFrequency.MANUAL,
     releaseHistoryFetcher: async () => releaseHistory,
     updateChecker,
-    onBinaryPatchResult,
+    onUpdateArchiveResult,
   });
 
   return { CodePush, nativeBridge };
@@ -211,11 +211,13 @@ describe('checkForUpdate without a binary patch in the release history', () => {
 });
 
 /**
- * A diff archive only applies to the one release it was computed against, so which of the
- * two patch urls of a release is downloaded depends on what the app is running right now.
+ * A diff archive only applies to the one release it was computed against, so whether the
+ * diff url is handed to the native side at all depends on what the app is running right
+ * now. The patch url is always handed over with it, because the diff falling back to the
+ * patch archive is the native side's decision to make.
  */
 describe('checkForUpdate with asset diff packages in the release history', () => {
-  it('downloads the diff archive when the installed update matches a diff base', async () => {
+  it('carries the diff url next to the patch url when the installed update matches a diff base', async () => {
     const { CodePush, nativeBridge } = loadCodePush({
       releaseHistory: diffRelease(),
       installedPackage: { packageHash: INSTALLED_HASH },
@@ -226,11 +228,12 @@ describe('checkForUpdate with asset diff packages in the release history', () =>
 
     expect(downloadedPackageMetadata(nativeBridge)).toMatchObject({
       downloadUrl: DOWNLOAD_URL,
-      binaryPatchDownloadUrl: DIFF_URL,
+      binaryPatchDownloadUrl: BINARY_PATCH_DOWNLOAD_URL,
+      assetDiffDownloadUrl: DIFF_URL,
     });
   });
 
-  it('downloads the plain patch archive when the installed update matches no diff base', async () => {
+  it('leaves the diff url out when the installed update matches no diff base', async () => {
     const { CodePush, nativeBridge } = loadCodePush({
       releaseHistory: diffRelease(),
       installedPackage: { packageHash: 'other-hash' },
@@ -239,20 +242,20 @@ describe('checkForUpdate with asset diff packages in the release history', () =>
     const remotePackage = await CodePush.checkForUpdate();
     await remotePackage.download();
 
-    expect(downloadedPackageMetadata(nativeBridge)).toMatchObject({
-      binaryPatchDownloadUrl: BINARY_PATCH_DOWNLOAD_URL,
-    });
+    const metadata = downloadedPackageMetadata(nativeBridge);
+    expect(metadata).toMatchObject({ binaryPatchDownloadUrl: BINARY_PATCH_DOWNLOAD_URL });
+    expect(metadata).not.toHaveProperty('assetDiffDownloadUrl');
   });
 
-  it('downloads the plain patch archive when no update is installed', async () => {
+  it('leaves the diff url out when no update is installed', async () => {
     const { CodePush, nativeBridge } = loadCodePush({ releaseHistory: diffRelease() });
 
     const remotePackage = await CodePush.checkForUpdate();
     await remotePackage.download();
 
-    expect(downloadedPackageMetadata(nativeBridge)).toMatchObject({
-      binaryPatchDownloadUrl: BINARY_PATCH_DOWNLOAD_URL,
-    });
+    const metadata = downloadedPackageMetadata(nativeBridge);
+    expect(metadata).toMatchObject({ binaryPatchDownloadUrl: BINARY_PATCH_DOWNLOAD_URL });
+    expect(metadata).not.toHaveProperty('assetDiffDownloadUrl');
   });
 
   it('does not send the diff package map across the bridge', async () => {
@@ -310,13 +313,33 @@ describe('checkForUpdate through the deprecated updateChecker', () => {
 });
 
 /**
- * How a patch attempt went is reported to the app that asked to hear about it, and to
+ * How the archive attempts went is reported to the app that asked to hear about it, and to
  * nobody else: it is not part of the update, and an app that asked for nothing gets the
  * install it always got.
  */
-describe('the binary patch result of a sync', () => {
-  const APPLIED = { status: 'applied', applyDurationMs: 812 };
-  const FELL_BACK = { status: 'fallback', fallbackReason: 'base_hash_mismatch', applyDurationMs: 1503 };
+describe('the update archive result of a sync', () => {
+  const APPLIED = {
+    status: 'applied',
+    archive: 'binary-patch',
+    totalDurationMs: 812,
+    attempts: [{ archive: 'binary-patch', durationMs: 812, applyDurationMs: 64 }],
+  };
+  const FELL_BACK = {
+    status: 'fallback',
+    archive: 'binary-patch',
+    fallbackReason: 'base_hash_mismatch',
+    totalDurationMs: 1503,
+    attempts: [{ archive: 'binary-patch', fallbackReason: 'base_hash_mismatch', durationMs: 1503 }],
+  };
+  const APPLIED_AFTER_DIFF_FELL_BACK = {
+    status: 'applied',
+    archive: 'binary-patch',
+    totalDurationMs: 1503,
+    attempts: [
+      { archive: 'asset-diff', fallbackReason: 'asset_merge_failed', durationMs: 690, applyDurationMs: 41 },
+      { archive: 'binary-patch', durationMs: 813, applyDurationMs: 58 },
+    ],
+  };
 
   /** The metadata the update is installed from, as the native module is given it. */
   function installedPackageMetadata(nativeBridge) {
@@ -327,46 +350,62 @@ describe('the binary patch result of a sync', () => {
   it('tells the app the update was installed from its patch, and how long that took', async () => {
     const { CodePush, nativeBridge } = loadCodePush({
       releaseHistory: patchedRelease(),
-      binaryPatchResult: APPLIED,
+      updateArchiveResult: APPLIED,
     });
-    const onBinaryPatchResult = jest.fn();
+    const onUpdateArchiveResult = jest.fn();
 
-    const syncStatus = await CodePush.sync({ onBinaryPatchResult });
+    const syncStatus = await CodePush.sync({ onUpdateArchiveResult });
 
     expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
-    expect(onBinaryPatchResult).toHaveBeenCalledTimes(1);
-    expect(onBinaryPatchResult).toHaveBeenCalledWith(LABEL, APPLIED);
+    expect(onUpdateArchiveResult).toHaveBeenCalledTimes(1);
+    expect(onUpdateArchiveResult).toHaveBeenCalledWith(LABEL, APPLIED);
     expect(nativeBridge.installUpdate).toHaveBeenCalledTimes(1);
   });
 
   it('tells the app why the update came from the full archive instead', async () => {
     const { CodePush } = loadCodePush({
       releaseHistory: patchedRelease(),
-      binaryPatchResult: FELL_BACK,
+      updateArchiveResult: FELL_BACK,
     });
-    const onBinaryPatchResult = jest.fn();
+    const onUpdateArchiveResult = jest.fn();
 
     // A patch that could not be applied is not a failed update: the full archive installs.
-    const syncStatus = await CodePush.sync({ onBinaryPatchResult });
+    const syncStatus = await CodePush.sync({ onUpdateArchiveResult });
 
     expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
-    expect(onBinaryPatchResult).toHaveBeenCalledWith(LABEL, FELL_BACK);
+    expect(onUpdateArchiveResult).toHaveBeenCalledWith(LABEL, FELL_BACK);
+  });
+
+  it("the app is handed each archive's apply time and the whole path's total", async () => {
+    const { CodePush } = loadCodePush({
+      releaseHistory: diffRelease(),
+      installedPackage: { packageHash: INSTALLED_HASH },
+      updateArchiveResult: APPLIED_AFTER_DIFF_FELL_BACK,
+    });
+    const onUpdateArchiveResult = jest.fn();
+
+    await CodePush.sync({ onUpdateArchiveResult });
+
+    expect(onUpdateArchiveResult).toHaveBeenCalledWith(LABEL, APPLIED_AFTER_DIFF_FELL_BACK);
+    const [, result] = onUpdateArchiveResult.mock.calls[0];
+    expect(result.totalDurationMs).toBe(1503);
+    expect(result.attempts.map((attempt) => attempt.applyDurationMs)).toEqual([41, 58]);
   });
 
   it('tells the app that registered the callback on the decorator, even about a sync it asked for itself', async () => {
-    const onBinaryPatchResult = jest.fn();
+    const onUpdateArchiveResult = jest.fn();
     const { CodePush } = loadCodePush({
       releaseHistory: patchedRelease(),
-      binaryPatchResult: APPLIED,
-      onBinaryPatchResult,
+      updateArchiveResult: APPLIED,
+      onUpdateArchiveResult,
     });
 
     // The decorator checks nothing on its own, so this sync is the app's own call.
     const syncStatus = await CodePush.sync();
 
     expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
-    expect(onBinaryPatchResult).toHaveBeenCalledTimes(1);
-    expect(onBinaryPatchResult).toHaveBeenCalledWith(LABEL, APPLIED);
+    expect(onUpdateArchiveResult).toHaveBeenCalledTimes(1);
+    expect(onUpdateArchiveResult).toHaveBeenCalledWith(LABEL, APPLIED);
   });
 
   it('tells only the callback of the sync call when one was passed to it', async () => {
@@ -374,11 +413,11 @@ describe('the binary patch result of a sync', () => {
     const passedToTheSyncCall = jest.fn();
     const { CodePush } = loadCodePush({
       releaseHistory: patchedRelease(),
-      binaryPatchResult: APPLIED,
-      onBinaryPatchResult: registeredOnTheDecorator,
+      updateArchiveResult: APPLIED,
+      onUpdateArchiveResult: registeredOnTheDecorator,
     });
 
-    const syncStatus = await CodePush.sync({ onBinaryPatchResult: passedToTheSyncCall });
+    const syncStatus = await CodePush.sync({ onUpdateArchiveResult: passedToTheSyncCall });
 
     expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
     expect(passedToTheSyncCall).toHaveBeenCalledTimes(1);
@@ -388,65 +427,81 @@ describe('the binary patch result of a sync', () => {
 
   it('says nothing about a download that had no patch to try', async () => {
     const { CodePush } = loadCodePush({ releaseHistory: fullOnlyRelease() });
-    const onBinaryPatchResult = jest.fn();
+    const onUpdateArchiveResult = jest.fn();
 
-    const syncStatus = await CodePush.sync({ onBinaryPatchResult });
+    const syncStatus = await CodePush.sync({ onUpdateArchiveResult });
 
     expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
-    expect(onBinaryPatchResult).not.toHaveBeenCalled();
+    expect(onUpdateArchiveResult).not.toHaveBeenCalled();
   });
 
   it('installs the update even when the callback throws', async () => {
     const { CodePush, nativeBridge } = loadCodePush({
       releaseHistory: patchedRelease(),
-      binaryPatchResult: APPLIED,
+      updateArchiveResult: APPLIED,
     });
-    const onBinaryPatchResult = jest.fn(() => {
+    const onUpdateArchiveResult = jest.fn(() => {
       throw new Error('the telemetry the app sends the result to is down');
     });
 
-    const syncStatus = await CodePush.sync({ onBinaryPatchResult });
+    const syncStatus = await CodePush.sync({ onUpdateArchiveResult });
 
     expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
-    expect(onBinaryPatchResult).toHaveBeenCalledTimes(1);
+    expect(onUpdateArchiveResult).toHaveBeenCalledTimes(1);
     expect(nativeBridge.installUpdate).toHaveBeenCalledTimes(1);
   });
 
   it('keeps the result out of the package the update is installed from', async () => {
     const { CodePush, nativeBridge } = loadCodePush({
       releaseHistory: patchedRelease(),
-      binaryPatchResult: APPLIED,
+      updateArchiveResult: APPLIED,
     });
 
-    await CodePush.sync({ onBinaryPatchResult: jest.fn() });
+    await CodePush.sync({ onUpdateArchiveResult: jest.fn() });
 
     const installedPackage = installedPackageMetadata(nativeBridge);
     expect(installedPackage).toMatchObject({ label: LABEL, packageHash: PACKAGE_HASH });
-    expect(installedPackage).not.toHaveProperty('binaryPatchResult');
+    expect(installedPackage).not.toHaveProperty('updateArchiveResult');
   });
 
   it('installs the same update, without the result, when no callback is registered', async () => {
     const { CodePush, nativeBridge } = loadCodePush({
       releaseHistory: patchedRelease(),
-      binaryPatchResult: FELL_BACK,
+      updateArchiveResult: FELL_BACK,
     });
 
     const syncStatus = await CodePush.sync();
 
     expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
-    expect(installedPackageMetadata(nativeBridge)).not.toHaveProperty('binaryPatchResult');
+    expect(installedPackageMetadata(nativeBridge)).not.toHaveProperty('updateArchiveResult');
+  });
+
+  it('resolves a direct download even when the callback passed to it throws', async () => {
+    const { CodePush } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      updateArchiveResult: APPLIED,
+    });
+    const onUpdateArchiveResult = jest.fn(() => {
+      throw new Error('the telemetry the app sends the result to is down');
+    });
+
+    const remotePackage = await CodePush.checkForUpdate();
+    const localPackage = await remotePackage.download(undefined, onUpdateArchiveResult);
+
+    expect(onUpdateArchiveResult).toHaveBeenCalledTimes(1);
+    expect(localPackage).toMatchObject({ label: LABEL, packageHash: PACKAGE_HASH });
   });
 
   it('leaves the result off the package a download resolves with', async () => {
     const { CodePush } = loadCodePush({
       releaseHistory: patchedRelease(),
-      binaryPatchResult: APPLIED,
+      updateArchiveResult: APPLIED,
     });
 
     const remotePackage = await CodePush.checkForUpdate();
     const localPackage = await remotePackage.download();
 
     expect(localPackage).toMatchObject({ label: LABEL, packageHash: PACKAGE_HASH });
-    expect(localPackage).not.toHaveProperty('binaryPatchResult');
+    expect(localPackage).not.toHaveProperty('updateArchiveResult');
   });
 });

package/src/package-mixins.js

@@ -1,3 +1,5 @@
+const log = require("./logging");
+
 // This function is used to augment remote and local
 // package objects with additional functionality/properties
 // beyond what is included in the metadata sent by the server.
@@ -6,13 +8,14 @@ module.exports = (NativeCodePush) => {
     return {
       /**
        * @param downloadProgressCallback Called as the archive is received.
-       * @param binaryPatchResultCallback Called with `{ status, fallbackReason?, applyDurationMs }`
-       *        when the update was published with a binary patch, so that the app can observe
-       *        how the patch went. It says nothing about whether the download succeeded - a
-       *        patch that could not be applied is reported here and the update is downloaded
-       *        in full - and it is the only place the result is ever available.
+       * @param updateArchiveResultCallback Called with `{ status, archive, fallbackReason?,
+       *        totalDurationMs, attempts }` when the update was published with a binary patch,
+       *        so that the app can observe how the archives went. It says nothing about whether
+       *        the download succeeded - archives that could not be applied are reported here
+       *        and the update is downloaded in full - and it is the only place the result is
+       *        ever available.
        */
-      async download(downloadProgressCallback, binaryPatchResultCallback) {
+      async download(downloadProgressCallback, updateArchiveResultCallback) {
         if (!this.downloadUrl) {
           throw new Error("Cannot download an update without a download url");
         }
@@ -33,14 +36,20 @@ module.exports = (NativeCodePush) => {
 
           const downloadResult = await NativeCodePush.downloadUpdate(updatePackageCopy, !!downloadProgressCallback);
 
-          // The patch result describes the download that just happened, not the update it
+          // The archive result describes the download that just happened, not the update it
           // delivered, and the package is handed around as the update's metadata from here
           // on - it is even written back to the native side on install. So the result is
           // taken off the package and reported on its own, leaving the package exactly what
           // the native side saved.
-          const { binaryPatchResult, ...downloadedPackage } = downloadResult ?? {};
-          if (binaryPatchResult) {
-            binaryPatchResultCallback?.(binaryPatchResult);
+          const { updateArchiveResult, ...downloadedPackage } = downloadResult ?? {};
+          if (updateArchiveResult && updateArchiveResultCallback) {
+            // The result is an observation, so an observer that throws must not turn a
+            // downloaded update into a failed one.
+            try {
+              updateArchiveResultCallback(updateArchiveResult);
+            } catch (error) {
+              log(`The update archive result callback threw: ${error?.message ?? error}`);
+            }
           }
 
           return { ...downloadedPackage, ...local };

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

@@ -36,9 +36,11 @@ export interface ReleaseInfo {
     binaryPatchDownloadUrl?: string;
     /**
      * URLs of patch archives that also carry an asset diff, keyed by the packageHash of the
-     * release each archive was diffed against. A client whose installed update matches one of
-     * these keys downloads that archive instead of `binaryPatchDownloadUrl`; every other client
-     * ignores this field. Only present when the release was published with asset diff archives.
+     * release each archive was diffed against. Give a key to every release worth diffing
+     * against: a client whose installed update matches one downloads that archive first, and
+     * every other client ignores this field. Only present when the release was published with
+     * asset diff archives. `UpdateArchiveResult` describes what a client does with one it
+     * cannot use.
      */
     diffPackages?: Record<string, string>;
     packageHash: string;
@@ -54,6 +56,13 @@ export interface UpdateCheckResponse {
      * that cannot use it downloads the full update from `download_url` instead.
      */
     binary_patch_download_url?: string;
+    /**
+     * The URL of the asset diff archive built against the update the client is running.
+     * It is only present when the release publishes a diff against exactly that update, and
+     * it accompanies `binary_patch_download_url` rather than replacing it: a response can
+     * carry both. `UpdateArchiveResult` describes the order the client tries them in.
+     */
+    asset_diff_download_url?: string;
     description?: string;
     is_available: boolean;
     is_disabled?: boolean;
@@ -71,7 +80,7 @@ export interface UpdateCheckResponse {
  * instead. These are the words every platform's applier reports, so a rollout can be
  * judged by them whichever platform it is running on.
  */
-export type BinaryPatchFallbackReason =
+export type ArchiveFallbackReason =
     /** The bundle inside the app binary could not be opened or read. */
     | "base_bundle_unavailable"
     /** The bundle inside the app binary is not the one the patch was computed against. */
@@ -84,30 +93,88 @@ export type BinaryPatchFallbackReason =
     | "patch_apply_failed"
     /** The restored bundle is not the one the manifest promised. */
     | "target_verification_failed"
+    /** The asset diff could not be merged with the installed update it was built against. */
+    | "asset_merge_failed"
     /** The update restored from the patch did not pass the checks that follow the restore. */
     | "package_verification_failed";
 
 /**
- * How installing an update from its binary patch archive went.
+ * The archives on the patch path; the full archive is not one of them. There are two: the
+ * patch archive built against the app binary's bundle, and an asset diff archive that
+ * additionally leaves out the assets an installed base update already holds.
+ */
+export type UpdateArchive = "binary-patch" | "asset-diff";
+
+/**
+ * One archive tried on the patch path: which archive it was, how long the try took, and,
+ * when it was given up on, why.
+ */
+export interface UpdateArchiveAttempt {
+    archive: UpdateArchive;
+
+    /**
+     * Why this archive was given up on. Absent for the attempt the downloaded update came
+     * from, and also when the attempt ended in an error none of the appliers has a word
+     * for.
+     */
+    fallbackReason?: ArchiveFallbackReason;
+
+    /**
+     * How long this attempt ran, in milliseconds, whichever way it ended: from the archive
+     * starting to download to the try being finished with.
+     */
+    durationMs: number;
+
+    /**
+     * How long the applier took to rebuild the bundle from this archive's patch, in
+     * milliseconds. Absent when the attempt ended before the bundle was restored.
+     */
+    applyDurationMs?: number;
+}
+
+/**
+ * Which of an update's patch archives the download came from, and what the patch path did
+ * on the way there. It is reported once the update has been downloaded and before the
+ * `LocalPackage` it resolved to is installed, so nothing here speaks to how installing goes.
  */
-export interface BinaryPatchResult {
+export interface UpdateArchiveResult {
     /**
-     * Whether the update was installed from its patch archive, or had to be downloaded in
-     * full instead. A fallback is not an error: the update is installed either way.
+     * Whether one of the update's patch archives produced it, or the full archive had to be
+     * downloaded instead. A fallback is not an error: the update arrives either way.
      */
     status: "applied" | "fallback";
 
     /**
-     * Why the full archive had to be downloaded. Absent when the patch was applied, and
-     * also when the attempt ended in an error none of the appliers has a word for.
+     * The archive of the last attempt: the one the downloaded update came from when a patch
+     * archive produced it, and the last one given up on when none did.
+     */
+    archive: UpdateArchive;
+
+    /**
+     * Why the full archive had to be downloaded: the reason the last attempt ended in.
+     * Absent when a patch archive produced the update, and also when the attempt ended in
+     * an error none of the appliers has a word for.
      */
-    fallbackReason?: BinaryPatchFallbackReason;
+    fallbackReason?: ArchiveFallbackReason;
 
     /**
-     * How long the patch work took, in milliseconds: applying the patch when it was
-     * applied, and the whole attempt when it was given up on.
+     * How long the whole patch path took, in milliseconds: from the first archive starting
+     * to download to the last attempt being finished with. The full download that follows a
+     * fallback is not part of it, because that is not time the patch path spent.
      */
-    applyDurationMs: number;
+    totalDurationMs: number;
+
+    /**
+     * Every archive that was tried, in the order it was tried. The full archive is never
+     * among them, because it is downloaded only once the patch path has given up.
+     *
+     * Most downloads leave a single entry. A second one appears when the asset diff failed
+     * after its bundle was restored - an asset-side failure the patch archive is not
+     * implicated in - and the patch archive was tried in its place. A diff that fails before
+     * its bundle is restored skips the patch archive instead, because both archives carry the
+     * same bundle patch and it would fail the same way.
+     */
+    attempts: UpdateArchiveAttempt[];
 }
 
 export interface CodePushOptions extends SyncOptions {
@@ -250,8 +317,12 @@ export interface RemotePackage extends Package {
      * Downloads the available update from the CodePush service.
      *
      * @param downloadProgressCallback An optional callback that allows tracking the progress of the update while it is being downloaded.
+     * @param updateArchiveResultCallback An optional callback for observing which archive an update published with a binary patch was downloaded from. It is called once when the download had such an archive to try, and only after that download has succeeded; what it says nothing about is whether installing the resolved `LocalPackage` succeeds. An archive that could not be applied is reported here and the update is downloaded in full.
      */
-    download(downloadProgressCallback?: DownloadProgressCallback): Promise<LocalPackage>;
+    download(
+        downloadProgressCallback?: DownloadProgressCallback,
+        updateArchiveResultCallback?: (result: UpdateArchiveResult) => void,
+    ): Promise<LocalPackage>;
 
     /**
      * The URL at which the package is available for download.
@@ -265,6 +336,15 @@ export interface RemotePackage extends Package {
      * package is downloaded in full from `downloadUrl`.
      */
     binaryPatchDownloadUrl?: string;
+
+    /**
+     * The URL of the asset diff archive built against the update this app is running.
+     * It is only present when the release publishes a diff against exactly that update, and
+     * it accompanies `binaryPatchDownloadUrl` rather than replacing it, so a package can hold
+     * both. `download` chooses between them and reports the choice as an
+     * `UpdateArchiveResult`.
+     */
+    assetDiffDownloadUrl?: string;
 }
 
 export interface SyncOptions {
@@ -297,8 +377,8 @@ export interface SyncOptions {
 
     /**
      * An "options" object used to determine whether a confirmation dialog should be displayed to the end user when an update is available,
-     * and if so, what strings to use. Defaults to null, which has the effect of disabling the dialog completely. Setting this to any truthy
-     * value will enable the dialog with the default strings, and passing an object to this parameter allows enabling the dialog as well as
+     * and if so, what strings to use. Defaults to null, which has the effect of disabling the dialog completely. Setting this to `true`
+     * will enable the dialog with the default strings, and passing an object to this parameter allows enabling the dialog as well as
      * overriding one or more of the default strings.
      */
     updateDialog?: UpdateDialog | true;
@@ -306,24 +386,25 @@ export interface SyncOptions {
     /**
      * The rollback retry mechanism allows the application to attempt to reinstall an update that was previously rolled back (with the restrictions
      * specified in the options). It is an "options" object used to determine whether a rollback retry should occur, and if so, what settings to use
-     * for the rollback retry. This defaults to null, which has the effect of disabling the retry mechanism. Setting this to any truthy value will enable
-     * the retry mechanism with the default settings, and passing an object to this parameter allows enabling the rollback retry as well as overriding
-     * one or more of the default values.
+     * for the rollback retry. This defaults to null, which has the effect of disabling the retry mechanism. Passing an object to this parameter enables
+     * the rollback retry: an empty object retries with the default settings, and each value the object specifies overrides the default for that
+     * setting.
      */
     rollbackRetryOptions?: RollbackRetryOptions;
 
     /**
-     * An optional callback for observing how an update published with a binary patch was
-     * installed: whether it came from the patch archive, why it did not when it did not, and
-     * how long the patch work took. It is called once per download that had a patch to try,
-     * with the label of the release being installed.
+     * An optional callback for observing which archive an update published with a binary
+     * patch was downloaded from: whether it came from one of its patch archives, why each
+     * archive that was given up on was, and how long the patch work took. It is called once
+     * per download that had such an archive to try, after that download has succeeded and
+     * before the update is installed, with the label of the release it carries.
      *
      * Purely for observation. The library neither stores the result nor sends it anywhere -
      * an app that wants it in its telemetry sends it itself - and nothing about the update
      * depends on the callback: registering none changes nothing, and one that throws is
-     * logged and does not fail the install.
+     * logged and does not fail the download it is reporting on.
      */
-    onBinaryPatchResult?: (label: string, result: BinaryPatchResult) => void;
+    onUpdateArchiveResult?: (label: string, result: UpdateArchiveResult) => void;
 
     /**
      * Specifies whether to ignore the update if the installation fails.
@@ -583,13 +664,13 @@ declare namespace CodePush {
         RUNNING,
 
         /**
-         * Indicates than an update has been installed, but the
+         * Indicates that an update has been installed, but the
          * app hasn't been restarted yet in order to apply it.
          */
         PENDING,
 
         /**
-         * Indicates than an update represents the latest available
+         * Indicates that an update represents the latest available
          * release, and can be either currently running or pending.
          */
         LATEST
@@ -625,7 +706,7 @@ declare namespace CodePush {
         ON_APP_RESUME,
 
         /**
-         * Don't automatically check for updates, but only do it when codePush.sync() is manully called inside app code.
+         * Don't automatically check for updates, but only do it when codePush.sync() is manually called inside app code.
          */
         MANUAL
     }