// 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; /** 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; } 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: ///.png */ frames: string; /** Output: ///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 ///... (`shots render --variant b`). */ variants?: Record; /** 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; } 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): ///.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; } 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; } export interface VideoConfig { /** Gameplay clips: //*.mp4|mov, or /*.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 //NN-.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; } 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; /** 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; 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_" (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-ads.txt is reachable and contains every line listed here. */ ads?: { appAdsTxt?: string[] }; /** Rendered store graphics dir (///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; 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(); 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_" (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(); 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 { 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]);