@misterhomer1992/miit-bot-payment 1.1.6 → 2.0.4

package/src/modules/errors/types.ts

@@ -0,0 +1,201 @@
+/**
+ * Base error class for all custom errors in the payment system.
+ * Provides consistent error structure with code, message, and optional context.
+ */
+export abstract class BaseError extends Error {
+    public readonly code: string;
+    public readonly context?: Record<string, unknown>;
+    public readonly timestamp: Date;
+
+    constructor(message: string, code: string, context?: Record<string, unknown>) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.context = context;
+        this.timestamp = new Date();
+
+        // Maintains proper stack trace for where error was thrown (only in V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+
+    /**
+     * Returns a structured representation of the error for logging
+     */
+    public toJSON(): Record<string, unknown> {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            context: this.context,
+            timestamp: this.timestamp.toISOString(),
+            stack: this.stack,
+        };
+    }
+}
+
+/**
+ * Error codes for payment-related failures
+ */
+export enum PaymentErrorCode {
+    CREATE_FAILED = 'PAYMENT_CREATE_FAILED',
+    UPDATE_FAILED = 'PAYMENT_UPDATE_FAILED',
+    PROCESSING_FAILED = 'PAYMENT_PROCESSING_FAILED',
+    CALLBACK_FAILED = 'PAYMENT_CALLBACK_FAILED',
+    INVALID_RESPONSE = 'PAYMENT_INVALID_RESPONSE',
+    PROVIDER_ERROR = 'PAYMENT_PROVIDER_ERROR',
+}
+
+/**
+ * Error class for payment-related failures.
+ * Use for errors during payment creation, processing, or provider communication.
+ */
+export class PaymentError extends BaseError {
+    constructor(
+        message: string,
+        code: PaymentErrorCode = PaymentErrorCode.PROCESSING_FAILED,
+        context?: Record<string, unknown>
+    ) {
+        super(message, code, context);
+    }
+}
+
+/**
+ * Error codes for subscription-related failures
+ */
+export enum SubscriptionErrorCode {
+    CREATE_FAILED = 'SUBSCRIPTION_CREATE_FAILED',
+    UPDATE_FAILED = 'SUBSCRIPTION_UPDATE_FAILED',
+    CANCEL_FAILED = 'SUBSCRIPTION_CANCEL_FAILED',
+    RENEWAL_FAILED = 'SUBSCRIPTION_RENEWAL_FAILED',
+    INVALID_STATUS = 'SUBSCRIPTION_INVALID_STATUS',
+    EXPIRED = 'SUBSCRIPTION_EXPIRED',
+}
+
+/**
+ * Error class for subscription-related failures.
+ * Use for errors during subscription lifecycle operations.
+ */
+export class SubscriptionError extends BaseError {
+    constructor(
+        message: string,
+        code: SubscriptionErrorCode = SubscriptionErrorCode.UPDATE_FAILED,
+        context?: Record<string, unknown>
+    ) {
+        super(message, code, context);
+    }
+}
+
+/**
+ * Error codes for validation failures
+ */
+export enum ValidationErrorCode {
+    INVALID_SIGNATURE = 'VALIDATION_INVALID_SIGNATURE',
+    INVALID_INPUT = 'VALIDATION_INVALID_INPUT',
+    MISSING_REQUIRED_FIELD = 'VALIDATION_MISSING_REQUIRED_FIELD',
+    INVALID_FORMAT = 'VALIDATION_INVALID_FORMAT',
+    SIGNATURE_MISMATCH = 'VALIDATION_SIGNATURE_MISMATCH',
+}
+
+/**
+ * Error class for signature and input validation failures.
+ * Use for errors when validating signatures, inputs, or data formats.
+ */
+export class ValidationError extends BaseError {
+    public readonly field?: string;
+
+    constructor(
+        message: string,
+        code: ValidationErrorCode = ValidationErrorCode.INVALID_INPUT,
+        context?: Record<string, unknown>,
+        field?: string
+    ) {
+        super(message, code, context);
+        this.field = field;
+    }
+
+    public toJSON(): Record<string, unknown> {
+        return {
+            ...super.toJSON(),
+            field: this.field,
+        };
+    }
+}
+
+/**
+ * Error codes for not found errors
+ */
+export enum NotFoundErrorCode {
+    PAYMENT_NOT_FOUND = 'NOT_FOUND_PAYMENT',
+    SUBSCRIPTION_NOT_FOUND = 'NOT_FOUND_SUBSCRIPTION',
+    USER_NOT_FOUND = 'NOT_FOUND_USER',
+    PLAN_NOT_FOUND = 'NOT_FOUND_PLAN',
+    INVOICE_NOT_FOUND = 'NOT_FOUND_INVOICE',
+    TOKEN_PACK_NOT_FOUND = 'NOT_FOUND_TOKEN_PACK',
+    RESOURCE_NOT_FOUND = 'NOT_FOUND_RESOURCE',
+}
+
+/**
+ * Error class for missing resources.
+ * Use when a requested entity cannot be found.
+ */
+export class NotFoundError extends BaseError {
+    public readonly resourceType?: string;
+    public readonly resourceId?: string;
+
+    constructor(
+        message: string,
+        code: NotFoundErrorCode = NotFoundErrorCode.RESOURCE_NOT_FOUND,
+        context?: Record<string, unknown>,
+        resourceType?: string,
+        resourceId?: string
+    ) {
+        super(message, code, context);
+        this.resourceType = resourceType;
+        this.resourceId = resourceId;
+    }
+
+    public toJSON(): Record<string, unknown> {
+        return {
+            ...super.toJSON(),
+            resourceType: this.resourceType,
+            resourceId: this.resourceId,
+        };
+    }
+}
+
+/**
+ * Type guard to check if an error is a BaseError
+ */
+export function isBaseError(error: unknown): error is BaseError {
+    return error instanceof BaseError;
+}
+
+/**
+ * Type guard to check if an error is a PaymentError
+ */
+export function isPaymentError(error: unknown): error is PaymentError {
+    return error instanceof PaymentError;
+}
+
+/**
+ * Type guard to check if an error is a SubscriptionError
+ */
+export function isSubscriptionError(error: unknown): error is SubscriptionError {
+    return error instanceof SubscriptionError;
+}
+
+/**
+ * Type guard to check if an error is a ValidationError
+ */
+export function isValidationError(error: unknown): error is ValidationError {
+    return error instanceof ValidationError;
+}
+
+/**
+ * Type guard to check if an error is a NotFoundError
+ */
+export function isNotFoundError(error: unknown): error is NotFoundError {
+    return error instanceof NotFoundError;
+}

package/src/modules/invoice/const.ts

@@ -0,0 +1,7 @@
+import { InvoiceEntity } from './types';
+
+const DEFAULT_INVOICE_ENTITY: Partial<InvoiceEntity> = {
+    currency: 'UAH',
+};
+
+export { DEFAULT_INVOICE_ENTITY };

package/src/modules/invoice/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './repository';
+export * from './service';
+export * from './const';

package/src/modules/invoice/repository.ts

@@ -0,0 +1,52 @@
+import { Firestore, getFirestore, QueryDocumentSnapshot } from 'firebase-admin/firestore';
+import { InvoiceEntity, IInvoiceRepository } from './types';
+import { DEFAULT_INVOICE_ENTITY } from './const';
+
+class InvoiceRepository implements IInvoiceRepository {
+    private readonly db: Firestore;
+    private readonly collectionName = 'invoices';
+
+    constructor({ db }: { db?: Firestore } = {}) {
+        this.db = db || getFirestore();
+    }
+
+    public async getByOrderReference(orderReference: string): Promise<InvoiceEntity | null> {
+        const querySnapshot = await this.db
+            .collection(this.collectionName)
+            .where('orderReference', '==', orderReference)
+            .limit(1)
+            .get();
+
+        if (querySnapshot.empty) {
+            return null;
+        }
+
+        const doc = querySnapshot.docs[0];
+        return this.mapDocumentToEntity(doc);
+    }
+
+    public async create(invoiceData: Omit<InvoiceEntity, 'id'>): Promise<InvoiceEntity> {
+        // Generate a new document reference to get the ID first
+        const docRef = this.db.collection(this.collectionName).doc();
+
+        const invoiceEntity: InvoiceEntity = {
+            id: docRef.id,
+            ...DEFAULT_INVOICE_ENTITY,
+            ...invoiceData,
+        };
+
+        // Use set() to create the document with the ID included in the data
+        await docRef.set(invoiceEntity);
+
+        return invoiceEntity;
+    }
+
+    private mapDocumentToEntity(doc: QueryDocumentSnapshot): InvoiceEntity {
+        return {
+            id: doc.id,
+            ...doc.data(),
+        } as InvoiceEntity;
+    }
+}
+
+export { InvoiceRepository };

package/src/modules/invoice/service.ts

@@ -0,0 +1,44 @@
+import { Logger } from '../logger/types';
+import { InvoiceRepository } from './repository';
+import { InvoiceEntity, IInvoiceRepository, IInvoiceService } from './types';
+
+export class InvoiceService implements IInvoiceService {
+    private readonly logger: Logger;
+    private readonly repository: IInvoiceRepository;
+
+    constructor({ logger, repository }: { logger: Logger; repository?: IInvoiceRepository }) {
+        this.logger = logger;
+        this.repository = repository || new InvoiceRepository();
+    }
+
+    public async create(invoiceData: Omit<InvoiceEntity, 'id'>): Promise<InvoiceEntity> {
+        try {
+            return await this.repository.create(invoiceData);
+        } catch (error) {
+            this.logger.error({
+                message: 'Error in invoice service create',
+                payload: {
+                    orderReference: invoiceData.orderReference,
+                    error: JSON.stringify(error),
+                },
+            });
+
+            throw error;
+        }
+    }
+
+    public async getByOrderReference(orderReference: string): Promise<InvoiceEntity | null> {
+        try {
+            return await this.repository.getByOrderReference(orderReference);
+        } catch (error) {
+            this.logger.error({
+                message: 'Error in invoice service getByOrderReference',
+                payload: {
+                    orderReference,
+                    error: JSON.stringify(error),
+                },
+            });
+            return null;
+        }
+    }
+}

package/src/modules/invoice/types.ts

@@ -0,0 +1,47 @@
+type InvoiceEntity = {
+    id: string;
+    merchantAccount: string;
+    orderReference: string;
+    merchantSignature: string;
+    reasonCode: number;
+    reason: string;
+    createdDate: string;
+    processingDate: string;
+    currency: string;
+    amount: number;
+    chargeId?: string;
+};
+
+/**
+ * Interface for invoice repository operations.
+ * Defines the contract for data access layer.
+ */
+interface IInvoiceRepository {
+    /**
+     * Retrieves an invoice by its order reference.
+     */
+    getByOrderReference(orderReference: string): Promise<InvoiceEntity | null>;
+
+    /**
+     * Creates a new invoice record in the database.
+     */
+    create(invoiceData: Omit<InvoiceEntity, 'id'>): Promise<InvoiceEntity>;
+}
+
+/**
+ * Interface for invoice service operations.
+ * Defines the contract for business logic layer.
+ */
+interface IInvoiceService {
+    /**
+     * Creates a new invoice.
+     */
+    create(invoiceData: Omit<InvoiceEntity, 'id'>): Promise<InvoiceEntity>;
+
+    /**
+     * Retrieves an invoice by order reference.
+     */
+    getByOrderReference(orderReference: string): Promise<InvoiceEntity | null>;
+}
+
+export type { InvoiceEntity, IInvoiceRepository, IInvoiceService };

package/src/modules/logger/types.ts

@@ -0,0 +1,8 @@
+interface Logger {
+    info: (message?: Record<string, unknown>) => void;
+    warning: (message?: Record<string, unknown>) => void;
+    error: (message?: Record<string, unknown>) => void;
+    debug: (message?: Record<string, unknown>) => void;
+}
+
+export { Logger };

package/src/modules/network/utils.ts

@@ -0,0 +1,24 @@
+function mockTimeoutResponse({
+    // timeout = 12000,
+    timeout = 1002000,
+    rejectedCode = 'RESPONSE_TIMEOUT',
+} = {}): {
+    promise: Promise<never>;
+    cleanUp: () => void;
+} {
+    let timeoutId;
+    const promise = new Promise<never>(function (_, reject) {
+        timeoutId = setTimeout(() => {
+            reject({
+                code: rejectedCode,
+            });
+        }, timeout);
+    });
+
+    return {
+        promise,
+        cleanUp: () => clearTimeout(timeoutId),
+    };
+}
+
+export { mockTimeoutResponse };

package/src/modules/payments/api.ts

@@ -0,0 +1,289 @@
+import moment from 'moment';
+import {
+    Currency,
+    editRegularPurchase,
+    generateRegularPurchase,
+    generatePurchase,
+    Language,
+} from '@misterhomer1992/wayforpay-api';
+import { isObject, isBadOrEmptyString } from '../../utils';
+import { createSubscriptionOrderReference, createTokenPackOrderReference, createUpgradeOrderReference } from './utils';
+
+interface WayforpayResponse {
+    url?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Creates a payment API URL for regular purchases via Wayforpay.
+ * Generates a unique order reference and creates a payment URL with the provided parameters.
+ *
+ * @param params - Payment creation parameters
+ * @param params.userId - The unique identifier of the user making the payment
+ * @param params.platform - The application namespace (e.g., 'app' or 'telegram')
+ * @param params.productName - The name of the product being purchased
+ * @param params.productPrice - The price of the product
+ * @param params.planId - The identifier of the subscription plan
+ * @param params.dateNext - Optional date for the next payment in the regular purchase cycle
+ * @param params.currency - The currency code (e.g., 'UAH', 'USD')
+ * @param params.regularCount - Optional number of regular payments (defaults to 3)
+ * @returns Promise resolving to an object containing the payment URL and order reference, or null
+ * @throws Error with code 'CREATE_PAYMENT_API' if the API response is invalid or missing URL
+ */
+async function createPaymentAPI({
+    userId,
+    platform,
+    productName,
+    productPrice,
+    planId,
+    dateNext,
+    currency,
+    regularCount = 3,
+    regularMode = 'daily',
+    language = 'UA',
+}: {
+    userId: string;
+    platform: string;
+    productName: string;
+    productPrice: number;
+    planId: string;
+    dateNext?: string;
+    currency: string;
+    regularCount?: number;
+    regularMode?: 'daily' | 'weekly' | 'monthly' | 'yearly';
+    language?: string;
+}): Promise<{ url: string; orderReference: string } | null> {
+    const orderDate = Date.now();
+    const formattedUtc = moment.utc().toISOString();
+    const orderReference = createSubscriptionOrderReference({
+        userId,
+        platform,
+        planId,
+        utcDate: formattedUtc,
+    });
+
+    const response = (await generateRegularPurchase({
+        merchantAccount: process.env.WAYFORPAY_MERCHANT_ACCOUNT as string,
+        merchantDomainName: process.env.WAYFORPAY_MERCHANT_DOMAIN as string,
+        merchantSecretKey: process.env.WAYFORPAY_MERCHANT_SECRET_KEY as string,
+        orderDate,
+        orderReference,
+        productName: [productName],
+        productPrice: [productPrice],
+        currency: currency as Currency,
+        language: language as Language,
+        serviceUrl: process.env.WAYFORPAY_SERVICE_URL as string,
+        regularMode,
+        regularCount,
+        dateNext,
+    })) as WayforpayResponse;
+
+    if (!isObject(response) || isBadOrEmptyString(response.url)) {
+        throw {
+            code: 'CREATE_PAYMENT_API',
+        };
+    }
+
+    return {
+        url: response.url,
+        orderReference,
+    };
+}
+
+/**
+ * Edits an existing regular purchase via Wayforpay.
+ * Updates the parameters of an existing recurring payment schedule.
+ *
+ * @param params - Parameters for editing the regular purchase
+ * @param params.orderReference - The unique reference of the order to edit
+ * @param params.amount - The new payment amount
+ * @param params.dateBegin - The start date for the regular purchase in DD.MM.YYYY format
+ * @param params.dateEnd - The end date for the regular purchase in DD.MM.YYYY format
+ * @param params.regularMode - The frequency mode for regular payments
+ * @returns Promise resolving to the Wayforpay API response
+ * @throws Error with code 'EDIT_REGULAR_PURCHASE_API' if the API response is invalid
+ */
+async function editRegularPurchaseAPI({
+    orderReference,
+    amount,
+    dateBegin,
+    dateEnd,
+    regularMode,
+    currency,
+}: {
+    orderReference: string;
+    amount: number;
+    dateBegin: string;
+    dateEnd: string;
+    regularMode: 'daily' | 'weekly' | 'monthly' | 'yearly';
+    currency: string;
+}): Promise<WayforpayResponse> {
+    const response = await editRegularPurchase({
+        merchantAccount: process.env.WAYFORPAY_MERCHANT_ACCOUNT as string,
+        merchantPassword: process.env.WAYFORPAY_MERCHANT_PASSWORD as string,
+        orderReference,
+        amount,
+        dateBegin,
+        dateEnd,
+        regularMode,
+        currency: currency as Currency,
+    });
+
+    if (!isObject(response)) {
+        throw {
+            code: 'EDIT_REGULAR_PURCHASE_API',
+        };
+    }
+
+    return response;
+}
+
+/**
+ * Creates a one-time payment API URL for token pack purchases via Wayforpay.
+ * Generates a unique order reference using the v2 token pack format.
+ *
+ * @param params - Payment creation parameters
+ * @param params.userId - The unique identifier of the user making the payment
+ * @param params.platform - The application namespace (e.g., 'app' or 'telegram')
+ * @param params.productName - The name of the token pack being purchased
+ * @param params.productPrice - The price of the token pack
+ * @param params.packId - The identifier of the token pack
+ * @param params.currency - The currency code (e.g., 'UAH', 'USD')
+ * @param params.language - The language for the payment page (defaults to 'UA')
+ * @param params.returnUrl - Optional URL to redirect to after payment
+ * @returns Promise resolving to an object containing the payment URL and order reference, or null
+ * @throws Error with code 'CREATE_TOKEN_PACK_PAYMENT_API' if the API response is invalid or missing URL
+ */
+async function createTokenPackPaymentAPI({
+    userId,
+    platform,
+    productName,
+    productPrice,
+    packId,
+    currency,
+    language = 'UA',
+    returnUrl,
+}: {
+    userId: string;
+    platform: string;
+    productName: string;
+    productPrice: number;
+    packId: string;
+    currency: string;
+    language?: string;
+    returnUrl?: string;
+}): Promise<{ url: string; orderReference: string } | null> {
+    const orderDate = Date.now();
+    const formattedUtc = moment.utc().toISOString();
+    const orderReference = createTokenPackOrderReference({
+        userId,
+        platform,
+        packId,
+        utcDate: formattedUtc,
+    });
+
+    const response = (await generatePurchase({
+        merchantAccount: process.env.WAYFORPAY_MERCHANT_ACCOUNT as string,
+        merchantDomainName: process.env.WAYFORPAY_MERCHANT_DOMAIN as string,
+        merchantSecretKey: process.env.WAYFORPAY_MERCHANT_SECRET_KEY as string,
+        orderDate,
+        orderReference,
+        productName: [productName],
+        productPrice: [productPrice],
+        currency: currency as Currency,
+        language: language as Language,
+        serviceUrl: process.env.WAYFORPAY_SERVICE_URL as string,
+        returnUrl,
+    })) as WayforpayResponse;
+
+    if (!isObject(response) || isBadOrEmptyString(response.url)) {
+        throw {
+            code: 'CREATE_TOKEN_PACK_PAYMENT_API',
+        };
+    }
+
+    return {
+        url: response.url,
+        orderReference,
+    };
+}
+
+/**
+ * Creates a recurring payment API URL for subscription upgrades via Wayforpay.
+ * Generates a unique order reference using the upgrade format.
+ *
+ * @param params - Payment creation parameters
+ * @param params.userId - The unique identifier of the user making the payment
+ * @param params.platform - The application namespace (e.g., 'app' or 'telegram')
+ * @param params.currentPlanId - The identifier of the current subscription plan
+ * @param params.newPlanId - The identifier of the new subscription plan to upgrade to
+ * @param params.productName - The name of the upgraded plan being purchased
+ * @param params.productPrice - The price difference (upgrade cost)
+ * @param params.currency - The currency code (e.g., 'UAH', 'USD')
+ * @param params.regularMode - The frequency mode for regular payments
+ * @param params.regularCount - Number of regular payments (defaults to 3)
+ * @param params.language - The language for the payment page (defaults to 'UA')
+ * @returns Promise resolving to an object containing the payment URL and order reference, or null
+ * @throws Error with code 'CREATE_UPGRADE_PAYMENT_API' if the API response is invalid or missing URL
+ */
+async function createUpgradePaymentAPI({
+    userId,
+    platform,
+    currentPlanId,
+    newPlanId,
+    productName,
+    productPrice,
+    currency,
+    regularMode = 'monthly',
+    regularCount = 3,
+    language = 'UA',
+}: {
+    userId: string;
+    platform: string;
+    currentPlanId: string;
+    newPlanId: string;
+    productName: string;
+    productPrice: number;
+    currency: string;
+    regularMode?: 'daily' | 'monthly' | 'yearly';
+    regularCount?: number;
+    language?: string;
+}): Promise<{ url: string; orderReference: string } | null> {
+    const orderDate = Date.now();
+    const formattedUtc = moment.utc().toISOString();
+    const orderReference = createUpgradeOrderReference({
+        userId,
+        platform,
+        currentPlanId,
+        newPlanId,
+        utcDate: formattedUtc,
+    });
+
+    const response = (await generateRegularPurchase({
+        merchantAccount: process.env.WAYFORPAY_MERCHANT_ACCOUNT as string,
+        merchantDomainName: process.env.WAYFORPAY_MERCHANT_DOMAIN as string,
+        merchantSecretKey: process.env.WAYFORPAY_MERCHANT_SECRET_KEY as string,
+        orderDate,
+        orderReference,
+        productName: [productName],
+        productPrice: [productPrice],
+        currency: currency as Currency,
+        language: language as Language,
+        serviceUrl: process.env.WAYFORPAY_SERVICE_URL as string,
+        regularMode,
+        regularCount,
+    })) as WayforpayResponse;
+
+    if (!isObject(response) || isBadOrEmptyString(response.url)) {
+        throw {
+            code: 'CREATE_UPGRADE_PAYMENT_API',
+        };
+    }
+
+    return {
+        url: response.url,
+        orderReference,
+    };
+}
+
+export { createPaymentAPI, editRegularPurchaseAPI, createTokenPackPaymentAPI, createUpgradePaymentAPI };

package/src/modules/payments/const.ts

@@ -0,0 +1,11 @@
+import { PaymentEntity } from './types';
+
+const DEFAULT_PAYMENT_ENTITY: Partial<PaymentEntity> = {
+    status: 'pending',
+    provider: 'wayforpay',
+    platform: 'telegram',
+    currency: 'UAH',
+    paymentType: 'subscription',
+};
+
+export { DEFAULT_PAYMENT_ENTITY };