@lucaapp/service-utils 2.0.9 → 4.0.0

package/dist/index.d.ts

@@ -11,4 +11,9 @@ export * from './lib/wsEvent';
 export * from './lib/lifecycle';
 export * from './lib/logger';
 export * from './lib/datetime';
+export * from './lib/proxy';
+export * from './lib/random';
+export * from './lib/crypto';
+export * from './lib/phone';
+export * from './lib/http';
 export * from './types';

package/dist/index.js

@@ -27,4 +27,9 @@ __exportStar(require("./lib/wsEvent"), exports);
 __exportStar(require("./lib/lifecycle"), exports);
 __exportStar(require("./lib/logger"), exports);
 __exportStar(require("./lib/datetime"), exports);
+__exportStar(require("./lib/proxy"), exports);
+__exportStar(require("./lib/random"), exports);
+__exportStar(require("./lib/crypto"), exports);
+__exportStar(require("./lib/phone"), exports);
+__exportStar(require("./lib/http"), exports);
 __exportStar(require("./types"), exports);

package/dist/lib/crypto/hash.d.ts

@@ -0,0 +1,46 @@
+import crypto from 'crypto';
+/**
+ * Hash a password using scrypt with a salt
+ * @param password - The password to hash
+ * @param salt - The salt to use for hashing
+ * @returns A promise that resolves to the hashed password as a Buffer
+ */
+export declare const hashPassword: (password: string, salt: string) => Promise<Buffer>;
+/**
+ * Generate a pseudo hash for testing or placeholder purposes
+ * @returns A promise that resolves to a pseudo hash as a Buffer
+ */
+export declare const pseudoHashPassword: () => Promise<Buffer>;
+/**
+ * Create a SHA-256 hash of the input data
+ * @param data - The data to hash
+ * @returns The SHA-256 hash as a hexadecimal string
+ */
+export declare const sha256: (data: string) => string;
+/**
+ * Create a SHA-256 hash of multiple data pieces concatenated
+ * @param dataArray - Array of strings to concatenate and hash
+ * @returns The concatenated SHA-256 hash as a hexadecimal string
+ */
+export declare const concatSha256: (dataArray: string[]) => string;
+/**
+ * Create an MD5 hash of the input data
+ * @param data - The data to hash
+ * @returns The MD5 hash as a hexadecimal string
+ */
+export declare const md5: (data: string) => string;
+/**
+ * Create an HMAC-SHA256 hash
+ * @param data - The data to hash
+ * @param key - The secret key for HMAC
+ * @returns The HMAC-SHA256 hash as a hexadecimal string
+ */
+export declare const hmacSha256: (data: string, key: string) => string;
+/**
+ * Create a hash with custom algorithm and encoding
+ * @param data - The data to hash
+ * @param algorithm - The hash algorithm to use (e.g., 'sha256', 'md5', 'sha1')
+ * @param encoding - The output encoding ('hex', 'base64', 'binary')
+ * @returns The hash in the specified encoding
+ */
+export declare const createHash: (data: string, algorithm?: string, encoding?: crypto.BinaryToTextEncoding) => string;

package/dist/lib/crypto/hash.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHash = exports.hmacSha256 = exports.md5 = exports.concatSha256 = exports.sha256 = exports.pseudoHashPassword = exports.hashPassword = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const util_1 = require("util");
+const scrypt = (0, util_1.promisify)(crypto_1.default.scrypt);
+const KEY_LENGTH = 64;
+/**
+ * Hash a password using scrypt with a salt
+ * @param password - The password to hash
+ * @param salt - The salt to use for hashing
+ * @returns A promise that resolves to the hashed password as a Buffer
+ */
+const hashPassword = async (password, salt) => {
+    const hash = await scrypt(password, salt, KEY_LENGTH);
+    return hash;
+};
+exports.hashPassword = hashPassword;
+/**
+ * Generate a pseudo hash for testing or placeholder purposes
+ * @returns A promise that resolves to a pseudo hash as a Buffer
+ */
+const pseudoHashPassword = async () => {
+    const hash = await scrypt('pseudo', 'pseudo', KEY_LENGTH);
+    return hash;
+};
+exports.pseudoHashPassword = pseudoHashPassword;
+/**
+ * Create a SHA-256 hash of the input data
+ * @param data - The data to hash
+ * @returns The SHA-256 hash as a hexadecimal string
+ */
+const sha256 = (data) => {
+    const hash = crypto_1.default.createHash('sha256');
+    hash.update(data);
+    return hash.digest('hex');
+};
+exports.sha256 = sha256;
+/**
+ * Create a SHA-256 hash of multiple data pieces concatenated
+ * @param dataArray - Array of strings to concatenate and hash
+ * @returns The concatenated SHA-256 hash as a hexadecimal string
+ */
+const concatSha256 = (dataArray) => {
+    let result = '';
+    dataArray.forEach(data => {
+        const hash = crypto_1.default.createHash('sha256');
+        hash.update(data);
+        result += hash.digest('hex');
+    });
+    return result;
+};
+exports.concatSha256 = concatSha256;
+/**
+ * Create an MD5 hash of the input data
+ * @param data - The data to hash
+ * @returns The MD5 hash as a hexadecimal string
+ */
+const md5 = (data) => {
+    const hash = crypto_1.default.createHash('md5');
+    hash.update(data);
+    return hash.digest('hex');
+};
+exports.md5 = md5;
+/**
+ * Create an HMAC-SHA256 hash
+ * @param data - The data to hash
+ * @param key - The secret key for HMAC
+ * @returns The HMAC-SHA256 hash as a hexadecimal string
+ */
+const hmacSha256 = (data, key) => {
+    const hmac = crypto_1.default.createHmac('sha256', key);
+    hmac.update(data);
+    return hmac.digest('hex');
+};
+exports.hmacSha256 = hmacSha256;
+/**
+ * Create a hash with custom algorithm and encoding
+ * @param data - The data to hash
+ * @param algorithm - The hash algorithm to use (e.g., 'sha256', 'md5', 'sha1')
+ * @param encoding - The output encoding ('hex', 'base64', 'binary')
+ * @returns The hash in the specified encoding
+ */
+const createHash = (data, algorithm = 'sha256', encoding = 'hex') => {
+    const hash = crypto_1.default.createHash(algorithm);
+    hash.update(data);
+    return hash.digest(encoding);
+};
+exports.createHash = createHash;

package/dist/lib/crypto/index.d.ts

@@ -0,0 +1 @@
+export * from './hash';

package/dist/lib/crypto/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./hash"), exports);

package/dist/lib/datetime/dateConversion.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Converts a Date object or string to ISO date format (YYYY-MM-DD)
+ * Returns undefined if the input is null, undefined, or invalid
+ */
+export declare const toISODateString: (date: Date | string | null | undefined) => string | undefined;
+/**
+ * Converts an ISO date string to a Date object
+ * Returns undefined if the input is null, undefined, or invalid
+ */
+export declare const toDateObject: (date: string | null | undefined) => Date | undefined;

package/dist/lib/datetime/dateConversion.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDateObject = exports.toISODateString = void 0;
+const moment_1 = __importDefault(require("moment"));
+const DATE_FORMAT_ISO = 'YYYY-MM-DD';
+/**
+ * Converts a Date object or string to ISO date format (YYYY-MM-DD)
+ * Returns undefined if the input is null, undefined, or invalid
+ */
+const toISODateString = (date) => {
+    if (!date)
+        return undefined;
+    const momentDate = (0, moment_1.default)(date);
+    if (!momentDate.isValid())
+        return undefined;
+    return momentDate.format(DATE_FORMAT_ISO);
+};
+exports.toISODateString = toISODateString;
+/**
+ * Converts an ISO date string to a Date object
+ * Returns undefined if the input is null, undefined, or invalid
+ */
+const toDateObject = (date) => {
+    if (!date)
+        return undefined;
+    const momentDate = (0, moment_1.default)(date);
+    if (!momentDate.isValid())
+        return undefined;
+    return momentDate.toDate();
+};
+exports.toDateObject = toDateObject;

package/dist/lib/datetime/index.d.ts

@@ -1 +1,2 @@
 export * from './datetime';
+export * from './dateConversion';

package/dist/lib/datetime/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./datetime"), exports);
+__exportStar(require("./dateConversion"), exports);

package/dist/lib/http/axios.d.ts

@@ -0,0 +1,66 @@
+import { AxiosError, AxiosInstance, AxiosInterceptorManager, AxiosResponse, InternalAxiosRequestConfig } from 'axios';
+/**
+ * Logger interface for axios utilities
+ * Services should provide their own logger implementation
+ */
+export interface AxiosLogger {
+    trace(obj: unknown, message: string): void;
+    error(obj: unknown, message: string): void;
+    warn(obj: unknown, message: string): void;
+}
+/**
+ * Configuration options for creating axios clients
+ */
+export interface AxiosClientConfig {
+    proxy?: false;
+    timeout?: number;
+    baseURL?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Handle axios errors with proper logging
+ * @param axiosError - The axios error to handle
+ * @param logger - Logger instance for error reporting
+ */
+export declare const handleAxiosError: (axiosError: AxiosError, logger: AxiosLogger) => void;
+/**
+ * Create logging interceptors for axios instances
+ * @param name - Name identifier for the client (used in logs)
+ * @param logger - Logger instance for request/response logging
+ * @returns Object containing request and response interceptors
+ */
+export declare const createLoggingInterceptors: (name: string, logger: AxiosLogger) => {
+    request: Parameters<AxiosInterceptorManager<InternalAxiosRequestConfig>["use"]>;
+    response: Parameters<AxiosInterceptorManager<AxiosResponse>["use"]>;
+};
+/**
+ * Create a configured axios client with optional logging
+ * @param config - Configuration options for the axios client
+ * @param logger - Optional logger for request/response logging
+ * @param clientName - Optional name for the client (used in logs)
+ * @returns Configured axios instance
+ */
+export declare const createAxiosClient: (config?: AxiosClientConfig, logger?: AxiosLogger, clientName?: string) => AxiosInstance;
+/**
+ * Create a default axios client with proxy disabled
+ * @param logger - Optional logger for request/response logging
+ * @param clientName - Optional name for the client (used in logs)
+ * @returns Default configured axios instance
+ */
+export declare const createDefaultAxiosClient: (logger?: AxiosLogger, clientName?: string) => AxiosInstance;
+/**
+ * Create an axios client with timeout configuration
+ * @param timeout - Timeout in milliseconds
+ * @param logger - Optional logger for request/response logging
+ * @param clientName - Optional name for the client (used in logs)
+ * @returns Configured axios instance with timeout
+ */
+export declare const createAxiosClientWithTimeout: (timeout: number, logger?: AxiosLogger, clientName?: string) => AxiosInstance;
+/**
+ * Add logging interceptors to an existing axios instance
+ * @param client - Existing axios instance
+ * @param logger - Logger instance for request/response logging
+ * @param clientName - Name identifier for the client (used in logs)
+ * @returns The same axios instance with logging interceptors added
+ */
+export declare const addLoggingToAxiosClient: (client: AxiosInstance, logger: AxiosLogger, clientName?: string) => AxiosInstance;

package/dist/lib/http/axios.js

@@ -0,0 +1,131 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addLoggingToAxiosClient = exports.createAxiosClientWithTimeout = exports.createDefaultAxiosClient = exports.createAxiosClient = exports.createLoggingInterceptors = exports.handleAxiosError = void 0;
+const boom_1 = require("@hapi/boom");
+const axios_1 = __importDefault(require("axios"));
+/**
+ * Handle axios errors with proper logging
+ * @param axiosError - The axios error to handle
+ * @param logger - Logger instance for error reporting
+ */
+const handleAxiosError = (axiosError, logger) => {
+    const { response } = axiosError;
+    const message = response?.data
+        ? JSON.stringify(response.data)
+        : JSON.stringify(axiosError);
+    logger.error({ axiosError }, `Axios API Response: ${message}`);
+};
+exports.handleAxiosError = handleAxiosError;
+/**
+ * Serialize request for logging purposes
+ * @param config - Axios request configuration
+ * @returns Serialized request object
+ */
+const serializeRequest = ({ headers, method, url, }) => ({ method, url, headers });
+/**
+ * Create logging interceptors for axios instances
+ * @param name - Name identifier for the client (used in logs)
+ * @param logger - Logger instance for request/response logging
+ * @returns Object containing request and response interceptors
+ */
+const createLoggingInterceptors = (name, logger) => ({
+    request: [
+        request => {
+            logger.trace({ request: serializeRequest(request) }, `[${name}] -> ${request.method?.toUpperCase()} ${request.url}`);
+            return request;
+        },
+        rawError => {
+            const error = (0, boom_1.boomify)(rawError);
+            logger.error(error, `[${name}] Request error: ${error.message}`);
+            return Promise.reject(rawError);
+        },
+    ],
+    response: [
+        response => {
+            const { status, headers, config: request, data } = response;
+            logger.trace({
+                response: {
+                    status,
+                    headers,
+                    body: data,
+                },
+                request: serializeRequest(request),
+            }, `[${name}] <- ${status} ${request.method?.toUpperCase()} ${request.url}`);
+            return response;
+        },
+        rawError => {
+            const error = (0, boom_1.boomify)(rawError);
+            if (error.response) {
+                logger.error({ err: error, responseData: error.response.data }, `[${name}] <- ${error.response.status} ${error.config?.method?.toUpperCase()} ${error.config?.url}`);
+            }
+            else {
+                logger.error({ err: error }, `[${name}] Response error: ${error.message}`);
+            }
+            return Promise.reject(rawError);
+        },
+    ],
+});
+exports.createLoggingInterceptors = createLoggingInterceptors;
+/**
+ * Create a configured axios client with optional logging
+ * @param config - Configuration options for the axios client
+ * @param logger - Optional logger for request/response logging
+ * @param clientName - Optional name for the client (used in logs)
+ * @returns Configured axios instance
+ */
+const createAxiosClient = (config = {}, logger, clientName = 'Default Client') => {
+    const { proxy = false, timeout, baseURL, headers, ...restConfig } = config;
+    const client = axios_1.default.create({
+        proxy,
+        timeout,
+        baseURL,
+        headers,
+        ...restConfig,
+    });
+    // Add logging interceptors if logger is provided
+    if (logger) {
+        const loggingInterceptors = (0, exports.createLoggingInterceptors)(clientName, logger);
+        client.interceptors.request.use(...loggingInterceptors.request);
+        client.interceptors.response.use(...loggingInterceptors.response);
+    }
+    return client;
+};
+exports.createAxiosClient = createAxiosClient;
+/**
+ * Create a default axios client with proxy disabled
+ * @param logger - Optional logger for request/response logging
+ * @param clientName - Optional name for the client (used in logs)
+ * @returns Default configured axios instance
+ */
+const createDefaultAxiosClient = (logger, clientName = 'Default Client') => {
+    return (0, exports.createAxiosClient)({ proxy: false }, logger, clientName);
+};
+exports.createDefaultAxiosClient = createDefaultAxiosClient;
+/**
+ * Create an axios client with timeout configuration
+ * @param timeout - Timeout in milliseconds
+ * @param logger - Optional logger for request/response logging
+ * @param clientName - Optional name for the client (used in logs)
+ * @returns Configured axios instance with timeout
+ */
+const createAxiosClientWithTimeout = (timeout, logger, clientName = 'Timeout Client') => {
+    return (0, exports.createAxiosClient)({ proxy: false, timeout }, logger, clientName);
+};
+exports.createAxiosClientWithTimeout = createAxiosClientWithTimeout;
+/**
+ * Add logging interceptors to an existing axios instance
+ * @param client - Existing axios instance
+ * @param logger - Logger instance for request/response logging
+ * @param clientName - Name identifier for the client (used in logs)
+ * @returns The same axios instance with logging interceptors added
+ */
+const addLoggingToAxiosClient = (client, logger, clientName = 'Client') => {
+    const loggingInterceptors = (0, exports.createLoggingInterceptors)(clientName, logger);
+    client.interceptors.request.use(...loggingInterceptors.request);
+    client.interceptors.response.use(...loggingInterceptors.response);
+    return client;
+};
+exports.addLoggingToAxiosClient = addLoggingToAxiosClient;

package/dist/lib/http/index.d.ts

@@ -0,0 +1 @@
+export * from './axios';

package/dist/lib/http/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./axios"), exports);

package/dist/lib/phone/index.d.ts

@@ -0,0 +1 @@
+export * from './phone';

package/dist/lib/phone/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./phone"), exports);

package/dist/lib/phone/phone.d.ts

@@ -0,0 +1,65 @@
+import { PhoneNumber } from 'libphonenumber-js/max';
+/**
+ * Output format options for phone numbers
+ */
+export declare enum OutputFormat {
+    International = "international",
+    E164 = "E.164",
+    National = "national"
+}
+/**
+ * Validate if a phone number is valid for Germany
+ * @param value - The phone number string to validate
+ * @returns True if the phone number is valid and from Germany
+ */
+export declare const isValidPhoneNumber: (value: string) => boolean;
+/**
+ * Validate if a phone number is a valid German mobile number
+ * @param value - The phone number string to validate
+ * @returns True if the phone number is a valid German mobile number
+ */
+export declare const isValidMobilePhoneNumber: (value: string) => boolean;
+/**
+ * Format a phone number to E.164 format
+ * @param phone - The phone number string to format
+ * @returns The formatted phone number in E.164 format or undefined if invalid
+ */
+export declare const getFormattedPhoneNumber: (phone: string) => string | undefined;
+/**
+ * Try to parse and format a phone number with error handling
+ * @param phone - The phone number string to parse
+ * @param outputFormat - The desired output format (defaults to E.164)
+ * @returns The formatted phone number or undefined if parsing fails
+ */
+export declare const tryParsePhoneNumber: (phone?: string, outputFormat?: OutputFormat) => string | undefined;
+/**
+ * Format phone number for international display (used in backend/format.ts pattern)
+ * @param phone - The phone number string, null, or undefined
+ * @returns Formatted international phone number, or the original value if null/undefined
+ */
+export declare const formatPhoneNumber: (phone: string | undefined | null) => string | undefined | null;
+/**
+ * Parse a phone number and return the PhoneNumber object
+ * @param phone - The phone number string to parse
+ * @param defaultCountry - The default country code (defaults to 'DE')
+ * @returns The parsed PhoneNumber object or undefined if invalid
+ */
+export declare const parsePhone: (phone: string, defaultCountry?: string) => PhoneNumber | undefined;
+/**
+ * Get the country code from a phone number
+ * @param phone - The phone number string
+ * @returns The country code or undefined if parsing fails
+ */
+export declare const getPhoneCountry: (phone: string) => string | undefined;
+/**
+ * Get the phone number type (mobile, landline, etc.)
+ * @param phone - The phone number string
+ * @returns The phone number type or undefined if parsing fails
+ */
+export declare const getPhoneType: (phone: string) => string | undefined;
+/**
+ * Normalize a phone number by removing spaces and formatting
+ * @param phone - The phone number string
+ * @returns The normalized phone number or undefined if invalid
+ */
+export declare const normalizePhoneNumber: (phone: string) => string | undefined;

package/dist/lib/phone/phone.js

@@ -0,0 +1,150 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePhoneNumber = exports.getPhoneType = exports.getPhoneCountry = exports.parsePhone = exports.formatPhoneNumber = exports.tryParsePhoneNumber = exports.getFormattedPhoneNumber = exports.isValidMobilePhoneNumber = exports.isValidPhoneNumber = exports.OutputFormat = void 0;
+const max_1 = __importStar(require("libphonenumber-js/max"));
+/**
+ * Output format options for phone numbers
+ */
+var OutputFormat;
+(function (OutputFormat) {
+    OutputFormat["International"] = "international";
+    OutputFormat["E164"] = "E.164";
+    OutputFormat["National"] = "national";
+})(OutputFormat || (exports.OutputFormat = OutputFormat = {}));
+/**
+ * Validate if a phone number is valid for Germany
+ * @param value - The phone number string to validate
+ * @returns True if the phone number is valid and from Germany
+ */
+const isValidPhoneNumber = (value) => {
+    const parsedNumber = (0, max_1.default)(value, 'DE');
+    return !!parsedNumber?.isValid() && parsedNumber?.country === 'DE';
+};
+exports.isValidPhoneNumber = isValidPhoneNumber;
+/**
+ * Validate if a phone number is a valid German mobile number
+ * @param value - The phone number string to validate
+ * @returns True if the phone number is a valid German mobile number
+ */
+const isValidMobilePhoneNumber = (value) => {
+    const parsedNumber = (0, max_1.default)(value, 'DE');
+    return (!!parsedNumber?.isValid() &&
+        parsedNumber?.getType() === 'MOBILE' &&
+        parsedNumber?.country === 'DE');
+};
+exports.isValidMobilePhoneNumber = isValidMobilePhoneNumber;
+/**
+ * Format a phone number to E.164 format
+ * @param phone - The phone number string to format
+ * @returns The formatted phone number in E.164 format or undefined if invalid
+ */
+const getFormattedPhoneNumber = (phone) => (0, max_1.default)(phone, 'DE')?.format('E.164');
+exports.getFormattedPhoneNumber = getFormattedPhoneNumber;
+/**
+ * Try to parse and format a phone number with error handling
+ * @param phone - The phone number string to parse
+ * @param outputFormat - The desired output format (defaults to E.164)
+ * @returns The formatted phone number or undefined if parsing fails
+ */
+const tryParsePhoneNumber = (phone, outputFormat = OutputFormat.E164) => {
+    if (!phone) {
+        return undefined;
+    }
+    try {
+        const phoneNumber = (0, max_1.parsePhoneNumberWithError)(phone, 'DE');
+        switch (outputFormat) {
+            case OutputFormat.International:
+                return phoneNumber?.formatInternational();
+            case OutputFormat.National:
+                return phoneNumber?.formatNational();
+            case OutputFormat.E164:
+            default:
+                return phoneNumber?.format('E.164');
+        }
+    }
+    catch {
+        // Silently handle parsing errors
+        return undefined;
+    }
+};
+exports.tryParsePhoneNumber = tryParsePhoneNumber;
+/**
+ * Format phone number for international display (used in backend/format.ts pattern)
+ * @param phone - The phone number string, null, or undefined
+ * @returns Formatted international phone number, or the original value if null/undefined
+ */
+const formatPhoneNumber = (phone) => {
+    if (!phone)
+        return phone;
+    return (0, max_1.default)(phone, 'DE')?.formatInternational();
+};
+exports.formatPhoneNumber = formatPhoneNumber;
+/**
+ * Parse a phone number and return the PhoneNumber object
+ * @param phone - The phone number string to parse
+ * @param defaultCountry - The default country code (defaults to 'DE')
+ * @returns The parsed PhoneNumber object or undefined if invalid
+ */
+const parsePhone = (phone, defaultCountry = 'DE') => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (0, max_1.default)(phone, defaultCountry) || undefined;
+};
+exports.parsePhone = parsePhone;
+/**
+ * Get the country code from a phone number
+ * @param phone - The phone number string
+ * @returns The country code or undefined if parsing fails
+ */
+const getPhoneCountry = (phone) => {
+    // Try parsing without default country first to detect international numbers
+    const parsed = (0, max_1.default)(phone);
+    return parsed?.country;
+};
+exports.getPhoneCountry = getPhoneCountry;
+/**
+ * Get the phone number type (mobile, landline, etc.)
+ * @param phone - The phone number string
+ * @returns The phone number type or undefined if parsing fails
+ */
+const getPhoneType = (phone) => {
+    // Try parsing without default country first, then with DE if needed
+    let parsed = (0, max_1.default)(phone);
+    if (!parsed) {
+        parsed = (0, max_1.default)(phone, 'DE');
+    }
+    return parsed?.getType();
+};
+exports.getPhoneType = getPhoneType;
+/**
+ * Normalize a phone number by removing spaces and formatting
+ * @param phone - The phone number string
+ * @returns The normalized phone number or undefined if invalid
+ */
+const normalizePhoneNumber = (phone) => {
+    const parsed = (0, max_1.default)(phone, 'DE');
+    return parsed?.format('E.164');
+};
+exports.normalizePhoneNumber = normalizePhoneNumber;

package/dist/lib/proxy/index.d.ts

@@ -0,0 +1 @@
+export * from './proxy';

package/dist/lib/proxy/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./proxy"), exports);

package/dist/lib/proxy/proxy.d.ts

@@ -0,0 +1,37 @@
+import { AxiosError, AxiosInstance, AxiosRequestConfig } from 'axios';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import https from 'https';
+export interface ProxyConfig {
+    https?: string | null;
+    http?: string | null;
+    retries?: number;
+    timeout?: number;
+}
+export interface ProxyClientOptions {
+    proxy?: string | null;
+    timeout?: number;
+    throttleRequestsPerSecond?: number;
+    rejectUnauthorized?: boolean;
+    retryCondition?: (error: AxiosError) => boolean;
+    onRetry?: (retryCount: number, error: AxiosError, requestConfig: AxiosRequestConfig) => void;
+}
+/**
+ * Creates an HTTPS proxy agent for the given proxy URL
+ */
+export declare const createHttpsProxyAgent: (proxy: string) => HttpsProxyAgent<string>;
+/**
+ * Creates a proxy-aware Axios client with configurable options
+ */
+export declare const createProxyClient: ({ proxy, timeout, throttleRequestsPerSecond, rejectUnauthorized, retryCondition, onRetry, }?: ProxyClientOptions) => AxiosInstance;
+/**
+ * Parses proxy configuration from URL string
+ */
+export declare const getProxyConfig: (proxyUrl?: string | null) => {
+    host: string;
+    port: number;
+} | undefined;
+/**
+ * Creates a proxy agent based on configuration
+ * Falls back to regular HTTPS agent if no proxy is configured
+ */
+export declare const createProxyAgent: (proxyUrl?: string | null, rejectUnauthorized?: boolean) => HttpsProxyAgent<string> | https.Agent;

package/dist/lib/proxy/proxy.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProxyAgent = exports.getProxyConfig = exports.createProxyClient = exports.createHttpsProxyAgent = void 0;
+const axios_1 = __importDefault(require("axios"));
+const axios_rate_limit_1 = __importDefault(require("axios-rate-limit"));
+const axios_retry_1 = __importDefault(require("axios-retry"));
+const https_proxy_agent_1 = require("https-proxy-agent");
+const https_1 = __importDefault(require("https"));
+/**
+ * Creates an HTTPS proxy agent for the given proxy URL
+ */
+const createHttpsProxyAgent = (proxy) => new https_proxy_agent_1.HttpsProxyAgent(proxy);
+exports.createHttpsProxyAgent = createHttpsProxyAgent;
+/**
+ * Default retry condition that excludes 429 Too Many Requests from retries
+ */
+const defaultRetryCondition = (error) => {
+    // Do not retry on 429 Too Many Requests
+    if (error.response && error.response.status === 429) {
+        return false;
+    }
+    return axios_retry_1.default.isNetworkOrIdempotentRequestError(error);
+};
+/**
+ * Creates a proxy-aware Axios client with configurable options
+ */
+const createProxyClient = ({ proxy, timeout = 120000, throttleRequestsPerSecond, rejectUnauthorized = true, retryCondition = defaultRetryCondition, onRetry, } = {}) => {
+    const retryConfig = {
+        retries: 3,
+        retryDelay: axios_retry_1.default.exponentialDelay,
+        shouldResetTimeout: true,
+        retryCondition,
+        onRetry,
+    };
+    let client;
+    if (!proxy) {
+        // No proxy - create regular client
+        client = axios_1.default.create({
+            proxy: false,
+            timeout,
+            httpsAgent: new https_1.default.Agent({
+                rejectUnauthorized,
+            }),
+        });
+    }
+    else {
+        // With proxy - create proxy-aware client
+        client = axios_1.default.create({
+            httpsAgent: (0, exports.createHttpsProxyAgent)(proxy),
+            proxy: false,
+            timeout,
+        });
+    }
+    // Apply retry configuration
+    (0, axios_retry_1.default)(client, retryConfig);
+    // Apply rate limiting if specified
+    if (throttleRequestsPerSecond) {
+        (0, axios_rate_limit_1.default)(client, { maxRPS: throttleRequestsPerSecond });
+    }
+    return client;
+};
+exports.createProxyClient = createProxyClient;
+/**
+ * Parses proxy configuration from URL string
+ */
+const getProxyConfig = (proxyUrl) => {
+    if (!proxyUrl) {
+        return undefined;
+    }
+    try {
+        const { hostname, port } = new URL(proxyUrl);
+        return {
+            host: hostname,
+            port: Number(port) || 8080,
+        };
+    }
+    catch (error) {
+        console.error('Error parsing proxy URL:', error);
+        return undefined;
+    }
+};
+exports.getProxyConfig = getProxyConfig;
+/**
+ * Creates a proxy agent based on configuration
+ * Falls back to regular HTTPS agent if no proxy is configured
+ */
+const createProxyAgent = (proxyUrl, rejectUnauthorized = true) => {
+    if (proxyUrl) {
+        return (0, exports.createHttpsProxyAgent)(proxyUrl);
+    }
+    return new https_1.default.Agent({
+        rejectUnauthorized,
+    });
+};
+exports.createProxyAgent = createProxyAgent;

package/dist/lib/random/index.d.ts

@@ -0,0 +1 @@
+export * from './random';

package/dist/lib/random/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./random"), exports);

package/dist/lib/random/random.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Generates a random string of specified length using the provided alphabet
+ * @param length - The length of the string to generate
+ * @param alphabet - The alphabet to use for character selection (defaults to alphanumeric uppercase)
+ * @returns A random string of the specified length
+ */
+export declare const generateRandomString: (length: number, alphabet?: string) => string;
+/**
+ * Generates a random numeric string of specified length
+ * @param length - The length of the numeric string to generate
+ * @returns A random numeric string
+ */
+export declare const generateRandomNumericString: (length: number) => string;
+/**
+ * Generates a random alphabetic string of specified length (uppercase)
+ * @param length - The length of the alphabetic string to generate
+ * @returns A random alphabetic string
+ */
+export declare const generateRandomAlphabeticString: (length: number) => string;
+/**
+ * Generates a random lowercase alphanumeric string of specified length
+ * @param length - The length of the string to generate
+ * @returns A random lowercase alphanumeric string
+ */
+export declare const generateRandomLowercaseString: (length: number) => string;

package/dist/lib/random/random.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRandomLowercaseString = exports.generateRandomAlphabeticString = exports.generateRandomNumericString = exports.generateRandomString = void 0;
+const crypto_1 = require("crypto");
+const DEFAULT_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+/**
+ * Gets a random character from the provided alphabet
+ */
+const getRandomCharFromAlphabet = (alphabet) => alphabet.charAt((0, crypto_1.randomInt)(alphabet.length));
+/**
+ * Generates a random string of specified length using the provided alphabet
+ * @param length - The length of the string to generate
+ * @param alphabet - The alphabet to use for character selection (defaults to alphanumeric uppercase)
+ * @returns A random string of the specified length
+ */
+const generateRandomString = (length, alphabet = DEFAULT_ALPHABET) => Array.from({ length })
+    .map(() => getRandomCharFromAlphabet(alphabet))
+    .join('');
+exports.generateRandomString = generateRandomString;
+/**
+ * Generates a random numeric string of specified length
+ * @param length - The length of the numeric string to generate
+ * @returns A random numeric string
+ */
+const generateRandomNumericString = (length) => (0, exports.generateRandomString)(length, '0123456789');
+exports.generateRandomNumericString = generateRandomNumericString;
+/**
+ * Generates a random alphabetic string of specified length (uppercase)
+ * @param length - The length of the alphabetic string to generate
+ * @returns A random alphabetic string
+ */
+const generateRandomAlphabeticString = (length) => (0, exports.generateRandomString)(length, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ');
+exports.generateRandomAlphabeticString = generateRandomAlphabeticString;
+/**
+ * Generates a random lowercase alphanumeric string of specified length
+ * @param length - The length of the string to generate
+ * @returns A random lowercase alphanumeric string
+ */
+const generateRandomLowercaseString = (length) => (0, exports.generateRandomString)(length, 'abcdefghijklmnopqrstuvwxyz0123456789');
+exports.generateRandomLowercaseString = generateRandomLowercaseString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "2.0.9",
+  "version": "4.0.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -29,14 +29,17 @@
     "@types/response-time": "^2.3.9",
     "@types/swagger-ui-express": "4.1.3",
     "axios": "^1.11.0",
+    "axios-rate-limit": "^1.4.0",
+    "axios-retry": "^4.5.0",
     "body-parser": "^2.2.0",
     "busboy": "^1.6.0",
     "cls-rtracer": "^2.6.3",
     "express": "4.21.2",
     "express-async-errors": "3.1.1",
+    "https-proxy-agent": "^7.0.6",
     "jose": "4.15.9",
     "kafkajs": "2.1.0",
-    "libphonenumber-js": "1.9.44",
+    "libphonenumber-js": "^1.12.10",
     "lodash": "^4.17.21",
     "moment-timezone": "^0.5.44",
     "negotiator": "^0.6.4",