/**
 * Интерфейсы для работы с VK.
 * Определяют структуру данных для взаимодействия с VK Bot API
 *
 * Основные компоненты:
 * - Сообщения (IVkMessage)
 * - Информация о клиенте (IVkClientInfo)
 * - Объекты запросов (IVkRequestObject)
 * - Обновления (IVkRequestContent)
 */
/**
 * Сообщение VK.
 * Содержит информацию о входящем или исходящем сообщении
 */
export interface IVkMessage {
    /** Дата отправки сообщения в формате Unix timestamp */
    date?: number;
    /** ID отправителя сообщения */
    from_id: number;
    /** ID сообщения */
    id: number;
    /**
     * Тип сообщения
     * 0 - входящее
     * 1 - исходящее
     */
    out?: number;
    /** ID беседы или пользователя */
    peer_id?: number;
    /** Текст сообщения */
    text: string;
    /** ID сообщения в беседе */
    conversation_message_id?: number;
    /** Массив пересланных сообщений */
    fwd_messages?: string[];
    /** Является ли сообщение важным */
    important?: boolean;
    /** Уникальный идентификатор сообщения */
    random_id?: number;
    /** Вложения (фото, видео, документы и т.д.) */
    attachments?: Record<string, unknown>;
    /** Скрыто ли сообщение */
    is_hidden?: boolean;
    /** Дополнительные данные */
    payload?: Record<string, unknown>;
}
/**
 * Информация о клиенте.
 * Содержит данные о возможностях клиента
 */
export interface IVkClientInfo {
    /** Поддерживаемые действия с кнопками */
    button_actions: string[];
    /** Поддерживает ли клиент клавиатуру */
    keyboard: boolean;
    /** Поддерживает ли клиент inline-клавиатуру */
    inline_keyboard: boolean;
    /** ID языка клиента */
    lang_id: number;
}
/**
 * Объект запроса VK.
 * Содержит информацию о сообщении и клиенте
 */
export interface IVkRequestObject {
    /** Информация о сообщении */
    message: IVkMessage;
    /** Информация о клиенте */
    clientInfo?: IVkClientInfo;
    /**
     * Идентификатор пользователя.
     */
    user_id?: number;
    /**
     * Идентификатор диалога со стороны бота.
     */
    peer_id: number;
    /**
     * Случайная строка. Активна в течение минуты, спустя минуту становится недействительной.
     */
    event_id?: string;
    /**
     * Дополнительная информация, указанная в клавише.
     */
    payload: Record<string, unknown> | string;
    /**
     * Идентификатор сообщения в беседе. Не передаётся для клавиатур беседы.
     */
    conversation_message_id?: number;
}
/**
 * Обновление от VK.
 * Содержит информацию о типе события и связанных данных
 */
export interface IVkRequestContent {
    /** Тип события (message_new, message_event и т.д.) */
    type: string;
    /** Объект запроса с данными */
    object?: IVkRequestObject;
    /** ID группы */
    group_id?: string;
    /** ID события */
    event_id?: string;
    /** Секретный ключ для проверки подписи */
    secret?: string;
}
/**
 * @interface IVkButtonObject
 * Интерфейс для объекта, содержащего коллекцию кнопок VK.
 *
 * Используется для создания клавиатуры с кнопками в VK.
 *
 * @example
 * ```ts
 * const keyboard: IVkButtonObject = {
 *     one_time: false,
 *     buttons: [
 *         [{
 *             action: {
 *                 type: 'text',
 *                 label: 'Нажми меня'
 *             },
 *             color: 'primary'
 *         }]
 *     ]
 * };
 * ```
 */
export interface IVkButtonObject {
    /**
     * Определяет, будет ли клавиатура скрыта после нажатия на кнопку.
     * true - клавиатура скроется после нажатия
     * false - клавиатура останется видимой
     * @example
     * ```ts
     * const keyboard: IVkButtonObject = {
     *     one_time: true, // Клавиатура скроется после нажатия
     *     buttons: [...]
     * };
     * ```
     */
    one_time: boolean;
    /**
     * Массив кнопок или массив массивов кнопок.
     * Каждый внутренний массив представляет собой строку кнопок.
     * @example
     * ```ts
     * const keyboard: IVkButtonObject = {
     *     one_time: false,
     *     buttons: [
     *         // Первая строка кнопок
     *         [{
     *             action: { type: 'text', label: 'Кнопка 1' },
     *             color: 'primary'
     *         }],
     *         // Вторая строка кнопок
     *         [{
     *             action: { type: 'text', label: 'Кнопка 2' },
     *             color: 'secondary'
     *         }]
     *     ]
     * };
     * ```
     */
    buttons: IVkButton[] | IVkButton[][];
}
/**
 * @interface IVkButtonAction
 * Интерфейс для действия кнопки VK.
 *
 * Определяет тип действия, которое будет выполнено при нажатии на кнопку.
 *
 * @example
 * ```ts
 * // Текстовая кнопка
 * const textAction: IVkButtonAction = {
 *     type: 'text',
 *     label: 'Нажми меня'
 * };
 *
 * // Кнопка-ссылка
 * const linkAction: IVkButtonAction = {
 *     type: 'open_link',
 *     link: 'http://localhost',
 *     label: 'Перейти на сайт'
 * };
 * ```
 */
export interface IVkButtonAction {
    /**
     * Тип действия кнопки.
     * Возможные значения:
     * - text - текстовая кнопка
     * - open_link - кнопка-ссылка
     * - location - кнопка геолокации
     * - vkpay - кнопка оплаты
     * - open_app - кнопка открытия приложения
     * @example
     * ```ts
     * const action: IVkButtonAction = {
     *     type: 'text',
     *     label: 'Нажми меня'
     * };
     * ```
     */
    type?: string;
    /**
     * URL для перехода при нажатии на кнопку.
     * Используется только для кнопок типа open_link.
     * @example
     * ```ts
     * const action: IVkButtonAction = {
     *     type: 'open_link',
     *     link: 'http://localhost',
     *     label: 'Перейти на сайт'
     * };
     * ```
     */
    link?: string;
    /**
     * Текст, отображаемый на кнопке.
     * @example
     * ```ts
     * const action: IVkButtonAction = {
     *     type: 'text',
     *     label: 'Нажми меня'
     * };
     * ```
     */
    label?: string | null;
    /**
     * Дополнительные данные, передаваемые при нажатии на кнопку.
     * Могут быть строкой или объектом.
     * @example
     * ```ts
     * const action: IVkButtonAction = {
     *     type: 'text',
     *     label: 'Добавить в корзину',
     *     payload: {
     *         action: 'add_to_cart',
     *         productId: 123
     *     }
     * };
     * ```
     */
    payload?: string | object;
}
/**
 * @interface IVkButton
 * Интерфейс для кнопки VK.
 *
 * Определяет структуру кнопки и её визуальное представление.
 *
 * @example
 * ```ts
 * const button: IVkButton = {
 *     action: {
 *         type: 'text',
 *         label: 'Нажми меня',
 *         payload: { action: 'click' }
 *     },
 *     color: 'primary'
 * };
 * ```
 */
export interface IVkButton {
    /**
     * Действие кнопки.
     * Определяет тип действия и его параметры.
     * @example
     * ```ts
     * const button: IVkButton = {
     *     action: {
     *         type: 'text',
     *         label: 'Нажми меня'
     *     }
     * };
     * ```
     */
    action: IVkButtonAction;
    /**
     * Цвет кнопки.
     * Возможные значения:
     * - primary - основная кнопка (синяя)
     * - secondary - вторичная кнопка (белая)
     * - negative - отрицательная кнопка (красная)
     * - positive - положительная кнопка (зеленая)
     * @example
     * ```ts
     * const button: IVkButton = {
     *     action: { type: 'text', label: 'Нажми меня' },
     *     color: 'primary'
     * };
     * ```
     */
    color?: string;
    /**
     * Хеш кнопки.
     * Используется для верификации кнопки.
     * @example
     * ```ts
     * const button: IVkButton = {
     *     action: { type: 'text', label: 'Нажми меня' },
     *     hash: 'abc123'
     * };
     * ```
     */
    hash?: string | null;
    /**
     * Дополнительные данные кнопки.
     * Могут содержать любую информацию.
     * @example
     * ```ts
     * const button: IVkButton = {
     *     action: { type: 'text', label: 'Нажми меня' },
     *     payload: {
     *         customData: 'value'
     *     }
     * };
     * ```
     */
    payload?: Record<string, unknown>;
    /**
     * Идентификатор группы кнопки.
     * Используется для группировки кнопок.
     * @example
     * ```ts
     * const button: IVkButton = {
     *     action: { type: 'text', label: 'Нажми меня' },
     *     _group: 'navigation'
     * };
     * ```
     */
    _group?: string;
}
/**
 * @interface IVkCardElement
 * Интерфейс для элемента карточки ВКонтакте.
 * Определяет структуру отдельного элемента в карусели или галерее.
 *
 * Особенности:
 * - Поддерживает заголовок и описание
 * - Может содержать до 3 кнопок
 * - Поддерживает различные типы действий
 * - Требует ID фотографии из ВКонтакте
 *
 * @example
 * ```ts
 * // Создание элемента карточки с кнопками
 * const element: IVkCardElement = {
 *     title: 'Название товара',
 *     description: 'Описание товара',
 *     photo_id: '123456789',
 *     buttons: [
 *         { action: { type: 'text', label: 'Купить' } },
 *         { action: { type: 'link', link: 'http://localhost' } }
 *     ],
 *     action: { type: 'open_photo' }
 * };
 *
 * // Создание простого элемента карточки
 * const simpleElement: IVkCardElement = {
 *     title: 'Фотография',
 *     description: 'Описание фотографии',
 *     photo_id: '987654321'
 * };
 * ```
 */
export interface IVkCardElement {
    /**
     * Заголовок элемента карточки.
     * Отображается в верхней части элемента.
     *
     * Особенности:
     * - Рекомендуемая длина: до 80 символов
     * - Поддерживает эмодзи
     * - Отображается жирным шрифтом
     *
     * @example
     * ```ts
     * title: 'Название товара'
     * title: '🔥 Горячее предложение'
     * ```
     */
    title: string;
    /**
     * Описание элемента карточки.
     * Отображается под заголовком.
     *
     * Особенности:
     * - Рекомендуемая длина: до 200 символов
     * - Поддерживает переносы строк
     * - Может содержать ссылки
     *
     * @example
     * ```ts
     * description = 'Цена: 1000 руб.\nДоставка: бесплатно'
     * ```
     */
    description: string;
    /**
     * Идентификатор изображения в ВКонтакте.
     * Формат: строка без префикса 'photo'.
     *
     * Особенности:
     * - Должен быть валидным ID фотографии
     * - Фотография должна быть загружена в ВКонтакте
     * - Поддерживает различные форматы изображений
     *
     * @example
     * ```ts
     * photo_id: '123456789'
     * photo_id: '987654321_456789'
     * ```
     */
    photo_id: string;
    /**
     * Массив кнопок для элемента карточки.
     * Максимальное количество кнопок - 3.
     *
     * Особенности:
     * - Поддерживает различные типы кнопок
     * - Каждая кнопка может иметь свое действие
     * - Кнопки отображаются в нижней части карточки
     *
     * @example
     * ```ts
     * // Кнопки с разными действиями
     * buttons: [
     *     { action: { type: 'text', label: 'Купить' } },
     *     { action: { type: 'link', link: 'http://localhost' } },
     *     { action: { type: 'callback', label: 'Подробнее' } }
     * ]
     *
     * // Одна кнопка
     * buttons: [
     *     { action: { type: 'text', label: 'Подробнее' } }
     * ]
     * ```
     */
    buttons?: IVkButton[];
    /**
     * Действие, происходящее при нажатии на элемент карточки.
     *
     * Особенности:
     * - Определяет поведение при клике на карточку
     * - Может открывать фотографию или выполнять другие действия
     * - Работает независимо от кнопок
     *
     * @example
     * ```ts
     * // Открыть фотографию
     * action: { type: 'open_photo' }
     *
     * // Выполнить действие
     * action: { type: 'callback' }
     * ```
     */
    action?: {
        /**
         * Тип действия.
         */
        type: string;
    };
}
/**
 * @interface IVkCard
 * Интерфейс для карточки ВКонтакте.
 * Определяет структуру карточки, которая может быть каруселью или галереей.
 *
 * Особенности:
 * - Поддерживает два типа карточек: карусель и галерея
 * - Может содержать множество элементов
 * - Элементы могут иметь кнопки и действия
 * - Поддерживает различные форматы изображений
 *
 * @example
 * ```ts
 * // Создание карусели с товарами
 * const carousel: IVkCard = {
 *     type: 'carousel',
 *     elements: [
 *         {
 *             title: 'Товар 1',
 *             description: 'Описание 1',
 *             photo_id: '123456789',
 *             buttons: [{ action: { type: 'text', label: 'Купить' } }]
 *         },
 *         {
 *             title: 'Товар 2',
 *             description: 'Описание 2',
 *             photo_id: '987654321',
 *             buttons: [{ action: { type: 'text', label: 'Купить' } }]
 *         }
 *     ]
 * };
 *
 * // Создание галереи фотографий
 * const gallery: IVkCard = {
 *     type: 'gallery',
 *     elements: [
 *         {
 *             title: 'Фото 1',
 *             description: 'Описание 1',
 *             photo_id: '123456789',
 *             action: { type: 'open_photo' }
 *         },
 *         {
 *             title: 'Фото 2',
 *             description: 'Описание 2',
 *             photo_id: '987654321',
 *             action: { type: 'open_photo' }
 *         }
 *     ]
 * };
 * ```
 */
export interface IVkCard {
    /**
     * Тип карточки.
     * Может быть 'carousel' для карусели или 'gallery' для галереи.
     *
     * Особенности:
     * - Карусель: элементы можно листать горизонтально
     * - Галерея: элементы отображаются в сетке
     * - Тип определяет способ отображения элементов
     *
     * @example
     * ```ts
     * // Карусель товаров
     * type: 'carousel'
     *
     * // Галерея фотографий
     * type: 'gallery'
     * ```
     */
    type: string;
    /**
     * Массив элементов карточки.
     * Каждый элемент представляет собой отдельную карточку в карусели.
     *
     * Особенности:
     * - Может содержать множество элементов
     * - Каждый элемент имеет свои настройки
     * - Элементы отображаются в зависимости от типа карточки
     *
     * @example
     * ```ts
     * // Элементы карусели
     * elements: [
     *     { title: 'Товар 1', description: 'Описание 1', photo_id: '123456789' },
     *     { title: 'Товар 2', description: 'Описание 2', photo_id: '987654321' }
     * ]
     *
     * // Элементы галереи
     * elements: [
     *     { title: 'Фото 1', description: 'Описание 1', photo_id: '123456789' },
     *     { title: 'Фото 2', description: 'Описание 2', photo_id: '987654321' }
     * ]
     * ```
     */
    elements: IVkCardElement[];
}