feat: add username-based user update support

kastov · kastov · commit 3259de5c21cb · 2025-09-22T06:02:37.000+03:00
- Adds optional username field to update request schema
- Implements validation to ensure either UUID or username is provided
- Updates endpoint description to reflect new lookup options
- UUID takes precedence when both identifiers are provided
diff --git a/libs/contract/commands/users/update-user.command.ts b/libs/contract/commands/users/update-user.command.ts
@@ -11,73 +11,85 @@ export namespace UpdateUserCommand {
     export const endpointDetails = getEndpointDetails(
         USERS_ROUTES.UPDATE,
         'patch',
-        'Update a user',
+        'Update a user by UUID or username',
     );
 
-    export const RequestSchema = z.object({
-        uuid: z.string().uuid(),
-        status: z
-            .enum([USERS_STATUS.ACTIVE, USERS_STATUS.DISABLED], {
-                errorMap: () => ({
-                    message:
-                        "You can't change status to LIMITED or EXPIRED. These statuses handled by Remnawave.",
-                }),
-            })
+    export const RequestSchema = z
+        .object({
+            username: z.optional(z.string().describe('Username of the user')),
+            uuid: z.optional(
+                z
+                    .string()
+                    .uuid()
+                    .describe(
+                        'UUID of the user. UUID has higher priority than username, so if both are provided, username will be ignored.',
+                    ),
+            ),
+            status: z
+                .enum([USERS_STATUS.ACTIVE, USERS_STATUS.DISABLED], {
+                    errorMap: () => ({
+                        message:
+                            "You can't change status to LIMITED or EXPIRED. These statuses handled by Remnawave.",
+                    }),
+                })
 
-            .optional(),
-        trafficLimitBytes: z
-            .number({
-                invalid_type_error: 'Traffic limit must be a number',
-            })
-            .int('Traffic limit must be an integer')
-            .min(0, 'Traffic limit must be greater than 0')
-            .describe('Traffic limit in bytes. 0 - unlimited')
-            .optional(),
-        trafficLimitStrategy: UsersSchema.shape.trafficLimitStrategy
-            .describe('Traffic limit reset strategy')
-            .superRefine((val, ctx) => {
-                if (val && !Object.values(RESET_PERIODS).includes(val)) {
-                    ctx.addIssue({
-                        code: z.ZodIssueCode.invalid_enum_value,
-                        message: 'Invalid traffic limit strategy',
-                        path: ['trafficLimitStrategy'],
-                        received: val,
-                        options: Object.values(RESET_PERIODS),
-                    });
-                }
-            })
-            .optional(),
-        expireAt: z
-            .string()
-            .datetime({ local: true, offset: true, message: 'Invalid date format' })
-            .transform((str) => new Date(str))
-            .refine((date) => date > new Date(), {
-                message: 'Expiration date cannot be in the past',
-            })
-            .describe('Expiration date: 2025-01-17T15:38:45.065Z')
-            .optional(),
-        description: z.optional(z.string().nullable()),
-        tag: z.optional(
-            z
+                .optional(),
+            trafficLimitBytes: z
+                .number({
+                    invalid_type_error: 'Traffic limit must be a number',
+                })
+                .int('Traffic limit must be an integer')
+                .min(0, 'Traffic limit must be greater than 0')
+                .describe('Traffic limit in bytes. 0 - unlimited')
+                .optional(),
+            trafficLimitStrategy: UsersSchema.shape.trafficLimitStrategy
+                .describe('Traffic limit reset strategy')
+                .superRefine((val, ctx) => {
+                    if (val && !Object.values(RESET_PERIODS).includes(val)) {
+                        ctx.addIssue({
+                            code: z.ZodIssueCode.invalid_enum_value,
+                            message: 'Invalid traffic limit strategy',
+                            path: ['trafficLimitStrategy'],
+                            received: val,
+                            options: Object.values(RESET_PERIODS),
+                        });
+                    }
+                })
+                .optional(),
+            expireAt: z
                 .string()
-                .regex(
-                    /^[A-Z0-9_]+$/,
-                    'Tag can only contain uppercase letters, numbers, underscores',
-                )
-                .max(16, 'Tag must be less than 16 characters')
-                .nullable(),
-        ),
-        telegramId: z.optional(z.number().int().nullable()),
-        email: z.optional(z.string().email('Invalid email format').nullable()),
-        hwidDeviceLimit: z.optional(
-            z.number().int().min(0, 'Device limit must be non-negative').nullable(),
-        ),
-        activeInternalSquads: z
-            .array(z.string().uuid(), {
-                invalid_type_error: 'Enabled internal squads must be an array of UUIDs',
-            })
-            .optional(),
-    });
+                .datetime({ local: true, offset: true, message: 'Invalid date format' })
+                .transform((str) => new Date(str))
+                .refine((date) => date > new Date(), {
+                    message: 'Expiration date cannot be in the past',
+                })
+                .describe('Expiration date: 2025-01-17T15:38:45.065Z')
+                .optional(),
+            description: z.optional(z.string().nullable()),
+            tag: z.optional(
+                z
+                    .string()
+                    .regex(
+                        /^[A-Z0-9_]+$/,
+                        'Tag can only contain uppercase letters, numbers, underscores',
+                    )
+                    .max(16, 'Tag must be less than 16 characters')
+                    .nullable(),
+            ),
+            telegramId: z.optional(z.number().int().nullable()),
+            email: z.optional(z.string().email('Invalid email format').nullable()),
+            hwidDeviceLimit: z.optional(
+                z.number().int().min(0, 'Device limit must be non-negative').nullable(),
+            ),
+            activeInternalSquads: z
+                .array(z.string().uuid(), {
+                    invalid_type_error: 'Enabled internal squads must be an array of UUIDs',
+                })
+                .optional(),
+        })
+        .refine((data) => data.uuid || data.username, {
+            message: 'Either uuid or username must be provided',
+        });
 
     export type Request = z.infer<typeof RequestSchema>;
 
diff --git a/libs/contract/package.json b/libs/contract/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@remnawave/backend-contract",
-  "version": "2.1.53",
+  "version": "2.1.54",
   "public": true,
   "license": "AGPL-3.0-only",
   "description": "A contract library for Remnawave Backend. It can be used in backend and frontend.",
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -66,7 +66,7 @@
     "@nestjs/jwt": "11.0.0",
     "@nestjs/passport": "11.0.5",
     "@nestjs/platform-express": "11.1.6",
-    "@nestjs/schedule": "6.0.0",
+    "@nestjs/schedule": "6.0.1",
     "@nestjs/serve-static": "5.0.3",
     "@nestjs/swagger": "11.2.0",
     "@nestjs/terminus": "^11.0.0",
@@ -78,7 +78,7 @@
     "@remnawave/hashed-set": "^0.0.4",
     "@remnawave/node-contract": "0.5.9",
     "@remnawave/xtls-sdk": "^0.6.3",
-    "@scalar/nestjs-api-reference": "^1.0.1",
+    "@scalar/nestjs-api-reference": "^1.0.2",
     "@stablelib/base64": "^2.0.1",
     "@stablelib/x25519": "^2.0.1",
     "@willsoto/nestjs-prometheus": "^6.0.2",
@@ -163,4 +163,4 @@
     "typescript": "~5.9.2",
     "typescript-eslint": "^8.39.1"
   }
-}
+}
diff --git a/src/common/utils/startup-app/docs.ts b/src/common/utils/startup-app/docs.ts
@@ -79,6 +79,8 @@ export async function getDocs(app: INestApplication<unknown>, config: ConfigServ
             config.getOrThrow<string>('SCALAR_PATH'),
 
             apiReference({
+                orderSchemaPropertiesBy: 'preserve',
+                orderRequiredPropertiesFirst: true,
                 showSidebar: true,
                 layout: 'modern',
                 hideModels: false,
@@ -92,6 +94,7 @@ export async function getDocs(app: INestApplication<unknown>, config: ConfigServ
                 theme: 'purple',
                 hideClientButton: false,
                 darkMode: true,
+                persistAuth: true,
                 hiddenClients: [
                     'asynchttp',
                     'nethttp',
@@ -112,6 +115,7 @@ export async function getDocs(app: INestApplication<unknown>, config: ConfigServ
                     targetKey: 'js',
                     clientKey: 'axios',
                 },
+                telemetry: false,
 
                 content: documentFactory,
             }),
diff --git a/src/modules/users/repositories/users.repository.ts b/src/modules/users/repositories/users.repository.ts
@@ -480,7 +480,6 @@ export class UsersRepository implements ICrud<BaseUserEntity> {
             lastConnectedNode: true,
         },
     ): Promise<UserEntity | null> {
-        // TODO: check this
         const result = await this.qb.kysely
             .selectFrom('users')
             .selectAll()
diff --git a/src/modules/users/users.service.ts b/src/modules/users/users.service.ts
@@ -174,6 +174,7 @@ export class UsersService {
         try {
             const {
                 uuid,
+                username,
                 expireAt,
                 trafficLimitBytes,
                 trafficLimitStrategy,
@@ -186,13 +187,12 @@ export class UsersService {
                 activeInternalSquads,
             } = dto;
 
-            const user = await this.userRepository.findUniqueByCriteria(
-                { uuid: uuid },
-                {
-                    activeInternalSquads: true,
-                    lastConnectedNode: false,
-                },
-            );
+            const userCriteria = uuid ? { uuid } : { username };
+
+            const user = await this.userRepository.findUniqueByCriteria(userCriteria, {
+                activeInternalSquads: true,
+                lastConnectedNode: false,
+            });
 
             if (!user) {
                 throw new Error(ERRORS.USER_NOT_FOUND.message);

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@remnawave/backend-contract",`
`3`		`- "version": "2.1.53",`
	`3`	`+ "version": "2.1.54",`
`4`	`4`	`"public": true,`
`5`	`5`	`"license": "AGPL-3.0-only",`
`6`	`6`	`"description": "A contract library for Remnawave Backend. It can be used in backend and frontend.",`