@appcorp/stellar-solutions-modules 0.1.34 → 0.1.35

package/global-modules/tax/types.d.ts

@@ -1,50 +1,260 @@
-import { VistaTableHeaderActionItem } from '@appcorp/app-corp-vista/type/vista-table-type';
-import { RowActionItem } from '@appcorp/app-corp-vista/type/vista-dropdown-menu-type';
-import { TaxActions } from './actions';
-import { Dispatch } from 'react';
-import { VistaFormElements } from '@appcorp/app-corp-vista/type/vista-form-elements';
-export interface MenuItem {
-    preferenceId: string;
-    label: string;
-    order: number;
-    id: string;
+/**
+ * Tax Module Types
+ *
+ * This module defines all TypeScript interfaces, types, and enums for the Tax feature.
+ * Provides type safety and clear contracts for all tax-related operations.
+ *
+ * Type Categories:
+ * - Context Types (React context and state management)
+ * - Entity Types (Backend data structures)
+ * - State Types (Frontend component state)
+ * - API Types (Request/response interfaces)
+ * - UI Types (Drawer and component enums)
+ * - Utility Types (Helper and computed types)
+ *
+ * Advanced Features:
+ * - Tax management with rate calculations
+ * - CRUD operations support
+ * - Enhanced search and pagination
+ *
+ * Naming Conventions:
+ * - Interfaces: PascalCase with descriptive suffixes (Type, State, Args)
+ * - Enums: UPPER_SNAKE_CASE for values, PascalCase for enum names
+ * - Types: PascalCase following interface conventions
+ */
+import { Dispatch } from "react";
+import { RowAction, HeaderAction } from "@/components/ui/enhanced-table";
+import { TaxActions } from "./actions";
+/**
+ * Tax Context Interface
+ *
+ * Defines the complete context API for tax state management.
+ * Includes all handlers, state getters, and utility functions.
+ */
+export interface TaxContextType {
+    byIdError?: Error;
+    byIdLoading: boolean;
+    deleteError?: Error;
+    deleteLoading: boolean;
+    listError?: Error;
+    listLoading: boolean;
+    updateError?: Error;
+    updateLoading: boolean;
+    dispatch: Dispatch<TaxActions>;
+    handleInputChange: (key: string, value: string | boolean) => void;
+    handleNextClick: () => void;
+    handlePageLimit: (k: string, v: object) => void;
+    handlePreviousClick: () => void;
+    handleSubmit: () => void;
+    clearSearch: () => void;
+    closeDrawer: () => void;
+    searchOnChange: (k: string, v: string) => void;
+    headerActions: HeaderAction[];
+    rowActions: RowAction[];
 }
-export interface Tax {
-    taxName: string;
-    taxValue: string;
-    id: string;
-    description: string;
-    preferenceId: string;
+/**
+ * Tax Backend Entity
+ *
+ * Represents the complete tax data structure as received from the API.
+ * Includes all tax-specific fields and relationships.
+ */
+export interface TaxTypeBE {
+    createdAt: string;
+    description?: string;
     enabled: boolean;
-    errors: {
-        [key: string]: string;
-    };
-    createdAt?: string;
-    updatedAt?: string;
-    loading: boolean;
+    id: string;
     isDefault: boolean;
-    btnDisableTax: boolean;
+    preference: PreferenceTypeBE;
+    preferenceId: string;
+    taxName: string;
+    taxRate: string;
+    updatedAt: string;
 }
-export type TaxForm = Omit<TaxTypeBE, 'createdAt' | 'updatedAt' | 'preference'>;
+/**
+ * Preference Backend Entity
+ *
+ * Represents preference data structure containing taxes.
+ */
+export interface PreferenceTypeBE {
+    bankingDetails: BankingDetailTypeBE[];
+    branches: BranchTypeBE[];
+    createdAt: string;
+    currencies: CurrencyTypeBE[];
+    id: string;
+    menuOrder: MenuOrderTypeBE[];
+    onboarding: boolean;
+    paymentModes: PaymentModeTypeBE[];
+    taxes: TaxTypeBE[];
+    updatedAt: string;
+}
+/**
+ * Tax Component State
+ *
+ * Complete state interface for the tax module components.
+ * Extends entity data with UI state, form state, and search capabilities.
+ */
 export interface TaxState {
-    count: number;
-    currentPage: number;
     description: string;
-    disableSaveButton: boolean;
-    drawer: null | TAX_DRAWER;
     enabled: boolean;
-    errors: {
-        [key: string]: string;
-    };
     id: string;
     isDefault: boolean;
-    pageLimit: number;
     preferenceId: string;
-    searchQuery: string;
     taxName: string;
     taxRate: string;
+    count: number;
     taxes: TaxTypeBE[];
+    currentPage: number;
+    pageLimit: number;
+    searchQuery: string;
+    disableSaveButton: boolean;
+    drawer: null | TAX_DRAWER;
+    errors: Record<string, string>;
+}
+/**
+ * Fetch Taxes API Arguments
+ *
+ * Parameters for tax list API requests.
+ * Supports pagination and search functionality.
+ */
+export interface FetchTaxesArgs {
+    currentPage: number;
+    pageLimit: number;
+    searchQuery?: string;
+}
+/**
+ * Tax API Response
+ *
+ * Standard API response format for tax operations.
+ */
+export interface TaxApiResponse {
+    data?: TaxTypeBE[];
+    count?: number;
+    error?: string;
+    success: boolean;
+}
+/**
+ * Single Tax API Response
+ *
+ * API response format for individual tax operations.
+ */
+export interface SingleTaxApiResponse {
+    data?: TaxTypeBE;
+    error?: string;
+    success: boolean;
+}
+/**
+ * Update Tax Arguments
+ *
+ * Parameters for tax update operations.
+ */
+export interface UpdateTaxArgs {
+    id: string;
+    enabled: boolean;
+}
+/**
+ * Tax Drawer Types
+ *
+ * Enumeration of all available drawer states for tax UI.
+ */
+export declare enum TAX_DRAWER {
+    FORM_DRAWER = "FORM_DRAWER"
 }
+/**
+ * Payment Types
+ *
+ * Enumeration of payment type classifications.
+ */
+export declare enum PAYMENT_TYPE {
+    FULL_PAYMENT = "FULL_PAYMENT",
+    PARTIAL_PAYMENT = "PARTIAL_PAYMENT"
+}
+/**
+ * Tax Form Fields
+ *
+ * Utility type for tax form field keys.
+ * Useful for form validation and dynamic field handling.
+ */
+export type TaxFormFields = keyof Omit<TaxTypeBE, "id" | "createdAt" | "updatedAt" | "preference">;
+/**
+ * Tax Required Fields
+ *
+ * Fields that are mandatory for tax creation.
+ */
+export type TaxRequiredFields = "taxName" | "taxRate" | "preferenceId";
+/**
+ * Tax Optional Fields
+ *
+ * Fields that are optional for tax creation.
+ */
+export type TaxOptionalFields = "description" | "enabled" | "isDefault";
+/**
+ * Tax Search Fields
+ *
+ * Fields that can be used for searching taxes.
+ */
+export type TaxSearchFields = "taxName" | "description";
+/**
+ * Tax Sort Fields
+ *
+ * Fields that can be used for sorting tax lists.
+ */
+export type TaxSortFields = "taxName" | "taxRate" | "createdAt" | "enabled" | "isDefault";
+/**
+ * Partial Tax Update
+ *
+ * Type for partial tax updates (PATCH operations).
+ */
+export type PartialTaxUpdate = Partial<Omit<TaxTypeBE, "id" | "createdAt" | "updatedAt">>;
+/**
+ * Tax Form Data
+ *
+ * Type for tax form data (excludes backend-only fields).
+ */
+export type TaxForm = Omit<TaxTypeBE, "createdAt" | "updatedAt" | "preference">;
+/**
+ * Type guard to check if object is a valid TaxTypeBE
+ */
+export declare const isTaxTypeBE: (obj: unknown) => obj is TaxTypeBE;
+/**
+ * Type guard to check if string is a valid tax drawer type
+ */
+export declare const isTaxDrawer: (value: string) => value is TAX_DRAWER;
+/**
+ * Type guard to check if string is a valid payment type
+ */
+export declare const isPaymentType: (value: string) => value is PAYMENT_TYPE;
+/**
+ * Type guard to check if object has valid tax filter structure
+ */
+export declare const isFetchTaxesArgs: (obj: unknown) => obj is FetchTaxesArgs;
+/**
+ * Check if tax is enabled
+ */
+export declare const isTaxEnabled: (tax: TaxTypeBE) => boolean;
+/**
+ * Check if tax is default
+ */
+export declare const isTaxDefault: (tax: TaxTypeBE) => boolean;
+/**
+ * Get tax display name
+ */
+export declare const getTaxDisplayName: (tax: TaxTypeBE) => string;
+/**
+ * Get tax rate as number
+ */
+export declare const getTaxRateAsNumber: (tax: TaxTypeBE) => number;
+/**
+ * Calculate tax amount
+ */
+export declare const calculateTaxAmount: (amount: number, tax: TaxTypeBE) => number;
+/**
+ * Format tax rate for display
+ */
+export declare const formatTaxRate: (tax: TaxTypeBE) => string;
+/**
+ * Legacy Banking Detail Type
+ * TODO: Move to banking-details module
+ */
 export interface BankingDetailTypeBE {
     accountNumber: string;
     accountTitle: string;
@@ -60,6 +270,10 @@ export interface BankingDetailTypeBE {
     swiftCode?: string;
     updatedAt: string;
 }
+/**
+ * Legacy Branch Type
+ * TODO: Move to branches module
+ */
 export interface BranchTypeBE {
     branchAddress: string;
     branchName: string;
@@ -74,6 +288,10 @@ export interface BranchTypeBE {
     preferenceId: string;
     updatedAt: string;
 }
+/**
+ * Legacy Currency Type
+ * TODO: Move to currencies module
+ */
 export interface CurrencyTypeBE {
     code: string;
     createdAt: string;
@@ -85,6 +303,10 @@ export interface CurrencyTypeBE {
     preferenceId: string;
     updatedAt: string;
 }
+/**
+ * Legacy Menu Order Type
+ * TODO: Move to preferences module
+ */
 export interface MenuOrderTypeBE {
     createdAt: string;
     id: string;
@@ -94,10 +316,25 @@ export interface MenuOrderTypeBE {
     preferenceId: string;
     updatedAt: string;
 }
-export declare enum PAYMENT_TYPE {
-    FULL_PAYMENT = "FULL_PAYMENT",
-    PARTIAL_PAYMENT = "PARTIAL_PAYMENT"
+/**
+ * Legacy Payment Mode Type
+ * TODO: Move to payment-modes module
+ */
+export interface PaymentModeTypeBE {
+    createdAt: string;
+    enabled: boolean;
+    id: string;
+    isDefault: boolean;
+    label: string;
+    payments?: PaymentTypeBE[];
+    preference?: PreferenceTypeBE;
+    preferenceId: string;
+    updatedAt: string;
 }
+/**
+ * Legacy Payment Type
+ * TODO: Move to payments module
+ */
 export interface PaymentTypeBE {
     amount: string;
     attachment?: string;
@@ -115,62 +352,52 @@ export interface PaymentTypeBE {
     ref: string;
     updatedAt: string;
 }
-export interface PaymentModeTypeBE {
-    createdAt: string;
-    enabled: boolean;
+/**
+ * Legacy Tax Interface
+ * TODO: Move to taxes module (current module)
+ */
+export interface Tax {
+    taxName: string;
+    taxValue: string;
     id: string;
-    isDefault: boolean;
-    label: string;
-    payments?: PaymentTypeBE[];
-    preference?: PreferenceTypeBE;
+    description: string;
     preferenceId: string;
-    updatedAt: string;
-}
-export interface TaxTypeBE {
-    createdAt: string;
-    description?: string;
     enabled: boolean;
-    id: string;
+    errors: {
+        [key: string]: string;
+    };
+    createdAt?: string;
+    updatedAt?: string;
+    loading: boolean;
     isDefault: boolean;
-    preference: PreferenceTypeBE;
-    preferenceId: string;
-    taxName: string;
-    taxRate: string;
-    updatedAt: string;
+    btnDisableTax: boolean;
 }
-export interface PreferenceTypeBE {
-    bankingDetails: BankingDetailTypeBE[];
-    branches: BranchTypeBE[];
-    createdAt: string;
-    currencies: CurrencyTypeBE[];
+/**
+ * Legacy Menu Item Interface
+ * TODO: Move to preferences module
+ */
+export interface MenuItem {
+    preferenceId: string;
+    label: string;
+    order: number;
     id: string;
-    menuOrder: MenuOrderTypeBE[];
-    onboarding: boolean;
-    paymentModes: PaymentModeTypeBE[];
-    taxes: TaxTypeBE[];
-    updatedAt: string;
-}
-export interface TaxContextType {
-    byIdError?: Error;
-    byIdLoading: boolean;
-    clearSearch: () => void;
-    closeDrawer: () => void;
-    deleteError?: Error;
-    deleteLoading: boolean;
-    dispatch: Dispatch<TaxActions>;
-    dynamicFormElements: VistaFormElements;
-    handleNextClick: () => void;
-    handlePageLimit: (k: string, v: object) => void;
-    handlePreviousClick: () => void;
-    handleSubmit: () => void;
-    headerActions: VistaTableHeaderActionItem[];
-    listError?: Error;
-    listLoading: boolean;
-    rowActions: RowActionItem[];
-    searchOnChange: (k: string, v: string) => void;
-    updateError?: Error;
-    updateLoading: boolean;
 }
+/**
+ * Legacy Currency Args
+ * TODO: Move to currencies module
+ */
+export type CurrencyArgs = {
+    id: string;
+    label: string;
+    enabled: boolean;
+    code: string;
+    isDefault: boolean;
+    preferenceId: string;
+};
+/**
+ * Legacy Create Bank Detail Args
+ * TODO: Move to banking-details module
+ */
 export interface CreateBankDetailArg {
     id: string;
     accountNumber: string;
@@ -187,6 +414,10 @@ export interface CreateBankDetailArg {
     loading: boolean;
     isDefault: boolean;
 }
+/**
+ * Legacy Create Branches Args
+ * TODO: Move to branches module
+ */
 export interface createBranchesArgs {
     personName: string;
     personEmail: string;
@@ -204,6 +435,10 @@ export interface createBranchesArgs {
     loading: boolean;
     isDefault: boolean;
 }
+/**
+ * Legacy Create Taxes Args
+ * TODO: Move to taxes module (current module)
+ */
 export interface createTaxesArgs {
     taxName: string;
     taxValue: string;
@@ -219,24 +454,18 @@ export interface createTaxesArgs {
     loading: boolean;
     isDefault: boolean;
 }
+/**
+ * Legacy Update Payment Mode Args
+ * TODO: Move to payment-modes module
+ */
 export interface updatePaymentModeArgs {
     id: string;
     enabled: boolean;
 }
-export interface MenuItem {
-    preferenceId: string;
-    label: string;
-    order: number;
-    id: string;
-}
-export type CurrencyArgs = {
-    id: string;
-    label: string;
-    enabled: boolean;
-    code: string;
-    isDefault: boolean;
-    preferenceId: string;
-};
+/**
+ * Legacy Update Currency Args
+ * TODO: Move to currencies module
+ */
 export interface updateCurrencyArgs {
     id: string;
     label: string;
@@ -245,9 +474,10 @@ export interface updateCurrencyArgs {
     isDefault: boolean;
     preferenceId: string;
 }
-export declare enum TAX_DRAWER {
-    FORM_DRAWER = "FORM_DRAWER"
-}
+/**
+ * Legacy Preference Modal Enum
+ * TODO: Move to preferences module
+ */
 export declare enum PREFERENCE_MODAL {
     DUMMY = "DUMMY"
 }