storemeta 0.1.0

package/dist/writers/ensure-directory.js

@@ -0,0 +1,16 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { StoremetaError } from "../cli/errors.js";
+export async function ensureDirectory(directoryPath) {
+    const resolvedPath = resolve(directoryPath);
+    try {
+        await mkdir(resolvedPath, { recursive: true });
+    }
+    catch (cause) {
+        throw new StoremetaError("FILESYSTEM_ERROR", `Failed to create directory at ${resolvedPath}`, { cause });
+    }
+    return resolvedPath;
+}
+export async function ensureParentDirectory(filePath) {
+    return ensureDirectory(dirname(resolve(filePath)));
+}

package/dist/writers/order-screenshots.js

@@ -0,0 +1,19 @@
+import { extname } from "node:path";
+function getCanonicalScreenshotExtension(fileName) {
+    const extension = extname(fileName).toLowerCase();
+    return extension.length > 0 ? extension : ".png";
+}
+export function orderScreenshotsForWrite(screenshots) {
+    return [...screenshots]
+        .sort((left, right) => {
+        if (left.position !== right.position) {
+            return left.position - right.position;
+        }
+        return left.fileName.localeCompare(right.fileName);
+    })
+        .map((screenshot, index) => ({
+        ...screenshot,
+        position: index + 1,
+        fileName: `${index + 1}${getCanonicalScreenshotExtension(screenshot.fileName)}`,
+    }));
+}

package/dist/writers/resolve-screenshot-path.js

@@ -0,0 +1,8 @@
+import { normalizeLocaleCode } from "../locales/normalize.js";
+import { resolvePathWithinBaseDir } from "./resolve-within-base-dir.js";
+export function resolveScreenshotSetDirectory(baseDir, screenshotSet) {
+    return resolvePathWithinBaseDir(baseDir, screenshotSet.platform, normalizeLocaleCode(screenshotSet.locale), screenshotSet.assetType);
+}
+export function resolveScreenshotFilePath(baseDir, screenshot) {
+    return resolvePathWithinBaseDir(baseDir, screenshot.platform, normalizeLocaleCode(screenshot.locale), screenshot.assetType, screenshot.fileName);
+}

package/dist/writers/resolve-within-base-dir.js

@@ -0,0 +1,17 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { StoremetaError } from "../cli/errors.js";
+export function assertPathWithinBaseDir(baseDir, targetPath) {
+    const resolvedBaseDir = resolve(baseDir);
+    const resolvedTargetPath = resolve(targetPath);
+    const relativePath = relative(resolvedBaseDir, resolvedTargetPath);
+    if (relativePath === "" ||
+        (!relativePath.startsWith("..") && !isAbsolute(relativePath))) {
+        return resolvedTargetPath;
+    }
+    throw new StoremetaError("FILESYSTEM_ERROR", `Resolved path escapes base directory: ${resolvedTargetPath}`);
+}
+export function resolvePathWithinBaseDir(baseDir, ...pathSegments) {
+    const resolvedBaseDir = resolve(baseDir);
+    const resolvedTargetPath = resolve(resolvedBaseDir, ...pathSegments);
+    return assertPathWithinBaseDir(resolvedBaseDir, resolvedTargetPath);
+}

package/dist/writers/write-metadata.js

@@ -0,0 +1,17 @@
+import { writeFile } from "node:fs/promises";
+import { StoremetaError } from "../cli/errors.js";
+import { serializeMetadataDocument } from "../formats/serialize-metadata.js";
+import { ensureParentDirectory } from "./ensure-directory.js";
+import { resolvePathWithinBaseDir } from "./resolve-within-base-dir.js";
+export async function writeMetadataFile(baseDir, filePath, document) {
+    const resolvedPath = resolvePathWithinBaseDir(baseDir, filePath);
+    const serialized = serializeMetadataDocument(document);
+    try {
+        await ensureParentDirectory(resolvedPath);
+        await writeFile(resolvedPath, serialized, "utf8");
+    }
+    catch (cause) {
+        throw new StoremetaError("FILESYSTEM_ERROR", `Failed to write metadata file at ${resolvedPath}`, { cause });
+    }
+    return resolvedPath;
+}

package/docs/API_EDITABLE_METADATA_SURFACE.md

@@ -0,0 +1,319 @@
+# API Editable Metadata Surface
+
+This document lists the app metadata and store-asset areas that are editable through the public Apple and Google APIs, based on the official documentation reviewed on March 27, 2026.
+
+Scope:
+- app/store metadata and assets
+- localized and non-localized surfaces
+- public API-editable items only
+
+Out of scope:
+- binaries and track rollout mechanics except where directly tied to metadata
+- in-app purchases and subscriptions
+- account administration
+- analytics and reporting
+
+This document is intentionally conservative:
+- `Confirmed` means the official docs reviewed clearly expose a writable public API path or request body.
+- `Likely` means the reviewed docs strongly imply API support, but the exact writable field list was not fully visible from the sources reviewed.
+- `Not confirmed` means the field exists in product/help docs, but public writable API support was not confirmed from the reviewed sources.
+
+## Apple
+
+### Localizable And Confirmed API-Editable
+
+These are confirmed as part of the App Store Connect API metadata surface.
+
+#### App info localization surface
+
+- `name`
+- `subtitle`
+
+Resource model:
+- `appInfoLocalizations`
+
+Notes:
+- These are shared app-info fields localized per locale.
+
+#### App version localization surface
+
+- `description`
+- `keywords`
+- `marketingUrl`
+- `promotionalText`
+- `supportUrl`
+- `whatsNew`
+
+Resource model:
+- `appStoreVersionLocalizations`
+
+Notes:
+- These are localized per app version and locale.
+- `whatsNew` is specifically version-oriented.
+
+#### Localized visual assets
+
+- screenshots
+- app previews
+
+Resource model:
+- `appScreenshotSets`
+- `appScreenshots`
+- `appPreviewSets`
+- `appPreviews`
+
+Notes:
+- These hang off app store version localizations.
+- Screenshots are clearly part of the localized product-page surface.
+- App previews are API-editable and are attached through preview sets.
+
+### Non-Localized And Confirmed API-Editable
+
+#### App store version surface
+
+- `versionString`
+- `copyright`
+- `releaseType`
+- `earliestReleaseDate`
+
+Resource model:
+- `appStoreVersions`
+
+Notes:
+- These are version-scoped rather than localization-scoped.
+
+#### Build linkage
+
+- attached build for a version
+
+Resource model:
+- `appStoreVersions/{id}/relationships/build`
+
+Notes:
+- This is not a textual metadata field, but it is part of the version configuration surface.
+
+#### App review information
+
+- `contactFirstName`
+- `contactLastName`
+- `contactPhone`
+- `contactEmail`
+- `demoAccountName`
+- `demoAccountPassword`
+- `demoAccountRequired`
+- `notes`
+
+Resource model:
+- `appStoreReviewDetails`
+
+#### Age rating declaration
+
+Confirmed API-addressable fields include:
+- `advertising`
+- `alcoholTobaccoOrDrugUseOrReferences`
+- `contests`
+- `gambling`
+- `gamblingSimulated`
+- `gunsOrOtherWeapons`
+- `healthOrWellnessTopics`
+- `kidsAgeBand`
+- `lootBox`
+- `medicalOrTreatmentInformation`
+- `messagingAndChat`
+- `parentalControls`
+- `profanityOrCrudeHumor`
+- `ageAssurance`
+- `sexualContentGraphicAndNudity`
+- `sexualContentOrNudity`
+- `horrorOrFearThemes`
+- `matureOrSuggestiveThemes`
+- `unrestrictedWebAccess`
+- `userGeneratedContent`
+- `violenceCartoonOrFantasy`
+- `violenceRealisticProlongedGraphicOrSadistic`
+- `violenceRealistic`
+- `ageRatingOverride`
+- `ageRatingOverrideV2`
+- `koreaAgeRatingOverride`
+- `developerAgeRatingInfoUrl`
+
+Resource model:
+- `ageRatingDeclarations`
+
+#### Accessibility declarations
+
+Confirmed API-addressable fields include:
+- `deviceFamily`
+- `state`
+- `supportsAudioDescriptions`
+- `supportsCaptions`
+- `supportsDarkInterface`
+- `supportsDifferentiateWithoutColorAlone`
+- `supportsLargerText`
+- `supportsReducedMotion`
+- `supportsSufficientContrast`
+- `supportsVoiceControl`
+- `supportsVoiceover`
+
+Resource model:
+- `accessibilityDeclarations`
+
+### Likely API-Editable, But Exact Writable Field List Not Fully Confirmed From Reviewed Sources
+
+These appear to be API-addressable from the official docs reviewed, but the exact writable field list was not fully visible in the source snippets reviewed.
+
+- primary category
+- primary subcategories
+- secondary category
+- secondary subcategories
+
+Resource hints:
+- `appInfos`
+- `appCategories`
+
+Reason for caution:
+- Apple’s category docs explicitly say to update categories through the `App Infos` resource, but the exact request schema was not fully visible in the reviewed sources.
+
+### Not Confirmed From Reviewed Sources
+
+These exist in Apple’s product/help documentation, but writable public API support was not confirmed from the reviewed sources.
+
+- `privacyPolicyUrl`
+- `privacyChoicesUrl`
+- custom license agreement text
+- app privacy questionnaire data types
+
+Reason for caution:
+- They may be writable through other public endpoints, but that was not confirmed from the sources reviewed for this document.
+
+## Google Play
+
+### Localizable And Confirmed API-Editable
+
+#### Listing text
+
+- `title`
+- `shortDescription`
+- `fullDescription`
+- `video`
+
+Resource model:
+- `edits.listings`
+
+Notes:
+- The listing resource is locale-specific.
+- `video` is the promotional YouTube URL in the listing resource.
+
+#### Localized graphic assets
+
+- `phoneScreenshots`
+- `sevenInchScreenshots`
+- `tenInchScreenshots`
+- `tvScreenshots`
+- `wearScreenshots`
+- `icon`
+- `featureGraphic`
+- `tvBanner`
+
+Resource model:
+- `edits.images`
+- `AppImageType`
+
+Notes:
+- The images API is language-scoped.
+- This means screenshots and the listed graphic asset types are part of the localized editable API surface.
+
+### Non-Localized And Confirmed API-Editable
+
+- `defaultLanguage`
+- `contactWebsite`
+- `contactEmail`
+- `contactPhone`
+
+Resource model:
+- `edits.details`
+
+Notes:
+- These are app-level details rather than locale-specific listing text.
+
+### Explicitly Not Supported Or Not Fully Editable Through The Publishing API
+
+The official Google docs explicitly note some limits.
+
+Notable examples:
+- legal consents required for publishing are not fillable through the API
+- changing app state from published to unpublished is not supported through this API
+
+## Practical V1 Implications For `storemeta`
+
+### Confirmed API Surface Worth Targeting
+
+Apple localized:
+- `name`
+- `subtitle`
+- `description`
+- `keywords`
+- `marketingUrl`
+- `promotionalText`
+- `supportUrl`
+- `whatsNew`
+- screenshots
+- app previews
+
+Apple non-localized:
+- `versionString`
+- `copyright`
+- app review details
+
+Google localized:
+- `title`
+- `shortDescription`
+- `fullDescription`
+- `video`
+- screenshots
+- `icon`
+- `featureGraphic`
+- `tvBanner`
+
+Google non-localized:
+- `defaultLanguage`
+- `contactWebsite`
+- `contactEmail`
+- `contactPhone`
+
+### Current CLI Implementation Cut
+
+The current `storemeta` CLI implements this subset:
+
+Apple:
+- app-info localization text
+- app-version localization text
+- screenshots
+
+Google:
+- listing text
+- screenshots
+
+Everything beyond that should be implemented only after confirming the exact write semantics in code and tests.
+
+## Sources
+
+Apple:
+- App information help: https://developer.apple.com/help/app-store-connect/reference/app-information/app-information
+- Required, localizable, and editable properties: https://developer.apple.com/help/app-store-connect/reference/app-information/required-localizable-and-editable-properties
+- App Store localizations: https://developer.apple.com/help/app-store-connect/reference/app-information/app-store-localizations
+- App Store version localizations fields: https://developer.apple.com/documentation/appstoreconnectapi/appstoreversionlocalizationcreaterequest/data-data.dictionary/attributes-data.dictionary
+- App Store review detail fields: https://developer.apple.com/documentation/appstoreconnectapi/appstorereviewdetail/attributes-data.dictionary
+- App Store versions fields and related resources: https://developer.apple.com/documentation/appstoreconnectapi/get-v1-apps-_id_-appstoreversions
+- App previews modify endpoint: https://developer.apple.com/documentation/appstoreconnectapi/patch-v1-apppreviews-_id_
+- Build linkage endpoint: https://developer.apple.com/documentation/appstoreconnectapi/patch-v1-appstoreversions-_id_-relationships-build
+- Categories overview: https://developer.apple.com/documentation/appstoreconnectapi/app-categories
+- Accessibility declarations fields: https://developer.apple.com/documentation/appstoreconnectapi/get-v1-apps-_id_-accessibilitydeclarations
+- Age rating modify endpoint: https://developer.apple.com/documentation/appstoreconnectapi/patch-v1-ageratingdeclarations-_id_
+
+Google:
+- Edits overview: https://developers.google.com/android-publisher/edits
+- Listings resource: https://developers.google.com/android-publisher/api-ref/rest/v3/edits.listings
+- Images resource: https://developers.google.com/android-publisher/api-ref/rest/v3/edits.images
+- App image types: https://developers.google.com/android-publisher/api-ref/rest/v3/AppImageType
+- App details resource: https://developers.google.com/android-publisher/api-ref/rest/v3/edits.details

package/docs/AUTH_SETUP.md

@@ -0,0 +1,67 @@
+# Auth Setup
+
+`storemeta` reads credentials from environment variables. Do not put secret values directly in `storemeta.yml`.
+
+## Apple App Store Connect
+
+Create an API key:
+
+1. Open App Store Connect.
+2. Go to Users and Access.
+3. Open Integrations.
+4. Open App Store Connect API.
+5. Create or select an API key with access to the target app.
+6. Copy the Issuer ID.
+7. Copy the Key ID.
+8. Download the `.p8` private key file.
+
+Configure your shell:
+
+```bash
+export STORE_APPLE_ISSUER_ID=00000000-0000-0000-0000-000000000000
+export STORE_APPLE_KEY_ID=XXXXXXXXXX
+export STORE_APPLE_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
+```
+
+Common Apple errors:
+
+- `401 Unauthorized`: issuer id, key id, and `.p8` file do not match, or the key does not have access to the app.
+- Missing credential env var: the environment variable name in `storemeta.yml` is not exported in the current shell.
+- File read failure: `STORE_APPLE_PRIVATE_KEY_PATH` does not point to a readable `.p8` file.
+
+## Google Play
+
+Create a service account:
+
+1. Open Google Cloud Console.
+2. Create or select a project.
+3. Enable the Google Play Developer API.
+4. Create a service account.
+5. Create and download a JSON key for that service account.
+6. Open Google Play Console.
+7. Go to Users and permissions.
+8. Invite the service account email as a user.
+9. Grant access to the target app and the permissions needed for metadata and screenshots.
+
+Configure your shell:
+
+```bash
+export STORE_GOOGLE_SERVICE_ACCOUNT_PATH=/absolute/path/to/google-service-account.json
+```
+
+Common Google errors:
+
+- `401 Unauthorized`: service account JSON is invalid or cannot exchange an OAuth token.
+- `403 Forbidden`: service account is not added to Play Console or lacks permission for the app.
+- `400 Bad Request` for locale: Google Play expects locale codes such as `tr-TR`, not just `tr`.
+
+## Check Credentials
+
+Run:
+
+```bash
+storemeta auth check
+storemeta validate
+```
+
+`auth check` confirms that configured credential environment variables are present. `validate` checks config, metadata files, and screenshot layout.