@bts-soft/core 2.3.3 → 2.3.6

package/README.md

@@ -36,178 +36,61 @@ The ecosystem is built on three core pillars:
 
 ## Deep Dive: `@bts-soft/validation`
 
-The validation module is the first line of defense for any BTS Soft application. It moves beyond simple "type checking" and implements complex domain rules and security sanitization.
+The validation module is the primary security layer for BTS Soft applications. It implements a "Validation-at-the-Edge" philosophy, where data is validated, sanitized, and transformed before it reaches the service layer.
 
-### Philosophy: Security-First Validation
+### Key Features
 
-Every text-based decorator in this package includes a hidden security layer. By default, it applies the `SQL_INJECTION_REGEX` to prevent malicious payloads from reaching the database layer. Additionally, it leverages `class-transformer` to normalize data (e.g., trimming whitespace and converting to lowercase) before the business logic ever sees it.
+1.  **Declarative Security**: Every text-based decorator integrates the `SQL_INJECTION_REGEX` to filter malicious patterns.
+2.  **Smart Transformations**: Leverages `class-transformer` for automatic data normalization (e.g., auto-capitalization of names, lowercase emails, and digit-only national IDs).
+3.  **Protocol Agnostic**: Native support for both REST (Express) and GraphQL (Apollo), allowing a single DTO to serve both architectures via the `isGraphql` flag.
+4.  **Policy-Driven Passwords**: Comprehensive password validation with three configurable complexity levels.
 
 ---
 
-### Decorator Reference (Exhaustive)
+### Core Decorators
 
-#### 1. `@EmailField(nullable?: boolean, isGraphql?: boolean)`
-Validates an email address and normalizes it to lowercase.
-- **Validators**: `IsEmail`, `IsOptional`, `Matches` (SQLi).
-- **Transform**: `toLower`.
-- **Usage (REST)**:
-```typescript
-class LoginDto {
-  @EmailField()
-  email: string;
-}
-```
-- **Usage (GraphQL)**:
-```typescript
-@InputType()
-class RegisterInput {
-  @EmailField(false, true)
-  email: string;
-}
-```
+#### 1. Identity & Security
+- **`@PasswordField`**: Supports `ALPHANUMERIC`, `SYMBOLIC`, and `COMPREHENSIVE` complexity scenarios.
+- **`@NationalIdField`**: Specialized for Egyptian National IDs (14 digits) with auto-stripping of non-digits.
+- **`@IdField`**: Flexible validation for generic IDs (ULID, UUID, etc) with length enforcement.
 
-#### 2. `@PasswordField(min?: number, max?: number, nullable?: boolean, isGraphql?: boolean)`
-Enforces a high-security password policy.
-- **Rules**: Must contain at least one uppercase letter, one lowercase letter, one digit, and one special character.
-- **Default Constraints**: Min: 8, Max: 16.
-- **Usage**:
-```typescript
-class ChangePasswordDto {
-  @PasswordField(12, 32)
-  newPassword: string;
-}
-```
+#### 2. Text & Content
+- **`@NameField`**: Validates names and automatically applies title-case (e.g., "omar sabry" → "Omar Sabry").
+- **`@CapitalTextField`**: Generic text field with auto-capitalization for proper nouns like cities.
+- **`@TextField`**: Standard input field with length limits and strict SQL injection checks.
+- **`@DescriptionField`**: Designed for long-form content with support for newlines and special punctuation.
+- **`@UsernameField`**: Enforces system-level handle rules (3-30 chars, starts with a letter).
 
-#### 3. `@PhoneField(format?: CountryCode, nullable?: boolean, isGraphql?: boolean)`
-Validates and cleans international phone numbers.
-- **Logic**: Automatically removes non-digit characters (except `+`) before validation.
-- **Default Format**: `EG` (Egypt).
-- **Usage**:
-```typescript
-class ProfileDto {
-  @PhoneField('SA')
-  whatsappNumber: string;
-}
-```
+#### 3. Contact & Primitives
+- **`@EmailField`**: Validates email format and normalizes input to lowercase.
+- **`@PhoneField`**: Validates international phone numbers using `libphonenumber-js` with regional support.
+- **`@UrlField`**: Validates web addresses and ensures lowercase normalization.
+- **`@NumberField`**: Supports integers and floats with flexible min/max constraints.
+- **`@BooleanField`**: Strict boolean checking for logic flags.
+- **`@DateField`**: Handles date strings and Date objects with automatic type conversion.
 
-#### 4. `@NationalIdField(nullable?: boolean, isGraphql?: boolean)`
-Strict validation for Egyptian National IDs.
-- **Rules**: Exactly 14 digits, must start with 2 or 3.
-- **Cleaning**: Removes any non-digit input automatically.
-- **Usage**:
-```typescript
-class IdentityDto {
-  @NationalIdField()
-  nationalId: string;
-}
-```
-
-#### 5. `@NameField(nullable?: boolean, isGraphql?: boolean)`
-Validates personal names with automatic title-case capitalization.
-- **Logic**: Capitalizes the first letter of every name segment.
-- **Constraints**: 2-100 characters.
-- **Usage**:
-```typescript
-class UpdateUserDto {
-  @NameField()
-  fullName: string; // "omar sabry" -> "Omar Sabry"
-}
-```
-
-#### 6. `@DescriptionField(nullable?: boolean, isGraphql?: boolean)`
-Designed for long-form text content like biographies or comments.
-- **Constraints**: 10-2000 characters.
-- **Logic**: Allows more characters than `TextField` (includes newlines and specialized punctuation).
-- **Usage**:
-```typescript
-class UpdateBioDto {
-  @DescriptionField()
-  biography: string;
-}
-```
-
-#### 7. `@NumberField(isInteger?: boolean, min?: number, max?: number, nullable?: boolean, isGraphql?: boolean)`
-Versatile numeric validation.
-- **Options**: Toggle between integer and float.
-- **Usage**:
-```typescript
-class ProductDto {
-  @NumberField(true, 1, 1000)
-  stockCount: number;
-
-  @NumberField(false, 0.01)
-  price: number;
-}
-```
-
-#### 8. `@UsernameField(nullable?: boolean, isGraphql?: boolean)`
-Validates standard system usernames.
-- **Rules**: 3-30 characters, Alphanumeric + Underscore, must start with a letter.
-- **Usage**:
-```typescript
-class SetUsernameDto {
-  @UsernameField()
-  username: string;
-}
-```
-
-#### 9. `@TextField(text: string, min?: number, max?: number, nullable?: boolean, isGraphql?: boolean)`
-The "Swiss Army Knife" for general text inputs.
-- **Features**: Customizable error messages, length limits, and SQLi protection.
-- **Default**: Min 1, Max 255.
-- **Usage**:
-```typescript
-class SearchDto {
-  @TextField('Search Query', 3, 50)
-  q: string;
-}
-```
+---
 
-#### 10. `@CapitalField(text: string, min?: number, max?: number, nullable?: boolean, isGraphql?: boolean)`
-Similar to `TextField` but enforces capitalization on every word.
-- **Usage**: Useful for City names, Country names, or Titles.
+### Implementation Example
 
-#### 11. `@DateField(nullable?: boolean, isGraphql?: boolean)`
-Validates and converts input into a JavaScript `Date` object.
-- **Usage**:
 ```typescript
-class EventDto {
-  @DateField()
-  startDate: Date;
-}
-```
+import { NameField, EmailField, PasswordField, PasswordComplexity } from '@bts-soft/validation';
 
-#### 12. `@BooleanField(nullable?: boolean, isGraphql?: boolean)`
-Strict boolean validation.
-- **Usage**:
-```typescript
-class PreferencesDto {
-  @BooleanField()
-  isPublic: boolean;
-}
-```
+export class RegisterUserDto {
+  @NameField('Full Name')
+  name: string;
 
-#### 13. `@EnumField(entity: object, nullable?: boolean, isGraphql?: boolean)`
-Synchronizes validation with TypeScript Enums.
-- **Usage**:
-```typescript
-enum UserRole { ADMIN = 'admin', USER = 'user' }
+  @EmailField()
+  email: string;
 
-class UpdateRoleDto {
-  @EnumField(UserRole)
-  role: UserRole;
+  @PasswordField(12, 32, PasswordComplexity.COMPREHENSIVE)
+  password: string;
 }
 ```
 
-#### 14. `@UrlField(nullable?: boolean, isGraphql?: boolean)`
-Validates complete web URLs.
-- **Logic**: Enforces protocol and converts host to lowercase.
-
-#### 15. `@IdField(length?: number, nullable?: boolean, isGraphql?: boolean)`
-Generic length-based ID validation (useful for ULID/UUID patterns).
-
 ---
 
+
 ### Utility Exports
 
 The validation package also exports the underlying transformation functions for manual use:
@@ -410,45 +293,50 @@ await notificationService.send(ChannelType.MESSENGER, {
 
 ## Deep Dive: `@bts-soft/upload`
 
-The upload module is a production-hardened media orchestration service. It is designed to handle the complexities of multi-part streams, file validation, and cloud storage management.
+The upload module is a production-hardened media orchestration service designed to handle the complexities of multi-part streams, file validation, and cross-provider storage management.
 
-### Architecture Patterns
+### Multi-Provider Architecture
 
-The service is built on three pillars of software engineering:
+The service leverages the **Strategy Pattern** to support multiple storage backends without changing the application logic:
 
-1.  **Strategy Pattern**: 
-    The `IUploadStrategy` interface allows you to define how files are stored. The default implementation is `CloudinaryUploadStrategy`, but you can easily plug in Amazon S3 or Google Cloud Storage.
-    
-2.  **Command Pattern**: 
-    Each upload type (Image, Video, Audio, Raw File) is encapsulated in a command. This allows the system to apply specific optimizations (like chunked video upload) without cluttering the main service.
+1.  **Cloudinary Strategy**: Default for production, providing on-the-fly optimization, transcoding, and CDN delivery.
+2.  **Local Disk Strategy**: Ideal for development or high-security environments where files must remain on the internal network.
 
-3.  **Observer Pattern**: 
-    Successful and failed uploads trigger events that `IUploadObserver` instances can listen to. This is used for global logging, analytics, and cleanup tasks.
+Switching providers is handled via the `UPLOAD_PROVIDER` environment variable.
 
----
+### Design Patterns
 
-### Media Type Specifications
+The module is built on three pillars of software engineering:
 
-| Media Type | File Extensions | Size Limit | Processing Logic |
-| :--- | :--- | :--- | :--- |
-| **Images** | `jpg`, `png`, `webp`, `gif` | 5 MB | Format optimization, fetch_format: auto |
-| **Videos** | `mp4`, `webm`, `avi`, `mov` | 100 MB | Chunked upload (6MB chunks), Duration extraction |
-| **Audio** | `mp3`, `wav`, `ogg`, `m4a` | 50 MB | Treated as a "video" resource for waveform generation |
-| **Raw Files** | `pdf`, `doc`, `zip`, `txt` | 10 MB | Stored as 'raw' resources with original headers |
+- **Strategy Pattern**: The `IUploadStrategy` and `IDeleteStrategy` interfaces decouple the service from the underlying storage technology.
+- **Command Pattern**: Each operation (Upload, Delete) is encapsulated in a command object, ensuring consistent execution and error handling.
+- **Observer Pattern**: Triggers events on success or failure, enabling centralized logging and auditing via `IUploadObserver`.
 
----
+### Media Specifications & Validation
 
-### Provider Integration (Cloudinary)
+The system enforces strict validation for file extensions and sizes. Limits can be customized via environment variables.
 
-To initialize the upload system, ensure your environment is configured:
+| Media Type | File Extensions | Default Limit | Storage Logic |
+| :--- | :--- | :--- | :--- |
+| **Images** | `jpg`, `png`, `webp`, `gif` | 5 MB | Auto-optimization and non-destructive resizing. |
+| **Videos** | `mp4`, `webm`, `avi`, `mov` | 100 MB | Chunked upload support with duration extraction. |
+| **Audio** | `mp3`, `wav`, `ogg`, `m4a` | 50 MB | Optimized for playback and metadata extraction. |
+| **Raw Files** | `pdf`, `doc`, `zip`, `txt` | 10 MB | Stored as 'raw' binary with original headers. |
+
+### Configuration Reference
 
 ```env
+# Provider Selection
+UPLOAD_PROVIDER=cloudinary # or 'local'
+
+# Cloudinary Credentials (if provider=cloudinary)
 CLOUDINARY_CLOUD_NAME=your_name
 CLOUDINARY_API_KEY=your_key
 CLOUDINARY_API_SECRET=your_secret
-```
 
-The system automatically handles the creation of a Cloudinary client instance and injects it into the default strategies.
+# Local Settings (if provider=local)
+UPLOAD_LOCAL_PATH=./uploads
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bts-soft/core",
-  "version": "2.3.3",
+  "version": "2.3.6",
   "author": "Omar Sabry",
   "description": "All bts-soft packages - meta-package bundling common, cache, validation, upload, and notifications for NestJS.",
   "main": "dist/index.js",
@@ -17,8 +17,8 @@
     "@bts-soft/notifications": "1.4.5",
     "@bts-soft/common": "1.2.8",
     "@bts-soft/cache": "1.0.9",
-    "@bts-soft/validation": "1.1.1",
-    "@bts-soft/upload": "1.4.0"
+    "@bts-soft/validation": "1.1.4",
+    "@bts-soft/upload": "1.4.1"
   },
   "peerDependencies": {
     "@nestjs/common": ">=11.0.0",