@en-solutions/tgm-client-sdk 1.6.21

package/README.md

@@ -0,0 +1,788 @@
+# @en-solutions/tgm-client-sdk
+
+![Angular 18+](https://img.shields.io/badge/Angular-18%2B-DD0031?logo=angular&logoColor=white)
+![TypeScript 5.4](https://img.shields.io/badge/TypeScript-5.4-3178C6?logo=typescript&logoColor=white)
+![npm](https://img.shields.io/badge/npm-private-CB3837?logo=npm&logoColor=white)
+![RxJS 7.8](https://img.shields.io/badge/RxJS-7.8-B7178C?logo=reactivex&logoColor=white)
+
+---
+
+## Overview
+
+The **TGM Client SDK** is a comprehensive, type-safe Angular library that provides services for every endpoint exposed by the TGM Manager backend API. It ships **90+ injectable services** covering authentication, CRUD operations across dozens of domain entities, real-time chat (STOMP/WebSocket), video calling (LiveKit), reservoir management, platform administration, file management, search, AI integration, workflow approvals, and more.
+
+Everything is fully typed: **125 const-object enums**, **165+ DTOs and interfaces**, and a generic `BaseCrudService<T>` pattern that gives every domain entity a consistent `getAll`, `getById`, `create`, `update`, `delete`, and `count` API out of the box.
+
+---
+
+## Architecture
+
+```
+@en-solutions/tgm-client-sdk
+|
+|-- src/
+|   |-- public-api.ts                  Library entry point (barrel exports)
+|   |
+|   |-- lib/
+|       |-- tgm-sdk.module.ts          TgmSdkModule with forRoot() configuration
+|       |-- tgm-sdk.config.ts          TgmSdkConfig interface, InjectionToken, TokenStorageStrategy
+|       |
+|       |-- core/
+|       |   |-- http-client.service.ts  TgmHttpClient -- central HTTP layer with auth & multi-tenancy
+|       |   |-- auth-interceptor.ts     Attaches Authorization: Bearer <token> header
+|       |   |-- client-interceptor.ts   Attaches X-Client-ID header for tenant routing
+|       |   |-- websocket.service.ts    STOMP-over-SockJS WebSocket abstraction
+|       |   |-- error-handler.ts        TgmApiError class and mapHttpError utility
+|       |
+|       |-- models/
+|       |   |-- base.models.ts          ApiResponse, PagedResponse, PaginationParams, BaseEntity
+|       |   |-- enums/                  125 const-object enums across 11 files
+|       |   |   |-- status.enums.ts     WorkOrderStatus, UnitStatus, AlertStatus, etc.
+|       |   |   |-- type.enums.ts       WorkOrderType, ComponentType, DocumentType, etc.
+|       |   |   |-- energy.enums.ts     EnergySourceType, GridConnectionStatus, etc.
+|       |   |   |-- erp.enums.ts        ERPProvider, SyncStatus, etc.
+|       |   |   |-- sso.enums.ts        SsoProvider, SsoStrategy, etc.
+|       |   |   |-- inspection.enums.ts InspectionStatus, InspectionType, etc.
+|       |   |   |-- user.enums.ts       UserRole, UserStatus, etc.
+|       |   |   |-- time.enums.ts       Frequency, DayOfWeek, etc.
+|       |   |   |-- misc.enums.ts       Priority, Severity, Currency, etc.
+|       |   |   |-- reservoir.enums.ts  GateType, SampleType, AIScenarioType, ReadingType, etc.
+|       |   |-- auth/                   Login, SSO, TOTP request/response DTOs
+|       |   |-- admin/                  Client, Ticket, ERP, Webhook, Role, Audit DTOs
+|       |   |-- api/                    23 domain model files (units, work orders, reservoir, etc.)
+|       |   |   |-- reservoir.models.ts GateSystem, AlertDefinition, AIScenario, TimeSeriesQueryParams, etc.
+|       |   |-- chat/                   Conversation, ChatMessage, Presence, Typing DTOs
+|       |   |-- video/                  VideoCall, participant, signaling event DTOs
+|       |
+|       |-- services/
+|       |   |-- auth/                   4 services  -- AuthService, SsoAuthService, TotpService, PlatformAuthService
+|       |   |-- api/                    57 services -- Domain CRUD (units, work orders, components, reservoir, etc.)
+|       |   |-- admin/                  30 services -- Platform admin, client management, ERP, webhooks
+|       |   |-- chat/                   2 services  -- ChatRestService, ChatWebSocketService
+|       |   |-- video/                  2 services  -- VideoCallRestService, VideoCallWebSocketService
+|       |   |-- reservoir/              1 service   -- ReservoirWebSocketService (real-time 4-stream WebSocket)
+|       |
+|       |-- components/
+|           |-- video-call/
+|               |-- video-call.module.ts         VideoCallModule (standalone Angular module)
+|               |-- video-room/                  VideoRoomComponent
+|               |-- video-controls/              VideoControlsComponent
+|               |-- video-participant/           VideoParticipantComponent
+|               |-- incoming-call/               IncomingCallComponent
+|               |-- services/                    LivekitRoomService, VideoCallSignalingService, VideoCallStateService
+|               |-- types/                       ParticipantInfo, VideoCallState
+|
+|-- docs/                              10 detailed Markdown guides
+|-- ng-package.json                    ng-packagr build configuration
+|-- package.json                       Package metadata, scripts, dependencies
+|-- tsconfig.json                      TypeScript configuration
+```
+
+---
+
+## Features
+
+- **Type-safe services** -- Every API endpoint is wrapped in an Angular `@Injectable` service with full TypeScript generics and strict return types.
+- **Generic BaseCrudService pattern** -- Domain services extend `BaseCrudService<T, CreateReq, UpdateReq>` which provides `getAll()`, `getById()`, `create()`, `update()`, `delete()`, and `count()` automatically.
+- **Automatic authentication** -- JWT tokens are attached to every request via `AuthInterceptor`. On a `401` response, the SDK transparently refreshes the token and retries the original request.
+- **Pluggable token storage** -- Implement `TokenStorageStrategy` to swap between in-memory (default), `localStorage`, `sessionStorage`, or any custom persistence layer.
+- **Multi-tenancy support** -- The `ClientInterceptor` attaches an `X-Client-ID` header to every request. The client ID can be set statically in configuration or changed at runtime via `TgmHttpClient.setClientId()`.
+- **Real-time chat** -- `ChatWebSocketService` provides reactive observables for incoming messages, typing indicators, presence updates, read receipts, and emoji reactions over STOMP/SockJS.
+- **Video calling** -- `VideoCallRestService` manages call lifecycle (initiate, answer, join, end). Pre-built Angular components (`VideoRoomComponent`, `VideoControlsComponent`, `VideoParticipantComponent`, `IncomingCallComponent`) integrate with LiveKit for WebRTC video/audio.
+- **Reservoir management** -- 11 services for hydroelectric dam operations including gate control, sensor time-series, environmental compliance, and AI optimization scenarios, plus a real-time 4-stream WebSocket service.
+- **125 const-object enums** -- `WorkOrderStatus`, `UnitStatus`, `AlertSeverity`, `ERPProvider`, `GateType`, `AIScenarioType`, and 119 more, all defined as const objects with companion union types for compile-time safety and runtime iteration.
+- **165+ DTOs and interfaces** -- Covering units, components, work orders, inspections, interventions, fleet, energy, compliance, quality, materials, sensors, budgets, projects, warranties, knowledge base, reservoir management, and more.
+- **File upload and download** -- `UploadService` supports single/multi-file upload, file linking, batch operations, and binary download.
+- **Platform administration** -- 30 admin services for client management, API keys, subscriptions, ERP connections, identity providers, webhooks, backups, audit logs, impersonation, OCR, and system health.
+- **AI and search integration** -- `AiService` and `SearchService` for platform-wide intelligent search and AI-powered features.
+- **Structured error handling** -- All HTTP errors are mapped to a `TgmSdkError` object with status code, message, raw error body, and original `HttpErrorResponse`.
+
+---
+
+## Installation
+
+### From GitHub Packages (recommended)
+
+The SDK is published to **GitHub Packages** under the `@ensolutions` scope.
+
+#### 1. Create a GitHub Personal Access Token (PAT)
+
+Go to **GitHub > Settings > Developer settings > Personal access tokens > Tokens (classic)** and create a token with the `read:packages` scope.
+
+#### 2. Configure npm to use GitHub Packages for the `@ensolutions` scope
+
+Create or edit an `.npmrc` file in your Angular project root:
+
+```ini
+@en-solutions:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT
+```
+
+> **Tip**: To avoid committing your token, set it as an environment variable instead:
+> ```ini
+> @en-solutions:registry=https://npm.pkg.github.com
+> //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+> ```
+> Then export it in your shell: `export GITHUB_TOKEN=ghp_xxxxxxxxxxxx`
+
+#### 3. Install the SDK
+
+```bash
+npm install @en-solutions/tgm-client-sdk
+```
+
+#### CI/CD (GitHub Actions)
+
+In GitHub Actions, the built-in `GITHUB_TOKEN` secret has `read:packages` permission by default:
+
+```yaml
+- name: Install dependencies
+  run: npm ci
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+With this `.npmrc` in your project:
+```ini
+@en-solutions:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+```
+
+### From source (npm link for local development)
+
+```bash
+# Build the SDK
+cd /path/to/tgm-client-sdk
+npm install
+npm run build
+
+# Link it globally
+npm link
+
+# In your Angular application
+cd /path/to/your-angular-app
+npm link @en-solutions/tgm-client-sdk
+```
+
+### Peer Dependencies
+
+These must already be installed in your Angular application:
+
+| Package            | Version    |
+|--------------------|------------|
+| `@angular/common`  | `^18.0.0`  |
+| `@angular/core`    | `^18.0.0`  |
+| `rxjs`             | `^7.8.0`   |
+
+### Runtime Dependencies (bundled)
+
+| Package            | Purpose                                       |
+|--------------------|-----------------------------------------------|
+| `@stomp/stompjs`   | STOMP WebSocket protocol for chat and video signaling |
+| `sockjs-client`    | WebSocket fallback transport                  |
+| `livekit-client`   | LiveKit WebRTC video/audio room integration   |
+
+---
+
+## Quick Start
+
+### 1. Import the module
+
+```typescript
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { TgmSdkModule } from '@en-solutions/tgm-client-sdk';
+
+@NgModule({
+  imports: [
+    BrowserModule,
+    TgmSdkModule.forRoot({
+      baseUrl: 'http://localhost:1337',
+      clientId: 'my-tenant-id',
+    }),
+  ],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+```
+
+### 2. Inject a service and make a call
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+import { UnitService, Unit, PagedResponse } from '@en-solutions/tgm-client-sdk';
+
+@Component({
+  selector: 'app-units',
+  template: `
+    <ul>
+      <li *ngFor="let unit of units">{{ unit.name }} -- {{ unit.status }}</li>
+    </ul>
+  `,
+})
+export class UnitsComponent implements OnInit {
+  units: Unit[] = [];
+
+  constructor(private unitService: UnitService) {}
+
+  ngOnInit(): void {
+    this.unitService.getAll({ page: 0, pageSize: 25 }).subscribe({
+      next: (response: PagedResponse<Unit>) => {
+        this.units = response.data;
+        console.log('Total units:', response.meta.pagination.total);
+      },
+      error: (err) => console.error('Failed to load units:', err.message),
+    });
+  }
+}
+```
+
+---
+
+## Configuration
+
+The `TgmSdkConfig` interface accepts the following options:
+
+```typescript
+TgmSdkModule.forRoot({
+  baseUrl: 'http://localhost:1337',
+  clientId: 'my-tenant-id',
+  wsEndpoint: '/ws',
+  tokenStorage: new MyCustomTokenStorage(),
+  autoRefresh: true,
+  tokenKey: 'jwt',
+  refreshTokenKey: 'refreshToken',
+});
+```
+
+| Option             | Type                    | Default            | Description |
+|--------------------|-------------------------|--------------------|-------------|
+| `baseUrl`          | `string`                | **(required)**     | Base URL of the TGM Manager backend (e.g., `http://localhost:1337`). Trailing slashes are automatically stripped. |
+| `clientId`         | `string`                | `undefined`        | Static client/tenant identifier. Sent as the `X-Client-ID` header on every request. Can also be changed at runtime with `TgmHttpClient.setClientId()`. |
+| `wsEndpoint`       | `string`                | `'/ws'`            | WebSocket endpoint path for STOMP connections (chat and video signaling). |
+| `tokenStorage`     | `TokenStorageStrategy`  | `InMemoryTokenStorage` | Pluggable token persistence. Implement `getToken()`, `setToken()`, `removeToken()`, `getRefreshToken()`, `setRefreshToken()`, `removeRefreshToken()` for custom storage. |
+| `autoRefresh`      | `boolean`               | `true`             | When `true`, the SDK automatically attempts to refresh the JWT using the stored refresh token on any `401` response, then retries the original request. |
+| `tokenKey`         | `string`                | `'jwt'`            | The property name used to extract the access token from authentication response payloads. |
+| `refreshTokenKey`  | `string`                | `'refreshToken'`   | The property name used to extract the refresh token from authentication response payloads. |
+
+### Custom Token Storage Example
+
+```typescript
+export class LocalStorageTokenStorage implements TokenStorageStrategy {
+  getToken(): string | null {
+    return localStorage.getItem('tgm_token');
+  }
+  setToken(token: string): void {
+    localStorage.setItem('tgm_token', token);
+  }
+  removeToken(): void {
+    localStorage.removeItem('tgm_token');
+  }
+  getRefreshToken(): string | null {
+    return localStorage.getItem('tgm_refresh_token');
+  }
+  setRefreshToken(token: string): void {
+    localStorage.setItem('tgm_refresh_token', token);
+  }
+  removeRefreshToken(): void {
+    localStorage.removeItem('tgm_refresh_token');
+  }
+}
+
+// Usage
+TgmSdkModule.forRoot({
+  baseUrl: 'http://localhost:1337',
+  tokenStorage: new LocalStorageTokenStorage(),
+});
+```
+
+---
+
+## Usage Examples
+
+### Authentication
+
+```typescript
+import { AuthService, AuthResponse } from '@en-solutions/tgm-client-sdk';
+
+// Login with email/password
+this.authService.login({ identifier: 'user@example.com', password: 'secret' }).subscribe({
+  next: (res: AuthResponse) => {
+    console.log('Logged in as:', res.user.username);
+    // Tokens are stored automatically via handleAuthResponse()
+  },
+  error: (err) => console.error('Login failed:', err.message),
+});
+
+// Badge/PIN login
+this.authService.badgeLogin({ badgeNumber: 'ABC123', pin: '1234' }).subscribe();
+
+// Check authentication state reactively
+this.authService.isAuthenticated$.subscribe((isAuth) => {
+  console.log('Authenticated:', isAuth);
+});
+
+// Logout (clears tokens and resets user state)
+this.authService.logout();
+```
+
+### CRUD Operations
+
+Every domain service that extends `BaseCrudService` provides these methods:
+
+```typescript
+import { WorkOrderService, WorkOrder, WorkOrderStatus } from '@en-solutions/tgm-client-sdk';
+
+// List with pagination, sorting, and filtering
+this.workOrderService.getAll({
+  page: 0,
+  pageSize: 50,
+  sort: 'createdAt',
+  order: 'DESC',
+  status: WorkOrderStatus.IN_PROGRESS,
+}).subscribe((response) => {
+  console.log(response.data);                    // WorkOrder[]
+  console.log(response.meta.pagination.total);   // Total count
+});
+
+// Get by ID
+this.workOrderService.getById(42).subscribe((response) => {
+  console.log(response.data);  // WorkOrder
+});
+
+// Create
+this.workOrderService.create({
+  title: 'Replace pump bearings',
+  unitId: 7,
+  priority: 'HIGH',
+}).subscribe((response) => {
+  console.log('Created:', response.data.id);
+});
+
+// Update
+this.workOrderService.update(42, { status: WorkOrderStatus.COMPLETED }).subscribe();
+
+// Delete
+this.workOrderService.delete(42).subscribe();
+
+// Count
+this.workOrderService.count().subscribe((response) => {
+  console.log('Total work orders:', response.data);
+});
+```
+
+### Pagination Pattern
+
+```typescript
+import { PaginationParams, PagedResponse } from '@en-solutions/tgm-client-sdk';
+
+loadPage(page: number): void {
+  const params: PaginationParams = {
+    page,
+    pageSize: 25,
+    sort: 'name',
+    order: 'ASC',
+  };
+
+  this.unitService.getAll(params).subscribe((res: PagedResponse<Unit>) => {
+    this.items = res.data;
+    this.totalPages = res.meta.pagination.pageCount;
+    this.totalItems = res.meta.pagination.total;
+    this.currentPage = res.meta.pagination.page;
+  });
+}
+```
+
+### File Upload
+
+```typescript
+import { UploadService } from '@en-solutions/tgm-client-sdk';
+
+// Single file upload
+onFileSelected(event: Event): void {
+  const file = (event.target as HTMLInputElement).files?.[0];
+  if (file) {
+    this.uploadService.upload(file).subscribe({
+      next: (res) => console.log('Uploaded:', res.data),
+      error: (err) => console.error('Upload failed:', err.message),
+    });
+  }
+}
+
+// Multiple file upload
+this.uploadService.uploadMultiple(fileList).subscribe();
+
+// Download
+this.uploadService.download(fileId).subscribe((blob: Blob) => {
+  const url = URL.createObjectURL(blob);
+  window.open(url);
+});
+```
+
+### Real-Time Chat (WebSocket)
+
+```typescript
+import { ChatWebSocketService, ChatRestService, ChatMessage } from '@en-solutions/tgm-client-sdk';
+
+// Connect to the WebSocket
+this.chatWs.connect();
+
+// Listen for incoming messages
+this.chatWs.messages$.subscribe((message: ChatMessage) => {
+  console.log(`[${message.sender.username}]: ${message.content}`);
+});
+
+// Listen for typing indicators
+this.chatWs.typing$.subscribe((event) => {
+  console.log(`User ${event.userId} is ${event.typing ? 'typing' : 'idle'}`);
+});
+
+// Listen for presence updates
+this.chatWs.presence$.subscribe((presence) => {
+  console.log(`User ${presence.userId} is ${presence.status}`);
+});
+
+// Send a message
+this.chatWs.sendMessage({
+  conversationId: 1,
+  content: 'Hello, team!',
+});
+
+// Send typing indicator
+this.chatWs.sendTyping(1, true);
+
+// Mark messages as read
+this.chatWs.markRead(1, 456);
+
+// REST API for conversation management
+this.chatRest.getConversations({ page: 0, pageSize: 20 }).subscribe();
+this.chatRest.createConversation({ name: 'Project Alpha', participantIds: [2, 3, 4] }).subscribe();
+
+// Disconnect when done
+this.chatWs.disconnect();
+```
+
+### Video Calls
+
+```typescript
+import {
+  VideoCallRestService,
+  VideoCallWebSocketService,
+  VideoCallModule,
+} from '@en-solutions/tgm-client-sdk';
+
+// Initiate a call
+this.videoCallRest.initiateCall({
+  targetUserId: 5,
+  companyId: 1,
+  type: 'VIDEO',
+}).subscribe((res) => {
+  console.log('Call initiated:', res.data.id);
+});
+
+// Answer an incoming call
+this.videoCallRest.answerCall(callId, true).subscribe((res) => {
+  // res.data contains the LiveKit token for room connection
+  console.log('LiveKit token:', res.data?.token);
+});
+
+// End a call
+this.videoCallRest.endCall(callId).subscribe();
+
+// Use the pre-built video components by importing VideoCallModule
+// in your feature module:
+@NgModule({
+  imports: [VideoCallModule],
+})
+export class MyFeatureModule {}
+```
+
+### Reservoir Management
+
+```typescript
+import {
+  GateSystemService,
+  AlertDefinitionService,
+  ReservoirTimeSeriesService,
+  GateControlService,
+  ReservoirWebSocketService,
+  GateSystem,
+  AlertDefinition,
+  GateType,
+  GateControlType,
+} from '@en-solutions/tgm-client-sdk';
+
+// --- CRUD: Create a gate system ---
+this.gateSystemService.create({
+  name: 'Spillway Gate A1',
+  reservoirId: 1,
+  gateType: GateType.SPILLWAY,
+  controlType: GateControlType.HYDRAULIC,
+}).subscribe((res) => {
+  console.log('Created gate system:', res.data.id);
+});
+
+// --- CRUD: List alert definitions with pagination ---
+this.alertDefinitionService.getAll({
+  page: 0,
+  pageSize: 25,
+  sort: 'createdAt',
+  order: 'DESC',
+}).subscribe((res) => {
+  console.log('Alert definitions:', res.data);
+  console.log('Total:', res.meta.pagination.total);
+});
+
+// --- Time-Series: Query sensor data ---
+this.timeSeriesService.getSensorTimeSeries('reservoir-1', 'water_level', {
+  start: '2025-01-01T00:00:00Z',
+  end: '2025-01-31T23:59:59Z',
+  interval: '1h',
+  aggregation: 'mean',
+}).subscribe((res) => {
+  console.log('Sensor readings:', res.data);
+});
+
+// --- Time-Series: Get weather forecast ---
+this.timeSeriesService.getWeatherForecast('reservoir-1', {
+  start: '2025-02-01T00:00:00Z',
+  end: '2025-02-07T23:59:59Z',
+}).subscribe((res) => {
+  console.log('Weather forecast:', res.data);
+});
+
+// --- Gate Control: Operate a gate ---
+this.gateControlService.operateGate('gate-42', {
+  targetPosition: 75.0,
+  reason: 'Flood management -- increasing discharge',
+}).subscribe((res) => {
+  console.log('Gate operation event:', res.data);
+});
+
+// --- Gate Control: Acknowledge an alert ---
+this.gateControlService.acknowledgeAlert(123, {
+  acknowledgedBy: 'operator@example.com',
+  notes: 'Inspected on-site, situation resolved',
+}).subscribe((res) => {
+  console.log('Alert acknowledged:', res.data);
+});
+
+// --- Real-Time WebSocket: Connect to reservoir streams ---
+this.reservoirWs.connect('reservoir-1');
+
+// Listen for live sensor data
+this.reservoirWs.sensors$.subscribe((data) => {
+  console.log('Sensor update:', data);
+});
+
+// Listen for external data (weather, grid market, lab results)
+this.reservoirWs.externalData$.subscribe((data) => {
+  console.log('External data:', data);
+});
+
+// Listen for manual data (inspections, operator readings)
+this.reservoirWs.manualData$.subscribe((data) => {
+  console.log('Manual data:', data);
+});
+
+// Listen for status alerts and operating events
+this.reservoirWs.statusAlerts$.subscribe((alert) => {
+  console.log('Status alert:', alert);
+});
+
+// Disconnect when done
+this.reservoirWs.disconnect();
+```
+
+### Runtime Multi-Tenancy
+
+```typescript
+import { TgmHttpClient } from '@en-solutions/tgm-client-sdk';
+
+// Switch tenant at runtime (updates X-Client-ID header for all subsequent requests)
+this.httpClient.setClientId('new-tenant-id');
+
+// Check current tenant
+console.log('Current client:', this.httpClient.getClientId());
+```
+
+---
+
+## API Reference
+
+### Auth Services (4 services)
+
+| Service                | Methods | Description |
+|------------------------|---------|-------------|
+| `AuthService`          | 16      | Local login, badge login, registration, password reset, email verification, token refresh, user state |
+| `SsoAuthService`       | --      | SSO login flows (SAML, OIDC, etc.) |
+| `TotpService`          | --      | TOTP (time-based one-time password) setup and verification |
+| `PlatformAuthService`  | --      | Platform admin authentication (separate from tenant auth) |
+
+### API Services (57 services)
+
+| Service                      | Domain | Service                      | Domain |
+|------------------------------|--------|------------------------------|--------|
+| `UnitService`                | Units / Plants | `WorkOrderService`       | Work orders |
+| `ComponentService`           | Components / Assets | `InterventionService`  | Interventions |
+| `InterventionRequestService` | Intervention requests | `InspectionService`   | Inspections |
+| `CompanyService`             | Companies | `UserService`              | Users |
+| `DepartmentService`          | Departments | `LocationService`        | Locations |
+| `RoomService`                | Rooms | `DocumentService`            | Documents |
+| `MaterialItemService`        | Material items | `MaterialConsumableService` | Consumables |
+| `MaterialToolingService`     | Tooling | `MaterialInstrumentService` | Instruments |
+| `SensorService`              | IoT sensors | `AlertService`            | Alerts |
+| `EnergyService`              | Energy data | `FleetService`            | Fleet management |
+| `WarrantyService`            | Warranties | `ComplianceService`       | Compliance |
+| `QualityService`             | Quality (RCA, CAPA) | `FailureService`      | Failure tracking |
+| `ProjectService`             | Projects | `CapexProjectService`      | CapEx projects |
+| `BudgetService`              | Budgets | `BidService`                | Bids / Tenders |
+| `WorkflowService`            | Workflow approvals | `TodoService`          | To-do items |
+| `NoteService`                | Notes | `LogService`                 | Activity logs |
+| `EventService`               | Events | `CommunityService`          | Community |
+| `KnowledgeService`           | Knowledge base | `CustomFieldService`   | Custom fields |
+| `DashboardService`           | Dashboard | `SearchService`           | Global search |
+| `AiService`                  | AI features | `UploadService`          | File upload/download |
+| `ExportService`              | Data export | `ExtensionService`       | Extensions |
+| `SandboxService`             | Sandboxes | `LoginHistoryService`    | Login history |
+| `MiscCrudService`            | Misc entities | | |
+
+### Reservoir Management Services (11 services + 1 WebSocket)
+
+| Service | Endpoint | Description |
+|---------|----------|-------------|
+| `GateSystemService` | `/api/gate-systems` | Gate system configuration (CRUD) |
+| `AlertDefinitionService` | `/api/alert-definitions` | Alert rule definitions (CRUD) |
+| `ManualReadingService` | `/api/manual-readings` | Operator manual gauge readings (CRUD) |
+| `LaboratoryResultService` | `/api/laboratory-results` | Lab water/sediment analysis results (CRUD) |
+| `FishMonitoringService` | `/api/fish-monitoring` | Fish passage monitoring data (CRUD) |
+| `RegulatoryUpdateService` | `/api/regulatory-updates` | Regulatory compliance updates (CRUD) |
+| `OperationalObservationService` | `/api/operational-observations` | Field operator observations (CRUD) |
+| `BathymetricSurveyService` | `/api/bathymetric-surveys` | Reservoir bathymetry surveys (CRUD) |
+| `AIScenarioService` | `/api/ai-scenarios` | AI turbine dispatch optimization scenarios (CRUD) |
+| `ReservoirTimeSeriesService` | `/api/reservoirs/{id}/timeseries/*` | InfluxDB queries for sensor, weather, grid market, and gate data |
+| `GateControlService` | `/api/gates/{id}/operate` | Gate operations and alert acknowledgment |
+| `ReservoirWebSocketService` | STOMP `/topic/reservoir/{id}/*` | Real-time 4-stream WebSocket (sensors, external, manual, status) |
+
+### Admin / Platform Services (30 services)
+
+| Service                    | Description |
+|----------------------------|-------------|
+| `PlatformAdminService`     | Platform-level admin operations |
+| `ClientAdminService`       | Client/tenant CRUD and provisioning |
+| `ClientApiKeyService`      | API key management per client |
+| `ClientUsageService`       | Usage metrics and quotas |
+| `ClientOcrService`         | OCR processing management |
+| `SubscriptionService`      | Subscription plans and billing |
+| `RoleAdminService`         | Role definitions and permissions |
+| `UserAdminService`         | User administration across clients |
+| `UserPermissionService`    | Fine-grained permission management |
+| `ImpersonationService`     | Admin impersonation of users |
+| `TicketService` *(client-facing)* | Support ticket creation, viewing, and comments |
+| `ErpAdminService`          | ERP integration configuration |
+| `IdentityProviderService`  | SSO/IdP setup (SAML, OIDC, LDAP) |
+| `WebhookAdminService`      | Webhook endpoint management |
+| `PlatformWebhookService`   | Platform-level webhook events |
+| `EmailAdminService`        | Email template management |
+| `EmailProviderService`     | Email provider configuration |
+| `MessagingProviderService` | SMS/push notification providers |
+| `NotificationService`      | Notification delivery |
+| `AnnouncementService`      | Platform announcements |
+| `ArticleAdminService`      | Knowledge base administration |
+| `DocumentAdminService`     | Document administration |
+| `BackupService`            | Database backup and restore |
+| `CacheAdminService`        | Cache management and invalidation |
+| `QueueAdminService`        | Background job queue management |
+| `DataExportService`        | Bulk data export operations |
+| `AuditLogService`          | Audit trail queries |
+| `ActivityLogService`       | Activity log queries |
+| `SystemHealthService`      | Health checks and system status |
+| `SandboxAdminService`      | Sandbox environment management |
+
+### Chat Services (2 services)
+
+| Service                 | Description |
+|-------------------------|-------------|
+| `ChatRestService`       | REST API for conversations, messages, participants, reactions, read receipts, presence (28 methods) |
+| `ChatWebSocketService`  | Real-time STOMP/WebSocket for messages, typing, presence, reactions, read receipts (8 methods) |
+
+### Video Call Services (2 services + 4 components)
+
+| Service / Component         | Description |
+|-----------------------------|-------------|
+| `VideoCallRestService`      | REST API for call initiation, answer, join, end, history (7 methods) |
+| `VideoCallWebSocketService` | WebSocket signaling for call events |
+| `VideoRoomComponent`        | Pre-built video room UI component |
+| `VideoControlsComponent`    | Mic/camera/screen-share toggle controls |
+| `VideoParticipantComponent` | Individual participant video tile |
+| `IncomingCallComponent`     | Incoming call notification with accept/decline |
+
+---
+
+## Documentation
+
+Detailed guides are available in the [`docs/`](./docs/) folder:
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](./docs/getting-started.md) | Installation, setup, and first request |
+| [Configuration](./docs/configuration.md) | TgmSdkConfig options, token storage, multi-tenancy |
+| [Authentication](./docs/authentication.md) | Login, SSO, TOTP, platform auth, token management |
+| [API Services](./docs/api-services.md) | BaseCrudService pattern and all domain services |
+| [Admin Services](./docs/admin-services.md) | Platform admin, client management, ERP, webhooks |
+| [Real-Time](./docs/real-time.md) | WebSocket chat and video call integration |
+| [Models](./docs/models.md) | DTOs, enums, base models, and type patterns |
+| [Error Handling](./docs/error-handling.md) | TgmApiError, error types, global handling |
+| [Examples](./docs/examples.md) | Practical code examples for common use cases |
+
+---
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+- Angular CLI (optional, for scaffolding tests)
+
+### Build
+
+```bash
+# Production build (outputs to ./dist/)
+npm run build
+
+# Watch mode for development
+npm run build:watch
+```
+
+### Lint
+
+```bash
+# Type-check without emitting (uses tsc --noEmit)
+npm run lint
+```
+
+### Link for Local Testing
+
+```bash
+# In the SDK directory
+npm run build
+npm link
+
+# In a consuming Angular application
+npm link @en-solutions/tgm-client-sdk
+```
+
+### Project Scripts
+
+| Script          | Command                              | Description |
+|-----------------|--------------------------------------|-------------|
+| `build`         | `ng-packagr -p ng-package.json`      | Build the library for distribution |
+| `build:watch`   | `ng-packagr -p ng-package.json --watch` | Rebuild on file changes |
+| `lint`          | `tsc --noEmit`                       | Type-check all source files |
+
+---
+
+## License
+
+**Proprietary** -- This is an internal SDK developed and maintained by ENSolutions. Unauthorized distribution is prohibited.