@temboplus/afloat 0.1.77-beta.2 → 0.1.77-beta.21

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.2",
+  "version": "0.1.77-beta.21",
   "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.5"
   }
 }

package/dist/modules/auth/auth.manager.d.ts

@@ -1,249 +0,0 @@
-import { Permission } from "@/modules/login/permission.type.js";
-import { User } from "@/modules/auth/user.model.js";
-/**
- * Clean authentication manager for client-side usage only.
- *
- * This class provides a centralized way to manage user authentication state,
- * including login, logout, and permission checking. It uses a singleton pattern
- * for client-side usage and directly interfaces with the unified auth store.
- *
- * **Architecture:**
- * - **Client-side**: Use the singleton instance via `AfloatAuth.instance`
- * - **Server-side**: Pass tokens directly to repositories (no auth manager needed)
- *
- * **Features:**
- * - Direct integration with unified auth store
- * - React hooks for reactive UI updates
- * - Permission checking utilities
- * - Automatic wallet session management
- *
- * @example
- * ```typescript
- * // Client-side usage
- * const auth = AfloatAuth.instance;
- * const user = await auth.logIn(email, password);
- *
- * // Server-side usage (no auth manager needed)
- * const walletRepo = new WalletRepository({ token: extractedToken });
- * const balance = await walletRepo.getBalance({ wallet });
- * ```
- */
-export declare class AfloatAuth {
-    /** Client-side singleton instance */
-    private static _instance;
-    /**
-     * Private constructor to control instantiation.
-     * Use the static instance getter instead.
-     *
-     * @private
-     */
-    private constructor();
-    /**
-     * Gets or creates the client-side singleton instance.
-     *
-     * @returns The client-side singleton instance
-     *
-     * @example
-     * ```typescript
-     * const auth = AfloatAuth.instance;
-     * if (auth.currentUser) {
-     *   console.log("User is logged in");
-     * }
-     * ```
-     */
-    static get instance(): AfloatAuth;
-    /**
-     * Gets the authentication repository for API operations.
-     *
-     * @private
-     * @returns The auth repository instance with current token
-     */
-    private get repo();
-    /**
-     * Gets the current authentication token.
-     *
-     * @returns The current authentication token, or undefined if not authenticated
-     *
-     * @example
-     * ```typescript
-     * const token = auth.getUserToken();
-     * if (token) {
-     *   const apiClient = new SomeRepository({ token });
-     * }
-     * ```
-     */
-    getUserToken(): string | undefined;
-    /**
-     * Gets the currently authenticated user.
-     *
-     * @returns The current user instance, or undefined if not authenticated
-     *
-     * @example
-     * ```typescript
-     * const user = auth.currentUser;
-     * if (user) {
-     *   console.log(`Welcome, ${user.name}!`);
-     * }
-     * ```
-     */
-    get currentUser(): User | undefined;
-    /**
-     * Checks if a user is currently authenticated.
-     *
-     * @returns True if user is authenticated, false otherwise
-     *
-     * @example
-     * ```typescript
-     * if (auth.isAuthenticated) {
-     *   // User is logged in
-     *   showDashboard();
-     * } else {
-     *   // User needs to log in
-     *   showLoginForm();
-     * }
-     * ```
-     */
-    get isAuthenticated(): boolean;
-    /**
-     * React hook for accessing the current user in client-side components.
-     *
-     * This hook provides reactive updates when the user state changes,
-     * making it perfect for React components that need to respond to
-     * authentication state changes.
-     *
-     * @returns The current user with reactive updates, or undefined if not authenticated
-     * @throws {Error} If called in a server environment
-     *
-     * @example
-     * ```typescript
-     * function UserProfile() {
-     *   const user = AfloatAuth.instance.useCurrentUser();
-     *
-     *   if (!user) {
-     *     return <LoginForm />;
-     *   }
-     *
-     *   return <div>Hello, {user.name}!</div>;
-     * }
-     * ```
-     */
-    useCurrentUser(): User | undefined;
-    /**
-     * Checks if the current user has a specific permission.
-     *
-     * @param perm - The permission to check
-     * @returns True if the user has the permission, false otherwise
-     *
-     * @example
-     * ```typescript
-     * if (auth.checkPermission(Permission.ViewBalance)) {
-     *   // User can view wallet balance
-     *   const walletRepo = new WalletRepository({ token: auth.getUserToken() });
-     *   const balance = await walletRepo.getBalance(wallet);
-     * } else {
-     *   console.log("User doesn't have permission to view balance");
-     * }
-     * ```
-     */
-    checkPermission(perm: Permission): boolean;
-    /**
-     * Authenticates a user with email and password.
-     *
-     * On successful authentication:
-     * - Clears any existing auth data
-     * - Stores the new user and token atomically
-     * - Initializes related services (wallet manager)
-     *
-     * @param email - The user's email address
-     * @param password - The user's password
-     * @returns Promise resolving to the authenticated user
-     * @throws {Error} If authentication fails
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   const user = await auth.logIn("user@example.com", "password123");
-     *   console.log("Login successful!");
-     *   router.push("/dashboard");
-     * } catch (error) {
-     *   console.error("Login failed:", error.message);
-     *   setError("Invalid credentials");
-     * }
-     * ```
-     */
-    logIn(email: string, password: string): Promise<User>;
-    /**
-     * Updates the current user's password.
-     *
-     * @param currentPassword - The user's current password
-     * @param newPassword - The new password to set
-     * @returns Promise resolving to true if successful
-     * @throws {Error} If the password update fails or user is not authenticated
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   await auth.resetPassword("oldPassword", "newPassword123");
-     *   console.log("Password updated successfully");
-     *   showSuccessMessage("Password updated!");
-     * } catch (error) {
-     *   console.error("Password update failed:", error.message);
-     *   showErrorMessage("Failed to update password");
-     * }
-     * ```
-     */
-    resetPassword(currentPassword: string, newPassword: string): Promise<boolean>;
-    /**
-     * Logs out the current user and clears all authentication data.
-     *
-     * This method:
-     * - Clears user state from memory and storage
-     * - Removes authentication tokens
-     * - Resets related services
-     *
-     * @example
-     * ```typescript
-     * auth.logOut();
-     * router.push("/login");
-     * console.log("User logged out successfully");
-     * ```
-     */
-    logOut(): void;
-    /**
-     * Refreshes the current authentication state.
-     * Useful for clearing potentially stale data.
-     *
-     * @example
-     * ```typescript
-     * // Clear current state and force fresh authentication
-     * auth.refresh();
-     * ```
-     */
-    refresh(): void;
-    /**
-     * Gets debug information about the current authentication state.
-     * Useful for troubleshooting authentication issues.
-     *
-     * @returns Object containing authentication state information
-     *
-     * @example
-     * ```typescript
-     * const debugInfo = auth.getDebugInfo();
-     * console.log("Auth Debug Info:", debugInfo);
-     * ```
-     */
-    getDebugInfo(): {
-        hasUser: boolean;
-        hasToken: boolean;
-        isAuthenticated: boolean;
-        userName: string;
-        tokenLength: number;
-        managerInstance: string;
-    };
-    /**
-     * Clears all stored authentication data from the unified store.
-     *
-     * @private
-     */
-    private clearSavedData;
-}

package/dist/modules/auth/auth.store.d.ts

@@ -1,139 +0,0 @@
-import { type StoreApi, type UseBoundStore } from "zustand";
-import { User } from "@/modules/auth/user.model.js";
-/** Type definition for the store's internal state */
-type AuthState = {
-    user: string | undefined;
-    token: string | undefined;
-};
-/** Type definition for the store's actions */
-interface AuthActions {
-    setUser: (user: User) => void;
-    getUser: () => User | undefined;
-    setToken: (token: string) => void;
-    getToken: () => string | undefined;
-    setUserAndToken: (user: User, token: string) => void;
-    clearAuth: () => void;
-}
-/**
- * Unified Zustand store for managing both user and token state with persistence.
- *
- * Features:
- * - Persists both user data and token to sessionStorage
- * - Serializes/deserializes User objects to/from JSON
- * - Provides reactive state updates for React components
- * - Automatically syncs user and token state
- * - Server-side rendering safe
- */
-export declare const authStore: UseBoundStore<StoreApi<AuthState & AuthActions>>;
-/**
- * Gets the current authenticated user from the auth store.
- * This function can be called from anywhere in the application.
- *
- * @returns The current user or undefined if not authenticated
- *
- * @example
- * ```typescript
- * // In BaseRepository or any other file
- * const user = getCurrentUser();
- * if (user) {
- *   console.log(`Current user: ${user.name}`);
- * }
- * ```
- */
-export declare const getCurrentUser: () => User | undefined;
-/**
- * Gets the current authentication token from the auth store.
- * This function can be called from anywhere in the application,
- * including BaseRepository for automatic token injection.
- *
- * @returns The current token or undefined if not authenticated
- *
- * @example
- * ```typescript
- * // In BaseRepository
- * const token = getCurrentToken();
- * if (token) {
- *   // Use token for API calls
- *   return initClient(contract, { baseHeaders: { token } });
- * }
- * ```
- */
-export declare const getCurrentToken: () => string | undefined;
-/**
- * React hook to access the current user with reactive updates.
- *
- * @returns The current user or undefined if not authenticated
- * @throws {Error} If called in a server environment
- *
- * @example
- * ```typescript
- * function UserProfile() {
- *   const user = useCurrentUser();
- *
- *   if (!user) {
- *     return <div>Please log in</div>;
- *   }
- *
- *   return <div>Welcome, {user.name}!</div>;
- * }
- * ```
- */
-export declare const useCurrentUser: () => User | undefined;
-/**
- * React hook to access the current token with reactive updates.
- *
- * @returns The current token or undefined if not authenticated
- * @throws {Error} If called in a server environment
- *
- * @example
- * ```typescript
- * function SomeComponent() {
- *   const token = useCurrentToken();
- *
- *   if (!token) {
- *     return <div>Please log in</div>;
- *   }
- *
- *   // Use token...
- * }
- * ```
- */
-export declare const useCurrentToken: () => string | undefined;
-/**
- * Checks if a user is currently authenticated.
- *
- * @returns True if user is authenticated, false otherwise
- *
- * @example
- * ```typescript
- * if (isAuthenticated()) {
- *   // User is logged in
- *   showDashboard();
- * } else {
- *   // User needs to log in
- *   showLoginForm();
- * }
- * ```
- */
-export declare const isAuthenticated: () => boolean;
-/**
- * Gets debug information about the current authentication state.
- * Useful for troubleshooting authentication issues.
- *
- * @returns Object containing authentication state information
- *
- * @example
- * ```typescript
- * const debugInfo = getAuthDebugInfo();
- * console.log("Auth Debug Info:", debugInfo);
- * ```
- */
-export declare const getAuthDebugInfo: () => {
-    hasUser: boolean;
-    hasToken: boolean;
-    isAuthenticated: boolean;
-    userName: string;
-    tokenLength: number;
-    storeState: string | (AuthState & AuthActions);
-};
-export {};

package/dist/modules/auth/storage/client-store.d.ts

@@ -1,29 +0,0 @@
-import { type StoreApi, type UseBoundStore } from "zustand";
-import type { AuthStore } from "./types.js";
-import { User } from "@/modules/auth/user.model.js";
-/** Type definition for the store's state */
-type State = {
-    user: string | undefined;
-};
-/** Type definition for the store's actions */
-interface Actions {
-    setUser: (user: User) => void;
-    getUser: () => User | undefined;
-    refresh: () => void;
-}
-/**
- * Creates and exports the Zustand store directly for reactive hooks
- * @internal This should only be used by AfloatAuth
- */
-export declare const clientStore: UseBoundStore<StoreApi<State & Actions>>;
-/**
- * Creates a client-side authentication store using Zustand.
- * @returns {AuthStore} An implementation of AuthStore for client-side use
- */
-export declare const createClientStore: () => AuthStore;
-/**
- * React hook to access the current user with reactive updates.
- * @returns {User | undefined} The current user or undefined if not authenticated
- */
-export declare const useClientUser: () => User | undefined;
-export {};

package/dist/modules/auth/storage/client-token-handler.d.ts

@@ -1,31 +0,0 @@
-import type { TokenHandler } from "./types.js";
-/**
- * Client-side implementation of TokenHandler.
- * Manages tokens using sessionStorage.
- * @implements {TokenHandler}
- */
-export declare class ClientTokenHandler implements TokenHandler {
-    /** Singleton instance */
-    private static _instance;
-    /** Private constructor to enforce singleton pattern */
-    private constructor();
-    /**
-     * Gets the singleton instance of ClientTokenHandler.
-     * @returns {ClientTokenHandler} The singleton instance
-     */
-    static get instance(): ClientTokenHandler;
-    /**
-     * Retrieves the token from sessionStorage.
-     * @returns {string | undefined} The stored token or undefined if not present
-     */
-    getUserToken(): string | undefined;
-    /**
-     * Stores the token in sessionStorage.
-     * @param {string} token - The token to store
-     */
-    setUserToken(token: string): void;
-    /**
-     * Removes the token from sessionStorage.
-     */
-    clearToken(): void;
-}

package/dist/modules/auth/storage/types.d.ts

@@ -1,41 +0,0 @@
-import { User } from "../user.model.js";
-/**
- * Interface defining the contract for auth storage implementations.
- * This allows for different storage strategies in different environments.
- */
-export interface AuthStore {
-    /**
-     * Retrieves the currently authenticated user.
-     * @returns {User | undefined} The current user or undefined if not authenticated
-     */
-    getUser(): User | undefined;
-    /**
-     * Sets the current authenticated user.
-     * @param {User} user - The user to set as currently authenticated
-     */
-    setUser(user: User): void;
-    /**
-     * Clears the current authentication state.
-     */
-    refresh(): void;
-}
-/**
- * Interface defining the contract for token handling implementations.
- * This allows for different token storage strategies in different environments.
- */
-export interface TokenHandler {
-    /**
-     * Retrieves the current authentication token.
-     * @returns {string | undefined} The current token or undefined if not present
-     */
-    getUserToken(): string | undefined;
-    /**
-     * Sets the authentication token.
-     * @param {string} token - The token to store
-     */
-    setUserToken(token: string): void;
-    /**
-     * Clears the stored authentication token.
-     */
-    clearToken(): void;
-}