@vandenberghinc/volt 1.2.6 → 1.2.8

package/backend/dist/esm/backend/src/plugins/browser.d.ts

@@ -0,0 +1 @@
+export {};

package/backend/dist/esm/backend/src/plugins/browser.js

@@ -0,0 +1,170 @@
+// import * as vlib from "@vandenberghinc/vlib";
+// import { chromium, firefox, Browser, BrowserContext, Page } from 'playwright';
+export {};
+// export class BrowserPreview {
+//     private browser_type: string;
+//     private browser: Browser | null;
+//     private context: BrowserContext | null;
+//     private page: Page | null;
+//     /**
+//      * Initializes the browser_controller with the specified browser type.
+//      * @param {string} browser - The browser to launch ('chrome' or 'firefox').
+//      */
+//     constructor(browser: string = 'chrome') {
+//         this.browser_type = browser.toLowerCase();
+//         this.browser = null;
+//         this.context = null;
+//         this.page = null;
+//     }
+//     /**
+//      * Starts the browser and opens a new page.
+//      */
+//     async start(): Promise<void> {
+//         try {
+//             if (this.browser_type === 'chrome') {
+//                 // Launch Chromium with Chrome channel for Chrome-specific features
+//                 this.browser = await chromium.launch({
+//                     headless: false, // Set to true if you don't need to see the browser
+//                     channel: 'chrome', // Ensure Chrome is installed on your system
+//                     args: [
+//                         '--ignore-certificate-errors',
+//                         '--allow-insecure-localhost',
+//                     ],
+//                 });
+//             } else if (this.browser_type === 'firefox') {
+//                 this.browser = await firefox.launch({
+//                     headless: false, // Set to true if you don't need to see the browser
+//                 });
+//             } else {
+//                 throw new Error(`Unsupported browser type: ${this.browser_type}`);
+//             }
+//             this.context = await this.browser.newContext({
+//                 ignoreHTTPSErrors: true,
+//                 viewport: null,
+//             });
+//             this.page = await this.context.newPage();
+//             log(0, `${this.browser_type} browser launched successfully.`);
+//         } catch (error: any) {
+//             error(`Error launching browser: ${error.message}`);
+//         }
+//     }
+//     /**
+//      * Stops the browser and cleans up resources.
+//      */
+//     async stop(): Promise<void> {
+//         try {
+//             if (this.browser) {
+//                 await this.browser.close();
+//                 log(0, `${this.browser_type} browser closed successfully.`);
+//             }
+//         } catch (error: any) {
+//             error(`Error closing browser: ${error.message}`);
+//         }
+//     }
+//     /**
+//      * Refreshes the active tab if its URL matches the specified endpoint.
+//      * @param {string | RegExp} endpoint - The server endpoint URL to check against the active tab.
+//      */
+//     async refresh(endpoint: string | RegExp): Promise<void> {
+//         if (!this.page) {
+//             log.warn(0, `No page is open. Please call start() first.`);
+//             return;
+//         }
+//         let current_endpoint: string = this.page.url().replace(/http[s]*:\/\//g, "");
+//         const index = current_endpoint.indexOf("/");
+//         if (index !== -1) {
+//             current_endpoint = current_endpoint.substr(index);
+//         }
+//         // Normalize URLs for comparison
+//         current_endpoint = this._normalize_url(current_endpoint);
+//         if (typeof endpoint === "string") {
+//             endpoint = this._normalize_url(endpoint);
+//         }
+//         if (
+//             (typeof endpoint === "string" && current_endpoint === endpoint) ||
+//             (endpoint instanceof RegExp && endpoint.test(current_endpoint))
+//         ) {
+//             // Capture the current scroll position
+//             const scrollPosition = await this.page.evaluate(() => {
+//                 // @ts-ignore
+//                 const scrollableElement = document.scrollingElement;
+//                 if (scrollableElement) {
+//                     return {
+//                         x: scrollableElement.scrollLeft,
+//                         y: scrollableElement.scrollTop
+//                     };
+//                 } else {
+//                     // Fallback to window scroll if scrollingElement not found
+//                     return {
+//                         // @ts-ignore
+//                         x: window.scrollX,
+//                         // @ts-ignore
+//                         y: window.scrollY
+//                     };
+//                 }
+//             });
+//             // Reload the page
+//             await this.page.reload();
+//             log(2, `Page reloaded because it matches the endpoint: ${endpoint}`);
+//             // Restore the scroll position after reload
+//             await this.page.evaluate(({ x, y }) => {
+//                 // @ts-ignore
+//                 const scrollableElement = document.scrollingElement;
+//                 if (scrollableElement) {
+//                     scrollableElement.scrollTo(x, y);
+//                 } else {
+//                     // @ts-ignore
+//                     window.scrollTo(x, y);
+//                 }
+//             }, { x: scrollPosition.x, y: scrollPosition.y });
+//             log(2, `Scroll position restored to x: ${scrollPosition.x}, y: ${scrollPosition.y}`);
+//         } else {
+//             log(2, `Active tab URL (${current_endpoint}) does not match the endpoint (${endpoint}). No action taken.`);
+//         }
+//     }
+//     /**
+//      * Opens the specified endpoint in the browser.
+//      * @param {string} endpoint - The URL to navigate to.
+//      */
+//     async navigate(endpoint: string): Promise<void> {
+//         try {
+//             if (!this.page) {
+//                 log.warn(0, `No page is open. Please call start() first.`);
+//                 return;
+//             }
+//             await this.page.goto(endpoint);
+//             log(1, `Navigated to ${endpoint}`);
+//         } catch (error: any) {
+//             error(`Error navigating to ${endpoint}: ${error.message}`);
+//         }
+//     }
+//     /**
+//      * Normalizes URLs by removing trailing slashes and converting to lowercase.
+//      * @param {string} url - The URL to normalize.
+//      * @returns {string} - The normalized URL.
+//      */
+//     _normalize_url(url: string): string {
+//         if (/http[s]*:\/\//.test(url)) {
+//             url = url.replace(/http[s]*:\/\//g, "");
+//             const index = url.indexOf("/");
+//             if (index !== -1) {
+//                 url = url.substr(index);
+//             }
+//         }
+//         let index;
+//         if ((index = url.indexOf("#")) !== -1) {
+//             url = url.substr(0, index);
+//         }
+//         while (url.includes("//")) {
+//             url = url.replaceAll("//", "/");
+//         }
+//         while (url[0] === "/") {
+//             url = url.slice(1);
+//         }
+//         while (url[url.length - 1] === "/") {
+//             url = url.slice(0, -1);
+//         }
+//         return url.toLowerCase();
+//     }
+// }
+// export default BrowserPreview;

package/backend/dist/esm/backend/src/plugins/communication.d.ts

@@ -0,0 +1,70 @@
+import net from 'net';
+declare module 'net' {
+    interface Socket {
+        buffer: string;
+    }
+}
+/**
+ * Very basic internal communication socket between processes.
+ */
+declare class Base {
+    port: number;
+    host: string;
+    _on_message: ((message: any, socket: net.Socket) => void) | null;
+    constructor(port: number, host?: string);
+    on_message(callback: (message: any, socket: net.Socket) => void): this;
+    /**
+     * Processes the buffer to extract complete messages.
+     * Handles multiple consecutive messages.
+     * @param {net.Socket} socket - The client socket.
+     */
+    _process_buffer(socket: net.Socket): void;
+}
+export declare class Server extends Base {
+    server: net.Server;
+    clients: Set<net.Socket>;
+    /**
+     * Initializes the JSON Server.
+     * @param {number} port - Port number to listen on.
+     * @param {string} host - Host address to bind to.
+     */
+    constructor(port: number, host?: string);
+    /**
+     * Sends a JSON message to a specific socket.
+     * @param {net.Socket} socket - The socket to send the message to.
+     * @param {Object} obj - The JSON object to send.
+     */
+    message(socket: net.Socket, obj: Record<string, any>): void;
+    /**
+     * Broadcasts a JSON message to all connected clients.
+     * @param {Object} obj - The JSON object to broadcast.
+     */
+    broadcast(obj: Record<string, any>): void;
+    /**
+     * Closes the server and all client connections.
+     */
+    close(): void;
+}
+export declare class Client extends Base {
+    socket: net.Socket;
+    /**
+     * Initializes the JSON Client.
+     * @param {number} port - Port number to connect to.
+     * @param {string} host - Host address to connect to.
+     */
+    constructor(port: number, host?: string);
+    /**
+     * Sends a JSON message to the server.
+     * @param {Object} obj - The JSON object to send.
+     */
+    message(obj: Record<string, any>): void;
+    /**
+     * Closes the client connection.
+     */
+    close(): void;
+}
+declare const _default: {
+    Server: typeof Server;
+    Client: typeof Client;
+};
+export default _default;

package/backend/dist/esm/backend/src/plugins/communication.js

@@ -0,0 +1,169 @@
+import net from 'net';
+/**
+ * Very basic internal communication socket between processes.
+ */
+// Base class.
+class Base {
+    port;
+    host;
+    _on_message;
+    constructor(port, host = '127.0.0.1') {
+        this.port = port;
+        this.host = host;
+        this._on_message = null;
+    }
+    // Set on message.
+    on_message(callback) {
+        this._on_message = callback;
+        return this;
+    }
+    /**
+     * Processes the buffer to extract complete messages.
+     * Handles multiple consecutive messages.
+     * @param {net.Socket} socket - The client socket.
+     */
+    _process_buffer(socket) {
+        while (socket.buffer.length >= 4) { // At least 4 characters for length prefix
+            // Read the first 4 characters to get the message length
+            const length_str = socket.buffer.slice(0, 4);
+            const message_length = parseInt(length_str, 10);
+            if (isNaN(message_length)) {
+                console.error('Invalid message length:', length_str);
+                socket.destroy();
+                break;
+            }
+            if (socket.buffer.length >= 4 + message_length) {
+                const message_str = socket.buffer.slice(4, 4 + message_length);
+                socket.buffer = socket.buffer.slice(4 + message_length);
+                try {
+                    const message = JSON.parse(message_str);
+                    if (this._on_message)
+                        this._on_message(message, socket);
+                }
+                catch (err) {
+                    console.error('Invalid JSON received:', message_str);
+                }
+            }
+            else {
+                // Wait for more data
+                break;
+            }
+        }
+    }
+}
+// Server class.
+export class Server extends Base {
+    server;
+    clients;
+    /**
+     * Initializes the JSON Server.
+     * @param {number} port - Port number to listen on.
+     * @param {string} host - Host address to bind to.
+     */
+    constructor(port, host = '127.0.0.1') {
+        super(port, host);
+        this.server = net.createServer();
+        this.clients = new Set();
+        this.server.on('connection', (socket) => {
+            console.log('Client connected:', socket.remoteAddress, socket.remotePort);
+            this.clients.add(socket);
+            socket.setEncoding('utf8');
+            // Initialize buffer for each client
+            socket.buffer = '';
+            socket.on('data', (data) => {
+                socket.buffer += data;
+                this._process_buffer(socket);
+            });
+            socket.on('close', () => {
+                console.log('Client disconnected:', socket.remoteAddress, socket.remotePort);
+                this.clients.delete(socket);
+            });
+            socket.on('error', (err) => {
+                console.error('Socket error:', err);
+                socket.destroy();
+                this.clients.delete(socket);
+            });
+        });
+        this.server.on('error', (err) => {
+            console.error('Server error:', err);
+        });
+        this.server.listen(port, host, () => {
+            console.log(`JSON Server listening on ${host}:${port}`);
+        });
+    }
+    /**
+     * Sends a JSON message to a specific socket.
+     * @param {net.Socket} socket - The socket to send the message to.
+     * @param {Object} obj - The JSON object to send.
+     */
+    message(socket, obj) {
+        const json = JSON.stringify(obj);
+        const length = json.length.toString().padStart(4, '0'); // 4-digit length prefix
+        socket.write(length + json);
+    }
+    /**
+     * Broadcasts a JSON message to all connected clients.
+     * @param {Object} obj - The JSON object to broadcast.
+     */
+    broadcast(obj) {
+        for (let socket of this.clients) {
+            this.message(socket, obj);
+        }
+    }
+    /**
+     * Closes the server and all client connections.
+     */
+    close() {
+        for (let socket of this.clients) {
+            socket.destroy();
+        }
+        this.server.close(() => {
+            console.log('JSON Server closed.');
+        });
+    }
+}
+// Client class.
+export class Client extends Base {
+    socket;
+    /**
+     * Initializes the JSON Client.
+     * @param {number} port - Port number to connect to.
+     * @param {string} host - Host address to connect to.
+     */
+    constructor(port, host = '127.0.0.1') {
+        super(port, host);
+        this.socket = net.createConnection(port, host, () => {
+            console.log(`Connected to JSON Server at ${host}:${port}`);
+        });
+        this.socket.buffer = '';
+        this.socket.setEncoding('utf8');
+        this.socket.on('data', (data) => {
+            this.socket.buffer += data;
+            this._process_buffer(this.socket);
+        });
+        this.socket.on('close', () => {
+            console.log('Disconnected from JSON Server');
+        });
+        this.socket.on('error', (err) => {
+            console.error('Socket error:', err);
+            this.socket.destroy();
+        });
+    }
+    /**
+     * Sends a JSON message to the server.
+     * @param {Object} obj - The JSON object to send.
+     */
+    message(obj) {
+        const json = JSON.stringify(obj);
+        const length = json.length.toString().padStart(4, '0'); // 4-digit length prefix
+        this.socket.write(length + json);
+    }
+    /**
+     * Closes the client connection.
+     */
+    close() {
+        this.socket.end();
+    }
+}
+// Exports.
+export default { Server, Client };

package/backend/dist/esm/backend/src/plugins/mail/mail.d.ts

@@ -0,0 +1,255 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh.
+ */
+import * as nodemailer from "nodemailer";
+import * as vlib from "@vandenberghinc/vlib";
+import { Readable } from "stream";
+import { Url } from "url";
+import * as UI from "./ui.js";
+/**
+ * The mail class, used to send emails via SMTP.
+ *
+ * @note This class is initialized under server property `mail` when the server is started with the `smtp` option.
+ *
+ * @nav Plugins
+ * @docs
+ */
+export declare class Mail {
+    /** the smpt mailer. */
+    private smtp;
+    /** the smtp sender address. */
+    sender: Mail.Address;
+    /** the default mail style. */
+    style: Mail.Style;
+    /** construct a new server instance. */
+    constructor({ smtp, style, }: Mail.Opts);
+    /**
+     * send one or multiple mails.
+     *
+     * @note ensure SPF/DKIM are configured when sending attachments.
+     * @returns resolves/rejects when the mail has been sent.
+     *
+     * @param sender optional sender override.
+     * @param recipients recipient addresses.
+     * @param subject subject line.
+     * @param body html string or `UI.MailElement`.
+     * @param attachments supported inputs (paths, backend model, REST model, or nodemailer attachment).
+     * @param max_attachments limit on number of attachments; -1 disables.
+     * @param max_attachment_size max size (bytes) per attachment; -1 disables.
+     * @param max_attachments_size max total size (bytes) across attachments; -1 disables.
+     *
+     * @docs
+     */
+    send({ sender, recipients, subject, body, attachments, max_attachments, max_attachment_size, max_attachments_size, allow_untrusted_urls, }: {
+        sender?: Mail.Address;
+        recipients?: Mail.Address[];
+        subject?: string;
+        body?: string | UI.MailElement;
+        attachments?: Mail.Attachment.Any[];
+    } & Mail.Attachment.Limits): Promise<void>;
+    /**
+     * convert a single generic attachment input into a nodemailer attachment.
+     */
+    private build_attachment;
+    /** returns true when url starts with http:// or https:// */
+    private is_http_url;
+    /**
+     * normalize and validate a mixed attachment input into nodemailer attachments.
+     * @param input mixed list of attachments.
+     * @param limits size/count validation limits.
+     * @returns normalized nodemailer attachments.
+     * @throws {ExternalError} when limits are exceeded.
+     */
+    private normalize_and_validate_attachments;
+    /**
+     * measure the on-wire payload size (approx) of a nodemailer attachment content.
+     * note: if `encoding: "base64"` is set, we decode to compute raw byte size.
+     */
+    private measure_attachment_bytes;
+    /**
+     * normalize a base64 or url-safe base64 string to standard base64 (no decoding).
+     * trims whitespace and converts url-safe chars.
+     */
+    private normalize_base64;
+    /**
+     * optional content headers for charset/compression hints.
+     * email clients usually ignore custom headers; added for traceability.
+     */
+    private build_content_headers;
+}
+/** nested types for the mail module. */
+export declare namespace Mail {
+    /** a mail address, either a string or an array of [name, email]. */
+    type Address = string | [string, string];
+    /** options for the smtp mailer. */
+    interface Opts {
+        /**
+         * the smtp nodemailer arguments object.
+         * more information can be found at the nodemailer documentation.
+         */
+        smtp: {
+            /** the smtp sender address; either a string email, e.g. `your@email.com`, or`[name, email]`. */
+            sender: Address;
+            /** the mail server's host address. */
+            host?: string;
+            /** the mail server's port. */
+            port?: number;
+            /** enable secure options. */
+            secure?: boolean;
+            /** the authentication settings. */
+            auth?: {
+                /** the email used for authentication. */
+                user: string;
+                /** the password used for authentication. */
+                pass: string;
+            };
+            /**
+             * the smtp `nodemailer.createTransport` argument that overrides the other {@link Mail.Opts.smtp} options.
+             * use this to supply vendor-specific transport options.
+             */
+            override?: nodemailer.TransportOptions;
+        };
+        /** the default mail style. */
+        style?: Style;
+    }
+    /**
+     * style tokens used to theme automatically generated emails.
+     */
+    interface Style {
+        /** the font family. */
+        font: string;
+        /** the title foreground color. */
+        title_fg: string;
+        /** the subtitle foreground color. */
+        subtitle_fg: string;
+        /** the body text foreground color. */
+        text_fg: string;
+        /** the foreground color used for buttons. */
+        button_fg: string;
+        /** the footer foreground color. */
+        footer_fg: string;
+        /** page background color. */
+        bg: string;
+        /** widget background color. */
+        widget_bg: string;
+        /** widget border color. */
+        widget_border: string;
+        /** button background color. */
+        button_bg: string;
+        /** divider color. */
+        divider_bg: string;
+    }
+    /**
+     * stable backend attachment model.
+     * mirrors the frontend Attachment; provide either raw `bytes` or `{ content, encoding }`.
+     * encoding is only used when `content` is a string.
+     */
+    interface Attachment {
+        /** file or directory name. */
+        name: string;
+        /** path relative to a logical root (optional). */
+        path?: string;
+        /** mime type of the data. */
+        mime_type?: string;
+        /** charset used for text decoding (if applicable). */
+        charset?: string;
+        /** raw bytes buffer. */
+        bytes?: Buffer | Uint8Array;
+        /** textual payload to be decoded using `encoding`. */
+        content?: string;
+        /** encoding used to decode `content` into bytes (e.g. base64, hex, utf8, binary, latin1). */
+        encoding?: "base64" | "hex" | "utf8" | "utf-8" | "binary" | "latin1";
+        /** whether bytes are gzip-compressed (metadata only). */
+        compressed?: boolean;
+    }
+    /** Nested attachment types. */
+    namespace Attachment {
+        /** The possible encodings. */
+        type Encoding = "base64" | "hex" | "utf8" | "utf-8" | "binary" | "latin1";
+        const encodings: Set<Encoding>;
+        /** Attachment validation limits. */
+        interface Limits {
+            /** Maximum number of attachments allowed (unset means no limit). */
+            max_attachments?: number;
+            /** Maximum size in bytes per attachment (unset means no limit). */
+            max_attachment_size?: number;
+            /** Maximum cumulative size in bytes across all attachments (unset means no limit). */
+            max_attachments_size?: number;
+            /** Allow loading http/https urls as attachments (default: false). */
+            allow_untrusted_urls?: boolean;
+        }
+        /** Type guard. */
+        function is(a: any): a is Attachment;
+        /**
+         * user-friendly REST attachment payload.
+         * choose one of:
+         *  - `{ content, encoding }` for inline payloads (encoding: base64/hex/utf8/binary/latin1).
+         *  - `{ url }` for http(s) or data: urls (streamed by nodemailer).
+         */
+        interface RestAPI {
+            /** file name to display to the recipient. */
+            name: string;
+            /** relative path inside a bundle/archive (metadata only, optional). */
+            path?: string;
+            /** mime type of the data. */
+            mime_type?: string;
+            /** charset used for text decoding (if applicable). */
+            charset?: string;
+            /** whether the provided bytes are gzip-compressed (metadata only). */
+            compressed?: boolean;
+            /** textual payload to be decoded using `encoding`. */
+            content?: string;
+            /** encoding used to decode `content` into bytes. */
+            encoding?: "base64" | "hex" | "utf8" | "utf-8" | "binary" | "latin1";
+            /** http(s) url or data: url to stream. */
+            url?: string;
+        }
+        namespace RestAPI {
+            /** Type guard. */
+            function is(a: any): a is RestAPI;
+            /** Schema validation. */
+            const Schema: vlib.Schema.Opts;
+        }
+        /** A native nodemailer attachment. */
+        interface Native {
+            /** String, Buffer or a Stream contents for the attachment */
+            content?: string | Buffer | Readable | undefined;
+            /** path to a file or an URL (data uris are allowed as well) if you want to stream the file instead of including it (better for larger attachments) */
+            path?: string | Url | undefined;
+            /** filename to be reported as the name of the attached file, use of unicode is allowed. If you do not want to use a filename, set this value as false, otherwise a filename is generated automatically */
+            filename?: string | false | undefined;
+            /** optional content id for using inline images in HTML message source. Using cid sets the default contentDisposition to 'inline' and moves the attachment into a multipart/related mime node, so use it only if you actually want to use this attachment as an embedded image */
+            cid?: string | undefined;
+            /** If set and content is string, then encodes the content to a Buffer using the specified encoding. Example values: base64, hex, binary etc. Useful if you want to use binary attachments in a JSON formatted e-mail object */
+            encoding?: string | undefined;
+            /** optional content type for the attachment, if not set will be derived from the filename property */
+            contentType?: string | undefined;
+            /** optional transfer encoding for the attachment, if not set it will be derived from the contentType property. Example values: quoted-printable, base64. If it is unset then base64 encoding is used for the attachment. If it is set to false then previous default applies (base64 for most, 7bit for text). */
+            contentTransferEncoding?: "7bit" | "base64" | "quoted-printable" | false | undefined;
+            /** optional content disposition type for the attachment, defaults to ‘attachment’ */
+            contentDisposition?: "attachment" | "inline" | undefined;
+            /** is an object of additional headers */
+            headers?: {
+                [key: string]: string | string[] | {
+                    prepared: boolean;
+                    value: string;
+                };
+            } | Array<{
+                key: string;
+                value: string;
+            }>;
+            /** an optional value that overrides entire node content in the mime message. If used then all other options set for this node are ignored. */
+            raw?: string | Buffer | Readable | Native | undefined;
+        }
+        /** Nested native types. */
+        namespace Native {
+            /** Simple type guard. */
+            function is(a: any): a is Native;
+        }
+        /**
+         * Unified attachment input accepted by {@link Mail.send}.
+         */
+        type Any = string | vlib.Path | Attachment | RestAPI | Native;
+    }
+}