npm - @zyadfayed96/hpp-sdk - Versions diffs - 1.0.0 - Mend

@zyadfayed96/hpp-sdk 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,91 @@
+# HPP SDK
+Official JavaScript SDK for HPP Payment Integration.
+## Installation
+Install via npm:
+```bash
+npm install hpp-sdk
+```
+## Usage
+### 1. Import the SDK
+**Using ES Modules (React, Vue, etc.):**
+```javascript
+import { HPP } from 'hpp-sdk';
+```
+**Using CommonJS (Node.js):**
+```javascript
+const HPP = require('hpp-sdk');
+```
+**Using Script Tag (Browser):**
+```html
+<script src="path/to/node_modules/hpp-sdk/hpp-sdk.js"></script>
+<!-- OR -->
+<script src="hpp-sdk.js"></script>
+```
+### 2. Initialize and Open Payment
+```javascript
+const hpp = new HPP({
+  IDAccount: 'your-account-id',
+  PaymentIdentifier: 'payment-session-id',
+  mode: 'production', // or 'sandbox'
+  viewType: 'popup', // 'popup', 'redirect', or 'embed'
+  // Callback for success
+  onSuccess: (data) => {
+    console.log('Payment Successful:', data);
+  },
+  // Callback for error
+  onError: (error) => {
+    console.error('Payment Failed:', error);
+  },
+  // Callback for dialog close (popup mode only)
+  onClose: () => {
+    console.log('Payment dialog closed');
+  }
+});
+// Open the payment interface
+hpp.open();
+```
+### 3. Handle Callback (For Redirect Mode)
+If you use `viewType: 'redirect'`, you need to host a callback page (e.g., `hpp-callback.html`) to handle the user returning from the payment gateway.
+1.  Create a file named `hpp-callback.html` on your server.
+2.  Copy the content from the example `hpp-callback.html` provided in this package (or implement your own logic).
+3.  The callback page should parse the URL parameters and communicate back to your main application or display the result.
+## Configuration Options
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `IDAccount` | String | Yes | Your Merchant Account ID. |
+| `PaymentIdentifier` | String | Yes | Unique identifier for the payment session. |
+| `mode` | String | Yes | Environment: `'production'` or `'sandbox'`. |
+| `viewType` | String | No | `'popup'` (default), `'redirect'`, or `'embed'`. |
+| `openInDialog` | Boolean | No | Legacy option for popup mode (default: `true`). |
+| `dialogWidth` | Number | No | Width of the popup window (default: `1000`). |
+| `dialogHeight` | Number | No | Height of the popup window (default: `700`). |
+| `onSuccess` | Function | No | Callback when payment is successful. |
+| `onError` | Function | No | Callback when payment fails. |
+| `onClose` | Function | No | Callback when the popup is closed by the user. |
+## License
+ISC

package/hpp-callback.html ADDED Viewed

@@ -0,0 +1,315 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Payment Processing...</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: linear-gradient(135deg, #FEFEFE 0%, #EEEEEE 100%);
+            min-height: 100vh;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            padding: 20px;
+        }
+        .container {
+            background: white;
+            border-radius: 12px;
+            box-shadow: 0 10px 30px rgba(0, 0, 0, 0.3);
+            padding: 40px;
+            max-width: 500px;
+            width: 100%;
+            text-align: center;
+        }
+        .spinner {
+            border: 4px solid #f0f0f0;
+            border-top: 4px solid #667eea;
+            border-radius: 50%;
+            width: 50px;
+            height: 50px;
+            animation: spin 1s linear infinite;
+            margin: 0 auto 20px;
+        }
+        @keyframes spin {
+            0% { transform: rotate(0deg); }
+            100% { transform: rotate(360deg); }
+        }
+        h1 {
+            color: #333;
+            margin-bottom: 10px;
+            font-size: 24px;
+        }
+        p {
+            color: #666;
+            margin-bottom: 10px;
+        }
+        .result-section {
+            display: none;
+            margin-top: 30px;
+            padding-top: 20px;
+            border-top: 2px solid #f0f0f0;
+        }
+        .result-section.show {
+            display: block;
+        }
+        .success {
+            color: #155724;
+            background: #d4edda;
+            border: 1px solid #c3e6cb;
+            padding: 15px;
+            border-radius: 6px;
+            margin-bottom: 15px;
+        }
+        .error {
+            color: #721c24;
+            background: #f8d7da;
+            border: 1px solid #f5c6cb;
+            padding: 15px;
+            border-radius: 6px;
+            margin-bottom: 15px;
+        }
+        .data-display {
+            background: #f8f9fa;
+            padding: 15px;
+            border-radius: 6px;
+            font-family: 'Courier New', monospace;
+            font-size: 12px;
+            text-align: left;
+            overflow-x: auto;
+            max-height: 300px;
+            overflow-y: auto;
+            margin-bottom: 15px;
+        }
+        .button-group {
+            display: flex;
+            gap: 10px;
+            justify-content: center;
+        }
+        button {
+            padding: 10px 20px;
+            border: none;
+            border-radius: 6px;
+            font-weight: 600;
+            cursor: pointer;
+            transition: all 0.3s;
+        }
+        .btn-primary {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+        }
+        .btn-primary:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 10px 25px rgba(102, 126, 234, 0.4);
+        }
+        .btn-secondary {
+            background: #f0f0f0;
+            color: #333;
+        }
+        .btn-secondary:hover {
+            background: #e0e0e0;
+        }
+        .loading-text {
+            color: #666;
+            font-size: 14px;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div id="processingSection" class="processing-section">
+            <div class="spinner"></div>
+            <h1>Processing Payment</h1>
+            <p class="loading-text">Please wait while we process your payment...</p>
+        </div>
+        <div id="resultSection" class="result-section">
+            <h1 id="resultTitle">Payment Status</h1>
+            <div id="resultMessage" class="success"></div>
+            <div id="resultData" class="data-display" style="display: none;"></div>
+            <div class="button-group">
+                <button class="btn-primary" id="backBtn">← Back to Payment Form</button>
+                <button class="btn-secondary" id="closeBtn">Close</button>
+            </div>
+        </div>
+    </div>
+    <script>
+        let paymentResult = null
+        // Get URL parameters
+        function getURLParams() {
+            const params = new URLSearchParams(window.location.search)
+            return {
+                status: params.get('status'),
+                message: params.get('message'),
+                reference: params.get('reference'),
+                amount: params.get('amount'),
+                code: params.get('code'),
+                data: params.get('data')
+            }
+        }
+        // Parse result from URL
+        function parsePaymentResult() {
+            const params = getURLParams()
+            if (params.status === 'success') {
+                return {
+                    status: 'success',
+                    reference: params.reference,
+                    amount: params.amount,
+                    message: params.message || 'Payment successful!'
+                }
+            } else if (params.status === 'reference_code') {
+                // Handle reference code payment
+                return {
+                    status: 'success',
+                    reference: params.reference,
+                    amount: params.amount,
+                    message: 'Reference Code Generated Successfully!'
+                }
+            } else if (params.status === 'error') {
+                // Handle error status
+                return {
+                    status: 'error',
+                    code: params.code,
+                    message: params.message || 'Payment failed'
+                }
+            } else if (params.code) {
+                // Fallback for code-based error detection
+                return {
+                    status: 'error',
+                    code: params.code,
+                    message: params.message || 'Payment failed'
+                }
+            } else if (params.data) {
+                try {
+                    return JSON.parse(decodeURIComponent(params.data))
+                } catch (e) {
+                    return {
+                        status: 'pending',
+                        message: 'Payment is being processed'
+                    }
+                }
+            }
+            return null
+        }
+        // Display result
+        function displayResult(result) {
+            const resultSection = document.getElementById('resultSection')
+            const resultTitle = document.getElementById('resultTitle')
+            const resultMessage = document.getElementById('resultMessage')
+            const resultData = document.getElementById('resultData')
+            const processingSection = document.getElementById('processingSection')
+            processingSection.style.display = 'none'
+            if (result.status === 'success') {
+                resultTitle.textContent = '✅ Payment Successful'
+                resultMessage.className = 'success'
+                resultMessage.innerHTML = `
+                    <strong>${result.message}</strong>
+                    ${result.reference ? `<br>Reference: ${result.reference}` : ''}
+                    ${result.amount ? `<br>Amount: ${result.amount}` : ''}
+                `
+            } else if (result.status === 'error') {
+                resultTitle.textContent = '❌ Payment Failed'
+                resultMessage.className = 'error'
+                resultMessage.innerHTML = `
+                    <strong>${result.message}</strong>
+                    ${result.code ? `<br>Error Code: ${result.code}` : ''}
+                `
+            } else {
+                resultTitle.textContent = '⏳ Payment Pending'
+                resultMessage.className = 'success'
+                resultMessage.textContent = result.message || 'Payment is being processed. Please check your email for updates.'
+            }
+            // Show data if available
+            if (Object.keys(result).length > 2) {
+                resultData.style.display = 'block'
+                resultData.textContent = JSON.stringify(result, null, 2)
+            }
+            resultSection.classList.add('show')
+            // Send result to opener (if opened from popup)
+            sendToOpener(result)
+        }
+        // Send result back to opener window
+        function sendToOpener(result) {
+            if (window.opener && !window.opener.closed) {
+                const message = {
+                    type: 'hpp-callback-result',
+                    data: result
+                }
+                window.opener.postMessage(message, '*')
+            }
+        }
+        // Go back to payment form
+        document.getElementById('backBtn').addEventListener('click', () => {
+            window.history.back()
+        })
+        // Close window
+        document.getElementById('closeBtn').addEventListener('click', () => {
+            if (window.opener) {
+                window.close()
+            } else {
+                window.history.back()
+            }
+        })
+        // Initialize
+        window.addEventListener('load', () => {
+            paymentResult = parsePaymentResult()
+            if (paymentResult) {
+                displayResult(paymentResult)
+            } else {
+                // No result found, wait a bit then show error
+                setTimeout(() => {
+                    const errorMsg = document.getElementById('resultMessage')
+                    errorMsg.className = 'error'
+                    errorMsg.textContent = 'Unable to retrieve payment result. Please contact support.'
+                    document.getElementById('resultSection').classList.add('show')
+                    document.getElementById('processingSection').style.display = 'none'
+                }, 2000)
+            }
+        })
+        // Log callback
+        console.log('%c📋 HPP Callback Page', 'font-size: 16px; font-weight: bold; color: #667eea;')
+        console.log('Waiting for payment result...')
+    </script>
+</body>
+</html>

package/hpp-sdk.js ADDED Viewed

@@ -0,0 +1,341 @@
+/**
+ * HPP SDK - JavaScript Version (Compiled)
+ *
+ * Ready-to-use JavaScript file for browser and Node.js environments
+ *
+ * Usage:
+ * ```html
+ * <script src="hpp-sdk.js"></script>
+ * <script>
+ *   const hpp = new HPP({
+ *     IDAccount: 'your-account-id',
+ *     PaymentIdentifier: 'payment-123',
+ *     mode: 'production',
+ *     onSuccess: (data) => console.log('Success:', data),
+ *     onError: (error) => console.error('Error:', error)
+ *   })
+ *   hpp.open()
+ * </script>
+ * ```
+ *
+ * Or in modules:
+ * ```javascript
+ * import { HPP } from './hpp-sdk.js'
+ * const hpp = new HPP({...})
+ * ```
+ */
+// ============================================================================
+// HPP Communication Utility
+// ============================================================================
+class HPPCommunication {
+  /**
+   * Check if running in SDK mode (opened from parent window)
+   */
+  static isSDKMode() {
+    return window.opener !== null && window.opener !== undefined
+  }
+  /**
+   * Send payment success status to parent window
+   */
+  static sendSuccess(data) {
+    if (!this.isSDKMode()) return
+    const message = {
+      type: 'hpp-status',
+      data: data,
+    }
+    window.opener?.postMessage(message, '*')
+  }
+  /**
+   * Send payment error status to parent window
+   */
+  static sendError(error) {
+    if (!this.isSDKMode()) return
+    const message = {
+      type: 'hpp-status',
+      data: error,
+    }
+    window.opener?.postMessage(message, '*')
+  }
+  /**
+   * Notify parent that HPP is ready
+   */
+  static sendReady() {
+    if (!this.isSDKMode()) return
+    const message = {
+      type: 'hpp-ready',
+    }
+    window.opener?.postMessage(message, '*')
+  }
+  /**
+   * Send close signal to parent window
+   */
+  static sendClose() {
+    if (!this.isSDKMode()) return
+    const message = {
+      type: 'hpp-close',
+    }
+    window.opener?.postMessage(message, '*')
+  }
+  /**
+   * Close the HPP window and notify parent
+   */
+  static closeHPP() {
+    this.sendClose()
+    window.close()
+  }
+}
+// ============================================================================
+// HPP Main Class
+// ============================================================================
+class HPP {
+  constructor(config) {
+    // Validate required fields
+    if (!config.IDAccount || !config.PaymentIdentifier || !config.mode) {
+      throw new Error(
+        'HPP SDK: Missing required config parameters (IDAccount, PaymentIdentifier, mode)',
+      )
+    }
+    this.config = {
+      openInDialog: true,
+      dialogWidth: 1000,
+      dialogHeight: 700,
+      ...config,
+    }
+    this.dialogWindow = null
+    this.isDialogOpen = false
+    this.messageHandler = null
+  }
+  /**
+   * Open the HPP payment interface
+   */
+  open() {
+    if (this.isDialogOpen) {
+      console.warn('HPP: Dialog is already open')
+      return
+    }
+    const { openInDialog } = this.config
+    if (openInDialog) {
+      this.openDialog()
+    } else {
+      this.openPage()
+    }
+  }
+  /**
+   * Open HPP in a dialog/modal window
+   */
+  openDialog() {
+    const url = this.buildHppUrl()
+    const width = typeof this.config.dialogWidth === 'number' ? this.config.dialogWidth : 1000
+    const height = typeof this.config.dialogHeight === 'number' ? this.config.dialogHeight : 700
+    // Center the dialog
+    const left = window.screenLeft + (window.outerWidth - width) / 2
+    const top = window.screenTop + (window.outerHeight - height) / 2
+    const windowFeatures = `width=${width},height=${height},left=${left},top=${top},resizable=yes,scrollbars=yes`
+    this.dialogWindow = window.open(url, 'hpp-dialog', windowFeatures)
+    if (!this.dialogWindow) {
+      console.error('HPP: Failed to open dialog. Popup blocker may be active.')
+      if (this.config.onError) {
+        this.config.onError({
+          code: 'DIALOG_OPEN_FAILED',
+          message: 'Failed to open payment dialog. Please check if popups are blocked.',
+        })
+      }
+      return
+    }
+    this.isDialogOpen = true
+    this.setupMessageListener()
+    // Check if window is closed periodically
+    const checkInterval = setInterval(() => {
+      if (!this.dialogWindow || this.dialogWindow.closed) {
+        clearInterval(checkInterval)
+        this.isDialogOpen = false
+        this.cleanup()
+        if (this.config.onClose) {
+          this.config.onClose()
+        }
+      }
+    }, 500)
+  }
+  /**
+   * Open HPP in a full page (redirect)
+   */
+  openPage() {
+    const url = this.buildHppUrl()
+    window.location.href = url
+  }
+  /**
+   * Build the HPP URL with all parameters
+   */
+  buildHppUrl() {
+    const { baseUrl, IDAccount, PaymentIdentifier, CustomerRequestID, mode, viewType } = this.config
+    let url = `${baseUrl}/hpp/${IDAccount}/${PaymentIdentifier}`
+    if (CustomerRequestID) {
+      url += `/${CustomerRequestID}`
+    }
+    // Add query parameters
+    const params = new URLSearchParams({
+      Mode: mode,
+      sdk: 'true', // Indicate that HPP is opened via SDK
+    })
+    // Add viewType if provided
+    if (viewType) {
+      params.append('viewType', viewType)
+    }
+    return `${url}?${params.toString()}`
+  }
+  /**
+   * Setup message listener for postMessage communication
+   */
+  setupMessageListener() {
+    if (this.messageHandler) {
+      window.removeEventListener('message', this.messageHandler)
+    }
+    this.messageHandler = (event) => {
+      // Verify message format
+      const message = event.data
+      if (typeof message !== 'object' || !message.type || !message.type.startsWith('hpp-')) {
+        return
+      }
+      switch (message.type) {
+        case 'hpp-status':
+          this.handlePaymentStatus(message.data)
+          break
+        case 'hpp-ready':
+          // HPP is ready, can be used for additional setup
+          break
+        case 'hpp-close':
+          this.close()
+          break
+      }
+    }
+    window.addEventListener('message', this.messageHandler)
+  }
+  /**
+   * Handle payment status from HPP
+   */
+  handlePaymentStatus(data) {
+    if (
+      data.status === 'success' ||
+      data.status === 'pending' ||
+      data.status === 'reference_code'
+    ) {
+      if (this.config.onSuccess) {
+        this.config.onSuccess(data)
+      }
+    } else if (data.code) {
+      // It's an error response
+      if (this.config.onError) {
+        this.config.onError(data)
+      }
+    }
+  }
+  /**
+   * Close the dialog/window
+   */
+  close() {
+    if (this.dialogWindow && !this.dialogWindow.closed) {
+      this.dialogWindow.close()
+    }
+    this.isDialogOpen = false
+    this.cleanup()
+  }
+  /**
+   * Check if dialog is open
+   */
+  isOpen() {
+    return this.isDialogOpen && this.dialogWindow !== null && !this.dialogWindow.closed
+  }
+  /**
+   * Get dialog window reference
+   */
+  get window() {
+    return this.dialogWindow
+  }
+  /**
+   * Cleanup resources
+   */
+  cleanup() {
+    if (this.messageHandler) {
+      window.removeEventListener('message', this.messageHandler)
+      this.messageHandler = null
+    }
+  }
+  /**
+   * Destructor to clean up resources
+   */
+  destroy() {
+    this.close()
+    this.cleanup()
+  }
+}
+// ============================================================================
+// Exports
+// ============================================================================
+// For browser global (script tag usage)
+if (typeof window !== 'undefined') {
+  window.HPP = HPP
+  window.HPPCommunication = HPPCommunication
+}
+// For CommonJS (if loaded as module)
+if (typeof module !== 'undefined' && typeof module.exports !== 'undefined') {
+  module.exports = HPP
+  module.exports.HPP = HPP
+  module.exports.HPPCommunication = HPPCommunication
+  module.exports.default = HPP
+}
+// For ES6 modules (comment out export statements for script tag compatibility)
+// export { HPP, HPPCommunication }
+// export default HPP

package/index.d.ts ADDED Viewed

@@ -0,0 +1,35 @@
+declare module 'hpp-sdk' {
+  export interface HPPConfig {
+    IDAccount: string;
+    PaymentIdentifier: string;
+    mode: 'production' | 'sandbox';
+    viewType?: 'popup' | 'redirect' | 'embed';
+    openInDialog?: boolean;
+    dialogWidth?: number;
+    dialogHeight?: number;
+    CustomerRequestID?: string;
+    onSuccess?: (data: any) => void;
+    onError?: (error: any) => void;
+    onClose?: () => void;
+  }
+  export class HPP {
+    constructor(config: HPPConfig);
+    open(): void;
+    openDialog(): void;
+    openPage(): void;
+    close(): void;
+    destroy(): void;
+  }
+  export class HPPCommunication {
+    static isSDKMode(): boolean;
+    static sendSuccess(data: any): void;
+    static sendError(error: any): void;
+    static sendReady(): void;
+    static sendClose(): void;
+    static closeHPP(): void;
+  }
+  export default HPP;
+}

package/package.json ADDED Viewed

@@ -0,0 +1,17 @@
+{
+  "name": "@zyadfayed96/hpp-sdk",
+  "version": "1.0.0",
+  "description": "HPP Payment SDK for JavaScript",
+  "main": "hpp-sdk.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "hpp",
+    "payment",
+    "sdk"
+  ],
+  "author": "",
+  "license": "ISC"
+}