@katorymnd/pawapay-node-sdk 2.6.1 → 2.8.0

package/CHANGELOG.md

@@ -5,32 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.1.0] - 2025-12-22
+## [2.8.0] - 2026-04-06
 
 ### Added
-- **Security Layer:** Implemented surgical JavaScript obfuscation for core API and License logic.
-- **Integrity Checker:** Added a new background process to detect if SDK files have been tampered with or modified.
-- **Server-Side Validation:** Integrated a heartbeat and domain activation system with `katorymnd.com`.
-- **Installation Imprint:** Implemented a unique installation "Soul" (TOFU - Trust On First Use) via the `.pawapay-imprint` system.
-- **Path Locking:** Added hardware and project-path fingerprinting to prevent unauthorized SDK migration between servers.
+- **Native Vault Core:** Migrated core security, licensing, and payload logic to compiled Rust binaries (`.node`).
+- **PawaPay API V2:** Full surgical integration of V2 endpoints (Deposits, Payouts, Refunds) alongside V1.
+- **Cross-Platform Support:** Added pre-compiled native support for Windows (x64), Linux (x64/arm64, glibc/musl), and macOS (Intel/Silicon).
+- **Surgical Staging:** Implemented a new `build-secure.js` pipeline that filters development backups and proprietary source files before publication.
+- **Enhanced Test Suite:** Added comprehensive Jest integration and unit tests covering the Native Vault and API logic.
 
 ### Changed
-- **Build Pipeline:** Moved production builds to a `/dist` folder strategy to ensure development secrets (like `.env`) are never published.
-- **Deployment:** Updated the publishing workflow to use `pnpm publish:secure`.
-- **License Logic:** Strict domain enforcement via `PAWAPAY_SDK_LICENSE_DOMAIN` environment variable.
+- **Security Strategy:** Replaced legacy JavaScript obfuscation with Native Machine Code protection for industry-leading IP security.
+- **Configuration Logic:** Updated `Config.js` to default to `sandbox` environment automatically if omitted.
+- **Documentation:** Rebranded the SDK as a high-performance Native Core library.
+- **Environment Handling:** Cleaned up `.env.example` to follow standard API provider patterns.
 
 ### Fixed
-- Fixed an issue where the SDK would occasionally fail to detect the environment in Docker containers.
-- Improved error messaging when a license key is missing or the domain is unauthorized.
+- **Jest Collisions:** Fixed a "Haste module naming collision" by implementing `modulePathIgnorePatterns` for the `/dist` folder.
+- **VM Stability:** Resolved an issue where background timers in the VM prevented Jest from exiting cleanly.
+- **URL Normalization:** Improved API URL normalization via native Rust string processing.
 
 ### Removed
-- Removed localhost forgiveness; all environments now require a valid domain configuration for security.
-- Removed development scripts and backup files from the final production distribution.
+- **Obfuscation:** Removed all `javascript-obfuscator` dependencies and logic.
+- **Legacy Artifacts:** Removed `opcodes.json`, `bytecode.bin`, and all `.secure.js` / `.unsecure.js` development files from the production distribution.
+
+---
+
+## [1.1.0] - 2025-12-22
+
+### Added
+- **Security Layer:** Implemented initial JavaScript protection for core API and License logic.
+- **Integrity Checker:** Added background process to detect file modifications.
+- **Installation Imprint:** Implemented unique installation "Soul" (TOFU) via the `.pawapay-imprint` system.
+
+### Changed
+- **Build Pipeline:** Moved production builds to a `/dist` folder strategy.
+- **License Logic:** Strict domain enforcement via `PAWAPAY_SDK_LICENSE_DOMAIN`.
 
 ---
 
 ## [1.0.0] - 2025-11-15
-- Initial release of the PawaPay Node.js SDK.
+- Initial release of the pawaPay Node.js SDK.
 - Core API client for mobile money deposits and payments.
-- Basic error handling and logging.
-
+- Basic error handling and logging.

package/LICENSE

@@ -1,19 +1,25 @@
 PROPRIETARY SOFTWARE LICENSE AGREEMENT
 
-Copyright (c) 2025 Katorymnd Web Solutions. All Rights Reserved.
+Copyright (c) 2026 Katorymnd Web Solutions. All Rights Reserved.
 
 NOTICE: This software is the proprietary property of Katorymnd Web Solutions. The intellectual property contained herein is protected by copyright and other intellectual property laws.
 
 1. LICENSE GRANT
-Subject to the terms of this Agreement and payment of the applicable fees, Katorymnd Web Solutions grants you a limited, non-exclusive, non-transferable, revocable license to use the PawaPay Node SDK ("Software") solely for the purpose of integrating PawaPay services into your applications.
+Subject to the terms of this Agreement and payment of the applicable fees, Katorymnd Web Solutions grants you a limited, non-exclusive, non-transferable, revocable license to use the pawaPay Node SDK ("Software"). This license is granted for use on a **single authorized domain** as specified during the purchase and activation process.
 
 2. RESTRICTIONS
 You may NOT:
-
 * Distribute, sub-license, rent, lease, or lend the Software to any third party.
-* Make the Software available to the public in any form (including open-source repositories).
-* Reverse engineer, decompile, or disassemble the Software (except strictly to the extent that such activity is expressly permitted by applicable law notwithstanding this limitation).
+* Make the Software available to the public in any form (including but not limited to public GitHub/GitLab repositories).
+* Reverse engineer, decompile, disassemble, or attempt to derive the source code from the Native Core binaries (.node files) included in the Software.
+* Bypass, modify, or defeat any license validation or integrity check mechanisms within the Software.
 * Remove or alter any copyright notices or proprietary markings on the Software.
 
-3. DISCLAIMER OF WARRANTIES
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. KATORYMND WEB SOLUTIONS DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+3. INTELLECTUAL PROPERTY
+Katorymnd Web Solutions retains all rights, title, and interest in and to the Software, including all native compiled binaries and JavaScript wrappers. This Agreement does not grant you any ownership rights to the Software.
+
+4. DISCLAIMER OF WARRANTIES
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. KATORYMND WEB SOLUTIONS DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
+5. TERMINATION
+This license is effective until terminated. Your rights under this license will terminate automatically without notice if you fail to comply with any term(s) of this Agreement, including but not limited to unauthorized domain reuse or tampering with the native core.

package/README.md

@@ -1,252 +1,136 @@
-# pawaPay Node.js SDK
-
-A professional, commercial Node.js SDK for integrating with the **pawaPay API**.
-This SDK enables seamless payment processing with **mobile money deposits, refunds, payouts**, and **real-time transaction verification**, designed for production-grade systems.
-
-> **Commercial Software**
-> This SDK is a premium product. A valid license key is required to operate it in production environments.
-
-> **Versioning Note**
-> V1 is the default main codebase. V2 has been surgically integrated and can run alongside V1, selectable through configuration without breaking existing implementations.
-
----
-
-## Folder Structure
-
-```
-example/
-data/
-src/
-tests/
-logs/
-```
-
-* **example**
-  Contains live and demo samples for each major workflow, including deposits, refunds, payouts, and configuration fetching. Both frontend and backend usage patterns are demonstrated.
-
-* **data**
-  Stores generated and cached configuration files such as `mno_availability` and `active_conf` JSON files for both V1 and V2.
-![configuration](https://katorymnd.com/tqc_images/pawapay-node-config.png)
-* **src**
-  Core SDK source code and internal architecture.
-
-* **logs**
-  Cotains logs files for  any  request - failed or successful.
-
-* **tests**
-  Automated test suites using Mocha or Jest, covering SDK logic and transaction workflows.
-
----
-
-## Available Features
-
-The pawaPay Node.js SDK provides a comprehensive, production-ready feature set with real-time validation at every stage.
-
-### Mobile Money Deposit Request
-
-![Mobile Money Deposit](https://katorymnd.com/tqc_images/pawapay-node-deposit.png)
-
-Initiate deposit requests to mobile money accounts with built-in real-time transaction verification. Each deposit is validated immediately, ensuring accurate and current status reporting.
-
----
-
-### Mobile Money Refund Request
-
-![Mobile Money Refund](https://katorymnd.com/tqc_images/pawapay-node-refund.png)
-
-Process refunds for completed deposits using the original `depositId`. Refund availability depends on your pawaPay merchant configuration, and all refund requests are verified in real time.
-
----
-
-### Mobile Money Payout Request
-
-![Mobile Money Payout](https://katorymnd.com/tqc_images/pawapay-node-payout.png)
-
-Execute payouts to single or multiple recipients within one request. This feature is optimized for bulk payments and includes real-time payout status tracking.
-
----
-
-### Real-Time Transaction Verification
-
-All operations, deposits, refunds, and payouts, are verified in real time. This ensures reliable, up-to-date transaction states without polling delays or stale responses.
-
----
-
-### Country-Specific Payment Configuration
-
-The SDK dynamically fetches supported Mobile Network Operators (MNOs) based on the country associated with your merchant account. This prevents attempts against inactive or unsupported operators.
-
----
-
-### Mobile Network Operator (MNO) Status Checks
 
-Before initiating a transaction, the SDK verifies MNO availability in real time. This minimizes failed payments caused by inactive networks.
-
----
-
-### Owner Name Notification
-
-![Owner Name Notification](https://katorymnd.com/tqc_images/pay-request-from.png)
+# pawaPay Node.js SDK
 
-Supports displaying the organization or owner name in payment notifications, helping end users easily identify payment requests.
+A professional, high-performance Node.js SDK for integrating with the **pawaPay API**. 
+This SDK provides a streamlined interface for **mobile money deposits, refunds, payouts**, and **real-time transaction verification**, built for production-grade fintech applications.
 
 ---
 
-### Deposit via Hosted Payment Page
-![Deposit via Hosted Payment Page](https://katorymnd.com/tqc_images/pawapay-node-payPage.png)
-Use the hosted payment widget to collect payments through a secure redirect flow.
+## 🏗️ Architecture
 
-1. Your application creates a payment session.
-2. pawaPay returns a `redirectUrl`.
-3. The customer completes payment on the hosted page.
-4. Upon success, the customer is redirected back to your application:
+The SDK is designed for maximum reliability and speed. It utilizes a **Native Core Integration** to handle complex cryptographic operations and data normalization, ensuring that your payment processing is both fast and secure across all supported environments.
 
-```
-deposit-page-success?depositId=951e084a-005c-4976-ad4e-205ddedb914e
+### Folder Structure
+```text
+example/          # Implementation samples and workflows
+data/             # Localized MNO & API configurations
+src/              # SDK Source code
+  ├── api/        # API Request wrappers
+  ├── core/       # Native runtime binaries
+  └── utils/      # Internal helper logic
+tests/            # Automated test suites
+scripts/          # SDK management utilities
 ```
 
-You may then activate services, store customer details, or trigger post-payment workflows as required.
-
 ---
 
-### Sandbox and Live Environments
+## 🚀 Key Features
 
-Easily switch between sandbox and production environments using environment variables. No code changes are required.
+| Feature | Description |
+| :--- | :--- |
+| **Native Performance** | Core logic is executed via optimized native bindings. |
+| **Hybrid V1/V2 Support** | Toggle between pawaPay API V1 and V2 within the same project. |
+| **MNO Intelligence** | Automatic network availability checks before payment initiation. |
+| **Enterprise Logging** | Structured logging for successful and failed transaction flows. |
+| **Platform Optimized** | Pre-compiled for Windows, Linux, and macOS (Intel & Apple Silicon). |
 
 ---
 
-## Table of Contents
-
-* [Overview](#overview)
-* [Licensing & Pricing](#licensing--pricing)
-* [Installation](#installation)
-* [Configuration (.env)](#configuration-env)
-* [Usage](#usage)
-
-  * [Initializing the SDK](#initializing-the-sdk)
-  * [MNO Configuration & Version Switching](#mno-configuration--version-switching)
-
-* [Support](#support)
-
----
-
-## Overview
-
-The pawaPay Node.js SDK integrates seamlessly with Node.js frameworks such as **Express**, **NestJS**, and **Fastify**.
-It abstracts pawaPay’s payment APIs into a clean, predictable interface focused on correctness, security, and operational clarity.
-
----
-
-## Licensing & Pricing
-
-This is a **paid commercial SDK**.
-
-* **License Model:** One-time payment
-* **Validity:** Lifetime license
-* **Scope:** One licensed domain per key
-
-To purchase a license and obtain your credentials:
-
-👉 **[https://katorymnd.com/pawapay-payment-sdk/nodejs](https://katorymnd.com/pawapay-payment-sdk/nodejs)**
+## 📦 Installation
 
-You will receive:
-
-* `KATORYMND_PAWAPAY_SDK_LICENSE_KEY`
-* `PAWAPAY_SDK_LICENSE_SECRET`
-
----
-
-## Installation
+The SDK is cross-platform and will automatically utilize the correct native components for your specific server architecture.
 
 ```bash
 npm install @katorymnd/pawapay-node-sdk
 # or
-yarn add @katorymnd/pawapay-node-sdk
+pnpm add @katorymnd/pawapay-node-sdk
 ```
 
 ---
 
-## Configuration (.env)
+## 🛠️ Configuration (.env)
 
-Create a `.env` file in your project root and configure both pawaPay API credentials and SDK licensing keys.
+Set up your project environment with your pawaPay credentials and SDK access keys.
 
 ```bash
-# ===============================
-# pawaPay API Tokens
-# ===============================
-
+# .env.example
+# Sandbox API token (for testing environment)
 PAWAPAY_SANDBOX_API_TOKEN=your_sandbox_api_token_here
+
+# Production API token (for live environment)
 PAWAPAY_PRODUCTION_API_TOKEN=your_production_api_token_here
 
-# ===============================
-# Katorymnd pawaPay SDK Licensing
-# ===============================
+# License key used by the Katorymnd PawaPay SDK
+KATORYMND_PAWAPAY_SDK_LICENSE_KEY=your_license_key_here
+
+# License domain (used for license validation)
+PAWAPAY_SDK_LICENSE_DOMAIN=your_license_domain_here
 
-KATORYMND_PAWAPAY_SDK_LICENSE_KEY=your_sdk_license_key_here
-PAWAPAY_SDK_LICENSE_DOMAIN=your-licensed-domain.com
-PAWAPAY_SDK_LICENSE_SECRET=your_sdk_license_secret_here
+# License secret (used for license validation)
+PAWAPAY_SDK_LICENSE_SECRET=your_license_secret_here
 ```
 
 ---
 
-## Usage
+## 💻 Usage
 
-### Initializing the SDK
+To begin, initialize the `ApiClient`. The SDK will perform a quick environmental check and prepare the native core for processing.
 
-Ensure the licensed domain is present in your `.env` file:
+```javascript
+const { ApiClient } = require('@katorymnd/pawapay-node-sdk');
 
-```bash
-PAWAPAY_SDK_LICENSE_DOMAIN=your-licensed-domain.com
+const client = new ApiClient({
+    apiToken: process.env.PAWAPAY_SANDBOX_API_TOKEN,
+    environment: 'sandbox', 
+    licenseKey: process.env.KATORYMND_PAWAPAY_SDK_LICENSE_KEY,
+    apiVersion: 'v2', 
+    sslVerify: false  
+});
 ```
 
-On first initialization, the SDK securely binds:
-
-* Your license key
-* Your license secret
-* Your domain
-
-This binding is permanent for that license and prevents unauthorized reuse across domains.
+### 📤 Initiating a Deposit
+```javascript
+async function handlePayment() {
+    try {
+        const response = await client.initiateDepositV2(
+            "unique-order-id-123",
+            "5000",
+            "UGX",
+            "256783456789",
+            "MTN_MOMO_UGA",
+            "Payment for Order #101"
+        );
+        
+        console.log("Response:", response.response);
+    } catch (error) {
+        console.error("API Error:", error.message);
+    }
+}
+```
 
 ---
 
-### MNO Configuration & Version Switching
-
-The SDK ships with default configuration templates. However, you are expected to maintain **up-to-date MNO and active configuration files**.
-
-* Use the example script:
-
-  ```
-  example/fetchMnoConf.js
-  ```
-* This script fetches and generates:
-
-  * `active_conf_v1.json`
-  * `mno_availability_v1.json`
-  * `active_conf_v2.json`
-  * `mno_availability_v2.json`
+## 🌍 Platform Support
 
-You may toggle **V1 or V2** behavior through these configuration files.
+The SDK includes high-performance native core support for:
+* **Windows:** x64 (msvc)
+* **Linux:** x64, arm64 (including `musl` for Docker/Alpine)
+* **macOS:** x64 (Intel), arm64 (Apple Silicon)
 
-> **Important**
-> You should configure a cron job to periodically refresh these files to ensure MNO availability and configuration data remain current.
-
-This approach keeps runtime fast, predictable, and independent of unnecessary API calls.
-
-## Support
+---
 
-For any issues, questions, or guidance:
+## 🔐 Licensing
 
-* **Documentation:** Visit the [official documentation](https://katorymnd.com/pawapay-payment-sdk/nodejs)
+This is a commercial product. The SDK is licensed per domain and requires a valid key for operation.
 
-* **Community Support:** Available with Starter and higher licenses
-* **Priority Support:** Included with Professional (6 months) and Agency (1 year) licenses
-* **Urgent Assistance:** Available as an add-on for production outages
+👉 **Get a License:** [katorymnd.com/pawapay-payment-sdk](https://katorymnd.com/pawapay-payment-sdk/nodejs)
 
-**Commercial Support:** 
-For licensed users experiencing production issues or needing implementation guidance.
+---
 
-**Contact:** [support@katorymnd.com](mailto:support@katorymnd.com)  
-_Backup:_ [katorymnd@gmail.com](mailto:katorymnd@gmail.com)
+## 🆘 Support
 
+* **Documentation:** [Official Guides](https://katorymnd.com/pawapay-payment-sdk/nodejs)
+* **Email Support:** [support@katorymnd.com](mailto:support@katorymnd.com)
+* **Gmail Support:** [katorymnd@gmail.com](mailto:katorymnd@gmail.com)
 
-----
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@katorymnd/pawapay-node-sdk",
-  "version": "2.6.1",
+  "version": "2.8.0",
   "description": "Official Premium Node.js SDK by Katorymnd Web Solutions for PawaPay mobile money API integration.",
   "main": "src/index.js",
   "exports": {
@@ -35,13 +35,18 @@
     "format:check": "prettier --check .",
     "check-master-keys": "node scripts/checkMasterKeys.js",
     "build": "pnpm check-master-keys && vite build",
-    "build:vm": "node scripts/vm-encode-bytecode.js",
-    "vm:test": "node scripts/test-vm.js",
-    "build:secure": "pnpm check-master-keys && node scripts/obfuscate.js",
-    "build:full": "pnpm clean:dist && pnpm build:vm && pnpm build:secure",
-    "test:install": "pnpm build:secure && cd dist && node scripts/install-sdk.js && echo '✅ Test Complete: Wizard ran successfully'",
+    "build:core": "napi build --release --no-js --dts false --manifest-path core-rust/Cargo.toml --output-dir ./src/core",
+    "build:secure": "pnpm check-master-keys && node scripts/build-secure.js",
+    "build:full": "pnpm clean:dist && pnpm build:secure",
+    "test:install": "pnpm build:full && cd dist && node scripts/install-sdk.js && echo '✅ Test Complete: Native Vault SDK successfully staged and verified'",
     "postinstall": "node scripts/install-sdk.js",
-    "publish:secure": "pnpm build:full && echo '🔍 Verifying Installer...' && cd dist && node scripts/install-sdk.js && echo '🧹 Cleaning Dev Artifacts...' && rimraf src/utils/vm/*.bin src/utils/vm/*.json && echo '🚀 Publishing...' && npm publish --access public"
+    "publish:secure": "pnpm build:full && echo '🔍 Verifying Installer...' && cd dist && node scripts/install-sdk.js && echo '🚀 Publishing...' && npm publish --access public"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/dist/"
+    ]
   },
   "keywords": [
     "katorymnd",
@@ -78,6 +83,7 @@
     "winston": "^3.18.3"
   },
   "devDependencies": {
+    "@napi-rs/cli": "^3.6.0",
     "bootstrap": "^5.3.3",
     "connect-livereload": "^0.6.1",
     "ejs": "^3.1.10",
@@ -85,7 +91,6 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "express": "^4.21.2",
-    "javascript-obfuscator": "^4.1.1",
     "jest": "^29.7.0",
     "livereload": "^0.10.3",
     "nodemon": "^3.1.10",
@@ -95,6 +100,16 @@
     "vite": "^7.1.12",
     "vite-plugin-ejs": "^1.7.0"
   },
+  "napi": {
+    "name": "katorymnd_pawapay_core",
+    "triples": {
+      "defaults": true,
+      "additional": [
+        "x86_64-unknown-linux-musl",
+        "aarch64-unknown-linux-musl"
+      ]
+    }
+  },
   "engines": {
     "node": ">=14.0.0",
     "pnpm": ">=8.0.0"
@@ -108,4 +123,4 @@
   "bugs": {
     "url": "https://github.com/katorymnd/pawapay-node-sdk/issues"
   }
-}
+}