Metadata-Version: 2.5
Name: asc-appstore-tools
Version: 0.1.28
Summary: CLI tool for bulk-uploading App Store Connect metadata
License: MIT
Keywords: app-store,app-store-connect,cli,metadata,screenshots
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: fastapi>=0.110.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pyjwt[crypto]>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: requests>=2.31.0
Requires-Dist: toml>=0.10.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn>=0.29.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: cryptography>=41.0.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: playwright>=1.43.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# App Store Connect Upload Tool

[简体中文](README.zh-CN.md) | [Tutorials](docs/tutorials/README.md)

`asc` is a Python 3.9+ CLI for routine App Store Connect release work. Use it from the terminal or its local Web UI to manage localized store content, in-app purchases, Xcode builds, and releases across multiple apps.

## What You Can Do

- Upload localized metadata, keywords, store URLs, and screenshots
- Create or update in-app purchases and auto-renewable subscriptions from JSON
- Upload missing IAP and subscription review screenshots
- Update What's New text, with optional LLM-assisted translation
- Build Xcode projects, export `.ipa` files, and upload builds to App Store Connect for TestFlight or App Store distribution
- Manage multiple App Profiles with project-local defaults
- Run common workflows from a local Web UI with persistent task history and Webhook notifications
- Protect state-changing operations with machine, network, and credential Guard checks

## Requirements

- Python 3.9 or later
- An App Store Connect API key with the **App Manager** role or higher
- The key's Issuer ID, Key ID, `.p8` private key, and the app's numeric Apple ID
- macOS with Xcode command line tools for `build`, `deploy`, and `release`

Metadata, screenshot, IAP, and Web UI workflows can run on Linux and Windows. Apple allows each `.p8` private key to be downloaded only once, so store it securely.

## Quick Start

### 1. Install `asc`

Preferred: install the published package from PyPI.

```bash
python -m pip install asc-appstore-tools
```

On macOS / Linux, the repository installer also defaults to PyPI (GitHub is a fallback, or use `--ref` for a branch):

```bash
curl -fL --retry 5 --connect-timeout 20 \
  -o /tmp/asc-install.sh \
  https://raw.githubusercontent.com/yinghuiwang/AppStoreTools/main/install.sh
bash /tmp/asc-install.sh
```

Alternatively, install the published package or the latest source:

```bash
python -m pip install asc-appstore-tools
# or
python -m pip install git+https://github.com/yinghuiwang/AppStoreTools.git
```

### 2. Configure a project

Run the guided setup from your Xcode project. It checks the environment and helps create or import an App Profile:

```bash
cd /path/to/MyXcodeProject
asc install
```

For manual setup, use `asc init` to scaffold `AppStore/` data or `asc app add myapp` to create a profile. Profiles and copied private keys are stored outside the project under `~/.config/asc/`.

### 3. Check and preview

Verify credentials and preview the default metadata and screenshot upload before changing App Store Connect:

```bash
asc check
asc upload --dry-run
```

Use `asc --app myapp <command>` to select a profile explicitly, or set one once with `asc app default myapp`.

## Common Workflows

### Metadata and screenshots

```bash
# An imported asc init profile points to AppStore/data/appstore_info.csv
asc metadata --dry-run

# The same profile points to AppStore/data/screenshots/
asc screenshots --dry-run
```

See [Metadata & Screenshots](docs/tutorials/02-metadata-and-screenshots.md) for the CSV columns, locale folders, supported display types, and upload behavior.

### IAP and subscriptions

```bash
asc iap --iap-file AppStore/data/iap_packages.json --dry-run
asc iap --iap-file AppStore/data/iap_packages.json --update-existing

# Find products missing a review image and upload configured defaults
asc iap-screenshots --iap-file AppStore/data/iap_packages.json --dry-run
```

Start from the current template generated by `asc init` at `AppStore/data/iap_packages.json`. A repository checkout also contains sample data at `data/iap_packages.json`. See [IAP & Subscriptions](docs/tutorials/03-iap-and-subscriptions.md) for the schema and update rules.

### What's New and store URLs

```bash
asc whats-new --text "Bug fixes and performance improvements." --dry-run

# Translate one source text to the app's other locales through an OpenAI-compatible API
asc whats-new --text "Bug fixes and performance improvements." \
  --translate --source-locale en-US --dry-run

asc set-support-url --text "https://example.com/support" --dry-run
asc set-marketing-url --text "https://example.com" --dry-run
asc set-privacy-policy-url --text "https://example.com/privacy" --dry-run
```

LLM settings are managed from the Web UI or `~/.config/asc/llm.toml`; `OPENAI_API_KEY` is also supported. File-based release notes and locale selection are covered in [What's New & Store URLs](docs/tutorials/04-whats-new-and-urls.md).

### Build and release

```bash
asc build --dry-run
asc --app myapp deploy --ipa build/export/MyApp.ipa --dry-run
asc --app myapp release --destination testflight --dry-run
```

`asc build` and `asc release` can discover the Xcode project, scheme, bundle ID, signing certificate, and provisioning profile, then cache resolved values in `.asc/config.toml`. See [Build & Deploy](docs/tutorials/05-build-and-deploy.md) for signing and App Store release options.

### Local Web UI

```bash
asc web
asc web status
asc web stop
```

Production `asc web` serves the Vue 3 SPA at `http://127.0.0.1:8080` by default. It exposes the main upload and release workflows, keeps task history in `~/.config/asc/tasks.db`, and can send completion notifications to Feishu, WeCom, or DingTalk from its settings page.

Local development uses two processes (do not add `asc web --vite`):

```bash
asc web --foreground
cd frontend && npm run dev
```

Vite on `:5173` proxies `/api` and `/static` to the FastAPI app. A release build requires `npm ci && npm run build` first so `src/asc/web/static/spa/` is included in the package.

Run `asc --help` for all commands and `asc <command> --help` for every option.

## Configuration

Values are resolved in this order, from highest to lowest priority:

1. CLI options such as `--app`, `--csv`, or `--screenshots`
2. Project-local `.asc/config.toml`
3. Global App Profile
4. Environment variables

| Location | Purpose |
|---|---|
| `.asc/config.toml` | Project defaults, including the default app and build settings |
| `.asc/error.log` | Detailed errors for commands run from the current project |
| `~/.config/asc/profiles/` | Reusable App Profiles and App Store Connect credentials |
| `~/.config/asc/keys/` | Private keys copied during profile setup |
| `~/.config/asc/llm.toml` | OpenAI-compatible translation providers |
| `~/.config/asc/webhook.toml` | Web task notification settings |
| `~/.config/asc/tasks.db` | Persistent Web UI task history and logs |

For multiple apps, profile import, default selection, and CI environment variables, see [Multi-App Profiles](docs/tutorials/06-multi-app-profiles.md) and [CI/CD Automation](docs/tutorials/08-ci-cd.md).

## Tutorials

| # | Guide | Covers |
|---|---|---|
| 01 | [Install & Project Init](docs/tutorials/01-install-and-init.md) | Installation, API keys, project templates, and the first profile |
| 02 | [Metadata & Screenshots](docs/tutorials/02-metadata-and-screenshots.md) | CSV content, screenshot folders, validation, and uploads |
| 03 | [IAP & Subscriptions](docs/tutorials/03-iap-and-subscriptions.md) | JSON schema, one-time purchases, and subscriptions |
| 04 | [What's New & Store URLs](docs/tutorials/04-whats-new-and-urls.md) | Release notes and support, marketing, and privacy URLs |
| 05 | [Build & Deploy](docs/tutorials/05-build-and-deploy.md) | Archives, signing, IPA export, and uploads for TestFlight or App Store distribution |
| 06 | [Multi-App Profiles](docs/tutorials/06-multi-app-profiles.md) | Profile management and project defaults |
| 07 | [Guard Security](docs/tutorials/07-guard-security.md) | Machine, network, and credential binding |
| 08 | [CI/CD Automation](docs/tutorials/08-ci-cd.md) | Non-interactive setup and GitHub Actions |

## Development

```bash
git clone https://github.com/yinghuiwang/AppStoreTools.git
cd AppStoreTools
python -m pip install -e ".[dev]"
pytest
python -m build
```

Browser E2E (`tests/test_web_agent_e2e.py`) needs Playwright Chromium and is skipped if the browser is missing:

```bash
python -m playwright install chromium
pytest tests/test_web_agent_e2e.py
```

Source code lives in `src/asc/`; tests mirror the feature areas under `tests/`. Publishing is handled by `.github/workflows/publish.yml` when a `v*.*.*` tag is pushed.

After changing the Vue UI, rebuild production assets with `cd frontend && npm ci && npm run build` (requires Node). Fonts stay under `src/asc/web/static/`.

## Security

- Never commit `.p8` keys, `.env` files, local profiles, or generated credentials.
- Use `--dry-run` before metadata, screenshot, IAP, URL, build, or release changes.
- Keep Guard enabled on developer machines; use `asc guard status` to inspect bindings.
- Bind the Web UI to `127.0.0.1` unless access from another machine is intentional.
- Keep API keys and Webhook secrets in environment variables or the configuration files under `~/.config/asc/`, not in upload data.

## Troubleshooting

### `asc: command not found`

Open a new terminal or reload the shell configuration:

```bash
source ~/.zshrc
# or
source ~/.bash_profile
```

### `asc check` reports no editable version

Create an App Store version in App Store Connect first. The version must be in an editable state such as `PREPARE_FOR_SUBMISSION`.

### A Guard check blocks an operation

Run `asc guard status` to see the active binding and conflict. Follow [Guard Security](docs/tutorials/07-guard-security.md) before unbinding or disabling protection.

### A command fails without enough detail

Re-run it with the global debug option, for example `asc --debug upload --dry-run`, and inspect `.asc/error.log`.
