desktopr 1.3.1 → 2.0.0

package/dist-sdk/utils/shared/_types.d.ts

@@ -0,0 +1,64 @@
+export type ColorInfo = {
+    HEX: string;
+    RGB: {
+        R: number;
+        G: number;
+        B: number;
+    };
+    TAILWIND_CLASS: string;
+};
+export type AppRoute = {
+    id: string;
+    title: string;
+    description?: string;
+};
+export type VoidFunction = () => void;
+export type AuthMode = "signin" | "signup" | "forgot_password" | null | undefined;
+export type PasswordStrength = {
+    text: 'very weak';
+    score: 0;
+} | {
+    text: 'weak';
+    score: 1;
+} | {
+    text: 'medium';
+    score: 2;
+} | {
+    text: 'strong';
+    score: 3;
+} | {
+    text: 'very strong';
+    score: 4;
+};
+export type TailwindWidth = '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' | '7xl';
+export type TableData = {
+    id?: string;
+    title?: string;
+    columns: string[];
+    rows: (string | number | boolean | null)[][];
+    enableHorizontalHeader?: boolean;
+};
+export type CheckboxSetOption = {
+    value: string | number;
+    label: string;
+    id?: string;
+    description?: string;
+};
+export type DropdownOption = {
+    label: string;
+    value: string | number;
+    id: string;
+    flag?: string;
+};
+export type ComboboxOption = DropdownOption & {
+    description?: string;
+};
+export type AnyObject = Record<string, any>;
+export type HexColor = `#${string}`;
+export type RgbColor = `rgb(${number}, ${number}, ${number})`;
+export type RgbaColor = `rgba(${number}, ${number}, ${number}, ${number})`;
+export type HslColor = `hsl(${number}, ${number}%, ${number}%)`;
+export type HslaColor = `hsla(${number}, ${number}%, ${number}%, ${number})`;
+export type ColorString = HexColor | RgbColor | RgbaColor | HslColor | HslaColor;
+export type CssNamedColor = 'aliceblue' | 'antiquewhite' | 'aqua' | 'aquamarine' | 'azure' | 'beige' | 'bisque' | 'black' | 'blanchedalmond' | 'blue' | 'blueviolet' | 'brown' | 'burlywood' | 'cadetblue' | 'chartreuse' | 'chocolate' | 'coral' | 'cornflowerblue' | 'cornsilk' | 'crimson' | 'cyan' | 'darkblue' | 'darkcyan' | 'darkgoldenrod' | 'darkgray' | 'darkgreen' | 'darkgrey' | 'darkkhaki' | 'darkmagenta' | 'darkolivegreen' | 'darkorange' | 'darkorchid' | 'darkred' | 'darksalmon' | 'darkseagreen' | 'darkslateblue' | 'darkslategray' | 'darkslategrey' | 'darkturquoise' | 'darkviolet' | 'deeppink' | 'deepskyblue' | 'dimgray' | 'dimgrey' | 'dodgerblue' | 'firebrick' | 'floralwhite' | 'forestgreen' | 'fuchsia' | 'gainsboro' | 'ghostwhite' | 'gold' | 'goldenrod' | 'gray' | 'green' | 'greenyellow' | 'grey' | 'honeydew' | 'hotpink' | 'indianred' | 'indigo' | 'ivory' | 'khaki' | 'lavender' | 'lavenderblush' | 'lawngreen' | 'lemonchiffon' | 'lightblue' | 'lightcoral' | 'lightcyan' | 'lightgoldenrodyellow' | 'lightgray' | 'lightgreen' | 'lightgrey' | 'lightpink' | 'lightsalmon' | 'lightseagreen' | 'lightskyblue' | 'lightslategray' | 'lightslategrey' | 'lightsteelblue' | 'lightyellow' | 'lime' | 'limegreen' | 'linen' | 'magenta' | 'maroon' | 'mediumaquamarine' | 'mediumblue' | 'mediumorchid' | 'mediumpurple' | 'mediumseagreen' | 'mediumslateblue' | 'mediumspringgreen' | 'mediumturquoise' | 'mediumvioletred' | 'midnightblue' | 'mintcream' | 'mistyrose' | 'moccasin' | 'navajowhite' | 'navy' | 'oldlace' | 'olive' | 'olivedrab' | 'orange' | 'orangered' | 'orchid' | 'palegoldenrod' | 'palegreen' | 'paleturquoise' | 'palevioletred' | 'papayawhip' | 'peachpuff' | 'peru' | 'pink' | 'plum' | 'powderblue' | 'purple' | 'rebeccapurple' | 'red' | 'rosybrown' | 'royalblue' | 'saddlebrown' | 'salmon' | 'sandybrown' | 'seagreen' | 'seashell' | 'sienna' | 'silver' | 'skyblue' | 'slateblue' | 'slategray' | 'slategrey' | 'snow' | 'springgreen' | 'steelblue' | 'tan' | 'teal' | 'thistle' | 'tomato' | 'turquoise' | 'violet' | 'wheat' | 'white' | 'whitesmoke' | 'yellow' | 'yellowgreen';
+export type StringLiteralJoin<T extends string[], Sep extends string = ''> = T extends [infer F extends string, ...infer R extends string[]] ? R['length'] extends 0 ? F : `${F}${Sep}${StringLiteralJoin<R, Sep>}` : '';

package/dist-sdk/utils/shared/_types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-sdk/utils/utils/_browserStorage.d.ts

@@ -0,0 +1,22 @@
+export type BrowserStorageType = "local" | "session";
+interface _BrowserStorageAPI {
+    getItem(key: string): unknown | null;
+    getNamespaceItems(): {
+        key: string;
+        value: unknown;
+    }[];
+    getItemsByKeys(keys: string[]): {
+        key: string;
+        value: unknown;
+    }[];
+    setItem(key: string, value: unknown, options?: {
+        expiresIn?: number;
+    }): void;
+    removeItem(key: string): void;
+    clear(): void;
+    clearExpired(): void;
+    length(): number;
+    keysList(): string[];
+}
+export declare function browserStorage(type: BrowserStorageType, namespace?: string): _BrowserStorageAPI;
+export {};

package/dist-sdk/utils/utils/_browserStorage.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserStorage = browserStorage;
+const _logger_1 = require("./_logger");
+const _isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+function browserStorage(type, namespace) {
+    const _storage = _isBrowser
+        ? type === "local"
+            ? localStorage
+            : sessionStorage
+        : undefined;
+    const _prefix = namespace ? `${namespace}:` : "";
+    function _fullKey(key) {
+        return `${_prefix}${key}`;
+    }
+    function getItem(key) {
+        if (!_isBrowser)
+            return null;
+        const raw = _storage?.getItem(_fullKey(key));
+        if (!raw)
+            return null;
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed.expiresAt && Date.now() > parsed.expiresAt) {
+                _storage?.removeItem(_fullKey(key));
+                return null;
+            }
+            return parsed.value;
+        }
+        catch {
+            return null;
+        }
+    }
+    function getNamespaceItems() {
+        if (!_isBrowser)
+            return [];
+        const items = [];
+        for (let i = 0; i < (_storage?.length ?? 0); i++) {
+            const fullKey = _storage?.key(i);
+            if (!fullKey || (_prefix && !fullKey.startsWith(_prefix)))
+                continue;
+            const key = fullKey.slice(_prefix.length); // rimuove il namespace
+            const raw = _storage?.getItem(fullKey);
+            if (!raw)
+                continue;
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed.expiresAt && Date.now() > parsed.expiresAt)
+                    continue;
+                items.push({ key, value: parsed.value });
+            }
+            catch {
+                // ignora valori corrotti
+            }
+        }
+        return items;
+    }
+    function getItemsByKeys(keys) {
+        if (!_isBrowser)
+            return [];
+        const items = [];
+        for (const key of keys) {
+            const fullKey = _fullKey(key);
+            const raw = _storage?.getItem(fullKey);
+            if (!raw)
+                continue;
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed.expiresAt && Date.now() > parsed.expiresAt)
+                    continue;
+                items.push({ key, value: parsed.value });
+            }
+            catch {
+                // ignora valori corrotti
+            }
+        }
+        return items;
+    }
+    function setItem(key, value, options) {
+        if (!_isBrowser)
+            return;
+        const expiresAt = options?.expiresIn
+            ? Date.now() + options.expiresIn * 1000
+            : undefined;
+        const payload = { value, expiresAt };
+        try {
+            _storage?.setItem(_fullKey(key), JSON.stringify(payload));
+        }
+        catch (err) {
+            _logger_1.logger.warn(`[browserStorage] Failed to set key "${key}"`, err);
+        }
+    }
+    function removeItem(key) {
+        if (!_isBrowser)
+            return;
+        _storage?.removeItem(_fullKey(key));
+    }
+    function clear() {
+        if (!_isBrowser)
+            return;
+        keysList().forEach((key) => _storage?.removeItem(key));
+    }
+    function clearExpired() {
+        if (!_isBrowser)
+            return;
+        keysList().forEach((key) => {
+            const raw = _storage?.getItem(key);
+            if (!raw)
+                return;
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed.expiresAt && Date.now() > parsed.expiresAt) {
+                    _storage?.removeItem(key);
+                }
+            }
+            catch {
+                // ignore
+            }
+        });
+    }
+    function length() {
+        if (!_isBrowser)
+            return 0;
+        return keysList().length;
+    }
+    function keysList() {
+        if (!_isBrowser)
+            return [];
+        const keys = [];
+        for (let i = 0; i < (_storage?.length ?? 0); i++) {
+            const key = _storage?.key(i);
+            if (key && (!_prefix || key.startsWith(_prefix))) {
+                keys.push(key);
+            }
+        }
+        return keys;
+    }
+    return {
+        getItem,
+        getNamespaceItems,
+        getItemsByKeys,
+        setItem,
+        removeItem,
+        clear,
+        clearExpired,
+        length,
+        keysList,
+    };
+}

package/dist-sdk/utils/utils/_integerUtils.d.ts

@@ -0,0 +1,50 @@
+export type Brand<Base, Tag extends string> = Base & {
+    readonly __brand: Tag;
+};
+export type U8 = Brand<number, "u8">;
+export type U16 = Brand<number, "u16">;
+export type U32 = Brand<number, "u32">;
+export type U64 = Brand<number, "u64">;
+export type I8 = Brand<number, "i8">;
+export type I16 = Brand<number, "i16">;
+export type I32 = Brand<number, "i32">;
+export type I64 = Brand<number, "i64">;
+export type F32 = Brand<number, "f32">;
+export type F64 = Brand<number, "f64">;
+export type NumberPredicate = (v: unknown) => v is number;
+export interface NumPredicates {
+    isU8: NumberPredicate;
+    isU16: NumberPredicate;
+    isU32: NumberPredicate;
+    isU64: NumberPredicate;
+    isI8: NumberPredicate;
+    isI16: NumberPredicate;
+    isI32: NumberPredicate;
+    isI64: NumberPredicate;
+    isF32: NumberPredicate;
+    isF64: NumberPredicate;
+}
+export interface Refinement<TBrand extends string> {
+    /** Type guard verso il tipo brandizzato */
+    is(v: unknown): v is Brand<number, TBrand>;
+    /** Costruttore che valida e lancia su input invalido */
+    as(v: unknown): Brand<number, TBrand>;
+    /** Costruttore “safe” che restituisce null se non valido */
+    try(v: unknown): Brand<number, TBrand> | null;
+    /** Parser da stringa (usa Number), valida e lancia su input invalido */
+    parse(s: string): Brand<number, TBrand>;
+}
+export interface NumAPI extends NumPredicates {
+    U8: Refinement<"u8">;
+    U16: Refinement<"u16">;
+    U32: Refinement<"u32">;
+    U64: Refinement<"u64">;
+    I8: Refinement<"i8">;
+    I16: Refinement<"i16">;
+    I32: Refinement<"i32">;
+    I64: Refinement<"i64">;
+    F32: Refinement<"f32">;
+    F64: Refinement<"f64">;
+}
+export declare const Pred: Readonly<NumPredicates>;
+export declare const Num: NumAPI;

package/dist-sdk/utils/utils/_integerUtils.js

@@ -0,0 +1,74 @@
+"use strict";
+// numberUtils.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Num = exports.Pred = void 0;
+// ---------- Runtime helpers ----------
+function isIntegerInRange(v, min, max) {
+    return typeof v === "number" && Number.isInteger(v) && v >= min && v <= max;
+}
+function isF32Runtime(v) {
+    return typeof v === "number" && Math.fround(v) === v;
+}
+// Predicati tipizzati e riusabili
+exports.Pred = {
+    // Unsigned
+    isU8: (v) => isIntegerInRange(v, 0, 0xFF),
+    isU16: (v) => isIntegerInRange(v, 0, 0xFFFF),
+    isU32: (v) => isIntegerInRange(v, 0, 0xFFFFFFFF),
+    isU64: (v) => isIntegerInRange(v, 0, Number.MAX_SAFE_INTEGER),
+    // Signed
+    isI8: (v) => isIntegerInRange(v, -0x80, 0x7F),
+    isI16: (v) => isIntegerInRange(v, -0x8000, 0x7FFF),
+    isI32: (v) => isIntegerInRange(v, -0x80000000, 0x7FFFFFFF),
+    isI64: (v) => typeof v === "number" &&
+        Number.isInteger(v) &&
+        v >= Number.MIN_SAFE_INTEGER &&
+        v <= Number.MAX_SAFE_INTEGER,
+    // Floats
+    isF32: (v) => isF32Runtime(v),
+    isF64: (v) => typeof v === "number",
+};
+// Factory per i refinements
+function makeRefinement(tag, isFn) {
+    return {
+        is: (v) => isFn(v),
+        as: (v) => {
+            if (!isFn(v))
+                throw new TypeError(`Expected ${tag}, got ${String(v)}`);
+            return v;
+        },
+        try: (v) => (isFn(v) ? v : null),
+        parse: (s) => {
+            const n = Number(s);
+            if (!Number.isFinite(n) || !isFn(n)) {
+                throw new TypeError(`Invalid ${tag} from "${s}"`);
+            }
+            return n;
+        },
+    };
+}
+// Implementazione + tipizzazione esplicita
+exports.Num = {
+    // Predicates (stile number.is...)
+    isU8: exports.Pred.isU8,
+    isU16: exports.Pred.isU16,
+    isU32: exports.Pred.isU32,
+    isU64: exports.Pred.isU64,
+    isI8: exports.Pred.isI8,
+    isI16: exports.Pred.isI16,
+    isI32: exports.Pred.isI32,
+    isI64: exports.Pred.isI64,
+    isF32: exports.Pred.isF32,
+    isF64: exports.Pred.isF64,
+    // Branded constructors / refiners
+    U8: makeRefinement("u8", exports.Pred.isU8),
+    U16: makeRefinement("u16", exports.Pred.isU16),
+    U32: makeRefinement("u32", exports.Pred.isU32),
+    U64: makeRefinement("u64", exports.Pred.isU64),
+    I8: makeRefinement("i8", exports.Pred.isI8),
+    I16: makeRefinement("i16", exports.Pred.isI16),
+    I32: makeRefinement("i32", exports.Pred.isI32),
+    I64: makeRefinement("i64", exports.Pred.isI64),
+    F32: makeRefinement("f32", exports.Pred.isF32),
+    F64: makeRefinement("f64", exports.Pred.isF64),
+};

package/dist-sdk/utils/utils/_jitter.d.ts

@@ -0,0 +1,4 @@
+export declare const backoffNoJitter: (attempt: number, baseMin?: number, capMin?: number) => number;
+export declare const addJitter: (minutes: number, ratio?: number) => number;
+export declare const fullJitter: (attempt: number, baseMin?: number, capMin?: number) => number;
+export declare const decorrelatedJitter: (prevMin: number, baseMin?: number, capMin?: number) => number;

package/dist-sdk/utils/utils/_jitter.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decorrelatedJitter = exports.fullJitter = exports.addJitter = exports.backoffNoJitter = void 0;
+// backoff "pulito" (senza jitter): base * 2^(n-1), con cap
+const backoffNoJitter = (attempt, baseMin = 15, capMin = 240) => Math.min(capMin, baseMin * Math.pow(2, Math.max(0, attempt - 1)));
+exports.backoffNoJitter = backoffNoJitter;
+// ±10% attorno al valore (equal jitter semplice)
+const addJitter = (minutes, ratio = 0.10) => {
+    const min = minutes * (1 - ratio);
+    const max = minutes * (1 + ratio);
+    return Math.round(min + Math.random() * (max - min));
+};
+exports.addJitter = addJitter;
+// Full jitter: scegli un valore casuale tra 0 e il backoff calcolato
+const fullJitter = (attempt, baseMin = 15, capMin = 240) => {
+    const d = (0, exports.backoffNoJitter)(attempt, baseMin, capMin);
+    return Math.round(Math.random() * d);
+};
+exports.fullJitter = fullJitter;
+// Decorrelated jitter (richiede il delay precedente)
+const decorrelatedJitter = (prevMin, baseMin = 15, capMin = 240) => {
+    const next = Math.min(capMin, Math.max(baseMin, Math.random() * (prevMin * 3)));
+    return Math.round(next);
+};
+exports.decorrelatedJitter = decorrelatedJitter;

package/dist-sdk/utils/utils/_json.d.ts

@@ -0,0 +1,63 @@
+import { AnySchema } from "ajv";
+/**
+ * Public interface for the jsonTools utility.
+ * Import this if you want to type variables or parameters that expose
+ * the same API surface as `jsonTools`.
+ */
+export interface JsonTools {
+    /**
+     * Validate a JSON string against an optional schema.
+     * - If `schema` is omitted: only checks JSON validity and returns the parsed value.
+     * - If `schema` is provided: validates using Ajv (draft-07 friendly).
+     */
+    validate<T = unknown>(jsonStr: string, schema?: AnySchema | string): {
+        ok: true;
+        data: T;
+    } | {
+        ok: false;
+        errors: string[];
+    };
+    /** Safely parse a JSON string without throwing. */
+    parse<T = unknown>(jsonStr: string): {
+        ok: true;
+        data: T;
+    } | {
+        ok: false;
+        error: string;
+    };
+    /** Safely stringify any value to JSON (handles circular refs and never throws). */
+    stringify(value: any, space?: number): string;
+    /** Pretty-print a JSON string with a given indentation (returns original if invalid). */
+    pretty(jsonStr: string, indent?: number): string;
+    /** Minify a JSON string by removing whitespace (returns original if invalid). */
+    compact(jsonStr: string): string;
+    /** Deep structural equality for JSON-compatible values (key-order insensitive for objects). */
+    isEqual(a: unknown, b: unknown): boolean;
+    /** Safely access nested properties via dot-path (supports numeric indices). */
+    get<T = unknown>(obj: any, path: string): T | undefined;
+    /**
+     * Non-mutating deep merge of two objects (arrays are overwritten).
+     * Returns a new object typed as the intersection T & U.
+     */
+    merge<T extends object, U extends object>(target: T, source: U): T & U;
+    /**
+     * Compute a flat diff map of paths to old/new values.
+     * Paths use dot notation; "(root)" indicates the root value.
+     */
+    diff(a: unknown, b: unknown): Record<string, {
+        oldValue: any;
+        newValue: any;
+    }>;
+    /** Summarize a JSON Schema for quick inspection (types, enums, properties). */
+    schemaSummary(schema: AnySchema): string;
+    /** Infer a minimal JSON Schema from an example value. */
+    inferSchema(example: unknown): AnySchema;
+}
+/**
+ * A small toolkit for working with JSON strings.
+ *
+ * @remarks
+ * - The only exported API is this default object `jsonTools`.
+ * - All functions are documented with JSDoc so tooltips are shown in IDEs.
+ */
+export declare const jsonTools: JsonTools;