@mpgd/cli 0.62.0 → 0.63.0

package/dist/store-products-play.js

@@ -0,0 +1,622 @@
+import { resolveProductPlatformId, resolveStoreListingLocalizations, } from '@mpgd/catalog';
+import { canonicalLanguageTag, decimalToUnitsAndNanos, stableJson, stableSha256, StoreProductPlanStaleError, } from './store-products.js';
+// OneTimeProduct field limits (API reference): title 55, description 200,
+// product ID of digits, lowercase letters, `_` and `.`.
+const maxTitleLength = 55;
+const maxDescriptionLength = 200;
+const productIdPattern = /^[a-z0-9][a-z0-9_.]*$/u;
+const purchaseOptionIdPattern = /^[a-z0-9][a-z0-9-]{0,62}$/u;
+const defaultPurchaseOptionId = 'buy';
+const maxPrintedPriceChanges = 20;
+export async function planPlayProducts(input, port) {
+    const catalogTarget = input.catalogTarget ?? 'android';
+    const keepLivePrices = input.keepLivePrices === true;
+    const remote = await port.listOneTimeProducts(input.packageName, input.signal);
+    const remoteById = new Map();
+    for (const product of remote) {
+        if (typeof product.productId === 'string') {
+            remoteById.set(product.productId, product);
+        }
+    }
+    const conversions = new Map();
+    const convert = (money, taxCategory) => {
+        const key = stableJson({ money, taxCategory });
+        let pending = conversions.get(key);
+        if (pending === undefined) {
+            pending = port.convertRegionPrices({
+                packageName: input.packageName,
+                price: toPlayMoney(money),
+                ...(taxCategory === undefined ? {} : { productTaxCategoryCode: taxCategory }),
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+            conversions.set(key, pending);
+        }
+        return pending;
+    };
+    const products = [];
+    const skipped = [];
+    const named = new Set();
+    for (const product of input.catalog.products) {
+        const productId = resolveProductPlatformId(product, catalogTarget);
+        if (productId === undefined) {
+            continue;
+        }
+        named.add(productId);
+        if (product.type === 'subscription') {
+            skipped.push({
+                logicalId: product.id,
+                productId,
+                reason: 'subscriptions are outside the sync',
+            });
+            continue;
+        }
+        const entry = input.listings.products[product.id];
+        if (entry === undefined) {
+            skipped.push({ logicalId: product.id, productId, reason: 'no store listing' });
+            continue;
+        }
+        if (!productIdPattern.test(productId)) {
+            throw new Error(`Google Play product ID ${productId} (${product.id}) may contain only digits, lowercase letters, "_" and ".".`);
+        }
+        const remoteProduct = remoteById.get(productId);
+        const planned = await planOne({
+            packageName: input.packageName,
+            logicalId: product.id,
+            productId,
+            localizations: resolveStoreListingLocalizations(entry, 'googlePlay'),
+            googlePlay: entry.googlePlay ?? {},
+            remote: remoteProduct,
+            keepLivePrices,
+            convert,
+        });
+        if ('skip' in planned) {
+            skipped.push({ logicalId: product.id, productId, reason: planned.skip });
+        }
+        else {
+            products.push(planned);
+        }
+    }
+    const remoteOnly = [...remoteById.keys()].filter((id) => !named.has(id)).sort();
+    return {
+        schemaVersion: 1,
+        store: 'google-play',
+        packageName: input.packageName,
+        catalogTarget,
+        keepLivePrices,
+        products,
+        skipped,
+        remoteOnly,
+    };
+}
+async function planOne(input) {
+    const { productId, remote, googlePlay } = input;
+    const label = `Google Play product ${productId} (${input.logicalId})`;
+    const notes = [];
+    // Listings: the file's languages replace Play's; other languages stay.
+    const desiredListings = Object.entries(input.localizations).map(([languageCode, text]) => {
+        if ([...text.title].length > maxTitleLength) {
+            throw new Error(`${label}: the ${languageCode} title is longer than ${maxTitleLength} characters.`);
+        }
+        if ([...text.description].length > maxDescriptionLength) {
+            throw new Error(`${label}: the ${languageCode} description is longer than ${maxDescriptionLength} characters.`);
+        }
+        // Play's own spelling when it already lists the language, else BCP-47 casing.
+        const remoteSpelling = remote?.listings?.find((listing) => fold(listing.languageCode) === fold(languageCode))?.languageCode;
+        return {
+            languageCode: typeof remoteSpelling === 'string' ? remoteSpelling : canonicalLanguageTag(languageCode),
+            title: text.title,
+            description: text.description,
+        };
+    });
+    const desiredLanguages = new Set(desiredListings.map((listing) => fold(listing.languageCode)));
+    const keptListings = (remote?.listings ?? []).filter((listing) => !desiredLanguages.has(fold(listing.languageCode)));
+    if (keptListings.length > 0) {
+        notes.push(`Play keeps listing languages the file does not name: ${keptListings.map((listing) => String(listing.languageCode)).join(', ')}.`);
+    }
+    const listings = sortListings([...desiredListings, ...keptListings]);
+    // The managed purchase option.
+    const remoteOptions = remote?.purchaseOptions ?? [];
+    let purchaseOptionId = googlePlay.purchaseOptionId;
+    if (purchaseOptionId === undefined) {
+        const buyOptions = remoteOptions.filter((option) => option.buyOption !== undefined);
+        if (remoteOptions.length === 0) {
+            purchaseOptionId = defaultPurchaseOptionId;
+        }
+        else if (buyOptions.length === 1 && typeof buyOptions[0]?.purchaseOptionId === 'string') {
+            purchaseOptionId = buyOptions[0].purchaseOptionId;
+        }
+        else {
+            throw new Error(`${label} has ${remoteOptions.length} purchase options on Play; name the one to manage with `
+                + 'googlePlay.purchaseOptionId.');
+        }
+    }
+    if (!purchaseOptionIdPattern.test(purchaseOptionId)) {
+        throw new Error(`${label}: purchase option ID ${purchaseOptionId} is not a valid Play purchase option ID.`);
+    }
+    const remoteOption = remoteOptions.find((option) => option.purchaseOptionId === purchaseOptionId);
+    if (remoteOption?.rentOption !== undefined && remoteOption.rentOption !== null) {
+        throw new Error(`${label}: purchase option ${purchaseOptionId} is a rent option; the sync manages buy options only.`);
+    }
+    if (googlePlay.price === undefined) {
+        if (remote === undefined) {
+            return { skip: 'needs googlePlay.price to create the product' };
+        }
+        if (remoteOption === undefined) {
+            throw new Error(`${label}: purchase option ${purchaseOptionId} is not on Play and the file gives no price for it.`);
+        }
+    }
+    // Prices: Play's conversion of the base price, then the file's overrides.
+    let pricing;
+    if (googlePlay.price !== undefined) {
+        // Convert with the category the product keeps: the file's, else Play's.
+        const conversionTaxCategory = googlePlay.productTaxCategoryCode
+            ?? remote?.taxAndComplianceSettings?.productTaxCategoryCode ?? undefined;
+        const converted = await input.convert(googlePlay.price.base, conversionTaxCategory);
+        const regionsVersion = converted.regionVersion?.version;
+        if (typeof regionsVersion !== 'string' || regionsVersion === '') {
+            throw new Error('Google Play price conversion returned no regions version.');
+        }
+        const byRegion = new Map();
+        for (const [key, value] of Object.entries(converted.convertedRegionPrices ?? {})) {
+            const regionCode = value.regionCode ?? key;
+            if (value.price?.currencyCode === undefined || value.price.currencyCode === null) {
+                throw new Error(`Google Play price conversion returned no price for ${regionCode}.`);
+            }
+            byRegion.set(regionCode, {
+                regionCode,
+                price: normalizeMoney(value.price),
+                availability: 'AVAILABLE',
+            });
+        }
+        for (const [regionCode, money] of Object.entries(googlePlay.price.regions ?? {})) {
+            const convertedRegion = byRegion.get(regionCode);
+            if (convertedRegion === undefined) {
+                throw new Error(`${label}: Google Play does not sell in ${regionCode} at regions version ${regionsVersion}.`);
+            }
+            if (convertedRegion.price?.currencyCode !== money.currency) {
+                throw new Error(`${label}: the ${regionCode} price must be in ${String(convertedRegion.price?.currencyCode)}, not ${money.currency}.`);
+            }
+            byRegion.set(regionCode, {
+                regionCode,
+                price: toPlayMoney(money),
+                availability: 'AVAILABLE',
+            });
+        }
+        const usd = converted.convertedOtherRegionsPrice?.usdPrice;
+        const eur = converted.convertedOtherRegionsPrice?.eurPrice;
+        if (usd === undefined || eur === undefined) {
+            throw new Error('Google Play price conversion returned no USD and EUR prices for new regions.');
+        }
+        // Prices follow the file; a region's availability stays as Play has it.
+        const remoteRegions = remoteOption?.regionalPricingAndAvailabilityConfigs ?? [];
+        // An existing option is not opted in to regions it does not list (for
+        // example one Play launched after the option opted out of new regions),
+        // unless the file names the region. A new option sells everywhere.
+        if (remoteRegions.length > 0) {
+            const listed = new Set(remoteRegions.map((config) => String(config.regionCode)));
+            const named = new Set(Object.keys(googlePlay.price.regions ?? {}));
+            const unlisted = [...byRegion.keys()].filter((region) => !listed.has(region) && !named.has(region));
+            for (const region of unlisted) {
+                byRegion.delete(region);
+            }
+            if (unlisted.length > 0) {
+                notes.push(`Play sells in ${unlisted.length} region(s) this purchase option does not list; the sync `
+                    + `leaves them out (name them in googlePlay.price.regions or add them in Play Console): ${unlisted.sort().join(', ')}.`);
+            }
+        }
+        for (const config of remoteRegions) {
+            const desired = typeof config.regionCode === 'string'
+                ? byRegion.get(config.regionCode)
+                : undefined;
+            if (desired !== undefined && typeof config.availability === 'string'
+                && config.availability !== desired.availability) {
+                byRegion.set(String(config.regionCode), { ...desired, availability: config.availability });
+            }
+        }
+        const keptRegions = remoteRegions.filter((config) => typeof config.regionCode === 'string' && !byRegion.has(config.regionCode));
+        if (keptRegions.length > 0) {
+            notes.push(`Play keeps ${keptRegions.length} region(s) the conversion does not list: ${keptRegions.map((config) => String(config.regionCode)).join(', ')}.`);
+        }
+        // New regions: a new option opts in; an existing one keeps its choice.
+        const remoteNewRegions = remoteOption === undefined ? undefined : remoteOption.newRegionsConfig;
+        pricing = {
+            regional: sortRegions([...byRegion.values(), ...keptRegions]),
+            newRegions: remoteOption !== undefined && remoteNewRegions === undefined
+                ? undefined
+                : {
+                    usdPrice: normalizeMoney(usd),
+                    eurPrice: normalizeMoney(eur),
+                    availability: remoteNewRegions?.availability ?? 'AVAILABLE',
+                },
+            regionsVersion,
+        };
+    }
+    const live = remoteOption?.state === 'ACTIVE';
+    if (remoteOption?.state === 'INACTIVE' || remoteOption?.state === 'INACTIVE_PUBLISHED') {
+        notes.push(`Purchase option ${purchaseOptionId} is ${remoteOption.state} on Play; the sync does not reactivate it.`);
+    }
+    const otherLegacy = remoteOptions.some((option) => option.purchaseOptionId !== purchaseOptionId && option.buyOption?.legacyCompatible === true);
+    const baseOption = remoteOption === undefined
+        ? {
+            purchaseOptionId,
+            // Play Billing Library 7 and older see only the legacy-compatible buy option.
+            buyOption: { legacyCompatible: !otherLegacy },
+        }
+        : withoutState(remoteOption);
+    let desiredOption = {
+        ...baseOption,
+        buyOption: {
+            ...baseOption.buyOption,
+            // The backend grants one unit per purchase token and rejects any other
+            // quantity (GOOGLE_PLAY_QUANTITY_UNSUPPORTED), so multi-quantity stays off.
+            multiQuantityEnabled: false,
+        },
+        ...(pricing === undefined ? {} : {
+            regionalPricingAndAvailabilityConfigs: pricing.regional,
+            ...(pricing.newRegions === undefined ? {} : { newRegionsConfig: pricing.newRegions }),
+        }),
+    };
+    const changes = [];
+    const isNewOption = remoteOption === undefined;
+    if (remote === undefined) {
+        changes.push('listings', 'prices', 'purchase-option');
+    }
+    else {
+        if (!sameListings(remote.listings ?? [], listings)) {
+            changes.push('listings');
+        }
+        if (isNewOption) {
+            changes.push('purchase-option', 'prices');
+        }
+        else if (pricing !== undefined && !samePricing(remoteOption, desiredOption)) {
+            changes.push('prices');
+        }
+    }
+    if (!isNewOption && remoteOption.buyOption?.multiQuantityEnabled === true) {
+        changes.push('multi-quantity');
+        notes.push('Multi-quantity is turned off: the kit backend grants one unit per purchase and rejects larger quantities.');
+    }
+    const taxCategory = googlePlay.productTaxCategoryCode;
+    if (taxCategory !== undefined && remote?.taxAndComplianceSettings?.productTaxCategoryCode !== taxCategory) {
+        changes.push('tax-category');
+    }
+    let livePriceChange = live && changes.includes('prices');
+    let pricesHeld = false;
+    if (livePriceChange && input.keepLivePrices && remoteOption !== undefined) {
+        pricesHeld = true;
+        desiredOption = {
+            ...desiredOption,
+            regionalPricingAndAvailabilityConfigs: remoteOption.regionalPricingAndAvailabilityConfigs,
+            newRegionsConfig: remoteOption.newRegionsConfig,
+        };
+        changes.splice(changes.indexOf('prices'), 1);
+        livePriceChange = false;
+        notes.push('A price change on this live product is held (--keep-live-prices).');
+    }
+    const priceChanges = changes.includes('prices') ? diffPrices(remoteOption, desiredOption) : [];
+    if (isNewOption || remoteOption.state === 'DRAFT') {
+        if ((desiredOption.regionalPricingAndAvailabilityConfigs ?? []).length === 0) {
+            notes.push(`Purchase option ${purchaseOptionId} has no prices on Play; give googlePlay.price to activate it.`);
+        }
+        else {
+            changes.push('activate');
+        }
+    }
+    const remoteSha256 = remote === undefined ? null : stableSha256(remote);
+    if (changes.length === 0) {
+        return {
+            logicalId: input.logicalId,
+            productId,
+            action: 'unchanged',
+            changes,
+            purchaseOptionId,
+            live,
+            livePriceChange: false,
+            priceChanges: [],
+            notes,
+            remoteSha256,
+            desiredSha256: stableSha256({ productId, listings, desiredOption }),
+        };
+    }
+    const mask = new Set();
+    if (changes.includes('listings')) {
+        mask.add('listings');
+    }
+    if (changes.some((change) => change === 'prices' || change === 'purchase-option' || change === 'multi-quantity')) {
+        mask.add('purchaseOptions');
+    }
+    if (changes.includes('tax-category')) {
+        mask.add('taxAndComplianceSettings');
+    }
+    const purchaseOptions = isNewOption
+        ? [...remoteOptions.map(withoutState), desiredOption]
+        : remoteOptions.map((option) => option.purchaseOptionId === purchaseOptionId ? desiredOption : withoutState(option));
+    const { regionsVersion: _remoteVersion, ...remoteFields } = remote ?? {};
+    const product = {
+        ...remoteFields,
+        packageName: input.packageName,
+        productId,
+        listings,
+        purchaseOptions,
+        ...(taxCategory === undefined && remote?.taxAndComplianceSettings === undefined ? {} : {
+            taxAndComplianceSettings: {
+                ...remote?.taxAndComplianceSettings,
+                ...(taxCategory === undefined ? {} : { productTaxCategoryCode: taxCategory }),
+            },
+        }),
+    };
+    // Prices written from the conversion go with its regions version; a patch
+    // that sends Play's own prices back keeps the version Play reported.
+    const regionsVersion = pricing !== undefined && !pricesHeld
+        && (mask.has('purchaseOptions') || remote === undefined)
+        ? pricing.regionsVersion
+        : (remote?.regionsVersion?.version ?? pricing?.regionsVersion);
+    if (mask.size > 0 && (regionsVersion === undefined || regionsVersion === null || regionsVersion === '')) {
+        throw new Error(`${label}: no regions version is known for the update; give googlePlay.price.`);
+    }
+    const write = {
+        ...(mask.size === 0 ? {} : {
+            patch: {
+                product,
+                updateMask: [...mask].join(','),
+                allowMissing: remote === undefined,
+                regionsVersion: String(regionsVersion),
+            },
+        }),
+        ...(changes.includes('activate') ? { activatePurchaseOptionId: purchaseOptionId } : {}),
+    };
+    return {
+        logicalId: input.logicalId,
+        productId,
+        action: remote === undefined ? 'create' : 'update',
+        changes,
+        purchaseOptionId,
+        live,
+        livePriceChange,
+        priceChanges,
+        notes,
+        remoteSha256,
+        desiredSha256: stableSha256({ changes, write }),
+        write,
+    };
+}
+export class PlayProductApplyError extends Error {
+    productId;
+    stage;
+    done;
+    constructor(productId, stage, 
+    /** The products already written (created, updated or activated). */
+    done, cause) {
+        super(`Google Play ${stage} of ${productId} failed or its result is unknown (${cause instanceof Error ? cause.message : String(cause)}). Products already written: ${done.map((entry) => entry.productId).join(', ') || 'none'}. Run "mpgd store products plan" `
+            + 'again: it reads Play and lists what is left; writing the same product again is safe.', { cause });
+        this.productId = productId;
+        this.stage = stage;
+        this.done = done;
+        this.name = 'PlayProductApplyError';
+    }
+}
+/**
+ * Apply a reviewed plan. `current` is a fresh plan from the same inputs:
+ * apply writes only when every product it would change still has the
+ * remote state and the planned write the reviewer saw. A product that is
+ * now unchanged (an earlier apply landed) is skipped, so a re-run is safe.
+ */
+export async function applyPlayProductPlan(input) {
+    const { saved, current } = input;
+    if (!input.approved) {
+        throw new Error('Writing Google Play products requires --approve.');
+    }
+    if (saved.packageName !== current.packageName || saved.catalogTarget !== current.catalogTarget
+        || saved.keepLivePrices !== current.keepLivePrices) {
+        throw new StoreProductPlanStaleError('The saved plan was made for another app or other options.');
+    }
+    const savedById = new Map(saved.products.map((product) => [product.productId, product]));
+    const pending = current.products.filter((product) => product.action !== 'unchanged');
+    for (const product of pending) {
+        const reviewed = savedById.get(product.productId);
+        if (reviewed === undefined || reviewed.action !== product.action
+            || reviewed.remoteSha256 !== product.remoteSha256
+            || reviewed.desiredSha256 !== product.desiredSha256) {
+            throw new StoreProductPlanStaleError(`Google Play product ${product.productId} changed on Play or in the game files since the plan.`);
+        }
+    }
+    const priced = pending.filter((product) => product.livePriceChange);
+    if (priced.length > 0 && input.confirmPriceChange !== true) {
+        throw new Error(`The plan changes the price of live Google Play products (${priced.map((product) => product.productId).join(', ')}); confirm with --confirm-price-change, `
+            + 'or plan again with --keep-live-prices.');
+    }
+    const done = [];
+    for (const product of current.products) {
+        if (product.action === 'unchanged' || product.write === undefined) {
+            done.push({ productId: product.productId, status: 'unchanged' });
+            continue;
+        }
+        input.signal?.throwIfAborted();
+        const { patch, activatePurchaseOptionId } = product.write;
+        if (patch !== undefined) {
+            try {
+                await input.port.patchOneTimeProduct({
+                    packageName: current.packageName,
+                    productId: product.productId,
+                    product: patch.product,
+                    updateMask: patch.updateMask,
+                    allowMissing: patch.allowMissing,
+                    regionsVersion: patch.regionsVersion,
+                    ...(input.signal === undefined ? {} : { signal: input.signal }),
+                });
+            }
+            catch (error) {
+                throw new PlayProductApplyError(product.productId, 'patch', written(done), error);
+            }
+        }
+        if (activatePurchaseOptionId !== undefined) {
+            try {
+                await input.port.activatePurchaseOption({
+                    packageName: current.packageName,
+                    productId: product.productId,
+                    purchaseOptionId: activatePurchaseOptionId,
+                    ...(input.signal === undefined ? {} : { signal: input.signal }),
+                });
+            }
+            catch (error) {
+                // The patch before it landed: report this product as written too.
+                const patched = patch === undefined
+                    ? done
+                    : [
+                        ...done,
+                        {
+                            productId: product.productId,
+                            status: product.action === 'create' ? 'created' : 'updated',
+                        },
+                    ];
+                throw new PlayProductApplyError(product.productId, 'activate', written(patched), error);
+            }
+        }
+        done.push({
+            productId: product.productId,
+            status: product.action === 'create'
+                ? 'created'
+                : patch === undefined
+                    ? 'activated'
+                    : 'updated',
+        });
+    }
+    return { packageName: current.packageName, products: done };
+}
+/** Products an apply wrote (created, updated or activated), not the unchanged ones. */
+function written(done) {
+    return done.filter((entry) => entry.status !== 'unchanged');
+}
+/** One line per product for the terminal. */
+export function formatPlayProductPlan(plan) {
+    const lines = [`Google Play ${plan.packageName} (catalog target ${plan.catalogTarget})`];
+    for (const product of plan.products) {
+        const flags = [
+            product.live ? 'live' : undefined,
+            product.livePriceChange ? 'PRICE CHANGE ON LIVE PRODUCT' : undefined,
+        ].filter((flag) => flag !== undefined);
+        lines.push(`  ${product.action.padEnd(9)} ${product.productId} (${product.logicalId})${product.changes.length === 0 ? '' : `: ${product.changes.join(', ')}`}${flags.length === 0 ? '' : ` [${flags.join('; ')}]`}`);
+        const shown = product.priceChanges.slice(0, maxPrintedPriceChanges);
+        for (const change of shown) {
+            lines.push(`            price ${change.region}: ${change.from ?? '-'} -> ${change.to ?? '-'}`);
+        }
+        if (product.priceChanges.length > shown.length) {
+            lines.push(`            ... ${product.priceChanges.length - shown.length} more price changes in the plan file`);
+        }
+        for (const note of product.notes) {
+            lines.push(`            note: ${note}`);
+        }
+    }
+    for (const entry of plan.skipped) {
+        lines.push(`  skipped   ${entry.productId ?? '-'} (${entry.logicalId}): ${entry.reason}`);
+    }
+    for (const productId of plan.remoteOnly) {
+        lines.push(`  remote    ${productId}: only on Play; not in the catalog (never deleted)`);
+    }
+    return lines.join('\n');
+}
+function toPlayMoney(money) {
+    return { currencyCode: money.currency, ...decimalToUnitsAndNanos(money.amount) };
+}
+function normalizeMoney(money) {
+    return {
+        currencyCode: money.currencyCode ?? undefined,
+        units: money.units === undefined || money.units === null || money.units === ''
+            ? '0'
+            : BigInt(money.units).toString(),
+        nanos: money.nanos ?? 0,
+    };
+}
+function sameMoney(left, right) {
+    if (left === undefined || right === undefined) {
+        return left === right;
+    }
+    return stableJson(normalizeMoney(left)) === stableJson(normalizeMoney(right));
+}
+function samePricing(remote, desired) {
+    const index = (configs) => new Map((configs ?? []).map((config) => [String(config.regionCode), config]));
+    const left = index(remote.regionalPricingAndAvailabilityConfigs);
+    const right = index(desired.regionalPricingAndAvailabilityConfigs);
+    if (left.size !== right.size) {
+        return false;
+    }
+    for (const [region, config] of right) {
+        const other = left.get(region);
+        if (other === undefined || other.availability !== config.availability
+            || !sameMoney(other.price, config.price)) {
+            return false;
+        }
+    }
+    const a = remote.newRegionsConfig;
+    const b = desired.newRegionsConfig;
+    return a?.availability === b?.availability
+        && sameMoney(a?.usdPrice, b?.usdPrice)
+        && sameMoney(a?.eurPrice, b?.eurPrice);
+}
+function diffPrices(remote, desired) {
+    const describe = (config) => config === undefined
+        ? undefined
+        : `${formatMoney(config.price)}${config.availability === 'AVAILABLE' ? '' : ` (${String(config.availability)})`}`;
+    const left = new Map((remote?.regionalPricingAndAvailabilityConfigs ?? []).map((config) => [
+        String(config.regionCode),
+        config,
+    ]));
+    const right = new Map((desired.regionalPricingAndAvailabilityConfigs ?? []).map((config) => [
+        String(config.regionCode),
+        config,
+    ]));
+    const changes = [];
+    for (const region of [...new Set([...left.keys(), ...right.keys()])].sort()) {
+        const from = describe(left.get(region));
+        const to = describe(right.get(region));
+        if (from !== to) {
+            changes.push({
+                region,
+                ...(from === undefined ? {} : { from }),
+                ...(to === undefined ? {} : { to }),
+            });
+        }
+    }
+    const newRegions = (config) => config === undefined
+        ? undefined
+        : `${formatMoney(config.usdPrice)} / ${formatMoney(config.eurPrice)} (${String(config.availability)})`;
+    const fromNew = newRegions(remote?.newRegionsConfig);
+    const toNew = newRegions(desired.newRegionsConfig);
+    if (fromNew !== toNew) {
+        changes.push({
+            region: 'new-regions',
+            ...(fromNew === undefined ? {} : { from: fromNew }),
+            ...(toNew === undefined ? {} : { to: toNew }),
+        });
+    }
+    return changes;
+}
+function formatMoney(money) {
+    if (money === undefined) {
+        return '?';
+    }
+    const normal = normalizeMoney(money);
+    const nanos = String(normal.nanos ?? 0).padStart(9, '0').replace(/0+$/u, '');
+    return `${String(normal.units)}${nanos === '' ? '' : `.${nanos}`} ${String(normal.currencyCode)}`;
+}
+function sameListings(remote, desired) {
+    const normal = (listings) => stableJson(sortListings(listings).map((listing) => ({
+        languageCode: listing.languageCode,
+        title: listing.title,
+        description: listing.description,
+    })));
+    return normal(remote) === normal(desired);
+}
+function sortListings(listings) {
+    return [...listings].sort((left, right) => String(left.languageCode).localeCompare(String(right.languageCode)));
+}
+function sortRegions(configs) {
+    return [...configs].sort((left, right) => String(left.regionCode).localeCompare(String(right.regionCode)));
+}
+function withoutState(option) {
+    const { state: _state, ...rest } = option;
+    return rest;
+}
+function fold(value) {
+    return String(value).toLowerCase();
+}

package/dist/store-products.d.ts

@@ -0,0 +1,46 @@
+import { type ProductCatalog, type StoreListingCatalog } from '@mpgd/catalog';
+/**
+* Shared pieces of `mpgd store products plan|apply`: the game files the sync
+* reads, the saved plan file, and the stable digests apply uses to refuse a
+* plan the store or the files have moved past.
+*/
+export type StoreProductAction = 'create' | 'update' | 'unchanged';
+export declare const defaultStoreListingFileName = "mpgd.store-listings.json";
+export declare const defaultProductCatalogFileName = "mpgd.catalog.json";
+export interface StoreProductSources {
+  readonly catalogFile: string;
+  readonly listingsFile: string;
+  readonly catalog: ProductCatalog;
+  readonly listings: StoreListingCatalog;
+}
+/**
+* Read and cross-check the game's product catalog and store listing file.
+* Given paths resolve against the current directory, like every other mpgd
+* file flag (`deploy --plan`, `--release-notes`); the defaults are the
+* game's own files.
+*/
+export declare function readStoreProductSources(input: {
+  readonly gameRoot: string;
+  readonly catalogFile?: string;
+  readonly listingsFile?: string;
+}): StoreProductSources;
+/** JSON with object keys sorted, so equal values always hash the same. */
+export declare function stableJson(value: unknown): string;
+export declare function stableSha256(value: unknown): string;
+/** A new plan file, never overwriting one (the same rule as `deploy plan --out`). */
+export declare function writeStoreProductPlan(file: string, plan: unknown): string;
+export declare function readStoreProductPlanFile(file: string): Record<string, unknown>;
+export declare class StoreProductPlanStaleError extends Error {
+  constructor(detail: string);
+}
+/** Decimal string (`"0.99"`) as whole units and nanos, without floating point. */
+export declare function decimalToUnitsAndNanos(amount: string): {
+  units: string;
+  nanos: number;
+};
+/** Decimal strings compared by value: `0.99` equals `0.990`. */
+export declare function sameDecimal(left: string, right: string): boolean;
+/** BCP-47 casing: language lowercase, script title case, region uppercase. */
+export declare function canonicalLanguageTag(tag: string): string;
+/** `map` with at most `limit` calls in flight; results keep input order. */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, map: (item: T) => Promise<R>): Promise<R[]>;