# Installation

Install the Blocks package:

```bash
npm install useblocks@1.0.117
```

Add the Blocks **build plugin** to your bundled app configuration (it copies package assets into the output and injects **`UseblocksEnvironment.publicPath`** for chunk URLs). Without the helper plugin you must set the bundle base URL yourself.

## Agents & automation checklist

Use this when generating integration code or reviewing PRs against the Blocks plugin SDK. Canonical typings live in **`useblocks.d.ts`** (**`ExportedApi`**); avoid inventing field names.

For how merged **`ExportedApi`** interfaces, **`AppEvent`**, and payload types fit together (and how **`handleSubjectChanged`** differs), see **`docs/plugin-types-agents.md`** in the upstream authoring repository.

| Rule | Details |
| --- | --- |
| **`init`** | **`content` is mandatory**. **`init(options) → Promise<Instance>`**. |
| Module vs **instance** | The **`useblocks`** bundle exports **`init`** (plus optional named ESM APIs). **`setConfig`**, **`show`**, **`save`**, **`destroy`** belong to the **`init`** return value—not the namespace object. |
| Same DOM repeat | Calling **`init`** again on an existing mount triggers **`reset`**. Avoid parallel **`init`** on one container. |
| Events | **`instance.handle*(…)`** usually returns **unsubscribe**. **`handleSubjectChanged`** / **`handlePreheaderChanged`** use bespoke signatures — see typings. |
| Async | Handlers plus **`getAuthToken`** may be **`async`**; funnel errors via **`handleError`** or your own telemetry. |
| Build | Without Webpack/Vite helpers you must wire **`UseblocksEnvironment`** / **`publicPath`**. Expect a heavy UI bundle (React, Monaco, etc.). |
| Auth | Prefer **`getAuthToken`** or **`jwtAuth`**; keep **`client_secret`** on the server only. |
| File manager | Wire **`storageProvider`** + **`config.imageCenterFileManagerView`** and read the **`StorageProvider`** contract before stubbing backends. |
| **`commonStyles`** | Optional on **`init` / `reset`**: content-styles object (partial merge with **`COMMON_STYLES`**). Details — **`docs/plugin-content-styles.md`** in the authoring repository. |

Reference HTML samples (`plugin_default.html`, etc.) live under **`src/pluginExamples/`** in the authoring repository.

### Webpack

Use the exported class constructor with matching variable name:

```javascript
const UseblocksWebpackPlugin = require('useblocks/webpack');

module.exports = {
  plugins: [
    new UseblocksWebpackPlugin({
      // Optional: outputFolder, modulesPath, publicPath — see package.
    }),
  ],
};
```

### Vite

The factory returns **an array of two plugins** (serve + build) — **spread** it into `plugins`:

```javascript
import { defineConfig } from 'vite';
import useblocksVite from 'useblocks/vite';

export default defineConfig({
  plugins: [
    ...useblocksVite({
      // Optional: outputFolder, modulesPath, publicPath — see package.
    }),
  ],
});
```

# Initialization

Import the plugin in application code:

```javascript
import * as useblocks from 'useblocks';
```

**`init`** requires **`content`** (HTML string or email/template wrapper). Methods such as **`setConfig`**, **`updateConfig`**, **`show`**, **`save`** are on the **instance returned from `init`**, not on the **`useblocks`** namespace object.

Typical root fields include **`getAuthToken`** or **`jwtAuth`**, **`element`**, **`content`**, **`config`**, **`project`**, **`baseUrl`**, **`storageProvider`**, **`commonStyles`**.

- **`commonStyles`** — optional content-styles preset merged with shipped **`COMMON_STYLES`** (see **`docs/plugin-content-styles.md`** in the authoring repository). Partial objects are safe.

- **`getAuthToken`** — **`(user?, project?, prevToken?) => string | Promise<string>`**. Obtain **`client_secret` only from your backend**; never expose it in the browser.
- **`jwtAuth`** — alternative to **`getAuthToken`**: **`{ email, password, remember? }`** (see **`useblocks.d.ts`** or shipped typings).

ESM builds also expose named exports (for example **`useblocks-esm.js`**):

```javascript
import { init, parseAMP, COMMON_STYLES, version, helpers, errors } from 'useblocks';
```

**`parseAMP`** parses AMP email code without UI; **`COMMON_STYLES`** is the default content-styles object for this build (spread into **`init({ commonStyles })`**); documented in **`src/constants/commonStyles.defaults.ts`**. **`version`** is the build string; **`helpers`** / **`errors`** include HTTP helpers and error classes (e.g. file manager).

### Fetching the OAuth token on the backend

```bash
curl --location 'https://api.useblocks.io/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=*******' \
--data-urlencode 'client_secret=*******' \
--data-urlencode 'grant_type=client_credentials'
```

### Creating the plugin instance

```javascript
useblocks
  .init({
    getAuthToken,
    element: '#test',
    content: {
      subject: 'Email subject',
      html: 'EMAIL_CODE',
    },
    config: {},
  })
  .then((instance) => {});
```

You can take **`EMAIL_CODE`** from <a href="https://cdn.useblocks.io/plugin/new-email.html" target="_blank">our sample</a> or paste your own HTML.

For debugging, the dev build may support a front-end token flow — configure an auth proxy in your app if you use that path.

# Configuration

Configuration is a nested object: editor chrome, initial email payload, and callback hooks.

Calling **`init`** again on the **same DOM host** internally performs **`reset`** with the new options — avoid two concurrent **`init`** calls on one container.

### Element

Pass a selector string, an **`Element`**, or a **`DocumentFragment`**. Omitting **`element`** can run in background mode without a visible host.

### Content

Possible shapes:

#### `{string}`

Raw HTML markup for the email.

#### `{object}` email fields

```javascript
{
  id?: string; // Unique email ID in your system.
  html?: string;
  subject?: string;
  preheader?: string;
}
```

#### `{object}` Template, blocks, comments

```javascript
{
  templateId?: string | number; // Template ID inside Blocks.
  email?: object;
  blocks?: [],
  comments?: [],
}
```

After **`init`**, update with **`instance.show(content)`**.

### Content styles (`commonStyles`)

Top-level **`init` / `reset`** option (not inside **`config`**). Shallow docs here — full reference: **`docs/plugin-content-styles.md`**.

- **`COMMON_STYLES`** named export — default preset for this product build.
- Partial overrides are deep-merged with **`COMMON_STYLES`** so UI panels stay consistent.
- Saved **`email.common_styles`** wins over **`init.commonStyles`** when present.
- Clear stored plugin override with **`commonStyles: undefined`** on **`reset`** / **`updateConfig`**.
- Show the sidebar tab via **`config.commonStylesEnabled`** (usually default **true**).

### Config

Editor UI tuning. Use **`instance.setConfig`**, **`instance.updateConfig`**, **`instance.getConfig`** after **`init`** — **not** `useblocks.setConfig` / `useblocks.updateConfig`.

##### Parameter list (`config`)

| Parameter              | Description                       | Default |
| ---------------------- | --------------------------------- | ------- |
| theme | Plugin theme: light, dark. | light |
| autosaveTimeout | Delay before autosave, ms. | 10000 |
| mergeTags | JSON with the list of dynamic variables. | undefined |
| styles | String with styles in CSS format. | '' |
| | | |
| headerShow | Show header. | true |
| headerArrowBackVisible | Show “Back” arrow. | true |
| headerTitleVisible | Show “Subject” field. | true |
| headerPreheaderVisible | Show “Preheader” field. | true |
| historyEnabled | Show “Version history” button. | true |
| codeEnabled | Show “Code mode” button. | true |
| codeModeDirection                      | Default code editor display mode                                    | none|left|right|bottom|
| codeSideEnabled | Show “Code mode” button when desktop/mobile toggle is available. | true |
| previewIconEnabled | Show “Preview” button. | true |
| previewModeEnabled | Link to Preview. | true |
| livePreviewEnabled | Show “Email client testing” button. | true |
| sendTestEnabled | Show “Send test” button. | true |
| sharePreviewEnabled | Show “Share” button. | true |
| webversionEnabled | Show link to web version. | true |
| commonStylesEnabled | Show content styles. | true |
| emailResponsiveControlEnabled | Show email responsiveness toggle. | true |
| templateNotEmAlertShow | Show alert that template is not from EM. | true |
| | | |
| emailDropdownMenuEnabled | Show email menu. | true |
| emailDropdownMenuClone | Show “Clone” item. | true |
| emailDropdownMenuImport | Show “Import” item. | true |
| emailDropdownMenuImportButton | Show “Import” as a button. | true |
| emailDropdownMenuLock | Show “Lock” item. | true |
| emailDropdownMenuRemove | Show “Delete” item. | true |
| | | |
| emailExportEnabled | Show “Export” button. | true |
| exportHtmlEnabled | Export to HTML. | true |
| exportZipEnabled | Export to ZIP. | true |
| exportClipboardEnabled | Export to clipboard. | true |
| exportWebHookEnabled | Export to webhook. | true |
| exportOutlookEnabled | Export to Outlook. | true |
| exportPdfEnabled | Export to PDF. | true |
| exportPngEnabled | Export to PNG. | true |
| | | |
| nextButtonEnabled | Show secondary button. | false |
| nextButtonText | Text on secondary button. | '' |
| saveButtonEnabled | Show primary button. | true |
| saveButtonText | Text on primary button. | '' |
| commandButtonsEnabled | Show primary and secondary buttons. | true |
| | | |
| sidePanelFloating | Floating side panel. | true |
| desktopMobileSwitchRule | Modes switch bar. | true |
| desktopMobileSwitchPanel | Modes switch panel. | false |
| onlyCodeModeInMobile | Show only code on mobile. | false |
| | | |
| pathEnabled | Show breadcrumbs. | true |
| copyPasteEnabled | Show copy–paste block in iframe. | true |
| saveBlockEnabled | Show save block button. | true |
| globalBlockCheckboxEnabled | “Global block” switch in Save block modal (off in bundled defaults — set **`true`** in plugin **`config`** to enable). | false |
| editImageControlEnabled | Show image editing button. | true |
| | | |
| menuDirection | Side panel position. | 'right' |
| defaultBuildPanel | Default opened tab setting. | ''/'empty'/'project'/'common'/'template' |
| commentsEnabled | Show “Comments” button. | true |
| aiAssistentEnabled | Show “AI assistant”. | true |
| optimizeEnabled | Show “Optimization” button. | true |
| optimizeLinksEnabled | Show links check. | true |
| optimizeImagesEnabled | Show images check. | true |
| optimizeSpamAssassinEnabled | Show SpamAssassin check. | true |
| optimizeCheckCodeEnabled | Show code check. | true |
| settingsEnabled | Show “Settings” button. | true |
| UTMEnabled | Show UTM tags tab. | true |
| descriptionEnabled | Show “Description” field in settings. | true |
| tagsEnabled | Show “Tags” field in settings. | true |
| switchDesktopMobilePropsEnabled | Show mobile properties toggle. | true |
| stepToOtherElementEnabled | Show buttons to jump to other elements. | true |
| deleteButtonEnabled | Show delete element button. | true |
| toggleSidePanel | Allow collapsing side panel. | true |
| blocksSectionsShow | Show blocks menu. | true |
| blocksEmptyEnabled | Show empty blocks. | true |
| blocksSavedEnabled | Show saved blocks. | true |
| blocksCommonEnabled | Show common blocks. | true |
| blocksTemplateEnabled | Show template blocks. | true |
| blocksSearchEnabled | Show blocks search. | true |
| blocksAddPanelEnabled | Show add block panel in visual editor. | true |
| imagePathDropdownEnabled | Show dropdown with image path. | true |
| | | |
| formFieldImageTitleEnabled | Show title field in image form. | true |
| formFieldBorderEnabled | Show border controls. | true |
| formFieldBorderRadiusEnabled | Show border radius controls. | true |
| formFieldBoxShadowEnabled | Show shadow controls. | true |
| formFieldVisibilityEnabled | Show element visibility controls. | true |
| formFieldExportAsPictureEnabled | Show “export as image” toggle. | true |
| | | |
| formButtonFieldInsertImageEnabled | Show “insert image into text” button for button. | true |
| formButtonFieldVerticalAlignEnabled | Show vertical alignment controls for button. | true |
| formButtonFieldTextAlignEnabled | Show text alignment controls for button. | true |
| formButtonFieldBackgroundImageEnabled | Show background image controls for button. | true |
| formButtonFieldPaddingsEnabled | Show padding controls for button. | true |
| formButtonFieldReplacerEnabled | Show replacer for button. | true |
| | | |
| formCellFieldVerticalAlignEnabled | Show vertical alignment controls for cell. | true |
| formCellFieldBackgroundImageEnabled | Show background image controls for cell. | true |
| formCellFieldPaddingsEnabled | Show padding controls for cell. | true |
| formCellFieldSizeEnabled | Show width and height controls. | true |
| | | |
| formImageFieldVerticalAlignEnabled | Show vertical alignment controls for image. | true |
| formImageFieldReplacerEnabled | Show replacer for image. | true |
| formImageFieldHeightEnabled | Show height field for image. | true |
| | | |
| formTableFieldBackgroundImageEnabled | Show background image controls for table. | true |
| formDivFieldBackgroundImageEnabled | Show background image controls for container. | true |
| formEmailFieldBackgroundImageEnabled | Show background image controls for email. | true |
| | | |
| formTextFieldTypografEnabled | Show typograph button. | true |
| formTextFieldReplacerEnabled | Show replacer button. | true |
| | | |
| elementImageEnabled | Element Image. | true |
| elementTextEnabled | Element Text. | true |
| elementHeaderEnabled | Element Heading. | true |
| elementButtonEnabled | Element Button. | true |
| elementListULEnabled | Element List UL. | true |
| elementListOLEnabled | Element List OL. | true |
| elementDividerEnabled | Element Divider. | true |
| elementSpacerEnabled | Element Spacer. | true |
| elementSocialEnabled | Element Social. | true |
| elementTableEnabled | Element Table. | true |
| elementCountdownEnabled | Element Countdown. | true |
| elementVideoEnabled | Element Video. | true |
| elementAIimageEnabled | Element AI image. | true |
| elementAItextEnabled | Element AI text. | true |
| elementCarouselEnabled | Element AMP carousel. | true |
| elementAccordionEnabled | Element AMP accordion. | true |
| elementFormEnabled | Element AMP form. | true |
| | | |
| imageCenterLocalUploadEnabled | Local file upload field in Image Center. | true |
| imageCenterStockEnabled | Stock photos tab. | true |
| imageCenterGifEnabled | Stock GIFs tab. | true |
| imageCenterEditorEnabled | Image editor tab. | true |
| compressMaxSize | Client-side compression max bytes in file manager (~5&nbsp;MiB default). | see types |
| compressMaxWidthOrHeight | Resize max width/height, px (2000 default). | see types |

### Event wiring

Either pass callbacks to **`init`**, or call **`instance.handle*(listener, priority?)`** — typical pattern returns **unsubscribe** fn. Hooks may be **`async`**.

**Save** handlers (**`handleSaveEmail`**, **`handleSaveBlock`**, **`handleSaveComment`**) receive **`SaveEventPayload`**: **`{ patch, value, prev?, source? }`**.

**`handlePropagateGlobalBlock`** is separate: fired when the user clicks sync on a **global** block in the preview (iframe **`application_eblock_propagate_update`**). Payload is **`{ emBlockId, blockHtml }`** — update the library template and optionally propagate HTML to all emails that reference that **`em-block-id`**. Block HTML in plugin types uses **`code`** (mapped from internal **`html`**).

Subject / preheader use different subscription signatures — inspect **`useblocks.d.ts`**.

```javascript
useblocks.init({
  element: '#test',
  content: { email: { id: '1' } },
  getAuthToken,
  handleReadEmail: async (id) => fetchEmail(id),
  handleSaveEmail: async (payload) => saveEmail(payload.value),
}).then((instance) => {
  const unsubscribe = instance.handleEmailChanged(async () => {});
  /* unsubscribe(); */
});
```

### Events

See typings (**`ExportedApi.DataMixin.Events`**) — includes for example **`handleRemoveEmail`**, **`handleRemoveEmailAutoSave`**, **`handleReadCommonBlocks`**, **`handleReadTemplateBlocks`**, **`handleCloneEmail`**, **`handleShareEmail`**, **`handleLivePreviewEmail`**, **`handlePreviewEmail`**, **`handleValidate`**, **`handleSubjectChanged`**, **`handlePreheaderChanged`**, **`handleReadLocale`**, **`handleTranslate`**, **`handleLimitUsage`**, plus the rows below.

| Name                      | Summary                              |
| ------------------------- | ------------------------------------ |
| handleReadEmail           | Load email by id (**string**)        |
| handleSaveEmail           | Persist email (**`SaveEventPayload`**) |
| handleReadEmailRevisions | Autosaves / revisions                |
| handleEmailAutosave       | Autosave created                     |
| handleReadBlocks          | Project blocks                       |
| handleReadCommonBlocks    | Shared / common blocks               |
| handleReadTemplateBlocks  | Template blocks for current email    |
| handleSaveBlock           | Save block (**`SaveEventPayload`**)  |
| handleRemoveBlock         | Delete block                         |
| handlePropagateGlobalBlock | Sync global block template from iframe (**`GlobalBlockPropagateUpdatePayload`**: **`{ emBlockId, blockHtml }`**) — sync button on a block with **`em-block-id`** |
| handleReadComments        | Email comments                       |
| handleSaveComment         | Save comment                         |
| handleRemoveComment       | Delete comment                       |
| handleSaveButtonClick     | Toolbar primary click                |
| handleNextButtonClick     | “Next” click                         |
| handlePreviousButtonClick | “Back” click                         |
| handleEmailChanged        | Email payload changed                |
| handleHtmlChanged         | HTML string changed                  |
| handleDestroy             | Destroy lifecycle                    |
| handleLoad                | Instance ready hook                  |
| handleLoadImage           | Image upload helpers & proxies       |
| handleNotify              | Generic notification                 |
| handleError               | Error toast hook                     |
| handleSuccess             | Success toast hook                   |
| handleTestEmailSend       | Send test mail                       |
| handleTestEmailModal      | Test send modal opened               |

### Methods

Exports on the module bundle: **`init`**, **`parseAMP`**, etc. Everything else below lives on **`useblocks.init()`’s fulfilled instance**:

| Method | Notes |
| ------ | ----- |
| show | Swap email content (**`Content`**) |
| save | Trigger persistence pipeline |
| getEmail | Current **`CompiledEmail`** |
| compileEmail | Controlled compilation |
| setEmailMeta | Merge **`meta`** on the current email only |
| setBlockMeta | Merge or clear **`meta`** for a block by **`blockId`** (blocks cache) |
| getBlocks / getComments / getEmailRevisions | Data snapshots (**`Block.meta`** round-trip when the host sets own-property) |
| getCodeErrors | Linter output |
| getConfig / setConfig / updateConfig | UI config |
| notify | Push notification |
| getElement | Mount node |
| destroy | Teardown (call on SPA unmount) |
| reset | Re-init with new options |
| undoRedoService | Undo/redo API |

## 📂 File Manager

```ts
useblocks.init({
  storageProvider: /* StorageProvider implementation */,
  config: {
    imageCenterFileManagerView: true,
  },
});
```

The `fileManager` section controls feature flags; every field is optional — default **true** when omitted unless noted in typings.

#### Basic Operations

- **enableTrash** — enables trash functionality for deleted files. When enabled, files are moved to trash instead of permanent deletion. Default: true
- **enableRenameFolder** — allows renaming folders. Default is true  
- **enableRenameFile** — allows renaming files. Default is true  
- **enableUpdateFile** — allows updating file content or metadata. Default is true  
- **enableEdit** — allows editing files (changing content or properties). Default is true  
- **enableMoveFile** — allows moving files between folders. Default is true  
- **enableMoveFolder** — allows moving folders. Default is true  
- **enableCopyFile** — allows copying files. Default is true  
- **enableCopyFolder** — allows copying folders. Default is true  
- **enableDelete** — allows deleting files and folders. When the recycle bin is enabled, files are moved there instead of being permanently deleted. Default is true  
- **multiSelect** — allows multiple selection of files and folders for batch operations. Default is true  
- **defaultFolderName** — default folder name  
- **sortOptions** — whitelist of sort dropdown values (`'date-desc' \| 'date-asc' \| 'size-desc' \| 'size-asc' \| 'name-asc' \| 'name-desc' \| 'type-asc'`). If omitted or empty, all options supported by the file-manager package are shown. Use a non-empty array to hide sorts your platform does not implement (e.g. size or type).

#### Pagination & Display

- **enablePagination** — enables paginated navigation. If disabled, all items are loaded at once. Default: true

#### Client-Side Processing

- **clientSideSorting** — client-side file sorting.
  - If `true`, applies standard sorting (by name ascending).
  - If a function is provided, it receives the current file array, optional `sortBy` and `sortOrder`, and returns a sorted array.

- **clientSidePaging** — client-side file pagination.
  - If `true`, applies standard array slicing based on `page` and `limit`.
  - If a function is provided, it receives the file array, `page` and `limit`, and returns an array for the specific page only.

- **clientSideFilter** — client-side file filtering.
  - If `true`, applies standard filtering by `search` text.
  - If a function is provided, it receives the file array and optional `search`, and returns a filtered array.

#### Cache Strategy

- **cacheStrategy** — caching strategy for performance optimization.
  - **ttl** — cache time-to-live in milliseconds. Default: 300000 (5 minutes)
  - **errorTtl** — cache TTL for errors in milliseconds. Default: 60000 (1 minute)
  - **allowSortedInsert** — allows inserting elements into sorted arrays without full cache invalidation. Default: false
  - **allowSearchInsert** — allows inserting elements into filtered arrays without full cache invalidation. Default: false
  - **invalidateOnPaginationFull** — marks cache as stale when inserting into a full paginated page. Default: true
  - **comparator** — comparison function for sorting two files. Default: name-based comparison
  - **filterMatch** — function to check if a file passes current filters. Default: name-based search

### Interface StorageProvider

#### Properties

| Property                    | Type      | Description                                     | Default |
| --------------------------- | --------- | ----------------------------------------------- | ------- |
| `pathMode`                  | `boolean` | Use path as identifier for folders              | -       |
| `rootId`                    | `string`  | Custom identifier for root folder               | `''`    |
| `trashPath`                 | `string`  | Path to trash/recycle bin folder                | -       |
| `tempPath`                  | `string`  | Path to temporary folder for uploads            | -       |
| `useSoftDelete`             | `boolean` | Enable client-side soft delete                  | `false` |
| `ensureFolderTrailingSlash` | boolean   | Add a trailing slash to folder paths            | `true`  |
| `validateDuplicates`        | `boolean` | Client-side check for existing files or folders | -       |

#### Methods

##### Core Methods

| Method              | Parameters                                                                                                                                                                                                                           | Returns                                                                    | Description                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **getItems**        | `options`:<br>- `folderId?: string`<br>- `search?: string`<br>- `sortBy?: string`<br>- `sortOrder?: 'asc'\|'desc'`<br>- `page?: number`<br>- `limit?: number`<br>- `itemType: 'all'\|'file'\|'folder'`                               | `{ items: FileSystemItem[], pagination?: Partial<ApiPaginationResponse> }` | Retrieve files/folders with filtering, sorting, pagination                                                       |
| **createFolder**    | `name: string`, `parentid?: string`                                                                                                                                                                                                  | `FileSystemItem`                                                           | Create new folder                                                                                                |
| uploadFile          | `file`: <br>- `name: string`<br>- `size: number`<br>- `type: string`<br>- `folderId?: string`<br>- `data: Blob \| string`<br>- `thumbnail?: string`<br>- `dimensions?: string`<br>- `aspectRatio?: string`<br>- `extension?: string` | `FileSystemItemUpdate`                                                     | Upload file with metadata                                                                                        |
| uploadFiles         | `request`:<br>- `items: { requestId?: string, name: string, size: number, type: string, folderId?: string \| null, data: Blob \| string, extension?: string }[]`<br>- `folderId?: string \| null`                                    | `BatchResult<UploadFileResultData>`                                        | Upload multiple files. The order of items matters — if `requestId` is not provided, results are matched by index |
| **uploadFileByUrl** | `url: string`, `folderId?: string`                                                                                                                                                                                                   | `FileSystemItem`                                                           | Upload file from URL (check for existing files)                                                                  |
| `findItemByPath`    | `path: string`                                                                                                                                                                                                                       | `FileSystemItem \| undefined`                                              | Find system files/folders by path                                                                                |
| `setController`     | `controller: StorageProviderController`                                                                                                                                                                                              | `void`                                                                     | Set cache management controller                                                                                  |
| `getFileData`       | `file: FileSystemItem`                                                                                                                                                                                                               | `Blob`                                                                     | Get file content as blob                                                                                         |
| `getUrl`            | `file: FileSystemItem`                                                                                                                                                                                                               | `string`                                                                   | Get file access URL                                                                                              |
| `getThumbnailUrl`   | `file: FileSystemItem`                                                                                                                                                                                                               | `string`                                                                   | Get thumbnail URL                                                                                                |
| `renameItem`        | `item: FileSystemItem`, `newName: string`                                                                                                                                                                                            | `FileSystemItemUpdate`                                                     | Rename file/folder                                                                                               |
| `deleteItem`        | `item: FileSystemItem`                                                                                                                                                                                                               | `void`                                                                     | Delete single item (moves to trash if soft delete enabled)                                                       |
| `deleteItems`       | `items: FileSystemItem[]`                                                                                                                                                                                                            | `BatchResult<never>`                                                       | Delete multiple items                                                                                            |
| `moveItem`          | `item: FileSystemItem`, `targetFolderId?: string`                                                                                                                                                                                    | `FileSystemItemUpdate`                                                     | Move single item                                                                                                 |
| `moveItems`         | `items: FileSystemItem[]`, `targetFolderId?: string`                                                                                                                                                                                 | `BatchResult<FileSystemItemUpdate>`                                        | Move multiple items                                                                                              |
| `copyItem`          | `item: FileSystemItem`, `targetFolderId?: string`                                                                                                                                                                                    | `FileSystemItemUpdate`                                                     | Copy single item                                                                                                 |
| `copyItems`         | `items: FileSystemItem[]`, `targetFolderId?: string`                                                                                                                                                                                 | `BatchResult<FileSystemItemUpdate>`                                        | Copy multiple items                                                                                              |
| `updateFile`        | `file: FileSystemItem`, `updates`: metadata object                                                                                                                                                                                   | `FileSystemItemUpdate`                                                     | Update file metadata/content                                                                                     |

##### Type Definitions

- **`MayBePromise<T>`**: `T | Promise<T>`
- **`FileSystemItem`**: File or folder object
- **`FileSystemItemUpdate`**: Item with changed fields
- **`BatchResult<T>`**: Result with success/failure details
- **`ApiPaginationResponse`**: Pagination metadata

##### Important Notes

- **Soft Delete**: When `useSoftDelete=true`, delete operations move items to `trashPath`
- **Root Folder**: Use `rootId` or empty string for root operations
- **Path Resolution**: `trashPath` and `tempPath` are resolved to actual folder IDs
- **URL Upload**: Should check if file already exists on current server
- **Cache Control**: Use `setController` for cache invalidation requests
- **Double soft delete**: If your backend already implements soft delete, keep `useSoftDelete=false`
