feat: enhance template engine with user-specific data

- Bumped version of the backend contract to 0.3.68.
- Added new template keys for USERNAME, EMAIL, and TELEGRAM_ID.
- Implemented a method in TemplateEngine to format templates with user data, including traffic metrics and status.
- Updated SubscriptionService and FormatHostsService to utilize the new user-specific template formatting for profile titles and remarks.

Author: kastov

libs/contract/constants/templates/template-keys.ts

@@ -4,5 +4,8 @@ export const TEMPLATE_KEYS = [
     'TRAFFIC_LEFT',
     'STATUS',
     'TOTAL_TRAFFIC',
+    'USERNAME',
+    'EMAIL',
+    'TELEGRAM_ID',
 ] as const;
 export type TemplateKeys = (typeof TEMPLATE_KEYS)[number];

libs/contract/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnawave/backend-contract",
-  "version": "0.3.67",
+  "version": "0.3.68",
   "public": true,
   "license": "AGPL-3.0-only",
   "description": "A contract library for Remnawave Backend. It can be used in backend and frontend.",

src/common/utils/templates/replace-templates-values.ts

@@ -1,4 +1,11 @@
+import dayjs from 'dayjs';
+
 import { TemplateKeys } from '@libs/contracts/constants/templates/template-keys';
+import { USER_STATUSES_TEMPLATE } from '@libs/contracts/constants';
+
+import { UserWithActiveInboundsEntity } from '@modules/users/entities/user-with-active-inbounds.entity';
+
+import { prettyBytesUtil } from '../bytes';
 
 type TemplateValues = {
     [key in TemplateKeys]: number | string | undefined;
@@ -17,4 +24,17 @@ export class TemplateEngine {
 
         return hasReplacement ? result : template;
     }
+
+    static formarWithUser(template: string, user: UserWithActiveInboundsEntity): string {
+        return this.replace(template, {
+            DAYS_LEFT: dayjs(user.expireAt).diff(dayjs(), 'day'),
+            TRAFFIC_USED: prettyBytesUtil(user.usedTrafficBytes, true, 3),
+            TRAFFIC_LEFT: prettyBytesUtil(user.trafficLimitBytes - user.usedTrafficBytes, true, 3),
+            TOTAL_TRAFFIC: prettyBytesUtil(user.trafficLimitBytes, true, 3),
+            STATUS: USER_STATUSES_TEMPLATE[user.status],
+            USERNAME: user.username,
+            EMAIL: user.email || '',
+            TELEGRAM_ID: user.telegramId?.toString() || '',
+        });
+    }
 }

src/modules/subscription-template/generators/format-hosts.service.ts

@@ -1,5 +1,4 @@
 import { randomUUID } from 'node:crypto';
-import dayjs from 'dayjs';
 
 import { Injectable } from '@nestjs/common';
 import { QueryBus } from '@nestjs/cqrs';
@@ -13,9 +12,7 @@ import {
 import { RawObject } from '@common/helpers/xray-config/interfaces/transport.config';
 import { TemplateEngine } from '@common/utils/templates/replace-templates-values';
 import { XRayConfig } from '@common/helpers/xray-config/xray-config.validator';
-import { prettyBytesUtil } from '@common/utils/bytes/pretty-bytes.util';
 import { ICommandResponse } from '@common/types/command-response.type';
-import { USER_STATUSES_TEMPLATE } from '@libs/contracts/constants/templates/user-statuses';
 import { SECURITY_LAYERS, USERS_STATUS } from '@libs/contracts/constants';
 
 import { SubscriptionSettingsEntity } from '@modules/subscription-settings/entities/subscription-settings.entity';
@@ -57,7 +54,11 @@ export class FormatHostsService {
                         break;
                 }
 
-                formattedHosts.push(...this.createFallbackHosts(specialRemarks));
+                const templatedRemarks = specialRemarks.map((remark) =>
+                    TemplateEngine.formarWithUser(remark, user),
+                );
+
+                formattedHosts.push(...this.createFallbackHosts(templatedRemarks));
 
                 return formattedHosts;
             }
@@ -96,17 +97,7 @@ export class FormatHostsService {
                 continue;
             }
 
-            const remark = TemplateEngine.replace(inputHost.remark, {
-                DAYS_LEFT: dayjs(user.expireAt).diff(dayjs(), 'day'),
-                TRAFFIC_USED: prettyBytesUtil(user.usedTrafficBytes, true, 3),
-                TRAFFIC_LEFT: prettyBytesUtil(
-                    user.trafficLimitBytes - user.usedTrafficBytes,
-                    true,
-                    3,
-                ),
-                TOTAL_TRAFFIC: prettyBytesUtil(user.trafficLimitBytes, true, 3),
-                STATUS: USER_STATUSES_TEMPLATE[user.status],
-            });
+            const remark = TemplateEngine.formarWithUser(inputHost.remark, user);
 
             const address = inputHost.address;
             const port = inputHost.port;

src/modules/subscription/subscription.service.ts

@@ -4,6 +4,7 @@ import { Injectable, Logger } from '@nestjs/common';
 import { CommandBus, QueryBus } from '@nestjs/cqrs';
 import { ConfigService } from '@nestjs/config';
 
+import { TemplateEngine } from '@common/utils/templates/replace-templates-values';
 import { prettyBytesUtil } from '@common/utils/bytes/pretty-bytes.util';
 import { ICommandResponse } from '@common/types/command-response.type';
 import { XRayConfig } from '@common/helpers/xray-config';
@@ -365,15 +366,19 @@ export class SubscriptionService {
         const headers: ISubscriptionHeaders = {
             'content-disposition': `attachment; filename="${user.username}"`,
             'support-url': settings.supportLink,
-            'profile-title': `base64:${Buffer.from(settings.profileTitle).toString('base64')}`,
+            'profile-title': `base64:${Buffer.from(
+                TemplateEngine.formarWithUser(settings.profileTitle, user),
+            ).toString('base64')}`,
             'profile-update-interval': settings.profileUpdateInterval.toString(),
             'subscription-userinfo': Object.entries(getSubscriptionUserInfo(user))
                 .map(([key, val]) => `${key}=${val}`)
                 .join('; '),
         };
 
         if (isHapp && settings.happAnnounce) {
-            headers.announce = `base64:${Buffer.from(settings.happAnnounce).toString('base64')}`;
+            headers.announce = `base64:${Buffer.from(
+                TemplateEngine.formarWithUser(settings.happAnnounce, user),
+            ).toString('base64')}`;
         }
 
         if (isHapp && settings.happRouting) {