umbot
Version:
Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф
264 lines (263 loc) • 10.7 kB
TypeScript
import { IVkApi, IVkDocSave, IVkParams, IVkParamsUsersGet, IVkPhotosSave, IVKSendMessage, IVkUploadFile, IVkUploadServer, IVkUsersGet, TVkDocType, TVkPeerId } from './interfaces';
import { AppContext, Request } from '../../../index';
/**
* Класс для взаимодействия с API ВКонтакте
* Предоставляет методы для отправки сообщений, загрузки файлов и работы с другими функциями API
* @see (https://vk.ru/dev/bots_docs) Смотри тут
*
* @example
* ```ts
* import { VkRequest } from './api/VkRequest';
*
* // Создание экземпляра
* const vk = new VkRequest();
* vk.initToken('your-vk-token');
*
* // Отправка простого сообщения
* await vk.messagesSend(12345, 'Привет!');
*
* // Отправка сообщения с клавиатурой
* const keyboard = {
* one_time: true,
* buttons: [[{
* action: {
* type: 'text',
* label: 'Кнопка',
* payload: '{"button": 1}'
* },
* color: 'primary'
* }]]
* };
*
* await vk.messagesSend(12345, 'Выберите действие:', {
* keyboard: JSON.stringify(keyboard)
* });
*
* // Загрузка и отправка фото
* const server = await vk.photosGetMessagesUploadServer(12345);
* if (server) {
* const upload = await vk.upload(server.upload_url, 'path/to/photo.jpg');
* if (upload) {
* const photo = await vk.photosSaveMessagesPhoto(
* upload.photo,
* upload.server,
* upload.hash
* );
* if (photo) {
* await vk.messagesSend(12345, 'Фото:', {
* attachments: [`photo${photo.owner_id}_${photo.id}`]
* });
* }
* }
* }
* ```
*/
export declare class VkRequest {
#private;
/**
* Экземпляр класса для выполнения HTTP-запросов
*/
protected _request: Request;
/**
* Текст последней возникшей ошибки
*/
protected _error: object | string | null;
/**
* Токен доступа к VK API
*/
token: string | null;
/**
* Флаг для прямой передачи содержимого файла
* По умолчанию: false
*/
isAttachContent: boolean;
/**
* Контекст приложения.
*/
protected _appContext: AppContext;
/**
* Создает экземпляр класса для работы с API ВКонтакте
* Устанавливает токен из конфигурации приложения, если он доступен
*/
constructor(appContext: AppContext);
/**
* Инициализирует токен доступа к VK API
* @param token Токен доступа к VK API
*/
initToken(token: string): void;
/**
* Выполняет вызов метода VK API
* @param method Название метода VK API
* @returns Результат выполнения метода или null при ошибке
*/
call<T extends IVkApi>(method: string): Promise<T | null>;
/**
* Загружает файл на сервера ВКонтакте
* @param url URL для загрузки файла
* @param file Путь к файлу или его содержимое
* @returns Информация о загруженном файле или null при ошибке
*
* @remarks
* Для фотографий возвращает:
* - photo: строка, содержащая информацию о фото
* - server: строка, идентификатор сервера
* - hash: строка, хеш загруженного файла
*
* Для документов возвращает:
* - file: строка, информация о загруженном файле
*
* @example
* ```ts
* // Загрузка фото
* const server = await vk.photosGetMessagesUploadServer(12345);
* if (server) {
* const upload = await vk.upload(server.upload_url, 'photo.jpg');
* if (upload) {
* const photo = await vk.photosSaveMessagesPhoto(
* upload.photo,
* upload.server,
* upload.hash
* );
* }
* }
*
* // Загрузка документа
* const server = await vk.docsGetMessagesUploadServer(12345, 'doc');
* if (server) {
* const upload = await vk.upload(server.upload_url, 'document.pdf');
* if (upload) {
* const doc = await vk.docsSave(
* upload.file,
* 'Документ',
* 'тег1,тег2'
* );
* }
* }
* ```
*/
upload(url: string, file: string): Promise<IVkUploadFile | null>;
/**
* Отправляет сообщение пользователю или в чат
* @param peerId Идентификатор получателя:
* - ID пользователя (например, "12345")
* - ID чата: 2000000000 + chat_id (например, для чата 1: 2000000001)
* - ID сообщества: -ID сообщества (например, "-123456789")
* @param message Текст сообщения
* @param params Дополнительные параметры:
* - random_id: уникальный ID для избежания повторов
* - attachment: медиавложения в формате "<type><owner_id>_<media_id>"
* Примеры:
* - Фото: "photo123456_789"
* - Документ: "doc123456_789"
* - Аудио: "audio123456_789"
* - Видео: "video123456_789"
* - keyboard: клавиатура в JSON формате или строкой
* - template: шаблон карусели в JSON формате или строкой
*
* @example
* ```ts
* // Простое сообщение
* await vk.messagesSend(12345, 'Привет!');
*
* // Сообщение с вложениями
* await vk.messagesSend(12345, 'Фото:', {
* attachments: ['photo123_456', 'doc123_456']
* });
*
* // Сообщение с клавиатурой
* const keyboard = {
* one_time: true,
* buttons: [[{
* action: {
* type: 'text',
* label: 'Кнопка',
* payload: '{"button": 1}'
* },
* color: 'primary'
* }]]
* };
* await vk.messagesSend(12345, 'Выберите:', {
* keyboard: JSON.stringify(keyboard)
* });
*
* // Сообщение с каруселью
* const template = {
* type: 'carousel',
* elements: [{
* title: 'Заголовок',
* description: 'Описание',
* photo_id: '-123456_789',
* buttons: [{
* action: {
* type: 'text',
* label: 'Кнопка',
* payload: '{"button": 1}'
* }
* }]
* }]
* };
* await vk.messagesSend(12345, '', {
* template: JSON.stringify(template)
* });
* ```
*
* @returns Информация об отправленном сообщении или null при ошибке
*/
messagesSend(peerId: TVkPeerId, message: string, params?: IVkParams | null): Promise<IVKSendMessage | null>;
/**
* Получает информацию о пользователе или списке пользователей
* @param userId ID пользователя или массив ID
* @param params Дополнительные параметры запроса
* @returns Информация о пользователях или null при ошибке
*/
usersGet(userId: TVkPeerId | string[], params?: IVkParamsUsersGet | null): Promise<IVkUsersGet | null>;
/**
* Получает URL для загрузки фотографий в сообщения
* @param peerId ID получателя сообщения
* @returns Данные для загрузки или null при ошибке
*/
photosGetMessagesUploadServer(peerId: TVkPeerId): Promise<IVkUploadServer | null>;
/**
* Сохраняет загруженную фотографию в сообщениях
* @param photo Идентификатор фотографии
* @param server Идентификатор сервера
* @param hash Хэш-сумма фотографии
* @returns Информация о сохраненной фотографии или null при ошибке
*/
photosSaveMessagesPhoto(photo: string, server: string, hash: string): Promise<IVkPhotosSave[] | null>;
/**
* Получает URL для загрузки документов в сообщения
* @param peerId ID получателя сообщения
* @param type Тип документа:
* - 'doc': обычный документ (PDF, ZIP и т.д.)
* - 'audio_message': голосовое сообщение
* - 'graffiti': граффити
* @returns Данные для загрузки или null при ошибке
*
* @example
* ```ts
* // Загрузка обычного документа
* const server = await vk.docsGetMessagesUploadServer(12345, 'doc');
*
* // Загрузка голосового сообщения
* const server = await vk.docsGetMessagesUploadServer(12345, 'audio_message');
*
* // Загрузка граффити
* const server = await vk.docsGetMessagesUploadServer(12345, 'graffiti');
* ```
*/
docsGetMessagesUploadServer(peerId: TVkPeerId, type: TVkDocType): Promise<IVkUploadServer | null>;
/**
* Сохраняет загруженный документ
* @param file Идентификатор документа
* @param title Название документа
* @param tags Теги документа
* @returns Информация о сохраненном документе или null при ошибке
*/
docsSave(file: string, title: string, tags?: string | null): Promise<IVkDocSave | null>;
/**
* Записывает информацию об ошибках в лог-файл
* @param error Текст ошибки для логирования
*/
protected _log(error?: string): void;
}