@temboplus/afloat 0.1.81 → 0.2.0-beta.2

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

@@ -0,0 +1,383 @@
+import { PayoutDTO, PayoutStatus, PayoutApprovalStatus, PayoutAuthorizer } from "@/modules/payout/payout.dtos.js";
+import { Amount } from "@temboplus/frontend-core";
+import { BeneficiaryInfo } from "../beneficiary/beneficiary-info.model.js";
+import z from "zod";
+/**
+ * Zod schema for Payout JSON serialization
+ * This mirrors the PayoutDTO structure but is specifically for JSON serialization
+ */
+export declare const PayoutJSONSchema: z.ZodObject<{
+    id: z.ZodString;
+    profileId: z.ZodString;
+    payeeName: z.ZodString;
+    channel: z.ZodString;
+    msisdn: z.ZodString;
+    amount: z.ZodNumber;
+    currencyCode: z.ZodString;
+    countryCode: z.ZodString;
+    description: z.ZodString;
+    notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodNativeEnum<typeof PayoutStatus>;
+    statusMessage: z.ZodString;
+    partnerReference: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    actionedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    approvalStatus: z.ZodOptional<z.ZodNullable<z.ZodNativeEnum<typeof PayoutApprovalStatus>>>;
+    createdBy: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        identity: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        id: string;
+        identity: string;
+    }, {
+        name: string;
+        id: string;
+        identity: string;
+    }>>>;
+    actionedBy: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        identity: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        id: string;
+        identity: string;
+    }, {
+        name: string;
+        id: string;
+        identity: string;
+    }>>>;
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    status: PayoutStatus;
+    createdAt: string;
+    id: string;
+    version: string;
+    profileId: string;
+    updatedAt: string;
+    description: string;
+    channel: string;
+    msisdn: string;
+    amount: number;
+    payeeName: string;
+    countryCode: string;
+    currencyCode: string;
+    statusMessage: string;
+    notes?: string | null | undefined;
+    partnerReference?: string | null | undefined;
+    actionedAt?: string | null | undefined;
+    approvalStatus?: PayoutApprovalStatus | null | undefined;
+    createdBy?: {
+        name: string;
+        id: string;
+        identity: string;
+    } | null | undefined;
+    actionedBy?: {
+        name: string;
+        id: string;
+        identity: string;
+    } | null | undefined;
+}, {
+    status: PayoutStatus;
+    createdAt: string;
+    id: string;
+    profileId: string;
+    updatedAt: string;
+    description: string;
+    channel: string;
+    msisdn: string;
+    amount: number;
+    payeeName: string;
+    countryCode: string;
+    currencyCode: string;
+    statusMessage: string;
+    version?: string | undefined;
+    notes?: string | null | undefined;
+    partnerReference?: string | null | undefined;
+    actionedAt?: string | null | undefined;
+    approvalStatus?: PayoutApprovalStatus | null | undefined;
+    createdBy?: {
+        name: string;
+        id: string;
+        identity: string;
+    } | null | undefined;
+    actionedBy?: {
+        name: string;
+        id: string;
+        identity: string;
+    } | null | undefined;
+}>;
+/**
+ * Infer the PayoutJSON type from the schema
+ */
+export type PayoutJSON = z.infer<typeof PayoutJSONSchema>;
+/**
+ * Payout class that wraps the Zod schema and provides additional functionality
+ */
+export declare class Payout {
+    private readonly data;
+    /**
+     * Private constructor - use static methods to create instances
+     */
+    private constructor();
+    /** Unique identifier for the payout */
+    get id(): string;
+    /** Profile identifier associated with this payout */
+    get profileId(): string;
+    /** Name of the payee/recipient */
+    get payeeName(): string;
+    /** Payment channel used for this payout */
+    get channel(): string;
+    /** Mobile number or bank account identifier */
+    get msisdn(): string;
+    /**
+     * Amount to be paid out
+     * @returns {Amount} Amount object representing the payout value
+     */
+    get amount(): Amount;
+    /** Description of the payout purpose */
+    get description(): string;
+    /** Optional additional notes about the payout */
+    get notes(): string | undefined | null;
+    /**
+     * 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(): PayoutStatus;
+    /** Status message providing details about current state */
+    get statusMessage(): string;
+    /** Optional reference ID from payment partner */
+    get partnerReference(): string | undefined | null;
+    /** Timestamp when payout was created */
+    get createdAt(): Date;
+    /** Timestamp when payout was last updated */
+    get updatedAt(): Date;
+    /** Timestamp when payout was last updated */
+    get actionedAt(): Date | undefined | null;
+    /** Current approval status of the payout */
+    get approvalStatus(): PayoutApprovalStatus | undefined | null;
+    /** Information about who created the payout */
+    get createdBy(): PayoutAuthorizer | undefined | null;
+    /** Information about who last actioned the payout */
+    get actionedBy(): PayoutAuthorizer | undefined | null;
+    /**
+     * Tries to construct beneficiary information from the payout data.
+     */
+    get beneficiaryInfo(): BeneficiaryInfo | undefined;
+    /**
+     * @deprecated Use beneficiaryInfo instead
+     */
+    get contactInfo(): BeneficiaryInfo | undefined;
+    /**
+     * Creates a Payout instance from raw data
+     * @throws {ZodError} if validation fails
+     */
+    static create(data: PayoutDTO): Payout;
+    /**
+     * Creates multiple Payout instances from an array of raw data
+     * @throws {ZodError} if validation fails for any item
+     */
+    static createMany(dataArray: PayoutDTO[]): Payout[];
+    /**
+     * Creates a Payout instance from raw data without throwing
+     * @returns {Payout | null} Payout instance or null if validation fails
+     */
+    static createSafe(data: PayoutDTO): Payout | 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: unknown): obj is Payout;
+    /**
+     * 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: unknown): obj is Payout;
+    /**
+   * Serializes the Payout instance to a JSON-compatible object
+   *
+   * Converts all Date objects to ISO strings for proper JSON serialization.
+   * The resulting object can be safely stringified and stored or transmitted.
+   *
+   * @returns {PayoutJSON} A plain object containing all payout data
+   *
+   * @example
+   * ```typescript
+   * const payout = Payout.create(payoutData);
+   * const json = payout.toJSON();
+   * // {
+   * //   id: "payout-123",
+   * //   amount: 50000,
+   * //   currencyCode: "TZS",
+   * //   createdAt: "2024-01-15T10:30:00.000Z",
+   * //   ...
+   * // }
+   * ```
+   */
+    toJSON(): PayoutJSON;
+    /**
+     * Serializes the Payout instance to a JSON string
+     *
+     * @returns {string} JSON string representation of the payout
+     *
+     * @example
+     * ```typescript
+     * const payout = Payout.create(payoutData);
+     * const jsonString = payout.toJSONString();
+     *
+     * // Store in localStorage
+     * localStorage.setItem('pendingPayout', jsonString);
+     *
+     * // Or send to server
+     * await fetch('/api/cache-payout', {
+     *   method: 'POST',
+     *   body: jsonString
+     * });
+     * ```
+     */
+    toJSONString(): string;
+    /**
+     * Creates a Payout instance from a JSON-compatible object or string
+     *
+     * This method reconstructs a Payout instance from data that was previously
+     * serialized using toJSON(). It validates the input data using Zod schema
+     * and converts ISO date strings back to Date objects.
+     *
+     * @param {PayoutJSON | string} json - Either a PayoutJSON object or a JSON string
+     * @returns {Payout | undefined} A Payout instance if valid, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * // From localStorage
+     * const stored = localStorage.getItem('pendingPayout');
+     * const payout = Payout.fromJSON(stored!);
+     *
+     * if (payout) {
+     *   console.log(payout.amount.label); // "TSh 50,000.00"
+     *   console.log(payout.status); // "PENDING"
+     * }
+     *
+     * // From object
+     * const payoutJson = {
+     *   id: "payout-123",
+     *   amount: 50000,
+     *   currencyCode: "TZS",
+     *   createdAt: "2024-01-15T10:30:00.000Z",
+     *   ...
+     * };
+     * const payout = Payout.fromJSON(payoutJson);
+     * ```
+     */
+    static fromJSON(json: PayoutJSON | string): Payout | undefined;
+    /**
+     * Type guard using Zod schema validation
+     *
+     * Checks if an unknown value conforms to the PayoutJSON structure
+     * without attempting to create a Payout instance.
+     *
+     * @param {unknown} obj - The object to validate
+     * @returns {boolean} True if the object is a valid PayoutJSON
+     *
+     * @example
+     * ```typescript
+     * const data = JSON.parse(localStorage.getItem('payout'));
+     *
+     * if (Payout.isPayoutJSON(data)) {
+     *   const payout = Payout.fromJSON(data);
+     *   // TypeScript knows data is PayoutJSON here
+     * }
+     * ```
+     */
+    static isPayoutJSON(obj: unknown): obj is PayoutJSON;
+    /**
+     * Creates multiple Payout instances from a JSON array
+     *
+     * @param {PayoutJSON[] | string} jsonArray - Array of PayoutJSON objects or JSON string
+     * @returns {Payout[]} Array of Payout instances (invalid items are filtered out)
+     *
+     * @example
+     * ```typescript
+     * // From API response
+     * const response = await fetch('/api/payouts');
+     * const jsonArray = await response.json();
+     * const payouts = Payout.fromJSONArray(jsonArray);
+     *
+     * // From stored array
+     * const stored = localStorage.getItem('recentPayouts');
+     * const payouts = Payout.fromJSONArray(stored!);
+     * ```
+     */
+    static fromJSONArray(jsonArray: PayoutJSON[] | string): Payout[];
+    /**
+     * Serializes an array of Payout instances to JSON
+     *
+     * @param {Payout[]} payouts - Array of Payout instances to serialize
+     * @returns {PayoutJSON[]} Array of PayoutJSON objects
+     *
+     * @example
+     * ```typescript
+     * const payouts = [payout1, payout2, payout3];
+     * const jsonArray = Payout.toJSONArray(payouts);
+     *
+     * // Store or transmit
+     * localStorage.setItem('recentPayouts', JSON.stringify(jsonArray));
+     * ```
+     */
+    static toJSONArray(payouts: Payout[]): PayoutJSON[];
+}

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

@@ -0,0 +1,134 @@
+import { QueryBuilder } from "@/lib/query/index.js";
+import { PayoutStatus, PayoutApprovalStatus, PayoutFilters } from "./payout.dtos.js";
+import { Amount } from "@temboplus/frontend-core";
+/**
+ * Payout-specific query builder that extends the base QueryBuilder
+ * and handles all possible input conversions (DTOs, URL params, etc.)
+ */
+export declare class PayoutQuery extends QueryBuilder {
+    /**
+     * Create empty payout query with defaults
+     */
+    static create(): PayoutQuery;
+    /**
+     * Create from typed DTO/filters object
+     */
+    static fromFilters(filters: PayoutFilters): PayoutQuery;
+    /**
+     * Create from URL search parameters (strings)
+     */
+    static fromUrlParams(params: Record<string, string>): PayoutQuery;
+    /**
+     * Create from URLSearchParams object
+     */
+    static fromSearchParams(searchParams: URLSearchParams): PayoutQuery;
+    /**
+     * Create from Next.js Request object
+     */
+    static fromRequest(request: Request): PayoutQuery;
+    /**
+     * Create from any supported input type
+     */
+    static from(input: QueryBuilder | PayoutFilters | Record<string, string> | URLSearchParams | null | undefined): PayoutQuery;
+    /**
+     * Type guard for string records
+     */
+    private static isStringRecord;
+    whereStatus(status: PayoutStatus): this;
+    whereApprovalStatus(approvalStatus: PayoutApprovalStatus): this;
+    whereChannel(channel: string): this;
+    wherePending(): this;
+    whereApproved(): this;
+    whereRejected(): this;
+    wherePaid(): this;
+    whereFailed(): this;
+    whereAmountBetween(min: Amount, max: Amount): this;
+    wherePayee(payeeName: string): this;
+    whereMsisdn(msisdn: string): this;
+    whereProfileId(profileId: string): this;
+    wherePartnerReference(partnerReference: string): this;
+    whereSearch(searchTerm: string): this;
+    whereCurrencyCode(currencyCode: string): this;
+    /**
+     * Apply all filters from PayoutFilters object
+     */
+    private applyFilters;
+    /**
+     * Convert to PayoutFilters DTO
+     */
+    toFilters(): PayoutFilters;
+    /**
+     * Convert to user-friendly URL parameters (for browser URLs)
+     */
+    toUrlParams(): Record<string, string>;
+    /**
+     * Convert to URLSearchParams
+     */
+    toSearchParams(): URLSearchParams;
+    /**
+     * Convert to query string
+     */
+    toQueryString(): string;
+    /**
+     * Create new instance with updated pagination
+     */
+    withPagination(page: number, limit?: number): PayoutQuery;
+    /**
+     * Create new instance with updated sorting
+     */
+    withSorting(sortBy: string, sortOrder?: "asc" | "desc"): PayoutQuery;
+    /**
+     * Create new instance with date range
+     */
+    withDateRange(startDate?: string | Date, endDate?: string | Date): PayoutQuery;
+    /**
+     * Create new instance with status filter
+     */
+    withStatus(status?: PayoutStatus): PayoutQuery;
+    /**
+     * Create new instance with approval status filter
+     */
+    withApprovalStatus(approvalStatus?: PayoutApprovalStatus): PayoutQuery;
+    /**
+     * Create new instance with channel filter
+     */
+    withChannel(channel?: string): PayoutQuery;
+    /**
+     * Includes default relations for eager loading.
+     * This ensures that related data (createdBy, actionedBy) is fetched automatically.
+     * @returns The current query builder instance.
+     */
+    includeDefaultRelations(): this;
+    /**
+     * Reset to first page
+     */
+    resetPage(): PayoutQuery;
+    /**
+     * Check if any filters are applied
+     */
+    hasFilters(): boolean;
+    /**
+     * Get human-readable filter descriptions
+     */
+    getActiveFilters(): string[];
+    /**
+     * Extract filter values from QueryBuilder options
+     */
+    private extractFilterValues;
+    /**
+     * Extract primary sort field
+     */
+    private extractSortField;
+    /**
+     * Extract primary sort order
+     */
+    private extractSortOrder;
+    /**
+     * Type guard for valid statuses
+     */
+    private isValidStatus;
+    /**
+     * Type guard for valid approval statuses
+     */
+    private isValidApprovalStatus;
+}