@mysteryinfosolutions/api-core 1.8.0 → 1.9.0

package/index.d.ts

@@ -1,8 +1,36 @@
 import * as i0 from '@angular/core';
+import { InjectionToken } from '@angular/core';
 import { Observable } from 'rxjs';
-import { HttpClient } from '@angular/common/http';
+import { HttpClient, HttpErrorResponse, HttpInterceptorFn } from '@angular/common/http';
 
-interface TableColumn<T = any> {
+/**
+ * Configuration for a table column.
+ *
+ * @template T The type of data row this column applies to
+ *
+ * @example
+ * const columns: TableColumn<User>[] = [
+ *   {
+ *     key: 'name',
+ *     label: 'Full Name',
+ *     isSortable: true,
+ *     width: '200px'
+ *   },
+ *   {
+ *     key: 'email',
+ *     label: 'Email Address',
+ *     type: 'text',
+ *     hideOnMobile: true
+ *   },
+ *   {
+ *     key: 'createdAt',
+ *     label: 'Created',
+ *     pipe: 'date',
+ *     valueGetter: (row) => row.createdAt
+ *   }
+ * ];
+ */
+interface TableColumn<T = Record<string, unknown>> {
     /** Unique key used to identify the column */
     key: keyof T | string;
     /** Display label for the column header */
@@ -13,74 +41,252 @@ interface TableColumn<T = any> {
     width?: string;
     /** Type of cell rendering */
     type?: 'text' | 'checkbox' | 'action' | 'custom';
-    /** Function to extract value from row */
-    valueGetter?: (row: T) => any;
+    /** Function to extract value from row - return type can be any displayable value */
+    valueGetter?: (row: T) => string | number | boolean | Date | null | undefined;
     /** Whether to hide the column on mobile screen sizes */
     hideOnMobile?: boolean;
     /** Optional Angular pipe to apply to the value */
-    pipe?: 'date' | 'currency' | 'uppercase' | 'lowercase' | string;
+    pipe?: 'date' | 'currency' | 'uppercase' | 'lowercase' | 'number' | 'percent' | string;
     /** CSS class to apply to cell */
     cellClass?: string;
     /** CSS class to apply to header */
     headerClass?: string;
     /** Whether the column should be visible at all (default: true) */
     visible?: boolean;
+    /** Alignment for cell content */
+    align?: 'left' | 'center' | 'right';
+    /** Whether the column is sticky (remains visible when scrolling) */
+    sticky?: boolean;
 }
 
+/**
+ * Enum defining column selection modes for API queries.
+ *
+ * @remarks
+ * Used to control which columns are returned in API responses,
+ * useful for optimizing payload size and performance.
+ *
+ * @example
+ * const filter = {
+ *   selectMode: SELECT_MODE.ONLYCOLUMNS,
+ *   selectColumns: 'id,name,email'
+ * };
+ */
 declare enum SELECT_MODE {
+    /** Return all columns (default behavior) */
     ALL = 1,
+    /** Return only specified columns via selectColumns parameter */
     ONLYCOLUMNS = 2
 }
 
+/**
+ * Base filter class providing common filtering, pagination, and sorting capabilities.
+ *
+ * @remarks
+ * Extend this class in your custom filter types to add domain-specific filter properties.
+ * The base filter handles pagination, sorting, searching, and date range filtering.
+ *
+ * @example
+ * interface UserFilter extends Filter {
+ *   role?: string;
+ *   isActive?: boolean;
+ *   departmentId?: number;
+ * }
+ *
+ * const filter: UserFilter = {
+ *   page: 1,
+ *   pageLength: 25,
+ *   search: 'john',
+ *   role: 'admin',
+ *   sort: [new SortItem('name', 'ASC')]
+ * };
+ */
 declare abstract class Filter {
+    /** Array of specific IDs to filter by */
     ids?: number[];
+    /** Column name to use for date range filtering */
     dateRangeColumn?: string;
+    /** Start date for date range filter (ISO format) */
     dateRangeFrom?: string;
+    /** End date for date range filter (ISO format) */
     dateRangeTo?: string;
+    /** Current page number (1-based) */
     page?: number;
+    /** Number of records per page */
     pageLength?: number;
+    /** Array of sort configurations */
     sort?: SortItem[];
+    /** Search query string */
     search?: string;
+    /** Comma-separated list of columns to search in */
     searchColumns?: string;
+    /** Comma-separated list of columns to select/return */
     selectColumns?: string;
+    /** Mode for column selection */
     selectMode?: SELECT_MODE;
-    [key: string]: string | number | number[] | SortItem[] | SELECT_MODE | boolean | undefined;
 }
 
+/**
+ * Standard error object returned by the API.
+ *
+ * @example
+ * {
+ *   code: 'VALIDATION_ERROR',
+ *   message: 'Invalid email address',
+ *   details: 'Email must be in valid format',
+ *   showMessageToUser: true
+ * }
+ */
 interface IMisError {
+    /** Short error identifier */
     error?: string;
+    /** Error code for programmatic handling */
     code?: string;
+    /** Human-readable error message */
     message?: string;
+    /** Detailed error information */
     details?: string;
-    stack?: any;
+    /** Stack trace (only in development) */
+    stack?: string | Record<string, unknown>;
+    /** Default fallback message */
     defaultMessage?: string;
+    /** Whether this error should be displayed to the user */
     showMessageToUser?: boolean;
 }
+/**
+ * Pagination metadata returned with multi-result responses.
+ *
+ * @example
+ * {
+ *   totalRecords: 150,
+ *   currentPage: 2,
+ *   lastPage: 15,
+ *   perPage: 10,
+ *   next: 3,
+ *   previous: 1
+ * }
+ */
 interface IMultiresultMetaData {
+    /** Total number of records across all pages */
     totalRecords: number;
+    /** Previous page number (if exists) */
     previous?: number;
+    /** Current page number */
     currentPage?: number;
+    /** Next page number (if exists) */
     next?: number;
+    /** Number of records per page */
     perPage?: number;
+    /** Current segment/batch number */
     segment?: number;
+    /** Last page number */
     lastPage?: number;
 }
+/**
+ * Container for paginated list responses.
+ *
+ * @template T The type of records in the list
+ *
+ * @example
+ * const response: IMultiresult<User> = {
+ *   records: [
+ *     { id: 1, name: 'John' },
+ *     { id: 2, name: 'Jane' }
+ *   ],
+ *   pager: {
+ *     totalRecords: 100,
+ *     currentPage: 1,
+ *     lastPage: 10,
+ *     perPage: 10
+ *   }
+ * };
+ */
 interface IMultiresult<T> {
+    /** Array of records for the current page */
     records: T[];
+    /** Pagination metadata */
     pager: IMultiresultMetaData;
 }
+/**
+ * Standard API response wrapper.
+ *
+ * @template T The type of data contained in the response
+ *
+ * @example
+ * // Success response
+ * const response: IResponse<User> = {
+ *   status: 200,
+ *   data: { id: 1, name: 'John' },
+ *   infoDtls: null
+ * };
+ *
+ * // Error response
+ * const errorResponse: IResponse<User> = {
+ *   status: 400,
+ *   data: null,
+ *   error: {
+ *     code: 'VALIDATION_ERROR',
+ *     message: 'Invalid input'
+ *   }
+ * };
+ */
 interface IResponse<T> {
+    /** HTTP status code */
     status?: number;
+    /** Response data (null if error occurred) */
     data?: T | null;
+    /** Error information (present if request failed) */
     error?: IMisError;
-    infoDtls?: any;
+    /** Additional information or metadata */
+    infoDtls?: Record<string, unknown> | null;
 }
+/**
+ * Type alias for paginated list responses.
+ *
+ * @template T The type of records in the list
+ */
 type PagedResponse<T> = IResponse<IMultiresult<T>>;
+/**
+ * Type alias for single record responses.
+ *
+ * @template T The type of the record
+ */
 type SingleResponse<T> = IResponse<T>;
 
+/**
+ * Represents a single sort configuration for a field.
+ *
+ * @remarks
+ * Used in filter objects to specify sorting criteria.
+ * Multiple SortItem instances can be combined for multi-column sorting.
+ *
+ * @example
+ * // Single sort
+ * const sort = new SortItem('name', 'ASC');
+ *
+ * @example
+ * // Multi-column sort
+ * const sorts = [
+ *   new SortItem('priority', 'DESC'),
+ *   new SortItem('createdAt', 'DESC'),
+ *   new SortItem('name', 'ASC')
+ * ];
+ *
+ * const filter = {
+ *   page: 1,
+ *   pageLength: 25,
+ *   sort: sorts
+ * };
+ */
 declare class SortItem {
     field: string;
     order: 'ASC' | 'DESC';
+    /**
+     * Creates a sort configuration.
+     *
+     * @param field The field/column name to sort by
+     * @param order Sort direction: 'ASC' (ascending) or 'DESC' (descending)
+     */
     constructor(field: string, order: 'ASC' | 'DESC');
 }
 
@@ -150,6 +356,143 @@ declare abstract class BaseResourceConfig<T> {
     permissions: Record<StandardPermission | string, string>;
 }
 
+/**
+ * Configuration options for the api-core library.
+ *
+ * @example
+ * // In your app.config.ts or module providers
+ * import { API_CORE_CONFIG, ApiCoreConfig } from '@mysteryinfosolutions/api-core';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     {
+ *       provide: API_CORE_CONFIG,
+ *       useValue: {
+ *         pagination: {
+ *           defaultPage: 1,
+ *           defaultPageLength: 25,
+ *           pageLengthOptions: [25, 50, 100]
+ *         },
+ *         api: {
+ *           dateFormat: 'iso',
+ *           includeCredentials: true
+ *         }
+ *       } as ApiCoreConfig
+ *     }
+ *   ]
+ * };
+ */
+interface ApiCoreConfig {
+    /**
+     * Pagination configuration defaults
+     */
+    pagination?: {
+        /** Default page number (1-based) */
+        defaultPage?: number;
+        /** Default number of items per page */
+        defaultPageLength?: number;
+        /** Available page length options for user selection */
+        pageLengthOptions?: number[];
+        /** Maximum allowed page length (to prevent large requests) */
+        maxPageLength?: number;
+    };
+    /**
+     * API request/response configuration
+     */
+    api?: {
+        /** Date format for API requests ('iso' | 'timestamp' | 'custom') */
+        dateFormat?: 'iso' | 'timestamp' | 'custom';
+        /** Custom date formatter function (if dateFormat is 'custom') */
+        dateFormatter?: (date: Date) => string;
+        /** Whether to include credentials in requests */
+        includeCredentials?: boolean;
+        /** Default headers to include in all requests */
+        defaultHeaders?: Record<string, string>;
+        /** Request timeout in milliseconds */
+        timeout?: number;
+    };
+    /**
+     * Query string formatting options
+     */
+    queryString?: {
+        /** Format for array parameters ('brackets' | 'comma' | 'repeat') */
+        arrayFormat?: 'brackets' | 'comma' | 'repeat';
+        /** Custom array formatter function */
+        arrayFormatter?: (key: string, values: unknown[]) => string;
+        /** Whether to encode query parameters */
+        encode?: boolean;
+        /** Custom encoder function */
+        encoder?: (value: string) => string;
+    };
+    /**
+     * Sort configuration
+     */
+    sort?: {
+        /** Default sort order */
+        defaultOrder?: 'ASC' | 'DESC';
+        /** Separator between field and order in query string */
+        separator?: string;
+        /** Whether to allow multi-column sorting */
+        allowMultiSort?: boolean;
+    };
+    /**
+     * Error handling configuration
+     */
+    errorHandling?: {
+        /** Whether to log errors to console */
+        logErrors?: boolean;
+        /** Whether to show user-friendly error messages */
+        showUserMessages?: boolean;
+        /** Global error handler function */
+        onError?: (error: unknown) => void;
+    };
+    /**
+     * Loading state configuration
+     */
+    loading?: {
+        /** Minimum loading time in ms (prevents flash of loading state) */
+        minLoadingTime?: number;
+        /** Whether to show loading indicators by default */
+        showLoadingByDefault?: boolean;
+    };
+}
+/**
+ * Default configuration values for the api-core library.
+ */
+declare const DEFAULT_API_CORE_CONFIG: Required<ApiCoreConfig>;
+/**
+ * Injection token for api-core configuration.
+ *
+ * @example
+ * // Provide custom configuration
+ * providers: [
+ *   {
+ *     provide: API_CORE_CONFIG,
+ *     useValue: {
+ *       pagination: { defaultPageLength: 25 }
+ *     } as ApiCoreConfig
+ *   }
+ * ]
+ *
+ * @example
+ * // Inject in service
+ * constructor(@Inject(API_CORE_CONFIG) private config: ApiCoreConfig) {}
+ */
+declare const API_CORE_CONFIG: InjectionToken<ApiCoreConfig>;
+/**
+ * Merges user-provided configuration with default values.
+ *
+ * @param userConfig User-provided configuration
+ * @returns Merged configuration with defaults
+ *
+ * @example
+ * const config = mergeConfig({
+ *   pagination: { defaultPageLength: 25 }
+ * });
+ * // Returns full config with defaultPageLength: 25 and all other defaults
+ */
+declare function mergeConfig(userConfig?: ApiCoreConfig): Required<ApiCoreConfig>;
+
 declare class ApiCore {
     static ɵfac: i0.ɵɵFactoryDeclaration<ApiCore, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<ApiCore, "lib-api-core", never, {}, {}, never, never, true, never>;
@@ -174,12 +517,133 @@ declare class ApiCore {
  */
 declare function generatePermissions<T extends string = StandardPermission>(resource: string, extra?: T[]): Record<T | StandardPermission, string>;
 
+/**
+ * Converts an array of SortItem objects into a comma-separated sort string.
+ *
+ * @param sortItems Array of sort configurations
+ * @returns Formatted sort string (e.g., "name:ASC,createdAt:DESC") or empty string
+ *
+ * @example
+ * const sorts = [
+ *   new SortItem('name', 'ASC'),
+ *   new SortItem('createdAt', 'DESC')
+ * ];
+ * const sortString = sortObjectToString(sorts);
+ * // Returns: "name:ASC,createdAt:DESC"
+ */
 declare const sortObjectToString: (sortItems: SortItem[]) => string;
-declare const jsonToQueryString: (json: any) => string;
-declare const isEmpty: (obj: any) => boolean;
+/**
+ * Converts a filter object into a URL query string.
+ *
+ * @param filter Filter object with query parameters
+ * @returns URL query string with '?' prefix, or empty string if no parameters
+ *
+ * @remarks
+ * - Automatically converts SortItem arrays to sort strings
+ * - Encodes all values for URL safety
+ * - Filters out undefined and null values
+ * - Arrays are encoded as comma-separated values in brackets
+ *
+ * @example
+ * const filter = {
+ *   page: 1,
+ *   pageLength: 25,
+ *   search: 'John Doe',
+ *   roles: ['admin', 'user'],
+ *   sort: [new SortItem('name', 'ASC')]
+ * };
+ * const queryString = jsonToQueryString(filter);
+ * // Returns: "?page=1&pageLength=25&search=John%20Doe&roles=[admin,user]&sort=name:ASC"
+ */
+declare const jsonToQueryString: (filter: Record<string, unknown>) => string;
+/**
+ * Checks if an object is empty (has no own properties).
+ *
+ * @param obj Object to check
+ * @returns True if object is null, undefined, or has no properties
+ *
+ * @example
+ * isEmpty({});              // true
+ * isEmpty(null);            // true
+ * isEmpty(undefined);       // true
+ * isEmpty({ page: 1 });     // false
+ * isEmpty([]);              // true (arrays with no length)
+ */
+declare const isEmpty: (obj: Record<string, unknown> | null | undefined) => boolean;
 
 /**
- * A generic state management service for handling filters, pagination, and records.
+ * Generic reactive state management service for data-driven features.
+ *
+ * @template TRecord The type of record/entity being managed
+ * @template TFilter Filter type extending Partial<TRecord> & Filter
+ *
+ * @remarks
+ * BaseStateService provides comprehensive state management for list-based views including:
+ * - Filter state with pagination and sorting
+ * - Records collection with CRUD helpers
+ * - Loading states (with context keys)
+ * - Error handling
+ * - Record selection
+ * - Pagination metadata
+ *
+ * All state is reactive using RxJS BehaviorSubjects, making it easy to integrate
+ * with Angular templates using the async pipe.
+ *
+ * @example
+ * // Basic setup in component
+ * @Component({
+ *   selector: 'app-users',
+ *   providers: [BaseStateService] // Component-level instance
+ * })
+ * export class UsersComponent implements OnInit, OnDestroy {
+ *   state = new BaseStateService<User, UserFilter>();
+ *
+ *   constructor(private userService: UserService) {}
+ *
+ *   ngOnInit() {
+ *     // Subscribe to filter changes
+ *     this.state.filter$.subscribe(filter => {
+ *       this.loadUsers(filter);
+ *     });
+ *
+ *     // Set initial filter
+ *     this.state.setFilter({ page: 1, pageLength: 25 });
+ *   }
+ *
+ *   loadUsers(filter: UserFilter) {
+ *     this.state.setLoading('list', true);
+ *
+ *     this.userService.getAll(filter).subscribe({
+ *       next: (response) => {
+ *         if (response.data) {
+ *           this.state.setApiResponse(response.data);
+ *         }
+ *         this.state.setLoading('list', false);
+ *       },
+ *       error: (err) => {
+ *         this.state.setError('Failed to load users');
+ *         this.state.setLoading('list', false);
+ *       }
+ *     });
+ *   }
+ *
+ *   ngOnDestroy() {
+ *     this.state.destroy();
+ *   }
+ * }
+ *
+ * @example
+ * // Using in template
+ * <div *ngIf="state.isLoading$('list') | async">Loading...</div>
+ * <div *ngIf="state.error$ | async as error">{{ error }}</div>
+ *
+ * <div *ngFor="let user of state.records$ | async">
+ *   {{ user.name }}
+ * </div>
+ *
+ * <div *ngIf="state.pager$ | async as pager">
+ *   Page {{ pager.currentPage }} of {{ pager.lastPage }}
+ * </div>
  */
 declare class BaseStateService<TRecord, TFilter extends Partial<TRecord> & Filter = Partial<TRecord> & Filter> {
     private readonly filterSubject;
@@ -188,17 +652,35 @@ declare class BaseStateService<TRecord, TFilter extends Partial<TRecord> & Filte
     private readonly selectedSubject;
     private readonly loadingMapSubject;
     private readonly errorSubject;
-    /** Observable stream of current filter. */
+    /**
+     * Observable stream of current filter.
+     * Optimized with distinctUntilChanged to prevent duplicate emissions.
+     */
     filter$: Observable<TFilter>;
-    /** Observable stream of current records. */
+    /**
+     * Observable stream of current records.
+     * Optimized with distinctUntilChanged for reference equality.
+     */
     records$: Observable<TRecord[]>;
-    /** Observable stream of current pager metadata. */
+    /**
+     * Observable stream of current pager metadata.
+     * Optimized with distinctUntilChanged for deep equality.
+     */
     pager$: Observable<IMultiresultMetaData | null>;
-    /** Observable stream of the currently selected record. */
+    /**
+     * Observable stream of the currently selected record.
+     * Optimized with distinctUntilChanged for reference equality.
+     */
     selected$: Observable<TRecord | null>;
-    /** Observable stream of loading state. */
+    /**
+     * Observable stream of loading state.
+     * Optimized with distinctUntilChanged for deep equality.
+     */
     loading$: Observable<Record<string, boolean>>;
-    /** Observable stream of current error message. */
+    /**
+     * Observable stream of current error message.
+     * Optimized with distinctUntilChanged for value equality.
+     */
     error$: Observable<string | null>;
     /** Returns the current filter. */
     get currentFilter(): TFilter;
@@ -232,10 +714,25 @@ declare class BaseStateService<TRecord, TFilter extends Partial<TRecord> & Filte
      */
     setApiResponse(response: IMultiresult<TRecord>): void;
     /**
- * Updates the sort order in the current filter.
- * Toggles order if column already exists, or adds it otherwise.
- * @param column Column name to sort by.
- */
+     * Updates the sort order in the current filter.
+     * Toggles order if column already exists and no explicit sort is provided, or adds it otherwise.
+     *
+     * @param column Column name to sort by
+     * @param sort Optional sort order. If not provided and column exists, toggles between ASC/DESC.
+     *              If not provided and column doesn't exist, defaults to ASC.
+     *
+     * @example
+     * // Add new sort (defaults to ASC)
+     * state.setSort('name');
+     *
+     * @example
+     * // Toggle existing sort
+     * state.setSort('name'); // If already ASC, becomes DESC; if DESC, becomes ASC
+     *
+     * @example
+     * // Explicitly set sort order
+     * state.setSort('name', 'DESC'); // Always sets to DESC
+     */
     setSort(column: string, sort?: "ASC" | "DESC"): void;
     /**
      * Removes a specific column from the current sort.
@@ -252,6 +749,10 @@ declare class BaseStateService<TRecord, TFilter extends Partial<TRecord> & Filte
      *
      * @param key A unique key representing the loading context (e.g., "list", "detail")
      * @returns Observable emitting `true` if the given context is loading, `false` otherwise.
+     *
+     * @remarks
+     * Optimized with distinctUntilChanged to prevent duplicate emissions
+     * and shareReplay to share subscriptions.
      */
     isLoading$(key: string): Observable<boolean>;
     /**
@@ -329,19 +830,331 @@ declare class BaseStateService<TRecord, TFilter extends Partial<TRecord> & Filte
     destroySubscriptions(subjects?: Array<'filterSubject' | 'recordsSubject' | 'pagerSubject' | 'selectedSubject' | 'loadingMapSubject' | 'errorSubject'>): void;
 }
 
+/**
+ * Abstract base service providing standard CRUD operations for REST APIs.
+ *
+ * @template T The full model type representing your entity
+ * @template TFilter Filter type extending Partial<T> & Filter for query parameters
+ * @template TCreate DTO type for creating new records (defaults to Partial<T>)
+ * @template TUpdate DTO type for updating records (defaults to Partial<T>)
+ *
+ * @remarks
+ * Extend this class in your feature services to get type-safe CRUD operations
+ * with minimal boilerplate. The service automatically handles:
+ * - Query string generation from filters
+ * - Pagination and sorting
+ * - Standardized response/error handling
+ * - Type safety throughout the request/response cycle
+ *
+ * @example
+ * // Define your model
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ *   role: string;
+ * }
+ *
+ * // Define custom filter
+ * interface UserFilter extends Filter {
+ *   role?: string;
+ *   isActive?: boolean;
+ * }
+ *
+ * // Create service
+ * @Injectable({ providedIn: 'root' })
+ * export class UserService extends BaseService<User, UserFilter> {
+ *   constructor(http: HttpClient) {
+ *     super(http, '/api/users');
+ *   }
+ *
+ *   // Add custom methods
+ *   activateUser(id: number): Observable<IResponse<User>> {
+ *     return this.http.post<IResponse<User>>(`${this.baseUrl}/${id}/activate`, {});
+ *   }
+ * }
+ *
+ * @example
+ * // With separate DTOs for create/update
+ * interface CreateUserDto {
+ *   name: string;
+ *   email: string;
+ *   password: string;
+ * }
+ *
+ * interface UpdateUserDto {
+ *   name?: string;
+ *   email?: string;
+ *   // Note: password excluded
+ * }
+ *
+ * @Injectable({ providedIn: 'root' })
+ * export class UserService extends BaseService<
+ *   User,
+ *   UserFilter,
+ *   CreateUserDto,
+ *   UpdateUserDto
+ * > {
+ *   constructor(http: HttpClient) {
+ *     super(http, '/api/users');
+ *   }
+ * }
+ */
 declare abstract class BaseService<T, // Full model type
 TFilter extends Partial<T> & Filter = Partial<T> & Filter, // Filter: model fields + pagination/sorting
 TCreate = Partial<T>, // DTO for create
 TUpdate = Partial<T>> {
     protected http: HttpClient;
     protected baseUrl: string;
+    /**
+     * Creates an instance of BaseService.
+     *
+     * @param http Angular HttpClient for making HTTP requests
+     * @param baseUrl Base URL for the resource API endpoint (e.g., '/api/users')
+     */
     constructor(http: HttpClient, baseUrl: string);
+    /**
+     * Fetches a paginated list of records with optional filtering and sorting.
+     *
+     * @param filter Optional filter object containing pagination, sorting, and search criteria
+     * @returns Observable of response containing records array and pagination metadata
+     *
+     * @example
+     * // Basic usage
+     * userService.getAll().subscribe(response => {
+     *   console.log(response.data?.records);
+     *   console.log(response.data?.pager.totalRecords);
+     * });
+     *
+     * @example
+     * // With filters
+     * userService.getAll({
+     *   page: 2,
+     *   pageLength: 25,
+     *   search: 'john',
+     *   role: 'admin',
+     *   sort: [new SortItem('name', 'ASC')]
+     * }).subscribe(response => {
+     *   // Handle response
+     * });
+     */
     getAll(filter?: TFilter): Observable<IResponse<IMultiresult<T>>>;
+    /**
+     * Fetches a single record by its ID.
+     *
+     * @param id The unique identifier of the record
+     * @returns Observable of response containing the single record
+     *
+     * @example
+     * userService.getDetails(123).subscribe(response => {
+     *   if (response.data) {
+     *     console.log('User:', response.data);
+     *   }
+     * });
+     */
     getDetails(id: number): Observable<IResponse<T>>;
+    /**
+     * Creates a new record.
+     *
+     * @param data Data transfer object containing fields for the new record
+     * @returns Observable of response containing the created record (usually with generated ID)
+     *
+     * @example
+     * userService.create({
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     *   password: 'secure123'
+     * }).subscribe(response => {
+     *   if (response.data) {
+     *     console.log('Created user:', response.data);
+     *   }
+     * });
+     */
     create(data: TCreate): Observable<IResponse<T>>;
+    /**
+     * Updates an existing record.
+     *
+     * @param id The unique identifier of the record to update
+     * @param data Data transfer object containing fields to update (partial update supported)
+     * @returns Observable of response containing the updated record
+     *
+     * @example
+     * userService.update(123, {
+     *   name: 'Jane Doe',
+     *   email: 'jane@example.com'
+     * }).subscribe(response => {
+     *   if (response.data) {
+     *     console.log('Updated user:', response.data);
+     *   }
+     * });
+     */
     update(id: number, data: TUpdate): Observable<IResponse<T>>;
-    delete(id: number, method?: 'soft' | 'hard'): Observable<IResponse<any>>;
+    /**
+     * Deletes a record (soft or hard delete).
+     *
+     * @param id The unique identifier of the record to delete
+     * @param method Deletion method: 'soft' (mark as deleted, reversible) or 'hard' (permanent removal)
+     * @returns Observable of response confirming deletion
+     *
+     * @remarks
+     * - Soft delete: Record is marked as deleted but can be restored later
+     * - Hard delete: Record is permanently removed from the database
+     * - Default is 'soft' for safety
+     *
+     * @example
+     * // Soft delete (default)
+     * userService.delete(123).subscribe(() => {
+     *   console.log('User soft deleted');
+     * });
+     *
+     * @example
+     * // Hard delete (permanent)
+     * userService.delete(123, 'hard').subscribe(() => {
+     *   console.log('User permanently deleted');
+     * });
+     */
+    delete(id: number, method?: 'soft' | 'hard'): Observable<IResponse<unknown>>;
+}
+
+/**
+ * Configuration options for the ApiErrorHandler.
+ */
+interface ApiErrorHandlerConfig {
+    /** Whether to log errors to console (default: true in dev, false in prod) */
+    logErrors?: boolean;
+    /** Custom error message transformer */
+    errorMessageTransformer?: (error: HttpErrorResponse) => string;
+    /** Callback to be called when an error occurs */
+    onError?: (error: ProcessedError) => void;
+}
+/**
+ * Processed error information with additional context.
+ */
+interface ProcessedError {
+    /** HTTP status code */
+    status: number;
+    /** User-friendly error message */
+    message: string;
+    /** Technical error details */
+    details?: string;
+    /** Error code from API */
+    code?: string;
+    /** Original HTTP error response */
+    originalError: HttpErrorResponse;
+    /** Whether this error should be shown to user */
+    showToUser: boolean;
+    /** Error type classification */
+    type: 'network' | 'client' | 'server' | 'unknown';
+}
+/**
+ * Service for handling and processing API errors consistently.
+ *
+ * @example
+ * // Basic usage in a service
+ * constructor(private errorHandler: ApiErrorHandler) {}
+ *
+ * loadData() {
+ *   this.http.get('/api/data').subscribe({
+ *     error: (err: HttpErrorResponse) => {
+ *       const processed = this.errorHandler.handleError(err);
+ *       this.showErrorToUser(processed.message);
+ *     }
+ *   });
+ * }
+ *
+ * @example
+ * // Configure globally
+ * providers: [
+ *   {
+ *     provide: ApiErrorHandler,
+ *     useFactory: () => {
+ *       const handler = new ApiErrorHandler();
+ *       handler.configure({
+ *         logErrors: true,
+ *         onError: (error) => {
+ *           // Send to logging service
+ *           loggingService.logError(error);
+ *         }
+ *       });
+ *       return handler;
+ *     }
+ *   }
+ * ]
+ */
+declare class ApiErrorHandler {
+    private config;
+    /**
+     * Configure the error handler.
+     *
+     * @param config Configuration options
+     */
+    configure(config: ApiErrorHandlerConfig): void;
+    /**
+     * Process an HTTP error and return structured error information.
+     *
+     * @param error The HTTP error response
+     * @returns Processed error with user-friendly message and metadata
+     */
+    handleError(error: HttpErrorResponse): ProcessedError;
+    /**
+     * Extract error message from various error formats.
+     *
+     * @param error The HTTP error response
+     * @returns User-friendly error message
+     */
+    extractErrorMessage(error: HttpErrorResponse): string;
+    /**
+     * Get default error message based on HTTP status code.
+     *
+     * @param status HTTP status code
+     * @returns Default error message
+     */
+    private getDefaultMessageForStatus;
+    /**
+     * Classify error type based on status code.
+     *
+     * @param status HTTP status code
+     * @returns Error type classification
+     */
+    private getErrorType;
+    /**
+     * Determine if error should be shown to user.
+     *
+     * @param error HTTP error response
+     * @returns Whether to show error to user
+     */
+    private shouldShowToUser;
+    /**
+     * Process the error into a structured format.
+     *
+     * @param error HTTP error response
+     * @returns Processed error object
+     */
+    private processError;
+    /**
+     * Log error to console (in dev mode).
+     *
+     * @param error Processed error
+     */
+    private logError;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ApiErrorHandler, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ApiErrorHandler>;
 }
 
-export { ApiCore, BaseResourceConfig, BaseService, BaseStateService, Filter, SELECT_MODE, SortItem, generatePermissions, isEmpty, jsonToQueryString, sortObjectToString };
-export type { IMisError, IMultiresult, IMultiresultMetaData, IResponse, PagedResponse, SingleResponse, StandardPermission, TableColumn };
+/**
+ * HTTP Interceptor that catches errors and processes them through the ApiErrorHandler.
+ *
+ * @example
+ * // In your app.config.ts or main provider:
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHttpClient(
+ *       withInterceptors([apiErrorInterceptor])
+ *     )
+ *   ]
+ * };
+ */
+declare const apiErrorInterceptor: HttpInterceptorFn;
+
+export { API_CORE_CONFIG, ApiCore, ApiErrorHandler, BaseResourceConfig, BaseService, BaseStateService, DEFAULT_API_CORE_CONFIG, Filter, SELECT_MODE, SortItem, apiErrorInterceptor, generatePermissions, isEmpty, jsonToQueryString, mergeConfig, sortObjectToString };
+export type { ApiCoreConfig, ApiErrorHandlerConfig, IMisError, IMultiresult, IMultiresultMetaData, IResponse, PagedResponse, ProcessedError, SingleResponse, StandardPermission, TableColumn };