@vandenberghinc/volt 1.2.4 → 1.2.6

package/backend/dist/cjs/backend/src/server.old.d.ts

@@ -1,594 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2022 - 2025 Daan van den Bergh.
- */
-import * as vlib from "@vandenberghinc/vlib";
-import { Meta } from './meta.js';
-import * as MailUI from './plugins/mail/ui.js';
-import { Mail } from "./plugins/mail/mail.js";
-import { Status } from "./status.js";
-import { Endpoint } from "./endpoint.js";
-import { Database } from "./database/database.js";
-import { Users } from "./users.js";
-import { Paddle, Payment } from "./payments/paddle.js";
-import { RateLimits, RateLimitServer, RateLimitClient } from "./rate_limit.js";
-import { Route } from "./route.js";
-import { EventCallback, EventName, Events } from './events.js';
-import { Stripe } from "./payments/stripe/stripe.js";
-/** Nested types for the {@link Server} class. */
-export declare namespace Server {
-    /**
-     * Options for constructing a server.
-     * @docs
-     */
-    interface Opts {
-        /** Whether the server is in production mode or in development mode. */
-        production?: boolean;
-        /** The IP address where the server will run. */
-        ip?: string;
-        /** The port where the server will run. Leave `null` to run on port `80` for HTTP and `443` for HTTPS. */
-        port?: number;
-        /** The full domain url without `http://` or `https://`. */
-        domain: string;
-        /** Used to indicate if the current server is the primary node. */
-        is_primary?: boolean;
-        /** The path to a persistent directory where some files such as logs, status info etc will be saved. */
-        source: string;
-        /** The database settings, see {@link Database.Opts}. */
-        database: string | Database.Opts;
-        /** Array with paths to static directories or static directory objects, see {@link Server.StaticDirectory}. */
-        statics?: Array<string | vlib.Path | Server.StaticDirectory>;
-        /** The path to the favicon. */
-        favicon?: string;
-        /** Your company information, see {@link Server.CompanyInfo}. */
-        company: Server.CompanyInfo;
-        /** The default meta object. */
-        meta?: Meta | Meta.Opts;
-        /** The TLS settings for HTTPS, see {@link Server.TLSConfig}. */
-        tls?: Server.TLSConfig;
-        /** The mail options. */
-        mail?: Mail.Opts;
-        /**
-         * The rate limit server and client settings. Rate limiting works with a centralizer websocket server and secondary clients.
-         * By default rate limiting is enabled but can be disabled by explicitly setting `rate_limit` to `false`.
-         */
-        rate_limit?: false | {
-            /** The primary server rate limit settings. */
-            server?: RateLimitServer.Opts;
-            /** The rate limit client settings. */
-            client?: RateLimitClient.Opts;
-        };
-        /** An array with names of crypto keys. Keys will be generated and stored in the database when they do not exist, and accessible as `Server.keys.$name`. Items may be a string (name) or an object with `name` and `length`, see {@link Server.KeyOpts}. */
-        keys?: (string | Server.KeyOpts)[];
-        /** The arguments for the payment class, see {@link Server.PaymentOpts}. */
-        payments?: Server.PaymentOpts;
-        /** Override the default headers generated by volt. Leave `default_headers` undefined to let volt automatically generate default headers. */
-        default_headers?: Record<string, any>;
-        /** The Google Tag ID. */
-        google_tag?: string;
-        /** Additional options for managing the {@link Users} class. */
-        users?: Users.Opts;
-        /** Enable threading behaviour when in production mode. */
-        threading?: false | true | {
-            /** Wether to enable threading behaviour. */
-            enabled: boolean;
-            /** The number of processes when threading is enabled. By default, the number of CPU's will be used. */
-            threads?: number;
-        };
-        /** Boolean indicating if the development server is being run offline. */
-        offline?: boolean;
-        /**
-         * Additional endpoints to add to the sitemap. By default all endpoints where attribute `view` is defined are added.
-         * @note Regex based endpoints are not added to the default sitemap so they should perhaps they should partially be included here.
-        */
-        additional_sitemap_endpoints?: string[];
-        /**
-         * Optional settings for the service daemons. Pass `false` to disable, see {@link vlib.Daemon.Opts}.
-         * The {@link vlib.Daemon.Opts.name} field will be defined with a default value of `domain.replaceAll(".", "")`.
-         * The {@link vlib.Daemon.Opts.logs}, {@link vlib.Daemon.Opts.errors} fields will be defined with a default value of `<source>/daemon/<name>`.
-         */
-        daemon?: false | vlib.Types.Optional<vlib.Daemon.Opts, "name">;
-        /** The active log level. */
-        log_level?: number;
-    }
-    /**
-     * Key options for the {@link Server.Opts} interface.
-     * @docs
-     */
-    interface KeyOpts {
-        /** The name of the key. */
-        name: string;
-        /** The length of the key. */
-        length: number;
-    }
-    /**
-     * Company profile information used in invoices, emails, and branding.
-     * @experimental
-     * @docs
-     */
-    interface CompanyInfo {
-        /** The name of your company. */
-        name: string;
-        /** The legal name of your company. */
-        legal_name: string;
-        /** The street name of your company's address. */
-        street: string;
-        /** The house number or house name of your company's address. */
-        house_number: string;
-        /** The postal/zip code of your company's address. */
-        postal_code: string;
-        /** The city of your company's address. */
-        city: string;
-        /** The province or state of your company's address. */
-        province: string;
-        /** The country name of your company's address. */
-        country: string;
-        /** The two-letter ISO country code of your company's location. */
-        country_code: string;
-        /** The tax ID of your company. */
-        tax_id?: string;
-        /** The type of company. */
-        type?: string;
-        /** The endpoint URL path of your company's icon (PNG). Must be an endpoint URL since access to the file path is also required for creating invoices. */
-        icon?: string;
-        /** The endpoint URL path of your company's stroke icon (PNG). In payment invoices the stroke icon precedes the default icon. Must be an endpoint URL since access to the file path is also required for creating invoices. */
-        stroke_icon?: string;
-        /** The file path of your company's icon (PNG), automatically retrieved from the {@link Server.CompanyInfo.icon} property when possible. */
-        icon_path?: string;
-        /** The file path of your company's stroke icon (PNG), automatically retrieved from the {@link Server.CompanyInfo.stroke_icon} property when possible. */
-        stroke_icon_path?: string;
-    }
-    /**
-     * TLS certificate configuration for enabling HTTPS.
-     * @docs
-     */
-    interface TLSConfig {
-        /** The path to the certificate. */
-        cert: string;
-        /** The path to the private key file. */
-        key: string;
-        /** The path to the CA bundle file. */
-        ca?: string | null;
-        /** The passphrase of the private key. */
-        passphrase?: string;
-    }
-    /**
-     * Description of a static directory or file that should be served.
-     * @docs
-     */
-    interface StaticDirectory {
-        /** The path to the static directory or file. */
-        path: string;
-        /** The base endpoint of the static directory, by default the path's name will be used.*/
-        endpoint?: string;
-        /** Enable caching for the static endpoints; this value will be used for parameter `Endpoint.cache`. */
-        cache?: number | boolean;
-        /** Define a specific cache policy per endpoint from this static directory as `{<endpoint>: <cache>}`; the cache value will be used for parameter `Endpoint.cache`. */
-        endpoints_cache?: Record<string, boolean | number>;
-        /** An array of paths to exclude. The array may contain regexes. */
-        exclude?: Array<string | RegExp>;
-    }
-    /**
-     * A definition of a registered endpoint, can be used to export params and response types to the frontend.
-     * @prop params The inferred interface of the endpoint parameters, note that the runtime value of this property is always `undefined`.
-     * @prop Params Alias for property {@link Server.RegisteredEndpoint.params}.
-     * @docs
-     */
-    type RegisteredEndpoint<M extends Endpoint.Method, E extends string | RegExp, P extends Record<string, any>> = {
-        /** The HTTP method for the endpoint (e.g. GET, POST). */
-        method: M;
-        /** A pascal cased alias for the endpoint, for type exports conforming with `Params`. */
-        Method: M;
-        /**
-         * The route's endpoint endpoint, string or regex,
-         * use `route.endpoint_str` for the string representation.
-         */
-        endpoint: E;
-        /** A pascal cased alias for the method, for type exports conforming with `Params`. */
-        Endpoint: E;
-        /** The endpoint route. */
-        route: Route;
-        /**
-         * The inferred params type, can be used to export the params payload type.
-         * @warning This value is `undefined` at runtime, but contains the correct params payload type at compile time.
-         */
-        Params: P;
-    };
-    /**
-     * The payment options.
-     * @docs
-     */
-    type PaymentOpts = (Paddle.Opts & {
-        /** The payment provider type. */
-        type: "paddle";
-    });
-}
-/**
- * The server class.
- * @note Automatically runs on HTTP/HTTPS depending on the constructor options.
- *
- * @nav Server
- * @docs
- */
-export declare class Server {
-    /**
-     * A temporary directory which holds the cached endpoint data.
-     * For instance if we bundle JS then we save it to file and serve it from the file,
-     * similar for transformed image endpoints.
-     *
-     * Note that upon each server start, we should clear this cache and remove all files inside this dir.
-     */
-    endpoint_cache_dir: vlib.Path;
-    /** The binded ip address. */
-    ip: string;
-    /** The binded http port. */
-    port: number;
-    /** The binded https port. */
-    https_port: number;
-    /** The raw domain. */
-    domain: string;
-    /** The full domain name with http/https depending if tls is enabled. */
-    full_domain: string;
-    /** The persistent storage source directory. */
-    source: vlib.Path;
-    /** Is the primary thread. */
-    is_primary: boolean;
-    /** Is in production mode. */
-    production: boolean;
-    /** The company information. */
-    company: Server.CompanyInfo;
-    /** The default meta information. */
-    meta: Meta;
-    /** Is running in offline mode. */
-    offline: boolean;
-    /** The database instance. */
-    db: Database;
-    /** The rate limit instance. */
-    rate_limit?: RateLimitServer | RateLimitClient;
-    /** The added endpoints. */
-    endpoints: Map<string, Endpoint>;
-    /** The added error endpoints. */
-    err_endpoints: Map<number, Endpoint>;
-    /** A record of keys used for hashing. */
-    keys: Record<string, string>;
-    /** Alias for the `Status` module. */
-    status: typeof Status;
-    /** Alias for the `RateLimits` module. */
-    rate_limits: typeof RateLimits;
-    /** The file logger. */
-    log: vlib.logging.FileLogger;
-    /** The users instance. */
-    users: Users;
-    /** The payments instance. */
-    payments?: Stripe;
-    /** Daemon instance to manage a live daemon. */
-    daemon?: vlib.Daemon;
-    /** The mail instance. */
-    mail?: Mail;
-    csp: Record<string, string>;
-    statics_aspect_ratios: Map<string | RegExp, any>;
-    google_tag?: string;
-    rate_limit_api_key: string | undefined;
-    performance: vlib.Performance;
-    /** The events map @internal */
-    events: vlib.Events<Events>;
-    private favicon?;
-    private statics;
-    private _user_keys_opts;
-    private additional_sitemap_endpoints;
-    private tls?;
-    private default_headers;
-    private http;
-    private https;
-    private threading;
-    private _keys_db;
-    private _sys_keys_db;
-    private _website_status_db;
-    /**
-     * Construct a new server instance.
-     * @docs
-     */
-    constructor({ ip, port, // leave undefined for blank detection.
-    domain, is_primary, source, database, statics, favicon, company, meta, tls, mail, rate_limit, keys, payments, default_headers, google_tag, users, production, threading, offline, additional_sitemap_endpoints, log_level, daemon, }: Server.Opts);
-    /** Get a content type (MIME) from a file extension. */
-    /**
-     * Get a content type (MIME) from a file extension. The file extension should include the leading dot, e.g. ".html".
-     * @docs
-     */
-    get_content_type(extension: string): string;
-    /**
-     * Set the logging verbosity level.
-     * @docs
-     */
-    set_log_level(level: number): void;
-    /**
-     * Generate a cryptographically secure random key as a hex string.
-     * @docs
-     */
-    generate_crypto_key(length?: number): string;
-    /**
-     * Create an HMAC hash using the provided key and data.
-     * @docs
-     */
-    hmac(key: string, data: string, algo?: string): string;
-    /**
-     * Create a hash (no key) of the given data using the specified algorithm.
-     * @docs
-     */
-    hash(data: string | object, algo?: string): string;
-    private _init_default_headers;
-    private _set_header_defaults;
-    private _create_default_endpoints;
-    private _create_sitemap;
-    private _create_robots_txt;
-    private _initialize_statics;
-    /** Initialize the system and user defined keys. */
-    _initialize_keys(): Promise<void>;
-    /**
-     * Checks if an endpoint route already exists.
-     * @param method    HTTP method
-     * @param endpoint  String path or RegExp
-     */
-    private _check_duplicate_route;
-    private _serve;
-    /** The promise of database initialization and connecting. */
-    private _db_init_promise;
-    /** Is initialized. */
-    private _initialized;
-    /** Is initialized by a worker. */
-    private _initialized_by_worker;
-    /**
-     * Initialize the server.
-     * @returns A promise that resolves when the server has been initialized.
-     * @docs
-     */
-    initialize({ worker, }?: {
-        /**
-         * By default the server is initialized as web server.
-         *
-         * However, when using worker threads, the web server parts are skipped.
-         * Only essential operations such as database, users, payments etc. are initialized.
-         * Therefore the server can still be used within a worker threads without
-         * the overhead of creating http/https servers, endpoints, static files, etc.
-         *
-         * The user-defined initialize callbacks are still executed but the `worker` is passed as indication.
-         */
-        worker?: boolean;
-    }): Promise<void>;
-    /**
-     * Find an endpoint by route or string.
-     * @docs
-     */
-    find_endpoint(route: Route): Endpoint | undefined;
-    find_endpoint(endpoint: string, method?: string): Endpoint | undefined;
-    /**
-     * Start the server.
-     *
-     * @example
-     * {Start}
-     * Start the server.
-     * ```
-     * const server = new volt.Server({ ... });
-     * await server.start();
-     * ```
-     * @docs
-     */
-    start(): Promise<void>;
-    /**
-     * Stop the server.
-     * @note After stopping the server we can no longer restart the server.
-     *
-     * @example
-     * {Stop}
-     * Stop the server.
-     * ```
-     * const server = new volt.Server({ ... });
-     * await server.start();
-     * ...
-     * await server.stop();
-     * ```
-     *
-     * @docs
-     */
-    stop(): Promise<void>;
-    /**
-     * Add an event callback.
-     * See {@link Events} for more info.
-     * @docs
-     */
-    on<N extends EventName>(name: N, callback: EventCallback<N>): this;
-    /**
-     * Remove an event callback.
-     * See {@link Events} for more info.
-     * @docs
-     */
-    off<N extends EventName>(name: N, callback: EventCallback<N>): this;
-    /**
-     * Add a single endpoint.
-     * Only supports a single endpoint due to parameter inference.
-     * @note An error is thrown when the endpoint route already exists.
-     * @template Response User inputted response type that will be returned as response, optionaly typing used for consistency.
-     * @template S system template for inferring the endpoint callback parameters.
-     * @param endpoint The endpoint or endpoint options to add.
-     * @returns A registered endpoint object that can for instance be used to infer the endpoint parameters.
-     *
-     * @docs
-     */
-    endpoint<const M extends Endpoint.Method = "GET", const E extends string | RegExp = string, const S extends vlib.Schema.Entries.Opts = {}>(endpoint: Endpoint<M, E, S> | ConstructorParameters<typeof Endpoint<M, E, S>>[0]): Server.RegisteredEndpoint<M, E, vlib.Schema.Entries.Infer<S>>;
-    /**
-     *  Add an endpoint per error status code.
-     * @param status_code
-     *      The status code of the error.
-     *
-     *      The supported status codes are:
-     *      * `*` For all errors not specifically defined.
-     *      * `status >= 400`
-     * @param endpoint The error endpoint or error endpoint options.
-     *
-     * @note
-     * Best practice is to define a universal `/error` endpoint using `Endpoint.templates` to render the error details.
-     * Then this endpoint can be cloned using `Endpoint.clone()` and defined with specific template values per status code.
-     *
-     * @docs
-     */
-    error_endpoint<const S extends vlib.Schema.Entries.Opts = {}>(status_code: "*" | number, endpoint: Endpoint<any, any, S> | Omit<Endpoint.Opts<any, any, S>, "method" | "endpoint">): this;
-    /**
-     * Add an url to the Content-Security-Policy. This function does not overwrite the existing key's value.
-     * @warning This function no longer has any effect when `Server.start()` has been called.
-     * @param key The Content-Security-Policy key, e.g. `script-src`.
-     * @param value The value to add to the Content-Security-Policy key.
-     * @example
-     * ...
-     * server.add_csp("script-src", "somewebsite.com");
-     * server.add_csp("upgrade-insecure-requests");
-     * @docs
-     */
-    add_csp(key: string, value?: null | string | string[]): void;
-    /**
-     * Remove an url from the Content-Security-Policy. This function does not overwrite the existing key's value.
-     * @warning This function no longer has any effect when `Server.start()` has been called.
-     * @param key The Content-Security-Policy key, e.g. `script-src`.
-     * @param value The value to remove from the Content-Security-Policy key.
-     * @example
-     * ...
-     * server.remove_csp("script-src", "somewebsite.com");
-     * server.remove_csp("upgrade-insecure-requests");
-     * @docs
-     */
-    remove_csp(key: string, value?: null | string): void;
-    /**
-     * Delete an key from the Content-Security-Policy.
-     * @warning This function no longer has any effect when `Server.start()` has been called.
-     * @param key The Content-Security-Policy key, e.g. `script-src`.
-     * @example
-     * ...
-     * server.del_csp("script-src");
-     * server.del_csp("upgrade-insecure-requests");
-     * @docs
-     */
-    del_csp(key: string): void;
-    /**
-     * This function is meant to be used when the server is in production mode, it will make an API request to your server through the defined `Server.domain` parameter.
-     * @note This function can be called without initializing the server.
-     * @param type The wanted output type. Either an `object` or a `string` type for CLI purposes.
-     * @docs
-     */
-    fetch_status(type?: "object" | "string"): Promise<string | Record<string, any>>;
-    /**
-     * Generate a key and csr for tls.
-     * @docs
-     */
-    generate_ssl_key({ output_path, ec, }: {
-        output_path: string;
-        ec?: boolean;
-    }): Promise<void>;
-    /**
-     * Generate a csr for tls.
-     * @docs
-     */
-    generate_csr({ output_path, key_path, name, domain, organization_unit, country_code, province, city, }: {
-        output_path: string;
-        key_path: string;
-        name: string;
-        domain: string;
-        organization_unit: string;
-        country_code: string;
-        province: string;
-        city: string;
-    }): Promise<void>;
-    /** Called for each product in a successful one-time payment. Override to implement your logic. */
-    on_payment({ product, payment }: {
-        product: any;
-        payment: any;
-    }): Promise<void>;
-    /** Called for each product in a successful subscription. Override to implement your logic. */
-    on_subscription({ product, payment }: {
-        product: any;
-        payment: any;
-    }): Promise<void>;
-    /** Called when a cancellation succeeds. Override to implement your logic. */
-    on_cancellation({ payment, line_items }: {
-        payment: any;
-        line_items: any[];
-    }): Promise<void>;
-    /** Called when a refund succeeds. The line items array are the items that were refunded. */
-    on_refund({ payment, line_items }: {
-        payment: any;
-        line_items: any[];
-    }): Promise<void>;
-    /** Called when a refund fails. The line items array are the items where the refund failed. */
-    on_failed_refund({ payment, line_items }: {
-        payment: any;
-        line_items: any[];
-    }): Promise<void>;
-    /** Called when a chargeback occurs. The line items array are the items that were charged back. */
-    on_chargeback({ payment, line_items }: {
-        payment: any;
-        line_items: any[];
-    }): Promise<void>;
-    /** Called when a chargeback fails. The line items array are the items where the chargeback failed. */
-    on_failed_chargeback({ payment, line_items }: {
-        payment: any;
-        line_items: any[];
-    }): Promise<void>;
-    /** Build the base email layout used by the various transactional email builders. */
-    private _mail_template;
-    /** Helper that renders a list of payment line items for use in transactional emails. */
-    private _render_mail_payment_line_items;
-    /** Assert mail is configured. */
-    assert_mail(): asserts this is {
-        mail: Mail;
-    };
-    /**
-     * Build the 2FA verification email content.
-     */
-    on_2fa_mail({ code, username, email, date, ip, device }: {
-        code: string;
-        username: string;
-        email: string;
-        date: string;
-        ip: string;
-        device: string;
-    }): any;
-    /**
-     * Build the successful payment email content.
-     */
-    on_payment_mail({ payment }: {
-        payment: Payment;
-    }): MailUI.MailElement;
-    /**
-     * Build the failed payment email content.
-     */
-    on_failed_payment_mail({ payment }: {
-        payment: Payment;
-    }): MailUI.MailElement;
-    /** Build the successful cancellation email content. */
-    on_cancellation_mail({ payment, line_items }: {
-        payment: any;
-        line_items: any[];
-    }): any;
-    /** Build the failed cancellation email content. */
-    on_failed_cancellation_mail({ payment }: {
-        payment: any;
-    }): any;
-    /** Build the successful refund email content. */
-    on_refund_mail({ payment, line_items }: {
-        payment: any;
-        line_items: any[];
-    }): any;
-    /** Build the failed refund email content. */
-    on_failed_refund_mail({ payment, line_items }: {
-        payment: any;
-        line_items: any[];
-    }): any;
-    /** Build the successful chargeback email content. */
-    on_chargeback_mail({ payment, line_items }: {
-        payment: any;
-        line_items: any[];
-    }): any;
-    /** Build the failed chargeback email content. */
-    on_failed_chargeback_mail({ payment, line_items }: {
-        payment: any;
-        line_items: any[];
-    }): any;
-}