umbot
Version:
Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф
215 lines (214 loc) • 9.19 kB
TypeScript
import { VkRequest } from './VkRequest';
import { IMarusiaApiAudioUpdateLink, IMarusiaApiCreateAudio, IMarusiaApiPictureUpdateLink, IMarusiaApiRemove, IMarusiaApiSavePicture } from './interfaces';
import { AppContext } from '../../../index';
/**
* Класс для взаимодействия с API голосового помощника Маруся
* Расширяет функционал VkRequest для работы со специфичными методами Маруси
* @see (https://dev.vk.ru/ru/marusia/api) Смотри тут
*
* @example
* ```ts
* import { MarusiaRequest } from './api/MarusiaRequest';
*
* // Создание экземпляра
* const marusia = new MarusiaRequest();
* marusia.initToken('your-marusia-token');
*
* // Загрузка изображения
* async function uploadImage(imagePath: string) {
* // Получаем URL для загрузки
* const uploadLink = await marusia.marusiaGetPictureUploadLink();
* if (uploadLink) {
* // Загружаем изображение
* const upload = await marusia.upload(uploadLink.upload_url, imagePath);
* if (upload) {
* // Сохраняем изображение
* const picture = await marusia.marusiaSavePicture(
* upload.photo,
* upload.server,
* upload.hash
* );
* return picture;
* }
* }
* return null;
* }
*
* // Загрузка аудио
* async function uploadAudio(audioPath: string) {
* // Получаем URL для загрузки
* const uploadLink = await marusia.marusiaGetAudioUploadLink();
* if (uploadLink) {
* // Загружаем аудиофайл
* const upload = await marusia.upload(uploadLink.upload_url, audioPath);
* if (upload) {
* // Сохраняем аудио
* const audio = await marusia.marusiaCreateAudio(upload);
* return audio;
* }
* }
* return null;
* }
* ```
*/
export declare class MarusiaRequest extends VkRequest {
/**
* Создает экземпляр класса для работы с API Маруси
*/
constructor(appContext: AppContext);
/**
* Запрашивает URL для загрузки изображения на сервера Маруси
*
* @remarks
* Поддерживаемые форматы изображений:
* - JPEG, JPG, PNG
* - Максимальный размер: 5MB
* - Рекомендуемое разрешение: 800x800 пикселей
*
* @example
* ```ts
* // Получение URL для загрузки
* const uploadLink = await marusia.marusiaGetPictureUploadLink();
* if (uploadLink) {
* // Загрузка изображения
* const upload = await marusia.upload(uploadLink.upload_url, 'image.jpg');
* if (upload) {
* console.log('Изображение загружено:', upload);
* }
* }
* ```
*
* @returns {Promise<IMarusiaApiPictureUpdateLink | null>} Данные для загрузки изображения или null при ошибке
*/
marusiaGetPictureUploadLink(): Promise<IMarusiaApiPictureUpdateLink | null>;
/**
* Сохраняет загруженное изображение в Марусе
* @param photo Идентификатор загруженного изображения
* @param server Идентификатор сервера загрузки
* @param hash Хэш-сумма для проверки изображения
*
* @remarks
* После успешного сохранения изображение становится доступным в навыке
* и может быть использовано в карточках и других элементах интерфейса.
*
* @example
* ```ts
* // Полный процесс загрузки и сохранения изображения
* const uploadLink = await marusia.marusiaGetPictureUploadLink();
* if (uploadLink) {
* const upload = await marusia.upload(uploadLink.upload_url, 'image.jpg');
* if (upload) {
* const picture = await marusia.marusiaSavePicture(
* upload.photo,
* upload.server,
* upload.hash
* );
* if (picture) {
* console.log('ID изображения:', picture.id);
* }
* }
* }
* ```
*
* @returns {Promise<IMarusiaApiSavePicture | null>} Результат сохранения или null при ошибке
*/
marusiaSavePicture(photo: string, server: string, hash: string): Promise<IMarusiaApiSavePicture | null>;
/**
* Удаляет загруженное изображение из Маруси
* @param id Идентификатор загруженного изображения
*
* @returns {Promise<IMarusiaApiRemove | null>} Результат удаления или null при ошибке
*/
marusiaDeletePicture(id: string): Promise<IMarusiaApiRemove | null>;
/**
* Получает список всех изображений из навыка
*
* @remarks
* Метод возвращает информацию о всех изображениях, загруженных в навык:
* - id: уникальный идентификатор изображения
* - url: URL для доступа к изображению
* - preview_url: URL превью изображения
* - created: дата создания (Unix timestamp)
*
* @example
* ```ts
* // Получение списка изображений
* const pictures = await marusia.marusiaGetPictures();
* if (pictures) {
* pictures.items.forEach(picture => {
* console.log('ID:', picture.id);
* console.log('URL:', picture.url);
* console.log('Превью:', picture.preview_url);
* });
* }
* ```
*
* @returns Список изображений или null при ошибке
*/
marusiaGetPictures(): Promise<unknown>;
/**
* Запрашивает URL для загрузки аудиофайла на сервера Маруси
*
* @remarks
* Поддерживаемые форматы аудио:
* - MP3
* - Максимальный размер: 10MB
* - Максимальная длительность: 5 минут
* - Рекомендуемый битрейт: 128 kbps
*
* @example
* ```ts
* // Получение URL для загрузки
* const uploadLink = await marusia.marusiaGetAudioUploadLink();
* if (uploadLink) {
* // Загрузка аудио
* const upload = await marusia.upload(uploadLink.upload_url, 'audio.mp3');
* if (upload) {
* console.log('Аудио загружено:', upload);
* }
* }
* ```
*
* @returns {Promise<IMarusiaApiAudioUpdateLink | null>} Данные для загрузки аудио или null при ошибке
*/
marusiaGetAudioUploadLink(): Promise<IMarusiaApiAudioUpdateLink | null>;
/**
* Сохраняет загруженный аудиофайл в Марусе
* @param audio_meta Метаданные аудиофайла после загрузки
*
* @remarks
* После успешного сохранения аудиофайл становится доступным в навыке
* и может быть использован в голосовых ответах.
*
* @example
* ```ts
* // Полный процесс загрузки и сохранения аудио
* const uploadLink = await marusia.marusiaGetAudioUploadLink();
* if (uploadLink) {
* const upload = await marusia.upload(uploadLink.upload_url, 'audio.mp3');
* if (upload) {
* const audio = await marusia.marusiaCreateAudio(upload);
* if (audio) {
* console.log('ID аудио:', audio.id);
* console.log('URL аудио:', audio.url);
* }
* }
* }
* ```
*
* @returns {Promise<IMarusiaApiCreateAudio | null>} Результат сохранения или null при ошибке
*/
marusiaCreateAudio(audio_meta: object): Promise<IMarusiaApiCreateAudio | null>;
/**
* Удаляет загруженный аудиофайл из Маруси
* @param id Идентификатор загруженного аудиофайла
*
* @returns {Promise<IMarusiaApiRemove | null>} Результат удаления или null при ошибке
*/
marusiaDeleteAudio(id: string): Promise<IMarusiaApiRemove | null>;
/**
* Записывает информацию об ошибках в лог-файл
* @param error Текст ошибки для логирования
*/
protected _log(error: string): void;
}