http-request-manager 18.15.32 → 18.15.34

package/src/docs/MODELS_README.md

@@ -0,0 +1,1264 @@
+# Models Reference Guide
+
+Comprehensive reference for all data models used in the HTTP Request Manager library.
+
+## Model Pattern
+
+All models follow a consistent pattern with an interface and implementation class:
+
+```typescript
+export interface ModelNameInterface {
+  property1: string;
+  property2?: number;
+  property3: SomeType;
+}
+
+export class ModelNameModel implements ModelNameInterface {
+  constructor(
+    public property1: string = '',
+    public property2?: number,
+    public property3: SomeType
+  ) {}
+
+  static adapt(item?: any): ModelNameModel {
+    return new ModelNameModel(
+      item?.property1,
+      item?.property2,
+      item?.property3 ? SomeType.adapt(item.property3) : SomeType.adapt()
+    );
+  }
+}
+```
+
+**Key Features:**
+- ✅ Interface + Class pattern
+- ✅ Public constructor parameters
+- ✅ Default values for required fields
+- ✅ Static `adapt()` method for transformation
+- ✅ Type safety with TypeScript
+
+---
+
+## HTTP Request Models
+
+### ApiRequest
+
+Configuration for HTTP requests.
+
+```typescript
+export interface ApiRequestInterface {
+  server: string;
+  path?: any[];
+  headers?: any;
+  adapter?: any;
+  mapper?: any;
+  polling?: number;
+  retry?: RetryOptions;
+  stream?: boolean;
+  streamType?: StreamType;
+  displayError?: boolean;
+  displaySuccess?: boolean;
+  successMessage?: string;
+  errorMessage?: string;
+  saveAs?: string;
+  fileContentHeader?: string;
+  ws?: WSOptions;
+  env?: string;
+  uploadFiles?: File | File[];
+  uploadFieldName?: string;
+  uploadHttpMethod?: 'POST' | 'PUT';
+  allowedTypes?: string[];
+  maxFileSize?: number;
+  maxTotalSize?: number;
+}
+
+export class ApiRequest implements ApiRequestInterface {
+  constructor(
+    public server = '',
+    public path?: any[],
+    public headers?: any,
+    public adapter?: any,
+    public mapper?: any,
+    public polling?: number,
+    public retry?: RetryOptions,
+    public stream?: boolean,
+    public streamType?: StreamType,
+    public displayError?: boolean,
+    public displaySuccess?: boolean,
+    public successMessage?: string,
+    public errorMessage?: string,
+    public saveAs?: string,
+    public fileContentHeader?: string,
+    public ws?: WSOptions,
+    public env?: string,
+    public uploadFiles?: File | File[],
+    public uploadFieldName?: string,
+    public uploadHttpMethod?: 'POST' | 'PUT',
+    public allowedTypes?: string[],
+    public maxFileSize?: number,
+    public maxTotalSize?: number,
+  ) {}
+
+  static adapt(item?: any): ApiRequest {
+    const server = Array.isArray(item?.server) ? item.server.join('/') : item?.server || '';
+    return new ApiRequest(
+      server,
+      item?.path ? item.path : [],
+      item?.headers ? item.headers : {},
+      item?.adapter,
+      item?.mapper,
+      item?.polling ? Math.floor(item.polling) : 0,
+      item?.retry ? RetryOptions.adapt(item.retry) : RetryOptions.adapt(),
+      item?.stream ? item.stream : false,
+      item?.streamType || StreamType.AI_STREAMING,
+      item?.displayError ? item.displayError : false,
+      item?.displaySuccess ? item.displaySuccess : false,
+      item?.successMessage,
+      item?.errorMessage,
+      item?.saveAs,
+      item?.fileContentHeader,
+      item?.ws,
+      item?.env || 'dev',
+      item?.uploadFiles,
+      item?.uploadFieldName,
+      item?.uploadHttpMethod,
+      Array.isArray(item?.allowedTypes) ? item.allowedTypes : [],
+      item?.maxFileSize,
+      item?.maxTotalSize,
+    );
+  }
+}
+```
+
+**Properties:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `server` | `string` | `''` | Base URL or server key for the request |
+| `path` | `any[]` | `[]` | Path segments to append to URL |
+| `headers` | `any` | `{}` | Custom headers for the request |
+| `adapter` | `Function` | `undefined` | Transform incoming response data |
+| `mapper` | `Function` | `undefined` | Transform outgoing request payload |
+| `polling` | `number` | `0` | Polling interval in seconds (0 = disabled) |
+| `retry` | `RetryOptions` | `{ times: 0, delay: 3 }` | Retry configuration |
+| `stream` | `boolean` | `false` | Enable streaming response handling |
+| `streamType` | `StreamType` | `AI_STREAMING` | Streaming format: `NDJSON`, `SSE`, or `AI_STREAMING` |
+| `displayError` | `boolean` | `false` | Show error toast notification |
+| `displaySuccess` | `boolean` | `false` | Show success toast notification |
+| `successMessage` | `string` | `undefined` | Custom success toast message |
+| `errorMessage` | `string` | `undefined` | Custom error toast message |
+| `saveAs` | `string` | `undefined` | Filename for file downloads |
+| `fileContentHeader` | `string` | `undefined` | Content-Disposition header value for downloads |
+| `ws` | `WSOptions` | `undefined` | WebSocket configuration for real-time sync |
+| `env` | `string` | `'dev'` | Environment for WebSocket channel naming |
+| `uploadFiles` | `File \| File[]` | `undefined` | Files to upload (set internally by `uploadRequest`) |
+| `uploadFieldName` | `string` | `undefined` | Form-data field name for uploaded files |
+| `uploadHttpMethod` | `'POST' \| 'PUT'` | `undefined` | HTTP method for upload requests |
+| `allowedTypes` | `string[]` | `[]` | Allowed MIME types for upload validation |
+| `maxFileSize` | `number` | `undefined` | Maximum per-file size in bytes |
+| `maxTotalSize` | `number` | `undefined` | Maximum total upload size in bytes |
+
+**Usage:**
+```typescript
+const request = ApiRequest.adapt({
+  server: 'https://api.example.com',
+  path: ['users', 123],
+  headers: { 'Authorization': 'Bearer token' },
+  adapter: User.adapt,
+  retry: { times: 3, delay: 2 }
+});
+```
+
+### RequestOptions
+
+Extended request configuration for state manager methods (`fetchRecords`, `fetchStream`, etc.).
+
+```typescript
+export interface RequestOptionsInterface {
+  path: any[];
+  headers: any;
+  forceRefresh?: boolean;
+  ignoreQueryParams?: string[];
+  queryParamsExpiresIn?: string | number;
+  watchParams?: string[];
+  watchExpiresAt?: number;
+}
+
+export class RequestOptions implements RequestOptionsInterface {
+  constructor(
+    public path: any[] = [],
+    public headers = {},
+    public forceRefresh?: boolean,
+    public ignoreQueryParams?: string[],
+    public queryParamsExpiresIn?: string | number,
+    public watchParams?: string[],
+    public watchExpiresAt?: number,
+  ) {}
+
+  static adapt(item?: any): RequestOptions {
+    return new RequestOptions(
+      item?.path,
+      item?.headers,
+      item?.forceRefresh,
+      Array.isArray(item?.ignoreQueryParams) ? item.ignoreQueryParams : [],
+      item?.queryParamsExpiresIn,
+      item?.watchParams,
+      item?.watchExpiresAt,
+    );
+  }
+}
+```
+
+**Properties:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `path` | `any[]` | `[]` | URL path segments |
+| `headers` | `any` | `{}` | Custom HTTP headers |
+| `forceRefresh` | `boolean` | `undefined` | Bypass query tracking and always make the API request |
+| `ignoreQueryParams` | `string[]` | `[]` | Query parameter keys to exclude from request-change tracking |
+| `queryParamsExpiresIn` | `string \| number` | `undefined` | Expiry duration for tracked query values (e.g., `'10s'`, `'5mn'`, `'1h'`) |
+| `watchParams` | `string[]` | `undefined` | Specific query keys to watch for change detection (variation mode) |
+| `watchExpiresAt` | `number` | `undefined` | Epoch timestamp when tracked values expire |
+
+**Usage:**
+```typescript
+service.fetchRecords(RequestOptions.adapt({
+  path: ['users'],
+  ignoreQueryParams: ['page', 'size'],
+  queryParamsExpiresIn: '10s',
+  forceRefresh: false
+}));
+```
+
+**Scope and behavior:**
+- Database enabled (`DatabaseStorage` configured): tracker is active and can prevent repeated identical API calls until expiry resets tracked values.
+- Database disabled: tracker is not enabled; requests go straight to API.
+- `forceRefresh: true` bypasses tracking and always makes the API request.
+
+---
+
+## Configuration Models
+
+### ConfigOptions
+
+Global library configuration passed via `forRoot()`.
+
+```typescript
+export interface ConfigOptions {
+  httpRequestOptions?: ConfigHTTPOptions;
+  LocalStorageOptions?: ConfigLocalStorageOptions;
+}
+
+export class ConfigOptions implements ConfigOptions {
+  constructor(
+    public httpRequestOptions?: ConfigHTTPOptions,
+    public LocalStorageOptions?: ConfigLocalStorageOptions
+  ) {}
+
+  static adapt(item?: any): ConfigOptions {
+    return new ConfigOptions(
+      item?.httpRequestOptions ? ConfigHTTPOptions.adapt(item.httpRequestOptions) : undefined,
+      item?.LocalStorageOptions ? ConfigLocalStorageOptions.adapt(item.LocalStorageOptions) : undefined
+    );
+  }
+}
+```
+
+### ConfigHTTPOptions
+
+HTTP service configuration.
+
+```typescript
+export interface ConfigHTTPOptions {
+  server: string;
+  path?: any[];
+  headers?: any;
+  polling?: number;
+  retry?: RetryOptions;
+  stream?: boolean;
+  displayError?: boolean;
+  displaySuccess?: boolean;
+}
+
+export class ConfigHTTPOptions {
+  constructor(
+    public server: string = '',
+    public path?: any[],
+    public headers?: any,
+    public polling?: number,
+    public retry?: RetryOptions,
+    public stream?: boolean,
+    public displayError?: boolean,
+    public displaySuccess?: boolean,
+  ) {}
+
+  static adapt(item?: any): ConfigHTTPOptions {
+    return new ConfigHTTPOptions(
+      item?.server,
+      Array.isArray(item?.path) ? item.path : [],
+      item?.headers,
+      item?.polling,
+      item?.retry ? RetryOptions.adapt(item.retry) : undefined,
+      item?.stream,
+      item?.displayError,
+      item?.displaySuccess,
+    );
+  }
+}
+```
+
+**Usage:**
+```typescript
+HttpRequestManagerModule.forRoot({
+  httpRequestOptions: {
+    server: 'https://api.example.com',
+    retry: { times: 3, delay: 2 },
+    displayError: true
+  }
+})
+```
+
+### ConfigLocalStorageOptions
+
+LocalStorage configuration.
+
+```typescript
+export interface ConfigLocalStorageOptions {
+  storageName: string;
+  storageSettingsName: string;
+  options?: SettingOptions;
+}
+
+export class ConfigLocalStorageOptions {
+  constructor(
+    public storageName: string = 'storage',
+    public storageSettingsName: string = 'global-storage',
+    public options?: SettingOptions
+  ) {}
+
+  static adapt(item?: any): ConfigLocalStorageOptions {
+    return new ConfigLocalStorageOptions(
+      item?.storageName,
+      item?.storageSettingsName,
+      item?.options ? SettingOptions.adapt(item.options) : undefined
+    );
+  }
+}
+```
+
+### ConfigToken
+
+Injection token type for configuration.
+
+```typescript
+export const CONFIG_SETTINGS_TOKEN = new InjectionToken<ConfigOptions>(
+  'HTTP_REQUEST_MANAGER_CONFIG'
+);
+```
+
+**Usage:**
+```typescript
+constructor(
+  @Inject(CONFIG_SETTINGS_TOKEN) private config?: ConfigOptions
+) {
+  // Use config
+}
+```
+
+---
+
+## State Management Models
+
+### DataType
+
+Enum for data structure types.
+
+```typescript
+export enum DataType {
+  ARRAY = 'array',
+  OBJECT = 'object'
+}
+```
+
+**Usage:**
+```typescript
+// For list of records
+super(request, DataType.ARRAY);
+
+// For single object
+super(request, DataType.OBJECT);
+```
+
+### DatabaseStorage
+
+IndexedDB caching configuration.
+
+```typescript
+export interface DatabaseStorageInterface {
+  table: string;
+  expiresIn?: string;
+}
+
+export class DatabaseStorage {
+  constructor(
+    public table: string,
+    public expiresIn?: string
+  ) {}
+
+  static adapt(item?: any): DatabaseStorage {
+    return new DatabaseStorage(
+      item?.table,
+      item?.expiresIn
+    );
+  }
+}
+```
+
+**Usage:**
+```typescript
+super(
+  ApiRequest.adapt({ path: ['users'] }),
+  DataType.ARRAY,
+  DatabaseStorage.adapt({
+    table: 'users',
+    expiresIn: '1h'
+  })
+);
+```
+
+### StateStorageOptions
+
+Persistent state configuration for StoreStateManagerService.
+
+```typescript
+export interface StateStorageOptionsInterface {
+  store: string;
+  options?: SettingOptions;
+  model?: Function;
+  version?: number;
+}
+
+export class StateStorageOptions {
+  constructor(
+    public store: string,
+    public options?: SettingOptions,
+    public model?: Function,
+    public version?: number
+  ) {}
+
+  static adapt(item?: any): StateStorageOptions {
+    return new StateStorageOptions(
+      item?.store,
+      item?.options ? SettingOptions.adapt(item.options) : undefined,
+      item?.model,
+      item?.version
+    );
+  }
+}
+```
+
+**Usage:**
+```typescript
+export class AppStateService extends StoreStateManagerService<AppState> {
+  constructor() {
+    super(StateStorageOptions.adapt({
+      store: 'app-state',
+      options: {
+        storage: StorageType.GLOBAL,
+        encrypted: true,
+        expiresIn: '24h'
+      },
+      model: AppState.adapt,
+      version: 1
+    }));
+  }
+}
+```
+
+---
+
+## WebSocket Models
+
+### WSOptions
+
+WebSocket connection configuration.
+
+```typescript
+export interface WSOptionsInterface {
+  wsServer: string;
+  id: string;
+  user?: any;
+  channels?: string[];
+  jwtToken?: string;
+}
+
+export class WSOptions {
+  constructor(
+    public wsServer: string,
+    public id: string,
+    public user?: any,
+    public channels?: string[],
+    public jwtToken?: string
+  ) {}
+
+  static adapt(item?: any): WSOptions {
+    return new WSOptions(
+      item?.wsServer,
+      item?.id,
+      item?.user,
+      Array.isArray(item?.channels) ? item.channels : [],
+      item?.jwtToken
+    );
+  }
+}
+```
+
+**Usage:**
+```typescript
+const wsOptions = WSOptions.adapt({
+  wsServer: 'ws://localhost:8080',
+  id: 'my-channel',
+  user: { userId: 123, name: 'John' },
+  channels: ['notifications', 'updates']
+});
+
+wsManager.connect(wsOptions, 'jwt-token');
+```
+
+### StreamType
+
+Enum for streaming response types.
+
+```typescript
+export enum StreamType {
+  NDJSON = 'ndjson',
+  SSE = 'sse'
+}
+```
+
+### ChannelType
+
+Enum for channel prefixes.
+
+```typescript
+export enum ChannelType {
+  STATE = 'SYS',        // Private state sync
+  MESSAGE = 'PUB',      // Public messaging
+  NOTIFICATION = 'MES'  // Persistent notifications
+}
+```
+
+**Usage:**
+```typescript
+const privateChannel = createChannelName(ChannelType.STATE, 'user-123');
+// Result: 'SYS-user-123'
+
+const publicChannel = createChannelName(ChannelType.MESSAGE, 'general');
+// Result: 'PUB-general'
+
+const notificationChannel = createChannelName(ChannelType.NOTIFICATION, 'alerts');
+// Result: 'MES-alerts'
+```
+
+### ChannelMessage
+
+WebSocket message structure.
+
+```typescript
+export interface ChannelMessageInterface {
+  type: string;
+  channel: string;
+  content: any;
+  sessionId?: {
+    id: string;
+    name?: string;
+    email?: string;
+  };
+  timestamp?: number;
+}
+
+export class ChannelMessage {
+  constructor(
+    public type: string,
+    public channel: string,
+    public content: any,
+    public sessionId?: {
+      id: string;
+      name?: string;
+      email?: string;
+    },
+    public timestamp?: number
+  ) {}
+
+  static adapt(item?: any): ChannelMessage {
+    return new ChannelMessage(
+      item?.type,
+      item?.channel,
+      item?.content,
+      item?.sessionId ? {
+        id: item.sessionId.id,
+        name: item.sessionId.name,
+        email: item.sessionId.email
+      } : undefined,
+      item?.timestamp
+    );
+  }
+}
+```
+
+### WSUser
+
+WebSocket user information.
+
+```typescript
+export interface WSUserInterface {
+  id: string;
+  name?: string;
+  email?: string;
+  channels?: string[];
+}
+
+export class WSUser {
+  constructor(
+    public id: string,
+    public name?: string,
+    public email?: string,
+    public channels?: string[]
+  ) {}
+
+  static adapt(item?: any): WSUser {
+    return new WSUser(
+      item?.id,
+      item?.name,
+      item?.email,
+      Array.isArray(item?.channels) ? item.channels : []
+    );
+  }
+}
+```
+
+### CommunicationType
+
+Enum for WebSocket message types.
+
+```typescript
+export enum CommunicationType {
+  SUBSCRIBE = 'subscribe',
+  UNSUBSCRIBE = 'unsubscribe',
+  MESSAGE = 'message',
+  NOTIFICATION = 'notification',
+  BROADCAST = 'broadcast',
+  USER_LIST = 'user-list',
+  CHANNEL_CREATED = 'channel-created',
+  CHANNEL_DELETED = 'channel-deleted',
+  PRESENCE = 'presence',
+  HISTORY = 'history',
+  LAST_SEEN = 'last-seen'
+}
+```
+
+---
+
+## Storage Models
+
+### StorageType
+
+Enum for storage scope.
+
+```typescript
+export enum StorageType {
+  GLOBAL = 'global',   // localStorage
+  SESSION = 'session'  // sessionStorage
+}
+```
+
+### SettingOptions
+
+Storage configuration options.
+
+```typescript
+export interface SettingOptionsInterface {
+  storage?: StorageType;
+  expires?: number;
+  expiresIn?: string;
+  encrypted?: boolean;
+}
+
+export class SettingOptions {
+  constructor(
+    public storage?: StorageType,
+    public expires?: number,
+    public expiresIn?: string,
+    public encrypted?: boolean
+  ) {}
+
+  static adapt(item?: any): SettingOptions {
+    return new SettingOptions(
+      item?.storage,
+      item?.expires,
+      item?.expiresIn,
+      item?.encrypted
+    );
+  }
+}
+```
+
+**Usage:**
+```typescript
+// Encrypted localStorage with 7-day expiration
+SettingOptions.adapt({
+  storage: StorageType.GLOBAL,
+  encrypted: true,
+  expiresIn: '7d'
+});
+
+// Unencrypted sessionStorage
+SettingOptions.adapt({
+  storage: StorageType.SESSION,
+  encrypted: false
+});
+```
+
+### StorageData
+
+Internal storage data structure.
+
+```typescript
+export interface StorageDataInterface {
+  data: any;
+  settings: SettingOptions;
+  expires?: number;
+}
+```
+
+---
+
+## Database Models
+
+### TableSchemaDef
+
+IndexedDB table schema definition.
+
+```typescript
+export interface TableSchemaDefInterface {
+  table: string;
+  schema: string;
+}
+
+export class TableSchemaDef {
+  constructor(
+    public table: string,
+    public schema: string
+  ) {}
+
+  static adapt(item?: any): TableSchemaDef {
+    return new TableSchemaDef(
+      item?.table,
+      item?.schema
+    );
+  }
+}
+```
+
+**Usage:**
+```typescript
+const userTable = TableSchemaDef.adapt({
+  table: 'users',
+  schema: '++id, name, email, age, createdAt'
+});
+
+dbManager.createDatabaseTable(userTable).subscribe();
+```
+
+### Schema Examples
+
+```typescript
+// Simple auto-increment ID
+'++id'
+
+// Multiple indexes
+'++id, name, email'
+
+// Compound index
+'++id, [category+status]'
+
+// Multi-entry index
+'++id, tags' // tags is an array
+
+// Full schema example
+'++id, name, email, &username, [firstName+lastName], tags'
+```
+
+---
+
+## Retry & Error Models
+
+### RetryOptions
+
+Retry configuration for HTTP requests.
+
+```typescript
+export interface RetryOptionsInterface {
+  times: number;
+  delay: number;
+}
+
+export class RetryOptions {
+  constructor(
+    public times: number = 0,
+    public delay: number = 3
+  ) {}
+
+  static adapt(item?: any): RetryOptions {
+    return new RetryOptions(
+      item?.times || 0,
+      item?.delay || 3
+    );
+  }
+}
+```
+
+**Usage:**
+```typescript
+// Retry 3 times with 2 second delay
+RetryOptions.adapt({ times: 3, delay: 2 });
+
+// No retry
+RetryOptions.adapt({ times: 0 });
+
+// Default retry
+RetryOptions.adapt(); // { times: 0, delay: 3 }
+```
+
+### ErrorSettings
+
+Error handling configuration for interceptors.
+
+```typescript
+export interface ErrorSettingsInterface {
+  displayError?: boolean;
+  displayWarning?: boolean;
+  customHandler?: (error: any) => void;
+}
+
+export class ErrorSettings {
+  constructor(
+    public displayError?: boolean,
+    public displayWarning?: boolean,
+    public customHandler?: (error: any) => void
+  ) {}
+}
+```
+
+---
+
+## Utility Models
+
+### ObjectMerger
+
+Deep merge configuration.
+
+```typescript
+export interface MergeOptions {
+  clone?: boolean;
+  mergeArrays?: boolean;
+  customMerge?: (key: string, target: any, source: any) => any;
+}
+```
+
+**Usage:**
+```typescript
+const merged = objectMerger.deepMerge(obj1, obj2, {
+  clone: true,
+  mergeArrays: false
+});
+```
+
+### HeadersConfig
+
+Header configuration.
+
+```typescript
+export interface HeadersConfig {
+  'Content-Type'?: string;
+  'Accept-Language'?: string;
+  'Current-Date'?: string;
+  'Authorization'?: string;
+  [key: string]: string | undefined;
+}
+```
+
+---
+
+## Model Adapters Pattern
+
+All models use the `adapt()` pattern for safe transformation:
+
+```typescript
+// Basic adaptation
+const user = User.adapt(apiResponse);
+
+// With nested objects
+const order = Order.adapt({
+  ...data,
+  customer: Customer.adapt(data.customer),
+  items: data.items.map(item => OrderItem.adapt(item))
+});
+
+// With defaults
+const config = ConfigOptions.adapt(userProvided || {});
+
+// Array adaptation
+const users = response.users.map(u => User.adapt(u));
+```
+
+### Adapter Functions
+
+Adapters can be passed to HTTP requests:
+
+```typescript
+const request = ApiRequest.adapt({
+  path: ['users'],
+  adapter: User.adapt  // Transform response
+});
+
+httpManager.getRequest(request).subscribe();
+// data$ will emit User[] instead of raw JSON
+```
+
+### Custom Adapters
+
+Create adapters for your models:
+
+```typescript
+export interface ProductInterface {
+  id: number;
+  name: string;
+  price: number;
+  category: Category;
+}
+
+export class Product implements ProductInterface {
+  constructor(
+    public id: number = 0,
+    public name: string = '',
+    public price: number = 0,
+    public category: Category
+  ) {}
+
+  static adapt(item?: any): Product {
+    return new Product(
+      item?.id,
+      item?.name,
+      item?.price,
+      item?.category ? Category.adapt(item.category) : Category.adapt()
+    );
+  }
+}
+```
+
+---
+
+## Batch Request Models
+
+### BatchOptions
+
+Configuration for batch request execution.
+
+```typescript
+export interface BatchOptionsInterface {
+  mode?: 'sequential' | 'parallel';
+  stopOnError?: boolean;
+  concurrency?: number;
+  ignoreErrors?: boolean;
+  logErrors?: boolean;
+  displaySuccess?: boolean;
+  displayError?: boolean;
+}
+
+export class BatchOptions implements BatchOptionsInterface {
+  constructor(
+    public mode: 'sequential' | 'parallel' = 'sequential',
+    public stopOnError: boolean = false,
+    public concurrency: number = 3,
+    public ignoreErrors: boolean = false,
+    public logErrors: boolean = true,
+    public displaySuccess?: boolean,
+    public displayError?: boolean,
+  ) {}
+
+  static adapt(item?: any): BatchOptions {
+    return new BatchOptions(
+      item?.mode ?? 'sequential',
+      item?.stopOnError ?? false,
+      item?.concurrency ?? 3,
+      item?.ignoreErrors ?? false,
+      item?.logErrors !== false,
+      item?.displaySuccess ?? false,
+      item?.displayError ?? false,
+    );
+  }
+}
+```
+
+### BatchProgress
+
+Progress tracking for batch operations.
+
+```typescript
+export interface BatchProgress {
+  total: number;
+  pending: number;
+  completed: number;
+  failed: number;
+  percent: number;
+}
+```
+
+### BatchRequestState
+
+Per-request state within a batch operation.
+
+```typescript
+export type BatchRequestState<T> = 
+  | BatchPendingState
+  | BatchSuccessState<T>
+  | BatchErrorState;
+
+export interface BatchPendingState {
+  index: number;
+  request: any;
+  isPending: true;
+  data?: undefined;
+  error?: undefined;
+}
+
+export interface BatchSuccessState<T> {
+  index: number;
+  request: any;
+  isPending: false;
+  data: T;
+  error?: undefined;
+}
+
+export interface BatchErrorState {
+  index: number;
+  request: any;
+  isPending: false;
+  data?: undefined;
+  error: any;
+}
+```
+
+### BatchResult
+
+Result of a single request within a batch.
+
+```typescript
+export interface BatchResultInterface<T = any> {
+  request: any;
+  success: boolean;
+  data?: T;
+  error?: any;
+  index: number;
+  timestamp: number;
+}
+
+export class BatchResult<T = any> implements BatchResultInterface<T> {
+  constructor(
+    public request: any,
+    public success: boolean,
+    public data?: T,
+    public error?: any,
+    public index: number = 0,
+    public timestamp: number = Date.now(),
+  ) {}
+
+  static adapt<T>(item?: any): BatchResult<T> {
+    return new BatchResult<T>(
+      item?.request,
+      item?.success ?? false,
+      item?.data,
+      item?.error,
+      item?.index ?? 0,
+      item?.timestamp ?? Date.now(),
+    );
+  }
+}
+```
+
+---
+
+## Upload Models
+
+### UploadValidationErrorModel
+
+Error returned when upload validation fails.
+
+```typescript
+export interface InvalidFileInfoInterface {
+  fileName: string;
+  fileSize: number;
+  fileType: string;
+  errors: string[];
+}
+
+export class InvalidFileInfoModel implements InvalidFileInfoInterface {
+  constructor(
+    public fileName: string = '',
+    public fileSize: number = 0,
+    public fileType: string = '',
+    public errors: string[] = []
+  ) {}
+
+  static adapt(item?: any): InvalidFileInfoModel {
+    return new InvalidFileInfoModel(
+      item?.fileName,
+      item?.fileSize,
+      item?.fileType,
+      Array.isArray(item?.errors) ? item.errors : []
+    );
+  }
+}
+
+export interface UploadValidationErrorInterface {
+  invalidFiles: InvalidFileInfoModel[];
+  validFilesCount: number;
+  totalFilesCount: number;
+}
+
+export class UploadValidationErrorModel implements UploadValidationErrorInterface {
+  constructor(
+    public invalidFiles: InvalidFileInfoModel[] = [],
+    public validFilesCount: number = 0,
+    public totalFilesCount: number = 0
+  ) {}
+
+  static adapt(item?: any): UploadValidationErrorModel {
+    return new UploadValidationErrorModel(
+      Array.isArray(item?.invalidFiles) ? item.invalidFiles.map((f: any) => InvalidFileInfoModel.adapt(f)) : [],
+      item?.validFilesCount,
+      item?.totalFilesCount
+    );
+  }
+}
+```
+
+---
+
+## Query Parameter Tracking Models
+
+### QueryParamsTrackerOptions
+
+Options for the query parameter tracking system.
+
+```typescript
+export interface QueryParamsTrackerOptionsInterface {
+  mode?: 'exact' | 'variation';
+  watchParams?: string[];
+  watchExpiresAt?: string | number;
+  watchParamsExpire?: string | number;
+}
+
+export class QueryParamsTrackerOptionsModel implements QueryParamsTrackerOptionsInterface {
+  constructor(
+    public mode?: 'exact' | 'variation',
+    public watchParams?: string[],
+    public watchExpiresAt?: string | number,
+    public watchParamsExpire?: string | number
+  ) {}
+
+  static adapt(item?: any): QueryParamsTrackerOptionsModel {
+    return new QueryParamsTrackerOptionsModel(
+      item?.mode,
+      Array.isArray(item?.watchParams) ? item.watchParams : [],
+      item?.watchExpiresAt,
+      item?.watchParamsExpire
+    );
+  }
+}
+```
+
+**Properties:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `mode` | `'exact' \| 'variation'` | `undefined` | Tracking mode: `exact` matches full query hash, `variation` watches individual param values |
+| `watchParams` | `string[]` | `[]` | Specific query parameter keys to watch for changes |
+| `watchExpiresAt` | `string \| number` | `undefined` | Epoch timestamp or duration string when tracked values expire |
+| `watchParamsExpire` | `string \| number` | `undefined` | Alternative expiry duration for watched params (e.g., `'10s'`, `'5mn'`) |
+
+### NormalizedRequestOptions
+
+Internal normalized representation of request options.
+
+```typescript
+export type QueryValue = string;
+export type NormalizedQueryParams = Record<string, QueryValue>;
+
+export interface NormalizedRequestOptionsInterface {
+  pathKey: string;
+  query: NormalizedQueryParams;
+  hasQuery: boolean;
+}
+```
+
+### PathTrackerState
+
+Per-path tracking state for consumed query values.
+
+```typescript
+export interface PathTrackerStateInterface {
+  watchExpiresAt?: number;
+  consumedValuesByKey: Record<string, QueryValue[]>;
+}
+```
+
+### QueryTrackerState
+
+Top-level state for the query parameter tracking system.
+
+```typescript
+export interface QueryTrackerStateInterface {
+  paths: Record<string, PathTrackerStateInterface>;
+}
+```
+
+---
+
+## Operation Models
+
+### OperationResultModel
+
+Result of a CRUD operation emitted after state changes.
+
+```typescript
+export interface OperationResultInterface {
+  success: boolean;
+  operation: 'CREATE' | 'UPDATE' | 'DELETE';
+}
+
+export class OperationResultModel implements OperationResultInterface {
+  constructor(
+    public success: boolean = false,
+    public operation: 'CREATE' | 'UPDATE' | 'DELETE' = 'UPDATE',
+  ) {}
+
+  static adapt(item?: any): OperationResultModel {
+    return new OperationResultModel(
+      item?.success ?? false,
+      item?.operation || 'UPDATE',
+    );
+  }
+}
+```
+
+---
+
+## Related Documentation
+
+- [`Complete API Reference`](COMPLETE_API_REFERENCE.md) - Full API with methods
+- [`HTTP Manager`](HTTP_MANAGER_README.md) - HTTP service usage
+- [`State Manager`](HTTP_STATE_MANAGER_README.md) - State management
+- [`Architecture`](ARCHITECTURE.md) - System architecture