# Smart Folder

{% hint style="danger" %}
**この機能はまだリリースされていません**：この API には Eagle 4.0 Build 22 以降が必要です。リリース日程については Eagle 公式サイトをご確認ください。
{% endhint %}

## エンドポイント一覧

| メソッド | エンドポイント                        | 説明                       |
| ---- | ------------------------------ | ------------------------ |
| GET  | `/api/v2/smartFolder/get`      | スマートフォルダを一覧表示            |
| POST | `/api/v2/smartFolder/get`      | スマートフォルダを一覧表示（リクエストボディ）  |
| POST | `/api/v2/smartFolder/create`   | スマートフォルダを作成              |
| POST | `/api/v2/smartFolder/update`   | スマートフォルダを更新              |
| POST | `/api/v2/smartFolder/remove`   | スマートフォルダを削除              |
| GET  | `/api/v2/smartFolder/getItems` | 条件に一致するアイテムを取得           |
| POST | `/api/v2/smartFolder/getItems` | 条件に一致するアイテムを取得（リクエストボディ） |
| GET  | `/api/v2/smartFolder/getRules` | 利用可能なルールスキーマを取得          |

***

## GET /api/v2/smartFolder/get <a href="#list" id="list"></a>

すべてのスマートフォルダを一覧表示、または ID でフィルタリングします。

### クエリパラメータ

* `id` string（任意）— ID で単一のスマートフォルダを返却
* `ids` string（任意）— カンマ区切りのスマートフォルダ ID

### レスポンス

```json
{
    "status": "success",
    "data": [
        {
            "id": "LRK3AQGN7VCB1",
            "name": "大きな画像",
            "conditions": [
                {
                    "rules": [
                        { "property": "width", "method": ">", "value": [1920] }
                    ],
                    "match": "AND",
                    "boolean": "TRUE"
                }
            ],
            "description": "",
            "icon": "",
            "iconColor": "blue",
            "children": [],
            "modificationTime": 1700000000000,
            "imageCount": 42
        }
    ]
}
```

### 例

```javascript
// すべてのスマートフォルダを一覧表示
await fetch("http://localhost:41595/api/v2/smartFolder/get").then(r => r.json());

// ID でスマートフォルダを取得
await fetch("http://localhost:41595/api/v2/smartFolder/get?id=LRK3AQGN7VCB1").then(r => r.json());
```

***

## POST /api/v2/smartFolder/get <a href="#list-post" id="list-post"></a>

GET と同じですが、JSON ボディでフィルタパラメータを受け付けます。

### リクエストボディ

* `id` string（任意）— スマートフォルダ ID
* `ids` string\[]（任意）— スマートフォルダ ID の配列

### 例

```javascript
// 複数の ID でスマートフォルダを取得
await fetch("http://localhost:41595/api/v2/smartFolder/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ids: ["SMART_FOLDER_ID_1", "SMART_FOLDER_ID_2"]
    })
}).then(r => r.json());
```

***

## POST /api/v2/smartFolder/create <a href="#create" id="create"></a>

新しいスマートフォルダを作成します。

### リクエストボディ

* `name` string（必須）— スマートフォルダ名
* `conditions` Object\[]（必須）— フィルタ条件（下記の [conditions フォーマット](#conditions)を参照）
* `description` string（任意）— 説明
* `icon` string（任意）— アイコン
* `iconColor` string（任意）— アイコンの色。使用可能な値：`red`、`orange`、`yellow`、`green`、`aqua`、`blue`、`purple`、`pink`
* `parent` string（任意）— 親スマートフォルダ ID。省略するとルートレベルに作成されます。

### レスポンス

新しく作成されたスマートフォルダオブジェクトを返却します。

```json
{
    "status": "success",
    "data": {
        "id": "NEW_SMART_FOLDER_ID",
        "name": "大きな画像",
        "conditions": [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [1920] }
                ],
                "match": "AND"
            }
        ],
        "description": "",
        "icon": "",
        "iconColor": "",
        "children": [],
        "modificationTime": 1700000000000,
        "imageCount": 150
    }
}
```

### 例

```javascript
// 幅が 1920 より大きい PNG 画像用のスマートフォルダを作成
await fetch("http://localhost:41595/api/v2/smartFolder/create", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        name: "大きな PNG",
        conditions: [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [1920] },
                    { "property": "type", "method": "equal", "value": "png" }
                ],
                "match": "AND"
            }
        ],
        iconColor: "blue"
    })
}).then(r => r.json());
```

***

## POST /api/v2/smartFolder/update <a href="#update" id="update"></a>

既存のスマートフォルダのメタデータを更新します。含まれているフィールドのみが変更されます。

### リクエストボディ

* `id` string（必須）— 更新するスマートフォルダ ID

**変更可能なフィールド：**

* `name` string（任意）— 新しい名前
* `conditions` Object\[]（任意）— 新しいフィルタ条件
* `description` string（任意）— 新しい説明
* `icon` string（任意）— 新しいアイコン
* `iconColor` string（任意）— 新しいアイコンの色

### レスポンス

更新されたスマートフォルダオブジェクトを返却します。

### 例

```javascript
// 名前とアイコンの色を更新
await fetch("http://localhost:41595/api/v2/smartFolder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        name: "超大型画像",
        iconColor: "green"
    })
}).then(r => r.json());

// フィルタ条件を更新
await fetch("http://localhost:41595/api/v2/smartFolder/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "LRK3AQGN7VCB1",
        conditions: [
            {
                "rules": [
                    { "property": "width", "method": ">", "value": [3840] }
                ],
                "match": "AND"
            }
        ]
    })
}).then(r => r.json());
```

***

## POST /api/v2/smartFolder/remove <a href="#remove" id="remove"></a>

スマートフォルダを削除します。すべての子スマートフォルダも同時に削除されます。

### リクエストボディ

* `id` string（必須）— 削除するスマートフォルダ ID

### レスポンス

```json
{
    "status": "success",
    "data": true
}
```

### 例

```javascript
await fetch("http://localhost:41595/api/v2/smartFolder/remove", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ id: "LRK3AQGN7VCB1" })
}).then(r => r.json());
```

***

## GET /api/v2/smartFolder/getItems <a href="#get-items" id="get-items"></a>

スマートフォルダのフィルタ条件に一致するアイテムを取得します。

### クエリパラメータ

* `smartFolderId` string（必須）— スマートフォルダ ID
* `orderBy` string（任意）— ソートフィールド
* `fields` string（任意）— カンマ区切りの返却フィールドリスト

### レスポンス

```json
{
    "status": "success",
    "data": [
        {
            "id": "M3QSGJNQTC2DG",
            "name": "wallpaper",
            "ext": "png",
            "width": 3840,
            "height": 2160,
            "tags": ["wallpaper"],
            "folders": []
        }
    ]
}
```

### 例

```javascript
// スマートフォルダ内のすべてのアイテムを取得
await fetch("http://localhost:41595/api/v2/smartFolder/getItems?smartFolderId=LRK3AQGN7VCB1")
    .then(r => r.json());

// 特定のフィールドのみを返却
await fetch("http://localhost:41595/api/v2/smartFolder/getItems?smartFolderId=LRK3AQGN7VCB1&fields=id,name,tags")
    .then(r => r.json());
```

***

## POST /api/v2/smartFolder/getItems <a href="#get-items-post" id="get-items-post"></a>

GET と同じですが、JSON ボディでパラメータを受け付けます。

### リクエストボディ

* `smartFolderId` string（必須）— スマートフォルダ ID
* `orderBy` string（任意）— ソートフィールド
* `fields` string\[]（任意）— 返却するフィールド

### 例

```javascript
await fetch("http://localhost:41595/api/v2/smartFolder/getItems", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        smartFolderId: "LRK3AQGN7VCB1",
        fields: ["id", "name", "ext", "width", "height"]
    })
}).then(r => r.json());
```

***

## GET /api/v2/smartFolder/getRules <a href="#get-rules" id="get-rules"></a>

利用可能なフィルタルールスキーマを取得します。各プロパティでサポートされている methods、valueType、options などの情報を返却し、呼び出し側が有効な conditions を動的に構築できるようにします。

### レスポンス

```json
{
    "status": "success",
    "data": {
        "name": {
            "methods": ["contain", "uncontain", "equal", "startWith", "endWith", "empty", "not-empty", "regex"],
            "valueType": "string"
        },
        "width": {
            "methods": ["=", ">=", "<=", ">", "<", "between"],
            "valueType": "number"
        },
        "type": {
            "methods": ["equal", "unequal"],
            "valueType": "string",
            "options": ["jpg", "png", "gif", "svg", "bmp", "webp", "..."]
        }
    }
}
```

### 例

```javascript
// conditions を動的に構築するために利用可能なルールを取得
await fetch("http://localhost:41595/api/v2/smartFolder/getRules").then(r => r.json());
```

{% hint style="info" %}
**ヒント：** まず `getRules` を呼び出して利用可能なプロパティとメソッドをすべて取得し、返却されたスキーマに基づいて `conditions` を構築してから `create` または `update` に渡してください。無効なフィルタ条件を回避できます。
{% endhint %}

***

## Conditions フォーマット <a href="#conditions" id="conditions"></a>

スマートフォルダの `conditions` は条件グループの配列で、各グループに複数のルールが含まれます：

```json
[
    {
        "rules": [
            { "property": "name", "method": "contain", "value": "cat" },
            { "property": "width", "method": ">", "value": [1920] }
        ],
        "match": "AND",
        "boolean": "TRUE"
    }
]
```

### 条件グループのプロパティ

| プロパティ     | 型         | 説明                                                 |
| --------- | --------- | -------------------------------------------------- |
| `rules`   | Object\[] | ルールの配列                                             |
| `match`   | string    | ルール間の論理演算。`"AND"`：すべて一致；`"OR"`：いずれか一致              |
| `boolean` | string    | グループの包含/除外ロジック。`"TRUE"`（包含、デフォルト）または `"FALSE"`（除外） |

### ルールのプロパティ

| プロパティ      | 型      | 説明                                 |
| ---------- | ------ | ---------------------------------- |
| `property` | string | フィルタプロパティ（例：`name`、`width`、`type`） |
| `method`   | string | フィルタメソッド（例：`contain`、`>`、`equal`）  |
| `value`    | any    | フィルタ値（プロパティとメソッドによって形式が異なる）        |

{% hint style="info" %}
**ヒント：** `GET /api/v2/smartFolder/getRules` を使用して、利用可能なすべてのプロパティ、メソッド、およびそれに対応する valueType を確認できます。
{% endhint %}

***

## SmartFolder プロパティ <a href="#properties" id="properties"></a>

API から返却されるスマートフォルダには以下のプロパティが含まれます：

| プロパティ              | 型         | 説明             |
| ------------------ | --------- | -------------- |
| `id`               | string    | 一意のスマートフォルダ ID |
| `name`             | string    | 名前             |
| `conditions`       | Object\[] | フィルタ条件         |
| `description`      | string    | 説明             |
| `icon`             | string    | アイコン           |
| `iconColor`        | string    | アイコンの色         |
| `children`         | Object\[] | 子スマートフォルダ      |
| `modificationTime` | integer   | 最終更新タイムスタンプ    |
| `imageCount`       | integer   | 条件に一致するアイテム数   |