@exact-team/freekassa-sdk-nestjs

NestJS FreeKassa SDK Module

Описание

FreeKassa SDK Module для NestJS - это модуль для интеграции платежной системы FreeKassa в ваши NestJS приложения. Модуль предоставляет удобный интерфейс для работы с API FreeKassa и автоматически управляет жизненным циклом SDK.

Установка

npm install @exact-team/freekassa-sdk-nestjs @exact-team/freekassa-sdk

Структура проекта

src/
├── common/        # Общие утилиты и константы
├── decorators/    # Декораторы для внедрения зависимостей
├── interfaces/    # Интерфейсы и типы
├── freekassa-sdk-nestjs.module.ts  # Основной модуль
└── freekassa-sdk-nestjs.builder.ts # Билдер для конфигурации

Основные возможности

• 🚀 Простая интеграция с NestJS приложениями
• ⚡ Поддержка синхронной и асинхронной конфигурации
• 🔄 Автоматическая очистка при завершении работы приложения
• 🌐 Глобальная доступность модуля
• 🎯 Пользовательский декоратор для простого внедрения зависимостей
• 🔒 Типизация всех параметров и ответов API
• 📦 Поддержка всех методов API FreeKassa

Конфигурация

Обязательные параметры

• key - API ключ для подписи запросов
• secretWord1 - Первое секретное слово для подписи платежных форм
• secretWord2 - Второе секретное слово для проверки уведомлений
• shopId - ID вашего магазина
• lang - Язык интерфейса (ru или en)
• currency - Валюта платежей (RUB, USD, EUR, UAH, KZT)
• payUrl - URL платежной формы (по умолчанию: https://pay.fk.money/)
• apiUrl - URL API (по умолчанию: https://api.fk.life/v1/)

Использование

Синхронная конфигурация

import { FreeKassaSdkNestjsModule } from '@exact-team/freekassa-sdk-nestjs';

@Module({
  imports: [
    FreeKassaSdkNestjsModule.forRoot({
      key: 'your-api-key',
      secretWord1: 'your-secret-word-1',
      secretWord2: 'your-secret-word-2',
      shopId: 12345,
      lang: 'ru',
      currency: 'RUB',
      payUrl: 'https://pay.fk.money/',
      apiUrl: 'https://api.fk.life/v1/',
    }),
  ],
})
export class AppModule {}

Асинхронная конфигурация

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { ConfigService } from '@nestjs/config';
import { FreeKassaSdkNestjsModule } from '@exact-team/freekassa-sdk-nestjs';
import { IFreekassaModuleOptions } from '@exact-team/freekassa-sdk-nestjs';

@Module({
  imports: [
    FreeKassaSdkNestjsModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService): Promise<IFreekassaModuleOptions> => ({
        key: configService.getOrThrow('FREEKASSA_API_KEY'),
        secretWord1: configService.getOrThrow('FREEKASSA_SECRET_WORD_1'),
        secretWord2: configService.getOrThrow('FREEKASSA_SECRET_WORD_2'),
        shopId: Number(configService.getOrThrow('FREEKASSA_SHOP_ID')),
        lang: 'ru',
        currency: 'RUB',
        payUrl: 'https://pay.fk.money/',
        apiUrl: 'https://api.fk.life/v1/',
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Использование в сервисах

import { Injectable } from '@nestjs/common';
import { InjectFreeKassa } from '@exact-team/freekassa-sdk-nestjs';
import { FreeKassa } from '@exact-team/freekassa-sdk';

@Injectable()
export class PaymentService {
  constructor(@InjectFreeKassa() private readonly freekassa: FreeKassa) {}

  async createPayment(amount: number, currency: string) {
    return this.freekassa.createPayment({
      methodId: 1,
      email: '[e-mail]',
      ip: '127.0.0.1',
      amount,
      paymentId: new Date().getTime().toString(),
    });
  }

  async verifyNotification(notification: any) {
    return this.freekassa.verifyNotification(notification);
  }
}

API

FreeKassaSdkNestjsModule

• forRoot(options: IFreekassaModuleOptions): Статический метод для синхронной конфигурации модуля
• forRootAsync(options: AsyncModuleOptions): Статический метод для асинхронной конфигурации модуля

Декораторы

• @InjectFreeKassa(): Декоратор для внедрения экземпляра FreeKassa SDK

Обработка ошибок

Модуль предоставляет типизированные ошибки для всех возможных ситуаций:

try {
  await this.freekassa.createPayment({
    methodId: 1,
    email: '[e-mail]',
    ip: '127.0.0.1',
    amount: 10,
    paymentId: new Date().getTime().toString(),
  });
} catch (error) {
  // Обработка ошибок FreeKassa
  console.error(error);
}

Требования

• Node.js 20+
• NestJS 10+
• TypeScript 5.0+

Разработка

Сборка

# Сборка проекта
npm run build

# Запуск линтера
npm run lint

Линтинг

Проект использует ESLint и Prettier для поддержания качества кода.

Тестирование

Для тестирования модуля рекомендуется:

• Использовать тестовые API-ключи
• Проверять все сценарии обработки ошибок
• Верифицировать подписи платежных форм
• Тестировать обработку уведомлений

Лицензия

ISC

Автор

exact01

Поддержка

Для получения поддержки или сообщения об ошибках, пожалуйста, создайте issue в репозитории проекта.