@mpgd/cli 0.62.0 → 0.64.0

package/dist/store-presence.js

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { assertStorePresence, assertStorePresenceImage, readStoreImageInfo, } from '@mpgd/catalog';
+import { readJsonFile, StorePlanStaleError } from './store-sync.js';
+/**
+ * The game side of `mpgd store presence plan|apply`: the store presence
+ * file and the graphics it names, read and checked against the store rules
+ * before anything talks to a store.
+ */
+export const defaultStorePresenceFileName = 'mpgd.store-presence.json';
+export const storePresencePlanCommand = 'mpgd store presence plan';
+/**
+ * Read and validate the store presence file. A given path resolves against
+ * the current directory, like the other mpgd file flags; the default is the
+ * game's own file.
+ */
+export function readStorePresenceSource(input) {
+    const file = input.presenceFile === undefined
+        ? path.join(path.resolve(input.gameRoot), defaultStorePresenceFileName)
+        : path.resolve(input.presenceFile);
+    if (!existsSync(file)) {
+        throw new Error(`Store presence sync needs ${file}.`);
+    }
+    return { file, directory: path.dirname(file), presence: assertStorePresence(readJsonFile(file)) };
+}
+/**
+ * Read one graphic: it must stay inside the file's directory (symbolic links
+ * included), be the PNG or JPEG its extension says, and meet the store's
+ * rules for its slot.
+ */
+export function readLocalStoreImage(directory, relative, target, label) {
+    const file = path.resolve(directory, relative);
+    if (!existsSync(file) || !statSync(file).isFile()) {
+        throw new Error(`${label}: ${relative} is missing.`);
+    }
+    const real = path.relative(realpathSync(directory), realpathSync(file));
+    if (real === '..' || real.startsWith(`..${path.sep}`) || path.isAbsolute(real)) {
+        throw new Error(`${label}: ${relative} resolves outside the store presence file's directory.`);
+    }
+    const bytes = readFileSync(file);
+    let info;
+    try {
+        info = readStoreImageInfo(bytes);
+    }
+    catch (error) {
+        throw new Error(`${label}: ${relative} is ${error.message}.`);
+    }
+    const extensionFormat = /\.png$/iu.test(relative) ? 'png' : 'jpeg';
+    if (info.format !== extensionFormat) {
+        throw new Error(`${label}: ${relative} is a ${info.format} file with a .${path.extname(relative).slice(1)} name.`);
+    }
+    assertStorePresenceImage(target, info, bytes.byteLength, `${label}: ${relative}`);
+    return {
+        path: relative,
+        file,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+        sha1: createHash('sha1').update(bytes).digest('hex'),
+        md5: createHash('md5').update(bytes).digest('hex'),
+        byteLength: bytes.byteLength,
+        info,
+    };
+}
+/** Refuse to upload a graphic whose bytes changed after the plan was checked. */
+export function assertLocalStoreImageUnchanged(file, sha256) {
+    const current = createHash('sha256').update(readFileSync(file)).digest('hex');
+    if (current !== sha256) {
+        throw new StorePlanStaleError(`${file} changed since the plan.`, storePresencePlanCommand);
+    }
+}
+export function imageMimeType(info) {
+    return info.format === 'png' ? 'image/png' : 'image/jpeg';
+}
+const shortText = 80;
+/** CRLF and lone CR as LF, so a file saved on Windows and the store's text compare equal. */
+export function normalizeLineBreaks(value) {
+    return value.replace(/\r\n?/gu, '\n');
+}
+/**
+ * Two URLs that differ only in form (host case, a trailing slash, default
+ * port): a store may normalize the URL it was given.
+ */
+export function sameUrlForm(left, right) {
+    const normal = (value) => {
+        try {
+            return new URL(value).href.replace(/\/$/u, '');
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const a = normal(left);
+    return a !== undefined && a === normal(right);
+}
+/** Compares after normalizing line breaks; `to` is expected normalized already. */
+export function describeTextChange(field, from, to) {
+    const before = typeof from === 'string' ? normalizeLineBreaks(from) : null;
+    if (before === to) {
+        return undefined;
+    }
+    const short = (value) => value === null || [...value].length <= shortText;
+    return {
+        field,
+        fromLength: before === null ? null : [...before].length,
+        toLength: [...to].length,
+        ...(short(before) && short(to) ? { ...(before === null ? {} : { from: before }), to } : {}),
+    };
+}
+export function formatTextChange(change) {
+    const lengths = `${change.fromLength === null ? 'new' : `${change.fromLength} chars`} -> ${change.toLength} chars`;
+    if (change.to === undefined) {
+        return `${change.field}: ${lengths}`;
+    }
+    return `${change.field}: ${JSON.stringify(change.from ?? null)} -> ${JSON.stringify(change.to)}`;
+}
+/**
+ * Plan one image slot. A single-image slot (an icon) is replaced when it
+ * differs. A list adds the images the store lacks after the ones it holds;
+ * a complete set appends when the store holds a prefix of it, else replaces
+ * the slot so the store holds exactly the set in order.
+ */
+export function planStoreImageSet(input) {
+    const { local, remote, storeName } = input;
+    const remoteDigests = remote.map((image) => image.digest);
+    const desiredDigests = local.map((image) => image.digest);
+    const notes = [];
+    const unchanged = () => ({
+        action: 'unchanged',
+        upload: [],
+        keep: remoteDigests,
+        remove: [],
+        notes,
+    });
+    const replace = () => ({
+        action: 'replace',
+        upload: local,
+        keep: [],
+        remove: remote.filter((image) => !desiredDigests.includes(image.digest)),
+        notes,
+    });
+    const same = remoteDigests.length === desiredDigests.length
+        && remoteDigests.every((digest, index) => digest === desiredDigests[index]);
+    if (same) {
+        return unchanged();
+    }
+    if (input.single) {
+        return remote.length === 0
+            ? { action: 'add', upload: local, keep: [], remove: [], notes }
+            : replace();
+    }
+    const isPrefix = remoteDigests.length < desiredDigests.length
+        && remoteDigests.every((digest, index) => digest === desiredDigests[index]);
+    if (input.complete && !isPrefix) {
+        if (remote.some((image) => desiredDigests.includes(image.digest))) {
+            notes.push(`${storeName}'s images are deleted and the set uploaded again in the file's order.`);
+        }
+        return replace();
+    }
+    const missing = local.filter((image) => !remoteDigests.includes(image.digest));
+    if (missing.length === 0) {
+        notes.push(`${storeName} holds the file's images in another order or with others; mark the set complete to match it.`);
+        return unchanged();
+    }
+    if (remote.length + missing.length > input.maxImages) {
+        throw new Error(`${input.label}: ${storeName} holds ${remote.length} and the file adds ${missing.length}; a set takes at `
+            + `most ${input.maxImages}. Mark the set complete to replace ${storeName}'s images.`);
+    }
+    const kept = remote.length - (local.length - missing.length);
+    if (!input.complete && kept > 0) {
+        notes.push(`${storeName} keeps ${kept} image(s) the file does not list.`);
+    }
+    return { action: 'add', upload: missing, keep: remoteDigests, remove: [], notes };
+}

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

@@ -0,0 +1,144 @@
+import { type ProductCatalog, type StoreListingCatalog } from '@mpgd/catalog';
+import type { AscIapPort, AscIapType } from './app-store-iap-port.js';
+import { type StoreProductAction } from './store-products.js';
+/**
+* App Store Connect in-app purchase sync: compare the game's catalog and
+* store listing file with App Store Connect and plan the writes. The plan
+* only reads; in-app purchases only on App Store Connect are reported, never
+* deleted; localizations and territories the file does not name are kept.
+* Nothing is submitted for review: an in-app purchase's first review goes
+* with an app version (App Store Connect Help, "Submit an In-App Purchase").
+*/
+export type AppStoreProductChange = 'create' | 'reference-name' | 'family-sharing' | 'version' | 'localizations' | 'prices' | 'availability' | 'review-screenshot';
+export interface AppStoreLocalizationEntry {
+  readonly locale: string;
+  readonly name: string;
+  readonly description: string;
+}
+export interface AppStoreProductWrite {
+  readonly create?: {
+    readonly type: AscIapType;
+    readonly referenceName: string;
+    readonly familySharable: boolean;
+  };
+  readonly update?: {
+    readonly referenceName?: string;
+    readonly familySharable?: true;
+  };
+  /**
+  * Localizations to upsert by locale. `existing` writes to `versionId`;
+  * `create` makes a new draft version first (App Store Connect copies the
+  * current metadata into it); `resolve` (a new in-app purchase) uses the
+  * version App Store Connect provisioned, or creates one.
+  */
+  readonly localizations?: {
+    readonly version: 'existing' | 'create' | 'resolve';
+    readonly versionId?: string;
+    readonly entries: readonly AppStoreLocalizationEntry[];
+  };
+  /** A new schedule effective now; the base territory's price comes first. */
+  readonly prices?: {
+    readonly baseTerritory: string;
+    /** `pricePointId` is resolved at plan time for an existing in-app purchase. */
+    readonly prices: readonly {
+      readonly territory: string;
+      readonly customerPrice: string;
+      readonly pricePointId?: string;
+    }[];
+  };
+  readonly availability?: {
+    readonly territories: readonly string[];
+    readonly availableInNewTerritories: boolean;
+  };
+  readonly reviewScreenshot?: {
+    /** Absolute path on this checkout. */
+    readonly file: string;
+    /** Path relative to the listing file, as the file names it. */
+    readonly path: string;
+    readonly md5: string;
+    /** The completed screenshot to delete first (App Store Connect keeps one). */
+    readonly replaceId?: string;
+  };
+}
+export interface AppStorePriceChange {
+  /** Alpha-3 territory, or `base-territory`. */
+  readonly territory: string;
+  readonly from?: string;
+  readonly to?: string;
+}
+export interface PlannedAppStoreProduct {
+  readonly logicalId: string;
+  readonly productId: string;
+  readonly action: StoreProductAction;
+  readonly changes: readonly AppStoreProductChange[];
+  readonly iapId?: string;
+  readonly state?: string;
+  /** `APPROVED`: the in-app purchase is on sale wherever the app is. */
+  readonly live: boolean;
+  readonly livePriceChange: boolean;
+  readonly priceChanges: readonly AppStorePriceChange[];
+  readonly notes: readonly string[];
+  readonly remoteSha256: string | null;
+  readonly desiredSha256: string;
+  readonly write?: AppStoreProductWrite;
+}
+export interface AppStoreProductPlan {
+  readonly schemaVersion: 1;
+  readonly store: 'app-store';
+  /** Numeric App Store Connect app ID. */
+  readonly appId: string;
+  readonly bundleId: string;
+  readonly catalogTarget: string;
+  readonly keepLivePrices: boolean;
+  readonly products: readonly PlannedAppStoreProduct[];
+  readonly skipped: readonly {
+    readonly logicalId: string;
+    readonly productId?: string;
+    readonly reason: string;
+  }[];
+  /** Product IDs on App Store Connect that no catalog product names. Never deleted. */
+  readonly remoteOnly: readonly string[];
+  /** What the sync cannot do; the reviewer does it in App Store Connect. */
+  readonly manual: readonly string[];
+}
+export interface AppStoreProductPlanInput {
+  readonly appId: string;
+  readonly bundleId: string;
+  readonly catalog: ProductCatalog;
+  readonly listings: StoreListingCatalog;
+  /** Directory of the listing file; review screenshot paths resolve against it. */
+  readonly listingsDirectory: string;
+  /** Catalog `platformProductIds` key of the App Store; defaults to `ios`. */
+  readonly catalogTarget?: string;
+  readonly keepLivePrices?: boolean;
+}
+export declare function planAppStoreProducts(input: AppStoreProductPlanInput, port: AscIapPort): Promise<AppStoreProductPlan>;
+export interface AppStoreProductApplyResult {
+  readonly appId: string;
+  readonly products: readonly {
+    readonly productId: string;
+    readonly status: 'created' | 'updated' | 'unchanged';
+    readonly iapId?: string;
+  }[];
+  readonly manual: readonly string[];
+}
+export declare class AppStoreProductApplyError extends Error {
+  readonly productId: string;
+  readonly stage: string;
+  readonly done: AppStoreProductApplyResult['products'];
+  constructor(productId: string, stage: string, done: AppStoreProductApplyResult['products'], cause: unknown, detail?: string);
+}
+/**
+* Apply a reviewed plan, like the Google Play apply: `current` is a fresh
+* plan, and every product apply would write must still match the reviewed
+* remote state and planned write.
+*/
+export declare function applyAppStoreProductPlan(input: {
+  readonly saved: AppStoreProductPlan;
+  readonly current: AppStoreProductPlan;
+  readonly port: AscIapPort;
+  readonly approved: boolean;
+  readonly confirmPriceChange?: boolean;
+}): Promise<AppStoreProductApplyResult>;
+/** One line per product for the terminal, then the manual steps. */
+export declare function formatAppStoreProductPlan(plan: AppStoreProductPlan): string;