# smartFolder

{% hint style="danger" %}
**Version Requirement**: This feature requires Eagle 4.0 build22 or later.
{% endhint %}

```javascript
// Create a smart folder using the fluent builder
const sf = await eagle.smartFolder.create({
    name: 'Large PNGs',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('type').equal('png'),
        ])
    ]
});

// Modify properties
sf.name = 'Extra Large PNGs';
sf.iconColor = 'blue';

// Save changes
await sf.save();
```

{% hint style="success" %}
**🦄 Best Practice:** Use the `getRules()` method to get all available filter rule schemas. Combined with the `rule()` fluent builder and `Condition.create()` helper, you can construct conditions more safely.
{% endhint %}

## Methods <a href="#methods" id="methods"></a>

## create(options) <a href="#create" id="create"></a>

Create a smart folder

* `options` Object
  * `name` string - Smart folder name
  * `conditions` Object\[] - Filter conditions
  * `description` string (optional) - Description
  * `iconColor` string (optional) - Icon color
  * `parent` string (optional) - Parent smart folder ID
* Returns `Promise<smartFolder: SmartFolder>` - The newly created smart folder

```javascript
// Using raw JSON format
let sf = await eagle.smartFolder.create({
    name: 'Cat Images',
    conditions: [
        {
            rules: [
                { property: 'name', method: 'contain', value: 'cat' }
            ],
            match: 'AND'
        }
    ]
});

// Using the fluent builder
let sf2 = await eagle.smartFolder.create({
    name: 'Large Images',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('height')['>']([1080]),
        ])
    ],
    iconColor: 'blue'
});
```

***

## get(options) <a href="#get" id="get"></a>

Get smart folders matching the specified criteria.

* `options` Object - Query criteria
  * `id` string (optional) - Smart folder ID
  * `ids` string\[] (optional) - Array of smart folder IDs
* Returns `Promise<smartFolders: SmartFolder[]>` - Query results

```javascript
// Get smart folders by IDs
let smartFolders = await eagle.smartFolder.get({
    ids: ['sf_id1', 'sf_id2']
});
```

***

## getAll() <a href="#getall" id="getall"></a>

Get all smart folders.

* Returns `Promise<smartFolders: SmartFolder[]>` - Query results

```javascript
let smartFolders = await eagle.smartFolder.getAll();
```

***

## getById(smartFolderId) <a href="#getbyid" id="getbyid"></a>

Get the smart folder with the specified `smartFolderId`.

* `smartFolderId` string - Smart folder ID
* Returns `Promise<smartFolder: SmartFolder>` - Query result

```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');
```

***

## getByIds(smartFolderIds) <a href="#getbyids" id="getbyids"></a>

Get smart folders matching the specified `smartFolderIds`.

* `smartFolderIds` string\[] - Array of smart folder IDs
* Returns `Promise<smartFolders: SmartFolder[]>` - Query results

```javascript
let smartFolders = await eagle.smartFolder.getByIds(['sf_id1', 'sf_id2']);
```

***

## remove(smartFolderId) <a href="#remove" id="remove"></a>

Delete the specified smart folder.

* `smartFolderId` string - Smart folder ID
* Returns `Promise<result: boolean>`

```javascript
await eagle.smartFolder.remove('smart_folder_id');
```

***

## getRules() <a href="#getrules" id="getrules"></a>

Get the available filter rule schema. Returns supported methods, valueType, options, and more for each property.

* Returns `Promise<rules: Object>` - Rule schema object

```javascript
const rules = await eagle.smartFolder.getRules();
console.log(rules);
// {
//     name: { methods: ['contain', 'equal', ...], valueType: 'string' },
//     width: { methods: ['=', '>=', '>', ...], valueType: 'number' },
//     type: { methods: ['equal', 'unequal'], valueType: 'string', options: [...] },
//     ...
// }
```

{% hint style="info" %}
Tip: Call `getRules()` first to get available properties and methods, then use the `rule()` builder to construct conditions safely.
{% endhint %}

***

## rule(property) <a href="#rule" id="rule"></a>

Fluent builder for constructing a single filter rule. Returns an object with all available methods; calling a method produces the corresponding Rule object.

* `property` string - Filter property (e.g., `name`, `width`, `type`)
* Returns `Object` - Builder object with all available methods

```javascript
// Name contains "cat"
eagle.smartFolder.rule('name').contain('cat');

// Width greater than 1920
eagle.smartFolder.rule('width')['>']([1920]);

// Type equals png
eagle.smartFolder.rule('type').equal('png');

// Rating greater than or equal to 3
eagle.smartFolder.rule('rating')['>=']([3]);

// Name is empty
eagle.smartFolder.rule('name').empty();

// Used with Condition.create
let condition = eagle.smartFolder.Condition.create('AND', [
    eagle.smartFolder.rule('name').contain('cat'),
    eagle.smartFolder.rule('width')['>']([1920]),
]);
```

***

## Class: SmartFolder <a href="#class" id="class"></a>

The object type returned by SmartFolder API `get` methods, providing modify and save capabilities.

```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');

console.log(sf.id);
console.log(sf.name);

sf.name = 'New Name';
console.log(sf.name);

await sf.save();
```

{% hint style="success" %}
**🦄 Best Practice:** Use the SmartFolder instance's `save()` method to persist changes safely.
{% endhint %}

***

#### Instance Methods <a href="#instance-methods" id="instance-methods"></a>

### **save()**

Save all modifications

* Returns `Promise<smartFolder: SmartFolder>` - The updated smart folder

```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');
sf.name = 'New Name';
sf.iconColor = 'green';

// Save changes
await sf.save();
```

***

### **getItems(options)**

Get items matching this smart folder's filter conditions.

* `options` Object (optional)
  * `orderBy` string (optional) - Sort field
  * `fields` string\[] (optional) - Fields to return
* Returns `Promise<items: Object[]>` - Array of matching items

```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');

// Get all matching items
let items = await sf.getItems();

// Specify return fields
let items2 = await sf.getItems({
    fields: ['id', 'name', 'ext', 'width', 'height']
});
```

***

#### Instance Properties <a href="#instance-properties" id="instance-properties"></a>

A `SmartFolder` instance contains the following properties:

### **`id` string**

Read-only. Smart folder ID.

### **`name` string**

Smart folder name.

### **`conditions` Object\[]**

Filter conditions array.

### **`description` string**

Smart folder description.

### **`icon` string**

Read-only. Smart folder icon.

### **`iconColor` string**

Smart folder icon color.

```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');

// Set icon color to red
sf.iconColor = eagle.smartFolder.IconColor.Red;

// Or use a string value directly
sf.iconColor = 'red';

// Save changes
await sf.save();
```

### **`modificationTime` integer**

Read-only. Last modification timestamp.

### **`children` SmartFolder\[]**

Read-only. Array of child smart folders.

```javascript
let children = sf.children;
console.log(children[0].name);
```

### **`parent` string**

Read-only. Parent smart folder ID.

### **`imageCount` integer**

Read-only. Number of items matching the conditions.

***

## Helper Classes <a href="#helpers" id="helpers"></a>

### **SmartFolder.Rule**

Rule object describing a single filter rule.

```javascript
// Create via constructor
let rule = new eagle.smartFolder.Rule('name', 'contain', 'cat');

// Or use the rule() fluent builder (recommended)
let rule2 = eagle.smartFolder.rule('name').contain('cat');
```

### **SmartFolder.Condition**

Condition group object containing multiple rules and logic operators.

```javascript
// Create using Condition.create
let condition = eagle.smartFolder.Condition.create('AND', [
    eagle.smartFolder.rule('name').contain('cat'),
    eagle.smartFolder.rule('width')['>']([1920]),
]);

// Create an exclusion condition
let excludeCondition = eagle.smartFolder.Condition.create('OR', [
    eagle.smartFolder.rule('type').equal('gif'),
], 'FALSE');
```

**Condition.create(match, rules, boolean)**

* `match` string - `'AND'` or `'OR'`
* `rules` Object\[] - Array of rules
* `boolean` string (optional) - `'TRUE'` (include, default) or `'FALSE'` (exclude)

***

## Static Properties <a href="#static-properties" id="static-properties"></a>

### **`IconColor` Object**

Provides predefined icon color constants for setting the `iconColor` property.

```javascript
eagle.smartFolder.IconColor.Red      // 'red'
eagle.smartFolder.IconColor.Orange   // 'orange'
eagle.smartFolder.IconColor.Yellow   // 'yellow'
eagle.smartFolder.IconColor.Green    // 'green'
eagle.smartFolder.IconColor.Aqua     // 'aqua'
eagle.smartFolder.IconColor.Blue     // 'blue'
eagle.smartFolder.IconColor.Purple   // 'purple'
eagle.smartFolder.IconColor.Pink     // 'pink'
```

{% hint style="success" %}
**🦄 Best Practice:** Use `eagle.smartFolder.IconColor` constants instead of string values directly for better code hints and type safety.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.eagle.cool/plugin-api/api/smart-folder.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.