@temboplus/frontend-core 0.4.0 → 0.4.2

package/dist/models/country/country.schema.d.ts

@@ -1,73 +0,0 @@
-import { z } from "zod";
-/**
- * Zod schema for Country JSON serialization
- * This schema validates the JSON representation of a Country instance
- */
-export declare const CountryJSONSchema: z.ZodObject<{
-    /** The ISO 3166-1 alpha-2 country code */
-    code: z.ZodString;
-    /** Version for future compatibility */
-    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-}, "strip", z.ZodTypeAny, {
-    code: string;
-    version: string;
-}, {
-    code: string;
-    version?: string | undefined;
-}>;
-/**
- * Zod schema for validating ISO 3166-1 alpha-2 country codes.
- *
- * This schema checks if a given string is a valid ISO 3166-1 alpha-2 country code
- * by checking against the predefined set of valid codes.
- *
- * @example
- * const result = iso2CountryCodeSchema.safeParse("US");
- * if (result.success) {
- *   console.log("Valid ISO2 country code");
- * } else {
- *   console.error("Invalid ISO2 country code");
- * }
- */
-export declare const ISO2CountryCodeSchema: z.ZodEffects<z.ZodString, string, string>;
-/**
- * Zod schema for validating ISO 3166-1 alpha-3 country codes.
- *
- * This schema checks if a given string is a valid ISO 3166-1 alpha-3 country code
- * by checking against the predefined set of valid codes.
- *
- * @example
- * const result = iso3CountryCodeSchema.safeParse("USA");
- * if (result.success) {
- *  console.log("Valid ISO3 country code");
- * } else {
- *  console.error("Invalid ISO3 country code");
- * }
- */
-export declare const ISO3CountryCodeSchema: z.ZodEffects<z.ZodString, string, string>;
-/**
- * Zod schema for validating either ISO 3166-1 alpha-2 or alpha-3 country codes.
- *
- * This schema allows for flexibility in accepting both two-letter and three-letter
- * country codes, making it useful for functions that need to handle both formats.
- *
- * @example
- * const result = countryCodeSchema.safeParse("US");
- * if (result.success) {
- *   console.log("Valid country code");
- * } else {
- *   console.error("Invalid country code");
- * }
- */
-export declare const CountryCodeSchema: z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodEffects<z.ZodString, string, string>, z.ZodObject<{
-    /** The ISO 3166-1 alpha-2 country code */
-    code: z.ZodString;
-    /** Version for future compatibility */
-    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-}, "strip", z.ZodTypeAny, {
-    code: string;
-    version: string;
-}, {
-    code: string;
-    version?: string | undefined;
-}>]>;

package/dist/models/country/index.d.ts

@@ -1,4 +0,0 @@
-export * from "./country.js";
-export * from "./country.types.js";
-export * from "./country.validation.js";
-export * from "./country.schema.js";

package/dist/models/currency/currency.d.ts

@@ -1,214 +0,0 @@
-/**
- * @fileoverview This file contains both the Currency class and CurrencyService class.
- *
- * ARCHITECTURE NOTE: Currency and CurrencyService Classes
- * ======================================================
- *
- * These two classes have been intentionally placed in the same file to resolve
- * a circular dependency issue. The original implementation had these in separate files:
- *
- * - Currency class: Defines currency properties and lookup helpers
- * - CurrencyService class: Loads currency data and provides instance methods
- *
- * The circular dependency occurred because:
- * 1. Currency needed CurrencyService for centralized lookups
- * 2. CurrencyService needed Currency to create Currency instances
- *
- * By combining both classes in a single file:
- * - We ensure proper initialization order
- * - The public API remains unchanged
- *
- * This approach follows the principle that closely related classes with circular
- * dependencies are best managed in a unified module.
- */
-import type { CurrencyCode } from "./currency.types.js";
-import { z } from "zod";
-import { CurrencyJSONSchema } from "./currency.schema.js";
-/**
- * Infer the CurrencyJSON type from the schema
- */
-export type CurrencyJSON = z.infer<typeof CurrencyJSONSchema>;
-/**
- * Represents a currency with essential details.
- * @class Currency
- */
-export declare class Currency {
-    private readonly _symbol;
-    private readonly _name;
-    private readonly _symbolNative;
-    private readonly _decimalDigits;
-    private readonly _rounding;
-    private readonly _code;
-    private readonly _namePlural;
-    /**
-     * Creates a new Currency instance.
-     * @param {string} _symbol - The international symbol of the currency
-     * @param {string} _name - The full name of the currency
-     * @param {string} _symbolNative - The native symbol of the currency
-     * @param {number} _decimalDigits - Number of decimal places typically used with this currency
-     * @param {number} _rounding - Rounding increment used for this currency
-     * @param {CurrencyCode} _code - The ISO 4217 currency code
-     * @param {string} _namePlural - The plural form of the currency name
-     */
-    constructor(token: symbol, _symbol: string, _name: string, _symbolNative: string, _decimalDigits: number, _rounding: number, _code: CurrencyCode, _namePlural: string);
-    /**
-     * Gets the international symbol of the currency.
-     * @returns {string} The international symbol of the currency
-     */
-    get symbol(): string;
-    /**
-     * Gets the full name of the currency.
-     * @returns {string} The full name of the currency
-     */
-    get name(): string;
-    /**
-     * Gets the native symbol of the currency.
-     * @returns {string} The native symbol of the currency
-     */
-    get symbolNative(): string;
-    /**
-     * Gets the number of decimal places typically used with this currency.
-     * @returns {number} The number of decimal places
-     */
-    get decimalDigits(): number;
-    /**
-     * Gets the rounding increment used for this currency.
-     * @returns {number} The rounding increment
-     */
-    get rounding(): number;
-    /**
-     * Gets the ISO 4217 currency code.
-     * @returns {string} The ISO 4217 currency code
-     */
-    get code(): CurrencyCode;
-    /**
-     * Gets the plural form of the currency name.
-     * @returns {string} The plural form of the currency name
-     */
-    get namePlural(): string;
-    /**
-     * Creates a string representation of the currency.
-     * @returns {string} String representation of the currency
-     */
-    toString(): string;
-    /**
-     * Retrieves a currency by its ISO code.
-     * @param {CurrencyCode} code The ISO code of the currency.
-     * @returns {Currency | undefined} The currency corresponding to the ISO code or `undefined` if not found.
-     */
-    static fromCode(code: CurrencyCode): Currency | undefined;
-    /**
-     * Returns all available currencies.
-     * @returns {Currency[]} Array of all currencies
-     */
-    static getAll(): Currency[];
-    /**
-     * Validates if a given currency code is valid
-     * @param code The currency code to validate
-     * @returns True if the currency code is valid
-     */
-    static isValidCode(code?: CurrencyCode | null): boolean;
-    /**
-     * Attempts to create a Currency instance from an ISO code string.
-     * The `CurrencyCode` type provides type hints for valid ISO codes but resolves to `string`.
-     * @param input The ISO code string.
-     * @returns A Currency instance if valid input, undefined otherwise.
-     */
-    static from(input: string | CurrencyCode): Currency | undefined;
-    /**
-     * Checks if an unknown value is a Currency instance
-     * @param obj The value to validate
-     * @returns Type predicate indicating if the value is a valid Currency
-     */
-    static is(obj: unknown): obj is Currency;
-    /**
-     * Serializes the Currency instance to a JSON-compatible object
-     */
-    toJSON(): CurrencyJSON;
-    /**
-     * Serializes the Currency instance to a JSON string
-     */
-    toJSONString(): string;
-    /**
-     * Creates a Currency instance from a JSON-compatible object or string
-     */
-    static fromJSON(json: CurrencyJSON | string): Currency | undefined;
-    /**
-     * Creates a Currency instance from a JSON string
-     */
-    static fromJSONString(jsonString: string): Currency | undefined;
-    /**
-     * Type guard to check if an object is a valid CurrencyJSON using Zod validation
-     */
-    static isCurrencyJSON(obj: unknown): obj is CurrencyJSON;
-}
-/**
- * Service for managing currency data.
- * @class CurrencyService
- */
-export declare class CurrencyService {
-    private static instance;
-    private currencyList;
-    private currencyRecord;
-    private constructor();
-    /**
-     * Gets the singleton instance of CurrencyService.
-     * Creates the instance if it doesn't exist.
-     * @static
-     * @returns {CurrencyService} The singleton instance
-     */
-    static getInstance(): CurrencyService;
-    /**
-     * Initializes the service with currency data.
-     * Should be called once when your application starts.
-     */
-    private initialize;
-    /**
-     * Gets all currencies.
-     * @returns {Currency[]} Array of all currencies
-     */
-    getAll(): Currency[];
-    /**
-     * Gets all currencies as a record.
-     * @returns {Record<string, Currency>} Record of currency codes and currency objects
-     */
-    getAllAsRecord(): Record<string, Currency>;
-    /**
-     * Retrieves a currency by its ISO code.
-     * @param {string} code The ISO code of the currency.
-     * @returns {Currency | undefined} The currency corresponding to the ISO code or `undefined` if not found.
-     */
-    fromCode(code: string): Currency | undefined;
-    /**
-     * Validates if a given ISO currency code is valid
-     *
-     * @param {string | null | undefined} code - The currency code to validate.
-     *   Should be a three-letter ISO currency code (e.g., 'USD', 'EUR').
-     *
-     * @returns {boolean} Returns true if:
-     *   - The currency code is not null/undefined
-     *   - The currency code successfully resolves to a valid Currency instance
-     *   Returns false otherwise.
-     */
-    isValidCode(code?: string | null): boolean;
-    /**
-     * Gets a regex-ready pattern matching all currency symbols
-     * Pattern is memoized for performance
-     * @returns {string} Pipe-separated pattern of escaped currency symbols
-     *
-     * @example
-     * const pattern = currencyService.getCurrencySymbolPattern();
-     * // Returns something like: "\$|€|\£|¥"
-     */
-    getCurrencySymbolPattern(): string;
-    /**
-     * Escapes special characters in a string for use in regular expressions
-     * @private
-     * @param {string} string - The string to escape
-     * @returns {string} The escaped string
-     *
-     * @example
-     * private escapeRegExp("$") // Returns "\$"
-     */
-    private escapeRegExp;
-}

package/dist/models/currency/currency.schema.d.ts

@@ -1,24 +0,0 @@
-import { z } from "zod";
-/**
- * Zod schema for validating ISO 4217 currency codes
- *
- * This schema checks if the provided string is a valid ISO 4217 currency code.
- * If the validation fails, it returns an error message.
- */
-export declare const CurrencyCodeSchema: z.ZodEffects<z.ZodString, string, string>;
-/**
- * Zod schema for Currency JSON serialization
- * This schema validates the JSON representation of a Currency instance
- */
-export declare const CurrencyJSONSchema: z.ZodObject<{
-    /** The ISO 4217 currency code */
-    code: z.ZodString;
-    /** Version for future compatibility */
-    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-}, "strip", z.ZodTypeAny, {
-    code: string;
-    version: string;
-}, {
-    code: string;
-    version?: string | undefined;
-}>;

package/dist/models/currency/currency.validation.d.ts

@@ -1,11 +0,0 @@
-import { type CurrencyCode } from "./currency.types.js";
-export declare const CurrencyValidation: {
-    isCurrencyCode: typeof isCurrencyCode;
-};
-/**
- * Type guard to check if a string is a valid CurrencyCode.
- * @param code The string to check.
- * @returns True if the string is a member of the CurrencyCode union type, false otherwise.
- */
-declare function isCurrencyCode(code: string): code is CurrencyCode;
-export {};

package/dist/models/currency/index.d.ts

@@ -1,4 +0,0 @@
-export * from "./currency.js";
-export * from "./currency.types.js";
-export * from "./currency.validation.js";
-export * from "./currency.schema.js";

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

@@ -1,6 +0,0 @@
-export * from "./phone-number.factory.js";
-export * from "./phone-number.types.js";
-export * from "./mno/mno.utils.js";
-export * from "./mno/mno.types.js";
-export * from "./phone-number.js";
-export * from "./mno/index.js";

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

@@ -1,6 +0,0 @@
-export * from "./ke/mobile-number.ke.js";
-export * from "./ke/mobile-number.ke-mnos.js";
-export * from "./tz/mobile-number.tz.js";
-export * from "./tz/mobile-number.tz-mnos.js";
-export * from "./mno.types.js";
-export * from "./mno.utils.js";

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

@@ -1,22 +0,0 @@
-import { ISO2CountryCode } from "@models/country/country.types.js";
-import { CountryMNOImplementation, KEMNOId, MNOInfo } from "@models/phone-number/mno/mno.types.js";
-/**
- * Configuration object for Kenyan mobile network operators.
- * Conforms to the generic MNOInfo interface.
- */
-export declare const KE_MNO_CONFIG: Record<KEMNOId, MNOInfo>;
-/**
- * Gets all available Kenyan MNO configurations.
- * @returns Array of all KE MNO configurations.
- */
-export declare function getAllKEMNOs(): MNOInfo[];
-export declare class KEMNOImplementation implements CountryMNOImplementation {
-    private static instance;
-    private constructor();
-    static getInstance(): KEMNOImplementation;
-    getAllMNOs(): MNOInfo[];
-    isValidMNOId(id: string): boolean;
-    getMNOById(id: string): MNOInfo | undefined;
-    requiresExplicitMNO(): boolean;
-    getCountryCode(): ISO2CountryCode;
-}

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

@@ -1,45 +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 Kenyan (KE) **mobile** phone number.
- * Extends the generic PhoneNumber class and implements the common PhoneNumberContract interface.
- * Note: Does not provide MNO details as per requirement.
- */
-export declare class KEMobileNumber 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 Kenyan **mobile** phone number.
-     * Checks base validity AND ensures the national number starts with a valid KE mobile prefix.
-     * @returns {boolean} True if the number is a valid KE mobile number structure.
-     */
-    validate(): boolean;
-    /**
-     * Gets associated mobile operator information. Returns undefined for KE.
-     * Overrides the base implementation.
-     * @returns {MNOInfo | undefined} Always returns 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 `KEMobileNumber` instance from a given string input.
-     * Performs KE-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 {KEMobileNumber | undefined} An instance if valid, otherwise undefined.
-     */
-    static from(input: string | null | undefined, options?: PhoneNumberParseOptions): KEMobileNumber | undefined;
-}

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

@@ -1,62 +0,0 @@
-/**
- * Tanzanian mobile network operator identifiers.
- * Values are used in payout channel-code field and should not change.
- */
-import { ISO2CountryCode } from "@models/country/country.types.js";
-export declare enum TZMNOId {
-    VODACOM = "VODACOM",
-    AIRTEL = "AIRTEL",
-    TIGO = "TIGO",
-    HALOTEL = "HALOTEL"
-}
-/**
- * Kenyan mobile network operator identifiers.
- * Values are used in payout channel-code field and should not change.
- */
-export declare enum KEMNOId {
-    SAFARICOM = "SAFARICOM"
-}
-/**
- * Union type for all MNO IDs
- */
-export type MNOId = TZMNOId | KEMNOId;
-/**
- * Generic interface for Mobile Network Operator information.
- * Now properly typed with specific MNO IDs.
- */
-export interface MNOInfo {
-    id: MNOId;
-    displayName: string;
-    mobileMoneyService: string;
-}
-/**
- * Extended interface for country-specific MNO implementations
- */
-export interface CountryMNOImplementation {
-    /**
-     * Get all MNOs for this country
-     */
-    getAllMNOs(): MNOInfo[];
-    /**
-     * Validate if an MNO ID is valid for this country
-     */
-    isValidMNOId(id: string): boolean;
-    /**
-     * Get MNO info by ID
-     */
-    getMNOById(id: string): MNOInfo | undefined;
-    /**
-     * Check if this country requires explicit MNO (has MNP)
-     */
-    requiresExplicitMNO(): boolean;
-    /**
-     * Get the country code
-     */
-    getCountryCode(): ISO2CountryCode;
-    /**
-     * Validate MNO for a phone number (if applicable)
-     *
-     * Returns undefined for countries with MNP
-     */
-    validateMNOForPhoneNumber?(phoneNumber: string, mnoId: string): boolean;
-}

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

@@ -1,40 +0,0 @@
-import { CountryCode, ISO2CountryCode } from "@models/country/country.types.js";
-import { CountryMNOImplementation, MNOInfo } from "./mno.types.js";
-/**
- * Utility functions for working with MNO data across countries.
- */
-export declare class MNOUtils {
-    private static implementations;
-    /**
-     * Get MNO implementation for a specific country
-     */
-    private static getImplementation;
-    /**
-     * Get all MNOs for a specific country
-     */
-    static getCountryMNOs(countryCode: CountryCode): MNOInfo[];
-    /**
-     * Validate if an MNO ID is valid for a specific country
-     */
-    static isValidMNOForCountry(mnoId: string, countryCode: CountryCode): boolean;
-    /**
-     * Get MNO info by ID for a specific country
-     */
-    static getMNOById(mnoId: string, countryCode: CountryCode): MNOInfo | undefined;
-    /**
-     * Check if a country requires explicit MNO (has MNP)
-     */
-    static requiresExplicitMNO(countryCode: CountryCode): boolean;
-    /**
-     * Validate MNO for a phone number (country-specific logic)
-     */
-    static validateMNOForPhoneNumber(phoneNumber: string, mnoId: string, countryCode: CountryCode): boolean;
-    /**
-     * Get MNO by phone number (for countries without MNP)
-     */
-    static getMNOByPhoneNumber(phoneNumber: string, countryCode: CountryCode): MNOInfo | undefined;
-    /**
-     * Register a new country implementation
-     */
-    static registerCountryImplementation(countryCode: ISO2CountryCode, implementation: CountryMNOImplementation): void;
-}

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

@@ -1,48 +0,0 @@
-import { ISO2CountryCode } from "@models/country/country.types.js";
-import { CountryMNOImplementation, MNOInfo, TZMNOId } from "@models/phone-number/mno/mno.types.js";
-/**
- * Configuration object for Tanzanian mobile network operators.
- * Conforms to the generic NetworkOperatorInfo interface.
- */
-export declare const TZ_MNO_CONFIG: Record<TZMNOId, MNOInfo>;
-/**
- * Tanzania MNO Implementation
- * Handles all TZ-specific MNO logic including prefix validation
- */
-export declare class TZMNOImplementation implements CountryMNOImplementation {
-    private static instance;
-    private constructor();
-    static getInstance(): TZMNOImplementation;
-    getAllMNOs(): MNOInfo[];
-    isValidMNOId(id: string): boolean;
-    getMNOById(id: string): MNOInfo | undefined;
-    requiresExplicitMNO(): boolean;
-    getCountryCode(): ISO2CountryCode;
-    /**
-     * Validate MNO against phone number prefix (TZ-specific logic)
-     */
-    validateMNOForPhoneNumber(phoneNumber: string, mnoId: string): boolean;
-    /**
-     * Get MNO by phone number prefix (TZ-specific)
-     */
-    getMNOByPhonePrefix(phoneNumber: string): MNOInfo | undefined;
-    /**
-     * Get prefixes for a specific MNO (TZ-specific utility)
-     */
-    getPrefixesForMNO(mnoId: TZMNOId): string[];
-}
-/**
- * @deprecated Use TZMNOImplementation.getInstance().getPrefixesForMNO() instead
- * Helper function within the TZ context to get prefixes for an operator ID.
- */
-export declare function getTZPrefixesForOperator(operatorId: TZMNOId): string[] | undefined;
-/**
- * @deprecated Use TZMNOImplementation.getInstance().getMNOByPhonePrefix() instead
- * Helper function within the TZ context to find operator config by prefix.
- */
-export declare function findTZOperatorByPrefix(prefix: string): MNOInfo | undefined;
-/**
- * @deprecated Use TZMNOImplementation.getInstance().getAllMNOs() instead
- * Gets all available Tanzanian MNO configurations.
- */
-export declare function getAllTZMNOs(): MNOInfo[];

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;
-}