@temboplus/tembo-dashboard 0.0.10 → 0.0.12

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

@@ -1,11 +1,17 @@
 import { BaseRepository, PaginationDTO } from "@/lib/api";
 import { payoutContract } from "./payout.api-contract";
-import { type PayoutQueryParamsDTO } from "./payout.dtos";
 import { Payout } from "./payout.model";
-import { WalletInfo, TransactionSummary } from "@/lib/models";
+import { PayoutQuery } from "./payout.query";
+import { PayoutFilters } from "./payout.types";
+import { TransactionSummary, WalletInfo } from "@/lib/models";
+/**
+ * Flexible query input type - supports the class, filters interface, URL params, etc.
+ */
+export type PayoutQueryInput = PayoutQuery | PayoutFilters | Record<string, string> | URLSearchParams | null | undefined;
 /**
  * Repository class for managing payouts through API interactions.
- * Handles payout operations, filtering, and transaction management.
+ * Handles payout operations, filtering, and summary data retrieval.
+ * Simplified to use PayoutQuery as the primary query interface.
  */
 export declare class PayoutRepository extends BaseRepository<typeof payoutContract> {
     constructor(options?: {
@@ -13,9 +19,36 @@ export declare class PayoutRepository extends BaseRepository<typeof payoutContra
         root?: string;
     });
     /**
-     * Get all payouts with filtering and pagination
+     * Get all payouts with filtering and pagination.
+     * Accepts flexible input types and normalizes them to PayoutQuery.
+     *
+     * @param query - Query parameters in any supported format
+     * @returns Promise resolving to payouts and pagination info
+     *
+     * @example
+     * ```typescript
+     * // From API route with URL search params
+     * const { searchParams } = new URL(req.url);
+     * const result = await repo.getPayouts(searchParams);
+     *
+     * // From client with typed params
+     * const filters: PayoutFilters = { page: 1, limit: 20, status: 'PAYMENT_ACCEPTED' };
+     * const result2 = await repo.getPayouts(filters);
+     *
+     * // With PayoutQuery instance
+     * const query = PayoutQuery.create().whereSuccessful().withPagination(1, 50);
+     * const result3 = await repo.getPayouts(query);
+     * ```
+     */
+    getPayouts(query?: PayoutQueryInput): Promise<{
+        payouts: Payout[];
+        pagination: PaginationDTO;
+    }>;
+    /**
+     * Convenience method for Next.js API routes
+     * Extracts search params directly from Request object
      */
-    getPayouts(query?: PayoutQueryParamsDTO): Promise<{
+    getPayoutsFromRequest(req: Request): Promise<{
         payouts: Payout[];
         pagination: PaginationDTO;
     }>;
@@ -24,11 +57,11 @@ export declare class PayoutRepository extends BaseRepository<typeof payoutContra
      */
     getPayout(id: string): Promise<Payout>;
     /**
-     * Get payout summary statistics
+     * Get collections summary statistics
      */
-    getPayoutSummary(): Promise<TransactionSummary>;
+    getPayoutStats(): Promise<TransactionSummary>;
     /**
-     * Get account balance and status information
+     * Get wallet information
      */
-    getAccountBalance(): Promise<WalletInfo>;
+    getWalletInfo(): Promise<WalletInfo>;
 }

package/dist/modules/payout/{payout.dtos.d.ts → payout.types.d.ts}

@@ -111,7 +111,7 @@ export declare const PayoutDTOSchemas: {
         reversedTransactionId?: string | null | undefined;
         isReconciled?: number | undefined;
     }>;
-    payoutQueryParams: z.ZodObject<{
+    payoutFilters: z.ZodObject<{
         page: z.ZodDefault<z.ZodNumber>;
         limit: z.ZodDefault<z.ZodNumber>;
         sortBy: z.ZodDefault<z.ZodString>;
@@ -157,6 +157,85 @@ export declare const PayoutDTOSchemas: {
         maxAmount?: number | undefined;
         ref?: string | undefined;
     }>;
+    payoutURLQueryParams: z.ZodObject<{
+        page: z.ZodOptional<z.ZodEffects<z.ZodString, number, string>>;
+        limit: z.ZodOptional<z.ZodEffects<z.ZodString, number, string>>;
+        sortBy: z.ZodDefault<z.ZodString>;
+        sortOrder: z.ZodDefault<z.ZodEnum<["asc", "desc"]>>;
+        startDate: z.ZodOptional<z.ZodString>;
+        endDate: z.ZodOptional<z.ZodString>;
+        msisdn: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        channel: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, MOBILE_PAYOUT_CHANNEL | BANK_PAYOUT_CHANNEL, string>>;
+        status: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, PAYOUT_STATUS, string>>;
+        minAmount: z.ZodOptional<z.ZodEffects<z.ZodString, number, string>>;
+        maxAmount: z.ZodOptional<z.ZodEffects<z.ZodString, number, string>>;
+        search: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sortBy: string;
+        sortOrder: "asc" | "desc";
+        status?: PAYOUT_STATUS | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        page?: number | undefined;
+        limit?: number | undefined;
+        search?: string | undefined;
+        id?: string | undefined;
+        msisdn?: string | undefined;
+        channel?: MOBILE_PAYOUT_CHANNEL | BANK_PAYOUT_CHANNEL | undefined;
+        minAmount?: number | undefined;
+        maxAmount?: number | undefined;
+        ref?: string | undefined;
+    }, {
+        status?: string | undefined;
+        startDate?: string | undefined;
+        endDate?: string | undefined;
+        page?: string | undefined;
+        limit?: string | undefined;
+        search?: string | undefined;
+        id?: string | undefined;
+        msisdn?: string | undefined;
+        channel?: string | undefined;
+        sortBy?: string | undefined;
+        sortOrder?: "asc" | "desc" | undefined;
+        minAmount?: string | undefined;
+        maxAmount?: string | undefined;
+        ref?: string | undefined;
+    }>;
+    payoutStatus: z.ZodNativeEnum<typeof PAYOUT_STATUS>;
+    payoutChannel: z.ZodUnion<[z.ZodNativeEnum<typeof MOBILE_PAYOUT_CHANNEL>, z.ZodNativeEnum<typeof BANK_PAYOUT_CHANNEL>]>;
+    mobileChannel: z.ZodNativeEnum<typeof MOBILE_PAYOUT_CHANNEL>;
+    bankChannel: z.ZodNativeEnum<typeof BANK_PAYOUT_CHANNEL>;
+    walletSummary: z.ZodObject<{
+        balance: z.ZodNumber;
+        currency: z.ZodString;
+        lastUpdated: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        balance: number;
+        currency: string;
+        lastUpdated: string;
+    }, {
+        balance: number;
+        currency: string;
+        lastUpdated: string;
+    }>;
+    transactionSummary: z.ZodObject<{
+        yesterday: z.ZodNumber;
+        today: z.ZodNumber;
+        thisMonth: z.ZodNumber;
+        lastMonth: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        yesterday: number;
+        today: number;
+        thisMonth: number;
+        lastMonth: number;
+    }, {
+        yesterday: number;
+        today: number;
+        thisMonth: number;
+        lastMonth: number;
+    }>;
     pagination: z.ZodObject<{
         page: z.ZodNumber;
         limit: z.ZodNumber;
@@ -179,10 +258,7 @@ export declare const PayoutDTOSchemas: {
         hasNext: boolean;
         hasPrev: boolean;
     }>;
-    payoutStatus: z.ZodNativeEnum<typeof PAYOUT_STATUS>;
-    payoutChannel: z.ZodUnion<[z.ZodNativeEnum<typeof MOBILE_PAYOUT_CHANNEL>, z.ZodNativeEnum<typeof BANK_PAYOUT_CHANNEL>]>;
-    mobileChannel: z.ZodNativeEnum<typeof MOBILE_PAYOUT_CHANNEL>;
-    bankChannel: z.ZodNativeEnum<typeof BANK_PAYOUT_CHANNEL>;
 };
 export type PayoutDTO = z.infer<typeof PayoutDTOSchemas.payout>;
-export type PayoutQueryParamsDTO = z.infer<typeof PayoutDTOSchemas.payoutQueryParams>;
+export type PayoutFilters = z.infer<typeof PayoutDTOSchemas.payoutFilters>;
+export type PayoutURLQueryParams = z.infer<typeof PayoutDTOSchemas.payoutURLQueryParams>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temboplus/tembo-dashboard",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "A foundational library for Temboplus-Dashboard projects providing type-safe data layer abstraction with API contracts, domain models, and repositories.",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",

package/dist/modules/collection/collection.query-builder.d.ts

@@ -1,27 +0,0 @@
-import { QueryBuilder } from "@/lib/query";
-import { COLLECTION_STATUS, COLLECTION_CHANNEL, CollectionQueryParamsDTO } from "./collection.dtos";
-/**
- * Specialized query builder for collection queries
- */
-export declare class CollectionQueryBuilder extends QueryBuilder {
-    static create(): CollectionQueryBuilder;
-    static forCollections(): CollectionQueryBuilder;
-    static fromDTO(dto: CollectionQueryParamsDTO): CollectionQueryBuilder;
-    whereStatus(status: COLLECTION_STATUS): this;
-    whereChannel(channel: COLLECTION_CHANNEL): this;
-    wherePending(): this;
-    whereSuccessful(): this;
-    whereFailed(): this;
-    whereAmountBetween(min: number, max: number): this;
-    whereSender(msisdn: string): this;
-    whereAccount(accountNo: string): this;
-    whereReference(reference: string): this;
-    wherePartnerReference(partnerReference: string): this;
-    whereSearch(searchTerm: string): this;
-    toCollectionQuery(): CollectionQueryParamsDTO;
-    private extractFilterValues;
-    private extractSortField;
-    private extractSortOrder;
-    private isValidChannel;
-    private isValidStatus;
-}

package/dist/modules/collection/collection.query-params.model.d.ts

@@ -1,218 +0,0 @@
-import { COLLECTION_STATUS, COLLECTION_CHANNEL, CollectionQueryParamsDTO } from "./collection.dtos";
-/**
- * Collection query parameters class with built-in conversion methods.
- * Supports creation from various input types and conversion to different formats.
- */
-export declare class CollectionQueryParams {
-    readonly page: number;
-    readonly limit: number;
-    readonly sortBy: string;
-    readonly sortOrder: "asc" | "desc";
-    readonly startDate?: string;
-    readonly endDate?: string;
-    readonly msisdn?: string;
-    readonly id?: string;
-    readonly reference?: string;
-    readonly accountNo?: string;
-    readonly partnerReference?: string;
-    readonly channel?: COLLECTION_CHANNEL;
-    readonly status?: COLLECTION_STATUS;
-    readonly minAmount?: number;
-    readonly maxAmount?: number;
-    readonly search?: string;
-    constructor(params?: Partial<CollectionQueryParamsDTO>);
-    /**
-     * Robust type guard that also validates the data structure.
-     * Stricter than `is()` method - validates all properties against schema.
-     *
-     * @param obj - Object to check and validate
-     * @returns True if the object is a valid CollectionQueryParams instance with valid data
-     *
-     * @example
-     * ```typescript
-     * const validParams = new CollectionQueryParams({ page: 1, limit: 20 });
-     * const invalidParams = { page: -1, limit: 'invalid' };
-     *
-     * console.log(CollectionQueryParams.isValid(validParams)); // true
-     * console.log(CollectionQueryParams.isValid(invalidParams)); // false
-     * ```
-     */
-    static is(obj: any): obj is CollectionQueryParams;
-    /**
-     * Create from URL search parameters (strings)
-     * @param params - URL search parameters as string key-value pairs
-     * @returns New CollectionQueryParams instance
-     * @throws Error if validation fails
-     *
-     * @example
-     * ```typescript
-     * const params = CollectionQueryParams.fromUrlParams({
-     *   page: "1",
-     *   limit: "20",
-     *   status: "PAYMENT_ACCEPTED"
-     * });
-     * ```
-     */
-    static fromUrlParams(params: Record<string, string>): CollectionQueryParams;
-    /**
-     * Create from URLSearchParams object
-     * @param searchParams - URLSearchParams instance
-     * @returns New CollectionQueryParams instance
-     *
-     * @example
-     * ```typescript
-     * const url = new URL('https://api.example.com/collections?page=1&limit=20');
-     * const params = CollectionQueryParams.fromSearchParams(url.searchParams);
-     * ```
-     */
-    static fromSearchParams(searchParams: URLSearchParams): CollectionQueryParams;
-    /**
-     * Create from a Next.js Request object
-     * @param request - Next.js Request object
-     * @returns New CollectionQueryParams instance
-     *
-     * @example
-     * ```typescript
-     * // In API route
-     * export async function GET(req: Request) {
-     *   const params = CollectionQueryParams.fromRequest(req);
-     *   // use params...
-     * }
-     * ```
-     */
-    static fromRequest(request: Request): CollectionQueryParams;
-    /**
-     * Create from typed DTO object
-     * @param dto - Typed CollectionQueryParamsDTO object
-     * @returns New CollectionQueryParams instance
-     */
-    static fromDTO(dto: CollectionQueryParamsDTO): CollectionQueryParams;
-    /**
-     * Create from any supported input type
-     * @param input - Any supported input type
-     * @returns New CollectionQueryParams instance
-     *
-     * @example
-     * ```typescript
-     * // Works with all these types
-     * const params1 = CollectionQueryParams.from({ page: 1, limit: 20 });
-     * const params2 = CollectionQueryParams.from({ page: "1", limit: "20" });
-     * const params3 = CollectionQueryParams.from(new URLSearchParams("page=1"));
-     * const params4 = CollectionQueryParams.from(null); // defaults
-     * ```
-     */
-    static from(input: CollectionQueryParamsDTO | Record<string, string> | URLSearchParams | null | undefined): CollectionQueryParams;
-    /**
-     * Type guard to check if input is a string-based record
-     */
-    private static isStringRecord;
-    /**
-     * Convert to URL-safe string parameters
-     * @returns Object with string values for URLSearchParams
-     *
-     * @example
-     * ```typescript
-     * const params = new CollectionQueryParams({ page: 1, limit: 20 });
-     * const urlParams = params.toUrlParams();
-     * const queryString = new URLSearchParams(urlParams).toString();
-     * ```
-     */
-    toUrlParams(): Record<string, string>;
-    /**
-     * Convert to URLSearchParams object
-     * @returns URLSearchParams instance
-     */
-    toSearchParams(): URLSearchParams;
-    /**
-     * Convert to query string
-     * @returns URL query string (without leading ?)
-     */
-    toQueryString(): string;
-    /**
-     * Convert to typed DTO object
-     * @returns Plain object matching CollectionQueryParamsDTO interface
-     */
-    toDTO(): CollectionQueryParamsDTO;
-    /**
-     * Convert to JSON string
-     * @returns JSON string representation
-     */
-    toJSON(): string;
-    /**
-     * Create a new instance with updated pagination
-     * @param page - Page number
-     * @param limit - Items per page
-     * @returns New CollectionQueryParams instance
-     */
-    withPagination(page: number, limit?: number): CollectionQueryParams;
-    /**
-     * Create a new instance with updated sorting
-     * @param sortBy - Field to sort by
-     * @param sortOrder - Sort direction
-     * @returns New CollectionQueryParams instance
-     */
-    withSorting(sortBy: string, sortOrder?: "asc" | "desc"): CollectionQueryParams;
-    /**
-     * Create a new instance with date range filter
-     * @param startDate - Start date (ISO string)
-     * @param endDate - End date (ISO string)
-     * @returns New CollectionQueryParams instance
-     */
-    withDateRange(startDate?: string, endDate?: string): CollectionQueryParams;
-    /**
-     * Create a new instance with status filter
-     * @param status - Collection status
-     * @returns New CollectionQueryParams instance
-     */
-    withStatus(status?: COLLECTION_STATUS): CollectionQueryParams;
-    /**
-     * Create a new instance with channel filter
-     * @param channel - Collection channel
-     * @returns New CollectionQueryParams instance
-     */
-    withChannel(channel?: COLLECTION_CHANNEL): CollectionQueryParams;
-    /**
-     * Create a new instance with amount range filter
-     * @param minAmount - Minimum amount
-     * @param maxAmount - Maximum amount
-     * @returns New CollectionQueryParams instance
-     */
-    withAmountRange(minAmount?: number, maxAmount?: number): CollectionQueryParams;
-    /**
-     * Create a new instance with search filter
-     * @param search - Search term
-     * @returns New CollectionQueryParams instance
-     */
-    withSearch(search?: string): CollectionQueryParams;
-    /**
-     * Create a new instance with multiple filters
-     * @param filters - Partial filter object
-     * @returns New CollectionQueryParams instance
-     */
-    withFilters(filters: Partial<CollectionQueryParamsDTO>): CollectionQueryParams;
-    /**
-     * Reset to first page (useful when changing filters)
-     * @returns New CollectionQueryParams instance with page = 1
-     */
-    resetPage(): CollectionQueryParams;
-    /**
-     * Check if this represents the default/empty query
-     * @returns True if all values are at their defaults
-     */
-    isDefault(): boolean;
-    /**
-     * Check if any filters are applied (excluding pagination and sorting)
-     * @returns True if any filter fields are set
-     */
-    hasFilters(): boolean;
-    /**
-     * Get a summary of active filters
-     * @returns Array of human-readable filter descriptions
-     */
-    getActiveFilters(): string[];
-    /**
-     * Create a clone of this instance
-     * @returns New CollectionQueryParams instance with same values
-     */
-    clone(): CollectionQueryParams;
-}

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

@@ -1,96 +0,0 @@
-import { CollectionQueryParamsDTO } from "./collection.dtos";
-/**
- * Converts URL search parameters (string-based) to properly typed CollectionQueryParamsDTO.
- *
- * This function handles the conversion from URL search parameters (which are always strings)
- * to the typed DTO used internally. It performs validation and type conversion for:
- * - Numbers (page, limit, amounts)
- * - Enums (status, channel)
- * - Dates (startDate, endDate)
- * - Optional string fields
- *
- * @param urlParams - Raw URL search parameters as key-value string pairs
- * @returns Validated and typed CollectionQueryParamsDTO object
- *
- * @throws {ZodError} When URL parameters fail validation (invalid enum values, malformed numbers, etc.)
- *
- * @example
- * ```typescript
- * const urlParams = {
- *   page: "1",
- *   limit: "20",
- *   status: "PAYMENT_ACCEPTED",
- *   minAmount: "100.50"
- * };
- *
- * const queryParams = urlParamsToQueryParams(urlParams);
- * // Result: { page: 1, limit: 20, status: COLLECTION_STATUS.PAYMENT_ACCEPTED, minAmount: 100.5 }
- * ```
- *
- * @example
- * ```typescript
- * // Usage in API route
- * export async function GET(req: NextRequest) {
- *   const searchParams = Object.fromEntries(req.nextUrl.searchParams.entries());
- *   const queryParams = urlParamsToQueryParams(searchParams);
- *   // Now you have properly typed parameters
- * }
- * ```
- */
-declare function urlParamsToQueryParams(urlParams: Record<string, string>): CollectionQueryParamsDTO;
-/**
- * Converts typed CollectionQueryParamsDTO to URL-safe string parameters.
- *
- * This function transforms the typed DTO back into string-based key-value pairs
- * suitable for URL search parameters or form submission. It:
- * - Filters out undefined and null values
- * - Converts all values to strings
- * - Preserves the original parameter names
- *
- * @param queryParams - Typed collection query parameters
- * @returns Object with string values suitable for URLSearchParams or query string construction
- *
- * @example
- * ```typescript
- * const queryParams: CollectionQueryParamsDTO = {
- *   page: 1,
- *   limit: 20,
- *   status: COLLECTION_STATUS.PAYMENT_ACCEPTED,
- *   minAmount: 100.50,
- *   search: "test query"
- * };
- *
- * const urlParams = queryParamsToURLParams(queryParams);
- * // Result: {
- * //   page: "1",
- * //   limit: "20",
- * //   status: "PAYMENT_ACCEPTED",
- * //   minAmount: "100.5",
- * //   search: "test query"
- * // }
- * ```
- *
- * @example
- * ```typescript
- * // Usage with URLSearchParams
- * const queryParams = { page: 1, limit: 20, status: COLLECTION_STATUS.PAYMENT_ACCEPTED };
- * const urlParams = queryParamsToURLParams(queryParams);
- * const searchParams = new URLSearchParams(urlParams);
- * const queryString = searchParams.toString();
- * // Result: "page=1&limit=20&status=PAYMENT_ACCEPTED"
- * ```
- *
- * @example
- * ```typescript
- * // Usage in client-side API calls
- * const filters = { status: COLLECTION_STATUS.PENDING_ACK, minAmount: 50 };
- * const urlParams = queryParamsToURLParams(filters);
- * const response = await fetch(`/api/collections?${new URLSearchParams(urlParams)}`);
- * ```
- */
-declare function queryParamsToURLParams(queryParams: CollectionQueryParamsDTO): Record<string, string>;
-export declare const CollectionUtils: {
-    urlParamsToQueryParams: typeof urlParamsToQueryParams;
-    queryParamsToURLParams: typeof queryParamsToURLParams;
-};
-export {};

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

@@ -1,25 +0,0 @@
-import { QueryBuilder } from "@/lib/query";
-import { PAYOUT_STATUS, PAYOUT_CHANNEL, PayoutQueryParamsDTO } from "./payout.dtos";
-/**
- * Specialized query builder for payout queries
- */
-export declare class PayoutQueryBuilder extends QueryBuilder {
-    static create(): PayoutQueryBuilder;
-    static fromDTO(dto: PayoutQueryParamsDTO): PayoutQueryBuilder;
-    whereStatus(status: PAYOUT_STATUS): this;
-    whereChannel(channel: PAYOUT_CHANNEL): this;
-    wherePending(): this;
-    whereSuccessful(): this;
-    whereFailed(): this;
-    whereAmountBetween(min: number, max: number): this;
-    whereRecipient(msisdn: string): this;
-    whereReference(ref: string): this;
-    whereSearch(searchTerm: string): this;
-    toPayoutQuery(): PayoutQueryParamsDTO;
-    private extractFilterValues;
-    private extractSortField;
-    private extractSortOrder;
-    private isValidChannel;
-    private isValidStatus;
-    static forPayouts(): PayoutQueryBuilder;
-}