@temboplus/afloat 0.2.1-beta.2 → 0.2.1-beta.3

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

@@ -5,40 +5,40 @@ import { Bank, PhoneNumber } from "@temboplus/frontend-core";
 import type { BankSwiftCode, ISO2CountryCode, MobileMoneyProvider, MobileMoneyProviderId } from "@temboplus/frontend-core";
 import { z } from "zod";
 export declare const MobileBeneficiaryJSONSchema: z.ZodObject<{
-    type: z.ZodLiteral<BeneficiaryType.Mobile>;
+    type: z.ZodLiteral<BeneficiaryType.MOBILE>;
     name: z.ZodString;
     phoneNumber: z.ZodString;
     mnoId: z.ZodUnion<[z.ZodEnum<["VODACOM", "AIRTEL", "TIGO", "HALOTEL"]>, z.ZodEnum<["SAFARICOM"]>]>;
     _version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
-    type: BeneficiaryType.Mobile;
+    type: BeneficiaryType.MOBILE;
     name: string;
     _version: string;
     phoneNumber: string;
     mnoId: "VODACOM" | "AIRTEL" | "TIGO" | "HALOTEL" | "SAFARICOM";
 }, {
-    type: BeneficiaryType.Mobile;
+    type: BeneficiaryType.MOBILE;
     name: string;
     phoneNumber: string;
     mnoId: "VODACOM" | "AIRTEL" | "TIGO" | "HALOTEL" | "SAFARICOM";
     _version?: string | undefined;
 }>;
 export declare const BankBeneficiaryJSONSchema: z.ZodObject<{
-    type: z.ZodLiteral<BeneficiaryType.Bank>;
+    type: z.ZodLiteral<BeneficiaryType.BANK>;
     accName: z.ZodString;
     swiftCode: z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodEffects<z.ZodString, string, string>]>;
     countryCode: z.ZodEffects<z.ZodString, string, string>;
     accNo: z.ZodString;
     _version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
-    type: BeneficiaryType.Bank;
+    type: BeneficiaryType.BANK;
     _version: string;
     countryCode: string;
     accName: string;
     swiftCode: string;
     accNo: string;
 }, {
-    type: BeneficiaryType.Bank;
+    type: BeneficiaryType.BANK;
     countryCode: string;
     accName: string;
     swiftCode: string;
@@ -46,39 +46,39 @@ export declare const BankBeneficiaryJSONSchema: z.ZodObject<{
     _version?: string | undefined;
 }>;
 export declare const BeneficiaryJSONSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-    type: z.ZodLiteral<BeneficiaryType.Mobile>;
+    type: z.ZodLiteral<BeneficiaryType.MOBILE>;
     name: z.ZodString;
     phoneNumber: z.ZodString;
     mnoId: z.ZodUnion<[z.ZodEnum<["VODACOM", "AIRTEL", "TIGO", "HALOTEL"]>, z.ZodEnum<["SAFARICOM"]>]>;
     _version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
-    type: BeneficiaryType.Mobile;
+    type: BeneficiaryType.MOBILE;
     name: string;
     _version: string;
     phoneNumber: string;
     mnoId: "VODACOM" | "AIRTEL" | "TIGO" | "HALOTEL" | "SAFARICOM";
 }, {
-    type: BeneficiaryType.Mobile;
+    type: BeneficiaryType.MOBILE;
     name: string;
     phoneNumber: string;
     mnoId: "VODACOM" | "AIRTEL" | "TIGO" | "HALOTEL" | "SAFARICOM";
     _version?: string | undefined;
 }>, z.ZodObject<{
-    type: z.ZodLiteral<BeneficiaryType.Bank>;
+    type: z.ZodLiteral<BeneficiaryType.BANK>;
     accName: z.ZodString;
     swiftCode: z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodEffects<z.ZodString, string, string>]>;
     countryCode: z.ZodEffects<z.ZodString, string, string>;
     accNo: z.ZodString;
     _version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
-    type: BeneficiaryType.Bank;
+    type: BeneficiaryType.BANK;
     _version: string;
     countryCode: string;
     accName: string;
     swiftCode: string;
     accNo: string;
 }, {
-    type: BeneficiaryType.Bank;
+    type: BeneficiaryType.BANK;
     countryCode: string;
     accName: string;
     swiftCode: string;
@@ -145,6 +145,14 @@ export declare class MobileBeneficiaryInfo extends BaseBeneficiary {
     private static checkInputs;
     /** Picks an MNO from a DTO `channel` field, or auto-detects when supported. */
     private static pickMnoIdFromDTO;
+    /**
+     * Extracts a mobile provider id from an upstream payout channel code.
+     *
+     * @param countryCode - Beneficiary phone country code.
+     * @param channel - Candidate channel value from a beneficiary or payout DTO.
+     * @returns The provider id encoded in a mobile B2C channel, or `undefined` when the value is not a mobile channel.
+     */
+    private static pickMnoIdFromPayoutChannel;
     static from(data: {
         name: string;
         phoneNumber: PhoneNumber;

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

@@ -4,14 +4,14 @@ import { z } from "zod";
  *
  * @remarks
  * Currently supports two channel types:
- * - "Bank": For traditional banking channels
- * - "Mobile": For mobile money channels
+ * - "Bank": For traditional banking beneficiaries
+ * - "Mobile": For mobile money beneficiaries
  *
  * @see {@link BeneficiaryType} for the inferred type
  */
 export declare enum BeneficiaryType {
-    Bank = "Bank",
-    Mobile = "Mobile"
+    BANK = "Bank",
+    MOBILE = "Mobile"
 }
 /**
  * Type representing user-provided beneficiary information.

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

@@ -108,7 +108,7 @@ export declare class Beneficiary {
      */
     get displayName(): string;
     /**
-     * Type of beneficiary (Bank or Mobile).
+     * Type of beneficiary (`Bank` or `Mobile` on the wire).
      *
      * @returns {BeneficiaryType} The beneficiary type
      */

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

@@ -1,83 +1,149 @@
 import { Wallet } from "@/modules/wallet/wallet.model.js";
-import { Amount, PhoneNumber } from "@temboplus/frontend-core";
+import { Amount, ChannelType, 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";
+export type PayoutChannelCode = PayoutChannel;
 /**
- * Valid payout channel codes that can be used in the system
+ * Resolves the upstream payout channel owned by the library.
  *
- * @remarks
- * - `${countryCode}-BANK-B2C`: Code for bank transfers
- * - `${countryCode}-${telecom}-B2C`: Pattern for mobile money transfers where the telecom company is the provider code
- *
- * @see {@link PayoutChannelCodeFactory} for functions to generate valid codes
- */
-export type PayoutChannelCode = `${ISO2CountryCode}-${string}-B2C`;
-/**
- * Factory for creating standardized payout channel codes
- *
- * @example
- * ```ts
- * // Create bank channel code
- * const bankCode = PayoutChannelCodeFactory.forBank(bankContactInfo, wallet); // Returns "TZ-BANK-B2C"
- *
- * // Create mobile channel code
- * const mobileCode = PayoutChannelCodeFactory.forMobile(phoneNumber, mnoId, wallet); // Returns "TZ-VODACOM-B2C" for Vodacom number
- * ```
+ * Consumers provide wallet, beneficiary, and amount details only. This resolver
+ * applies Tembo routing rules and returns the concrete upstream B2C channel.
  */
-declare class PayoutChannelCodeFactory {
+export declare class PayoutChannelResolver {
+    /**
+     * Resolves the upstream payout channel for a payout.
+     *
+     * @param args - Payout routing inputs.
+     * @param args.wallet - Wallet paying out; its country and currency define the corridor.
+     * @param args.receiver - Beneficiary receiving the payout.
+     * @param args.amount - Amount being paid out; its currency must match the wallet/country.
+     * @returns The concrete upstream channel code to send to the payout API.
+     * @throws Error when wallet, receiver, amount, or supported-country details are incompatible.
+     */
+    static resolve(args: {
+        wallet: Wallet;
+        receiver: BeneficiaryInfo;
+        amount: Amount;
+    }): PayoutChannel;
+    /**
+     * Resolves a bank beneficiary to the upstream bank payout channel.
+     *
+     * @param receiver - Valid bank beneficiary details containing bank and account information.
+     * @param wallet - Wallet paying out; its country must match the beneficiary country.
+     * @returns `TZ-BANK-B2C` or `KE-BANK-B2C`.
+     * @throws Error when the beneficiary is invalid, unsupported, or in a different country from the wallet.
+     */
+    static forBank(receiver: BankBeneficiaryInfo, wallet: Wallet): PayoutChannel;
+    /**
+     * Resolves a mobile money beneficiary to the upstream mobile payout channel.
+     *
+     * Routing rules:
+     * - All Kenya mobile money payouts route through `KE-SAFARICOM-B2C`.
+     * - Tanzania Vodacom mobile numbers route through `TZ-TIGO-B2C`.
+     * - Tanzania Tigo, Airtel, and Halotel route through their matching upstream channels.
+     *
+     * @param phoneNumber - Parsed mobile beneficiary phone number.
+     * @param mnoId - Beneficiary mobile money provider id.
+     * @param wallet - Wallet paying out; its country must match the phone number country.
+     * @returns The concrete upstream mobile money payout channel.
+     * @throws Error when the phone, provider, country, or wallet corridor is invalid or unsupported.
+     */
+    static forMobile(phoneNumber: PhoneNumber, mnoId: MobileMoneyProviderId, wallet: Wallet): PayoutChannel;
+    /**
+     * Converts a concrete payout channel into the generic coverage channel type.
+     *
+     * @param channel - Concrete upstream payout channel.
+     * @returns `ChannelType.BANK` for bank channels; otherwise `ChannelType.MOBILE_MONEY`.
+     */
+    static getChannelType(channel: PayoutChannel): ChannelType;
+    /**
+     * Extracts the country code prefix from a payout channel.
+     *
+     * @param channel - Concrete upstream payout channel.
+     * @returns ISO-2 country code embedded in the channel.
+     */
+    static getCountryCode(channel: PayoutChannel): ISO2CountryCode;
+    /**
+     * Extracts the mobile provider segment from a mobile payout channel.
+     *
+     * @param channel - Concrete upstream payout channel.
+     * @returns Provider id for mobile money channels; `undefined` for bank channels.
+     */
+    static getProviderId(channel: PayoutChannel): MobileMoneyProviderId | undefined;
+    /**
+     * Checks whether a concrete payout channel is a bank channel.
+     *
+     * @param channel - Concrete upstream payout channel.
+     * @returns `true` for `*-BANK-B2C` channels; otherwise `false`.
+     */
+    static isBankChannel(channel: PayoutChannel): boolean;
     /**
-     * Creates a bank transfer channel code
-     * @param contactInfo - Bank contact information
-     * @throws {Error} If country is not supported
+     * Checks whether a concrete payout channel is a mobile money channel.
+     *
+     * @param channel - Concrete upstream payout channel.
+     * @returns `true` for mobile money channels; otherwise `false`.
      */
-    static forBank(contactInfo: BankBeneficiaryInfo, wallet: Wallet): PayoutChannelCode;
+    static isMobileMoneyChannel(channel: PayoutChannel): boolean;
     /**
-     * Creates a mobile money channel code based on the telecom provider
-     * @param phoneNumber - Phone number object containing telecom information
-     * @returns {PayoutChannelCode} Channel code in format "TZ-{TELECOM}-B2C"
-     * @throws {Error} If phone number is invalid or country is not supported
+     * Ensures the payout is internally consistent before resolving a channel.
      *
-     * @see {@link PhoneNumber} from "@temboplus/frontend-core" for phone number structure
+     * @param wallet - Wallet paying out.
+     * @param receiver - Beneficiary receiving the payout.
+     * @param amount - Amount being paid out.
+     * @returns Nothing when validation passes.
+     * @throws Error when wallet country, receiver country, wallet currency, or amount currency do not align.
      */
-    static forMobile(phoneNumber: PhoneNumber, mnoId: MobileMoneyProviderId, wallet: Wallet): PayoutChannelCode;
+    private static assertCompatibleWalletReceiverAndAmount;
 }
 /**
- * Factory class for creating payout input DTOs based on channel and contact information
+ * Builds the upstream payout API body from domain models.
  *
- * @example
- * ```ts
- * const factory = new PayoutInputFactory();
- * const payoutInput = factory.getPayoutInput({
- *   channel: PayoutChannel.MOBILE,
- *   receiver: mobileContactInfo,
- *   amount: new Amount(1000),
- *   notes: "Payment for services"
- * }, wallet);
- * ```
+ * The factory owns channel resolution; callers provide only wallet, receiver,
+ * amount, and optional notes.
  */
 export declare class PayoutInputFactory {
-    private readonly handlers;
     /**
-     * Creates a payout input DTO based on the provided parameters
+     * Creates the DTO expected by the upstream payout API.
      *
-     * @param args - Configuration object containing channel, receiver, amount, and optional notes
-     * @returns {PayoutInputDTO} The configured payout input data transfer object
-     * @throws {Error} If no suitable handler is found for the specified channel and contact type
+     * @param args - Payout input fields controlled by the consumer.
+     * @param args.receiver - Beneficiary receiving the payout.
+     * @param args.amount - Amount to pay out.
+     * @param args.notes - Optional note used as narration when present.
+     * @param wallet - Wallet paying out.
+     * @returns Complete payout API input including the library-resolved channel.
+     * @throws Error when the receiver cannot be routed or validation fails.
      */
     getPayoutInput(args: {
-        channel: PayoutChannel;
         receiver: BeneficiaryInfo;
         amount: Amount;
         notes?: string;
     }, wallet: Wallet): PayoutInputDTO;
+    /**
+     * Builds the upstream payout DTO for a mobile money beneficiary.
+     *
+     * @param receiver - Valid mobile beneficiary.
+     * @param amount - Amount to pay out.
+     * @param channel - Resolved upstream mobile money payout channel.
+     * @param notes - Optional note used as narration when present.
+     * @returns Complete mobile money payout API input.
+     */
+    private createMobileInput;
+    /**
+     * Builds the upstream payout DTO for a bank beneficiary.
+     *
+     * @param receiver - Valid bank beneficiary.
+     * @param amount - Amount to pay out.
+     * @param channel - Resolved upstream bank payout channel.
+     * @param notes - Optional note used as narration when present.
+     * @returns Complete bank payout API input.
+     */
+    private createBankInput;
 }
 /**
- * @deprecated Use PayoutChannelCodeFactory instead
- * @see {@link PayoutChannelCodeFactory}
+ * @deprecated Use PayoutChannelResolver instead.
  */
 export declare const createPayoutChannelCode: {
-    bank: typeof PayoutChannelCodeFactory.forBank;
-    mobile: typeof PayoutChannelCodeFactory.forMobile;
+    bank: typeof PayoutChannelResolver.forBank;
+    mobile: typeof PayoutChannelResolver.forMobile;
 };
-export {};

package/dist/modules/payout/payout.api-contract.d.ts

@@ -402,7 +402,7 @@ export declare const contract: {
     postPayout: {
         method: "POST";
         body: z.ZodObject<{
-            channel: z.ZodString;
+            channel: z.ZodNativeEnum<typeof import("./payout.dtos.js").PayoutChannel>;
             msisdn: z.ZodString;
             amount: z.ZodNumber;
             description: z.ZodString;
@@ -411,14 +411,14 @@ export declare const contract: {
             payeeName: z.ZodString;
         }, "strip", z.ZodTypeAny, {
             description: string;
-            channel: string;
+            channel: import("./payout.dtos.js").PayoutChannel;
             msisdn: string;
             amount: number;
             payeeName: string;
             notes?: string | null | undefined;
         }, {
             description: string;
-            channel: string;
+            channel: import("./payout.dtos.js").PayoutChannel;
             msisdn: string;
             amount: number;
             payeeName: string;

package/dist/modules/payout/payout.dtos.d.ts

@@ -1,14 +1,21 @@
 import { z } from "zod";
 /**
  * Represents the available channels through which payouts can be processed.
+ *
+ * These values are the upstream API channel codes, not beneficiary categories.
+ * Beneficiary categories live in `BeneficiaryType`.
+ *
  * @enum {string}
  * @readonly
  */
 export declare enum PayoutChannel {
-    /** Payment processed through mobile money services */
-    MOBILE = "Mobile",
-    /** Payment processed through traditional banking channels */
-    BANK = "Bank"
+    TZ_TIGO_B2C = "TZ-TIGO-B2C",
+    TZ_VODACOM_B2C = "TZ-VODACOM-B2C",
+    TZ_AIRTEL_B2C = "TZ-AIRTEL-B2C",
+    TZ_HALOTEL_B2C = "TZ-HALOTEL-B2C",
+    KE_SAFARICOM_B2C = "KE-SAFARICOM-B2C",
+    TZ_BANK_B2C = "TZ-BANK-B2C",
+    KE_BANK_B2C = "KE-BANK-B2C"
 }
 /**
  * Represents the current status of a payout transaction.
@@ -66,7 +73,7 @@ declare const AuthorizerSchema: z.ZodObject<{
  * Extends base payout schema with payee information
  */
 declare const PayoutInputDTOSchema: z.ZodObject<{
-    channel: z.ZodString;
+    channel: z.ZodNativeEnum<typeof PayoutChannel>;
     msisdn: z.ZodString;
     amount: z.ZodNumber;
     description: z.ZodString;
@@ -75,14 +82,14 @@ declare const PayoutInputDTOSchema: z.ZodObject<{
     payeeName: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     description: string;
-    channel: string;
+    channel: PayoutChannel;
     msisdn: string;
     amount: number;
     payeeName: string;
     notes?: string | null | undefined;
 }, {
     description: string;
-    channel: string;
+    channel: PayoutChannel;
     msisdn: string;
     amount: number;
     payeeName: string;
@@ -509,7 +516,7 @@ export declare const PayoutDTOSchemas: {
         } | null | undefined;
     }>;
     readonly PayoutInputDTO: z.ZodObject<{
-        channel: z.ZodString;
+        channel: z.ZodNativeEnum<typeof PayoutChannel>;
         msisdn: z.ZodString;
         amount: z.ZodNumber;
         description: z.ZodString;
@@ -518,14 +525,14 @@ export declare const PayoutDTOSchemas: {
         payeeName: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         description: string;
-        channel: string;
+        channel: PayoutChannel;
         msisdn: string;
         amount: number;
         payeeName: string;
         notes?: string | null | undefined;
     }, {
         description: string;
-        channel: string;
+        channel: PayoutChannel;
         msisdn: string;
         amount: number;
         payeeName: string;
@@ -533,6 +540,7 @@ export declare const PayoutDTOSchemas: {
     }>;
     readonly PayoutStatus: z.ZodNativeEnum<typeof PayoutStatus>;
     readonly PayoutApprovalStatus: z.ZodNativeEnum<typeof PayoutApprovalStatus>;
+    readonly PayoutChannel: z.ZodNativeEnum<typeof PayoutChannel>;
     readonly PayoutAuthorizer: z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;

package/dist/modules/payout/payout.query.d.ts

@@ -200,7 +200,7 @@ export declare class PayoutQuery extends QueryBuilder {
      *   .whereApproved()
      *   .orderByDesc("createdAt")
      *   .build();
-     * // => { "approvalStatus:eq": "APPROVED", orderByDesc: "createdAt" }
+     * // => { "approvalStatus:eq": "Approved", orderByDesc: "createdAt" }
      * ```
      *
      * @returns An objection-find query object

package/dist/modules/payout/payout.repository.d.ts

@@ -2,20 +2,20 @@ import { BaseRepository } from "@/lib/api/index.js";
 import { Payout } from "@/modules/payout/payout.model.js";
 import { Amount } from "@temboplus/frontend-core";
 import { PayoutAPI } from "./payout.api-contract.js";
-import { PayoutChannel } from "./payout.dtos.js";
 import { PayoutQuery } from "./payout.query.js";
 import { PayoutFilters } from "./payout.dtos.js";
 import { Paged } from "@/lib/query/index.js";
 import { Wallet } from "../wallet/wallet.model.js";
 import { BeneficiaryInfo } from "../beneficiary/beneficiary-info.model.js";
 /**
- * Input type for payout creation mutation
+ * Input type for payout creation mutation.
+ *
+ * Consumers do not provide a payout channel. The repository resolves the
+ * upstream B2C channel from wallet, beneficiary, and amount details.
  */
 export interface CreatePayoutInput {
     /** The wallet to pay from */
     wallet: Wallet;
-    /** The payout channel to use (MOBILE or BANK) */
-    channel: PayoutChannel;
     /** Contact information for the payout receiver */
     receiver: BeneficiaryInfo;
     /** The amount to pay out */
@@ -123,9 +123,11 @@ export declare class PayoutRepository extends BaseRepository<PayoutAPI> {
     /**
      * Creates a new payout with the provided input data.
      *
+     * The upstream payout channel is resolved internally by the library before
+     * the API request is sent.
+     *
      * @param input - The payout creation data
      * @param input.wallet - The wallet to pay from
-     * @param input.channel - The payout channel to use
      * @param input.receiver - Contact information for the payout receiver
      * @param input.amount - The amount to pay out
      * @param input.notes - Optional notes for the payout
@@ -136,7 +138,6 @@ export declare class PayoutRepository extends BaseRepository<PayoutAPI> {
      * ```typescript
      * const payout = await repo.pay({
      *   wallet: selectedWallet,
-     *   channel: PayoutChannel.MOBILE,
      *   receiver: { name: "John Doe", phone: "+255123456789" },
      *   amount: Amount.from(10000, "TZS"),
      *   notes: "Payment for services"

package/package.json

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