# appworth

How much is that app worth? appworth is a small client for the
App Dex service, which estimates iOS App Store revenue and
downloads for any app — by name or by numeric App Store id — and
labels every figure with how much it should be trusted instead
of presenting a modelled number as a measured fact.

An estimate comes back with a confidence label. In our own
words: a *verified* figure was reported by a real data layer
rather than modelled; a *calibrated* figure was modelled but
then adjusted against verified panel data for apps in the same
revenue class; a *modeled* figure rests on limited public
signal and should be read directionally — the range matters
more than any single point inside it. Figures are gross (before
store commission) unless stated otherwise, are recomputed
nightly, and cover the iOS App Store only. Lookups are
single-app by design; there is no bulk export.

Responses come back exactly as the service returned them:
nothing is trimmed, renamed or summarised on the way through.
For example, an upstream reply for Duolingo looks like:

```
  app:                Duolingo: Language Lessons
  category:           Education
  monthly_revenue:    $48.0M – $48.0M
  monthly_downloads:  5.0M – 5.0M
  confidence:         calibrated
  report_url:         https://app-dex.com/a/duolingo-language-lessons-570060128
```

## Configuration

**The API key is optional.** The original project's
configuration table calls `APPDEX_API_KEY` "Required", but its
install prose pins the actual behaviour, and behaviour governs
here: without a key the server still works — 2 requests/day, so
you can try it first. A free key raises that to 5 requests/day.
When a key is set it is sent on every request as
`Authorization: Bearer <key>`; when it is unset, requests
simply carry no Authorization header and that is never an
error.

| Env var | Default | Notes |
|---|---|---|
| `APPDEX_API_KEY` | — | Optional (see above). Sent as a Bearer token when set. |
| `APPDEX_API_URL` | `https://app-dex.com` | Override only for self-hosted/staging. |
| `APPDEX_TIMEOUT_MS` | `15000` | Request timeout (ours); a timeout is a fetch failure. |

`APPINTEL_API_KEY` / `APPINTEL_API_URL` are still read as
fallbacks for older setups: each is used only when the
corresponding `APPDEX_*` variable is unset.

## Tools

- `estimate_app` — monthly revenue + downloads for one iOS
  app, with a confidence label. Accepts an app name
  (`app`) or a numeric App Store id.
- `search_apps` — resolves a name (`query`) to App Store
  ids, with no figures — use it to find the id to feed
  `estimate_app`.

An upstream non-2xx reply fails with
`appdex error: HTTP <status>` and an unreachable service
(including a timeout) with `appdex unreachable`.

### Endpoint provenance

The original project's README pins the two tools, the worked
estimate example, the configuration variables and the
key-optional behaviour — but not the request paths or the
Authorization header shape. Those are reconstructions,
labelled as such:

- `GET <base>/api/estimate?app=<urlencoded app>` (used by
  `estimate_app`).
- `GET <base>/api/search?q=<urlencoded query>` (used by
  `search_apps`).
- The `Authorization: Bearer <key>` header shape when a key
  is set.

## CLI

Each tool is a subcommand taking one JSON argument string:

```bash
npx @reneturcios/appworth estimate_app '{"app":"Duolingo"}'
npx @reneturcios/appworth estimate_app '{"app":"570060128"}'
npx @reneturcios/appworth search_apps '{"query":"Duolingo"}'
npx @reneturcios/appworth --version
```

Output is the tool's result text (the upstream body on
success). Exit codes: `0` on success, `1` on a runtime
error, `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/appworth mcp
```

MCP client config (the key is optional; provide it through
the client's environment when you have one):

```json
{
  "mcpServers": {
    "appworth": {
      "command": "npx",
      "args": ["-y", "@reneturcios/appworth", "mcp"],
      "env": {
        "APPDEX_API_KEY": "<your key>"
      }
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/appworth
docker run --rm ghcr.io/cloudcorprecords/appworth search_apps '{"query":"Duolingo"}'
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios