nestjs-monobank 1.2.8

package/src/common/interfaces/common.interface.ts

@@ -0,0 +1,206 @@
+import { InvoiceStatusEnum } from '../../modules/invoice/enums';
+import { Discount } from '../enums/discount.enum'
+
+/**
+ * Позиція в кошику замовлення.
+ */
+export interface BasketItem {
+    /**
+     * Назва товару або послуги.
+     * Обов’язкове поле.
+     */
+    name: string;
+
+    /**
+     * Кількість одиниць товару.
+     * Обов’язкове поле.
+     */
+    qty: number;
+
+    /**
+     * Ціна за одиницю товару у мінімальних одиницях валюти (наприклад, копійки для гривні).
+     * Обов’язкове поле.
+     */
+    sum: number;
+
+    /**
+     * Загальна сума за позицію (sum * qty).
+     * Якщо не передано — може бути обрахована на бекенді.
+     * Необов’язкове поле.
+     */
+    total?: number;
+
+    /**
+     * Посилання на зображення товару.
+     * Необов’язкове поле.
+     */
+    icon?: string;
+
+    /**
+     * Назва одиниці виміру товару (наприклад: шт, кг, м).
+     * Необов’язкове поле.
+     */
+    unit?: string;
+
+    /**
+     * Код товару (обов’язкове поле для фіскалізації).
+     * Обов’язкове поле.
+     */
+    code: string;
+
+    /**
+     * Значення штрих-коду, яке може бути використане при фіскалізації.
+     * Необов’язкове поле.
+     */
+    barcode?: string;
+
+    /**
+     * Текст, що буде виводитись перед назвою товару (наприклад, категорія).
+     * Необов’язкове поле.
+     */
+    header?: string;
+
+    /**
+     * Текст, що буде виводитись після назви товару.
+     * Необов’язкове поле.
+     */
+    footer?: string;
+
+    /**
+     * Масив податкових ставок, вибраних під час налаштування каси в Checkbox.
+     * У випадку з ПРРО monopay ставки поки що не використовуються.
+     * Необов’язкове поле.
+     */
+    tax?: number[];
+
+    /**
+     * Код УКТ ЗЕД для товару.
+     * Необов’язкове поле.
+     */
+    uktzed?: string;
+
+    /**
+     * Знижки або надбавки, що застосовуються саме до цієї позиції.
+     * Необов’язкове поле.
+     */
+    discounts?: Discount[];
+}
+
+/**
+ * Інформація про платіж для клієнта та фіскалізації.
+ */
+export interface MerchantPaymInfoItem {
+    /**
+     * Номер замовлення або чека, який задає продавець.
+     * Необов’язкове поле.
+     */
+    reference?: string;
+
+    /**
+     * Призначення платежу, що буде відображене у чеку.
+     * Максимальна довжина — 280 символів.
+     * Необов’язкове поле.
+     */
+    destination?: string;
+
+    /**
+     * Службове поле для додаткової інформації.
+     * Не відображається клієнту. Максимум 280 символів.
+     * Необов’язкове поле.
+     */
+    comment?: string;
+
+    /**
+     * Масив email-адрес клієнтів, на які буде відправлено фіскальний чек.
+     * Працює лише за наявності зв’язки з checkbox.
+     * Необов’язкове поле.
+     */
+    customerEmails?: string[];
+
+    /**
+     * Знижки або надбавки, які застосовуються до всього кошика.
+     * Враховуються під час фіскалізації (checkbox).
+     * Необов’язкове поле.
+     */
+    discounts?: Discount[];
+
+    /**
+     * Склад замовлення — деталі позицій у кошику.
+     * Обов’язкове поле при активній зв’язці з ПРРО.
+     */
+    basketOrder?: BasketItem[];
+}
+
+/**
+ * Дані про токенізовану картку у гаманці користувача.
+ */
+export interface WalletData {
+    /**
+     * Токен картки.
+     */
+    cardToken: string;
+    /**
+     * Ідентифікатор гаманця покупця.
+     */
+    walletId: string;
+    /**
+     * Статус токенізації картки.
+     */
+    status: "new" | "created" | "failed";
+}
+
+/**
+ * Статистика платежів по підписці
+ */
+export interface SubscriptionSummary {
+    /** Загальна сума успішно сплачених платежів */
+    totalPaid: number;
+  
+    /** Загальна сума невдалих платежів */
+    totalFailed: number;
+  }
+
+/**
+ * Інформація про виплату чайових співробітнику.
+ */
+export interface TipsInfo {
+    /**
+     * Ідентифікатор співробітника, якому можна виплатити чайові.
+     */
+    employeeId: string;
+    /**
+     * Сума успішно сплачених чайових у мінімальних одиницях валюти.
+     */
+    amount: number;
+}
+
+/**
+ * Дані для пагінації
+ */
+export interface Pagination {
+    /** Загальна кількість елементів */
+    totalItems: number;
+  
+    /** Кількість елементів на сторінці */
+    itemsPerPage: number;
+  
+    /** Поточна сторінка (починаючи з 1) */
+    currentPage: number;
+  
+    /** Загальна кількість сторінок */
+    totalPages: number;
+}
+
+export interface PaginatedResponse<T> {
+    items: T[];
+    pagination: Pagination;
+}
+  
+/**
+ * Інформація про оплату, включаючи дані щодо токенізації картки та чайових.
+ */
+export interface InvoiceCancelItem {
+    status: Exclude<InvoiceStatusEnum, InvoiceStatusEnum.CREATED>;
+    walletData: WalletData;
+    tipsInfo?: TipsInfo;
+}

package/src/common/interfaces/index.ts

@@ -0,0 +1,2 @@
+export * from "./common.interface";
+export * from "./monobank-options.interface";

package/src/common/interfaces/monobank-options.interface.ts

@@ -0,0 +1,18 @@
+import type { FactoryProvider, ModuleMetadata } from "@nestjs/common";
+
+export const MonobankOptionsSymbol = Symbol();
+
+/**
+ * Тип, що представляє параметри для налаштування Monobank.
+ */
+export type MonobankModuleOptions = {
+    /**
+     * Ключ API для автентифікації в Monobank.
+     */
+    apiKey: string; // Токен доступу або тестовий токен з особистого кабінету Monobank
+};
+
+/**
+ * Тип для асинхронного налаштування Monobank.
+ */
+export type MonobankModuleAsyncOptions = Pick<ModuleMetadata, "imports"> & Pick<FactoryProvider<MonobankModuleOptions>, "useFactory" | "inject">;

package/src/core/config/monobank.constants.ts

@@ -0,0 +1 @@
+export const MONOBANK_API_URL = "https://api.monobank.ua/api"

package/src/core/http/monobank.error.ts

@@ -0,0 +1,10 @@
+export class MonobankError extends Error {
+	public constructor(
+		public code: string,
+		public description: string,
+		public data?: any
+	) {
+		super(description)
+		this.name = "MonobankError"
+	}
+}

package/src/core/http/monobank.http-client.ts

@@ -0,0 +1,66 @@
+import {
+	MONOBANK_API_URL,
+} from '../config/monobank.constants'
+import { MonobankError } from './monobank.error'
+import { Inject, Injectable } from '@nestjs/common'
+import { Dispatcher, request } from 'undici'
+
+import { MonobankOptionsSymbol, type MonobankModuleOptions } from '../../common/interfaces'
+
+@Injectable()
+export class MonobankHttpClient {
+	public constructor(
+		@Inject(MonobankOptionsSymbol)
+		private readonly config: MonobankModuleOptions
+	) {}
+
+	public async request<T>(options: {
+		method: Dispatcher.HttpMethod
+		url: string
+		data?: any
+		params?: any
+	}): Promise<T> {
+	     const url = this.buildUrl(options.url, options.params)
+
+		const response = await request(url, {
+			method: options.method,
+			headersTimeout: 15000,
+			bodyTimeout: 15000,
+			headers: {
+				'Content-Type': 'application/json',
+				'X-Token': this.config.apiKey,
+			},
+			body: options.data ? JSON.stringify(options.data) : undefined
+		})
+
+		if (response.statusCode >= 400) {
+			const text = await response.body.text()
+			throw new MonobankError('monobank_error', text, text)
+		}
+
+		return (await response.body.json()) as T
+	}
+
+	public get<T>(url: string, params?: any) {
+          return this.request<T>({ method: 'GET', url, params })
+	}
+
+	public post<T>(url: string, data?: any) {
+          return this.request<T>({ method: 'POST', url, data })
+	}
+
+	public delete<T>(url: string, params?: any) {
+		return this.request<T>({ method: 'DELETE', url, params })
+	}
+
+	private buildUrl(url: string, params?: any): string {
+		let fullUrl = `${MONOBANK_API_URL}${url}`
+ 
+		if (params && typeof params === 'object') {
+			const qp = new URLSearchParams(params)
+			fullUrl += `?${qp.toString()}`
+		}
+
+		return fullUrl
+	}
+}

package/src/core/http/monobank.interceptor.ts

@@ -0,0 +1,24 @@
+import { AxiosInstance } from 'axios'
+
+export function attachMonobankInterceptors(http: AxiosInstance) {
+     http.interceptors.request.use(config => {
+		console.log(
+			`[Monobank Request] → ${config.method?.toUpperCase()} ${config.url}`
+		)
+		return config
+	})
+
+	http.interceptors.response.use(
+		res => res,
+		async error => {
+			const status = error?.response?.status
+
+			if (status >= 500) {
+				console.log('[Monobank] Retrying request after server error...')
+				return await http.request(error.config)
+			}
+
+			return Promise.reject(error)
+		}
+	)
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./common/interfaces";
+export * from "./monobank.module";
+export * from "./monobank.service";

package/src/modules/invoice/enums/cancel-status.enum.ts

@@ -0,0 +1,20 @@
+/**
+ * Статус операції скасування інвойсу.
+ * @enum {string}
+ */
+export enum CancelStatusEnum {
+	/**
+	 * Заявка на скасування знаходиться в обробці.
+	 */
+	PROCESSING = 'processing',
+
+	/**
+	 * Заявка на скасування виконана успішно.
+	 */
+	SUCCESS = 'success',
+
+	/**
+	 * Неуспішна заявка на скасування.
+	 */
+	FAILURE = 'failure',
+}

package/src/modules/invoice/enums/charge-status.enum.ts

@@ -0,0 +1,16 @@
+export enum ChargeStatusEnum {
+    /**
+     * Платіж обробляється.
+     */
+    PROCESSING = 'processing',
+
+    /**
+     * Платіж успішний.
+     */
+    SUCCESS = 'success',
+
+    /**
+     * Платіж неуспішний.
+     */
+    FAILURE = 'failure',
+}

package/src/modules/invoice/enums/index.ts

@@ -0,0 +1,3 @@
+export * from './invoice-status.enum'
+export * from './cancel-status.enum'
+export * from './charge-status.enum'

package/src/modules/invoice/enums/invoice-status.enum.ts

@@ -0,0 +1,40 @@
+/**
+ * Перечисление возможных статусов инвойса.
+ * @enum {string}
+ */
+export enum InvoiceStatusEnum {
+    /**
+     * Інвойс створено, очікується оплата.
+     */
+    CREATED = "created",
+
+    /**
+     * Платіж обробляється.
+     */
+    PROCESSING = "processing",
+
+    /**
+     * Сума заблокована.
+     */
+    HOLD = "hold",
+
+    /**
+     * Успішна оплата.
+     */
+    SUCCESS = "success",
+
+    /**
+     * Неуспішна оплата.
+     */
+    FAILURE = "failure",
+
+    /**
+     * Оплата повернена після успіху.
+     */
+    REVERSED = "reversed",
+
+    /**
+     * Час дії інвойсу вичерпано.
+     */
+    EXPIRED = "expired",
+}

package/src/modules/invoice/interfaces/index.ts

@@ -0,0 +1,2 @@
+export * from './requests'
+export * from './responses'

package/src/modules/invoice/interfaces/requests/create-cancel.request.ts

@@ -0,0 +1,26 @@
+import type { BasketItem } from "../../../../common/interfaces";
+
+/**
+ * Тіло запиту на скасування інвойсу.
+ */
+export interface CreateCancelRequest {
+    /**
+     * Унікальний ідентифікатор інвойсу, який необхідно скасувати.
+     */
+    invoiceId: string;
+
+    /**
+     * Унікальний зовнішній ідентифікатор запиту на скасування, визначений продавцем (необов’язковий).
+     */
+    extRef?: string;
+
+    /**
+     * Сума повернення у мінімальних одиницях валюти (необов’язкова, використовується при частковому поверненні).
+     */
+    amount?: number;
+
+    /**
+     * Список товарів, які необхідно скасувати, обов'язковий при активованій фіскалізації.
+     */
+    items?: BasketItem[];
+}

package/src/modules/invoice/interfaces/requests/create-charge.request.ts

@@ -0,0 +1,52 @@
+import type { MerchantPaymInfoItem } from "../../../../common/interfaces";
+import type { InvoiceSaveCardData } from "./create-invoice.request";
+
+/**
+ * Дані картки для проведення оплати
+ */
+export interface CardData {
+    /** PAN картки (номер) без пробілів */
+    pan: string;
+    /** Термін дії картки у форматі MMYY */
+    exp: string;
+    /** CVV/CVC код картки */
+    cvv: number;
+}
+
+/**
+ * Дані для проведення прямого платежу (Charge) через Monobank
+ */
+export interface CreateChargeRequest {
+    /** Сума оплати у мінімальних одиницях (копійки для гривні) */
+    amount: number;
+
+    /** Валюта у форматі ISO 4217 (за замовчуванням 980 — гривня) */
+    ccy?: number;
+
+    /** Дані картки */
+    cardData: CardData;
+
+    /** Інформація про замовлення/мерчанта */
+    merchantPaymInfo?: MerchantPaymInfoItem;
+
+    /** URL для отримання сповіщень про зміну статусу платежу */
+    webhookUrl?: string;
+
+    /** URL для повернення користувача після завершення оплати */
+    redirectUrl?: string;
+
+    /** Тип операції: 
+     * - "debit" — списання коштів одразу
+     * - "hold" — утримання коштів (9 днів)
+     */
+    paymentType?: "debit" | "hold";
+
+    /** Дані для збереження картки (токенізація), якщо підключено */
+    saveCardData?: InvoiceSaveCardData;
+
+    /** Ініціатор платежу:
+     * - "merchant" — ініційовано мерчантом (регулярні платежі)
+     * - "client" — ініційовано клієнтом (за запитом користувача)
+     */
+    initiationKind: "merchant" | "client";
+}

package/src/modules/invoice/interfaces/requests/create-finalize.request.ts

@@ -0,0 +1,22 @@
+import type { BasketItem } from "../../../../common/interfaces";
+
+/**
+ * Запит на підтвердження (списання) коштів із раніше створеного холду.
+ */
+export interface CreateFinalizeRequest {
+    /**
+     * Ідентифікатор рахунку (invoice), який потрібно підтвердити.
+     */
+    invoiceId: string;
+
+    /**
+     * (Необов'язково) Сума для списання в мінімальних одиницях.
+     * Якщо не вказано — буде списано повну суму холду.
+     */
+    amount?: number;
+
+    /**
+     * (Необов'язково) Список товарів для фіскалізації або звітності.
+     */
+    items?: BasketItem[];
+}

package/src/modules/invoice/interfaces/requests/create-invoice.request.ts

@@ -0,0 +1,103 @@
+import { type MerchantPaymInfoItem } from "../../../../common/interfaces";
+
+/**
+ * Дані для збереження картки (токенізації).
+ */
+export interface InvoiceSaveCardData {
+    /**
+     * Ознака збереження картки після оплати.
+     * Обов’язкове поле.
+     */
+    saveCard: boolean;
+
+    /**
+     * Ідентифікатор гаманця користувача.
+     * Необов’язкове поле.
+     */
+    walletId?: string;
+}
+
+/**
+ * Тип, що представляє запит на створення інвойсу (рахунку).
+ */
+export interface CreateInvoiceRequest {
+    /**
+     * Сума оплати у мінімальних одиницях (наприклад, копійки для гривні).
+     * Обов’язкове поле.
+     */
+    amount: number;
+
+    /**
+     * Код валюти за стандартом ISO 4217. За замовчуванням — 980 (гривня).
+     * Необов’язкове поле.
+     */
+    ccy?: number;
+
+    /**
+     * Адреса для повернення (GET) після завершення оплати (успішно або з помилкою).
+     * Необов’язкове поле.
+     */
+    redirectUrl?: string;
+
+    /**
+     * Адреса для зворотного виклику (webhook, POST), на яку надсилатиметься інформація про зміну статусу рахунку.
+     * Необов’язкове поле.
+     */
+    webHookUrl?: string;
+
+    /**
+     * Строк дії рахунку в секундах. За замовчуванням — 24 години.
+     * Необов’язкове поле.
+     */
+    validity?: number;
+
+    /**
+     * Тип операції.
+     * 'debit' — списання,
+     * 'hold' — холд коштів на 9 днів.
+     * Необов’язкове поле.
+     */
+    paymentType?: "debit" | "hold";
+
+    /**
+     * Ідентифікатор QR-каси для встановлення суми на існуючих касах.
+     * Необов’язкове поле.
+     */
+    qrId?: string;
+
+    /**
+     * Код терміналу субмерчанта. Доступний лише окремим мерчантам.
+     * Необов’язкове поле.
+     */
+    code?: string;
+
+    /**
+     * Відсоток комісії, який агент встановлює для себе.
+     * Необов’язкове поле.
+     */
+    agentFeePercent?: number;
+
+    /**
+     * Ідентифікатор працівника, який може отримати чайові.
+     * Необов’язкове поле.
+     */
+    tipsEmployeeId?: string;
+
+    /**
+     * Тип відображення платіжної форми. Якщо не вказано — буде звичайне посилання.
+     * Необов’язкове поле.
+     */
+    displayType?: "iframe";
+
+    /**
+     * Інформація про платіж, яка може використовуватись для фіскалізації (checkbox).
+     * Необов’язкове поле.
+     */
+    merchantPaymInfo?: MerchantPaymInfoItem;
+
+    /**
+     * Дані для збереження (токенізації) картки після оплати.
+     * Необов’язкове поле.
+     */
+    saveCardData?: InvoiceSaveCardData;
+}

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

@@ -0,0 +1,4 @@
+export * from './create-invoice.request'
+export * from './create-finalize.request'
+export * from './create-cancel.request'
+export * from './create-charge.request'

package/src/modules/invoice/interfaces/responses/cancel.response.ts

@@ -0,0 +1,21 @@
+import type { CancelStatusEnum } from "../../enums";
+
+/**
+ * Відповідь на запит про скасування інвойсу.
+ */
+export interface Cancel {
+    /**
+     * Статус операції скасування.
+     */
+    status: CancelStatusEnum;
+
+    /**
+     * Дата створення операції скасування.
+     */
+    createdDate: string;
+
+    /**
+     * Дата останньої модифікації операції.
+     */
+    modifiedDate: string;
+}