@vandenberghinc/volt 1.2.6 → 1.2.8

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

@@ -0,0 +1,164 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+import type { User as UserBackend, Users as UsersBackend } from "../../../backend/src/users.js";
+import { Request } from "./request.js";
+export declare namespace User {
+    /**
+     * Frontend user object as exposed by the backend.
+     */
+    type UserObject = UserBackend.Frontend;
+    /**
+     * Get the user ID of the authenticated user.
+     * @nav Frontend/User
+     * @type undefined, string
+     * @return Returns the user ID when the user is authenticated and `undefined` when the user is not authenticated.
+     * @docs
+     */
+    function uid(): string | undefined;
+    /**
+     * Get the username of the authenticated user.
+     * @nav Frontend/User
+     * @type undefined, string
+     * @return Returns the user's username when the user is authenticated and `undefined` when the user is not authenticated.
+     * @docs
+     */
+    function username(): string | undefined;
+    /**
+     * Get the email of the authenticated user.
+     * @nav Frontend/User
+     * @type undefined, string
+     * @return Returns the user's email when the user is authenticated and `undefined` when the user is not authenticated.
+     * @docs
+     */
+    function email(): string | undefined;
+    /**
+     * Get the first name of the authenticated user.
+     * @nav Frontend/User
+     * @type undefined, string
+     * @return Returns the user's first name when the user is authenticated and `undefined` when the user is not authenticated.
+     * @docs
+     */
+    function first_name(): string | undefined;
+    /**
+     * Get the last name of the authenticated user.
+     * @nav Frontend/User
+     * @type undefined, string
+     * @return Returns the user's last name when the user is authenticated and `undefined` when the user is not authenticated.
+     * @docs
+     */
+    function last_name(): string | undefined;
+    /**
+     * Check if the current user is authenticated.
+     * @nav Frontend/User
+     * @type boolean
+     * @return Returns a boolean indicating whether the current user is authenticated.
+     * @docs
+     */
+    function is_authenticated(): boolean;
+    /**
+     * Check if the current user is activated.
+     * @nav Frontend/User
+     * @type boolean
+     * @return Returns a boolean indicating whether the current user is activated.
+     * @docs
+     */
+    function is_activated(): boolean;
+    /**
+     * Get the authenticated user object.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with the authenticated user's object or a request error on a failed request.
+     * @docs
+     */
+    function get(): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.GetUser>;
+    /**
+     * Update the authenticated user object.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    function update(payload: UsersBackend.Endpoints.UpdateUser["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.UpdateUser>;
+    /**
+     * Activate the authenticated user.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    function activate(payload: UsersBackend.Endpoints.ActivateUser["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.ActivateUser>;
+    /**
+     * Change the password of the authenticated user.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    function change_password(payload: UsersBackend.Endpoints.ChangePassword["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.ChangePassword>;
+    /**
+     * Delete the user account.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    function delete_account(): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.DeleteUser>;
+    /**
+     * Generate a new API key for the authenticated user.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response with the newly generated API key as an attribute or a request error on a failed request.
+     * @docs
+     */
+    function generate_api_key(): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.GenerateAPIKey>;
+    /**
+     * Generate a new API key for the authenticated user.
+     * @nav Frontend/User
+     * @docs
+     */
+    function has_api_key(): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.HasAPIKey>;
+    /**
+     * Revoke the API key of the authenticated user.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    function revoke_api_key(): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.RevokeAPIKey>;
+    /**
+     * Load data from the authenticated user's database.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with the loaded user's data or a request error on a failed request.
+     *         When the document is not found, an error response with status `404` and type `document_not_found` will be returned,
+     *         unless a `default` value is provided in the request payload. In that case, the default value will be inserted
+     * @docs
+     */
+    function load_data(payload: UsersBackend.Endpoints.LoadUserData["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.LoadUserData>;
+    /**
+     * Set data to the authenticated user's database, only updating the supplied fields.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    function set_data(payload: UsersBackend.Endpoints.SetUserData["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.SetUserData>;
+    /**
+     * Delete public user data.
+     * @nav Frontend/User
+     */
+    function delete_data(payload: UsersBackend.Endpoints.DeleteUserData["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.DeleteUserData>;
+    /**
+     * Load protected data from the authenticated user's database.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with the loaded user's data or a request error on a failed request.
+     *         When the document is not found, an error response with status `404` and type `document_not_found` will be returned,
+     *         unless a `default` value is provided in the request payload. In that case, the default value will be inserted
+     * @docs
+     */
+    function load_protected_data(payload: UsersBackend.Endpoints.LoadProtectedUserData["payload"]): Request.ResultPromiseFromInfo<UsersBackend.Endpoints.LoadProtectedUserData>;
+}
+export { User as user };

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

@@ -0,0 +1,270 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+// Imports.
+import { Cookies } from "./cookies";
+import { request } from "./request.js";
+// User module.
+export var User;
+(function (User) {
+    /**
+     * Get the user ID of the authenticated user.
+     * @nav Frontend/User
+     * @type undefined, string
+     * @return Returns the user ID when the user is authenticated and `undefined` when the user is not authenticated.
+     * @docs
+     */
+    function uid() {
+        const uid = Cookies.get("UserID");
+        return typeof uid !== "string" || uid == "-1" || uid === "" ? undefined : uid;
+    }
+    User.uid = uid;
+    /**
+     * Get the username of the authenticated user.
+     * @nav Frontend/User
+     * @type undefined, string
+     * @return Returns the user's username when the user is authenticated and `undefined` when the user is not authenticated.
+     * @docs
+     */
+    function username() {
+        const username = Cookies.get("UserName");
+        return typeof username !== "string" || username === "" ? undefined : username;
+    }
+    User.username = username;
+    /**
+     * Get the email of the authenticated user.
+     * @nav Frontend/User
+     * @type undefined, string
+     * @return Returns the user's email when the user is authenticated and `undefined` when the user is not authenticated.
+     * @docs
+     */
+    function email() {
+        const email = Cookies.get("UserEmail");
+        return typeof email !== "string" || email === "" ? undefined : email;
+    }
+    User.email = email;
+    /**
+     * Get the first name of the authenticated user.
+     * @nav Frontend/User
+     * @type undefined, string
+     * @return Returns the user's first name when the user is authenticated and `undefined` when the user is not authenticated.
+     * @docs
+     */
+    function first_name() {
+        const first_name = Cookies.get("UserFirstName");
+        return typeof first_name !== "string" || first_name === "" ? undefined : first_name;
+    }
+    User.first_name = first_name;
+    /**
+     * Get the last name of the authenticated user.
+     * @nav Frontend/User
+     * @type undefined, string
+     * @return Returns the user's last name when the user is authenticated and `undefined` when the user is not authenticated.
+     * @docs
+     */
+    function last_name() {
+        const last_name = Cookies.get("UserLastName");
+        return typeof last_name !== "string" || last_name === "" ? undefined : last_name;
+    }
+    User.last_name = last_name;
+    /**
+     * Check if the current user is authenticated.
+     * @nav Frontend/User
+     * @type boolean
+     * @return Returns a boolean indicating whether the current user is authenticated.
+     * @docs
+     */
+    function is_authenticated() {
+        return User.uid() != undefined;
+    }
+    User.is_authenticated = is_authenticated;
+    /**
+     * Check if the current user is activated.
+     * @nav Frontend/User
+     * @type boolean
+     * @return Returns a boolean indicating whether the current user is activated.
+     * @docs
+     */
+    function is_activated() {
+        const activated = Cookies.get("UserActivated");
+        return activated === "true" || activated === "1";
+    }
+    User.is_activated = is_activated;
+    /**
+     * Get the authenticated user object.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with the authenticated user's object or a request error on a failed request.
+     * @docs
+     */
+    async function get() {
+        return request({
+            method: "GET",
+            url: "/volt/api/v1/user",
+        });
+    }
+    User.get = get;
+    /**
+     * Update the authenticated user object.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    async function update(payload) {
+        return request({
+            method: "POST",
+            url: "/volt/api/v1/user",
+            data: payload,
+        });
+    }
+    User.update = update;
+    /**
+     * Activate the authenticated user.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    async function activate(payload) {
+        return request({
+            method: "POST",
+            url: "/volt/api/v1/auth/activate",
+            data: payload,
+        });
+    }
+    User.activate = activate;
+    /**
+     * Change the password of the authenticated user.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    async function change_password(payload) {
+        return request({
+            method: "POST",
+            url: "/volt/api/v1/user/change_password",
+            data: payload,
+        });
+    }
+    User.change_password = change_password;
+    /**
+     * Delete the user account.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    async function delete_account() {
+        return request({
+            method: "DELETE",
+            url: "/volt/api/v1/user",
+        });
+    }
+    User.delete_account = delete_account;
+    /**
+     * Generate a new API key for the authenticated user.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response with the newly generated API key as an attribute or a request error on a failed request.
+     * @docs
+     */
+    async function generate_api_key() {
+        return request({
+            method: "POST",
+            url: "/volt/api/v1/user/api_key",
+        });
+    }
+    User.generate_api_key = generate_api_key;
+    /**
+     * Generate a new API key for the authenticated user.
+     * @nav Frontend/User
+     * @docs
+     */
+    async function has_api_key() {
+        return request({
+            method: "GET",
+            url: "/volt/api/v1/user/has_api_key",
+        });
+    }
+    User.has_api_key = has_api_key;
+    /**
+     * Revoke the API key of the authenticated user.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    async function revoke_api_key() {
+        return request({
+            method: "DELETE",
+            url: "/volt/api/v1/user/api_key",
+        });
+    }
+    User.revoke_api_key = revoke_api_key;
+    /**
+     * Load data from the authenticated user's database.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with the loaded user's data or a request error on a failed request.
+     *         When the document is not found, an error response with status `404` and type `document_not_found` will be returned,
+     *         unless a `default` value is provided in the request payload. In that case, the default value will be inserted
+     * @docs
+     */
+    async function load_data(payload) {
+        return request({
+            method: "GET",
+            url: "/volt/api/v1/user/data",
+            data: payload,
+        });
+    }
+    User.load_data = load_data;
+    /**
+     * Set data to the authenticated user's database, only updating the supplied fields.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with a successful update response or a request error on a failed request.
+     * @docs
+     */
+    async function set_data(payload) {
+        return request({
+            method: "POST",
+            url: "/volt/api/v1/user/data",
+            data: payload,
+        });
+    }
+    User.set_data = set_data;
+    /**
+     * Delete public user data.
+     * @nav Frontend/User
+     */
+    async function delete_data(payload) {
+        return request({
+            method: "DELETE",
+            url: "/volt/api/v1/user/data",
+            data: payload,
+        });
+    }
+    User.delete_data = delete_data;
+    /**
+     * Load protected data from the authenticated user's database.
+     * @nav Frontend/User
+     * @type Promise
+     * @return Returns a promise with the loaded user's data or a request error on a failed request.
+     *         When the document is not found, an error response with status `404` and type `document_not_found` will be returned,
+     *         unless a `default` value is provided in the request payload. In that case, the default value will be inserted
+     * @docs
+     */
+    async function load_protected_data(payload) {
+        return request({
+            method: "GET",
+            url: "/volt/api/v1/user/data/protected",
+            data: payload,
+        });
+    }
+    User.load_protected_data = load_protected_data;
+})(User || (User = {}));
+;
+export { User as user }; // also export as lowercase for compatibility.

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

@@ -0,0 +1,176 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+import { AnyElement } from "../ui/any_element.js";
+/** Utils module.  */
+export declare namespace Utils {
+    /** True if the current browser's vendor string indicates Apple (e.g., Safari on iOS/macOS). */
+    const is_apple: boolean;
+    /** True if the current browser is identified via vendor as Safari/Apple (same check as {@link is_apple}). */
+    const is_safari: boolean;
+    /**
+     * Determine whether the provided value is a string.
+     * @param value The value to check.
+     * @returns Returns true if the value is a string, otherwise false.
+     * @docs
+     */
+    function is_string(value: any): value is string;
+    /**
+     * Determine whether the provided value is a finite number.
+     * @param value The value to check.
+     * @returns Returns true if the value is a finite number, otherwise false.
+     * @docs
+     */
+    function is_numeric(value: any): value is number;
+    /**
+     * Determine whether the provided value is an integer.
+     * @param value The value to check.
+     * @returns Returns true if the value is an integer, otherwise false.
+     * @docs
+     */
+    function is_int(value: any): value is number;
+    /**
+     * Determine whether the provided value is a floating-point number.
+     * @param value The value to check.
+     * @returns Returns true if the value is a float, otherwise false.
+     * @docs
+     */
+    function is_float(value: any): value is number;
+    /**
+     * Determine whether the provided value is a function.
+     * @param value The value to check.
+     * @returns Returns true if the value is a function, otherwise false.
+     * @docs
+     */
+    function is_func(value: any): value is Function;
+    /**
+     * Determine whether the provided value is an array.
+     * @param value The value to check.
+     * @returns Returns true if the value is an array, otherwise false.
+     * @docs
+     */
+    function is_array(value: any): value is Array<any>;
+    /**
+     * Determine whether the provided value is a non-array object.
+     * @param value The value to check.
+     * @returns Returns true if the value is an object and not an array, otherwise false.
+     * @docs
+     */
+    function is_obj(value: any): value is object;
+    /**
+     * Determine whether the provided number is even.
+     * @param number The number to check.
+     * @returns Returns true if the number is even, otherwise false.
+     * @docs
+     */
+    function is_even(number: number): boolean;
+    /**
+     * Check if the user agent is a mobile device.
+     * @returns Returns true when a mobile user agent is detected.
+     * @docs
+     */
+    function is_mobile(): boolean;
+    /**
+     * Make all objects of an array or object immutable. All nested objects will also be made immutable recursively.
+     * @param object The array or object to freeze.
+     * @docs
+     */
+    function make_immutable(object: any): any;
+    /**
+     * Check if an element is a direct child of an element or the parent element itself.
+     * @param parent The parent element to test.
+     * @param target The target element to test.
+     * @docs
+     */
+    function is_child(parent: any, target: any): boolean;
+    /**
+     * Check if an element is a recursively nested child of an element or the parent element itself.
+     * @param parent The parent element to test.
+     * @param target The target element to test.
+     * @param stop_node A node at which to stop checking if target is a parent of the current element.
+     * @docs
+     */
+    function is_nested_child(parent: any, target: any, stop_node?: any): boolean;
+    /**
+     * Round a number to a specified number of decimal places.
+     * @param value The number to round.
+     * @param decimals The number of decimal places.
+     * @returns The rounded number.
+     * @docs
+     */
+    function round(value: number, decimals: number): number;
+    /**
+     * Get the width of the device's viewport.
+     * @returns The width of the device's viewport.
+     * @docs
+     */
+    function device_width(): number;
+    /**
+     * Get the height of the device's viewport.
+     * @returns The height of the device's viewport.
+     * @docs
+     */
+    function device_height(): number;
+    /**
+     * Get the endpoint sub URL of a full domain URL. When parameter "url" is undefined, it uses the current URL.
+     * @param url The full domain URL.
+     * @returns The endpoint sub URL.
+     * @docs
+     */
+    function endpoint(url?: string | null): string;
+    /**
+     * Execute a function when the content is loaded, optionally handling a splash screen.
+     * @param func The function to execute when the content is loaded.
+     * @returns void
+     * @docs
+     */
+    function on_load(func: () => HTMLElement | AnyElement | Promise<HTMLElement | AnyElement> | null | undefined): Promise<void>;
+    /**
+     * Redirect to a specified URL, optionally forcing the redirect even if the endpoint is the same.
+     * @param url The URL to redirect to.
+     * @param forced Whether to force the redirect even if the current endpoint is the same as the target URL.
+     * @docs
+     */
+    function redirect(url: string, forced?: boolean): void;
+    /**
+     * Get a URL parameter by name, with an optional default value.
+     * @param name The name of the URL parameter.
+     * @param def The default value to return if the parameter is not found.
+     * @returns The value of the URL parameter or the default value.
+     * @docs
+     */
+    function url_param(name: string, def?: any): any | null;
+    /**
+     * Encode an object into a URL-encoded query string.
+     * @param params The parameters to encode.
+     * @returns The URL-encoded query string.
+     * @docs
+     */
+    function url_encode(params: Record<string, any>): string;
+    /**
+     * Copy text to the clipboard.
+     * @param text The text to copy.
+     * @returns A Promise that resolves when the text is copied.
+     * @docs
+     */
+    function copy_to_clipboard(text: string): Promise<void>;
+    /**
+     * Create a debounced version of a function that delays invoking it until after a specified delay.
+     * @param delay The number of milliseconds to delay.
+     * @param func The function to debounce.
+     * @returns The debounced function.
+     * @docs
+     */
+    function debounce(delay: number, func: (...args: any[]) => void): (...args: any[]) => void;
+    /**
+     * @deprecated Use vlib.VDate instead.
+     * Convert a Unix timestamp in seconds or milliseconds to the user's date format.
+     * @param unix The Unix timestamp.
+     * @param mseconds Optional. Whether the Unix timestamp is in milliseconds.
+     * @returns The formatted date string.
+     * @docs
+     */
+    function unix_to_date(unix: number, mseconds?: boolean | null): string;
+}
+export { Utils as utils };