@temboplus/afloat 0.2.0-beta.7 → 0.2.0-beta.9

package/dist/modules/beneficiary/beneficiary-info.model.d.ts

@@ -1,9 +1,9 @@
 import { BeneficiaryType, BeneficiaryDTO } from "@/modules/beneficiary/beneficiary.dtos.js";
 import { PayoutDTO } from "@/modules/payout/payout.dtos.js";
-import { Bank, ISO2CountryCode, PhoneNumber } from "@temboplus/frontend-core";
-import type { BankSwiftCode, MNOId } from "@temboplus/frontend-core";
+import { Bank, PhoneNumber } from "@temboplus/frontend-core";
+import type { BankSwiftCode, ISO2CountryCode, MobileMoneyProviderId } from "@temboplus/frontend-core";
 import { z } from "zod";
-export declare const MobileBeneficiaryInfoJSONSchema: z.ZodObject<{
+export declare const MobileBeneficiaryJSONSchema: z.ZodObject<{
     type: z.ZodLiteral<"Mobile">;
     name: z.ZodString;
     phoneNumber: z.ZodString;
@@ -22,7 +22,7 @@ export declare const MobileBeneficiaryInfoJSONSchema: z.ZodObject<{
     mnoId: string;
     version?: string | undefined;
 }>;
-export declare const BankBeneficiaryInfoJSONSchema: z.ZodObject<{
+export declare const BankBeneficiaryJSONSchema: z.ZodObject<{
     type: z.ZodLiteral<"Bank">;
     accName: z.ZodString;
     swiftCode: z.ZodString;
@@ -44,7 +44,7 @@ export declare const BankBeneficiaryInfoJSONSchema: z.ZodObject<{
     accNo: string;
     version?: string | undefined;
 }>;
-export declare const BeneficiaryInfoJSONSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+export declare const BeneficiaryJSONSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"Mobile">;
     name: z.ZodString;
     phoneNumber: z.ZodString;
@@ -84,17 +84,33 @@ export declare const BeneficiaryInfoJSONSchema: z.ZodDiscriminatedUnion<"type",
     accNo: string;
     version?: string | undefined;
 }>]>;
-export type MobileBeneficiaryInfoJSON = z.infer<typeof MobileBeneficiaryInfoJSONSchema>;
-export type BankBeneficiaryInfoJSON = z.infer<typeof BankBeneficiaryInfoJSONSchema>;
-export type BeneficiaryInfoJSON = z.infer<typeof BeneficiaryInfoJSONSchema>;
-/**
- * Abstract base class for beneficiary information.
- */
-declare abstract class BaseBeneficiaryInfo {
+export type MobileBeneficiaryJSON = z.infer<typeof MobileBeneficiaryJSONSchema>;
+export type BankBeneficiaryJSON = z.infer<typeof BankBeneficiaryJSONSchema>;
+export type BeneficiaryJSON = z.infer<typeof BeneficiaryJSONSchema>;
+export declare class BeneficiaryError extends Error {
+    readonly context: {
+        phoneNumber?: string;
+        countryCode?: ISO2CountryCode;
+        mnoId?: string;
+        operation?: string;
+    };
+    constructor(message: string, context?: {
+        phoneNumber?: string;
+        countryCode?: ISO2CountryCode;
+        mnoId?: string;
+        operation?: string;
+    });
+}
+interface ValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+declare abstract class BaseBeneficiary {
     readonly type: BeneficiaryType;
     readonly countryCode: ISO2CountryCode;
-    constructor(type: BeneficiaryType, countryCode: ISO2CountryCode);
-    abstract get channelId(): MNOId | BankSwiftCode;
+    protected constructor(type: BeneficiaryType, countryCode: ISO2CountryCode);
+    abstract get channelId(): MobileMoneyProviderId | BankSwiftCode;
     abstract get channelName(): string;
     abstract get accountName(): string;
     abstract get accountNumber(): string;
@@ -102,54 +118,67 @@ declare abstract class BaseBeneficiaryInfo {
     abstract get accountNumberLabel(): string;
     abstract get channelLabel(): string;
     abstract validate(): boolean;
-    abstract toJSON(): BeneficiaryInfoJSON;
+    abstract getValidationDetails(): ValidationResult;
+    abstract toJSON(): BeneficiaryJSON;
     toJSONString(): string;
     get isMobile(): boolean;
     get isBank(): boolean;
     get displayName(): string;
 }
-/**
- * Mobile beneficiary information implementation.
- */
-export declare class MobileBeneficiaryInfo extends BaseBeneficiaryInfo {
+export declare class MobileBeneficiaryInfo extends BaseBeneficiary {
     readonly name: string;
     readonly phoneNumber: PhoneNumber;
-    readonly mnoId: MNOId;
-    constructor(name: string, phoneNumber: PhoneNumber, mnoId?: MNOId);
+    readonly mnoId: MobileMoneyProviderId;
+    constructor(name: string, phoneNumber: PhoneNumber, mnoId?: MobileMoneyProviderId);
+    /**
+     * For prefix-detectable countries the MNO is always derived from the phone,
+     * so any caller-supplied id is intentionally ignored. For explicit-only
+     * countries, the supplied id is used as-is (validation happens later).
+     */
+    private static resolveMnoId;
+    /**
+     * Single source of truth for input validity. Used by the constructor,
+     * validate(), and getValidationDetails().
+     */
+    private static checkInputs;
+    /** Picks an MNO from a DTO `channel` field, or auto-detects when supported. */
+    private static pickMnoIdFromDTO;
     static from(data: {
         name: string;
         phoneNumber: PhoneNumber;
-        mnoId?: MNOId;
+        mnoId?: MobileMoneyProviderId;
     }): MobileBeneficiaryInfo | undefined;
     static fromBeneficiaryDTO(info: BeneficiaryDTO): MobileBeneficiaryInfo | undefined;
     static fromPayoutDTO(info: PayoutDTO): MobileBeneficiaryInfo | undefined;
+    /**
+     * Pure runtime brand check — no rebuilding, no coercion. Use `fromJSON` to
+     * upgrade raw JSON shape into an instance.
+     */
     static is(obj: unknown): obj is MobileBeneficiaryInfo;
     validate(): boolean;
-    getValidationDetails(): {
-        isValid: boolean;
-        errors: string[];
-        warnings: string[];
-    };
+    getValidationDetails(): ValidationResult;
     get accountName(): string;
     get accountNumber(): string;
     get accountNameLabel(): string;
     get accountNumberLabel(): string;
     get channelLabel(): string;
-    get channelId(): MNOId;
+    get channelId(): MobileMoneyProviderId;
     get channelName(): string;
-    toJSON(): MobileBeneficiaryInfoJSON;
-    static fromJSON(json: MobileBeneficiaryInfoJSON | string): MobileBeneficiaryInfo | undefined;
-    static fromJSONString(jsonString: string): MobileBeneficiaryInfo | undefined;
-    static isMobileBeneficiaryInfoJSON(obj: unknown): obj is MobileBeneficiaryInfoJSON;
+    toJSON(): MobileBeneficiaryJSON;
+    static fromJSON(json: MobileBeneficiaryJSON | string): MobileBeneficiaryInfo | undefined;
+    static fromJSONString(s: string): MobileBeneficiaryInfo | undefined;
+    static isJSON(obj: unknown): obj is MobileBeneficiaryJSON;
 }
-/**
- * Bank beneficiary information implementation.
- */
-export declare class BankBeneficiaryInfo extends BaseBeneficiaryInfo {
+export declare class BankBeneficiaryInfo extends BaseBeneficiary {
     readonly accName: string;
     readonly bank: Bank;
     readonly accNo: string;
     constructor(accName: string, bank: Bank, accNo: string);
+    /**
+     * Single source of truth for input validity. Used by the constructor,
+     * validate(), and getValidationDetails().
+     */
+    private static checkInputs;
     static from(data: {
         accName: string;
         bank: Bank;
@@ -159,6 +188,7 @@ export declare class BankBeneficiaryInfo extends BaseBeneficiaryInfo {
     static fromPayoutDTO(info: PayoutDTO): BankBeneficiaryInfo | undefined;
     static is(obj: unknown): obj is BankBeneficiaryInfo;
     validate(): boolean;
+    getValidationDetails(): ValidationResult;
     get accountName(): string;
     get accountNumber(): string;
     get accountNameLabel(): string;
@@ -166,13 +196,22 @@ export declare class BankBeneficiaryInfo extends BaseBeneficiaryInfo {
     get channelLabel(): string;
     get channelId(): BankSwiftCode;
     get channelName(): string;
-    toJSON(): BankBeneficiaryInfoJSON;
-    static fromJSON(json: BankBeneficiaryInfoJSON | string): BankBeneficiaryInfo | undefined;
-    static fromJSONString(jsonString: string): BankBeneficiaryInfo | undefined;
-    static isBankBeneficiaryInfoJSON(obj: unknown): obj is BankBeneficiaryInfoJSON;
+    toJSON(): BankBeneficiaryJSON;
+    static fromJSON(json: BankBeneficiaryJSON | string): BankBeneficiaryInfo | undefined;
+    static fromJSONString(s: string): BankBeneficiaryInfo | undefined;
+    static isJSON(obj: unknown): obj is BankBeneficiaryJSON;
 }
+export type BeneficiaryInfo = MobileBeneficiaryInfo | BankBeneficiaryInfo;
 /**
- * Union type representing either a mobile or bank beneficiary.
+ * Top-level entry point for building / recognizing a beneficiary without
+ * caring about the variant. Each method dispatches on the discriminator.
  */
-export type BeneficiaryInfo = MobileBeneficiaryInfo | BankBeneficiaryInfo;
+export declare const BeneficiaryInfo: {
+    fromBeneficiaryDTO(info: BeneficiaryDTO): BeneficiaryInfo | undefined;
+    fromPayoutDTO(info: PayoutDTO): BeneficiaryInfo | undefined;
+    fromJSON(json: BeneficiaryJSON | string): BeneficiaryInfo | undefined;
+    fromJSONString(s: string): BeneficiaryInfo | undefined;
+    is(obj: unknown): obj is BeneficiaryInfo;
+    isJSON(obj: unknown): obj is BeneficiaryJSON;
+};
 export {};

package/dist/modules/beneficiary/beneficiary.model.d.ts

@@ -93,6 +93,8 @@ export type BeneficiaryJSON = z.infer<typeof BeneficiaryJSONSchema>;
  */
 export declare class Beneficiary {
     private readonly data;
+    private _info;
+    private _infoComputed;
     /**
      * Private constructor - use static factory methods to create instances.
      *
@@ -148,6 +150,9 @@ export declare class Beneficiary {
      * @remarks
      * For mobile beneficiaries, constructs from phone number.
      * For bank beneficiaries, constructs from SWIFT code and account number.
+     *
+     * Result is memoised — repeated accesses don't re-parse the phone number or
+     * re-resolve the bank.
      */
     get info(): BeneficiaryInfo | undefined;
     /**
@@ -275,7 +280,7 @@ export declare class Beneficiary {
      *
      * @static
      * @param {unknown} obj - The value containing potential beneficiary data
-     * @returns {obj is Beneficiary} Type predicate indicating if a Beneficiary can be constructed
+     * @returns {obj is BeneficiaryDTO} Type predicate indicating the value is a valid BeneficiaryDTO
      *
      * @example
      * ```typescript
@@ -288,8 +293,12 @@ export declare class Beneficiary {
      *
      * @remarks
      * This method performs strict validation against the {@link BeneficiaryDTO} schema.
+     *
+     * The predicate narrows to {@link BeneficiaryDTO} (not `Beneficiary`) — what
+     * `obj` actually is on success — so callers don't accidentally try to use
+     * instance methods like `toJSON()` on a raw DTO.
      */
-    static canConstruct(obj: unknown): obj is Beneficiary;
+    static canConstruct(obj: unknown): obj is BeneficiaryDTO;
     /**
      * Validates if an unknown value is a Beneficiary instance.
      * This is a runtime type guard that ensures proper object structure and data validity.

package/dist/modules/payout/payout-channel-handler.d.ts

@@ -1,5 +1,6 @@
 import { Wallet } from "@/modules/wallet/wallet.model.js";
-import { Amount, MNOId, PhoneNumber } from "@temboplus/frontend-core";
+import { Amount, PhoneNumber } from "@temboplus/frontend-core";
+import type { ISO2CountryCode, MobileMoneyProviderId } from "@temboplus/frontend-core";
 import { PayoutChannel, PayoutInputDTO } from "./payout.dtos.js";
 import { BankBeneficiaryInfo, BeneficiaryInfo } from "../beneficiary/beneficiary-info.model.js";
 /**
@@ -11,17 +12,17 @@ import { BankBeneficiaryInfo, BeneficiaryInfo } from "../beneficiary/beneficiary
  *
  * @see {@link PayoutChannelCodeFactory} for functions to generate valid codes
  */
-export type PayoutChannelCode = `${string}-BANK-B2C` | `${string}-${string}-B2C`;
+export type PayoutChannelCode = `${ISO2CountryCode}-${string}-B2C`;
 /**
  * Factory for creating standardized payout channel codes
  *
  * @example
  * ```ts
  * // Create bank channel code
- * const bankCode = PayoutChannelCodeFactory.forBank(bankContactInfo); // Returns "TZ-BANK-B2C"
+ * const bankCode = PayoutChannelCodeFactory.forBank(bankContactInfo, wallet); // Returns "TZ-BANK-B2C"
  *
  * // Create mobile channel code
- * const mobileCode = PayoutChannelCodeFactory.forMobile(phoneNumber); // Returns "TZ-VODACOM-B2C" for Vodacom number
+ * const mobileCode = PayoutChannelCodeFactory.forMobile(phoneNumber, mnoId, wallet); // Returns "TZ-VODACOM-B2C" for Vodacom number
  * ```
  */
 declare class PayoutChannelCodeFactory {
@@ -39,7 +40,7 @@ declare class PayoutChannelCodeFactory {
      *
      * @see {@link PhoneNumber} from "@temboplus/frontend-core" for phone number structure
      */
-    static forMobile(phoneNumber: PhoneNumber, mnoId: MNOId, wallet: Wallet): PayoutChannelCode;
+    static forMobile(phoneNumber: PhoneNumber, mnoId: MobileMoneyProviderId, wallet: Wallet): PayoutChannelCode;
 }
 /**
  * Factory class for creating payout input DTOs based on channel and contact information
@@ -52,7 +53,7 @@ declare class PayoutChannelCodeFactory {
  *   receiver: mobileContactInfo,
  *   amount: new Amount(1000),
  *   notes: "Payment for services"
- * });
+ * }, wallet);
  * ```
  */
 export declare class PayoutInputFactory {

package/dist/modules/wallet/narration.model.d.ts

@@ -199,8 +199,8 @@ export declare class Narration {
      */
     static is(obj: unknown): obj is Narration;
     /**
-   * Serializes the Narration instance to a JSON-compatible object
-   */
+     * Serializes the Narration instance to a JSON-compatible object
+     */
     toJSON(): NarrationJSON;
     /**
      * Serializes the Narration instance to a JSON string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temboplus/afloat",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.9",
   "description": "A foundational library for Temboplus-Afloat projects.",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",
@@ -58,6 +58,6 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@temboplus/frontend-core": "^0.3.0-beta.1"
+    "@temboplus/frontend-core": "^1.0.1-beta.2"
   }
 }