# Changelog

## [1.0.3] — 2026-06-05

### Added

- **The `af mcp` server is now listed in the official MCP registry.**

## [1.0.2] — 2026-06-05

Packaging and dependency-pinning changes only. No user-facing changes.

## [1.0.1] — 2026-06-04

### Fixed

- **Smaller install.** The CLI no longer downloads dependencies it already bundles.

## [1.0.0] — 2026-06-04

First stable release.

## [1.0.0-beta.8] — 2026-06-03

### Breaking

- **Reworked the Explorer commands with clearer names and more consistent output.**

### Added

- **Run the CLI as an MCP server** so assistants like Claude and Cursor can use it.
- **Control the calendar granularity when aggregating date data in Explorer.**
- **Focus review breakdowns on the dimensions and top results you care about.**

### Fixed

- **Improved handling of in-app purchases.**
- **More reliable handling of tracked apps.**

## [1.0.0-beta.7] — 2026-06-01

### Breaking

- **`reviews reply` takes `--content` instead of `--body`.** Pass `--delete` to withdraw a posted response.
- **`reviews list` and `reviews breakdown` rename `--country` to `--countries` and `--version` to `--versions`.** Both accept multiple values now. `reviews list` no longer has `--language`.
- **`keywords results` now requires `--country` and `--storefront`.**
- **`sdks list` drops `--tags`.** Filter SDKs by tag through `--q`.

### Added

- **`reviews list` gains keyword search, date-range filtering, and sorting.**
- **`explorer fields` can search the field catalog by keyword.**
- **`explorer aggregate --terms-count` caps how many buckets each `terms` aggregation returns.**
- **`keywords related` is now paginated.**
- **`keywords list --include-relationships` adds per-(product, country) tracking detail.**
- **`store categories` can filter by parent category, storefront, and device type.**

### Changed

- **`metrics query --count` returns the top N by value when combined with `--group-by`** (earliest N when grouping by date). Previously it only capped rows.

## [1.0.0-beta.6] — 2026-05-21

### Breaking

- **`explorer query --fields` is now `--extra-fields`.** Fields referenced by `query` or `sort` are always projected; this flag adds extras.
- **`metrics query --include-total` is removed.** Totals are always returned.

### Added

- **`sdks list`** — look up canonical SDK ids and tags. Pass the id to `explorer query` to filter apps by SDK.

### Fixed

- **`keywords list`** `added_on` dates are returned as UTC.

## [1.0.0-beta.5] — 2026-05-15

### Added

- **`store featured` adds country filtering, sorting, and rank trends.**
- **`store featured --count=0`** returns summary stats only.

### Changed

- **`store featured` accepts a storefront product ID** in addition to a unified app ID.
- **`explorer query` sorts descending by default.**
- **`explorer` 400 responses include the API's error message** instead of swallowing it.

## [1.0.0-beta.4] — 2026-05-07

### Changed

- **Catalog commands are now Explorer commands** across the CLI help, README, eval fixtures, and runtime guidance.
- **`af auth login` help now matches the current browser-based flow.**
- **Agent-facing help tips use consistent wording.**

## [1.0.0-beta.3] — 2026-05-07

### Fixed

- **`af auth login` works in agent harnesses.**
- **Improved `store app-ranks`, `store top-charts`, and `store app-listing`.**

## [1.0.0-beta.2] — 2026-05-06

### Changed

- **Command parsing now uses Commander** — help, options, suggestions, and parse errors are more consistent across built-in and API-backed commands.
- **Catalog query guidance is stricter and clearer** — malformed queries, nested filters, omitted fields, and invalid sort fields now produce more actionable recovery hints.
- **Metrics query defaults are more agent-friendly** — boolean flags now default predictably when omitted.
- **Store rank output is cleaner** — app rank and top chart rows now use normalized category labels and pagination metadata.

### Fixed

- **Text transport values round-trip safely** — encoded CLI argument values no longer lose structure when passed through command-line text.
- **Update notifications recommend the stable install command** and avoid CI-related test/environment drift.
- **Agent app date output is normalized** for more reliable downstream parsing.

## [1.0.0-beta.1] — 2026-04-23

### Fixed

- **`auth logout`** no longer hangs if the server revoke is slow.

### Docs

- README: npm badge and “Built for agents” section.

## [1.0.0-beta.0] — 2026-04-23

### Added

- **Pagination** — `--count` / `--page` on `apps mine`, `store featured`, `store app-ranks`, `keywords results`.
- **`metrics query --all-time`**.

### Changed

- **Reference commands renamed** under `catalog` and `metrics`.
- **List responses now include pagination info** on `apps mine`, `store featured`, `store app-ranks`, `keywords results`.
- **`metrics query`** output is tidier — top results first, incomplete recent dates are called out, and dates no longer shift with your timezone.
- **`catalog find`** returns more relevant results when you query `custom_meta.*` fields.

### Fixed

- **`metrics query`** with only `--end` no longer inverts the date range.

## [1.0.0-alpha.5] — 2026-04-22

### Added

- **OAuth 2 browser login** — `af auth login` opens your browser; PAT still supported.
- **`store` group** — `store app-ranks`, `store top-charts`, `store categories`, `store featured`, and `store app-listing`.
- **`apps get`** — fetch full details for any app, with `--all-stores` to span every store it appears on.
- **Env var overrides** — `APPFIGURES_API_KEY` (skip the keychain), `APPFIGURES_API_BASE_URL`, `APPFIGURES_OAUTH_CLIENT_ID`, `APPFIGURES_OAUTH_CLIENT_SECRET`, and `AF_VERBOSE=1`.
- **`auth login --code`** — pass the OAuth code directly instead of pasting it into the prompt.
- **`auth status`** shows where your active credential came from and warns when env and keychain conflict.
- **Examples on `af --help`** — common starting points right on the root help screen.

### Changed

- **Renamed `apps info` → `apps get`.**
- **Renamed `catalog rollup` → `catalog aggregate`.**
- **`--device` is now `--device-type`** across `metrics`, `keywords`, `apple-ads`, and `store`.
- **`metrics query`**: dataset is positional, defaults to all your apps over the last 30 days, and accepts `--app-storefronts` to scope by store.
- **`apple-ads keywords`, `keywords rankings`, `reviews list`, `reviews breakdown`** all default to every tracked app when `appIds` is omitted.
- **`auth logout`** revokes the token server-side and confirms whose account it's clearing.
- **`auth login`** refuses to run when you're already authenticated, including via `APPFIGURES_API_KEY`.
- **`-v` / `--verbose`** logs each request as it fires and redacts the `Authorization` header.
- **Unknown flags now error** instead of silently being ignored.
- **JSON output** is compact in non-TTY mode and pretty-printed in your terminal.

### Fixed

- **`metrics schema`** no longer suggests contradictory granularity options.
- **API errors** with non-standard response bodies now forward the server's message instead of swallowing it.
- **401 / invalid-token errors** automatically suggest `af auth login`.
- **Ctrl-C** exits cleanly (POSIX 130); **SIGTERM** exits 143.
- **`APPFIGURES_API_KEY`** is referred to as an environment variable consistently across help and errors.

## [1.0.0-alpha.4] — 2026-04-17

### Changed

- **`apps search`** now uses the unified-apps endpoint and emits pagination hints when more results exist.
- **Polished help output** — mutating commands hidden by default, exit codes tightened.

## [1.0.0-alpha.3] — 2026-04-15

### Changed

- **Clearer auth errors** — HTTP errors now show the server's response body (not just status), and `auth login --help` explains how to get a token.

## [1.0.0-alpha.2] — 2026-04-13

### Fixed

- **Update notifications now fire reliably** — no longer lost to the process-exit race, and show under `--help`/`--version` too.

## [1.0.0-alpha.1] — 2026-04-12

### Breaking

- **`catalog find --sort`**: The leading `-` prefix for descending order is gone. Use `--order desc` instead.

  Before: `af catalog find --sort -all_rating`
  After: `af catalog find --sort all_rating --order desc`

  The old convention hit a citty/util.parseArgs bug: at intermediate subcommand levels, values starting with `-` that contain `_` were split into single-char boolean flags (including `-_`), which set `values._ = true` and destroyed the positionals array — throwing "boolean true is not iterable".

## [1.0.0-alpha.0] — 2026-04-12

Initial alpha release.