237 lines
17 KiB
TypeScript
237 lines
17 KiB
TypeScript
// Purchasing power parity price proposals: one price sheet for every product, store and region.
|
|
// storebound prices ppp [--base <USD>] [--source worldbank|bigmac|file] [--file <csv>] [--only ids] [--store apple|play]
|
|
// [--min-ratio 0.3] [--max-ratio 1] [--max-level 0.5] [--only-decreases | --no-only-decreases]
|
|
// [--include-high-income] [--out store/prices-ppp.csv] [--offline] [--dry] [--json]
|
|
// Defaults (STAR DASH, 2026-10-14: the old method cut Germany to EUR 3.59 for a USD 4.99 product): only lower prices,
|
|
// only in economies whose price level is at most 50 % of the US, World Bank high-income economies at par (the store's
|
|
// own US-equivalent price), mainland China at par on Apple and skipped on Play; --floor / --ceiling are the old names
|
|
// of --min-ratio / --max-ratio. A top-10 revenue market (from .storebound/reports/ when a sales report is there, else
|
|
// lib/ppp.ts TOP_MARKETS) that would drop more than 20 % is warned about.
|
|
// storebound prices ppp --update-bigmac [--dry] download The Economist Big Mac index to .storebound/ppp-bigmac.json
|
|
// It writes a CSV in the `prices import` format (nothing is sent to a store), prints the diff against the stores'
|
|
// current prices and the next step (`storebound prices import --csv <out> --dry`). --dry prints the CSV and the diff
|
|
// and writes nothing. --json prints { source, base, rows, skipped, diff, out, written } (with --dry: written false).
|
|
// Online (credentials set, no --offline): Apple prices snap to the product's real price points per territory
|
|
// (GET /v2/inAppPurchases/{id}/pricePoints?filter[territory]=...&include=territory, read-only) and the territory's
|
|
// currency comes from Apple; Play regions and currencies come from pricing:convertRegionPrices of the base (a
|
|
// read-only conversion). A product missing on a store falls back to offline snapping for that store. Math and
|
|
// snapping rules: lib/ppp.ts.
|
|
// Sources (checked October 2026):
|
|
// https://developer.apple.com/documentation/appstoreconnectapi/get-v2-inapppurchases-_id_-pricepoints
|
|
// https://developers.google.com/android-publisher/api-ref/rest/v3/monetization/convertRegionPrices
|
|
// https://data.worldbank.org/indicator/PA.NUS.PPP, https://data.worldbank.org/indicator/PA.NUS.FCRF
|
|
// https://github.com/TheEconomist/big-mac-data (output-data/big-mac-raw-index.csv)
|
|
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
import { dirname, join } from 'node:path';
|
|
import worldbank from './data/ppp-worldbank.json' with { type: 'json' };
|
|
import { ascClient, type Asc, type J } from './apple/asc';
|
|
import { sellsOn } from './lib/config';
|
|
import { credentialValue } from './lib/credentials';
|
|
import type { Ctx } from './lib/ctx';
|
|
import { need } from './lib/ctx';
|
|
import { done, log, printJson, step, warn } from './lib/log';
|
|
import { ALPHA3, toMoney } from './lib/money';
|
|
import {
|
|
bigMacDataset, datasetJson, datasetProblems, parseFactorCsv, planRows, PPP_DEFAULTS, type PppDataset, pppCsv, type PppOptions, type PppRow, type StoreRegion, TOP_DROP,
|
|
TOP_MARKETS, topMarketDrops, topMarketsFromReports,
|
|
} from './lib/ppp';
|
|
import { parsePlayCsv, parseTsv } from './lib/reports';
|
|
import { alpha2, diffPrices, diffTable, playPriceRows, type PriceRow } from './lib/prices';
|
|
import { playClient, type PlayClient } from './play/client';
|
|
import { appleCurrent, iapId, pages, playProduct } from './prices';
|
|
|
|
const TAG = 'ppp';
|
|
const BIGMAC_URL = 'https://raw.githubusercontent.com/TheEconomist/big-mac-data/master/output-data/big-mac-raw-index.csv';
|
|
export const bundled = worldbank as unknown as PppDataset;
|
|
|
|
/** Downloads the Big Mac index and writes <root>/.storebound/ppp-bigmac.json (also used by tools/update-ppp.ts). */
|
|
export async function updateBigMac(root: string, dry: boolean): Promise<void> {
|
|
const r = await fetch(BIGMAC_URL);
|
|
if (!r.ok) throw new Error(`${BIGMAC_URL} -> ${r.status}`);
|
|
const ds = bigMacDataset(await r.text(), new Date().toISOString().slice(0, 10));
|
|
const p = join(root, '.storebound', 'ppp-bigmac.json');
|
|
if (dry) { done(TAG, `dry run: would write ${Object.keys(ds.countries).length} countries (${ds.source}) to ${p}`); return; }
|
|
mkdirSync(dirname(p), { recursive: true });
|
|
writeFileSync(p, datasetJson(ds));
|
|
done(TAG, `${Object.keys(ds.countries).length} countries (${ds.source}) -> ${p}`);
|
|
}
|
|
|
|
export function loadDataset(source: string, root: string, file: string | undefined): PppDataset {
|
|
if (source === 'worldbank') return bundled;
|
|
if (source === 'bigmac') {
|
|
const p = join(root, '.storebound', 'ppp-bigmac.json');
|
|
if (!existsSync(p)) throw new Error(`no Big Mac data at ${p}: run storebound prices ppp --update-bigmac (downloads The Economist's data to your machine; it is not bundled)`);
|
|
const ds = JSON.parse(readFileSync(p, 'utf8')) as PppDataset;
|
|
const e = datasetProblems(ds);
|
|
if (e.length) throw new Error(`${p}: ${e.join('; ')} (run storebound prices ppp --update-bigmac again)`);
|
|
return ds;
|
|
}
|
|
if (source === 'file') {
|
|
if (!file) throw new Error('--source file needs --file <csv> (or prices.ppp.file in the config)');
|
|
if (!existsSync(file)) throw new Error(`no PPP factor CSV at ${file} (columns: region, factor, currency, fx)`);
|
|
return parseFactorCsv(readFileSync(file, 'utf8'), bundled, file);
|
|
}
|
|
throw new Error('--source worldbank | bigmac | file');
|
|
}
|
|
|
|
/**
|
|
* Apple's own conversion of the US price: the equalizations of the USA price point (tax included, today's rates),
|
|
* region (alpha-2) -> customer price. Empty when the call fails (then the offline par price is used).
|
|
*/
|
|
export async function appleEqualized(c: Asc, usaPointId: string): Promise<Map<string, number>> {
|
|
const out = new Map<string, number>();
|
|
try {
|
|
const r = await pages(c, `/v1/inAppPurchasePricePoints/${usaPointId}/equalizations?include=territory&limit=8000`);
|
|
for (const p of r.data) { const t: string | undefined = p.relationships?.territory?.data?.id; if (t) out.set(alpha2(t), Number(p.attributes?.customerPrice)); }
|
|
} catch (e) { warn(TAG, `Apple equalizations of the US price: ${(e as Error).message}; offline par prices for Apple`); }
|
|
return out;
|
|
}
|
|
|
|
/** Apple price points of one IAP in the given territories (alpha-3), batched: region (alpha-2) -> currency + points (+ ids of the USA points). */
|
|
export async function applePoints(c: Asc, id: string, territories: string[], usaIds?: Map<number, string>): Promise<Map<string, StoreRegion>> {
|
|
const out = new Map<string, StoreRegion>();
|
|
for (let i = 0; i < territories.length; i += 10) {
|
|
const batch = territories.slice(i, i + 10);
|
|
const r = await pages(c, `/v2/inAppPurchases/${id}/pricePoints?filter[territory]=${batch.join(',')}&include=territory&fields[territories]=currency&limit=8000`);
|
|
const curr = new Map(r.included.filter((x: J) => x.type === 'territories').map((x: J) => [x.id, x.attributes?.currency] as const));
|
|
for (const p of r.data) {
|
|
const t: string | undefined = p.relationships?.territory?.data?.id;
|
|
if (!t) continue;
|
|
const region = alpha2(t);
|
|
const e: StoreRegion = out.get(region) ?? { currency: curr.get(t) ?? '', points: [] };
|
|
e.points!.push(Number(p.attributes?.customerPrice));
|
|
if (t === 'USA' && usaIds && p.id) usaIds.set(Number(p.attributes?.customerPrice), p.id);
|
|
out.set(region, e);
|
|
}
|
|
}
|
|
return out;
|
|
}
|
|
|
|
type Converted = { convertedRegionPrices?: Record<string, { regionCode: string; price: { currencyCode: string; units?: string; nanos?: number } }> };
|
|
|
|
/** The options of a run: flags over prices.ppp in the config over PPP_DEFAULTS (--floor / --ceiling: old names). */
|
|
export function pppOptions(a: Ctx['args'], pc: NonNullable<NonNullable<Ctx['loaded']['config']['prices']>['ppp']>): PppOptions {
|
|
const o: PppOptions = {
|
|
minRatio: a.num('min-ratio', a.num('floor', pc.minRatio ?? pc.floor ?? PPP_DEFAULTS.minRatio)),
|
|
maxRatio: a.num('max-ratio', a.num('ceiling', pc.maxRatio ?? pc.ceiling ?? PPP_DEFAULTS.maxRatio)),
|
|
maxLevel: a.num('max-level', pc.maxLevel ?? PPP_DEFAULTS.maxLevel),
|
|
onlyDecreases: a.has('no-only-decreases') ? false : a.has('only-decreases') ? true : pc.onlyDecreases ?? PPP_DEFAULTS.onlyDecreases,
|
|
includeHighIncome: a.has('include-high-income') || (pc.includeHighIncome ?? PPP_DEFAULTS.includeHighIncome),
|
|
};
|
|
if (!(o.minRatio > 0) || !(o.maxRatio > 0) || o.minRatio > o.maxRatio) throw new Error('--min-ratio and --max-ratio (old names --floor / --ceiling): shares of the US-equivalent price, 0 < min <= max (e.g. 0.3 and 1)');
|
|
if (!(o.maxLevel > 0)) throw new Error('--max-level: the highest price level (share of the US) that gets a PPP price, e.g. 0.5');
|
|
return o;
|
|
}
|
|
|
|
/** Top revenue markets: from the sales reports in .storebound/reports/ when there are any, else the static list. */
|
|
export function topMarkets(root: string, ds: PppDataset): { markets: string[]; from: 'sales-reports' | 'static' } {
|
|
const dir = join(root, '.storebound', 'reports');
|
|
const reports: Record<string, string>[][] = [];
|
|
if (existsSync(dir)) for (const f of readdirSync(dir)) {
|
|
if (f.endsWith('.summary.csv') || !/\.(tsv|csv|txt)$/.test(f)) continue;
|
|
try { const t = readFileSync(join(dir, f), 'utf8'); reports.push(f.endsWith('.csv') ? parsePlayCsv(t) : parseTsv(t)); } catch { /* unreadable: skipped */ }
|
|
}
|
|
const m = topMarketsFromReports(reports, ds);
|
|
return m.length ? { markets: m, from: 'sales-reports' } : { markets: TOP_MARKETS, from: 'static' };
|
|
}
|
|
|
|
export async function run(ctx: Ctx): Promise<void> {
|
|
const { config, root, resolve } = ctx.loaded;
|
|
const a = ctx.args;
|
|
const pc = config.prices?.ppp ?? {};
|
|
const dry = a.has('dry');
|
|
if (a.has('update-bigmac')) return updateBigMac(root, dry);
|
|
|
|
const store = a.get('store');
|
|
if (store && store !== 'apple' && store !== 'play') throw new Error('--store apple | play');
|
|
const source = a.get('source') ?? pc.source ?? 'worldbank';
|
|
const fileArg = a.get('file') ?? pc.file;
|
|
const ds = loadDataset(source, root, fileArg ? resolve(fileArg) : undefined);
|
|
const options = pppOptions(a, pc);
|
|
const { minRatio: floor, maxRatio: ceiling } = options;
|
|
const baseArg = a.get('base') !== undefined ? a.num('base', 0) : undefined;
|
|
if (baseArg !== undefined && !(baseArg > 0)) throw new Error('--base: a USD price, e.g. 4.99');
|
|
const only = a.list('only');
|
|
const products = need(config.products, 'products').filter(p => !only.length || only.includes(p.id));
|
|
if (!products.length) throw new Error(only.length ? `--only ${only.join(',')}: no such product in products[]` : 'products[] is empty');
|
|
const out = resolve(a.get('out') ?? pc.out ?? 'store/prices-ppp.csv');
|
|
const offline = a.has('offline');
|
|
const stores = (['apple', 'play'] as const).filter(s => (!store || store === s) && !!config[s]);
|
|
if (!stores.length) throw new Error('no store configured for this run (apple / play in storebound.config.ts)');
|
|
|
|
const online = {
|
|
apple: !offline && stores.includes('apple') && !!credentialValue(root, 'ASC_KEY_ID') && !!credentialValue(root, 'ASC_ISSUER_ID'),
|
|
play: !offline && stores.includes('play') && !!credentialValue(root, 'PLAY_SERVICE_ACCOUNT'),
|
|
};
|
|
for (const s of stores) if (!offline && !online[s]) warn(TAG, `${s}: no credentials, offline snapping (storebound doctor shows what is missing)`);
|
|
const c = online.apple ? await ascClient(root, config.apple!.bundleId, config.apple?.appId) : null;
|
|
const appId = c ? await c.app() : '';
|
|
const play: PlayClient | null = online.play ? await playClient(root, config.play!.packageName) : null;
|
|
log(TAG, `${ds.name}: ${ds.source}; retrieved ${ds.retrieved || '-'}; ${stores.map(s => `${s} ${online[s] ? 'online' : 'offline'}`).join(', ')}`);
|
|
log(TAG, `rules: ${options.onlyDecreases ? 'only lower prices' : 'lower and raise'}; PPP prices only where the price level is <= ${options.maxLevel} of the US; share of the US-equivalent price ${floor}..${ceiling}; ${options.includeHighIncome ? 'high-income economies included' : 'high-income economies at par'}; CN at par on Apple, not on Play`);
|
|
|
|
const rows: PppRow[] = [];
|
|
const kept: PppRow[] = [];
|
|
const current: PriceRow[] = [];
|
|
const skipped: { product: string; store: string; region: string; why: string }[] = [];
|
|
const offlineApple = new Set<string>();
|
|
const converted = new Map<number, Converted>();
|
|
const base: Record<string, number> = {};
|
|
for (const [i, p] of products.entries()) {
|
|
const usd = baseArg ?? p.usd;
|
|
base[p.id] = usd;
|
|
log(TAG, `${step(i + 1, products.length, p.id)}: base ${usd} USD`);
|
|
for (const s of stores) {
|
|
if (!sellsOn(config, p, s)) continue;
|
|
let regions: Map<string, StoreRegion> | undefined;
|
|
if (s === 'apple' && c) {
|
|
const id = await iapId(c, appId, p.id);
|
|
if (!id) warn(TAG, `${p.id}: not on App Store Connect (storebound apple iap creates it); offline snapping for Apple`);
|
|
else {
|
|
current.push(...(await appleCurrent(c, id, p.id, true)).rows);
|
|
const want = Object.keys(ALPHA3).filter(r => r === 'US' || ds.countries[r]).map(r => ALPHA3[r]!);
|
|
const usaIds = new Map<number, string>();
|
|
regions = await applePoints(c, id, want, usaIds);
|
|
const usaId = [...usaIds.entries()].find(([price]) => Math.round(price * 100) === Math.round(usd * 100))?.[1];
|
|
if (usaId) for (const [region, par] of await appleEqualized(c, usaId)) { const r = regions.get(region); if (r) r.par = par; }
|
|
else warn(TAG, `${p.id}: USD ${usd} is not an App Store price point; offline par prices for Apple`);
|
|
}
|
|
}
|
|
if (s === 'play' && play) {
|
|
const pp = await playProduct(play, p.id);
|
|
if (!pp) warn(TAG, `${p.id}: not on Google Play (storebound play products creates it); proposal against no current prices`);
|
|
else current.push(...playPriceRows(pp));
|
|
if (!converted.has(usd)) converted.set(usd, await play.call<Converted>('POST', `${play.API}/pricing:convertRegionPrices`, { price: toMoney('USD', usd) }));
|
|
// convertRegionPrices: the US price in every region, tax included, at today's rates: Play's par price
|
|
regions = new Map(Object.values(converted.get(usd)!.convertedRegionPrices ?? {}).map(r => [r.regionCode, { currency: r.price.currencyCode, par: Number(r.price.units ?? 0) + (r.price.nanos ?? 0) / 1e9 }] as const));
|
|
}
|
|
if (s === 'apple' && !regions) offlineApple.add(p.id);
|
|
const cur = new Map(current.filter(r => r.product === p.id && r.store === s && r.kind !== 'auto').map(r => [r.region, { currency: r.currency, price: r.price }] as const));
|
|
for (const r of current) if (r.product === p.id && r.store === s && r.kind === 'auto' && !cur.has(r.region)) cur.set(r.region, { currency: r.currency, price: r.price });
|
|
const plan = planRows({ product: p.id, base: usd, store: s, dataset: ds, options, regions, current: cur });
|
|
rows.push(...plan.rows);
|
|
kept.push(...plan.kept);
|
|
skipped.push(...plan.skipped.map(k => ({ product: p.id, store: s, ...k })));
|
|
}
|
|
}
|
|
|
|
const csv = pppCsv(rows);
|
|
const diff = diffPrices(current, rows.map(({ product, store, region, territory, currency, price }) => ({ product, store, region, territory, currency, price })));
|
|
const sourceInfo = { name: ds.name, year: ds.year ?? null, retrieved: ds.retrieved, url: ds.url, license: ds.license };
|
|
if (!dry) { mkdirSync(dirname(out), { recursive: true }); writeFileSync(out, csv); }
|
|
const top = topMarkets(root, ds);
|
|
const drops = topMarketDrops(rows, top.markets);
|
|
for (const d of drops) warn(TAG, `top market ${d.region} (${top.from === 'sales-reports' ? 'from your sales reports' : 'static top-10 list'}): ${d.product} ${d.store} ${d.currency} ${d.from} -> ${d.to} (-${Math.round(d.drop * 100)} %, more than ${TOP_DROP * 100} %); keep it out of the sheet unless you mean it`);
|
|
if (a.has('json')) {
|
|
printJson({ source: sourceInfo, base, floor, ceiling, options, online, rows: rows.map(({ territory: _t, ...r }) => r), kept: kept.map(({ territory: _t, ...r }) => r), skipped, diff, topMarkets: { ...top, drops }, out, written: !dry });
|
|
return;
|
|
}
|
|
if (dry) console.log(csv);
|
|
console.log(diffTable(diff));
|
|
const cut = rows.filter(r => r.share < 1).length, par = kept.length;
|
|
log(TAG, `${rows.length} rows (${cut} below the US-equivalent price; ${par} region(s) keep the store's own price: high-income, price level above ${options.maxLevel}, CN, or only-decreases), ${skipped.length} region(s) without a proposal${skipped.length ? ` (${[...new Set(skipped.map(k => k.region))].slice(0, 12).join(', ')}${skipped.length > 12 ? ', ...' : ''})` : ''}`);
|
|
if (offlineApple.size) warn(TAG, `Apple values for ${[...offlineApple].join(', ')} are offline proposals: each must still match an App Store price point (prices import checks it and lists the neighbours)`);
|
|
log(TAG, `source: ${ds.attribution ?? ds.source} (${ds.license})`);
|
|
log(TAG, 'a proposal: review the sheet (remove rows you do not want, round to your own price ladder); nothing was sent to a store');
|
|
done(TAG, dry ? `dry run: would write ${rows.length} rows to ${out}` : `${rows.length} rows -> ${out}; next: storebound prices import --csv ${a.get('out') ?? pc.out ?? 'store/prices-ppp.csv'} --dry`);
|
|
}
|