orvex-pay 1.1.0 → 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OrvexPay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -49,7 +49,26 @@ Currently, this SDK supports the `invoices` resource.
 Creates a new payment invoice and returns an `InvoiceResponse` containing the `payUrl`.
 
 ### `orvex.invoices.retrieve(invoiceId)`
-Gets the status of an existing invoice using its `invoiceId`. 
+Gets the status of an existing invoice using its `invoiceId`.
+
+## Webhook Security
+
+To ensure that a webhook was actually sent by OrvexPay, you should verify the signature.
+
+```typescript
+import { OrvexClient } from 'orvex-pay';
+
+// Use the raw body of the request
+const isValid = OrvexClient.webhooks.verifySignature(
+  req.rawBody, 
+  req.headers['x-orvex-signature'], 
+  process.env.ORVEX_WEBHOOK_SECRET
+);
+
+if (isValid) {
+  // Process the payment event
+}
+```
 
 ---
 

package/dist/index.d.mts

@@ -27,6 +27,7 @@ interface InvoiceResponse {
     payAmount: number;
     payCurrency: string;
     priceAmountInUsd?: number;
+    amountReceived?: number;
     payAddress: string;
     status: string;
     createdAt: string;
@@ -43,6 +44,7 @@ interface OrvexApiClientOptions {
 declare class InvoicesResource {
     private client;
     constructor(client: AxiosInstance);
+    private handleError;
     /**
      * Creates a new payment invoice.
      * @param params
@@ -51,16 +53,38 @@ declare class InvoicesResource {
     create(params: CreateInvoiceRequest): Promise<InvoiceResponse>;
     /**
      * Retrieves an invoice by its invoiceId.
-     * @param id The invoice ID returned by the initial API call
+     * @param invoiceId The invoice ID returned by the initial API call
      * @returns
      */
     retrieve(invoiceId: string): Promise<InvoiceResponse>;
 }
 
+declare class Webhooks {
+    /**
+     * Verifies the signature of an incoming webhook from OrvexPay.
+     *
+     * @param payload Raw string body of the webhook request.
+     * @param signature The signature from the 'x-orvex-signature' header.
+     * @param secret Your webhook secret from the Merchant Dashboard.
+     * @returns boolean
+     */
+    static verifySignature(payload: string, signature: string, secret: string): boolean;
+}
+
 declare class OrvexClient {
     invoices: InvoicesResource;
+    webhooks: typeof Webhooks;
     private readonly client;
     constructor(options: OrvexApiClientOptions);
 }
 
-export { type CreateInvoiceRequest, type InvoiceResponse, InvoicesResource, type OrvexApiClientOptions, OrvexClient };
+declare class OrvexError extends Error {
+    readonly statusCode?: number;
+    readonly responseData?: any;
+    constructor(message: string, statusCode?: number, responseData?: any);
+}
+declare class OrvexSignatureError extends OrvexError {
+    constructor(message: string);
+}
+
+export { type CreateInvoiceRequest, type InvoiceResponse, InvoicesResource, type OrvexApiClientOptions, OrvexClient, OrvexError, OrvexSignatureError, Webhooks, OrvexClient as default };

package/dist/index.d.ts

@@ -27,6 +27,7 @@ interface InvoiceResponse {
     payAmount: number;
     payCurrency: string;
     priceAmountInUsd?: number;
+    amountReceived?: number;
     payAddress: string;
     status: string;
     createdAt: string;
@@ -43,6 +44,7 @@ interface OrvexApiClientOptions {
 declare class InvoicesResource {
     private client;
     constructor(client: AxiosInstance);
+    private handleError;
     /**
      * Creates a new payment invoice.
      * @param params
@@ -51,16 +53,38 @@ declare class InvoicesResource {
     create(params: CreateInvoiceRequest): Promise<InvoiceResponse>;
     /**
      * Retrieves an invoice by its invoiceId.
-     * @param id The invoice ID returned by the initial API call
+     * @param invoiceId The invoice ID returned by the initial API call
      * @returns
      */
     retrieve(invoiceId: string): Promise<InvoiceResponse>;
 }
 
+declare class Webhooks {
+    /**
+     * Verifies the signature of an incoming webhook from OrvexPay.
+     *
+     * @param payload Raw string body of the webhook request.
+     * @param signature The signature from the 'x-orvex-signature' header.
+     * @param secret Your webhook secret from the Merchant Dashboard.
+     * @returns boolean
+     */
+    static verifySignature(payload: string, signature: string, secret: string): boolean;
+}
+
 declare class OrvexClient {
     invoices: InvoicesResource;
+    webhooks: typeof Webhooks;
     private readonly client;
     constructor(options: OrvexApiClientOptions);
 }
 
-export { type CreateInvoiceRequest, type InvoiceResponse, InvoicesResource, type OrvexApiClientOptions, OrvexClient };
+declare class OrvexError extends Error {
+    readonly statusCode?: number;
+    readonly responseData?: any;
+    constructor(message: string, statusCode?: number, responseData?: any);
+}
+declare class OrvexSignatureError extends OrvexError {
+    constructor(message: string);
+}
+
+export { type CreateInvoiceRequest, type InvoiceResponse, InvoicesResource, type OrvexApiClientOptions, OrvexClient, OrvexError, OrvexSignatureError, Webhooks, OrvexClient as default };

package/dist/index.js

@@ -31,19 +31,54 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   InvoicesResource: () => InvoicesResource,
-  OrvexClient: () => OrvexClient
+  OrvexClient: () => OrvexClient,
+  OrvexError: () => OrvexError,
+  OrvexSignatureError: () => OrvexSignatureError,
+  Webhooks: () => Webhooks,
+  default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
 var import_axios = __toESM(require("axios"));
 
+// src/errors.ts
+var OrvexError = class _OrvexError extends Error {
+  statusCode;
+  responseData;
+  constructor(message, statusCode, responseData) {
+    super(message);
+    this.name = "OrvexError";
+    this.statusCode = statusCode;
+    this.responseData = responseData;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _OrvexError);
+    }
+  }
+};
+var OrvexSignatureError = class extends OrvexError {
+  constructor(message) {
+    super(message, 401);
+    this.name = "OrvexSignatureError";
+  }
+};
+
 // src/resources/invoices.ts
 var InvoicesResource = class {
   client;
   constructor(client) {
     this.client = client;
   }
+  handleError(error) {
+    if (error.response && error.response.data) {
+      throw new OrvexError(
+        error.response.data.message || "OrvexPay API Error",
+        error.response.status,
+        error.response.data
+      );
+    }
+    throw error;
+  }
   /**
    * Creates a new payment invoice.
    * @param params 
@@ -54,15 +89,12 @@ var InvoicesResource = class {
       const response = await this.client.post("/api/invoice", params);
       return response.data;
     } catch (error) {
-      if (error.response && error.response.data) {
-        throw new Error(`OrvexPay API Error: ${JSON.stringify(error.response.data)}`);
-      }
-      throw error;
+      this.handleError(error);
     }
   }
   /**
    * Retrieves an invoice by its invoiceId.
-   * @param id The invoice ID returned by the initial API call
+   * @param invoiceId The invoice ID returned by the initial API call
    * @returns 
    */
   async retrieve(invoiceId) {
@@ -70,21 +102,44 @@ var InvoicesResource = class {
       const response = await this.client.get(`/api/invoice/${invoiceId}`);
       return response.data;
     } catch (error) {
-      if (error.response && error.response.data) {
-        throw new Error(`OrvexPay API Error: ${JSON.stringify(error.response.data)}`);
-      }
-      throw error;
+      this.handleError(error);
     }
   }
 };
 
+// src/webhooks.ts
+var crypto = __toESM(require("crypto"));
+var Webhooks = class {
+  /**
+   * Verifies the signature of an incoming webhook from OrvexPay.
+   * 
+   * @param payload Raw string body of the webhook request.
+   * @param signature The signature from the 'x-orvex-signature' header.
+   * @param secret Your webhook secret from the Merchant Dashboard.
+   * @returns boolean
+   */
+  static verifySignature(payload, signature, secret) {
+    if (!signature || !secret) {
+      throw new OrvexSignatureError("Missing signature or webhook secret.");
+    }
+    const expectedSignature = crypto.createHmac("sha256", secret).update(payload).digest("hex");
+    const signatureBuffer = Buffer.from(signature);
+    const expectedBuffer = Buffer.from(expectedSignature);
+    if (signatureBuffer.length !== expectedBuffer.length || !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) {
+      throw new OrvexSignatureError("Invalid webhook signature.");
+    }
+    return true;
+  }
+};
+
 // src/client.ts
 var OrvexClient = class {
   invoices;
+  webhooks = Webhooks;
   client;
   constructor(options) {
     if (!options.apiKey) {
-      throw new Error("OrvexPay: apiKey is required to initialize the client.");
+      throw new OrvexError("OrvexPay: apiKey is required to initialize the client.");
     }
     this.client = import_axios.default.create({
       baseURL: options.baseURL ? options.baseURL.replace(/\/$/, "") : "https://api.orvexpay.com",
@@ -97,8 +152,14 @@ var OrvexClient = class {
     this.invoices = new InvoicesResource(this.client);
   }
 };
+
+// src/index.ts
+var index_default = OrvexClient;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   InvoicesResource,
-  OrvexClient
+  OrvexClient,
+  OrvexError,
+  OrvexSignatureError,
+  Webhooks
 });

package/dist/index.mjs

@@ -1,12 +1,43 @@
 // src/client.ts
 import axios from "axios";
 
+// src/errors.ts
+var OrvexError = class _OrvexError extends Error {
+  statusCode;
+  responseData;
+  constructor(message, statusCode, responseData) {
+    super(message);
+    this.name = "OrvexError";
+    this.statusCode = statusCode;
+    this.responseData = responseData;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _OrvexError);
+    }
+  }
+};
+var OrvexSignatureError = class extends OrvexError {
+  constructor(message) {
+    super(message, 401);
+    this.name = "OrvexSignatureError";
+  }
+};
+
 // src/resources/invoices.ts
 var InvoicesResource = class {
   client;
   constructor(client) {
     this.client = client;
   }
+  handleError(error) {
+    if (error.response && error.response.data) {
+      throw new OrvexError(
+        error.response.data.message || "OrvexPay API Error",
+        error.response.status,
+        error.response.data
+      );
+    }
+    throw error;
+  }
   /**
    * Creates a new payment invoice.
    * @param params 
@@ -17,15 +48,12 @@ var InvoicesResource = class {
       const response = await this.client.post("/api/invoice", params);
       return response.data;
     } catch (error) {
-      if (error.response && error.response.data) {
-        throw new Error(`OrvexPay API Error: ${JSON.stringify(error.response.data)}`);
-      }
-      throw error;
+      this.handleError(error);
     }
   }
   /**
    * Retrieves an invoice by its invoiceId.
-   * @param id The invoice ID returned by the initial API call
+   * @param invoiceId The invoice ID returned by the initial API call
    * @returns 
    */
   async retrieve(invoiceId) {
@@ -33,21 +61,44 @@ var InvoicesResource = class {
       const response = await this.client.get(`/api/invoice/${invoiceId}`);
       return response.data;
     } catch (error) {
-      if (error.response && error.response.data) {
-        throw new Error(`OrvexPay API Error: ${JSON.stringify(error.response.data)}`);
-      }
-      throw error;
+      this.handleError(error);
     }
   }
 };
 
+// src/webhooks.ts
+import * as crypto from "crypto";
+var Webhooks = class {
+  /**
+   * Verifies the signature of an incoming webhook from OrvexPay.
+   * 
+   * @param payload Raw string body of the webhook request.
+   * @param signature The signature from the 'x-orvex-signature' header.
+   * @param secret Your webhook secret from the Merchant Dashboard.
+   * @returns boolean
+   */
+  static verifySignature(payload, signature, secret) {
+    if (!signature || !secret) {
+      throw new OrvexSignatureError("Missing signature or webhook secret.");
+    }
+    const expectedSignature = crypto.createHmac("sha256", secret).update(payload).digest("hex");
+    const signatureBuffer = Buffer.from(signature);
+    const expectedBuffer = Buffer.from(expectedSignature);
+    if (signatureBuffer.length !== expectedBuffer.length || !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) {
+      throw new OrvexSignatureError("Invalid webhook signature.");
+    }
+    return true;
+  }
+};
+
 // src/client.ts
 var OrvexClient = class {
   invoices;
+  webhooks = Webhooks;
   client;
   constructor(options) {
     if (!options.apiKey) {
-      throw new Error("OrvexPay: apiKey is required to initialize the client.");
+      throw new OrvexError("OrvexPay: apiKey is required to initialize the client.");
     }
     this.client = axios.create({
       baseURL: options.baseURL ? options.baseURL.replace(/\/$/, "") : "https://api.orvexpay.com",
@@ -60,7 +111,14 @@ var OrvexClient = class {
     this.invoices = new InvoicesResource(this.client);
   }
 };
+
+// src/index.ts
+var index_default = OrvexClient;
 export {
   InvoicesResource,
-  OrvexClient
+  OrvexClient,
+  OrvexError,
+  OrvexSignatureError,
+  Webhooks,
+  index_default as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orvex-pay",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Official Node.js SDK for the OrvexPay API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/client.ts

@@ -1,14 +1,17 @@
 import axios, { AxiosInstance } from 'axios';
 import { OrvexApiClientOptions } from './types';
 import { InvoicesResource } from './resources/invoices';
+import { Webhooks } from './webhooks';
+import { OrvexError } from './errors';
 
 export class OrvexClient {
     public invoices: InvoicesResource;
+    public webhooks = Webhooks;
     private readonly client: AxiosInstance;
 
     constructor(options: OrvexApiClientOptions) {
         if (!options.apiKey) {
-            throw new Error('OrvexPay: apiKey is required to initialize the client.');
+            throw new OrvexError('OrvexPay: apiKey is required to initialize the client.');
         }
 
         this.client = axios.create({

package/src/errors.ts

@@ -0,0 +1,23 @@
+export class OrvexError extends Error {
+    public readonly statusCode?: number;
+    public readonly responseData?: any;
+
+    constructor(message: string, statusCode?: number, responseData?: any) {
+        super(message);
+        this.name = 'OrvexError';
+        this.statusCode = statusCode;
+        this.responseData = responseData;
+
+        // Ensure stack trace is correctly captured in Node.js
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, OrvexError);
+        }
+    }
+}
+
+export class OrvexSignatureError extends OrvexError {
+    constructor(message: string) {
+        super(message, 401);
+        this.name = 'OrvexSignatureError';
+    }
+}

package/src/index.ts

@@ -1,3 +1,8 @@
+import { OrvexClient } from './client';
 export * from './client';
 export * from './types';
+export * from './errors';
+export * from './webhooks';
 export * from './resources/invoices';
+
+export default OrvexClient;

package/src/resources/invoices.ts

@@ -1,5 +1,6 @@
 import { AxiosInstance } from 'axios';
 import { CreateInvoiceRequest, InvoiceResponse } from '../types';
+import { OrvexError } from '../errors';
 
 export class InvoicesResource {
     private client: AxiosInstance;
@@ -8,6 +9,17 @@ export class InvoicesResource {
         this.client = client;
     }
 
+    private handleError(error: any): never {
+        if (error.response && error.response.data) {
+            throw new OrvexError(
+                error.response.data.message || 'OrvexPay API Error',
+                error.response.status,
+                error.response.data
+            );
+        }
+        throw error;
+    }
+
     /**
      * Creates a new payment invoice.
      * @param params 
@@ -18,16 +30,13 @@ export class InvoicesResource {
             const response = await this.client.post<InvoiceResponse>('/api/invoice', params);
             return response.data;
         } catch (error: any) {
-            if (error.response && error.response.data) {
-                throw new Error(`OrvexPay API Error: ${JSON.stringify(error.response.data)}`);
-            }
-            throw error;
+            this.handleError(error);
         }
     }
 
     /**
      * Retrieves an invoice by its invoiceId.
-     * @param id The invoice ID returned by the initial API call
+     * @param invoiceId The invoice ID returned by the initial API call
      * @returns 
      */
     async retrieve(invoiceId: string): Promise<InvoiceResponse> {
@@ -35,10 +44,7 @@ export class InvoicesResource {
             const response = await this.client.get<InvoiceResponse>(`/api/invoice/${invoiceId}`);
             return response.data;
         } catch (error: any) {
-            if (error.response && error.response.data) {
-                throw new Error(`OrvexPay API Error: ${JSON.stringify(error.response.data)}`);
-            }
-            throw error;
+            this.handleError(error);
         }
     }
 }

package/src/types.ts

@@ -26,6 +26,7 @@ export interface InvoiceResponse {
     payAmount: number;
     payCurrency: string;
     priceAmountInUsd?: number;
+    amountReceived?: number;
     payAddress: string;
     status: string;
     createdAt: string;

package/src/webhooks.ts

@@ -0,0 +1,32 @@
+import * as crypto from 'crypto';
+import { OrvexSignatureError } from './errors';
+
+export class Webhooks {
+    /**
+     * Verifies the signature of an incoming webhook from OrvexPay.
+     * 
+     * @param payload Raw string body of the webhook request.
+     * @param signature The signature from the 'x-orvex-signature' header.
+     * @param secret Your webhook secret from the Merchant Dashboard.
+     * @returns boolean
+     */
+    static verifySignature(payload: string, signature: string, secret: string): boolean {
+        if (!signature || !secret) {
+            throw new OrvexSignatureError('Missing signature or webhook secret.');
+        }
+
+        const expectedSignature = crypto
+            .createHmac('sha256', secret)
+            .update(payload)
+            .digest('hex');
+
+        const signatureBuffer = Buffer.from(signature);
+        const expectedBuffer = Buffer.from(expectedSignature);
+
+        if (signatureBuffer.length !== expectedBuffer.length || !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) {
+            throw new OrvexSignatureError('Invalid webhook signature.');
+        }
+
+        return true;
+    }
+}