@pague-dev/sdk-node 1.0.0 → 1.2.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 });
@@ -43,19 +46,25 @@ await pdev.withdrawals.create({ amount, bankAccountId });
 await pdev.transactions.get(id);
 
 // Webhooks
-import { parseWebhook } from '@pague-dev/sdk-node';
+import { verifyWebhookSignature, parseWebhook } from '@pague-dev/sdk-node';
+
+const signature = req.headers['x-webhook-signature'] as string;
+if (!verifyWebhookSignature(req.body, signature, 'your_webhook_secret')) {
+  return res.status(401).send('Invalid signature');
+}
+
 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
 - **Withdrawals** - Saques via PIX (avulso ou conta salva)
 - **Transactions** - Consulta de transações
-- **Webhooks** - Notificações em tempo real
+- **Webhooks** - Verificação de assinatura e parsing de eventos
 
 ## Exemplo
 

package/dist/index.cjs

@@ -1,4 +1,17 @@
+let node_crypto = require("node:crypto");
 
+//#region src/account/account.ts
+var Account = class {
+	endpoint = "/account";
+	constructor(pdev) {
+		this.pdev = pdev;
+	}
+	async get() {
+		return this.pdev.get(this.endpoint);
+	}
+};
+
+//#endregion
 //#region src/common/utils/build-pagination-query.ts
 function buildPaginationQuery(options) {
 	const searchParams = new URLSearchParams();
@@ -109,6 +122,7 @@ var Pdev = class {
 	key;
 	baseUrl;
 	headers;
+	account;
 	pix;
 	customers;
 	projects;
@@ -126,6 +140,7 @@ var Pdev = class {
 			"X-API-Key": this.key,
 			"Content-Type": "application/json"
 		});
+		this.account = new Account(this);
 		this.pix = new Pix(this);
 		this.customers = new Customers(this);
 		this.projects = new Projects(this);
@@ -261,6 +276,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 +323,5 @@ function parseWebhook(payload) {
 
 //#endregion
 exports.Pdev = Pdev;
-exports.parseWebhook = parseWebhook;
+exports.parseWebhook = parseWebhook;
+exports.verifyWebhookSignature = verifyWebhookSignature;

package/dist/index.d.cts

@@ -1,3 +1,35 @@
+//#region src/account/interfaces/account-info.interface.d.ts
+type AccountStatus = 'approved' | 'pending' | 'pending_documents' | 'pending_approval' | 'rejected' | 'suspended';
+type CompanyStatus = 'pending' | 'active' | 'suspended' | 'blocked';
+interface BalanceAmount {
+  amount: number;
+  amountFormatted: number;
+}
+interface AccountDetail {
+  id: string;
+  status: AccountStatus;
+}
+interface CompanyDetail {
+  razaoSocial: string;
+  nomeFantasia?: string;
+  cnpj: string;
+  email: string;
+  phone: string;
+  status: CompanyStatus;
+}
+interface BalanceDetail {
+  available: BalanceAmount;
+  promotional: BalanceAmount;
+  total: BalanceAmount;
+  currency: string;
+  updatedAt: string;
+}
+interface AccountInfo {
+  account: AccountDetail;
+  company: CompanyDetail | null;
+  balance: BalanceDetail;
+}
+//#endregion
 //#region src/charges/interfaces/charge.interface.d.ts
 type ChargeStatus = 'active' | 'expired' | 'disabled' | 'paid';
 type PaymentMethod = 'pix' | 'credit_card' | 'boleto';
@@ -108,6 +140,14 @@ interface ListCustomersOptions extends PaginationOptions {
 }
 type ListCustomersResponse = Response<PaginatedResponse<Customer>>;
 //#endregion
+//#region src/account/account.d.ts
+declare class Account {
+  private readonly pdev;
+  private readonly endpoint;
+  constructor(pdev: Pdev);
+  get(): Promise<Response<AccountInfo>>;
+}
+//#endregion
 //#region src/common/base-resource.d.ts
 /**
  * Base class for API resources that follow CRUD patterns.
@@ -326,6 +366,7 @@ declare class Pdev {
   readonly key: string;
   private readonly baseUrl;
   private readonly headers;
+  readonly account: Account;
   readonly pix: Pix;
   readonly customers: Customers;
   readonly projects: Projects;
@@ -538,6 +579,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, Transaction, TransactionPaymentMethod, TransactionStatus, TransactionType, WebhookEvent, WebhookEventType, WebhookHeaders, WebhookPayload, Withdrawal, WithdrawalCompletedData, WithdrawalCompletedEvent, WithdrawalFailedData, WithdrawalFailedEvent, WithdrawalStatus, parseWebhook };
+export { AccountDetail, AccountInfo, AccountStatus, BalanceAmount, BalanceDetail, Charge, ChargeStatus, CompanyDetail, CompanyStatus, 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

@@ -1,3 +1,35 @@
+//#region src/account/interfaces/account-info.interface.d.ts
+type AccountStatus = 'approved' | 'pending' | 'pending_documents' | 'pending_approval' | 'rejected' | 'suspended';
+type CompanyStatus = 'pending' | 'active' | 'suspended' | 'blocked';
+interface BalanceAmount {
+  amount: number;
+  amountFormatted: number;
+}
+interface AccountDetail {
+  id: string;
+  status: AccountStatus;
+}
+interface CompanyDetail {
+  razaoSocial: string;
+  nomeFantasia?: string;
+  cnpj: string;
+  email: string;
+  phone: string;
+  status: CompanyStatus;
+}
+interface BalanceDetail {
+  available: BalanceAmount;
+  promotional: BalanceAmount;
+  total: BalanceAmount;
+  currency: string;
+  updatedAt: string;
+}
+interface AccountInfo {
+  account: AccountDetail;
+  company: CompanyDetail | null;
+  balance: BalanceDetail;
+}
+//#endregion
 //#region src/charges/interfaces/charge.interface.d.ts
 type ChargeStatus = 'active' | 'expired' | 'disabled' | 'paid';
 type PaymentMethod = 'pix' | 'credit_card' | 'boleto';
@@ -108,6 +140,14 @@ interface ListCustomersOptions extends PaginationOptions {
 }
 type ListCustomersResponse = Response<PaginatedResponse<Customer>>;
 //#endregion
+//#region src/account/account.d.ts
+declare class Account {
+  private readonly pdev;
+  private readonly endpoint;
+  constructor(pdev: Pdev);
+  get(): Promise<Response<AccountInfo>>;
+}
+//#endregion
 //#region src/common/base-resource.d.ts
 /**
  * Base class for API resources that follow CRUD patterns.
@@ -326,6 +366,7 @@ declare class Pdev {
   readonly key: string;
   private readonly baseUrl;
   private readonly headers;
+  readonly account: Account;
   readonly pix: Pix;
   readonly customers: Customers;
   readonly projects: Projects;
@@ -538,6 +579,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, Transaction, TransactionPaymentMethod, TransactionStatus, TransactionType, WebhookEvent, WebhookEventType, WebhookHeaders, WebhookPayload, Withdrawal, WithdrawalCompletedData, WithdrawalCompletedEvent, WithdrawalFailedData, WithdrawalFailedEvent, WithdrawalStatus, parseWebhook };
+export { AccountDetail, AccountInfo, AccountStatus, BalanceAmount, BalanceDetail, Charge, ChargeStatus, CompanyDetail, CompanyStatus, 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,17 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+
+//#region src/account/account.ts
+var Account = class {
+	endpoint = "/account";
+	constructor(pdev) {
+		this.pdev = pdev;
+	}
+	async get() {
+		return this.pdev.get(this.endpoint);
+	}
+};
+
+//#endregion
 //#region src/common/utils/build-pagination-query.ts
 function buildPaginationQuery(options) {
 	const searchParams = new URLSearchParams();
@@ -108,6 +122,7 @@ var Pdev = class {
 	key;
 	baseUrl;
 	headers;
+	account;
 	pix;
 	customers;
 	projects;
@@ -125,6 +140,7 @@ var Pdev = class {
 			"X-API-Key": this.key,
 			"Content-Type": "application/json"
 		});
+		this.account = new Account(this);
 		this.pix = new Pix(this);
 		this.customers = new Customers(this);
 		this.projects = new Projects(this);
@@ -260,6 +276,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 +322,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": "1.0.0",
+  "version": "1.2.0",
   "description": "Node.js SDK for the pague.dev API",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",