@misterhomer1992/miit-bot-payment 1.1.7 → 2.0.4

package/src/modules/payments/types.ts

@@ -0,0 +1,193 @@
+import { NestedPathsAccess } from '../../types/utilities';
+
+type PaymentType = 'subscription' | 'token_pack' | 'subscription_upgrade';
+
+type PaymentEntity = {
+    /** Auto-generated unique ID (document ID) */
+    id?: string;
+    /** The unique ID you generate and send to Wayforpay. This is the key to match incoming webhooks to a payment attempt. */
+    orderReference: string;
+    /** The ID of the user initiating the payment */
+    userId: string;
+    /** The state of this payment attempt */
+    status: 'pending' | 'completed' | 'failed' | 'expired';
+    /** The URL from Wayforpay that is sent to the user */
+    paymentLink: string;
+    /** The plan or pack ID the user is attempting to purchase */
+    planId: string;
+    /** The type of payment (subscription or token_pack) */
+    paymentType: PaymentType;
+    /** The amount to be charged */
+    amount: number;
+    /** Currency of the payment */
+    currency: 'UAH' | 'USD';
+    /** When this payment attempt was created */
+    createdAt: string;
+    /** Optional. The ID of the corresponding document in the invoices collection, added after the webhook is processed */
+    invoiceId?: string;
+    /** Platform/app namespace */
+    platform: string;
+    /** Payment provider */
+    provider: 'wayforpay';
+};
+
+type PaymentFieldPath = NestedPathsAccess<PaymentEntity>;
+
+/**
+ * Interface for payment repository operations.
+ * Defines the contract for data access layer.
+ */
+interface IPaymentRepository {
+    /**
+     * Retrieves a payment by its order reference.
+     */
+    getByOrderReference(orderReference: string): Promise<PaymentEntity | null>;
+
+    /**
+     * Retrieves all payments for a specific user.
+     */
+    getByUser(params: { userId: string; platform: string; status?: PaymentEntity['status'] }): Promise<PaymentEntity[]>;
+
+    /**
+     * Creates a new payment record in the database.
+     */
+    create(paymentData: Omit<PaymentEntity, 'id'>): Promise<PaymentEntity>;
+
+    /**
+     * Updates specific fields of a payment identified by order reference.
+     * @param params - Update parameters
+     */
+    updateFields(params: { id: string; fields: any }): Promise<void>;
+
+    /**
+     * Retrieves all pending payments that are older than specified hours.
+     * @param params - Query parameters
+     * @returns Promise resolving to array of expired PaymentEntity
+     */
+    getExpiredPendingPayments(params?: { hoursOld?: number }): Promise<PaymentEntity[]>;
+}
+
+/**
+ * Result of signature validation.
+ */
+type SignatureValidationResult = {
+    isValid: boolean;
+    error?: string;
+};
+
+/**
+ * Interface for payment service operations.
+ * Defines the contract for business logic layer.
+ */
+interface IPaymentService {
+    /**
+     * Retrieves a payment by its order reference.
+     * @param orderReference - The unique order reference identifier
+     * @returns Promise resolving to PaymentEntity or null if not found
+     */
+    getByOrderReference(orderReference: string): Promise<PaymentEntity | null>;
+
+    /**
+     * Retrieves all payments for a specific user.
+     * @param params - Query parameters
+     * @returns Promise resolving to array of PaymentEntity
+     */
+    getByUser(params: { userId: string; platform: string; status?: PaymentEntity['status'] }): Promise<PaymentEntity[]>;
+
+    /**
+     * Creates a new payment record in the database.
+     * @param paymentData - Payment data without ID
+     * @returns Promise resolving to created PaymentEntity with ID
+     */
+    create(paymentData: Omit<PaymentEntity, 'id'>): Promise<PaymentEntity>;
+
+    /**
+     * Updates the status of a payment.
+     * @param params - Update parameters containing id and new status
+     */
+    updateStatus(params: { id: string; status: PaymentEntity['status'] }): Promise<void>;
+
+    /**
+     * Updates specific fields of a payment.
+     * @param params - Update parameters
+     * @deprecated Use updateStatus instead for status changes
+     */
+    changeStatus(params: { id: string; status: PaymentEntity['status'] }): Promise<void>;
+
+    /**
+     * Retrieves all pending payments that are older than specified hours.
+     * @param params - Query parameters
+     * @returns Promise resolving to array of expired PaymentEntity
+     */
+    getExpiredPendingPayments(params?: { hoursOld?: number }): Promise<PaymentEntity[]>;
+
+    /**
+     * Creates a payment intent for a user subscription.
+     * @param params - Payment intent parameters
+     * @returns Promise resolving to the created PaymentEntity with payment link
+     */
+    createPaymentIntent(params: {
+        userId: string;
+        platform: string;
+        planId: string;
+        productName: string;
+        productPrice: number;
+        currency: 'UAH' | 'USD';
+        regularCount?: number;
+        regularMode?: 'daily' | 'weekly' | 'monthly' | 'yearly';
+        language?: string;
+    }): Promise<PaymentEntity>;
+
+    /**
+     * Creates a payment intent for a token pack purchase.
+     * @param params - Payment intent parameters
+     * @returns Promise resolving to the created PaymentEntity with payment link
+     */
+    createTokenPackPaymentIntent(params: {
+        userId: string;
+        platform: string;
+        packId: string;
+        productName: string;
+        productPrice: number;
+        currency: 'UAH' | 'USD';
+        language?: string;
+        returnUrl?: string;
+    }): Promise<PaymentEntity>;
+
+    /**
+     * Validates the signature of payment callback data.
+     * @param callbackData - The callback data from the payment provider
+     * @returns Validation result indicating if signature is valid
+     */
+    validateSignature(callbackData: {
+        merchantAccount: string;
+        orderReference: string;
+        amount: number;
+        currency: string;
+        authCode: string;
+        cardPan: string;
+        transactionStatus: string;
+        reasonCode: string | number;
+        merchantSignature: string;
+    }): SignatureValidationResult;
+
+    /**
+     * Creates a payment intent for a subscription upgrade.
+     * @param params - Payment intent parameters
+     * @returns Promise resolving to the created PaymentEntity with payment link
+     */
+    createUpgradePaymentIntent(params: {
+        userId: string;
+        platform: string;
+        currentPlanId: string;
+        newPlanId: string;
+        productName: string;
+        upgradeCost: number;
+        currency: 'UAH' | 'USD';
+        regularMode?: 'daily' | 'monthly' | 'yearly';
+        regularCount?: number;
+        language?: string;
+    }): Promise<PaymentEntity>;
+}
+
+export type { PaymentEntity, PaymentType, PaymentFieldPath, IPaymentRepository, IPaymentService, SignatureValidationResult };

package/src/modules/payments/utils.ts

@@ -0,0 +1,428 @@
+/**
+ * Payment type for order references
+ */
+type OrderReferencePaymentType = 'sub' | 'tkn' | 'upg';
+
+/**
+ * Parameters for creating a subscription order reference
+ */
+interface CreateSubscriptionOrderReferenceParams {
+    userId: string;
+    platform: string;
+    planId: string;
+    utcDate: string;
+}
+
+/**
+ * Parameters for creating a token pack order reference
+ */
+interface CreateTokenPackOrderReferenceParams {
+    userId: string;
+    platform: string;
+    packId: string;
+    utcDate: string;
+}
+
+/**
+ * Parameters for creating an upgrade order reference
+ */
+interface CreateUpgradeOrderReferenceParams {
+    userId: string;
+    platform: string;
+    currentPlanId: string;
+    newPlanId: string;
+    utcDate: string;
+}
+
+/**
+ * Parsed upgrade order reference
+ */
+interface ParsedUpgradeOrderReference {
+    appName: string;
+    platform: string;
+    serviceType: string;
+    userId: string;
+    paymentType: 'upg';
+    currentPlanId: string;
+    newPlanId: string;
+    version: string;
+    timestamp: string;
+}
+
+/**
+ * Parsed order reference with payment type discrimination
+ */
+interface ParsedOrderReference {
+    appName: string;
+    platform: string;
+    serviceType: string;
+    userId: string;
+    /** Payment type: 'sub' for subscription, 'tkn' for token pack */
+    paymentType: OrderReferencePaymentType;
+    /** Plan ID for subscriptions, Pack ID for token packs */
+    itemId: string;
+    version: string;
+    timestamp: string;
+    chargeId?: string;
+}
+
+/**
+ * Legacy parsed reference string (backward compatibility)
+ */
+interface ParsedReferenceString {
+    appName: string;
+    platform: string;
+    serviceType: string;
+    userId: string;
+    planId: string;
+    version: string;
+    timestamp: string;
+    chargeId?: string;
+}
+
+const ORDER_REFERENCE_VERSION = 'v2';
+const ORDER_REFERENCE_APP_NAME = 'miia';
+const ORDER_REFERENCE_SERVICE_TYPE = 'bot';
+
+/**
+ * Creates a unique order reference for subscription payments.
+ * Format: miia_{platform}_bot_{userId}_sub_{planId}_v2_{utcDate}
+ *
+ * @param params - Parameters for generating the order reference
+ * @returns A unique order reference string
+ */
+function createSubscriptionOrderReference({
+    userId,
+    platform,
+    planId,
+    utcDate,
+}: CreateSubscriptionOrderReferenceParams): string {
+    return `${ORDER_REFERENCE_APP_NAME}_${platform}_${ORDER_REFERENCE_SERVICE_TYPE}_${userId}_sub_${planId}_${ORDER_REFERENCE_VERSION}_${utcDate}`;
+}
+
+/**
+ * Creates a unique order reference for token pack payments.
+ * Format: miia_{platform}_bot_{userId}_tkn_{packId}_v2_{utcDate}
+ *
+ * @param params - Parameters for generating the order reference
+ * @returns A unique order reference string
+ */
+function createTokenPackOrderReference({
+    userId,
+    platform,
+    packId,
+    utcDate,
+}: CreateTokenPackOrderReferenceParams): string {
+    return `${ORDER_REFERENCE_APP_NAME}_${platform}_${ORDER_REFERENCE_SERVICE_TYPE}_${userId}_tkn_${packId}_${ORDER_REFERENCE_VERSION}_${utcDate}`;
+}
+
+/**
+ * Creates a unique order reference for subscription upgrade payments.
+ * Format: miia_{platform}_bot_{userId}_upg_{currentPlanId}_to_{newPlanId}_v2_{utcDate}
+ *
+ * @param params - Parameters for generating the order reference
+ * @returns A unique order reference string
+ */
+function createUpgradeOrderReference({
+    userId,
+    platform,
+    currentPlanId,
+    newPlanId,
+    utcDate,
+}: CreateUpgradeOrderReferenceParams): string {
+    return `${ORDER_REFERENCE_APP_NAME}_${platform}_${ORDER_REFERENCE_SERVICE_TYPE}_${userId}_upg_${currentPlanId}_to_${newPlanId}_${ORDER_REFERENCE_VERSION}_${utcDate}`;
+}
+
+/**
+ * Checks if an order reference is for a subscription payment.
+ *
+ * @param orderReference - The order reference string to check
+ * @returns True if the order reference is for a subscription
+ */
+function isSubscriptionOrderReference(orderReference: string): boolean {
+    const parsed = parseOrderReference(orderReference);
+    if (!parsed) return false;
+
+    // v2 format with explicit type
+    if ('paymentType' in parsed && parsed.paymentType === 'sub') {
+        return true;
+    }
+
+    // v1 legacy format (all were subscriptions)
+    if (parsed.version === 'v1') {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Checks if an order reference is for a token pack payment.
+ *
+ * @param orderReference - The order reference string to check
+ * @returns True if the order reference is for a token pack
+ */
+function isTokenPackOrderReference(orderReference: string): boolean {
+    const parsed = parseOrderReference(orderReference);
+    if (!parsed) return false;
+
+    return 'paymentType' in parsed && parsed.paymentType === 'tkn';
+}
+
+/**
+ * Checks if an order reference is for a subscription upgrade payment.
+ *
+ * @param orderReference - The order reference string to check
+ * @returns True if the order reference is for an upgrade
+ */
+function isUpgradeOrderReference(orderReference: string): boolean {
+    const parsed = parseOrderReference(orderReference);
+    if (!parsed) return false;
+
+    return 'paymentType' in parsed && parsed.paymentType === 'upg';
+}
+
+/**
+ * Parses an upgrade order reference to extract both plan IDs.
+ *
+ * @param orderReference - The order reference string to parse
+ * @returns Parsed upgrade reference with currentPlanId and newPlanId, or null if invalid
+ */
+function parseUpgradeOrderReference(orderReference: string): ParsedUpgradeOrderReference | null {
+    const parts = orderReference.split('_');
+
+    // Format: miia_{platform}_bot_{userId}_upg_{currentPlanId}_to_{newPlanId}_v2_{timestamp}
+    // Minimum parts: appName, platform, serviceType, userId, upg, currentPlanId, to, newPlanId, version, timestamp
+    if (parts.length < 10) {
+        return null;
+    }
+
+    const [appName, platform, serviceType, userId, paymentType] = parts;
+
+    if (paymentType !== 'upg') {
+        return null;
+    }
+
+    // Find the 'to' separator to extract plan IDs
+    const toIndex = parts.indexOf('to', 5);
+    if (toIndex === -1) {
+        return null;
+    }
+
+    // currentPlanId is between 'upg' (index 4) and 'to'
+    const currentPlanId = parts.slice(5, toIndex).join('_');
+
+    // newPlanId is between 'to' and version (which starts with 'v')
+    // Find the version index (starts with 'v' and is followed by a number)
+    let versionIndex = -1;
+    for (let i = toIndex + 1; i < parts.length; i++) {
+        if (parts[i].match(/^v\d+$/)) {
+            versionIndex = i;
+            break;
+        }
+    }
+
+    if (versionIndex === -1) {
+        return null;
+    }
+
+    const newPlanId = parts.slice(toIndex + 1, versionIndex).join('_');
+    const version = parts[versionIndex];
+    const timestamp = parts.slice(versionIndex + 1).join('_');
+
+    return {
+        appName,
+        platform,
+        serviceType,
+        userId,
+        paymentType: 'upg',
+        currentPlanId,
+        newPlanId,
+        version,
+        timestamp,
+    };
+}
+
+/**
+ * Extracts the payment type from an order reference.
+ *
+ * @param orderReference - The order reference string
+ * @returns The payment type ('sub' or 'tkn'), or null if invalid
+ */
+function getOrderReferencePaymentType(orderReference: string): OrderReferencePaymentType | null {
+    const parsed = parseOrderReference(orderReference);
+    if (!parsed) return null;
+
+    if ('paymentType' in parsed) {
+        return parsed.paymentType;
+    }
+
+    // v1 legacy format was always subscription
+    if (parsed.version === 'v1') {
+        return 'sub';
+    }
+
+    return null;
+}
+
+/**
+ * Extracts the item ID (plan ID or pack ID) from an order reference.
+ *
+ * @param orderReference - The order reference string
+ * @returns The item ID, or null if invalid
+ */
+function getOrderReferenceItemId(orderReference: string): string | null {
+    const parsed = parseOrderReference(orderReference);
+    if (!parsed) return null;
+
+    if ('itemId' in parsed) {
+        return parsed.itemId;
+    }
+
+    // v1 legacy format
+    if ('planId' in parsed) {
+        return parsed.planId;
+    }
+
+    return null;
+}
+
+/**
+ * Extracts the user ID from an order reference.
+ *
+ * @param orderReference - The order reference string
+ * @returns The user ID, or null if invalid
+ */
+function getOrderReferenceUserId(orderReference: string): string | null {
+    const parsed = parseOrderReference(orderReference);
+    return parsed?.userId ?? null;
+}
+
+/**
+ * Parses an order reference string into its components.
+ * Supports both v1 (legacy) and v2 (new) formats.
+ *
+ * v1 format: miia_{platform}_bot_{userId}_{planId}_v1_{timestamp}
+ * v2 format: miia_{platform}_bot_{userId}_{type}_{itemId}_v2_{timestamp}
+ *
+ * @param referenceString - The order reference string to parse
+ * @returns Parsed reference object or null if invalid
+ */
+function parseOrderReference(referenceString: string): (ParsedOrderReference | ParsedReferenceString) | null {
+    const parts = referenceString.split('_');
+
+    // Minimum parts: appName, platform, serviceType, userId, planId/type, version, timestamp
+    if (parts.length < 7) {
+        return null;
+    }
+
+    const [appName, platform, serviceType, userId] = parts;
+
+    // Validate required fields
+    if (
+        typeof appName !== 'string' ||
+        typeof platform !== 'string' ||
+        typeof serviceType !== 'string' ||
+        typeof userId !== 'string'
+    ) {
+        return null;
+    }
+
+    // Check for v2 format (has payment type indicator)
+    const potentialType = parts[4];
+    const isV2Format = potentialType === 'sub' || potentialType === 'tkn' || potentialType === 'upg';
+
+    // Handle upgrade references separately (they have a different structure)
+    if (potentialType === 'upg') {
+        const upgradeParsed = parseUpgradeOrderReference(referenceString);
+        if (upgradeParsed) {
+            return {
+                appName: upgradeParsed.appName,
+                platform: upgradeParsed.platform,
+                serviceType: upgradeParsed.serviceType,
+                userId: upgradeParsed.userId,
+                paymentType: 'upg',
+                itemId: upgradeParsed.newPlanId, // Use newPlanId as itemId for compatibility
+                version: upgradeParsed.version,
+                timestamp: upgradeParsed.timestamp,
+            };
+        }
+        return null;
+    }
+
+    if (isV2Format) {
+        // v2 format: miia_{platform}_bot_{userId}_{type}_{itemId}_v2_{timestamp}[_{chargeId}]
+        const [, , , , paymentType, itemId, version, timestamp, chargeId] = parts;
+
+        if (
+            typeof paymentType !== 'string' ||
+            typeof itemId !== 'string' ||
+            typeof version !== 'string' ||
+            typeof timestamp !== 'string'
+        ) {
+            return null;
+        }
+
+        return {
+            appName,
+            platform,
+            serviceType,
+            userId,
+            paymentType: paymentType as OrderReferencePaymentType,
+            itemId,
+            version,
+            timestamp,
+            chargeId,
+        };
+    }
+
+    // v1 legacy format: miia_{platform}_bot_{userId}_{planId}_v1_{timestamp}[_{chargeId}]
+    const [, , , , planId, version, timestamp, chargeId] = parts;
+
+    if (typeof planId !== 'string' || typeof version !== 'string' || typeof timestamp !== 'string') {
+        return null;
+    }
+
+    return {
+        appName,
+        platform,
+        serviceType,
+        userId,
+        planId,
+        version,
+        timestamp,
+        chargeId,
+    };
+}
+
+export type {
+    OrderReferencePaymentType,
+    CreateSubscriptionOrderReferenceParams,
+    CreateTokenPackOrderReferenceParams,
+    CreateUpgradeOrderReferenceParams,
+    ParsedOrderReference,
+    ParsedReferenceString,
+    ParsedUpgradeOrderReference,
+};
+
+export {
+    // Constants
+    ORDER_REFERENCE_VERSION,
+    ORDER_REFERENCE_APP_NAME,
+    ORDER_REFERENCE_SERVICE_TYPE,
+    // New v2 functions
+    createSubscriptionOrderReference,
+    createTokenPackOrderReference,
+    createUpgradeOrderReference,
+    // Type checking functions
+    isSubscriptionOrderReference,
+    isTokenPackOrderReference,
+    isUpgradeOrderReference,
+    getOrderReferencePaymentType,
+    getOrderReferenceItemId,
+    getOrderReferenceUserId,
+    // Upgrade-specific functions
+    parseUpgradeOrderReference,
+    // Legacy (backward compatible)
+    parseOrderReference,
+};