@capgo/capacitor-updater 8.46.3 → 8.47.1

package/dist/esm/definitions.d.ts

@@ -254,6 +254,16 @@ declare module '@capacitor/cli' {
              * @since 7.20.0
              */
             allowManualBundleError?: boolean;
+            /**
+             * Allow JavaScript to start a native preview session and temporarily request updates for another app id.
+             * This is intended for trusted container apps that implement Expo Go-style preview flows.
+             *
+             * Only available for Android and iOS.
+             *
+             * @default false
+             * @since 8.47.0
+             */
+            allowPreview?: boolean;
             /**
              * Persist the customId set through {@link CapacitorUpdaterPlugin.setCustomId} across app restarts.
              *
@@ -500,6 +510,24 @@ export interface CapacitorUpdaterPlugin {
      * @throws {Error} When there is no index.html file inside the bundle folder.
      */
     set(options: BundleId): Promise<void>;
+    /**
+     * Start a temporary preview/testing session.
+     *
+     * This stores the currently active bundle as the pending fallback, enables the
+     * native shake menu, and makes the next applied bundle show a native notice
+     * explaining that shaking the device can reload or leave the preview.
+     * Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
+     * When `appId` is provided, the preview session temporarily uses that app id
+     * for update checks until the user leaves the preview. Native updater stats are
+     * skipped while the preview session is active.
+     *
+     * Use this before calling {@link set} for Expo Go-style preview flows.
+     *
+     * @param options Optional preview session options.
+     * @returns {Promise<void>} Resolves when preview session state is prepared.
+     * @since 8.47.0
+     */
+    startPreviewSession(options?: StartPreviewSessionOptions): Promise<void>;
     /**
      * Delete a bundle from local storage to free up disk space.
      *
@@ -749,6 +777,53 @@ export interface CapacitorUpdaterPlugin {
      * @since 4.0.0
      */
     getLatest(options?: GetLatestOptions): Promise<LatestVersion>;
+    /**
+     * Return the manifest entries that still need to be downloaded for a partial update.
+     *
+     * Pass the result from {@link getLatest} directly when it includes a `manifest`.
+     * The native plugin compares each manifest entry with the files already available
+     * in the builtin bundle and the local delta cache. Entries that can be reused are
+     * omitted from the returned `missing` list.
+     *
+     * For encrypted manifests, pass the `sessionKey` returned by {@link getLatest} so
+     * encrypted file hashes can be checked against local files.
+     *
+     * ```typescript
+     * const latest = await CapacitorUpdater.getLatest();
+     * const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
+     * ```
+     *
+     * @param options A {@link GetMissingBundleFilesOptions} object, or a {@link LatestVersion} response containing `manifest`.
+     * @returns {Promise<GetMissingBundleFilesResult>} The manifest entries that require network download.
+     * @throws {Error} If the manifest is missing or invalid.
+     * @since 8.47.0
+     */
+    getMissingBundleFiles(options: GetMissingBundleFilesOptions): Promise<GetMissingBundleFilesResult>;
+    /**
+     * Estimate the download size for manifest entries before downloading them.
+     *
+     * This method sends the provided manifest entries to the Capgo update endpoint
+     * once and reads the stored manifest `file_size` metadata. It does not perform
+     * per-file `HEAD` requests from the app.
+     *
+     * Use this after {@link getMissingBundleFiles} to estimate only the files this
+     * device still needs:
+     *
+     * ```typescript
+     * const latest = await CapacitorUpdater.getLatest();
+     * const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
+     * const size = await CapacitorUpdater.getBundleDownloadSize({
+     *   version: latest.version,
+     *   manifest: missing.missing,
+     * });
+     * ```
+     *
+     * @param options A {@link GetBundleDownloadSizeOptions} object containing manifest entries.
+     * @returns {Promise<GetBundleDownloadSizeResult>} Known byte totals and per-file size results.
+     * @throws {Error} If the manifest is missing or invalid.
+     * @since 8.47.0
+     */
+    getBundleDownloadSize(options: GetBundleDownloadSizeOptions): Promise<GetBundleDownloadSizeResult>;
     /**
      * Assign this device to a specific update channel at runtime.
      *
@@ -1615,6 +1690,128 @@ export interface ManifestEntry {
     file_hash: string | null;
     download_url: string | null;
 }
+export interface GetMissingBundleFilesOptions {
+    /**
+     * Manifest returned by {@link getLatest}. Passing the full {@link LatestVersion}
+     * response is supported because it contains this field.
+     *
+     * @since 8.47.0
+     */
+    manifest?: ManifestEntry[];
+    /**
+     * Target bundle version. Passing the full {@link LatestVersion} response is
+     * supported because it contains this field.
+     *
+     * @since 8.47.0
+     */
+    version?: string;
+    /**
+     * Session key returned by {@link getLatest}, required only when file hashes are encrypted.
+     *
+     * @since 8.47.0
+     */
+    sessionKey?: string;
+}
+export interface GetMissingBundleFilesResult {
+    /**
+     * Entries that are not available locally and need to be downloaded.
+     *
+     * @since 8.47.0
+     */
+    missing: ManifestEntry[];
+    /**
+     * Total entries in the provided manifest.
+     *
+     * @since 8.47.0
+     */
+    total: number;
+    /**
+     * Number of entries that need to be downloaded.
+     *
+     * @since 8.47.0
+     */
+    missingCount: number;
+    /**
+     * Number of entries that can be reused from builtin files or local cache.
+     *
+     * @since 8.47.0
+     */
+    reusableCount: number;
+}
+export interface GetBundleDownloadSizeOptions {
+    /**
+     * Manifest entries to estimate. Pass `missing.missing` from {@link getMissingBundleFiles}
+     * to estimate only the bytes this device still needs to download.
+     *
+     * @since 8.47.0
+     */
+    manifest?: ManifestEntry[];
+    /**
+     * Target bundle version. Pass `latest.version` when estimating files returned
+     * by {@link getLatest}.
+     *
+     * @since 8.47.0
+     */
+    version?: string;
+}
+export interface BundleFileSize {
+    /**
+     * File name from the manifest entry.
+     *
+     * @since 8.47.0
+     */
+    file_name: string | null;
+    /**
+     * File hash from the manifest entry.
+     *
+     * @since 8.47.0
+     */
+    file_hash: string | null;
+    /**
+     * Download URL from the manifest entry.
+     *
+     * @since 8.47.0
+     */
+    download_url: string | null;
+    /**
+     * Estimated bytes to download when the server exposes a size.
+     *
+     * @since 8.47.0
+     */
+    size?: number;
+    /**
+     * Error for this entry when the size could not be determined.
+     *
+     * @since 8.47.0
+     */
+    error?: string;
+}
+export interface GetBundleDownloadSizeResult {
+    /**
+     * Sum of all known file sizes in bytes.
+     *
+     * @since 8.47.0
+     */
+    totalSize: number;
+    /**
+     * Number of files with a known size.
+     *
+     * @since 8.47.0
+     */
+    knownFiles: number;
+    /**
+     * Number of files whose size could not be determined.
+     *
+     * @since 8.47.0
+     */
+    unknownFiles: number;
+    /**
+     * Per-file size results.
+     *
+     * @since 8.47.0
+     */
+    files: BundleFileSize[];
+}
 export interface LatestVersion {
     /**
      * Result of getLatest method
@@ -1671,6 +1868,20 @@ export interface LatestVersion {
      * @since 6.1
      */
     manifest?: ManifestEntry[];
+    /**
+     * Missing manifest entries for this device when {@link GetLatestOptions.includeBundleSize}
+     * is enabled.
+     *
+     * @since 8.47.0
+     */
+    missing?: GetMissingBundleFilesResult;
+    /**
+     * Estimated download size for missing manifest entries when
+     * {@link GetLatestOptions.includeBundleSize} is enabled.
+     *
+     * @since 8.47.0
+     */
+    downloadSize?: GetBundleDownloadSizeResult;
     /**
      * Optional link associated with this bundle version (e.g., release notes URL, changelog, GitHub release).
      * @since 7.35.0
@@ -1718,6 +1929,36 @@ export interface GetLatestOptions {
      * @default undefined
      */
     channel?: string;
+    /**
+     * Temporarily use another app id for this update check while using a trusted preview container.
+     * This only changes the app id sent by this request; it does not persist a preview session.
+     * Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
+     * @since 8.47.0
+     * @default undefined
+     */
+    appId?: string;
+    /**
+     * When true, the native plugin computes which manifest files are missing on
+     * this device and asks the Capgo update endpoint for their stored sizes before
+     * resolving {@link getLatest}.
+     *
+     * This adds one backend request only when the update response contains a
+     * manifest. It does not perform per-file network checks.
+     *
+     * @since 8.47.0
+     * @default false
+     */
+    includeBundleSize?: boolean;
+}
+export interface StartPreviewSessionOptions {
+    /**
+     * App id to use while the preview session is active.
+     * The previous app id is restored when leaving the preview session.
+     * Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
+     * @since 8.47.0
+     * @default undefined
+     */
+    appId?: string;
 }
 export interface AppReadyResult {
     bundle: BundleInfo;