@mpgd/cli 0.67.0 → 0.68.0

package/dist/app-store-release-port.d.ts

@@ -0,0 +1,168 @@
+/**
+* App Store Connect release port: the App Store version, its build, App
+* Review information, release options, the age rating declaration and the
+* review submission. `app-store-release-asc.ts` implements it with the
+* pinned `asc` CLI; the planner and tests see only these shapes. The store
+* page reads and the version localization writes come from
+* `app-store-presence-port.ts`, and the in-app purchase reads from
+* `app-store-iap-port.ts`.
+*
+* Resources (App Store Connect API, read 2026-10-31):
+* - App Store versions: https://developer.apple.com/documentation/appstoreconnectapi/appstoreversion
+*   (`releaseType` MANUAL, AFTER_APPROVAL or SCHEDULED; `earliestReleaseDate`; `copyright`)
+* - The version's build: https://developer.apple.com/documentation/appstoreconnectapi/patch-v1-appstoreversions-_id_-relationships-build
+* - Builds: https://developer.apple.com/documentation/appstoreconnectapi/build
+*   (`processingState` PROCESSING, FAILED, INVALID or VALID; `usesNonExemptEncryption`)
+* - App Review information: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-appstorereviewdetails
+* - Phased release: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-appstoreversionphasedreleases
+*   (`PhasedReleaseState` INACTIVE, ACTIVE, PAUSED or COMPLETE)
+* - Review submissions: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-reviewsubmissions,
+*   their items https://developer.apple.com/documentation/appstoreconnectapi/post-v1-reviewsubmissionitems,
+*   and submitting one https://developer.apple.com/documentation/appstoreconnectapi/patch-v1-reviewsubmissions-_id_
+* - Manual release: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-appstoreversionreleaserequests
+*/
+export type AscReleaseType = 'MANUAL' | 'AFTER_APPROVAL' | 'SCHEDULED';
+export interface AscReleaseApp {
+  readonly bundleId: string;
+  /** The app's primary language, for example `en-US`. */
+  readonly primaryLocale?: string | undefined;
+}
+export interface AscReleaseVersion {
+  readonly id: string;
+  readonly versionString: string;
+  /** `appVersionState`, or `appStoreState` when App Store Connect sends only that. */
+  readonly state?: string | undefined;
+  /** The legacy `appStoreState`. */
+  readonly appStoreState?: string | undefined;
+  readonly releaseType?: string | undefined;
+  readonly earliestReleaseDate?: string | undefined;
+  readonly copyright?: string | undefined;
+  readonly createdDate?: string | undefined;
+}
+export interface AscReleaseBuild {
+  readonly id: string;
+  /** The build number (`CFBundleVersion`). */
+  readonly buildNumber: string;
+  readonly processingState?: string | undefined;
+  readonly expired?: boolean | undefined;
+  /** `undefined` while App Store Connect waits for the export compliance answer. */
+  readonly usesNonExemptEncryption?: boolean | undefined;
+  readonly uploadedDate?: string | undefined;
+}
+export interface AscReviewDetail {
+  readonly id: string;
+  readonly contactFirstName?: string | undefined;
+  readonly contactLastName?: string | undefined;
+  readonly contactEmail?: string | undefined;
+  readonly contactPhone?: string | undefined;
+  readonly demoAccountName?: string | undefined;
+  /** asc withholds the password; only whether one is set is known. */
+  readonly demoAccountPasswordSet: boolean;
+  readonly demoAccountRequired: boolean;
+  readonly notes?: string | undefined;
+}
+/** The fields a review detail write sends; a field left out stays as it is. */
+export interface AscReviewDetailWrite {
+  readonly contactFirstName?: string;
+  readonly contactLastName?: string;
+  readonly contactEmail?: string;
+  readonly contactPhone?: string;
+  readonly notes?: string;
+  readonly demoAccountRequired?: boolean;
+  readonly demoAccountName?: string;
+  readonly demoAccountPassword?: string;
+}
+export interface AscPhasedRelease {
+  readonly id: string;
+  /** INACTIVE, ACTIVE, PAUSED or COMPLETE. */
+  readonly state: string;
+  readonly currentDayNumber?: number | undefined;
+  readonly startDate?: string | undefined;
+}
+export interface AscAgeRating {
+  readonly id: string;
+  /** The answered content descriptors, by attribute name. */
+  readonly answered: readonly string[];
+}
+export interface AscReviewSubmission {
+  readonly id: string;
+  /** READY_FOR_REVIEW, WAITING_FOR_REVIEW, IN_REVIEW, UNRESOLVED_ISSUES, CANCELING, COMPLETING or COMPLETE. */
+  readonly state: string;
+  readonly submittedDate?: string | undefined;
+}
+export interface AscReviewSubmissionItem {
+  readonly id: string;
+  /** READY_FOR_REVIEW, ACCEPTED, APPROVED, REJECTED or REMOVED. */
+  readonly state?: string | undefined;
+  readonly appStoreVersionId?: string | undefined;
+  readonly inAppPurchaseVersionId?: string | undefined;
+}
+export type AscReviewItemType = 'appStoreVersions' | 'inAppPurchaseVersions';
+export interface AscReleasePort {
+  readApp(appId: string): Promise<AscReleaseApp>;
+  /** iOS App Store versions of the app, with their release options. */
+  listVersions(appId: string): Promise<AscReleaseVersion[]>;
+  /** iOS builds of one marketing version, optionally one build number. */
+  listBuilds(input: {
+    readonly appId: string;
+    readonly marketingVersion: string;
+    readonly buildNumber?: string;
+  }): Promise<AscReleaseBuild[]>;
+  /** The build attached to the version, if any. */
+  readAttachedBuild(versionId: string): Promise<{
+    readonly id: string;
+    readonly buildNumber?: string;
+  } | undefined>;
+  /** `undefined` when the version has no App Review information yet. */
+  readReviewDetail(versionId: string): Promise<AscReviewDetail | undefined>;
+  /** `undefined` when the version has no phased release. */
+  readPhasedRelease(versionId: string): Promise<AscPhasedRelease | undefined>;
+  /** The age rating declaration of an app information record. */
+  readAgeRating(appInfoId: string): Promise<AscAgeRating | undefined>;
+  /** iOS review submissions of the app, every state. */
+  listReviewSubmissions(appId: string): Promise<AscReviewSubmission[]>;
+  listReviewSubmissionItems(submissionId: string): Promise<AscReviewSubmissionItem[]>;
+  /** Returns the new version's ID. */
+  createVersion(input: {
+    readonly appId: string;
+    readonly versionString: string;
+    readonly releaseType: AscReleaseType;
+    readonly copyright?: string;
+  }): Promise<string>;
+  updateVersion(input: {
+    readonly versionId: string;
+    readonly versionString?: string;
+    readonly copyright?: string;
+    readonly releaseType?: AscReleaseType;
+    readonly earliestReleaseDate?: string;
+  }): Promise<void>;
+  attachBuild(input: {
+    readonly versionId: string;
+    readonly buildId: string;
+  }): Promise<void>;
+  createReviewDetail(input: {
+    readonly versionId: string;
+    readonly fields: AscReviewDetailWrite;
+  }): Promise<void>;
+  updateReviewDetail(input: {
+    readonly detailId: string;
+    readonly fields: AscReviewDetailWrite;
+  }): Promise<void>;
+  /** A new phased release in INACTIVE: it starts when the version is released. */
+  createPhasedRelease(versionId: string): Promise<void>;
+  deletePhasedRelease(phasedReleaseId: string): Promise<void>;
+  updatePhasedRelease(input: {
+    readonly phasedReleaseId: string;
+    readonly state: 'ACTIVE' | 'PAUSED' | 'COMPLETE';
+  }): Promise<void>;
+  /** Returns the new submission's ID. */
+  createReviewSubmission(appId: string): Promise<string>;
+  addReviewSubmissionItem(input: {
+    readonly submissionId: string;
+    readonly type: AscReviewItemType;
+    readonly id: string;
+  }): Promise<void>;
+  submitReviewSubmission(submissionId: string): Promise<void>;
+  /** Releases a version in PENDING_DEVELOPER_RELEASE. */
+  releaseVersion(versionId: string): Promise<void>;
+}

package/dist/app-store-release-port.js

@@ -0,0 +1,24 @@
+/**
+ * App Store Connect release port: the App Store version, its build, App
+ * Review information, release options, the age rating declaration and the
+ * review submission. `app-store-release-asc.ts` implements it with the
+ * pinned `asc` CLI; the planner and tests see only these shapes. The store
+ * page reads and the version localization writes come from
+ * `app-store-presence-port.ts`, and the in-app purchase reads from
+ * `app-store-iap-port.ts`.
+ *
+ * Resources (App Store Connect API, read 2026-10-31):
+ * - App Store versions: https://developer.apple.com/documentation/appstoreconnectapi/appstoreversion
+ *   (`releaseType` MANUAL, AFTER_APPROVAL or SCHEDULED; `earliestReleaseDate`; `copyright`)
+ * - The version's build: https://developer.apple.com/documentation/appstoreconnectapi/patch-v1-appstoreversions-_id_-relationships-build
+ * - Builds: https://developer.apple.com/documentation/appstoreconnectapi/build
+ *   (`processingState` PROCESSING, FAILED, INVALID or VALID; `usesNonExemptEncryption`)
+ * - App Review information: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-appstorereviewdetails
+ * - Phased release: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-appstoreversionphasedreleases
+ *   (`PhasedReleaseState` INACTIVE, ACTIVE, PAUSED or COMPLETE)
+ * - Review submissions: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-reviewsubmissions,
+ *   their items https://developer.apple.com/documentation/appstoreconnectapi/post-v1-reviewsubmissionitems,
+ *   and submitting one https://developer.apple.com/documentation/appstoreconnectapi/patch-v1-reviewsubmissions-_id_
+ * - Manual release: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-appstoreversionreleaserequests
+ */
+export {};

package/dist/app-store-release.d.ts

@@ -0,0 +1,238 @@
+import type { StorePresence } from '@mpgd/catalog';
+import type { AscIapPort } from './app-store-iap-port.js';
+import type { AscStorePresencePort } from './app-store-presence-port.js';
+import type { AscPhasedRelease, AscReleasePort, AscReleaseType, AscReviewSubmissionItem } from './app-store-release-port.js';
+import { type StorePresenceTextChange } from './store-presence.js';
+/**
+* App Store Connect release: everything between "the build is in
+* TestFlight" and "the version is submitted for review", planned from App
+* Store Connect and the game files, then applied step by step.
+*
+* The plan reads; apply re-plans, refuses when App Store Connect or the
+* files moved past the reviewed plan, and writes in a fixed order: the
+* version (created or renamed, then its copyright and release options), its
+* build, What's New, App Review information, the phased release, the review
+* submission with the version and the in-app purchases that go with it, and
+* the submission itself. App Store Connect has no transaction: a failed
+* apply names the steps already written, and a new plan lists what is left.
+*
+* A version that does not exist yet is created alone: App Store Connect
+* then needs its store page (`mpgd store presence apply`) before anything
+* else can be checked, so the next plan picks up from there.
+*/
+export declare const appStoreReleasePlanCommand = "mpgd store release plan";
+export type AppStoreReleaseStage = 'create-version' | 'prepare' | 'submitted' | 'approved' | 'released';
+export interface AppStoreReleaseRequest {
+  /** The marketing version (`CFBundleShortVersionString`) to submit. */
+  readonly marketingVersion: string;
+  /** The build number; without it, the newest build of the version. */
+  readonly buildNumber?: string;
+  /** The App Store Connect build `deploy run` recorded for this build, when known. */
+  readonly recordedBuildId?: string;
+  /** The iOS app runs on iPad too: App Review needs 13-inch iPad screenshots. */
+  readonly universal: boolean;
+  readonly releaseType: AscReleaseType;
+  /** ISO 8601 date-time; required for, and only for, SCHEDULED. */
+  readonly earliestReleaseDate?: string;
+  readonly phasedRelease: boolean;
+  /** In-app purchase product IDs deliberately left out of this submission. */
+  readonly skipIaps: readonly string[];
+  /** Send the demo account password again even when App Store Connect has one. */
+  readonly rotateDemoPassword: boolean;
+}
+/** The demo account values the presence file names by environment variable. */
+export interface AppStoreReleaseDemoAccount {
+  readonly name: string;
+  readonly password: string;
+}
+export interface AppStoreReleasePlanInput {
+  readonly appId: string;
+  readonly bundleId: string;
+  readonly presence: StorePresence;
+  readonly request: AppStoreReleaseRequest;
+  /** Resolved from `appStore.review.demoAccount`; never saved. */
+  readonly demoAccount?: AppStoreReleaseDemoAccount;
+  /**
+  * Why the demo account could not be read (an unset variable, say). The plan
+  * is still made, with these as blockers, so it can be reviewed without the secrets.
+  */
+  readonly demoAccountProblems?: readonly string[];
+  readonly now?: () => Date;
+}
+export interface AppStoreReleasePorts {
+  readonly release: AscReleasePort;
+  readonly presence: AscStorePresencePort;
+  readonly iap: AscIapPort;
+}
+export interface PlannedReleaseIap {
+  readonly productId: string;
+  readonly iapId: string;
+  readonly type: string;
+  readonly state: string;
+  /** `attach`: added to the submission; `attached`: already in it. */
+  readonly action: 'attach' | 'attached' | 'skip' | 'none' | 'blocked';
+  readonly versionId?: string;
+}
+export interface AppStoreReleasePlan {
+  readonly schemaVersion: 1;
+  readonly store: 'app-store';
+  readonly appId: string;
+  readonly bundleId: string;
+  readonly marketingVersion: string;
+  readonly stage: AppStoreReleaseStage;
+  readonly version: {
+    readonly action: 'create' | 'rename' | 'reuse';
+    readonly id?: string;
+    /** `rename`: the editable version's current version string. */
+    readonly from?: string;
+    readonly state?: string;
+    /** No version of the app has been released: App Store Connect takes no What's New. */
+    readonly first: boolean;
+  };
+  /** One `versions update` (copyright, release type, earliest release date), when anything differs. */
+  readonly versionUpdate?: {
+    readonly copyright?: string;
+    readonly releaseType?: AscReleaseType;
+    readonly earliestReleaseDate?: string;
+  };
+  readonly build?: {
+    readonly id: string;
+    readonly buildNumber: string;
+    readonly action: 'attach' | 'unchanged';
+    /** The build attached now, which the new one replaces. */
+    readonly replaces?: string;
+  };
+  readonly whatsNew: readonly {
+    readonly locale: string;
+    readonly localizationId: string;
+    readonly change: StorePresenceTextChange;
+  }[];
+  readonly reviewDetail: {
+    readonly action: 'create' | 'update' | 'unchanged';
+    readonly id?: string;
+    /** Field names only; the values stay in the game file and the environment. */
+    readonly fields: readonly string[];
+  };
+  readonly phasedRelease: {
+    readonly action: 'create' | 'delete' | 'unchanged';
+    readonly id?: string;
+    readonly state?: string;
+  };
+  readonly iaps: readonly PlannedReleaseIap[];
+  readonly submission: {
+    readonly action: 'create' | 'reuse' | 'submitted' | 'none';
+    readonly id?: string;
+    readonly state?: string;
+    readonly addVersion: boolean;
+    readonly submit: boolean;
+  };
+  /** The writes apply makes, in order. */
+  readonly operations: readonly string[];
+  /** What must be fixed before apply runs; apply refuses while any is listed. */
+  readonly blockers: readonly string[];
+  readonly notes: readonly string[];
+  /** What the kit cannot do; the developer does it in App Store Connect. */
+  readonly manual: readonly string[];
+  readonly changed: boolean;
+  readonly remoteSha256: string;
+  readonly desiredSha256: string;
+}
+/** Read App Store Connect and plan; never writes. */
+export declare function planAppStoreRelease(input: AppStoreReleasePlanInput, ports: AppStoreReleasePorts): Promise<AppStoreReleasePlan>;
+export interface AppStoreReleaseApplyResult {
+  readonly appId: string;
+  readonly marketingVersion: string;
+  readonly status: 'created-version' | 'submitted' | 'unchanged' | 'dry-run';
+  /** The writes, in order (dry run: the writes apply would make). */
+  readonly steps: readonly string[];
+  readonly versionId?: string;
+  readonly submissionId?: string;
+  readonly next: readonly string[];
+  readonly manual: readonly string[];
+}
+export declare class AppStoreReleaseApplyError extends Error {
+  readonly stage: string;
+  /** The writes that landed before the failure. */
+  readonly written: readonly string[];
+  /** App Store Connect refused the step (asc exited with a 4xx-class code): nothing from it landed. */
+  readonly definitive: boolean;
+  /** What to do instead of re-running the same plan, when re-running cannot help. */
+  readonly detail?: string | undefined;
+  constructor(stage: string, 
+  /** The writes that landed before the failure. */
+  written: readonly string[], cause: unknown, 
+  /** App Store Connect refused the step (asc exited with a 4xx-class code): nothing from it landed. */
+  definitive?: boolean, 
+  /** What to do instead of re-running the same plan, when re-running cannot help. */
+  detail?: string | undefined);
+}
+/** Refuse a plan with blockers, with every blocker named. */
+export declare function assertNoBlockers(plan: AppStoreReleasePlan): void;
+/**
+* Apply a reviewed plan: re-plan, refuse when App Store Connect or the files
+* moved past it or it has blockers, then write step by step. A plan whose
+* changes already landed is a no-op, so a re-run is safe. `dryRun` stops
+* after the checks and returns the writes it would make.
+*/
+export declare function applyAppStoreRelease(input: {
+  readonly saved: AppStoreReleasePlan;
+  readonly plan: AppStoreReleasePlanInput;
+  readonly ports: AppStoreReleasePorts;
+  readonly approved: boolean;
+  readonly dryRun?: boolean;
+}): Promise<AppStoreReleaseApplyResult>;
+/** The plan for the terminal. */
+export declare function formatAppStoreReleasePlan(plan: AppStoreReleasePlan): string;
+export interface AppStoreReleaseStatus {
+  readonly appId: string;
+  readonly version?: {
+    readonly id: string;
+    readonly versionString: string;
+    readonly state: string;
+    readonly releaseType?: string;
+    readonly earliestReleaseDate?: string;
+    readonly build?: {
+      readonly id: string;
+      readonly buildNumber?: string;
+    };
+  };
+  readonly submission?: {
+    readonly id: string;
+    readonly state: string;
+    readonly submittedDate?: string;
+    readonly items: readonly AscReviewSubmissionItem[];
+  };
+  readonly phasedRelease?: AscPhasedRelease;
+  /** Where the release stands and what comes next, in a sentence. */
+  readonly summary: string;
+}
+/** Where a version stands: its state, build, review submission and phased release. Reads only. */
+export declare function readAppStoreReleaseStatus(input: {
+  readonly appId: string;
+  readonly bundleId: string;
+  readonly marketingVersion?: string;
+}, port: AscReleasePort): Promise<AppStoreReleaseStatus>;
+/** Release an approved version that waits for a manual release. */
+export declare function publishAppStoreVersion(input: {
+  readonly appId: string;
+  readonly bundleId: string;
+  readonly marketingVersion: string;
+  readonly approved: boolean;
+}, port: AscReleasePort): Promise<{
+  readonly status: 'released' | 'unchanged';
+  readonly versionId: string;
+  readonly state: string;
+}>;
+export type PhasedReleaseAction = 'pause' | 'resume' | 'complete';
+/** Pause, resume or complete the phased release of a released version. */
+export declare function changeAppStorePhasedRelease(input: {
+  readonly appId: string;
+  readonly bundleId: string;
+  readonly marketingVersion: string;
+  readonly action: PhasedReleaseAction;
+  readonly approved: boolean;
+}, port: AscReleasePort): Promise<{
+  readonly status: 'updated' | 'unchanged';
+  readonly phasedReleaseId: string;
+  readonly state: string;
+}>;