core-services-sdk 1.3.22 → 1.3.23

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.22",
+  "version": "1.3.23",
   "main": "src/index.js",
   "type": "module",
+  "types": "types/index.d.ts",
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "vitest run --coverage",
     "format": "prettier --write .",
-    "bump": "node ./scripts/bump-version.js"
+    "bump": "node ./scripts/bump-version.js",
+    "build:types": "tsc --declaration --allowJs --emitDeclarationOnly --outDir types ./src/index.js"
   },
   "repository": {
     "type": "git",
@@ -45,7 +47,8 @@
     "eslint-plugin-prettier": "^5.5.1",
     "path": "^0.12.7",
     "prettier": "^3.6.2",
+    "typescript": "^5.9.2",
     "url": "^0.11.4",
     "vitest": "^3.2.4"
   }
-}
+}

package/src/index.js

@@ -8,3 +8,4 @@ export * from './logger/index.js'
 export * from './mailer/index.js'
 export * from './rabbit-mq/index.js'
 export * from './templates/index.js'
+export * from './util/index.js'

package/src/util/index.js

@@ -0,0 +1,12 @@
+import { mask, maskSingle } from './mask-sensitive.js'
+
+/**
+ * @namespace util
+ * Common utility functions.
+ */
+export const util = {
+  mask,
+  maskSingle,
+}
+
+export { mask, maskSingle }

package/src/util/mask-sensitive.js

@@ -0,0 +1,78 @@
+/**
+ * Mask middle of a primitive value while keeping left/right edges.
+ * @param {string|number|boolean|null|undefined} value
+ * @param {string} [fill='•']
+ * @param {number} [maskLen=3]
+ * @param {number} [left=4]
+ * @param {number} [right=4]
+ * @returns {string}
+ */
+export const maskSingle = (
+  value,
+  fill = '•',
+  maskLen = 3,
+  left = 4,
+  right = 4,
+) => {
+  if (value == null) {
+    return ''
+  }
+  const str = String(value)
+  if (str.length === 0) {
+    return ''
+  }
+  const m = Math.max(1, maskLen)
+
+  if (str.length <= left + right) {
+    if (str.length === 1) {
+      return fill
+    }
+    if (str.length === 2) {
+      return str[0] + fill.repeat(2) // "ab" -> "a••"
+    }
+    return str.slice(0, 1) + fill.repeat(m) + str.slice(-1)
+  }
+
+  return str.slice(0, left) + fill.repeat(m) + str.slice(-right)
+}
+
+/**
+ * Recursively mask values in strings, numbers, booleans, arrays, and objects.
+ * @param {string|number|boolean|Array|Object|null|undefined} value
+ * @param {string} [fill='•']
+ * @param {number} [maskLen=3]
+ * @param {number} [left=4]
+ * @param {number} [right=4]
+ * @returns {string|Array|Object}
+ */
+export const mask = (value, fill = '•', maskLen = 3, left = 4, right = 4) => {
+  const type = typeof value
+
+  if (value instanceof Date) {
+    const isoDate = value.toISOString()
+    return maskSingle(isoDate, '', isoDate.length, 0, 0)
+  }
+
+  if (value == null || (value && ['string', 'number'].includes(type))) {
+    return maskSingle(value, fill, maskLen, left, right)
+  }
+
+  if (type === 'boolean') {
+    return maskSingle(value, '', 0, 0, 0)
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((aValue) => mask(aValue, fill, maskLen, left, right))
+  }
+
+  if (typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([prop, propValue]) => [
+        prop,
+        mask(propValue, fill, maskLen, left, right),
+      ]),
+    )
+  }
+
+  return value
+}

package/tests/rabbit-mq/rabbit-mq.test.js

@@ -22,6 +22,7 @@ describe('RabbitMQ SDK', () => {
   let received = null
 
   beforeAll(async () => {
+    // @ts-ignore
     sdk = await initializeQueue({ host, log: testLog })
 
     await sdk.subscribe({

package/tests/util/mask-sensitive.unit.test.js

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest'
+
+import { mask, maskSingle } from '../../src/util/index.js'
+
+describe('maskSingle', () => {
+  it('masks middle of a regular string (length == left+right)', () => {
+    expect(maskSingle('abcdefgh')).toBe('a•••h')
+  })
+
+  it('masks numbers with default settings', () => {
+    expect(maskSingle(12345678)).toBe('1•••8')
+  })
+
+  it('masks booleans', () => {
+    expect(maskSingle(true)).toBe('t•••e')
+    expect(maskSingle(false)).toBe('f•••e')
+  })
+
+  it('masks very short strings correctly', () => {
+    expect(maskSingle('ab')).toBe('a••b'.slice(0, 3)) // will produce 'a••'
+    expect(maskSingle('a')).toBe('•')
+    expect(maskSingle('')).toBe('')
+  })
+
+  it('respects custom fill and mask length', () => {
+    expect(maskSingle('abcdefgh', '*', 5)).toBe('a*****h')
+  })
+
+  it('ensures maskLen is at least 1', () => {
+    expect(maskSingle('abcdefgh', '*', 0)).toBe('a*h')
+  })
+
+  it('returns empty string for null/undefined', () => {
+    expect(maskSingle(null)).toBe('')
+    expect(maskSingle(undefined)).toBe('')
+  })
+})
+
+describe('mask', () => {
+  it('masks primitives (string, number, boolean)', () => {
+    expect(mask('abcdefgh')).toBe('a•••h')
+    expect(mask(12345678)).toBe('1•••8')
+    expect(mask(true)).toBe('true')
+    expect(mask(false)).toBe('false')
+  })
+
+  it('returns empty string for null/undefined', () => {
+    expect(mask(null)).toBe('')
+    expect(mask(undefined)).toBe('')
+  })
+
+  it('masks arrays recursively', () => {
+    expect(mask(['abcdefgh', 12345678])).toEqual(['a•••h', '1•••8'])
+  })
+
+  it('masks objects recursively', () => {
+    expect(mask({ a: 'abcdefgh', b: 12345678 })).toEqual({
+      a: 'a•••h',
+      b: '1•••8',
+    })
+  })
+
+  it('masks nested objects/arrays recursively', () => {
+    const input = { arr: ['abcdefgh', { num: 12345678 }] }
+    const expected = { arr: ['a•••h', { num: '1•••8' }] }
+    expect(mask(input)).toEqual(expected)
+  })
+
+  it('handles Date instances by returning full ISO string', () => {
+    const d = new Date('2025-08-15T12:34:56.789Z')
+    expect(mask(d)).toBe(d.toISOString())
+  })
+
+  it('respects custom fill and mask length in recursive calls', () => {
+    const input = { val: 'abcdefgh' }
+    const expected = { val: 'a*****h' }
+    expect(mask(input, '*', 5)).toEqual(expected)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "allowJs": true,
+    "emitDeclarationOnly": true,
+    "outDir": "types"
+  },
+  "include": ["src"]
+}

package/types/core/combine-unique-arrays.d.ts

@@ -0,0 +1 @@
+export function combineUniqueArrays(...lists: Array<any>[]): Array<any>;

package/types/core/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./regex-utils.js";
+export * from "./otp-generators.js";
+export * from "./sanitize-objects.js";
+export * from "./normalize-min-max.js";
+export * from "./normalize-to-array.js";
+export * from "./combine-unique-arrays.js";
+export * from "./normalize-phone-number.js";

package/types/core/normalize-min-max.d.ts

@@ -0,0 +1,10 @@
+export function normalizeMinMax(defaultMinMax: {
+    min: number;
+    max: number;
+}, valuesMinMax: {
+    min?: number;
+    max?: number;
+} | null | undefined): {
+    min: number;
+    max: number;
+};

package/types/core/normalize-phone-number.d.ts

@@ -0,0 +1,48 @@
+/** Resolve libphonenumber regardless of interop shape */
+export function getLib(): any;
+export function phoneUtil(): any;
+/**
+ * Parse & validate an international number (must start with '+').
+ * @param {string} input
+ * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
+ * @throws {Error} If the number is invalid
+ */
+export function normalizePhoneOrThrowIntl(input: string): {
+    e164: string;
+    national: string;
+    international: string;
+    regionCode: string | undefined;
+    type: number;
+};
+/**
+ * Parse & validate a national number using a region hint.
+ * @param {string} input
+ * @param {string} defaultRegion
+ * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
+ * @throws {Error} If the number is invalid
+ */
+export function normalizePhoneOrThrowWithRegion(input: string, defaultRegion: string): {
+    e164: string;
+    national: string;
+    international: string;
+    regionCode: string | undefined;
+    type: number;
+};
+/**
+ * Smart normalization:
+ * - If input starts with '+', parse as international.
+ * - Otherwise require a defaultRegion and parse as national.
+ * @param {string} input
+ * @param {{ defaultRegion?: string }} [opts]
+ * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
+ * @throws {Error} If invalid or defaultRegion is missing for non-international input
+ */
+export function normalizePhoneOrThrow(input: string, opts?: {
+    defaultRegion?: string;
+}): {
+    e164: string;
+    national: string;
+    international: string;
+    regionCode: string | undefined;
+    type: number;
+};

package/types/core/normalize-to-array.d.ts

@@ -0,0 +1 @@
+export function normalizeToArray(value: any): string[];

package/types/core/otp-generators.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Generates a one-time password (OTP) code based on a specified type or character set.
+ *
+ * @param {Object} [options={}] - The options object.
+ * @param {number} [options.length=4] - The desired length of the generated code (1-30).
+ * @param {string} [options.type='numeric'] - The type of characters to use. One of:
+ *  'any', 'alpha', 'numeric', 'symbols', 'alphaLower', 'alphaUpper', 'alphanumeric', 'alphanumericSymbols'.
+ * @param {string} [options.charset] - A custom string of characters to use instead of the predefined types.
+ * @returns {string} The generated code.
+ * @throws {Error} If the length is not a number between 1 and 30.
+ * @throws {Error} If charset is provided and is not a non-empty string.
+ * @throws {Error} If the type is invalid and no valid charset is provided.
+ */
+export function generateCode({ length, type, charset }?: {
+    length?: number;
+    type?: string;
+    charset?: string;
+}): string;
+/**
+ * Generates an OTP code using alphabetic characters (both lowercase and uppercase).
+ *
+ * @param {number} [length=4] - The desired length of the code.
+ * @returns {string} The generated code.
+ */
+export function generateCodeAlpha(length?: number): string;
+/**
+ * Generates an OTP code using only numeric digits (0-9).
+ *
+ * @param {number} [length=4] - The desired length of the code.
+ * @returns {string} The generated code.
+ */
+export function generateCodeDigits(length?: number): string;
+/**
+ * Generates an OTP code using alphabetic characters and digits.
+ *
+ * @param {number} [length=4] - The desired length of the code.
+ * @returns {string} The generated code.
+ */
+export function generateCodeAlphaNumeric(length?: number): string;
+/**
+ * Generates an OTP code using alphabetic characters, digits, and symbols.
+ *
+ * @param {number} [length=4] - The desired length of the code.
+ * @returns {string} The generated code.
+ */
+export function generateCodeAlphaNumericSymbols(length?: number): string;
+export const OTP_GENERATOR_TYPES: Readonly<{
+    any: "any";
+    alpha: "alpha";
+    numeric: "numeric";
+    symbols: "symbols";
+    alphaLower: "alphaLower";
+    alphaUpper: "alphaUpper";
+    alphanumeric: "alphanumeric";
+    alphanumericSymbols: "alphanumericSymbols";
+}>;

package/types/core/regex-utils.d.ts

@@ -0,0 +1 @@
+export function isValidRegex(pattern: string | RegExp): boolean;

package/types/core/sanitize-objects.d.ts

@@ -0,0 +1,4 @@
+export function sanitizeObject(obj: any, filter: (entry: [string, any]) => boolean): any;
+export function sanitizeUndefinedFields(obj: any): any;
+export function sanitizeObjectAllowProps(obj: any, allowedFields?: string[]): any;
+export function sanitizeObjectDisallowProps(obj: any, disallowedFields?: string[]): any;

package/types/crypto/crypto.d.ts

@@ -0,0 +1,18 @@
+export function getSalt(length: number): Buffer;
+export function getSaltHex(length: number): string;
+export function getEncryptedBuffer({ salt, expression, length, }: {
+    expression: string;
+    salt: string;
+    length?: number;
+}): Promise<Buffer>;
+export function encrypt({ salt, expression, passwordPrivateKey }: {
+    expression: string;
+    salt: string;
+    passwordPrivateKey?: string;
+}): Promise<string>;
+export function isPasswordMatch({ salt, password, encryptedPassword, passwordPrivateKey, }: {
+    salt: string;
+    password: string;
+    encryptedPassword: string;
+    passwordPrivateKey?: string;
+}): Promise<boolean>;

package/types/crypto/encryption.d.ts

@@ -0,0 +1,6 @@
+export function encryptPassword({ password }: {
+    password: string;
+}, { saltLength, passwordPrivateKey }: {
+    saltLength: number;
+    passwordPrivateKey?: string;
+}): Promise<any>;

package/types/crypto/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./crypto.js";
+export * from "./encryption.js";

package/types/fastify/error-codes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A reusable generic error object representing a server-side failure (HTTP 500).
+ * Useful as a fallback error descriptor for unhandled or unexpected failures.
+ *
+ * @typedef {Object} GeneralError
+ * @property {number} httpStatusCode - The HTTP status code (500).
+ * @property {string} httpStatusText - The human-readable status text ("Internal Server Error").
+ * @property {string} code - An application-specific error code in the format "GENERAL.<StatusText>".
+ */
+/** @type {GeneralError} */
+export const GENERAL_ERROR: GeneralError;
+/**
+ * A reusable generic error object representing a server-side failure (HTTP 500).
+ * Useful as a fallback error descriptor for unhandled or unexpected failures.
+ */
+export type GeneralError = {
+    /**
+     * - The HTTP status code (500).
+     */
+    httpStatusCode: number;
+    /**
+     * - The human-readable status text ("Internal Server Error").
+     */
+    httpStatusText: string;
+    /**
+     * - An application-specific error code in the format "GENERAL.<StatusText>".
+     */
+    code: string;
+};

package/types/fastify/error-handlers/with-error-handling.d.ts

@@ -0,0 +1,15 @@
+export function withErrorHandling(log: object, defaultError: HttpError): (funcToInvoke: () => Promise<any>) => Promise<any>;
+export function withErrorHandlingReply({ reply, log, defaultError }: {
+    reply: Reply;
+    log: Logger;
+    defaultError?: HttpError;
+}): (funcToInvoke: any) => Promise<any>;
+export function replyOnErrorOnly({ reply, log, defaultError }: {
+    reply: Reply;
+    log: Logger;
+    defaultError?: HttpError;
+}): (funcToInvoke: any) => Promise<any>;
+export type Reply = import("fastify").FastifyReply;
+export type Request = import("fastify").FastifyRequest;
+export type Logger = import("pino").Logger;
+import { HttpError } from '../../http/HttpError.js';

package/types/fastify/index.d.ts

@@ -0,0 +1,2 @@
+export { GENERAL_ERROR } from "./error-codes.js";
+export * from "./error-handlers/with-error-handling.js";

package/types/http/HttpError.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Represents a custom HTTP error with optional status code, status text, error code, and extra metadata.
+ * Useful for consistent error handling across services.
+ */
+export class HttpError extends Error {
+    /**
+     * Checks if a given object is an instance of `HttpError`.
+     *
+     * @param {*} instance - The object to check.
+     * @returns {boolean} True if `instance` is an instance of `HttpError`.
+     */
+    static isInstanceOf(instance: any): boolean;
+    /**
+     * Checks if the error is an instance of `HttpError` or has similar shape.
+     *
+     * @param {object} error
+     * @returns {error is HttpError}
+     */
+    static isHttpError(error: object): error is HttpError;
+    /**
+     * Creates an HttpError from a generic Error instance or returns it if already an HttpError.
+     *
+     * @param {Error | HttpError} error
+     * @returns {HttpError}
+     */
+    static FromError(error: Error | HttpError): HttpError;
+    /**
+     * Creates an instance of HttpError.
+     *
+     * @param {Object} [error] - Optional error object.
+     * @param {string | number} [error.code] - Application-specific error code.
+     * @param {string} [error.message] - Custom error message.
+     * @param {number} [error.httpStatusCode] - HTTP status code (e.g., 404, 500).
+     * @param {string} [error.httpStatusText] - Optional human-readable HTTP status text.
+     * @param {object} [error.extendInfo] - Optional extended metadata for diagnostics.
+     */
+    constructor(error?: {
+        code?: string | number;
+        message?: string;
+        httpStatusCode?: number;
+        httpStatusText?: string;
+        extendInfo?: object;
+    });
+    /**
+     * @type {string | number | undefined}
+     * A short application-specific error code (e.g., "INVALID_INPUT" or a numeric code).
+     */
+    code: string | number | undefined;
+    /**
+     * @type {number | undefined}
+     * HTTP status code associated with the error (e.g., 400, 500).
+     */
+    httpStatusCode: number | undefined;
+    /**
+     * @type {string | undefined}
+     * Human-readable HTTP status text (e.g., "Bad Request").
+     */
+    httpStatusText: string | undefined;
+    /**
+     * @type {object | undefined}
+     * Optional metadata for debugging/logging (e.g., request ID, user ID, retryAfter).
+     */
+    extendInfo: object | undefined;
+    /**
+     * Converts the error to a plain object (useful for logging or sending as JSON).
+     *
+     * @returns {{
+     *   code: string | number | undefined,
+     *   message: string,
+     *   httpStatusCode: number | undefined,
+     *   httpStatusText: string | undefined,
+     *   extendInfo?: object
+     * }}
+     */
+    toJSON(): {
+        code: string | number | undefined;
+        message: string;
+        httpStatusCode: number | undefined;
+        httpStatusText: string | undefined;
+        extendInfo?: object;
+    };
+}

package/types/http/http-method.d.ts

@@ -0,0 +1,7 @@
+export const HTTP_METHODS: Readonly<{
+    GET: "GET";
+    POST: "POST";
+    PUT: "PUT";
+    PATCH: "PATCH";
+    DELETE: "DELETE";
+}>;

package/types/http/http.d.ts

@@ -0,0 +1,36 @@
+export function get({ url, headers, expectedType, }: {
+    url: any;
+    headers?: {};
+    expectedType?: "json";
+}): Promise<any>;
+export function post({ url, body, headers, expectedType, }: {
+    url: any;
+    body: any;
+    headers?: {};
+    expectedType?: "json";
+}): Promise<any>;
+export function put({ url, body, headers, expectedType, }: {
+    url: any;
+    body: any;
+    headers?: {};
+    expectedType?: "json";
+}): Promise<any>;
+export function patch({ url, body, headers, expectedType, }: {
+    url: any;
+    body: any;
+    headers?: {};
+    expectedType?: "json";
+}): Promise<any>;
+export function deleteApi({ url, body, headers, expectedType, }: {
+    url: any;
+    body: any;
+    headers?: {};
+    expectedType?: "json";
+}): Promise<any>;
+export namespace http {
+    export { get };
+    export { put };
+    export { post };
+    export { patch };
+    export { deleteApi };
+}

package/types/http/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./http.js";
+export * from "./HttpError.js";
+export * from "./http-method.js";
+export * from "./responseType.js";

package/types/http/responseType.d.ts

@@ -0,0 +1,20 @@
+/**
+ * *
+ */
+export type ResponseType = string;
+/**
+ * Enum representing supported response types for HTTP client parsing.
+ *
+ * @readonly
+ * @enum {string}
+ * @property {string} xml  - XML response (parsed using xml2js).
+ * @property {string} json - JSON response (parsed via JSON.parse).
+ * @property {string} text - Plain text response.
+ * @property {string} file - Binary file or blob (not automatically parsed).
+ */
+export const ResponseType: Readonly<{
+    xml: "xml";
+    json: "json";
+    text: "text";
+    file: "file";
+}>;

package/types/ids/generators.d.ts

@@ -0,0 +1,10 @@
+export function generateId(): string;
+export function generatePrefixedId(prefix: string): string;
+export function generateUserId(): string;
+export function generateTenantId(): string;
+export function generatePermissionId(): string;
+export function generateCorrelationId(): string;
+export function generateVerificationId(): string;
+export function generateRolePermissionsId(): string;
+export function generateOnboardingId(): string;
+export function generateSessionId(): string;

package/types/ids/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./prefixes.js";
+export * from "./generators.js";

package/types/ids/prefixes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Mapping of entity types to their unique ID prefixes.
+ *
+ * These prefixes are prepended to ULIDs to create consistent and identifiable IDs across the system.
+ * For example: 'usr_01HZY3M7K4FJ9A8Q4Y1ZB5NX3T'
+ */
+export type ID_PREFIXES = string;
+/**
+ * Mapping of entity types to their unique ID prefixes.
+ *
+ * These prefixes are prepended to ULIDs to create consistent and identifiable IDs across the system.
+ * For example: 'usr_01HZY3M7K4FJ9A8Q4Y1ZB5NX3T'
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const ID_PREFIXES: Readonly<{
+    /** User entity ID prefix */
+    USER: "usr";
+    /** Tenant entity ID prefix */
+    TENANT: "tnt";
+    /** Permission entity ID prefix */
+    PERMISSION: "prm";
+    /** Correlation ID prefix (e.g., for tracing requests) */
+    CORRELATION: "crln";
+    /** Verification entity ID prefix (e.g., email/phone code) */
+    VERIFICATION: "vrf";
+    /** Role-permissions mapping ID prefix */
+    ROLE_PERMISSIONS: "role";
+    /** Onboarding mapping ID prefix */
+    ONBOARDING: "onb";
+    /** Session mapping ID prefix */
+    SESSION: "sess";
+}>;

package/types/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./core/index.js";
+export * from "./crypto/index.js";
+export * from "./fastify/index.js";
+export * from "./http/index.js";
+export * from "./ids/index.js";
+export * from "./mongodb/index.js";
+export * from "./logger/index.js";
+export * from "./mailer/index.js";
+export * from "./rabbit-mq/index.js";
+export * from "./templates/index.js";
+export * from "./util/index.js";

package/types/logger/get-logger.d.ts

@@ -0,0 +1,23 @@
+export function getLogger(option: true | any | undefined): import("pino").Logger | typeof dummyLogger;
+declare namespace dummyLogger {
+    function info(): void;
+    function warn(): void;
+    function trace(): void;
+    function debug(): void;
+    function error(): void;
+    function fatal(): void;
+    function levels(): void;
+    function silent(): void;
+    function child(): {
+        info: () => void;
+        warn: () => void;
+        trace: () => void;
+        debug: () => void;
+        error: () => void;
+        fatal: () => void;
+        levels: () => void;
+        silent: () => void;
+        child(): /*elided*/ any;
+    };
+}
+export {};

package/types/logger/index.d.ts

@@ -0,0 +1 @@
+export * from "./get-logger.js";

package/types/mailer/index.d.ts

@@ -0,0 +1,2 @@
+export function initMailer(config: any): Mailer;
+import { Mailer } from './mailer.service.js';

package/types/mailer/mailer.service.d.ts

@@ -0,0 +1,21 @@
+export class Mailer {
+    /**
+     * @param {object} transporter - Nodemailer transporter instance
+     */
+    constructor(transporter: object);
+    transporter: any;
+    /**
+     * Send an email
+     */
+    send({ to, subject, html, text, from, cc, bcc, replyTo, attachments }: {
+        to: any;
+        subject: any;
+        html: any;
+        text: any;
+        from: any;
+        cc: any;
+        bcc: any;
+        replyTo: any;
+        attachments: any;
+    }): Promise<any>;
+}

package/types/mailer/transport.factory.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Factory for creating email transporters based on configuration.
+ */
+export class TransportFactory {
+    /**
+     * Create a Nodemailer transporter
+     *
+     * @param {object} config - Transport configuration object
+     * @param {'smtp' | 'gmail' | 'sendgrid' | 'ses'} config.type - Type of email transport
+     *
+     * For type 'smtp':
+     * @param {string} config.host - SMTP server host
+     * @param {number} config.port - SMTP server port
+     * @param {boolean} config.secure - Use TLS
+     * @param {{ user: string, pass: string }} config.auth - SMTP auth credentials
+     *
+     * For type 'gmail':
+     * @param {{ user: string, pass: string }} config.auth - Gmail credentials
+     *
+     * For type 'sendgrid':
+     * @param {string} config.apiKey - SendGrid API key
+     *
+     * For type 'ses':
+     * @param {string} config.accessKeyId - AWS access key
+     * @param {string} config.secretAccessKey - AWS secret
+     * @param {string} config.region - AWS region
+     *
+     * @returns {import('nodemailer').Transporter | typeof import('@sendgrid/mail')}
+     */
+    static create(config: {
+        type: "smtp" | "gmail" | "sendgrid" | "ses";
+        host: string;
+        port: number;
+        secure: boolean;
+        auth: {
+            user: string;
+            pass: string;
+        };
+        auth: {
+            user: string;
+            pass: string;
+        };
+        apiKey: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        region: string;
+    }): any | typeof import("@sendgrid/mail");
+}

package/types/mongodb/connect.d.ts

@@ -0,0 +1,4 @@
+export function mongoConnect({ uri, serverApi }: {
+    uri: string;
+    serverApi?: object;
+}): Promise<import("mongodb").MongoClient>;

package/types/mongodb/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./connect.js";
+export * from "./initialize-mongodb.js";
+export * from "./validate-mongo-uri.js";

package/types/mongodb/initialize-mongodb.d.ts

@@ -0,0 +1,13 @@
+export function initializeMongoDb({ config, collectionNames }: {
+    config: {
+        uri: string;
+        options: {
+            dbName: string;
+        };
+    };
+    collectionNames: Record<string, string>;
+}): Promise<Record<string, import("mongodb").Collection> & {
+    withTransaction: <T>(action: ({
+        session: import("mongodb").ClientSession;
+    })) => Promise<T>;
+}>;

package/types/mongodb/validate-mongo-uri.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Validates whether a given string is a properly formatted MongoDB URI.
+ *
+ * Supports both standard (`mongodb://`) and SRV (`mongodb+srv://`) protocols.
+ *
+ * @param {string} uri - The URI string to validate.
+ * @returns {boolean} `true` if the URI is a valid MongoDB connection string, otherwise `false`.
+ *
+ * @example
+ * isValidMongoUri('mongodb://localhost:27017/mydb') // true
+ * isValidMongoUri('mongodb+srv://cluster.example.com/test') // true
+ * isValidMongoUri('http://localhost') // false
+ * isValidMongoUri('') // false
+ */
+export function isValidMongoUri(uri: string): boolean;

package/types/rabbit-mq/index.d.ts

@@ -0,0 +1 @@
+export * from "./rabbit-mq.js";

package/types/rabbit-mq/rabbit-mq.d.ts

@@ -0,0 +1,40 @@
+export function connectQueueService({ host, log }: {
+    host: string;
+    log: import("pino").Logger;
+}): Promise<amqp.Connection>;
+export function createChannel({ host, log }: {
+    host: string;
+    log: import("pino").Logger;
+}): Promise<amqp.Channel>;
+export function subscribeToQueue({ log, queue, channel, prefetch, onReceive, nackOnError, }: {
+    channel: any;
+    queue: string;
+    onReceive: (data: any, correlationId?: string) => Promise<void>;
+    log: import("pino").Logger;
+    nackOnError?: boolean;
+    prefetch?: number;
+}): Promise<void>;
+export function initializeQueue({ host, log }: {
+    host: string;
+    log: import("pino").Logger;
+}): Promise<{
+    publish: (queue: string, data: any, correlationId?: string) => Promise<boolean>;
+    subscribe: (options: {
+        queue: string;
+        onReceive: (data: any, correlationId?: string) => Promise<void>;
+        nackOnError?: boolean;
+    }) => Promise<void>;
+    channel: amqp.Channel;
+}>;
+export function rabbitUriFromEnv(env: {
+    RABBIT_HOST: string;
+    RABBIT_PORT: string | number;
+    RABBIT_USERNAME: string;
+    RABBIT_PASSWORD: string;
+    RABBIT_PROTOCOL?: string;
+}): string;
+export type Log = {
+    info: (obj: any, msg?: string) => void;
+    error: (obj: any, msg?: string) => void;
+    debug: (obj: any, msg?: string) => void;
+};

package/types/templates/index.d.ts

@@ -0,0 +1 @@
+export * from "./template-loader.js";

package/types/templates/template-loader.d.ts

@@ -0,0 +1,3 @@
+export function isItFile(filePathOrString: string): Promise<boolean>;
+export function getTemplateContent(maybeFilePathOrString: string): Promise<string>;
+export function loadTemplates(templateSet: Record<string, string>): Promise<Record<string, (params: Record<string, any>) => string>>;

package/types/util/index.d.ts

@@ -0,0 +1,7 @@
+export namespace util {
+    export { mask };
+    export { maskSingle };
+}
+import { mask } from './mask-sensitive.js';
+import { maskSingle } from './mask-sensitive.js';
+export { mask, maskSingle };

package/types/util/mask-sensitive.d.ts

@@ -0,0 +1,2 @@
+export function maskSingle(value: string | number | boolean | null | undefined, fill?: string, maskLen?: number, left?: number, right?: number): string;
+export function mask(value: string | number | boolean | any[] | any | null | undefined, fill?: string, maskLen?: number, left?: number, right?: number): string | any[] | any;

package/vitest.config.js

@@ -1,9 +1,19 @@
-export default {
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
   test: {
     testTimeout: 30000,
     hookTimeout: 30000,
+    exclude: [
+      'node_modules',
+      'types/**',
+      '**/*.d.ts',
+      '**/index.js',
+      'vitest.config.js',
+    ],
     coverage: {
-      exclude: ['**/index.js', 'vitest.config.js'],
+      include: ['src/**/*.js'],
+      exclude: ['types/**', '**/*.d.ts', '**/index.js', 'vitest.config.js'],
     },
   },
-}
+})