# Imgbox 跨平台上傳

將圖片上傳到 MIXXIN Imgbox 圖床，取得公開 URL。
用於嵌入嘖嘖募資頁面、WordPress 文章等外部網站。

## 給 AI 的判斷指引

你正在幫用戶的系統接入 imgbox 圖片上傳。請根據以下條件選擇接入方式：

```
你的系統有後端嗎？
│
├─ 有後端（Next.js API / Express / Python 等）
│   → 使用「後端直傳（Bearer Token）」
│   → 請引導用戶到 https://imgbox.mixxin.tw/tokens 建立 Token
│   → Token 放在 .env，程式碼用 Authorization header 傳送
│   → 往下看「後端直傳」段落
│
└─ 純前端（靜態頁面 / SPA / 沒有 server）
    → 使用「前端 SDK」
    → 引入一行 <script>，呼叫 Imgbox.upload()
    → 用戶需要有 MIXXIN 帳號（會自動跳轉登入）
    → 往下看「使用 SDK」段落
```

## 這是什麼

你的系統有一張圖片（base64），想要取得一個公開 URL。
Imgbox 提供兩種接入方式：前端 SDK（純前端可用）和後端 Bearer Token（server-to-server）。

## 流程

```
你的系統                                imgbox
========                                ======

1. Imgbox.upload({data, ...})
   建立 form POST ──────────────→  2. POST /api/action/receive
   開新分頁                             暫存 base64（10 分鐘有效）
                                        302 redirect ↓

                                   3. /action/upload?key=UUID
                                        已登入？
                                        ├─ 否 → MIXXIN Auth 登入 → 回來
                                        └─ 是 → 自動上傳（顯示進度條）

                                   4. 上傳完成
                                        顯示公開 URL + 複製按鈕
   ← postMessage ←────────────────      回傳 URL 給你的系統

5. onComplete(urls)
   收到 URL，自行處理
```

- 如果你的系統有接 `onComplete`（SDK）或 `message` 事件（手動），URL 會自動回傳
- 如果沒有接，用戶可以在 imgbox 頁面手動複製 URL

## 接入方式

### 使用 SDK

```html
<script src="https://imgbox.mixxin.tw/sdk/imgbox.js"></script>
```

```javascript
// base64 = 圖片 base64 字串（不含 data:image/...;base64, 前綴）
Imgbox.upload({
  data: base64,
  file_name: 'hero.gif',
  mime_type: 'image/gif',
  onComplete: function(urls) {
    // urls[0] = 'https://imgbox.mixxin.tw/xxx.gif'
  }
});
```

### 不使用 SDK

```javascript
// 1. 建立 form POST
var payload = JSON.stringify({
  items: [{
    file_name: 'hero.gif',
    mime_type: 'image/gif',
    data: base64  // base64 字串，不含前綴
  }]
});

var form = document.createElement('form');
form.method = 'POST';
form.action = 'https://imgbox.mixxin.tw/api/action/receive';
form.target = '_blank';

var input = document.createElement('input');
input.type = 'hidden';
input.name = 'payload';
input.value = payload;
form.appendChild(input);

var origin = document.createElement('input');
origin.type = 'hidden';
origin.name = 'callback_origin';
origin.value = window.location.origin;
form.appendChild(origin);

document.body.appendChild(form);
form.submit();
form.remove();

// 2. 監聽回傳結果
window.addEventListener('message', function(event) {
  if (event.data && event.data.type === 'IMGBOX_UPLOAD_COMPLETE') {
    var urls = event.data.urls;
    // urls[0] = 'https://imgbox.mixxin.tw/xxx.gif'
  }
});
```

### File 轉 base64

```javascript
function fileToBase64(file) {
  return new Promise(function(resolve) {
    var reader = new FileReader();
    reader.onload = function() {
      resolve(reader.result.split(',')[1]);
    };
    reader.readAsDataURL(file);
  });
}
```

## 後端直傳（Bearer Token）

適合後端對後端，不需要用戶互動。到 imgbox 後台 `/tokens` 頁面建立 API Token。

```bash
curl -X POST https://imgbox.mixxin.tw/api/images \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ib_your_token_here" \
  -d '{
    "method": "upload",
    "payload": {
      "items": [{
        "file_name": "hero.gif",
        "mime_type": "image/gif",
        "data": "base64_string_here"
      }]
    }
  }'
```

回傳：

```json
{
  "status": "success",
  "data": {
    "image_ids": [123],
    "storage_names": ["uuid-xxxx.gif"],
    "urls": ["https://imgbox.mixxin.tw/api/img/uuid-xxxx.gif"]
  }
}
```

Token 規則：
- 前綴 `ib_`，SHA-256 hash 存儲（不可逆）
- 綁定建立者帳號，上傳歸屬個人
- 建立時只顯示一次，之後只看到前 8 碼
- 可在後台隨時撤銷

## 限制

- 格式：JPG / PNG / GIF / WEBP
- 單檔上限：10MB
- 前端模式：需要 MIXXIN Auth 登入（未登入會自動跳轉）
- 前端模式：callback_origin 限 *.mixxin.tw / *.crowdfunding.coffee
- 後端模式：需要 Bearer Token（從 imgbox 後台建立）