storebound/cli/lib/config.ts
CRT d3cc7e43d4 Product Page Optimization through the API (apple ppo) and an optional 6.3" iPhone size key
apple ppo status | create --variant b[,c] | upload --variant b | start | stop: v2 experiments (platform IOS, traffic
proportion), one treatment per shots variant (max 3), a treatment localization per App Store locale, and the variant
renders synced into the treatment screenshot sets (shared MD5-idempotent set sync with apple screenshots, which no
longer creates sets on --dry). start / stop ask first and are not MCP tools; MCP: apple_ppo_status, apple_ppo_create,
apple_ppo_upload. Play experiments stay console-only (documented).
apple.iphoneMedium (off by default): iphone-medium size key, 1206 x 2622 (1179 x 2556 accepted), uploaded as
APP_IPHONE_61; rendered, checked, required and uploaded only when enabled. Apple's scaling rule documented in the config
and the store-screenshots skill.
2026-10-10 23:28:10 +08:00

443 lines
23 KiB
TypeScript

// Per-project config (storebound.config.ts at the project root). Everything game-specific lives here; credentials never
// do (see credentials.ts). The file default-exports a plain object; `import type { ShipConfig }` is optional.
import { existsSync } from 'node:fs';
import { dirname, isAbsolute, join, resolve } from 'node:path';
import { validateCapture, validateRecord } from '../shots/devices';
import { type TfConfig, validateTestflight } from './testflight';
export type ProductType = 'consumable' | 'non_consumable';
export interface PriceOverride {
/** ISO 3166-1 alpha-2 region for Play, e.g. "TR". */
region: string;
/** App Store territory (alpha-3), e.g. "TUR". Looked up from `region` when left out. */
territory?: string;
/** ISO 4217 currency, e.g. "TRY". */
currency: string;
/** Customer price in that currency, e.g. 129.99. Apple needs an existing price point with exactly this value. */
price: number;
}
export interface ProductListing { title: string; description: string }
export interface Product {
/** Store product id (same on both stores), e.g. "com.example.game.no_ads". */
id: string;
type: ProductType;
/** Base price in USD. Play converts it per region (convertRegionPrices); Apple equalizes it from the USA base. */
usd: number;
overrides?: PriceOverride[];
/** Language id (see `languages`) -> title + description. Apple: title 30, description 45 characters. */
listings: Record<string, ProductListing>;
/** Apple only: internal reference name (defaults to the first listing title). */
referenceName?: string;
/** Apple only: note for the reviewer on this product. */
reviewNote?: string;
/** Apple only: review screenshot (path relative to the project root). */
reviewScreenshot?: string;
familySharable?: boolean;
}
export interface Language {
/** Your id for the language; also the folder name under the renders dir and the key in copy files. */
id: string;
/** Play listing language code(s), e.g. "en-US" or ["es-ES", "es-419"]. Leave out to skip on Play. */
play?: string | string[];
/** App Store Connect locale, e.g. "en-US", "tr", "zh-Hans". Leave out to skip on the App Store. */
apple?: string;
rtl?: boolean;
}
export type PlayPurpose = 'functionality' | 'analytics' | 'communications' | 'fraud' | 'advertising' | 'personalization' | 'account';
export interface DataUsage {
/** Transferred to a third party that is not your service provider (ad networks usually are "shared"). */
shared: boolean;
ephemeral?: boolean;
/** Only true when the user can really choose (Play rejects "optional" otherwise). */
optional?: boolean;
collect: PlayPurpose[];
share?: PlayPurpose[];
}
export interface DataSafety {
collectsData: boolean;
encryptedInTransit: boolean;
deletionRequest: boolean;
/** Response ids for PSL_SUPPORTED_ACCOUNT_CREATION_METHODS. Default ["PSL_ACM_NONE"] (no accounts). */
accountCreation?: string[];
/** Play data type id (e.g. "PSL_DEVICE_ID") -> usage. Types not listed are "not collected". */
data: Record<string, DataUsage>;
}
export interface ShotBadgeSlot { y: number; side: 'l' | 'r'; icon?: string; iconBg?: string; hot?: boolean; stars?: boolean; rot?: number }
export interface ShotFrame { src: string; x?: number; dy?: number; scale?: number; rotate?: number }
export interface Palette { bg: [string, string, string]; glow: string; ink: string; shadow: string }
export interface ShotScene { id: string; palette: string | Palette; hero?: boolean; frames: ShotFrame[]; badges?: ShotBadgeSlot[]; over?: number }
export interface ShotsConfig {
/** JSON file: { [languageId]: { [sceneId]: { eyebrow, title: [line1, line2], sub, badges: [[big, small?]] } } } */
copy: string;
/** Raw frames: <frames>/<languageId>/<phone|tablet>/<name>.png */
frames: string;
/** Output: <out>/<languageId>/<size>/NN.png and feature/1024x500.png */
out: string;
/** Optional logo image for the hero scene and the feature graphic. */
logo?: string;
/** Google Fonts families for titles / body text (downloaded and subset by `shots fonts`). */
fonts?: { title?: string; body?: string };
scenes: ShotScene[];
feature?: { frame: string; palette?: string | Palette };
/** Phone screen size of the raw frames in CSS px (default 440 x 902 @3x, iPhone 6.9" minus the 54 px status bar).
* `bar` = status bar height the template draws above the frame (and that capture crops off). */
phone?: { w: number; h: number; dpr?: number; bar?: number };
/** Tablet frames: default 1032 x 1352 @2x (13" iPad minus its 24 px bar) with apple.ipad, else 800 x 1240 @2x. */
tablet?: { w: number; h: number; dpr?: number; bar?: number };
/** Optional capture of raw frames (web build, iOS Simulator, Android emulator / device, or your own folder). */
capture?: ShotsCapture;
/** A/B variants: other scene orders / copy, rendered into <out>/<variant>/<lang>/... (`shots render --variant b`). */
variants?: Record<string, ShotVariant>;
/** App preview / promo video from gameplay clips (`shots record`, `shots video`). */
video?: VideoConfig;
}
/** One raw frame. Web: `path` (+ query). Simulator / emulator: `url` deep link and / or `args` / `extras`. */
export interface ShotSpec {
/** Web: URL path after baseUrl, "{lang}" replaced. */
path?: string;
/** ios-sim / android-emu: deep link opened after launch, e.g. "mygame://shot/{shot}?lang={lang}". */
url?: string;
/** Web: JS expression polled until true. */
waitFor?: string;
/** Wait before the screenshot (ms). Default 1000 (web) / 2500 (simulator, emulator). */
delayMs?: number;
/** Web: JS run in the page before the screenshot. */
eval?: string[];
device?: 'phone' | 'tablet' | 'both';
/** ios-sim: extra launch arguments, e.g. ["-shotScene", "{shot}", "-seed", "1"] (read them with UserDefaults / your engine). */
args?: string[];
/** android-emu: intent extras for `am start` (string / int / float / boolean), "{lang}" replaced in strings. */
extras?: Record<string, string | number | boolean>;
}
export interface ShotsCapture {
/** Where frames come from. Default "web". */
source?: 'web' | 'ios-sim' | 'android-emu' | 'folder';
/** web: URL of the running game, e.g. http://127.0.0.1:5173 */
baseUrl?: string;
/** web: appended to every URL, e.g. "lang={lang}&noads=1". */
query?: string;
ios?: {
/** Simulator name or UDID for phone shots, e.g. "iPhone 17 Pro Max" (6.9"). */
device?: string;
devices?: { phone?: string; tablet?: string };
bundleId: string;
/** Optional .app to install first (a Simulator build: xcodebuild -sdk iphonesimulator, Unity / Godot / Flutter export). */
app?: string;
/** Launch arguments for every shot ("{lang}", "{shot}" replaced). */
args?: string[];
/** Status bar override 9:41, full battery and signal. Default true. */
statusBar?: boolean;
/** After storebound boots a simulator: launch the app once and wait this long before the first shot (a cold
* first launch is much slower than the next ones). Default 8000 ms; 0 turns it off. */
warmupMs?: number;
};
android?: {
/** adb serial (adb devices); default: the only device. */
serial?: string;
serials?: { phone?: string; tablet?: string };
package: string;
/** Launch activity when a shot has no deep link. Default ".MainActivity". */
activity?: string;
/** Optional APK to install first. */
apk?: string;
/** System UI demo mode (clean status bar). Default true. */
demoMode?: boolean;
/** Per-app language via `cmd locale set-app-locales` (Android 13+). Default true. */
appLocale?: boolean;
};
/** folder: where your frames are (default shots.frames): <dir>/<lang>/<phone|tablet>/<name>.png */
folder?: string;
/** Rows cut from the top of a simulator / emulator screenshot (its status bar; the template draws one). A number for
* every device, or per device class. Default: the frame's bar share of the height (phone 54 / 956 = 162 px on a 6.9"
* iPhone, 13" iPad 24 / 1376 = 48 px). */
cropTop?: number | { phone?: number; tablet?: number };
shots: Record<string, ShotSpec>;
}
export interface ShotVariant {
/** Scene ids in the order this variant shows them (a subset is fine). Default: the base order. */
scenes?: string[];
/** Copy file merged over the base copy per language and scene (only the scenes / fields that change). */
copy?: string;
/** Palette per scene id. */
palettes?: Record<string, string | Palette>;
}
export interface VideoConfig {
/** Gameplay clips: <clips>/<lang>/*.mp4|mov, or <clips>/*.mp4|mov shared by every language. Default store/video/clips. */
clips?: string;
/** Target length in seconds (15-30 for App Store previews). Default 25. */
seconds?: number;
/** Outputs: iphone (886x1920), ipad (1200x1600, iPad apps), youtube (1080x1920), youtube-landscape (1920x1080). */
targets?: string[];
/** Caption overlays from the screenshot copy (scene titles), one per clip. Default true. */
captions?: boolean;
/** Scene ids whose titles caption the clips, in order. Default: the scene order. */
captionScenes?: string[];
/** Music / sound file mixed in (looped, faded out). Default: a silent stereo track (Apple wants an audio track). */
audio?: string;
/** Poster frame time in seconds (App Store shows it before playback). Default 5. */
poster?: number;
/** cover (crop to fill, default) or contain (letterbox on `background`). */
fit?: 'cover' | 'contain';
background?: string;
/** Gameplay clips recorded by `storebound shots record` into <clips>/<lang>/NN-<name>.mp4. */
record?: VideoRecord;
}
/** How `shots record` films clips. Uses shots.capture for the web URL / simulator / emulator settings. */
export interface VideoRecord {
/** Default: shots.capture.source (web when unset). folder = only list / check the clips you put there yourself. */
source?: 'web' | 'ios-sim' | 'android-emu' | 'folder';
/** Which frame size / simulator / emulator: phone (default) or tablet. */
device?: 'phone' | 'tablet';
/** Clip name -> what to film, in order. */
clips: Record<string, ClipSpec>;
}
export interface ClipSpec {
/** Length in seconds (1-60). */
seconds: number;
/** web: URL path after shots.capture.baseUrl ("{lang}" replaced), e.g. "/?level=3&autoplay=1". */
path?: string;
/** web: JS expression polled until true before filming starts. */
waitFor?: string;
/** web: JS run before filming starts. */
eval?: string[];
/** ios-sim / android-emu: deep link opened after launch. */
url?: string;
/** ios-sim: extra launch arguments ("{lang}", "{shot}" = the clip name). */
args?: string[];
/** android-emu: intent extras for `am start`. */
extras?: Record<string, string | number | boolean>;
/** Wait after launch before filming (ms). Default 1000 (web) / 2500 (simulator, emulator). */
delayMs?: number;
}
export interface IconsConfig {
/** 1024 opaque composite (the full icon). */
composite: string;
/** 1024 RGBA subject on transparent background (adaptive foreground). */
foreground?: string;
/** 1024 opaque background (adaptive background). */
background?: string;
/** Output dir for the store icons (app-store-1024.png, play-512.png). */
out: string;
/** Web icons (icon-512/192/180, favicon-64/32, maskable-512). */
web?: string;
/** @capacitor/assets source dir (icon-only, icon-foreground, icon-background). */
capacitorAssets?: string;
/** Command to run after writing the capacitor sources, e.g. "bunx @capacitor/assets generate". */
capacitorCommand?: string;
/** Android res dir; legacy ic_launcher{,_round}.png get redrawn from the adaptive layers. */
androidRes?: string;
adaptiveScale?: number;
maskableScale?: number;
}
export interface AppleAppInfo {
categories?: { primary: string; primarySubOne?: string; primarySubTwo?: string; secondary?: string };
/** Overrides for the age rating declaration; everything else is NONE / false. */
ageRating?: Record<string, string | boolean | null>;
contentRights?: 'DOES_NOT_USE_THIRD_PARTY_CONTENT' | 'USES_THIRD_PARTY_CONTENT';
/** Free app, available in every territory and new ones. */
free?: boolean;
reviewNotes?: string;
}
export interface ShipConfig {
app: {
name: string;
copyright?: string;
privacyPolicyUrl: string;
supportUrl: string;
marketingUrl?: string;
website: string;
contactEmail: string;
};
languages: Language[];
play?: {
packageName: string; defaultLanguage?: string; listing?: string; icon?: string;
/** Promo video: a YouTube URL (public or unlisted, ads off, embeddable). Play takes no video upload. Sent by `play listing`. */
video?: string;
/** Cloud Storage bucket of the Play Console report exports, e.g. "pubsite_prod_rev_<number>" (Play Console >
* Download reports > Statistics > Copy Cloud Storage URI). Used by `storebound analytics snapshot`. */
reportsBucket?: string;
};
apple?: {
bundleId: string; appId?: string; primaryLocale?: string; listing?: string; info?: AppleAppInfo; reviewShots?: string;
/**
* Export compliance answer for every build (`storebound apple encryption`, `validate`). false ONLY when the game uses
* no encryption beyond what the OS provides (HTTPS / TLS through the system, standard auth). Never set it to false
* to skip the question: a wrong answer is a legal problem, not a store one. Unset = storebound will not answer.
*/
usesNonExemptEncryption?: boolean;
/** Screenshot display types every locale must have (validate). Default ["APP_IPHONE_67"] (+ "APP_IPAD_PRO_3GEN_129" with ipad). */
screenshotTypes?: string[];
/** The app runs on iPad: renders, checks and uploads 13" iPad screenshots (2064 x 2752) and iPad app previews. */
ipad?: boolean;
/**
* Also render, check and upload a 6.3" iPhone set (Dynamic Island, medium display, 1206 x 2622 -> APP_IPHONE_61).
* Off by default: App Store Connect lists a medium-display screenshot as required for iPhone but fills it by
* scaling the 6.5" set down when it is missing, and the 6.9" set covers the large displays. Turn it on for
* pixel-exact art on 6.3" phones, or if Apple stops scaling. (Screenshot specifications, App Store Connect Help.)
*/
iphoneMedium?: boolean;
/** TestFlight beta groups, the tester CSV (in .storebound/) and Test Information (`storebound apple testflight`). */
testflight?: TfConfig;
};
products?: Product[];
/** Price sheet for `storebound prices export | import` (product x store x region). */
prices?: {
/** CSV path. Default store/prices.csv. */
csv?: string;
/** App Store base territory of every price schedule (alpha-3). Default: the current one, else USA. */
baseTerritory?: string;
};
dataSafety?: DataSafety;
/** Ads: `validate` checks that <app.website>/app-ads.txt is reachable and contains every line listed here. */
ads?: { appAdsTxt?: string[] };
/** Rendered store graphics dir (<renders>/<languageId>/<size>/NN.png|jpg). Defaults to shots.out. */
renders?: string;
shots?: ShotsConfig;
icons?: IconsConfig;
}
/** Identity helper for typed configs: `export default defineConfig({...})`. */
export const defineConfig = (c: ShipConfig): ShipConfig => c;
const ID_RE = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+$/;
const PRODUCT_RE = /^[A-Za-z0-9._]+$/;
const URL_RE = /^https:\/\/\S+$/;
/** Every problem with a config, empty when it is fine. Pure (no IO). */
export function validateConfig(c: unknown): string[] {
const e: string[] = [];
const cfg = c as Partial<ShipConfig>;
if (!cfg || typeof cfg !== 'object') return ['config must be an object'];
const app = cfg.app;
if (!app) e.push('app: missing');
else {
if (!app.name) e.push('app.name: missing');
for (const k of ['privacyPolicyUrl', 'supportUrl', 'website'] as const) if (!URL_RE.test(app[k] ?? '')) e.push(`app.${k}: must be an https URL`);
if (app.marketingUrl && !URL_RE.test(app.marketingUrl)) e.push('app.marketingUrl: must be an https URL');
if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(app.contactEmail ?? '')) e.push('app.contactEmail: not an email address');
}
const langs = cfg.languages;
if (!Array.isArray(langs) || !langs.length) e.push('languages: at least one language');
const ids = new Set<string>();
for (const [i, l] of (langs ?? []).entries()) {
if (!l.id) e.push(`languages[${i}].id: missing`);
if (ids.has(l.id)) e.push(`languages[${i}].id: duplicate "${l.id}"`);
ids.add(l.id);
}
if (cfg.play && !ID_RE.test(cfg.play.packageName ?? '')) e.push('play.packageName: not a package name (com.example.game)');
if (cfg.play?.video && !/^https:\/\/(www\.youtube\.com\/watch\?v=[\w-]{6,}|youtu\.be\/[\w-]{6,})$/.test(cfg.play.video))
e.push('play.video: a plain YouTube video URL (https://www.youtube.com/watch?v=... or https://youtu.be/...), no playlist, channel or extra parameters');
if (cfg.play?.reportsBucket && !/^(gs:\/\/)?pubsite_prod(_rev)?_\d+\/?$/.test(cfg.play.reportsBucket))
e.push('play.reportsBucket: the Play reports bucket, e.g. "pubsite_prod_rev_<number>" (Play Console > Download reports > Copy Cloud Storage URI)');
if (cfg.apple) {
if (!ID_RE.test(cfg.apple.bundleId ?? '')) e.push('apple.bundleId: not a bundle id (com.example.game)');
if (cfg.apple.appId && !/^\d+$/.test(cfg.apple.appId)) e.push('apple.appId: numeric Apple ID of the app (App Store Connect > App Information)');
const enc = cfg.apple.usesNonExemptEncryption;
if (enc !== undefined && typeof enc !== 'boolean') e.push('apple.usesNonExemptEncryption: true | false');
if (cfg.apple.screenshotTypes && !cfg.apple.screenshotTypes.every(t => /^APP_[A-Z0-9_]+$/.test(t))) e.push('apple.screenshotTypes: display types like APP_IPHONE_67');
e.push(...validateTestflight(cfg.apple.testflight));
}
if (cfg.ads?.appAdsTxt && !cfg.ads.appAdsTxt.every(l => typeof l === 'string' && l.split(',').length >= 3))
e.push('ads.appAdsTxt: lines like "example-network.com, pub-123, DIRECT, abc123"');
const seen = new Set<string>();
for (const [i, p] of (cfg.products ?? []).entries()) {
const at = `products[${i}]`;
if (!PRODUCT_RE.test(p.id ?? '')) e.push(`${at}.id: letters, digits, "." and "_" only`);
if (seen.has(p.id)) e.push(`${at}.id: duplicate "${p.id}"`);
seen.add(p.id);
if (p.type !== 'consumable' && p.type !== 'non_consumable') e.push(`${at}.type: consumable | non_consumable`);
if (!(typeof p.usd === 'number' && p.usd > 0)) e.push(`${at}.usd: positive number`);
if (!p.listings || !Object.keys(p.listings).length) e.push(`${at}.listings: at least one language`);
for (const [lang, l] of Object.entries(p.listings ?? {})) {
if (!ids.has(lang)) e.push(`${at}.listings.${lang}: not in languages`);
if (!l.title) e.push(`${at}.listings.${lang}.title: missing`);
if ([...(l.title ?? '')].length > 30) e.push(`${at}.listings.${lang}.title: over 30 characters (App Store limit)`);
if (!l.description) e.push(`${at}.listings.${lang}.description: missing`);
}
for (const o of p.overrides ?? []) {
if (!/^[A-Z]{2}$/.test(o.region)) e.push(`${at}.overrides: region "${o.region}" must be ISO alpha-2 (TR)`);
if (!/^[A-Z]{3}$/.test(o.currency)) e.push(`${at}.overrides: currency "${o.currency}" must be ISO 4217 (TRY)`);
if (!(o.price > 0)) e.push(`${at}.overrides: price must be positive`);
}
}
if (cfg.prices?.baseTerritory && !/^[A-Z]{3}$/.test(cfg.prices.baseTerritory)) e.push('prices.baseTerritory: App Store territory, alpha-3 (USA)');
if (cfg.dataSafety) {
for (const [t, u] of Object.entries(cfg.dataSafety.data ?? {})) {
if (!/^PSL_[A-Z_]+$/.test(t)) e.push(`dataSafety.data.${t}: use the Play type id (PSL_DEVICE_ID, ...)`);
if (!u.collect?.length) e.push(`dataSafety.data.${t}: at least one collection purpose`);
if (u.shared && !u.share?.length) e.push(`dataSafety.data.${t}: shared, so it needs sharing purposes`);
}
}
if (cfg.shots) {
const s = cfg.shots;
for (const k of ['copy', 'frames', 'out'] as const) if (!s[k]) e.push(`shots.${k}: missing`);
if (!s.scenes?.length) e.push('shots.scenes: at least one scene');
for (const sc of s.scenes ?? []) if (!sc.frames?.length) e.push(`shots.scenes[${sc.id}].frames: at least one frame`);
e.push(...validateCapture(s.capture));
const sceneIds = new Set((s.scenes ?? []).map(x => x.id));
for (const [k, v] of Object.entries(s.variants ?? {})) {
if (!/^[a-z0-9][a-z0-9-]*$/.test(k)) e.push(`shots.variants.${k}: lowercase letters, digits, "-" (it is a folder name)`);
if (cfg.languages?.some(l => l.id === k)) e.push(`shots.variants.${k}: same name as a language id`);
for (const id of v.scenes ?? []) if (!sceneIds.has(id)) e.push(`shots.variants.${k}.scenes: unknown scene "${id}"`);
for (const id of Object.keys(v.palettes ?? {})) if (!sceneIds.has(id)) e.push(`shots.variants.${k}.palettes: unknown scene "${id}"`);
}
if (s.video) {
const v = s.video;
if (v.seconds !== undefined && !(v.seconds >= 15 && v.seconds <= 30)) e.push('shots.video.seconds: 15-30 (App Store app preview length)');
for (const t of v.targets ?? []) if (!['iphone', 'ipad', 'youtube', 'youtube-landscape'].includes(t)) e.push(`shots.video.targets: unknown "${t}" (iphone, ipad, youtube, youtube-landscape)`);
if (v.fit && !['cover', 'contain'].includes(v.fit)) e.push('shots.video.fit: cover | contain');
for (const id of v.captionScenes ?? []) if (!sceneIds.has(id)) e.push(`shots.video.captionScenes: unknown scene "${id}"`);
if (v.record) e.push(...validateRecord(v.record, s.capture));
}
}
if (cfg.icons) {
if (!cfg.icons.composite) e.push('icons.composite: missing');
if (!cfg.icons.out) e.push('icons.out: missing');
if (cfg.icons.androidRes && !(cfg.icons.foreground && cfg.icons.background)) e.push('icons.androidRes needs icons.foreground + icons.background');
}
return e;
}
export interface Loaded { config: ShipConfig; root: string; path: string; resolve(p: string): string }
const NAMES = ['storebound.config.ts', 'storebound.config.js', 'storebound.config.json'];
/** Finds storebound.config.* from `start` upwards (or uses `explicit`), imports and validates it. */
export async function loadConfig(explicit?: string, start = process.cwd()): Promise<Loaded> {
let path = explicit ? resolve(explicit) : '';
if (!path) {
for (let d = resolve(start); ; d = dirname(d)) {
const hit = NAMES.map(n => join(d, n)).find(existsSync);
if (hit) { path = hit; break; }
if (dirname(d) === d) break;
}
}
if (!path || !existsSync(path)) throw new Error('no storebound.config.ts found (run `storebound init` or pass --config)');
const mod = await import(path);
const config = (mod.default ?? mod) as ShipConfig;
const errors = validateConfig(config);
if (errors.length) throw new Error(`${path}:\n ` + errors.join('\n '));
const root = dirname(path);
return { config, root, path, resolve: (p: string) => (isAbsolute(p) ? p : join(root, p)) };
}
/** Play language codes of a language entry. */
export const playCodes = (l: Language): string[] => (l.play === undefined ? [] : Array.isArray(l.play) ? l.play : [l.play]);