pec-payment-sdk 1.1.1

package/dist/esm/types.d.ts

@@ -0,0 +1,122 @@
+export type Currency = 'rial' | 'toman';
+export type OrderId = string | number;
+export interface PecClientOptions {
+    /** Merchant terminal PIN (`LoginAccount` in PEC SOAP requests). */
+    loginAccount: string;
+    /** Default callback URL when not provided per request. */
+    callbackUrl?: string;
+}
+export interface RequestPaymentInput {
+    /** Amount in the unit specified by `currency`. Converted to Rials before sending to PEC. */
+    amount: number;
+    orderId: OrderId;
+    currency?: Currency;
+    callbackUrl?: string;
+    additionalData?: string;
+    originator?: string;
+}
+export interface PaymentTokenResult {
+    status: number;
+    message: string;
+    token: string;
+    paymentUrl?: string;
+}
+export interface ConfirmPaymentInput {
+    token: string | number;
+}
+export interface ConfirmPaymentResult {
+    status: number;
+    token: string;
+    cardNumberMasked: string;
+    rrn: string;
+}
+export interface ReversePaymentInput {
+    token: string | number;
+}
+export interface ReversePaymentResult {
+    status: number;
+    message: string;
+    token: string;
+}
+export interface MultiplexedAccount {
+    amount: number;
+    iban: string;
+    payId: string;
+}
+export interface RequestMultiplexedPaymentInput {
+    amount: number;
+    orderId: OrderId;
+    accounts: MultiplexedAccount[];
+    currency?: Currency;
+    callbackUrl?: string;
+    originator?: string;
+}
+export interface RequestGovernmentPaymentInput {
+    amount: number;
+    orderId: OrderId;
+    govId: string;
+    currency?: Currency;
+    callbackUrl?: string;
+    originator?: string;
+}
+export interface RequestGovernmentMultiplexedPaymentInput {
+    amount: number;
+    orderId: OrderId;
+    govId: string;
+    accounts: MultiplexedAccount[];
+    currency?: Currency;
+    callbackUrl?: string;
+    originator?: string;
+}
+export interface RequestBillPaymentInput {
+    orderId: OrderId;
+    billId: string;
+    payId: string;
+    callbackUrl?: string;
+    additionalData?: string;
+    originator?: string;
+}
+export interface GetBillInfoInput {
+    billId: string;
+    payId: string;
+}
+export interface BillInfoResult {
+    status: number;
+    message: string;
+    amount: string;
+    billId: string;
+    payId: string;
+}
+export interface RequestMobileTopupInput {
+    orderId: OrderId;
+    chargeMobileNumber: string;
+    requesterMobileNumber: string;
+    topupType: string | number;
+    amount: number;
+    currency?: Currency;
+    callbackUrl?: string;
+    additionalData?: string;
+    originator?: string;
+}
+export interface GetSaleReportInput {
+    username: string;
+    password: string;
+    fromDate: string;
+    toDate: string;
+    rrn?: string;
+    orderId?: OrderId;
+    token?: string | number;
+}
+export interface GetSaleReportResult {
+    [key: string]: unknown;
+}
+/** Fields POSTed by PEC to the merchant callback URL after payment. */
+export interface CallbackPayload {
+    token: string;
+    status: number;
+    orderId: string;
+    terminalNo: string;
+    amount: string;
+    rrn: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/utils.d.ts

@@ -0,0 +1,43 @@
+import type { CallbackPayload, Currency, MultiplexedAccount } from './types.js';
+/** Converts an amount to Rials for PEC API requests. */
+export declare function toRials(amount: number, currency?: Currency): number;
+/** Ensures amount is a positive finite number. */
+export declare function validateAmount(amount: number): void;
+export declare function getPaymentPageUrl(token: string | number): string;
+export declare function isSuccessStatus(status: number | string): boolean;
+/** Returns true when the bank callback indicates a successful payment worth confirming. */
+export declare function shouldConfirmPayment(callback: CallbackPayload): boolean;
+export declare function generateOrderId(): string;
+/** Validates callback URLs (HTTP for local dev, HTTPS for production). */
+export declare function isValidUrl(url: string): boolean;
+/** @deprecated Use {@link isValidUrl} instead. */
+export declare function isValidHttpsUrl(url: string): boolean;
+/**
+ * Parses the bank callback payload (PEC POSTs to your callback URL).
+ * Pass `req.body` for POST callbacks; merge `req.query` if your route uses GET.
+ */
+export declare function parseCallback(body: Record<string, unknown>): CallbackPayload;
+export declare function normalizeSoapField(value: unknown): string;
+export declare function normalizeSoapNumber(value: unknown): number;
+export declare function buildPaymentTokenResult(status: unknown, token: unknown, message: unknown): {
+    status: number;
+    token: string;
+    message: string;
+    paymentUrl?: string;
+};
+export declare function mapMultiplexedAccounts(accounts: MultiplexedAccount[], currency?: Currency): Array<{
+    Amount: number;
+    IBAN: string;
+    PayId: string;
+}>;
+export declare function validateMultiplexedAccounts(accounts: MultiplexedAccount[]): void;
+/** Validates sale report date range (max 30 days, end after start). */
+export declare function validateSaleReportDateRange(fromDate: string, toDate: string): void;
+export declare function normalizeBillInfoResult(payload: Record<string, unknown>): {
+    status: number;
+    message: string;
+    amount: string;
+    billId: string;
+    payId: string;
+};
+//# sourceMappingURL=utils.d.ts.map

package/dist/esm/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAMhF,wDAAwD;AACxD,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAkB,GAAG,MAAM,CAG5E;AAED,kDAAkD;AAClD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAInD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAEhE;AAED,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEvE;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAU/C;AAED,kDAAkD;AAClD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AAoBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,CAS5E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQzD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE1D;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,OAAO,GACf;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAgBzE;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,QAAQ,GAAE,QAAkB,GAC3B,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAQxD;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAchF;AAED,uEAAuE;AACvE,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAelF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf,CAQA"}

package/dist/esm/utils.js

@@ -0,0 +1,144 @@
+import { randomBytes } from 'crypto';
+import { PAYMENT_PAGE_BASE, PEC_SUCCESS_STATUS } from './constants.js';
+import { PecValidationError } from './errors.js';
+const MAX_SALE_REPORT_RANGE_MS = 30 * 24 * 60 * 60 * 1000;
+/** Converts an amount to Rials for PEC API requests. */
+export function toRials(amount, currency = 'toman') {
+    validateAmount(amount);
+    return currency === 'toman' ? amount * 10 : amount;
+}
+/** Ensures amount is a positive finite number. */
+export function validateAmount(amount) {
+    if (!Number.isFinite(amount) || amount <= 0) {
+        throw new PecValidationError('amount must be a positive number');
+    }
+}
+export function getPaymentPageUrl(token) {
+    return `${PAYMENT_PAGE_BASE}${token}`;
+}
+export function isSuccessStatus(status) {
+    return Number(status) === PEC_SUCCESS_STATUS;
+}
+/** Returns true when the bank callback indicates a successful payment worth confirming. */
+export function shouldConfirmPayment(callback) {
+    return callback.status === PEC_SUCCESS_STATUS && Number(callback.rrn) > 0;
+}
+export function generateOrderId() {
+    return randomBytes(20).toString('hex');
+}
+/** Validates callback URLs (HTTP for local dev, HTTPS for production). */
+export function isValidUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return ((parsed.protocol === 'https:' || parsed.protocol === 'http:') &&
+            parsed.hostname.length > 0);
+    }
+    catch {
+        return false;
+    }
+}
+/** @deprecated Use {@link isValidUrl} instead. */
+export function isValidHttpsUrl(url) {
+    return isValidUrl(url) && url.startsWith('https:');
+}
+function readField(body, keys) {
+    for (const key of keys) {
+        const value = body[key];
+        if (value !== undefined && value !== null && value !== '') {
+            return String(value);
+        }
+    }
+    return '';
+}
+function parseCallbackStatus(body) {
+    const raw = readField(body, ['status', 'Status']);
+    if (raw === '') {
+        return NaN;
+    }
+    return Number(raw);
+}
+/**
+ * Parses the bank callback payload (PEC POSTs to your callback URL).
+ * Pass `req.body` for POST callbacks; merge `req.query` if your route uses GET.
+ */
+export function parseCallback(body) {
+    return {
+        token: readField(body, ['Token', 'token']),
+        status: parseCallbackStatus(body),
+        orderId: readField(body, ['OrderId', 'orderId']),
+        terminalNo: readField(body, ['TerminalNo', 'terminalNo']),
+        amount: readField(body, ['Amount', 'amount']),
+        rrn: readField(body, ['RRN', 'rrn']),
+    };
+}
+export function normalizeSoapField(value) {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    if (Array.isArray(value)) {
+        return normalizeSoapField(value[0]);
+    }
+    return String(value);
+}
+export function normalizeSoapNumber(value) {
+    return Number(normalizeSoapField(value));
+}
+export function buildPaymentTokenResult(status, token, message) {
+    const normalizedStatus = normalizeSoapNumber(status);
+    const normalizedToken = normalizeSoapField(token);
+    const normalizedMessage = normalizeSoapField(message);
+    const result = {
+        status: normalizedStatus,
+        token: normalizedToken,
+        message: normalizedMessage,
+    };
+    if (isSuccessStatus(normalizedStatus) && normalizedToken.length > 0) {
+        return { ...result, paymentUrl: getPaymentPageUrl(normalizedToken) };
+    }
+    return result;
+}
+export function mapMultiplexedAccounts(accounts, currency = 'toman') {
+    validateMultiplexedAccounts(accounts);
+    return accounts.map((account) => ({
+        Amount: toRials(account.amount, currency),
+        IBAN: account.iban,
+        PayId: account.payId,
+    }));
+}
+export function validateMultiplexedAccounts(accounts) {
+    if (!Array.isArray(accounts) || accounts.length === 0) {
+        throw new PecValidationError('accounts must be a non-empty array');
+    }
+    for (const account of accounts) {
+        validateAmount(account.amount);
+        if (!account.iban?.trim()) {
+            throw new PecValidationError('each account must include a valid iban');
+        }
+        if (!account.payId?.trim()) {
+            throw new PecValidationError('each account must include a valid payId');
+        }
+    }
+}
+/** Validates sale report date range (max 30 days, end after start). */
+export function validateSaleReportDateRange(fromDate, toDate) {
+    const from = new Date(fromDate);
+    const to = new Date(toDate);
+    if (Number.isNaN(from.getTime()) || Number.isNaN(to.getTime())) {
+        throw new PecValidationError('fromDate and toDate must be valid date strings');
+    }
+    if (to.getTime() < from.getTime()) {
+        throw new PecValidationError('toDate must be on or after fromDate');
+    }
+    if (to.getTime() - from.getTime() > MAX_SALE_REPORT_RANGE_MS) {
+        throw new PecValidationError('date range must not exceed 30 days');
+    }
+}
+export function normalizeBillInfoResult(payload) {
+    return {
+        status: normalizeSoapNumber(payload.Status),
+        message: normalizeSoapField(payload.Message),
+        amount: normalizeSoapField(payload.Amount),
+        billId: normalizeSoapField(payload.BillId),
+        payId: normalizeSoapField(payload.PayId),
+    };
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pec-payment-sdk",
+  "version": "1.1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlirezaMoVali/pec-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AlirezaMoVali/pec-sdk/issues"
+  },
+  "homepage": "https://github.com/AlirezaMoVali/pec-sdk#readme",
+  "keywords": [
+    "pec",
+    "parsian",
+    "payment",
+    "gateway",
+    "shaparak",
+    "iran",
+    "ipg"
+  ],
+  "description": "TypeScript SDK for PEC (Parsian Electronic Commerce) payment gateway.",
+  "type": "commonjs",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && node scripts/postbuild-esm.mjs",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "author": "Alireza Mohammadvali <a.mv99@outlook.com> (https://github.com/AlirezaMoVali)",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.4.4",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.8",
+    "soap": "^1.1.7"
+  },
+  "files": [
+    "dist"
+  ]
+}