<p align="left">
  <a href="https://emailmaker.ru/" target="blank"><img src="https://emcdn.ru/389992/240402_17_0uOwHpL.png" width="500" alt="EmailMaker" /></a>
</p>

# Установка

Выполните этот код в командной строке:

```cmd
$ npm i @emailmaker/emailmaker@1.0.115 -save
```

Добавьте EmailMaker plugin в ваш App config.

### Для сборщика Webpack

Импорт пакета:

```javascript
const emailMakerPlugin = require('@emailmaker/emailmaker/webpack');
```

Определение пакета в приложении:

```javascript
module.exports = {
  plugins: [new EmailmakerWebpackPlugin()],
};
```

### Для сборщика Vite

Импорт пакета:

```javascript
import emailMakerPlugin from 'emailmaker/vite';
```

Определение пакета в приложении:

```javascript
export default defineConfig({
  plugins: [emailMakerPlugin()],
});
```

# Инициализация

Импортируйте EmailMaker plugin в вашем компоненте:

```javascript
import * as emailmaker from '@emailmaker/emailmaker';
```

Параметры инициализации плагина содержат параметр `getAuthToken`. В него должна быть передана функция, которая запрашивает авторизационный OAuth токен по Client ID и Client Secret.

### Получение OAuth токена на бэкенде

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

### Создание сущности EmailMaker plugin

```javascript
emailmaker
  .init({
    getAuthToken: getAuthToken,
    element: '#test',
    content: {
      title: 'Email subject',
      html: `КОД_ПИСЬМА`,
    },
    config: {},
  })
  .then((instance) => {});
```

КОД_ПИСЬМА можно взять из <a href="https://emcdn.ru/plugin/new-email.html" target="_blank">нашего образца</a> или вставить HTML-код своего письма.

# Конфигурация

Конфигурация плагина представляет собой JSON с несколькими уровнями вложенности. В конфигурации вы можете настроить внешний вид, содержимое, с которым будет работать плагин и логику.

### element

Вы можете передать строку `element` в конфигурацию плагина. Это селектор DOM-элемента, внутри которого нужно инициализировать плагин. Если элемент не определен, приложение будет запущено в фоновом режиме.

### content

Секция `content` содержит параметры письма, которое нужно отобразить в редакторе.
В этот параметр может быть передано:

#### {string}

HTML верстка письма.

#### {object} email options

```javascript
{
	id?: string; // Уникальный ID проекта в вашей системе.
	html?: string; // HTML верстка письма.
	subject?: string; // Тема письма.
	preheader?: string; // Прехедер письма.
}
```

#### {object} full description

```javascript
{
	temlateId?: string; // ID шаблона внутри EmailMaker.
	email?: object; // email options.
	blocks?: []; // Дополнительные блоки.
	comments?: []; // Комментарии в письме.
}
```

Можно изменить содержимое в любой момент после инициализации с помощью метода `instance.show(content)`.

### config

Раздел для настройки внешнего вида и настроек редактора. Вы можете изменить конфигурацию этого раздела после инициализации, используя `emailmaker.setConfig` или `emailmaker.updateConfig`.

##### Список параметров секции config
| Параметр                               | Описание                                                                    | Значение по умолчанию |
| -------------------------------------- | --------------------------------------------------------------------------- | --------------------- |
| theme                                  | Тема плагина: light, dark.                                                  | light                 |
| autosaveTimeout                        | Задержка перед автосохранением, мс.                                         | 10000                 |
| mergeTags                              | JSON со списком динамических переменных.                                    | undefined             |
| styles                                 | Строка со стилями в формате CSS.                                            | ''                    |
|                                        |                                                                             |                       |
| headerShow                             | Ппоказ шапки.                                                               | true                  |
| headerArrowBackVisible                 | Показ стрелки "Назад".                                                      | true                  |
| headerTitleVisible                     | Показ поля "Тема".                                                          | true                  |
| headerPreheaderVisible                 | Показ поля "Прехедер".                                                      | true                  |
| historyEnabled                         | Показ кнопки "История версий".                                              | true                  |
| codeEnabled                            | Показ кнопки "Code-mode".                                                   | true                  |
| codeModeDirection                      | Режим показа редактора кода по умолчанию                                    | none|left|right|bottom|
| codeSideEnabled                        | Показ кнопки "Code-mode" в режиме, когда есть переключатель десктоп/мобайл. | true                  |
| previewIconEnabled                     | Показ кнопки "Предпросмотр".                                                | true                  |
| previewModeEnabled                     | Ссылка на Предпросмотр.                                                     | true                  |
| livePreviewEnabled                     | Показ кнопки "Тестировние в почтовиках".                                    | true                  |
| sendTestEnabled                        | Показ кнопки "Отправить тест".                                              | true                  |
| sharePreviewEnabled                    | Показ кнопки "Поделиться".                                                  | true                  |
| webversionEnabled                      | Показ ссылки на веб-версию.                                                 | true                  |
| commonStylesEnabled                    | Показ стилей контента.                                                      | true                  |
| emailResponsiveControlEnabled          | Показ переключателя адаптивности письма.                                    | true                  |
| templateNotEmAlertShow                 | Показ уведомления о том, что шаблон не из EM.                               | true                  |
|                                        |                                                                             |                       |
| emailDropdownMenuEnabled               | Показ меню письма.                                                          | true                  |
| emailDropdownMenuClone                 | Показ пункта "Клонировать".                                                 | true                  |
| emailDropdownMenuImport                | Показ пункта "Импортировать".                                               | true                  |
| emailDropdownMenuImportButton          | Показ пункта "Импортировать" кнопкой                                        | true                  |
| emailDropdownMenuLock                  | Показ пункта "Заблокировать".                                               | true                  |
| emailDropdownMenuRemove                | Показ пункта "Удалить".                                                     | true                  |
|                                        |                                                                             |                       |
| emailExportEnabled                     | Показ кнопки "Экспорт".                                                     | true                  |
| exportHtmlEnabled                      | Экспорт в HTML.                                                             | true                  |
| exportZipEnabled                       | Экспорт в ZIP.                                                              | true                  |
| exportClipboardEnabled                 | Экспорт в буфер.                                                            | true                  |
| exportWebHookEnabled                   | Экспорт в вебхук.                                                           | true                  |
| exportOutlookEnabled                   | Экспорт в Outlook.                                                          | true                  |
| exportPdfEnabled                       | Экспорт в PDF.                                                              | true                  |
| exportPngEnabled                       | Экспорт в PNG.                                                              | true                  |
|                                        |                                                                             |                       |
| nextButtonEnabled                      | Показ второстепенной кнопки.                                                | false                 |
| nextButtonText                         | Текст на второстепенной кнопке.                                             | ''                    |
| saveButtonEnabled                      | Показ основной кнопки.                                                      | true                  |
| saveButtonText                         | Текст основной кнопки.                                                      | true                  |
| commandButtonsEnabled                  | Показ основной и второстепенной кнопки.                                     | true                  |
|                                        |                                                                             |                       |
| sidePanelFloating                      | Плавающая боковая панель.                                                   | true                  |
| desktopMobileSwitchRule                | Полоса переключения режимов.                                                | true                  |
| desktopMobileSwitchPanel               | Панель переключения режимов.                                                | false                 |
| onlyCodeModeInMobile                   | вывод в мобиле только кода.                                                 | false                 |
|                                        |                                                                             |                       |
| pathEnabled                            | Показ хлебных крошек.                                                       | true                  |
| copyPasteEnabled                       | Показ копирования-вставки блока в iframe.                                   | true                  |
| saveBlockEnabled                       | Показ кнопки сохранения блока.                                              | true                  |
| editImageControlEnabled                | Показ кнопки редактирования изображения.                                    | true                  |
|                                        |                                                                             |                       |
| menuDirection                          | Расположение боковой панели.                                                | 'right'               |
| defaultBuildPanel                      | Настройка открывающейся вкладки по умолчанию.                               | ''/'empty'/'project'/'common'/'template'                 |
| commentsEnabled                        | Показ кнопки "Комментарии".                                                 | true                  |
| aiAssistentEnabled                     | Показ "AI ассистента".                                                      | true                  |
| optimizeEnabled                        | Показ кнопки "Оптимизация".                                                 | true                  |
| optimizeLinksEnabled                   | Показ проверки ссылок.                                                      | true                  |
| optimizeImagesEnabled                  | Показ проверки картинок.                                                    | true                  |
| optimizeSpamAssassinEnabled            | Показ проверки SpamAssassin.                                                | true                  |
| optimizeCheckCodeEnabled               | Показ проверки кода.                                                        | true                  |
| settingsEnabled                        | Показ кнопки "Настройки".                                                   | true                  |
| UTMEnabled                             | Показ таба UTM-метки.                                                       | true                  |
| descriptionEnabled                     | Показ поля "Описание" в настройках.                                         | true                  |
| tagsEnabled                            | Показ поля Теги в настройках.                                               | true                  |
| switchDesktopMobilePropsEnabled        | Показ переключателя мобильных свойств.                                      | true                  |
| stepToOtherElementEnabled              | Показ кнопок перехода к другим элементам.                                   | true                  |
| deleteButtonEnabled                    | Показ кнопки удаления элемента.                                             | true                  |
| toggleSidePanel                        | Возможность схлопывать боковую панель.                                      | true                  |
| blocksSectionsShow                     | Показ меню блоков.                                                          | true                  |
| blocksEmptyEnabled                     | Показ пустых блоков.                                                        | true                  |
| blocksSavedEnabled                     | Показ сохранённых блоков.                                                   | true                  |
| blocksCommonEnabled                    | Показ общих блоков.                                                         | true                  |
| blocksTemplateEnabled                  | Показ блоков шаблона.                                                       | true                  |
| blocksSearchEnabled                    | Показ поиска по блокам.                                                     | true                  |
| blocksAddPanelEnabled                  | Показ панели добавления блока в визуальном редакторе.                       | true                  |
| imagePathDropdownEnabled               | Показ выпадашки с путём к изображению.                                      | true                  |
|                                        |                                                                             |                       |
| formFieldImageTitleEnabled             | Показ поля title в форме картинки.                                          | true                  |
| formFieldBorderEnabled                 | Показ полей изменения рамки.                                                | true                  |
| formFieldBorderRadiusEnabled           | Показ полей изменения скругления.                                           | true                  |
| formFieldBoxShadowEnabled              | Показ полей изменения тени.                                                 | true                  |
| formFieldVisibilityEnabled             | Показ кнопок изменения видимости элемента.                                  | true                  |
| formFieldExportAsPictureEnabled        | Показ переключателя экспорт в картинку.                                     | true                  |
|                                        |                                                                             |                       |
| formButtonFieldInsertImageEnabled      | Показ кнопки вставки изображения в текст у кнопки.                          | true                  |
| formButtonFieldVerticalAlignEnabled    | Показ кнопок вертикального выравнивания у кнопки.                           | true                  |
| formButtonFieldTextAlignEnabled        | Показ кнопок выравнивания текста у кнопки.                                  | true                  |
| formButtonFieldBackgroundImageEnabled  | Показ полей фонового изображения у кнопки.                                  | true                  |
| formButtonFieldPaddingsEnabled         | Показ полей внутренних отступов у кнопки.                                   | true                  |
| formButtonFieldReplacerEnabled         | Показ реплейсера у кнопки.                                                  | true                  |
|                                        |                                                                             |                       |
| formCellFieldVerticalAlignEnabled      | Показ кнопок вертикального выравнивания у ячейки.                           | true                  |
| formCellFieldBackgroundImageEnabled    | Показ полей фонового изображения у ячейки.                                  | true                  |
| formCellFieldPaddingsEnabled           | Показ полей внутренних отступов у ячейки.                                   | true                  |
| formCellFieldSizeEnabled               | Показ полей ширины и высоты.                                                | true                  |
|                                        |                                                                             |                       |
| formImageFieldVerticalAlignEnabled     | Показ кнопок вертикального выравнивания у картинки.                         | true                  |
| formImageFieldReplacerEnabled          | Показ кнопок вертикального выравнивания у картинки.                         | true                  |
| formImageFieldHeightEnabled            | Показ поля высоты у картинки.                                               | true                  |
|                                        |                                                                             |                       |
| formTableFieldBackgroundImageEnabled   | Показ полей фонового изображения у таблицы.                                 | true                  |
| formDivFieldBackgroundImageEnabled     | Показ полей фонового изображения у контейнера.                              | true                  |
| formEmailFieldBackgroundImageEnabled   | Показ полей фонового изображения у письма.                                  | true                  |
|                                        |                                                                             |                       |
| formTextFieldTypografEnabled           | Показ кнопки типографа.                                                     | true                  |
| formTextFieldReplacerEnabled           | Показ кнопки реплейсера.                                                    | true                  |
|                                        |                                                                             |                       |
| elementImageEnabled                    | Элемент Картинка.                                                           | true                  |
| elementTextEnabled                     | Элемент Текст.                                                              | true                  |
| elementHeaderEnabled                   | Элемент Заголовок.                                                          | true                  |
| elementButtonEnabled                   | Элемент Кнопка.                                                             | true                  |
| elementListULEnabled                   | Элемент Список UL.                                                          | true                  |
| elementListOLEnabled                   | Элемент Список OL.                                                          | true                  |
| elementDividerEnabled                  | Элемент Разделитель.                                                        | true                  |
| elementSpacerEnabled                   | Элемент Отступ.                                                             | true                  |
| elementSocialEnabled                   | Элемент Соцсети                                                             | true                  |
| elementTableEnabled                    | Элемент Таблица.                                                            | true                  |
| elementCountdownEnabled                | Элемент Счётчик.                                                            | true                  |
| elementVideoEnabled                    | Элемент Видео.                                                              | true                  |
| elementAIimageEnabled                  | Элемент AI картинка.                                                        | true                  |
| elementAItextEnabled                   | Элемент AI текст.                                                           | true                  |
| elementCarouselEnabled                 | Элемент AMP карусель.                                                       | true                  |
| elementAccordionEnabled                | Элемент AMP аккордион.                                                      | true                  |
| elementFormEnabled                     | Элемент AMP форма.                                                          | true                  |
|                                        |                                                                             |                       |
| imageCenterLocalUploadEnabled          | Поле загрузки файла с компьютера в Image Center.                            | true                  |
| imageCenterStockEnabled                | Таб Стока фотографий.                                                       | true                  |
| imageCenterGifEnabled                  | Таб Стока гифок.                                                            | true                  |
| imageCenterEditorEnabled               | Таб редактора изображений.                                                  | true                  |
| compressMaxSize                        | Макс. вес картинки после оптимизации, Мб.                                   | true                  |
| compressMaxWidthOrHeight               | Макс. ширина картинки после оптимизации, px.                                | true                  |
### Обработка событий

События могут быть переданы в конфигурации или добавлены после при работе с экземпляром плагина. Все подписчики событий могут быть асинхронными функциями.

#### Пример

```javascript
emailmaker.init({
	....,
	// Подписка на события в инициализации.
	handleReadEmail: (e) => {},
	handleSaveEmail: async (e) => {}
}).then((instance) => {
	// Подписка на события после инициализации.
	const dispose = instance.handleReadEmail(e => {});
	const dispose = instance.handleSaveEmail(async (e) => {});
});
```

Передавая асинхронную функцию, вы можете реализовать асинхронную загрузку данных.

#### Пример

```javascript
emailmaker.init({
	element: "#test",
	content: {
		id: "1"
	}
	handleReadEmail: async (id) => {
		return await  fetchData(id); // Ваша функция получения данных.
	}
}).then((instance) => {
	setTimeout(() => instance.show({ id: "2" }), 1000)
});
```

### События

| Обработчик события        | Описание                                   |
| ------------------------- | ------------------------------------------ |
| handleReadEmail           | Чтение письма                              |
| handleSaveEmail           | Сохранение / обновление письма             |
| handleReadEmailRevisions  | Чтение списка автосохранений               |
| handleEmailAutosave       | Автосохранение                             |
| handleReadBlocks          | Чтение списка блоков проекта               |
| handleSaveBlock           | Сохранение / обновление блока проекта      |
| handleRemoveBlock         | Удаление блока проекта                     |
| handleReadComments        | Чтение списка комментариев письма          |
| handleSaveComment         | Сохранение / обновление комментария        |
| handleRemoveComment       | Удаление комментария письма                |
| handleSaveButtonClick     | Нажатие кнопки сохранения письма           |
| handleNextButtonClick     | Нажатие кнопки Далее                       |
| handlePreviousButtonClick | Нажатие кнопки Назад                       |
| handleEmailChanged        | Изменение любого параметра письма          |
| handleHtmlChanged         | Изменение кода письма                      |
| handleDestroy             | Деструкция плагина                         |
| handleLoad                | Окончание инициализации экземпляра плагина |
| handleLoadImage           | Загрузка изображений                       |
| handleNotify              | Уведомление                                |
| handleError               | Уведомление типа Ошибка                    |
| handleSuccess             | Уведомление типа Успех                     |
| handleTestEmailSend       | Отправка тестового письма                  |
| handleTestEmailModal      | Открытие модального окна тестового письма  |

### Методы

| Метод             | Описание                                  |
| ----------------- | ----------------------------------------- |
| init              | Инициализация (async)                     |
| show              | Изменение содержимого после инициализации |
| destroy           | Деструкция экземпляра                     |
| reset             | Сброс всей конфигурации                   |
| getEmail          | Получение текущего письма                 |
| getConfig         | Получение конфигурации                    |
| getBlocks         | Получение блоков проекта                  |
| getComments       | Получение комментариев письма             |
| getEmailRevisions | Получение списка контроля версий          |
| setConfig         | Установка новых парамеров config          |
| updateConfig      | Добавление к параметрам config            |
| notify            | Показ уведомлений                         |
| getElement        | Получение элемента инициализации          |
| save              | Сохраенние письма.                        |
| compileEmail      | Получение скопмилированного письма        |

### 📂 Файловый менеджер

Для включения файлового менеджера необходимо в конфигурации инициализации указать параметры:

```ts
emailmaker.init({
  storageProvider: ..., // реализация интерфейса StorageProvider
  config: {
    imageCenterFileManagerView: true
  }
});
```

Секция `fileManager` управляет возможностями файлового менеджера. Все поля необязательные; если не заданы или `false`, соответствующая функция отключена.

#### Basic Operations

- **enableTrash** — включает функциональность корзины для удаленных файлов. При включении файлы перемещаются в корзину вместо полного удаления. По умолчанию true
- **enableRenameFolder** — разрешает переименование папок. По умолчанию true
- **enableRenameFile** — разрешает переименование файлов. По умолчанию true
- **enableUpdateFile** — разрешает обновление содержимого или метаданных файлов. По умолчанию true
- **enableEdit** — разрешает редактирование файлов (изменение содержимого или свойств). По умолчанию true
- **enableMoveFile** — разрешает перемещение файлов между папками. По умолчанию true
- **enableMoveFolder** — разрешает перемещение папок. По умолчанию true
- **enableCopyFile** — разрешает копирование файлов. По умолчанию true
- **enableCopyFolder** — разрешает копирование папок. По умолчанию true
- **enableDelete** — разрешает удаление файлов и папок. При включенной корзине файлы перемещаются в корзину. По умолчанию true
- **multiSelect** — разрешает множественный выбор файлов и папок для групповых операций. По умолчанию true
- **defaultFolderName** — Имя папки по умолчанию
- **sortOptions** — белый список значений сортировки в дропдауне списка файлов (`'date-desc' \| 'date-asc' \| 'size-desc' \| 'size-asc' \| 'name-asc' \| 'name-desc' \| 'type-asc'`). Если не задан или массив пустой — доступны все варианты, которые отображает file-manager. Пример: `['date-desc', 'name-asc']` — скрыть сортировки по размеру и типу, если платформа их не реализует.

#### Pagination & Display

- **enablePagination** — разрешает постраничную навигацию. Если отключено, все элементы загружаются сразу. По умолчанию true

#### Client-Side Processing

- **clientSideSorting** — клиентская сортировка файлов.
  - Если `true`, применяется стандартная сортировка (по имени по возрастанию).
  - Если указана функция, она принимает текущий массив файлов, необязательные `sortBy` и `sortOrder`, и возвращает отсортированный массив.

- **clientSidePaging** — клиентская пагинация файлов.
  - Если `true`, применяется стандартная нарезка массива по `page` и `limit`.
  - Если указана функция, она принимает массив файлов, `page` и `limit`, и возвращает массив только для нужной страницы.

- **clientSideFilter** — клиентская фильтрация файлов.
  - Если `true`, применяется стандартная фильтрация по тексту `search`.
  - Если указана функция, она принимает массив файлов и необязательный `search`, и возвращает отфильтрованный массив.

#### Cache Strategy

- **cacheStrategy** — стратегия кэширования для оптимизации производительности.
  - **ttl** — время жизни кэша в миллисекундах. По умолчанию 300000 (5 минут)
  - **errorTtl** — время жизни кэша для ошибок в миллисекундах. По умолчанию 60000 (1 минута)
  - **allowSortedInsert** — разрешает вставку элемента в отсортированный массив без полной инвалидации кэша. По умолчанию false
  - **allowSearchInsert** — разрешает вставку элемента в массив с фильтрами без полной инвалидации кэша. По умолчанию false
  - **invalidateOnPaginationFull** — если страница полная, кэш помечается как устаревший при вставке нового элемента. По умолчанию true
  - **comparator** — функция сравнения двух файлов для сортировки. По умолчанию сравнение по имени
  - **filterMatch** — функция проверки, проходит ли файл текущий фильтр. По умолчанию поиск по имени

### Интерфейс `StorageProvider`

#### Свойства

| Свойство                    | Тип       | Описание                                                    | По умолчанию |
| --------------------------- | --------- | ----------------------------------------------------------- | ------------ |
| `pathMode`                  | `boolean` | Использовать путь как идентификатор для папок               | -            |
| `rootId`                    | `string`  | Пользовательский идентификатор корневой папки               | `''`         |
| `trashPath`                 | `string`  | Путь к корзине/папке для удаленных файлов                   | -            |
| `tempPath`                  | `string`  | Путь к временной папке для загрузок                         | -            |
| `useSoftDelete`             | `boolean` | Включить программное мягкое удаление                        | `false`      |
| `ensureFolderTrailingSlash` | `boolean` | Добавлять к путям папок завершающий слэш                    | `true`       |
| `validateDuplicates`        | `boolean` | Проверка на существование при операциях с файлами и папками | -            |

#### Методы

##### Основные методы

| Метод               | Параметры                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Возвращает                                                                 | Описание                                                                                                              |
| ------------------- |   | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **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> }` | Получить список файлов и папок с фильтрацией, сортировкой, пагинацией                                                 |
| **createFolder**    | `name: string`, `parentid?: string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `FileSystemItem`                                                           | Создать новую папку                                                                                                   |
| 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`                                                     | Загрузить файл с метаданными                                                                                          |
| uploadFiles         | `request`:<br>- `items`: массив объектов:<br>&nbsp;&nbsp;&nbsp;&nbsp;- `requestId?: string` — необязательный идентификатор для сопоставления результата<br>&nbsp;&nbsp;&nbsp;&nbsp;- `name: string` — имя файла<br>&nbsp;&nbsp;&nbsp;&nbsp;- `size: number` — размер файла в байтах<br>&nbsp;&nbsp;&nbsp;&nbsp;- `type: string` — MIME-тип файла<br>&nbsp;&nbsp;&nbsp;&nbsp;- `folderId?: string \| null` — целевая папка<br>&nbsp;&nbsp;&nbsp;&nbsp;- `data: Blob \| string` — содержимое файла<br>&nbsp;&nbsp;&nbsp;&nbsp;- `extension?: string` — расширение файла<br>- `folderId?: string \| null` — папка для загрузки по умолчанию | `BatchResult<UploadFileResultData>`                                        | Загрузить несколько файлов. Порядок элементов важен — при отсутствии `requestId` результаты сопоставляются по индексу |
| **uploadFileByUrl** | `url: string`, `folderId?: string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `FileSystemItem`                                                           | Загрузить файл по URL (проверять существующие файлы)                                                                  |
| `findItemByPath`    | `path: string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `FileSystemItem \| undefined`                                              | Найти системные файлы/папки по пути                                                                                   |
| `setController`     | `controller: StorageProviderController`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `void`                                                                     | Установить контроллер управления кэшем                                                                                |
| `getFileData`       | `file: FileSystemItem`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `Blob`                                                                     | Получить содержимое файла как blob                                                                                    |
| `getUrl`            | `file: FileSystemItem`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `string`                                                                   | Получить URL для доступа к файлу                                                                                      |
| `getThumbnailUrl`   | `file: FileSystemItem`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `string`                                                                   | Получить URL миниатюры                                                                                                |
| `renameItem`        | `item: FileSystemItem`, `newName: string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `FileSystemItemUpdate`                                                     | Переименовать файл/папку                                                                                              |
| `deleteItem`        | `item: FileSystemItem`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `void`                                                                     | Удалить один элемент (перемещает в корзину при мягком удалении)                                                       |
| `deleteItems`       | `items: FileSystemItem[]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `BatchResult<never>`                                                       | Удалить несколько элементов                                                                                           |
| `moveItem`          | `item: FileSystemItem`, `targetFolderId?: string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `FileSystemItemUpdate`                                                     | Переместить один элемент                                                                                              |
| `moveItems`         | `items: FileSystemItem[]`, `targetFolderId?: string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `BatchResult<FileSystemItemUpdate>`                                        | Переместить несколько элементов                                                                                       |
| `copyItem`          | `item: FileSystemItem`, `targetFolderId?: string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `FileSystemItemUpdate`                                                     | Копировать один элемент                                                                                               |
| `copyItems`         | `items: FileSystemItem[]`, `targetFolderId?: string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `BatchResult<FileSystemItemUpdate>`                                        | Копировать несколько элементов                                                                                        |
| `updateFile`        | `file: FileSystemItem`, `updates`: объект с метаданными                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `FileSystemItemUpdate`                                                     | Обновить метаданные/содержимое файла                                                                                  |

##### Определения типов

- **`MayBePromise<T>`**: `T | Promise<T>`
- **`FileSystemItem`**: Объект файла или папки
- **`FileSystemItemUpdate`**: Элемент с измененными полями
- **`BatchResult<T>`**: Результат с деталями успеха/ошибки
- **`ApiPaginationResponse`**: Метаданные пагинации

##### Важные примечания

- **Мягкое удаление**: Когда `useSoftDelete=true`, операции удаления перемещают элементы в `trashPath`
- **Корневая папка**: Используйте `rootId` или пустую строку для операций с корневой папкой
- **Разрешение путей**: `trashPath` и `tempPath` преобразуются в реальные идентификаторы папок
- **Загрузка по URL**: Должна проверять, существует ли файл уже на текущем сервере
- **Управление кэшем**: Используйте `setController` для запросов инвалидации кэша
- **Двойное мягкое удаление**: Если бэкенд уже реализует мягкое удаление, оставьте `useSoftDelete=false`
