@temboplus/afloat 0.1.63 → 0.1.64

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

@@ -125,7 +125,7 @@ declare abstract class BaseContactInfo {
  * - Comprehensive error handling with structured context
  *
  * **MNP Handling:**
- * - **Tanzania (no MNP)**: MNO can be auto-detected from phone number prefix
+ * - **Tanzania (no MNP)**: MNO is always auto-detected from phone number prefix, ignoring any provided MNO
  * - **Kenya (has MNP)**: MNO must be explicitly provided as numbers can be ported
  *
  * @extends BaseContactInfo
@@ -137,12 +137,13 @@ declare abstract class BaseContactInfo {
  *
  * @example
  * ```typescript
- * // Tanzania - MNO auto-detected from prefix
+ * // Tanzania - MNO auto-detected from prefix (ignores provided MNO)
  * 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);
+ * // Tanzania - Even with explicit MNO, it's auto-detected from prefix
+ * const tzExplicit = new MobileContactInfo("John Doe", tzPhoneNumber, TZMNOId.AIRTEL);
+ * console.log(tzExplicit.channel); // "VODACOM" (auto-detected, not AIRTEL)
  *
  * // Kenya - MNO must be explicit due to MNP
  * const keContact = new MobileContactInfo("Jane Smith", kePhoneNumber, KEMNOId.SAFARICOM);
@@ -165,26 +166,27 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * 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
+     *    - **Countries without MNP (TZ)**: Always auto-detects MNO from phone number prefix (ignores provided MNO)
      *
      * @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)
+     * @param {MNOId} [mnoId] - MNO ID. Required for MNP countries (KE), ignored for non-MNP countries (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)
+     * - Invalid MNO for the country (MNP countries only)
      * - Missing MNO for MNP countries
      * - Unable to auto-detect MNO for non-MNP countries
      *
      * @example
      * ```typescript
      * try {
-     *   // All these are valid
+     *   // Tanzania - MNO always auto-detected
      *   const tzAuto = new MobileContactInfo("John", tzPhone);
-     *   const tzExplicit = new MobileContactInfo("John", tzPhone, TZMNOId.VODACOM);
+     *   const tzIgnored = new MobileContactInfo("John", tzPhone, TZMNOId.AIRTEL); // AIRTEL ignored, auto-detected from prefix
+     *
+     *   // Kenya - MNO must be explicit
      *   const keExplicit = new MobileContactInfo("Jane", kePhone, KEMNOId.SAFARICOM);
      * } catch (error) {
      *   if (error instanceof ContactInfoError) {
@@ -202,7 +204,9 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * 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)
+     * 4. Handles MNO based on country MNP status:
+     *    - **MNP countries**: Uses channel field (required)
+     *    - **Non-MNP countries**: Auto-detects from phone number (ignores channel field)
      * 5. Delegates to constructor for final validation
      *
      * @static
@@ -211,24 +215,35 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * @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)
+     * @param {string} [info.channel] - MNO ID (required for MNP countries, ignored for non-MNP countries)
      *
      * @returns {MobileContactInfo | undefined} New instance if successful, undefined if validation fails
      *
      * @example
      * ```typescript
-     * const contactDTO = {
+     * // Tanzania DTO - channel ignored, auto-detected from phone number
+     * const tzContactDTO = {
      *   type: "Mobile",
-     *   accountNo: "+255712345678",
+     *   accountNo: "+255712345678", // Vodacom prefix
      *   countryCode: "TZ",
      *   displayName: "John Doe",
-     *   channel: "VODACOM" // Optional for TZ, required for KE
+     *   channel: "AIRTEL" // This will be ignored, Vodacom will be auto-detected
      * };
      *
-     * const contact = MobileContactInfo.fromContactDTO(contactDTO);
-     * if (contact) {
-     *   console.log(`Created contact: ${contact.displayName}`);
-     * }
+     * // Kenya DTO - channel required
+     * const keContactDTO = {
+     *   type: "Mobile",
+     *   accountNo: "+254712345678",
+     *   countryCode: "KE",
+     *   displayName: "Jane Smith",
+     *   channel: "SAFARICOM" // Required for Kenya
+     * };
+     *
+     * const tzContact = MobileContactInfo.fromContactDTO(tzContactDTO);
+     * console.log(tzContact?.channelId); // "VODACOM" (not "AIRTEL")
+     *
+     * const keContact = MobileContactInfo.fromContactDTO(keContactDTO);
+     * console.log(keContact?.channelId); // "SAFARICOM"
      * ```
      */
     static fromContactDTO(info: ContactDTO): MobileContactInfo | undefined;
@@ -239,7 +254,9 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * **Process:**
      * 1. Validates country code format
      * 2. Parses phone number from msisdn field
-     * 3. Extracts MNO from channel field (if available)
+     * 3. Handles MNO based on country MNP status:
+     *    - **MNP countries**: Uses channel field (required)
+     *    - **Non-MNP countries**: Auto-detects from phone number (ignores channel field)
      * 4. Uses payeeName as the contact name
      * 5. Delegates to constructor for validation
      *
@@ -248,23 +265,30 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * @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
+     * @param {string} [info.channel] - MNO ID (required for MNP countries, ignored for non-MNP countries)
      *
      * @returns {MobileContactInfo | undefined} New instance if successful, undefined if parsing fails
      *
      * @example
      * ```typescript
-     * const payoutDTO = {
+     * // Tanzania payout - channel ignored
+     * const tzPayoutDTO = {
+     *   msisdn: "+255712345678", // Vodacom prefix
+     *   countryCode: "TZ",
+     *   payeeName: "John Doe",
+     *   channel: "AIRTEL" // Ignored, Vodacom auto-detected
+     * };
+     *
+     * // Kenya payout - channel required
+     * const kePayoutDTO = {
      *   msisdn: "+254712345678",
      *   countryCode: "KE",
      *   payeeName: "Jane Smith",
-     *   channel: "SAFARICOM"
+     *   channel: "SAFARICOM" // Required
      * };
      *
-     * const contact = MobileContactInfo.fromPayoutDTO(payoutDTO);
-     * if (contact) {
-     *   console.log(`Payout contact: ${contact.displayName} via ${contact.channelDisplayName}`);
-     * }
+     * const tzContact = MobileContactInfo.fromPayoutDTO(tzPayoutDTO);
+     * console.log(tzContact?.channelName); // "M-Pesa" (Vodacom's service)
      * ```
      */
     static fromPayoutDTO(info: PayoutDTO): MobileContactInfo | undefined;
@@ -278,7 +302,7 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * 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
+     *    - **Non-MNP countries (TZ)**: Validates MNO matches phone number prefix (auto-detected)
      *
      * @static
      * @param {unknown} obj - The object to validate
@@ -307,6 +331,7 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * - 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)
+     * - For non-MNP countries, validates that the MNO matches what would be auto-detected
      */
     static is(obj: unknown): obj is MobileContactInfo;
     /**
@@ -317,7 +342,7 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * 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
+     * 4. **Consistency check**: For non-MNP countries, validates MNO matches auto-detected value from phone prefix
      *
      * @returns {boolean} True if all validations pass, false otherwise
      *
@@ -335,32 +360,6 @@ export declare class MobileContactInfo extends BaseContactInfo {
      *
      * @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.
@@ -377,7 +376,7 @@ export declare class MobileContactInfo extends BaseContactInfo {
      *
      * @example
      * ```typescript
-     * const contact = new MobileContactInfo("John", phoneNumber, TZMNOId.AIRTEL);
+     * const contact = new MobileContactInfo("John", phoneNumber);
      * const validation = contact.getValidationDetails();
      *
      * console.log(`Valid: ${validation.isValid}`);
@@ -392,18 +391,14 @@ export declare class MobileContactInfo extends BaseContactInfo {
      *   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
+     * // For non-MNP countries, the MNO is always consistent as it's auto-detected
+     * // Warnings would only appear if there were other potential issues
      * ```
      *
      * @remarks
      * Uses MNOUtils for country-specific validation logic:
-     * - **Tanzania**: Validates MNO against phone number prefix
-     * - **Kenya**: Acknowledges MNP limitations, focuses on MNO validity
+     * - **Tanzania**: Validates MNO matches auto-detected value from phone number prefix
+     * - **Kenya**: Acknowledges MNP limitations, focuses on MNO validity for country
      */
     getValidationDetails(): {
         isValid: boolean;
@@ -461,12 +456,11 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * @example
      * ```typescript
      * const contact = new MobileContactInfo("John", tzPhone, TZMNOId.VODACOM);
-     * console.log(contact.channel); // "VODACOM"
+     * console.log(contact.channel); // "VODACOM" (for MNP countries)
      *
-     * // Type-safe usage
-     * if (contact.channel === TZMNOId.VODACOM) {
-     *   console.log("This is a Vodacom number");
-     * }
+     * // For non-MNP countries, always returns auto-detected value
+     * const contact2 = new MobileContactInfo("John", tzPhone, TZMNOId.AIRTEL); // AIRTEL ignored
+     * console.log(contact2.channel); // "VODACOM" (auto-detected from phone prefix)
      * ```
      */
     get channelId(): MNOId;
@@ -478,6 +472,7 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * - 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
+     * - For non-MNP countries, always reflects the auto-detected MNO service
      *
      * @returns {string} The mobile money service name for display
      *
@@ -489,8 +484,9 @@ export declare class MobileContactInfo extends BaseContactInfo {
      * 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"
+     * // For non-MNP countries, shows auto-detected service regardless of provided MNO
+     * const tzContact = new MobileContactInfo("Bob", tzVodacomPhone, TZMNOId.AIRTEL); // AIRTEL ignored
+     * console.log(tzContact.channelDisplayName); // "M-Pesa" (Vodacom's service, auto-detected)
      * ```
      *
      * @remarks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temboplus/afloat",
-  "version": "0.1.63",
+  "version": "0.1.64",
   "description": "A foundational library for Temboplus-Afloat projects.",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",