@thepayulink/server 2.0.0 → 2.1.0

package/README.md

@@ -22,8 +22,9 @@ Node 18+ (uses global `fetch`). Works with `import` and `require`.
 import PayuLink, { rupees } from '@thepayulink/server';
 
 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
+  keyId: process.env.PAYULINK_KEY_ID,                  // pl_live_… / pl_test_…
+  keySecret: process.env.PAYULINK_KEY_SECRET,          // backend only — never ship this
+  webhookSecret: process.env.PAYULINK_WEBHOOK_SECRET,  // whs_… from panel → Config (NOT keySecret)
 });
 
 // 1) Create an order for the TRUE amount, computed on your server.

package/dist/index.d.ts

@@ -1,81 +1,107 @@
-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). */
-  webhookSecret?: string;
+  /**
+   * Webhook signing secret (webhook_secret_v2, whs_…) from merchant panel → Config.
+   * Required to verify webhooks — it is NOT your keySecret. Pass [newSecret, oldSecret]
+   * while rotating.
+   */
+  webhookSecret?: string | 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 };
+  /**
+   * @deprecated Only affects legacy version-1 callbacks. Signed (v2) webhooks always go to
+   * the URL configured in the merchant panel.
+   */
+  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 | string[]): boolean;
+    /** Verifies signature + ±5min timestamp tolerance. Throws PayuLinkError if invalid. */
+    constructEvent(rawBody: string | Buffer, headers: Record<string, any>, secret?: string | 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,64 @@ 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|string[]} [opts.webhookSecret] Webhook signing secret (webhook_secret_v2,
+   *                                      whs_…, from merchant panel → Config). Required to verify
+   *                                      webhooks. Pass [new, old] while rotating — see constructEvent.
+   *                                      It is NOT your keySecret: the two are different secrets.
+   * @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.webhookSecret = opts.webhookSecret || opts.keySecret;
+    this.apiBase = String(opts.apiBase || "https://payulink.io/api").replace(/\/$/, "");
+    this.webhookSecret = opts.webhookSecret || null;
     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 +95,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 +110,128 @@ 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.
+   * @param {object} [p.customer]  { name, contact, email } — prefill for the checkout.
+   *
+   * Webhooks always go to the URL set in the merchant panel. (`notifyUrl` is still sent for
+   * backward compatibility but only affects legacy version-1 callbacks, not signed webhooks.)
    */
-  _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");
-    return safeEqual(expected, signature);
+  /**
+   * 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 keys = [].concat(secret || this.webhookSecret || []).filter(Boolean);
+    if (keys.length === 0) {
+      throw new PayuLinkError("No webhook secret: pass `webhookSecret` (whs_\u2026, merchant panel \u2192 Config) to new PayuLink({...}). Webhooks are not signed with your keySecret.");
+    }
+    return keys.some((key) => safeEqual("sha256=" + import_node_crypto.default.createHmac("sha256", key).update(`${timestamp}.${String(rawBody)}`).digest("hex"), 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|string[]} [secret]  Overrides opts.webhookSecret.
+   * @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": "2.0.0",
-  "description": "PayuLink server SDK \u2014 create orders and verify payments/webhooks with your key_secret.",
+  "version": "2.1.0",
+  "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,7 +22,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "node build.mjs"
+    "build": "node build.mjs",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "payulink",

package/src/index.js

@@ -41,8 +41,10 @@ export default class PayuLink {
    * @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 {string|string[]} [opts.webhookSecret] Webhook signing secret (webhook_secret_v2,
+   *                                      whs_…, from merchant panel → Config). Required to verify
+   *                                      webhooks. Pass [new, old] while rotating — see constructEvent.
+   *                                      It is NOT your keySecret: the two are different secrets.
    * @param {number} [opts.timeout]      Request timeout ms. Default 15000.
    */
   constructor(opts = {}) {
@@ -51,7 +53,9 @@ export default class PayuLink {
     this.keyId = opts.keyId;
     this.keySecret = opts.keySecret;
     this.apiBase = String(opts.apiBase || 'https://payulink.io/api').replace(/\/$/, '');
-    this.webhookSecret = opts.webhookSecret || opts.keySecret;
+    // No fallback to keySecret. Webhooks are never signed with it, so the old fallback
+    // turned a missing env var into "every webhook fails signature" with no clue why.
+    this.webhookSecret = opts.webhookSecret || null;
     this.timeout = opts.timeout || 15000;
     this.mode = /^pl_test_/.test(opts.keyId) ? 'test' : 'live';
 
@@ -109,6 +113,10 @@ export default class PayuLink {
    * @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.
+   * @param {object} [p.customer]  { name, contact, email } — prefill for the checkout.
+   *
+   * Webhooks always go to the URL set in the merchant panel. (`notifyUrl` is still sent for
+   * backward compatibility but only affects legacy version-1 callbacks, not signed webhooks.)
    */
   _createOrder(p = {}) {
     const amount = Math.round(Number(p.amount));
@@ -165,10 +173,16 @@ export default class PayuLink {
    */
   _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);
+    const keys = [].concat(secret || this.webhookSecret || []).filter(Boolean);
+    if (keys.length === 0) {
+      throw new PayuLinkError('No webhook secret: pass `webhookSecret` (whs_…, merchant panel → Config) '
+        + 'to new PayuLink({...}). Webhooks are not signed with your keySecret.');
+    }
+    // Several secrets are accepted so a rotation never drops events: deliveries already
+    // queued (and their retries, for up to ~30h) stay signed with the secret that was
+    // current when each event was created.
+    return keys.some((key) => safeEqual('sha256=' + crypto.createHmac('sha256', key)
+      .update(`${timestamp}.${String(rawBody)}`).digest('hex'), signature));
   }
 
   /**
@@ -185,7 +199,7 @@ export default class PayuLink {
    *
    * @param {string|Buffer} rawBody
    * @param {object} headers  The request headers object.
-   * @param {string} [secret]
+   * @param {string|string[]} [secret]  Overrides opts.webhookSecret.
    * @param {number} [toleranceSec=300]
    */
   _constructEvent(rawBody, headers = {}, secret, toleranceSec = 300) {