Metadata-Version: 2.4
Name: imexp
Version: 0.1.0
Summary: Interactive CLI wrapper for imessage-exporter with contact name resolution and post-processing
Project-URL: Homepage, https://github.com/code-switched/imexp
Project-URL: Repository, https://github.com/code-switched/imexp
Project-URL: Issues, https://github.com/code-switched/imexp/issues
Author-email: Code <switched.code@gmail.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: backup,export,imessage,ios,macos,messages,sms
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: dateparser==1.2.2
Provides-Extra: dev
Requires-Dist: pylint==4.0.4; extra == 'dev'
Requires-Dist: pytest-cov==7.0.0; extra == 'dev'
Requires-Dist: pytest==9.0.2; extra == 'dev'
Description-Content-Type: text/markdown

# imexp

An interactive CLI wrapper for [imessage-exporter](https://github.com/ReagentX/imessage-exporter) that adds contact name resolution and post-processing to your iMessage exports.

## Features

- **Interactive wizard** — run `imexp` with no arguments for a guided export experience
- **Natural language dates** — use phrases like "last 6 months" or "2 weeks ago"
- **Contact resolution** — automatically maps phone numbers and emails to names from your macOS or iOS Contacts database
- **iOS backup support** — auto-detects backups and lets you pick by device name/date
- **Post-processing** — renames exported files and replaces raw handles with contact names
- **Export history** — tracks your last export date to avoid duplicates

## Requirements

- Python 3.12+
- macOS or Windows for the official wheels

macOS local Address Book lookups require macOS. iOS backup exports work on both macOS and Windows.

## Installation

Install from PyPI:

```bash
pip install imexp
```

Official wheels bundle the matching `imessage-exporter` binary for:

- macOS Apple Silicon
- macOS Intel
- Windows x86_64

Source installs do not bundle the exporter binary. For editable or source installs, either:

- install `imessage-exporter` separately and keep it on `PATH`
- point `IMEXP_EXPORTER_PATH` at a local binary

Example source install:

```bash
git clone https://github.com/code-switched/imexp.git
cd imexp
pip install -e .
```

## Usage

### Interactive mode

Simply run with no arguments for the guided wizard:

```bash
imexp
```

You'll be prompted for:
- Platform (macOS or iOS backup)
- Date range (natural language supported)
- Export location

### Command-line mode

```bash
imexp export --start-date "2024-01-01" --end-date "2024-06-01" --format txt
```

### Relabel existing exports

Re-run contact resolution on a previous export:

```bash
imexp relabel --export-path ./data/messages/sms/2024-01-15-10-30-00
```

### Common options

| Option | Description |
|--------|-------------|
| `--start-date` | Start date (natural language or YYYY-MM-DD) |
| `--end-date` | End date (defaults to now) |
| `--format` | Output format: `txt`, `html` (default: `txt`) |
| `--platform` | `macOS` or `iOS` |
| `--db-path` | Path to iOS backup or custom chat.db |
| `--export-path` | Custom output directory |
| `--non-interactive` | Disable prompts for scripted use |
| `-v, --verbose` | Enable debug logging |

## How it works

1. Runs `imessage-exporter` with your specified options
2. Loads contacts from macOS Contacts.app or iOS backup
3. Post-processes exported files:
   - Renames files from phone numbers to contact names
   - Replaces raw handles in file contents with names
4. Saves unknown number → name mappings to `contacts.json` for future exports
5. Tracks export history in `history.json` for incremental exports

## Configuration files

By default, files are stored in `./data/messages/sms/`:

- `contacts.json` — custom name overrides for unknown numbers
- `history.json` — tracks last export date

## License

`imexp` is distributed under `GPL-3.0-or-later`.

The official wheels bundle the upstream `imessage-exporter` binary, which is also licensed under `GPL-3.0`.
