Add multi-storefront keyword support

[mogens9]

Summary

• add a shared storefront registry and validate all configured App Store country codes instead of hardcoding US
• scope Apple Search Ads popularity requests to the selected storefront country, e.g. storefronts: ["DK"]
• use country-specific App Store search URLs and non-US iTunes lookup fallback for ranking/difficulty enrichment
• add MCP country input support and update docs/help text

Validation

• npm test -- --watchman=false
• npm run typecheck
• npm run build
• live smoke: node cli/dist/cli.js keywords "height ai" --stdout --country DK --app-id 6764027433 --no-associate

[netlify]

✅ Deploy Preview for aso-cli canceled.

Name	Link
🔨 Latest commit	c7d0aa1
🔍 Latest deploy log	https://app.netlify.com/projects/aso-cli/deploys/6a4a1b6530ab65000869a666

[semihcihan]

Thanks for putting this together. The country propagation through the CLI, MCP, and persistence layers looks well structured.

I found a few areas that I think would be worth addressing before merging:

• The dashboard is still effectively US-only. The UI, startup refresh, owned-app hydration, app search, top-app/history requests, and App Store links use DEFAULT_ASO_COUNTRY. It may be best either to thread a selected country through those flows or describe this PR specifically as CLI/MCP multi-storefront support and document the dashboard limitation.

• Dashboard routes generally normalize country values but do not validate them at the HTTP boundary. Adding the same supported-country validation used by CLI/MCP would allow unsupported values to return a consistent 400 INVALID_REQUEST response.

• The MZSearch fallback storefront header appears incorrect for non-US countries. getAppleStoreFrontHeader currently generates ${storefrontId}-1,29 for every country, but the value after the hyphen is a language variation rather than a constant.

  I tested the endpoint directly and observed:

  • 143441-1,29 (US) → HTTP 200
  • 143458-1,29 (DK, current implementation) → HTTP 400
  • 143458-11,29 (DK/Danish) → HTTP 200
  • 143458,29 (DK with the language variation omitted) → HTTP 200
  • 143443-1,29 (DE, current implementation) → HTTP 400
  • 143443-4,29 (DE/German) → HTTP 200

  The App Store search-page path can hide this because MZSearch is only used as fallback. We should look up the default App Store language for each supported country/storefront and use that code in the storefront registry or MZSearch header, rather than hardcoding a single variation. Representative US/DK/DE request tests would help prevent regressions.

  I also compared dslang=da, dslang=DK-DA, dslang=en-US, and no dslang cookie with a valid DK header; they produced identical successful responses. The storefront header seems to be the relevant issue.

• Non-US app lookup currently bypasses the App Store product-page request entirely:

  if (country !== "US") {
    return fetchItunesLookupAppDocs(...);
  }

  This means US and non-US enrichment use different primary metadata sources, even though fetchAppDocById now constructs country-specific URLs such as https://apps.apple.com/dk/app/id.... Those country-specific pages returned HTTP 200 in the US, DK, and DE cases I tested.

  It may be more consistent to try fetchAppDocById for every supported country, then use iTunes Lookup only for unresolved apps or missing fields, reusing the existing mergeFallbackDoc behavior. Tests covering non-US primary success, primary failure, and partial-field merging would make that source order explicit.

• Several system documents still describe US-only behavior, including the MCP section, endpoint matrix, SQLite country note, and parts of the keyword/runtime flow documentation. It would also be useful to document that newly supported non-US storefronts currently use only their default locale for difficulty matching.

• Some additional feature-level coverage would be helpful: a CLI command test showing a non-US country reaches the pipeline and country-scoped association writes, the MZSearch fallback cases above, and dashboard country tests if dashboard support remains part of this PR's scope.

Thanks again for the contribution. The main challenge is identifying the correct API variations for each storefront and ensuring that our parameters match what the App Store actually uses there. This PR establishes an important foundation for multi-storefront support, but I think adding each new storefront will require additional testing to verify its parameters and behavior. To reduce the risk, perhaps this PR could establish the general country-support foundation while officially enabling only one or two additional storefronts that have been tested end to end.