Metadata-Version: 2.4
Name: mapsnatch
Version: 0.1.0
Summary: Bulk-export all your MindMeister maps without a Business plan
License: AGPL-3.0-or-later
Project-URL: Homepage, https://mapsnatch.com
Project-URL: Documentation, https://gavinc.github.io/mapsnatch/
Project-URL: Repository, https://github.com/gavinc/mapsnatch
Project-URL: Changelog, https://github.com/gavinc/mapsnatch/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/gavinc/mapsnatch/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Requires-Dist: python-dotenv>=1.0
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-mock>=3; extra == "dev"
Requires-Dist: responses>=0.25; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Dynamic: license-file

# MapSnatch

[![CI](https://github.com/gavinc/mapsnatch/actions/workflows/ci.yml/badge.svg)](https://github.com/gavinc/mapsnatch/actions/workflows/ci.yml)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](./LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-purple)](https://gavinc.github.io/mapsnatch/)

> MindMeister lets you export maps one at a time unless you pay for a Business plan.
> This tool gives you bulk export using their own public API — available on all plan types including free.

**Hosted version (no CLI):** [mapsnatch.com](https://mapsnatch.com) — pay once, export in the browser.

| | |
|---|---|
| [Contributing](./CONTRIBUTING.md) | [Security](./SECURITY.md) |
| [Support](./SUPPORT.md) | [Docs](https://gavinc.github.io/mapsnatch/) |
| [Code of Conduct](./CODE_OF_CONDUCT.md) | [Report a bug](https://github.com/gavinc/mapsnatch/issues/new?template=bug_report.yml) |

If this CLI saves you time, tips are welcome (not required):

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/D5G31ZW8MC)

## Install

**PyPI:** not published yet — there is no `pip install mapsnatch` on PyPI. First release needs [PYPI_SETUP.md](./PYPI_SETUP.md) (trusted publisher + `v0.1.0` tag).

**From GitHub (works today):**

```bash
git clone https://github.com/gavinc/mapsnatch
cd mapsnatch
pip install -e .
echo "MINDMEISTER_API_TOKEN=your_personal_access_token_here" > .env
mapsnatch
```

Create a personal access token at [mindmeister.com/api](https://www.mindmeister.com/api)

## Supported formats

| Flag | Format | Notes |
|------|--------|-------|
| `mm` | FreeMind | **Recommended** — best portability, opens in FreeMind and Freeplane |
| `pdf` | PDF | Good for sharing and archiving |
| `mind` | MindMeister native | For re-import back into MindMeister |
| `xmind` | XMind | For use in the XMind app |
| `rtf` | Rich Text Format | Text-based outline |

**Not supported:** `png` and `docx` return empty responses from the API — these appear to require a Business plan subscription.

## Usage

```
mapsnatch [OPTIONS]

Options:
  --format, -f    Export format: mm, pdf, mind, xmind, rtf  (default: mm)
  --output, -o    Output directory                           (default: ./exports)
  --token, -t     Personal access token (or MINDMEISTER_API_TOKEN in env / .env)
  --dry-run       List maps without downloading
  --list-formats  Show supported formats and exit
```

### Examples

```bash
# Export all maps as FreeMind format (default)
mapsnatch

# Export as PDF into a custom directory
mapsnatch --format pdf --output ~/mindmaps

# List what maps would be exported without downloading
mapsnatch --dry-run

# Pass personal access token on the command line
mapsnatch --token YOUR_PERSONAL_ACCESS_TOKEN
```

## How it works

MindMeister provides a public REST API (v1 + v2) that allows any authenticated user to list and export their maps. This tool:

1. Fetches your full map list from `GET /services/rest/oauth2?method=mm.maps.getList`
2. Downloads each map via `GET /api/v2/maps/{id}.{format}`
3. Extracts the file from its zip container (for `mm`, `mind`, `xmind` formats)
4. Saves it with a sanitised filename into your output directory

Auth uses your personal access token as a Bearer credential — no OAuth dance required.

## Opening exported files

- **FreeMind (.mm)** — Open with [FreeMind](https://freemind.sourceforge.io/) or [Freeplane](https://www.freeplane.org/) (recommended — free, cross-platform)
- **XMind (.xmind)** — Open with [XMind](https://www.xmind.net/)
- **PDF** — Any PDF viewer
- **RTF** — Any word processor

## Setup

### Get your personal access token

1. Log in to MindMeister
2. Open [mindmeister.com/api](https://www.mindmeister.com/api) and create a **personal access token**
3. Copy the token (not the same as MindMeister's separate "API keys" product)

### Configure

Either:

```bash
# Option A: .env file (recommended)
echo "MINDMEISTER_API_TOKEN=your_token_here" > .env

# Option B: environment variable
export MINDMEISTER_API_TOKEN=your_token_here

# Option C: command line flag
mapsnatch --token your_token_here
```

## Contributing

See **[CONTRIBUTING.md](./CONTRIBUTING.md)**. Pull requests welcome — run `python -m pytest -v` before opening a PR.

## License

[AGPL-3.0-or-later](./LICENSE)
