@alacard-project/config-sdk 1.0.0 → 1.0.4

package/README.md

@@ -1,4 +1,4 @@
-# @alacard/config-sdk
+# @alacard-project/config-sdk
 
 **Alacard Config SDK** — это клиентская библиотека для взаимодействия с централизованным микросервисом конфигураций (CCS) через gRPC. SDK обеспечивает строго типизированный доступ к настройкам, поддерживает горячую перезагрузку через Kafka и имеет встроенный fallback на `.env` файлы.
 
@@ -8,14 +8,12 @@
 - 🛡️ **Строгая типизация**: Автоматическая генерация TypeScript-интерфейсов из Protocol Buffers (`ts-proto`).
 - ⚡ **Hot-Reloading**: Мгновенное обновление параметров в памяти приложения при изменении в базе (через Kafka).
 - 📂 **.env Fallback**: Поддержка локальных `.env.<environment>` файлов для разработки и как резервный вариант.
-- 🏗️ **Instance-based**: Поддержка нескольких экземпляров клиента в одном процессе (подготовлено для сложной архитектуры 2026 года).
+- 🏗️ **Instance-based**: Поддержка нескольких экземпляров клиента в одном процессе.
 
 ## Установка
 
-Так как пакет является приватным, убедитесь, что ваш `.npmrc` настроен для доступа к соответствующему реестру.
-
 ```bash
-npm install @alacard/config-sdk
+npm install @alacard-project/config-sdk
 ```
 
 ## Быстрый старт
@@ -25,83 +23,31 @@ npm install @alacard/config-sdk
 Инициализируйте клиент при запуске вашего приложения (например, в `main.ts` или `bootstrap.ts`):
 
 ```typescript
-import { ConfigClient } from '@alacard/config-sdk';
+import { ConfigClient } from '@alacard-project/config-sdk';
 
 async function bootstrap() {
   const config = await ConfigClient.initialize({
     serviceName: 'auth-service',
     environment: process.env.NODE_ENV || 'development',
-    grpcUrl: process.env.GRPC_CONFIG_URL || 'localhost:50055',
-    internalKey: process.env.INTERNAL_CONFIG_KEY, // Ключ для ConfigGrpcGuard
-    
-    // Опционально: Интеграция с Vault (KV + PKI)
-    vault: {
-      address: 'https://vault.prod.alacard.local:8200',
-      roleId: process.env.VAULT_ROLE_ID!,
-      secretId: process.env.VAULT_SECRET_ID!,
-      pkiPath: 'pki/issue/config-service', // Путь для динамических сертификатов
-    },
-
-    // Опционально: Ручная настройка mTLS (если не используется Vault PKI)
-    /*
-    tls: {
-      rootCert: fs.readFileSync('./certs/ca.crt'),
-      clientCert: fs.readFileSync('./certs/client.crt'),
-      clientKey: fs.readFileSync('./certs/client.key'),
-    },
-    */
-
-    kafkaBrokers: ['localhost:9092'],
-    useDotenvFallback: true,
+    grpcUrl: process.env.GRPC_CONFIG_URL || 'config-microservice:50055',
+    kafkaBrokers: ['kafka:9092'],
+    useDotenvFallback: true, // Использовать .env если gRPC недоступен
   });
 
   const dbUrl = config.get('DATABASE_URL');
+  console.log('Config loaded!');
 }
 ```
 
-## Как это работает (Порядок загрузки)
-
-1. **.env Fallback**: SDK пробует прочитать локальный `.env.<env>` файл (если `useDotenvFallback: true`).
-2. **Vault KV**: Если настроен `vault`, SDK логинится через AppRole и забирает секреты из `secret/data/config-service/<serviceName>`.
-3. **Vault PKI (mTLS)**: Если в `vault` указан `pkiPath`, SDK получает динамические сертификаты для защиты gRPC соединения.
-4. **gRPC Config Service**: SDK запрашивает финальный конфиг через зашифрованное соединение с микросервиса конфигураций.
-5. **Kafka Watch**: Запускается подписка на изменения для обновления параметров "на лету".
+### Использование в NestJS
 
-  // Получение настроек
-  const port = config.getInt('PORT', 3000);
-  const dbUrl = config.get('DATABASE_URL');
+Рекомендуется создать `ConfigService` обертку или использовать `ConfigModule` (если он реализован в вашем проекте), который внутри вызывает `ConfigClient.initialize`.
 
-  console.log(`Сервис запущен на порту ${port}`);
-}
-```
-
-### Использование в других частях кода
-
-После инициализации вы можете получить доступ к инстансу в любом месте приложения:
-
-```typescript
-import { ConfigClient } from '@alacard/config-sdk';
-
-const config = ConfigClient.getInstance();
-const apiKey = config.get('EXTERNAL_API_KEY');
-```
-
-## Доступные методы
-
-- `get(key: string, defaultValue?: string): string` — получить строковое значение.
-- `getInt(key: string, defaultValue?: number): number` — получить целое число.
-- `getAll(): Record<string, string>` — получить все загруженные настройки.
-
-## Команды для разработки
-
-Если вы вносите правки в сам SDK:
-
-- `npm run gen:proto` — перегенерировать TypeScript-код из `.proto` файлов.
-- `npm run build` — скомпилировать TypeScript в JavaScript для публикации.
-
-## Структура конфигурации (gRPC)
+## Как это работает (Порядок загрузки)
 
-SDK использует `config.proto` для связи. Запросы отправляются методом `GetConfig`, включая `serviceName`, `environment` и `version`.
+1. **.env Fallback**: SDK пробует прочитать локальный `.env.<env>` файл (если `useDotenvFallback: true`).
+2. **gRPC Config Service**: SDK запрашивает финальный конфиг через gRPC.
+3. **Kafka Watch**: Запускается подписка на изменения для обновления параметров "на лету".
 
 ---
 © 2026 Alacard Team

package/dist/config-client.d.ts

@@ -1,5 +1,4 @@
 import { VaultOptions } from './vault-client';
-export { VaultOptions };
 export interface ConfigOptions {
     serviceName: string;
     environment: string;

package/dist/index.d.ts

@@ -1 +1,3 @@
 export * from './config-client';
+export * from './vault-client';
+export * from './nest-helpers';

package/dist/index.js

@@ -15,3 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./config-client"), exports);
+__exportStar(require("./vault-client"), exports);
+__exportStar(require("./nest-helpers"), exports);

package/dist/nest-helpers.d.ts

@@ -0,0 +1,16 @@
+import { Environment } from '@alacard-project/shared';
+export declare abstract class BaseConfigService {
+    protected readonly configService: any;
+    private remoteConfig;
+    constructor(configService: any);
+    setRemoteConfig(config: Record<string, string>): void;
+    protected get<T = string>(key: string, defaultValue?: T): T;
+    protected getRequiredString(key: string): string;
+    protected getRequiredNumber(key: string): number;
+    protected getOptionalString(key: string, defaultValue: string): string;
+    protected getOptionalNumber(key: string, defaultValue: number): number;
+    get environment(): Environment;
+    get databaseUrl(): string;
+    get kafkaBrokers(): string[];
+    get isProduction(): boolean;
+}

package/dist/nest-helpers.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseConfigService = void 0;
+const shared_1 = require("@alacard-project/shared");
+// Note: This requires @nestjs/config to be installed in the consumer microservice
+// We keep it in the SDK as a helper for NestJS-based microservices.
+class BaseConfigService {
+    configService;
+    remoteConfig = {};
+    constructor(configService) {
+        this.configService = configService;
+    }
+    setRemoteConfig(config) {
+        this.remoteConfig = { ...this.remoteConfig, ...config };
+    }
+    get(key, defaultValue) {
+        if (this.remoteConfig[key] !== undefined) {
+            return this.remoteConfig[key];
+        }
+        return this.configService.get(key, defaultValue);
+    }
+    getRequiredString(key) {
+        const value = this.get(key);
+        if (!value && process.env.NODE_ENV !== shared_1.Environment.TEST) {
+            throw new Error(`Configuration Error: ${key} is required`);
+        }
+        return value || '';
+    }
+    getRequiredNumber(key) {
+        const value = this.get(key);
+        if (!value && process.env.NODE_ENV !== shared_1.Environment.TEST) {
+            throw new Error(`Configuration Error: ${key} is required`);
+        }
+        return parseInt(value || '0', 10);
+    }
+    getOptionalString(key, defaultValue) {
+        return this.get(key, defaultValue) || defaultValue;
+    }
+    getOptionalNumber(key, defaultValue) {
+        const value = this.get(key);
+        return value ? parseInt(value, 10) : defaultValue;
+    }
+    get environment() {
+        return this.get('NODE_ENV', shared_1.Environment.DEVELOPMENT) || shared_1.Environment.DEVELOPMENT;
+    }
+    get databaseUrl() {
+        return this.getRequiredString('DATABASE_URL');
+    }
+    get kafkaBrokers() {
+        const brokers = this.get('KAFKA_BROKERS', 'localhost:9092');
+        return (brokers || 'localhost:9092').split(',');
+    }
+    get isProduction() {
+        return this.environment === shared_1.Environment.PRODUCTION;
+    }
+}
+exports.BaseConfigService = BaseConfigService;

package/eslint.config.mjs

@@ -0,0 +1,27 @@
+// @ts-check
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import globals from 'globals';
+
+export default tseslint.config(
+    {
+        ignores: ['dist/**'],
+    },
+    eslint.configs.recommended,
+    ...tseslint.configs.recommended,
+    {
+        languageOptions: {
+            globals: {
+                ...globals.node,
+                ...globals.jest,
+            },
+        },
+        rules: {
+            '@typescript-eslint/interface-name-prefix': 'off',
+            '@typescript-eslint/explicit-function-return-type': 'off',
+            '@typescript-eslint/explicit-module-boundary-types': 'off',
+            '@typescript-eslint/no-explicit-any': 'off', // Relaxed for SDK flexibility
+            '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+        },
+    },
+);

package/package.json

@@ -1,6 +1,9 @@
 {
     "name": "@alacard-project/config-sdk",
-    "version": "1.0.0",
+    "version": "1.0.4",
+    "engines": {
+        "node": ">=24.0.0"
+    },
     "private": false,
     "description": "Standalone gRPC-based Configuration SDK for Alacard microservices",
     "main": "dist/index.js",
@@ -8,18 +11,47 @@
     "scripts": {
         "build": "tsc",
         "gen:proto": "protoc --plugin=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=src/proto --proto_path=proto proto/config.proto --ts_proto_opt=outputServices=grpc-js,env=node,useOptionals=messages,exportCommonSymbols=false,esModuleInterop=true",
+        "lint": "eslint \"src/**/*.ts\" --fix",
+        "test": "jest",
+        "test:cov": "jest --coverage",
         "prepublishOnly": "npm run build"
     },
     "dependencies": {
-        "@grpc/grpc-js": "^1.14.3",
-        "@grpc/proto-loader": "^0.8.0",
-        "kafkajs": "^2.2.4",
-        "dotenv": "^16.4.6",
-        "axios": "^1.7.9"
+        "@alacard-project/shared": "^1.0.4",
+        "@bufbuild/protobuf": "^2.2.3",
+        "@grpc/grpc-js": "^1.12.5",
+        "@grpc/proto-loader": "^0.7.13",
+        "axios": "^1.7.9",
+        "dotenv": "^16.4.7",
+        "kafkajs": "^2.2.4"
     },
     "devDependencies": {
-        "typescript": "^5.5.6",
-        "@types/node": "^20.15.0",
-        "ts-proto": "^2.2.0"
+        "@eslint/js": "^9.18.0",
+        "@types/jest": "^29.5.14",
+        "@types/node": "^22.10.7",
+        "eslint": "^9.18.0",
+        "globals": "^15.14.0",
+        "jest": "^29.7.0",
+        "ts-jest": "^29.2.5",
+        "ts-proto": "^2.6.1",
+        "typescript": "^5.7.3",
+        "typescript-eslint": "^8.20.0"
+    },
+    "jest": {
+        "moduleFileExtensions": [
+            "js",
+            "json",
+            "ts"
+        ],
+        "rootDir": "src",
+        "testRegex": ".*\\.spec\\.ts$",
+        "transform": {
+            "^.+\\.(t|j)s$": "ts-jest"
+        },
+        "collectCoverageFrom": [
+            "**/*.(t|j)s"
+        ],
+        "coverageDirectory": "../coverage",
+        "testEnvironment": "node"
     }
 }

package/src/config-client.ts

@@ -6,8 +6,6 @@ import { ConfigServiceClient } from './proto/config';
 import { GetConfigRequest } from './proto/config';
 import { VaultClient, VaultOptions } from './vault-client';
 
-export { VaultOptions };
-
 export interface ConfigOptions {
     serviceName: string;
     environment: string;

package/src/index.ts

@@ -1 +1,3 @@
 export * from './config-client';
+export * from './vault-client';
+export * from './nest-helpers';

package/src/nest-helpers.ts

@@ -0,0 +1,63 @@
+import { Environment } from '@alacard-project/shared';
+
+// Note: This requires @nestjs/config to be installed in the consumer microservice
+// We keep it in the SDK as a helper for NestJS-based microservices.
+
+export abstract class BaseConfigService {
+    private remoteConfig: Record<string, string> = {};
+
+    constructor(protected readonly configService: any) { }
+
+    setRemoteConfig(config: Record<string, string>) {
+        this.remoteConfig = { ...this.remoteConfig, ...config };
+    }
+
+    protected get<T = string>(key: string, defaultValue?: T): T {
+        if (this.remoteConfig[key] !== undefined) {
+            return this.remoteConfig[key] as unknown as T;
+        }
+        return this.configService.get(key, defaultValue);
+    }
+
+    protected getRequiredString(key: string): string {
+        const value = this.get<string>(key);
+        if (!value && process.env.NODE_ENV !== Environment.TEST) {
+            throw new Error(`Configuration Error: ${key} is required`);
+        }
+        return value || '';
+    }
+
+    protected getRequiredNumber(key: string): number {
+        const value = this.get<string>(key);
+        if (!value && process.env.NODE_ENV !== Environment.TEST) {
+            throw new Error(`Configuration Error: ${key} is required`);
+        }
+        return parseInt(value || '0', 10);
+    }
+
+    protected getOptionalString(key: string, defaultValue: string): string {
+        return this.get<string>(key, defaultValue) || defaultValue;
+    }
+
+    protected getOptionalNumber(key: string, defaultValue: number): number {
+        const value = this.get<string>(key);
+        return value ? parseInt(value, 10) : defaultValue;
+    }
+
+    get environment(): Environment {
+        return this.get<Environment>('NODE_ENV', Environment.DEVELOPMENT) || Environment.DEVELOPMENT;
+    }
+
+    get databaseUrl(): string {
+        return this.getRequiredString('DATABASE_URL');
+    }
+
+    get kafkaBrokers(): string[] {
+        const brokers = this.get<string>('KAFKA_BROKERS', 'localhost:9092');
+        return (brokers || 'localhost:9092').split(',');
+    }
+
+    get isProduction(): boolean {
+        return this.environment === Environment.PRODUCTION;
+    }
+}

package/test/config.client.spec.ts

@@ -0,0 +1,34 @@
+import { ConfigClient } from '../src/config-client';
+
+// Mock gRPC and Kafka dependencies
+jest.mock('@grpc/grpc-js', () => ({
+    credentials: { createInsecure: jest.fn() },
+    ServiceClient: jest.fn(),
+    loadPackageDefinition: jest.fn(),
+}));
+jest.mock('@grpc/proto-loader', () => ({
+    loadSync: jest.fn(),
+}));
+
+describe('ConfigClient', () => {
+    let client: ConfigClient;
+
+    beforeEach(() => {
+        // Reset mocks if needed
+        jest.clearAllMocks();
+    });
+
+    it('should be defined', () => {
+        expect(ConfigClient).toBeDefined();
+    });
+
+    // Add more tests for initialization and fetching
+    it('should handle environment variables gracefully if remote fails', async () => {
+        // Simulation of fallback
+        process.env.TEST_VAR = 'fallback_value';
+
+        // This test would ideally mock the static initialize logic
+        // But for now we just verify structural integrity
+        expect(process.env.TEST_VAR).toBe('fallback_value');
+    });
+});

package/.idea/workspace.xml

@@ -1,45 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ChangeListManager">
-    <list default="true" id="d6ddd62d-b258-48c7-8ac2-ae28e47081ad" name="Changes" comment="" />
-    <option name="SHOW_DIALOG" value="false" />
-    <option name="HIGHLIGHT_CONFLICTS" value="true" />
-    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
-    <option name="LAST_RESOLUTION" value="IGNORE" />
-  </component>
-  <component name="MarkdownSettingsMigration">
-    <option name="stateVersion" value="1" />
-  </component>
-  <component name="ProjectId" id="38cLw1hfbaQQ7IG2qhtRfg4zBzC" />
-  <component name="ProjectViewState">
-    <option name="hideEmptyMiddlePackages" value="true" />
-    <option name="showLibraryContents" value="true" />
-  </component>
-  <component name="PropertiesComponent"><![CDATA[{
-  "keyToString": {
-    "RunOnceActivity.ShowReadmeOnStart": "true",
-    "WebServerToolWindowFactoryState": "false",
-    "node.js.detected.package.eslint": "true",
-    "node.js.detected.package.tslint": "true",
-    "node.js.selected.package.eslint": "(autodetect)",
-    "node.js.selected.package.tslint": "(autodetect)",
-    "nodejs_package_manager_path": "npm",
-    "vue.rearranger.settings.migration": "true"
-  }
-}]]></component>
-  <component name="SpellCheckerSettings" RuntimeDictionaries="0" Folders="0" CustomDictionaries="0" DefaultDictionary="application-level" UseSingleDictionary="true" transferred="true" />
-  <component name="TaskManager">
-    <task active="true" id="Default" summary="Default task">
-      <changelist id="d6ddd62d-b258-48c7-8ac2-ae28e47081ad" name="Changes" comment="" />
-      <created>1769094147893</created>
-      <option name="number" value="Default" />
-      <option name="presentableId" value="Default" />
-      <updated>1769094147893</updated>
-      <workItem from="1769094150802" duration="320000" />
-    </task>
-    <servers />
-  </component>
-  <component name="TypeScriptGeneratedFilesManager">
-    <option name="version" value="3" />
-  </component>
-</project>