@bloque/payments 0.0.2 → 0.0.3

package/README.md

@@ -214,6 +214,59 @@ const checkout = await bloque.checkout.cancel('checkout_id_here');
 
 **Returns**: A `Checkout` object with updated status reflecting the cancellation.
 
+### Webhooks
+
+The webhooks resource allows you to verify the authenticity of webhook events sent from Bloque.
+
+#### Verify Webhook Signature
+
+Verify that a webhook event was actually sent by Bloque using HMAC-SHA256 signature verification.
+
+```typescript
+const isValid = bloque.webhooks.verify(
+  requestBody,
+  signatureHeader,
+  { secret: process.env.WEBHOOK_SECRET }
+);
+
+if (isValid) {
+  // Process the webhook event
+} else {
+  // Reject the webhook
+}
+```
+
+**Parameters**:
+- `body` (string | object): The raw webhook request body
+- `signature` (string): The signature from the `x-bloque-signature` header
+- `options` (optional): Verification options
+  - `secret` (string): Webhook secret key. Can be set during SDK initialization or passed here
+
+**Returns**: `boolean` - `true` if the webhook signature is valid, `false` otherwise
+
+**Configuration**:
+
+You can set the webhook secret during SDK initialization:
+
+```typescript
+const bloque = new Bloque({
+  apiKey: process.env.BLOQUE_API_KEY!,
+  server: 'production',
+  webhookSecret: process.env.BLOQUE_WEBHOOK_SECRET,
+});
+
+// Then you can verify without passing the secret each time
+const isValid = bloque.webhooks.verify(body, signature);
+```
+
+Or pass it directly during verification:
+
+```typescript
+const isValid = bloque.webhooks.verify(body, signature, {
+  secret: process.env.BLOQUE_WEBHOOK_SECRET,
+});
+```
+
 ## Examples
 
 ### Processing Payments
@@ -345,6 +398,61 @@ async function handlePayment(payload: PaymentSubmitPayload) {
 }
 ```
 
+### Webhook Handler
+
+Handle incoming webhook events from Bloque and verify their authenticity:
+
+```typescript
+import { Bloque } from '@bloque/payments';
+
+// Initialize SDK with webhook secret
+const bloque = new Bloque({
+  apiKey: process.env.BLOQUE_API_KEY!,
+  server: 'production',
+  webhookSecret: process.env.BLOQUE_WEBHOOK_SECRET,
+});
+
+// Webhook endpoint
+app.post(
+  '/webhooks/bloque',
+  (req, res) => {
+    const signature = req.headers['x-bloque-signature'] as string;
+
+    try {
+      // Verify the webhook signature
+      const isValid = bloque.webhooks.verify(req.body.toString(), signature);
+
+      if (!isValid) {
+        return res.status(400).send('Invalid signature');
+      }
+
+      // Parse and process the event
+      const event = JSON.parse(req.body.toString());
+
+      switch (event.type) {
+        case 'checkout.completed':
+          console.log('Checkout completed:', event.data);
+          // Update database, send confirmation, etc.
+          break;
+
+        case 'payment.succeeded':
+          console.log('Payment succeeded:', event.data);
+          break;
+
+        case 'payment.failed':
+          console.log('Payment failed:', event.data);
+          break;
+      }
+
+      res.json({ received: true });
+    } catch (error) {
+      console.error('Webhook error:', error);
+      res.status(400).send('Webhook error');
+    }
+  },
+);
+```
+
 ### Basic Checkout with Single Item
 
 ```typescript
@@ -444,6 +552,8 @@ import type {
   CheckoutStatus,
   CheckoutItem,
   CheckoutParams,
+  // Webhook types
+  WebhookVerifyOptions,
 } from '@bloque/payments';
 
 const item: CheckoutItem = {
@@ -526,8 +636,8 @@ bun run check
 ## Links
 
 - [Homepage](https://www.bloque.app)
-- [GitHub Repository](git+https://github.com/bloque-app/bloque-payments.git)
-- [Issue Tracker](git+https://github.com/bloque-app/bloque-payments.git/issues)
+- [GitHub Repository](git+https://github.com/bloque-app/payments.git)
+- [Issue Tracker](git+https://github.com/bloque-app/payments.git/issues)
 
 ## License
 

package/dist/client.d.ts

@@ -1,15 +1,18 @@
 import { CheckoutResource } from './resources/checkout';
 import { PaymentResource } from './resources/payment';
+import { WebhookResource } from './resources/webhook';
 export type BloqueConfig = {
     server: 'sandbox' | 'production';
     apiKey: string;
     timeout?: number;
     maxRetries?: number;
+    webhookSecret?: string;
 };
 export declare class Bloque {
     #private;
     checkout: CheckoutResource;
     payments: PaymentResource;
+    webhooks: WebhookResource;
     constructor(config: BloqueConfig);
     private initializeResources;
 }

package/dist/index.cjs

@@ -26,7 +26,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     Bloque: ()=>Bloque
 });
-var package_namespaceObject = JSON.parse('{"UU":"@bloque/payments","rE":"0.0.2"}');
+var package_namespaceObject = JSON.parse('{"UU":"@bloque/payments","rE":"0.0.3"}');
 class BloqueError extends Error {
     constructor(message){
         super(message);
@@ -282,16 +282,46 @@ class PaymentResource extends BaseResource {
         };
     }
 }
+const external_node_crypto_namespaceObject = require("node:crypto");
+class WebhookResource {
+    #secret;
+    constructor(secret){
+        this.#secret = secret || '';
+    }
+    verify(body, signature, options) {
+        const secret = options?.secret || this.#secret;
+        if (!secret) throw new Error('Webhook secret is required. Pass it in options or set it during Bloque initialization.');
+        if (!signature) return false;
+        const payload = 'string' == typeof body ? body : JSON.stringify(body);
+        const computedSignature = this.#computeSignature(payload, secret);
+        return this.#secureCompare(signature, computedSignature);
+    }
+    setSecret(secret) {
+        this.#secret = secret;
+    }
+    #computeSignature(payload, secret) {
+        const hmac = (0, external_node_crypto_namespaceObject.createHmac)('sha256', secret);
+        hmac.update(payload);
+        return hmac.digest('hex');
+    }
+    #secureCompare(a, b) {
+        if (a.length !== b.length) return false;
+        let result = 0;
+        for(let i = 0; i < a.length; i++)result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+        return 0 === result;
+    }
+}
 class Bloque {
     #httpClient;
     #config;
     checkout;
     payments;
+    webhooks;
     constructor(config){
         if (!config.apiKey) throw new Error('API key is required');
         this.#config = config;
         this.#httpClient = new HttpClient({
-            baseURL: 'https: //api.bloque.app/api/payments',
+            baseURL: 'sandbox' === this.#config.server ? 'https://dev.bloque.app/api/payments' : 'https://api.bloque.app/api/payments',
             apiKey: this.#config.apiKey,
             timeout: this.#config.timeout,
             maxRetries: this.#config.maxRetries
@@ -301,6 +331,7 @@ class Bloque {
     initializeResources() {
         this.checkout = new CheckoutResource(this.#httpClient);
         this.payments = new PaymentResource(this.#httpClient);
+        this.webhooks = new WebhookResource(this.#config.webhookSecret);
     }
 }
 exports.Bloque = __webpack_exports__.Bloque;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export type { CreatePaymentParams, PaymentResponse, PaymentSubmitPayload, } from '@bloque/payments-core';
 export { Bloque, type BloqueConfig } from './client';
+export type { WebhookVerifyOptions } from './resources/webhook';
 export type { Checkout, CheckoutItem, CheckoutParams, CheckoutStatus, } from './types/checkout';

package/dist/index.js

@@ -1,4 +1,5 @@
-var package_namespaceObject = JSON.parse('{"UU":"@bloque/payments","rE":"0.0.2"}');
+import { createHmac } from "node:crypto";
+var package_namespaceObject = JSON.parse('{"UU":"@bloque/payments","rE":"0.0.3"}');
 class BloqueError extends Error {
     constructor(message){
         super(message);
@@ -254,16 +255,45 @@ class PaymentResource extends BaseResource {
         };
     }
 }
+class WebhookResource {
+    #secret;
+    constructor(secret){
+        this.#secret = secret || '';
+    }
+    verify(body, signature, options) {
+        const secret = options?.secret || this.#secret;
+        if (!secret) throw new Error('Webhook secret is required. Pass it in options or set it during Bloque initialization.');
+        if (!signature) return false;
+        const payload = 'string' == typeof body ? body : JSON.stringify(body);
+        const computedSignature = this.#computeSignature(payload, secret);
+        return this.#secureCompare(signature, computedSignature);
+    }
+    setSecret(secret) {
+        this.#secret = secret;
+    }
+    #computeSignature(payload, secret) {
+        const hmac = createHmac('sha256', secret);
+        hmac.update(payload);
+        return hmac.digest('hex');
+    }
+    #secureCompare(a, b) {
+        if (a.length !== b.length) return false;
+        let result = 0;
+        for(let i = 0; i < a.length; i++)result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+        return 0 === result;
+    }
+}
 class Bloque {
     #httpClient;
     #config;
     checkout;
     payments;
+    webhooks;
     constructor(config){
         if (!config.apiKey) throw new Error('API key is required');
         this.#config = config;
         this.#httpClient = new HttpClient({
-            baseURL: 'https: //api.bloque.app/api/payments',
+            baseURL: 'sandbox' === this.#config.server ? 'https://dev.bloque.app/api/payments' : 'https://api.bloque.app/api/payments',
             apiKey: this.#config.apiKey,
             timeout: this.#config.timeout,
             maxRetries: this.#config.maxRetries
@@ -273,6 +303,7 @@ class Bloque {
     initializeResources() {
         this.checkout = new CheckoutResource(this.#httpClient);
         this.payments = new PaymentResource(this.#httpClient);
+        this.webhooks = new WebhookResource(this.#config.webhookSecret);
     }
 }
 export { Bloque };

package/dist/resources/webhook.d.ts

@@ -0,0 +1,26 @@
+export interface WebhookVerifyOptions {
+    secret: string;
+}
+export declare class WebhookResource {
+    #private;
+    constructor(secret?: string);
+    /**
+     * Verify the authenticity of a webhook payload using HMAC-SHA256
+     *
+     * @param body - The raw webhook body (string or object)
+     * @param signature - The signature from the webhook header
+     * @param options - Optional verification options
+     * @returns True if the webhook is valid
+     *
+     * @example
+     * ```typescript
+     * const isValid = bloque.webhooks.verify(
+     *   req.body,
+     *   req.headers['x-bloque-signature'],
+     *   { secret: process.env.WEBHOOK_SECRET }
+     * );
+     * ```
+     */
+    verify(body: string | Record<string, unknown>, signature: string, options?: WebhookVerifyOptions): boolean;
+    setSecret(secret: string): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloque/payments",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Official Bloque SDK for creating and managing payments and checkouts.",
   "type": "module",
   "keywords": [