@rshval/back-kit 1.1.1

package/README.md

@@ -0,0 +1,538 @@
+# @rshval/back-kit
+
+Публичный npm-пакет `@rshval/back-kit` с серверными утилитами для Node.js/TypeScript проектов.
+
+> Репозиторий используется для внутренних проектов автора. Любое использование третьими лицами выполняется на их страх и риск.
+
+## Установка
+
+```bash
+npm i @rshval/back-kit
+```
+
+Пакет ESM-only (`"type": "module"`). Для CommonJS используйте динамический `import()`.
+
+---
+
+## Все экспортируемые функции и примеры использования
+
+Ниже перечислены все публичные экспорты из пакета (через `src/index.ts`) и короткие примеры.
+
+### 1) Email
+
+#### `createMailOptions({ from, to, subject, text })`
+Создаёт объект параметров письма для nodemailer. Поддерживает `to` как строку (обычная отправка) или объект формы (`MailOptionsBody`) для заявок/обратной связи.
+
+```ts
+import { createMailOptions } from '@rshval/back-kit'
+
+const options = createMailOptions({
+  from: 'robot@example.com',
+  to: 'user@example.com',
+  subject: 'Hello',
+  text: 'Welcome!'
+})
+```
+
+#### `sendEmailWithConfig({ nodemailerConfig, to, subject, text })`
+Создаёт transport через nodemailer, отправляет письмо и возвращает строку с результатом отправки.
+
+```ts
+import { sendEmailWithConfig } from '@rshval/back-kit'
+
+await sendEmailWithConfig({
+  nodemailerConfig: {
+    host: 'smtp.example.com',
+    port: 465,
+    secure: true,
+    auth: { user: 'robot@example.com', pass: '***' }
+  },
+  to: 'user@example.com',
+  subject: 'Reset password',
+  text: 'Code: 123456'
+})
+```
+
+---
+
+### 2) Конфиг и JWT
+
+#### `getBaseUrlByConfig(config, baseUrl?)`
+Строит base URL по конфигу приложения. В `development` добавляет `:port`.
+
+```ts
+import { getBaseUrlByConfig } from '@rshval/back-kit'
+
+const base = getBaseUrlByConfig(
+  {
+    NODE_ENV: 'development',
+    server: { domain: 'localhost', port: 3000 },
+    jwt: {}
+  },
+  '/api'
+)
+// //localhost:3000/api
+```
+
+#### `createTokenByConfig({ config, user, expiresIn })`
+Создаёт JWT-токен на основе `config.jwt.JWT_KEY` (или `JWT_KEY_NO_ENV`).
+
+```ts
+import { createTokenByConfig } from '@rshval/back-kit'
+
+const token = createTokenByConfig({
+  config: {
+    server: { domain: 'example.com' },
+    jwt: { JWT_KEY: 'super-secret' }
+  },
+  user: { _id: '64a...' },
+  expiresIn: '7d'
+})
+```
+
+---
+
+### 3) Вспомогательные утилиты
+
+#### `createPinCode(min?, max?)`
+Генерирует случайный числовой PIN в диапазоне (`10000..99990` по умолчанию).
+
+```ts
+import { createPinCode } from '@rshval/back-kit'
+
+const pin = createPinCode()
+```
+
+#### `getIp(req)`
+Пытается определить IP клиента из `req.ip`, сокетов и `x-forwarded-for`.
+
+```ts
+import { getIp } from '@rshval/back-kit'
+
+const ip = await getIp(req)
+```
+
+#### `translitUrl(str)`
+Транслитерирует строку в URL-friendly slug (`-`, lower-case).
+
+```ts
+import { translitUrl } from '@rshval/back-kit'
+
+const slug = translitUrl('Пример страницы')
+// primer-stranicy
+```
+
+---
+
+### 4) Валидация
+
+#### `patternEmail()`
+Возвращает RegExp для проверки email.
+
+#### `patternPassword()`
+Возвращает RegExp для пароля (минимум 8 символов, буквы + цифры).
+
+#### `isValidEmail(val)`
+Проверяет корректность email.
+
+#### `isValidPhoneNumber(val)`
+Проверяет номер телефона через `libphonenumber-js`.
+
+#### `isValidCode(code, length)`
+Проверяет длину кода.
+
+#### `isEmpty(val)`
+Проверяет пустую строку (`trim`) или пустой объект.
+
+```ts
+import {
+  patternEmail,
+  patternPassword,
+  isValidEmail,
+  isValidPhoneNumber,
+  isValidCode,
+  isEmpty
+} from '@rshval/back-kit'
+
+const emailRegex = patternEmail()
+const passwordRegex = patternPassword()
+
+isValidEmail('user@example.com') // true
+isValidPhoneNumber('+79991234567') // true/false
+isValidCode('123456', 6) // true
+isEmpty('   ') // true
+isEmpty({}) // true
+```
+
+---
+
+### 5) Билдеры (привязка к конфигу)
+
+#### `buildGetBaseUrl(config)`
+Возвращает функцию `(baseUrl?) => string`.
+
+#### `buildCreateToken(config)`
+Возвращает функцию создания JWT с уже «зашитым» конфигом.
+
+#### `buildSendEmail(nodemailerConfig)`
+Возвращает функцию отправки email с уже «зашитым» SMTP-конфигом.
+
+```ts
+import {
+  buildGetBaseUrl,
+  buildCreateToken,
+  buildSendEmail
+} from '@rshval/back-kit'
+
+const getBaseUrl = buildGetBaseUrl({
+  NODE_ENV: 'production',
+  server: { domain: 'example.com' },
+  jwt: { JWT_KEY: 'secret' }
+})
+
+const createToken = buildCreateToken({
+  server: { domain: 'example.com' },
+  jwt: { JWT_KEY: 'secret' }
+})
+
+const sendEmail = buildSendEmail({
+  host: 'smtp.example.com',
+  port: 465,
+  secure: true,
+  auth: { user: 'robot@example.com', pass: '***' }
+})
+```
+
+---
+
+### 6) База данных
+
+#### `startMongoDatabase(options)`
+Запускает подключение к MongoDB через mongoose, логирует статусы и умеет ретраить подключение.
+
+```ts
+import { startMongoDatabase } from '@rshval/back-kit'
+
+await startMongoDatabase({
+  config: {
+    name: 'main',
+    connect: process.env.MONGO_URI,
+    params: {}
+  },
+  logger: console
+})
+```
+
+---
+
+### 7) Кэш
+
+#### `createCacheService(options?)`
+Создаёт LRU cache-сервис с методами:
+- `get(key)`
+- `set(key, data, compareKey?, compareValue?, ttlMs?)`
+- `delete(key)`
+- `getId(val)`
+- `keys()`
+- `clear()`
+- `entries()` *(если `exposeEntries: true`)*
+- `values()` *(если `exposeValues: true`)*
+
+```ts
+import { createCacheService } from '@rshval/back-kit'
+
+const cache = createCacheService({ ttl: 60_000 })
+const key = cache.getId({ service: 'users', page: 1 })
+await cache.set(key, [{ s: 'state', data: [1, 2, 3] }])
+const value = await cache.get(key)
+```
+
+#### `createCacheMiddleware({ cache, ... })`
+Создаёт middleware-обёртку над cache-сервисом с методами:
+- `get(id)`
+- `set(id, data, expDataTime)`
+- `del(id)`
+- `delByPrefix(prefix)` *(если `includeDelByPrefix: true`)*
+
+```ts
+import { createCacheService, createCacheMiddleware } from '@rshval/back-kit'
+
+const cache = createCacheService({ supportTtlInSet: true })
+const cm = createCacheMiddleware({
+  cache,
+  passTtlToCacheSet: true,
+  includeDelByPrefix: true
+})
+
+await cm.set('users:list', [{ id: 1 }], 60_000)
+const cached = await cm.get('users:list')
+await cm.delByPrefix?.('users:')
+```
+
+---
+
+### 8) Логирование
+
+#### `createLoggerService({ rootdir? })`
+Возвращает фабрику логгеров. Для каждого namespace (`std`) пишет:
+- `logs/<std>/stdout.log`
+- `logs/<std>/stderr.log`
+
+```ts
+import { createLoggerService } from '@rshval/back-kit'
+
+const makeLogger = createLoggerService({ rootdir: process.cwd() })
+const logger = makeLogger('api')
+logger.log('started')
+```
+
+---
+
+### 9) WebSocket клиент
+
+#### `createSocketClientService(options)`
+Создаёт сервис клиента `socket.io` с методами:
+- `doSocketClient()` — старт подключения
+- `getSocketClient()` — вернуть текущий инстанс
+
+```ts
+import { createSocketClientService } from '@rshval/back-kit'
+
+const ws = createSocketClientService({
+  wsName: 'worker',
+  socketBase: 'https://example.com',
+  logger: console,
+  runWorkers: () => {
+    // jobs
+  }
+})
+
+ws.doSocketClient()
+```
+
+---
+
+### 10) Paymaster
+
+#### `createPaymasterService({ paymaster, clientServer, serverBaseUrl })`
+Создаёт сервис с методами:
+- `createPaymentLink({...})` — сформировать ссылку на оплату
+- `validateCallback(payload, rawBody?)` — проверить подпись callback
+- `parseCallback(payload)` — нормализовать callback в удобный объект
+
+```ts
+import { createPaymasterService } from '@rshval/back-kit'
+
+const paymaster = createPaymasterService({
+  paymaster: {
+    merchantId: 'merchant-id',
+    secretKey: 'secret',
+    checkoutUrl: 'https://paymaster.ru/Payment/Init',
+    checkSignature: true
+  },
+  clientServer: 'https://site.example.com',
+  serverBaseUrl: 'https://api.example.com'
+})
+
+const link = paymaster.createPaymentLink({
+  requestId: 'order_123',
+  amount: 1499,
+  description: 'Order #123'
+})
+```
+
+---
+
+### 11) Почтовые шаблоны
+
+#### `createMailTemplateService({ findTemplate, sendEmail })`
+Создаёт сервис шаблонов email с методами:
+- `extractVariables(template)` — список `{{variables}}`
+- `renderTemplate(template, context?)` — рендер subject/body
+- `sendByKey({ key, to, context? })` — найти шаблон, отрендерить и отправить
+
+```ts
+import { createMailTemplateService } from '@rshval/back-kit'
+
+const mailTemplates = createMailTemplateService({
+  findTemplate: async ({ key }) =>
+    key === 'welcome'
+      ? { subject: 'Hi, {{user.name}}', bodyText: 'Hello {{user.name}}!' }
+      : null,
+  sendEmail: async (to, subject, text) => {
+    console.log('send', to, subject, text)
+  }
+})
+
+await mailTemplates.sendByKey({
+  key: 'welcome',
+  to: 'user@example.com',
+  context: { user: { name: 'Alex' } }
+})
+```
+
+---
+
+### 12) Аудит изменений
+
+#### `buildAuditChanges({ beforeData, afterData, fieldsToCheck, protectedFields? })`
+Сравнивает данные «до/после» и возвращает массив изменений по выбранным полям.
+
+#### `createAuditLog({ ..., save })`
+Создаёт запись аудита через переданную функцию `save`. Если изменений нет — возвращает `null`.
+
+```ts
+import { buildAuditChanges, createAuditLog } from '@rshval/back-kit'
+
+const changes = buildAuditChanges({
+  beforeData: { name: 'Old', role: 'user' },
+  afterData: { name: 'New', role: 'user' },
+  fieldsToCheck: ['name', 'role'],
+  protectedFields: ['role']
+})
+
+await createAuditLog({
+  entityType: 'user',
+  entityId: '507f1f77bcf86cd799439011',
+  action: 'update',
+  changedBy: '507f191e810c19729de860ea',
+  changes,
+  save: async (payload) => payload
+})
+```
+
+---
+
+### 13) Seed-функции
+
+#### `createSeedFunctions({ cache, retryDelayMs? })`
+Возвращает методы:
+- `checkDatabaseIsConnected()` — проверяет состояние БД через кэш
+- `setSeedData(SeedModel, arr)` — добавляет seed-данные после подтверждения подключения
+
+```ts
+import { createSeedFunctions, createCacheService } from '@rshval/back-kit'
+
+const cache = createCacheService()
+const { setSeedData } = createSeedFunctions({ cache })
+
+// await setSeedData(UserModel, [{ name: 'Admin' }])
+```
+
+---
+
+### 14) API-клиент
+
+#### `createApiService({ userAgent, logger? })`
+Возвращает HTTP-клиент с методами:
+- `get(path, token?)`
+- `getXml(path, token?)`
+- `del(path, token?)`
+- `post(path, data, token?, xml?, contentType?)`
+- `put(path, data, token)`
+
+```ts
+import { createApiService } from '@rshval/back-kit'
+
+const api = createApiService({ userAgent: 'my-service/1.0.0', logger: console })
+
+const users = await api.get('https://api.example.com/users')
+const created = await api.post('https://api.example.com/users', { name: 'Alex' })
+```
+
+Также экспортируется тип токена:
+
+```ts
+import type { Token } from '@rshval/back-kit'
+```
+
+---
+
+### 15) Прочие экспортированные утилиты
+
+#### `add(a, b)`
+Возвращает сумму двух чисел.
+
+#### `test2()`
+Логирует `99` и возвращает `8`.
+
+```ts
+import { add, test2 } from '@rshval/back-kit'
+
+add(2, 3) // 5
+test2() // 8
+```
+
+---
+
+## Подготовка к публикации в npm
+
+### 1) Требования
+
+- Node.js 18+
+- npm 9+
+- доступ к npm-аккаунту, имеющему право публиковать пакет `@rshval/back-kit`
+
+### 2) Сборка и проверка содержимого публикации
+
+```bash
+npm install
+npm run build
+npm run pack:dry
+```
+
+`npm run pack:dry` показывает, какие файлы реально попадут в npm-пакет.
+
+### 3) Логин в npm
+
+```bash
+npm login
+```
+
+Проверить текущего пользователя:
+
+```bash
+npm whoami
+```
+
+### 4) Публикация
+
+1. Обновите версию:
+
+```bash
+npm version patch
+# или minor / major
+```
+
+2. Опубликуйте пакет:
+
+```bash
+npm publish
+```
+
+> Пакет публикуется как `public` (см. `publishConfig.access`).
+
+
+> Если при `npm publish` появляется ошибка `E403` с текстом
+> `Two-factor authentication or granular access token with bypass 2fa enabled is required`,
+> значит текущий токен не подходит для публикации.
+>
+> Варианты решения:
+> - выполните `npm login --auth-type=web` и подтвердите OTP при публикации;
+> - или создайте **granular access token** на npmjs.com с правами `read and write`
+>   для пакета и включённым `bypass 2FA for publishing`, затем обновите токен локально
+>   через `npm logout && npm login` (или настройкой в `.npmrc`).
+
+---
+
+## Разработка (standalone)
+
+```bash
+npm install
+npm run build
+```
+
+## Экспорты
+
+- ESM: `dist/index.js`
+- Типы: `dist/index.d.ts`

package/dist/api.d.ts

@@ -0,0 +1,17 @@
+interface Token {
+    type: 'Token' | 'Bearer';
+    key: string;
+}
+interface CreateApiServiceOptions {
+    userAgent: string;
+    logger?: Pick<Console, 'error'>;
+}
+export declare const createApiService: ({ userAgent, logger, }: CreateApiServiceOptions) => {
+    get: (path: string, token?: Token) => Promise<any>;
+    getXml: (path: string, token?: Token) => Promise<any>;
+    del: (path: string, token?: Token) => Promise<any>;
+    post: (path: string, data: Record<string, unknown>, token?: Token, xml?: boolean, contentType?: string) => Promise<any>;
+    put: (path: string, data: Record<string, unknown>, token: Token) => Promise<any>;
+};
+export type { Token };
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,UAAU,KAAK;IACb,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,UAAU,uBAAuB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CACjC;AAWD,eAAO,MAAM,gBAAgB,GAAI,wBAG9B,uBAAuB;gBA4DV,MAAM,UAAU,KAAK;mBAClB,MAAM,UAAU,KAAK;gBAExB,MAAM,UAAU,KAAK;iBAGzB,MAAM,QACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UACrB,KAAK,QACP,OAAO,gBACC,MAAM;gBAEV,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,KAAK;CAGlE,CAAC;AAEF,YAAY,EAAE,KAAK,EAAE,CAAC"}

package/dist/api.js

@@ -0,0 +1,51 @@
+export const createApiService = ({ userAgent, logger, }) => {
+    const send = async ({ method, path, data, token, xml, contentType, }) => {
+        const requestHeaders = new Headers();
+        requestHeaders.set('User-Agent', userAgent);
+        if (token) {
+            requestHeaders.set('Authorization', ` ${token.type} ${token.key}`);
+        }
+        let body;
+        if (data) {
+            requestHeaders.set('Content-Type', contentType ? contentType : 'application/json');
+            if (contentType === 'application/x-www-form-urlencoded') {
+                body = new URLSearchParams(data);
+            }
+            else {
+                body = JSON.stringify(data);
+            }
+        }
+        const opts = {
+            method,
+            headers: requestHeaders,
+            body,
+        };
+        try {
+            const res = await fetch(path, opts);
+            if (res.ok || res.status === 200 || res.status === 422) {
+                const text = await res.text();
+                if (xml) {
+                    return text;
+                }
+                return text ? JSON.parse(text) : {};
+            }
+            logger?.error('[' + new Date() + '] api error', res.status);
+            return null;
+        }
+        catch (error) {
+            logger?.error('[' + new Date() + '] error in API, options: ' + opts);
+            logger?.error(error);
+            if (error instanceof Error && error.name === 'AbortError') {
+                console.log('request was aborted');
+            }
+        }
+    };
+    return {
+        get: (path, token) => send({ method: 'GET', path, token }),
+        getXml: (path, token) => send({ method: 'GET', path, token, xml: true }),
+        del: (path, token) => send({ method: 'DELETE', path, token }),
+        post: (path, data, token, xml, contentType) => send({ method: 'POST', path, data, token, xml, contentType }),
+        put: (path, data, token) => send({ method: 'PUT', path, data, token }),
+    };
+};
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/audit-log.d.ts

@@ -0,0 +1,36 @@
+import mongoose from 'mongoose';
+export declare const buildAuditChanges: ({ beforeData, afterData, fieldsToCheck, protectedFields, }: {
+    beforeData: Record<string, unknown>;
+    afterData: Record<string, unknown>;
+    fieldsToCheck: string[];
+    protectedFields?: string[];
+}) => {
+    field: string;
+    before: unknown;
+    after: unknown;
+}[];
+export declare const createAuditLog: ({ entityType, entityId, action, changedBy, changes, meta, save, }: {
+    entityType: string;
+    entityId: mongoose.Types.ObjectId | string;
+    action: string;
+    changedBy?: mongoose.Types.ObjectId | string;
+    changes: Array<{
+        field: string;
+        before: unknown;
+        after: unknown;
+    }>;
+    meta?: Record<string, unknown>;
+    save: (payload: {
+        entityType: string;
+        entityId: mongoose.Types.ObjectId | string;
+        action: string;
+        changedBy?: mongoose.Types.ObjectId | string;
+        changes: Array<{
+            field: string;
+            before: unknown;
+            after: unknown;
+        }>;
+        meta?: Record<string, unknown>;
+    }) => Promise<unknown>;
+}) => Promise<unknown>;
+//# sourceMappingURL=audit-log.d.ts.map

package/dist/audit-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.d.ts","sourceRoot":"","sources":["../src/audit-log.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,UAAU,CAAC;AA6BhC,eAAO,MAAM,iBAAiB,GAAI,4DAK/B;IACD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;;;;GAWA,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,mEAQlC;IACD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC;IAC7C,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,OAAO,EAAE;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC;QAC3C,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC;QAC7C,OAAO,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,OAAO,CAAC;YAAC,KAAK,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC;QACnE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxB,qBAaA,CAAC"}

package/dist/audit-log.js

@@ -0,0 +1,45 @@
+import mongoose from 'mongoose';
+const normalizeValue = (value) => {
+    if (value instanceof mongoose.Types.ObjectId) {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeValue(item));
+    }
+    if (value && typeof value === 'object') {
+        const doc = value;
+        if (typeof doc.toObject === 'function') {
+            return normalizeValue(doc.toObject());
+        }
+    }
+    return value;
+};
+const valuesAreEqual = (left, right) => {
+    return (JSON.stringify(normalizeValue(left)) ===
+        JSON.stringify(normalizeValue(right)));
+};
+export const buildAuditChanges = ({ beforeData, afterData, fieldsToCheck, protectedFields = [], }) => {
+    const protectedSet = new Set(protectedFields);
+    return fieldsToCheck
+        .filter((field) => !protectedSet.has(field))
+        .filter((field) => !valuesAreEqual(beforeData[field], afterData[field]))
+        .map((field) => ({
+        field,
+        before: normalizeValue(beforeData[field]),
+        after: normalizeValue(afterData[field]),
+    }));
+};
+export const createAuditLog = async ({ entityType, entityId, action, changedBy, changes, meta, save, }) => {
+    if (!changes.length) {
+        return null;
+    }
+    return save({
+        entityType,
+        entityId,
+        action,
+        changedBy,
+        changes,
+        meta,
+    });
+};
+//# sourceMappingURL=audit-log.js.map