# ToolMint Dependency Migration

> npm/PyPI upgrade delta: curated playbooks + changelog/release heuristics. Not a full Actor/LLM upgrade agent.

- Status: Live
- Price: $0.05 / call (x402 exact, USDC on Base eip155:8453, payTo 0xfbF7413bcB3a604936775C96FDbe0b0C9c9E37F5)
- Base URL: https://toolmint-dep-migration.toolmint.workers.dev
- OpenAPI: https://toolmint.toolmint.workers.dev/tools/dep-migration/openapi.json

## Routes

- `GET /delta` $0.05
- `GET /delta/:eco/:name` $0.05

## What question it answers

"I am on `react` 17.0.2 and want 18.2.0. What do I have to change?"

## When to use it

- The package is in the playbook list (check `/playbooks` first, it is free), or it keeps a CHANGELOG or GitHub releases.
- You want a starting checklist before reading the upgrade guide.

## When not to use it

- As a replacement for the upgrade guide. The notes field says so. Missing items are possible.
- For packages with no public GitHub repo, no changelog, or not in the playbook list: you may get an almost empty answer, and you still pay.
- For many packages at once. There is one package per call (no manifest route).
- It does not diff type definitions or run code.

## Example

```bash
curl -i "https://toolmint-dep-migration.toolmint.workers.dev/delta?eco=npm&name=react&from=17.0.2&to=18.2.0"
# 402 + PAYMENT-REQUIRED. Pay with an x402 client, repeat with PAYMENT-SIGNATURE.
```

Response after payment (trimmed to one change; values illustrative, field names and the playbook text from the code):

```json
{
  "tool": "dep-migration",
  "version": "0.2.0",
  "ecosystem": "npm",
  "package": "react",
  "from": "17.0.2",
  "to": "18.2.0",
  "summary": "react 17.0.2 -> 18.2.0: ... Top signal: ReactDOM.render is replaced by createRoot (react-dom/client).",
  "changeCount": 12,
  "changes": [
    {
      "kind": "breaking",
      "summary": "[playbook] ReactDOM.render is replaced by createRoot (react-dom/client).",
      "detail": "Must-fix for any 17->18 app entrypoint.",
      "symbol": "ReactDOM.render",
      "replacement": "createRoot(...).render(...)",
      "sourceUrl": "https://react.dev/blog/2022/03/08/react-18-upgrade-guide",
      "confidence": "high"
    }
  ],
  "sources": [
    "https://registry.npmjs.org/react",
    "https://github.com/facebook/react",
    "https://api.github.com/repos/facebook/react/releases?per_page=30"
  ],
  "warnings": ["GitHub API rate limited (unauthenticated) - results may be incomplete"],
  "versionsCompared": ["17.0.2", "18.2.0"],
  "heuristic": true,
  "notes": "Heuristic public-changelog + curated playbooks. Not a substitute for reading upgrade guides. ...",
  "cached": false
}
```

`changes` holds at most 80 items. `kind` is one of `breaking`, `deprecation`, `removed`, `renamed`, `added`, `config`, `behavior`, `security`, `other`. Read `warnings` every time.

## Data sources and licence

registry.npmjs.org, pypi.org, api.github.com and raw.githubusercontent.com. The text comes from each project's own public changelog and release notes; licences differ by project. The tool returns short extracted lines with links, not whole documents. Playbook entries cite public upgrade-guide pages. Check each source's terms if you redistribute.

## Freshness and limits

- Cached 6 hours in memory per version pair on one server instance. `cached` tells you if you got a cache hit. There is no `fetchedAt`.
- GitHub is called without a token (60 calls per hour per IP, shared). Release notes are often missing; expect the warning above. The CHANGELOG file is fetched from raw.githubusercontent.com in a separate call, so it may still arrive when release notes do not.
- Only the latest 30 GitHub releases are read.
- Playbooks were written by hand and many entries for less-common packages are 1 to 3 lines.
- If it runs out, paid calls fail and are not charged.