apple-store-connect-ops

name	apple-store-connect-ops
description	Use this skill when the user asks to check App Store Connect operations, for example "帮我看看这周的下载情况和运营情况", "本周收入如何", "有没有退款", "列出我的 App", "看一下简介/图标/截图/关键词等商品页信息", "曝光量/转化率/留存怎么样", "有什么优化建议", or when they need first-run guidance to configure App Store Connect API keys, p8 files, issuer IDs, vendor numbers, Sales and Trends, or Analytics report exports.

Apple Store Connect Ops

Use this skill when the user wants App Store Connect operational data, App Store listing metadata, App Analytics exports, Sales and Trends income/refund checks, release history, daily briefings, or weekly review reports.

Safety

• Treat .p8 private keys, JWTs, issuer IDs, and raw report exports as sensitive.
• Never commit .env, .p8, data/, reports/, or downloaded CSV files.
• Prefer read-only scripts first. Only create Analytics report requests when the user explicitly asks or passes --create / --create-if-missing.
• Mention that Apple Analytics may be delayed, privacy-thresholded, sampled/noised, or limited to users who share analytics.
• Store only the private key path in .env; never copy the .p8 private key content into the skill.

Configuration

Scripts automatically load local .env into environment variables; explicit CLI flags override saved values. First-run setup:

node scripts/setup-config.mjs --validate

Ask the user for these values when they have not configured the skill yet:

• Key ID: App Store Connect > Users and Access > Integrations > App Store Connect API.
• Issuer ID: same API key page for Team API keys.
• p8 path: downloaded once when the API key is created; store the absolute file path.
• Vendor Number: App Store Connect > Business > Payments and Financial Reports; needed for Sales and Trends revenue/refund reports.
• API access: use a Team API key with Admin when creating Analytics report requests; Sales/Finance access is needed for Sales and Trends.

Non-interactive setup:

node scripts/setup-config.mjs \
  --key-id "<key-id>" \
  --issuer-id "<issuer-id-for-team-key>" \
  --private-key-path "/absolute/path/to/AuthKey_<key-id>.p8" \
  --vendor-number "<vendor-number>" \
  --validate

For an Individual API Key, omit ASC_ISSUER_ID and set ASC_INDIVIDUAL_KEY=1.

Intent Routing

• "看看这周下载/运营情况": run ops-summary.mjs --app-id ID; for all-app inventory first run list-apps.mjs --live-only.
• "本周收入如何": run sales-downloads.mjs and report Developer Proceeds by currency.
• "有没有退款": run sales-downloads.mjs and report refund units/rows/proceeds; say "未看到退款行" when all refund counts are zero.
• "曝光量/转化率/留存" or "Sources/来源": run analytics-dashboard.mjs --create-if-missing; it scans all active Analytics report requests unless --access-type or --request-id is passed. If reports show no_instances, explain that report requests exist but Apple has not generated downloadable instances yet.
• "评论/差评/用户反馈": run reviews-report.mjs --app-id ID --format markdown.
• "简介/图标/封面图/截图/关键词/商品页信息": run app-metadata.mjs --app-id ID --format markdown.
• "有什么优化建议": run recommendations-report.mjs --app-id ID; recommendations should explain the data signal, the action, and the next metric to verify.
• "列出所有 App / 上架 App": run list-apps.mjs --with-versions or --live-only.
• If credentials are missing, guide setup first instead of attempting ad-hoc code.

Common Workflows

1. Save and validate local configuration:

node scripts/setup-config.mjs --validate

2. Validate credentials:

node scripts/check-config.mjs --limit 5

3. List apps:

node scripts/list-apps.mjs --format table
node scripts/list-apps.mjs --with-versions --format json
node scripts/list-apps.mjs --live-only --format table

4. List version history and release counts:

node scripts/list-versions.mjs --all --format table
node scripts/list-versions.mjs --app-id 1234567890 --include-all --format json

5. Read App Store listing metadata, icons, screenshots, and localized copy:

node scripts/app-metadata.mjs --app-id 1234567890 --format markdown
node scripts/app-metadata.mjs --app-id 1234567890 --locale zh-Hans --format json
node scripts/app-metadata.mjs --all --skip-assets --format table

6. Inspect or create Analytics report requests:

node scripts/analytics-requests.mjs --app-id 1234567890
node scripts/analytics-requests.mjs --app-id 1234567890 --create

7. Download a specific Analytics report instance:

node scripts/download-analytics.mjs --app-id 1234567890 --report-name "App Store Downloads" --granularity DAILY

If no report name/category is passed, the downloader lists available reports and exits instead of downloading everything.

8. Check dashboard-like App Analytics report readiness for live apps:

node scripts/analytics-dashboard.mjs --create-if-missing
node scripts/analytics-dashboard.mjs --access-type ONE_TIME_SNAPSHOT --download --max-instances 7
node scripts/analytics-dashboard.mjs --request-id 00000000-0000-0000-0000-000000000000 --download

This checks downloads, acquisition/discovery, acquisition sources, installs/deletions, sessions, and Apple's current retention-candidate export.

9. Monitor Analytics instances until Apple generates downloadable reports:

node scripts/analytics-monitor.mjs --app-id 1234567890 --attempts 1
node scripts/analytics-monitor.mjs --app-id 1234567890 --attempts 24 --interval-seconds 3600

10. Summarize customer reviews:

node scripts/reviews-report.mjs --app-id 1234567890 --format markdown
node scripts/reviews-report.mjs --all --format table

11. Generate a combined operations summary and optimization advice:

node scripts/ops-summary.mjs --app-id 1234567890
node scripts/recommendations-report.mjs --app-id 1234567890

12. Generate local summaries from downloaded CSV or CSV.GZ files:

node scripts/summarize-daily.mjs --input-dir data/raw/analytics --date 2026-06-04
node scripts/summarize-weekly.mjs --input-dir data/raw/analytics --start-date 2026-05-29 --end-date 2026-06-04

13. List live apps and calculate last-week downloads when reports are available:

node scripts/weekly-downloads.mjs --create-if-missing

14. Use Sales and Trends for downloads, income, and refunds. This reports App Units, redownloads, total downloads, updates, paid units, developer proceeds, and refund rows from the daily Summary Sales report:

node scripts/sales-downloads.mjs
node scripts/sales-downloads.mjs --vendor-number 12345678

Script Map

• scripts/asc-client.mjs: shared JWT, request, pagination, and App Store Connect helpers.
• scripts/setup-config.mjs: first-run .env writer and optional credential validation.
• scripts/check-config.mjs: minimal credential and API reachability check.
• scripts/list-apps.mjs: app inventory, optionally with latest version and release count.
• scripts/list-versions.mjs: App Store version timeline and published count.
• scripts/app-metadata.mjs: App Store listing metadata, localized copy, app icon, screenshots, and previews.
• scripts/analytics-requests.mjs: read or create Analytics report requests.
• scripts/download-analytics.mjs: list reports, list instances, fetch segment URLs, download CSV.GZ.
• scripts/analytics-dashboard.mjs: fixed dashboard-style Analytics report readiness and optional download workflow.
• scripts/analytics-monitor.mjs: poll dashboard-critical Analytics reports until instances are ready.
• scripts/reviews-report.mjs: customer review summary, low-score review triage, and recent feedback.
• scripts/ops-summary.mjs: combined app, sales, analytics readiness, review, signal, and recommendation summary.
• scripts/recommendations-report.mjs: prioritized optimization recommendations based on the combined summary.
• scripts/weekly-downloads.mjs: live app inventory plus last-week App Store Downloads aggregation.
• scripts/sales-downloads.mjs: Sales and Trends daily summary aggregation by app; uses ASC_VENDOR_NUMBER or --vendor-number.
• scripts/report-utils.mjs: local CSV/CSV.GZ parsing and generic metric summarization.
• scripts/summarize-daily.mjs: Markdown daily briefing from local report exports.
• scripts/summarize-weekly.mjs: Markdown weekly briefing from local report exports.

References

• Load references/apple-api-map.md when endpoint behavior or permissions matter.
• Load references/metrics-map.md when interpreting metrics, dimensions, or summary caveats.