@temboplus/afloat 0.1.77-beta.9 → 0.1.79

package/script/npm/src/src/models/payout/derivatives/payout.js

@@ -0,0 +1,275 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Payout = void 0;
+const frontend_core_1 = require("@temboplus/frontend-core");
+const schemas_js_1 = require("../schemas.js");
+const index_js_1 = require("../../contact/index.js");
+const status_js_1 = require("../status.js");
+const channel_js_1 = require("../channel.js");
+/**
+ * Payout class that wraps the Zod schema and provides additional functionality
+ */
+class Payout {
+    /**
+     * Private constructor - use static methods to create instances
+     */
+    constructor(data) {
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.data = schemas_js_1.PayoutSchemas.payoutData.parse(data);
+    }
+    // Getters for all properties
+    /** Unique identifier for the payout */
+    get id() {
+        return this.data.id;
+    }
+    /** Profile identifier associated with this payout */
+    get profileId() {
+        return this.data.profileId;
+    }
+    /** Name of the payee/recipient */
+    get payeeName() {
+        return this.data.payeeName;
+    }
+    /** Payment channel used for this payout */
+    get channel() {
+        return this.data.channel;
+    }
+    /** Mobile number or bank account identifier */
+    get msisdn() {
+        return this.data.msisdn;
+    }
+    /**
+     * Amount to be paid out
+     * @returns {Amount} Amount object representing the payout value
+     */
+    get amount() {
+        return frontend_core_1.Amount.from(this.data.amount);
+    }
+    /** Description of the payout purpose */
+    get description() {
+        return this.data.description;
+    }
+    /** Optional additional notes about the payout */
+    get notes() {
+        return this.data.notes;
+    }
+    /**
+     * Current status of the payout
+     * Derived from both approval status and transaction status:
+     * - Returns REJECTED if approval status is "Rejected"
+     * - Returns FAILED if approved but transaction failed
+     * - Returns PAID if approved and transaction succeeded
+     * - Returns PENDING if awaiting approval
+     * - Falls back to transaction status in other cases
+     *
+     * @returns {PAYOUT_STATUS} Current status of the payout
+     * @see {@link PAYOUT_STATUS} for all possible status values
+     */
+    get status() {
+        if (this.data.approvalStatus === "Rejected") {
+            return status_js_1.PAYOUT_STATUS.REJECTED;
+        }
+        if (this.data.approvalStatus === "Approved") {
+            if (this.data.status === "FAILED") {
+                return status_js_1.PAYOUT_STATUS.FAILED;
+            }
+            return status_js_1.PAYOUT_STATUS.PAID;
+        }
+        if (this.data.approvalStatus === "Pending") {
+            return status_js_1.PAYOUT_STATUS.PENDING;
+        }
+        return this.data.status;
+    }
+    /** Status message providing details about current state */
+    get statusMessage() {
+        return this.data.statusMessage;
+    }
+    /** Optional reference ID from payment partner */
+    get partnerReference() {
+        return this.data.partnerReference;
+    }
+    /** Timestamp when payout was created */
+    get createdAt() {
+        return this.data.createdAt;
+    }
+    /** Timestamp when payout was last updated */
+    get updatedAt() {
+        return this.data.updatedAt;
+    }
+    /** Timestamp when payout was last updated */
+    get actionedAt() {
+        try {
+            // deno-lint-ignore no-explicit-any
+            return this.data.actionedAt ?? undefined;
+        }
+        catch (_) {
+            return undefined;
+        }
+    }
+    /** Current approval status of the payout */
+    get approvalStatus() {
+        return this.data.approvalStatus;
+    }
+    /** Information about who created the payout */
+    get createdBy() {
+        return this.data.createdBy;
+    }
+    /** Information about who last actioned the payout */
+    get actionedBy() {
+        return this.data.actionedBy;
+    }
+    /**
+     * Constructs contact information based on payout channel
+     *
+     * @returns {ContactInfo | undefined} Contact information object:
+     * - MobileContactInfo for mobile money payouts
+     * - BankContactInfo for bank transfers
+     * - undefined if contact info cannot be constructed
+     *
+     * @remarks
+     * For bank payouts, expects msisdn in format "SWIFTCODE:ACCOUNTNUMBER"
+     *
+     * @example
+     * ```ts
+     * // Mobile payout
+     * payout.contactInfo // Returns MobileContactInfo with phone details
+     *
+     * // Bank payout
+     * payout.contactInfo // Returns BankContactInfo with bank and account details
+     * ```
+     */
+    get contactInfo() {
+        let contactInfo;
+        // extracting mobile contact information
+        const phone = frontend_core_1.TZPhoneNumber.from(this.data.msisdn);
+        if (phone) {
+            contactInfo = new index_js_1.MobileContactInfo(this.data.payeeName, phone);
+        }
+        // extracting bank contact information
+        const isBankPayout = this.data.channel === channel_js_1.createPayoutChannelCode.bank() ||
+            this.data.channel === channel_js_1.createPayoutChannelCode.verto();
+        if (isBankPayout) {
+            // getting bank information from payout msisdn
+            const text = this.data.msisdn.trim().split(":");
+            try {
+                const swiftcode = text[0];
+                const accNo = text[1];
+                const bank = frontend_core_1.Bank.fromSWIFTCode(swiftcode);
+                if (bank) {
+                    contactInfo = new index_js_1.BankContactInfo(this.data.payeeName, bank, accNo);
+                }
+            }
+            catch (_) {
+                //
+            }
+        }
+        return contactInfo;
+    }
+    /**
+     * Creates a Payout instance from raw data
+     * @throws {ZodError} if validation fails
+     */
+    static create(data) {
+        return new Payout(data);
+    }
+    /**
+     * Creates multiple Payout instances from an array of raw data
+     * @throws {ZodError} if validation fails for any item
+     */
+    static createMany(dataArray) {
+        return dataArray.map((data) => new Payout(data));
+    }
+    /**
+     * Creates a Payout instance from raw data without throwing
+     * @returns {Payout | null} Payout instance or null if validation fails
+     */
+    static createSafe(data) {
+        try {
+            return new Payout(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Checks if an unknown value contains valid data to construct a Payout instance.
+     * This is useful when validating raw data structures before instantiation.
+     *
+     * @param {unknown} obj - The value containing potential payout data
+     * @returns {obj is Payout} Type predicate indicating if a Payout can be constructed
+     *
+     * @example
+     * ```typescript
+     * const rawData = await fetchPayoutData();
+     * if (Payout.canConstruct(rawData)) {
+     *   const payout = Payout.create(rawData);
+     *   // TypeScript knows payout is valid here
+     *   console.log(payout.amount.toString());
+     * }
+     * ```
+     *
+     * @throws {never} This method never throws errors
+     *
+     * @remarks
+     * This method performs strict validation against the {@link PayoutData} schema
+     */
+    static canConstruct(obj) {
+        if (!obj || typeof obj !== "object")
+            return false;
+        const result = schemas_js_1.PayoutSchemas.payoutData.safeParse(obj);
+        if (!result.success)
+            return false;
+        const payout = Payout.createSafe(result.data);
+        return payout !== null;
+    }
+    /**
+     * Validates if an unknown value is a Payout instance.
+     * This is a runtime type guard that ensures proper object structure and data validity.
+     *
+     * @param {unknown} obj - The value to validate
+     * @returns {obj is Payout} Type predicate indicating if the value is a valid Payout
+     *
+     * @example
+     * ```typescript
+     * const maybePayout = getPayoutFromCache();
+     * if (Payout.is(maybePayout)) {
+     *   // TypeScript knows maybePayout is a Payout here
+     *   console.log(maybePayout.status);
+     * }
+     * ```
+     *
+     * @throws {never} This method never throws errors
+     *
+     * @remarks
+     * This method performs a complete structural validation:
+     * 1. Checks if the value is an object
+     * 2. Verifies presence of internal data property
+     * 3. Validates the data against PayoutData schema
+     * 4. Ensures the object is a proper Payout instance
+     *
+     * Use this method when:
+     * - Validating cached Payout instances
+     * - Checking serialized Payout objects
+     * - Verifying API responses
+     * - Type narrowing in conditional blocks
+     */
+    static is(obj) {
+        if (!obj || typeof obj !== "object")
+            return false;
+        if (!("data" in obj))
+            return false;
+        return Payout.canConstruct(obj.data);
+    }
+    /**
+     * Converts Payout instance to a plain object
+     */
+    toJSON() {
+        return { ...this.data };
+    }
+}
+exports.Payout = Payout;

package/script/npm/src/src/models/payout/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./status.js";
+export * from "./schemas.js";
+export * from "./channel.js";
+export * from "./api.js";
+export * from "./narration.js";
+export * from "./derivatives/payout.js";
+//# sourceMappingURL=index.d.ts.map

package/script/npm/src/src/models/payout/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/src/models/payout/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC"}

package/script/npm/src/src/models/payout/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./status.js"), exports);
+__exportStar(require("./schemas.js"), exports);
+__exportStar(require("./channel.js"), exports);
+__exportStar(require("./api.js"), exports);
+__exportStar(require("./narration.js"), exports);
+__exportStar(require("./derivatives/payout.js"), exports);

package/script/npm/src/src/models/payout/narration.d.ts

@@ -0,0 +1,164 @@
+import { BankContactInfo, type ContactInfo, MobileContactInfo } from "@temboplus/afloat";
+/** Prefix for Ecobank mobile transfer narrations */
+export declare const ECOBANK_PREFIX = "MOBILE TRANSFER ";
+/** Current format prefix for bank payout narrations */
+export declare const BANK_NARR_PREFIX: string;
+/** Legacy format prefix for bank payout narrations */
+export declare const LEGACY_BANK_NARR_PREFIX: string;
+/** Current format prefix for mobile money payout narrations */
+export declare const MOBILE_NARR_PREFIX: string;
+/** Legacy format prefix for mobile money payout narrations */
+export declare const LEGACY_MOBILE_NARR_PREFIX: string;
+/**
+ * Handles payout narration generation and parsing for the Afloat platform.
+ *
+ * This class provides functionality to:
+ * - Generate standardized default narrations for mobile money and bank payouts
+ * - Parse existing narrations to extract contact information
+ * - Format narration text for different display contexts
+ * - Handle both current and legacy narration formats for backward compatibility
+ *
+ * @example
+ * ```typescript
+ * // Generate default narration for a mobile contact
+ * const mobileContact = new MobileContactInfo("John Doe", phoneNumber);
+ * const narration = Narration.generateDefaultPayoutNarration(mobileContact);
+ * // Result: "PAYOUT TO MOBILE +255123456789 JOHN DOE"
+ *
+ * // Parse narration to extract contact details
+ * const existingNarration = new Narration("PAYOUT TO BANK CRDB 1234567890 Jane Smith");
+ * const contact = existingNarration.getContactDetails();
+ * ```
+ */
+export declare class Narration {
+    /** The raw narration text */
+    text: string;
+    /**
+     * Creates a new Narration instance.
+     *
+     * @param text - The narration text to wrap
+     */
+    constructor(text: string);
+    /**
+     * Returns a medium-length version of the narration text suitable for table columns.
+     * Truncates to 47 characters + "..." if longer than 50 characters.
+     *
+     * @returns Truncated narration text for medium-width displays
+     */
+    get mediumText(): string;
+    /**
+     * Returns a short version of the narration text suitable for compact displays.
+     * Truncates to 32 characters + "..." if longer than 35 characters.
+     *
+     * @returns Truncated narration text for narrow displays
+     */
+    get shortText(): string;
+    /**
+     * Generates a default payout narration based on contact information.
+     * Automatically determines whether to generate mobile or bank narration based on contact type.
+     *
+     * @param data - Contact information (either MobileContactInfo or BankContactInfo)
+     * @returns Formatted default narration string in uppercase, or empty string if contact type is unrecognized
+     *
+     * @example
+     * ```typescript
+     * const mobileContact = new MobileContactInfo("John Doe", phoneNumber);
+     * const narration = Narration.generateDefaultPayoutNarration(mobileContact);
+     * // Returns: "PAYOUT TO MOBILE +255123456789 JOHN DOE"
+     *
+     * const bankContact = new BankContactInfo("Jane Smith", bank, "1234567890");
+     * const narration = Narration.generateDefaultPayoutNarration(bankContact);
+     * // Returns: "PAYOUT TO BANK CRDB 1234567890 JANE SMITH"
+     * ```
+     */
+    static generateDefaultPayoutNarration(data: ContactInfo): string;
+    /**
+     * Generates a standardized mobile money payout narration.
+     * Format: "PAYOUT TO MOBILE {phone_number} {name}"
+     *
+     * @param data - Mobile contact information containing phone number and name
+     * @returns Formatted mobile payout narration in uppercase
+     *
+     * @example
+     * ```typescript
+     * const contact = new MobileContactInfo("John Doe", phoneNumber);
+     * const narration = Narration.generateMobilePayoutNarration(contact);
+     * // Returns: "PAYOUT TO MOBILE +255123456789 JOHN DOE"
+     * ```
+     */
+    static generateMobilePayoutNarration(data: MobileContactInfo): string;
+    /**
+     * Generates a standardized bank payout narration.
+     * Format: "PAYOUT TO BANK {bank_short_name} {account_number} {account_name}"
+     *
+     * @param data - Bank contact information containing bank details, account number, and account name
+     * @returns Formatted bank payout narration in uppercase
+     *
+     * @example
+     * ```typescript
+     * const contact = new BankContactInfo("Jane Smith", bank, "1234567890");
+     * const narration = Narration.generateBankPayoutNarration(contact);
+     * // Returns: "PAYOUT TO BANK CRDB 1234567890 JANE SMITH"
+     * ```
+     */
+    static generateBankPayoutNarration(data: BankContactInfo): string;
+    /**
+     * Extracts contact information from the narration text.
+     * Attempts to parse both bank and mobile contact details from the narration.
+     *
+     * @returns Parsed ContactInfo (BankContactInfo or MobileContactInfo) if successful, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const narration = new Narration("PAYOUT TO BANK CRDB 1234567890 Jane Smith");
+     * const contact = narration.getContactDetails();
+     * // Returns: BankContactInfo instance with parsed details
+     * ```
+     */
+    getContactDetails: () => ContactInfo | undefined;
+    /**
+     * Extracts bank contact information from the narration text.
+     * Handles both current format ("PAYOUT TO BANK") and legacy format ("TO_BANK").
+     * Also handles Ecobank-prefixed narrations by stripping the prefix.
+     *
+     * Current format: "PAYOUT TO BANK {bank_name} {account_number} {account_name}"
+     * Legacy format: "TO_BANK => {json_object}"
+     *
+     * @returns BankContactInfo if parsing is successful, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * // Current format
+     * const narration = new Narration("PAYOUT TO BANK CRDB 1234567890 Jane Smith");
+     * const contact = narration.getBankContactDetails();
+     *
+     * // Legacy format
+     * const legacyNarration = new Narration('TO_BANK => {"account_number":"1234567890","account_name":"Jane Smith","swift_code":"CORUTZTZ"}');
+     * const legacyContact = narration.getBankContactDetails();
+     * ```
+     */
+    getBankContactDetails: () => BankContactInfo | undefined;
+    /**
+     * Extracts mobile contact information from the narration text.
+     * Handles both current format ("PAYOUT TO MOBILE") and legacy format ("TO_MOMO").
+     * Also handles Ecobank-prefixed narrations by stripping the prefix.
+     *
+     * Current format: "PAYOUT TO MOBILE {phone_number} {name}"
+     * Legacy format: "TO_MOMO => {json_object}"
+     *
+     * @returns MobileContactInfo if parsing is successful, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * // Current format
+     * const narration = new Narration("PAYOUT TO MOBILE +255123456789 John Doe");
+     * const contact = narration.getMobileContactDetails();
+     *
+     * // Legacy format
+     * const legacyNarration = new Narration('TO_MOMO => {"phone_number":"+255123456789","username":"John Doe"}');
+     * const legacyContact = narration.getMobileContactDetails();
+     * ```
+     */
+    getMobileContactDetails: () => MobileContactInfo | undefined;
+}
+//# sourceMappingURL=narration.d.ts.map

package/script/npm/src/src/models/payout/narration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"narration.d.ts","sourceRoot":"","sources":["../../../../../../src/src/models/payout/narration.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAG3B,oDAAoD;AACpD,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAEjD,uDAAuD;AACvD,eAAO,MAAM,gBAAgB,EAAE,MAAyB,CAAC;AACzD,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,MAAkB,CAAC;AAEzD,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,EAAE,MAA2B,CAAC;AAC7D,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,EAAE,MAAkB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,SAAS;IACpB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;gBACS,IAAI,EAAE,MAAM;IAIxB;;;;;OAKG;IACH,IAAI,UAAU,WAMb;IAED;;;;;OAKG;IACH,IAAI,SAAS,WAMZ;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,8BAA8B,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM;IAUhE;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,6BAA6B,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM;IAKrE;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,2BAA2B,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM;IAKjE;;;;;;;;;;;;OAYG;IACH,iBAAiB,QAAO,WAAW,GAAG,SAAS,CAM7C;IAEF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,qBAAqB,QAAO,eAAe,GAAG,SAAS,CAqCrD;IAEF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uBAAuB,QAAO,iBAAiB,GAAG,SAAS,CAuCzD;CACH"}