@temboplus/afloat 0.1.81 → 0.2.0-beta.2

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

@@ -0,0 +1,204 @@
+import { z } from "zod";
+/**
+ * Zod schema definition for validating Wallet data structures.
+ * Ensures data integrity for wallet objects, including runtime validation
+ * of country codes against the imported ISO2CountryCodesSet.
+ */
+declare const walletSchema: z.ZodObject<{
+    id: z.ZodString;
+    profileId: z.ZodString;
+    accountNo: z.ZodString;
+    accountName: z.ZodString;
+    channel: z.ZodString;
+    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;
+    profileId: string;
+    updatedAt: string;
+    channel: string;
+    countryCode: import("@temboplus/frontend-core").ISO2CountryCode;
+    currencyCode: import("@temboplus/frontend-core").CurrencyCode;
+    accountName: string;
+}, {
+    createdAt: string;
+    id: string;
+    accountNo: string;
+    profileId: string;
+    updatedAt: string;
+    channel: string;
+    accountName: string;
+    countryCode?: string | undefined;
+    currencyCode?: string | undefined;
+}>;
+/**
+ * Zod schema definition for validating Wallet data structures.
+ * Ensures data integrity for wallet objects, including runtime validation
+ * of country codes against the imported ISO2CountryCodesSet.
+ */
+declare const walletQuerySchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    profileId: z.ZodOptional<z.ZodString>;
+    accountNo: z.ZodOptional<z.ZodString>;
+    accountName: z.ZodOptional<z.ZodString>;
+    channel: z.ZodOptional<z.ZodString>;
+    countryCode: z.ZodOptional<z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>>;
+    currencyCode: z.ZodOptional<z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    accountNo?: string | undefined;
+    profileId?: string | undefined;
+    channel?: string | undefined;
+    countryCode?: string | undefined;
+    currencyCode?: string | undefined;
+    accountName?: string | undefined;
+}, {
+    id?: string | undefined;
+    accountNo?: string | undefined;
+    profileId?: string | undefined;
+    channel?: string | undefined;
+    countryCode?: string | undefined;
+    currencyCode?: string | undefined;
+    accountName?: string | undefined;
+}>;
+/**
+ * Schema definition for a statement entry.
+ */
+declare const statementEntrySchema: 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;
+}>;
+/**
+ * Collection of wallet-related schemas for export.
+ * Provides access to both wallet and statement entry validation schemas.
+ */
+export declare const WalletDTOSchemas: {
+    walletDTO: z.ZodObject<{
+        id: z.ZodString;
+        profileId: z.ZodString;
+        accountNo: z.ZodString;
+        accountName: z.ZodString;
+        channel: z.ZodString;
+        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;
+        profileId: string;
+        updatedAt: string;
+        channel: string;
+        countryCode: import("@temboplus/frontend-core").ISO2CountryCode;
+        currencyCode: import("@temboplus/frontend-core").CurrencyCode;
+        accountName: string;
+    }, {
+        createdAt: string;
+        id: string;
+        accountNo: string;
+        profileId: string;
+        updatedAt: string;
+        channel: string;
+        accountName: string;
+        countryCode?: string | undefined;
+        currencyCode?: string | undefined;
+    }>;
+    walletQuery: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        profileId: z.ZodOptional<z.ZodString>;
+        accountNo: z.ZodOptional<z.ZodString>;
+        accountName: z.ZodOptional<z.ZodString>;
+        channel: z.ZodOptional<z.ZodString>;
+        countryCode: z.ZodOptional<z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>>;
+        currencyCode: z.ZodOptional<z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>>;
+    }, "strip", z.ZodTypeAny, {
+        id?: string | undefined;
+        accountNo?: string | undefined;
+        profileId?: string | undefined;
+        channel?: string | undefined;
+        countryCode?: string | undefined;
+        currencyCode?: string | undefined;
+        accountName?: string | undefined;
+    }, {
+        id?: string | undefined;
+        accountNo?: string | undefined;
+        profileId?: string | undefined;
+        channel?: string | undefined;
+        countryCode?: string | undefined;
+        currencyCode?: string | undefined;
+        accountName?: string | undefined;
+    }>;
+    statementEntry: 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;
+    }>;
+};
+export type WalletDTO = z.infer<typeof walletSchema>;
+export type WalletQueryDTO = z.infer<typeof walletQuerySchema>;
+export type WalletStatementEntryDTO = z.infer<typeof statementEntrySchema>;
+export {};

package/{esm/src/models/wallet/wallet.d.ts → dist/modules/wallet/wallet.model.d.ts}

@@ -1,46 +1,44 @@
-import { z } from "zod";
 import { type CurrencyCode, type ISO2CountryCode } from "@temboplus/frontend-core";
+import { WalletDTOSchemas } from "@/modules/wallet/wallet.dtos.js";
+import z from "zod";
 /**
- * Zod schema definition for validating Wallet data structures.
- * Ensures data integrity for wallet objects, including runtime validation
- * of country codes against the imported ISO2CountryCodesSet.
+ * Zod schema for Wallet JSON serialization
  */
-declare const walletSchema: z.ZodObject<{
+export declare const WalletJSONSchema: z.ZodObject<{
     id: z.ZodString;
     profileId: z.ZodString;
     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.ZodString;
+    currencyCode: z.ZodString;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
+    version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
+    createdAt: string;
     id: string;
     accountNo: string;
-    channel: string;
+    version: string;
     profileId: string;
-    createdAt: string;
     updatedAt: string;
-    accountName: string;
+    channel: string;
     countryCode: string;
     currencyCode: string;
+    accountName: string;
 }, {
+    createdAt: string;
     id: string;
     accountNo: string;
-    channel: string;
     profileId: string;
-    createdAt: string;
     updatedAt: string;
+    channel: string;
+    countryCode: string;
+    currencyCode: string;
     accountName: string;
-    countryCode?: string | undefined;
-    currencyCode?: string | undefined;
+    version?: string | undefined;
 }>;
-/**
- * TypeScript type representing the validated data structure for a Wallet.
- * Derived from the walletSchema. Note: countryCode is inferred as string.
- */
-type WalletDataType = z.infer<typeof walletSchema>;
+export type WalletJSON = z.infer<typeof WalletJSONSchema>;
 /**
  * Represents a digital Wallet entity.
  *
@@ -61,7 +59,7 @@ export declare class Wallet {
      * Retrieves the Zod schema used for Wallet validation.
      * @returns The Zod schema object for Wallet.
      */
-    static get schema(): typeof walletSchema;
+    static get schema(): typeof WalletDTOSchemas.walletDTO;
     /**
      * Private constructor enforces instantiation via static factory methods.
      * @param data - The validated wallet data object (countryCode is string).
@@ -104,30 +102,12 @@ export declare class Wallet {
      * @returns The last update Date object.
      */
     get updatedAtDate(): Date;
-    /**
-     * Creates a plain data object representation of the Wallet instance.
-     * Suitable for serialization or validation.
-     * @returns A plain object conforming to the WalletDataType structure.
-     */
-    toObject(): WalletDataType;
-    /**
-     * Serializes the Wallet instance into a JSON string.
-     * @returns A JSON string representation of the wallet data.
-     */
-    toJSON(): string;
     /**
      * Validates the Wallet instance's current data against the defined schema.
      * This includes checking the countryCode against ISO2CountryCodesSet.
      * @returns True if the current instance data is valid, otherwise false.
      */
     validate(): boolean;
-    /**
-     * Creates a Wallet instance from a JSON string.
-     * Performs parsing and validation, including the countryCode runtime check.
-     * @param jsonString - A JSON string containing wallet data.
-     * @returns A new Wallet instance if parsing and validation succeed, otherwise undefined.
-     */
-    static fromJSON(jsonString: string): Wallet | undefined;
     /**
      * Creates a Wallet instance from a plain JavaScript object.
      * Validates the input object using the Wallet schema, including the countryCode runtime check.
@@ -142,6 +122,20 @@ export declare class Wallet {
      * @returns True if the object resembles a Wallet instance, false otherwise.
      */
     static is(obj: unknown): obj is Wallet;
+    /**
+   * Serializes the Wallet instance to a JSON-compatible object
+   */
+    toJSON(): WalletJSON;
+    /**
+     * Serializes the Wallet instance to a JSON string
+     */
+    toJSONString(): string;
+    /**
+     * Creates a Wallet instance from a JSON-compatible object or string
+     */
+    static fromJSON(json: WalletJSON | string): Wallet | undefined;
+    /**
+     * Type guard using Zod schema validation
+     */
+    static isWalletJSON(obj: unknown): obj is WalletJSON;
 }
-export {};
-//# sourceMappingURL=wallet.d.ts.map

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

@@ -0,0 +1,95 @@
+import { QueryBuilder } from "@/lib/query/index.js";
+import { WalletQueryDTO } from "./wallet.dtos.js";
+/**
+ * Wallet-specific query builder that extends the base QueryBuilder
+ * and handles all possible input conversions (DTOs, URL params, etc.)
+ */
+export declare class WalletQuery extends QueryBuilder {
+    /**
+     * Create empty wallet query with defaults
+     */
+    static create(): WalletQuery;
+    /**
+     * Create from typed DTO/filters object
+     */
+    static fromFilters(filters: WalletQueryDTO): WalletQuery;
+    /**
+     * Create from URL search parameters (strings)
+     */
+    static fromUrlParams(params: Record<string, string>): WalletQuery;
+    /**
+     * Create from URLSearchParams object
+     */
+    static fromSearchParams(searchParams: URLSearchParams): WalletQuery;
+    /**
+     * Create from Next.js Request object
+     */
+    static fromRequest(request: Request): WalletQuery;
+    /**
+     * Create from any supported input type
+     */
+    static from(input: QueryBuilder | WalletQueryDTO | Record<string, string> | URLSearchParams | null | undefined): WalletQuery;
+    /**
+     * Type guard for string records
+     */
+    private static isStringRecord;
+    whereId(id: string): this;
+    whereProfileId(profileId: string): this;
+    whereAccountNo(accountNo: string): this;
+    whereAccountName(accountName: string): this;
+    whereChannel(channel: string): this;
+    whereCountryCode(countryCode: string): this;
+    whereCurrencyCode(currencyCode: string): this;
+    /**
+     * Apply all filters from WalletQueryDTO object
+     */
+    private applyFilters;
+    /**
+     * Convert to WalletQueryDTO
+     */
+    toFilters(): WalletQueryDTO;
+    /**
+     * Convert to URL-safe string parameters
+     */
+    toUrlParams(): Record<string, string>;
+    /**
+     * Convert to URLSearchParams
+     */
+    toSearchParams(): URLSearchParams;
+    /**
+     * Convert to query string
+     */
+    toQueryString(): string;
+    /**
+     * Create new instance with wallet ID filter
+     */
+    withId(id: string): WalletQuery;
+    /**
+     * Create new instance with profile ID filter
+     */
+    withProfileId(profileId: string): WalletQuery;
+    /**
+     * Create new instance with account number filter
+     */
+    withAccountNo(accountNo: string): WalletQuery;
+    /**
+     * Create new instance with country code filter
+     */
+    withCountryCode(countryCode: string): WalletQuery;
+    /**
+     * Create new instance with currency code filter
+     */
+    withCurrencyCode(currencyCode: string): WalletQuery;
+    /**
+     * Check if any filters are applied
+     */
+    hasFilters(): boolean;
+    /**
+     * Get human-readable filter descriptions
+     */
+    getActiveFilters(): string[];
+    /**
+     * Extract filter values from QueryBuilder options
+     */
+    private extractFilterValues;
+}

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

@@ -0,0 +1,205 @@
+import { Amount } from "@temboplus/frontend-core";
+import { WalletStatementEntry } from "./statement-entry.model.js";
+import { Wallet } from "./wallet.model.js";
+import { contract } from "./wallet.contract.js";
+import { BaseRepository } from "@/lib/api/base-repository.js";
+import { WalletQuery } from "./wallet.query.js";
+import { WalletQueryDTO } from "./wallet.dtos.js";
+/**
+ * Flexible query input type - supports the class, filters interface, URL params, etc.
+ */
+export type WalletQueryInput = WalletQuery | WalletQueryDTO | Record<string, string> | URLSearchParams | null | undefined;
+/**
+ * Repository class for managing wallet operations including balance checking,
+ * statement generation, and wallet information retrieval.
+ *
+ * This repository handles pure API communication without permission checking.
+ * Permission validation should be handled at the service layer or route handlers.
+ *
+ * @extends {BaseRepository<typeof contract>}
+ *
+ * @example
+ * ```typescript
+ * // Direct token usage
+ * const repo = new WalletRepository({ token: userToken });
+ * const balance = await repo.getBalance({ wallet });
+ *
+ * // Service locator usage
+ * const repo = new WalletRepository();
+ * const wallets = await repo.getWallets();
+ * ```
+ */
+export declare class WalletRepository extends BaseRepository<typeof contract> {
+    /**
+     * Creates an instance of WalletRepository initialized with the wallet contract.
+     *
+     * @param options - Optional configuration
+     * @param options.root - Custom API root URL
+     * @param options.token - Authentication token for API calls
+     *
+     * @example
+     * ```typescript
+     * const repo = new WalletRepository({
+     *   token: "user-auth-token",
+     *   root: "base-api-url"
+     * });
+     * ```
+     */
+    constructor(options?: {
+        root?: string;
+        token?: string;
+    });
+    /**
+     * Retrieves the current available balance for a specific wallet.
+     *
+     * Supports two input methods:
+     * 1. Direct wallet object (preferred for performance)
+     * 2. Account number lookup (requires additional API call to fetch wallet details)
+     *
+     * @param props - The request properties (must provide either wallet or accountNo)
+     * @param props.wallet - The wallet object for which to retrieve the balance (preferred method)
+     * @param props.accountNo - Alternative: account number to lookup wallet and fetch balance
+     * @returns Promise that resolves to the available balance as an Amount object
+     * @throws {Error} If neither wallet nor accountNo is provided
+     * @throws {Error} If accountNo is provided but no matching wallet is found
+     * @throws {Error} If the balance fetch operation fails due to network or server errors
+     *
+     * @example
+     * ```typescript
+     * // Method 1: Using wallet object (recommended - faster)
+     * try {
+     *   const wallet = await repo.getWallets().then(w => w[0]);
+     *   const balance = await repo.getBalance({ wallet });
+     *   console.log(`Available balance: ${balance.label}`);
+     * } catch (error) {
+     *   console.error('Failed to fetch balance:', error.message);
+     * }
+     *
+     * // Method 2: Using account number (requires wallet lookup)
+     * try {
+     *   const balance = await repo.getBalance({ accountNo: '123456789' });
+     *   console.log(`Available balance: ${balance.label}`);
+     * } catch (error) {
+     *   console.error('Failed to fetch balance:', error.message);
+     * }
+     * ```
+     */
+    getBalance(props: {
+        wallet?: Wallet;
+        accountNo?: string;
+    }): Promise<Amount>;
+    /**
+     * Retrieves all wallets associated with the authenticated user.
+     *
+     * Supports flexible filtering through WalletQuery or plain filter objects.
+     *
+     * @param query - Optional query parameters for filtering wallets
+     * @returns Promise that resolves to an array of validated Wallet instances
+     * @throws {Error} If the wallet fetch operation fails or data is invalid
+     *
+     * @example
+     * ```typescript
+     * // Get all wallets
+     * const allWallets = await repo.getWallets();
+     *
+     * // Get specific wallet by account number
+     * const specificWallet = await repo.getWallets({ accountNo: '123456789' });
+     *
+     * // Get wallets with multiple filters using WalletQuery
+     * const query = WalletQuery.create()
+     *   .whereCountryCode('TZ')
+     *   .whereCurrencyCode('TZS');
+     * const tzWallets = await repo.getWallets(query);
+     *
+     * // Get wallets with filters object
+     * const usdWallets = await repo.getWallets({ currencyCode: 'USD' });
+     * ```
+     */
+    getWallets(query?: WalletQueryInput): Promise<Wallet[]>;
+    /**
+     * Retrieves a single wallet by its ID.
+     *
+     * Since the API doesn't have a dedicated /id endpoint, this method queries
+     * the list endpoint with the ID filter and returns the first result.
+     *
+     * @param id - The unique identifier of the wallet to retrieve
+     * @returns Promise that resolves to the wallet if found, undefined otherwise
+     * @throws {Error} If the fetch operation fails
+     *
+     * @example
+     * ```typescript
+     * const wallet = await repo.getByID("wallet-id");
+     * if (wallet) {
+     *   console.log(`Wallet: ${wallet.accountName}`);
+     * } else {
+     *   console.log('Wallet not found');
+     * }
+     * ```
+     */
+    getByID(id: string): Promise<Wallet | undefined>;
+    /**
+     * Retrieves wallet statement entries for a specified date range.
+     *
+     * Supports two input methods:
+     * 1. Direct wallet object (preferred for performance and currency context)
+     * 2. Account number lookup (requires additional API call to determine currency)
+     *
+     * If no date range is provided, defaults to the current month.
+     * Returns statement entries with enhanced narration objects containing payout detection
+     * and parsing capabilities.
+     *
+     * @param props - The statement request properties
+     * @param props.wallet - The wallet to get statement for (preferred method)
+     * @param props.accountNo - Alternative: account number to lookup wallet and fetch statement
+     * @param props.range - Optional date range (defaults to current month)
+     * @param props.range.startDate - Start date for statement period
+     * @param props.range.endDate - End date for statement period
+     * @returns Promise that resolves to an array of validated WalletStatementEntry instances with Narration objects
+     * @throws {Error} If neither wallet nor accountNo is provided
+     * @throws {Error} If accountNo is provided but no matching wallet is found
+     * @throws {Error} If the statement fetch operation fails or data is invalid
+     *
+     * @example
+     * ```typescript
+     * // Method 1: Using wallet object (recommended)
+     * const wallet = await repo.getWallets().then(w => w[0]);
+     * const currentMonthEntries = await repo.getStatement({ wallet });
+     *
+     * // Method 2: Using account number
+     * const entriesForAccount = await repo.getStatement({
+     *   accountNo: '123456789'
+     * });
+     *
+     * // Custom date range with wallet
+     * const customRangeEntries = await repo.getStatement({
+     *   wallet,
+     *   range: {
+     *     startDate: new Date('2024-01-01'),
+     *     endDate: new Date('2024-01-31')
+     *   }
+     * });
+     *
+     * // Process payout transactions
+     * const payoutEntries = currentMonthEntries.filter(entry => entry.isPayout);
+     * payoutEntries.forEach(entry => {
+     *   console.log(`Payout ID: ${entry.payoutId}, Amount: ${entry.amountDebited.label}`);
+     * });
+     * ```
+     */
+    getStatement(props: {
+        range?: {
+            startDate: Date;
+            endDate: Date;
+        };
+        wallet?: Wallet;
+        accountNo?: string;
+    }): Promise<WalletStatementEntry[]>;
+    /**
+     * Check if a wallet exists with the given query
+     */
+    exists(query?: WalletQueryInput): Promise<boolean>;
+    /**
+     * Get count of wallets matching a query
+     */
+    count(query?: WalletQueryInput): Promise<number>;
+}

package/dist/modules/wallet/wallet.utils.d.ts

@@ -0,0 +1,17 @@
+import { CountryCode } from "@temboplus/frontend-core";
+import { Wallet } from "./wallet.model.js";
+export declare const WalletUtils: {
+    /**
+     * Gets unique countries from a list of wallets
+     * @param wallets Array of wallets
+     * @returns Array of unique country codes
+     */
+    getUniqueCountries(wallets: Wallet[]): CountryCode[];
+    /**
+     * Gets wallets for a specific country
+     * @param wallets Array of wallets
+     * @param countryCode Country code to filter by
+     * @returns Array of wallets for the specified country
+     */
+    getWalletsByCountry(wallets: Wallet[], countryCode: CountryCode): Wallet[];
+};