@tc-libs/helper 4.0.0 → 4.1.0

package/README.md

@@ -0,0 +1,272 @@
+# @tc-libs/helper
+
+Package di utilita condivise per NestJS. Espone un `HelperModule` registrabile e una serie di servizi iniettabili per:
+
+- date e intervalli temporali
+- stringhe, slug, password e riferimenti casuali
+- numeri e percentuali
+- hashing
+- cifratura Base64, AES e JWT
+- gestione access token, refresh token e permission token
+- controlli geografici su raggio
+
+## Quando usarlo
+
+Usa questa libreria quando vuoi centralizzare logica tecnica riusabile invece di duplicare helper statici nei singoli servizi applicativi.
+
+I package `authentication`, `pagination`, `request`, `setting`, `task` e altri dipendono gia da questi servizi.
+
+## Installazione nel modulo Nest
+
+### Registrazione sincrona
+
+```ts
+import { Module } from '@nestjs/common';
+import { HelperModule } from '@tc-libs/helper';
+
+@Module({
+  imports: [
+    HelperModule.register(
+      {
+        jwt: {
+          defaultSecretKey: process.env.JWT_DEFAULT_SECRET!,
+          defaultExpirationTime: 3600,
+        },
+        auth: {
+          subject: 'access',
+          audience: 'my-api',
+          issuer: 'my-service',
+          accessToken: {
+            secretKey: process.env.ACCESS_TOKEN_SECRET!,
+            expirationTime: 3600,
+            notBeforeExpirationTime: 0,
+            encryptKey: process.env.ACCESS_TOKEN_ENCRYPT_KEY!,
+            encryptIv: process.env.ACCESS_TOKEN_ENCRYPT_IV!,
+          },
+          refreshToken: {
+            secretKey: process.env.REFRESH_TOKEN_SECRET!,
+            expirationTime: 86400,
+            expirationTimeRememberMe: 2592000,
+            notBeforeExpirationTime: 0,
+            encryptKey: process.env.REFRESH_TOKEN_ENCRYPT_KEY!,
+            encryptIv: process.env.REFRESH_TOKEN_ENCRYPT_IV!,
+          },
+          permissionToken: {
+            secretKey: process.env.PERMISSION_TOKEN_SECRET!,
+            expirationTime: 900,
+            notBeforeExpirationTime: 0,
+            encryptKey: process.env.PERMISSION_TOKEN_ENCRYPT_KEY!,
+            encryptIv: process.env.PERMISSION_TOKEN_ENCRYPT_IV!,
+          },
+        },
+      },
+      true,
+    ),
+  ],
+})
+export class AppModule {}
+```
+
+### Registrazione asincrona
+
+```ts
+HelperModule.registerAsync(
+  {
+    imports: [ConfigModule],
+    inject: [ConfigService],
+    useFactory: async (configService: ConfigService) => ({
+      jwt: {
+        defaultSecretKey: configService.getOrThrow<string>('JWT_DEFAULT_SECRET'),
+        defaultExpirationTime: 3600,
+      },
+      auth: {
+        subject: 'access',
+        audience: 'my-api',
+        issuer: 'my-service',
+        accessToken: {
+          secretKey: configService.getOrThrow<string>('ACCESS_TOKEN_SECRET'),
+          expirationTime: 3600,
+          notBeforeExpirationTime: 0,
+          encryptKey: configService.getOrThrow<string>('ACCESS_TOKEN_ENCRYPT_KEY'),
+          encryptIv: configService.getOrThrow<string>('ACCESS_TOKEN_ENCRYPT_IV'),
+        },
+        refreshToken: {
+          secretKey: configService.getOrThrow<string>('REFRESH_TOKEN_SECRET'),
+          expirationTime: 86400,
+          expirationTimeRememberMe: 2592000,
+          notBeforeExpirationTime: 0,
+          encryptKey: configService.getOrThrow<string>('REFRESH_TOKEN_ENCRYPT_KEY'),
+          encryptIv: configService.getOrThrow<string>('REFRESH_TOKEN_ENCRYPT_IV'),
+        },
+        permissionToken: {
+          secretKey: configService.getOrThrow<string>('PERMISSION_TOKEN_SECRET'),
+          expirationTime: 900,
+          notBeforeExpirationTime: 0,
+          encryptKey: configService.getOrThrow<string>('PERMISSION_TOKEN_ENCRYPT_KEY'),
+          encryptIv: configService.getOrThrow<string>('PERMISSION_TOKEN_ENCRYPT_IV'),
+        },
+      },
+    }),
+  },
+  true,
+);
+```
+
+## Servizi esportati
+
+```ts
+import {
+  DateService,
+  EncryptionService,
+  GeoService,
+  HashService,
+  NumberService,
+  PasswordService,
+  StringService,
+  TokenService,
+} from '@tc-libs/helper';
+```
+
+### `DateService`
+
+Operazioni principali:
+
+- validazione date e timestamp
+- formattazione
+- differenze tra date in giorni, minuti, ore, secondi o millisecondi
+- forward/backward di intervalli temporali
+- start/end di giorno, mese e anno
+- estrazione di giorno, mese e anno
+
+Esempio:
+
+```ts
+const expiresAt = this.dateService.forwardInMinutes(15);
+const age = this.dateService.calculateAge(user.birthDate);
+```
+
+### `StringService`
+
+Operazioni principali:
+
+- validazione email
+- generazione stringhe casuali e riferimenti
+- controllo robustezza password
+- censura di valori sensibili
+- slugify
+
+Esempio:
+
+```ts
+const slug = this.stringService.slugify('Listino Prezzi 2026');
+const reference = this.stringService.randomReference(6, 'ORD');
+```
+
+### `NumberService`
+
+Operazioni principali:
+
+- check di numeri interi o reali in input stringa
+- conversione a `number`
+- generazione random
+- calcolo percentuali
+
+```ts
+const code = this.numberService.random(6);
+const completion = this.numberService.percent(done, total);
+```
+
+### `HashService`
+
+Espone:
+
+- `sha1Base64`
+- `sha256`
+
+```ts
+const digest = this.hashService.sha256(payload);
+```
+
+### `PasswordService`
+
+Wrapper su `bcryptjs` per hashing e confronto password:
+
+```ts
+const hashed = await this.passwordService.hashPassword(plainPassword);
+const isValid = await this.passwordService.compare(plainPassword, hashed);
+```
+
+### `EncryptionService`
+
+Espone primitive per:
+
+- Base64 encode/decode
+- AES-256 CBC encrypt/decrypt
+- sign, decode e verify JWT
+
+```ts
+const encrypted = this.encryptionService.aes256Encrypt(data, key, iv);
+const token = this.encryptionService.jwtEncrypt(payload, {
+  secretKey,
+  expiredIn: 3600,
+  audience: 'my-api',
+  issuer: 'my-service',
+  subject: 'access',
+});
+```
+
+### `TokenService`
+
+Servizio ad alto livello costruito sopra `EncryptionService` e configurazione `auth`.
+
+Casi d'uso principali:
+
+- creare access token
+- creare refresh token con supporto `rememberMe`
+- creare permission token
+- validare token
+- leggere payload JWT
+- cifrare/decifrare il payload contenuto nei token
+
+```ts
+const payload = this.tokenService.createPayloadAccessToken(
+  { user: user._id, email: user.email },
+  false,
+);
+
+const encryptedPayload = await this.tokenService.encryptAccessToken(payload);
+const accessToken = this.tokenService.createAccessToken(encryptedPayload);
+```
+
+### `GeoService`
+
+Controlla se un punto e dentro un raggio espresso in metri:
+
+```ts
+const allowed = this.geoService.inRadius(
+  { latitude: 45.4642, longitude: 9.19, radiusInMeters: 500 },
+  { latitude: 45.465, longitude: 9.191 },
+);
+```
+
+## Export aggiuntivi
+
+Oltre ai servizi, il package esporta:
+
+- interfacce per date, stringhe, numeri, cifratura e token
+- costanti data come `ENUM_DATE_FORMAT` e `ENUM_DATE_DIFF`
+- token di configurazione `HELPER_CONFIG_OPTIONS`
+- tipi `HelperOptions` e `HelperAsyncOptions`
+
+## Note operative
+
+- `TokenService` dipende dalla registrazione di `HelperModule` con configurazione completa.
+- `EncryptionService` usa `JwtService`, quindi va risolto tramite DI Nest invece di essere istanziato manualmente.
+- Le chiavi AES e gli IV devono essere coerenti con il formato atteso dall'applicazione che produce/consuma i token.
+
+## Sviluppo
+
+```bash
+nx build helper
+nx test helper
+```

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "@tc-libs/helper",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "dependencies": {
-    "tslib": "^2.8.1",
-    "ms": "^2.1.3",
-    "@nestjs/common": "^11.0.12",
-    "@nestjs/jwt": "^11.0.0",
-    "moment": "^2.30.1",
+    "@faker-js/faker": "^9.6.0",
+    "bcryptjs": "^3.0.2",
     "crypto-js": "^4.2.0",
     "geolib": "^3.3.4",
-    "@faker-js/faker": "^9.6.0",
-    "bcryptjs": "^3.0.2"
+    "moment": "^2.30.1",
+    "ms": "^2.1.3",
+    "tslib": "^2.8.1"
   },
   "type": "commonjs",
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",
-  "types": "./../packages/helper/src/index.d.ts"
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.12",
+    "@nestjs/jwt": "^11.0.0"
+  },
+  "types": "./src/index.d.ts"
 }