pec-payment-sdk 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alireza
+
+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.fa.md

@@ -0,0 +1,212 @@
+# pec-payment-sdk
+
+[![npm version](https://img.shields.io/npm/v/pec-payment-sdk?logo=npm&logoColor=white)](https://www.npmjs.com/package/pec-payment-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/pec-payment-sdk?logo=npm&logoColor=white&label=downloads)](https://www.npmjs.com/package/pec-payment-sdk)
+[![GitHub stars](https://img.shields.io/github/stars/AlirezaMoVali/pec-sdk?style=flat&logo=github)](https://github.com/AlirezaMoVali/pec-sdk/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/AlirezaMoVali/pec-sdk?style=flat&logo=github)](https://github.com/AlirezaMoVali/pec-sdk/issues)
+[![GitHub license](https://img.shields.io/github/license/AlirezaMoVali/pec-sdk?style=flat)](https://github.com/AlirezaMoVali/pec-sdk/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4+-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+[English](./README.md) | **فارسی**
+
+SDK نوشته‌شده با TypeScript/JavaScript برای درگاه پرداخت **PEC** (تجارت الکترونیک پارسیان). با Node.js، Express، Fastify، NestJS، Next.js و هر پروژه CommonJS یا ESM سازگار است.
+
+این کتابخانه بر پایه سرویس‌های SOAP رسمی PEC (همان endpointهای نمونه PHP بانک) با API تایپ‌شده و helperهای آماده برای توسعه‌دهندگان ساخته شده است.
+
+## امکانات
+
+- جریان استاندارد خرید، تایید و برگشت تراکنش
+- پرداخت با تسهیم آنلاین
+- پرداخت با شناسه حساب دولتی و تسهیم چند حسابی دولتی
+- پرداخت قبض و استعلام قبض
+- خرید شارژ موبایل
+- گزارش تراکنش‌های فروش (REST API)
+- **تبدیل ریال / تومان** (SDK مبلغ را به ریال برای بانک ارسال می‌کند)
+- پشتیبانی از **CommonJS** (`require`) و **ESM** (`import`)
+- تایپ‌های کامل TypeScript
+
+## پیش‌نیاز
+
+- Node.js **۱۸ به بالا**
+
+## نصب
+
+```bash
+npm install pec-payment-sdk
+```
+
+## شروع سریع
+
+### ESM / TypeScript
+
+```typescript
+import {
+  PecClient,
+  generateOrderId,
+  parseCallback,
+  shouldConfirmPayment,
+  isSuccessStatus,
+} from 'pec-payment-sdk';
+
+const client = new PecClient({
+  loginAccount: process.env.PEC_LOGIN_ACCOUNT!,
+  callbackUrl: 'https://your-shop.com/payment/callback',
+});
+
+const sale = await client.requestPayment({
+  amount: 50000,
+  currency: 'toman', // پیش‌فرض؛ SDK مبلغ ۵۰۰٬۰۰۰ ریال به PEC می‌فرستد
+  orderId: generateOrderId(),
+});
+
+if (sale.paymentUrl) {
+  // کاربر را به صفحه پرداخت بانک هدایت کنید
+  res.redirect(sale.paymentUrl);
+}
+```
+
+### CommonJS
+
+```javascript
+const {
+  PecClient,
+  generateOrderId,
+  parseCallback,
+  shouldConfirmPayment,
+} = require('pec-payment-sdk');
+
+const client = new PecClient({
+  loginAccount: process.env.PEC_LOGIN_ACCOUNT,
+  callbackUrl: 'https://your-shop.com/payment/callback',
+});
+```
+
+## فرآیند پرداخت
+
+```
+۱. سرور شما     →  client.requestPayment()
+۲. هدایت کاربر  →  sale.paymentUrl (درگاه PEC)
+۳. پرداخت کاربر →  بانک به callbackUrl شما redirect می‌کند
+۴. سرور شما     →  parseCallback() + client.confirmPayment()
+```
+
+### هندلر callback (مثال Express)
+
+پس از پرداخت، PEC با **POST** به آدرس callback شما فیلدهایی مثل `Token`، `status`، `OrderId`، `RRN`، `Amount` و `TerminalNo` ارسال می‌کند. مقدار `req.body` را به `parseCallback()` بدهید. اگر route شما query می‌خواند، ابتدا آن را با body ادغام کنید.
+
+آدرس callback می‌تواند برای توسعه محلی **HTTP** (مثل `http://localhost`) یا در production **HTTPS** باشد.
+
+```typescript
+app.post('/payment/callback', async (req, res) => {
+  const callback = parseCallback(req.body);
+
+  if (!shouldConfirmPayment(callback)) {
+    return res.redirect('/payment/failed');
+  }
+
+  const result = await client.confirmPayment({ token: callback.token });
+
+  if (isSuccessStatus(result.status)) {
+    return res.redirect(`/payment/success?rrn=${result.rrn}`);
+  }
+
+  res.redirect('/payment/failed');
+});
+```
+
+## واحد پول (ریال / تومان)
+
+PEC مبلغ را به **ریال** می‌پذیرد. مبلغ را با واحدی که در اپلیکیشن استفاده می‌کنید بفرستید:
+
+| `currency` | مقدار ورودی | ارسال به PEC |
+|------------|-------------|--------------|
+| `'toman'` (پیش‌فرض) | `50000` | `500000` ریال |
+| `'rial'` | `500000` | `500000` ریال |
+
+```typescript
+import { toRials } from 'pec-payment-sdk';
+
+toRials(50000, 'toman'); // 500000
+toRials(500000, 'rial'); // 500000
+```
+
+در **پرداخت تسهیمی**، مبلغ هر حساب (`accounts[].amount`) با همان `currency` درخواست اصلی به ریال تبدیل می‌شود.
+
+## مرجع API
+
+### ساخت کلاینت
+
+```typescript
+const client = new PecClient({
+  loginAccount: string;  // PIN پذیرنده (LoginAccount)
+  callbackUrl?: string;  // آدرس callback پیش‌فرض
+});
+```
+
+### متدهای پرداخت
+
+| متد | توضیح |
+|-----|--------|
+| `requestPayment()` | خرید استاندارد کالا و خدمات |
+| `requestMultiplexedPayment()` | پرداخت با تسهیم آنلاین (چند شبا) |
+| `requestGovernmentPayment()` | پرداخت با شناسه حساب دولتی |
+| `requestGovernmentMultiplexedPayment()` | پرداخت دولتی با تسهیم چند حسابی |
+| `requestBillPayment()` | پرداخت قبض |
+| `getBillInfo()` | استعلام قبض قبل از پرداخت |
+| `requestMobileTopup()` | خرید شارژ موبایل |
+| `confirmPayment()` | تایید (تسویه) تراکنش موفق |
+| `reversePayment()` | برگشت تراکنش (در بازه زمانی مجاز بانک) |
+| `getSaleReport()` | دریافت گزارش تراکنش‌ها (REST API) |
+
+### توابع کمکی
+
+| Export | توضیح |
+|--------|--------|
+| `generateOrderId()` | تولید شماره سفارش یکتا |
+| `getPaymentPageUrl(token)` | ساخت URL هدایت به درگاه |
+| `parseCallback(body)` | پارس بدنه POST بازگشتی از بانک |
+| `shouldConfirmPayment(callback)` | بررسی آماده بودن callback برای confirm |
+| `isSuccessStatus(status)` | `true` وقتی status برابر `0` باشد |
+| `isValidUrl(url)` | اعتبارسنجی آدرس callback با HTTP/HTTPS |
+| `toRials(amount, currency)` | تبدیل مبلغ به ریال |
+| `validateAmount(amount)` | خطا در صورت مبلغ نامعتبر |
+| `validateSaleReportDateRange(from, to)` | محدودیت بازه ۳۰ روزه گزارش |
+
+### خطاها
+
+| کلاس | زمان رخداد |
+|------|-----------|
+| `PecValidationError` | ورودی نامعتبر (مثلاً callback خالی) |
+| `PecTransportError` | خطای شبکه یا SOAP |
+| `PecError` | خطای عمومی مرتبط با PEC |
+
+## CommonJS و ESM
+
+در هر دو سبک از یک نام پکیج استفاده کنید — Node و bundlerها به‌صورت خودکار build مناسب را انتخاب می‌کنند:
+
+```javascript
+// CommonJS
+const { PecClient } = require('pec-payment-sdk');
+```
+
+```typescript
+// ESM
+import { PecClient } from 'pec-payment-sdk';
+```
+
+## متغیرهای محیطی (پیشنهادی)
+
+```env
+PEC_LOGIN_ACCOUNT=your_merchant_pin
+```
+
+PIN پذیرنده را commit نکنید. از متغیر محیطی یا secrets manager استفاده کنید.
+
+## لینک‌ها
+
+- [مخزن GitHub](https://github.com/AlirezaMoVali/pec-sdk)
+- [مستندات درگاه PEC / پارسیان](https://pgw.pec.ir/)
+
+## مجوز
+
+[MIT](./LICENSE) © Alireza Mohammadvali

package/README.md

@@ -0,0 +1,212 @@
+# pec-payment-sdk
+
+[![npm version](https://img.shields.io/npm/v/pec-payment-sdk?logo=npm&logoColor=white)](https://www.npmjs.com/package/pec-payment-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/pec-payment-sdk?logo=npm&logoColor=white&label=downloads)](https://www.npmjs.com/package/pec-payment-sdk)
+[![GitHub stars](https://img.shields.io/github/stars/AlirezaMoVali/pec-sdk?style=flat&logo=github)](https://github.com/AlirezaMoVali/pec-sdk/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/AlirezaMoVali/pec-sdk?style=flat&logo=github)](https://github.com/AlirezaMoVali/pec-sdk/issues)
+[![GitHub license](https://img.shields.io/github/license/AlirezaMoVali/pec-sdk?style=flat)](https://github.com/AlirezaMoVali/pec-sdk/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4+-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+**English** | [فارسی](./README.fa.md)
+
+TypeScript/JavaScript SDK for **PEC** (Parsian Electronic Commerce / تجارت الکترونیک پارسیان) payment gateway. Works with Node.js, Express, Fastify, NestJS, Next.js, and any CommonJS or ESM project.
+
+Built on official PEC SOAP services (same endpoints as the bank’s PHP samples) with typed APIs and developer-friendly helpers.
+
+## Features
+
+- Standard sale, confirm, and reverse flows
+- Online multiplexed payments (تسهیم آنلاین)
+- Government ID payments and government multiplexed payments
+- Bill payment and bill inquiry
+- Mobile top-up
+- Sale transaction reporting (REST API)
+- **Rial / Toman** amount handling
+- **CommonJS** (`require`) and **ESM** (`import`) support
+- Full TypeScript types
+
+## Requirements
+
+- Node.js **18+**
+
+## Installation
+
+```bash
+npm install pec-payment-sdk
+```
+
+## Quick start
+
+### ESM / TypeScript
+
+```typescript
+import {
+  PecClient,
+  generateOrderId,
+  parseCallback,
+  shouldConfirmPayment,
+  isSuccessStatus,
+} from 'pec-payment-sdk';
+
+const client = new PecClient({
+  loginAccount: process.env.PEC_LOGIN_ACCOUNT!,
+  callbackUrl: 'https://your-shop.com/payment/callback',
+});
+
+const sale = await client.requestPayment({
+  amount: 50000,
+  currency: 'toman', // default; SDK sends 500,000 Rials to PEC
+  orderId: generateOrderId(),
+});
+
+if (sale.paymentUrl) {
+  // Redirect the customer to the bank payment page
+  res.redirect(sale.paymentUrl);
+}
+```
+
+### CommonJS
+
+```javascript
+const {
+  PecClient,
+  generateOrderId,
+  parseCallback,
+  shouldConfirmPayment,
+} = require('pec-payment-sdk');
+
+const client = new PecClient({
+  loginAccount: process.env.PEC_LOGIN_ACCOUNT,
+  callbackUrl: 'https://your-shop.com/payment/callback',
+});
+```
+
+## Payment flow
+
+```
+1. Your server  →  client.requestPayment()
+2. Redirect user →  sale.paymentUrl (PEC gateway)
+3. User pays     →  Bank redirects to your callbackUrl
+4. Your server   →  parseCallback() + client.confirmPayment()
+```
+
+### Callback handler (Express example)
+
+After payment, PEC **POSTs** to your callback URL with fields such as `Token`, `status`, `OrderId`, `RRN`, `Amount`, and `TerminalNo`. Pass `req.body` to `parseCallback()`. If your route reads query parameters instead, merge them into one object first.
+
+Callback URLs may use **HTTP** (e.g. `http://localhost`) for local development or **HTTPS** in production.
+
+```typescript
+app.post('/payment/callback', async (req, res) => {
+  const callback = parseCallback(req.body);
+
+  if (!shouldConfirmPayment(callback)) {
+    return res.redirect('/payment/failed');
+  }
+
+  const result = await client.confirmPayment({ token: callback.token });
+
+  if (isSuccessStatus(result.status)) {
+    return res.redirect(`/payment/success?rrn=${result.rrn}`);
+  }
+
+  res.redirect('/payment/failed');
+});
+```
+
+## Currency
+
+PEC expects amounts in **Rials**. Pass the amount in the unit your app uses:
+
+| `currency` | You pass | Sent to PEC |
+|------------|----------|-------------|
+| `'toman'` (default) | `50000` | `500000` Rials |
+| `'rial'` | `500000` | `500000` Rials |
+
+```typescript
+import { toRials } from 'pec-payment-sdk';
+
+toRials(50000, 'toman'); // 500000
+toRials(500000, 'rial'); // 500000
+```
+
+For **multiplexed payments**, each account `amount` uses the same `currency` as the main request.
+
+## API reference
+
+### Client
+
+```typescript
+const client = new PecClient({
+  loginAccount: string;  // Merchant PIN (LoginAccount)
+  callbackUrl?: string;  // Default callback if omitted per request
+});
+```
+
+### Payment methods
+
+| Method | Description |
+|--------|-------------|
+| `requestPayment()` | Standard sale / goods & services |
+| `requestMultiplexedPayment()` | Online split payment across IBAN accounts |
+| `requestGovernmentPayment()` | Payment with government account ID |
+| `requestGovernmentMultiplexedPayment()` | Government payment with split accounts |
+| `requestBillPayment()` | Bill payment |
+| `getBillInfo()` | Bill inquiry before payment |
+| `requestMobileTopup()` | Mobile charge / top-up |
+| `confirmPayment()` | Confirm (settle) a successful payment |
+| `reversePayment()` | Reverse a payment (within bank time limit) |
+| `getSaleReport()` | Fetch transactions via PEC reporting REST API |
+
+### Utilities
+
+| Export | Description |
+|--------|-------------|
+| `generateOrderId()` | Generate a unique order ID |
+| `getPaymentPageUrl(token)` | Build PEC redirect URL |
+| `parseCallback(body)` | Parse bank callback POST body |
+| `shouldConfirmPayment(callback)` | Check if callback is OK to confirm |
+| `isSuccessStatus(status)` | `true` when PEC status is `0` |
+| `isValidUrl(url)` | Validate HTTP/HTTPS callback URL |
+| `toRials(amount, currency)` | Convert amount to Rials |
+| `validateAmount(amount)` | Throw if amount is invalid |
+| `validateSaleReportDateRange(from, to)` | Enforce max 30-day report window |
+
+### Errors
+
+| Class | When |
+|-------|------|
+| `PecValidationError` | Invalid input (e.g. missing callback URL) |
+| `PecTransportError` | Network or SOAP failure |
+| `PecError` | General PEC-related error |
+
+## Module formats
+
+Use the same package name in both styles — Node and bundlers pick the right build automatically:
+
+```javascript
+// CommonJS
+const { PecClient } = require('pec-payment-sdk');
+```
+
+```typescript
+// ESM
+import { PecClient } from 'pec-payment-sdk';
+```
+
+## Environment variables (recommended)
+
+```env
+PEC_LOGIN_ACCOUNT=your_merchant_pin
+```
+
+Never commit your merchant PIN. Use environment variables or a secrets manager.
+
+## Links
+
+- [GitHub repository](https://github.com/AlirezaMoVali/pec-sdk)
+- [PEC / Parsian gateway documentation](https://pgw.pec.ir/)
+
+## License
+
+[MIT](./LICENSE) © Alireza Mohammadvali

package/dist/cjs/PecClient.d.ts

@@ -0,0 +1,28 @@
+import type { BillInfoResult, ConfirmPaymentInput, ConfirmPaymentResult, GetBillInfoInput, GetSaleReportInput, GetSaleReportResult, PaymentTokenResult, PecClientOptions, RequestBillPaymentInput, RequestGovernmentMultiplexedPaymentInput, RequestGovernmentPaymentInput, RequestMobileTopupInput, RequestMultiplexedPaymentInput, RequestPaymentInput, ReversePaymentInput, ReversePaymentResult } from './types.js';
+export declare class PecClient {
+    private readonly loginAccount;
+    private readonly defaultCallbackUrl?;
+    constructor(options: PecClientOptions);
+    /** Starts a standard sale payment and returns a token plus redirect URL. */
+    requestPayment(input: RequestPaymentInput): Promise<PaymentTokenResult>;
+    /** Starts an online multiplexed sale (تسهیم آنلاین). */
+    requestMultiplexedPayment(input: RequestMultiplexedPaymentInput): Promise<PaymentTokenResult>;
+    /** Starts a government-ID sale (شناسه حساب دولتی). */
+    requestGovernmentPayment(input: RequestGovernmentPaymentInput): Promise<PaymentTokenResult>;
+    /** Starts a government sale with multiplexed IBAN accounts. */
+    requestGovernmentMultiplexedPayment(input: RequestGovernmentMultiplexedPaymentInput): Promise<PaymentTokenResult>;
+    /** Starts a bill payment request. */
+    requestBillPayment(input: RequestBillPaymentInput): Promise<PaymentTokenResult>;
+    /** Retrieves bill details before payment. */
+    getBillInfo(input: GetBillInfoInput): Promise<BillInfoResult>;
+    /** Starts a mobile top-up/charge request. */
+    requestMobileTopup(input: RequestMobileTopupInput): Promise<PaymentTokenResult>;
+    /** Confirms/settles a successful payment using its token. */
+    confirmPayment(input: ConfirmPaymentInput): Promise<ConfirmPaymentResult>;
+    /** Reverses a payment. Works only within the bank's allowed time window. */
+    reversePayment(input: ReversePaymentInput): Promise<ReversePaymentResult>;
+    /** Fetches sale transactions from PEC reporting REST API. */
+    getSaleReport(input: GetSaleReportInput): Promise<GetSaleReportResult>;
+    private resolveCallbackUrl;
+}
+//# sourceMappingURL=PecClient.d.ts.map

package/dist/cjs/PecClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PecClient.d.ts","sourceRoot":"","sources":["../../src/PecClient.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,wCAAwC,EACxC,6BAA6B,EAC7B,uBAAuB,EACvB,8BAA8B,EAC9B,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAapB,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAS;gBAEjC,OAAO,EAAE,gBAAgB;IASrC,4EAA4E;IACtE,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqB7E,wDAAwD;IAClD,yBAAyB,CAC7B,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,kBAAkB,CAAC;IAwB9B,sDAAsD;IAChD,wBAAwB,CAC5B,KAAK,EAAE,6BAA6B,GACnC,OAAO,CAAC,kBAAkB,CAAC;IAqB9B,+DAA+D;IACzD,mCAAmC,CACvC,KAAK,EAAE,wCAAwC,GAC9C,OAAO,CAAC,kBAAkB,CAAC;IAwB9B,qCAAqC;IAC/B,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAsBrF,6CAA6C;IACvC,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC;IAgBnE,6CAA6C;IACvC,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAwBrF,6DAA6D;IACvD,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAuB/E,4EAA4E;IACtE,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsB/E,6DAA6D;IACvD,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAiC5E,OAAO,CAAC,kBAAkB;CAa3B"}