@pague-dev/sdk-node 0.5.0 → 1.1.0

package/README.md

@@ -19,9 +19,12 @@ const pdev = new Pdev('pd_live_sua_api_key');
 // Opção 2: Usar variável de ambiente PDEV_API_KEY
 const pdev = new Pdev();
 
-// PIX
+// PIX Dinâmico
 await pdev.pix.create({ amount, description, customer });
 
+// PIX QR Code Estático
+await pdev.pix.createStaticQrCode({ amount, description });
+
 // Charges
 await pdev.charges.create({ projectId, name, amount, paymentMethods });
 await pdev.charges.list({ page, limit });
@@ -49,7 +52,7 @@ const event = parseWebhook(req.body);
 
 ## Recursos
 
-- **PIX** - Cobranças instantâneas
+- **PIX** - Cobranças instantâneas (dinâmico e estático)
 - **Charges** - Links de pagamento
 - **Customers** - Gestão de clientes
 - **Projects** - Organização por projetos

package/dist/index.cjs

@@ -1,3 +1,4 @@
+let node_crypto = require("node:crypto");
 
 //#region src/common/utils/build-pagination-query.ts
 function buildPaginationQuery(options) {
@@ -261,6 +262,40 @@ function isValidWebhookEvent(event) {
 * });
 * ```
 */
+/**
+* Verifies the HMAC-SHA256 signature of a webhook payload.
+*
+* @param payload - The raw request body as a string
+* @param signature - The signature from the `X-Webhook-Signature` header
+* @param secret - Your webhook secret (plain text, before hashing)
+* @returns `true` if the signature is valid, `false` otherwise
+*
+* @example
+* ```typescript
+* import { verifyWebhookSignature, parseWebhook } from '@pague-dev/sdk-node';
+*
+* app.post('/webhook', (req, res) => {
+*   const signature = req.headers['x-webhook-signature'] as string;
+*   const rawBody = req.body; // raw string body
+*
+*   if (!verifyWebhookSignature(rawBody, signature, 'your_webhook_secret')) {
+*     return res.status(401).send('Invalid signature');
+*   }
+*
+*   const event = parseWebhook(rawBody);
+*   // handle event...
+* });
+* ```
+*/
+function verifyWebhookSignature(payload, signature, secret) {
+	if (!payload || !signature || !secret) return false;
+	try {
+		const expected = (0, node_crypto.createHmac)("sha256", (0, node_crypto.createHash)("sha256").update(secret).digest("hex")).update(payload).digest("hex");
+		return (0, node_crypto.timingSafeEqual)(Buffer.from(expected, "hex"), Buffer.from(signature, "hex"));
+	} catch {
+		return false;
+	}
+}
 function parseWebhook(payload) {
 	let parsed;
 	try {
@@ -274,4 +309,5 @@ function parseWebhook(payload) {
 
 //#endregion
 exports.Pdev = Pdev;
-exports.parseWebhook = parseWebhook;
+exports.parseWebhook = parseWebhook;
+exports.verifyWebhookSignature = verifyWebhookSignature;

package/dist/index.d.cts

@@ -194,15 +194,11 @@ interface CreatePixOptions {
 type CreatePixResponse = Response<PixCharge>;
 //#endregion
 //#region src/pix/interfaces/static-qr-code.interface.d.ts
-interface StaticQrCodeTransaction {
-  description: string;
-  amount: number;
-  comment?: string;
-  externalReference?: string;
-}
 interface CreateStaticQrCodeOptions {
-  transaction: StaticQrCodeTransaction;
+  amount: number;
+  description: string;
   projectId?: string;
+  externalReference?: string;
   metadata?: Record<string, unknown>;
 }
 interface StaticQrCode {
@@ -542,6 +538,32 @@ interface WebhookHeaders {
  * });
  * ```
  */
+/**
+ * Verifies the HMAC-SHA256 signature of a webhook payload.
+ *
+ * @param payload - The raw request body as a string
+ * @param signature - The signature from the `X-Webhook-Signature` header
+ * @param secret - Your webhook secret (plain text, before hashing)
+ * @returns `true` if the signature is valid, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature, parseWebhook } from '@pague-dev/sdk-node';
+ *
+ * app.post('/webhook', (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const rawBody = req.body; // raw string body
+ *
+ *   if (!verifyWebhookSignature(rawBody, signature, 'your_webhook_secret')) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = parseWebhook(rawBody);
+ *   // handle event...
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
 declare function parseWebhook(payload: string): WebhookEvent | null;
 //#endregion
-export { Charge, ChargeStatus, CreateChargeOptions, CreateChargeResponse, CreateCustomerOptions, CreateCustomerResponse, CreatePixCustomer, CreatePixOptions, CreatePixResponse, CreateProjectOptions, CreateProjectResponse, CreateStaticQrCodeOptions, CreateStaticQrCodeResponse, CreateWithdrawalOptions, CreateWithdrawalResponse, Customer, DocumentType, type ErrorResponse, GetChargeResponse, GetTransactionResponse, ListChargesOptions, ListChargesResponse, ListCustomersOptions, ListCustomersResponse, ListProjectsOptions, ListProjectsResponse, NotificationType, type PaginatedResponse, type PaginationOptions, PaymentCompletedData, PaymentCompletedEvent, PaymentMethod, Pdev, PixCharge, PixKeyType, PixStatus, Project, RefundCompletedData, RefundCompletedEvent, type Response, SortBy, SortOrder, StaticQrCode, StaticQrCodeTransaction, Transaction, TransactionPaymentMethod, TransactionStatus, TransactionType, WebhookEvent, WebhookEventType, WebhookHeaders, WebhookPayload, Withdrawal, WithdrawalCompletedData, WithdrawalCompletedEvent, WithdrawalFailedData, WithdrawalFailedEvent, WithdrawalStatus, parseWebhook };
+export { Charge, ChargeStatus, CreateChargeOptions, CreateChargeResponse, CreateCustomerOptions, CreateCustomerResponse, CreatePixCustomer, CreatePixOptions, CreatePixResponse, CreateProjectOptions, CreateProjectResponse, CreateStaticQrCodeOptions, CreateStaticQrCodeResponse, CreateWithdrawalOptions, CreateWithdrawalResponse, Customer, DocumentType, type ErrorResponse, GetChargeResponse, GetTransactionResponse, ListChargesOptions, ListChargesResponse, ListCustomersOptions, ListCustomersResponse, ListProjectsOptions, ListProjectsResponse, NotificationType, type PaginatedResponse, type PaginationOptions, PaymentCompletedData, PaymentCompletedEvent, PaymentMethod, Pdev, PixCharge, PixKeyType, PixStatus, Project, RefundCompletedData, RefundCompletedEvent, type Response, SortBy, SortOrder, StaticQrCode, Transaction, TransactionPaymentMethod, TransactionStatus, TransactionType, WebhookEvent, WebhookEventType, WebhookHeaders, WebhookPayload, Withdrawal, WithdrawalCompletedData, WithdrawalCompletedEvent, WithdrawalFailedData, WithdrawalFailedEvent, WithdrawalStatus, parseWebhook, verifyWebhookSignature };

package/dist/index.d.mts

@@ -194,15 +194,11 @@ interface CreatePixOptions {
 type CreatePixResponse = Response<PixCharge>;
 //#endregion
 //#region src/pix/interfaces/static-qr-code.interface.d.ts
-interface StaticQrCodeTransaction {
-  description: string;
-  amount: number;
-  comment?: string;
-  externalReference?: string;
-}
 interface CreateStaticQrCodeOptions {
-  transaction: StaticQrCodeTransaction;
+  amount: number;
+  description: string;
   projectId?: string;
+  externalReference?: string;
   metadata?: Record<string, unknown>;
 }
 interface StaticQrCode {
@@ -542,6 +538,32 @@ interface WebhookHeaders {
  * });
  * ```
  */
+/**
+ * Verifies the HMAC-SHA256 signature of a webhook payload.
+ *
+ * @param payload - The raw request body as a string
+ * @param signature - The signature from the `X-Webhook-Signature` header
+ * @param secret - Your webhook secret (plain text, before hashing)
+ * @returns `true` if the signature is valid, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature, parseWebhook } from '@pague-dev/sdk-node';
+ *
+ * app.post('/webhook', (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const rawBody = req.body; // raw string body
+ *
+ *   if (!verifyWebhookSignature(rawBody, signature, 'your_webhook_secret')) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = parseWebhook(rawBody);
+ *   // handle event...
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
 declare function parseWebhook(payload: string): WebhookEvent | null;
 //#endregion
-export { Charge, ChargeStatus, CreateChargeOptions, CreateChargeResponse, CreateCustomerOptions, CreateCustomerResponse, CreatePixCustomer, CreatePixOptions, CreatePixResponse, CreateProjectOptions, CreateProjectResponse, CreateStaticQrCodeOptions, CreateStaticQrCodeResponse, CreateWithdrawalOptions, CreateWithdrawalResponse, Customer, DocumentType, type ErrorResponse, GetChargeResponse, GetTransactionResponse, ListChargesOptions, ListChargesResponse, ListCustomersOptions, ListCustomersResponse, ListProjectsOptions, ListProjectsResponse, NotificationType, type PaginatedResponse, type PaginationOptions, PaymentCompletedData, PaymentCompletedEvent, PaymentMethod, Pdev, PixCharge, PixKeyType, PixStatus, Project, RefundCompletedData, RefundCompletedEvent, type Response, SortBy, SortOrder, StaticQrCode, StaticQrCodeTransaction, Transaction, TransactionPaymentMethod, TransactionStatus, TransactionType, WebhookEvent, WebhookEventType, WebhookHeaders, WebhookPayload, Withdrawal, WithdrawalCompletedData, WithdrawalCompletedEvent, WithdrawalFailedData, WithdrawalFailedEvent, WithdrawalStatus, parseWebhook };
+export { Charge, ChargeStatus, CreateChargeOptions, CreateChargeResponse, CreateCustomerOptions, CreateCustomerResponse, CreatePixCustomer, CreatePixOptions, CreatePixResponse, CreateProjectOptions, CreateProjectResponse, CreateStaticQrCodeOptions, CreateStaticQrCodeResponse, CreateWithdrawalOptions, CreateWithdrawalResponse, Customer, DocumentType, type ErrorResponse, GetChargeResponse, GetTransactionResponse, ListChargesOptions, ListChargesResponse, ListCustomersOptions, ListCustomersResponse, ListProjectsOptions, ListProjectsResponse, NotificationType, type PaginatedResponse, type PaginationOptions, PaymentCompletedData, PaymentCompletedEvent, PaymentMethod, Pdev, PixCharge, PixKeyType, PixStatus, Project, RefundCompletedData, RefundCompletedEvent, type Response, SortBy, SortOrder, StaticQrCode, Transaction, TransactionPaymentMethod, TransactionStatus, TransactionType, WebhookEvent, WebhookEventType, WebhookHeaders, WebhookPayload, Withdrawal, WithdrawalCompletedData, WithdrawalCompletedEvent, WithdrawalFailedData, WithdrawalFailedEvent, WithdrawalStatus, parseWebhook, verifyWebhookSignature };

package/dist/index.mjs

@@ -1,3 +1,5 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+
 //#region src/common/utils/build-pagination-query.ts
 function buildPaginationQuery(options) {
 	const searchParams = new URLSearchParams();
@@ -260,6 +262,40 @@ function isValidWebhookEvent(event) {
 * });
 * ```
 */
+/**
+* Verifies the HMAC-SHA256 signature of a webhook payload.
+*
+* @param payload - The raw request body as a string
+* @param signature - The signature from the `X-Webhook-Signature` header
+* @param secret - Your webhook secret (plain text, before hashing)
+* @returns `true` if the signature is valid, `false` otherwise
+*
+* @example
+* ```typescript
+* import { verifyWebhookSignature, parseWebhook } from '@pague-dev/sdk-node';
+*
+* app.post('/webhook', (req, res) => {
+*   const signature = req.headers['x-webhook-signature'] as string;
+*   const rawBody = req.body; // raw string body
+*
+*   if (!verifyWebhookSignature(rawBody, signature, 'your_webhook_secret')) {
+*     return res.status(401).send('Invalid signature');
+*   }
+*
+*   const event = parseWebhook(rawBody);
+*   // handle event...
+* });
+* ```
+*/
+function verifyWebhookSignature(payload, signature, secret) {
+	if (!payload || !signature || !secret) return false;
+	try {
+		const expected = createHmac("sha256", createHash("sha256").update(secret).digest("hex")).update(payload).digest("hex");
+		return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(signature, "hex"));
+	} catch {
+		return false;
+	}
+}
 function parseWebhook(payload) {
 	let parsed;
 	try {
@@ -272,4 +308,4 @@ function parseWebhook(payload) {
 }
 
 //#endregion
-export { Pdev, parseWebhook };
+export { Pdev, parseWebhook, verifyWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pague-dev/sdk-node",
-  "version": "0.5.0",
+  "version": "1.1.0",
   "description": "Node.js SDK for the pague.dev API",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",