@mysteryinfosolutions/api-core 1.7.13 → 1.9.0

package/fesm2022/mysteryinfosolutions-api-core.mjs

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
-import { Component } from '@angular/core';
-import { BehaviorSubject, map } from 'rxjs';
+import { InjectionToken, Component, Injectable, inject } from '@angular/core';
+import { BehaviorSubject, distinctUntilChanged, shareReplay, map, catchError, throwError } from 'rxjs';
 
 /**
  * BaseResourceConfig<T>
@@ -66,6 +66,92 @@ class BaseResourceConfig {
     permissions;
 }
 
+/**
+ * Default configuration values for the api-core library.
+ */
+const DEFAULT_API_CORE_CONFIG = {
+    pagination: {
+        defaultPage: 1,
+        defaultPageLength: 10,
+        pageLengthOptions: [10, 25, 50, 100],
+        maxPageLength: 1000
+    },
+    api: {
+        dateFormat: 'iso',
+        dateFormatter: (date) => date.toISOString(),
+        includeCredentials: false,
+        defaultHeaders: {},
+        timeout: 30000 // 30 seconds
+    },
+    queryString: {
+        arrayFormat: 'brackets',
+        arrayFormatter: (key, values) => `${key}=[${values.join(',')}]`,
+        encode: true,
+        encoder: (value) => encodeURIComponent(value)
+    },
+    sort: {
+        defaultOrder: 'ASC',
+        separator: ':',
+        allowMultiSort: true
+    },
+    errorHandling: {
+        logErrors: true,
+        showUserMessages: true,
+        onError: (error) => console.error('API Error:', error)
+    },
+    loading: {
+        minLoadingTime: 0,
+        showLoadingByDefault: true
+    }
+};
+/**
+ * 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) {}
+ */
+const API_CORE_CONFIG = new InjectionToken('api-core.config', {
+    providedIn: 'root',
+    factory: () => DEFAULT_API_CORE_CONFIG
+});
+/**
+ * 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
+ */
+function mergeConfig(userConfig) {
+    if (!userConfig) {
+        return DEFAULT_API_CORE_CONFIG;
+    }
+    return {
+        pagination: { ...DEFAULT_API_CORE_CONFIG.pagination, ...userConfig.pagination },
+        api: { ...DEFAULT_API_CORE_CONFIG.api, ...userConfig.api },
+        queryString: { ...DEFAULT_API_CORE_CONFIG.queryString, ...userConfig.queryString },
+        sort: { ...DEFAULT_API_CORE_CONFIG.sort, ...userConfig.sort },
+        errorHandling: { ...DEFAULT_API_CORE_CONFIG.errorHandling, ...userConfig.errorHandling },
+        loading: { ...DEFAULT_API_CORE_CONFIG.loading, ...userConfig.loading }
+    };
+}
+
 class ApiCore {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.0.2", ngImport: i0, type: ApiCore, deps: [], target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "20.0.2", type: ApiCore, isStandalone: true, selector: "lib-api-core", ngImport: i0, template: `
@@ -83,12 +169,26 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.0.2", ngImpor
   ` }]
         }] });
 
+/**
+ * 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'
+ * };
+ */
 var SELECT_MODE;
 (function (SELECT_MODE) {
+    /** Return all columns (default behavior) */
     SELECT_MODE[SELECT_MODE["ALL"] = 1] = "ALL";
+    /** Return only specified columns via selectColumns parameter */
     SELECT_MODE[SELECT_MODE["ONLYCOLUMNS"] = 2] = "ONLYCOLUMNS";
 })(SELECT_MODE || (SELECT_MODE = {}));
-;
 
 /**
  * Generates a permission mapping object for a given resource.
@@ -164,50 +264,169 @@ function generatePermissions(resource, extra = []) {
     }, {});
 }
 
+/**
+ * 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"
+ */
 const sortObjectToString = (sortItems) => {
     if (!Array.isArray(sortItems) || sortItems.length === 0)
         return '';
     return sortItems.map(s => `${s.field}:${s.order}`).join(',');
 };
-const jsonToQueryString = (json) => {
-    if (!json || typeof json !== 'object')
+/**
+ * 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"
+ */
+const jsonToQueryString = (filter) => {
+    if (!filter || typeof filter !== 'object')
         return '';
-    if (json.hasOwnProperty('sort')) {
-        json.sort = sortObjectToString(json.sort);
+    // Clone to avoid mutating original
+    const params = { ...filter };
+    // Convert sort array to string format
+    if ('sort' in params && Array.isArray(params['sort'])) {
+        params['sort'] = sortObjectToString(params['sort']);
     }
-    const queryArray = Object.keys(json)
-        .filter(key => json[key] !== undefined && json[key] !== null)
+    const queryArray = Object.keys(params)
+        .filter(key => params[key] !== undefined && params[key] !== null && params[key] !== '')
         .map(key => {
-        if (Array.isArray(json[key])) {
-            return `${encodeURIComponent(key)}=${encodeURIComponent('[' + json[key].toString() + ']')}`;
+        const value = params[key];
+        if (Array.isArray(value)) {
+            // Encode arrays as [item1,item2,item3]
+            return `${encodeURIComponent(key)}=${encodeURIComponent('[' + value.toString() + ']')}`;
         }
         else {
-            return `${encodeURIComponent(key)}=${encodeURIComponent(json[key])}`;
+            return `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`;
         }
     });
     return queryArray.length > 0 ? `?${queryArray.join('&')}` : '';
 };
+/**
+ * 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)
+ */
 const isEmpty = (obj) => {
     return !obj || Object.keys(obj).length === 0;
 };
 
+/**
+ * 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')]
+ * };
+ */
 class Filter {
-    ids = [];
+    /** Array of specific IDs to filter by */
+    ids;
+    /** Column name to use for date range filtering */
     dateRangeColumn;
+    /** Start date for date range filter (ISO format) */
     dateRangeFrom;
+    /** End date for date range filter (ISO format) */
     dateRangeTo;
-    page = 1;
-    pageLength = 10;
-    sort = [];
+    /** Current page number (1-based) */
+    page;
+    /** Number of records per page */
+    pageLength;
+    /** Array of sort configurations */
+    sort;
+    /** Search query string */
     search;
+    /** Comma-separated list of columns to search in */
     searchColumns;
+    /** Comma-separated list of columns to select/return */
     selectColumns;
+    /** Mode for column selection */
     selectMode;
 }
 
+/**
+ * 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
+ * };
+ */
 class SortItem {
     field;
     order;
+    /**
+     * Creates a sort configuration.
+     *
+     * @param field The field/column name to sort by
+     * @param order Sort direction: 'ASC' (ascending) or 'DESC' (descending)
+     */
     constructor(field, order) {
         this.field = field;
         this.order = order;
@@ -217,7 +436,78 @@ class SortItem {
 ;
 
 /**
- * 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>
  */
 class BaseStateService {
     filterSubject = new BehaviorSubject({ page: 1, pageLength: 10 });
@@ -226,18 +516,36 @@ class BaseStateService {
     selectedSubject = new BehaviorSubject(null);
     loadingMapSubject = new BehaviorSubject({});
     errorSubject = new BehaviorSubject(null);
-    /** Observable stream of current filter. */
-    filter$ = this.filterSubject.asObservable();
-    /** Observable stream of current records. */
-    records$ = this.recordsSubject.asObservable();
-    /** Observable stream of current pager metadata. */
-    pager$ = this.pagerSubject.asObservable();
-    /** Observable stream of the currently selected record. */
-    selected$ = this.selectedSubject.asObservable();
-    /** Observable stream of loading state. */
-    loading$ = this.loadingMapSubject.asObservable();
-    /** Observable stream of current error message. */
-    error$ = this.errorSubject.asObservable();
+    /**
+     * Observable stream of current filter.
+     * Optimized with distinctUntilChanged to prevent duplicate emissions.
+     */
+    filter$ = this.filterSubject.asObservable().pipe(distinctUntilChanged((prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)), shareReplay({ bufferSize: 1, refCount: true }));
+    /**
+     * Observable stream of current records.
+     * Optimized with distinctUntilChanged for reference equality.
+     */
+    records$ = this.recordsSubject.asObservable().pipe(distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
+    /**
+     * Observable stream of current pager metadata.
+     * Optimized with distinctUntilChanged for deep equality.
+     */
+    pager$ = this.pagerSubject.asObservable().pipe(distinctUntilChanged((prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)), shareReplay({ bufferSize: 1, refCount: true }));
+    /**
+     * Observable stream of the currently selected record.
+     * Optimized with distinctUntilChanged for reference equality.
+     */
+    selected$ = this.selectedSubject.asObservable().pipe(distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
+    /**
+     * Observable stream of loading state.
+     * Optimized with distinctUntilChanged for deep equality.
+     */
+    loading$ = this.loadingMapSubject.asObservable().pipe(distinctUntilChanged((prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)), shareReplay({ bufferSize: 1, refCount: true }));
+    /**
+     * Observable stream of current error message.
+     * Optimized with distinctUntilChanged for value equality.
+     */
+    error$ = this.errorSubject.asObservable().pipe(distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
     /** Returns the current filter. */
     get currentFilter() {
         return this.filterSubject.value;
@@ -288,24 +596,45 @@ class BaseStateService {
         this.setPager(response.pager);
     }
     /**
- * 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.
- */
-    setSort(column, sort = "ASC") {
+     * 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, sort) {
         const current = this.filterSubject.value;
         let sortItems = [...(current.sort ?? [])];
         const index = sortItems.findIndex(item => item.field === column);
         if (index !== -1) {
-            // If sort is explicitly provided, set it; otherwise, toggle
-            const currentOrder = sortItems[index].order;
-            const newOrder = (typeof sort === 'undefined' || sort === null)
-                ? (currentOrder === 'ASC' ? 'DESC' : 'ASC')
-                : sort;
-            sortItems[index] = new SortItem(sortItems[index].field, newOrder);
+            // Column already exists in sort
+            if (sort !== undefined) {
+                // Explicit sort provided - use it
+                sortItems[index] = new SortItem(sortItems[index].field, sort);
+            }
+            else {
+                // No explicit sort - toggle the order
+                const currentOrder = sortItems[index].order;
+                const newOrder = currentOrder === 'ASC' ? 'DESC' : 'ASC';
+                sortItems[index] = new SortItem(sortItems[index].field, newOrder);
+            }
         }
         else {
-            sortItems.push(new SortItem(column, sort));
+            // Column doesn't exist - add it (default to ASC if not specified)
+            sortItems.push(new SortItem(column, sort ?? 'ASC'));
         }
         this.filterSubject.next({
             ...current,
@@ -340,9 +669,13 @@ class BaseStateService {
      *
      * @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) {
-        return this.loading$.pipe(map(state => !!state[key]));
+        return this.loading$.pipe(map(state => !!state[key]), distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
     }
     /**
      * Sets the loading state for a specific key.
@@ -455,6 +788,7 @@ class BaseStateService {
     /** Resets and clears all managed state. */
     destroy() {
         this.reset();
+        this.destroySubscriptions();
     }
     /**
      * Completes specified subjects managed by this service.
@@ -475,36 +809,452 @@ class BaseStateService {
     }
 }
 
+/**
+ * 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');
+ *   }
+ * }
+ */
 class BaseService {
     http;
     baseUrl;
+    /**
+     * 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, baseUrl) {
         this.http = http;
         this.baseUrl = baseUrl;
     }
+    /**
+     * 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 = {}) {
         const clonedFilter = structuredClone(filter);
         const query = !isEmpty(filter) ? jsonToQueryString(clonedFilter) : '';
         return this.http.get(`${this.baseUrl}${query}`);
     }
+    /**
+     * 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) {
         return this.http.get(`${this.baseUrl}/${id}`);
     }
+    /**
+     * 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) {
         return this.http.post(this.baseUrl, data);
     }
+    /**
+     * 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, data) {
         return this.http.put(`${this.baseUrl}/${id}`, data);
     }
+    /**
+     * 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, method = 'soft') {
         const methodQuery = `?method=${method}`;
-        if (method === 'soft') {
-            return this.http.delete(`${this.baseUrl}/${id}${methodQuery}`, {});
-        }
         return this.http.delete(`${this.baseUrl}/${id}${methodQuery}`);
     }
 }
 
+/**
+ * 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;
+ *     }
+ *   }
+ * ]
+ */
+class ApiErrorHandler {
+    config = {
+        logErrors: true
+    };
+    /**
+     * Configure the error handler.
+     *
+     * @param config Configuration options
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * 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) {
+        const processed = this.processError(error);
+        if (this.config.logErrors) {
+            this.logError(processed);
+        }
+        if (this.config.onError) {
+            this.config.onError(processed);
+        }
+        return processed;
+    }
+    /**
+     * Extract error message from various error formats.
+     *
+     * @param error The HTTP error response
+     * @returns User-friendly error message
+     */
+    extractErrorMessage(error) {
+        if (this.config.errorMessageTransformer) {
+            return this.config.errorMessageTransformer(error);
+        }
+        // Try to extract from API response
+        if (error.error && typeof error.error === 'object') {
+            const apiError = error.error;
+            // Check for nested error object
+            if (apiError.error?.message) {
+                return apiError.error.message;
+            }
+            // Check for direct message
+            if (apiError.message) {
+                return apiError.message;
+            }
+        }
+        // Fallback to status-based messages
+        return this.getDefaultMessageForStatus(error.status);
+    }
+    /**
+     * Get default error message based on HTTP status code.
+     *
+     * @param status HTTP status code
+     * @returns Default error message
+     */
+    getDefaultMessageForStatus(status) {
+        switch (status) {
+            case 0:
+                return 'Unable to connect to the server. Please check your internet connection.';
+            case 400:
+                return 'Invalid request. Please check your input and try again.';
+            case 401:
+                return 'You are not authorized. Please log in and try again.';
+            case 403:
+                return 'You do not have permission to perform this action.';
+            case 404:
+                return 'The requested resource was not found.';
+            case 408:
+                return 'Request timeout. Please try again.';
+            case 409:
+                return 'This action conflicts with the current state. Please refresh and try again.';
+            case 422:
+                return 'Validation failed. Please check your input.';
+            case 429:
+                return 'Too many requests. Please wait a moment and try again.';
+            case 500:
+                return 'An internal server error occurred. Please try again later.';
+            case 502:
+                return 'Bad gateway. The server is temporarily unavailable.';
+            case 503:
+                return 'Service unavailable. Please try again later.';
+            case 504:
+                return 'Gateway timeout. The server took too long to respond.';
+            default:
+                if (status >= 400 && status < 500) {
+                    return 'Client error occurred. Please check your request.';
+                }
+                else if (status >= 500) {
+                    return 'Server error occurred. Please try again later.';
+                }
+                return 'An unexpected error occurred. Please try again.';
+        }
+    }
+    /**
+     * Classify error type based on status code.
+     *
+     * @param status HTTP status code
+     * @returns Error type classification
+     */
+    getErrorType(status) {
+        if (status === 0) {
+            return 'network';
+        }
+        else if (status >= 400 && status < 500) {
+            return 'client';
+        }
+        else if (status >= 500) {
+            return 'server';
+        }
+        return 'unknown';
+    }
+    /**
+     * Determine if error should be shown to user.
+     *
+     * @param error HTTP error response
+     * @returns Whether to show error to user
+     */
+    shouldShowToUser(error) {
+        // Check if API explicitly set showMessageToUser flag
+        if (error.error?.error?.showMessageToUser !== undefined) {
+            return error.error.error.showMessageToUser;
+        }
+        // By default, show client errors (4xx) but not server errors (5xx)
+        // unless it's a network error (0)
+        const status = error.status;
+        return status === 0 || (status >= 400 && status < 500);
+    }
+    /**
+     * Process the error into a structured format.
+     *
+     * @param error HTTP error response
+     * @returns Processed error object
+     */
+    processError(error) {
+        const message = this.extractErrorMessage(error);
+        const type = this.getErrorType(error.status);
+        const showToUser = this.shouldShowToUser(error);
+        let details;
+        let code;
+        // Extract additional details if available
+        if (error.error && typeof error.error === 'object') {
+            const apiError = error.error;
+            if (apiError.error) {
+                details = apiError.error.details;
+                code = apiError.error.code;
+            }
+        }
+        return {
+            status: error.status,
+            message,
+            details,
+            code,
+            originalError: error,
+            showToUser,
+            type
+        };
+    }
+    /**
+     * Log error to console (in dev mode).
+     *
+     * @param error Processed error
+     */
+    logError(error) {
+        const style = 'color: #ff6b6b; font-weight: bold;';
+        console.group('%c🔥 API Error', style);
+        console.log('Status:', error.status);
+        console.log('Type:', error.type);
+        console.log('Message:', error.message);
+        if (error.code) {
+            console.log('Code:', error.code);
+        }
+        if (error.details) {
+            console.log('Details:', error.details);
+        }
+        console.log('URL:', error.originalError.url);
+        console.log('Method:', error.originalError.error?.method || 'Unknown');
+        console.log('Original Error:', error.originalError);
+        console.groupEnd();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.0.2", ngImport: i0, type: ApiErrorHandler, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.0.2", ngImport: i0, type: ApiErrorHandler, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.0.2", ngImport: i0, type: ApiErrorHandler, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * 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])
+ *     )
+ *   ]
+ * };
+ */
+const apiErrorInterceptor = (req, next) => {
+    const errorHandler = inject(ApiErrorHandler);
+    return next(req).pipe(catchError((error) => {
+        const handledError = errorHandler.handleError(error);
+        return throwError(() => handledError);
+    }));
+};
+
 /*
  * Public API Surface of api-core
  */
@@ -513,5 +1263,5 @@ class BaseService {
  * Generated bundle index. Do not edit.
  */
 
-export { ApiCore, BaseResourceConfig, BaseService, BaseStateService, Filter, SELECT_MODE, SortItem, generatePermissions, isEmpty, jsonToQueryString, sortObjectToString };
+export { API_CORE_CONFIG, ApiCore, ApiErrorHandler, BaseResourceConfig, BaseService, BaseStateService, DEFAULT_API_CORE_CONFIG, Filter, SELECT_MODE, SortItem, apiErrorInterceptor, generatePermissions, isEmpty, jsonToQueryString, mergeConfig, sortObjectToString };
 //# sourceMappingURL=mysteryinfosolutions-api-core.mjs.map