@vandenberghinc/volt 1.1.26 → 1.1.28

package/backend/dist/cjs/{route.d.ts → backend/src/route.d.ts}

@@ -13,7 +13,6 @@ export declare class Route {
         required: boolean;
     }[];
     private matcher?;
-    matched_params: Record<string, any>;
     /**
      *
      * @param method   HTTP method (e.g. "GET", "post", etc.)
@@ -23,20 +22,14 @@ export declare class Route {
      *                    Ensure the wildcards are encapsulated by / or at the start of end of the string.
      */
     constructor(method: string, endpoint: string | RegExp);
-    /** Create match args
-      * @warning this is required for the `match()` method
-      */
-    static create_match_args(method: string, endpoint: string): {
-        method: string;
-        endpoint: string;
-    };
     /**
      * Tests this route against another Route (e.g. a “request” Route).
-     * Returns true/false and on true populates other.params.
+     * @returns `false` when not matched, and a `params` object when matched.
      */
-    match(other: Route): boolean;
+    match(other: Route): false | Record<string, any>;
     private _create_route_matcher;
     private static _stringify_endpoint_regex;
+    /** Clean an endpoint url. */
     static clean_endpoint(endpoint: RegExp): RegExp;
     static clean_endpoint(endpoint: string): string;
 }

package/backend/dist/cjs/{route.js → backend/src/route.js}

@@ -29,8 +29,6 @@ class Route {
   params = [];
   // path param names.
   matcher;
-  // Inserted only when passed as arg into `match()`.
-  matched_params = {};
   /**
    *
    * @param method   HTTP method (e.g. "GET", "post", etc.)
@@ -59,47 +57,51 @@ class Route {
     }
     this.id = `${this.method}:${this.endpoint_str}`;
   }
-  /** Create match args
-    * @warning this is required for the `match()` method
-    */
-  static create_match_args(method, endpoint) {
-    return {
-      method: method.trim().toUpperCase(),
-      endpoint: endpoint.replace(/\/+$/, "") || "/"
-    };
-  }
+  // /** Create match args
+  //   * @warning this is required for the `match()` method 
+  //   */
+  // public static create_match_args(method: string, endpoint: string): { method: string, endpoint: string} {
+  //     return {
+  //         method: method.trim().toUpperCase(),
+  //         endpoint: endpoint.replace(/\/+$/, "") || "/",
+  //     };
+  // }
   /**
    * Tests this route against another Route (e.g. a “request” Route).
-   * Returns true/false and on true populates other.params.
+   * @returns `false` when not matched, and a `params` object when matched.
    */
   match(other) {
     if (this.endpoint instanceof RegExp && other.endpoint instanceof RegExp) {
       return false;
     }
     if (other.method !== this.method) {
-      other.matched_params = {};
       return false;
     }
     if (this.endpoint instanceof RegExp) {
       const m = this.endpoint.exec(other.endpoint_str);
       if (!m) {
-        other.matched_params = {};
         return false;
+      } else if (m.groups) {
+        const x = Object.fromEntries(Object.entries(m.groups).map(([name, val]) => {
+          return [name, val == null ? val : decodeURIComponent(val)];
+        }));
+        console.log("ROUTE PARAMS:", x);
+        return x;
       }
-      other.matched_params = m.groups ? { ...m.groups } : {};
-      return true;
+      return {};
     }
     if (this.matcher) {
       const result = this.matcher.match(other.endpoint_str);
       if (!result) {
-        other.matched_params = {};
         return false;
       }
-      other.matched_params = result;
-      return true;
+      const keys = Object.keys(result);
+      for (const k of keys) {
+        result[k] = decodeURIComponent(result[k]);
+      }
+      return result;
     }
-    other.matched_params = {};
-    return this.endpoint_str === other.endpoint_str;
+    return this.endpoint_str === other.endpoint_str ? {} : false;
   }
   // ─── Helper: compile colon-style patterns ───
   _create_route_matcher(pattern) {

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

@@ -0,0 +1,485 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh.
+ */
+import * as vlib from "@vandenberghinc/vlib";
+import { Meta } from './meta.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 } from "./payments/paddle.js";
+import { RateLimits, RateLimitServer, RateLimitClient } from "./rate_limit.js";
+import { Route } from "./route.js";
+import { EventCallback, EventName, Events } from './events.js';
+/** Company profile information used in invoices, emails, and branding. */
+export 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 CompanyInfo.icon} property when possible. */
+    icon_path?: string;
+    /** The file path of your company's stroke icon (PNG), automatically retrieved from the {@link CompanyInfo.stroke_icon} property when possible. */
+    stroke_icon_path?: string;
+}
+/** TLS certificate configuration for enabling HTTPS. */
+export 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. */
+export 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 RegisteredEndpoint.params}.
+ */
+export 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. */
+export type PaymentOpts = (Paddle.Opts & {
+    /** The payment provider type. */
+    type: "paddle";
+});
+/** Nested types for the {@link Server} class. */
+export declare namespace Server {
+    /** Key options for the {@link Server.Opts} interface. */
+    interface KeyOpts {
+        /** The name of the key. */
+        name: string;
+        /** The length of the key. */
+        length: number;
+    }
+    /** Constructor options. */
+    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 StaticDirectory}. */
+        statics?: Array<string | vlib.Path | StaticDirectory>;
+        /** The path to the favicon. */
+        favicon?: string;
+        /** Your company information, see {@link CompanyInfo}. */
+        company: CompanyInfo;
+        /** The default meta object. */
+        meta?: Meta | Meta.Opts;
+        /** The TLS settings for HTTPS, see {@link TLSConfig}. */
+        tls?: 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 PaymentOpts}. */
+        payments?: 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;
+    }
+}
+/**
+ * The backend server class.
+ *
+ * When the HTTPS parameters `certificate` and `private_key` are defined, the server will run automatically on HTTP and HTTPS.
+ *
+ * @property users The initialized {@link Users} instance.
+ */
+export declare class Server {
+    /** Content type per mime. */
+    static content_type_mimes: Map<string, string>;
+    /** All file path extensions that are already compressed. */
+    static compressed_extensions: Set<string>;
+    /** 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: 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?: Paddle;
+    /** 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. */
+    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_content_type(extension: string): string;
+    /** Set the logging verbosity level. */
+    set_log_level(level: number): void;
+    /** Generate a cryptographically secure random key as a hex string. */
+    generate_crypto_key(length?: number): string;
+    /** Create an HMAC hash using the provided key and data. */
+    hmac(key: string, data: string, algo?: string): string;
+    /** Create a hash (no key) of the given data using the specified algorithm. */
+    hash(data: string | object, algo?: string): string;
+    private _init_default_headers;
+    private _set_header_defaults;
+    private _find_endpoint;
+    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;
+    initialize(): Promise<void>;
+    /**
+     * Start the server.
+     * @example
+     * ...
+     * server.start();
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server.
+     * @example
+     * ...
+     * server.stop();
+     */
+    stop(): Promise<void>;
+    /** Add an event callback. */
+    on<N extends EventName>(name: N, callback: EventCallback<N>): this;
+    /** Remove an event callback. */
+    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.
+     */
+    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]): 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:
+     *      * `404`
+     *      * `400` (Will not be used when the endpoint uses an API callback).
+     *      * `403`
+     *      * `404`
+     *      * `500`
+     * @param endpoint The error endpoint or error endpoint options
+    */
+    error_endpoint<const M extends Endpoint.Method = "GET", const E extends string | RegExp = string, const S extends vlib.Schema.Entries.Opts = {}>(status_code: number, endpoint: Endpoint<M, E, S> | Endpoint.Opts<M, E, S>): 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");
+     */
+    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");
+     */
+    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");
+     */
+    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.
+     */
+    fetch_status(type?: "object" | "string"): Promise<string | Record<string, any>>;
+    /** Generate a key and csr for tls. */
+    generate_ssl_key({ output_path, ec, }: {
+        output_path: string;
+        ec?: boolean;
+    }): Promise<void>;
+    /** Generate a csr for tls. */
+    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. */
+    _mail_template({ max_width, children, }: {
+        max_width?: number;
+        children?: any[];
+    }): any;
+    /** Helper that renders a list of payment line items for use in transactional emails. */
+    _render_mail_payment_line_items({ payment, line_items, show_total_due }: {
+        payment: any;
+        line_items: any[];
+        show_total_due?: boolean;
+    }): any[];
+    /** 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: any;
+    }): any;
+    /** Build the failed payment email content. */
+    on_failed_payment_mail({ payment }: {
+        payment: any;
+    }): any;
+    /** 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;
+}