@temboplus/frontend-core 0.2.20-beta.8 → 0.2.22

package/dist/models/phone-number/mno/tz/mobile-number.tz.d.ts

@@ -1,44 +0,0 @@
-import { ISO2CountryCode } from "@models/country/country.types.js";
-import { MNOInfo } from "@models/phone-number/mno/mno.types.js";
-import { PhoneNumber } from "@models/phone-number/phone-number.js";
-import { type ParsedPhoneNumber, PhoneNumberService } from "@models/phone-number/phone-number.service.js";
-import { type PhoneNumberContract, type PhoneNumberParseOptions, PhoneNumberType } from "@models/phone-number/phone-number.types.js";
-/**
- * Represents a validated Tanzanian (TZ) **mobile** phone number.
- * Extends the generic PhoneNumber class and provides TZ-specific behavior.
- */
-export declare class TZMobileNumber extends PhoneNumber implements PhoneNumberContract {
-    readonly countryCode: ISO2CountryCode;
-    /**
-     * Protected constructor. Use static `from` method for instantiation.
-     * Calls the base class constructor.
-     */
-    protected constructor(parsedInfo: ParsedPhoneNumber, service: PhoneNumberService);
-    /**
-     * Validates the structure for a Tanzanian **mobile** phone number.
-     * Checks base validity AND ensures the prefix belongs to a known TZ MNO.
-     * @returns {boolean} True if the number is a valid TZ mobile number.
-     */
-    validate(): boolean;
-    /**
-     * Gets associated Tanzanian mobile operator information based on the number's prefix.
-     * Overrides the base implementation.
-     * @returns {MNOInfo | undefined} Operator details or undefined.
-     */
-    getOperatorInfo(): MNOInfo | undefined;
-    /**
-     * Gets the specific type for this class, overriding the base method.
-     * @returns {PhoneNumberType} Always returns MOBILE.
-     */
-    getNumberType(): PhoneNumberType;
-    /**
-     * Attempts to create a `TZMobileNumber` instance from a given string input.
-     * Performs TZ-specific parsing and validation FIRST, then uses the core
-     * service for final validation and object creation.
-     *
-     * @param input - The input phone number string.
-     * @param options - Parsing options (optional).
-     * @returns {TZMobileNumber | undefined} An instance if valid, otherwise undefined.
-     */
-    static from(input: string | null | undefined, options?: PhoneNumberParseOptions): TZMobileNumber | undefined;
-}

package/dist/models/phone-number/phone-number.d.ts

@@ -1,135 +0,0 @@
-import { ISO2CountryCode } from "@models/country/country.types.js";
-import type { PhoneNumber as LibPhoneNumberInstance } from "libphonenumber-js";
-import { MNOInfo } from "./mno/mno.types.js";
-import { PhoneNumberService, ParsedPhoneNumber } from "./phone-number.service.js";
-import { PhoneNumberContract, PhoneNumberFormat, PhoneNumberType, PhoneNumberParseOptions } from "./phone-number.types.js";
-import { z } from "zod";
-/**
- * Zod schema for PhoneNumber JSON serialization
- * This schema validates the JSON representation of a PhoneNumber instance
- *
- * E.164 format validation rules:
- * - Starts with '+'
- * - Followed by country code (1-3 digits, first digit 1-9)
- * - Total length: 8-16 characters (including '+')
- * - Contains only digits after '+'
- */
-export declare const PhoneNumberJSONSchema: z.ZodObject<{
-    /** The phone number in E.164 format */
-    e164Format: z.ZodString;
-    /** Version for future compatibility */
-    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-}, "strip", z.ZodTypeAny, {
-    version: string;
-    e164Format: string;
-}, {
-    e164Format: string;
-    version?: string | undefined;
-}>;
-/**
- * Infer the PhoneNumberJSON type from the schema
- */
-export type PhoneNumberJSON = z.infer<typeof PhoneNumberJSONSchema>;
-/**
- * Represents a generic international phone number, validated using libphonenumber-js
- * via the PhoneNumberService. Implements the common PhoneNumberContract interface.
- * This class is intended to be extended by country-specific classes.
- */
-export declare class PhoneNumber implements PhoneNumberContract {
-    readonly countryCode: ISO2CountryCode;
-    readonly compactNumber: string;
-    readonly e164Format: string;
-    protected readonly _service: PhoneNumberService;
-    protected readonly _parsedInfo: ParsedPhoneNumber;
-    /**
-     * Protected constructor. Should be called by subclasses via super()
-     * or by static factory methods (`from`).
-     * @param parsedInfo - The result from PhoneNumberService.parse().
-     * @param service - An instance of PhoneNumberService.
-     */
-    protected constructor(parsedInfo: ParsedPhoneNumber, service: PhoneNumberService);
-    /**
-     * Validates the phone number using the underlying library via the service.
-     * Subclasses can override this to add more specific validation.
-     * @returns {boolean} True if the number is considered valid by the core library.
-     */
-    validate(): boolean;
-    /**
-     * Formats the phone number according to the specified format using the service.
-     * Subclasses can override this if country-specific formatting differs from the library's output.
-     * @param {PhoneNumberFormat} format - The desired output format.
-     * @returns {string} The formatted phone number string.
-     */
-    getWithFormat(format: PhoneNumberFormat): string;
-    /**
-     * Gets the type of the phone number (e.g., MOBILE, FIXED_LINE) using the service.
-     * Subclasses might override this for specific known types (e.g., always MOBILE).
-     * @returns {PhoneNumberType | undefined} The determined type or undefined.
-     */
-    getNumberType(): PhoneNumberType | undefined;
-    /**
-     * Gets associated mobile operator information.
-     * Base implementation returns undefined. Subclasses override this for specific countries.
-     * @returns {MNOInfo | undefined} Always returns undefined in the base class.
-     */
-    getOperatorInfo(): MNOInfo | undefined;
-    /**
-     * Gets a human-readable label, typically the international format.
-     * @returns {string} A display label for the phone number.
-     */
-    get label(): string;
-    /**
-     * Underlying instance from libphonenumber-js, exposed for potential advanced use.
-     * Use with caution, prefer methods defined in PhoneNumberContract.
-     */
-    get underlyingInstance(): LibPhoneNumberInstance;
-    /**
-     * Creates a generic PhoneNumber instance from an input string.
-     * Uses PhoneNumberService for parsing and validation.
-     * Use PhoneNumberFactory.create() for potentially getting country-specific instances.
-     *
-     * @param input - Phone number string.
-     * @param options - Parsing options like defaultCountry.
-     * @returns {PhoneNumber | undefined} Instance if valid and parsable, undefined otherwise.
-     */
-    static from(input: string, options?: PhoneNumberParseOptions): PhoneNumber | undefined;
-    /**
-     * Checks if a string can potentially be parsed and validated as a phone number
-     * using the generic 'from' method.
-     */
-    static canConstruct(input?: string | null, options?: PhoneNumberParseOptions): boolean;
-    /**
-     * Robust type guard checking structure and validatability.
-     */
-    static is(obj: unknown): obj is PhoneNumberContract;
-    /**
-     * Serializes the PhoneNumber instance to a JSON-compatible object
-     *
-     * This method creates a minimal object representation. Only the E.164 format
-     * is stored as everything else (country code, compact number, number type,
-     * and MNO info) can be reconstructed from it.
-     */
-    toJSON(): PhoneNumberJSON;
-    /**
-     * Serializes the PhoneNumber instance to a JSON string
-     */
-    toJSONString(): string;
-    /**
-     * Creates a PhoneNumber instance from a JSON-compatible object or string
-     *
-     * This static method reconstructs a PhoneNumber instance from data that was
-     * previously serialized using toJSON(). It uses PhoneNumberFactory to get
-     * the appropriate instance (generic or country-specific like TZMobileNumber).
-     * All properties including country code, compact number, MNO info, and number
-     * type are automatically reconstructed from the E.164 format.
-     */
-    static fromJSON(json: PhoneNumberJSON | string): PhoneNumber | undefined;
-    /**
-     * Creates a PhoneNumber instance from a JSON string
-     */
-    static fromJSONString(jsonString: string): PhoneNumber | undefined;
-    /**
-     * Type guard to check if an object is a valid PhoneNumberJSON using Zod validation
-     */
-    static isPhoneNumberJSON(obj: unknown): obj is PhoneNumberJSON;
-}

package/dist/models/phone-number/phone-number.factory.d.ts

@@ -1,52 +0,0 @@
-import { MNOInfo } from "./mno/mno.types.js";
-import { PhoneNumberParseOptions, PhoneNumberContract } from "./phone-number.types.js";
-/**
- * Factory class for creating phone number objects that conform to PhoneNumberContract.
- * It attempts to use country-specific implementations (like TZMobileNumber, KEMobileNumber)
- * when available and appropriate, otherwise falls back to the generic PhoneNumber class.
- *
- * Also provides validation methods related to specific use cases like payouts.
- */
-export declare class PhoneNumberFactory {
-    /**
-     * Creates an appropriate phone number instance (generic or country-specific)
-     * based on the input string and options.
-     *
-     * @param {string} numberToParse The raw phone number string.
-     * @param {PhoneNumberParseOptions} [options] Optional parsing options (e.g., defaultCountry).
-     * @returns {PhoneNumberContract | undefined} An instance conforming to PhoneNumberContract
-     * if the input is valid, otherwise undefined.
-     */
-    static create(numberToParse: string, options?: PhoneNumberParseOptions): PhoneNumberContract | undefined;
-    /**
-     * Convenience method to check if an input string can be constructed into
-     * ANY valid phone number object via the factory.
-     * @param {string | null | undefined} input The raw phone number string.
-     * @param {PhoneNumberParseOptions} [options] Optional parsing options.
-     * @returns {boolean} True if a valid phone number object can be created.
-     */
-    static canCreate(input: string | null | undefined, options?: PhoneNumberParseOptions): boolean;
-    /**
-     * Checks if a phone number (provided as a string or a PhoneNumberContract object)
-     * represents a valid number that can be successfully processed by the specific
-     * country implementation (TZMobileNumber or KEMobileNumber) required for payouts,
-     * and is of type MOBILE.
-     *
-     * @param input The raw phone number string OR an existing PhoneNumberContract object.
-     * @returns True if the number is valid for payout, false otherwise.
-     */
-    static checkPayoutEligibility(input: string | PhoneNumberContract): boolean;
-    /**
-     * Retrieves the Mobile Network Operator (MNO) information for a given phone number.
-     * This function first checks if the number is eligible for payout (i.e., a valid
-     * mobile number in a supported country). If it is, and the country is Tanzania (TZ),
-     * it attempts to parse the number using the Tanzania-specific number class
-     * (`TZMobileNumber`) to extract operator details. For other supported countries
-     * or if the parsing fails for Tanzania, it returns undefined.
-     *
-     * @param {string | PhoneNumberContract} input The raw phone number string OR an existing PhoneNumberContract object.
-     * @returns {MNOInfo | undefined} An object containing MNO information if the number
-     * is a valid Tanzanian mobile number and the operator can be identified; otherwise, undefined.
-     */
-    static getMNO(input: string | PhoneNumberContract): MNOInfo | undefined;
-}

package/dist/models/phone-number/phone-number.service.d.ts

@@ -1,36 +0,0 @@
-import { type NumberType, type PhoneNumber as LibPhoneNumber } from "libphonenumber-js/max";
-import { PhoneNumberFormat } from "./phone-number.types.js";
-import { ISO2CountryCode } from "@models/country/country.types.js";
-export interface ParsedPhoneNumber {
-    libInstance: LibPhoneNumber;
-    countryCode: ISO2CountryCode | undefined;
-    compactNumber: string;
-    e164Format: string;
-    isValid: boolean;
-    numberType: NumberType | undefined;
-}
-export declare class PhoneNumberService {
-    private static instance;
-    private constructor();
-    static getInstance(): PhoneNumberService;
-    /**
-     * Parses a phone number string using libphonenumber-js.
-     * @param numberToParse The raw phone number string.
-     * @param defaultCountry Optional default country code.
-     * @returns A ParsedPhoneNumber object if successful, otherwise undefined.
-     */
-    parse(numberToParse: string, defaultCountry?: ISO2CountryCode): ParsedPhoneNumber | undefined;
-    /**
-     * Validates a previously parsed LibPhoneNumber instance.
-     * @param libInstance The LibPhoneNumber instance from libphonenumber-js.
-     * @returns True if the number is considered valid by the library.
-     */
-    isValid(libInstance: LibPhoneNumber | undefined): boolean;
-    /**
-     * Formats a previously parsed LibPhoneNumber instance.
-     * @param libInstance The LibPhoneNumber instance from libphonenumber-js.
-     * @param formatType Our local PhoneNumberFormat enum value.
-     * @returns The formatted string, or the E.164 format as fallback.
-     */
-    format(libInstance: LibPhoneNumber | undefined, formatType: PhoneNumberFormat): string;
-}

package/dist/models/phone-number/phone-number.types.d.ts

@@ -1,115 +0,0 @@
-import { ISO2CountryCode } from "@models/country/country.types.js";
-import { MNOInfo } from "./mno/mno.types.js";
-/**
- * Enumeration for various phone number formats used for display and processing.
- */
-export declare enum PhoneNumberFormat {
-    /**
-     * International format, typically used for display.
-     * Includes '+' and country code, may include spacing for readability.
-     * (e.g., +1 202 555 0123)
-     * Note: Exact spacing might vary based on library implementation or locale.
-     */
-    INTERNATIONAL = "INTERNATIONAL",
-    /**
-     * National format, typically including national prefix (like '0') and local spacing.
-     * Formatting varies significantly by country.
-     * (e.g., 0712 345 678 for TZ, (213) 373-4253 for US)
-     */
-    NATIONAL = "NATIONAL",
-    /**
-     * Compact national format (National Significant Number).
-     * Typically digits only, without country code or national prefix '0'.
-     * (e.g., 712345678 for TZ, 2133734253 for US)
-     */
-    COMPACT = "COMPACT",
-    /**
-     * RFC3966 URI format for telephone numbers.
-     * (e.g., tel:+1-202-555-0123 or tel:+255712345678)
-     */
-    RFC3966 = "RFC3966",
-    /**
-     * Strict E.164 format. Includes '+' and country code, followed only by digits
-     * with no spacing or formatting characters. Globally unique.
-     * (e.g., +12025550123, +255712345678)
-     */
-    E164 = "E164",
-    /**
-     * International numeric format without the '+' prefix.
-     * Includes country code followed by the National Significant Number (NSN),
-     * digits only, with no formatting characters or separators.
-     * Commonly used in storage, logging, or systems where '+' is unnecessary or undesirable.
-     * (e.g., 12025550123, 255712345678)
-     */
-    INTERNATIONAL_NUMERIC = "INTERNATIONAL_NUMERIC"
-}
-/**
- * Represents the type of a phone number, mimicking the classification
- * used by the underlying libphonenumber-js library.
- */
-export declare enum PhoneNumberType {
-    FIXED_LINE = "FIXED_LINE",
-    MOBILE = "MOBILE",
-    FIXED_LINE_OR_MOBILE = "FIXED_LINE_OR_MOBILE",// Indicates ambiguity between fixed line and mobile
-    TOLL_FREE = "TOLL_FREE",
-    PREMIUM_RATE = "PREMIUM_RATE",
-    SHARED_COST = "SHARED_COST",
-    VOIP = "VOIP",// Voice over IP
-    PERSONAL_NUMBER = "PERSONAL_NUMBER",
-    PAGER = "PAGER",
-    UAN = "UAN",// Universal Access Number
-    VOICEMAIL = "VOICEMAIL",
-    UNKNOWN = "UNKNOWN"
-}
-/**
- * Options for parsing phone numbers
- */
-export interface PhoneNumberParseOptions {
-    /**
-     * Default country ISO code to use when parsing a non-international number,
-     * or when a dial code is shared by multiple countries.
-     */
-    defaultCountry?: ISO2CountryCode;
-}
-/**
- * Interface defining the common contract for all phone number objects
- * within the system (e.g., used by TemboPlus).
- */
-export interface PhoneNumberContract {
-    /** The phone number in E.164 format (e.g., +255712345678) */
-    readonly e164Format: string;
-    /** The national significant number (e.g., 712345678 for TZ) */
-    readonly compactNumber: string;
-    /** The ISO 3166-1 alpha-2 country code (e.g., "TZ", "KE") */
-    readonly countryCode: ISO2CountryCode;
-    /**
-     * Validates the phone number structure against rules for its country
-     * using the underlying phone number library.
-     * @returns {boolean} True if the number structure is valid for the country.
-     */
-    validate(): boolean;
-    /**
-     * Formats the number into different standard styles using the underlying library.
-     * @param {PhoneNumberFormat} format - The desired output format.
-     * @returns {string} The formatted phone number string.
-     */
-    getWithFormat(format: PhoneNumberFormat): string;
-    /**
-     * Gets associated mobile operator information, if available and implemented
-     * for the specific country. Returns undefined if not applicable or not found.
-     * @returns {MNOInfo | undefined} Operator details or undefined.
-     */
-    getOperatorInfo(): MNOInfo | undefined;
-    /**
-     * Gets a human-readable label, typically the international format.
-     * @returns {string} A display label for the phone number.
-     */
-    get label(): string;
-    /**
-     * Gets the type of the phone number (e.g., MOBILE, FIXED_LINE) as determined
-     * by the underlying phone number library.
-     * Requires library metadata that includes number types (e.g., libphonenumber-js/max).
-     * @returns {PhoneNumberType | undefined} The determined type or undefined if unknown/invalid.
-     */
-    getNumberType(): PhoneNumberType | undefined;
-}

package/dist/models/phone-number/phone-number.utils.d.ts

@@ -1,67 +0,0 @@
-import { CountryCode } from "@models/country/country.types.js";
-export declare const phoneLogger: import("pino").Logger<never, boolean>;
-export declare const PhoneNumberUtils: {
-    /**
-     * Removes all whitespace characters from the given string.
-     *
-     * @param {string} input - The input string.
-     * @returns {string} String with whitespace removed.
-     *
-     * @example
-     * removeSpaces(" 0712 345  678 ") // "0712345678"
-     * removeSpaces("   +255 712 345 678") // "+255712345678"
-     */
-    removeSpaces: (input: string) => string;
-    /**
-     * Strips all formatting characters used to enhance readability in phone numbers.
-     * Preserves only digits and an optional leading '+' if present.
-     *
-     * Characters removed include:
-     * - Whitespace: space, tab, non-breaking space
-     * - Hyphens, dots, slashes: `-`, `.`, `/`
-     * - Brackets: `(`, `)`
-     * - URI prefix: `tel:`
-     * - Extensions like `ext.`, `x`, or `#` and following digits
-     *
-     * @param {string} input - The phone number string to strip.
-     * @returns {string} A cleaned string with only digits and optional '+' prefix.
-     *
-     * @example
-     * stripFormattingCharacters("tel:+255 (712) 345-678") // "+255712345678"
-     * stripFormattingCharacters("0712-345-678 x99") // "0712345678"
-     * stripFormattingCharacters("(+255) 712/345.678 ext. 9") // "+255712345678"
-     * stripFormattingCharacters("712abc345678") // "712abc345678"
-     */
-    stripFormattingCharacters: (input: string) => string;
-    /**
-     * Normalizes a phone number string by:
-     * - Removing all special characters and spaces
-     * - Preserving only digits and a leading '+'
-     * - Ensuring the result starts with a '+' wherever appropriate
-     * - Handling national numbers when default country is provided
-     * - Removing leading '0' when it's a national number prefix
-     *
-     * @param {string} input - The phone number string to normalize
-     * @param {CountryCode} [defaultCountry] - Optional default country code
-     * @returns {string} The normalized phone number string
-     * @throws {Error} If invalid country code provided
-     *
-     * @example
-     * normalizePhoneNumber("+255 (712) 345-678") // "+255712345678"
-     * normalizePhoneNumber("0712 345 678", "TZ") // "+255712345678"
-     * normalizePhoneNumber("255712345678") // "255712345678"
-     */
-    normalizePhoneNumber: (input: string, defaultCountry?: CountryCode) => string;
-    /**
-     * Checks if a string contains only digits or a `+` prefix followed by digits.
-     *
-     * @param {string} input - The input string.
-     * @returns {boolean} True if valid format, false otherwise.
-     *
-     * @example
-     * isOnlyDigitsOrPlus("+255712345678") // true
-     * isOnlyDigitsOrPlus("0712345678") // true
-     * isOnlyDigitsOrPlus("+255-712-345-678") // false
-     */
-    isOnlyDigitsOrPlus: (input: string) => boolean;
-};

package/dist/reports/index.d.ts

@@ -1 +0,0 @@
-export * from "./report-manager.js";

package/dist/services/index.d.ts

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

package/dist/services/logger.d.ts

@@ -1,2 +0,0 @@
-import pino from "pino";
-export declare const logger: pino.Logger<never, boolean>;

package/dist/utils/text.d.ts

@@ -1,103 +0,0 @@
-/**
- * Capitalizes the first letter of a string and converts the rest of the string to lowercase.
- * @param {string} str - The input string.
- * @returns {string} - The formatted string with the first letter capitalized.
- */
-declare function capitalizeFirstLetter(str: string): string;
-/**
- * Combines a first name and a last name into a full name.
- * @param {string} firstName - The first name.
- * @param {string} lastName - The last name.
- * @returns {string} - The full name formatted as "FirstName LastName".
- */
-declare function getFullName(firstName: string, lastName: string): string;
-/**
- * Generates a URL-friendly slug from a given text.
- * @param {string} text - The input string.
- * @returns {string} - The generated slug with lowercase alphanumeric characters and hyphens.
- */
-declare function generateSlug(text: string): string;
-/**
- * Abbreviates a full name into a first name and the initial of the last name.
- * @param {string} fullName - The input full name.
- * @returns {string} - The abbreviated name in the format "FirstName L.".
- */
-declare function abbreviateName(fullName: string): string;
-/**
- * Extracts the initials from a full name.
- * @param {string} fullName - The input full name.
- * @returns {string} - The initials in uppercase format.
- */
-declare function getInitialsFrom(fullName: string): string;
-/**
- * Validates a personal name (account holder name, wallet owner name, etc.)
- * Used across bank accounts and MNO wallets for consistent validation.
- *
- * @param {string} name - The name to validate
- * @returns {boolean} True if the name meets all validation criteria, false otherwise
- *
- * @example
- * // Returns true
- * validatePersonalName("John Smith");
- *
- * @example
- * // Returns false (too short)
- * validatePersonalName("Jo");
- *
- * @example
- * // Returns false (invalid characters)
- * validatePersonalName("User123");
- */
-declare function validatePersonalName(name: string): boolean;
-/**
- * Validates a business name (company, organization, etc.)
- * More lenient than personal name validation.
- *
- * @param {string} name - The business name to validate
- * @returns {boolean} True if the name meets business name criteria, false otherwise
- *
- * @example
- * // Returns true
- * validateBusinessName("ABC Corporation Ltd");
- *
- * @example
- * // Returns true
- * validateBusinessName("Smith & Sons Inc.");
- *
- * @example
- * // Returns true
- * validateBusinessName("M-Pesa");
- */
-declare function validateBusinessName(name: string): boolean;
-/**
- * Validates any name (personal or business) with automatic detection.
- * First tries to detect if it's a business name, then validates accordingly.
- * If detection fails, tries both validation methods.
- *
- * @param {string} name - The name to validate (personal or business)
- * @returns {boolean} True if the name is valid as either personal or business name
- *
- * @example
- * // Returns true (personal name)
- * validateName("John Smith");
- *
- * @example
- * // Returns true (business name)
- * validateName("CRDB Bank PLC");
- *
- * @example
- * // Returns true (could be either)
- * validateName("Smith Solutions");
- */
-declare function validateName(name: string): boolean;
-export declare const TextUtils: {
-    capitalizeFirstLetter: typeof capitalizeFirstLetter;
-    getFullName: typeof getFullName;
-    generateSlug: typeof generateSlug;
-    abbreviateName: typeof abbreviateName;
-    getInitialsFrom: typeof getInitialsFrom;
-    validatePersonalName: typeof validatePersonalName;
-    validateBusinessName: typeof validateBusinessName;
-    validateName: typeof validateName;
-};
-export {};