Metadata-Version: 2.4
Name: himalaya-kit
Version: 0.3.0
Summary: An extension toolkit for reliable multi-step himalaya email automation and agent workflows
Author: himalaya-kit contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/xiaolinstar/himalaya-kit
Project-URL: Repository, https://github.com/xiaolinstar/himalaya-kit
Project-URL: Issues, https://github.com/xiaolinstar/himalaya-kit/issues
Project-URL: Changelog, https://github.com/xiaolinstar/himalaya-kit/releases
Keywords: email,himalaya,cli,imap,smtp,agent
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: markdown
Requires-Dist: markdown-it-py~=4.2; extra == "markdown"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# himalaya-kit

himalaya-kit is a Python toolkit that complements the [himalaya](https://github.com/pimalaya/himalaya) mail CLI for automation and AI-assisted workflows. It combines himalaya primitives into safer multi-step workflows for composing, sending, searching, batch-exporting, and optionally organizing mail.

> **Project status:** Alpha. The core workflows are usable, but command output and public interfaces may still evolve across `0.x` releases.

## Why this project exists

himalaya already provides a solid foundation for mail access and folder management. himalaya-kit is designed to fill the gaps that often appear in scripted or agent-driven workflows by offering a small, reusable layer on top of himalaya rather than replacing it.

## Features

| Command | Purpose |
|------|---------|
| `status` | Inspect config and backend integration without mail authentication |
| `send` | Compose and send a new message |
| `reply` | Reply to an existing message |
| `forward` | Forward a message with optional attachments |
| `search` | Search archived mail and online mail by sender or keyword |
| `export` | Safely batch-export, validate, index, and resume local `.eml` backups |

Optional workflows:

| Command | Purpose |
|------|---------|
| `archive` | Apply the bundled five-level organization preset |
| `yearly-archive` | Run the legacy yearly export-and-delete workflow |

## Installation

```bash
pip install himalaya-kit
```

Or install from source:

```bash
git clone https://github.com/xiaolinstar/himalaya-kit.git
cd himalaya-kit
pip install -e .
```

## Quick start

```bash
# Check how himalaya-kit is connected (does not authenticate to mail servers)
himalaya-kit status

# Send a message
himalaya-kit send -t "张三 <zhangsan@example.com>" -s "测试" -b "你好"

# Send Markdown mail
echo "# 报告" | himalaya-kit send -t user@example.com -s "周报" --markdown

# Reply to an existing message
himalaya-kit reply 12345 -b "收到，谢谢"

# Forward a message
himalaya-kit forward 12345 user@example.com --note "请查收"

# Search mail by sender
himalaya-kit search "Alice"

# Archive mail from the inbox
himalaya-kit archive --days 7

# Preview archive actions without moving mail
himalaya-kit archive --dry-run

# Preview a safe batch export (zero local writes and no server changes)
himalaya-kit export --before 2025-01-01 --dry-run

# Export one full message with native himalaya
himalaya message export --full -d message.eml 12345
```

## himalaya vs himalaya-kit

Use himalaya directly when one native command safely completes the task. Use himalaya-kit when the task needs batching, validation, durable state, recovery, or coordination across multiple himalaya commands.

| Goal | Recommended tool | Why |
|------|------------------|-----|
| Export one message | `himalaya message export` | Native primitive is sufficient |
| Copy or move known message IDs | `himalaya message copy/move` | Native batch operation is sufficient |
| Export a date range | `himalaya-kit export` | Adds pagination, validation, indexing, and recovery |
| Export then remove server copies | `himalaya-kit export --delete-after-export` | Enforces export → verify → save index → delete ordering |
| Apply the five-level inbox model | `himalaya-kit archive` | Optional bundled workflow, not a universal email model |

`archive` copies messages into priority folders and leaves the originals in place. `yearly-archive` is retained as a destructive compatibility workflow: after verified local export and index persistence, it marks server copies as deleted. Always run destructive workflows with `--dry-run` first.

## Safe batch export

```bash
# Strictly before the given date; defaults to INBOX
himalaya-kit export --before 2025-01-01 --dry-run

# Export a calendar year from multiple folders
himalaya-kit export --year 2025 \
  --folder INBOX --folder Sent \
  --output ~/email-archive/work

# Export an open/closed date range using strict boundaries
himalaya-kit export --after 2024-01-01 --before 2025-01-01

# Machine-readable plan for an Agent
himalaya-kit export --year 2025 --dry-run --json

# Destructive option: only delete after verified export and durable index save
himalaya-kit export --before 2025-01-01 --delete-after-export
```

Exports use himalaya's native `envelope list` and `message export` commands. himalaya-kit adds atomic file writes, basic `.eml` validation, collision-resistant names, an atomic `archive-index.json`, and repeat-run recovery. `--dry-run` does not create the output directory or modify server state.

Human-facing runs emit stable line-oriented logs as folders are scanned and messages complete, followed by a summary. `--json` suppresses those text logs and writes one complete JSON result to stdout for Agents and scripts. Dynamic terminal progress bars are intentionally not used.

## Requirements

- Python 3.10+
- The [himalaya](https://github.com/pimalaya/himalaya) CLI installed and configured
- A himalaya config file at `~/.config/himalaya/config.toml`

## Internationalization (i18n)

himalaya-kit supports Chinese (default) and English interfaces. You can switch languages in three ways:

### 1. Command-line argument

```bash
himalaya-kit --lang en send --help
himalaya-kit --lang zh send --help
```

### 2. Environment variable

```bash
export HIMALAYA_KIT_LANG=en
himalaya-kit send --help
```

### 3. Config file

```toml
[himalaya_kit]
lang = "en_US"
```

Supported language codes:
- `zh_CN` or `zh` - Chinese (default)
- `en_US` or `en` - English

## Configuration

himalaya-kit reuses the existing himalaya account configuration and does not require a separate mail setup. A typical configuration looks like this:

```toml
[accounts.work]
default = true
email = "yourname@company.com"
display-name = "Your Name"
# ... SMTP/IMAP settings
```

Optional extensions can be added under the `[himalaya_kit]` section:

```toml
[himalaya_kit]
backup-root = "~/email-archive"

my-email = "yourname@company.com"
priority-contacts = ["boss@company.com"]
system-accounts = ["noreply@company.com"]
internal-domains = ["company.com"]
timezone = "Asia/Shanghai"

notification-keywords = ["notification", "alert", "通知", "提醒"]

priority-folders = [
    "Priority-1-Urgent",
    "Priority-2-Internal",
    "Priority-3-External",
    "Priority-4-CC",
    "Priority-5-Notifications",
]

[himalaya_kit.contacts]
provider = "json"   # none | json | ai-todo
file = "~/.config/himalaya/contacts.json"
```

See [`examples/config.example.toml`](examples/config.example.toml) and [`examples/contacts.example.json`](examples/contacts.example.json) for full examples.

**Contacts**: himalaya has no built-in address book. Use a local JSON file (default provider when configured) or optionally plug in `ai-todo` as an external contact source. Contacts with `"tags": ["priority"]` are merged into high-priority classification alongside `priority-contacts`.

**Backward compatibility**: `leader-emails` is still read and merged into `priority-contacts`.

Environment variables:

| Variable | Description |
|------|------|
| `HIMALAYA_KIT_BACKUP_ROOT` | Override the archive backup directory |

## Python API

himalaya-kit 0.3 introduces a stable, Python-first SDK. The CLI calls the same
client API, while himalaya command execution is isolated behind a replaceable
backend:

```python
from datetime import date

from himalaya_kit import ExportSelection, HimalayaKit, SendRequest

kit = HimalayaKit(account="work")

# Local integration only: no IMAP/SMTP authentication.
print(kit.status().to_dict())

# A dry run builds the complete message without resolving SMTP credentials.
preview = kit.send(
    SendRequest(
        to="reader@example.com",
        subject="Weekly update",
        body="Hello from Python",
    ),
    dry_run=True,
)
print(preview.preview)

# Structured result suitable for scripts and Agents.
result = kit.export(
    ExportSelection(before=date(2025, 1, 1)),
    dry_run=True,
)
print(result.to_dict())
```

The default `HimalayaCliBackend` keeps compatibility with himalaya today. A
native Python IMAP/SMTP backend is planned for 0.4 without changing the
high-level client interface.

## Development

Run the test suite with:

```bash
pytest -q
```

## License

Apache License 2.0
