npm package: @letty-email/plugin
Description: Документация по установке плагина в ваше приложение
Latest version: 1.12.1

# Letty Plugin

Документация по установке плагина в ваше приложение

## Установка

### NPM-пакет

Установить пакет для развертывания плагина в своем приложении можно используя npm-пакет

#### npm

```
npm i @letty-email/plugin -E
```

#### yarn

```
yarn add @letty-email/plugin --exact
```

### HTML-script

_**Coming soon**_

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

### **Шаг 1. Импортируйте плагин**

Если используете npm-пакет

```javascript
import LettyPlugin from '@letty-email/plugin';
```

в случае встраивания плагина напрямую в html используйте объект `window`

```javascript
const LettyPlugin = window.LettyPlugin;
```

### **Шаг 2. Создание контейнера**

Чтобы редактор отобразился на вашей странице необходимо создать div-элемент с id `letty-plugin-container`

```html
<div id="letty-plugin-container"></div>
```

### **Шаг 3. Аутентификация**

Endpoint URL: `https://api.kvilla.ru`

- **Основной пользователь**

  - **Первый вход**

    1. Зарегистрируйте пользователя через `POST` `v1/register`

    ```JSON
    {
      "email": "example@example.ru",
      "password": "string",
    }
    ```

    2. Авторизуйтесь через `POST` `v1/login`

    ```JSON
    {
      "email": "example@example.ru",
      "password": "string",
    }
    ```

    и получите сессионную куку.

    3. Создайте организацию через `POST` `v1/organizations` с параметрами:

    ```JSON
    {
      "name": "string",
      "plan_id": 1,
      "with_default_project": true
    }
    ```

    в Headers нужно выставить Cookie = полученная сессия из прошлого шага.

    4. Создайте постоянный токен (API key) для организации: `POST` `/v1/organizations/{organizationID}/tokens`.

    ```JSON
      {
        "name": "string",
        "expires_at": "2025-08-26T00:16:54.409Z"
      }
    ```

    5. Сохраните API key у себя на бэкенде.
    6. Передайте ключ в редактор.

- **Саблогин**

  - **Первый вход**
    1. Если основной логин ещё не создан или не заходил — выполните шаги 1–5 для основного пользователя.
    2. Зарегистрируйте саблогин проделав шаги 1-2 для саблогина.
    3. Под авторизацией основного пользователя добавьте саблогин в организацию основного пользователя аккаунта: `POST` `/v1/organizations/{organizationID}/users`.
    ```JSON
      {
        "user_id": "ID саблогина",
        "role_id": 1
      }
    ```
    4. Создайте токен для пользователя: `POST` `/v1/organizations/{organizationID}/users/{userID}/tokens`.
    ```JSON
      {
        "name": "string",
        "expires_at": "2025-08-26T00:16:54.409Z"
      }
    ```
    5. Сохраните токен у себя бэкенде и передавайте его в редактор.

- **Повторный вход**

1.  Извлеките сохранённый API key.
2.  Передайте ключ в редактор.

### **Шаг 4. Создание плагина**

Инициализируйте редактор в JavaScript-коде:

```javascript
  import LettyPlugin from '@letty-email/plugin'

  const letty = LettyPlugin.create({
    token: "полученный токен авторизации",
    pluginId: "ID созданного плагина из ЛК",
    locale: "en" либо "ru",
  });
```

### **Шаг 5. Запуск редактора**

```javascript
letty.start({
  template: {}, // JSON-письма
  uid: 'Уникальный ID письма в вашей системе',
  templateName?: 'Название письма(если используете встроенную шапку редактора)'
});
```

## Параметры плагина

### **token**

Токен авторизации текущего клиента, который будет использоваться для получения и сохранения блоков, писем и всего, что с ними связано

### **pluginId**

Идентификатор текущей инсталляции плагина, которую вы создали и настроили в ЛК

### **on**

Объект содержащий обработчики событий редактора.

| Событие         | Описание                                                                                             | Возвращаемые параметры                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ready`         | Редактор загрузился и готов к работе                                                                 | <code>{<br>&nbsp;json: TemplateJSON;<br>&nbsp;html: string;<br>&nbsp;lastSavedTemplate: TemplateJSON;<br>&nbsp;}</code>                           |
| `error`         | Произошла ошибка                                                                                     | <code>{<br>&nbsp;message: string;<br>&nbsp;details: object\|string;<br>&nbsp;}</code>                                                             |
| `notification`  | Уведомление от редактора                                                                             | <code>{<br>&nbsp;intent: 'error' \| 'info' \| 'success' \| 'warning';<br>&nbsp;errorDetails?: object;<br>&nbsp;message: string;<br>&nbsp;}</code> |
| `autosave`      | Произошло автосохранение                                                                             | <code>{<br>&nbsp;json: TemplateJSON;<br>&nbsp;}</code>                                                                                            |
| `save`          | Произошло сохранение<br>_(Вызывается, в случае если используется внутренняя шапка редактора)_        | <code>{<br>&nbsp;json: TemplateJSON;<br>&nbsp;}</code>                                                                                            |
| `exit`          | Попытка выхода из редактора<br>_(Вызывается, в случае если используется внутренняя шапка редактора)_ | <code>{<br>&nbsp;json: TemplateJSON;<br>&nbsp;}</code>                                                                                            |
| `toggleGrid`    | Включена подсветка сетки                                                                             | <code>{<br>&nbsp;state: boolean;<br>&nbsp;}</code>                                                                                                |
| `togglePreview` | Включен предпросмотр                                                                                 | <code>{<br>&nbsp;state: boolean;<br>&nbsp;json: TemplateJSON;<br>&nbsp;html: string;<br>&nbsp;darkHTML: string;<br>&nbsp;}</code>                 |
| `toggleMenu`    | Включено меню                                                                                        | <code>{<br>&nbsp;menu: [EditorMenu](#EditorMenu) \| null;<br>&nbsp;}</code>                                                                       |
| `history`       | Добавлено изменение/Произошло перемещение по истории                                                 | <code>{<br>&nbsp;hasUndos: boolean;<br>&nbsp;hasRedos: boolean;<br>&nbsp;type: 'change'\|'undo'\|'redo'<br>&nbsp;}</code>                         |
| `uploadImage`   | В редактор пришло изображение для загрузки                                                           |                                                                                                                                                   |
| `openGallery`   | Открыта галерея                                                                                      |                                                                                                                                                   |

### **container - опциональный**

Id элемента в котором будет развернут iframe с редактором
По умолчанию `letty-plugin-container`

### **locale - опциональный**

Язык локализации редактора.
Доступные опции: `ru` и `en`
По умолчанию `ru`

### **autosave - опциональный**

Параметры автосохранения
Варианты значения: `true`, `false`, либо `{ interval: number }`
По умолчанию `true`

## Методы редактора

### `start` - Запуск редактора

```typescript
({
  template: TemplateJSON; // Шаблон письма
  uid: string; // Уникальный идентификатор письма
  templateName?: string; // Название письма для вывода во встроенной шапке редактора
}) => void
```

### `changeTemplate` - Сменить используемый шаблон

```typescript
(
  template: TemplateJSON, // Шаблон письма
  options?: {
    templateName?: string; // Название письма для вывода во встроенной шапке редактора
    uid?: string; // Уникальный идентификатор письма, на случай, если планируете сменить редактируемое письмо, а не просто контент
  },
) => void
```

### `toggleGrid` - переключить отображение сетки

Вызывает ивент `toggleGrid`

```typescript
(
  state?: boolean, // Состояние сетки. Если значение отсутствует, то выставляется противоположное текущему
) => void
```

### `togglePreview` - Переключить отображение предпросмотра

Вызывает ивент `togglePreview`

```typescript
(
  state?: boolean, // Состояние сетки. Если значение отсутствует, то выставляется противоположное текущему
) => void
```

### `toggleMenu` - Переключить меню/Выключить меню

Вызывает ивент `toggleMenu`

```typescript
(
  menu: EditorMenu | null, // Идентификатор вызываемого меню, либо null, для закрытия открытого меню
) => void
```

<a name="EditorMenu"></a>

```
EditorMenu: 'audit', 'guide', 'style', 'blocks'
```

### `toggleViewMode` - Переключить режим отображения редактора

Вызывает ивент `toggleMenu`

```typescript
(
  mode: 'desktop' | 'mobile', // Идентификатор вызываемого меню, либо null, для закрытия открытого меню
) => void
```

### `undo` - Назад по истории изменений

Вызывает ивент `history`

```typescript
() => void
```

### `redo` - Вперед по истории изменений

Вызывает ивент `history`

```typescript
() => void
```

### `save` - Асинхронный метод для сохранения текущего состояния

Возвращаемые параметры:

```typescript
{
  json: TemplateJSON,
  html: string,
}
```

### `exit` - Асинхронный метод для выхода из редактора

```typescript
{
  json: TemplateJSON,
  html: string,
}
```

### `exportContent` - Асинхронный метод для получения текущего контента письма

```typescript
{
  json: TemplateJSON,
  html: string,
}
```