vydanne 0.7.0 → 0.8.1

package/README.md

@@ -201,7 +201,7 @@ DRY RUN — 40 store write(s) withheld. Re-run with --apply to perform them.
 ```
 
 The commands this applies to are marked `✎` in the usage text (`vydanne` with no arguments): `prepare`, `push`, `fill`, `previews`,
-`age-rating`, `review-contact`, `accessibility`, `prerelease`. Everything else only reads, and ignores
+`appinfo`, `age-rating`, `review-contact`, `accessibility`, `prerelease`. Everything else only reads, and ignores
 the flag.
 
 Two details worth knowing:
@@ -232,6 +232,7 @@ Two details worth knowing:
 | `previews` | Uploads App Preview videos. |
 | `inspect` | Shows the app's current state in the store. Read-only. |
 | `locales` | Lists your languages and Apple's code for each — and warns about any language the App Store doesn't offer. |
+| `appinfo` | Sets the App Store **category** and the **content-rights** answer — the two app-level facts that block *Add for Review* and belong to no single release. Declared as `categories` (Apple's ids: `GAMES`, `GAMES_PUZZLE` — never display names) and `contentRights: false` for an app that shows no third-party content. Left undeclared, `contentRights` is not written at all, so an answer already given in App Store Connect is never overwritten by a default nobody chose. |
 | `age-rating` | Sets the age rating. `rating: "4+"` needs nothing else; any higher rating is described feature-by-feature in `ageRating` and Apple computes the band from it. |
 | `review-contact` | Fills in the App Review contact details (who Apple calls if there's a problem). |
 | `accessibility` | Saves Accessibility Nutrition Labels from the `accessibility` block in your config. Stays a draft until your app is live. Refuses to run if you have not declared one — see below. |
@@ -243,7 +244,7 @@ Two details worth knowing:
 
 For **Google Play**, add `--store google` to `inspect`, `diff`, `preflight`, `fill`, or `prerelease`.
 
-`prepare`, `push`, `fill`, `previews`, `age-rating`, `review-contact`, `accessibility` and `prerelease`
+`prepare`, `push`, `fill`, `previews`, `appinfo`, `age-rating`, `review-contact`, `accessibility` and `prerelease`
 change the store, so they need [`--apply`](#--apply-or-nothing-happens); without it they report and exit.
 
 ## The release pipeline — the order matters

package/SKILL.md

@@ -210,7 +210,7 @@ who it's for → honest close. Keep it scannable; lead each bullet with the payo
 ## B. Commands (push it)
 
 `fill` (metadata + screenshots, native PATCH/chunked upload — works even at READY_FOR_REVIEW) ·
-`previews` (App Preview videos) · `age-rating` · `review-contact` · `accessibility` (draft; publish once
+`previews` (App Preview videos) · `appinfo` (category + content rights) · `age-rating` · `review-contact` · `accessibility` (draft; publish once
 live) · `privacy` (prints answers for the UI — the API can't reach Apple's iris host) · `iap` (validate +
 RGB flatten) · `compliance` (US self-classification PDF) · `bridge` (zdymak's output → the folders
 `fill` reads) · `diff` (what differs vs live, text AND media by checksum) · `preflight`
@@ -303,7 +303,7 @@ The AAB binary and the (YouTube-URL) promo video stay outside vydanne.
 ## `--apply` — writes are opt-in
 
 **Every store-mutating command is a DRY RUN without `--apply`**: `prepare` · `push` · `fill` ·
-`previews` · `age-rating` · `review-contact` · `accessibility` · `prerelease` (marked `✎` in
+`previews` · `appinfo` · `age-rating` · `review-contact` · `accessibility` · `prerelease` (marked `✎` in
 the usage text, printed by `vydanne` with no arguments). They read the store, print each write they would make, and send nothing. Read-only
 commands ignore the flag.
 
@@ -343,3 +343,21 @@ promo) · char limits (name/subtitle 30, keywords 100, promo 170; IAP name 30 /
 short 80 / full 4000) · **Play uses its OWN locale codes** · Play images push only when the local file
 exists, so a missing set never wipes the live one · Apple requires `name` when *creating* an app-info
 localization (409 otherwise).
+
+## The blockers that only appear on the Add for Review screen
+
+Apple checks these last, so a release can be green everywhere — metadata filled, screenshots up,
+build attached, `preflight` clean — and still stop dead with a list nobody can act on from a
+terminal. Four of the five are now vydanne's; the fifth is not reachable by any API.
+
+| blocker | who sets it |
+|---|---|
+| Privacy Policy URL | `fill` — `privacy_url.txt` per locale (an `appInfoLocalizations` field, so **every** locale needs it) |
+| Copyright | `prepare` — `<metadataDir>/copyright.txt`, on create **and** on reuse |
+| Primary category | `appinfo` — `categories` |
+| Content Rights | `appinfo` — `contentRights` |
+| **Price tier** | **App Store Connect UI.** Pricing is a separate agreement-bound surface; vydanne does not touch money. |
+
+`preflight` will NOT catch these. It verifies submission-completeness of the things it writes; a
+category it never sets is not a gap it knows to look for. Run `appinfo` once per app and the list
+shortens to the price.

package/bin/vydanne.mjs

@@ -128,6 +128,10 @@ usage: vydanne <command> [--apply] [--config vydanne.config.mjs]
                   skipped); every skip is reported again at the end, so green still means green.
                   Ends at a green preflight — Add to Review + Submit stay yours, in the web UI.
 ✎ fill            metadata + screenshots + previews (native; iOS & macOS separate)
+✎ appinfo         App Store category + the content-rights answer — the two app-level facts that
+                  block Add for Review and belong to no single release. 'categories' takes Apple's
+                  ids (GAMES, GAMES_PUZZLE — not display names); 'contentRights: false' for an app
+                  showing no third-party content. Set once; re-running is a no-op.
 ✎ age-rating      set the age rating (AppInfo declaration)
 ✎ review-contact  App Review contact from the gitignored files
 ✎ accessibility   Accessibility Nutrition Labels (draft; VYDANNE_A11Y_PUBLISH=1 to publish once live)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "App Store Connect + Google Play submission prep — the companion to zdymak (media). Native Node (no fastlane/Ruby/Python): localized listings, screenshot/preview/icon upload, ratings, review contact, accessibility & privacy labels, IAP, export docs, build upload to TestFlight / a Play closed track, a diff of local-vs-store, and a preflight verifier that encodes the store gotchas. Never submits for review. iOS/macOS via the ASC REST API; Android via the Play Developer Edits API (--store google).",
   "keywords": [
     "app-store-connect",
@@ -52,7 +52,8 @@
     "check:docs": "node scripts/check-docs.mjs",
     "check:types": "tsc --noEmit -p tsconfig.json && node scripts/check-types.mjs",
     "check:config": "node scripts/check-config.mjs",
-    "prepublishOnly": "npm run check:docs && npm run check:types && npm run check:config",
+    "verify": "npm run check:docs && npm run check:types && npm run check:config",
+    "prepublishOnly": "npm run verify",
     "release:patch": "node scripts/release.mjs patch",
     "release:minor": "node scripts/release.mjs minor",
     "release:major": "node scripts/release.mjs major"

package/src/commands/appInfo.mjs

@@ -0,0 +1,124 @@
+import { green, yellow, red } from "../util.mjs";
+
+/**
+ * The two app-level facts that block **Add for Review** and nothing else in vydanne could set.
+ *
+ *   You must select a primary category for your app.
+ *   You must set up Content Rights Information in App Information.
+ *
+ * Both are one API call each and were simply never wired, so a release that was green everywhere —
+ * metadata filled, screenshots uploaded, build attached, preflight clean — still stopped dead at the
+ * last screen with two errors nobody could act on from a terminal. That is the worst place to
+ * discover missing automation: after the work, in a web form, with no record of what the right
+ * answer was last time.
+ *
+ * Deliberately its OWN command rather than folded into `prepare`. `prepare` is about a version; these
+ * are about the app, and they outlive every version — setting them once is normal and re-running is a
+ * no-op. Keeping them separate also means a failure here names itself instead of failing a step whose
+ * name says "version".
+ */
+
+/**
+ * Apple's category vocabulary is a fixed set of ids, and `GAMES` is the only one with subcategories.
+ * Listed rather than free-typed because a wrong id returns a 409 that names neither the field nor the
+ * legal values, and the guess someone makes from that ("Puzzle", "games") is wrong twice over — the
+ * ids are upper snake case and game subcategories are prefixed.
+ */
+const CATEGORIES = new Set([
+  "BOOKS", "BUSINESS", "DEVELOPER_TOOLS", "EDUCATION", "ENTERTAINMENT", "FINANCE", "FOOD_AND_DRINK",
+  "GAMES", "GRAPHICS_AND_DESIGN", "HEALTH_AND_FITNESS", "LIFESTYLE", "MAGAZINES_AND_NEWSPAPERS",
+  "MEDICAL", "MUSIC", "NAVIGATION", "NEWS", "PHOTO_AND_VIDEO", "PRODUCTIVITY", "REFERENCE",
+  "SHOPPING", "SOCIAL_NETWORKING", "SPORTS", "TRAVEL", "UTILITIES", "WEATHER",
+]);
+
+const GAME_SUBCATEGORIES = new Set([
+  "GAMES_ACTION", "GAMES_ADVENTURE", "GAMES_BOARD", "GAMES_CARD", "GAMES_CASINO", "GAMES_CASUAL",
+  "GAMES_FAMILY", "GAMES_MUSIC", "GAMES_PUZZLE", "GAMES_RACING", "GAMES_ROLE_PLAYING",
+  "GAMES_SIMULATION", "GAMES_SPORTS", "GAMES_STRATEGY", "GAMES_TRIVIA", "GAMES_WORD",
+]);
+
+/** Apple's own two values, stated as a question so a config cannot get the polarity backwards. */
+const RIGHTS = {
+  true: "USES_THIRD_PARTY_CONTENT",
+  false: "DOES_NOT_USE_THIRD_PARTY_CONTENT",
+};
+
+function validate(config) {
+  const c = config.categories;
+  if (!c) return { problem: "appinfo: no `categories` in the config — set at least { primary: 'GAMES' }." };
+  const bad = [];
+  if (!CATEGORIES.has(c.primary)) bad.push(`primary '${c.primary}' is not an Apple category id (e.g. GAMES, PUZZLE is a SUBcategory)`);
+  if (c.secondary && !CATEGORIES.has(c.secondary)) bad.push(`secondary '${c.secondary}' is not an Apple category id`);
+  for (const k of ["primarySubcategoryOne", "primarySubcategoryTwo", "secondarySubcategoryOne", "secondarySubcategoryTwo"]) {
+    if (c[k] && !GAME_SUBCATEGORIES.has(c[k])) bad.push(`${k} '${c[k]}' is not a game subcategory id (they are GAMES_*)`);
+  }
+  // Apple allows subcategories only under GAMES; sending them otherwise is a 409 that reads as a
+  // generic relationship error.
+  if (c.primarySubcategoryOne && c.primary !== "GAMES") bad.push("subcategories are only valid when primary is GAMES");
+  if (config.contentRights !== undefined && typeof config.contentRights !== "boolean") {
+    bad.push("contentRights must be true (uses third-party content) or false (does not)");
+  }
+  return bad.length ? { problem: `appinfo: ${bad.join("; ")}` } : {};
+}
+
+const rel = (id) => (id ? { data: { type: "appCategories", id } } : { data: null });
+
+export async function run(config, client) {
+  const { problem } = validate(config);
+  if (problem) { console.error(red(problem)); return false; }
+
+  await client.findApp(config.bundleId);
+  // Same refusal as age-rating, and for the same reason: the LIVE app info's category is not ours to
+  // aim a write at, and appInfo() returning the live record instead of null once made that write look
+  // like it had worked.
+  const info = await client.appInfo();
+  if (!info) {
+    console.error(red("appinfo: no editable app info — refusing to write to the live record."));
+    console.error("  `vydanne prepare --apply` starts the next version, which makes app info editable again.");
+    return false;
+  }
+
+  const c = config.categories;
+  const relationships = {
+    primaryCategory: rel(c.primary),
+    primarySubcategoryOne: rel(c.primarySubcategoryOne),
+    primarySubcategoryTwo: rel(c.primarySubcategoryTwo),
+    secondaryCategory: rel(c.secondary),
+    secondarySubcategoryOne: rel(c.secondarySubcategoryOne),
+    secondarySubcategoryTwo: rel(c.secondarySubcategoryTwo),
+  };
+  const shown = [c.primary, c.primarySubcategoryOne, c.primarySubcategoryTwo, c.secondary]
+    .filter(Boolean).join(" · ");
+  console.log(`  categories: ${shown}`);
+
+  const r = await client.patch(`/v1/appInfos/${info.id}`, {
+    data: { type: "appInfos", id: info.id, relationships },
+  });
+  if (r.status >= 300) {
+    console.error(red(`appinfo: categories ${r.status}`));
+    for (const e of r.json?.errors || []) console.error(`    ${e.title}: ${e.detail}`);
+    return false;
+  }
+  console.log(client.dryRun ? yellow(`  WOULD set categories`) : green(`  categories set`));
+
+  // Content rights is on the APP, not the app info — a different resource, which is most of why it
+  // was missed. Skipped entirely when undeclared, so an app that has already answered in the UI is
+  // not overwritten by a default nobody chose.
+  if (config.contentRights === undefined) {
+    console.log(yellow("  contentRights not declared — Add for Review needs it; set `contentRights: false` if the app uses no third-party content."));
+    return true;
+  }
+  const declaration = RIGHTS[String(config.contentRights)];
+  const a = await client.patch(`/v1/apps/${client.appId}`, {
+    data: { type: "apps", id: client.appId, attributes: { contentRightsDeclaration: declaration } },
+  });
+  if (a.status >= 300) {
+    console.error(red(`appinfo: content rights ${a.status}`));
+    for (const e of a.json?.errors || []) console.error(`    ${e.title}: ${e.detail}`);
+    return false;
+  }
+  console.log(client.dryRun
+    ? yellow(`  WOULD set content rights -> ${declaration}`)
+    : green(`  content rights -> ${declaration}`));
+  return true;
+}

package/src/commands/diff.mjs

@@ -10,7 +10,12 @@ const VERSION_FIELDS = [
   ["description", "description", true], ["keywords", "keywords", false], ["promotionalText", "promotional_text", false],
   ["whatsNew", "release_notes", true], ["marketingUrl", "marketing_url", false], ["supportUrl", "support_url", false],
 ];
-const INFO_FIELDS = [["name", "name", false], ["subtitle", "subtitle", false]];
+// Must list everything `fill`'s INFO_TXT writes, or `diff` reports "in sync" over a field it never
+// looked at — which is not a harmless gap: `fill` PATCHes unconditionally (patchAttrs never compares),
+// so `diff` is the ONLY thing that can say whether a value actually reached Apple. When
+// privacyPolicyUrl was added to fill and not here, one command claimed 19 pending writes while the
+// other claimed sync, and neither was evidence of anything.
+const INFO_FIELDS = [["name", "name", false], ["subtitle", "subtitle", false], ["privacyPolicyUrl", "privacy_url", false]];
 
 const norm = (s) => (s == null ? null : String(s).replace(/\r/g, "").replace(/\n+$/, "").trim());
 const short = (s, n = 24) => { s = String(s).replace(/\n/g, " "); return s.length > n ? s.slice(0, n) + "…" : s; };

package/src/commands/fill.mjs

@@ -6,9 +6,15 @@ import { uploadAsset } from "../upload.mjs";
 import { reportCrossStore } from "../crossStore.mjs";
 import { deviceMap, screenshotBase, IMAGE_FILE } from "../screenshots.mjs";
 
-// Version-localization fields (attr -> metadata filename) and AppInfo fields (name/subtitle, shared).
+// Version-localization fields (attr -> metadata filename) and AppInfo fields (shared across releases).
 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" };
+// `privacyPolicyUrl` belongs here rather than on the version because it is an APP-level fact, not a
+// per-release one. Apple blocks Add for Review without it ("You must enter a Privacy Policy URL in
+// App Privacy") — a wall you hit at the very end, once everything else is green, and one nothing in
+// vydanne could clear because this map stopped at name/subtitle. It is per-LOCALE all the same, so a
+// game with a single policy page writes the same line into each locale's `privacy_url.txt`; the
+// filename follows fastlane's own convention, so an existing metadata tree needs no rearranging.
+const INFO_TXT = { name: "name", subtitle: "subtitle", privacyPolicyUrl: "privacy_url" };
 
 /**
  * PATCH a localization, surviving attributes Apple refuses to edit RIGHT NOW.

package/src/commands/prepare.mjs

@@ -44,7 +44,12 @@ const NEXT_STEPS = [
 async function versionsFor(client, platform) {
   const { json } = await client.get(
     `/v1/apps/${client.appId}/appStoreVersions?filter[platform]=${platform}&limit=200` +
-      `&fields[appStoreVersions]=versionString,appStoreState`,
+      // `copyright` is requested because syncCopyright compares against it. A sparse fieldset that
+      // omits it does not read as absent — it reads as EMPTY, so the comparison can never match and
+      // the field is re-PATCHed on every run, spending a request to change nothing and printing
+      // "(was empty)" over a value that was already correct. A guard that cannot see the thing it
+      // guards is not a guard.
+      `&fields[appStoreVersions]=versionString,appStoreState,copyright`,
   );
   return json.data || [];
 }
@@ -70,6 +75,46 @@ function readCopyright(config) {
   return fs.readFileSync(p, "utf8").trim() || null;
 }
 
+/**
+ * Copyright on a version that ALREADY EXISTED.
+ *
+ * It was only ever set at creation, on the reasoning below that nothing else in vydanne writes this
+ * version-level field — which was true and yet left the gap wide open, because `prepare` is
+ * find-or-CREATE. Every app whose draft was made before `copyright.txt` existed, or made by hand in
+ * App Store Connect, or created by an older vydanne, reused that version forever and never got a
+ * copyright. The tooling then reported "prepare done — the version is editable" and the operator
+ * discovered the truth from Apple, at the end, as `Copyright - This field is required` on the Add
+ * for Review screen. The comment three lines down even called it "a metadata rejection waiting to
+ * happen".
+ *
+ * So the create path and the reuse path now converge: after this, a version has the copyright the
+ * repo declares, however that version came to exist.
+ *
+ * PATCHes only on a real difference. Apple's rate limits are per-app and a `prepare` that rewrites
+ * an already-correct field on every `push` spends a request to change nothing — and, more to the
+ * point, prints a line claiming it did something.
+ */
+async function syncCopyright(client, config, version) {
+  const want = readCopyright(config);
+  if (!want) return;
+  const have = version.attributes?.copyright ?? "";
+  if (have === want) return;
+
+  const was = have ? ` (was "${have}")` : " (was empty)";
+  const r = await client.patch(`/v1/appStoreVersions/${version.id}`, {
+    data: { type: "appStoreVersions", id: version.id, attributes: { copyright: want } },
+  });
+  if (r.status >= 300) {
+    console.error(red(`  could not set copyright (${r.status})`));
+    for (const e of r.json?.errors || []) console.error(`    ${e.title}: ${e.detail}`);
+    return;
+  }
+  version.attributes.copyright = want;
+  console.log(client.dryRun
+    ? yellow(`  WOULD set copyright: "${want}"${was}`)
+    : green(`  copyright set: "${want}"${was}`));
+}
+
 /**
  * Is `a` a higher marketing version than `b`?
  *
@@ -117,6 +162,7 @@ export async function ensureVersion(client, config, platform, versionString) {
       return null;
     }
     console.log(green(`  version ${versionString} already exists (${state}) — reusing it`));
+    await syncCopyright(client, config, existing);
     return existing;
   }
 

package/src/config.mjs

@@ -8,7 +8,7 @@ import { DEFAULT_PLAY_IMAGES } from "./play/images.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", "localeMap", "metadataDir", "screenshots", "rating", "ageRating", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "bridge", "push", "reviewContact", "allowCrossStoreTerms"];
+export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "localeMap", "metadataDir", "screenshots", "rating", "ageRating", "categories", "contentRights", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "bridge", "push", "reviewContact", "allowCrossStoreTerms"];
 
 // One `vydanne.config.mjs` per app (ESM, like zdymak.config.mjs) — nothing hard-coded. Secrets stay out:
 // credentials resolve from the environment, a gitignored .env, or ~/.appstoreconnect/config.json (see
@@ -44,6 +44,12 @@ export async function loadConfig(p) {
     // Content descriptors for a rating above 4+. Null means "the 4+ shorthand", which `age-rating`
     // expands to an all-NONE declaration; anything else must be declared, never guessed.
     ageRating: raw.ageRating || null,
+    // App Store category, and whether the app shows third-party content. Both block Add for Review
+    // and neither has a safe default: a category guessed on the app's behalf is a shelf it did not
+    // choose, and a content-rights answer guessed on its behalf is a DECLARATION TO APPLE nobody
+    // made. So both stay null/undefined until declared, and `appinfo` refuses rather than assumes.
+    categories: raw.categories || null,
+    contentRights: raw.contentRights,
     privacy: raw.privacy || { collected: ["CRASH_DATA", "PERFORMANCE_DATA"], tracking: false },
     iaps: raw.iaps || [],
     metadataDir: raw.metadataDir || "fastlane/metadata",

package/src/registry.mjs

@@ -19,6 +19,7 @@ export const COMMANDS = {
   // written to a live listing while everyone re-derived it. Stops at the first failure; never submits.
   push: { mod: "push", client: true, writes: true },
   fill: { mod: "fill", client: true, writes: true },
+  appinfo: { mod: "appInfo", client: true, writes: true },
   "age-rating": { mod: "ageRating", client: true, writes: true },
   "review-contact": { mod: "reviewContact", client: true, writes: true },
   accessibility: { mod: "accessibility", client: true, writes: true },

package/types/index.d.ts

@@ -19,6 +19,11 @@ export type CommandName =
    */
   | 'push'
   | 'fill'
+  /**
+   * The two app-level facts that block **Add for Review** and belong to no single release: the App
+   * Store category, and whether the app shows third-party content. Set once; re-running is a no-op.
+   */
+  | 'appinfo'
   | 'age-rating'
   | 'review-contact'
   | 'accessibility'
@@ -68,6 +73,19 @@ export interface PreviewSpec {
   locales?: string[];
 }
 
+/**
+ * Apple's category ids, not display names: upper snake case, and game subcategories are `GAMES_*`
+ * ('GAMES_PUZZLE', never 'Puzzle'). Apple takes up to two subcategories per category.
+ */
+export interface CategoriesConfig {
+  primary: string;
+  primarySubcategoryOne?: string;
+  primarySubcategoryTwo?: string;
+  secondary?: string;
+  secondarySubcategoryOne?: string;
+  secondarySubcategoryTwo?: string;
+}
+
 export interface PrivacyConfig {
   /** ASC data-type ids, e.g. ['CRASH_DATA', 'PERFORMANCE_DATA']. */
   collected: string[];
@@ -268,6 +286,17 @@ export interface VydanneConfig {
   rating?: string;
   /** Content descriptors for a rating above '4+'. Merged over an all-NONE base. */
   ageRating?: AgeRatingConfig;
+  /**
+   * App Store category, written by `appinfo`. Apple blocks Add for Review without a primary one, and
+   * subcategories are valid only under `'GAMES'`.
+   */
+  categories?: CategoriesConfig;
+  /**
+   * Does the app contain, show or access THIRD-PARTY content? Also blocks Add for Review. Left
+   * undefined it is not written at all, so an answer already given in App Store Connect is never
+   * overwritten by a default nobody chose — this is a declaration to Apple, not a preference.
+   */
+  contentRights?: boolean;
   privacy?: PrivacyConfig;
   iaps?: IapConfig[];
   previews?: PreviewSpec[];