@misterhomer1992/miit-bot-payment 1.1.7 → 2.0.4

package/src/modules/payments/subscription-check-webhook.handler.ts

@@ -0,0 +1,211 @@
+import { Logger } from '../logger/types';
+import { SubscriptionCheckWebhookService } from './subscription-check-webhook.service';
+import type { WayForPayCallbackData } from './wayforpay.types';
+import type { WebhookRequest, WebhookResponse } from './webhook.handler';
+import type {
+    ISubscriptionCheckWebhookService,
+    SubscriptionCheckWebhookResult,
+} from './subscription-check-webhook.types';
+
+/**
+ * Configuration options for the subscription check webhook handler.
+ */
+interface SubscriptionCheckWebhookHandlerConfig {
+    logger: Logger;
+    webhookService?: ISubscriptionCheckWebhookService;
+}
+
+/**
+ * Result of parsing the webhook request body.
+ */
+interface ParseResult {
+    success: boolean;
+    data?: WayForPayCallbackData;
+    error?: string;
+}
+
+/**
+ * SubscriptionCheckWebhookHandler provides HTTP request handling for WayForPay
+ * subscription status check callbacks. It validates incoming requests and delegates
+ * processing to the SubscriptionCheckWebhookService.
+ *
+ * Usage with Express:
+ * ```typescript
+ * const handler = new SubscriptionCheckWebhookHandler({ logger });
+ * app.post('/webhook/subscription-check', (req, res) => handler.handleRequest(req, res));
+ * ```
+ *
+ * Usage with Cloud Functions:
+ * ```typescript
+ * const handler = new SubscriptionCheckWebhookHandler({ logger });
+ * export const subscriptionCheckWebhook = (req, res) => handler.handleRequest(req, res);
+ * ```
+ */
+export class SubscriptionCheckWebhookHandler {
+    private readonly logger: Logger;
+    private readonly webhookService: ISubscriptionCheckWebhookService;
+
+    constructor(config: SubscriptionCheckWebhookHandlerConfig) {
+        this.logger = config.logger;
+        this.webhookService =
+            config.webhookService ||
+            new SubscriptionCheckWebhookService({
+                logger: config.logger,
+            });
+    }
+
+    /**
+     * Handles an incoming HTTP request from WayForPay for subscription checks.
+     * Validates the request body, processes the subscription check callback,
+     * and returns the appropriate response.
+     *
+     * @param req - The HTTP request object
+     * @param res - The HTTP response object
+     */
+    public async handleRequest(req: WebhookRequest, res: WebhookResponse): Promise<void> {
+        this.logger.info({
+            message: 'Received WayForPay subscription check webhook request',
+            payload: {},
+        });
+
+        // Parse and validate the request body
+        const parseResult = this.parseRequestBody(req.body);
+
+        if (!parseResult.success || !parseResult.data) {
+            this.logger.warning({
+                message: 'Invalid subscription check webhook request body',
+                payload: { error: parseResult.error },
+            });
+
+            res.status(400).json({
+                error: parseResult.error || 'Invalid request body',
+            });
+            return;
+        }
+
+        const callbackData = parseResult.data;
+
+        // Process the webhook
+        const result = await this.webhookService.processSubscriptionCheckWebhook(callbackData);
+
+        // Return the response to WayForPay
+        this.sendResponse(res, result);
+    }
+
+    /**
+     * Processes callback data directly without HTTP request parsing.
+     * Useful for testing or when data is already parsed.
+     *
+     * @param callbackData - The parsed callback data from WayForPay
+     * @returns Processing result with response to send back to WayForPay
+     */
+    public async processCallback(
+        callbackData: WayForPayCallbackData,
+    ): Promise<SubscriptionCheckWebhookResult> {
+        return this.webhookService.processSubscriptionCheckWebhook(callbackData);
+    }
+
+    /**
+     * Parses and validates the webhook request body.
+     */
+    private parseRequestBody(body: unknown): ParseResult {
+        if (!body || typeof body !== 'object') {
+            return {
+                success: false,
+                error: 'Request body must be a JSON object',
+            };
+        }
+
+        const data = body as Record<string, unknown>;
+
+        // Validate required fields for subscription check webhook
+        const requiredFields = [
+            'merchantAccount',
+            'orderReference',
+            'merchantSignature',
+            'amount',
+            'currency',
+            'transactionStatus',
+        ];
+
+        const missingFields = requiredFields.filter(
+            (field) => data[field] === undefined || data[field] === null,
+        );
+
+        if (missingFields.length > 0) {
+            return {
+                success: false,
+                error: `Missing required fields: ${missingFields.join(', ')}`,
+            };
+        }
+
+        // Validate transaction status
+        const validStatuses = ['Approved', 'Declined', 'Expired', 'Pending', 'InProcessing', 'Refunded'];
+        if (!validStatuses.includes(data.transactionStatus as string)) {
+            return {
+                success: false,
+                error: `Invalid transaction status: ${data.transactionStatus}`,
+            };
+        }
+
+        return {
+            success: true,
+            data: data as unknown as WayForPayCallbackData,
+        };
+    }
+
+    /**
+     * Sends the response back to WayForPay.
+     * WayForPay expects a 200 status with a signed response body.
+     */
+    private sendResponse(res: WebhookResponse, result: SubscriptionCheckWebhookResult): void {
+        // WayForPay expects a 200 status code even for declined transactions
+        // The accept/decline status is communicated in the response body
+        res.status(200).json(result.response);
+
+        this.logger.info({
+            message: 'Subscription check webhook response sent',
+            payload: {
+                success: result.success,
+                status: result.response.status,
+                orderReference: result.response.orderReference,
+            },
+        });
+    }
+}
+
+/**
+ * Creates a subscription check webhook handler function for use with serverless platforms.
+ * Returns a function that can be directly used as a Cloud Function or Lambda handler.
+ *
+ * @param config - Configuration options for the webhook handler
+ * @returns An async function that handles webhook requests
+ *
+ * @example
+ * ```typescript
+ * // Firebase Cloud Functions
+ * import * as functions from 'firebase-functions';
+ * import { createSubscriptionCheckWebhookHandler } from 'miit-bot-payment';
+ *
+ * const logger = { info: console.log, warning: console.warn, error: console.error };
+ * export const subscriptionCheckWebhook = functions.https.onRequest(
+ *     createSubscriptionCheckWebhookHandler({ logger })
+ * );
+ * ```
+ */
+export function createSubscriptionCheckWebhookHandler(
+    config: SubscriptionCheckWebhookHandlerConfig,
+): (req: WebhookRequest, res: WebhookResponse) => Promise<void> {
+    const handler = new SubscriptionCheckWebhookHandler(config);
+    return (req: WebhookRequest, res: WebhookResponse) => handler.handleRequest(req, res);
+}
+
+/**
+ * Type export for the webhook handler function signature.
+ */
+export type SubscriptionCheckWebhookHandlerFunction = (
+    req: WebhookRequest,
+    res: WebhookResponse,
+) => Promise<void>;
+
+export type { SubscriptionCheckWebhookHandlerConfig };

package/src/modules/payments/subscription-check-webhook.service.ts

@@ -0,0 +1,398 @@
+import moment from 'moment';
+import type { ResponseTransactionStatus } from '@misterhomer1992/wayforpay-api';
+import { Logger } from '../logger/types';
+
+const APPROVED_STATUS: ResponseTransactionStatus = 'Approved';
+const DECLINED_STATUS: ResponseTransactionStatus = 'Declined';
+const EXPIRED_STATUS: ResponseTransactionStatus = 'Expired';
+
+import { WayForPayService } from './wayforpay.service';
+import { SubscriptionService } from '../subscription/service';
+import { SubscriptionPlanService } from '../subscriptionPlan/service';
+import {
+    parseOrderReference,
+    isSubscriptionOrderReference,
+    getOrderReferenceUserId,
+    getOrderReferenceItemId,
+} from './utils';
+import type { WayForPayCallbackData, IWayForPayService } from './wayforpay.types';
+import type { ISubscriptionService, SubscriptionEntity } from '../subscription/types';
+import type { ISubscriptionPlanService } from '../subscriptionPlan/types';
+import type {
+    SubscriptionCheckWebhookResult,
+    ISubscriptionCheckWebhookService,
+} from './subscription-check-webhook.types';
+import { ConfigurationManager, GracePeriodConfig, DEFAULT_GRACE_PERIOD_CONFIG } from '../../config';
+
+/**
+ * SubscriptionCheckWebhookService processes subscription status check webhooks from WayForPay.
+ * It handles signature verification, renewal status checks, and subscription updates.
+ *
+ * WayForPay sends subscription check webhooks for recurring payments to verify
+ * if the subscription should be renewed or deactivated.
+ */
+export class SubscriptionCheckWebhookService implements ISubscriptionCheckWebhookService {
+    private readonly logger: Logger;
+    private readonly wayForPayService: IWayForPayService;
+    private readonly subscriptionService: ISubscriptionService;
+    private readonly subscriptionPlanService: ISubscriptionPlanService;
+    private readonly gracePeriodConfig: GracePeriodConfig;
+
+    constructor({
+        logger,
+        wayForPayService,
+        subscriptionService,
+        subscriptionPlanService,
+        gracePeriodConfig,
+    }: {
+        logger: Logger;
+        wayForPayService?: IWayForPayService;
+        subscriptionService?: ISubscriptionService;
+        subscriptionPlanService?: ISubscriptionPlanService;
+        gracePeriodConfig?: GracePeriodConfig;
+    }) {
+        this.logger = logger;
+        this.wayForPayService = wayForPayService || new WayForPayService({ logger });
+        this.subscriptionService = subscriptionService || new SubscriptionService({ logger });
+        this.subscriptionPlanService = subscriptionPlanService || new SubscriptionPlanService({ logger });
+        this.gracePeriodConfig = gracePeriodConfig || this.loadGracePeriodConfig();
+    }
+
+    private loadGracePeriodConfig(): GracePeriodConfig {
+        try {
+            const configManager = ConfigurationManager.getInstance();
+            return configManager.getGracePeriodConfig();
+        } catch {
+            return DEFAULT_GRACE_PERIOD_CONFIG;
+        }
+    }
+
+    /**
+     * Processes a subscription check webhook from WayForPay.
+     * This method handles the complete webhook flow:
+     * 1. Verifies the signature to validate request authenticity
+     * 2. Checks the renewal status from WayForPay
+     * 3. Renews subscription if payment was successful
+     * 4. Marks subscription for deactivation if payment failed
+     *
+     * @param callbackData - The callback data from WayForPay
+     * @returns Processing result with response to send back to WayForPay
+     */
+    public async processSubscriptionCheckWebhook(
+        callbackData: WayForPayCallbackData,
+    ): Promise<SubscriptionCheckWebhookResult> {
+        const { orderReference, transactionStatus } = callbackData;
+
+        this.logger.info({
+            message: 'Processing subscription check webhook',
+            payload: {
+                orderReference,
+                transactionStatus,
+                regularOn: callbackData.regularOn,
+            },
+        });
+
+        try {
+            // Step 1: Verify signature to validate request authenticity
+            const signatureResult = this.wayForPayService.verifyCallbackSignature(callbackData);
+
+            if (!signatureResult.isValid) {
+                this.logger.warning({
+                    message: 'Invalid subscription check webhook signature',
+                    payload: {
+                        orderReference,
+                        error: signatureResult.error,
+                    },
+                });
+
+                return {
+                    success: false,
+                    response: this.wayForPayService.buildWebhookResponse(orderReference, 'decline'),
+                    error: signatureResult.error || 'Invalid signature',
+                };
+            }
+
+            // Step 2: Validate this is a subscription order reference
+            if (!isSubscriptionOrderReference(orderReference)) {
+                this.logger.warning({
+                    message: 'Subscription check webhook received for non-subscription order',
+                    payload: { orderReference },
+                });
+
+                return {
+                    success: true,
+                    response: this.wayForPayService.buildWebhookResponse(orderReference, 'accept'),
+                };
+            }
+
+            // Step 3: Check renewal status and process accordingly
+            if (transactionStatus === APPROVED_STATUS) {
+                await this.handleSuccessfulRenewal(callbackData);
+            } else if (transactionStatus === DECLINED_STATUS || transactionStatus === EXPIRED_STATUS) {
+                await this.handleFailedRenewal(callbackData);
+            } else {
+                this.logger.info({
+                    message: 'Subscription check webhook received with non-final status',
+                    payload: {
+                        orderReference,
+                        transactionStatus,
+                    },
+                });
+            }
+
+            return {
+                success: true,
+                response: this.wayForPayService.buildWebhookResponse(orderReference, 'accept'),
+            };
+        } catch (error) {
+            this.logger.error({
+                message: 'Error processing subscription check webhook',
+                payload: {
+                    orderReference,
+                    error: JSON.stringify(error),
+                },
+            });
+
+            return {
+                success: false,
+                response: this.wayForPayService.buildWebhookResponse(orderReference, 'decline'),
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+
+    /**
+     * Handles a successful subscription renewal.
+     * Extends the subscription expiration date based on the plan.
+     */
+    private async handleSuccessfulRenewal(callbackData: WayForPayCallbackData): Promise<void> {
+        const { orderReference } = callbackData;
+
+        const parsedReference = parseOrderReference(orderReference);
+        if (!parsedReference) {
+            this.logger.warning({
+                message: 'Could not parse order reference for successful renewal',
+                payload: { orderReference },
+            });
+            return;
+        }
+
+        const userId = getOrderReferenceUserId(orderReference);
+        const planId = getOrderReferenceItemId(orderReference);
+        const { platform } = parsedReference;
+
+        if (!userId || !planId) {
+            this.logger.warning({
+                message: 'Could not extract userId or planId from order reference',
+                payload: { orderReference },
+            });
+            return;
+        }
+
+        // Find active subscription for user
+        const existingSubscription = await this.subscriptionService.getByUser({
+            userId,
+            platform,
+            status: 'active',
+        });
+
+        if (!existingSubscription) {
+            this.logger.warning({
+                message: 'No active subscription found for successful renewal',
+                payload: { userId, platform, orderReference },
+            });
+            return;
+        }
+
+        // Get subscription plan to calculate new expiration
+        const subscriptionPlan = await this.subscriptionPlanService.getById(planId);
+        if (!subscriptionPlan) {
+            this.logger.warning({
+                message: 'Subscription plan not found for renewal',
+                payload: { planId, orderReference },
+            });
+            return;
+        }
+
+        // Calculate new expiration date
+        const newExpiresAt = this.calculateExpirationDate(
+            subscriptionPlan.regularMode,
+            subscriptionPlan.count,
+        );
+
+        // Renew subscription
+        await this.renewSubscription(existingSubscription, newExpiresAt);
+
+        this.logger.info({
+            message: 'Subscription renewed successfully via check webhook',
+            payload: {
+                subscriptionId: existingSubscription.id,
+                userId,
+                platform,
+                planId,
+                newExpiresAt,
+            },
+        });
+    }
+
+    /**
+     * Handles a failed subscription renewal.
+     * Marks the subscription as cancelled initially, then deactivates after grace period.
+     */
+    private async handleFailedRenewal(callbackData: WayForPayCallbackData): Promise<void> {
+        const { orderReference, reason, reasonCode, transactionStatus } = callbackData;
+
+        const parsedReference = parseOrderReference(orderReference);
+        if (!parsedReference) {
+            this.logger.warning({
+                message: 'Could not parse order reference for failed renewal',
+                payload: { orderReference },
+            });
+            return;
+        }
+
+        const userId = getOrderReferenceUserId(orderReference);
+        const { platform } = parsedReference;
+
+        if (!userId) {
+            this.logger.warning({
+                message: 'Could not extract userId from order reference for failed renewal',
+                payload: { orderReference },
+            });
+            return;
+        }
+
+        // Find active subscription for user
+        const existingSubscription = await this.subscriptionService.getByUser({
+            userId,
+            platform,
+            status: 'active',
+        });
+
+        if (!existingSubscription) {
+            this.logger.info({
+                message: 'No active subscription found for failed renewal check',
+                payload: { userId, platform, orderReference },
+            });
+            return;
+        }
+
+        // Check if subscription has expired past the grace period
+        const now = moment.utc();
+        const expiresAt = moment.utc(existingSubscription.expiresAt);
+        const gracePeriodMs = this.gracePeriodConfig.enabled ? this.gracePeriodConfig.durationMs : 0;
+        const gracePeriodEnd = expiresAt.clone().add(gracePeriodMs, 'milliseconds');
+
+        if (now.isAfter(gracePeriodEnd)) {
+            // Subscription has expired past grace period and renewal failed - deactivate it
+            await this.subscriptionService.deactivateSubscription({ id: existingSubscription.id });
+
+            this.logger.info({
+                message: 'Subscription deactivated due to failed renewal check (past grace period)',
+                payload: {
+                    subscriptionId: existingSubscription.id,
+                    userId,
+                    platform,
+                    orderReference,
+                    transactionStatus,
+                    reason,
+                    reasonCode,
+                    expiresAt: existingSubscription.expiresAt,
+                    gracePeriodMs,
+                    gracePeriodEnd: gracePeriodEnd.toISOString(),
+                },
+            });
+        } else if (expiresAt.isBefore(now)) {
+            // Subscription has expired but still within grace period - cancel (mark for future deactivation)
+            await this.subscriptionService.cancelSubscription({ id: existingSubscription.id });
+
+            this.logger.info({
+                message: 'Subscription cancelled due to failed renewal (within grace period)',
+                payload: {
+                    subscriptionId: existingSubscription.id,
+                    userId,
+                    platform,
+                    orderReference,
+                    expiresAt: existingSubscription.expiresAt,
+                    gracePeriodEnd: gracePeriodEnd.toISOString(),
+                    transactionStatus,
+                    reason,
+                    reasonCode,
+                },
+            });
+        } else {
+            // Subscription not yet expired - log for monitoring but don't deactivate
+            this.logger.info({
+                message: 'Failed renewal check for subscription that has not yet expired',
+                payload: {
+                    subscriptionId: existingSubscription.id,
+                    userId,
+                    platform,
+                    orderReference,
+                    expiresAt: existingSubscription.expiresAt,
+                    transactionStatus,
+                    reason,
+                    reasonCode,
+                },
+            });
+        }
+    }
+
+    /**
+     * Renews an existing subscription by extending its expiration date.
+     */
+    private async renewSubscription(
+        existingSubscription: SubscriptionEntity,
+        newExpiresAt: string,
+    ): Promise<void> {
+        // If the subscription hasn't expired yet, extend from current expiration
+        const currentExpiration = moment.utc(existingSubscription.expiresAt);
+        const now = moment.utc();
+
+        let extendedExpiresAt: string;
+        if (currentExpiration.isAfter(now)) {
+            // Extend from current expiration date
+            const durationToAdd = moment.utc(newExpiresAt).diff(moment.utc(), 'milliseconds');
+            extendedExpiresAt = currentExpiration.add(durationToAdd, 'milliseconds').toISOString();
+        } else {
+            // Subscription has expired, use the new expiration date
+            extendedExpiresAt = newExpiresAt;
+        }
+
+        await this.subscriptionService.renewSubscription({
+            userId: existingSubscription.userId,
+            platform: existingSubscription.platform,
+            expiresAt: extendedExpiresAt,
+        });
+
+        this.logger.info({
+            message: 'Subscription renewed via check webhook',
+            payload: {
+                subscriptionId: existingSubscription.id,
+                previousExpiresAt: existingSubscription.expiresAt,
+                newExpiresAt: extendedExpiresAt,
+            },
+        });
+    }
+
+    /**
+     * Calculates the subscription expiration date based on the regular mode.
+     */
+    private calculateExpirationDate(
+        regularMode: 'daily' | 'monthly' | 'yearly',
+        count: number,
+    ): string {
+        const now = moment.utc();
+
+        switch (regularMode) {
+            case 'daily':
+                return now.add(count, 'days').toISOString();
+            case 'monthly':
+                return now.add(count, 'months').toISOString();
+            case 'yearly':
+                return now.add(count, 'years').toISOString();
+            default:
+                return now.add(count, 'months').toISOString();
+        }
+    }
+}

package/src/modules/payments/subscription-check-webhook.types.ts

@@ -0,0 +1,29 @@
+import { WayForPayCallbackData, WayForPayWebhookResponse } from './wayforpay.types';
+
+/**
+ * Result of processing a subscription check webhook callback
+ */
+type SubscriptionCheckWebhookResult = {
+    success: boolean;
+    response: WayForPayWebhookResponse;
+    error?: string;
+};
+
+/**
+ * Interface for subscription check webhook handler service operations.
+ * Handles subscription status check webhooks from WayForPay.
+ */
+interface ISubscriptionCheckWebhookService {
+    /**
+     * Processes a subscription check webhook from WayForPay.
+     * Verifies signature, checks renewal status, and updates subscription accordingly.
+     *
+     * @param callbackData - The callback data from WayForPay
+     * @returns Processing result with response to send back to WayForPay
+     */
+    processSubscriptionCheckWebhook(
+        callbackData: WayForPayCallbackData,
+    ): Promise<SubscriptionCheckWebhookResult>;
+}
+
+export type { SubscriptionCheckWebhookResult, ISubscriptionCheckWebhookService };