# MDclient

Markdown 筆記服務的 Python 客戶端函式庫。

支援 CodiMD、HedgeDoc、HackMD 等服務。

## 特色

- ✅ 簡單好用的 Python API
- ✅ 支援多種 Markdown 筆記服務
- ✅ 自動會話管理（Cookie）
- ✅ 支援 .env 設定檔
- ✅ 完整的筆記操作（建立、讀取、更新、刪除、匯出）

## 安裝

```bash
pip install mdclient
```

如果需要 .env 支援：

```bash
pip install "mdclient[env]"
```

## 快速開始

```python
from mdclient import MDClient, MDAuth

# 登入
auth = MDAuth()
auth.login("your@email.com", "password")

# 使用客戶端
client = MDClient()
notes = client.list_notes()

for note in notes:
    print(f"{note['text']} - {note['id']}")
```

## 主要功能

### 列出筆記

```python
client = MDClient()
notes = client.list_notes()
```

### 建立筆記

```python
result = client.create_note("標題", "# 內容")
```

### 取得筆記

```python
note = client.get_note(note_id)
print(note['content'])
```

### 匯出筆記

```python
content = client.export_note(note_id, format="md")
```

### 搜尋筆記

```python
results = client.search_notes("關鍵字")
```

### 刪除筆記

```python
client.delete_note(note_id)
```

## 使用 .env 檔案

建立 `.env` 檔案：

```env
MDCLIENT_URL=https://codimd.lotimmy.com
MDCLIENT_EMAIL=your@email.com
MDCLIENT_PASSWORD=your_password
```

在程式碼中使用：

```python
import os
from dotenv import load_dotenv
from mdclient import MDAuth, MDClient

load_dotenv()

auth = MDAuth(base_url=os.getenv('MDCLIENT_URL'))
auth.login(
    os.getenv('MDCLIENT_EMAIL'),
    os.getenv('MDCLIENT_PASSWORD')
)

client = MDClient(base_url=os.getenv('MDCLIENT_URL'))
notes = client.list_notes()
```

## 自訂伺服器

```python
from mdclient import MDAuth, MDClient

auth = MDAuth(base_url="https://your-server.com")
auth.login("user@example.com", "password")

client = MDClient(base_url="https://your-server.com")
notes = client.list_notes()
```

## CLI 工具（可選）

專案包含一個可選的 CLI 工具：

```bash
# 登入
python3 mdclient_cli.py login

# 列出筆記
python3 mdclient_cli.py list

# 建立筆記
python3 mdclient_cli.py create "標題"

# 取得筆記
python3 mdclient_cli.py get <note_id>

# 匯出筆記
python3 mdclient_cli.py export <note_id> -o note.md
```

## API 參考

詳細的 API 文件請查看 [API.md](API.md)。

## 範例

- [example.py](example.py) - 基本使用範例
- [auth_example.py](auth_example.py) - 認證功能範例

## 專案結構

```
mdclient/
├── mdclient/           # 核心 Python 函式庫
│   ├── __init__.py    # 匯出 MDClient, MDAuth
│   ├── auth.py        # 認證功能
│   └── client.py      # API 客戶端
├── mdclient_cli.py    # 可選的 CLI 工具
├── example.py         # Python 使用範例
├── auth_example.py    # 認證範例
├── .env.example       # 環境變數範例
├── API.md             # API 文件
├── QUICKSTART.md      # 快速開始
└── README.md          # 本檔案
```

## 環境變數

- `MDCLIENT_URL` - 伺服器位址
- `MDCLIENT_EMAIL` - 登入信箱
- `MDCLIENT_PASSWORD` - 登入密碼
- `MDCLIENT_COOKIE_FILE` - Cookie 檔案路徑

## 開發

```bash
# 安裝開發依賴
pip install -e ".[dev]"

# 執行測試
pytest

# 程式碼格式化
black mdclient/

# 型別檢查
mypy mdclient/
```

## 授權

MIT