@temboplus/afloat 0.1.61 → 0.1.63

package/dist/models/contact-info.model.d.ts

@@ -0,0 +1,817 @@
+import { Bank, ISO2CountryCode, PhoneNumber } from "@temboplus/frontend-core";
+import { PayoutDTO } from "../features/payout";
+import { ContactType, ContactDTO } from "../features/contact/contact.dtos";
+import type { BankSwiftCode, MNOId } from "@temboplus/frontend-core";
+/**
+ * Abstract base class that provides a common interface for different types of contact information.
+ * This class defines the structure and validation requirements for both mobile and bank contacts.
+ *
+ * Serves as the foundation for type-safe contact handling throughout the application,
+ * ensuring consistent behavior between mobile money and bank transfer contacts.
+ *
+ * @abstract
+ * @class BaseContactInfo
+ *
+ * @property {ContactType} type - The type of contact (either "Mobile" or "Bank")
+ * @property {ISO2CountryCode} countryCode - The ISO2 country code where this contact operates
+ *
+ * @example
+ * ```typescript
+ * // Cannot instantiate directly - use concrete implementations
+ * const mobileContact = new MobileContactInfo("John Doe", phoneNumber);
+ * const bankContact = new BankContactInfo("Jane Smith", bank, "123456789");
+ *
+ * // Polymorphic usage
+ * function processContact(contact: BaseContactInfo) {
+ *   console.log(`Processing ${contact.type} contact: ${contact.displayName}`);
+ *   console.log(`Channel: ${contact.channelDisplayName}`);
+ * }
+ * ```
+ */
+declare abstract class BaseContactInfo {
+    readonly type: ContactType;
+    readonly countryCode: ISO2CountryCode;
+    /**
+     * Creates a new instance of BaseContactInfo.
+     * Protected constructor ensures only subclasses can instantiate.
+     *
+     * @protected
+     * @param {ContactType} type - The type of contact to create ("Mobile" or "Bank")
+     * @param {ISO2CountryCode} countryCode - The ISO2 country code for this contact
+     */
+    constructor(type: ContactType, countryCode: ISO2CountryCode);
+    /**
+     * Gets the typed channel identifier for the contact.
+     * Returns MNO ID for mobile contacts, SWIFT code for bank contacts.
+     *
+     * @abstract
+     * @returns {MNOId | BankSwiftCode} The typed channel identifier
+     *
+     * @example
+     * ```typescript
+     * const mobileChannel: MNOId = mobileContact.channelId; // "VODACOM", "SAFARICOM", etc.
+     * const bankChannel: BankSwiftCode = bankContact.channelId; // "CORUTZTZ", "KCBLKENX", etc.
+     * ```
+     */
+    abstract get channelId(): MNOId | BankSwiftCode;
+    /**
+     * Gets the human-readable channel name for display purposes.
+     * Returns mobile money service name for mobile contacts, bank short name for bank contacts.
+     *
+     * @abstract
+     * @returns {string} The display-friendly channel name
+     *
+     * @example
+     * ```typescript
+     * console.log(mobileContact.channelName); // "M-Pesa", "Airtel Money", etc.
+     * console.log(bankContact.channelName); // "CRDB", "KCB", etc.
+     * ```
+     */
+    abstract get channelName(): string;
+    /**
+     * Gets the primary display name for the contact.
+     *
+     * @abstract
+     * @returns {string} The contact's display name (personal name for mobile, account name for bank)
+     */
+    abstract get accountName(): string;
+    /**
+     * Gets the primary account/identification number for the contact.
+     *
+     * @abstract
+     * @returns {string} The contact's number (phone number for mobile, account number for bank)
+     */
+    abstract get accountNumber(): string;
+    /**
+     * Gets the localized label for the display name field.
+     *
+     * @abstract
+     * @returns {string} The appropriate label for the display name based on contact type
+     */
+    abstract get accountNameLabel(): string;
+    /**
+     * Gets the localized label for the account number field.
+     *
+     * @abstract
+     * @returns {string} The appropriate label for the account number based on contact type
+     */
+    abstract get accountNumberLabel(): string;
+    /**
+     * Gets the localized label for the channel field.
+     *
+     * @abstract
+     * @returns {string} The appropriate label for the channel based on contact type
+     */
+    abstract get channelLabel(): string;
+    /**
+     * Validates that all contact information is consistent and correct.
+     *
+     * @abstract
+     * @returns {boolean} True if the contact information is valid
+     */
+    abstract validate(): boolean;
+}
+/**
+ * Implementation of BaseContactInfo for mobile phone contacts.
+ * Handles storage, validation, and display of contact details specific to mobile money services.
+ *
+ * This class properly delegates MNO-related logic to country-specific implementations,
+ * supporting both countries with Mobile Number Portability (MNP) and those without.
+ *
+ * **Key Features:**
+ * - Automatic MNO detection for countries without MNP (e.g., Tanzania)
+ * - Explicit MNO requirement for countries with MNP (e.g., Kenya)
+ * - Country-specific validation through MNOUtils delegation
+ * - Comprehensive error handling with structured context
+ *
+ * **MNP Handling:**
+ * - **Tanzania (no MNP)**: MNO can be auto-detected from phone number prefix
+ * - **Kenya (has MNP)**: MNO must be explicitly provided as numbers can be ported
+ *
+ * @extends BaseContactInfo
+ * @class MobileContactInfo
+ *
+ * @property {string} name - The contact's personal name
+ * @property {PhoneNumber} phoneNumber - The validated phone number object
+ * @property {MNOId} mnoId - The mobile network operator identifier (always available after construction)
+ *
+ * @example
+ * ```typescript
+ * // Tanzania - MNO auto-detected from prefix
+ * const tzContact = new MobileContactInfo("John Doe", tzPhoneNumber);
+ * console.log(tzContact.channel); // "VODACOM" (auto-detected)
+ *
+ * // Tanzania - Explicit MNO (validated against prefix)
+ * const tzExplicit = new MobileContactInfo("John Doe", tzPhoneNumber, TZMNOId.VODACOM);
+ *
+ * // Kenya - MNO must be explicit due to MNP
+ * const keContact = new MobileContactInfo("Jane Smith", kePhoneNumber, KEMNOId.SAFARICOM);
+ *
+ * // Kenya - This would throw an error (MNO required)
+ * // const keContact = new MobileContactInfo("Jane Smith", kePhoneNumber); // ❌ Error
+ * ```
+ *
+ * @throws {ContactInfoError} When validation fails (invalid name, phone, or MNO)
+ */
+export declare class MobileContactInfo extends BaseContactInfo {
+    readonly name: string;
+    readonly phoneNumber: PhoneNumber;
+    readonly mnoId: MNOId;
+    /**
+     * Creates a new mobile contact with comprehensive validation.
+     *
+     * **Validation Process:**
+     * 1. Validates name is non-empty
+     * 2. Validates phone number structure
+     * 3. Handles MNO validation based on country MNP status:
+     *    - **Countries with MNP (KE)**: Requires explicit MNO, validates it's valid for country
+     *    - **Countries without MNP (TZ)**: Can auto-detect or validate explicit MNO against prefix
+     *
+     * @param {string} name - The contact's personal name (required, non-empty)
+     * @param {PhoneNumber} phoneNumber - The validated phone number object
+     * @param {MNOId} [mnoId] - Optional MNO ID. Required for MNP countries (KE), optional for non-MNP (TZ)
+     *
+     * @throws {ContactInfoError} When any validation fails:
+     * - Empty or invalid name
+     * - Invalid phone number structure
+     * - Invalid MNO for the country
+     * - MNO-phone number mismatch (for non-MNP countries)
+     * - Missing MNO for MNP countries
+     * - Unable to auto-detect MNO for non-MNP countries
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // All these are valid
+     *   const tzAuto = new MobileContactInfo("John", tzPhone);
+     *   const tzExplicit = new MobileContactInfo("John", tzPhone, TZMNOId.VODACOM);
+     *   const keExplicit = new MobileContactInfo("Jane", kePhone, KEMNOId.SAFARICOM);
+     * } catch (error) {
+     *   if (error instanceof ContactInfoError) {
+     *     console.log(`${error.message} - Context:`, error.context);
+     *   }
+     * }
+     * ```
+     */
+    constructor(name: string, phoneNumber: PhoneNumber, mnoId?: MNOId);
+    /**
+     * Creates a MobileContactInfo instance from a ContactDTO object.
+     * Handles validation and MNO extraction from the DTO's channel field.
+     *
+     * **Process:**
+     * 1. Validates DTO type is "Mobile"
+     * 2. Validates country code format
+     * 3. Parses phone number with country context
+     * 4. Extracts and validates MNO from channel field (if provided)
+     * 5. Delegates to constructor for final validation
+     *
+     * @static
+     * @param {ContactDTO} info - The contact data transfer object
+     * @param {string} info.type - Must be "Mobile"
+     * @param {string} info.accountNo - The phone number string to parse
+     * @param {string} info.countryCode - ISO2 country code
+     * @param {string} info.displayName - The contact's name
+     * @param {string} [info.channel] - Optional MNO ID (required for MNP countries)
+     *
+     * @returns {MobileContactInfo | undefined} New instance if successful, undefined if validation fails
+     *
+     * @example
+     * ```typescript
+     * const contactDTO = {
+     *   type: "Mobile",
+     *   accountNo: "+255712345678",
+     *   countryCode: "TZ",
+     *   displayName: "John Doe",
+     *   channel: "VODACOM" // Optional for TZ, required for KE
+     * };
+     *
+     * const contact = MobileContactInfo.fromContactDTO(contactDTO);
+     * if (contact) {
+     *   console.log(`Created contact: ${contact.displayName}`);
+     * }
+     * ```
+     */
+    static fromContactDTO(info: ContactDTO): MobileContactInfo | undefined;
+    /**
+     * Creates a MobileContactInfo instance from a PayoutDTO object.
+     * Extracts mobile contact information from payout data structure.
+     *
+     * **Process:**
+     * 1. Validates country code format
+     * 2. Parses phone number from msisdn field
+     * 3. Extracts MNO from channel field (if available)
+     * 4. Uses payeeName as the contact name
+     * 5. Delegates to constructor for validation
+     *
+     * @static
+     * @param {PayoutDTO} info - The payout data transfer object
+     * @param {string} info.msisdn - The phone number in various formats
+     * @param {string} info.countryCode - ISO2 country code
+     * @param {string} info.payeeName - The recipient's name
+     * @param {string} [info.channel] - Optional MNO ID
+     *
+     * @returns {MobileContactInfo | undefined} New instance if successful, undefined if parsing fails
+     *
+     * @example
+     * ```typescript
+     * const payoutDTO = {
+     *   msisdn: "+254712345678",
+     *   countryCode: "KE",
+     *   payeeName: "Jane Smith",
+     *   channel: "SAFARICOM"
+     * };
+     *
+     * const contact = MobileContactInfo.fromPayoutDTO(payoutDTO);
+     * if (contact) {
+     *   console.log(`Payout contact: ${contact.displayName} via ${contact.channelDisplayName}`);
+     * }
+     * ```
+     */
+    static fromPayoutDTO(info: PayoutDTO): MobileContactInfo | undefined;
+    /**
+     * Type guard to validate if an unknown object is a valid MobileContactInfo instance.
+     * Performs comprehensive structural and data validation including country-specific MNO rules.
+     *
+     * **Validation Process:**
+     * 1. **Structural validation**: Checks required properties exist with correct types
+     * 2. **Name validation**: Ensures name is non-empty string
+     * 3. **Phone validation**: Validates phone number can be parsed and is valid
+     * 4. **MNO validation**: Country-specific validation:
+     *    - **MNP countries (KE)**: Validates MNO ID is valid for country
+     *    - **Non-MNP countries (TZ)**: Validates MNO matches phone number prefix
+     *
+     * @static
+     * @param {unknown} obj - The object to validate
+     * @returns {obj is MobileContactInfo} Type predicate indicating validity
+     *
+     * @example
+     * ```typescript
+     * const unknownData = JSON.parse(someJsonString);
+     *
+     * if (MobileContactInfo.is(unknownData)) {
+     *   // TypeScript now knows this is MobileContactInfo
+     *   console.log(unknownData.name); // ✅ Type-safe access
+     *   console.log(unknownData.phoneNumber.e164Format); // ✅ Type-safe
+     *   console.log(unknownData.mnoId); // ✅ Type-safe
+     * } else {
+     *   console.log("Invalid MobileContactInfo structure");
+     * }
+     *
+     * // Usage in arrays
+     * const contacts = jsonArray.filter(MobileContactInfo.is);
+     * // contacts is now typed as MobileContactInfo[]
+     * ```
+     *
+     * @remarks
+     * - Validates both serialized and live objects
+     * - Phone numbers can be provided as strings or PhoneNumber objects
+     * - Uses country-specific MNO validation through MNOUtils
+     * - Returns false for any validation failure (fail-fast approach)
+     */
+    static is(obj: unknown): obj is MobileContactInfo;
+    /**
+     * Validates that all contact information is consistent and correct.
+     * Uses country-specific validation logic through MNOUtils delegation.
+     *
+     * **Validation Checks:**
+     * 1. **Name validation**: Non-empty string
+     * 2. **Phone validation**: Valid phone number structure
+     * 3. **MNO validation**: Valid MNO for the country
+     * 4. **Consistency check**: For non-MNP countries, validates MNO matches phone prefix
+     *
+     * @returns {boolean} True if all validations pass, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const contact = new MobileContactInfo("John", phoneNumber, TZMNOId.VODACOM);
+     *
+     * if (contact.validate()) {
+     *   console.log("Contact is valid and ready to use");
+     * } else {
+     *   console.log("Contact has validation issues");
+     *   // Use getValidationDetails() for specific error information
+     * }
+     * ```
+     *
+     * @see {@link getValidationDetails} For detailed validation results with specific errors
+     */
+    /**
+     * Validates that all bank contact information meets banking industry standards.
+     * Uses comprehensive validation rules for account names, numbers, and bank data.
+     *
+     * **Validation Checks:**
+     * 1. **Account name**: Format, length, and character requirements
+     * 2. **Account number**: Country-specific format validation
+     * 3. **Bank data**: SWIFT code validity and institution data integrity
+     *
+     * @returns {boolean} True if all validations pass, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const contact = new BankContactInfo("John Doe", bank, "0150123456789");
+     *
+     * if (contact.validate()) {
+     *   console.log("Bank contact is ready for transactions");
+     * } else {
+     *   console.log("Bank contact has validation issues");
+     * }
+     * ```
+     *
+     * @remarks
+     * Uses BankValidation utility methods for industry-standard validation rules.
+     * All validation must pass for the contact to be considered valid.
+     */
+    validate(): boolean;
+    /**
+     * Provides detailed validation results with specific error and warning information.
+     * Uses country-specific validation logic for comprehensive analysis.
+     *
+     * **Validation Categories:**
+     * - **Errors**: Critical issues that make the contact invalid
+     * - **Warnings**: Potential issues that don't prevent usage but indicate inconsistencies
+     *
+     * @returns {Object} Detailed validation results
+     * @returns {boolean} returns.isValid - True if no errors found
+     * @returns {string[]} returns.errors - Array of error messages for critical issues
+     * @returns {string[]} returns.warnings - Array of warning messages for potential issues
+     *
+     * @example
+     * ```typescript
+     * const contact = new MobileContactInfo("John", phoneNumber, TZMNOId.AIRTEL);
+     * const validation = contact.getValidationDetails();
+     *
+     * console.log(`Valid: ${validation.isValid}`);
+     *
+     * if (validation.errors.length > 0) {
+     *   console.log("Errors found:");
+     *   validation.errors.forEach(error => console.log(`- ${error}`));
+     * }
+     *
+     * if (validation.warnings.length > 0) {
+     *   console.log("Warnings:");
+     *   validation.warnings.forEach(warning => console.log(`- ${warning}`));
+     * }
+     *
+     * // Example output for TZ number with wrong MNO:
+     * // Valid: false
+     * // Errors:
+     * // - Invalid MNO AIRTEL for country TZ
+     * // Warnings:
+     * // - MNO doesn't match phone number prefix - possible data inconsistency
+     * ```
+     *
+     * @remarks
+     * Uses MNOUtils for country-specific validation logic:
+     * - **Tanzania**: Validates MNO against phone number prefix
+     * - **Kenya**: Acknowledges MNP limitations, focuses on MNO validity
+     */
+    getValidationDetails(): {
+        isValid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    /**
+     * Gets the contact's personal name for display purposes.
+     *
+     * @override
+     * @returns {string} The contact's personal name
+     */
+    get accountName(): string;
+    /**
+     * Gets the phone number formatted for display and storage.
+     * Returns the number in international numeric format (without + prefix).
+     *
+     * @override
+     * @returns {string} Phone number in international numeric format (e.g., "255712345678")
+     *
+     * @example
+     * ```typescript
+     * const contact = new MobileContactInfo("John", phoneNumber);
+     * console.log(contact.accNumber); // "255712345678"
+     * ```
+     */
+    get accountNumber(): string;
+    /**
+     * Gets the localized label for the display name field.
+     *
+     * @override
+     * @returns {string} Always returns "Name" for mobile contacts
+     */
+    get accountNameLabel(): string;
+    /**
+     * Gets the localized label for the account number field.
+     *
+     * @override
+     * @returns {string} Always returns "Phone Number" for mobile contacts
+     */
+    get accountNumberLabel(): string;
+    /**
+     * Gets the localized label for the channel field.
+     *
+     * @override
+     * @returns {string} Always returns "Channel" for mobile contacts
+     */
+    get channelLabel(): string;
+    /**
+     * Gets the typed MNO identifier for this mobile contact.
+     * This is the programmatic identifier used for API calls and business logic.
+     *
+     * @returns {MNOId} The MNO identifier (e.g., "VODACOM", "SAFARICOM")
+     *
+     * @example
+     * ```typescript
+     * const contact = new MobileContactInfo("John", tzPhone, TZMNOId.VODACOM);
+     * console.log(contact.channel); // "VODACOM"
+     *
+     * // Type-safe usage
+     * if (contact.channel === TZMNOId.VODACOM) {
+     *   console.log("This is a Vodacom number");
+     * }
+     * ```
+     */
+    get channelId(): MNOId;
+    /**
+     * Gets the human-readable mobile money service name for display purposes.
+     * Uses MNOUtils to retrieve service information from country-specific implementations.
+     *
+     * **Behavior:**
+     * - Returns the mobile money service name (e.g., "M-Pesa", "Airtel Money")
+     * - Falls back to MNO display name if service name unavailable
+     * - Falls back to MNO ID if no display information available
+     *
+     * @returns {string} The mobile money service name for display
+     *
+     * @example
+     * ```typescript
+     * const vodacomContact = new MobileContactInfo("John", tzPhone, TZMNOId.VODACOM);
+     * console.log(vodacomContact.channelDisplayName); // "M-Pesa"
+     *
+     * const safaricomContact = new MobileContactInfo("Jane", kePhone, KEMNOId.SAFARICOM);
+     * console.log(safaricomContact.channelDisplayName); // "M-Pesa"
+     *
+     * const airtelContact = new MobileContactInfo("Bob", tzPhone, TZMNOId.AIRTEL);
+     * console.log(airtelContact.channelDisplayName); // "Airtel Money"
+     * ```
+     *
+     * @remarks
+     * Uses MNOUtils.getMNOById() which delegates to country-specific implementations
+     * for consistent and accurate service name retrieval.
+     */
+    get channelName(): string;
+}
+/**
+ * Implementation of BaseContactInfo for bank account contacts.
+ * Handles storage, validation, and display of contact details specific to bank transfers.
+ *
+ * This class provides comprehensive validation for bank account information including
+ * SWIFT code validation, account name verification, and account number format checking.
+ *
+ * **Key Features:**
+ * - SWIFT code validation per country regulations
+ * - Account name format validation
+ * - Account number format validation (country-specific rules)
+ * - Integration with Bank service for institution data
+ *
+ * @extends BaseContactInfo
+ * @class BankContactInfo
+ *
+ * @property {string} accName - The bank account holder's name
+ * @property {Bank} bank - The bank institution object with SWIFT code and details
+ * @property {string} accNo - The bank account number
+ *
+ * @example
+ * ```typescript
+ * // Create bank contact with validation
+ * const bank = Bank.from("CORUTZTZ", "TZ"); // CRDB Bank
+ * const contact = new BankContactInfo("John Doe", bank, "0150123456789");
+ *
+ * console.log(contact.channel); // "CORUTZTZ" (SWIFT code)
+ * console.log(contact.channelDisplayName); // "CRDB" (bank short name)
+ * console.log(contact.displayName); // "John Doe"
+ * console.log(contact.accNumber); // "0150123456789"
+ * ```
+ *
+ * @throws {ContactInfoError} When validation fails (invalid account name, number, or bank)
+ */
+export declare class BankContactInfo extends BaseContactInfo {
+    readonly accName: string;
+    readonly bank: Bank;
+    readonly accNo: string;
+    /**
+     * Creates a new bank contact with comprehensive validation.
+     *
+     * **Validation Process:**
+     * 1. **Account name validation**: Checks format and character requirements
+     * 2. **Account number validation**: Validates format per country banking rules
+     * 3. **Bank validation**: Ensures bank object is valid and contains required data
+     *
+     * @param {string} accName - The bank account holder's name (must pass BankValidation.validateAccountName)
+     * @param {Bank} bank - The bank institution object (must be valid Bank instance)
+     * @param {string} accNo - The bank account number (must pass country-specific validation)
+     *
+     * @throws {ContactInfoError} When validation fails:
+     * - Invalid account name format
+     * - Invalid account number format for the country
+     * - Invalid or missing bank information
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const bank = Bank.from("CORUTZTZ", "TZ");
+     *   const contact = new BankContactInfo("John Doe", bank, "0150123456789");
+     *   console.log("Bank contact created successfully");
+     * } catch (error) {
+     *   if (error instanceof ContactInfoError) {
+     *     console.log(`Validation failed: ${error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    constructor(accName: string, bank: Bank, accNo: string);
+    /**
+     * Creates a BankContactInfo instance from a ContactDTO object.
+     * Handles SWIFT code validation and bank lookup.
+     *
+     * **Process:**
+     * 1. Validates DTO type is "Bank"
+     * 2. Validates country code format
+     * 3. Validates SWIFT code format and existence
+     * 4. Looks up bank information using SWIFT code
+     * 5. Delegates to constructor for final validation
+     *
+     * @static
+     * @param {ContactDTO} info - The contact data transfer object
+     * @param {string} info.type - Must be "Bank"
+     * @param {string} info.channel - The SWIFT code for the bank
+     * @param {string} info.countryCode - ISO2 country code
+     * @param {string} info.displayName - The account holder's name
+     * @param {string} info.accountNo - The bank account number
+     *
+     * @returns {BankContactInfo | undefined} New instance if successful, undefined if validation fails
+     *
+     * @example
+     * ```typescript
+     * const contactDTO = {
+     *   type: "Bank",
+     *   channel: "CORUTZTZ", // CRDB Bank SWIFT code
+     *   countryCode: "TZ",
+     *   displayName: "John Doe",
+     *   accountNo: "0150123456789"
+     * };
+     *
+     * const contact = BankContactInfo.fromContactDTO(contactDTO);
+     * if (contact) {
+     *   console.log(`Created bank contact: ${contact.displayName} at ${contact.bank.shortName}`);
+     * }
+     * ```
+     */
+    static fromContactDTO(info: ContactDTO): BankContactInfo | undefined;
+    /**
+     * Creates a BankContactInfo instance from a PayoutDTO object.
+     * Parses bank information from the payout's msisdn field using "swiftcode:accountno" format.
+     *
+     * **Expected Format:** The msisdn field should contain "SWIFTCODE:ACCOUNTNUMBER"
+     *
+     * **Process:**
+     * 1. Validates country code format
+     * 2. Splits msisdn field on ":" delimiter
+     * 3. Validates SWIFT code format and existence
+     * 4. Looks up bank information
+     * 5. Creates contact with parsed information
+     *
+     * @static
+     * @param {PayoutDTO} info - The payout data transfer object
+     * @param {string} info.msisdn - Bank info in format "SWIFTCODE:ACCOUNTNUMBER"
+     * @param {string} info.countryCode - ISO2 country code
+     * @param {string} info.payeeName - The account holder's name
+     *
+     * @returns {BankContactInfo | undefined} New instance if successful, undefined if parsing fails
+     *
+     * @example
+     * ```typescript
+     * const payoutDTO = {
+     *   msisdn: "CORUTZTZ:0150123456789", // SWIFT:Account format
+     *   countryCode: "TZ",
+     *   payeeName: "Jane Smith"
+     * };
+     *
+     * const contact = BankContactInfo.fromPayoutDTO(payoutDTO);
+     * if (contact) {
+     *   console.log(`Payout to: ${contact.displayName}`);
+     *   console.log(`Bank: ${contact.bank.fullName}`);
+     *   console.log(`Account: ${contact.accNumber}`);
+     * }
+     * ```
+     *
+     * @remarks
+     * Returns undefined if:
+     * - msisdn doesn't contain exactly one ":" separator
+     * - SWIFT code is invalid for the country
+     * - Bank lookup fails
+     * - Any validation error occurs
+     */
+    static fromPayoutDTO(info: PayoutDTO): BankContactInfo | undefined;
+    /**
+     * Type guard to validate if an unknown object is a valid BankContactInfo instance.
+     * Performs comprehensive structural and business logic validation.
+     *
+     * **Validation Process:**
+     * 1. **Structural validation**: Checks required properties exist with correct types
+     * 2. **Account name validation**: Uses BankValidation.validateAccountName()
+     * 3. **Account number validation**: Uses country-specific BankValidation.validateAccountNumber()
+     * 4. **Bank validation**: Ensures bank object passes Bank.is() validation
+     *
+     * @static
+     * @param {unknown} obj - The object to validate
+     * @returns {obj is BankContactInfo} Type predicate indicating validity
+     *
+     * @example
+     * ```typescript
+     * const unknownData = JSON.parse(bankJsonString);
+     *
+     * if (BankContactInfo.is(unknownData)) {
+     *   // TypeScript now knows this is BankContactInfo
+     *   console.log(unknownData.accName); // ✅ Type-safe access
+     *   console.log(unknownData.bank.fullName); // ✅ Type-safe
+     *   console.log(unknownData.accNo); // ✅ Type-safe
+     * } else {
+     *   console.log("Invalid BankContactInfo structure");
+     * }
+     *
+     * // Usage in arrays
+     * const bankContacts = jsonArray.filter(BankContactInfo.is);
+     * // bankContacts is now typed as BankContactInfo[]
+     * ```
+     *
+     * @remarks
+     * - Validates both serialized and live objects
+     * - Uses banking industry validation rules through BankValidation
+     * - Ensures bank object contains valid SWIFT code and institution data
+     * - Returns false for any validation failure (fail-fast approach)
+     */
+    static is(obj: unknown): obj is BankContactInfo;
+    validate(): boolean;
+    /**
+     * Gets the bank account holder's name for display purposes.
+     *
+     * @override
+     * @returns {string} The account holder's name
+     */
+    get accountName(): string;
+    /**
+     * Gets the bank account number for display and processing.
+     *
+     * @override
+     * @returns {string} The bank account number as provided
+     */
+    get accountNumber(): string;
+    /**
+     * Gets the localized label for the display name field.
+     *
+     * @override
+     * @returns {string} Always returns "Acc. Name" for bank contacts
+     */
+    get accountNameLabel(): string;
+    /**
+     * Gets the localized label for the account number field.
+     *
+     * @override
+     * @returns {string} Always returns "Bank Acc. No." for bank contacts
+     */
+    get accountNumberLabel(): string;
+    /**
+     * Gets the localized label for the channel field.
+     *
+     * @override
+     * @returns {string} Always returns "Bank" for bank contacts
+     */
+    get channelLabel(): string;
+    /**
+     * Gets the bank's SWIFT code as the channel identifier.
+     * This is the programmatic identifier used for bank transfers and API calls.
+     *
+     * @returns {BankSwiftCode} The bank's SWIFT/BIC code (e.g., "CORUTZTZ", "KCBLKENX")
+     *
+     * @example
+     * ```typescript
+     * const contact = new BankContactInfo("John", crdBank, "123456789");
+     * console.log(contact.channel); // "CORUTZTZ"
+     *
+     * // Type-safe usage
+     * if (contact.channel === "CORUTZTZ") {
+     *   console.log("This is a CRDB Bank account");
+     * }
+     * ```
+     */
+    get channelId(): BankSwiftCode;
+    /**
+     * Gets the bank's short name for display purposes.
+     * Provides a human-readable identifier for the banking institution.
+     *
+     * @returns {string} The bank's abbreviated name (e.g., "CRDB", "KCB", "Equity")
+     *
+     * @example
+     * ```typescript
+     * const crdContact = new BankContactInfo("John", crdBank, "123456789");
+     * console.log(crdContact.channelDisplayName); // "CRDB"
+     *
+     * const kcbContact = new BankContactInfo("Jane", kcbBank, "987654321");
+     * console.log(kcbContact.channelDisplayName); // "KCB"
+     * ```
+     *
+     * @remarks
+     * The short name is maintained by the Bank service and represents
+     * the commonly used abbreviation for the banking institution.
+     */
+    get channelName(): string;
+}
+/**
+ * Union type representing either a mobile or bank contact.
+ * Used for type-safe handling of contact information throughout the application.
+ *
+ * This discriminated union allows for:
+ * - **Type-safe polymorphism**: Handle different contact types with single interface
+ * - **Runtime type discrimination**: Use `contact.type` to determine specific type
+ * - **Comprehensive validation**: Each type provides its own validation logic
+ * - **Consistent API**: Both types implement BaseContactInfo interface
+ *
+ * @typedef {MobileContactInfo | BankContactInfo} ContactInfo
+ *
+ * @example
+ * ```typescript
+ * // Type-safe handling of mixed contact types
+ * function processContact(contact: ContactInfo) {
+ *   console.log(`Processing ${contact.type} contact: ${contact.displayName}`);
+ *   console.log(`Channel: ${contact.channelDisplayName}`);
+ *
+ *   // Type discrimination for specific behavior
+ *   if (contact.type === "Mobile") {
+ *     // TypeScript knows this is MobileContactInfo
+ *     console.log(`MNO: ${contact.mnoId}`);
+ *     console.log(`Phone: ${contact.phoneNumber.e164Format}`);
+ *   } else {
+ *     // TypeScript knows this is BankContactInfo
+ *     console.log(`Bank: ${contact.bank.fullName}`);
+ *     console.log(`SWIFT: ${contact.bank.swiftCode}`);
+ *   }
+ * }
+ *
+ * // Usage with arrays
+ * const contacts: ContactInfo[] = [
+ *   new MobileContactInfo("John", phoneNumber, TZMNOId.VODACOM),
+ *   new BankContactInfo("Jane", bank, "123456789")
+ * ];
+ *
+ * contacts.forEach(processContact);
+ *
+ * // Type guards work seamlessly
+ * const mobileContacts = contacts.filter((c): c is MobileContactInfo => c.type === "Mobile");
+ * const bankContacts = contacts.filter((c): c is BankContactInfo => c.type === "Bank");
+ * ```
+ *
+ * @see {@link MobileContactInfo} For mobile money contact implementation
+ * @see {@link BankContactInfo} For bank transfer contact implementation
+ * @see {@link BaseContactInfo} For common interface and behavior
+ */
+export type ContactInfo = MobileContactInfo | BankContactInfo;
+export {};