@thepayulink/server 1.0.0 → 2.0.0

package/README.md

@@ -1,10 +1,12 @@
 # @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.
+Backend SDK for the [PayuLink](https://payulink.io) Checkout API. Create orders
+with a **server-fixed amount**, check status, and verify payment signatures and
+webhooks. 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`.
+> Your **`key_secret` never leaves your backend.** The client SDK only ever
+> receives an `order_id`.
 
 ## Install
 
@@ -17,118 +19,104 @@ Node 18+ (uses global `fetch`). Works with `import` and `require`.
 ## Quick start
 
 ```js
-import Payulink from '@thepayulink/server';
+import PayuLink, { rupees } 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',
+const pl = new PayuLink({
+  keyId: process.env.PAYULINK_KEY_ID,          // pl_live_… / pl_test_…
+  keySecret: process.env.PAYULINK_KEY_SECRET,  // backend only — never ship this
 });
 
-// 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' },
+// 1) Create an order for the TRUE amount, computed on your server.
+const order = await pl.orders.create({
+  amount: rupees(199.5),        // PAISE — 19950. rupees() keeps you honest.
+  receipt: 'booking_1042',      // your reference; also your idempotency key
+  notes: { packageId: 'kailash' },
 });
-// -> { order_id, key_id, amount, item, status: 'created' }
+// -> { id: 'order_…', amount: 19950, currency: 'INR', status: 'created', … }
 
-// 2) Send order.order_id to your client → open it in the client SDK.
+// 2) Hand order.id to the client SDK (@thepayulink/checkout) with your key_id.
 
-// 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 });
+// 3) Verify the handoff before you fulfil.
+app.post('/verify', express.json(), (req, res) => {
+  if (!pl.verifyPaymentSignature(req.body)) return res.status(400).send('bad signature');
+  fulfil(req.body.payulink_order_id);
+  res.sendStatus(200);
 });
 ```
 
-## Verifying a payment
-
-Two equivalent ways, pick one:
+## Amounts are in paise
 
-**A. Fetch the order (simplest, always correct):**
+`19950` is ₹199.50 — same convention as Razorpay. Use the `rupees()` helper and
+you can't get the factor of 100 wrong:
 
 ```js
-const s = await ey.orders.fetch(orderId);
-if (s.paid) { /* confirmed */ }
+import { rupees, toRupees } from '@thepayulink/server';
+rupees(199.5);    // 19950
+toRupees(19950);  // 199.5
 ```
 
-**B. Verify the signature from the client success callback (Razorpay-style):**
+## API
 
-The client success payload includes `{ order_id, utr, signature }`. Verify it:
+| Method | Returns | Purpose |
+| --- | --- | --- |
+| `orders.create({ amount, currency?, receipt?, notes? })` | order | Create an amount-fixed order. |
+| `orders.fetch(orderId)` | order | Authoritative status. |
+| `orders.isPaid(orderId)` | boolean | Convenience. |
+| `verifyPaymentSignature({ payulink_order_id, payulink_payment_id, payulink_signature })` | boolean | Verify the client success handoff. |
+| `webhooks.constructEvent(rawBody, headers)` | event | Verify + parse a webhook (throws if invalid or stale). |
 
-```js
-const ok = ey.verifyPaymentSignature({ order_id, utr, signature });
-if (ok) { /* authentic success */ }
-```
+### Idempotency
 
-## Webhooks
+`receipt` is unique per merchant. Reusing one returns the **same** order instead
+of creating a second — so a double-clicked button or a retried request can't
+charge twice. Reusing it with a *different* amount is a `409`.
 
-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:
+### Signatures
+
+`signature = HMAC_SHA256(order_id + "|" + payment_id, key_secret)` — the same
+check as Razorpay's `razorpay_signature`. Only someone holding your `key_secret`
+could have produced it, which is why the browser callback alone is never proof.
+
+### Webhooks
 
 ```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) => {
+app.post('/webhooks/payulink', express.raw({ type: '*/*' }), (req, res) => {
   let event;
   try {
-    event = ey.webhooks.constructEvent(req.body, req.get('x-payulink-signature'));
+    event = pl.webhooks.constructEvent(req.body, req.headers);  // throws if bad or stale
   } 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);
+    return res.status(400).send(e.message);
   }
-  res.sendStatus(200);
+  if (event.event_type === 'payin.verified') fulfil(event.data.merchant_order_no);
+  res.sendStatus(200);   // 2xx = delivered; anything else is retried
 });
 ```
 
-Events: `payin.verified` (paid), `payin.failed`, `payin.expired`, `payin.cancelled`.
+Pass the **raw** body — a re-serialised object won't match the signature.
+`constructEvent` also rejects timestamps outside ±5 minutes, so a captured
+webhook can't be replayed later. Deliveries retry 8 times over ~30h, so
+**dedupe on `X-PayuLink-Event-Id`**.
 
-## API
+## Errors
 
-| 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. |
+Failures throw `PayuLinkError` with `.status`, `.code` and `.body`:
+
+```js
+import { PayuLinkError } from '@thepayulink/server';
+try { await pl.orders.create({ amount: 5 }); }
+catch (e) { if (e instanceof PayuLinkError) console.error(e.code, e.message); }
+```
+
+## Upgrading from 1.x
 
-Errors throw `PayulinkError` with `.status` and `.body`.
+1.x talked to a self-hosted proxy, used `pl_sk_…` keys and **rupee** amounts.
 
-## License
+| 1.x | 2.x |
+| --- | --- |
+| `new Payulink({ keySecret: 'pl_sk_…' })` | `new PayuLink({ keyId: 'pl_live_…', keySecret })` |
+| `amount: 19900` (rupees) | `amount: rupees(199)` (paise) |
+| `order.order_id` | `order.id` |
+| `verifyPaymentSignature({ order_id, utr, signature })` | `verifyPaymentSignature({ payulink_order_id, payulink_payment_id, payulink_signature })` |
+| `webhooks.constructEvent(body, sig)` | `webhooks.constructEvent(body, headers)` — timestamp checked |
 
-UNLICENSED — internal to Elite Yatra.
+License: MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "2.0.0",
+  "description": "PayuLink server SDK \u2014 create orders and verify payments/webhooks with your key_secret.",
   "type": "module",
   "main": "./dist/payulink-server.cjs",
   "module": "./src/index.js",
@@ -25,7 +25,6 @@
     "build": "node build.mjs"
   },
   "keywords": [
-    "eliteyatra",
     "payulink",
     "payment",
     "server",
@@ -34,9 +33,10 @@
     "orders",
     "webhooks"
   ],
-  "author": "Elite Yatra",
+  "author": "PayuLink",
   "license": "MIT",
   "devDependencies": {
     "esbuild": "^0.23.0"
-  }
+  },
+  "homepage": "https://payulink.io"
 }

package/src/index.js

@@ -1,60 +1,77 @@
-// @thepayulink/server — backend SDK for Elite Yatra / PayuLink.
+// @thepayulink/server — backend SDK for the PayuLink Checkout API (v1).
 //
-//   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, … }
+//   import PayuLink from '@thepayulink/server';
+//   const pl = new PayuLink({ keyId: 'pl_live_…', keySecret: '…' });
+//
+//   // 1. Create an order on YOUR server. The amount is fixed here and the
+//   //    client can never change it.
+//   const order = await pl.orders.create({ amount: 19950, receipt: 'rcpt#1' }); // ₹199.50 in PAISE
+//
+//   // 2. Hand order.id to the client SDK, which opens it with the PUBLISHABLE key_id.
+//
+//   // 3. Verify the success handoff before you fulfil anything.
+//   if (pl.verifyPaymentSignature(req.body)) fulfil(order.id);
 //
 // Requires Node 18+ (global fetch).
 import crypto from 'node:crypto';
 
-export class PayulinkError extends Error {
-  constructor(message, { status, body } = {}) {
+/** Amount helpers — the API speaks PAISE, like Razorpay. */
+export const rupees = (r) => Math.round(Number(r) * 100);
+export const toRupees = (paise) => Number(paise) / 100;
+
+export class PayuLinkError extends Error {
+  constructor(message, { status, code, body } = {}) {
     super(message);
-    this.name = 'PayulinkError';
+    this.name = 'PayuLinkError';
     this.status = status;
+    this.code = code;
     this.body = body;
   }
 }
 
 function safeEqual(a, b) {
-  const ba = Buffer.from(String(a || ''));
-  const bb = Buffer.from(String(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 {
+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.
+   * @param {string} opts.keyId          Publishable key (pl_live_… / pl_test_…).
+   * @param {string} opts.keySecret      Secret key. BACKEND ONLY — never ship this.
+   * @param {string} [opts.apiBase]      Default https://payulink.io/api
+   * @param {string} [opts.webhookSecret] Webhook signing secret (webhook_secret_v2 from your
+   *                                      merchant panel). Falls back to keySecret.
+   * @param {number} [opts.timeout]      Request timeout ms. Default 15000.
    */
   constructor(opts = {}) {
-    if (!opts.keySecret) throw new PayulinkError('`keySecret` (pl_sk_…) is required');
+    if (!opts.keyId) throw new PayuLinkError('`keyId` (pl_live_… / pl_test_…) is required');
+    if (!opts.keySecret) throw new PayuLinkError('`keySecret` is required and must stay on your server');
+    this.keyId = opts.keyId;
     this.keySecret = opts.keySecret;
-    this.keyId = opts.keyId || null;
-    this.apiBase = String(opts.apiBase || 'https://eliteyatra.vip').replace(/\/$/, '');
+    this.apiBase = String(opts.apiBase || 'https://payulink.io/api').replace(/\/$/, '');
     this.webhookSecret = opts.webhookSecret || opts.keySecret;
     this.timeout = opts.timeout || 15000;
+    this.mode = /^pl_test_/.test(opts.keyId) ? 'test' : 'live';
 
     this.orders = {
       create: (params) => this._createOrder(params),
       fetch: (orderId) => this._fetchOrder(orderId),
-      isPaid: async (orderId) => (await this._fetchOrder(orderId)).paid === true,
+      isPaid: async (orderId) => (await this._fetchOrder(orderId)).status === 'paid',
     };
-    // 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),
+      verify: (rawBody, signature, timestamp, secret) =>
+        this._verifyWebhook(rawBody, signature, timestamp, secret),
+      constructEvent: (rawBody, headers, secret) => this._constructEvent(rawBody, headers, secret),
     };
   }
 
-  async _request(method, path, { body, auth } = {}) {
+  get _authHeader() {
+    return 'Basic ' + Buffer.from(`${this.keyId}:${this.keySecret}`).toString('base64');
+  }
+
+  async _request(method, path, { body } = {}) {
     const ctrl = new AbortController();
     const t = setTimeout(() => ctrl.abort(), this.timeout);
     let res;
@@ -63,74 +80,137 @@ export default class Payulink {
         method,
         headers: {
           'Content-Type': 'application/json',
-          ...(auth ? { Authorization: `Bearer ${this.keySecret}` } : {}),
-          ...(this.keyId ? { 'x-payulink-key': this.keyId } : {}),
+          Authorization: this._authHeader,
         },
         body: body ? JSON.stringify(body) : undefined,
         signal: ctrl.signal,
       });
     } catch (e) {
       clearTimeout(t);
-      throw new PayulinkError(`Network error: ${e.message}`);
+      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 });
+    if (!res.ok) {
+      const err = data && data.error ? data.error : {};
+      throw new PayuLinkError(err.description || `Request failed (HTTP ${res.status})`,
+        { status: res.status, code: err.code, 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}>}
+   * Create an order with a server-fixed amount.
+   * @param {object} p
+   * @param {number} p.amount      Amount in PAISE (19950 = ₹199.50). Minimum 100.
+   * @param {string} [p.currency]  INR (default).
+   * @param {string} [p.receipt]   Your reference. Unique per merchant — reusing it
+   *                               returns the SAME order, which makes retries safe.
+   * @param {object} [p.notes]     Arbitrary key/value metadata.
    */
-  _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 },
+  _createOrder(p = {}) {
+    const amount = Math.round(Number(p.amount));
+    if (!Number.isFinite(amount) || amount < 100) {
+      throw new PayuLinkError('`amount` is required, in PAISE, and must be >= 100 (₹1). '
+        + 'Tip: use the `rupees()` helper — rupees(199.5) === 19950.');
+    }
+    return this._request('POST', '/v1/orders', {
+      body: {
+        amount,
+        currency: p.currency || 'INR',
+        receipt: p.receipt,
+        notes: p.notes,
+        customer_name: p.customer?.name,
+        customer_mobile: p.customer?.contact,
+        customer_email: p.customer?.email,
+        notify_url: p.notifyUrl,
+      },
     });
   }
 
-  /**
-   * Fetch the authoritative status of an order.
-   * @returns {Promise<{merchant_order_no, status, status_label, paid, utr, amount, signature}>}
-   */
+  /** Authoritative order status. */
   _fetchOrder(orderId) {
-    if (!orderId) throw new PayulinkError('orderId is required');
-    return this._request('GET', `/api/order/${encodeURIComponent(orderId)}`);
+    if (!orderId) throw new PayuLinkError('orderId is required');
+    return this._request('GET', `/v1/orders/${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}
+   * Verify the success handoff the client SDK returns. Mirrors Razorpay's
+   * `validatePaymentVerification`.
+   *
+   *   signature = hex(HMAC_SHA256(order_id + "|" + payment_id, key_secret))
+   *
+   * ALWAYS do this on your server before fulfilling. The client callback alone
+   * is not proof of payment.
+   *
+   * @param {object} p { payulink_order_id, payulink_payment_id, payulink_signature }
+   *                   (also accepts order_id / payment_id / signature)
    */
-  verifyPaymentSignature({ order_id, utr, signature } = {}) {
-    if (!order_id || !signature) return false;
-    const expected = crypto.createHmac('sha256', this.keySecret).update(`${order_id}|${utr || ''}`).digest('hex');
+  verifyPaymentSignature(p = {}) {
+    const orderId = p.payulink_order_id || p.order_id;
+    const paymentId = p.payulink_payment_id || p.payment_id;
+    const signature = p.payulink_signature || p.signature;
+    if (!orderId || !paymentId || !signature) return false;
+    const expected = crypto.createHmac('sha256', this.keySecret)
+      .update(`${orderId}|${paymentId}`).digest('hex');
     return safeEqual(expected, signature);
   }
 
-  _verifyWebhook(rawBody, signature, secret) {
-    const expected = crypto.createHmac('sha256', secret || this.webhookSecret).update(String(rawBody)).digest('hex');
+  /**
+   * Verify a webhook. PayuLink signs webhooks Stripe-style:
+   *   X-PayuLink-Signature: sha256=<hex>   over  `${timestamp}.${rawBody}`
+   *   X-PayuLink-Timestamp: <epoch ms>
+   */
+  _verifyWebhook(rawBody, signature, timestamp, secret) {
+    if (!signature || !timestamp) return false;
+    const key = secret || this.webhookSecret;
+    const expected = 'sha256=' + crypto.createHmac('sha256', key)
+      .update(`${timestamp}.${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.
+   * Verify + parse a webhook. Throws if the signature is bad or the timestamp is
+   * outside the tolerance window (replay protection).
+   *
+   * Pass the RAW body (string/Buffer) — a re-serialised object will not match.
+   *
+   *   app.post('/webhook', express.raw({type:'*\/*'}), (req, res) => {
+   *     const event = pl.webhooks.constructEvent(req.body, req.headers);
+   *     if (event.event_type === 'payin.verified') fulfil(event);
+   *     res.sendStatus(200);
+   *   });
+   *
+   * @param {string|Buffer} rawBody
+   * @param {object} headers  The request headers object.
+   * @param {string} [secret]
+   * @param {number} [toleranceSec=300]
    */
-  _constructEvent(rawBody, signature, secret) {
-    if (!this._verifyWebhook(rawBody, signature, secret)) {
-      throw new PayulinkError('Invalid webhook signature', { status: 401 });
+  _constructEvent(rawBody, headers = {}, secret, toleranceSec = 300) {
+    const get = (n) => headers[n] || headers[n.toLowerCase()] ||
+      (typeof headers.get === 'function' ? headers.get(n) : undefined);
+    const signature = get('X-PayuLink-Signature');
+    const timestamp = get('X-PayuLink-Timestamp');
+    if (!signature) throw new PayuLinkError('Missing X-PayuLink-Signature', { status: 401 });
+    if (!timestamp) throw new PayuLinkError('Missing X-PayuLink-Timestamp', { status: 401 });
+
+    // Replay window: a captured webhook must not be replayable forever.
+    const ageSec = Math.abs(Date.now() - Number(timestamp)) / 1000;
+    if (!Number.isFinite(ageSec) || ageSec > toleranceSec) {
+      throw new PayuLinkError(`Webhook timestamp outside tolerance (${Math.round(ageSec)}s)`, { status: 401 });
+    }
+    if (!this._verifyWebhook(rawBody, signature, timestamp, secret)) {
+      throw new PayuLinkError('Invalid webhook signature', { status: 401 });
+    }
+    try {
+      const event = JSON.parse(String(rawBody));
+      event.id = event.id || get('X-PayuLink-Event-Id');
+      event.event_type = event.event_type || get('X-PayuLink-Event-Type');
+      return event;
+    } catch {
+      throw new PayuLinkError('Invalid webhook JSON', { status: 400 });
     }
-    try { return JSON.parse(String(rawBody)); }
-    catch { throw new PayulinkError('Invalid webhook JSON', { status: 400 }); }
   }
 }