@temboplus/afloat 0.1.77-beta.6 → 0.1.77-beta.8

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

@@ -1,40 +1,74 @@
 import { ContactDTO, ContactType } from "@/modules/contact/contact.dtos.js";
 import { ContactInfo } from "./contact-info.model.js";
 /**
- * Contact class that wraps the Zod schema and provides additional functionality
+ * Contact class that wraps the Zod schema and provides additional functionality.
+ * Represents a contact entity with validation and type-safe access to contact information.
+ *
+ * @class Contact
+ *
+ * @example
+ * ```typescript
+ * // Preferred: Use static factory methods
+ * const contact = Contact.from(contactData);
+ *
+ * // From JSON
+ * const jsonContact = Contact.fromJSON(jsonString);
+ *
+ * // Type-safe access
+ * if (contact) {
+ *   console.log(contact.displayName);
+ *   console.log(contact.info?.channelName);
+ * }
+ * ```
  */
 export declare class Contact {
     private readonly data;
     /**
-     * Private constructor - use static methods to create instances
+     * Private constructor - use static factory methods to create instances.
+     *
+     * @deprecated Use {@link Contact.from} or other static factory methods instead
+     * @private
+     * @param {ContactDTO} data - Validated contact data
      */
     private constructor();
     /**
-     * Unique identifier for the contact
+     * Unique identifier for the contact.
+     *
+     * @returns {string} The contact's unique ID
      */
     get id(): string;
     /**
-     * Profile identifier associated with this contact
+     * Profile identifier associated with this contact.
+     *
+     * @returns {string} The profile ID
      */
     get profileId(): string;
     /**
-     * Display name of the contact
+     * Display name of the contact.
+     *
+     * @returns {string} The contact's display name
      */
     get displayName(): string;
     /**
-     * Type of contact (Bank or Mobile)
+     * Type of contact (Bank or Mobile).
+     *
+     * @returns {ContactType} The contact type
      */
     get type(): ContactType;
     /**
-     * Creation timestamp of the contact
+     * Creation timestamp of the contact.
+     *
+     * @returns {Date} The creation date
      */
     get createdAt(): Date;
     /**
-     * Update timestamp of the contact
+     * Update timestamp of the contact.
+     *
+     * @returns {Date} The last update date
      */
     get updatedAt(): Date;
     /**
-     * Detailed contact information based on contact type
+     * Detailed contact information based on contact type.
      *
      * @returns {ContactInfo | undefined} Contact information object:
      * - MobileContactInfo for mobile money contacts
@@ -42,12 +76,12 @@ export declare class Contact {
      * - undefined if contact information cannot be constructed
      *
      * @remarks
-     * For mobile contacts, constructs from phone number
-     * For bank contacts, constructs from SWIFT code and account number
+     * For mobile contacts, constructs from phone number.
+     * For bank contacts, constructs from SWIFT code and account number.
      */
     get info(): ContactInfo | undefined;
     /**
-     * Account number for the contact
+     * Account number for the contact.
      *
      * @returns {string} Account number:
      * - For valid contacts, returns formatted account number from ContactInfo
@@ -55,12 +89,14 @@ export declare class Contact {
      */
     get accNo(): string;
     /**
-     * Account name for the contact
-     * Always returns the display name
+     * Account name for the contact.
+     * Always returns the display name.
+     *
+     * @returns {string} The account name
      */
     get accName(): string;
     /**
-     * Label for the account number field based on contact type
+     * Label for the account number field based on contact type.
      *
      * @returns {string} Appropriate label:
      * - "Phone Number" for mobile contacts
@@ -69,7 +105,7 @@ export declare class Contact {
      */
     get accNoLabel(): string;
     /**
-     * Label for the channel field based on contact type
+     * Label for the channel field based on contact type.
      *
      * @returns {string} Appropriate label:
      * - "Channel" for mobile contacts
@@ -78,7 +114,7 @@ export declare class Contact {
      */
     get channelLabel(): string;
     /**
-     * Label for the account name field based on contact type
+     * Label for the account name field based on contact type.
      *
      * @returns {string} Appropriate label:
      * - "Full Name" for mobile contacts
@@ -86,26 +122,105 @@ export declare class Contact {
      * - "Display Name" as fallback
      */
     get accNameLabel(): string;
+    /**
+     * Human-readable channel name for the contact.
+     *
+     * @returns {string} The channel name (e.g., "M-Pesa", "CRDB") or empty string
+     */
     get channelName(): string;
     /**
-     * Creates a Contact instance from raw data
-     * @throws {ZodError} if validation fails
+     * Creates a Contact instance from raw data.
+     * This is the preferred method for creating Contact instances.
+     *
+     * @static
+     * @param {ContactDTO} data - Raw contact data to validate and wrap
+     * @returns {Contact | undefined} Contact instance or undefined if validation fails
+     *
+     * @example
+     * ```typescript
+     * const contact = Contact.from({
+     *   id: "123",
+     *   profileId: "profile-456",
+     *   displayName: "John Doe",
+     *   type: "Mobile",
+     *   accountNo: "+255712345678",
+     *   channel: "VODACOM",
+     *   createdAt: "2024-01-01T00:00:00Z",
+     *   updatedAt: "2024-01-01T00:00:00Z"
+     * });
+     * ```
+     */
+    static from(data: ContactDTO): Contact | undefined;
+    /**
+     * Creates a Contact instance from raw data, throwing on validation failure.
+     *
+     * @static
+     * @param {ContactDTO} data - Raw contact data to validate and wrap
+     * @returns {Contact} Contact instance
+     * @throws {ZodError} If validation fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const contact = Contact.create(contactData);
+     * } catch (error) {
+     *   console.error("Validation failed:", error);
+     * }
+     * ```
      */
     static create(data: ContactDTO): Contact;
     /**
-     * Creates multiple Contact instances from an array of raw data
-     * @throws {ZodError} if validation fails for any item
+     * Creates multiple Contact instances from an array of raw data.
+     *
+     * @static
+     * @param {ContactDTO[]} dataArray - Array of contact data
+     * @returns {Contact[]} Array of Contact instances
+     * @throws {ZodError} If validation fails for any item
+     *
+     * @example
+     * ```typescript
+     * const contacts = Contact.createMany([contactData1, contactData2]);
+     * ```
      */
     static createMany(dataArray: ContactDTO[]): Contact[];
     /**
-     * Creates a Contact instance from raw data without throwing
+     * Creates a Contact instance from raw data without throwing.
+     *
+     * @static
+     * @param {ContactDTO} data - Raw contact data
      * @returns {Contact | null} Contact instance or null if validation fails
+     *
+     * @example
+     * ```typescript
+     * const contact = Contact.createSafe(contactData);
+     * if (contact) {
+     *   console.log("Contact created successfully");
+     * }
+     * ```
      */
     static createSafe(data: ContactDTO): Contact | null;
+    /**
+     * Creates a Contact instance from a JSON string.
+     *
+     * @static
+     * @param {string} jsonString - JSON string containing contact data
+     * @returns {Contact | undefined} Contact instance or undefined if parsing/validation fails
+     *
+     * @example
+     * ```typescript
+     * const jsonString = '{"id":"123","displayName":"John Doe",...}';
+     * const contact = Contact.fromJSON(jsonString);
+     * if (contact) {
+     *   console.log(contact.displayName);
+     * }
+     * ```
+     */
+    static fromJSON(jsonString: string): Contact | undefined;
     /**
      * Checks if an unknown value contains valid data to construct a Contact instance.
      * This is useful when validating raw data structures before instantiation.
      *
+     * @static
      * @param {unknown} obj - The value containing potential contact data
      * @returns {obj is Contact} Type predicate indicating if a Contact can be constructed
      *
@@ -114,13 +229,10 @@ export declare class Contact {
      * const rawData = await fetchFromAPI();
      * if (Contact.canConstruct(rawData)) {
      *   const contact = Contact.create(rawData);
-     *   // TypeScript knows contact is valid here
      *   console.log(contact.displayName);
      * }
      * ```
      *
-     * @throws {never} This method never throws errors
-     *
      * @remarks
      * This method performs strict validation against the {@link ContactDTO} schema.
      */
@@ -129,6 +241,7 @@ export declare class Contact {
      * Validates if an unknown value is a Contact instance.
      * This is a runtime type guard that ensures proper object structure and data validity.
      *
+     * @static
      * @param {unknown} obj - The value to validate
      * @returns {obj is Contact} Type predicate indicating if the value is a valid Contact
      *
@@ -136,18 +249,15 @@ export declare class Contact {
      * ```typescript
      * const maybeContact = getContactFromCache();
      * if (Contact.is(maybeContact)) {
-     *   // TypeScript knows maybeContact is a Contact here
-     *   console.log(maybeContact.displayName);
+     *   console.log(maybeContact.displayName); // Type-safe
      * }
      * ```
      *
-     * @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 ContactData schema
+     * 3. Validates the data against ContactDTO schema
      * 4. Ensures the object is a proper Contact instance
      *
      * Use this method when:
@@ -158,7 +268,29 @@ export declare class Contact {
      */
     static is(obj: unknown): obj is Contact;
     /**
-     * Converts Payout instance to a plain object
+     * Converts the Contact instance to a plain object.
+     *
+     * @returns {ContactDTO} Plain object representation of the contact
+     *
+     * @example
+     * ```typescript
+     * const contact = Contact.from(contactData);
+     * const plainObject = contact?.toObject();
+     * // Use plainObject for API calls or storage
+     * ```
+     */
+    toObject(): ContactDTO;
+    /**
+     * Converts the Contact instance to a JSON string.
+     *
+     * @returns {string} JSON string representation of the contact
+     *
+     * @example
+     * ```typescript
+     * const contact = Contact.from(contactData);
+     * const jsonString = contact?.toJSON();
+     * localStorage.setItem('contact', jsonString);
+     * ```
      */
-    toJSON(): ContactDTO;
+    toJSON(): string;
 }

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

@@ -1,10 +1,14 @@
 import { Amount } from "@temboplus/frontend-core";
 import { WalletStatementEntry } from "./statement-entry.model.js";
 import { Wallet } from "./wallet.model.js";
-import { WalletDTOSchemas } from "./wallet.dtos.js";
-import { z } from "zod";
 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.
@@ -87,13 +91,9 @@ export declare class WalletRepository extends BaseRepository<typeof contract> {
     /**
      * Retrieves all wallets associated with the authenticated user.
      *
-     * Supports optional filtering through query parameters such as accountNo,
-     * status, or currency filtering.
+     * Supports flexible filtering through WalletQuery or plain filter objects.
      *
      * @param query - Optional query parameters for filtering wallets
-     * @param query.accountNo - Filter by specific account number
-     * @param query.status - Filter by wallet status (active, inactive, etc.)
-     * @param query.currencyCode - Filter by currency code
      * @returns Promise that resolves to an array of validated Wallet instances
      * @throws {Error} If the wallet fetch operation fails or data is invalid
      *
@@ -105,14 +105,38 @@ export declare class WalletRepository extends BaseRepository<typeof contract> {
      * // Get specific wallet by account number
      * const specificWallet = await repo.getWallets({ accountNo: '123456789' });
      *
-     * // Get wallets with multiple filters
-     * const activeUSDWallets = await repo.getWallets({
-     *   status: 'active',
-     *   currencyCode: 'USD'
-     * });
+     * // 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?: z.infer<typeof WalletDTOSchemas.walletQuery>): Promise<Wallet[]>;
+    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.
      *
@@ -170,4 +194,12 @@ export declare class WalletRepository extends BaseRepository<typeof contract> {
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temboplus/afloat",
-  "version": "0.1.77-beta.6",
+  "version": "0.1.77-beta.8",
   "description": "A foundational library for Temboplus-Afloat projects.",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",
@@ -58,6 +58,6 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "@temboplus/frontend-core": "^0.2.19"
+    "@temboplus/frontend-core": "^0.2.20-beta.0"
   }
 }