# Changelog

Eagle Plugin API changelog, documenting all important feature changes since the first Plugin API version.

{% hint style="info" %}
Update: Eagle 4.0 Build12 has been officially released. Features marked "Eagle 4.0 Build12+" are now available. If you are on an older version, please upgrade to 4.0 build12 or later.
{% endhint %}

## March 24, 2026

### 📄 Item API Enhancement

**New Feature: Comment CRUD API (Eagle 4.0 build22+)**

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

* Added [`item.comments`](https://developer.eagle.cool/plugin-api/api/item#comments-object) read-only property to access item comments/annotations
* Added [`item.addComment(commentData)`](https://developer.eagle.cool/plugin-api/api/item#add-comment) method for adding image rect comments or video timestamp comments
* Added [`item.updateComment(commentId, updateData)`](https://developer.eagle.cool/plugin-api/api/item#update-comment) method for updating existing comments
* Added [`item.removeComment(commentId)`](https://developer.eagle.cool/plugin-api/api/item#remove-comment) method for removing comments

```javascript
let item = await eagle.item.getById('item_id');

// Read comments
console.log(item.comments);

// Add image rect comment
await item.addComment({ x: 350, y: 480, width: 380, height: 400, annotation: "Face area" });

// Add video timestamp comment
await item.addComment({ duration: 65.5, annotation: "Important scene" });

// Update comment
await item.updateComment('comment_id', { annotation: "Updated text" });

// Remove comment
await item.removeComment('comment_id');
```

### 📁 Smart Folder API

**New Feature: Smart Folder CRUD API (Eagle 4.0 build22+)**

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

* Added [`eagle.smartFolder`](https://developer.eagle.cool/plugin-api/api/smart-folder) module with full smart folder management support
* Added `create()`, `get()`, `getAll()`, `getById()`, `getByIds()`, `remove()` methods
* Added `getRules()` method to get available filter rule schema
* Added `rule()` fluent builder and `Condition.create()` helper
* SmartFolder instances support `save()` and `getItems()` methods

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

// Query rule schema
const rules = await eagle.smartFolder.getRules();

// Get matching items
const items = await sf.getItems();
```

### 🔧 Manifest Configuration Enhancement

**New Feature: followCursor Window Positioning (Eagle 4.0 build22+)**

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

* Added `followCursor` manifest setting — when enabled, the window automatically positions near the cursor
* Ideal for tool-type plugins that require quick interaction, minimizing the distance for user interaction
* When enabled, the window does not remember its position and follows the cursor each time it opens

```json
{
    "main": {
        "followCursor": true
    }
}
```

## January 22, 2026

### 💻 App API Enhancement

**New Feature: Show Main Window (Eagle 4.0 build18+)**

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

* Added [`eagle.app.show()`](https://developer.eagle.cool/plugin-api/api/app#show) method, allowing plugins to bring the Eagle main application window to the front and display it on top

```javascript
// Bring Eagle main window to the front
await eagle.app.show();
```

### 📄 Item API Enhancement

**New Feature: Modify Import Time (Eagle 4.0 build18+)**

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

* [`item.importedAt`](https://developer.eagle.cool/plugin-api/api/item#importedat-interger) property now supports modification, allowing plugins to customize file import time
* Useful for batch importing historical files, data migration, and other scenarios requiring preservation of original timestamps

```javascript
// Modify import time
item.importedAt = new Date('2024-01-01').getTime();
await item.save();
```

## January 9, 2026

### 🔍 AI Search Semantic Search API

**New Feature: AI Semantic Search Integration (Eagle 4.0 build18+)**

* Added [`eagle.extraModule.aiSearch`](https://developer.eagle.cool/plugin-api/extra-module/ai-search) module, providing AI semantic search capabilities
* **Status Query Methods**:
  * `isInstalled()` - Check if AI Search plugin is installed
  * `isReady()` - Check if service is ready
  * `isStarting()` - Check if service is starting
  * `isSyncing()` - Check if data is syncing
* **Service Control Methods**:
  * `open()` - Open AI Search plugin
  * `checkServiceHealth()` - Check service health status
  * `getSyncStatus()` - Get detailed sync status
* **Search Methods**:
  * `searchByText(query, options)` - Text semantic search
  * `searchByBase64(base64, options)` - Base64 image search
  * `searchByItemId(itemId, options)` - Search similar images by item ID

```javascript
const aiSearch = eagle.extraModule.aiSearch;

// Check service status
if (await aiSearch.isReady()) {
    // Text semantic search
    const result = await aiSearch.searchByText('an orange cat', { limit: 10 });

    // Results contain complete Item objects
    result.results.forEach(r => {
        console.log(`${r.item.name} - Similarity: ${(r.score * 100).toFixed(1)}%`);
    });
}
```

## January 8, 2026

### 🏷️ TagGroup/Tag API Incremental Operations

**New Feature: Incremental Tag Group Operations (Eagle 4.0 build18+)**

* [`tagGroup.addTags()`](https://developer.eagle.cool/plugin-api/api/tag-group#addtags) - Incrementally add or move tags to a group without passing the complete tags array
* [`tagGroup.removeTags()`](https://developer.eagle.cool/plugin-api/api/tag-group#removetags) - Remove specified tags from a group
* [`eagle.tag.merge()`](https://developer.eagle.cool/plugin-api/api/tag#merge) - Merge tags by renaming source tag to target tag

```javascript
// Add tags to group
await tagGroup.addTags({ tags: ['UI', 'UX'] });

// Move tags (remove from original groups)
await tagGroup.addTags({ tags: ['Branding'], removeFromSource: true });

// Remove tags from group
await tagGroup.removeTags({ tags: ['Outdated'] });

// Merge tags
const result = await eagle.tag.merge({ source: 'UI Design', target: 'UI' });
```

### 🏷️ TagGroup API Enhancement

**New Feature: Tag Group Description Property (Eagle 4.0 build18+)**

* Added `description` property to [`tagGroup`](https://developer.eagle.cool/plugin-api/api/tag-group), allowing you to add descriptive text to tag groups
* Supported in both `create()` and `save()` methods

```javascript
// Create a tag group with description
await eagle.tagGroup.create({
    name: "new group",
    description: "Group description"
});

// Modify tag group description
tagGroup.description = "New description";
await tagGroup.save();
```

## January 6, 2026

### 🏷️ Tag API Enhancement

**New Feature: Get Starred Tags (Eagle 4.0 build18+)**

* Added [`eagle.tag.getStarredTags()`](https://developer.eagle.cool/plugin-api/api/tag#starred) method to retrieve user's favorite/starred tags

```javascript
const starred = await eagle.tag.getStarredTags();
```

**Documentation Fix**

* Fixed incorrect API method name: `getRecents()` → [`getRecentTags()`](https://developer.eagle.cool/plugin-api/api/tag#dwsxw)

## August 21, 2025

### 💻 App API Enhancement

**New Feature: app.userDataPath Property (Eagle 4.0 build12+)**

* Added [`app.userDataPath`](https://developer.eagle.cool/plugin-api/api/app#ud9km) property, returns the path to the current user data directory
* Provides quick access to Eagle's user data storage location

```javascript
console.log(eagle.app.userDataPath);
// "C:\Users\User\AppData\Roaming\Eagle"
```

## August 19, 2025

### 📁 Folder API Enhancements

**New Feature: Folder parent Property Modifiable (Eagle 4.0 build12+)**

* Added [`folder.parent`](https://developer.eagle.cool/plugin-api/api/folder#woenk) property modification support, allowing dynamic adjustment of folder hierarchy
* Support for moving folders to different parent directories or root directory

```javascript
// Move to another parent folder
folder.parent = 'parent_folder_id';
await folder.save();

// Move to root directory  
folder.parent = null;
await folder.save();
```

**New Feature: Folder iconColor Property Modifiable (Eagle 4.0 build12+)**

* Changed [`folder.iconColor`](https://developer.eagle.cool/plugin-api/api/folder#woenk) property from read-only to modifiable
* Added [`eagle.folder.IconColor`](https://developer.eagle.cool/plugin-api/api/folder#static-properties) static constant object, providing predefined color options
* Supported colors: Red, Orange, Yellow, Green, Aqua, Blue, Purple, Pink

```javascript
folder.iconColor = eagle.folder.IconColor.Blue;
await folder.save();
```

## August 13, 2025

### 🏷️ Tag API Feature Expansion

**New Feature: Tag Filtering and Tag Class Enhancement**

* [`eagle.tag.get()`](https://developer.eagle.cool/plugin-api/api/tag#x9nu2) method added `name` parameter, supporting fuzzy search by tag name
* Tag instance added [`save()`](https://developer.eagle.cool/plugin-api/api/tag#instance-methods) method, supporting tag name modification
* Added Tag instance properties: [`name`](https://developer.eagle.cool/plugin-api/api/tag#instance-properties) (modifiable), `count`, `color`, `groups`, `pinyin`

```javascript
// Filter tags
const filteredTags = await eagle.tag.get({ name: "design" });

// Modify tag name  
tag.name = 'new-name';
await tag.save();
```

⚠️ **Note: Modifying tag names will automatically update all files using that tag**

## August 5, 2025

### 📄 Item API Performance and Selection Enhancements

**New Feature: Performance Optimization**

* [`eagle.item.get()`](https://developer.eagle.cool/plugin-api/api/item#bdcw2) added `fields` parameter, supporting selective field return for significant query performance improvement
* Added [`eagle.item.getIdsWithModifiedAt()`](https://developer.eagle.cool/plugin-api/api/item#getidswithmodifiedat) method, optimized for incremental synchronization
* Added [`modifiedAt`](https://developer.eagle.cool/plugin-api/api/item#woenk) property, recording file last modification time

```javascript
// Return only needed fields
let items = await eagle.item.get({
    tags: ["Design"],
    fields: ["id", "name", "tags", "modifiedAt"]
});

// Efficient incremental sync
let fileInfo = await eagle.item.getIdsWithModifiedAt();
```

**New Feature: Counting and Selection Methods**

* Added [`eagle.item.count(options)`](https://developer.eagle.cool/plugin-api/api/item#count) - conditional counting
* Added [`eagle.item.countAll()`](https://developer.eagle.cool/plugin-api/api/item#countall) - total file count
* Added [`eagle.item.countSelected()`](https://developer.eagle.cool/plugin-api/api/item#countselected) - selected file count
* Added [`eagle.item.select(itemIds)`](https://developer.eagle.cool/plugin-api/api/item#select) - programmatic file selection

```javascript
let count = await eagle.item.count({ isSelected: true });
await eagle.item.select(['ITEM_ID_1', 'ITEM_ID_2']);
```

**Enhanced Feature: open() Method**

* [`eagle.item.open()`](https://developer.eagle.cool/plugin-api/api/item#yxkul) added `window` option, supporting opening files in new window

```javascript
await eagle.item.open('item_id', { window: true });
```

## July 31, 2025

### 🪟 Window API Expansion

**New Feature: Window Geometry Control**

* Added [`eagle.window.getSize()`](https://developer.eagle.cool/plugin-api/api/window#mq0dz) - get window size
* Added [`eagle.window.setBounds(bounds)`](https://developer.eagle.cool/plugin-api/api/window#setbounds-bounds) - set window bounds (position + size)
* Added [`eagle.window.getBounds()`](https://developer.eagle.cool/plugin-api/api/window#getbounds) - get window bounds information

```javascript
await eagle.window.getSize();
await eagle.window.setBounds({ x: 440, y: 225, width: 800, height: 600 });
await eagle.window.getBounds();
```

## November 28, 2024

### 🏷️ TagGroup CRUD Operations

**New Feature: Complete Tag Group Management**

* Added [`eagle.tagGroup.create(options)`](https://developer.eagle.cool/plugin-api/api/tag-group#x9nu2) - create new tag group
* Added [`tagGroup.save()`](https://developer.eagle.cool/plugin-api/api/tag-group#x9nu2) - save modifications
* Added [`tagGroup.remove()`](https://developer.eagle.cool/plugin-api/api/tag-group#x9nu2) - delete tag group

```javascript
// Create tag group
await eagle.tagGroup.create({
    name: "new group",
    color: "red", 
    tags: ["tag1", "tag2"]
});

// Modify and save
tagGroup.name = "new name";
await tagGroup.save();

// Delete group
await tagGroup.remove();
```

### 🗑️ Item Deletion Feature

**New Feature: File Trash Operations**

* Added [`item.moveToTrash()`](https://developer.eagle.cool/plugin-api/api/item#movetotrash) instance method, moving files to system trash

```javascript
let item = await eagle.item.getById('item_id');
await item.moveToTrash();
```

## July 25, 2024

### 🪟 Window API Enhancement

**New Feature: HTTP Referer Setting**

* Added [`eagle.window.setReferer(url)`](https://developer.eagle.cool/plugin-api/api/window#4a6f) method, setting referer header for subsequent network requests

```javascript
eagle.window.setReferer("https://example.com");
```

## May 10, 2024

### 🖱️ Context Menu API

**New Feature: Custom Context Menu**

* Added [`eagle.contextMenu.open()`](https://developer.eagle.cool/plugin-api/api/context-menu#tkp0d) method, supporting custom context menus
* Support for multi-level submenus, custom click events, system native styling

```javascript
eagle.contextMenu.open([
    {
        id: "edit",
        label: "Edit",
        submenu: [...],
        click: () => { ... }
    }
]);
```

### 🪟 Window API Screenshot Feature

**New Feature: Page Screenshot**

* Added [`eagle.window.capturePage(rect)`](https://developer.eagle.cool/plugin-api/api/window#yvfx9) method, supporting full page or specified area screenshots
* Returns NativeImage object, convertible to base64 or PNG buffer

```javascript
// Full page screenshot
const image = await eagle.window.capturePage();

// Specified area screenshot
const image2 = await eagle.window.capturePage({ 
    x: 0, y: 0, width: 100, height: 50 
});
```

## April 17, 2024

### 🔍 Preview Plugin Feature Enhancement

**New Feature: Zoom Control Parameter**

* Preview plugin configuration added [`allowZoom`](https://developer.eagle.cool/plugin-api/get-started/plugin-types/preview) parameter, controlling whether users can zoom preview content

```json
"thumbnail": {
    "path": "thumbnail/icns.js",
    "size": 400,
    "allowZoom": false
}
```