@vandenberghinc/volt 1.1.26 → 1.1.28

package/frontend/dist/frontend/src/modules/attachment.js

@@ -0,0 +1,306 @@
+/**
+ * @author ...
+ * @copyright ...
+ */
+import { Compression } from "./compression.js";
+/** A file attachment with an internal byte buffer and compression/encoding helpers. */
+export class Attachment {
+    /** File or directory name. */
+    name;
+    /** Path relative to the dropped root. */
+    path;
+    /** MIME type of the data. */
+    mime_type;
+    /** Charset used for text decoding (if applicable). */
+    charset;
+    /** Whether the internal buffer is gzip-compressed. */
+    compressed;
+    /** Optional original File/Blob source. */
+    file;
+    /** Internal raw buffer (compressed or not depending on state). */
+    _bytes;
+    /** Create an Attachment from initial metadata and/or bytes. */
+    constructor(init) {
+        this.name = init.name;
+        this.path = init.path ?? "";
+        this.mime_type = init.mime_type ?? "";
+        this.charset = init.charset;
+        this.file = init.file;
+        this.compressed = !!init.compressed;
+        this._bytes = init.bytes ? Compression.to_uint8(init.bytes) : new Uint8Array(0);
+    }
+    /** Current size of the internal buffer in bytes (compressed if flagged). */
+    get size() { return this._bytes.byteLength; }
+    /** Get a copy of the internal buffer (leave compression state unchanged). */
+    bytes() { return new Uint8Array(this._bytes); }
+    /** Replace the internal buffer (optionally update compression flag). */
+    set_bytes(bytes, compressed = false) {
+        this._bytes = Compression.to_uint8(bytes);
+        this.compressed = compressed;
+        return this;
+    }
+    /** Ensure the buffer is gzip-compressed (noop if already compressed). */
+    compress(options = { level: 9 }) {
+        if (!this.compressed) {
+            this._bytes = Compression.compress(this._bytes, options);
+            this.compressed = true;
+        }
+        return this;
+    }
+    /** Ensure the buffer is uncompressed (noop if already uncompressed). */
+    decompress() {
+        if (this.compressed) {
+            this._bytes = Compression.decompress(this._bytes);
+            this.compressed = false;
+        }
+        return this;
+    }
+    /** Return Base64 of the current buffer (compressed or not). */
+    to_base64({ url_safe = false } = {}) {
+        return Compression.to_base64(this._bytes, { url_safe });
+    }
+    /**
+     * Return a string view of the data using a charset.
+     * @param decompress Whether to decompress first if compressed. Default true.
+     * @param encoding Charset label; defaults to this.charset or "utf-8".
+     */
+    to_string(decompress = true, encoding) {
+        const buf = decompress && this.compressed ? Compression.decompress(this._bytes) : this._bytes;
+        const enc = (encoding ?? this.charset ?? "utf-8").toLowerCase();
+        if (enc === "utf-8" || enc === "utf8")
+            return new TextDecoder().decode(buf);
+        try {
+            return new TextDecoder(enc).decode(buf);
+        }
+        catch {
+            return new TextDecoder().decode(buf);
+        }
+    }
+    /**
+     * Parse JSON from the data.
+     * @param decompress Whether to decompress first if compressed. Default true.
+     */
+    to_json(decompress = true) {
+        return JSON.parse(this.to_string(decompress));
+    }
+    /**
+     * Convert this attachment to a backend REST API attachment payload.
+     *
+     * This returns an object compatible with the server's `Mail.Attachment.RestAPI`
+     * shape using either:
+     *  - `{ content, encoding }` (default; embeds the payload), or
+     *  - `{ url }` (streams from an http(s)/data URL).
+     *
+     * @param opts Conversion options.
+     * @param opts.encoding Output string encoding for `content`. Defaults to `"base64"`.
+     *                      Supported: `"base64" | "hex" | "utf8"`.
+     *                      Use `"utf8"` only for textual data.
+     * @param opts.decompress Whether to decompress before encoding. Defaults to `true`.
+     * @param opts.url Optional http(s) or data: URL. When provided, `content`/`encoding`
+     *                 are omitted and the server will stream from this URL.
+     *
+     * @returns A REST API attachment payload with metadata plus either `{ content, encoding }` or `{ url }`.
+     */
+    to_rest_api(opts = {}) {
+        const { encoding = "base64", decompress = true, url } = opts;
+        const base = {
+            name: this.name,
+            path: this.path || undefined,
+            mime_type: this.mime_type || undefined,
+            charset: this.charset || undefined,
+            compressed: this.compressed || undefined,
+        };
+        if (url) {
+            return { ...base, url };
+        }
+        const bytes = decompress && this.compressed ? Compression.decompress(this._bytes) : this._bytes;
+        if (encoding === "base64") {
+            return { ...base, content: Compression.to_base64(bytes, { url_safe: false }), encoding };
+        }
+        if (encoding === "hex") {
+            // encode bytes -> hex (lowercase)
+            const hex = (() => {
+                const v = bytes;
+                let out = "";
+                for (let i = 0; i < v.length; i++) {
+                    const h = v[i].toString(16).padStart(2, "0");
+                    out += h;
+                }
+                return out;
+            })();
+            return { ...base, content: hex, encoding };
+        }
+        if (encoding === "utf8") {
+            // textual encoding (may be lossy for binary data)
+            const text = new TextDecoder().decode(bytes);
+            return { ...base, content: text, encoding };
+        }
+        // fallback to base64 if unsupported encoding is passed
+        return { ...base, content: Compression.to_base64(bytes, { url_safe: false }), encoding: "base64" };
+    }
+    /** Clone the attachment, including bytes and metadata. */
+    clone() {
+        return new Attachment({
+            name: this.name,
+            path: this.path,
+            mime_type: this.mime_type,
+            charset: this.charset,
+            bytes: this.bytes(),
+            file: this.file,
+            compressed: this.compressed,
+        });
+    }
+}
+(function (Attachment) {
+    /** Create an Attachment from a Blob/File; optionally read and compress. */
+    async function from_blob(blob, opts = {}) {
+        const name = (opts.name ?? blob.name) || "blob";
+        const mime_type = blob.type || "";
+        const charset = (() => {
+            const label = opts.charset ?? "auto";
+            if (label !== "auto")
+                return label;
+            const m = /charset\s*=\s*([^;]+)/i.exec(mime_type);
+            return m ? m[1].trim().toLowerCase() : undefined;
+        })();
+        const att = new Attachment({ name, mime_type, charset, file: blob, bytes: new Uint8Array(0), compressed: false });
+        if (opts.read !== false) {
+            const ab = "arrayBuffer" in blob
+                ? await blob.arrayBuffer()
+                : await new Promise((res, rej) => {
+                    const r = new FileReader();
+                    r.onerror = () => rej(r.error);
+                    r.onload = () => res(r.result);
+                    r.readAsArrayBuffer(blob);
+                });
+            att.set_bytes(new Uint8Array(ab), false);
+            if (opts.compress)
+                att.compress();
+        }
+        return att;
+    }
+    Attachment.from_blob = from_blob;
+    /**
+     * Handle drag/drop; recursively traverses directories and adds only files.
+     * Uses FS Access API when available, falls back to WebKit entries, otherwise flat files only.
+     */
+    function on_drop(node, sink, opts) {
+        let { callback, read = true, compress = false, on_start, on_stop, on_error = (e) => console.error(e), max_size = 50 * 1024 * 1024, total_max_size = 50 * 1024 * 1024, } = opts;
+        /** Sum current sink sizes. */
+        const sink_total = () => sink.reduce((a, b) => a + b.size, 0);
+        /** Guard size constraints. */
+        const enforce_sizes = (file) => {
+            if (max_size !== -1 && file.size > max_size) {
+                on_error(new Error(`Attachment '${file.name}' exceeds the size limit of ${Math.round(max_size / (1024 * 1024))}MB.`));
+                return false;
+            }
+            if (total_max_size !== -1 && (sink_total() + file.size) > total_max_size) {
+                on_error(new Error(`Attachment '${file.name}' exceeds the total size limit of ${Math.round(total_max_size / (1024 * 1024))}MB.`));
+                return false;
+            }
+            return true;
+        };
+        /** Push a file as Attachment (respects read/compress). */
+        const push_file = async (file, rel_path = "") => {
+            if (!enforce_sizes(file))
+                return;
+            try {
+                const att = await Attachment.from_blob(file, { read, compress });
+                att.path = rel_path || file.path || file.name;
+                sink.push(att);
+                callback(att);
+            }
+            catch (e) {
+                on_error(e instanceof Error ? e : new Error(String(e)));
+            }
+        };
+        /** FS Access API: recursively collect files from a directory handle. */
+        const walk_fs_handle = async (handle, prefix = "") => {
+            if (handle.kind === "file") {
+                const file = await handle.getFile();
+                await push_file(file, `${prefix}${file.name}`);
+                return;
+            }
+            if (handle.kind === "directory") {
+                // @ts-ignore: async iterator is standard on Chromium
+                for await (const [name, child] of handle.entries()) {
+                    await walk_fs_handle(child, `${prefix}${name}/`);
+                }
+            }
+        };
+        /** WebKit fallback: recursively collect files from a FileSystemEntry directory. */
+        const walk_webkit_entry = async (entry, prefix = "") => {
+            if (entry.isFile) {
+                await new Promise((resolve, reject) => {
+                    entry.file(async (file) => { try {
+                        await push_file(file, `${prefix}${file.name}`);
+                        resolve();
+                    }
+                    catch (e) {
+                        reject(e);
+                    } }, reject);
+                });
+                return;
+            }
+            if (entry.isDirectory) {
+                const reader = entry.createReader();
+                const read_all = async () => new Promise((res, rej) => reader.readEntries((ents) => res(ents), rej));
+                // readEntries may return partial batches; keep reading until empty
+                for (;;) {
+                    const batch = await read_all();
+                    if (!batch.length)
+                        break;
+                    for (const child of batch) {
+                        await walk_webkit_entry(child, `${prefix}${entry.name ? entry.name + "/" : ""}${child.name ? "" : ""}`);
+                        // Note: child.name is already included when recursing into child; build prefix at directory level:
+                    }
+                }
+            }
+        };
+        node.ondragover = (event) => {
+            event.preventDefault();
+            event.dataTransfer && (event.dataTransfer.dropEffect = "copy");
+            on_start?.(event);
+        };
+        node.ondragend = (event) => { event.preventDefault(); on_stop?.(event); };
+        node.ondrop = (event) => {
+            event.preventDefault();
+            const items = event.dataTransfer?.items;
+            if (!items)
+                return;
+            // Process each DataTransferItem
+            (async () => {
+                for (let i = 0; i < items.length; i++) {
+                    const item = items[i];
+                    if (item.kind !== "file")
+                        continue;
+                    // Prefer FS Access API if available.
+                    const get_handle = item.getAsFileSystemHandle?.bind(item);
+                    if (get_handle) {
+                        try {
+                            const handle = await get_handle();
+                            // handle can be file or directory
+                            await walk_fs_handle(handle, "");
+                            continue;
+                        }
+                        catch { /* fall through to other paths */ }
+                    }
+                    // WebKit directory traversal fallback.
+                    const entry = item.webkitGetAsEntry?.();
+                    if (entry && (entry.isDirectory || entry.isFile)) {
+                        try {
+                            await walk_webkit_entry(entry, "");
+                            continue;
+                        }
+                        catch { /* fall through */ }
+                    }
+                    // Basic file fallback: just the file (most browsers).
+                    const file = item.getAsFile();
+                    if (file)
+                        await push_file(file, file.name);
+                }
+            })().catch((e) => on_error(e instanceof Error ? e : new Error(String(e))));
+        };
+    }
+    Attachment.on_drop = on_drop;
+})(Attachment || (Attachment = {}));

package/frontend/dist/frontend/src/modules/auth.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+import type { Users as UsersBackend } from "../../../backend/src/users.js";
+import { Request } from "./request.js";
+export declare namespace Auth {
+    /**
+     * Make a sign in request.
+     * @param payload The request payload.
+     * @docs
+     */
+    function sign_in(payload: UsersBackend.Endpoints.SignIn["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.SignIn>;
+    /**
+     * Make a sign up request.
+     *
+     * Note that a request can be made first without the `payload.code` field,
+     * when all other fields are correctly defined it will return a {@link Status.two_factor_auth_required} backend status.
+     * Indicating a two-factor authentication challenge is sent, prompt the user to the next screen where the user can fill in the 2fa code.
+     * Then retrieve the 2fa code and resubmit the request with the code included.
+     *
+     * @param payload The request payload.
+     * @docs
+     */
+    function sign_up(payload: UsersBackend.Endpoints.SignUp["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.SignUp>;
+    /**
+     * Make a sign out request.
+     * @docs
+     */
+    function sign_out(): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.SignOut>;
+    /**
+     * Make a send 2FA request.
+     * @param payload The request payload.
+     * @docs
+     */
+    function send_2fa(payload: UsersBackend.Endpoints.Send2FA["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.Send2FA>;
+    /**
+     * Make a forgot password request.
+     * @param payload The request payload.
+     * @docs
+     */
+    function forgot_password(payload: UsersBackend.Endpoints.ForgotPassword["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.ForgotPassword>;
+}
+export { Auth as auth };

package/frontend/dist/frontend/src/modules/auth.js

@@ -0,0 +1,80 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+import { request } from "./request.js";
+// Namespace.
+export var Auth;
+(function (Auth) {
+    /**
+     * Make a sign in request.
+     * @param payload The request payload.
+     * @docs
+     */
+    function sign_in(payload) {
+        return request({
+            method: "POST",
+            url: "/volt/api/v1/auth/signin",
+            data: payload,
+        });
+    }
+    Auth.sign_in = sign_in;
+    /**
+     * Make a sign up request.
+     *
+     * Note that a request can be made first without the `payload.code` field,
+     * when all other fields are correctly defined it will return a {@link Status.two_factor_auth_required} backend status.
+     * Indicating a two-factor authentication challenge is sent, prompt the user to the next screen where the user can fill in the 2fa code.
+     * Then retrieve the 2fa code and resubmit the request with the code included.
+     *
+     * @param payload The request payload.
+     * @docs
+     */
+    function sign_up(payload) {
+        return request({
+            method: "POST",
+            url: "/volt/api/v1/auth/signup",
+            data: payload,
+        });
+    }
+    Auth.sign_up = sign_up;
+    /**
+     * Make a sign out request.
+     * @docs
+     */
+    function sign_out() {
+        return request({
+            method: "POST",
+            url: "/volt/api/v1/auth/signout",
+        });
+    }
+    Auth.sign_out = sign_out;
+    /**
+     * Make a send 2FA request.
+     * @param payload The request payload.
+     * @docs
+     */
+    function send_2fa(payload) {
+        return request({
+            method: "POST",
+            url: "/volt/api/v1/auth/2fa",
+            data: payload,
+        });
+    }
+    Auth.send_2fa = send_2fa;
+    /**
+     * Make a forgot password request.
+     * @param payload The request payload.
+     * @docs
+     */
+    function forgot_password(payload) {
+        return request({
+            method: "POST",
+            url: "/volt/api/v1/auth/forgot_password",
+            data: payload,
+        });
+    }
+    Auth.forgot_password = forgot_password;
+})(Auth || (Auth = {}));
+;
+export { Auth as auth }; // also export as lowercase for compatibility.

package/frontend/dist/{modules → frontend/src/modules}/color.js

@@ -1,4 +1,4 @@
-import { Scheme } from "@vandenberghinc/vlib/frontend";
+import { Schema } from "@vandenberghinc/vlib/frontend";
 /**
  * A utility class for color manipulation, conversion, and adjustment.
  * Accepts colors in hex (e.g. "#ff0000"), RGB/RGBA strings (e.g. "rgb(255, 0, 0)" or "rgba(255,0,0,1)"),
@@ -73,7 +73,7 @@ export class Color {
         else if (Array.isArray(input)) {
             return Color.array_to_rgba(input);
         }
-        throw new Error(`Invalid color input "${input}" with type "${Scheme.value_type(input)}". Ensure the input is a hex or rgb(a) color.`);
+        throw new Error(`Invalid color input "${input}" with type "${Schema.value_type(input)}". Ensure the input is a hex or rgb(a) color.`);
     }
     /**
      * Converts a numeric array to an RGBA object.

package/frontend/dist/frontend/src/modules/compression.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+import type { DeflateOptions } from "pako";
+/**
+ * Compression module.
+ * @nav Compression
+ */
+export declare namespace Compression {
+    /** Bytes-like inputs accepted by this wrapper (string must be pre-encoded if you want raw bytes). */
+    type BytesLike = Uint8Array | ArrayBuffer | DataView | ArrayLike<number> | Buffer;
+    /** GZip options passed through to pako.gzip. */
+    type GzipOptions = DeflateOptions;
+    /** Encode a UTF-8 string to bytes. */
+    function encode_utf8(str: string): Uint8Array;
+    /** Decode UTF-8 bytes to string. */
+    function decode_utf8(bytes: BytesLike): string;
+    /** Encode raw bytes to Base64 (URL-safe optional). */
+    function to_base64(bytes: BytesLike, opts?: {
+        url_safe?: boolean;
+    }): string;
+    /** Decode Base64 to bytes (supports URL-safe). */
+    function from_base64(b64: string): Uint8Array;
+    /** Internal: normalize various byte-like inputs to Uint8Array. */
+    function to_uint8(x: BytesLike): Uint8Array;
+    /** Compress bytes using gzip (no implicit stringify). */
+    function compress(data: BytesLike | string, options?: GzipOptions): Uint8Array;
+    /** Compress a JSON object or array. */
+    function compress_json(blob: Record<string, any> | any[], options?: GzipOptions): Promise<Uint8Array>;
+    /** Compress a Blob/File using FileReader (browser-safe). */
+    function compress_blob(blob: Blob | File, options?: GzipOptions): Promise<Uint8Array>;
+    /** Decompress gzip to raw bytes (use decode_utf8 / json_from_bytes explicitly if needed). */
+    function decompress(data: BytesLike): Uint8Array;
+    /** Decompress gzip and return a UTF-8 string. */
+    function decompress_to_string(data: BytesLike): string;
+    /** Decompress gzip and return parsed JSON. */
+    function decompress_to_json<T = unknown>(data: BytesLike): T;
+}

package/frontend/dist/frontend/src/modules/compression.js

@@ -0,0 +1,102 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+import * as pako from "pako";
+/**
+ * Compression module.
+ * @nav Compression
+ */
+export var Compression;
+(function (Compression) {
+    // ---------------------------------------------------------
+    // Types.
+    // ---------------------------------------------------------
+    // 
+    /** Encode a UTF-8 string to bytes. */
+    function encode_utf8(str) {
+        return new TextEncoder().encode(str);
+    }
+    Compression.encode_utf8 = encode_utf8;
+    /** Decode UTF-8 bytes to string. */
+    function decode_utf8(bytes) {
+        return new TextDecoder().decode(to_uint8(bytes));
+    }
+    Compression.decode_utf8 = decode_utf8;
+    /** Encode raw bytes to Base64 (URL-safe optional). */
+    function to_base64(bytes, opts) {
+        const b = to_uint8(bytes);
+        const s = (typeof window !== "undefined" && "btoa" in window)
+            ? btoa(String.fromCharCode(...b))
+            : Buffer.from(b).toString("base64");
+        if (opts?.url_safe) {
+            return s.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+        }
+        return s;
+    }
+    Compression.to_base64 = to_base64;
+    /** Decode Base64 to bytes (supports URL-safe). */
+    function from_base64(b64) {
+        const norm = b64.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((b64.length + 3) % 4);
+        if (typeof window !== "undefined" && "atob" in window) {
+            const bin = atob(norm);
+            const out = new Uint8Array(bin.length);
+            for (let i = 0; i < bin.length; i++)
+                out[i] = bin.charCodeAt(i);
+            return out;
+        }
+        return new Uint8Array(Buffer.from(norm, "base64"));
+    }
+    Compression.from_base64 = from_base64;
+    /** Internal: normalize various byte-like inputs to Uint8Array. */
+    function to_uint8(x) {
+        if (x instanceof Uint8Array)
+            return x;
+        if (x instanceof ArrayBuffer)
+            return new Uint8Array(x);
+        if (x instanceof DataView)
+            return new Uint8Array(x.buffer, x.byteOffset, x.byteLength);
+        // Covers Buffer and generic ArrayLike<number> without copying if already Uint8Array/Buffer.
+        return new Uint8Array(x);
+    }
+    Compression.to_uint8 = to_uint8;
+    // ---------------------------------------------------------
+    // Compression.
+    /** Compress bytes using gzip (no implicit stringify). */
+    function compress(data, options = { level: 9 }) {
+        const input = typeof data === "string" ? encode_utf8(data) : to_uint8(data);
+        return pako.gzip(input, options);
+    }
+    Compression.compress = compress;
+    /** Compress a JSON object or array. */
+    async function compress_json(blob, options = { level: 9 }) {
+        return compress(encode_utf8(JSON.stringify(blob)), options);
+    }
+    Compression.compress_json = compress_json;
+    /** Compress a Blob/File using FileReader (browser-safe). */
+    async function compress_blob(blob, options = { level: 9 }) {
+        const ab = await new Promise((resolve, reject) => {
+            const r = new FileReader();
+            r.onerror = () => reject(r.error);
+            r.onload = () => resolve(r.result);
+            r.readAsArrayBuffer(blob);
+        });
+        return pako.gzip(new Uint8Array(ab), options);
+    }
+    Compression.compress_blob = compress_blob;
+    /** Decompress gzip to raw bytes (use decode_utf8 / json_from_bytes explicitly if needed). */
+    function decompress(data) {
+        return pako.ungzip(to_uint8(data));
+    }
+    Compression.decompress = decompress;
+    /** Decompress gzip and return a UTF-8 string. */
+    function decompress_to_string(data) {
+        return decode_utf8(decompress(data));
+    }
+    Compression.decompress_to_string = decompress_to_string;
+    /** Decompress gzip and return parsed JSON. */
+    function decompress_to_json(data) {
+        return JSON.parse(decode_utf8(decompress(data)));
+    }
+    Compression.decompress_to_json = decompress_to_json;
+})(Compression || (Compression = {}));

package/frontend/dist/frontend/src/modules/cookies.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+export declare namespace Cookies {
+    let enabled: boolean;
+    /**
+     * Checks if cookies need to be parsed again.
+     * @docs
+     */
+    function is_parse_required(): boolean;
+    /**
+     * Get cookies or a specific cookie by name.
+     * @experimental true
+     * @param name The name of the cookie.
+     * @docs
+     */
+    function get(name?: string | null): string | {
+        [key: string]: string;
+    } | undefined;
+    /**
+     * Checks if the user has set a cookie preference (enabled or disabled).
+     * @docs
+     */
+    function has_preference(): boolean;
+    /**
+     * Checks if cookies are accepted by the user.
+     * @docs
+     */
+    function is_accepted(): boolean;
+    /**
+     * Enables cookies (opt-in) and updates the user's preference.
+     * @param _set_storage Whether to update the localStorage preference (default: true).
+     * @docs
+     */
+    function enable(_set_storage?: boolean): void;
+    /**
+     * Disables cookies (opt-out) and updates the user's preference.
+     * @param _set_storage Whether to update the localStorage preference (default: true).
+     * @docs
+     */
+    function disable(_set_storage?: boolean): void;
+}
+export { Cookies as cookies };