nestjs-monobank 1.2.8

package/src/modules/wallet/interfaces/requests/index.ts

@@ -0,0 +1 @@
+export * from './create-card-token.request'

package/src/modules/wallet/interfaces/responses/card-token.response.ts

@@ -0,0 +1,44 @@
+/**
+ * Результат платежу за токеном картки.
+ */
+export interface CardTokenResponse {
+    /**
+     * Унікальний ідентифікатор рахунку (invoice).
+     */
+    invoiceId: string;
+
+    /**
+     * URL для проведення 3DS підтвердження платежу.
+     */
+    tdsUrl: string;
+
+    /**
+     * Статус платежу: "success", "failure" тощо.
+     */
+    status: string;
+
+    /**
+     * Причина невдачі платежу (якщо статус "failure").
+     */
+    failureReason?: string;
+
+    /**
+     * Сума платежу в мінімальних одиницях (наприклад, копійки для гривні).
+     */
+    amount: number;
+
+    /**
+     * ISO 4217 код валюти.
+     */
+    ccy: number;
+
+    /**
+     * Дата створення рахунку (може бути null).
+     */
+    createdDate: string | null;
+
+    /**
+     * Дата останнього оновлення рахунку (може бути null).
+     */
+    modifiedDate: string | null;
+}

package/src/modules/wallet/interfaces/responses/create-card-token.response.ts

@@ -0,0 +1,7 @@
+import type { CardTokenResponse } from './card-token.response'
+
+/**
+ * Відповідь API при створенні платежу за токеном картки.
+ * Наслідує базову структуру CardTokenResponse.
+ */
+export interface CreateCardTokenResponse extends CardTokenResponse {}

package/src/modules/wallet/interfaces/responses/index.ts

@@ -0,0 +1,2 @@
+export * from './card-token.response'
+export * from './create-card-token.response'

package/src/modules/wallet/wallet.module.ts

@@ -0,0 +1,8 @@
+import { Module } from "@nestjs/common";
+import { WalletService } from "./wallet.service";
+
+@Module({
+  providers: [WalletService],
+  exports: [WalletService],
+})
+export class WalletModule {}

package/src/modules/wallet/wallet.service.ts

@@ -0,0 +1,71 @@
+import { Injectable } from "@nestjs/common";
+import { MonobankHttpClient } from "../../core/http/monobank.http-client";
+import type {
+	CardTokenResponse,
+	CreateCardTokenRequest,
+	CreateCardTokenResponse
+} from './interfaces'
+
+@Injectable()
+export class WalletService {
+     public constructor(
+          public readonly http: MonobankHttpClient
+     ) {}
+
+	 /**
+	 * Створює токен картки (Card Token) для збереження платіжної картки.
+	 *
+	 * Використовується для:
+	 * - привʼязки картки клієнта
+	 * - повторних платежів без повторного введення реквізитів
+	 * - роботи з wallet-платежами Monobank
+	 *
+	 * @param {CreateCardTokenRequest} data - Дані для створення токена картки.
+	 * @returns {Promise<CreateCardTokenResponse>} Дані створеного токена картки.
+	 *
+	 * @example
+	 * const data: CreateCardTokenRequest = {
+	 *   amount: 100,
+	 *   ccy: 980,
+	 *   redirectUrl: "https://example.com/success",
+	 *   webHookUrl: "https://example.com/webhook"
+	 * };
+	 *
+	 * const token = await this.monobankService.wallet.create(data);
+	 * console.log(token.cardToken);
+	 */
+     public async create(data: CreateCardTokenRequest): Promise<CreateCardTokenResponse> {
+		 return this.http.post("/merchant/wallet/payment", data)
+     }
+
+	 /**
+	 * Отримує інформацію про wallet за його ідентифікатором.
+	 *
+	 * @param {string} id - Унікальний ідентифікатор wallet.
+	 * @returns {Promise<CardTokenResponse>} Дані wallet (привʼязана картка, статус тощо).
+	 *
+	 * @example
+	 * const wallet = await this.monobankService.wallet.getById("wlt_123456");
+	 * console.log(wallet);
+	 */
+	 public async getById(id: string): Promise<CardTokenResponse> {
+		 return this.http.get(`/merchant/wallet?walletId=${id}`)
+	 }
+
+	 /**
+	 * Видаляє привʼязану картку за токеном.
+	 *
+	 * Після видалення:
+	 * - токен стає недійсним
+	 * - повторні списання по цій картці неможливі
+	 *
+	 * @param {string} token - Токен картки (cardToken).
+	 * @returns {Promise<void>} Результат операції видалення.
+	 *
+	 * @example
+	 * await this.monobankService.wallet.deleteByToken("card_token_abc123");
+	 */
+	 public async deleteByToken(token: string): Promise<void> {
+		 return this.http.delete(`/merchant/wallet/card?cardToken=${token}`)
+	 }
+}

package/src/modules/webhook/webhook.module.ts

@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common'
+import { WebhookService } from './webhook.service'
+import { MerchantModule } from "../merchant/merchant.module";
+
+@Module({
+    imports: [
+        MerchantModule
+    ],
+	providers: [WebhookService],
+	exports: [WebhookService]
+})
+export class WebhookModule {}

package/src/modules/webhook/webhook.service.ts

@@ -0,0 +1,60 @@
+import { Injectable } from '@nestjs/common'
+import { MerchantService } from '../merchant/merchant.service'
+
+import * as crypto from 'crypto'
+
+@Injectable()
+export class WebhookService {
+	public constructor(public readonly merchant: MerchantService) {}
+
+	 /**
+	 * Верифікує підпис webhook-повідомлення від Monobank.
+	 *
+	 * Метод:
+	 * 1. Отримує публічний ключ мерчанта через Merchant API
+	 * 2. Декодує підпис з Base64
+	 * 3. Перевіряє цифровий підпис за алгоритмом SHA256
+	 *
+	 * Використовується для гарантії, що webhook:
+	 * - дійсно надісланий Monobank
+	 * - не був змінений під час передачі
+	 *
+	 * @param {Buffer} rawBody - Сире тіло HTTP-запиту (без JSON.parse).
+	 * @param {string} xSignBase64 - Значення заголовка `X-Sign` у форматі Base64.
+	 *
+	 * @returns {Promise<boolean>}
+	 * - `true` — підпис валідний
+	 * - `false` — підпис невалідний
+	 *
+	 * @example
+	 * // controller.ts
+	 * @Post('/mono-webhook')
+	 * async handleWebhook(
+	 *   @Headers('x-sign') xSign: string,
+	 *   @Req() req: RawBodyRequest<Request>
+	 * ) {
+	 *   const isValid = await this.webhookService.verifyWebhookSignature(
+	 *     req.rawBody,
+	 *     xSign
+	 *   );
+	 *
+	 *   if (!isValid) {
+	 *     throw new UnauthorizedException('Invalid webhook signature');
+	 *   }
+	 *
+	 *   // обробка події
+	 * }
+	 */
+	public async verifyWebhookSignature(rawBody: Buffer, xSignBase64: string): Promise<boolean> {
+		const { key: publicKeyBase64 } = await this.merchant.getMerchantPubkey();
+
+		const sign = Buffer.from(xSignBase64, "base64");
+		const publicKey = Buffer.from(publicKeyBase64, "base64");
+
+		const verifier = crypto.createVerify("SHA256");
+		verifier.write(rawBody);
+		verifier.end();
+
+		return verifier.verify({ key: publicKey, format: "pem", type: "spki" }, sign);
+	}
+}

package/src/monobank.module.ts

@@ -0,0 +1,115 @@
+import { type DynamicModule, Global, Module } from "@nestjs/common";
+import {
+	type MonobankModuleAsyncOptions,
+	type MonobankModuleOptions,
+	MonobankOptionsSymbol
+} from './common/interfaces'
+
+import { MonobankService } from "./monobank.service";
+import { InvoiceModule } from './modules/invoice/invoice.module'
+import { MerchantModule } from './modules/merchant/merchant.module'
+import { StatementModule } from './modules/statement/statement.module'
+import { WalletModule } from './modules/wallet/wallet.module'
+import { WebhookModule } from './modules/webhook/webhook.module'
+import { MonobankHttpClient } from './core/http/monobank.http-client'
+import { SubscriptionModule } from "./modules/subscription/subscription.module";
+import { QrModule } from "./modules/qr/qr.module";
+
+@Global()
+@Module({})
+export class MonobankModule {
+    /**
+     * Метод для реєстрації модуля з синхронними параметрами.
+     * Цей метод використовується для конфігурації модуля з наперед заданими параметрами.
+     * @param {MonobankModuleOptions} options - Налаштування для конфігурації Monobank API.
+     * @returns {DynamicModule} Повертає динамічний модуль з необхідними провайдерами та імпортами.
+     *
+     * @example
+     * ```ts
+     * MonobankModule.forRoot({
+     *   apiKey: configService.getOrThrow('MONOBANK_API_KEY')
+     * });
+     * ```
+     */
+    public static forRoot(options: MonobankModuleOptions): DynamicModule {
+        return {
+            module: MonobankModule,
+            imports: [
+				InvoiceModule,
+				MerchantModule,
+				StatementModule,
+				WalletModule,
+                            QrModule,
+                            SubscriptionModule,
+				WebhookModule
+			],
+            providers: [
+                {
+                    provide: MonobankOptionsSymbol,
+                    useValue: options,
+                },
+				{
+					provide: MonobankHttpClient,
+					useFactory: (cfg: MonobankModuleOptions) => new MonobankHttpClient(cfg),
+					inject: [MonobankOptionsSymbol]
+				},
+
+                MonobankService,
+            ],
+            exports: [MonobankService, MonobankHttpClient],
+            global: true,
+        };
+    }
+
+    /**
+     * Метод для реєстрації модуля з асинхронною конфігурацією.
+     * Цей метод використовується для конфігурації модуля з параметрами, які будуть передані через фабричну функцію.
+     * @param {MonobankModuleAsyncOptions} options - Асинхронні параметри для конфігурації Monobank API.
+     * @returns {DynamicModule} Повертає динамічний модуль з необхідними провайдерами та імпортами.
+     *
+     * @example
+     * ```ts
+     * MonobankModule.forRootAsync({
+     *   imports: [ConfigModule],
+     *   useFactory: async (configService: ConfigService) => ({
+     *     apiKey: configService.getOrThrow('MONOBANK_API_KEY')
+     *   }),
+     *   inject: [ConfigService]
+     * });
+     * ```
+     */
+    public static forRootAsync(options: MonobankModuleAsyncOptions): DynamicModule {
+        return {
+			module: MonobankModule,
+			imports: [
+				...(options.imports || []),
+				InvoiceModule,
+				MerchantModule,
+				StatementModule,
+				WalletModule,
+				WebhookModule,
+                            QrModule,
+                            SubscriptionModule,
+				InvoiceModule
+			],
+			providers: [
+				{
+					provide: MonobankOptionsSymbol,
+					useFactory: options.useFactory,
+					inject: options.inject || []
+				},
+
+				{
+					provide: MonobankHttpClient,
+					useFactory: (cfg: MonobankModuleOptions) =>
+						new MonobankHttpClient(cfg),
+					inject: [MonobankOptionsSymbol]
+				},
+
+				MonobankService
+			],
+			exports: [MonobankService, MonobankHttpClient],
+			global: true
+        };
+    }
+}

package/src/monobank.service.ts

@@ -0,0 +1,21 @@
+import { Injectable } from "@nestjs/common";
+import { InvoiceService } from './modules/invoice/invoice.service'
+import { MerchantService } from './modules/merchant/merchant.service'
+import { StatementService } from './modules/statement/statement.service'
+import { WalletService } from './modules/wallet/wallet.service'
+import { SubscriptionService } from "./modules/subscription/subscription.service";
+import { WebhookService } from "./modules/webhook/webhook.service";
+import { QrService } from "./modules/qr/qr.service";
+
+@Injectable()
+export class MonobankService {
+	public constructor(
+		public invoices: InvoiceService,
+		public merchants: MerchantService,
+		public statements: StatementService,
+		public wallets: WalletService,
+		public qr: QrService,
+              public subscriptions: SubscriptionService,
+              public webhook: WebhookService
+	) {}
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+	"compilerOptions": {
+		"module": "commonjs",
+		"declaration": true,
+		"noImplicitAny": false,
+		"removeComments": false,
+		"noLib": false,
+		"emitDecoratorMetadata": true,
+		"experimentalDecorators": true,
+		"target": "es2017",
+		"sourceMap": false,
+		"rootDir": "./src",
+		"outDir": "./dist",
+		"skipLibCheck": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "**/*.spec.ts"]
+}