@flusys/ng-core 4.0.2 → 4.1.0

package/README.md

@@ -1,341 +1,386 @@
-# @flusys/ng-core Package Guide
+# @flusys/ng-core
 
-## Overview
+> Foundation library for the FLUSYS Angular platform — configuration injection, base HTTP services, API loaders, and HTTP interceptors.
 
-`@flusys/ng-core` is the foundation package providing core functionality for all FLUSYS Angular libraries. Contains configuration management, HTTP interceptors, base services, and type definitions.
+[![npm version](https://img.shields.io/npm/v/@flusys/ng-core.svg)](https://www.npmjs.com/package/@flusys/ng-core)
+[![Angular](https://img.shields.io/badge/Angular-21-red.svg)](https://angular.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-**Key Principle:** ng-core has NO dependencies on other @flusys packages. All other packages depend on ng-core.
+---
 
-## Package Information
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration Reference](#configuration-reference)
+  - [IAppConfig](#iappconfig)
+  - [APP_CONFIG Token](#app_config-token)
+- [Base Services](#base-services)
+  - [BaseApiService](#baseapiservice)
+  - [ApiLoaderService](#apiloaderservice)
+- [HTTP Interceptors](#http-interceptors)
+- [Helper Functions](#helper-functions)
+- [Exported Tokens](#exported-tokens)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
-- **Package:** `@flusys/ng-core`
-- **Version:** 4.0.2
-- **Peer Dependencies:** `@angular/*: >=21.0.0`, `primeng: >=21.0.0`
-- **Build Command:** `npm run build:ng-core`
+---
 
-## Package Structure
+## Overview
 
-```
-ng-core/
-├── components/
-│   └── lib-app-config/          # Global toast, confirm, loader
-├── interceptors/
-│   ├── api-loader.interceptor.ts
-│   └── error-catching.interceptor.ts
-├── interfaces/
-│   └── app-config.interface.ts  # IAppConfig, helpers, constants
-├── services/
-│   ├── api-loader.service.ts
-│   └── base-api.service.ts
-└── public-api.ts
-```
+`@flusys/ng-core` is the zero-dependency foundation of the FLUSYS Angular package hierarchy. Every other FLUSYS Angular package depends on it. It provides:
 
-## Public API
+- The **`APP_CONFIG`** injection token — single source of truth for all application configuration
+- **`BaseApiService`** — typed POST-only RPC HTTP client
+- **`ApiLoaderService`** — manages global loading state across concurrent requests
+- **HTTP interceptors** — base URL injection and error normalization
+- Utility helper functions for feature detection
 
-```typescript
-// Components
-export { LibAppConfigComponent } from './components/public-api';
-
-// Services
-export { ApiLoaderService, BaseApiService } from './services/public-api';
-
-// Interceptors
-export { apiLoaderInterceptor, errorCatchingInterceptor, SKIP_ERROR_TOAST } from './interceptors/public-api';
-
-// Interfaces & Types
-export {
-  APP_CONFIG, IAppConfig, IServiceConfig, IStorageServiceConfig,
-  IAuthorConfig, IRegistrationDefaults, PermissionMode,
-} from './interfaces/public-api';
-
-// Helper Functions
-export {
-  getDatabaseMode, isServiceEnabled, isFeatureEnabled, getServiceUrl,
-  isCompanyFeatureEnabled, isStorageFeatureEnabled, isFormBuilderFeatureEnabled,
-  isEmailFeatureEnabled, getPermissionMode, getDefaultStorageConfigId,
-  isSignUpEnabled, getDefaultCompanySlug, getDefaultBranchSlug, getRegistrationDefaults,
-} from './interfaces/public-api';
-
-// Constants
-export { DEFAULT_APP_NAME, DEFAULT_AUTHOR } from './interfaces/public-api';
-```
+This package has **no FLUSYS dependencies** — it only depends on Angular core.
 
 ---
 
-## 1. APP_CONFIG (Configuration Management)
+## Features
 
-Centralized configuration system with dynamic service URLs and feature flags.
+- ✅ Typed `IAppConfig` with full IntelliSense
+- ✅ POST-only RPC HTTP client (`BaseApiService`)
+- ✅ Global loading state management (`ApiLoaderService`)
+- ✅ `APP_CONFIG` injection token for DI-based configuration
+- ✅ Feature detection helpers (`isAuthEnabled()`, `isIamEnabled()`, `isSignUpEnabled()`, etc.)
+- ✅ HTTP interceptors for base URL and error handling
+- ✅ Zoneless-compatible (no Zone.js dependency)
+- ✅ Signal-friendly architecture
 
-### IAppConfig Interface
+---
 
-```typescript
-export type PermissionMode = 'rbac' | 'direct' | 'full';
+## Compatibility
 
-export interface IServiceConfig {
-  baseUrl: string;
-  enabled: boolean;
-}
+| Package | Version |
+|---------|---------|
+| Angular | 21+ |
+| TypeScript | 5.x |
+| RxJS | 7.x |
 
-export interface IStorageServiceConfig extends IServiceConfig {
-  defaultStorageConfigId?: string;  // Default storage config for uploads
-}
+---
 
-export interface IAuthorConfig { name: string; url: string; }
+## Installation
 
-export interface IRegistrationDefaults {
-  companySlug?: string;  // Pre-fill company code (readonly)
-  branchSlug?: string;   // Pre-fill branch code (readonly)
-}
+```bash
+npm install @flusys/ng-core
+```
 
-export interface IAppConfig {
-  appName: string;
-  author?: IAuthorConfig;
-  apiBaseUrl: string;                    // Default fallback URL
-  enableCompanyFeature: boolean;         // Company selection/switching
-  enableSignUp?: boolean;                // Registration enabled (default: true)
-  registrationDefaults?: IRegistrationDefaults;
+---
 
-  services: {
-    auth: IServiceConfig;
-    administration: IServiceConfig;
-    iam: IServiceConfig;
-    storage: IStorageServiceConfig;
-    formBuilder: IServiceConfig;
-    email: IServiceConfig;
-  };
+## Quick Start
 
-  multiTenant: {
-    enabled: boolean;      // true = multi-tenant DB, false = single DB
-    tenantHeader: string;  // Header name (e.g., 'x-tenant-id')
-    tenantId?: string;
-  };
+### 1. Define App Config
 
-  permissionMode?: PermissionMode;  // Defaults to 'full'
-}
+```typescript
+// environments/environment.ts
+import { IAppConfig } from '@flusys/ng-core';
 
-export const APP_CONFIG = new InjectionToken<IAppConfig>('APP_CONFIG');
+export const environment: IAppConfig = {
+  appName: 'My App',
+  apiBaseUrl: 'http://localhost:2002',
+  production: false,
+  services: {
+    auth: {
+      enabled: true,
+      features: {
+        signUp: true,
+        emailVerification: true,
+      },
+    },
+    iam: { enabled: true },
+    storage: { enabled: true },
+    email: { enabled: false },
+    formBuilder: { enabled: false },
+    eventManager: { enabled: false },
+    notification: { enabled: false },
+    localization: { enabled: false },
+  },
+  multiTenant: false,
+  permissionMode: 'FULL',
+};
 ```
 
-### Helper Functions
-
-| Function | Returns | Description |
-|----------|---------|-------------|
-| `getDatabaseMode(config)` | `'single' \| 'multi-tenant'` | Database mode from `multiTenant.enabled` |
-| `isServiceEnabled(config, name)` | `boolean` | Check if service is enabled |
-| `isFeatureEnabled(config, feature)` | `boolean` | Same as above with strict ServiceName type |
-| `getServiceUrl(config, name)` | `string` | Service URL or fallback to `apiBaseUrl` |
-| `isCompanyFeatureEnabled(config)` | `boolean` | Check `enableCompanyFeature` |
-| `isStorageFeatureEnabled(config)` | `boolean` | Check `services.storage.enabled` |
-| `isFormBuilderFeatureEnabled(config)` | `boolean` | Check `services.formBuilder.enabled` |
-| `isEmailFeatureEnabled(config)` | `boolean` | Check `services.email.enabled` |
-| `getPermissionMode(config)` | `PermissionMode` | Permission mode (default: `'full'`) |
-| `getDefaultStorageConfigId(config)` | `string \| undefined` | Default storage config ID |
-| `isSignUpEnabled(config)` | `boolean` | Sign-up enabled (default: `true`) |
-| `getDefaultCompanySlug(config)` | `string \| undefined` | Registration default company |
-| `getDefaultBranchSlug(config)` | `string \| undefined` | Registration default branch |
-| `getRegistrationDefaults(config)` | `IRegistrationDefaults \| undefined` | Full registration defaults |
-
-**ServiceName:** `'auth' | 'administration' | 'iam' | 'storage' | 'formBuilder' | 'email'`
-
-### Constants
+### 2. Provide Config in `app.config.ts`
 
 ```typescript
-export const DEFAULT_APP_NAME = 'FLUSYS';
-export const DEFAULT_AUTHOR: IAuthorConfig = { name: 'Flusys', url: 'https://flusys.vercel.app' };
+import { ApplicationConfig } from '@angular/core';
+import { APP_CONFIG } from '@flusys/ng-core';
+import { environment } from './environments/environment';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    { provide: APP_CONFIG, useValue: environment },
+    // ... other providers
+  ],
+};
 ```
 
-### Configuration Modes
+### 3. Inject Config Anywhere
 
-| Mode | `enableCompanyFeature` | `multiTenant.enabled` | Services |
-|------|------------------------|----------------------|----------|
-| Simple | `false` | `false` | Disabled |
-| Single DB + Multi-Company | `true` | `false` | Enabled |
-| Multi-Tenant | `true` | `true` | Enabled |
+```typescript
+import { inject } from '@angular/core';
+import { APP_CONFIG, IAppConfig } from '@flusys/ng-core';
 
----
+@Injectable({ providedIn: 'root' })
+export class MyService {
+  private config = inject<IAppConfig>(APP_CONFIG);
+
+  getApiUrl(): string {
+    return this.config.apiBaseUrl;
+  }
+}
+```
 
-## 2. HTTP Interceptors
+---
 
-Both use modern Angular functional interceptor pattern.
+## Configuration Reference
 
-### apiLoaderInterceptor
+### IAppConfig
 
-Tracks loading state with tagged loaders via `x-loader-tag` header.
+Complete configuration interface for the FLUSYS platform:
 
 ```typescript
-export function apiLoaderInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
-  const loaderService = inject(ApiLoaderService);
-  const loaderTag = req.headers.get('x-loader-tag') ?? loaderService.DEFAULT_TAG;
+interface IAppConfig {
+  /** Application display name */
+  appName: string;
 
-  loaderService.increase(loaderTag);
-  const cleanReq = req.clone({ headers: req.headers.delete('x-loader-tag') });
+  /** Backend API base URL */
+  apiBaseUrl: string;
 
-  return next(cleanReq).pipe(finalize(() => loaderService.decrease(loaderTag)));
-}
-```
+  /** Production mode flag */
+  production: boolean;
 
-**Usage:**
-```typescript
-this.http.post('/api/users/get-all', filter, {
-  headers: new HttpHeaders({ 'x-loader-tag': 'users-list' })
-});
-```
-
-### errorCatchingInterceptor
+  /** Multi-tenant mode — isolates data per company */
+  multiTenant?: boolean;
 
-Displays error toasts via PrimeNG `MessageService`.
+  /** IAM permission evaluation mode */
+  permissionMode?: 'RBAC' | 'DIRECT' | 'FULL';
 
-| Skips | Reason |
-|-------|--------|
-| 401 | Handled by `tokenRefreshInterceptor` |
-| 403 | Handled by permission UI |
-| `/check-login` | Expected to fail when not logged in |
-| `SKIP_ERROR_TOAST` context | Component handles locally |
+  services: {
+    auth?: {
+      enabled: boolean;
+      features?: {
+        /** Allow self-registration */
+        signUp?: boolean;
+        /** Email verification on register */
+        emailVerification?: boolean;
+        /** Require company selection after login */
+        companySelection?: boolean;
+      };
+    };
+    iam?: { enabled: boolean };
+    storage?: { enabled: boolean };
+    email?: { enabled: boolean };
+    formBuilder?: { enabled: boolean };
+    eventManager?: { enabled: boolean };
+    notification?: { enabled: boolean };
+    localization?: { enabled: boolean };
+  };
+}
+```
 
-**Error Extraction:** Uses `error.error.error` as summary, `error.error.message` as detail (handles NestJS array format). SSR-safe.
+### APP_CONFIG Token
 
-**Skip Toast for Local Handling:**
 ```typescript
-this.http.post(url, data, { context: new HttpContext().set(SKIP_ERROR_TOAST, true) });
+import { APP_CONFIG } from '@flusys/ng-core';
+
+// In component/service
+const config = inject<IAppConfig>(APP_CONFIG);
 ```
 
 ---
 
-## 3. Services
+## Base Services
 
-### ApiLoaderService
+### BaseApiService
 
-Signal-based loading state with tagged loaders.
+Typed HTTP client configured for POST-only RPC endpoints. All FLUSYS API services extend this class.
 
 ```typescript
+import { BaseApiService, ISingleResponse, IListResponse } from '@flusys/ng-core';
+
 @Injectable({ providedIn: 'root' })
-export class ApiLoaderService {
-  private readonly loaders = signal<Record<string, number>>({});
-  readonly DEFAULT_TAG = 'default';
+export class ProductApiService extends BaseApiService {
+  protected resource = 'product';
 
-  readonly show: Signal<boolean> = computed(() =>
-    Object.values(this.loaders()).some((count) => count > 0)
-  );
+  getAll(params: IListParams): Observable<IListResponse<Product>> {
+    return this.post(`${this.resource}/get-all`, params);
+  }
 
-  getLoader(name: string): Signal<boolean> {
-    return computed(() => (this.loaders()[name] ?? 0) > 0);
+  getById(id: string): Observable<ISingleResponse<Product>> {
+    return this.post(`${this.resource}/get/${id}`, {});
   }
 
-  increase(name: string = this.DEFAULT_TAG): void { /* increment */ }
-  decrease(name: string = this.DEFAULT_TAG): void { /* decrement, min 0 */ }
+  insert(data: CreateProductDto): Observable<ISingleResponse<Product>> {
+    return this.post(`${this.resource}/insert`, data);
+  }
+
+  update(data: UpdateProductDto): Observable<ISingleResponse<Product>> {
+    return this.post(`${this.resource}/update`, data);
+  }
+
+  delete(id: string): Observable<IMessageResponse> {
+    return this.post(`${this.resource}/delete`, { id });
+  }
 }
 ```
 
-**Usage:**
-```typescript
-@if (apiLoaderService.show()) { <p-progressBar mode="indeterminate" /> }
-@if (apiLoaderService.getLoader('users-list')()) { <p-skeleton /> }
-```
+**Key Methods:**
 
-### BaseApiService
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `post<T>` | `(path, body, options?)` | POST request with automatic base URL |
+| `get<T>` | `(path, options?)` | GET request (rarely used in FLUSYS) |
+| `setLoader` | `(show: boolean)` | Manually toggle loading indicator |
+
+**BaseApiService** automatically:
+- Prepends `apiBaseUrl` from `APP_CONFIG`
+- Sets `Content-Type: application/json`
+- Triggers `ApiLoaderService` for loading state
+- Normalizes errors through `GlobalErrorHandler`
+
+### ApiLoaderService
 
-Abstract base for API services with automatic URL resolution.
+Tracks concurrent HTTP requests to show/hide global loading indicators.
 
 ```typescript
-export abstract class BaseApiService {
-  protected readonly http = inject(HttpClient);
-  protected readonly appConfig = inject(APP_CONFIG);
-  protected readonly baseUrl: string;
+import { ApiLoaderService } from '@flusys/ng-core';
 
-  constructor(serviceName: string) {
-    this.baseUrl = getServiceUrl(this.appConfig, serviceName);
-  }
+@Component({ ... })
+export class AppComponent {
+  private loader = inject(ApiLoaderService);
 
-  protected getUrl(endpoint: string): string {
-    const clean = endpoint.startsWith('/') ? endpoint.substring(1) : endpoint;
-    return `${this.baseUrl}/${clean}`;
-  }
+  // Reactive loading state (signal)
+  isLoading = this.loader.isLoading;
 }
 ```
 
-**Usage:**
-```typescript
-@Injectable({ providedIn: 'root' })
-export class UserApiService extends BaseApiService {
-  constructor() { super('auth'); }
-  getAll(filter: any) { return this.http.post(this.getUrl('user/get-all'), filter); }
+```html
+<!-- Use in template -->
+@if (isLoading()) {
+  <p-progressBar mode="indeterminate" />
 }
 ```
 
----
+**ApiLoaderService API:**
 
-## 4. Components
+| Member | Type | Description |
+|--------|------|-------------|
+| `isLoading` | `Signal<boolean>` | True when any HTTP request is pending |
+| `increment()` | `void` | Manually increment request counter |
+| `decrement()` | `void` | Manually decrement request counter |
 
-### LibAppConfigComponent
+---
+
+## HTTP Interceptors
 
-Root configuration component. Include once at app root.
+`@flusys/ng-core` provides base HTTP interceptors registered via `provideHttpClient`:
 
-- **Selector:** `lib-app-config`
+### Base URL Interceptor
 
-**Provides:** Global loading progress bar (fixed top, 4px, z-index 998), toast notifications (success uses primary color), confirm dialogs.
+Automatically prepends `APP_CONFIG.apiBaseUrl` to all relative HTTP requests.
 
-**Usage:**
 ```typescript
-@Component({
-  selector: 'app-root',
-  imports: [LibAppConfigComponent, RouterOutlet],
-  template: `<lib-app-config /><router-outlet />`
-})
-export class AppComponent {}
+// Absolute URLs are passed through unchanged
+// Relative URLs like '/auth/login' become 'http://localhost:2002/auth/login'
 ```
 
----
+### Error Normalizer Interceptor
 
-## Setup
+Normalizes all HTTP error responses into a consistent `IErrorResponse` shape before they reach your services.
+
+### Registering Interceptors
 
 ```typescript
-// app.config.ts
-import { APP_CONFIG, errorCatchingInterceptor, apiLoaderInterceptor } from '@flusys/ng-core';
-import { authInterceptor, tokenRefreshInterceptor } from '@flusys/ng-auth';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { baseUrlInterceptor, errorNormalizerInterceptor } from '@flusys/ng-core';
 
 export const appConfig: ApplicationConfig = {
   providers: [
     provideHttpClient(
-      withFetch(),
       withInterceptors([
-        authInterceptor,           // ng-auth: auth + tenant headers
-        tokenRefreshInterceptor,   // ng-auth: 401 + refresh
-        errorCatchingInterceptor,  // ng-core: error toasts
-        apiLoaderInterceptor,      // ng-core: loading state
+        baseUrlInterceptor,
+        errorNormalizerInterceptor,
       ])
     ),
-    { provide: APP_CONFIG, useValue: DEFAULT_APP_CONFIG },
-  ]
+  ],
 };
 ```
 
 ---
 
-## Best Practices
+## Helper Functions
 
-1. **Always provide APP_CONFIG** at application root
-2. **Match backend mode** - `multiTenant.enabled` should align with FLUSYS_NEST
-3. **Never import other @flusys packages** in ng-core
-4. **Use `BaseApiService`** for all API services
-5. **Use tagged loaders** for granular loading states
+Feature detection helpers that read from `APP_CONFIG`:
 
-## Common Issues
+```typescript
+import {
+  isAuthEnabled,
+  isIamEnabled,
+  isStorageEnabled,
+  isSignUpEnabled,
+  isEmailVerificationEnabled,
+  isCompanySelectionEnabled,
+  isLocalizationEnabled,
+  isNotificationEnabled,
+} from '@flusys/ng-core';
+
+// Usage in a service or guard
+const authOn = isAuthEnabled(config);       // boolean
+const iamOn = isIamEnabled(config);         // boolean
+const storageOn = isStorageEnabled(config); // boolean
+const signUpOn = isSignUpEnabled(config);   // boolean
+```
 
-| Issue | Solution |
-|-------|----------|
-| `NullInjectorError: APP_CONFIG` | Add `{ provide: APP_CONFIG, useValue: config }` to providers |
-| Circular dependency | ng-core must NOT import other @flusys packages |
-| Loader flickers | Counter-based system handles concurrent requests automatically |
-| No error toast | Check: MessageService configured, not 401/403, not SKIP_ERROR_TOAST |
+---
+
+## Exported Tokens
+
+| Token | Type | Description |
+|-------|------|-------------|
+| `APP_CONFIG` | `InjectionToken<IAppConfig>` | Global app configuration |
+| `TRANSLATE_ADAPTER` | `InjectionToken<ITranslateAdapter>` | Localization adapter interface |
 
 ---
 
-## See Also
+## Troubleshooting
+
+**`NullInjectorError: No provider for APP_CONFIG`**
+
+You forgot to provide `APP_CONFIG` in `app.config.ts`:
 
-- [SHARED-GUIDE.md](./SHARED-GUIDE.md) - Components, directives, pipes
-- [LAYOUT-GUIDE.md](./LAYOUT-GUIDE.md) - Layout system
-- [FLUSYS_NEST/docs/CORE-GUIDE.md](../../FLUSYS_NEST/docs/CORE-GUIDE.md) - Backend core
+```typescript
+providers: [
+  { provide: APP_CONFIG, useValue: environment },
+]
+```
+
+**`Cannot read properties of undefined (reading 'apiBaseUrl')`**
+
+`APP_CONFIG` was provided but the environment object is missing the required field. Check that your environment file implements the full `IAppConfig` interface.
+
+**`HTTP 404 on API requests`**
+
+Check that `apiBaseUrl` does not have a trailing slash:
+
+```typescript
+// ❌ Wrong
+apiBaseUrl: 'http://localhost:2002/'
+
+// ✅ Correct
+apiBaseUrl: 'http://localhost:2002'
+```
 
 ---
 
-**Last Updated:** 2026-02-25 | **Version:** 3.0.1 | **Angular:** 21
+## License
+
+MIT © FLUSYS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/ng-core",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "Core utilities and services for FLUSYS Angular packages",
   "license": "MIT",
   "peerDependencies": {