@mpgd/cli 0.58.0 → 0.61.0

package/dist/play-internal-submission.js

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto';
 import { createReadStream, existsSync, statSync } from 'node:fs';
 import { inspectAndroidBundleSigner } from './android-bundle-signer.js';
+import { assertPlayReleaseConfirmed, assertPlayReleaseRequest, defaultPlayReleaseRequest, hashMappingFile, isPlayDraftAppRejection, isWellKnownPlayTrack, mergeNewPlayRelease, newPlayRelease, playReleaseNeedsConfirmation, } from './play-release-options.js';
 const sha256Pattern = /^[a-f0-9]{64}$/u;
 const editIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
-const trackName = 'internal';
 const bundleUploadTimeoutMs = 120_000;
 export class PlaySubmissionUncertainError extends Error {
     stage;
@@ -24,9 +24,45 @@ export async function submitVerifiedAndroidBundle(input) {
     const publisher = createServiceAccountPublisher(input.serviceAccountFile);
     return submitVerifiedAndroidBundleWithPublisher(input, publisher);
 }
+/** Verify the record and artifact, then describe the edit without calling Google Play. */
+export async function planVerifiedAndroidBundleSubmission(input) {
+    const request = input.release ?? defaultPlayReleaseRequest;
+    assertPlayReleaseRequest(request);
+    const versionCode = await preflight(input);
+    await assertMappingUnchanged(request);
+    return {
+        dryRun: true,
+        packageName: input.packageName,
+        track: request.track,
+        versionCode,
+        bundleSha256: input.record.artifactSha256,
+        release: newPlayRelease(request, input.record.releaseKey, versionCode),
+        ...(request.mappingFile === undefined || request.mappingSha256 === undefined ? {} : {
+            mapping: { file: request.mappingFile, sha256: request.mappingSha256 },
+        }),
+        requiresConfirmProduction: playReleaseNeedsConfirmation(request),
+        operations: [
+            'edits.insert',
+            'edits.bundles.list',
+            `edits.tracks.get ${request.track}`,
+            'edits.bundles.upload (skipped when the edit already has this version code)',
+            ...(request.mappingFile === undefined
+                ? [] : ['edits.deobfuscationfiles.upload proguard']),
+            `edits.tracks.update ${request.track} (other releases kept; a ${request.status === 'draft' ? 'draft replaces an older draft'
+                : 'new release replaces an in-progress or halted rollout'})`,
+            'edits.validate',
+            'edits.commit changesInReviewBehavior=ERROR_IF_IN_REVIEW',
+        ],
+    };
+}
 /** Internal injection point for credential-free SDK contract tests. */
 export async function submitVerifiedAndroidBundleWithPublisher(input, publisher, requestRootUrl) {
+    const request = input.release ?? defaultPlayReleaseRequest;
+    assertPlayReleaseRequest(request);
+    assertPlayReleaseConfirmed(request, input.confirmProduction === true);
+    const trackName = request.track;
     const versionCode = await preflight(input);
+    await assertMappingUnchanged(request);
     const expectedSha256 = input.record.artifactSha256;
     const packageName = input.packageName;
     if (input.resumeEditId !== undefined && !editIdPattern.test(input.resumeEditId)) {
@@ -35,14 +71,22 @@ export async function submitVerifiedAndroidBundleWithPublisher(input, publisher,
     input.signal?.throwIfAborted();
     let editId = input.resumeEditId ?? await publisher.insertEdit(packageName, input.signal);
     let freshEdit = input.resumeEditId === undefined;
-    if (input.resumeEditId === undefined) {
+    // A new edit is checkpointed after the read-only checks below and before
+    // anything is uploaded or committed, so a refused request leaves no edit to
+    // reconcile and can be retried with corrected options.
+    let editPersisted = input.resumeEditId !== undefined;
+    const persistEdit = async () => {
+        if (editPersisted) {
+            return;
+        }
         try {
             await input.onEditCreated?.(editId);
         }
         catch {
             throw new PlaySubmissionUncertainError('checkpoint', editId);
         }
-    }
+        editPersisted = true;
+    };
     let bundles;
     try {
         bundles = await publisher.listBundles(packageName, editId, input.signal);
@@ -52,39 +96,73 @@ export async function submitVerifiedAndroidBundleWithPublisher(input, publisher,
             throw error;
         }
         // A successful commit may have invalidated the old edit while its response
-        // was lost. Open a new snapshot solely to inspect the live internal track.
+        // was lost. Open a new snapshot solely to inspect the live track.
         editId = await publisher.insertEdit(packageName, input.signal);
         freshEdit = true;
-        try {
-            await input.onEditCreated?.(editId);
-        }
-        catch {
-            throw new PlaySubmissionUncertainError('checkpoint', editId);
-        }
+        editPersisted = false;
+        await persistEdit();
         bundles = await publisher.listBundles(packageName, editId, input.signal);
     }
     let existing = findVersionBundle(bundles, versionCode, expectedSha256);
-    const currentTrack = await getInternalTrack(publisher, packageName, editId, input.signal);
+    const currentTrack = await getTrackOrEmpty(publisher, packageName, editId, trackName, input.signal, !isWellKnownPlayTrack(trackName));
+    const release = newPlayRelease(request, input.record.releaseKey, versionCode);
+    const commit = async (status) => {
+        const committed = await validateAndCommit({
+            publisher, packageName, editId, trackName, versionCode, release, status,
+            currentTrack, ...(input.signal === undefined ? {} : { signal: input.signal }),
+            ...(input.onDraftAppFallback === undefined ? {} : {
+                onDraftAppFallback: input.onDraftAppFallback,
+            }),
+        });
+        return result(input, trackName, editId, versionCode, false, committed);
+    };
     if (hasVersion(currentTrack.releases, versionCode)) {
         if (existing === undefined) {
-            throw new Error('Google Play internal track has this version without matching bundle bytes.');
+            throw new Error(`Google Play ${trackName} track has this version without matching bundle bytes.`);
+        }
+        // Our own edit (resumed), or the live track after that edit was committed
+        // and its response lost (a resume that found the edit gone), may hold this
+        // release as a draft-app fallback.
+        const fallbackDraft = request.status !== 'draft' && (!freshEdit
+            ? hasVersionWithStatus(currentTrack.releases, versionCode, 'draft')
+            : input.resumeEditId !== undefined && (currentTrack.releases ?? []).some((item) => item.status === 'draft' && item.name === input.record.releaseKey
+                && item.versionCodes?.includes(String(versionCode))));
+        if (!hasVersionWithStatus(currentTrack.releases, versionCode, request.status)
+            && !fallbackDraft) {
+            throw new Error(`Google Play ${trackName} track version is not ${request.status}; inspect it before resubmitting.`);
         }
-        if (!hasCompletedVersion(currentTrack.releases, versionCode)) {
-            throw new Error('Google Play internal track version is not completed; inspect it before resubmitting.');
+        const observedStatus = fallbackDraft
+            && !hasVersionWithStatus(currentTrack.releases, versionCode, request.status)
+            ? 'draft' : request.status;
+        const observed = (currentTrack.releases ?? []).find((item) => item.status === observedStatus
+            && item.versionCodes?.includes(String(versionCode)));
+        if (observed !== undefined && !matchesRequestedRelease(observed, request, observedStatus)) {
+            throw new Error(`Google Play ${trackName} track already has this version with another rollout fraction `
+                + 'or other release notes; change it with "mpgd deploy rollout" or inspect it.');
         }
         if (freshEdit) {
-            return result(input, editId, versionCode, true);
+            await persistEdit();
+            if (request.mappingFile !== undefined) {
+                // The release may have reached Play without this mapping: add it to
+                // the version in an edit of its own.
+                await uploadMapping(publisher, request, packageName, editId, versionCode, input.signal, requestRootUrl);
+                return { ...await commit(observedStatus), alreadyCommitted: true };
+            }
+            return result(input, trackName, editId, versionCode, true, {
+                status: observedStatus,
+                draftAppFallback: observedStatus !== request.status,
+            });
         }
         // A resumed edit sees its own uncommitted track. Publish it before success.
-        await publisher.validateEdit(packageName, editId, input.signal);
-        try {
-            await publisher.commitEdit(packageName, editId, input.signal);
-        }
-        catch {
-            throw new PlaySubmissionUncertainError('commit', editId);
-        }
-        return result(input, editId, versionCode, false);
+        await uploadMapping(publisher, request, packageName, editId, versionCode, input.signal, requestRootUrl);
+        return commit(observedStatus);
+    }
+    if (playReleaseStartsRollout(request.status, currentTrack.releases)) {
+        // Play Console: "Rollout percentage options are unavailable for a first release."
+        throw new Error(`Google Play ${trackName} has no completed release yet, so a staged rollout cannot start; `
+            + 'release it with --status completed (or draft) first.');
     }
+    await persistEdit();
     if (existing === undefined) {
         try {
             const uploaded = await publisher.uploadBundle({
@@ -113,23 +191,69 @@ export async function submitVerifiedAndroidBundleWithPublisher(input, publisher,
             }
         }
     }
-    const release = {
-        name: input.record.releaseKey,
-        status: 'completed',
-        versionCodes: [String(versionCode)],
-    };
+    await uploadMapping(publisher, request, packageName, editId, versionCode, input.signal, requestRootUrl);
     const desired = {
         track: trackName,
-        releases: [...(currentTrack.releases ?? []), release],
+        releases: mergeNewPlayRelease(currentTrack.releases, release).releases,
     };
+    await updateTrackChecked(publisher, packageName, editId, trackName, desired, versionCode, request.status, input.signal);
+    return commit(request.status);
+}
+async function validateAndCommit(input) {
+    const { publisher, packageName, editId } = input;
+    try {
+        await publisher.validateEdit(packageName, editId, input.signal);
+    }
+    catch (error) {
+        if (input.status !== 'draft' && isPlayDraftAppRejection(error)) {
+            return commitDraftFallback(input);
+        }
+        if (isDefinitiveHttpError(error)) {
+            throw error;
+        }
+        throw new PlaySubmissionUncertainError('validate', editId);
+    }
+    try {
+        await publisher.commitEdit(packageName, editId, input.signal);
+        return { status: input.status, draftAppFallback: input.status === 'draft'
+                && input.release.status !== 'draft' };
+    }
+    catch (error) {
+        // A definitive draft-app rejection means nothing was committed.
+        if (input.status !== 'draft' && isPlayDraftAppRejection(error)) {
+            return commitDraftFallback(input);
+        }
+        // Inserting a new edit invalidates the first edit for this API user. A
+        // failed commit response cannot safely be reconciled by creating one.
+        throw new PlaySubmissionUncertainError('commit', editId);
+    }
+}
+/**
+ * Play accepts only draft releases until an app's first release is rolled out
+ * from Play Console. Re-stage the same version as a draft in the same edit and
+ * commit that, so the operator can roll it out from the console.
+ */
+async function commitDraftFallback(input) {
+    input.onDraftAppFallback?.(input.trackName);
+    const { userFraction: _fraction, ...withoutFraction } = input.release;
+    const draft = { ...withoutFraction, status: 'draft' };
+    const others = (input.currentTrack.releases ?? []).filter((release) => !release.versionCodes?.includes(String(input.versionCode)));
+    await updateTrackChecked(input.publisher, input.packageName, input.editId, input.trackName, {
+        track: input.trackName,
+        releases: mergeNewPlayRelease(others, draft).releases,
+    }, input.versionCode, 'draft', input.signal);
+    await validateAndCommit({ ...input, status: 'draft' });
+    return { status: 'draft', draftAppFallback: true };
+}
+async function updateTrackChecked(publisher, packageName, editId, trackName, desired, versionCode, status, signal) {
     try {
-        await publisher.updateTrack(packageName, editId, desired, input.signal);
+        await publisher.updateTrack(packageName, editId, desired, signal);
     }
     catch (error) {
         let applied;
         try {
-            const observed = await getInternalTrack(publisher, packageName, editId, input.signal);
-            applied = hasCompletedVersion(observed.releases, versionCode);
+            const observed = await getTrackOrEmpty(publisher, packageName, editId, trackName, signal);
+            applied = hasVersionWithStatus(observed.releases, versionCode, status);
         }
         catch {
             throw new PlaySubmissionUncertainError('track-update', editId);
@@ -138,24 +262,61 @@ export async function submitVerifiedAndroidBundleWithPublisher(input, publisher,
             throw error;
         }
     }
+}
+async function uploadMapping(publisher, request, packageName, editId, versionCode, signal, requestRootUrl) {
+    if (request.mappingFile === undefined) {
+        return;
+    }
+    // Re-uploading replaces the edit's mapping for this version code, so a lost
+    // response is safe to retry on the same edit.
     try {
-        await publisher.validateEdit(packageName, editId, input.signal);
+        await publisher.uploadDeobfuscationFile({
+            packageName,
+            editId,
+            versionCode,
+            mappingFile: request.mappingFile,
+            timeoutMs: bundleUploadTimeoutMs,
+            ...(signal === undefined ? {} : { signal }),
+            ...(requestRootUrl === undefined ? {} : { requestRootUrl }),
+        });
     }
     catch (error) {
         if (isDefinitiveHttpError(error)) {
             throw error;
         }
-        throw new PlaySubmissionUncertainError('validate', editId);
+        throw new PlaySubmissionUncertainError('deobfuscation-upload', editId);
     }
-    try {
-        await publisher.commitEdit(packageName, editId, input.signal);
-        return result(input, editId, versionCode, false);
+}
+async function assertMappingUnchanged(request) {
+    if (request.mappingFile !== undefined
+        && await hashMappingFile(request.mappingFile) !== request.mappingSha256) {
+        throw new Error('R8 mapping file changed after the release request was created.');
     }
-    catch {
-        // Inserting a new edit invalidates the first edit for this API user. A
-        // failed commit response cannot safely be reconciled by creating one.
-        throw new PlaySubmissionUncertainError('commit', editId);
+}
+/**
+ * The release already on the track matches what this request would create:
+ * the rollout fraction (a draft-app fallback has none) and, when given, the
+ * release notes in any order.
+ */
+export function matchesRequestedRelease(observed, request, observedStatus) {
+    const fraction = typeof observed.userFraction === 'number' ? observed.userFraction : undefined;
+    if (observedStatus === request.status && fraction !== request.userFraction) {
+        return false;
+    }
+    if (request.releaseNotes === undefined) {
+        return true;
     }
+    const key = (language, text) => JSON.stringify([language ?? '', text ?? '']);
+    const observedNotes = (observed.releaseNotes ?? []).map((note) => key(note.language, note.text))
+        .sort();
+    const wanted = request.releaseNotes.map((note) => key(note.language, note.text)).sort();
+    return observedNotes.length === wanted.length
+        && observedNotes.every((note, index) => note === wanted[index]);
+}
+/** A staged rollout needs a completed release on the track to stage over. */
+function playReleaseStartsRollout(status, releases) {
+    return status === 'inProgress'
+        && !(releases ?? []).some((release) => release.status === 'completed');
 }
 async function preflight(input) {
     input.signal?.throwIfAborted();
@@ -195,25 +356,29 @@ function findVersionBundle(bundles, versionCode, sha256) {
     }
     return sameVersion;
 }
-async function getInternalTrack(publisher, packageName, editId, signal) {
+async function getTrackOrEmpty(publisher, packageName, editId, trackName, signal, mustExist = false) {
     try {
-        return await publisher.getTrack(packageName, editId, signal);
+        return await publisher.getTrack(packageName, editId, trackName, signal);
     }
     catch (error) {
         if (isHttpStatus(error, 404)) {
+            if (mustExist) {
+                throw new Error(`Google Play has no closed-testing track named "${trackName}"; create it in Play `
+                    + 'Console or check the name.');
+            }
             return { track: trackName, releases: [] };
         }
         throw error;
     }
 }
-function isHttpStatus(error, status) {
+export function isHttpStatus(error, status) {
     if (typeof error !== 'object' || error === null) {
         return false;
     }
     const value = error;
     return value.code === status || value.response?.status === status;
 }
-function isDefinitiveHttpError(error) {
+export function isDefinitiveHttpError(error) {
     if (typeof error !== 'object' || error === null) {
         return false;
     }
@@ -230,16 +395,18 @@ function isDefinitiveHttpError(error) {
 function hasVersion(releases, versionCode) {
     return releases?.some((release) => release.versionCodes?.includes(String(versionCode))) ?? false;
 }
-function hasCompletedVersion(releases, versionCode) {
-    return releases?.some((release) => release.status === 'completed'
+function hasVersionWithStatus(releases, versionCode, status) {
+    return releases?.some((release) => release.status === status
         && release.versionCodes?.includes(String(versionCode))) ?? false;
 }
-function result(input, editId, versionCode, alreadyCommitted) {
+function result(input, trackName, editId, versionCode, alreadyCommitted, committed) {
     return {
         status: 'committed',
         packageName: input.packageName,
         editId,
         track: trackName,
+        releaseStatus: committed.status,
+        draftAppFallback: committed.draftAppFallback,
         versionCode,
         bundleSha256: input.record.artifactSha256,
         alreadyCommitted,

package/dist/play-publisher-port.d.ts

@@ -3,10 +3,22 @@ export interface PlayBundle {
   readonly versionCode?: number | null;
   readonly sha256?: string | null;
 }
+/** Android Publisher v3 `LocalizedText`: a BCP-47 language tag and its text. */
+export interface PlayLocalizedText {
+  readonly language?: string | null | undefined;
+  readonly text?: string | null | undefined;
+}
+/**
+* Android Publisher v3 `Release`. Releases read from Play keep every field Play
+* returned (for example `countryTargeting`), so a track update that sends them
+* back leaves them unchanged.
+*/
 export interface PlayTrackRelease {
   readonly name?: string | null | undefined;
   readonly status?: string | null | undefined;
   readonly versionCodes?: readonly string[] | null | undefined;
+  readonly userFraction?: number | null | undefined;
+  readonly releaseNotes?: readonly PlayLocalizedText[] | null | undefined;
 }
 export interface PlayTrack {
   readonly track?: string | null | undefined;
@@ -23,8 +35,21 @@ export interface PlayPublisher {
     readonly requestRootUrl?: string;
     readonly signal?: AbortSignal;
   }): Promise<PlayBundle>;
-  getTrack(packageName: string, editId: string, signal?: AbortSignal): Promise<PlayTrack>;
+  /** `edits.deobfuscationfiles.upload` with type `proguard` (an R8/ProGuard mapping). */
+  uploadDeobfuscationFile(input: {
+    readonly packageName: string;
+    readonly editId: string;
+    readonly versionCode: number;
+    readonly mappingFile: string;
+    readonly timeoutMs: number;
+    readonly requestRootUrl?: string;
+    readonly signal?: AbortSignal;
+  }): Promise<void>;
+  getTrack(packageName: string, editId: string, track: string, signal?: AbortSignal): Promise<PlayTrack>;
+  /** Updates the track named by `track.track`. */
   updateTrack(packageName: string, editId: string, track: PlayTrack, signal?: AbortSignal): Promise<void>;
   validateEdit(packageName: string, editId: string, signal?: AbortSignal): Promise<void>;
   commitEdit(packageName: string, editId: string, signal?: AbortSignal): Promise<void>;
+  /** Discards an uncommitted edit (`edits.delete`), used after a read-only dry run. */
+  deleteEdit(packageName: string, editId: string, signal?: AbortSignal): Promise<void>;
 }

package/dist/play-release-options.d.ts

@@ -0,0 +1,97 @@
+import type { PlayTrackRelease } from './play-publisher-port.js';
+/**
+* Android Publisher v3 `Release.status` values the kit writes. `halted` is set
+* only on an existing rollout (`mpgd deploy rollout --action halt`): a new
+* bundle cannot start out halted.
+* https://developers.google.com/android-publisher/api-ref/rest/v3/edits.tracks#status
+*/
+export type PlayReleaseStatus = 'draft' | 'completed' | 'inProgress' | 'halted';
+export type PlayNewReleaseStatus = Exclude<PlayReleaseStatus, 'halted'>;
+/** The kit's original destination; Play's tracks guide also lists this track as `qa`. */
+export declare const defaultPlayTrack = "internal";
+/** Play Console: "up to 500 Unicode characters per language". */
+export declare const maximumPlayReleaseNoteCharacters = 500;
+/** What one `deploy submit`/`deploy run` asks Play to do with the new bundle. */
+export interface PlayReleaseRequest {
+  readonly track: string;
+  readonly status: PlayNewReleaseStatus;
+  /** Required for `inProgress`: 0 < fraction < 1. */
+  readonly userFraction?: number;
+  readonly releaseNotes?: readonly PlayReleaseNote[];
+  /** Absolute path of an R8/ProGuard `mapping.txt` for this exact build. */
+  readonly mappingFile?: string;
+  /** SHA-256 of `mappingFile`, fixed when the request is created. */
+  readonly mappingSha256?: string;
+}
+export interface PlayReleaseNote {
+  readonly language: string;
+  readonly text: string;
+}
+export declare const defaultPlayReleaseRequest: PlayReleaseRequest;
+export interface CreatePlayReleaseRequestInput {
+  readonly track?: string | undefined;
+  readonly status?: string | undefined;
+  readonly userFraction?: string | number | undefined;
+  readonly releaseNotesFile?: string | undefined;
+  readonly mappingFile?: string | undefined;
+}
+/** Validate CLI release options; with none it returns the internal/completed default. */
+export declare function createPlayReleaseRequest(input: CreatePlayReleaseRequestInput): Promise<PlayReleaseRequest>;
+/** Re-check a programmatic request; the CLI path builds it with createPlayReleaseRequest. */
+export declare function assertPlayReleaseRequest(request: PlayReleaseRequest): void;
+export declare function assertPlayTrackName(track: string): void;
+/** `production` and form-factor production tracks such as `wear:production`. */
+export declare function isProductionTrack(track: string): boolean;
+/**
+* A default track (`internal`/`qa`, `alpha`, `beta`, `production`, optionally
+* form-factor prefixed). Other names are closed-testing tracks, which "are
+* created manually", so a missing one is a typo rather than an empty track.
+*/
+export declare function isWellKnownPlayTrack(track: string): boolean;
+/** Production releases and every staged rollout need an explicit confirmation flag. */
+export declare function playReleaseNeedsConfirmation(request: Pick<PlayReleaseRequest, 'track' | 'status'>): boolean;
+export declare function assertPlayReleaseConfirmed(request: Pick<PlayReleaseRequest, 'track' | 'status'>, confirmed: boolean): void;
+export declare function isDefaultPlayReleaseRequest(request: PlayReleaseRequest): boolean;
+/**
+* Binds a submission checkpoint to the release options that started it, so a
+* resumed edit is never committed with another track or status. The original
+* internal/completed request has no digest, which keeps its checkpoints as before.
+*/
+export declare function playReleaseRequestDigest(request: PlayReleaseRequest): string | undefined;
+export declare function parsePlayUserFraction(value: string | number): number;
+/** Android Publisher v3 `Release.userFraction`: "0 < fraction < 1". */
+export declare function assertPlayUserFraction(fraction: number): void;
+export declare function readPlayReleaseNotesFile(file: string): PlayReleaseNote[];
+/**
+* Accepts the Play Console's own language-tag format, one block per language:
+*
+*     <en-US>
+*     Bug fixes.
+*     </en-US>
+*
+* or JSON: `{ "en-US": "Bug fixes." }` or `[{ "language": "en-US", "text": "Bug fixes." }]`.
+*/
+export declare function parsePlayReleaseNotes(source: string): PlayReleaseNote[];
+export declare function assertPlayReleaseNotes(notes: readonly PlayReleaseNote[]): void;
+export declare function hashMappingFile(mappingFile: string): Promise<string>;
+/** Build the Release body for a new bundle; the default matches the original body exactly. */
+export declare function newPlayRelease(request: PlayReleaseRequest, name: string, versionCode: number): PlayTrackRelease;
+/**
+* Add a new release to the releases Play returned for the track. Every other
+* release is sent back unchanged, except the ones the new release supersedes:
+* a completed or staged release replaces an in-progress or halted rollout, and
+* a draft replaces an older draft. A track with only completed releases (the
+* usual internal track) therefore gets exactly the original appended body.
+*/
+export declare function mergeNewPlayRelease(current: readonly PlayTrackRelease[] | null | undefined, release: PlayTrackRelease): {
+  readonly releases: PlayTrackRelease[];
+  readonly superseded: PlayTrackRelease[];
+};
+/**
+* The Play Developer API answers "Only releases with status draft may be
+* created on draft app." while an app has never been published. Google's API
+* reference does not document it; it is reported by fastlane, the
+* upload-google-play action and others, on edits.commit. Only a definitive 4xx
+* with that text counts: the edit was not committed.
+*/
+export declare function isPlayDraftAppRejection(error: unknown): boolean;