@thepayulink/server 1.0.0

package/README.md

@@ -0,0 +1,134 @@
+# @thepayulink/server
+
+Server-side SDK for Elite Yatra / PayuLink. Create orders with a **fixed amount**,
+check payment status, and verify signatures & webhooks — all with your secret key.
+This is the backend half of the checkout, analogous to the `razorpay` Node SDK.
+
+> The **secret key never leaves your backend.** The client SDK only ever receives an `order_id`.
+
+## Install
+
+```bash
+npm install @thepayulink/server
+```
+
+Node 18+ (uses global `fetch`). Works with `import` and `require`.
+
+## Quick start
+
+```js
+import Payulink from '@thepayulink/server';
+
+const ey = new Payulink({
+  keyId: process.env.PAYULINK_PUBLISHABLE_KEY,   // pl_pk_… (optional)
+  keySecret: process.env.PAYULINK_SECRET_KEY,    // pl_sk_… (required, backend only)
+  apiBase: 'https://eliteyatra.vip',
+});
+
+// 1) Create an order for the TRUE amount (computed on your server).
+const order = await ey.orders.create({
+  amount: 19900,                            // rupees
+  item: 'Kailash Mansarovar Yatra — 2 travellers',
+  customer: { name: 'Asha', mobile: '9876543210' },
+});
+// -> { order_id, key_id, amount, item, status: 'created' }
+
+// 2) Send order.order_id to your client → open it in the client SDK.
+
+// 3) Later, confirm the payment authoritatively before fulfilment.
+const status = await ey.orders.fetch(order.order_id);
+if (status.paid) {
+  // deliver the booking — this reflects PayuLink's webhook-verified status
+}
+```
+
+### Express example
+
+```js
+import express from 'express';
+import Payulink from '@thepayulink/server';
+
+const ey = new Payulink({ keySecret: process.env.PAYULINK_SECRET_KEY });
+const app = express();
+app.use(express.json());
+
+// Client asks your backend to start a payment.
+app.post('/create-order', async (req, res) => {
+  const pkg = await db.getPackage(req.body.packageId);      // trusted price
+  const order = await ey.orders.create({
+    amount: pkg.bookingAmount * (req.body.travellers || 1),
+    item: pkg.title,
+    customer: req.body.customer,
+  });
+  res.json({ orderId: order.order_id, keyId: order.key_id });
+});
+
+// Client reports success → confirm before trusting it.
+app.post('/confirm', async (req, res) => {
+  const s = await ey.orders.fetch(req.body.orderId);
+  res.json({ paid: s.paid, utr: s.utr });
+});
+```
+
+## Verifying a payment
+
+Two equivalent ways, pick one:
+
+**A. Fetch the order (simplest, always correct):**
+
+```js
+const s = await ey.orders.fetch(orderId);
+if (s.paid) { /* confirmed */ }
+```
+
+**B. Verify the signature from the client success callback (Razorpay-style):**
+
+The client success payload includes `{ order_id, utr, signature }`. Verify it:
+
+```js
+const ok = ey.verifyPaymentSignature({ order_id, utr, signature });
+if (ok) { /* authentic success */ }
+```
+
+## Webhooks
+
+Set `PAYULINK_MERCHANT_WEBHOOK_URL` on the pay server to your endpoint. It receives
+signed events; verify with the raw body and the `x-payulink-signature` header:
+
+```js
+// Use a raw body parser on this route so the signature matches byte-for-byte.
+app.post('/webhooks/eliteyatra', express.raw({ type: '*/*' }), (req, res) => {
+  let event;
+  try {
+    event = ey.webhooks.constructEvent(req.body, req.get('x-payulink-signature'));
+  } catch (e) {
+    return res.status(400).send('Invalid signature');
+  }
+
+  if (event.event === 'payin.verified') {
+    // event.data: { order_id, status, utr, amount, item }
+    fulfilBooking(event.data.order_id);
+  }
+  res.sendStatus(200);
+});
+```
+
+Events: `payin.verified` (paid), `payin.failed`, `payin.expired`, `payin.cancelled`.
+
+## API
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `orders.create({ amount, item?, customer? })` | `Order` | Amount is fixed server-side. |
+| `orders.fetch(orderId)` | `OrderStatus` | Authoritative status; `.paid` boolean. |
+| `orders.isPaid(orderId)` | `boolean` | Convenience. |
+| `payments.fetch(orderId)` | `OrderStatus` | Alias of `orders.fetch`. |
+| `verifyPaymentSignature({ order_id, utr, signature })` | `boolean` | Verify client success handoff. |
+| `webhooks.constructEvent(rawBody, signature)` | `WebhookEvent` | Throws on bad signature. |
+| `webhooks.verify(rawBody, signature)` | `boolean` | Non-throwing check. |
+
+Errors throw `PayulinkError` with `.status` and `.body`.
+
+## License
+
+UNLICENSED — internal to Elite Yatra.

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+export interface PayulinkConfig {
+  /** Secret key (pl_sk_…). Required. Backend only. */
+  keySecret: string;
+  /** Publishable key (pl_pk_…). Optional. */
+  keyId?: string;
+  /** Pay server base URL. Default https://eliteyatra.vip. */
+  apiBase?: string;
+  /** Secret to verify inbound webhooks (defaults to keySecret). */
+  webhookSecret?: string;
+  /** Request timeout in ms. Default 15000. */
+  timeout?: number;
+}
+
+export interface CreateOrderParams {
+  /** Amount in rupees. Required. */
+  amount: number;
+  item?: string;
+  customer?: { name?: string; mobile?: string; email?: string };
+}
+
+export interface Order {
+  order_id: string;
+  key_id: string | null;
+  amount: number;
+  item: string;
+  status: string;
+}
+
+export interface OrderStatus {
+  merchant_order_no: string;
+  /** 0=SUCCESS, 1=FAILED, 2=PENDING, 3=EXPIRED, … */
+  status: number;
+  status_label: string;
+  paid: boolean;
+  utr: string | null;
+  amount: number;
+  item: string;
+  signature: string | null;
+  expires_at: number | null;
+  server_now: number;
+}
+
+export interface WebhookEvent {
+  id: string;
+  event: string;
+  created_at: number;
+  data: {
+    order_id: string;
+    status: number;
+    status_label: string;
+    utr: string | null;
+    amount: number;
+    item: string;
+  };
+}
+
+export class PayulinkError extends Error {
+  status?: number;
+  body?: unknown;
+}
+
+export default class Payulink {
+  constructor(config: PayulinkConfig);
+
+  orders: {
+    create(params: CreateOrderParams): Promise<Order>;
+    fetch(orderId: string): Promise<OrderStatus>;
+    isPaid(orderId: string): Promise<boolean>;
+  };
+
+  payments: {
+    fetch(orderId: string): Promise<OrderStatus>;
+  };
+
+  webhooks: {
+    verify(rawBody: string | Buffer, signature: string, secret?: string): boolean;
+    constructEvent(rawBody: string | Buffer, signature: string, secret?: string): WebhookEvent;
+  };
+
+  verifyPaymentSignature(p: { order_id: string; utr?: string | null; signature: string }): boolean;
+}

package/dist/payulink-server.cjs

@@ -0,0 +1,162 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var src_exports = {};
+__export(src_exports, {
+  PayulinkError: () => PayulinkError,
+  default: () => Payulink
+});
+module.exports = __toCommonJS(src_exports);
+var import_node_crypto = __toESM(require("node:crypto"), 1);
+var PayulinkError = class extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message);
+    this.name = "PayulinkError";
+    this.status = status;
+    this.body = body;
+  }
+};
+function safeEqual(a, b) {
+  const ba = Buffer.from(String(a || ""));
+  const bb = Buffer.from(String(b || ""));
+  return ba.length === bb.length && ba.length > 0 && import_node_crypto.default.timingSafeEqual(ba, bb);
+}
+var Payulink = class {
+  /**
+   * @param {object} opts
+   * @param {string} opts.keySecret  Secret key (pl_sk_…). Required. Backend only.
+   * @param {string} [opts.keyId]    Publishable key (pl_pk_…). Optional.
+   * @param {string} [opts.apiBase]  Pay server URL. Default https://eliteyatra.vip.
+   * @param {string} [opts.webhookSecret] Secret used to verify inbound webhooks (defaults to keySecret).
+   * @param {number} [opts.timeout]  Request timeout in ms. Default 15000.
+   */
+  constructor(opts = {}) {
+    if (!opts.keySecret) throw new PayulinkError("`keySecret` (pl_sk_\u2026) is required");
+    this.keySecret = opts.keySecret;
+    this.keyId = opts.keyId || null;
+    this.apiBase = String(opts.apiBase || "https://eliteyatra.vip").replace(/\/$/, "");
+    this.webhookSecret = opts.webhookSecret || opts.keySecret;
+    this.timeout = opts.timeout || 15e3;
+    this.orders = {
+      create: (params) => this._createOrder(params),
+      fetch: (orderId) => this._fetchOrder(orderId),
+      isPaid: async (orderId) => (await this._fetchOrder(orderId)).paid === true
+    };
+    this.payments = { fetch: (orderId) => this._fetchOrder(orderId) };
+    this.webhooks = {
+      verify: (rawBody, signature, secret) => this._verifyWebhook(rawBody, signature, secret),
+      constructEvent: (rawBody, signature, secret) => this._constructEvent(rawBody, signature, secret)
+    };
+  }
+  async _request(method, path, { body, auth } = {}) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), this.timeout);
+    let res;
+    try {
+      res = await fetch(`${this.apiBase}${path}`, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          ...auth ? { Authorization: `Bearer ${this.keySecret}` } : {},
+          ...this.keyId ? { "x-payulink-key": this.keyId } : {}
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: ctrl.signal
+      });
+    } catch (e) {
+      clearTimeout(t);
+      throw new PayulinkError(`Network error: ${e.message}`);
+    }
+    clearTimeout(t);
+    let data = {};
+    try {
+      data = await res.json();
+    } catch {
+    }
+    if (!res.ok) throw new PayulinkError(data.error || `Request failed (HTTP ${res.status})`, { status: res.status, body: data });
+    return data;
+  }
+  /**
+   * Create an order with a server-fixed amount. The client only receives the
+   * returned `order_id` and cannot change the amount.
+   * @param {object} params  { amount (rupees), item?, customer? }
+   * @returns {Promise<{order_id, key_id, amount, item, status}>}
+   */
+  _createOrder(params = {}) {
+    const amount = Math.round(Number(params.amount) || 0);
+    if (!(amount >= 1)) throw new PayulinkError("`amount` (in rupees) is required and must be >= 1");
+    return this._request("POST", "/api/orders", {
+      auth: true,
+      body: { amount, item: params.item, customer: params.customer }
+    });
+  }
+  /**
+   * Fetch the authoritative status of an order.
+   * @returns {Promise<{merchant_order_no, status, status_label, paid, utr, amount, signature}>}
+   */
+  _fetchOrder(orderId) {
+    if (!orderId) throw new PayulinkError("orderId is required");
+    return this._request("GET", `/api/order/${encodeURIComponent(orderId)}`);
+  }
+  /**
+   * Verify a payment handoff signature returned to the client on success.
+   * Mirrors Razorpay's signature check.
+   * @param {object} p  { order_id, utr, signature }
+   * @returns {boolean}
+   */
+  verifyPaymentSignature({ order_id, utr, signature } = {}) {
+    if (!order_id || !signature) return false;
+    const expected = import_node_crypto.default.createHmac("sha256", this.keySecret).update(`${order_id}|${utr || ""}`).digest("hex");
+    return safeEqual(expected, signature);
+  }
+  _verifyWebhook(rawBody, signature, secret) {
+    const expected = import_node_crypto.default.createHmac("sha256", secret || this.webhookSecret).update(String(rawBody)).digest("hex");
+    return safeEqual(expected, signature);
+  }
+  /**
+   * Verify an inbound webhook and return the parsed event. Throws if the
+   * signature is invalid. Pass the RAW request body (string/Buffer) and the
+   * `x-payulink-signature` header.
+   */
+  _constructEvent(rawBody, signature, secret) {
+    if (!this._verifyWebhook(rawBody, signature, secret)) {
+      throw new PayulinkError("Invalid webhook signature", { status: 401 });
+    }
+    try {
+      return JSON.parse(String(rawBody));
+    } catch {
+      throw new PayulinkError("Invalid webhook JSON", { status: 400 });
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PayulinkError
+});
+(()=>{const ns=module.exports,C=ns.default;if(C){C.PayulinkError=ns.PayulinkError;C.Payulink=C;C.default=C;module.exports=C;}})();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@thepayulink/server",
+  "version": "1.0.0",
+  "description": "Server-side SDK for Elite Yatra / PayuLink — create orders, check payment status, and verify signatures & webhooks with your secret key.",
+  "type": "module",
+  "main": "./dist/payulink-server.cjs",
+  "module": "./src/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./dist/payulink-server.cjs"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node build.mjs"
+  },
+  "keywords": [
+    "eliteyatra",
+    "payulink",
+    "payment",
+    "server",
+    "sdk",
+    "upi",
+    "orders",
+    "webhooks"
+  ],
+  "author": "Elite Yatra",
+  "license": "MIT",
+  "devDependencies": {
+    "esbuild": "^0.23.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,136 @@
+// @thepayulink/server — backend SDK for Elite Yatra / PayuLink.
+//
+//   import Payulink from '@thepayulink/server';
+//   const ey = new Payulink({ keyId: 'pl_pk_…', keySecret: 'pl_sk_…' });
+//   const order = await ey.orders.create({ amount: 19900, item: 'Kailash Yatra' });
+//   // …open `order.order_id` in the client SDK…
+//   const status = await ey.orders.fetch(order.order_id);   // { paid, status, utr, … }
+//
+// Requires Node 18+ (global fetch).
+import crypto from 'node:crypto';
+
+export class PayulinkError extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message);
+    this.name = 'PayulinkError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function safeEqual(a, b) {
+  const ba = Buffer.from(String(a || ''));
+  const bb = Buffer.from(String(b || ''));
+  return ba.length === bb.length && ba.length > 0 && crypto.timingSafeEqual(ba, bb);
+}
+
+export default class Payulink {
+  /**
+   * @param {object} opts
+   * @param {string} opts.keySecret  Secret key (pl_sk_…). Required. Backend only.
+   * @param {string} [opts.keyId]    Publishable key (pl_pk_…). Optional.
+   * @param {string} [opts.apiBase]  Pay server URL. Default https://eliteyatra.vip.
+   * @param {string} [opts.webhookSecret] Secret used to verify inbound webhooks (defaults to keySecret).
+   * @param {number} [opts.timeout]  Request timeout in ms. Default 15000.
+   */
+  constructor(opts = {}) {
+    if (!opts.keySecret) throw new PayulinkError('`keySecret` (pl_sk_…) is required');
+    this.keySecret = opts.keySecret;
+    this.keyId = opts.keyId || null;
+    this.apiBase = String(opts.apiBase || 'https://eliteyatra.vip').replace(/\/$/, '');
+    this.webhookSecret = opts.webhookSecret || opts.keySecret;
+    this.timeout = opts.timeout || 15000;
+
+    this.orders = {
+      create: (params) => this._createOrder(params),
+      fetch: (orderId) => this._fetchOrder(orderId),
+      isPaid: async (orderId) => (await this._fetchOrder(orderId)).paid === true,
+    };
+    // Alias for Razorpay-familiar naming.
+    this.payments = { fetch: (orderId) => this._fetchOrder(orderId) };
+    this.webhooks = {
+      verify: (rawBody, signature, secret) => this._verifyWebhook(rawBody, signature, secret),
+      constructEvent: (rawBody, signature, secret) => this._constructEvent(rawBody, signature, secret),
+    };
+  }
+
+  async _request(method, path, { body, auth } = {}) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), this.timeout);
+    let res;
+    try {
+      res = await fetch(`${this.apiBase}${path}`, {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          ...(auth ? { Authorization: `Bearer ${this.keySecret}` } : {}),
+          ...(this.keyId ? { 'x-payulink-key': this.keyId } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: ctrl.signal,
+      });
+    } catch (e) {
+      clearTimeout(t);
+      throw new PayulinkError(`Network error: ${e.message}`);
+    }
+    clearTimeout(t);
+    let data = {};
+    try { data = await res.json(); } catch { /* non-JSON */ }
+    if (!res.ok) throw new PayulinkError(data.error || `Request failed (HTTP ${res.status})`, { status: res.status, body: data });
+    return data;
+  }
+
+  /**
+   * Create an order with a server-fixed amount. The client only receives the
+   * returned `order_id` and cannot change the amount.
+   * @param {object} params  { amount (rupees), item?, customer? }
+   * @returns {Promise<{order_id, key_id, amount, item, status}>}
+   */
+  _createOrder(params = {}) {
+    const amount = Math.round(Number(params.amount) || 0);
+    if (!(amount >= 1)) throw new PayulinkError('`amount` (in rupees) is required and must be >= 1');
+    return this._request('POST', '/api/orders', {
+      auth: true,
+      body: { amount, item: params.item, customer: params.customer },
+    });
+  }
+
+  /**
+   * Fetch the authoritative status of an order.
+   * @returns {Promise<{merchant_order_no, status, status_label, paid, utr, amount, signature}>}
+   */
+  _fetchOrder(orderId) {
+    if (!orderId) throw new PayulinkError('orderId is required');
+    return this._request('GET', `/api/order/${encodeURIComponent(orderId)}`);
+  }
+
+  /**
+   * Verify a payment handoff signature returned to the client on success.
+   * Mirrors Razorpay's signature check.
+   * @param {object} p  { order_id, utr, signature }
+   * @returns {boolean}
+   */
+  verifyPaymentSignature({ order_id, utr, signature } = {}) {
+    if (!order_id || !signature) return false;
+    const expected = crypto.createHmac('sha256', this.keySecret).update(`${order_id}|${utr || ''}`).digest('hex');
+    return safeEqual(expected, signature);
+  }
+
+  _verifyWebhook(rawBody, signature, secret) {
+    const expected = crypto.createHmac('sha256', secret || this.webhookSecret).update(String(rawBody)).digest('hex');
+    return safeEqual(expected, signature);
+  }
+
+  /**
+   * Verify an inbound webhook and return the parsed event. Throws if the
+   * signature is invalid. Pass the RAW request body (string/Buffer) and the
+   * `x-payulink-signature` header.
+   */
+  _constructEvent(rawBody, signature, secret) {
+    if (!this._verifyWebhook(rawBody, signature, secret)) {
+      throw new PayulinkError('Invalid webhook signature', { status: 401 });
+    }
+    try { return JSON.parse(String(rawBody)); }
+    catch { throw new PayulinkError('Invalid webhook JSON', { status: 400 }); }
+  }
+}