feat: add background_tasks + list_snapshots tools (v0.3.4)
- background_tasks: SYNO.FileStation.BackgroundTask::list (v3) — paginated table of active/recent copy/move/delete/extract/compress tasks - list_snapshots: SYNO.FileStation.Snapshot::list (v2) — Btrfs snapshots per share; maps error 400 to a clear Btrfs-required message - 20 new tests (107 total) - SPEC.md and CLAUDE.md updated (26 tools) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -97,7 +97,7 @@ regardless of service state.
|
||||
|
||||
---
|
||||
|
||||
## Tools (v0.2.10 — 20 tools)
|
||||
## Tools (v0.3.4 — 26 tools)
|
||||
|
||||
### Read-only
|
||||
|
||||
@@ -134,6 +134,22 @@ regardless of service state.
|
||||
| `list_sharing_links` | List all sharing links (paginated table) |
|
||||
| `delete_sharing_link` | Delete a sharing link by ID |
|
||||
|
||||
### Thumbnail & Favorites
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `get_thumbnail` | Fetch a thumbnail for an image/video file as base64 |
|
||||
| `list_favorites` | List all FileStation user favorites |
|
||||
| `add_favorite` | Add a path to FileStation favorites |
|
||||
| `delete_favorite` | Remove a path from FileStation favorites |
|
||||
|
||||
### Background Tasks & Snapshots
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `background_tasks` | List FileStation background tasks (copy, move, delete, etc.) |
|
||||
| `list_snapshots` | List Btrfs snapshots for a shared folder (requires Btrfs volume) |
|
||||
|
||||
---
|
||||
|
||||
### Tool details
|
||||
@@ -439,6 +455,96 @@ pagination hint when more results are available.
|
||||
|
||||
---
|
||||
|
||||
#### `get_thumbnail`
|
||||
**Parameters:**
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `path` | str | yes | — | Share-relative path to the image or video file |
|
||||
| `size` | str | no | `large` | `small`, `medium`, `large`, or `original` |
|
||||
|
||||
**Returns:** JSON `{filename, size_bytes, content_base64}` (JPEG bytes encoded as base64).
|
||||
|
||||
**DSM call:** `SYNO.FileStation.Thumb::get` (POST, v2)
|
||||
|
||||
> DSM returns image bytes directly when the file has a thumbnail. Non-image content-type
|
||||
> indicates a DSM error envelope — the tool parses and surfaces the error code.
|
||||
|
||||
---
|
||||
|
||||
#### `list_favorites`
|
||||
**Parameters:**
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `offset` | int | no | 0 | Pagination offset |
|
||||
| `limit` | int | no | 200 | Max items to return |
|
||||
|
||||
**Returns:** Table with name, path, type, status, real path, modified time.
|
||||
|
||||
**DSM call:** `SYNO.FileStation.Favorite::list` (v2, `additional=["real_path","size","time"]`)
|
||||
|
||||
---
|
||||
|
||||
#### `add_favorite`
|
||||
**Parameters:**
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | str | yes | Share-relative path to pin |
|
||||
| `name` | str | yes | Display label for the favorite |
|
||||
|
||||
**Returns:** `"Added favorite '{name}' → {path}"` or error.
|
||||
|
||||
**DSM call:** `SYNO.FileStation.Favorite::add` (v2, `index=-1`)
|
||||
|
||||
---
|
||||
|
||||
#### `delete_favorite`
|
||||
**Parameters:**
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | str | yes | Share-relative path of the favorite to remove |
|
||||
|
||||
**Returns:** `"Deleted favorite for {path}"` or error.
|
||||
|
||||
**DSM call:** `SYNO.FileStation.Favorite::delete` (v2)
|
||||
|
||||
---
|
||||
|
||||
#### `background_tasks`
|
||||
**Parameters:**
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `offset` | int | no | 0 | Pagination offset |
|
||||
| `limit` | int | no | 100 | Max tasks to return (capped at 200) |
|
||||
|
||||
**Returns:** Table with task ID, type, status, path, and file progress. Includes total count
|
||||
and a pagination hint when more results are available.
|
||||
|
||||
**DSM call:** `SYNO.FileStation.BackgroundTask::list` (v3)
|
||||
|
||||
> Only the `list` method is available on this NAS — tasks cannot be stopped or cleared
|
||||
> via this API.
|
||||
|
||||
---
|
||||
|
||||
#### `list_snapshots`
|
||||
**Parameters:**
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `share_path` | str | yes | — | Share-relative root path (e.g. `/docker`) |
|
||||
| `offset` | int | no | 0 | Pagination offset |
|
||||
| `limit` | int | no | 100 | Max snapshots to return (capped at 500) |
|
||||
|
||||
**Returns:** Table with snapshot ID, creation time, description, and locked flag. Includes
|
||||
total count and a pagination hint when more results are available.
|
||||
|
||||
**DSM call:** `SYNO.FileStation.Snapshot::list` (v2, `folder_path={share_path}`)
|
||||
|
||||
> **Btrfs required:** DSM returns error 400 when the share is not on a Btrfs volume.
|
||||
> The tool maps this to a clear message: *"Snapshots not available — requires Btrfs-formatted
|
||||
> volume."*
|
||||
|
||||
---
|
||||
|
||||
## Error Handling Strategy
|
||||
|
||||
### Principles
|
||||
|
||||
Reference in New Issue
Block a user