flamerest 1.0.125 → 1.0.128

package/README.md

@@ -18,6 +18,31 @@ import FLAMEREST from "flamerest";
 window.REST = new FLAMEREST('localhost');
 ```
 
+## Callbacks
+
+### Unauthorized Callback
+Обработка 401 ошибок (неавторизован):
+```javascript
+const rest = new FLAMEREST('https://api.example.com', undefined, () => {
+    // Пользователь не авторизован - перенаправляем на страницу входа
+    window.location.href = '/login';
+});
+```
+
+### Maintenance Callback
+Обработка 503 ошибок (сервер на обслуживании):
+```javascript
+const rest = new FLAMEREST('https://api.example.com', undefined, undefined, 'v1', (errorMessage) => {
+    // Сервер на обслуживании
+    if (errorMessage) {
+        alert(`Сервер временно недоступен: ${errorMessage}`);
+    } else {
+        alert('Сервер временно недоступен. Попробуйте позже.');
+    }
+    // Можно показать модальное окно с сообщением об обслуживании
+});
+```
+
 # Create and Update
 
 Just field list, but any field can be HTML Input [type=file], Clipboard object, DataTransfer [Drag&Drop/Clipboard] or FileList (automatically upload any of that)

package/REST.d.ts

@@ -0,0 +1,301 @@
+/**
+ * Базовый ответ от сервера
+ */
+export declare type BaseResponse<T> = {
+    type: string;
+    status: number;
+    ok: boolean;
+    data?: T;
+    errors: object | undefined;
+    message: string | undefined;
+};
+/**
+ * Часть ответа с пагинацией
+ */
+export declare type Paginated = {
+    pages: {
+        page: number;
+        perPage: number;
+        count: number;
+        total: number;
+    };
+};
+/**
+ * Стандартный ответ от Request с несколькими строками
+ */
+export declare type Rows<T> = BaseResponse<Array<T>> & Paginated;
+export declare type Row<T> = BaseResponse<T> & Paginated;
+export declare type CustomRequest<T> = BaseResponse<T>;
+export declare type CustomAnyRequest = BaseResponse<any>;
+/**
+ * Стандартный ответ от Request с изменённой строкой
+ */
+export declare type SavedObject<T> = BaseResponse<T>;
+/**
+ * Элемент баланса пользователя
+ */
+export interface BalanceItem {
+    name: string;
+    balance_decimal: string;
+    value: number;
+}
+/**
+ * Результат авторизации
+ */
+export declare type Authorized = {
+    isAuthorized: boolean;
+    User: {
+        avatar: string;
+        country: string;
+        id: number;
+        lang: string;
+        name: string;
+        role: string;
+        user_hash?: string;
+        balance: 0;
+        balance_all: {
+            [key: string]: BalanceItem;
+        };
+    };
+    errors: {
+        [key: string]: any;
+    };
+    token: string;
+};
+export declare class FLAMEREST {
+    /**
+     * Адрес серва
+     */
+    SERVER: string;
+    /**
+     * Стандартное число запросов на страницу
+     */
+    perPageDefault: number;
+    /**
+     * Будет вызван, если любой из запросов вернут требование авторизоваться
+     */
+    unauthorized_callback: (() => void) | undefined;
+    /**
+     * Будет вызван, если сервер вернёт статус 503 (Service Unavailable / Maintenance)
+     * Может содержать сообщение об ошибке из JSON ответа
+     */
+    maintenance_callback: ((errorMessage?: string) => void) | undefined;
+    /**
+     * Токен приложения конкретного клиента для отправки пуш уведомлений именно ему
+     */
+    pushNotificationToken: string | null;
+    /**
+     * Версия api
+     */
+    version: string;
+    /**
+     * Версия кода клиента (отправляется в заголовке каждого запроса).
+     * Можно установить извне: REST.VERSION_CODE = "1.2.3"
+     */
+    VERSION_CODE: string;
+    /**
+     * Если авторизация по токену, то он сюда подставляется
+     */
+    isAuthByJWTQuery: boolean;
+    /**
+     * Режим авторизации: Bearer|Link
+     */
+    authMode: "Bearer" | "Link";
+    token: string | null;
+    /**
+     * Конструктор класса FLAMEREST
+     * @param {string} server_address Адрес сервера (опционально)
+     * @param {string} localhost_endpoint Альтернативный адрес для localhost (опционально)
+     * @param {Function} unauthorized_callback Колбек для обработки 401 ошибок (опционально)
+     * @param {string} version Версия API (по умолчанию 'v1')
+     * @param {Function} maintenance_callback Колбек для обработки 503 ошибок (опционально)
+     */
+    constructor(server_address?: string, localhost_endpoint?: string, unauthorized_callback?: () => void, version?: string, maintenance_callback?: (errorMessage?: string) => void);
+    /**
+     * Установка плагина для Vue
+     * @param Vue
+     * @param options
+     */
+    install(Vue: any, options: any): void;
+    /**
+     *
+     * @param {string} url Адрес
+     * @param {object|string|FormData} params Параметры, которые надо передать, могут быть в виде объекта или строки
+     * @param {string} type Тип
+     * @param {string} responseType Тип ответа: json или blob
+     * @param {boolean} isNeedToken нужен ли токен для запроса
+     * @param {Object} customHeaders объект с доп заголовками, которые надо включить в запрос
+     */
+    request(url: string, params: object | string | FormData, type?: 'GET' | 'POST' | 'PUT' | 'DELETE', responseType?: 'json' | 'blob', isNeedToken?: boolean, customHeaders?: Record<string, string>): Promise<BaseResponse<any> & Partial<Paginated>>;
+    /**
+     * Получить выборку из таблицы через REST
+     * @param {string} table
+     * @param {object | string | null} where Позволяет делать выборку из связанных таблиц, надо только их указать через название таблицы sites.id=5, и указать колонку в expand
+     * @param {object | Array<string> | null} extfields
+     * @param {object | Array<string> | string | null} fields
+     * @param {object | Array<string> | string | null} sortfields
+     * @param {number | undefined} page
+     * @param {number | undefined} perPage
+     * @param {boolean | undefined} RemoveDuplicates
+     * @param {any} titles Это чтобы мы могли контроллить какие названия полей мы будет загружать при экспорте, чтобы они были как в таблице
+     * @param {any} tree дерево
+     * @param {any} params Доп параметры для кастомизации запроса на беке
+     * @param {any} exportData имя файла для экспорта
+     * @return Promise<Rows<T>>
+     */
+    get<T>(table: string, where?: object | string | null, extfields?: object | Array<string> | null, fields?: object | Array<string> | string | null, sortfields?: object | Array<string> | string | null, page?: number, perPage?: number, RemoveDuplicates?: boolean, format?: any, titles?: any, tree?: any, params?: any, exportData?: any): Promise<Rows<T>>;
+    /**
+     * Получить все записи по запросу [постранично]
+     * @param {string} table
+     * @param {object} params
+     * @returns {Promise<Rows<T>>}
+     */
+    all<T>(table: string, params?: {
+        where?: object;
+        extfields?: object | Array<string>;
+        fields?: object | Array<string>;
+        sort?: Array<string>;
+        page?: number;
+        perPage?: number;
+        tree?: number;
+        params?: any;
+        export?: {
+            format?: 'xlsx' | 'csv';
+            titles?: Array<string>;
+            filename?: string;
+        };
+    }): Promise<Rows<T>>;
+    /**
+       * Получить одну запись по ID или по условию выборки [первая запись]
+       * @param {string} table
+       * @param {number|string|object} IDOrWhere
+       * @param {object|Array} extfields
+       * @param {object|Array} fields
+       * @param {string} primaryKeyName если указан ID, то указать название первичного ключа, если от id он отличается
+     */
+    one<T>(table: string, IDOrWhere: number | string | object, extfields?: object | Array<string> | null, fields?: object | Array<string> | null, primaryKeyName?: string): Promise<T | null>;
+    /**
+     * Создать новую запись
+     * @param {string} table
+     * @param {object} values
+     * @param {number|string|null} appendTo
+     * @param {number|string|null} insertAfter
+     * @param {boolean|null} insertFirst
+     */
+    create<T>(table: string, values: object, appendTo?: number | string | null, insertAfter?: number | string | null, insertFirst?: number | string | null): Promise<SavedObject<T>>;
+    /**
+     * Удалить запись
+     * @param {string} table
+     * @param {number|string} id
+     * @param {object|null} byFields Если указан, удаляет по этим параметрам
+     */
+    remove(table: string, id?: number | string, byFields?: object | null): Promise<boolean | any>;
+    /**
+     * Редактировать значения
+     * @param {string} table
+     * @param {number|string} ID
+     * @param {object} values
+     * @param {number|string|null} appendTo
+     * @param {number|string|null} insertAfter
+     * @param {boolean|null} insertFirst
+     */
+    edit<T>(table: string, ID: number | string, values: object, appendTo?: number | string | null, insertAfter?: number | string | null, insertFirst?: number | string | null): Promise<SavedObject<T>>;
+    /**
+     * Получить схемы всех таблиц
+     */
+    getCRUDInfo(): Promise<object>;
+    /**
+     * Авторизоваться
+     * @param {string|undefined} username
+     * @param {string|undefined} password
+     * @param {object|string|null} pushNotificationToken
+     */
+    auth(username?: string, password?: string, pushNotificationToken?: object | string | null): Promise<Authorized>;
+    /**
+     * Зарегистрироваться с этим логином и паролем
+     * @param {string|null} email
+     * @param {string|null} username
+     * @param {string} password
+     * @param {string|null} name
+     * @param {object|string|null} pushNotificationToken
+     * @param {any} data
+     */
+    signup(email: string | null, username: string | null, password: string, name?: string | null, pushNotificationToken?: object | string | null, data?: any): Promise<Authorized>;
+    /**
+     * Выйти из системы
+     */
+    logout(): Promise<object>;
+    /**
+     * Восстановление пароля
+     * Запрос на восстановление пароля
+     * @param {*} email
+     * @returns
+     */
+    ResetPasswordRequest(email: string): Promise<any>;
+    /**
+     * Восстановление пароля
+     * Проверка токена восстановления
+     * @param {*} token токен подтверждения
+     * @returns
+     */
+    ResetPasswordTokenCheck(token: string): Promise<any>;
+    /**
+     * Восстановление пароля
+     * Сохранение нового пароля
+     * @param {*} token
+     * @param {*} password
+     * @returns
+     */
+    ResetPasswordSaveNewPassword(token: string, password: string): Promise<any>;
+    /**
+     * Подготовить объект под загрузку: загрузить данные из элементов Input [type=file] / Clipboard / DataTransfer [Drag&Drop/Clipboard]
+     * @param {object} values
+     */
+    prepare(values: {
+        [key: string]: any;
+    }, asFormData?: boolean): Promise<any>;
+    /**
+     * Прочесть файл асинхронно
+     * @param {File} file
+     * @param {'data' | 'text'} readAs
+     * @returns {Promise<string>}
+     */
+    readFileAsync(file: File, readAs?: 'data' | 'text'): Promise<string | ArrayBuffer | null>;
+    /**
+     * Заполнить существующий объект пришедшими из БД данными
+     * сохраняя при этом оригинальные классы и функции
+     * @param {*} object
+     * @param {*} values
+     */
+    fillObject<T extends object>(object: T, values: any): T;
+    generateID(length: number): string;
+    /**
+     * Вычисляет на лету детерминированную строку, которая будет использоваться как часть ключа для подписи.
+     * Ключ генерируется на основе последовательности числовых преобразований, что делает его неочевидным
+     * при статическом анализе кода. Этот метод всегда возвращает один и тот же результат.
+     * @returns {string} Детерминированно сгенерированная строка.
+     */
+    getDeterministicKeyPart(): string;
+    /**
+     * Создаёт подпись для запроса на основе его параметров, используя лучшие практики.
+     * Собирает все GET и POST параметры, сортирует их и формирует каноническую строку для хеширования.
+     * @param url URL запроса, включая GET-параметры.
+     * @param params POST-параметры запроса (в виде объекта).
+     * @returns Promise<string> Строка подписи.
+     */
+    private _generateRequestSignature;
+    /**
+     *
+     * @param {string} data
+     * @param {string} key
+     * @returns
+     */
+    hmac_sha256(message: BodyInit | null | undefined, secret_key: string): Promise<string>;
+}
+/**
+ * Экземпляр-синглтон класса FLAMEREST.
+ * Используйте его для всех запросов в приложении.
+ * `import REST from './REST.ts';`
+ */
+declare const REST: FLAMEREST;
+export default REST;