mdclient/API.md

# MDclient API 文件

## MDAuth

認證類，用於登入和管理會話。

### 建構函式

```python
MDAuth(base_url="https://codimd.lotimmy.com", cookie_file="key.conf")
```

**參數：**
- `base_url` (str): 伺服器位址
- `cookie_file` (str): Cookie 儲存檔案路徑

### 方法

#### login()

登入並儲存 Cookie。

```python
success = auth.login(email, password)
```

**參數：**
- `email` (str): 登入信箱
- `password` (str): 登入密碼

**回傳：**
- `bool`: 是否登入成功

#### test_cookie()

測試儲存的 Cookie 是否有效。

```python
is_valid = auth.test_cookie()
```

**回傳：**
- `bool`: Cookie 是否有效

#### load_cookie()

從檔案載入 Cookie。

```python
cookies = auth.load_cookie()
```

**回傳：**
- `dict` | `None`: Cookie 字典，檔案不存在時返回 None

---

## MDClient

客戶端類，提供所有筆記操作的 API。

### 建構函式

```python
MDClient(base_url="https://codimd.lotimmy.com", cookie_file="key.conf", email=None, password=None)
```

**參數：**
- `base_url` (str): 伺服器位址
- `cookie_file` (str): Cookie 檔案路徑
- `email` (str): 登入信箱（可選）
- `password` (str): 登入密碼（可選）

### 方法

#### list_notes()

列出所有筆記。

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

**回傳：**
- `list` | `None`: 筆記列表，失敗時返回 None

**筆記物件結構：**
```python
{
    "id": "note_id",
    "text": "筆記標題",
    "time": 1234567890,
    "tags": ["tag1", "tag2"],
    "pinned": False
}
```

#### get_note()

取得筆記內容。

```python
note = client.get_note(note_id)
```

**參數：**
- `note_id` (str): 筆記 ID

**回傳：**
- `dict` | `None`: 筆記內容，失敗時返回 None

**筆記內容結構：**
```python
{
    "id": "note_id",
    "title": "筆記標題",
    "content": "Markdown 內容",
    "lastChangeAt": "2024-01-01T00:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z"
}
```

#### create_note()

建立新筆記。

```python
result = client.create_note(title, content="")
```

**參數：**
- `title` (str): 筆記標題
- `content` (str): Markdown 內容

**回傳：**
- `dict` | `None`: 建立結果，失敗時返回 None

**回傳結構：**
```python
{
    "id": "new_note_id",
    "url": "https://server.com/new_note_id"
}
```

#### delete_note()

刪除筆記。

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

**參數：**
- `note_id` (str): 筆記 ID

**回傳：**
- `bool`: 是否刪除成功

#### export_note()

匯出筆記。

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

**參數：**
- `note_id` (str): 筆記 ID
- `format` (str): 匯出格式（md, pdf, html, slides）

**回傳：**
- `str` | `None`: 匯出的內容，失敗時返回 None

#### search_notes()

搜尋筆記。

```python
results = client.search_notes(query)
```

**參數：**
- `query` (str): 搜尋關鍵字

**回傳：**
- `list` | `None`: 符合的筆記列表

---

## 使用範例

### 完整工作流程

```python
from mdclient import MDAuth, MDClient

# 1. 登入
auth = MDAuth()
auth.login("user@example.com", "password")

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

# 3. 列出筆記
notes = client.list_notes()

# 4. 建立筆記
result = client.create_note("新筆記", "# 內容")

# 5. 取得筆記
note = client.get_note(result['id'])

# 6. 匯出筆記
content = client.export_note(result['id'])

# 7. 刪除筆記
client.delete_note(result['id'])
```

### 錯誤處理

```python
from mdclient import MDClient

client = MDClient()

# 檢查回傳值
notes = client.list_notes()
if notes is None:
    print("取得筆記失敗")
else:
    for note in notes:
        print(note['text'])

# 檢查操作結果
result = client.create_note("標題", "內容")
if result:
    print(f"建立成功: {result['id']}")
else:
    print("建立失敗")
```

### 自訂伺服器

```python
from mdclient import MDAuth, MDClient

# 連接到不同的伺服器
auth = MDAuth(base_url="https://demo.hedgedoc.org")
auth.login("user@example.com", "password")

client = MDClient(base_url="https://demo.hedgedoc.org")
notes = client.list_notes()
```