@snexon/payoniq-lite 1.0.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Snexon. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# @snexon/payoniq-lite
+
+Official Node.js & TypeScript SDK for the **Payoniq (Payonic)** payment gateway by [Snexon](https://snexon.com).
+
+Integrate instant, peer-to-peer mobile payments (bKash, Nagad, Rocket, Upay) and crypto into your Node.js, Next.js, Express, or Remix applications with zero third-party gateway transaction cuts.
+
+---
+
+## Features
+
+- 🚀 **Zero Boilerplate:** Initialize in seconds with typed methods for session creation and verification.
+- 🔒 **Cryptographic Webhook Security:** Timing-safe HMAC-SHA256 signature verification with built-in replay-attack prevention.
+- 📱 **Multi-Wallet Support:** Direct integration with bKash, Nagad, Rocket, Upay & crypto gateways.
+- 📦 **Fully Typed:** 100% written in TypeScript with complete type definitions and JSDoc documentation.
+- ⚡ **Lightweight & Dependency-Free:** Zero bloated dependencies, built directly on native Node.js crypto and modern fetch.
+
+---
+
+## Installation
+
+```bash
+# Using npm
+npm install @snexon/payoniq-lite
+
+# Using pnpm
+pnpm add @snexon/payoniq-lite
+
+# Using yarn
+yarn add @snexon/payoniq-lite
+```
+
+---
+
+## Quick Start
+
+### 1. Initialize the Client
+
+```typescript
+import { PayoniqClient } from "@snexon/payoniq-lite";
+
+const payoniq = new PayoniqClient({
+  apiKey: process.env.PAYONIQ_API_KEY!,
+  apiSecret: process.env.PAYONIQ_API_SECRET!,
+  baseUrl: process.env.PAYONIQ_BASE_URL || "http://localhost:4000",
+});
+```
+
+---
+
+### 2. Create a Checkout Session
+
+#### Next.js App Router (`app/api/checkout/route.ts`)
+
+```typescript
+import { NextResponse } from "next/server";
+import { PayoniqClient } from "@snexon/payoniq-lite";
+
+const payoniq = new PayoniqClient({
+  apiKey: process.env.PAYONIQ_API_KEY!,
+  apiSecret: process.env.PAYONIQ_API_SECRET!,
+  baseUrl: process.env.PAYONIQ_BASE_URL || "http://localhost:4000",
+});
+
+export async function POST(req: Request) {
+  const { amount, orderId, customerName, customerPhone } = await req.json();
+
+  const session = await payoniq.sessions.create({
+    orderId: orderId || `ORD-${Date.now()}`,
+    amount: amount,
+    currency: "BDT",
+    method: "ANY", // "BKASH" | "NAGAD" | "ROCKET" | "UPAY" | "USDT" | "ANY"
+    customerName,
+    customerPhone,
+    successUrl: "https://yourstore.com/order/success",
+    cancelUrl: "https://yourstore.com/cart",
+    expiryMinutes: 15,
+  });
+
+  return NextResponse.json({
+    checkoutUrl: session.checkoutUrl,
+    orderHash: session.orderHash,
+  });
+}
+```
+
+#### Node.js / Express (`server.js`)
+
+```javascript
+const express = require("express");
+const { PayoniqClient } = require("@snexon/payoniq-lite");
+
+const app = express();
+app.use(express.json());
+
+const payoniq = new PayoniqClient({
+  apiKey: process.env.PAYONIQ_API_KEY,
+  apiSecret: process.env.PAYONIQ_API_SECRET,
+  baseUrl: process.env.PAYONIQ_BASE_URL || "http://localhost:4000",
+});
+
+app.post("/api/checkout", async (req, res) => {
+  try {
+    const session = await payoniq.sessions.create({
+      orderId: `ORD-${Date.now()}`,
+      amount: req.body.amount,
+      currency: "BDT",
+    });
+    res.json({ checkoutUrl: session.checkoutUrl });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.listen(3000, () => console.log("Server running on port 3000"));
+```
+
+---
+
+### 3. Verify Webhooks & Process Payments
+
+Protect your application against spoofing and replay attacks with timing-safe HMAC-SHA256 signature verification.
+
+#### Next.js Route (`app/api/webhooks/payoniq/route.ts`)
+
+```typescript
+import { NextResponse } from "next/server";
+import { PayoniqClient } from "@snexon/payoniq-lite";
+
+const payoniq = new PayoniqClient({
+  apiKey: process.env.PAYONIQ_API_KEY!,
+  apiSecret: process.env.PAYONIQ_API_SECRET!,
+});
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const signature = req.headers.get("x-payoniq-signature") || "";
+
+  try {
+    // Validates signature and verifies timestamp (rejects if older than 300s)
+    const event = payoniq.webhooks.constructEvent(rawBody, signature);
+
+    if (event.event === "payment.settled") {
+      const { orderId, amount, trxId, method } = event.data;
+      console.log(`✅ Payment settled for ${orderId}: ${amount} BDT via ${method} (TrxID: ${trxId})`);
+      
+      // Update order status in your database
+      // await markOrderAsPaid(orderId, trxId);
+    }
+
+    return NextResponse.json({ received: true });
+  } catch (err: any) {
+    return NextResponse.json(
+      { error: "Webhook verification failed", message: err.message },
+      { status: 400 }
+    );
+  }
+}
+```
+
+---
+
+## API Reference
+
+### `PayoniqClient(options)`
+- `apiKey` *(string, required)*: Merchant API key from dashboard.
+- `apiSecret` *(string, optional)*: Required for cryptographic webhook verification.
+- `baseUrl` *(string, optional)*: Payoniq daemon/server endpoint (defaults to `http://localhost:4000`).
+
+### `payoniq.sessions.create(options)`
+Creates a non-custodial checkout session.
+- `amount` *(number, required)*: Payment amount.
+- `orderId` *(string, required)*: Unique merchant order reference.
+- `currency` *(string)*: Currency code (default: `"BDT"`).
+- `method` *(string)*: `"ANY"` | `"BKASH"` | `"NAGAD"` | `"ROCKET"` | `"UPAY"` | `"USDT"`.
+- `customerName` *(string, optional)*: Customer full name.
+- `customerPhone` *(string, optional)*: Customer phone number.
+- `successUrl` *(string, optional)*: Redirect URL upon successful payment.
+- `cancelUrl` *(string, optional)*: Redirect URL if cancelled.
+- `expiryMinutes` *(number, optional)*: Session lifetime (default: 15).
+
+### `payoniq.sessions.get(orderHash)`
+Retrieves an existing payment session and live reconciliation state.
+
+### `payoniq.webhooks.constructEvent(rawBody, signatureHeader)`
+Validates the HMAC-SHA256 signature and returns typed event data. Throws `PayoniqError` if invalid or expired.
+
+---
+
+## License
+
+MIT © [Snexon](https://snexon.com)

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@snexon/payoniq-lite",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Official TypeScript & Node.js SDK for Payoniq Gateway by Snexon",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"
@@ -14,6 +16,14 @@
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/snexon/payoniq"
+  },
+  "homepage": "https://snexon.com",
+  "bugs": {
+    "url": "https://github.com/snexon/payoniq/issues"
+  },
   "keywords": [
     "payoniq",
     "payonic",