@flusys/ng-core 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -0,0 +1,552 @@
+# @flusys/ng-core Package Guide
+
+## Overview
+
+`@flusys/ng-core` is the foundation package that provides core functionality for all FLUSYS Angular libraries and applications. It contains configuration management, HTTP interceptors, base services, and type definitions.
+
+**Key Principle:** ng-core has NO internal dependencies on other @flusys packages. All other packages depend on ng-core.
+
+## Package Information
+
+- **Package:** `@flusys/ng-core`
+- **Dependencies:** None (base package)
+- **Dependents:** ng-shared, ng-layout, ng-auth, ng-iam, ng-storage, flusysng
+- **Build Command:** `npm run build:ng-core`
+
+## Package Structure
+
+```
+ng-core/
+├── components/
+│   └── lib-app-config/
+│       ├── lib-app-config.component.ts
+│       ├── lib-app-config.component.html
+│       └── lib-app-config.component.scss
+├── interceptors/
+│   ├── api-loader.interceptor.ts
+│   └── error-catching.interceptor.ts
+├── interfaces/
+│   └── app-config.interface.ts
+├── services/
+│   ├── api-loader.service.ts
+│   └── base-api.service.ts
+└── public-api.ts
+```
+
+## Public API Exports
+
+```typescript
+// Components
+export * from './components/lib-app-config/lib-app-config.component';
+
+// Interceptors
+export * from './interceptors/api-loader.interceptor';
+export * from './interceptors/error-catching.interceptor';
+
+// Interfaces
+export * from './interfaces/app-config.interface';
+
+// Services
+export * from './services/api-loader.service';
+export * from './services/base-api.service';
+```
+
+---
+
+## Features
+
+### 1. APP_CONFIG (Configuration Management)
+
+Centralized configuration system with dynamic service URLs and feature flags.
+
+#### IAppConfig Interface
+
+```typescript
+export type PermissionMode = 'rbac' | 'direct' | 'full';
+
+export interface IServiceConfig {
+  baseUrl: string;
+  enabled: boolean;
+}
+
+export interface IAppConfig {
+  appName: string;
+  apiBaseUrl: string;                    // Default fallback URL
+  enableCompanyFeature: boolean;         // Company/branch selection
+
+  services: {
+    auth: IServiceConfig;
+    iam: IServiceConfig;
+    storage: IServiceConfig;
+    [key: string]: IServiceConfig;       // Extensible for custom services
+  };
+
+  multiTenant: {
+    enabled: boolean;                    // true = multi-tenant DB, false = single DB
+    tenantHeader: string;                // Header name (e.g., 'x-tenant-id')
+    tenantId?: string;                   // Optional tenant ID value
+  };
+
+  permissionMode?: PermissionMode;       // Defaults to 'full'
+}
+```
+
+#### APP_CONFIG Token
+
+```typescript
+export const APP_CONFIG = new InjectionToken<IAppConfig>('APP_CONFIG');
+```
+
+**Provider setup in app.config.ts:**
+
+```typescript
+import { APP_CONFIG } from '@flusys/ng-core';
+import { DEFAULT_APP_CONFIG } from './config/app.config';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    { provide: APP_CONFIG, useValue: DEFAULT_APP_CONFIG },
+  ]
+};
+```
+
+#### Environment Structure (Shared Base Pattern)
+
+All common configuration is extracted to a shared base:
+
+```typescript
+// projects/flusysng/src/environments/environment.base.ts
+export const BASE_ENVIRONMENT = {
+  appName: 'FLUSYS',
+  multiTenant: { enabled: false, tenantHeader: 'x-tenant-id' },
+  storage: { apiPath: '/upload/file', maxFileSize: 10485760, allowedMimeTypes: [...] },
+};
+
+// projects/flusysng/src/environments/environment.ts (development)
+import { BASE_ENVIRONMENT } from './environment.base';
+
+export const environment = {
+  ...BASE_ENVIRONMENT,
+  production: false,
+  apiBaseUrl: 'http://localhost:2002',
+  services: {
+    auth: { baseUrl: 'http://localhost:2002/auth', enabled: true },
+    iam: { baseUrl: 'http://localhost:2002/iam', enabled: true },
+    storage: { baseUrl: 'http://localhost:2002/storage', enabled: true },
+  },
+};
+```
+
+#### Helper Functions
+
+```typescript
+import {
+  getDatabaseMode,
+  isFeatureEnabled,
+  getServiceUrl,
+  isServiceEnabled,
+  isCompanyFeatureEnabled,
+  isStorageFeatureEnabled,
+  getPermissionMode,
+} from '@flusys/ng-core';
+```
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getDatabaseMode` | `(config) → 'single' \| 'multi-tenant'` | Get database mode from `multiTenant.enabled` |
+| `isFeatureEnabled` | `(config, feature: 'auth' \| 'iam' \| 'storage') → boolean` | Check if a service feature is enabled |
+| `getServiceUrl` | `(config, serviceName) → string` | Get service URL or fallback to `apiBaseUrl` |
+| `isServiceEnabled` | `(config, serviceName) → boolean` | Check if a service is enabled |
+| `isCompanyFeatureEnabled` | `(config) → boolean` | Check `enableCompanyFeature` flag |
+| `isStorageFeatureEnabled` | `(config) → boolean` | Check `services.storage.enabled` |
+| `getPermissionMode` | `(config) → PermissionMode` | Get permission mode (defaults to `'full'`) |
+
+#### Constants
+
+```typescript
+export const DEFAULT_APP_NAME = 'FLUSYS';
+```
+
+#### Configuration Modes
+
+**Mode 1: Simple (No Company, No IAM)**
+```typescript
+{
+  enableCompanyFeature: false,
+  multiTenant: { enabled: false, tenantHeader: 'x-tenant-id' },
+  services: {
+    auth: { baseUrl: '...', enabled: false },
+    iam: { baseUrl: '...', enabled: false },
+    storage: { baseUrl: '...', enabled: false },
+  }
+}
+```
+
+**Mode 2: Single DB + Multi-Company**
+```typescript
+{
+  enableCompanyFeature: true,
+  multiTenant: { enabled: false, tenantHeader: 'x-tenant-id' },
+  services: {
+    auth: { baseUrl: 'http://localhost:2002/auth', enabled: true },
+    iam: { baseUrl: 'http://localhost:2002/iam', enabled: true },
+    storage: { baseUrl: 'http://localhost:2002/storage', enabled: true },
+  }
+}
+```
+
+**Mode 3: Multi-Tenant**
+```typescript
+{
+  enableCompanyFeature: true,
+  multiTenant: { enabled: true, tenantHeader: 'x-tenant-id', tenantId: 'tenant-123' },
+  services: {
+    auth: { baseUrl: 'http://localhost:2002/auth', enabled: true },
+    iam: { baseUrl: 'http://localhost:2002/iam', enabled: true },
+    storage: { baseUrl: 'http://localhost:2002/storage', enabled: true },
+  }
+}
+```
+
+---
+
+### 2. HTTP Interceptors
+
+ng-core provides two functional interceptors. Both use the modern Angular functional interceptor pattern.
+
+#### apiLoaderInterceptor
+
+Tracks HTTP request loading state with tagged loaders. Uses a custom `x-loader-tag` header to group related requests.
+
+**Behavior:**
+1. Reads `x-loader-tag` header from request (defaults to `'default'`)
+2. Increments loader count for that tag
+3. Removes `x-loader-tag` header before sending to backend
+4. Decrements loader count on request completion (success or error)
+
+```typescript
+import { apiLoaderInterceptor } from '@flusys/ng-core';
+
+// Tag a specific request
+this.http.post('/api/users/get-all', filter, {
+  headers: new HttpHeaders({ 'x-loader-tag': 'users-list' })
+});
+
+// Check loading state for that tag
+apiLoaderService.getLoader('users-list')(); // true while loading
+```
+
+#### errorCatchingInterceptor
+
+Displays user-friendly error toast messages for failed HTTP requests via PrimeNG `MessageService`.
+
+**Behavior:**
+- Skips 401 errors (handled by `tokenRefreshInterceptor` in ng-auth)
+- Skips `/check-login` endpoint errors (expected to fail when not logged in)
+- Extracts message from `error.error.message` (string or array), `error.message`, or fallback
+- SSR-safe: only displays messages in browser (`isPlatformBrowser` check)
+
+#### Interceptor Chain
+
+```typescript
+import { errorCatchingInterceptor, apiLoaderInterceptor } from '@flusys/ng-core';
+import { authInterceptor, tokenRefreshInterceptor } from '@flusys/ng-auth';
+
+provideHttpClient(
+  withFetch(),
+  withInterceptors([
+    authInterceptor,           // from @flusys/ng-auth (adds auth + tenant headers)
+    tokenRefreshInterceptor,   // from @flusys/ng-auth (handles 401 + token refresh)
+    errorCatchingInterceptor,  // from @flusys/ng-core (displays error toasts)
+    apiLoaderInterceptor,      // from @flusys/ng-core (tracks loading state)
+  ])
+)
+```
+
+**Order matters:** Auth interceptors first, then error handling, then loader tracking.
+
+---
+
+### 3. Services
+
+#### ApiLoaderService
+
+Signal-based loading state management with tagged loaders. Provided at root level.
+
+**Signals:**
+
+| Signal | Type | Description |
+|--------|------|-------------|
+| `show` | `Signal<boolean>` | `true` if ANY loader tag has active requests |
+
+**Methods:**
+
+| Method | Parameters | Description |
+|--------|-----------|-------------|
+| `increase(name?)` | `name: string = 'default'` | Increment loader count for a tag |
+| `decrease(name?)` | `name: string = 'default'` | Decrement loader count for a tag (min 0) |
+| `getLoader(name)` | `name: string` | Get computed `Signal<boolean>` for a specific tag |
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `DEFAULT_TAG` | `string` | Default tag name (`'default'`) |
+
+**Usage:**
+
+```typescript
+// Global loading state
+@if (apiLoaderService.show()) {
+  <p-progressBar mode="indeterminate" />
+}
+
+// Tag-specific loading state
+@if (apiLoaderService.getLoader('users-list')()) {
+  <p>Loading users...</p>
+}
+```
+
+#### BaseApiService
+
+Abstract base class for API services. Provides automatic URL resolution from APP_CONFIG.
+
+**Protected members:**
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `http` | `HttpClient` | Injected HTTP client |
+| `appConfig` | `IAppConfig` | Injected app configuration |
+| `baseUrl` | `string` | Resolved base URL for the service |
+
+**Protected methods:**
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `getUrl(endpoint)` | `endpoint: string` | `string` | Build full URL, removes leading slash to avoid double slashes |
+
+**Usage:**
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class UserApiService extends BaseApiService {
+  constructor() {
+    super('auth'); // Resolves to services.auth.baseUrl
+  }
+
+  getAll(filter: any) {
+    return this.http.post(this.getUrl('user/get-all'), filter);
+  }
+
+  getById(id: string) {
+    return this.http.post(`${this.getUrl('user/get')}/${id}`, {});
+  }
+}
+```
+
+---
+
+### 4. Components
+
+#### LibAppConfigComponent
+
+Root configuration component providing global UI elements. Include once at app root.
+
+**Selector:** `lib-app-config`
+
+**Provides:**
+- Global loading progress bar (fixed top, 4px height, z-index 998)
+- Toast notifications (PrimeNG Toast)
+- Confirm dialogs (PrimeNG ConfirmDialog)
+
+**Template:**
+```html
+@if (apiLoaderService.show()) {
+  <p-progressBar mode="indeterminate" />
+}
+<p-toast />
+<p-confirmdialog />
+```
+
+**Usage:**
+```typescript
+import { LibAppConfigComponent } from '@flusys/ng-core';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [LibAppConfigComponent, RouterOutlet],
+  template: `
+    <lib-app-config />
+    <router-outlet />
+  `
+})
+export class AppComponent {}
+```
+
+---
+
+## Usage Examples
+
+### Basic App Setup
+
+```typescript
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient, withFetch, withInterceptors } from '@angular/common/http';
+import { APP_CONFIG, errorCatchingInterceptor, apiLoaderInterceptor } from '@flusys/ng-core';
+import { authInterceptor, tokenRefreshInterceptor } from '@flusys/ng-auth';
+import { DEFAULT_APP_CONFIG } from './config/app.config';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(
+      withFetch(),
+      withInterceptors([
+        authInterceptor,
+        tokenRefreshInterceptor,
+        errorCatchingInterceptor,
+        apiLoaderInterceptor,
+      ])
+    ),
+    { provide: APP_CONFIG, useValue: DEFAULT_APP_CONFIG },
+  ]
+};
+```
+
+### Creating an API Service
+
+```typescript
+import { Injectable } from '@angular/core';
+import { BaseApiService } from '@flusys/ng-core';
+
+@Injectable({ providedIn: 'root' })
+export class AuthApiService extends BaseApiService {
+  constructor() {
+    super('auth'); // Resolves to services.auth.baseUrl
+  }
+
+  login(credentials: any) {
+    return this.http.post(this.getUrl('auth/login'), credentials);
+  }
+}
+```
+
+### Using Tagged Loaders
+
+```typescript
+import { HttpHeaders } from '@angular/common/http';
+import { ApiLoaderService } from '@flusys/ng-core';
+
+// In a service - tag requests
+this.http.post('/api/users/get-all', filter, {
+  headers: new HttpHeaders({ 'x-loader-tag': 'users-list' })
+});
+
+// In a component - check specific loader
+readonly usersLoading = this.apiLoaderService.getLoader('users-list');
+
+// In template
+@if (usersLoading()) {
+  <p-skeleton />
+}
+```
+
+---
+
+## Best Practices
+
+1. **Always provide APP_CONFIG** at application root level
+2. **Match backend configuration mode** (`multiTenant.enabled` should align with FLUSYS_NEST setup)
+3. **Enable features based on backend availability** (`services.iam.enabled` only if IAM module is deployed)
+4. **Never import from other @flusys packages** in ng-core
+5. **Keep ng-core minimal** - only foundation functionality
+6. **Use `BaseApiService`** for all API services to avoid hardcoded URLs
+7. **Don't create custom error handling** - use `errorCatchingInterceptor`
+8. **Don't manually track loading** - use `apiLoaderInterceptor` with `x-loader-tag` headers
+
+## Common Issues
+
+### APP_CONFIG Not Found
+
+**Problem:** `NullInjectorError: No provider for InjectionToken APP_CONFIG`
+
+**Solution:** Provide APP_CONFIG in app.config.ts:
+```typescript
+{ provide: APP_CONFIG, useValue: DEFAULT_APP_CONFIG }
+```
+
+### Circular Dependency
+
+**Problem:** Build fails with circular dependency error involving ng-core.
+
+**Solution:** ng-core should NEVER import from other @flusys packages. Check imports and remove any references to ng-shared, ng-layout, or ng-auth.
+
+---
+
+## API Reference
+
+### Tokens
+
+| Token | Type | Description |
+|-------|------|-------------|
+| `APP_CONFIG` | `InjectionToken<IAppConfig>` | Application configuration |
+
+### Interceptors
+
+| Function | Description |
+|----------|-------------|
+| `apiLoaderInterceptor` | Loading state management with tagged loaders |
+| `errorCatchingInterceptor` | Error toast display (skips 401 and check-login) |
+
+### Services
+
+| Service | Description |
+|---------|-------------|
+| `ApiLoaderService` | Signal-based loading state with tagged loaders |
+| `BaseApiService` | Abstract base class for API services with URL resolution |
+
+### Interfaces & Types
+
+| Export | Description |
+|--------|-------------|
+| `IAppConfig` | App configuration interface |
+| `IServiceConfig` | Service configuration (`baseUrl`, `enabled`) |
+| `PermissionMode` | `'rbac' \| 'direct' \| 'full'` |
+
+### Helper Functions
+
+| Function | Description |
+|----------|-------------|
+| `getDatabaseMode(config)` | Returns `'single'` or `'multi-tenant'` |
+| `isFeatureEnabled(config, feature)` | Check service feature enabled (`'auth' \| 'iam' \| 'storage'`) |
+| `getServiceUrl(config, serviceName)` | Get service URL with fallback |
+| `isServiceEnabled(config, serviceName)` | Check if service is enabled |
+| `isCompanyFeatureEnabled(config)` | Check company feature flag |
+| `isStorageFeatureEnabled(config)` | Check storage service enabled |
+| `getPermissionMode(config)` | Get permission mode (default `'full'`) |
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `DEFAULT_APP_NAME` | `'FLUSYS'` | Default application name |
+
+### Components
+
+| Component | Selector | Description |
+|-----------|----------|-------------|
+| `LibAppConfigComponent` | `lib-app-config` | Global toast, confirm dialog, and loading bar |
+
+## See Also
+
+- **[SHARED-GUIDE.md](./SHARED-GUIDE.md)** - API services, components, directives
+- **[LAYOUT-GUIDE.md](./LAYOUT-GUIDE.md)** - Layout system
+- **[Angular Patterns](../../.claude/docs/angular/)** - Framework patterns
+- **[FLUSYS_NEST/docs/CORE-GUIDE.md](../../FLUSYS_NEST/docs/CORE-GUIDE.md)** - Backend core module
+
+---
+
+**Last Updated:** 2026-02-07
+**Package Version:** 1.0.0
+**Angular Version:** 21

package/package.json

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