@temboplus/afloat 0.1.81 → 0.2.0-beta.2

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

@@ -0,0 +1,225 @@
+import z from "zod";
+import { BankBeneficiaryInfo, BeneficiaryInfo, MobileBeneficiaryInfo } from "../beneficiary/beneficiary-info.model.js";
+/** Prefix for Ecobank mobile transfer narrations */
+export declare const ECOBANK_PREFIX = "MOBILE TRANSFER ";
+/** V2 format prefix for payout narrations using contact details */
+export declare const NARR_V2_PREFIX: string;
+/** V1 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;
+/** V1 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;
+/**
+ * Zod schema for Narration JSON serialization
+ */
+export declare const NarrationJSONSchema: z.ZodObject<{
+    text: z.ZodString;
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    text: string;
+}, {
+    text: string;
+    version?: string | undefined;
+}>;
+export type NarrationJSON = z.infer<typeof NarrationJSONSchema>;
+/**
+ * Handles payout narration generation and parsing for the Afloat platform.
+ *
+ * This class provides functionality to:
+ * - Generate standardized payout narrations using contact details (V2 format)
+ * - Parse existing narrations to extract contact information
+ * - Format narration text for different display contexts
+ * - Handle V2 (PAY format), V1, and legacy narration formats for backward compatibility
+ * - Serialize/deserialize to/from JSON format
+ *
+ * @example
+ * ```typescript
+ * // Generate V2 narration using contact info
+ * const mobileContact = new MobileContactInfo("John Doe", phoneNumber);
+ * const narration = Narration.generateDefaultPayoutNarration(mobileContact);
+ * // Result: "PAYOUT +255123456789 JOHN DOE"
+ *
+ * const bankContact = new BankContactInfo("Jane Smith", bank, "1234567890");
+ * const narration = Narration.generateDefaultPayoutNarration(bankContact);
+ * // Result: "PAYOUT CORUTZTZ 1234567890 JANE SMITH"
+ *
+ * // Extract contact details from narration
+ * const existingNarration = new Narration("PAYOUT +255123456789 JOHN DOE");
+ * const contactInfo = existingNarration.getBeneficiaryDetails();
+ * // Returns: MobileContactInfo instance
+ * ```
+ */
+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 the default payout narration based on contact information using the V2 format.
+     * Automatically determines whether to generate mobile or bank narration based on contact type.
+     *
+     * @param data - Contact information (either MobileBeneficiaryInfo or BankBeneficiaryInfo)
+     * @returns Formatted default narration string in uppercase using V2 format, or empty string if contact type is unrecognized
+     *
+     * @example
+     * ```typescript
+     * const mobileContact = new MobileBeneficiaryInfo("John Doe", phoneNumber);
+     * const narration = Narration.generateDefaultPayoutNarration(mobileContact);
+     * // Returns: "PAYOUT +255123456789 JOHN DOE"
+     *
+     * const bankContact = new BankBeneficiaryInfo("Jane Smith", bank, "1234567890");
+     * const narration = Narration.generateDefaultPayoutNarration(bankContact);
+     * // Returns: "PAYOUT CORUTZTZ 1234567890 JANE SMITH"
+     * ```
+     */
+    static generateDefaultPayoutNarration(data: BeneficiaryInfo): string;
+    /**
+     * Generates a V2 standardized mobile money payout narration with contact details.
+     * Format: "PAY {phone_number} {name}"
+     *
+     * @param data - Mobile contact information containing phone number and name
+     * @returns Formatted V2 mobile payout narration in uppercase
+     *
+     * @example
+     * ```typescript
+     * const contact = new MobileBeneficiaryInfo("John Doe", phoneNumber);
+     * const narration = Narration.generateMobilePayoutNarrationV2(contact);
+     * // Returns: "PAYOUT +255123456789 JOHN DOE"
+     * ```
+     */
+    static generateMobilePayoutNarrationV2(data: MobileBeneficiaryInfo): string;
+    /**
+     * Generates a V2 standardized bank payout narration with contact details.
+     * Format: "PAY {swift_code} {account_number} {account_name}"
+     *
+     * @param data - Bank contact information containing bank details, account number, and account name
+     * @returns Formatted V2 bank payout narration in uppercase
+     *
+     * @example
+     * ```typescript
+     * const contact = new BankBeneficiaryInfo("Jane Smith", bank, "1234567890");
+     * const narration = Narration.generateBankPayoutNarrationV2(contact);
+     * // Returns: "PAYOUT CORUTZTZ 1234567890 JANE SMITH"
+     * ```
+     */
+    static generateBankPayoutNarrationV2(data: BankBeneficiaryInfo): string;
+    /**
+     * Extracts contact information from the narration text.
+     * Supports V2 (PAY format), V1, and legacy formats for comprehensive contact detection.
+     *
+     * @returns Parsed BeneficiaryInfo (BankBeneficiaryInfo or MobileBeneficiaryInfo) if successful, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * // V2 format
+     * const v2Narration = new Narration("PAYOUT +255123456789 JOHN DOE");
+     * const v2Contact = v2Narration.getBeneficiaryDetails();
+     * // Returns: MobileContactInfo instance
+     *
+     * // V1 format
+     * const v1Narration = new Narration("PAYOUT TO BANK CRDB 1234567890 Jane Smith");
+     * const v1Contact = v1Narration.getBeneficiaryDetails();
+     * // Returns: BankContactInfo instance
+     * ```
+     */
+    getBeneficiaryDetails: () => BeneficiaryInfo | undefined;
+    /**
+     * Extracts bank contact information from the narration text.
+     * Handles V2 format (PAY with SWIFT code and details), V1 format, and legacy format.
+     * Also handles Ecobank-prefixed narrations by stripping the prefix.
+     *
+     * V2 format: "PAYOUT {swift_code} {account_number} {account_name}"
+     * V1 format: "PAYOUT TO BANK {bank_name} {account_number} {account_name}"
+     * Legacy format: "TO_BANK => {json_object}"
+     *
+     * @returns BankBeneficiaryInfo if parsing is successful, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * // V2 format
+     * const v2Narration = new Narration("PAYOUT CORUTZTZ 1234567890 JANE SMITH");
+     * const v2Contact = v2Narration.getBankBeneficiaryDetails();
+     *
+     * // V1 format
+     * const v1Narration = new Narration("PAYOUT TO BANK CRDB 1234567890 Jane Smith");
+     * const v1Contact = v1Narration.getBankBeneficiaryDetails();
+     * ```
+     */
+    getBankBeneficiaryDetails: () => BankBeneficiaryInfo | undefined;
+    /**
+     * Extracts mobile contact information from the narration text.
+     * Handles V2 format (PAY with phone number and name), V1 format, and legacy format.
+     * Also handles Ecobank-prefixed narrations by stripping the prefix.
+     *
+     * V2 format: "PAYOUT {phone_number} {name}"
+     * V1 format: "PAYOUT TO MOBILE {phone_number} {name}"
+     * Legacy format: "TO_MOMO => {json_object}"
+     *
+     * @returns MobileBeneficiaryInfo if parsing is successful, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * // V2 format
+     * const v2Narration = new Narration("PAYOUT +255123456789 JOHN DOE");
+     * const v2Contact = v2Narration.getMobileBeneficiaryDetails();
+     *
+     * // V1 format
+     * const v1Narration = new Narration("PAYOUT TO MOBILE +255123456789 John Doe");
+     * const v1Contact = v1Narration.getMobileBeneficiaryDetails();
+     * ```
+     */
+    getMobileBeneficiaryDetails: () => MobileBeneficiaryInfo | undefined;
+    /**
+     * Type guard to check if an unknown object is a valid Narration instance.
+     *
+     * @param obj - The object to check
+     * @returns Type predicate indicating if the object is a Narration instance
+     */
+    static is(obj: unknown): obj is Narration;
+    /**
+   * Serializes the Narration instance to a JSON-compatible object
+   */
+    toJSON(): NarrationJSON;
+    /**
+     * Serializes the Narration instance to a JSON string
+     */
+    toJSONString(): string;
+    /**
+     * Creates a Narration instance from a JSON-compatible object or string
+     */
+    static fromJSON(json: NarrationJSON | string): Narration | undefined;
+    /**
+     * Type guard using Zod schema validation
+     */
+    static isNarrationJSON(obj: unknown): obj is NarrationJSON;
+    /**
+     * @deprecated Use toJSON() instead
+     */
+    toJson(): NarrationJSON;
+    /**
+     * @deprecated Use fromJSON() instead
+     */
+    static fromJson(json: NarrationJSON | string): Narration | undefined;
+}

package/dist/modules/wallet/statement-entry.model.d.ts

@@ -0,0 +1,299 @@
+import { Amount } from "@temboplus/frontend-core";
+import { Narration } from "./narration.model.js";
+import z from "zod";
+/**
+ * Zod schema for WalletStatementEntry JSON serialization
+ */
+export declare const WalletStatementEntryJSONSchema: z.ZodObject<{
+    accountNo: z.ZodOptional<z.ZodString>;
+    debitOrCredit: z.ZodString;
+    tranRefNo: z.ZodString;
+    narration: z.ZodObject<{
+        text: z.ZodString;
+        version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        text: string;
+    }, {
+        text: string;
+        version?: string | undefined;
+    }>;
+    txnDate: z.ZodString;
+    valueDate: z.ZodString;
+    amountCredited: z.ZodObject<{
+        value: z.ZodNumber;
+        text: z.ZodString;
+        currencyCode: z.ZodString;
+        version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        value: number;
+        text: string;
+        currencyCode: string;
+    }, {
+        value: number;
+        text: string;
+        currencyCode: string;
+        version?: string | undefined;
+    }>;
+    amountDebited: z.ZodObject<{
+        value: z.ZodNumber;
+        text: z.ZodString;
+        currencyCode: z.ZodString;
+        version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        value: number;
+        text: string;
+        currencyCode: string;
+    }, {
+        value: number;
+        text: string;
+        currencyCode: string;
+        version?: string | undefined;
+    }>;
+    balance: z.ZodObject<{
+        value: z.ZodNumber;
+        text: z.ZodString;
+        currencyCode: z.ZodString;
+        version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        value: number;
+        text: string;
+        currencyCode: string;
+    }, {
+        value: number;
+        text: string;
+        currencyCode: string;
+        version?: string | undefined;
+    }>;
+    currencyCode: z.ZodString;
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    currencyCode: string;
+    debitOrCredit: string;
+    tranRefNo: string;
+    narration: {
+        version: string;
+        text: string;
+    };
+    txnDate: string;
+    valueDate: string;
+    amountCredited: {
+        version: string;
+        value: number;
+        text: string;
+        currencyCode: string;
+    };
+    amountDebited: {
+        version: string;
+        value: number;
+        text: string;
+        currencyCode: string;
+    };
+    balance: {
+        version: string;
+        value: number;
+        text: string;
+        currencyCode: string;
+    };
+    accountNo?: string | undefined;
+}, {
+    currencyCode: string;
+    debitOrCredit: string;
+    tranRefNo: string;
+    narration: {
+        text: string;
+        version?: string | undefined;
+    };
+    txnDate: string;
+    valueDate: string;
+    amountCredited: {
+        value: number;
+        text: string;
+        currencyCode: string;
+        version?: string | undefined;
+    };
+    amountDebited: {
+        value: number;
+        text: string;
+        currencyCode: string;
+        version?: string | undefined;
+    };
+    balance: {
+        value: number;
+        text: string;
+        currencyCode: string;
+        version?: string | undefined;
+    };
+    accountNo?: string | undefined;
+    version?: string | undefined;
+}>;
+export type WalletStatementEntryJSON = z.infer<typeof WalletStatementEntryJSONSchema>;
+/**
+ * Represents a single entry in a Wallet's statement history.
+ *
+ * This class provides methods for creating, validating, and accessing statement entry data.
+ * It integrates with the Zod schema validation for data integrity and includes narration parsing capabilities.
+ * The narration field now uses the Narration class for enhanced functionality.
+ */
+export declare class WalletStatementEntry {
+    private _accountNo?;
+    private _debitOrCredit;
+    private _tranRefNo;
+    private _narration;
+    private _txnDate;
+    private _valueDate;
+    private _amountCredited;
+    private _amountDebited;
+    private _balance;
+    private _currencyCode;
+    /**
+     * Gets the statement entry schema used for validation.
+     */
+    static get schema(): z.ZodObject<{
+        accountNo: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+        debitOrCredit: z.ZodString;
+        tranRefNo: z.ZodString;
+        narration: z.ZodString;
+        txnDate: z.ZodDate;
+        valueDate: z.ZodDate;
+        amountCredited: z.ZodNumber;
+        amountDebited: z.ZodNumber;
+        balance: z.ZodNumber;
+        currencyCode: z.ZodDefault<z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>>;
+    }, "strip", z.ZodTypeAny, {
+        currencyCode: string;
+        debitOrCredit: string;
+        tranRefNo: string;
+        narration: string;
+        txnDate: Date;
+        valueDate: Date;
+        amountCredited: number;
+        amountDebited: number;
+        balance: number;
+        accountNo?: string | undefined;
+    }, {
+        debitOrCredit: string;
+        tranRefNo: string;
+        narration: string;
+        txnDate: Date;
+        valueDate: Date;
+        amountCredited: number;
+        amountDebited: number;
+        balance: number;
+        accountNo?: string | undefined;
+        currencyCode?: string | undefined;
+    }>;
+    /**
+     * Private constructor to enforce use of static factory methods.
+     * Assumes data is already validated and dates are Date objects.
+     * @param data - Object containing statement entry information conforming to WalletStatementEntryDTO.
+     * @param narration - Narration instance for the transaction
+     */
+    private constructor();
+    /**
+     * Creates a new WalletStatementEntry instance after validating the input data.
+     * Handles date coercion via the schema and uses currencyCode from the data.
+     *
+     * @param data - Object containing statement entry information. Dates can be strings or Date objects.
+     * @returns A new WalletStatementEntry instance, or undefined if validation fails.
+     */
+    static create(data: {
+        accountNo?: string | null;
+        debitOrCredit: string;
+        tranRefNo: string;
+        narration: string | Narration;
+        txnDate: string | Date;
+        valueDate: string | Date;
+        amountCredited: number;
+        amountDebited: number;
+        balance: number;
+        currencyCode?: string;
+    }): WalletStatementEntry | undefined;
+    get accountNo(): string | undefined;
+    get debitOrCredit(): string;
+    get tranRefNo(): string;
+    get narration(): Narration;
+    get txnDate(): Date;
+    get valueDate(): Date;
+    get amountCredited(): Amount;
+    get amountDebited(): Amount;
+    get balance(): Amount;
+    get currencyCode(): string;
+    /**
+     * Validates the current statement entry instance data against the schema.
+     * @returns True if the statement entry instance data is valid, false otherwise.
+     */
+    validate(): boolean;
+    /**
+     * Type guard to check if an unknown object is a valid WalletStatementEntry instance.
+     * Performs structural checks (duck typing).
+     * @param obj - The object to check.
+     * @returns Type predicate indicating if the object is a WalletStatementEntry instance.
+     */
+    static is(obj: unknown): obj is WalletStatementEntry;
+    /**
+     * Checks if two WalletStatementEntry instances are equal based on their transaction reference numbers.
+     * @param other - Another WalletStatementEntry to compare with.
+     * @returns True if both entries have the same transaction reference number.
+     */
+    equals(other: WalletStatementEntry): boolean;
+    /**
+     * Creates a copy of this WalletStatementEntry with the same data.
+     * @returns A new WalletStatementEntry instance with identical data.
+     */
+    clone(): WalletStatementEntry | undefined;
+    /**
+     * Returns a string representation of the statement entry for debugging.
+     * @returns A formatted string with key transaction details.
+     */
+    toString(): string;
+    /**
+     * Legacy method for backwards compatibility - creates from plain object
+     * @deprecated Use fromJson() for serialized data or create() for raw data
+     */
+    static from(data: any): WalletStatementEntry | undefined;
+    /**
+   * Serializes the WalletStatementEntry instance to a JSON-compatible object
+   */
+    toJSON(): WalletStatementEntryJSON;
+    /**
+     * Serializes the WalletStatementEntry instance to a JSON string
+     */
+    toJSONString(): string;
+    /**
+     * Creates a WalletStatementEntry instance from a JSON-compatible object or string
+     */
+    static fromJSON(json: WalletStatementEntryJSON | string): WalletStatementEntry | undefined;
+    /**
+     * Type guard using Zod schema validation
+     */
+    static isWalletStatementEntryJSON(obj: unknown): obj is WalletStatementEntryJSON;
+    /**
+     * Creates WalletStatementEntry instances from a JSON array
+     */
+    static fromJSONArray(jsonArray: WalletStatementEntryJSON[] | string): WalletStatementEntry[];
+    /**
+     * Serializes an array of WalletStatementEntry instances to JSON
+     */
+    static toJSONArray(entries: WalletStatementEntry[]): WalletStatementEntryJSON[];
+    /**
+     * @deprecated Use toJSON() instead
+     */
+    toJson(): WalletStatementEntryJSON;
+    /**
+     * @deprecated Use fromJSON() instead
+     */
+    static fromJson(json: WalletStatementEntryJSON | string): WalletStatementEntry | undefined;
+    /**
+     * @deprecated Use fromJSONArray() instead
+     */
+    static fromJsonArray(jsonArray: WalletStatementEntryJSON[] | string): WalletStatementEntry[];
+    /**
+     * @deprecated Use toJSONArray() instead
+     */
+    static toJsonArray(entries: WalletStatementEntry[]): WalletStatementEntryJSON[];
+}

package/{script/npm/src/src/features/wallet/contract.d.ts → dist/modules/wallet/wallet.contract.d.ts}

@@ -12,19 +12,19 @@ export declare const contract: {
         }, "strip", z.ZodTypeAny, {
             id?: string | undefined;
             accountNo?: string | undefined;
-            channel?: string | undefined;
             profileId?: string | undefined;
-            accountName?: string | undefined;
+            channel?: string | undefined;
             countryCode?: string | undefined;
             currencyCode?: string | undefined;
+            accountName?: string | undefined;
         }, {
             id?: string | undefined;
             accountNo?: string | undefined;
-            channel?: string | undefined;
             profileId?: string | undefined;
-            accountName?: string | undefined;
+            channel?: string | undefined;
             countryCode?: string | undefined;
             currencyCode?: string | undefined;
+            accountName?: string | undefined;
         }>;
         method: "GET";
         path: "/";
@@ -35,27 +35,27 @@ export declare const contract: {
                 accountNo: z.ZodString;
                 accountName: z.ZodString;
                 channel: z.ZodString;
-                countryCode: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
-                currencyCode: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+                countryCode: z.ZodEffects<z.ZodDefault<z.ZodString>, import("@temboplus/frontend-core").ISO2CountryCode, string | undefined>;
+                currencyCode: z.ZodEffects<z.ZodDefault<z.ZodString>, import("@temboplus/frontend-core").CurrencyCode, string | undefined>;
                 createdAt: z.ZodString;
                 updatedAt: z.ZodString;
             }, "strip", z.ZodTypeAny, {
+                createdAt: string;
                 id: string;
                 accountNo: string;
-                channel: string;
                 profileId: string;
-                createdAt: string;
                 updatedAt: string;
+                channel: string;
+                countryCode: import("@temboplus/frontend-core").ISO2CountryCode;
+                currencyCode: import("@temboplus/frontend-core").CurrencyCode;
                 accountName: string;
-                countryCode: string;
-                currencyCode: string;
             }, {
+                createdAt: string;
                 id: string;
                 accountNo: string;
-                channel: string;
                 profileId: string;
-                createdAt: string;
                 updatedAt: string;
+                channel: string;
                 accountName: string;
                 countryCode?: string | undefined;
                 currencyCode?: string | undefined;
@@ -90,12 +90,12 @@ export declare const contract: {
             startDate: z.ZodDate;
             accountNo: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
-            endDate: Date;
             startDate: Date;
+            endDate: Date;
             accountNo?: string | undefined;
         }, {
-            endDate: Date;
             startDate: Date;
+            endDate: Date;
             accountNo?: string | undefined;
         }>;
         path: "/statement";
@@ -110,7 +110,9 @@ export declare const contract: {
                 amountCredited: z.ZodNumber;
                 amountDebited: z.ZodNumber;
                 balance: z.ZodNumber;
+                currencyCode: z.ZodDefault<z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>>;
             }, "strip", z.ZodTypeAny, {
+                currencyCode: string;
                 debitOrCredit: string;
                 tranRefNo: string;
                 narration: string;
@@ -130,8 +132,8 @@ export declare const contract: {
                 amountDebited: number;
                 balance: number;
                 accountNo?: string | undefined;
+                currencyCode?: string | undefined;
             }>, "many">;
         };
     };
 };
-//# sourceMappingURL=contract.d.ts.map