@nest-omni/core 4.1.3-2 → 4.1.3-4

package/vault/vault-config.service.d.ts

@@ -1,18 +1,71 @@
+/**
+ * Vault 配置服务
+ * 提供运行时动态访问 Vault 配置的能力
+ * 用于读取敏感配置而不缓存到 process.env
+ */
 export declare class VaultConfigService {
     private readonly logger;
     private vaultClient;
     constructor();
+    /**
+     * 检查 Vault 是否可用
+     */
     isAvailable(): boolean;
+    /**
+     * 运行时动态读取 Vault 配置
+     * @param path Vault 配置路径
+     * @param key 可选，指定要读取的配置键，不指定则返回整个配置对象
+     * @returns 配置值
+     *
+     * @example
+     * // 读取整个配置对象
+     * const config = await vaultConfigService.getSecret('secret/data/app/config');
+     *
+     * // 读取指定键
+     * const apiKey = await vaultConfigService.getSecret('secret/data/app/config', 'API_KEY');
+     */
     getSecret(path: string, key?: string): Promise<any>;
+    /**
+     * 写入配置到 Vault（需要相应权限）
+     * @param path Vault 配置路径
+     * @param data 配置数据
+     *
+     * @example
+     * await vaultConfigService.setSecret('secret/data/app/config', {
+     *   API_KEY: 'new-key',
+     *   DB_PASSWORD: 'new-password',
+     * });
+     */
     setSecret(path: string, data: Record<string, any>): Promise<void>;
+    /**
+     * 删除 Vault 中的配置（需要相应权限）
+     * @param path Vault 配置路径
+     */
     deleteSecret(path: string): Promise<void>;
+    /**
+     * 列出指定路径下的所有配置键
+     * @param path Vault 配置路径
+     * @returns 配置键列表
+     */
     listSecrets(path: string): Promise<string[]>;
+    /**
+     * 检查 Vault 健康状态
+     * @returns 是否健康
+     */
     healthCheck(): Promise<boolean>;
+    /**
+     * 获取 Vault 状态信息
+     * @returns Vault 状态
+     */
     getStatus(): Promise<{
         initialized: boolean;
         sealed: boolean;
         standby: boolean;
         version: string;
     } | null>;
+    /**
+     * 续订 Token（对于有时限的 Token）
+     * @param increment 续订时长（秒）
+     */
     renewToken(increment?: number): Promise<void>;
 }

package/vault/vault-config.service.js

@@ -22,6 +22,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VaultConfigService = void 0;
 const common_1 = require("@nestjs/common");
 const vault_config_loader_1 = require("./vault-config.loader");
+/**
+ * Vault 配置服务
+ * 提供运行时动态访问 Vault 配置的能力
+ * 用于读取敏感配置而不缓存到 process.env
+ */
 let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
     constructor() {
         this.logger = new common_1.Logger(VaultConfigService_1.name);
@@ -30,9 +35,25 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             this.logger.warn('Vault client not initialized. VaultConfigService methods will throw errors.');
         }
     }
+    /**
+     * 检查 Vault 是否可用
+     */
     isAvailable() {
         return vault_config_loader_1.VaultConfigLoader.isConnected();
     }
+    /**
+     * 运行时动态读取 Vault 配置
+     * @param path Vault 配置路径
+     * @param key 可选，指定要读取的配置键，不指定则返回整个配置对象
+     * @returns 配置值
+     *
+     * @example
+     * // 读取整个配置对象
+     * const config = await vaultConfigService.getSecret('secret/data/app/config');
+     *
+     * // 读取指定键
+     * const apiKey = await vaultConfigService.getSecret('secret/data/app/config', 'API_KEY');
+     */
     getSecret(path, key) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -44,16 +65,19 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
                 if (!result || !result.data) {
                     throw new Error(`No data found at path: ${path}`);
                 }
+                // KV v2 引擎的数据在 data.data 中
                 const data = apiVersion === 'v2' ? result.data.data : result.data;
                 if (!data || typeof data !== 'object') {
                     throw new Error(`Invalid secret format at path: ${path}`);
                 }
+                // 如果指定了 key，返回对应的值
                 if (key) {
                     if (!(key in data)) {
                         throw new Error(`Key '${key}' not found in secret at path: ${path}`);
                     }
                     return data[key];
                 }
+                // 否则返回整个配置对象
                 return data;
             }
             catch (error) {
@@ -62,6 +86,17 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 写入配置到 Vault（需要相应权限）
+     * @param path Vault 配置路径
+     * @param data 配置数据
+     *
+     * @example
+     * await vaultConfigService.setSecret('secret/data/app/config', {
+     *   API_KEY: 'new-key',
+     *   DB_PASSWORD: 'new-password',
+     * });
+     */
     setSecret(path, data) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -70,6 +105,7 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             try {
                 const apiVersion = process.env.VAULT_API_VERSION || 'v2';
                 if (apiVersion === 'v2') {
+                    // KV v2 引擎需要将数据包装在 data 字段中
                     yield this.vaultClient.write(path, { data });
                 }
                 else {
@@ -83,6 +119,10 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 删除 Vault 中的配置（需要相应权限）
+     * @param path Vault 配置路径
+     */
     deleteSecret(path) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -98,6 +138,11 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 列出指定路径下的所有配置键
+     * @param path Vault 配置路径
+     * @returns 配置键列表
+     */
     listSecrets(path) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -116,6 +161,10 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 检查 Vault 健康状态
+     * @returns 是否健康
+     */
     healthCheck() {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -131,6 +180,10 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 获取 Vault 状态信息
+     * @returns Vault 状态
+     */
     getStatus() {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -151,6 +204,10 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 续订 Token（对于有时限的 Token）
+     * @param increment 续订时长（秒）
+     */
     renewToken(increment) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {

package/vault/vault.module.d.ts

@@ -1,2 +1,6 @@
+/**
+ * Vault 模块
+ * 全局模块，提供 VaultConfigService 供整个应用使用
+ */
 export declare class VaultModule {
 }

package/vault/vault.module.js

@@ -9,6 +9,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VaultModule = void 0;
 const common_1 = require("@nestjs/common");
 const vault_config_service_1 = require("./vault-config.service");
+/**
+ * Vault 模块
+ * 全局模块，提供 VaultConfigService 供整个应用使用
+ */
 let VaultModule = class VaultModule {
 };
 exports.VaultModule = VaultModule;

package/decorators/examples/validation-decorators.example.d.ts

@@ -1,69 +0,0 @@
-export declare class ContactDto {
-    email?: string;
-    phone?: string;
-    wechat?: string;
-}
-export declare class SearchDto {
-    keyword?: string;
-    category?: string;
-    tags?: string[];
-}
-export declare class PasswordDto {
-    password: string;
-}
-export declare class EmailCheckDto {
-    email: string;
-    userService?: any;
-}
-export declare class OrderDto {
-    orderType: 'standard' | 'express';
-    deliveryDate?: Date;
-}
-export declare class DiscountDto {
-    discountType: 'percentage' | 'fixed';
-    discountValue: number;
-    get validatedDiscountValue(): number;
-}
-export declare class UserRegistrationDto {
-    username: string;
-    password: string;
-    confirmPassword: string;
-    validatePassword(password: string): boolean;
-    validatePasswordMatch(confirmPassword: string): boolean;
-}
-export declare class CreateProductDto {
-    name: string;
-    sku: string;
-    categoryId: string;
-    get validatedCategoryId(): string;
-    productService?: any;
-    categoryService?: any;
-    checkSkuUniqueness(sku: string): Promise<boolean>;
-    validateCategoryExists(categoryId: string): Promise<boolean>;
-}
-export declare class EmployeeDto {
-    name: string;
-    personalEmail?: string;
-    workEmail?: string;
-    phone?: string;
-    validatePhoneFormat(phone: string): boolean;
-}
-export declare class PaymentMethodDto {
-    paymentType: 'credit_card' | 'bank_transfer' | 'digital_wallet';
-    creditCard?: {
-        number: string;
-        expiryDate: string;
-        cvv: string;
-    };
-    bankAccount?: {
-        accountNumber: string;
-        routingNumber: string;
-    };
-    digitalWallet?: {
-        provider: string;
-        walletId: string;
-    };
-    validateCreditCard(creditCard: any): boolean;
-    validateBankAccount(bankAccount: any): boolean;
-    validateDigitalWallet(digitalWallet: any): boolean;
-}

package/decorators/examples/validation-decorators.example.js

@@ -1,331 +0,0 @@
-"use strict";
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PaymentMethodDto = exports.EmployeeDto = exports.CreateProductDto = exports.UserRegistrationDto = exports.DiscountDto = exports.OrderDto = exports.EmailCheckDto = exports.PasswordDto = exports.SearchDto = exports.ContactDto = void 0;
-const class_validator_1 = require("class-validator");
-const swagger_1 = require("@nestjs/swagger");
-const validator_decorators_1 = require("../validator.decorators");
-const field_decorators_1 = require("../field.decorators");
-class ContactDto {
-}
-exports.ContactDto = ContactDto;
-__decorate([
-    (0, swagger_1.ApiProperty)({ required: false }),
-    (0, class_validator_1.IsEmail)(),
-    (0, validator_decorators_1.AtLeastOneField)(['email', 'phone', 'wechat']),
-    __metadata("design:type", String)
-], ContactDto.prototype, "email", void 0);
-__decorate([
-    (0, swagger_1.ApiProperty)({ required: false }),
-    (0, class_validator_1.IsString)(),
-    __metadata("design:type", String)
-], ContactDto.prototype, "phone", void 0);
-__decorate([
-    (0, swagger_1.ApiProperty)({ required: false }),
-    (0, class_validator_1.IsString)(),
-    __metadata("design:type", String)
-], ContactDto.prototype, "wechat", void 0);
-class SearchDto {
-}
-exports.SearchDto = SearchDto;
-__decorate([
-    (0, field_decorators_1.StringFieldOptional)(),
-    (0, validator_decorators_1.AtLeastOneField)(['keyword', 'category', 'tags'], {
-        message: 'Please provide at least one search criteria: keyword, category, or tags',
-    }),
-    __metadata("design:type", String)
-], SearchDto.prototype, "keyword", void 0);
-__decorate([
-    (0, field_decorators_1.StringFieldOptional)(),
-    __metadata("design:type", String)
-], SearchDto.prototype, "category", void 0);
-__decorate([
-    (0, field_decorators_1.StringFieldOptional)({ each: true }),
-    __metadata("design:type", Array)
-], SearchDto.prototype, "tags", void 0);
-class PasswordDto {
-}
-exports.PasswordDto = PasswordDto;
-__decorate([
-    (0, validator_decorators_1.CustomValidation)((value) => {
-        if (!value || value.length < 8)
-            return false;
-        const hasUppercase = /[A-Z]/.test(value);
-        const hasLowercase = /[a-z]/.test(value);
-        const hasNumber = /[0-9]/.test(value);
-        return hasUppercase && hasLowercase && hasNumber;
-    }, {
-        message: 'Password must be at least 8 characters with uppercase, lowercase, and number',
-    }),
-    (0, swagger_1.ApiProperty)(),
-    __metadata("design:type", String)
-], PasswordDto.prototype, "password", void 0);
-class EmailCheckDto {
-}
-exports.EmailCheckDto = EmailCheckDto;
-__decorate([
-    (0, validator_decorators_1.CustomValidation)((value, args) => __awaiter(void 0, void 0, void 0, function* () {
-        const userService = args.object.userService;
-        if (!userService) {
-            console.warn('UserService not found, skipping email check');
-            return true;
-        }
-        const exists = yield userService.checkEmailExists(value);
-        return !exists;
-    }), {
-        message: 'Email already exists in the system',
-    }),
-    (0, class_validator_1.IsEmail)(),
-    (0, swagger_1.ApiProperty)(),
-    __metadata("design:type", String)
-], EmailCheckDto.prototype, "email", void 0);
-class OrderDto {
-}
-exports.OrderDto = OrderDto;
-__decorate([
-    (0, swagger_1.ApiProperty)({ enum: ['standard', 'express'] }),
-    (0, class_validator_1.IsString)(),
-    __metadata("design:type", String)
-], OrderDto.prototype, "orderType", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidation)((value, args) => {
-        const object = args.object;
-        if (object.orderType === 'express') {
-            return value !== null && value !== undefined;
-        }
-        return true;
-    }, {
-        message: 'Delivery date is required for express orders',
-    }),
-    (0, swagger_1.ApiProperty)({ required: false }),
-    __metadata("design:type", Date)
-], OrderDto.prototype, "deliveryDate", void 0);
-class DiscountDto {
-    get validatedDiscountValue() {
-        return this.discountValue;
-    }
-}
-exports.DiscountDto = DiscountDto;
-__decorate([
-    (0, swagger_1.ApiProperty)(),
-    __metadata("design:type", String)
-], DiscountDto.prototype, "discountType", void 0);
-__decorate([
-    (0, swagger_1.ApiProperty)(),
-    __metadata("design:type", Number)
-], DiscountDto.prototype, "discountValue", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidation)((value, args) => {
-        const object = args.object;
-        if (object.discountType === 'percentage') {
-            return value >= 0 && value <= 100;
-        }
-        else if (object.discountType === 'fixed') {
-            return value > 0;
-        }
-        return false;
-    }, {
-        message: 'Invalid discount value for the selected discount type',
-    }),
-    __metadata("design:type", Object),
-    __metadata("design:paramtypes", [])
-], DiscountDto.prototype, "validatedDiscountValue", null);
-class UserRegistrationDto {
-    validatePassword(password) {
-        if (!password || password.length < 8)
-            return false;
-        const hasUppercase = /[A-Z]/.test(password);
-        const hasLowercase = /[a-z]/.test(password);
-        const hasNumber = /[0-9]/.test(password);
-        const hasSpecial = /[!@#$%^&*]/.test(password);
-        return hasUppercase && hasLowercase && hasNumber && hasSpecial;
-    }
-    validatePasswordMatch(confirmPassword) {
-        return confirmPassword === this.password;
-    }
-}
-exports.UserRegistrationDto = UserRegistrationDto;
-__decorate([
-    (0, swagger_1.ApiProperty)(),
-    (0, class_validator_1.IsString)(),
-    __metadata("design:type", String)
-], UserRegistrationDto.prototype, "username", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidationMethod)('validatePassword', {
-        message: 'Password does not meet security requirements',
-    }),
-    (0, swagger_1.ApiProperty)(),
-    __metadata("design:type", String)
-], UserRegistrationDto.prototype, "password", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidationMethod)('validatePasswordMatch'),
-    (0, swagger_1.ApiProperty)(),
-    __metadata("design:type", String)
-], UserRegistrationDto.prototype, "confirmPassword", void 0);
-class CreateProductDto {
-    get validatedCategoryId() {
-        return this.categoryId;
-    }
-    checkSkuUniqueness(sku) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (!this.productService) {
-                console.warn('ProductService not found');
-                return true;
-            }
-            const exists = yield this.productService.skuExists(sku);
-            return !exists;
-        });
-    }
-    validateCategoryExists(categoryId) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (!this.categoryService) {
-                console.warn('CategoryService not found');
-                return true;
-            }
-            return yield this.categoryService.exists(categoryId);
-        });
-    }
-}
-exports.CreateProductDto = CreateProductDto;
-__decorate([
-    (0, swagger_1.ApiProperty)(),
-    (0, class_validator_1.IsString)(),
-    __metadata("design:type", String)
-], CreateProductDto.prototype, "name", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidationMethod)('checkSkuUniqueness', {
-        message: 'SKU already exists',
-    }),
-    (0, swagger_1.ApiProperty)(),
-    __metadata("design:type", String)
-], CreateProductDto.prototype, "sku", void 0);
-__decorate([
-    (0, swagger_1.ApiProperty)(),
-    __metadata("design:type", String)
-], CreateProductDto.prototype, "categoryId", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidationMethod)('validateCategoryExists', {
-        message: 'Category does not exist',
-    }),
-    __metadata("design:type", Object),
-    __metadata("design:paramtypes", [])
-], CreateProductDto.prototype, "validatedCategoryId", null);
-class EmployeeDto {
-    validatePhoneFormat(phone) {
-        if (!phone)
-            return true;
-        const phoneRegex = /^\+?[1-9]\d{1,14}$/;
-        return phoneRegex.test(phone);
-    }
-}
-exports.EmployeeDto = EmployeeDto;
-__decorate([
-    (0, swagger_1.ApiProperty)(),
-    (0, class_validator_1.IsString)(),
-    __metadata("design:type", String)
-], EmployeeDto.prototype, "name", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidation)((value) => {
-        const workDomains = ['company.com', 'corp.com'];
-        const domain = value === null || value === void 0 ? void 0 : value.split('@')[1];
-        return !workDomains.includes(domain);
-    }, {
-        message: 'Personal email should not be from work domains',
-    }),
-    (0, class_validator_1.IsEmail)(),
-    (0, validator_decorators_1.AtLeastOneField)(['personalEmail', 'workEmail']),
-    (0, swagger_1.ApiProperty)({ required: false }),
-    __metadata("design:type", String)
-], EmployeeDto.prototype, "personalEmail", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidation)((value) => {
-        const workDomains = ['company.com', 'corp.com'];
-        const domain = value === null || value === void 0 ? void 0 : value.split('@')[1];
-        return workDomains.includes(domain);
-    }, {
-        message: 'Work email must be from company domains',
-    }),
-    (0, class_validator_1.IsEmail)(),
-    (0, swagger_1.ApiProperty)({ required: false }),
-    __metadata("design:type", String)
-], EmployeeDto.prototype, "workEmail", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidationMethod)('validatePhoneFormat'),
-    (0, swagger_1.ApiProperty)({ required: false }),
-    __metadata("design:type", String)
-], EmployeeDto.prototype, "phone", void 0);
-class PaymentMethodDto {
-    validateCreditCard(creditCard) {
-        var _a;
-        if (!creditCard)
-            return true;
-        const number = (_a = creditCard.number) === null || _a === void 0 ? void 0 : _a.replace(/\s/g, '');
-        if (!/^\d{13,19}$/.test(number))
-            return false;
-        let sum = 0;
-        let isEven = false;
-        for (let i = number.length - 1; i >= 0; i--) {
-            let digit = parseInt(number[i], 10);
-            if (isEven) {
-                digit *= 2;
-                if (digit > 9)
-                    digit -= 9;
-            }
-            sum += digit;
-            isEven = !isEven;
-        }
-        return sum % 10 === 0;
-    }
-    validateBankAccount(bankAccount) {
-        if (!bankAccount)
-            return true;
-        const accountValid = /^\d{8,17}$/.test(bankAccount.accountNumber);
-        const routingValid = /^\d{9}$/.test(bankAccount.routingNumber);
-        return accountValid && routingValid;
-    }
-    validateDigitalWallet(digitalWallet) {
-        var _a;
-        if (!digitalWallet)
-            return true;
-        const validProviders = ['paypal', 'alipay', 'wechat_pay', 'apple_pay'];
-        return validProviders.includes((_a = digitalWallet.provider) === null || _a === void 0 ? void 0 : _a.toLowerCase());
-    }
-}
-exports.PaymentMethodDto = PaymentMethodDto;
-__decorate([
-    (0, swagger_1.ApiProperty)(),
-    __metadata("design:type", String)
-], PaymentMethodDto.prototype, "paymentType", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidationMethod)('validateCreditCard'),
-    (0, validator_decorators_1.AtLeastOneField)(['creditCard', 'bankAccount', 'digitalWallet']),
-    (0, swagger_1.ApiProperty)({ required: false }),
-    __metadata("design:type", Object)
-], PaymentMethodDto.prototype, "creditCard", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidationMethod)('validateBankAccount'),
-    (0, swagger_1.ApiProperty)({ required: false }),
-    __metadata("design:type", Object)
-], PaymentMethodDto.prototype, "bankAccount", void 0);
-__decorate([
-    (0, validator_decorators_1.CustomValidationMethod)('validateDigitalWallet'),
-    (0, swagger_1.ApiProperty)({ required: false }),
-    __metadata("design:type", Object)
-], PaymentMethodDto.prototype, "digitalWallet", void 0);