npm package: @souseha/media-sdk
Description: Cloudflare Media API Client SDK
Author: wangch
Latest version: 1.0.1

# @wangch/media-sdk

Cloudflare Media API 的 TypeScript SDK。

## 安裝

```bash
npm install @wangch/media-sdk
# 或
pnpm add @wangch/media-sdk
```

## 使用方式

### 初始化

```typescript
import { MediaClient } from '@wangch/media-sdk';

const client = new MediaClient({
  baseUrl: 'https://media-api.wangch.dev',
  apiKey: 'key_bd2wiki_xxxxxxxx',
});
```

### Images 操作

```typescript
// 上傳圖片
const image = await client.images.upload(file, {
  table: 'characters',
  record_id: 'luna',
  purpose: 'avatar',
  custom_id: 'characters/luna/avatar', // 選填
});

// 列出圖片
const images = await client.images.list({
  table: 'characters',
  per_page: 50,
});

// 取得單張圖片資訊
const info = await client.images.get('image-id');

// 刪除圖片
await client.images.delete('image-id');
```

### R2 操作

```typescript
// 上傳檔案
const object = await client.r2.upload('my-bucket', file, {
  key: 'path/to/file.json',
  table: 'backups',
  record_id: 'daily-2024-01-15',
});

// 列出檔案
const objects = await client.r2.list('my-bucket', {
  prefix: 'backups/',
  limit: 100,
});

// 取得檔案資訊
const objInfo = await client.r2.get('my-bucket', 'path/to/file.json');

// 取得簽名 URL
const { url, expires_at } = await client.r2.getSignedUrl('my-bucket', 'path/to/file.json', {
  expires_in: 3600,
});

// 下載檔案
const response = await client.r2.download('my-bucket', 'path/to/file.json');
const blob = await response.blob();

// 刪除檔案
await client.r2.delete('my-bucket', 'path/to/file.json');
```

### 錯誤處理

```typescript
import { MediaApiError } from '@wangch/media-sdk';

try {
  await client.images.get('non-existent-id');
} catch (error) {
  if (error instanceof MediaApiError) {
    console.log(error.code);    // 'NOT_FOUND'
    console.log(error.message); // '圖片不存在'
    console.log(error.status);  // 404
  }
}
```

## API 文件

### MediaClient

#### 建構選項

| 選項 | 類型 | 必填 | 說明 |
|------|------|------|------|
| baseUrl | string | 是 | API 基礎 URL |
| apiKey | string | 是 | API Key |
| timeout | number | 否 | 請求超時時間（毫秒，預設 30000） |

### ImagesModule

#### upload(file, options)

上傳圖片。

**參數：**
- `file`: File | Blob - 圖片檔案
- `options.table`: string - 資料表名稱（必填）
- `options.record_id`: string - 關聯記錄 ID（選填）
- `options.purpose`: string - 用途（選填）
- `options.custom_id`: string - 自訂 ID（選填）
- `options.extra_meta`: Record<string, string> - 額外 metadata（選填）

#### list(filter?)

列出圖片。

**參數：**
- `filter.table`: string - 過濾資料表
- `filter.record_id`: string - 過濾記錄 ID
- `filter.purpose`: string - 過濾用途
- `filter.page`: number - 頁碼（預設 1）
- `filter.per_page`: number - 每頁數量（預設 20，最大 100）

#### get(id)

取得單張圖片資訊。

#### delete(id)

刪除圖片。

### R2Module

#### upload(bucket, file, options)

上傳檔案。

**參數：**
- `bucket`: string - Bucket 名稱
- `file`: File | Blob - 檔案
- `options.key`: string - 檔案路徑/名稱（必填）
- `options.table`: string - 資料表名稱（必填）
- `options.record_id`: string - 關聯記錄 ID（選填）
- `options.purpose`: string - 用途（選填）
- `options.content_type`: string - Content-Type（選填）
- `options.extra_meta`: Record<string, string> - 額外 metadata（選填）

#### list(bucket, filter?)

列出檔案。

#### get(bucket, key)

取得檔案資訊。

#### getSignedUrl(bucket, key, options?)

取得簽名 URL。

#### download(bucket, key)

下載檔案。

#### delete(bucket, key)

刪除檔案。

## License

MIT