@egodigital/egoose/lib/apis/index.d.ts

/**
 * This file is part of the @egodigital/egoose distribution.
 * Copyright (c) e.GO Digital GmbH, Aachen, Germany (https://www.e-go-digital.com/)
 *
 * @egodigital/egoose is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, version 3.
 *
 * @egodigital/egoose is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */
/// <reference types="node" />
import { Response } from 'express';
/**
 * An entry for an API error.
 */
export interface ApiError {
    /**
     * German (de)
     */
    de?: string;
    /**
     * English (en)
     */
    en: string;
}
/**
 * An entry for an API error with a key.
 */
export interface ApiErrorWithKey extends ApiError {
    key: string;
}
/**
 * An api result.
 */
export interface ApiResult {
    /**
     * The (optional) data.
     */
    data?: any;
    /**
     * A list of one or more error keys.
     */
    errors?: string | string[];
    /**
     * A value, which indicates if the operation was successfull or not.
     */
    success: boolean;
}
/**
 * Options for 'createMonitoringApiResult()' function.
 */
export interface CreateMonitoringApiResultOptions {
    /**
     * The custom working directory.
     */
    cwd?: string;
    /**
     * An optional function, which checks a database connection.
     */
    databaseConnectionChecker?: () => boolean | PromiseLike<boolean>;
    /**
     * Use 'MemAvailable' from 'meminfo' for detecting free ram.
     */
    useMemAvailable?: boolean;
    /**
     * Also return version information about the app.
     */
    withAppVersion?: boolean;
}
/**
 * A possible value for 'importApiErrors()' and 'importApiErrorsSync()' functions.
 *
 * If STRING: The path to the JSON file to import.
 * If BUFFER: The binary content as UTF-8 JSON data.
 * If OBJECT or ARRAY: One or more items to import.
 */
export declare type ImportApiErrorsArgument = string | Buffer | ApiErrorWithKey | ApiErrorWithKey[];
/**
 * A result of a 'createMonitoringApiResult()' function call.
 */
export interface MonitoringApiResult {
    /**
     * The CPU usage in percentage.
     */
    cpu_load: number;
    /**
     * Indicates if a database connection is established or available.
     */
    database_connected?: boolean;
    /**
     * The total disk space, in bytes.
     */
    disk_space: number;
    /**
     * The total disk space in use, in bytes.
     */
    disk_space_used: number;
    /**
     * The total ram, in bytes.
     */
    ram: number;
    /**
     * The ram in use, in bytes.
     */
    ram_used: number;
    /**
     * Information about the version of the app.
     */
    version?: MonitoringApiAppVersion;
}
/**
 * Stores version information about the app for a monitoring API result.
 */
export interface MonitoringApiAppVersion {
    /**
     * The last commit date. Contains (false), if failed.
     */
    date?: string | false;
    /**
     * The last commit hash. Contains (false), if failed.
     */
    hash?: string | false;
}
/**
 * Additional options for 'sendResponse()' function.
 */
export interface SendResponseOptions {
    /**
     * A custom status code.
     */
    code?: number;
    /**
     * Returns error keys only or ApiError objects.
     */
    errorKeysOnly?: boolean;
}
/**
 * Global list of API errors.
 */
export declare const API_ERRORS: {
    [name: string]: ApiError;
};
/**
 * Creates an object for an result of a monitoring API endpoint.
 *
 * @param {CreateMonitoringApiResultOptions} [opts] Custom options.
 *
 * @return {Promise<MonitoringApiResult>} The promise with the result (object).
 */
export declare function createMonitoringApiResult(opts?: CreateMonitoringApiResultOptions): Promise<MonitoringApiResult>;
/**
 * Imports the data for 'API_ERRORS' constant.
 *
 * @param {ImportApiErrorsArgument} errors The items to import.
 */
export declare function importApiErrors(errors: ImportApiErrorsArgument): Promise<void>;
/**
 * Imports the data for 'API_ERRORS' constant (sync).
 *
 * @param {ImportApiErrorsArgument} errors The items to import.
 */
export declare function importApiErrorsSync(errors: ImportApiErrorsArgument): void;
/**
 * Sends an API response.
 *
 * @param {Response} res The response context.
 * @param {ApiResult} result The result context.
 * @param {SendResponseOptions} [opts] Custom options.
 *
 * @return {Response} The current response context.
 */
export declare function sendResponse(res: Response, result: ApiResult, opts?: SendResponseOptions): Response;