@thepayulink/server 1.0.0 → 2.0.1

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/dist/index.d.ts

@@ -1,81 +1,100 @@
-export interface PayulinkConfig {
-  /** Secret key (pl_sk_…). Required. Backend only. */
+// Type definitions for @thepayulink/server
+
+export interface PayuLinkOptions {
+  /** Publishable key: pl_live_… / pl_test_… */
+  keyId: string;
+  /** Secret key. BACKEND ONLY — never ship this to a browser or app. */
   keySecret: string;
-  /** Publishable key (pl_pk_…). Optional. */
-  keyId?: string;
-  /** Pay server base URL. Default https://eliteyatra.vip. */
+  /** Gateway base URL. Default https://payulink.io/api */
   apiBase?: string;
-  /** Secret to verify inbound webhooks (defaults to keySecret). */
+  /** Webhook signing secret (webhook_secret_v2). Falls back to keySecret. */
   webhookSecret?: string;
   /** Request timeout in ms. Default 15000. */
   timeout?: number;
 }
 
 export interface CreateOrderParams {
-  /** Amount in rupees. Required. */
+  /** Amount in PAISE. 19950 = ₹199.50. Minimum 100. */
   amount: number;
-  item?: string;
-  customer?: { name?: string; mobile?: string; email?: string };
+  /** Default 'INR'. */
+  currency?: string;
+  /** Your reference. Unique per merchant — reusing it returns the SAME order. */
+  receipt?: string;
+  /** Arbitrary key/value metadata. */
+  notes?: Record<string, unknown>;
+  /** Optional customer prefill. */
+  customer?: { name?: string; contact?: string; email?: string };
+  /** Per-order webhook override. */
+  notifyUrl?: string;
 }
 
 export interface Order {
-  order_id: string;
-  key_id: string | null;
+  /** e.g. order_9f2c4b… */
+  id: string;
+  entity: 'order';
+  /** PAISE */
   amount: number;
-  item: string;
-  status: string;
+  amount_paid: number;
+  amount_due: number;
+  currency: string;
+  receipt: string | null;
+  status: 'created' | 'attempted' | 'paid' | 'expired' | 'failed';
+  mode: 'live' | 'test';
+  attempts: number;
+  notes: Record<string, unknown>;
+  payment_id?: string;
+  utr?: string;
+  created_at: number | null;
 }
 
-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 PaymentHandoff {
+  payulink_order_id?: string;
+  payulink_payment_id?: string;
+  payulink_signature?: string;
+  /** Aliases also accepted. */
+  order_id?: string;
+  payment_id?: string;
+  signature?: string;
 }
 
 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;
-  };
+  id?: string;
+  event_type?: string;
+  data?: Record<string, any>;
+  [k: string]: any;
 }
 
-export class PayulinkError extends Error {
+export class PayuLinkError extends Error {
   status?: number;
+  code?: string;
   body?: unknown;
 }
 
-export default class Payulink {
-  constructor(config: PayulinkConfig);
+/** Convert rupees to paise. rupees(199.5) === 19950 */
+export function rupees(r: number): number;
+/** Convert paise to rupees. toRupees(19950) === 199.5 */
+export function toRupees(paise: number): number;
+
+export default class PayuLink {
+  constructor(options: PayuLinkOptions);
+
+  readonly keyId: string;
+  readonly apiBase: string;
+  /** Derived from the key prefix. */
+  readonly mode: 'live' | 'test';
 
   orders: {
     create(params: CreateOrderParams): Promise<Order>;
-    fetch(orderId: string): Promise<OrderStatus>;
+    fetch(orderId: string): Promise<Order>;
     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;
+    verify(rawBody: string | Buffer, signature: string, timestamp: string | number, secret?: string): boolean;
+    /** Verifies signature + ±5min timestamp tolerance. Throws PayuLinkError if invalid. */
+    constructEvent(rawBody: string | Buffer, headers: Record<string, any>, secret?: string): WebhookEvent;
   };
 
-  verifyPaymentSignature(p: { order_id: string; utr?: string | null; signature: string }): boolean;
+  /** signature = HMAC_SHA256(order_id + "|" + payment_id, key_secret) */
+  verifyPaymentSignature(p: PaymentHandoff): boolean;
 }

package/dist/payulink-server.cjs

@@ -29,52 +29,62 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var src_exports = {};
 __export(src_exports, {
-  PayulinkError: () => PayulinkError,
-  default: () => Payulink
+  PayuLinkError: () => PayuLinkError,
+  default: () => PayuLink,
+  rupees: () => rupees,
+  toRupees: () => toRupees
 });
 module.exports = __toCommonJS(src_exports);
 var import_node_crypto = __toESM(require("node:crypto"), 1);
-var PayulinkError = class extends Error {
-  constructor(message, { status, body } = {}) {
+var rupees = (r) => Math.round(Number(r) * 100);
+var toRupees = (paise) => Number(paise) / 100;
+var PayuLinkError = class 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 && import_node_crypto.default.timingSafeEqual(ba, bb);
 }
-var Payulink = class {
+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.
+   * @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_\u2026) is required");
+    if (!opts.keyId) throw new PayuLinkError("`keyId` (pl_live_\u2026 / pl_test_\u2026) 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 || 15e3;
+    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"
     };
-    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;
@@ -83,15 +93,14 @@ var Payulink = class {
         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) : void 0,
         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 = {};
@@ -99,64 +108,122 @@ var Payulink = class {
       data = await res.json();
     } catch {
     }
-    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 (\u20B91). Tip: use the `rupees()` helper \u2014 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 = import_node_crypto.default.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 = import_node_crypto.default.createHmac("sha256", this.keySecret).update(`${orderId}|${paymentId}`).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");
+  /**
+   * 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=" + import_node_crypto.default.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) : void 0);
+    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 });
+    const ageSec = Math.abs(Date.now() - Number(timestamp)) / 1e3;
+    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 {
-      return JSON.parse(String(rawBody));
+      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 });
+      throw new PayuLinkError("Invalid webhook JSON", { status: 400 });
     }
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  PayulinkError
+  PayuLinkError,
+  rupees,
+  toRupees
 });
 (()=>{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

@@ -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.1",
+  "description": "PayuLink server SDK — create orders and verify payments/webhooks with your key_secret.",
   "type": "module",
   "main": "./dist/payulink-server.cjs",
   "module": "./src/index.js",
@@ -22,10 +22,10 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "node build.mjs"
+    "build": "node build.mjs",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
-    "eliteyatra",
     "payulink",
     "payment",
     "server",
@@ -34,9 +34,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 }); }
   }
 }