@mpgd/cli 0.62.0 → 0.64.0

package/dist/app-store-iap-asc.d.ts

@@ -0,0 +1,14 @@
+import type { AscIapPort } from './app-store-iap-port.js';
+import { type AscCommandRunner, type AscCredential } from './asc-session.js';
+export type { AscCommandRunner, AscCredential } from './asc-session.js';
+/**
+* The in-app purchase port on the pinned `asc` 5.5.0 CLI (`asc-session.ts`).
+* Each method is one `asc ... --output json` command.
+*/
+/** Copy and verify the pinned binary; `close` removes it. */
+export declare function openAscIapSession(credential: AscCredential, signal?: AbortSignal): Promise<{
+  readonly port: AscIapPort;
+  close(): void;
+}>;
+/** The port over any runner; the tests drive it with recorded asc output. */
+export declare function createAscIapPort(run: AscCommandRunner, today?: () => string): AscIapPort;

package/dist/app-store-iap-asc.js

@@ -0,0 +1,219 @@
+import { ascExitNotFound, isEmptyResource, isRecord, list, ascListTimeoutMs as listTimeoutMs, ascLookupTimeoutMs as lookupTimeoutMs, openAscSession, optionalString, relationshipId, requiredString, single, ascUploadTimeoutMs as uploadTimeoutMs, } from './asc-session.js';
+import { ReleaseProcessError } from './deploy-process.js';
+import { sameDecimal } from './store-products.js';
+/**
+ * The in-app purchase port on the pinned `asc` 5.5.0 CLI (`asc-session.ts`).
+ * Each method is one `asc ... --output json` command.
+ */
+/** Copy and verify the pinned binary; `close` removes it. */
+export async function openAscIapSession(credential, signal) {
+    const session = await openAscSession(credential, signal);
+    return { port: createAscIapPort(session.run), close: () => session.close() };
+}
+/** The port over any runner; the tests drive it with recorded asc output. */
+export function createAscIapPort(run, today = () => new Date().toISOString().slice(0, 10)) {
+    const optional = async (args) => {
+        try {
+            return await run(args, lookupTimeoutMs);
+        }
+        catch (error) {
+            if (error instanceof ReleaseProcessError && error.exitCode === ascExitNotFound) {
+                return undefined;
+            }
+            throw error;
+        }
+    };
+    return {
+        async readAppBundleId(appId) {
+            const app = single(await run(['apps', 'view', '--id', appId], lookupTimeoutMs), 'apps view');
+            const bundleId = app.attributes.bundleId;
+            if (app.id !== appId || typeof bundleId !== 'string') {
+                throw new Error('asc apps view returned no bundle ID for the app.');
+            }
+            return bundleId;
+        },
+        async listIaps(appId) {
+            return list(await run(['iap', 'list', '--app', appId, '--paginate'], listTimeoutMs), 'iap list')
+                .map((resource) => ({
+                id: resource.id,
+                productId: requiredString(resource.attributes.productId, 'iap list productId'),
+                name: requiredString(resource.attributes.name, 'iap list name'),
+                inAppPurchaseType: requiredString(resource.attributes.inAppPurchaseType, 'iap list type'),
+                ...optionalString('state', resource.attributes.state),
+                ...optionalString('reviewNote', resource.attributes.reviewNote),
+                ...(resource.attributes.familySharable === true ? { familySharable: true } : {}),
+            }));
+        },
+        async listVersions(iapId) {
+            return list(await run(['iap', 'versions', 'list', '--iap-id', iapId, '--paginate'], listTimeoutMs), 'iap versions list').map((resource) => ({
+                id: resource.id,
+                ...(typeof resource.attributes.version === 'number' ? { version: resource.attributes.version } : {}),
+                ...optionalString('state', resource.attributes.state),
+            }));
+        },
+        async listLocalizations(versionId) {
+            return list(await run(['iap', 'versions', 'localizations', 'list', '--version-id', versionId, '--paginate'], listTimeoutMs), 'iap versions localizations list').map((resource) => ({
+                id: resource.id,
+                locale: requiredString(resource.attributes.locale, 'localization locale'),
+                name: requiredString(resource.attributes.name, 'localization name'),
+                ...optionalString('description', resource.attributes.description),
+            }));
+        },
+        async readPriceSchedule(iapId) {
+            const response = await optional(['iap', 'pricing', 'schedules', 'view', '--iap-id', iapId, '--include', 'baseTerritory']);
+            // No schedule: asc exits 4 (not found), or App Store Connect answers with no resource.
+            if (response === undefined || isEmptyResource(response)) {
+                return undefined;
+            }
+            const schedule = single(response, 'iap pricing schedules view');
+            const baseTerritory = relationshipId(schedule.relationships, 'baseTerritory');
+            const resolved = await run(['iap', 'pricing', 'schedules', 'manual-prices', '--schedule-id', schedule.id, '--resolved'], listTimeoutMs);
+            if (!isRecord(resolved) || !Array.isArray(resolved.prices)) {
+                throw new Error('asc iap pricing schedules manual-prices returned no prices.');
+            }
+            const manualPrices = resolved.prices.flatMap((row) => isRecord(row) && row.manual === true && typeof row.territory === 'string'
+                && typeof row.customerPrice === 'string'
+                ? [{ territory: row.territory, customerPrice: row.customerPrice }]
+                : []);
+            if (baseTerritory === undefined && manualPrices.length === 0) {
+                return undefined;
+            }
+            // `--resolved` lists only prices in effect; the raw list also holds future ones.
+            const all = list(await run(['iap', 'pricing', 'schedules', 'manual-prices', '--schedule-id', schedule.id, '--paginate'], listTimeoutMs), 'iap pricing schedules manual-prices');
+            const now = today();
+            // A future start or a future end (a temporary price expiring) is a
+            // transition a new open-ended schedule would remove.
+            const upcoming = (value) => typeof value === 'string' && value.slice(0, 10) > now;
+            const scheduledChanges = all.filter((price) => upcoming(price.attributes.startDate) || upcoming(price.attributes.endDate)).length;
+            return {
+                id: schedule.id,
+                ...(baseTerritory === undefined ? {} : { baseTerritory }),
+                manualPrices,
+                scheduledChanges,
+            };
+        },
+        async readAvailability(iapId) {
+            let response;
+            try {
+                response = await run(['iap', 'pricing', 'availability', 'view', '--iap-id', iapId], lookupTimeoutMs);
+            }
+            catch (error) {
+                // asc 5.5.0 reports an unset availability as an error naming it (availability.go).
+                if (error instanceof ReleaseProcessError
+                    && (error.exitCode === ascExitNotFound || error.output.includes('has no availability configured'))) {
+                    return undefined;
+                }
+                throw error;
+            }
+            if (isEmptyResource(response)) {
+                return undefined;
+            }
+            const availability = single(response, 'iap pricing availability view');
+            const territories = list(await run(['iap', 'pricing', 'availabilities', 'available-territories', '--id', availability.id, '--paginate'], listTimeoutMs), 'iap pricing availabilities available-territories').map((territory) => territory.id);
+            return {
+                id: availability.id,
+                availableInNewTerritories: availability.attributes.availableInNewTerritories === true,
+                territories,
+            };
+        },
+        async readReviewScreenshot(iapId) {
+            const response = await optional(['iap', 'review-screenshots', 'view', '--iap-id', iapId]);
+            if (!isRecord(response) || !isRecord(response.data) || typeof response.data.id !== 'string'
+                || response.data.id === '') {
+                return undefined;
+            }
+            const attributes = isRecord(response.data.attributes) ? response.data.attributes : {};
+            return {
+                id: response.data.id,
+                ...optionalString('fileName', attributes.fileName),
+                ...(typeof attributes.fileSize === 'number' ? { fileSize: attributes.fileSize } : {}),
+                ...optionalString('sourceFileChecksum', attributes.sourceFileChecksum),
+                ...optionalString('deliveryState', isRecord(attributes.assetDeliveryState) ? attributes.assetDeliveryState.state : undefined),
+            };
+        },
+        async listTerritories() {
+            const territories = list(await run(['pricing', 'territories', 'list', '--paginate'], listTimeoutMs), 'pricing territories list').map((resource) => resource.id);
+            if (territories.length === 0) {
+                throw new Error('asc pricing territories list returned no territories.');
+            }
+            return territories;
+        },
+        async createIap(input) {
+            const created = single(await run([
+                'iap', 'create',
+                '--app', input.appId,
+                '--type', input.type,
+                '--ref-name', input.referenceName,
+                '--product-id', input.productId,
+                ...(input.familySharable ? ['--family-sharable'] : []),
+            ], lookupTimeoutMs), 'iap create');
+            return created.id;
+        },
+        async updateIap(input) {
+            await run([
+                'iap', 'update',
+                '--id', input.iapId,
+                ...(input.referenceName === undefined ? [] : ['--ref-name', input.referenceName]),
+                ...(input.familySharable === true ? ['--family-sharable'] : []),
+            ], lookupTimeoutMs);
+        },
+        async createVersion(iapId) {
+            return single(await run(['iap', 'versions', 'create', '--iap-id', iapId], lookupTimeoutMs), 'iap versions create').id;
+        },
+        async createLocalization(input) {
+            await run([
+                'iap', 'versions', 'localizations', 'create',
+                '--version-id', input.versionId,
+                '--locale', input.locale,
+                '--name', input.name,
+                '--description', input.description,
+            ], lookupTimeoutMs);
+        },
+        async updateLocalization(input) {
+            await run([
+                'iap', 'versions', 'localizations', 'update',
+                '--localization-id', input.localizationId,
+                '--name', input.name,
+                '--description', input.description,
+            ], lookupTimeoutMs);
+        },
+        async findPricePoint(input) {
+            const points = list(await run([
+                'iap', 'pricing', 'price-points', 'list',
+                '--iap-id', input.iapId,
+                '--territory', input.territory,
+                '--price', input.customerPrice,
+                '--paginate',
+            ], listTimeoutMs), 'iap pricing price-points list').filter((point) => typeof point.attributes.customerPrice === 'string'
+                && sameDecimal(point.attributes.customerPrice, input.customerPrice));
+            const [point] = points;
+            if (points.length !== 1 || point === undefined) {
+                throw new Error(`App Store Connect has ${points.length} price points of ${input.customerPrice} in ${input.territory}; `
+                    + 'use a price that is an App Store price point there.');
+            }
+            return point.id;
+        },
+        async createPriceSchedule(input) {
+            await run([
+                'iap', 'pricing', 'schedules', 'create',
+                '--iap-id', input.iapId,
+                '--base-territory', input.baseTerritory,
+                '--prices', input.pricePointIds.join(','),
+            ], lookupTimeoutMs);
+        },
+        async setAvailability(input) {
+            await run([
+                'iap', 'pricing', 'availability', 'set',
+                '--iap-id', input.iapId,
+                '--territories', input.territories.join(','),
+                ...(input.availableInNewTerritories ? ['--available-in-new-territories'] : []),
+            ], lookupTimeoutMs);
+        },
+        async deleteReviewScreenshot(screenshotId) {
+            await run(['iap', 'review-screenshots', 'delete', '--screenshot-id', screenshotId, '--confirm'], lookupTimeoutMs);
+        },
+        async uploadReviewScreenshot(input) {
+            await run(['iap', 'review-screenshots', 'create', '--iap-id', input.iapId, '--file', input.file], uploadTimeoutMs);
+        },
+    };
+}

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

@@ -0,0 +1,125 @@
+/**
+* App Store Connect in-app purchase port. The kit drives App Store Connect
+* through the pinned `asc` CLI (docs/NATIVE_DEPLOY_TOOLING_DECISION.md);
+* `app-store-iap-asc.ts` implements this port with it, and the planner and
+* tests see only these shapes.
+*
+* Resources (App Store Connect API 4.4.1):
+* - In-app purchases v2: https://developer.apple.com/documentation/appstoreconnectapi/in-app-purchases
+* - Versions and their localizations: https://developer.apple.com/documentation/appstoreconnectapi/in-app-purchase-versions
+* - Price schedules: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchasepriceschedules
+* - Availability: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchaseavailabilities
+* - Review screenshot: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchaseappstorereviewscreenshots
+*/
+export type AscIapType = 'CONSUMABLE' | 'NON_CONSUMABLE';
+export interface AscIap {
+  readonly id: string;
+  readonly productId: string;
+  /** Reference name. */
+  readonly name: string;
+  readonly inAppPurchaseType: string;
+  /** `InAppPurchaseState`, for example `MISSING_METADATA` or `APPROVED`. */
+  readonly state?: string | undefined;
+  readonly familySharable?: boolean | undefined;
+  readonly reviewNote?: string | undefined;
+}
+export interface AscIapVersion {
+  readonly id: string;
+  readonly version?: number | undefined;
+  /** `PREPARE_FOR_SUBMISSION`, `READY_FOR_REVIEW`, `WAITING_FOR_REVIEW`, `APPROVED`, ... */
+  readonly state?: string | undefined;
+}
+export interface AscIapLocalization {
+  readonly id: string;
+  readonly locale: string;
+  readonly name: string;
+  readonly description?: string | undefined;
+}
+/** The current price schedule: base territory and the manual prices in effect. */
+export interface AscIapPriceSchedule {
+  readonly id: string;
+  readonly baseTerritory?: string | undefined;
+  /** Manual (not equalized) prices in effect now, per alpha-3 territory. */
+  readonly manualPrices: readonly {
+    readonly territory: string;
+    readonly customerPrice: string;
+  }[];
+  /** Manual prices that start in the future; a new schedule would drop them. */
+  readonly scheduledChanges: number;
+}
+export interface AscIapAvailability {
+  readonly id: string;
+  readonly availableInNewTerritories: boolean;
+  /** Alpha-3 territories the in-app purchase is sold in. */
+  readonly territories: readonly string[];
+}
+export interface AscIapReviewScreenshot {
+  readonly id: string;
+  readonly fileName?: string | undefined;
+  readonly fileSize?: number | undefined;
+  /** MD5 of the uploaded file, as App Store Connect records it. */
+  readonly sourceFileChecksum?: string | undefined;
+  /** `assetDeliveryState.state`: `AWAITING_UPLOAD`, `UPLOAD_COMPLETE`, `COMPLETE` or `FAILED`. */
+  readonly deliveryState?: string | undefined;
+}
+export interface AscIapPort {
+  /** The app record's bundle ID (`apps view`). */
+  readAppBundleId(appId: string): Promise<string>;
+  listIaps(appId: string): Promise<AscIap[]>;
+  listVersions(iapId: string): Promise<AscIapVersion[]>;
+  listLocalizations(versionId: string): Promise<AscIapLocalization[]>;
+  /** `undefined` when the in-app purchase has no price schedule yet. */
+  readPriceSchedule(iapId: string): Promise<AscIapPriceSchedule | undefined>;
+  /** `undefined` when no availability was set. */
+  readAvailability(iapId: string): Promise<AscIapAvailability | undefined>;
+  /** `undefined` when no review screenshot was uploaded. */
+  readReviewScreenshot(iapId: string): Promise<AscIapReviewScreenshot | undefined>;
+  /** Every App Store territory (alpha-3). */
+  listTerritories(): Promise<string[]>;
+  createIap(input: {
+    readonly appId: string;
+    readonly type: AscIapType;
+    readonly referenceName: string;
+    readonly productId: string;
+    readonly familySharable: boolean;
+  }): Promise<string>;
+  updateIap(input: {
+    readonly iapId: string;
+    readonly referenceName?: string;
+    readonly familySharable?: true;
+  }): Promise<void>;
+  createVersion(iapId: string): Promise<string>;
+  createLocalization(input: {
+    readonly versionId: string;
+    readonly locale: string;
+    readonly name: string;
+    readonly description: string;
+  }): Promise<void>;
+  updateLocalization(input: {
+    readonly localizationId: string;
+    readonly name: string;
+    readonly description: string;
+  }): Promise<void>;
+  /** The price point of `customerPrice` in `territory`; throws unless exactly one matches. */
+  findPricePoint(input: {
+    readonly iapId: string;
+    readonly territory: string;
+    readonly customerPrice: string;
+  }): Promise<string>;
+  /** A new schedule effective now: the base territory's and the manual prices. */
+  createPriceSchedule(input: {
+    readonly iapId: string;
+    readonly baseTerritory: string;
+    readonly pricePointIds: readonly string[];
+  }): Promise<void>;
+  setAvailability(input: {
+    readonly iapId: string;
+    readonly territories: readonly string[];
+    readonly availableInNewTerritories: boolean;
+  }): Promise<void>;
+  deleteReviewScreenshot(screenshotId: string): Promise<void>;
+  uploadReviewScreenshot(input: {
+    readonly iapId: string;
+    readonly file: string;
+  }): Promise<void>;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * App Store Connect in-app purchase port. The kit drives App Store Connect
+ * through the pinned `asc` CLI (docs/NATIVE_DEPLOY_TOOLING_DECISION.md);
+ * `app-store-iap-asc.ts` implements this port with it, and the planner and
+ * tests see only these shapes.
+ *
+ * Resources (App Store Connect API 4.4.1):
+ * - In-app purchases v2: https://developer.apple.com/documentation/appstoreconnectapi/in-app-purchases
+ * - Versions and their localizations: https://developer.apple.com/documentation/appstoreconnectapi/in-app-purchase-versions
+ * - Price schedules: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchasepriceschedules
+ * - Availability: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchaseavailabilities
+ * - Review screenshot: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-inapppurchaseappstorereviewscreenshots
+ */
+export {};

package/dist/app-store-presence-asc.d.ts

@@ -0,0 +1,23 @@
+import type { AscStorePresencePort } from './app-store-presence-port.js';
+import { type AscCommandRunner, type AscCredential } from './asc-session.js';
+/**
+* The store page port on the pinned `asc` 5.5.0 CLI. Commands (5.5.0 source,
+* `internal/cli/...`):
+*
+* - `apps view`, `apps info list` (`apps/app_infos.go`)
+* - `localizations list --type app-info` and `--version` (`localizations/localizations.go`)
+* - `app-setup info set` (`apps/app_setup.go`): creates or updates one app
+*   information localization
+* - `versions list` (`versions/versions.go`)
+* - `localizations create` and `localizations update --id` (`localizations/create.go`, `update.go`)
+* - `screenshots list|upload|delete` (`assets/assets_screenshots*.go`): an
+*   upload of one file appends it to the set and waits for the asset
+*   delivery to reach `COMPLETE`, failing on `FAILED`
+*/
+/** Copy and verify the pinned binary; `close` removes it. */
+export declare function openAscStorePresenceSession(credential: AscCredential, signal?: AbortSignal): Promise<{
+  readonly port: AscStorePresencePort;
+  close(): void;
+}>;
+/** The port over any runner; the tests drive it with recorded asc output. */
+export declare function createAscStorePresencePort(run: AscCommandRunner): AscStorePresencePort;

package/dist/app-store-presence-asc.js

@@ -0,0 +1,162 @@
+import { ascListTimeoutMs, ascLookupTimeoutMs, ascUploadTimeoutMs, isRecord, list, openAscSession, optionalString, requiredString, single, } from './asc-session.js';
+/**
+ * The store page port on the pinned `asc` 5.5.0 CLI. Commands (5.5.0 source,
+ * `internal/cli/...`):
+ *
+ * - `apps view`, `apps info list` (`apps/app_infos.go`)
+ * - `localizations list --type app-info` and `--version` (`localizations/localizations.go`)
+ * - `app-setup info set` (`apps/app_setup.go`): creates or updates one app
+ *   information localization
+ * - `versions list` (`versions/versions.go`)
+ * - `localizations create` and `localizations update --id` (`localizations/create.go`, `update.go`)
+ * - `screenshots list|upload|delete` (`assets/assets_screenshots*.go`): an
+ *   upload of one file appends it to the set and waits for the asset
+ *   delivery to reach `COMPLETE`, failing on `FAILED`
+ */
+/** Copy and verify the pinned binary; `close` removes it. */
+export async function openAscStorePresenceSession(credential, signal) {
+    const session = await openAscSession(credential, signal);
+    return { port: createAscStorePresencePort(session.run), close: () => session.close() };
+}
+/** The port over any runner; the tests drive it with recorded asc output. */
+export function createAscStorePresencePort(run) {
+    return {
+        async readAppBundleId(appId) {
+            const app = single(await run(['apps', 'view', '--id', appId], ascLookupTimeoutMs), 'apps view');
+            const bundleId = app.attributes.bundleId;
+            if (app.id !== appId || typeof bundleId !== 'string') {
+                throw new Error('asc apps view returned no bundle ID for the app.');
+            }
+            return bundleId;
+        },
+        async listAppInfos(appId) {
+            return list(await run(['apps', 'info', 'list', '--app', appId], ascLookupTimeoutMs), 'apps info list')
+                .map((resource) => ({
+                id: resource.id,
+                ...optionalString('state', resource.attributes.state ?? resource.attributes.appStoreState),
+            }));
+        },
+        async listAppInfoLocalizations(appId, appInfoId) {
+            return list(await run([
+                'localizations', 'list',
+                '--type', 'app-info',
+                '--app', appId,
+                '--app-info', appInfoId,
+                '--paginate',
+            ], ascListTimeoutMs), 'localizations list --type app-info').map((resource) => ({
+                id: resource.id,
+                locale: requiredString(resource.attributes.locale, 'app info localization locale'),
+                ...optionalString('name', resource.attributes.name),
+                ...optionalString('subtitle', resource.attributes.subtitle),
+                ...optionalString('privacyPolicyUrl', resource.attributes.privacyPolicyUrl),
+            }));
+        },
+        async listVersions(appId) {
+            return list(await run(['versions', 'list', '--app', appId, '--platform', 'IOS', '--paginate'], ascListTimeoutMs), 'versions list').map((resource) => ({
+                id: resource.id,
+                ...optionalString('versionString', resource.attributes.versionString),
+                ...optionalString('state', resource.attributes.appVersionState ?? resource.attributes.appStoreState),
+                ...optionalString('appStoreState', resource.attributes.appStoreState),
+                ...optionalString('createdDate', resource.attributes.createdDate),
+            }));
+        },
+        async listVersionLocalizations(versionId) {
+            return list(await run(['localizations', 'list', '--version', versionId, '--paginate'], ascListTimeoutMs), 'localizations list').map((resource) => ({
+                id: resource.id,
+                locale: requiredString(resource.attributes.locale, 'version localization locale'),
+                ...versionFields(resource),
+            }));
+        },
+        async listScreenshotSets(versionLocalizationId) {
+            const result = await run(['screenshots', 'list', '--version-localization', versionLocalizationId], ascListTimeoutMs);
+            if (!isRecord(result) || !Array.isArray(result.sets)) {
+                throw new Error('asc screenshots list returned no screenshot sets.');
+            }
+            return result.sets.map((entry) => {
+                const set = isRecord(entry) ? single({ data: entry.set }, 'screenshots list set') : undefined;
+                const screenshots = isRecord(entry) ? list({ data: entry.screenshots }, 'screenshots list') : undefined;
+                if (set === undefined || screenshots === undefined) {
+                    throw new Error('asc screenshots list returned a malformed set.');
+                }
+                return {
+                    id: set.id,
+                    displayType: requiredString(set.attributes.screenshotDisplayType, 'screenshot display type'),
+                    screenshots: screenshots.map(toScreenshot),
+                };
+            });
+        },
+        async upsertAppInfoLocalization(input) {
+            await run([
+                'app-setup', 'info', 'set',
+                '--app', input.appId,
+                '--app-info', input.appInfoId,
+                '--locale', input.locale,
+                '--name', input.name,
+                ...(input.subtitle === undefined ? [] : ['--subtitle', input.subtitle]),
+                ...(input.privacyPolicyUrl === undefined ? [] : ['--privacy-policy-url', input.privacyPolicyUrl]),
+            ], ascLookupTimeoutMs);
+        },
+        async createVersionLocalization(input) {
+            return single(await run([
+                'localizations', 'create',
+                '--version', input.versionId,
+                '--locale', input.locale,
+                ...fieldFlags(input.fields),
+            ], ascLookupTimeoutMs), 'localizations create').id;
+        },
+        async updateVersionLocalization(input) {
+            const flags = fieldFlags(input.fields);
+            if (flags.length === 0) {
+                return;
+            }
+            await run(['localizations', 'update', '--id', input.localizationId, ...flags], ascLookupTimeoutMs);
+        },
+        async uploadScreenshot(input) {
+            const result = await run([
+                'screenshots', 'upload',
+                '--version-localization', input.versionLocalizationId,
+                '--path', input.file,
+                '--device-type', input.displayType,
+            ], ascUploadTimeoutMs);
+            const results = isRecord(result) && Array.isArray(result.results) ? result.results : [];
+            const [item] = results;
+            if (results.length !== 1 || !isRecord(item) || typeof item.assetId !== 'string' || item.assetId === '') {
+                throw new Error('asc screenshots upload returned no uploaded screenshot.');
+            }
+            const state = typeof item.state === 'string' ? item.state.toUpperCase() : '';
+            if (state !== 'COMPLETE') {
+                throw new Error(`App Store Connect reports screenshot ${item.assetId} as ${state || 'not delivered'}.`);
+            }
+            return { id: item.assetId, deliveryState: state };
+        },
+        async deleteScreenshot(screenshotId) {
+            await run(['screenshots', 'delete', '--id', screenshotId, '--confirm'], ascLookupTimeoutMs);
+        },
+    };
+}
+const fieldNames = [
+    ['description', '--description'],
+    ['keywords', '--keywords'],
+    ['promotionalText', '--promotional-text'],
+    ['whatsNew', '--whats-new'],
+    ['supportUrl', '--support-url'],
+    ['marketingUrl', '--marketing-url'],
+];
+function fieldFlags(fields) {
+    return fieldNames.flatMap(([field, flag]) => {
+        const value = fields[field];
+        return value === undefined ? [] : [flag, value];
+    });
+}
+function versionFields(resource) {
+    return Object.assign({}, ...fieldNames.map(([field]) => optionalString(field, resource.attributes[field])));
+}
+function toScreenshot(resource) {
+    const delivery = resource.attributes.assetDeliveryState;
+    return {
+        id: resource.id,
+        ...optionalString('fileName', resource.attributes.fileName),
+        ...optionalString('sourceFileChecksum', resource.attributes.sourceFileChecksum),
+        ...optionalString('deliveryState', isRecord(delivery) ? delivery.state : undefined),
+    };
+}

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

@@ -0,0 +1,101 @@
+/**
+* App Store Connect store page port: app information localizations (name,
+* subtitle, privacy policy URL), App Store version localizations (description,
+* keywords, promotional text, what's new, URLs) and their screenshot sets.
+* `app-store-presence-asc.ts` implements it with the pinned `asc` CLI; the
+* planner and tests see only these shapes.
+*
+* Resources (App Store Connect API):
+* - App infos and their localizations: https://developer.apple.com/documentation/appstoreconnectapi/app-infos
+* - App Store versions and their localizations: https://developer.apple.com/documentation/appstoreconnectapi/app-store-versions
+* - Screenshot sets and screenshots: https://developer.apple.com/documentation/appstoreconnectapi/app-screenshot-sets
+*/
+export interface AscAppInfo {
+  readonly id: string;
+  /** `AppInfoState` (`state`, or the older `appStoreState`), for example `PREPARE_FOR_SUBMISSION`. */
+  readonly state?: string | undefined;
+}
+export interface AscAppInfoLocalization {
+  readonly id: string;
+  readonly locale: string;
+  readonly name?: string | undefined;
+  readonly subtitle?: string | undefined;
+  readonly privacyPolicyUrl?: string | undefined;
+}
+export interface AscAppStoreVersion {
+  readonly id: string;
+  readonly versionString?: string | undefined;
+  /** `appVersionState`, or `appStoreState` when App Store Connect sends only that. */
+  readonly state?: string | undefined;
+  /** The legacy `appStoreState`; App Store Connect fills the two inconsistently. */
+  readonly appStoreState?: string | undefined;
+  readonly createdDate?: string | undefined;
+}
+/** The version localization fields the sync writes. */
+export interface AscVersionLocalizationFields {
+  readonly description?: string | undefined;
+  readonly keywords?: string | undefined;
+  readonly promotionalText?: string | undefined;
+  readonly whatsNew?: string | undefined;
+  readonly supportUrl?: string | undefined;
+  readonly marketingUrl?: string | undefined;
+}
+export interface AscVersionLocalization extends AscVersionLocalizationFields {
+  readonly id: string;
+  readonly locale: string;
+}
+export interface AscScreenshot {
+  readonly id: string;
+  readonly fileName?: string | undefined;
+  /** MD5 of the uploaded file, as App Store Connect records it. */
+  readonly sourceFileChecksum?: string | undefined;
+  /** `assetDeliveryState.state`: `AWAITING_UPLOAD`, `UPLOAD_COMPLETE`, `COMPLETE` or `FAILED`. */
+  readonly deliveryState?: string | undefined;
+}
+export interface AscScreenshotSet {
+  readonly id: string;
+  /** `screenshotDisplayType`, for example `APP_IPHONE_67`. */
+  readonly displayType: string;
+  /** In the set's order. */
+  readonly screenshots: readonly AscScreenshot[];
+}
+export interface AscStorePresencePort {
+  /** The app record's bundle ID (`apps view`). */
+  readAppBundleId(appId: string): Promise<string>;
+  listAppInfos(appId: string): Promise<AscAppInfo[]>;
+  listAppInfoLocalizations(appId: string, appInfoId: string): Promise<AscAppInfoLocalization[]>;
+  /** iOS App Store versions of the app. */
+  listVersions(appId: string): Promise<AscAppStoreVersion[]>;
+  listVersionLocalizations(versionId: string): Promise<AscVersionLocalization[]>;
+  listScreenshotSets(versionLocalizationId: string): Promise<AscScreenshotSet[]>;
+  /** Creates the locale's app information localization or updates it. */
+  upsertAppInfoLocalization(input: {
+    readonly appId: string;
+    readonly appInfoId: string;
+    readonly locale: string;
+    readonly name: string;
+    readonly subtitle?: string;
+    readonly privacyPolicyUrl?: string;
+  }): Promise<void>;
+  /** Returns the new localization's ID. */
+  createVersionLocalization(input: {
+    readonly versionId: string;
+    readonly locale: string;
+    readonly fields: AscVersionLocalizationFields;
+  }): Promise<string>;
+  updateVersionLocalization(input: {
+    readonly localizationId: string;
+    readonly fields: AscVersionLocalizationFields;
+  }): Promise<void>;
+  /**
+  * Appends one screenshot to the set of `displayType` (creating the set),
+  * waiting until App Store Connect reports the asset delivered. Throws when
+  * the delivery fails.
+  */
+  uploadScreenshot(input: {
+    readonly versionLocalizationId: string;
+    readonly displayType: string;
+    readonly file: string;
+  }): Promise<AscScreenshot>;
+  deleteScreenshot(screenshotId: string): Promise<void>;
+}