@thepayulink/server 2.0.1 → 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

@@ -7,8 +7,12 @@ export interface PayuLinkOptions {
   keySecret: string;
   /** Gateway base URL. Default https://payulink.io/api */
   apiBase?: string;
-  /** Webhook signing secret (webhook_secret_v2). Falls back 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;
 }
@@ -24,7 +28,10 @@ export interface CreateOrderParams {
   notes?: Record<string, unknown>;
   /** Optional customer prefill. */
   customer?: { name?: string; contact?: string; email?: string };
-  /** Per-order webhook override. */
+  /**
+   * @deprecated Only affects legacy version-1 callbacks. Signed (v2) webhooks always go to
+   * the URL configured in the merchant panel.
+   */
   notifyUrl?: string;
 }
 
@@ -90,9 +97,9 @@ export default class PayuLink {
   };
 
   webhooks: {
-    verify(rawBody: string | Buffer, signature: string, timestamp: string | number, secret?: string): boolean;
+    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): WebhookEvent;
+    constructEvent(rawBody: string | Buffer, headers: Record<string, any>, secret?: string | string[]): WebhookEvent;
   };
 
   /** signature = HMAC_SHA256(order_id + "|" + payment_id, key_secret) */

package/dist/payulink-server.cjs

@@ -58,8 +58,10 @@ var PayuLink = class {
    * @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 = {}) {
@@ -68,7 +70,7 @@ var PayuLink = class {
     this.keyId = opts.keyId;
     this.keySecret = opts.keySecret;
     this.apiBase = String(opts.apiBase || "https://payulink.io/api").replace(/\/$/, "");
-    this.webhookSecret = opts.webhookSecret || opts.keySecret;
+    this.webhookSecret = opts.webhookSecret || null;
     this.timeout = opts.timeout || 15e3;
     this.mode = /^pl_test_/.test(opts.keyId) ? "test" : "live";
     this.orders = {
@@ -125,6 +127,10 @@ var PayuLink = class {
    * @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));
@@ -176,9 +182,11 @@ var PayuLink = class {
    */
   _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);
+    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 + parse a webhook. Throws if the signature is bad or the timestamp is
@@ -194,7 +202,7 @@ var PayuLink = class {
    *
    * @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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thepayulink/server",
-  "version": "2.0.1",
+  "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",

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) {