paperless-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rifat Mahmud
+
+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,61 @@
+# paperless-client
+
+A Node.js client for seamlessly interacting with the Paperless payment API. Built with TypeScript.
+
+## Installation
+
+You can install `paperless-client` using npm, pnpm, or yarn:
+
+```bash
+npm install paperless-client
+# or
+pnpm add paperless-client
+# or
+yarn add paperless-client
+```
+
+## Usage
+
+Here is a quick example of how to initiate a payment and check its status.
+
+```typescript
+import PaperlessClient, { formatDescription } from 'paperless-client'
+
+// 1. Initialize the client
+const client = new PaperlessClient(
+	'YOUR_MUID',
+	'YOUR_APP_ACCESS_KEY',
+	'YOUR_MERCHANT_REF_ID',
+	'https://payment-sandbox.paperlessltd.com' // or production URL
+)
+
+// 2. Generate a Payment URL
+async function initiate() {
+	const url = await client.getPaymentUrl({
+		merchant_order_id: '105',
+		customer_name: 'John Doe',
+		customer_email: 'john@example.com',
+		customer_phone: '01700000000',
+		product_desc: formatDescription([
+			{ name: 'Product 1', count: 2, perItemPrice: 100 }
+		]),
+		amount: '200',
+		currency: 'BDT',
+		approve_url: 'https://example.com/approve',
+		cancel_url: 'https://example.com/cancel',
+		decline_url: 'https://example.com/decline'
+	})
+
+	console.log('Redirect user to ->', url)
+}
+
+// 3. Check Payment Status
+async function checkStatus(token: string) {
+	const status = await client.checkPaymentStatus(token)
+	console.log('Transaction Status:', status.txn_status)
+}
+```
+
+## License
+
+MIT

package/dist/callback_data.d.ts

@@ -0,0 +1,9 @@
+export type CallbackDataType = {
+    merchant_txn_data: {
+        amount: string;
+        currency: string;
+        merchant_order_id: string;
+        token: string;
+        txn_status: 1000 | 1001 | 1009 | null;
+    };
+};

package/dist/callback_data.js

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

package/dist/check_payment.d.ts

@@ -0,0 +1,36 @@
+export type CheckPaymentResponseType = {
+    success: false;
+    data: any;
+} | {
+    success: true;
+    data: {
+        muid: string;
+        ref_id: string;
+        token: string;
+        merchant_req_amount: string;
+        merchant_ref_id: string;
+        merchant_currency: string;
+        merchant_amount_bdt: string;
+        conversion_rate: string;
+        service_ratio: string;
+        card_charge_bdt: string;
+        emi_ratio: string;
+        emi_charge: string;
+        bank_amount_bdt: string;
+        discount_bdt: string;
+        merchant_order_id: string;
+        request_ip: string;
+        txn_status: 1000 | 1001 | 1009 | null;
+        extra_json: null;
+        card_details: null;
+        is_foreign: 0 | 1;
+        payment_card: string;
+        card_code: number;
+        payment_method: string;
+        init_time: string;
+        txn_time: string;
+        statusCode: number;
+        customer_details: string;
+    };
+};
+export declare function checkPayment(origin: string, muid: string, token: string): Promise<CheckPaymentResponseType>;

package/dist/check_payment.js

@@ -0,0 +1,19 @@
+import { parseBody } from "./lib.js";
+export async function checkPayment(origin, muid, token) {
+    try {
+        const response = await fetch(`${origin}/api/v1/gateway/check-payment?muid=${muid}&token=${token}`);
+        if (!response.ok)
+            return { success: false, data: await parseBody(response) };
+        const data = await parseBody(response, true);
+        if (data === null) {
+            return { success: false, data: 'Failed to parse response' };
+        }
+        return { success: true, data };
+    }
+    catch {
+        return {
+            success: false,
+            data: 'An error occurred while checking payment status'
+        };
+    }
+}

package/dist/check_server.d.ts

@@ -0,0 +1,12 @@
+export type CheckStatusResponseType = {
+    success: false;
+    data: any;
+} | {
+    success: true;
+    data: {
+        selectedServer: boolean;
+        initiate_payment_url: string;
+        gateway_url: string;
+    };
+};
+export declare function checkServer(origin: string): Promise<CheckStatusResponseType>;

package/dist/check_server.js

@@ -0,0 +1,19 @@
+import { parseBody } from "./lib.js";
+export async function checkServer(origin) {
+    try {
+        const response = await fetch(`${origin}/api/v1/gateway/check-server`);
+        if (!response.ok)
+            return { success: false, data: await parseBody(response) };
+        const data = await response.json().catch(() => null);
+        if (data === null) {
+            return { success: false, data: 'Failed to parse response' };
+        }
+        return { success: true, data };
+    }
+    catch {
+        return {
+            success: false,
+            data: 'An error occurred while checking server status'
+        };
+    }
+}

package/dist/format_description.d.ts

@@ -0,0 +1,5 @@
+export declare function formatDescription(description: {
+    name: string;
+    count: number;
+    perItemPrice: number;
+}[]): string;

package/dist/format_description.js

@@ -0,0 +1,8 @@
+export function formatDescription(description) {
+    let descArr = [];
+    for (const item of description) {
+        const desc = `{${item.count} X ${item.name} [${item.perItemPrice}]=[${item.count * item.perItemPrice}]}`;
+        descArr.push(desc);
+    }
+    return descArr.join(' ');
+}

package/dist/getway_url.d.ts

@@ -0,0 +1 @@
+export declare function gatewayUrl(token: string, gatewayUrlTemp: string): string;

package/dist/getway_url.js

@@ -0,0 +1,3 @@
+export function gatewayUrl(token, gatewayUrlTemp) {
+    return gatewayUrlTemp.replace('{token}', token);
+}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { type InitiatePaymentOptionsType } from './initiate_payment.ts';
+import { formatDescription } from './format_description.ts';
+export { formatDescription };
+export { type CallbackDataType } from './callback_data.ts';
+export type GetPaymentUrlOptionsType = Omit<InitiatePaymentOptionsType, 'muid' | 'access_app_key' | 'merchant_ref_id'>;
+export default class PaperlessClient {
+    #private;
+    constructor(muid: string, app_access_key: string, merchant_ref_id: string, host: string);
+    getPaymentUrl(options: GetPaymentUrlOptionsType): Promise<string>;
+    checkPaymentStatus(token: string): Promise<{
+        muid: string;
+        ref_id: string;
+        token: string;
+        merchant_req_amount: string;
+        merchant_ref_id: string;
+        merchant_currency: string;
+        merchant_amount_bdt: string;
+        conversion_rate: string;
+        service_ratio: string;
+        card_charge_bdt: string;
+        emi_ratio: string;
+        emi_charge: string;
+        bank_amount_bdt: string;
+        discount_bdt: string;
+        merchant_order_id: string;
+        request_ip: string;
+        txn_status: 1000 | 1001 | 1009 | null;
+        extra_json: null;
+        card_details: null;
+        is_foreign: 0 | 1;
+        payment_card: string;
+        card_code: number;
+        payment_method: string;
+        init_time: string;
+        txn_time: string;
+        statusCode: number;
+        customer_details: string;
+    }>;
+}

package/dist/index.js

@@ -0,0 +1,48 @@
+import { checkServer } from "./check_server.js";
+import { initiatePayment } from "./initiate_payment.js";
+import { gatewayUrl } from "./getway_url.js";
+import { checkPayment } from "./check_payment.js";
+import { formatDescription } from "./format_description.js";
+export { formatDescription };
+export {} from "./callback_data.js";
+export default class PaperlessClient {
+    #muid;
+    #app_access_key;
+    #merchant_ref_id;
+    #host;
+    constructor(muid, app_access_key, merchant_ref_id, host) {
+        this.#muid = muid;
+        this.#app_access_key = app_access_key;
+        this.#merchant_ref_id = merchant_ref_id;
+        this.#host = host;
+    }
+    async getPaymentUrl(options) {
+        const checkServerResponse = await checkServer(this.#host);
+        if (!checkServerResponse.success) {
+            throw new Error('Server check failed', {
+                cause: checkServerResponse.data
+            });
+        }
+        const initiatePaymentResponse = await initiatePayment(checkServerResponse.data.initiate_payment_url, {
+            ...options,
+            muid: this.#muid,
+            access_app_key: this.#app_access_key,
+            merchant_ref_id: this.#merchant_ref_id
+        });
+        if (!initiatePaymentResponse.success) {
+            throw new Error('Payment initiation failed', {
+                cause: initiatePaymentResponse.data
+            });
+        }
+        return gatewayUrl(initiatePaymentResponse.data.token, checkServerResponse.data.gateway_url);
+    }
+    async checkPaymentStatus(token) {
+        const checkPaymentResponse = await checkPayment(this.#host, this.#muid, token);
+        if (!checkPaymentResponse.success) {
+            throw new Error('Payment check failed', {
+                cause: checkPaymentResponse.data
+            });
+        }
+        return checkPaymentResponse.data;
+    }
+}

package/dist/initiate_payment.d.ts

@@ -0,0 +1,38 @@
+export type InitiatePaymentOptionsType = {
+    muid: string;
+    access_app_key: string;
+    merchant_order_id: string;
+    merchant_ref_id: string;
+    customer_name: string;
+    customer_email: string;
+    customer_add?: string;
+    customer_phone: string;
+    customer_city?: string;
+    customer_postcode?: string;
+    customer_country?: string;
+    shipping_name?: string;
+    shipping_email?: string;
+    shipping_add?: string;
+    shipping_city?: string;
+    shipping_postcode?: string;
+    shipping_country?: string;
+    product_desc: string;
+    amount: string;
+    currency: string;
+    approve_url: string;
+    cancel_url: string;
+    decline_url: string;
+};
+export type InitiatePaymentResponseType = {
+    success: false;
+    data: any;
+} | {
+    success: true;
+    data: {
+        statusCode: string;
+        statusMsg: string;
+        token: string;
+        merchant_callback_url_update: boolean;
+    };
+};
+export declare function initiatePayment(url: string, options: InitiatePaymentOptionsType): Promise<InitiatePaymentResponseType>;

package/dist/initiate_payment.js

@@ -0,0 +1,26 @@
+import { parseBody } from "./lib.js";
+export async function initiatePayment(url, options) {
+    try {
+        const requestUrl = new URL(url);
+        for (const key in options) {
+            const value = options[key];
+            if (!value)
+                continue;
+            requestUrl.searchParams.append(key, value);
+        }
+        const response = await fetch(requestUrl, { method: 'POST' });
+        if (!response.ok)
+            return { success: false, data: await parseBody(response) };
+        const data = await response.json().catch(() => null);
+        if (data === null) {
+            return { success: false, data: 'Failed to parse response' };
+        }
+        return { success: true, data };
+    }
+    catch {
+        return {
+            success: false,
+            data: 'An error occurred while initiating payment'
+        };
+    }
+}

package/dist/lib.d.ts

@@ -0,0 +1 @@
+export declare function parseBody(response: Response, onlyJson?: boolean): Promise<any>;

package/dist/lib.js

@@ -0,0 +1,11 @@
+export async function parseBody(response, onlyJson = false) {
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        if (onlyJson)
+            return null;
+        return text;
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "paperless-client",
+  "version": "1.0.0",
+  "description": "A client for interacting with the Paperless payment API.",
+  "author": "Rifat Mahmud",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "typescript": "^6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RifatMahmudno-1/paperless-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/RifatMahmudno-1/paperless-client/issues"
+  },
+  "homepage": "https://github.com/RifatMahmudno-1/paperless-client#readme",
+  "scripts": {
+    "start": "node ./src/index.ts",
+    "dev": "node --watch-path=./src --watch-preserve-output ./src/index.ts",
+    "build": "tsc"
+  }
+}