@misterhomer1992/miit-bot-payment 1.1.7 → 2.0.4

package/src/modules/payments/webhook.handler.ts

@@ -0,0 +1,219 @@
+import { Logger } from '../logger/types';
+import { WebhookHandlerService } from './webhook.service';
+import type { WayForPayCallbackData } from './wayforpay.types';
+import type { IWebhookHandlerService, WebhookProcessingResult } from './webhook.types';
+import type { TokenPackPlan } from '../token/types';
+
+/**
+ * Request object interface for webhook handling.
+ * Compatible with Express.js and similar frameworks.
+ */
+interface WebhookRequest {
+    body: unknown;
+}
+
+/**
+ * Response object interface for webhook handling.
+ * Compatible with Express.js and similar frameworks.
+ */
+interface WebhookResponse {
+    status(code: number): WebhookResponse;
+    json(data: unknown): void;
+}
+
+/**
+ * Configuration options for the webhook handler.
+ */
+interface WebhookHandlerConfig {
+    logger: Logger;
+    webhookService?: IWebhookHandlerService;
+    tokenPackPlans?: TokenPackPlan[];
+}
+
+/**
+ * Result of parsing the webhook request body.
+ */
+interface ParseResult {
+    success: boolean;
+    data?: WayForPayCallbackData;
+    error?: string;
+}
+
+/**
+ * WebhookHandler provides HTTP request handling for WayForPay payment callbacks.
+ * It validates incoming requests and delegates processing to the WebhookHandlerService.
+ *
+ * Usage with Express:
+ * ```typescript
+ * const handler = new WebhookHandler({ logger });
+ * app.post('/webhook/wayforpay', (req, res) => handler.handleRequest(req, res));
+ * ```
+ *
+ * Usage with Cloud Functions:
+ * ```typescript
+ * const handler = new WebhookHandler({ logger });
+ * export const webhookFunction = (req, res) => handler.handleRequest(req, res);
+ * ```
+ */
+export class WebhookHandler {
+    private readonly logger: Logger;
+    private readonly webhookService: IWebhookHandlerService;
+
+    constructor(config: WebhookHandlerConfig) {
+        this.logger = config.logger;
+        this.webhookService =
+            config.webhookService ||
+            new WebhookHandlerService({
+                logger: config.logger,
+                tokenPackPlans: config.tokenPackPlans,
+            });
+    }
+
+    /**
+     * Handles an incoming HTTP request from WayForPay.
+     * Validates the request body, processes the payment 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 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 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.processPaymentWebhook(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<WebhookProcessingResult> {
+        return this.webhookService.processPaymentWebhook(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
+        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: WebhookProcessingResult): 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: 'Webhook response sent',
+            payload: {
+                success: result.success,
+                status: result.response.status,
+                orderReference: result.response.orderReference,
+            },
+        });
+    }
+}
+
+/**
+ * Creates a 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 { createWebhookHandler } from 'miit-bot-payment';
+ *
+ * const logger = { info: console.log, warning: console.warn, error: console.error };
+ * export const paymentWebhook = functions.https.onRequest(createWebhookHandler({ logger }));
+ * ```
+ */
+export function createWebhookHandler(
+    config: WebhookHandlerConfig,
+): (req: WebhookRequest, res: WebhookResponse) => Promise<void> {
+    const handler = new WebhookHandler(config);
+    return (req: WebhookRequest, res: WebhookResponse) => handler.handleRequest(req, res);
+}
+
+/**
+ * Type export for the webhook handler function signature.
+ */
+export type WebhookHandlerFunction = (req: WebhookRequest, res: WebhookResponse) => Promise<void>;
+
+export type { WebhookRequest, WebhookResponse, WebhookHandlerConfig };