@pfm-platform/accounts-data-access 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,702 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
+import { AccountsResponse, Account, NetWorth, AccountCreate, AccountUpdate, NetWorthAsset, NetWorthDebt, NetWorthAccountCreate, NetWorthAccountUpdate } from '@pfm-platform/shared';
+import * as axios from 'axios';
+
+interface UseAccountsParams {
+    userId: string;
+}
+/**
+ * Fetch all accounts for a user
+ * Uses Zod validation to ensure API response matches expected schema
+ *
+ * @param params - Query parameters
+ * @param options - TanStack Query options
+ * @returns Query result with validated accounts data
+ *
+ * @example
+ * ```tsx
+ * function AccountsList() {
+ *   const { data, isLoading, error } = useAccounts({ userId: 'user123' });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {data.accounts.map(account => (
+ *         <li key={account.id}>{account.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useAccounts(params: UseAccountsParams, options?: Omit<UseQueryOptions<AccountsResponse>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<{
+    accounts: {
+        id: number;
+        name: string;
+        balance: string;
+        account_type: "checking" | "savings" | "cards" | "student_loans" | "bill" | "autos" | "home" | "investment" | "loan" | "asset" | "cd" | "money_market" | "certificates" | "commercial" | "creditline";
+        state: "active" | "closed" | "archived" | "pending_deletion";
+        aggregation_type: "finicity" | "cashedge" | "partner";
+        harvest_updated_at: string | null;
+        include_in_expenses: boolean;
+        include_in_budget: boolean;
+        include_in_cashflow: boolean;
+        include_in_dashboard: boolean;
+        include_in_goals: boolean;
+        include_in_networth: boolean;
+        fi: {
+            id: number;
+            name: string;
+        } | null;
+        cashedge_account_type: {
+            name: string;
+            acct_type: string;
+            ext_type: string;
+            group: string;
+        } | null;
+        locked_balance?: string | null | undefined;
+        preferred_balance_type?: "Available" | "Current" | "Outstanding" | null | undefined;
+        display_account_type?: string | undefined;
+        reference_id?: string | undefined;
+        error?: {
+            message: string;
+            code: string;
+            actionable: boolean;
+            description?: string | undefined;
+        } | null | undefined;
+        other_balances?: {
+            balance_type: string;
+            balance: string;
+        }[] | undefined;
+    }[];
+}, Error>;
+
+interface UseAccountParams {
+    userId: string;
+    accountId: number;
+}
+/**
+ * Fetch a single account by ID
+ * Uses Zod validation to ensure API response matches expected schema
+ *
+ * @param params - Query parameters
+ * @param options - TanStack Query options
+ * @returns Query result with validated account data
+ *
+ * @example
+ * ```tsx
+ * function AccountDetail({ accountId }: { accountId: number }) {
+ *   const { data, isLoading, error } = useAccount({
+ *     userId: 'user123',
+ *     accountId
+ *   });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h2>{data.name}</h2>
+ *       <p>Balance: ${data.balance}</p>
+ *       <p>Type: {data.account_type}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useAccount(params: UseAccountParams, options?: Omit<UseQueryOptions<Account>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<{
+    id: number;
+    name: string;
+    balance: string;
+    account_type: "checking" | "savings" | "cards" | "student_loans" | "bill" | "autos" | "home" | "investment" | "loan" | "asset" | "cd" | "money_market" | "certificates" | "commercial" | "creditline";
+    state: "active" | "closed" | "archived" | "pending_deletion";
+    aggregation_type: "finicity" | "cashedge" | "partner";
+    harvest_updated_at: string | null;
+    include_in_expenses: boolean;
+    include_in_budget: boolean;
+    include_in_cashflow: boolean;
+    include_in_dashboard: boolean;
+    include_in_goals: boolean;
+    include_in_networth: boolean;
+    fi: {
+        id: number;
+        name: string;
+    } | null;
+    cashedge_account_type: {
+        name: string;
+        acct_type: string;
+        ext_type: string;
+        group: string;
+    } | null;
+    locked_balance?: string | null | undefined;
+    preferred_balance_type?: "Available" | "Current" | "Outstanding" | null | undefined;
+    display_account_type?: string | undefined;
+    reference_id?: string | undefined;
+    error?: {
+        message: string;
+        code: string;
+        actionable: boolean;
+        description?: string | undefined;
+    } | null | undefined;
+    other_balances?: {
+        balance_type: string;
+        balance: string;
+    }[] | undefined;
+}, Error>;
+
+interface UseNetWorthParams {
+    userId: string;
+}
+/**
+ * Fetch net worth summary for a user
+ * Includes: assets, debts, history, and summary metadata
+ * Uses Zod validation to ensure API response matches expected schema
+ *
+ * @param params - Query parameters
+ * @param options - TanStack Query options
+ * @returns Query result with validated net worth data
+ *
+ * @example
+ * ```tsx
+ * function NetWorthSummary() {
+ *   const { data, isLoading, error } = useNetWorth({ userId: 'user123' });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h2>Net Worth: {data.meta.net_worth}</h2>
+ *       <p>Total Assets: {data.meta.total_assets}</p>
+ *       <p>Total Debts: {data.meta.total_debts}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useNetWorth(params: UseNetWorthParams, options?: Omit<UseQueryOptions<NetWorth>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<{
+    meta: {
+        net_worth: string;
+        net_worth_change: string;
+        total_assets: string;
+        total_debts: string;
+    };
+    assets: {
+        id: number;
+        name: string;
+        balance: string;
+        additional_networth_account: boolean;
+    }[];
+    debts: {
+        id: number;
+        name: string;
+        balance: string;
+        additional_networth_account: boolean;
+    }[];
+    networth_histories: {
+        total: string;
+        total_asset: string;
+        total_debt: string;
+        month: string;
+        year: string;
+        since_last_month: string;
+    }[];
+}, Error>;
+
+/**
+ * Parameters for useCreateAccount mutation
+ */
+interface CreateAccountParams {
+    userId: string;
+    data: AccountCreate;
+}
+/**
+ * Mutation hook for creating a new account
+ *
+ * Creates an account manually for testing purposes.
+ * Uses mode switching for validation:
+ * - Admin mode: Minimal validation for test data creation
+ * - User mode: Full validation with business rules
+ *
+ * @example
+ * ```tsx
+ * const createAccount = useCreateAccount();
+ *
+ * createAccount.mutate({
+ *   userId: 'user123',
+ *   data: {
+ *     name: 'Test Checking',
+ *     balance: '1000.00',
+ *     account_type: 'checking',
+ *     state: 'active',
+ *     aggregation_type: 'partner',
+ *     include_in_expenses: true,
+ *     include_in_budget: true,
+ *     include_in_cashflow: true,
+ *     include_in_dashboard: true,
+ *     include_in_goals: false,
+ *     include_in_networth: true
+ *   }
+ * });
+ * ```
+ */
+declare function useCreateAccount(options?: Omit<UseMutationOptions<Account, Error, CreateAccountParams>, 'mutationFn'>): _tanstack_react_query.UseMutationResult<{
+    id: number;
+    name: string;
+    balance: string;
+    account_type: "checking" | "savings" | "cards" | "student_loans" | "bill" | "autos" | "home" | "investment" | "loan" | "asset" | "cd" | "money_market" | "certificates" | "commercial" | "creditline";
+    state: "active" | "closed" | "archived" | "pending_deletion";
+    aggregation_type: "finicity" | "cashedge" | "partner";
+    harvest_updated_at: string | null;
+    include_in_expenses: boolean;
+    include_in_budget: boolean;
+    include_in_cashflow: boolean;
+    include_in_dashboard: boolean;
+    include_in_goals: boolean;
+    include_in_networth: boolean;
+    fi: {
+        id: number;
+        name: string;
+    } | null;
+    cashedge_account_type: {
+        name: string;
+        acct_type: string;
+        ext_type: string;
+        group: string;
+    } | null;
+    locked_balance?: string | null | undefined;
+    preferred_balance_type?: "Available" | "Current" | "Outstanding" | null | undefined;
+    display_account_type?: string | undefined;
+    reference_id?: string | undefined;
+    error?: {
+        message: string;
+        code: string;
+        actionable: boolean;
+        description?: string | undefined;
+    } | null | undefined;
+    other_balances?: {
+        balance_type: string;
+        balance: string;
+    }[] | undefined;
+}, Error, CreateAccountParams, unknown>;
+
+interface UpdateAccountParams {
+    userId: string;
+    accountId: number;
+    data: AccountUpdate;
+}
+/**
+ * Update an existing account
+ * Validates input with Zod schema and invalidates related queries on success
+ *
+ * @param options - TanStack Mutation options
+ * @returns Mutation result
+ *
+ * @example
+ * ```tsx
+ * function AccountEditForm({ account }: { account: Account }) {
+ *   const updateAccount = useUpdateAccount();
+ *
+ *   const handleSubmit = (formData) => {
+ *     updateAccount.mutate({
+ *       userId: 'user123',
+ *       accountId: account.id,
+ *       data: {
+ *         nickname: formData.nickname,
+ *         goal_amount: formData.goalAmount,
+ *       }
+ *     }, {
+ *       onSuccess: () => {
+ *         toast.success('Account updated!');
+ *       },
+ *       onError: (error) => {
+ *         toast.error(`Failed to update: ${error.message}`);
+ *       }
+ *     });
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ */
+declare function useUpdateAccount(options?: Omit<UseMutationOptions<Account, Error, UpdateAccountParams>, 'mutationFn'>): _tanstack_react_query.UseMutationResult<{
+    id: number;
+    name: string;
+    balance: string;
+    account_type: "checking" | "savings" | "cards" | "student_loans" | "bill" | "autos" | "home" | "investment" | "loan" | "asset" | "cd" | "money_market" | "certificates" | "commercial" | "creditline";
+    state: "active" | "closed" | "archived" | "pending_deletion";
+    aggregation_type: "finicity" | "cashedge" | "partner";
+    harvest_updated_at: string | null;
+    include_in_expenses: boolean;
+    include_in_budget: boolean;
+    include_in_cashflow: boolean;
+    include_in_dashboard: boolean;
+    include_in_goals: boolean;
+    include_in_networth: boolean;
+    fi: {
+        id: number;
+        name: string;
+    } | null;
+    cashedge_account_type: {
+        name: string;
+        acct_type: string;
+        ext_type: string;
+        group: string;
+    } | null;
+    locked_balance?: string | null | undefined;
+    preferred_balance_type?: "Available" | "Current" | "Outstanding" | null | undefined;
+    display_account_type?: string | undefined;
+    reference_id?: string | undefined;
+    error?: {
+        message: string;
+        code: string;
+        actionable: boolean;
+        description?: string | undefined;
+    } | null | undefined;
+    other_balances?: {
+        balance_type: string;
+        balance: string;
+    }[] | undefined;
+}, Error, UpdateAccountParams, unknown>;
+
+interface DeleteAccountParams {
+    userId: string;
+    accountId: number;
+}
+/**
+ * Delete an account
+ * Removes account from user's account list
+ * Invalidates related queries on success
+ *
+ * @param options - TanStack Mutation options
+ * @returns Mutation result
+ *
+ * @example
+ * ```tsx
+ * function AccountDeleteButton({ accountId }: { accountId: number }) {
+ *   const deleteAccount = useDeleteAccount();
+ *
+ *   const handleDelete = () => {
+ *     if (confirm('Are you sure you want to delete this account?')) {
+ *       deleteAccount.mutate({
+ *         userId: 'user123',
+ *         accountId
+ *       }, {
+ *         onSuccess: () => {
+ *           toast.success('Account deleted successfully');
+ *           navigate('/accounts');
+ *         },
+ *         onError: (error) => {
+ *           toast.error(`Failed to delete: ${error.message}`);
+ *         }
+ *       });
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleDelete} disabled={deleteAccount.isPending}>
+ *       {deleteAccount.isPending ? 'Deleting...' : 'Delete Account'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useDeleteAccount(options?: Omit<UseMutationOptions<void, Error, DeleteAccountParams>, 'mutationFn'>): _tanstack_react_query.UseMutationResult<void, Error, DeleteAccountParams, unknown>;
+
+interface ArchiveAccountParams {
+    userId: string;
+    accountId: number;
+}
+/**
+ * Archive an account (soft delete)
+ * Changes account state to 'archived' instead of permanently deleting
+ * Invalidates related queries on success
+ *
+ * @param options - TanStack Mutation options
+ * @returns Mutation result
+ *
+ * @example
+ * ```tsx
+ * function AccountArchiveButton({ accountId }: { accountId: number }) {
+ *   const archiveAccount = useArchiveAccount();
+ *
+ *   const handleArchive = () => {
+ *     archiveAccount.mutate({
+ *       userId: 'user123',
+ *       accountId
+ *     }, {
+ *       onSuccess: (archivedAccount) => {
+ *         toast.success(`${archivedAccount.name} archived`);
+ *       },
+ *       onError: (error) => {
+ *         toast.error(`Failed to archive: ${error.message}`);
+ *       }
+ *     });
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleArchive} disabled={archiveAccount.isPending}>
+ *       {archiveAccount.isPending ? 'Archiving...' : 'Archive Account'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useArchiveAccount(options?: Omit<UseMutationOptions<Account, Error, ArchiveAccountParams>, 'mutationFn'>): _tanstack_react_query.UseMutationResult<{
+    id: number;
+    name: string;
+    balance: string;
+    account_type: "checking" | "savings" | "cards" | "student_loans" | "bill" | "autos" | "home" | "investment" | "loan" | "asset" | "cd" | "money_market" | "certificates" | "commercial" | "creditline";
+    state: "active" | "closed" | "archived" | "pending_deletion";
+    aggregation_type: "finicity" | "cashedge" | "partner";
+    harvest_updated_at: string | null;
+    include_in_expenses: boolean;
+    include_in_budget: boolean;
+    include_in_cashflow: boolean;
+    include_in_dashboard: boolean;
+    include_in_goals: boolean;
+    include_in_networth: boolean;
+    fi: {
+        id: number;
+        name: string;
+    } | null;
+    cashedge_account_type: {
+        name: string;
+        acct_type: string;
+        ext_type: string;
+        group: string;
+    } | null;
+    locked_balance?: string | null | undefined;
+    preferred_balance_type?: "Available" | "Current" | "Outstanding" | null | undefined;
+    display_account_type?: string | undefined;
+    reference_id?: string | undefined;
+    error?: {
+        message: string;
+        code: string;
+        actionable: boolean;
+        description?: string | undefined;
+    } | null | undefined;
+    other_balances?: {
+        balance_type: string;
+        balance: string;
+    }[] | undefined;
+}, Error, ArchiveAccountParams, unknown>;
+
+/**
+ * Parameters for useCreateNetWorthAccount mutation
+ */
+interface CreateNetWorthAccountParams {
+    userId: string;
+    data: NetWorthAccountCreate;
+}
+/**
+ * Mutation hook for creating a manual net worth account
+ *
+ * Creates a manual asset or debt account for net worth tracking.
+ * Returns either an asset or debt object depending on account_type.
+ *
+ * @example
+ * ```tsx
+ * const createAccount = useCreateNetWorthAccount();
+ *
+ * // Create asset
+ * createAccount.mutate({
+ *   userId: 'user123',
+ *   data: {
+ *     networth_account: {
+ *       account_type: 'asset',
+ *       balance: '250000.00',
+ *       name: 'My House'
+ *     }
+ *   }
+ * });
+ *
+ * // Create debt
+ * createAccount.mutate({
+ *   userId: 'user123',
+ *   data: {
+ *     networth_account: {
+ *       account_type: 'debt',
+ *       balance: '15000.00',
+ *       name: 'Car Loan'
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function useCreateNetWorthAccount(options?: Omit<UseMutationOptions<NetWorthAsset | NetWorthDebt, Error, CreateNetWorthAccountParams>, 'mutationFn'>): _tanstack_react_query.UseMutationResult<{
+    id: number;
+    name: string;
+    balance: string;
+    additional_networth_account: boolean;
+}, Error, CreateNetWorthAccountParams, unknown>;
+
+/**
+ * Parameters for useUpdateNetWorthAccount mutation
+ */
+interface UpdateNetWorthAccountParams {
+    userId: string;
+    accountId: number;
+    data: NetWorthAccountUpdate;
+}
+/**
+ * Mutation hook for updating a manual net worth account
+ *
+ * Updates name, balance, or account type for a manual net worth account.
+ * All fields are optional - only provided fields will be updated.
+ *
+ * @example
+ * ```tsx
+ * const updateAccount = useUpdateNetWorthAccount();
+ *
+ * // Update only balance
+ * updateAccount.mutate({
+ *   userId: 'user123',
+ *   accountId: 5,
+ *   data: {
+ *     networth_account: {
+ *       balance: '260000.00'
+ *     }
+ *   }
+ * });
+ *
+ * // Update name and type
+ * updateAccount.mutate({
+ *   userId: 'user123',
+ *   accountId: 5,
+ *   data: {
+ *     networth_account: {
+ *       name: 'Updated House Name',
+ *       account_type: 'debt'
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function useUpdateNetWorthAccount(options?: Omit<UseMutationOptions<NetWorthAsset | NetWorthDebt, Error, UpdateNetWorthAccountParams>, 'mutationFn'>): _tanstack_react_query.UseMutationResult<{
+    id: number;
+    name: string;
+    balance: string;
+    additional_networth_account: boolean;
+}, Error, UpdateNetWorthAccountParams, unknown>;
+
+/**
+ * Parameters for useDeleteNetWorthAccount mutation
+ */
+interface DeleteNetWorthAccountParams {
+    userId: string;
+    accountId: number;
+}
+/**
+ * Mutation hook for deleting a manual net worth account
+ *
+ * Permanently deletes a manual asset or debt account from net worth tracking.
+ * This operation cannot be undone.
+ *
+ * @example
+ * ```tsx
+ * const deleteAccount = useDeleteNetWorthAccount();
+ *
+ * deleteAccount.mutate({
+ *   userId: 'user123',
+ *   accountId: 5
+ * }, {
+ *   onSuccess: () => {
+ *     console.log('Net worth account deleted successfully');
+ *   }
+ * });
+ * ```
+ */
+declare function useDeleteNetWorthAccount(options?: Omit<UseMutationOptions<void, Error, DeleteNetWorthAccountParams>, 'mutationFn'>): _tanstack_react_query.UseMutationResult<void, Error, DeleteNetWorthAccountParams, unknown>;
+
+/**
+ * Query key factory for Accounts domain
+ * Following TanStack Query best practices for hierarchical cache keys
+ *
+ * Key structure:
+ * - ['accounts'] - Root key for all account queries
+ * - ['accounts', 'list', userId] - List of accounts for a user
+ * - ['accounts', 'detail', userId, accountId] - Single account detail
+ * - ['accounts', 'investments', userId, accountId] - Account investments
+ * - ['accounts', 'transactions', userId, accountId, page] - Account transactions
+ */
+declare const accountKeys: {
+    /**
+     * Root key for all account-related queries
+     */
+    all: readonly ["accounts"];
+    /**
+     * Key for all account list queries
+     */
+    lists: () => readonly ["accounts", "list"];
+    /**
+     * Key for a specific user's account list
+     * @param userId - User ID
+     */
+    list: (userId: string) => readonly ["accounts", "list", string];
+    /**
+     * Key for all account detail queries
+     */
+    details: () => readonly ["accounts", "detail"];
+    /**
+     * Key for a specific account detail
+     * @param userId - User ID
+     * @param accountId - Account ID
+     */
+    detail: (userId: string, accountId: number) => readonly ["accounts", "detail", string, number];
+    /**
+     * Key for all account investment queries
+     */
+    investments: () => readonly ["accounts", "investments"];
+    /**
+     * Key for a specific account's investments
+     * @param userId - User ID
+     * @param accountId - Account ID
+     */
+    investment: (userId: string, accountId: number) => readonly ["accounts", "investments", string, number];
+    /**
+     * Key for all account transaction queries
+     */
+    transactions: () => readonly ["accounts", "transactions"];
+    /**
+     * Key for a specific account's transactions
+     * @param userId - User ID
+     * @param accountId - Account ID
+     * @param page - Page number for pagination
+     */
+    transaction: (userId: string, accountId: number, page: number) => readonly ["accounts", "transactions", string, number, number];
+    /**
+     * Key for all net worth queries
+     */
+    networth: () => readonly ["accounts", "networth"];
+    /**
+     * Key for a specific user's net worth summary
+     * @param userId - User ID
+     */
+    networthSummary: (userId: string) => readonly ["accounts", "networth", string];
+    /**
+     * Key for all net worth account queries
+     */
+    networthAccounts: () => readonly ["accounts", "networth", "accounts"];
+    /**
+     * Key for a specific net worth account
+     * @param userId - User ID
+     * @param accountId - Net worth account ID
+     */
+    networthAccount: (userId: string, accountId: number) => readonly ["accounts", "networth", "accounts", string, number];
+};
+
+/**
+ * Base API client for Accounts domain
+ * Uses axios with interceptors for auth and error handling
+ */
+/**
+ * Axios instance configured for PFM API
+ * Base URL can be overridden via VITE_API_BASE_URL environment variable
+ */
+declare const api: axios.AxiosInstance;
+
+export { type ArchiveAccountParams, type CreateAccountParams, type CreateNetWorthAccountParams, type DeleteAccountParams, type DeleteNetWorthAccountParams, type UpdateAccountParams, type UpdateNetWorthAccountParams, type UseAccountParams, type UseAccountsParams, type UseNetWorthParams, accountKeys, api, useAccount, useAccounts, useArchiveAccount, useCreateAccount, useCreateNetWorthAccount, useDeleteAccount, useDeleteNetWorthAccount, useNetWorth, useUpdateAccount, useUpdateNetWorthAccount };