vydanne 0.2.0

package/src/commands/fill.mjs

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import path from "node:path";
+import { green, yellow, red } from "../util.mjs";
+import { VALID } from "../locales.mjs";
+import { uploadAsset } from "../upload.mjs";
+
+// Version-localization fields (attr -> metadata filename) and AppInfo fields (name/subtitle, shared).
+const VERSION_TXT = { description: "description", keywords: "keywords", promotionalText: "promotional_text", whatsNew: "release_notes", marketingUrl: "marketing_url", supportUrl: "support_url" };
+const INFO_TXT = { name: "name", subtitle: "subtitle" };
+const IOS_DEVICE = { iphone69: "APP_IPHONE_67", iphone65: "APP_IPHONE_65", ipad13: "APP_IPAD_PRO_3GEN_129", watch: "APP_WATCH_ULTRA" };
+const MAC_DEVICE = { macos: "APP_DESKTOP" };
+
+// Push metadata (native PATCH — works at any editable state, incl. READY_FOR_REVIEW, unlike deliver) +
+// screenshots (native chunked upload; skips sets that already have shots so it never duplicates).
+// iOS and macOS are separate platforms. Toggles: VYDANNE_SKIP_METADATA / VYDANNE_SKIP_SCREENSHOTS.
+export async function run(config, client) {
+  await client.findApp(config.bundleId);
+  const skipMeta = process.env.VYDANNE_SKIP_METADATA === "1";
+  const skipShots = process.env.VYDANNE_SKIP_SCREENSHOTS === "1";
+  const info = await client.appInfo();
+  const infoLocs = info ? (await client.get(`/v1/appInfos/${info.id}/appInfoLocalizations?limit=200`)).json.data || [] : [];
+
+  for (const platform of config.platforms) {
+    const v = await client.editVersion(platform);
+    if (!v) { console.error(red(`fill ${platform}: no editable version`)); continue; }
+    console.log(green(`fill ${platform} (metadata=${!skipMeta} screenshots=${!skipShots})...`));
+    const verLocs = await client.versionLocalizations(v.id);
+
+    if (!skipMeta) {
+      const dirs = fs.readdirSync(config.metadataDir, { withFileTypes: true }).filter((d) => d.isDirectory() && VALID.has(d.name)).map((d) => d.name);
+      for (const code of dirs) {
+        const folder = path.join(config.metadataDir, code);
+        const read = (f) => { const p = path.join(folder, `${f}.txt`); return fs.existsSync(p) ? fs.readFileSync(p, "utf8").replace(/\n+$/, "") : null; };
+        // version localization (description/keywords/promo/whatsNew/urls)
+        let vl = verLocs.find((l) => l.attributes.locale === code);
+        if (!vl) { const c = await client.post(`/v1/appStoreVersionLocalizations`, { data: { type: "appStoreVersionLocalizations", attributes: { locale: code }, relationships: { appStoreVersion: { data: { type: "appStoreVersions", id: v.id } } } } }); vl = c.json.data; verLocs.push(vl); }
+        const vattrs = {};
+        for (const [k, f] of Object.entries(VERSION_TXT)) { const t = read(f); if (t != null) vattrs[k] = t; }
+        if (Object.keys(vattrs).length) await client.patch(`/v1/appStoreVersionLocalizations/${vl.id}`, { data: { type: "appStoreVersionLocalizations", id: vl.id, attributes: vattrs } });
+        // app-info localization (name/subtitle — shared across platforms). Apple REQUIRES `name` when
+        // CREATING a localization (409 ATTRIBUTE.REQUIRED otherwise), so build the attrs first and send
+        // them in the POST; only PATCH when the localization already exists.
+        if (info) {
+          const iattrs = {};
+          for (const [k, f] of Object.entries(INFO_TXT)) { const t = read(f); if (t != null) iattrs[k] = t; }
+          let il = infoLocs.find((l) => l.attributes.locale === code);
+          if (!il) {
+            const c = await client.post(`/v1/appInfoLocalizations`, { data: { type: "appInfoLocalizations", attributes: { locale: code, ...iattrs }, relationships: { appInfo: { data: { type: "appInfos", id: info.id } } } } });
+            il = c.json.data;
+            if (il) infoLocs.push(il);
+            else console.error(`  appInfo ${code}: create failed — ${JSON.stringify(c.json?.errors?.[0]?.detail || c.json)}`);
+          } else if (Object.keys(iattrs).length) {
+            await client.patch(`/v1/appInfoLocalizations/${il.id}`, { data: { type: "appInfoLocalizations", id: il.id, attributes: iattrs } });
+          }
+        }
+      }
+      console.log(green(`  metadata: ${dirs.length} locales`));
+    }
+
+    if (!skipShots) await uploadScreenshots(config, client, platform, verLocs);
+  }
+  return true;
+}
+
+async function uploadScreenshots(config, client, platform, verLocs) {
+  const base = platform === "MAC_OS" ? "fastlane/screenshots-macos" : "fastlane/screenshots";
+  const DEV = platform === "MAC_OS" ? MAC_DEVICE : IOS_DEVICE;
+  if (!fs.existsSync(base)) return;
+  for (const code of fs.readdirSync(base).filter((d) => VALID.has(d))) {
+    const loc = verLocs.find((l) => l.attributes.locale === code);
+    if (!loc) continue;
+    const files = fs.readdirSync(path.join(base, code)).filter((f) => f.endsWith(".png")).sort();
+    const byDev = {};
+    for (const f of files) { const dt = DEV[f.split("_")[0]]; if (dt) (byDev[dt] ||= []).push(f); }
+    const { json: sets } = await client.get(`/v1/appStoreVersionLocalizations/${loc.id}/appScreenshotSets?include=appScreenshots&limit=50`);
+    for (const [dt, list] of Object.entries(byDev)) {
+      let set = (sets.data || []).find((s) => s.attributes.screenshotDisplayType === dt);
+      if (set && (set.relationships?.appScreenshots?.data || []).length) continue; // never duplicate
+      if (!set) { const c = await client.post(`/v1/appScreenshotSets`, { data: { type: "appScreenshotSets", attributes: { screenshotDisplayType: dt }, relationships: { appStoreVersionLocalization: { data: { type: "appStoreVersionLocalizations", id: loc.id } } } } }); set = c.json.data; }
+      for (const f of list) await uploadAsset(client, { type: "appScreenshots", setType: "appScreenshotSet", setId: set.id, filePath: path.join(base, code, f) });
+      console.log(green(`    ${code}/${dt}: ${list.length} screenshots`));
+    }
+  }
+}

package/src/commands/iap.mjs

@@ -0,0 +1,31 @@
+import sharp from "sharp";
+import { green, yellow, red } from "../util.mjs";
+
+// Validate IAP fields (Display Name <=30, Description <=45) + remind of the two image slots. Optional:
+// VYDANNE_FLATTEN=<png> flattens a screenshot to RGB (sim captures are RGBA → ASC rejects them).
+export async function run(config) {
+  if (process.env.VYDANNE_FLATTEN) return flatten(process.env.VYDANNE_FLATTEN);
+  const iaps = config.iaps || [];
+  if (!iaps.length) { console.log(yellow("no iaps in config")); return true; }
+  let ok = true;
+  for (const i of iaps) {
+    const dn = (i.displayName || "").length, de = (i.description || "").length;
+    const bad = [];
+    if (dn > 30) bad.push(`display_name ${dn}>30`);
+    if (de > 45) bad.push(`description ${de}>45`);
+    if (bad.length) ok = false;
+    console.log(`IAP ${i.productId} (${i.type}) ${i.price}`);
+    console.log(`  Display Name (<=30): ${dn}  ${bad.length ? red(bad.join(", ")) : green("ok")}`);
+    console.log(`  Description  (<=45): ${de}`);
+    console.log(`  Review note: ${(i.reviewNote || "").slice(0, 120)}`);
+  }
+  console.log(yellow("Two image slots: Review Screenshot (tall, required, RGB) + Promotional Image (1024x1024, optional — from zdymak)."));
+  return ok;
+}
+
+async function flatten(input) {
+  const out = input.replace(/(\.\w+)?$/, "-iap.png");
+  await sharp(input).flatten({ background: "#ffffff" }).removeAlpha().png().toFile(out);
+  console.log(green(`flattened -> ${out} (RGB, no alpha)`));
+  return true;
+}

package/src/commands/inspect.mjs

@@ -0,0 +1,20 @@
+// Read-only snapshot of what's in App Store Connect now, per platform.
+export async function run(config, client) {
+  await client.findApp(config.bundleId);
+  console.log(`APP ${client.app.attributes.name} (${config.bundleId})  id=${client.appId}  primary=${client.app.attributes.primaryLocale}`);
+  for (const platform of config.platforms) {
+    const v = await client.editVersion(platform);
+    if (!v) { console.log(`  ${platform}: no editable version`); continue; }
+    const locs = await client.versionLocalizations(v.id);
+    console.log(`  ${platform}: v${v.attributes.versionString}  ${v.attributes.appStoreState}  localizations=${locs.length}`);
+    const primary = locs.find((l) => l.attributes.locale === config.primaryLocale) || locs[0];
+    if (!primary) continue;
+    const ss = await client.get(`/v1/appStoreVersionLocalizations/${primary.id}/appScreenshotSets?include=appScreenshots&limit=50`);
+    const sets = (ss.json.data || []).map((s) => `${s.attributes.screenshotDisplayType.replace("APP_", "")}=${(s.relationships?.appScreenshots?.data || []).length}`);
+    if (sets.length) console.log(`     screenshots (${primary.attributes.locale}): ${sets.join("  ")}`);
+    const pp = await client.get(`/v1/appStoreVersionLocalizations/${primary.id}/appPreviewSets?include=appPreviews&limit=50`);
+    const psets = (pp.json.data || []).map((s) => `${s.attributes.previewType}=${(s.relationships?.appPreviews?.data || []).length}`).filter((x) => !x.endsWith("=0"));
+    if (psets.length) console.log(`     previews (${primary.attributes.locale}): ${psets.join("  ")}`);
+  }
+  return true;
+}

package/src/commands/preflight.mjs

@@ -0,0 +1,42 @@
+import { green, red, yellow, LIMITS, VERSION_FIELDS } from "../util.mjs";
+
+// Verify a listing is submission-complete the CORRECT way — each localization read by id (not the sparse
+// list), char limits, primary-locale coverage, per-platform — and warn on the gotchas before ASC does.
+export async function run(config, client) {
+  await client.findApp(config.bundleId);
+  const problems = [], notes = [];
+  const res = config.resolvedLocales;
+  if (res.unsupported.length) notes.push(`UI locales with no App Store listing (fall back to ${config.primaryLocale}): ${res.unsupported.join(", ")}`);
+
+  for (const platform of config.platforms) {
+    const v = await client.editVersion(platform);
+    if (!v) { problems.push(`${platform}: no editable version`); continue; }
+    console.log(`  ${platform}: version ${v.attributes.versionString} (${v.attributes.appStoreState})`);
+    const locs = await client.versionLocalizations(v.id);
+    const ascLocales = [...new Set([config.primaryLocale, ...Object.values(res.supported)])];
+
+    for (const code of ascLocales) {
+      const loc = locs.find((l) => l.attributes.locale === code);
+      if (!loc) { if (code === config.primaryLocale) problems.push(`${platform}/${code}: localization missing`); continue; }
+      const a = await client.localization(loc.id);
+      for (const [f, key] of Object.entries(VERSION_FIELDS)) {
+        const val = (a[key] || "").toString();
+        if (!val) (code === config.primaryLocale ? problems : notes).push(`${platform}/${code}: ${f} EMPTY`);
+        else if (LIMITS[f] && val.length > LIMITS[f]) problems.push(`${platform}/${code}: ${f} ${val.length}>${LIMITS[f]}`);
+      }
+    }
+
+    const primary = locs.find((l) => l.attributes.locale === config.primaryLocale);
+    if (primary) {
+      const { json } = await client.get(`/v1/appStoreVersionLocalizations/${primary.id}/appScreenshotSets?include=appScreenshots&limit=50`);
+      const count = (json.data || []).reduce((n, s) => n + (s.relationships?.appScreenshots?.data || []).length, 0);
+      if (!count) problems.push(`${platform}/${config.primaryLocale}: no screenshots`);
+    }
+  }
+
+  console.log();
+  if (!problems.length) console.log(green("preflight: no blockers"));
+  else { console.log(red(`preflight: ${problems.length} blocker(s)`)); problems.forEach((p) => console.log(`  ${red("x")} ${p}`)); }
+  notes.forEach((n) => console.log(`  ${yellow("!")} ${n}`));
+  return problems.length === 0;
+}

package/src/commands/previews.mjs

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+import { green, yellow, red } from "../util.mjs";
+import { uploadAsset, setPreviewPoster } from "../upload.mjs";
+
+// Upload App Preview videos natively (reserve → chunked PUT → commit → poll processing → poster frame).
+// config.previews: [{ platform, type, file, poster, locales }]. Skips locales that already have a preview.
+export async function run(config, client) {
+  await client.findApp(config.bundleId);
+  const specs = config.previews || defaultSpecs(config);
+  for (const s of specs) {
+    const v = await client.editVersion(s.platform);
+    if (!v) { console.error(red(`  ${s.platform}: no version`)); continue; }
+    const locs = await client.versionLocalizations(v.id);
+    for (const code of s.locales || [config.primaryLocale]) {
+      const loc = locs.find((l) => l.attributes.locale === code);
+      if (!loc) continue;
+      try {
+        const { json: sets } = await client.get(`/v1/appStoreVersionLocalizations/${loc.id}/appPreviewSets?include=appPreviews&limit=50`);
+        let set = (sets.data || []).find((x) => x.attributes.previewType === s.type);
+        const existing = set?.relationships?.appPreviews?.data || [];
+        if (existing.length && process.env.VYDANNE_REPLACE !== "1") {
+          console.log(yellow(`  ${s.platform}/${code}/${s.type}: already has a preview, skipping (set VYDANNE_REPLACE=1 to replace it)`)); continue;
+        }
+        for (const p of existing) { // VYDANNE_REPLACE: drop the old preview so the new upload takes its place
+          await client.del(`/v1/appPreviews/${p.id}`);
+          console.log(yellow(`  ${s.platform}/${code}/${s.type}: removed old preview ${p.id}`));
+        }
+        if (!set) {
+          const c = await client.post(`/v1/appPreviewSets`, { data: { type: "appPreviewSets", attributes: { previewType: s.type }, relationships: { appStoreVersionLocalization: { data: { type: "appStoreVersionLocalizations", id: loc.id } } } } });
+          set = c.json.data;
+        }
+        const file = path.resolve(s.file);
+        console.log(`  ${s.platform}/${code}/${s.type}: uploading ${path.basename(file)}...`);
+        const id = await uploadAsset(client, { type: "appPreviews", setType: "appPreviewSet", setId: set.id, filePath: file });
+        await setPreviewPoster(client, id, s.poster);
+        console.log(green(`    done ${s.platform}/${code}/${s.type}`));
+      } catch (e) {
+        console.error(red(`    error ${s.platform}/${code}/${s.type}: ${e.message}`));
+      }
+    }
+  }
+  return true;
+}
+
+function defaultSpecs(config) {
+  return [
+    { platform: "IOS", type: "IPHONE_67", file: "marketing/out/appstore-preview.mp4", poster: "00:00:05:00", locales: [config.primaryLocale, "en-US"] },
+    { platform: "MAC_OS", type: "DESKTOP", file: "marketing/out/mac-appstore-preview-mac.mp4", poster: "00:00:03:00", locales: [config.primaryLocale, "en-US"] },
+  ].filter((s) => config.platforms.includes(s.platform) && fs.existsSync(path.resolve(s.file)));
+}

package/src/commands/privacy.mjs

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+import { green, yellow } from "../util.mjs";
+
+// App Privacy is on Apple's iris host, which 401s the JWT — it CANNOT be set with the ASC API key. Write
+// the honest record + print the exact ASC-UI answers (a passkey login works there).
+const GROUP = { CRASH_DATA: "Diagnostics", PERFORMANCE_DATA: "Diagnostics", OTHER_DIAGNOSTIC_DATA: "Diagnostics" };
+
+export async function run(config) {
+  const collected = config.privacy?.collected || ["CRASH_DATA", "PERFORMANCE_DATA"];
+  const tracking = !!config.privacy?.tracking;
+  const record = collected.map((cat) => ({
+    category: cat, purposes: ["APP_FUNCTIONALITY"],
+    data_protections: [tracking ? "DATA_LINKED_TO_YOU" : "DATA_NOT_LINKED_TO_YOU", tracking ? "DATA_USED_TO_TRACK_YOU" : null].filter(Boolean),
+  }));
+  const out = path.join(path.dirname(config.metadataDir), "app_privacy_details.json");
+  fs.writeFileSync(out, JSON.stringify(record, null, 2));
+  console.log(green(`wrote ${out} (declaration record)`));
+  console.log();
+  console.log(yellow("App Privacy is UI-only (passkey) — the API key 401s on Apple's iris host. Enter:"));
+  if (collected.length) console.log("  Do you or your partners collect data? -> Yes");
+  for (const c of collected) {
+    const name = c.split("_").map((w) => w[0] + w.slice(1).toLowerCase()).join(" ");
+    console.log(`  ${GROUP[c] || "?"} -> ${name}: App Functionality · ${tracking ? "Linked" : "Not Linked"} · ${tracking ? "Tracking" : "No Tracking"}`);
+  }
+  console.log("  Everything else -> Not Collected.");
+  console.log(yellow("  'accesses' is not 'collects' — E2EE content you can't read is not collected."));
+  return true;
+}

package/src/commands/reviewContact.mjs

@@ -0,0 +1,27 @@
+import fs from "node:fs";
+import path from "node:path";
+import { green, red } from "../util.mjs";
+
+// App Review contact from the GITIGNORED metadata/review_information/*.txt. PATCH (or POST) the review
+// detail directly — deliver can't do this cleanly pre-first-submission.
+export async function run(config, client) {
+  const dir = path.join(config.metadataDir, "review_information");
+  const read = (n) => { const p = path.join(dir, `${n}.txt`); return fs.existsSync(p) ? fs.readFileSync(p, "utf8").trim() : ""; };
+  const attributes = {
+    contactFirstName: read("first_name"), contactLastName: read("last_name"),
+    contactPhone: read("phone_number"), contactEmail: read("email_address"),
+    demoAccountRequired: false, notes: read("notes"),
+  };
+  if (!attributes.contactEmail) { console.error(red(`review-contact: ${dir}/*.txt missing`)); return false; }
+  await client.findApp(config.bundleId);
+  const v = await client.editVersion(config.platforms[0]);
+  if (!v) { console.error(red("review-contact: no editable version")); return false; }
+  const { json } = await client.get(`/v1/appStoreVersions/${v.id}/appStoreReviewDetail`);
+  const existing = json.data;
+  const r = existing?.id
+    ? await client.patch(`/v1/appStoreReviewDetails/${existing.id}`, { data: { type: "appStoreReviewDetails", id: existing.id, attributes } })
+    : await client.post(`/v1/appStoreReviewDetails`, { data: { type: "appStoreReviewDetails", attributes, relationships: { appStoreVersion: { data: { type: "appStoreVersions", id: v.id } } } } });
+  if (r.status >= 300) { console.error(red(`review-contact: ${r.status}: ${JSON.stringify(r.json).slice(0, 200)}`)); return false; }
+  console.log(green(`review contact set -> ${attributes.contactFirstName} ${attributes.contactLastName} · ${attributes.contactPhone}`));
+  return true;
+}

package/src/config.mjs

@@ -0,0 +1,48 @@
+import path from "node:path";
+import fs from "node:fs";
+import { pathToFileURL } from "node:url";
+import { resolveLocales } from "./locales.mjs";
+
+// The public config surface — the drift guards assert each key is documented (README/SKILL) and typed
+// (types/index.d.ts). Add a config knob → document + type it, or the guards fail before publish.
+export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "metadataDir", "rating", "privacy", "iaps", "previews", "export", "google"];
+
+// One `vydanne.config.mjs` per app (ESM, like zdymak.config.mjs) — nothing hard-coded. Secrets stay out:
+// ASC key via ~/.appstoreconnect + ASC_KEY_ID/ASC_ISSUER_ID env; review-contact PII in gitignored files.
+export async function loadConfig(p) {
+  const file = path.resolve(p || process.env.VYDANNE_CONFIG || "vydanne.config.mjs");
+  if (!fs.existsSync(file)) throw new Error(`vydanne: config not found at ${file}`);
+  const mod = await import(pathToFileURL(file).href);
+  const raw = mod.default || mod;
+  const need = (k) => {
+    if (raw[k] == null) throw new Error(`vydanne: config missing '${k}'`);
+    return raw[k];
+  };
+  const c = {
+    raw,
+    bundleId: need("bundleId"),
+    primaryLocale: need("primaryLocale"),
+    keyId: process.env.ASC_KEY_ID || raw.asc?.keyId,
+    issuerId: process.env.ASC_ISSUER_ID || raw.asc?.issuerId,
+    uiLocales: raw.uiLocales || [],
+    platforms: raw.platforms || ["IOS"],
+    rating: raw.rating || "4+",
+    privacy: raw.privacy || { collected: ["CRASH_DATA", "PERFORMANCE_DATA"], tracking: false },
+    iaps: raw.iaps || [],
+    metadataDir: raw.metadataDir || "fastlane/metadata",
+    previews: raw.previews || null,
+    export: raw.export || { encryption: "standard" },
+    // Google Play. serviceAccountKey resolves from PLAY_JSON_KEY_FILE env first (keep the secret path out
+    // of the committed config). metadataDir follows fastlane supply's convention (fastlane/metadata/android).
+    google: raw.google
+      ? {
+          packageName: raw.google.packageName || raw.bundleId,
+          serviceAccountKey: process.env.PLAY_JSON_KEY_FILE || raw.google.serviceAccountKey,
+          metadataDir: raw.google.metadataDir || "fastlane/metadata/android",
+          defaultLocale: raw.google.defaultLocale || raw.primaryLocale,
+        }
+      : null,
+  };
+  c.resolvedLocales = resolveLocales(c.uiLocales);
+  return c;
+}

package/src/index.mjs

@@ -0,0 +1,6 @@
+// Programmatic entry (the CLI is bin/vydanne.mjs). `import { Client, loadConfig } from "vydanne"`.
+export { Client } from "./client.mjs";
+export { loadConfig, CONFIG_KEYS } from "./config.mjs";
+export { COMMANDS, COMMAND_NAMES } from "./registry.mjs";
+export { resolveLocales, toAsc, VALID } from "./locales.mjs";
+export { makeToken } from "./jwt.mjs";

package/src/jwt.mjs

@@ -0,0 +1,17 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// App Store Connect JWT (ES256). Node's built-in crypto signs it — `dsaEncoding: "ieee-p1363"` returns the
+// raw r||s signature JWT/JOSE needs (the default DER encoding would be rejected). No fastlane/spaceship.
+export function makeToken({ keyId, issuerId, keyPath }) {
+  keyPath ||= path.join(os.homedir(), ".appstoreconnect", "private_keys", `AuthKey_${keyId}.p8`);
+  if (!fs.existsSync(keyPath)) throw new Error(`vydanne: ASC key not found at ${keyPath}`);
+  const p8 = fs.readFileSync(keyPath, "utf8");
+  const b64u = (o) => Buffer.from(typeof o === "string" ? o : JSON.stringify(o)).toString("base64url");
+  const now = Math.floor(Date.now() / 1000);
+  const input = `${b64u({ alg: "ES256", kid: keyId, typ: "JWT" })}.${b64u({ iss: issuerId, iat: now, exp: now + 1200, aud: "appstoreconnect-v1" })}`;
+  const sig = crypto.sign("sha256", Buffer.from(input), { key: p8, dsaEncoding: "ieee-p1363" });
+  return `${input}.${sig.toString("base64url")}`;
+}

package/src/locales.mjs

@@ -0,0 +1,26 @@
+// App Store locale handling — the #1 gotcha: deliver/ASC folder codes must match Apple's exact list, and a
+// short UI code (`de`, `ar`) that isn't valid aborts a whole upload. A code with no App Store language
+// (e.g. Belarusian `be`) must fall back to the primary listing.
+export const VALID = new Set([
+  "ar-SA", "bn-BD", "ca", "cs", "da", "de-DE", "el", "en-AU", "en-CA", "en-GB", "en-US", "es-ES", "es-MX",
+  "fi", "fr-CA", "fr-FR", "gu-IN", "he", "hi", "hr", "hu", "id", "it", "ja", "kn-IN", "ko", "ml-IN", "mr-IN",
+  "ms", "nl-NL", "no", "or-IN", "pa-IN", "pl", "pt-BR", "pt-PT", "ro", "ru", "sk", "sl-SI", "sv", "ta-IN",
+  "te-IN", "th", "tr", "uk", "ur-PK", "vi", "zh-Hans", "zh-Hant",
+]);
+
+export const UI_TO_ASC = {
+  ar: "ar-SA", bn: "bn-BD", de: "de-DE", es: "es-ES", fr: "fr-FR", nl: "nl-NL",
+  pt: "pt-BR", ur: "ur-PK", zh: "zh-Hans", en: "en-US",
+};
+
+export const toAsc = (code) => (VALID.has(code) ? code : UI_TO_ASC[code] || null);
+
+export function resolveLocales(uiCodes = []) {
+  const supported = {};
+  const unsupported = [];
+  for (const c of uiCodes) {
+    const asc = toAsc(c);
+    asc ? (supported[c] = asc) : unsupported.push(c);
+  }
+  return { supported, unsupported };
+}

package/src/play/auth.mjs

@@ -0,0 +1,29 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+const SCOPE = "https://www.googleapis.com/auth/androidpublisher";
+
+// Google Play uses OAuth2 two-legged (service account): sign an RS256 JWT with the SA private key, exchange
+// it at the token endpoint for a ~1h access token. Native crypto — no googleapis lib. (Apple is per-request
+// ES256; Google is a token exchange — the one real auth difference between the two stores.)
+export async function getAccessToken(keyPath) {
+  if (!fs.existsSync(keyPath)) throw new Error(`vydanne: Play service-account key not found at ${keyPath}`);
+  const sa = JSON.parse(fs.readFileSync(keyPath, "utf8"));
+  if (sa.type !== "service_account") {
+    throw new Error(`vydanne: ${keyPath} is not a service-account key (type=${sa.type || "?"}). ` +
+      "You need a Google Cloud service account with the Android Publisher role — NOT an OAuth client_secret.");
+  }
+  const b64u = (o) => Buffer.from(typeof o === "string" ? o : JSON.stringify(o)).toString("base64url");
+  const now = Math.floor(Date.now() / 1000);
+  const claim = { iss: sa.client_email, scope: SCOPE, aud: sa.token_uri, iat: now, exp: now + 3600 };
+  const input = `${b64u({ alg: "RS256", typ: "JWT" })}.${b64u(claim)}`;
+  const sig = crypto.sign("RSA-SHA256", Buffer.from(input), sa.private_key).toString("base64url");
+  const res = await fetch(sa.token_uri, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: `${input}.${sig}` }),
+  });
+  const j = await res.json();
+  if (!j.access_token) throw new Error(`vydanne: Play token exchange failed: ${JSON.stringify(j).slice(0, 300)}`);
+  return j.access_token;
+}

package/src/play/client.mjs

@@ -0,0 +1,68 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getAccessToken } from "./auth.mjs";
+
+const BASE = "https://androidpublisher.googleapis.com/androidpublisher/v3";
+const UPLOAD = "https://androidpublisher.googleapis.com/upload/androidpublisher/v3";
+
+// Google Play Developer API client. THE key difference from Apple: everything goes through an **Edit**
+// transaction — insert an edit, mutate listings/images/details against it, then commit (all-or-nothing).
+// Nothing is live until commit; a dropped edit changes nothing. Image bytes go to the /upload endpoint.
+export class PlayClient {
+  static async create({ keyPath, packageName }) {
+    const token = await getAccessToken(keyPath);
+    return new PlayClient(token, packageName);
+  }
+  constructor(token, packageName) {
+    this.token = token;
+    this.pkg = packageName;
+  }
+
+  async req(method, subpath, { body, base = BASE } = {}) {
+    const res = await fetch(`${base}/applications/${this.pkg}${subpath}`, {
+      method,
+      headers: { Authorization: `Bearer ${this.token}`, ...(body ? { "Content-Type": "application/json" } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let json; try { json = text ? JSON.parse(text) : {}; } catch { json = text; }
+    return { status: res.status, json };
+  }
+
+  // ── Edit transaction ──────────────────────────────────────────────────────────────────────────────
+  async newEdit() {
+    const { status, json } = await this.req("POST", "/edits", { body: {} });
+    if (status >= 300) throw new Error(`edits.insert ${status}: ${JSON.stringify(json).slice(0, 200)}`);
+    return json.id;
+  }
+  validate(editId) { return this.req("POST", `/edits/${editId}:validate`, { body: {} }); }
+  commit(editId) { return this.req("POST", `/edits/${editId}:commit`, { body: {} }); }
+  deleteEdit(editId) { return this.req("DELETE", `/edits/${editId}`); }
+
+  // ── Listings (per language) ──────────────────────────────────────────────────────────────────────
+  getListings(editId) { return this.req("GET", `/edits/${editId}/listings`); }
+  // body: { language, title, shortDescription, fullDescription, video }
+  putListing(editId, language, body) { return this.req("PUT", `/edits/${editId}/listings/${language}`, { body: { language, ...body } }); }
+
+  // ── Details (default language + contact) ─────────────────────────────────────────────────────────
+  getDetails(editId) { return this.req("GET", `/edits/${editId}/details`); }
+  patchDetails(editId, body) { return this.req("PATCH", `/edits/${editId}/details`, { body }); }
+
+  // ── Images ───────────────────────────────────────────────────────────────────────────────────────
+  // imageType: phoneScreenshots | sevenInchScreenshots | tenInchScreenshots | wearScreenshots |
+  //            tvScreenshots | icon | featureGraphic | promoGraphic | tvBanner
+  listImages(editId, language, imageType) { return this.req("GET", `/edits/${editId}/listings/${language}/${imageType}`); }
+  deleteAllImages(editId, language, imageType) { return this.req("DELETE", `/edits/${editId}/listings/${language}/${imageType}`); }
+  async uploadImage(editId, language, imageType, filePath) {
+    const bytes = fs.readFileSync(filePath);
+    const mime = path.extname(filePath).toLowerCase() === ".jpg" || path.extname(filePath).toLowerCase() === ".jpeg" ? "image/jpeg" : "image/png";
+    const res = await fetch(`${UPLOAD}/applications/${this.pkg}/edits/${editId}/listings/${language}/${imageType}?uploadType=media`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${this.token}`, "Content-Type": mime },
+      body: bytes,
+    });
+    const j = await res.json().catch(() => ({}));
+    if (res.status >= 300) throw new Error(`image upload ${res.status}: ${JSON.stringify(j).slice(0, 200)}`);
+    return j;
+  }
+}

package/src/play/commands/diff.mjs

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+import { green, red, yellow } from "../../util.mjs";
+
+// [Play listing attribute, local metadata filename] — supply's convention under fastlane/metadata/android.
+const FIELDS = [["title", "title"], ["shortDescription", "short_description"], ["fullDescription", "full_description"]];
+const norm = (s) => (s == null ? null : String(s).replace(/\r/g, "").replace(/\n+$/, "").trim());
+
+// Show what differs between local Play sources (fastlane/metadata/android/<locale>/*.txt) and the live Play
+// listing — a dry-run of `fill --store google`.
+export async function run(config, client) {
+  const g = config.google;
+  const editId = await client.newEdit();
+  let actionable = 0;
+  try {
+    const listings = (await client.getListings(editId)).json.listings || [];
+    const remote = Object.fromEntries(listings.map((l) => [l.language, l]));
+    const dir = g.metadataDir;
+    const localLangs = fs.existsSync(dir) ? fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : [];
+
+    if (!localLangs.length) {
+      console.log(yellow(`  no local listing folders under ${dir} (Android Phase 2 — nothing to push yet)`));
+    }
+    for (const lang of localLangs) {
+      const read = (f) => { const p = path.join(dir, lang, `${f}.txt`); return fs.existsSync(p) ? norm(fs.readFileSync(p, "utf8")) : null; };
+      const R = remote[lang] || {};
+      const out = [];
+      if (!remote[lang]) { out.push(yellow("[fill would create]")); }
+      for (const [attr, file] of FIELDS) {
+        const L = read(file), Rv = norm(R[attr]);
+        if (L == null && (Rv == null || Rv === "")) continue;
+        if (L == null) out.push(`${file} ${yellow("[remote-only]")}`);
+        else if (!Rv) out.push(`${file} ${green("[local-only]")}`);
+        else if (L !== Rv) { out.push(`${file} ${red("differs")}`); actionable++; }
+      }
+      if (out.length) console.log(`  ${lang}: ${out.join(" · ")}`);
+    }
+    const localSet = new Set(localLangs);
+    const extra = listings.map((l) => l.language).filter((x) => !localSet.has(x));
+    if (extra.length) console.log(`  ${yellow("Play-only languages")} (no local folder): ${extra.join(", ")}`);
+  } finally {
+    await client.deleteEdit(editId);
+  }
+  console.log();
+  console.log(actionable ? yellow(`${actionable} actionable difference(s) — run \`fill --store google\` to sync`) : green("in sync — local matches Play"));
+  return true;
+}

package/src/play/commands/fill.mjs

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import { green, yellow, red } from "../../util.mjs";
+
+const FIELDS = [["title", "title"], ["shortDescription", "short_description"], ["fullDescription", "full_description"]];
+// Play image type -> local source (a dir of PNGs = screenshots; a single file = graphic). From zdymak.
+// Each type is uploaded only when its local asset EXISTS, so an app that lacks (say) tablet shots or a
+// znachok icon simply skips that type — a missing local set never deletes the live one.
+const IMAGES = [
+  ["icon", "brand/icons/play/icon-512.png", "file"],
+  ["featureGraphic", "marketing/out/play-feature-graphic.png", "file"],
+  ["phoneScreenshots", "marketing/out/play-phone-plain", "dir"],
+  ["sevenInchScreenshots", "marketing/out/play-tablet7-plain", "dir"],
+  ["tenInchScreenshots", "marketing/out/play-tablet-plain", "dir"],
+];
+
+// Push the Play listing (text + images) inside one Edit, then validate and commit. iOS/Android are separate
+// stores — this is the Google half. Images only touch a type whose local asset EXISTS (so a missing local
+// set never deletes the live one). VYDANNE_DRY=1 validates and discards without committing.
+export async function run(config, client) {
+  const g = config.google;
+  // SAFE BY DEFAULT: validate + discard the edit unless VYDANNE_COMMIT=1. A store-mutating commit must be
+  // an explicit opt-in — never the default (a stale/partial local set could otherwise clobber a live one).
+  const commit = process.env.VYDANNE_COMMIT === "1";
+  const localLangs = fs.existsSync(g.metadataDir)
+    ? fs.readdirSync(g.metadataDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
+    : [];
+  const haveImages = IMAGES.some(([, src]) => fs.existsSync(src));
+  if (!localLangs.length && !haveImages) {
+    console.log(yellow(`fill(play): no local listing folders under ${g.metadataDir} and no zdymak play assets — nothing to upload yet (populate them for Android Phase 2).`));
+    return true;
+  }
+
+  const editId = await client.newEdit();
+  try {
+    // Listing text
+    for (const lang of localLangs) {
+      const read = (f) => { const p = path.join(g.metadataDir, lang, `${f}.txt`); return fs.existsSync(p) ? fs.readFileSync(p, "utf8").replace(/\n+$/, "") : undefined; };
+      const body = {};
+      for (const [attr, file] of FIELDS) { const t = read(file); if (t !== undefined) body[attr] = t; }
+      if (Object.keys(body).length) {
+        const r = await client.putListing(editId, lang, body);
+        if (r.status >= 300) throw new Error(`listing ${lang} ${r.status}: ${JSON.stringify(r.json).slice(0, 160)}`);
+        console.log(green(`  ${lang}: listing (${Object.keys(body).join(", ")})`));
+      }
+    }
+    // Images — replace a type only when the local asset exists (delete-all then upload).
+    const lang = g.defaultLocale;
+    for (const [type, src, kind] of IMAGES) {
+      if (!fs.existsSync(src)) continue;
+      const files = kind === "dir" ? fs.readdirSync(src).filter((f) => /\.(png|jpe?g)$/i.test(f)).sort().map((f) => path.join(src, f)) : [src];
+      if (!files.length) continue;
+      await client.deleteAllImages(editId, lang, type);
+      for (const f of files) await client.uploadImage(editId, lang, type, f);
+      console.log(green(`  ${lang}/${type}: ${files.length} image(s)`));
+    }
+
+    const v = await client.validate(editId);
+    if (v.status >= 300) throw new Error(`validate ${v.status}: ${JSON.stringify(v.json).slice(0, 200)}`);
+    if (!commit) { await client.deleteEdit(editId); console.log(yellow("fill(play): validated — DRY (nothing changed). Review the above, then set VYDANNE_COMMIT=1 to commit.")); return true; }
+    const co = await client.commit(editId);
+    if (co.status >= 300) throw new Error(`commit ${co.status}: ${JSON.stringify(co.json).slice(0, 200)}`);
+    console.log(green("fill(play): committed."));
+  } catch (e) {
+    await client.deleteEdit(editId).catch(() => {});
+    throw e;
+  }
+  return true;
+}

package/src/play/commands/inspect.mjs

@@ -0,0 +1,24 @@
+const IMAGE_TYPES = ["phoneScreenshots", "sevenInchScreenshots", "tenInchScreenshots", "wearScreenshots", "tvScreenshots", "featureGraphic", "icon", "promoGraphic"];
+
+// Read-only snapshot of the Play listing — languages, contact details, image counts. Everything reads
+// through one throwaway edit (deleted, never committed), the same as the ASC `inspect`.
+export async function run(config, client) {
+  const g = config.google;
+  const editId = await client.newEdit();
+  try {
+    const details = (await client.getDetails(editId)).json;
+    const listings = (await client.getListings(editId)).json.listings || [];
+    console.log(`PLAY ${g.packageName}  default=${details.defaultLanguage}  contact=${details.contactEmail || "-"}`);
+    console.log(`  listings (${listings.length}): ${listings.map((l) => l.language).join(", ") || "(none)"}`);
+    const lang = details.defaultLanguage || g.defaultLocale;
+    const counts = [];
+    for (const t of IMAGE_TYPES) {
+      const imgs = (await client.listImages(editId, lang, t)).json.images || [];
+      if (imgs.length) counts.push(`${t}=${imgs.length}`);
+    }
+    console.log(`  images (${lang}): ${counts.join("  ") || "(none)"}`);
+  } finally {
+    await client.deleteEdit(editId);
+  }
+  return true;
+}