@mpgd/cli 0.61.1 → 0.63.0

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;