pathao-merchant-sdk 2.1.0 → 2.2.0

package/dist/webhooks.d.ts

@@ -5,35 +5,15 @@ import { EventEmitter } from 'events';
  *
  * Handles incoming webhook events from Pathao.
  *
- * IMPORTANT: The official Pathao API documentation does not describe a webhook
- * specification. This implementation is based on observed webhook behaviour and
- * community research. Treat it as best-effort until Pathao publishes official
- * webhook docs.
- *
- * Signature mechanism: Pathao sends the raw shared secret in the
- * `X-PATHAO-Signature` header. There is no HMAC — the header value IS the
- * secret. A constant-time comparison is used to prevent timing attacks.
- *
- * @example — framework-agnostic
- * ```typescript
- * import {
- *   PathaoWebhookHandler,
- *   PathaoWebhookEvent,
- * } from 'pathao-merchant-sdk/webhooks';
- *
- * const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);
- *
- * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => {
- *   console.log(payload.consignment_id, payload.collected_amount);
- * });
- *
- * // In your HTTP server — raw body as Buffer/string required:
- * const event = handler.process(rawBody, req.headers);
- * res.status(200).json({ received: true });
- * ```
+ * IMPORTANT INTEGRATION DETAILS:
+ * - Pathao does NOT sign incoming requests.
+ * - Instead, Pathao requires you to prove ownership by echoing your webhook secret
+ *   in the \`X-Pathao-Merchant-Webhook-Integration-Secret\` header of EVERY response.
+ * - This SDK automatically handles the \`webhook_integration\` handshake event, which
+ *   expects a 202 status code and the secret header.
  *
  * @example — Express
- * ```typescript
+ * \`\`\`typescript
  * import express from 'express';
  * import {
  *   PathaoWebhookHandler,
@@ -45,13 +25,18 @@ import { EventEmitter } from 'events';
  *
  * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => { ... });
  *
- * // Mount express.raw() BEFORE the webhook middleware
+ * // Mount express.json() BEFORE the webhook middleware
  * app.post(
  *   '/webhooks/pathao',
- *   express.raw({ type: 'application/json' }),
+ *   express.json(),
  *   handler.expressMiddleware(),
+ *   (req, res) => {
+ *     // The middleware already sets the required secret header.
+ *     // You just need to return a 200 OK for standard events.
+ *     res.status(200).send('OK');
+ *   }
  * );
- * ```
+ * \`\`\`
  */
 
 declare class PathaoWebhookError extends Error {
@@ -59,9 +44,10 @@ declare class PathaoWebhookError extends Error {
 }
 /**
  * All webhook event types emitted by Pathao.
- * Values are the exact strings that appear in the `event` field of each payload.
+ * Values are the exact strings that appear in the \`event\` field of each payload.
  */
 declare enum PathaoWebhookEvent {
+    WEBHOOK_INTEGRATION = "webhook_integration",
     ORDER_CREATED = "order.created",
     ORDER_UPDATED = "order.updated",
     ORDER_PICKUP_REQUESTED = "order.pickup-requested",
@@ -84,13 +70,15 @@ declare enum PathaoWebhookEvent {
     STORE_CREATED = "store.created",
     STORE_UPDATED = "store.updated"
 }
-/** Fields present on every webhook payload */
+interface WebhookIntegrationPayload {
+    event: PathaoWebhookEvent.WEBHOOK_INTEGRATION;
+}
+/** Fields present on every normal webhook payload */
 interface BaseWebhookPayload {
-    /** Dot-notation event type — matches a `PathaoWebhookEvent` value */
     event: string;
-    /** ISO timestamp of when the state change occurred */
+    /** Format: MySQL datetime YYYY-MM-DD HH:MM:SS (no timezone indicator) */
     updated_at: string;
-    /** ISO timestamp of when this webhook was dispatched */
+    /** Format: ISO 8601 timestamp */
     timestamp: string;
 }
 /** Fields shared by all order-related events */
@@ -185,9 +173,10 @@ interface StoreUpdatedPayload extends StoreWebhookPayload {
     event: PathaoWebhookEvent.STORE_UPDATED;
 }
 /** Union of all possible webhook payloads */
-type PathaoWebhookPayload = OrderCreatedPayload | OrderUpdatedPayload | OrderPickupRequestedPayload | OrderAssignedForPickupPayload | OrderPickedPayload | OrderPickupFailedPayload | OrderPickupCancelledPayload | OrderAtSortingHubPayload | OrderInTransitPayload | OrderAtLastMileHubPayload | OrderAssignedForDeliveryPayload | OrderDeliveredPayload | OrderPartialDeliveryPayload | OrderReturnedPayload | OrderDeliveryFailedPayload | OrderOnHoldPayload | OrderPaidPayload | OrderPaidReturnPayload | OrderExchangedPayload | StoreCreatedPayload | StoreUpdatedPayload;
-/** Maps each `PathaoWebhookEvent` to its specific payload type */
+type PathaoWebhookPayload = WebhookIntegrationPayload | OrderCreatedPayload | OrderUpdatedPayload | OrderPickupRequestedPayload | OrderAssignedForPickupPayload | OrderPickedPayload | OrderPickupFailedPayload | OrderPickupCancelledPayload | OrderAtSortingHubPayload | OrderInTransitPayload | OrderAtLastMileHubPayload | OrderAssignedForDeliveryPayload | OrderDeliveredPayload | OrderPartialDeliveryPayload | OrderReturnedPayload | OrderDeliveryFailedPayload | OrderOnHoldPayload | OrderPaidPayload | OrderPaidReturnPayload | OrderExchangedPayload | StoreCreatedPayload | StoreUpdatedPayload;
+/** Maps each \`PathaoWebhookEvent\` to its specific payload type */
 interface WebhookEventPayloadMap {
+    [PathaoWebhookEvent.WEBHOOK_INTEGRATION]: WebhookIntegrationPayload;
     [PathaoWebhookEvent.ORDER_CREATED]: OrderCreatedPayload;
     [PathaoWebhookEvent.ORDER_UPDATED]: OrderUpdatedPayload;
     [PathaoWebhookEvent.ORDER_PICKUP_REQUESTED]: OrderPickupRequestedPayload;
@@ -210,108 +199,114 @@ interface WebhookEventPayloadMap {
     [PathaoWebhookEvent.STORE_CREATED]: StoreCreatedPayload;
     [PathaoWebhookEvent.STORE_UPDATED]: StoreUpdatedPayload;
 }
-/** Signature header name sent by Pathao on every webhook request */
-declare const PATHAO_SIGNATURE_HEADER = "x-pathao-signature";
-/**
- * Verify the `X-PATHAO-Signature` header against the configured webhook secret.
- *
- * Uses a constant-time comparison to prevent timing attacks. The header value
- * is the raw shared secret — Pathao does not hash the signature.
- *
- * @returns `true` if valid, `false` if missing or mismatched.
- */
-declare function verifySignature(signature: string | undefined, webhookSecret: string): boolean;
+/** Required response header used to authorize your endpoint with Pathao */
+declare const PATHAO_SECRET_HEADER = "x-pathao-merchant-webhook-integration-secret";
 /**
- * Verify the webhook signature and parse the raw body in one step.
+ * Parses the raw body into a webhook payload.
+ * Pathao does not sign inbound requests, so this just ensures it is valid JSON with an event field.
  *
- * Throws `PathaoWebhookError` on signature failure or malformed JSON.
+ * Throws \`PathaoWebhookError\` on malformed JSON or missing event.
  *
- * @param rawBody       Raw request body — do NOT pre-parse with `JSON.parse`
- * @param headers       Request headers object
- * @param webhookSecret Your Pathao webhook integration secret
+ * @param rawBody       Raw request body or parsed object
  */
-declare function constructEvent(rawBody: Buffer | string, headers: Record<string, string | string[] | undefined>, webhookSecret: string): PathaoWebhookPayload;
-type GenericHeaders = Record<string, string | string[] | undefined>;
+declare function constructEvent(rawBody: Buffer | string | object): PathaoWebhookPayload;
+type WebhookResponseInstructions = {
+    statusCode: number;
+    headers: Record<string, string>;
+    payload: PathaoWebhookPayload | null;
+    error: PathaoWebhookError | null;
+};
 /**
- * Stateful webhook handler that verifies incoming requests, parses payloads,
+ * Stateful webhook handler that parses payloads, provides response instructions,
  * and dispatches events to typed listeners.
  *
  * @example
- * ```typescript
+ * \`\`\`typescript
  * const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);
  *
  * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => {
  *   // payload is fully typed as OrderDeliveredPayload
  *   console.log(payload.consignment_id, payload.collected_amount);
  * });
- * ```
+ * \`\`\`
  */
 declare class PathaoWebhookHandler extends EventEmitter {
     private readonly webhookSecret;
     constructor(webhookSecret: string);
     /** Listen for a specific Pathao event with a fully-typed payload callback. */
     on<E extends PathaoWebhookEvent>(event: E, listener: (payload: WebhookEventPayloadMap[E]) => void): this;
-    /** Fires for every successfully verified event regardless of type. */
+    /** Fires for every successfully parsed event regardless of type. */
     on(event: 'webhook', listener: (payload: PathaoWebhookPayload) => void): this;
-    /** Fires when verification or parsing fails. */
+    /** Fires when parsing fails. */
     on(event: 'error', listener: (error: PathaoWebhookError) => void): this;
+    /** Listen once for a specific Pathao event. */
+    once<E extends PathaoWebhookEvent>(event: E, listener: (payload: WebhookEventPayloadMap[E]) => void): this;
+    once(event: 'webhook', listener: (payload: PathaoWebhookPayload) => void): this;
+    once(event: 'error', listener: (error: PathaoWebhookError) => void): this;
     /**
-     * Verify the signature, parse the body, and dispatch the event.
+     * Parse the body and dispatch the event.
      *
-     * Throws `PathaoWebhookError` on failure and also emits `'error'` so
+     * Throws \`PathaoWebhookError\` on failure and also emits \`'error'\` so
      * listeners can respond without a try/catch.
      *
-     * @param rawBody  Raw request body — must NOT be pre-parsed
-     * @param headers  HTTP request headers
+     * @param rawBody  Raw request body or matched json object
      */
-    process(rawBody: Buffer | string, headers: GenericHeaders): PathaoWebhookPayload;
+    process(rawBody: Buffer | string | object): PathaoWebhookPayload;
     /**
      * Returns an Express-compatible middleware function.
      *
-     * **Requires** `express.raw({ type: 'application/json' })` mounted on the
-     * same route before this middleware so the raw body Buffer is preserved.
+     * Automatically sets the required \`X-Pathao-Merchant-Webhook-Integration-Secret\` header.
+     * Automatically responds with 202 for the \`webhook_integration\` handshake.
+     * For standard events, attaches the payload to \`req.pathaoWebhook\` and calls \`next()\`.
+     * On error, calls \`next(err)\`.
      *
-     * On success the parsed payload is attached to `req.pathaoWebhook`.
-     * On failure a `400` response is returned.
-     *
-     * ```typescript
+     * \`\`\`typescript
      * app.post(
      *   '/webhooks/pathao',
-     *   express.raw({ type: 'application/json' }),
+     *   express.json(),
      *   handler.expressMiddleware(),
+     *   (req, res) => res.sendStatus(200) // You must send 200 for other events
      * );
-     * ```
+     * \`\`\`
      */
     expressMiddleware(): (req: {
-        body: Buffer | string;
-        headers: GenericHeaders;
+        body: Buffer | string | object;
         pathaoWebhook?: PathaoWebhookPayload;
     }, res: {
+        setHeader: (name: string, value: string) => void;
         status: (code: number) => {
-            json: (body: unknown) => void;
+            send: () => void;
         };
     }, next: (err?: unknown) => void) => void;
     /**
-     * Returns a generic async handler for any framework (Fastify, Hono, plain
-     * `http.createServer`, etc.).
+     * Returns response instructions for any framework (Fastify, Hono, etc.).
      *
-     * Never rejects — always resolves with either `{ payload, error: null }` or
-     * `{ payload: null, error: PathaoWebhookError }`.
+     * Never throws — always resolves with a \`WebhookResponseInstructions\` object
+     * that tells you which status code and headers to return, along with the payload/error.
      *
-     * ```typescript
+     * \`\`\`typescript
      * const handle = handler.middleware();
-     * const { payload, error } = await handle(rawBody, request.headers);
-     * if (error) { reply.status(400).send({ error: error.message }); return; }
-     * reply.send({ received: true });
-     * ```
+     * const instructions = await handle(request.body);
+     *
+     * // Apply the required headers (the secret header)
+     * for (const [key, value] of Object.entries(instructions.headers)) {
+     *   reply.header(key, value);
+     * }
+     *
+     * if (instructions.error) {
+     *   return reply.status(instructions.statusCode).send({ error: instructions.error.message });
+     * }
+     *
+     * // If it was the handshake, we should just return 202 as instructed
+     * if (instructions.payload?.event === 'webhook_integration') {
+     *   return reply.status(instructions.statusCode).send();
+     * }
+     *
+     * // Process your real webhook
+     * return reply.status(instructions.statusCode).send({ received: true });
+     * \`\`\`
      */
-    middleware(): (rawBody: Buffer | string, headers: GenericHeaders) => Promise<{
-        payload: PathaoWebhookPayload;
-        error: null;
-    } | {
-        payload: null;
-        error: PathaoWebhookError;
-    }>;
+    middleware(): (rawBody: Buffer | string | object) => Promise<WebhookResponseInstructions>;
 }
 
-export { type BaseWebhookPayload, type OrderAssignedForDeliveryPayload, type OrderAssignedForPickupPayload, type OrderAtLastMileHubPayload, type OrderAtSortingHubPayload, type OrderCreatedPayload, type OrderDeliveredPayload, type OrderDeliveryFailedPayload, type OrderExchangedPayload, type OrderInTransitPayload, type OrderOnHoldPayload, type OrderPaidPayload, type OrderPaidReturnPayload, type OrderPartialDeliveryPayload, type OrderPickedPayload, type OrderPickupCancelledPayload, type OrderPickupFailedPayload, type OrderPickupRequestedPayload, type OrderReturnedPayload, type OrderUpdatedPayload, type OrderWebhookPayload, PATHAO_SIGNATURE_HEADER, PathaoWebhookError, PathaoWebhookEvent, PathaoWebhookHandler, type PathaoWebhookPayload, type StoreCreatedPayload, type StoreUpdatedPayload, type StoreWebhookPayload, type WebhookEventPayloadMap, constructEvent, verifySignature };
+export { type BaseWebhookPayload, type OrderAssignedForDeliveryPayload, type OrderAssignedForPickupPayload, type OrderAtLastMileHubPayload, type OrderAtSortingHubPayload, type OrderCreatedPayload, type OrderDeliveredPayload, type OrderDeliveryFailedPayload, type OrderExchangedPayload, type OrderInTransitPayload, type OrderOnHoldPayload, type OrderPaidPayload, type OrderPaidReturnPayload, type OrderPartialDeliveryPayload, type OrderPickedPayload, type OrderPickupCancelledPayload, type OrderPickupFailedPayload, type OrderPickupRequestedPayload, type OrderReturnedPayload, type OrderUpdatedPayload, type OrderWebhookPayload, PATHAO_SECRET_HEADER, PathaoWebhookError, PathaoWebhookEvent, PathaoWebhookHandler, type PathaoWebhookPayload, type StoreCreatedPayload, type StoreUpdatedPayload, type StoreWebhookPayload, type WebhookEventPayloadMap, type WebhookIntegrationPayload, type WebhookResponseInstructions, constructEvent };

package/dist/webhooks.js

@@ -1,6 +1,5 @@
 'use strict';
 
-var crypto = require('crypto');
 var events = require('events');
 
 // src/webhooks.ts
@@ -11,6 +10,7 @@ var PathaoWebhookError = class extends Error {
   }
 };
 var PathaoWebhookEvent = /* @__PURE__ */ ((PathaoWebhookEvent2) => {
+  PathaoWebhookEvent2["WEBHOOK_INTEGRATION"] = "webhook_integration";
   PathaoWebhookEvent2["ORDER_CREATED"] = "order.created";
   PathaoWebhookEvent2["ORDER_UPDATED"] = "order.updated";
   PathaoWebhookEvent2["ORDER_PICKUP_REQUESTED"] = "order.pickup-requested";
@@ -34,36 +34,18 @@ var PathaoWebhookEvent = /* @__PURE__ */ ((PathaoWebhookEvent2) => {
   PathaoWebhookEvent2["STORE_UPDATED"] = "store.updated";
   return PathaoWebhookEvent2;
 })(PathaoWebhookEvent || {});
-var PATHAO_SIGNATURE_HEADER = "x-pathao-signature";
-function verifySignature(signature, webhookSecret) {
-  if (!signature || !webhookSecret) return false;
-  try {
-    const sigBuf = Buffer.from(signature, "utf8");
-    const secretBuf = Buffer.from(webhookSecret, "utf8");
-    if (sigBuf.length !== secretBuf.length) return false;
-    return crypto.timingSafeEqual(sigBuf, secretBuf);
-  } catch {
-    return false;
-  }
-}
-function constructEvent(rawBody, headers, webhookSecret) {
-  const signature = extractHeader(headers, PATHAO_SIGNATURE_HEADER);
-  if (!signature) {
-    throw new PathaoWebhookError(
-      `Missing ${PATHAO_SIGNATURE_HEADER} header. Ensure Pathao is sending the signature.`
-    );
-  }
-  if (!verifySignature(signature, webhookSecret)) {
-    throw new PathaoWebhookError(
-      "Invalid webhook signature. Check that your webhookSecret matches the Pathao integration secret."
-    );
-  }
-  const bodyStr = Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : rawBody;
+var PATHAO_SECRET_HEADER = "x-pathao-merchant-webhook-integration-secret";
+function constructEvent(rawBody) {
   let parsed;
-  try {
-    parsed = JSON.parse(bodyStr);
-  } catch {
-    throw new PathaoWebhookError("Webhook payload is not valid JSON.");
+  if (typeof rawBody === "object" && !Buffer.isBuffer(rawBody)) {
+    parsed = rawBody;
+  } else {
+    const bodyStr = Buffer.isBuffer(rawBody) ? rawBody.toString("utf8") : rawBody;
+    try {
+      parsed = JSON.parse(bodyStr);
+    } catch {
+      throw new PathaoWebhookError("Webhook payload is not valid JSON.");
+    }
   }
   if (!parsed || typeof parsed !== "object" || !("event" in parsed)) {
     throw new PathaoWebhookError(
@@ -86,23 +68,28 @@ var PathaoWebhookHandler = class extends events.EventEmitter {
   on(event, listener) {
     return super.on(event, listener);
   }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  once(event, listener) {
+    return super.once(event, listener);
+  }
   // ─────────────────────────────────────────────────────────────────────────
   /**
-   * Verify the signature, parse the body, and dispatch the event.
+   * Parse the body and dispatch the event.
    *
-   * Throws `PathaoWebhookError` on failure and also emits `'error'` so
+   * Throws \`PathaoWebhookError\` on failure and also emits \`'error'\` so
    * listeners can respond without a try/catch.
    *
-   * @param rawBody  Raw request body — must NOT be pre-parsed
-   * @param headers  HTTP request headers
+   * @param rawBody  Raw request body or matched json object
    */
-  process(rawBody, headers) {
+  process(rawBody) {
     let payload;
     try {
-      payload = constructEvent(rawBody, headers, this.webhookSecret);
+      payload = constructEvent(rawBody);
     } catch (err) {
       const webhookErr = err instanceof PathaoWebhookError ? err : new PathaoWebhookError(err instanceof Error ? err.message : "Unknown error");
-      this.emit("error", webhookErr);
+      if (this.listenerCount("error") > 0) {
+        this.emit("error", webhookErr);
+      }
       throw webhookErr;
     }
     this.emit(payload.event, payload);
@@ -112,74 +99,95 @@ var PathaoWebhookHandler = class extends events.EventEmitter {
   /**
    * Returns an Express-compatible middleware function.
    *
-   * **Requires** `express.raw({ type: 'application/json' })` mounted on the
-   * same route before this middleware so the raw body Buffer is preserved.
-   *
-   * On success the parsed payload is attached to `req.pathaoWebhook`.
-   * On failure a `400` response is returned.
+   * Automatically sets the required \`X-Pathao-Merchant-Webhook-Integration-Secret\` header.
+   * Automatically responds with 202 for the \`webhook_integration\` handshake.
+   * For standard events, attaches the payload to \`req.pathaoWebhook\` and calls \`next()\`.
+   * On error, calls \`next(err)\`.
    *
-   * ```typescript
+   * \`\`\`typescript
    * app.post(
    *   '/webhooks/pathao',
-   *   express.raw({ type: 'application/json' }),
+   *   express.json(),
    *   handler.expressMiddleware(),
+   *   (req, res) => res.sendStatus(200) // You must send 200 for other events
    * );
-   * ```
+   * \`\`\`
    */
   expressMiddleware() {
     return (req, res, next) => {
       try {
-        req.pathaoWebhook = this.process(req.body, req.headers);
+        res.setHeader(PATHAO_SECRET_HEADER, this.webhookSecret);
+        const payload = this.process(req.body);
+        req.pathaoWebhook = payload;
+        if (payload.event === "webhook_integration" /* WEBHOOK_INTEGRATION */) {
+          res.status(202).send();
+          return;
+        }
         next();
       } catch (err) {
-        res.status(400).json({
-          error: err instanceof Error ? err.message : "Webhook processing failed"
-        });
+        next(err);
       }
     };
   }
   /**
-   * Returns a generic async handler for any framework (Fastify, Hono, plain
-   * `http.createServer`, etc.).
+   * Returns response instructions for any framework (Fastify, Hono, etc.).
    *
-   * Never rejects — always resolves with either `{ payload, error: null }` or
-   * `{ payload: null, error: PathaoWebhookError }`.
+   * Never throws — always resolves with a \`WebhookResponseInstructions\` object
+   * that tells you which status code and headers to return, along with the payload/error.
    *
-   * ```typescript
+   * \`\`\`typescript
    * const handle = handler.middleware();
-   * const { payload, error } = await handle(rawBody, request.headers);
-   * if (error) { reply.status(400).send({ error: error.message }); return; }
-   * reply.send({ received: true });
-   * ```
+   * const instructions = await handle(request.body);
+   * 
+   * // Apply the required headers (the secret header)
+   * for (const [key, value] of Object.entries(instructions.headers)) {
+   *   reply.header(key, value);
+   * }
+   * 
+   * if (instructions.error) {
+   *   return reply.status(instructions.statusCode).send({ error: instructions.error.message });
+   * }
+   * 
+   * // If it was the handshake, we should just return 202 as instructed
+   * if (instructions.payload?.event === 'webhook_integration') {
+   *   return reply.status(instructions.statusCode).send();
+   * }
+   * 
+   * // Process your real webhook
+   * return reply.status(instructions.statusCode).send({ received: true });
+   * \`\`\`
    */
   middleware() {
-    return async (rawBody, headers) => {
+    return async (rawBody) => {
+      const headers = { [PATHAO_SECRET_HEADER]: this.webhookSecret };
       try {
-        const payload = this.process(rawBody, headers);
-        return { payload, error: null };
+        const payload = this.process(rawBody);
+        const isHandshake = payload.event === "webhook_integration" /* WEBHOOK_INTEGRATION */;
+        return {
+          statusCode: isHandshake ? 202 : 200,
+          headers,
+          payload,
+          error: null
+        };
       } catch (err) {
         const webhookErr = err instanceof PathaoWebhookError ? err : new PathaoWebhookError(
           err instanceof Error ? err.message : "Unknown error"
         );
-        return { payload: null, error: webhookErr };
+        return {
+          statusCode: 400,
+          headers,
+          payload: null,
+          error: webhookErr
+        };
       }
     };
   }
 };
-function extractHeader(headers, name) {
-  const lower = name.toLowerCase();
-  const key = Object.keys(headers).find((k) => k.toLowerCase() === lower);
-  if (!key) return void 0;
-  const value = headers[key];
-  if (Array.isArray(value)) return value[0];
-  return value;
-}
 
-exports.PATHAO_SIGNATURE_HEADER = PATHAO_SIGNATURE_HEADER;
+exports.PATHAO_SECRET_HEADER = PATHAO_SECRET_HEADER;
 exports.PathaoWebhookError = PathaoWebhookError;
 exports.PathaoWebhookEvent = PathaoWebhookEvent;
 exports.PathaoWebhookHandler = PathaoWebhookHandler;
 exports.constructEvent = constructEvent;
-exports.verifySignature = verifySignature;
 //# sourceMappingURL=webhooks.js.map
 //# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/webhooks.ts"],"names":["PathaoWebhookEvent","timingSafeEqual","EventEmitter"],"mappings":";;;;;;AA6DO,IAAM,kBAAA,GAAN,cAAiC,KAAA,CAAM;AAAA,EAC5C,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AAAA,EACd;AACF;AAUO,IAAK,kBAAA,qBAAAA,mBAAAA,KAAL;AACL,EAAAA,oBAAA,eAAA,CAAA,GAAkC,eAAA;AAClC,EAAAA,oBAAA,eAAA,CAAA,GAAkC,eAAA;AAClC,EAAAA,oBAAA,wBAAA,CAAA,GAAkC,wBAAA;AAClC,EAAAA,oBAAA,2BAAA,CAAA,GAAkC,2BAAA;AAClC,EAAAA,oBAAA,cAAA,CAAA,GAAkC,cAAA;AAClC,EAAAA,oBAAA,qBAAA,CAAA,GAAkC,qBAAA;AAClC,EAAAA,oBAAA,wBAAA,CAAA,GAAkC,wBAAA;AAClC,EAAAA,oBAAA,0BAAA,CAAA,GAAkC,0BAAA;AAClC,EAAAA,oBAAA,kBAAA,CAAA,GAAkC,kBAAA;AAClC,EAAAA,oBAAA,iCAAA,CAAA,GAAkC,iCAAA;AAClC,EAAAA,oBAAA,6BAAA,CAAA,GAAkC,6BAAA;AAClC,EAAAA,oBAAA,iBAAA,CAAA,GAAkC,iBAAA;AAClC,EAAAA,oBAAA,wBAAA,CAAA,GAAkC,wBAAA;AAClC,EAAAA,oBAAA,gBAAA,CAAA,GAAkC,gBAAA;AAClC,EAAAA,oBAAA,uBAAA,CAAA,GAAkC,uBAAA;AAClC,EAAAA,oBAAA,eAAA,CAAA,GAAkC,eAAA;AAClC,EAAAA,oBAAA,YAAA,CAAA,GAAkC,YAAA;AAClC,EAAAA,oBAAA,mBAAA,CAAA,GAAkC,mBAAA;AAClC,EAAAA,oBAAA,iBAAA,CAAA,GAAkC,iBAAA;AAClC,EAAAA,oBAAA,eAAA,CAAA,GAAkC,eAAA;AAClC,EAAAA,oBAAA,eAAA,CAAA,GAAkC,eAAA;AArBxB,EAAA,OAAAA,mBAAAA;AAAA,CAAA,EAAA,kBAAA,IAAA,EAAA;AAgNL,IAAM,uBAAA,GAA0B;AAUhC,SAAS,eAAA,CACd,WACA,aAAA,EACS;AACT,EAAA,IAAI,CAAC,SAAA,IAAa,CAAC,aAAA,EAAe,OAAO,KAAA;AAEzC,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAY,MAAA,CAAO,IAAA,CAAK,SAAA,EAAe,MAAM,CAAA;AACnD,IAAA,MAAM,SAAA,GAAY,MAAA,CAAO,IAAA,CAAK,aAAA,EAAe,MAAM,CAAA;AACnD,IAAA,IAAI,MAAA,CAAO,MAAA,KAAW,SAAA,CAAU,MAAA,EAAQ,OAAO,KAAA;AAC/C,IAAA,OAAOC,sBAAA,CAAgB,QAAQ,SAAS,CAAA;AAAA,EAC1C,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT;AACF;AAWO,SAAS,cAAA,CACd,OAAA,EACA,OAAA,EACA,aAAA,EACsB;AACtB,EAAA,MAAM,SAAA,GAAY,aAAA,CAAc,OAAA,EAAS,uBAAuB,CAAA;AAEhE,EAAA,IAAI,CAAC,SAAA,EAAW;AACd,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,WAAW,uBAAuB,CAAA,gDAAA;AAAA,KAEpC;AAAA,EACF;AAEA,EAAA,IAAI,CAAC,eAAA,CAAgB,SAAA,EAAW,aAAa,CAAA,EAAG;AAC9C,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR;AAAA,KAEF;AAAA,EACF;AAEA,EAAA,MAAM,OAAA,GAAU,OAAO,QAAA,CAAS,OAAO,IAAI,OAAA,CAAQ,QAAA,CAAS,MAAM,CAAA,GAAI,OAAA;AAEtE,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAA,GAAS,IAAA,CAAK,MAAM,OAAO,CAAA;AAAA,EAC7B,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,mBAAmB,oCAAoC,CAAA;AAAA,EACnE;AAEA,EAAA,IACE,CAAC,MAAA,IACD,OAAO,WAAW,QAAA,IAClB,EAAE,WAAW,MAAA,CAAA,EACb;AACA,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AAEA,EAAA,OAAO,MAAA;AACT;AAsBO,IAAM,oBAAA,GAAN,cAAmCC,mBAAA,CAAa;AAAA,EAGrD,YAAY,aAAA,EAAuB;AACjC,IAAA,KAAA,EAAM;AACN,IAAA,IAAI,CAAC,aAAA,EAAe;AAClB,MAAA,MAAM,IAAI,kBAAA;AAAA,QACR;AAAA,OACF;AAAA,IACF;AACA,IAAA,IAAA,CAAK,aAAA,GAAgB,aAAA;AAAA,EACvB;AAAA;AAAA,EAcA,EAAA,CAAG,OAAwB,QAAA,EAA0C;AACnE,IAAA,OAAO,KAAA,CAAM,EAAA,CAAG,KAAA,EAAO,QAAQ,CAAA;AAAA,EACjC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,OAAA,CAAQ,SAA0B,OAAA,EAA+C;AAC/E,IAAA,IAAI,OAAA;AAEJ,IAAA,IAAI;AACF,MAAA,OAAA,GAAU,cAAA,CAAe,OAAA,EAAS,OAAA,EAAS,IAAA,CAAK,aAAa,CAAA;AAAA,IAC/D,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,UAAA,GAAa,GAAA,YAAe,kBAAA,GAC9B,GAAA,GACA,IAAI,mBAAmB,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,eAAe,CAAA;AAC/E,MAAA,IAAA,CAAK,IAAA,CAAK,SAAS,UAAU,CAAA;AAC7B,MAAA,MAAM,UAAA;AAAA,IACR;AAEA,IAAA,IAAA,CAAK,IAAA,CAAK,OAAA,CAAQ,KAAA,EAAO,OAAO,CAAA;AAChC,IAAA,IAAA,CAAK,IAAA,CAAK,WAAW,OAAO,CAAA;AAE5B,IAAA,OAAO,OAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBA,iBAAA,GAAoB;AAClB,IAAA,OAAO,CACL,GAAA,EAKA,GAAA,EACA,IAAA,KACS;AACT,MAAA,IAAI;AACF,QAAA,GAAA,CAAI,gBAAgB,IAAA,CAAK,OAAA,CAAQ,GAAA,CAAI,IAAA,EAAM,IAAI,OAAO,CAAA;AACtD,QAAA,IAAA,EAAK;AAAA,MACP,SAAS,GAAA,EAAK;AACZ,QAAA,GAAA,CAAI,MAAA,CAAO,GAAG,CAAA,CAAE,IAAA,CAAK;AAAA,UACnB,KAAA,EAAO,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU;AAAA,SAC7C,CAAA;AAAA,MACH;AAAA,IACF,CAAA;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAgBA,UAAA,GAAa;AACX,IAAA,OAAO,OACL,SACA,OAAA,KAIG;AACH,MAAA,IAAI;AACF,QAAA,MAAM,OAAA,GAAU,IAAA,CAAK,OAAA,CAAQ,OAAA,EAAS,OAAO,CAAA;AAC7C,QAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,IAAA,EAAK;AAAA,MAChC,SAAS,GAAA,EAAK;AACZ,QAAA,MAAM,UAAA,GAAa,GAAA,YAAe,kBAAA,GAC9B,GAAA,GACA,IAAI,kBAAA;AAAA,UACJ,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU;AAAA,SACvC;AACF,QAAA,OAAO,EAAE,OAAA,EAAS,IAAA,EAAM,KAAA,EAAO,UAAA,EAAW;AAAA,MAC5C;AAAA,IACF,CAAA;AAAA,EACF;AACF;AAOA,SAAS,aAAA,CACP,SACA,IAAA,EACoB;AACpB,EAAA,MAAM,KAAA,GAAQ,KAAK,WAAA,EAAY;AAC/B,EAAA,MAAM,GAAA,GAAM,MAAA,CAAO,IAAA,CAAK,OAAO,CAAA,CAAE,KAAK,CAAA,CAAA,KAAK,CAAA,CAAE,WAAA,EAAY,KAAM,KAAK,CAAA;AACpE,EAAA,IAAI,CAAC,KAAK,OAAO,MAAA;AACjB,EAAA,MAAM,KAAA,GAAQ,QAAQ,GAAG,CAAA;AACzB,EAAA,IAAI,MAAM,OAAA,CAAQ,KAAK,CAAA,EAAG,OAAO,MAAM,CAAC,CAAA;AACxC,EAAA,OAAO,KAAA;AACT","file":"webhooks.js","sourcesContent":["/**\n * Pathao Webhook Support\n *\n * Handles incoming webhook events from Pathao.\n *\n * IMPORTANT: The official Pathao API documentation does not describe a webhook\n * specification. This implementation is based on observed webhook behaviour and\n * community research. Treat it as best-effort until Pathao publishes official\n * webhook docs.\n *\n * Signature mechanism: Pathao sends the raw shared secret in the\n * `X-PATHAO-Signature` header. There is no HMAC — the header value IS the\n * secret. A constant-time comparison is used to prevent timing attacks.\n *\n * @example — framework-agnostic\n * ```typescript\n * import {\n *   PathaoWebhookHandler,\n *   PathaoWebhookEvent,\n * } from 'pathao-merchant-sdk/webhooks';\n *\n * const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);\n *\n * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => {\n *   console.log(payload.consignment_id, payload.collected_amount);\n * });\n *\n * // In your HTTP server — raw body as Buffer/string required:\n * const event = handler.process(rawBody, req.headers);\n * res.status(200).json({ received: true });\n * ```\n *\n * @example — Express\n * ```typescript\n * import express from 'express';\n * import {\n *   PathaoWebhookHandler,\n *   PathaoWebhookEvent,\n * } from 'pathao-merchant-sdk/webhooks';\n *\n * const app = express();\n * const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);\n *\n * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => { ... });\n *\n * // Mount express.raw() BEFORE the webhook middleware\n * app.post(\n *   '/webhooks/pathao',\n *   express.raw({ type: 'application/json' }),\n *   handler.expressMiddleware(),\n * );\n * ```\n */\n\nimport { timingSafeEqual } from 'crypto';\nimport { EventEmitter } from 'events';\n\n// ---------------------------------------------------------------------------\n// Error\n// ---------------------------------------------------------------------------\n\nexport class PathaoWebhookError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'PathaoWebhookError';\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Event types\n// ---------------------------------------------------------------------------\n\n/**\n * All webhook event types emitted by Pathao.\n * Values are the exact strings that appear in the `event` field of each payload.\n */\nexport enum PathaoWebhookEvent {\n  ORDER_CREATED                   = 'order.created',\n  ORDER_UPDATED                   = 'order.updated',\n  ORDER_PICKUP_REQUESTED          = 'order.pickup-requested',\n  ORDER_ASSIGNED_FOR_PICKUP       = 'order.assigned-for-pickup',\n  ORDER_PICKED                    = 'order.picked',\n  ORDER_PICKUP_FAILED             = 'order.pickup-failed',\n  ORDER_PICKUP_CANCELLED          = 'order.pickup-cancelled',\n  ORDER_AT_THE_SORTING_HUB        = 'order.at-the-sorting-hub',\n  ORDER_IN_TRANSIT                = 'order.in-transit',\n  ORDER_RECEIVED_AT_LAST_MILE_HUB = 'order.received-at-last-mile-hub',\n  ORDER_ASSIGNED_FOR_DELIVERY     = 'order.assigned-for-delivery',\n  ORDER_DELIVERED                 = 'order.delivered',\n  ORDER_PARTIAL_DELIVERY          = 'order.partial-delivery',\n  ORDER_RETURNED                  = 'order.returned',\n  ORDER_DELIVERY_FAILED           = 'order.delivery-failed',\n  ORDER_ON_HOLD                   = 'order.on-hold',\n  ORDER_PAID                      = 'order.paid',\n  ORDER_PAID_RETURN               = 'order.paid-return',\n  ORDER_EXCHANGED                 = 'order.exchanged',\n  STORE_CREATED                   = 'store.created',\n  STORE_UPDATED                   = 'store.updated',\n}\n\n// ---------------------------------------------------------------------------\n// Payload types\n// ---------------------------------------------------------------------------\n\n/** Fields present on every webhook payload */\nexport interface BaseWebhookPayload {\n  /** Dot-notation event type — matches a `PathaoWebhookEvent` value */\n  event: string;\n  /** ISO timestamp of when the state change occurred */\n  updated_at: string;\n  /** ISO timestamp of when this webhook was dispatched */\n  timestamp: string;\n}\n\n/** Fields shared by all order-related events */\nexport interface OrderWebhookPayload extends BaseWebhookPayload {\n  consignment_id: string;\n  merchant_order_id?: string;\n  store_id: number;\n  delivery_fee?: number;\n}\n\n/** Fields shared by all store-related events */\nexport interface StoreWebhookPayload extends BaseWebhookPayload {\n  store_id: number;\n  store_name: string;\n  store_address: string;\n  is_active: 0 | 1;\n}\n\n// Per-event payload types ────────────────────────────────────────────────────\n\nexport interface OrderCreatedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_CREATED;\n  delivery_fee: number;\n}\n\nexport interface OrderUpdatedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_UPDATED;\n  delivery_fee: number;\n}\n\nexport interface OrderPickupRequestedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PICKUP_REQUESTED;\n  delivery_fee: number;\n}\n\nexport interface OrderAssignedForPickupPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_ASSIGNED_FOR_PICKUP;\n}\n\nexport interface OrderPickedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PICKED;\n}\n\nexport interface OrderPickupFailedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PICKUP_FAILED;\n}\n\nexport interface OrderPickupCancelledPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PICKUP_CANCELLED;\n}\n\nexport interface OrderAtSortingHubPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_AT_THE_SORTING_HUB;\n}\n\nexport interface OrderInTransitPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_IN_TRANSIT;\n}\n\nexport interface OrderAtLastMileHubPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_RECEIVED_AT_LAST_MILE_HUB;\n}\n\nexport interface OrderAssignedForDeliveryPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_ASSIGNED_FOR_DELIVERY;\n}\n\nexport interface OrderDeliveredPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_DELIVERED;\n  collected_amount: number;\n}\n\nexport interface OrderPartialDeliveryPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PARTIAL_DELIVERY;\n  collected_amount: number;\n  reason?: string;\n}\n\nexport interface OrderReturnedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_RETURNED;\n  reason?: string;\n}\n\nexport interface OrderDeliveryFailedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_DELIVERY_FAILED;\n  reason?: string;\n}\n\nexport interface OrderOnHoldPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_ON_HOLD;\n  reason?: string;\n}\n\nexport interface OrderPaidPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PAID;\n  invoice_id: string;\n}\n\nexport interface OrderPaidReturnPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PAID_RETURN;\n  collected_amount: number;\n  reason?: string;\n}\n\nexport interface OrderExchangedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_EXCHANGED;\n  collected_amount: number;\n  reason?: string;\n}\n\nexport interface StoreCreatedPayload extends StoreWebhookPayload {\n  event: PathaoWebhookEvent.STORE_CREATED;\n}\n\nexport interface StoreUpdatedPayload extends StoreWebhookPayload {\n  event: PathaoWebhookEvent.STORE_UPDATED;\n}\n\n/** Union of all possible webhook payloads */\nexport type PathaoWebhookPayload =\n  | OrderCreatedPayload\n  | OrderUpdatedPayload\n  | OrderPickupRequestedPayload\n  | OrderAssignedForPickupPayload\n  | OrderPickedPayload\n  | OrderPickupFailedPayload\n  | OrderPickupCancelledPayload\n  | OrderAtSortingHubPayload\n  | OrderInTransitPayload\n  | OrderAtLastMileHubPayload\n  | OrderAssignedForDeliveryPayload\n  | OrderDeliveredPayload\n  | OrderPartialDeliveryPayload\n  | OrderReturnedPayload\n  | OrderDeliveryFailedPayload\n  | OrderOnHoldPayload\n  | OrderPaidPayload\n  | OrderPaidReturnPayload\n  | OrderExchangedPayload\n  | StoreCreatedPayload\n  | StoreUpdatedPayload;\n\n/** Maps each `PathaoWebhookEvent` to its specific payload type */\nexport interface WebhookEventPayloadMap {\n  [PathaoWebhookEvent.ORDER_CREATED]:                   OrderCreatedPayload;\n  [PathaoWebhookEvent.ORDER_UPDATED]:                   OrderUpdatedPayload;\n  [PathaoWebhookEvent.ORDER_PICKUP_REQUESTED]:          OrderPickupRequestedPayload;\n  [PathaoWebhookEvent.ORDER_ASSIGNED_FOR_PICKUP]:       OrderAssignedForPickupPayload;\n  [PathaoWebhookEvent.ORDER_PICKED]:                    OrderPickedPayload;\n  [PathaoWebhookEvent.ORDER_PICKUP_FAILED]:             OrderPickupFailedPayload;\n  [PathaoWebhookEvent.ORDER_PICKUP_CANCELLED]:          OrderPickupCancelledPayload;\n  [PathaoWebhookEvent.ORDER_AT_THE_SORTING_HUB]:        OrderAtSortingHubPayload;\n  [PathaoWebhookEvent.ORDER_IN_TRANSIT]:                OrderInTransitPayload;\n  [PathaoWebhookEvent.ORDER_RECEIVED_AT_LAST_MILE_HUB]: OrderAtLastMileHubPayload;\n  [PathaoWebhookEvent.ORDER_ASSIGNED_FOR_DELIVERY]:     OrderAssignedForDeliveryPayload;\n  [PathaoWebhookEvent.ORDER_DELIVERED]:                 OrderDeliveredPayload;\n  [PathaoWebhookEvent.ORDER_PARTIAL_DELIVERY]:          OrderPartialDeliveryPayload;\n  [PathaoWebhookEvent.ORDER_RETURNED]:                  OrderReturnedPayload;\n  [PathaoWebhookEvent.ORDER_DELIVERY_FAILED]:           OrderDeliveryFailedPayload;\n  [PathaoWebhookEvent.ORDER_ON_HOLD]:                   OrderOnHoldPayload;\n  [PathaoWebhookEvent.ORDER_PAID]:                      OrderPaidPayload;\n  [PathaoWebhookEvent.ORDER_PAID_RETURN]:               OrderPaidReturnPayload;\n  [PathaoWebhookEvent.ORDER_EXCHANGED]:                 OrderExchangedPayload;\n  [PathaoWebhookEvent.STORE_CREATED]:                   StoreCreatedPayload;\n  [PathaoWebhookEvent.STORE_UPDATED]:                   StoreUpdatedPayload;\n}\n\n// ---------------------------------------------------------------------------\n// Core functions\n// ---------------------------------------------------------------------------\n\n/** Signature header name sent by Pathao on every webhook request */\nexport const PATHAO_SIGNATURE_HEADER = 'x-pathao-signature';\n\n/**\n * Verify the `X-PATHAO-Signature` header against the configured webhook secret.\n *\n * Uses a constant-time comparison to prevent timing attacks. The header value\n * is the raw shared secret — Pathao does not hash the signature.\n *\n * @returns `true` if valid, `false` if missing or mismatched.\n */\nexport function verifySignature(\n  signature: string | undefined,\n  webhookSecret: string,\n): boolean {\n  if (!signature || !webhookSecret) return false;\n\n  try {\n    const sigBuf    = Buffer.from(signature,     'utf8');\n    const secretBuf = Buffer.from(webhookSecret, 'utf8');\n    if (sigBuf.length !== secretBuf.length) return false;\n    return timingSafeEqual(sigBuf, secretBuf);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Verify the webhook signature and parse the raw body in one step.\n *\n * Throws `PathaoWebhookError` on signature failure or malformed JSON.\n *\n * @param rawBody       Raw request body — do NOT pre-parse with `JSON.parse`\n * @param headers       Request headers object\n * @param webhookSecret Your Pathao webhook integration secret\n */\nexport function constructEvent(\n  rawBody: Buffer | string,\n  headers: Record<string, string | string[] | undefined>,\n  webhookSecret: string,\n): PathaoWebhookPayload {\n  const signature = extractHeader(headers, PATHAO_SIGNATURE_HEADER);\n\n  if (!signature) {\n    throw new PathaoWebhookError(\n      `Missing ${PATHAO_SIGNATURE_HEADER} header. ` +\n      'Ensure Pathao is sending the signature.',\n    );\n  }\n\n  if (!verifySignature(signature, webhookSecret)) {\n    throw new PathaoWebhookError(\n      'Invalid webhook signature. ' +\n      'Check that your webhookSecret matches the Pathao integration secret.',\n    );\n  }\n\n  const bodyStr = Buffer.isBuffer(rawBody) ? rawBody.toString('utf8') : rawBody;\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(bodyStr);\n  } catch {\n    throw new PathaoWebhookError('Webhook payload is not valid JSON.');\n  }\n\n  if (\n    !parsed ||\n    typeof parsed !== 'object' ||\n    !('event' in parsed)\n  ) {\n    throw new PathaoWebhookError(\n      'Webhook payload is missing the required `event` field.',\n    );\n  }\n\n  return parsed as PathaoWebhookPayload;\n}\n\n// ---------------------------------------------------------------------------\n// PathaoWebhookHandler\n// ---------------------------------------------------------------------------\n\ntype GenericHeaders = Record<string, string | string[] | undefined>;\n\n/**\n * Stateful webhook handler that verifies incoming requests, parses payloads,\n * and dispatches events to typed listeners.\n *\n * @example\n * ```typescript\n * const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);\n *\n * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => {\n *   // payload is fully typed as OrderDeliveredPayload\n *   console.log(payload.consignment_id, payload.collected_amount);\n * });\n * ```\n */\nexport class PathaoWebhookHandler extends EventEmitter {\n  private readonly webhookSecret: string;\n\n  constructor(webhookSecret: string) {\n    super();\n    if (!webhookSecret) {\n      throw new PathaoWebhookError(\n        'webhookSecret is required to create a PathaoWebhookHandler.',\n      );\n    }\n    this.webhookSecret = webhookSecret;\n  }\n\n  // Typed on() overloads ──────────────────────────────────────────────────\n\n  /** Listen for a specific Pathao event with a fully-typed payload callback. */\n  on<E extends PathaoWebhookEvent>(\n    event: E,\n    listener: (payload: WebhookEventPayloadMap[E]) => void,\n  ): this;\n  /** Fires for every successfully verified event regardless of type. */\n  on(event: 'webhook', listener: (payload: PathaoWebhookPayload) => void): this;\n  /** Fires when verification or parsing fails. */\n  on(event: 'error', listener: (error: PathaoWebhookError) => void): this;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  on(event: string | symbol, listener: (...args: any[]) => void): this {\n    return super.on(event, listener);\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Verify the signature, parse the body, and dispatch the event.\n   *\n   * Throws `PathaoWebhookError` on failure and also emits `'error'` so\n   * listeners can respond without a try/catch.\n   *\n   * @param rawBody  Raw request body — must NOT be pre-parsed\n   * @param headers  HTTP request headers\n   */\n  process(rawBody: Buffer | string, headers: GenericHeaders): PathaoWebhookPayload {\n    let payload: PathaoWebhookPayload;\n\n    try {\n      payload = constructEvent(rawBody, headers, this.webhookSecret);\n    } catch (err) {\n      const webhookErr = err instanceof PathaoWebhookError\n        ? err\n        : new PathaoWebhookError(err instanceof Error ? err.message : 'Unknown error');\n      this.emit('error', webhookErr);\n      throw webhookErr;\n    }\n\n    this.emit(payload.event, payload);\n    this.emit('webhook', payload);\n\n    return payload;\n  }\n\n  /**\n   * Returns an Express-compatible middleware function.\n   *\n   * **Requires** `express.raw({ type: 'application/json' })` mounted on the\n   * same route before this middleware so the raw body Buffer is preserved.\n   *\n   * On success the parsed payload is attached to `req.pathaoWebhook`.\n   * On failure a `400` response is returned.\n   *\n   * ```typescript\n   * app.post(\n   *   '/webhooks/pathao',\n   *   express.raw({ type: 'application/json' }),\n   *   handler.expressMiddleware(),\n   * );\n   * ```\n   */\n  expressMiddleware() {\n    return (\n      req: {\n        body: Buffer | string;\n        headers: GenericHeaders;\n        pathaoWebhook?: PathaoWebhookPayload;\n      },\n      res: { status: (code: number) => { json: (body: unknown) => void } },\n      next: (err?: unknown) => void,\n    ): void => {\n      try {\n        req.pathaoWebhook = this.process(req.body, req.headers);\n        next();\n      } catch (err) {\n        res.status(400).json({\n          error: err instanceof Error ? err.message : 'Webhook processing failed',\n        });\n      }\n    };\n  }\n\n  /**\n   * Returns a generic async handler for any framework (Fastify, Hono, plain\n   * `http.createServer`, etc.).\n   *\n   * Never rejects — always resolves with either `{ payload, error: null }` or\n   * `{ payload: null, error: PathaoWebhookError }`.\n   *\n   * ```typescript\n   * const handle = handler.middleware();\n   * const { payload, error } = await handle(rawBody, request.headers);\n   * if (error) { reply.status(400).send({ error: error.message }); return; }\n   * reply.send({ received: true });\n   * ```\n   */\n  middleware() {\n    return async (\n      rawBody: Buffer | string,\n      headers: GenericHeaders,\n    ): Promise<\n      | { payload: PathaoWebhookPayload; error: null }\n      | { payload: null; error: PathaoWebhookError }\n    > => {\n      try {\n        const payload = this.process(rawBody, headers);\n        return { payload, error: null };\n      } catch (err) {\n        const webhookErr = err instanceof PathaoWebhookError\n          ? err\n          : new PathaoWebhookError(\n            err instanceof Error ? err.message : 'Unknown error',\n          );\n        return { payload: null, error: webhookErr };\n      }\n    };\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/** Extract a single-value header, case-insensitively */\nfunction extractHeader(\n  headers: GenericHeaders,\n  name: string,\n): string | undefined {\n  const lower = name.toLowerCase();\n  const key = Object.keys(headers).find(k => k.toLowerCase() === lower);\n  if (!key) return undefined;\n  const value = headers[key];\n  if (Array.isArray(value)) return value[0];\n  return value;\n}\n"]}
+{"version":3,"sources":["../src/webhooks.ts"],"names":["PathaoWebhookEvent","EventEmitter"],"mappings":"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","file":"webhooks.js","sourcesContent":["/**\n * Pathao Webhook Support\n *\n * Handles incoming webhook events from Pathao.\n *\n * IMPORTANT INTEGRATION DETAILS:\n * - Pathao does NOT sign incoming requests.\n * - Instead, Pathao requires you to prove ownership by echoing your webhook secret\n *   in the \\`X-Pathao-Merchant-Webhook-Integration-Secret\\` header of EVERY response.\n * - This SDK automatically handles the \\`webhook_integration\\` handshake event, which\n *   expects a 202 status code and the secret header.\n *\n * @example — Express\n * \\`\\`\\`typescript\n * import express from 'express';\n * import {\n *   PathaoWebhookHandler,\n *   PathaoWebhookEvent,\n * } from 'pathao-merchant-sdk/webhooks';\n *\n * const app = express();\n * const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);\n *\n * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => { ... });\n *\n * // Mount express.json() BEFORE the webhook middleware\n * app.post(\n *   '/webhooks/pathao',\n *   express.json(),\n *   handler.expressMiddleware(),\n *   (req, res) => {\n *     // The middleware already sets the required secret header.\n *     // You just need to return a 200 OK for standard events.\n *     res.status(200).send('OK');\n *   }\n * );\n * \\`\\`\\`\n */\n\nimport { EventEmitter } from 'events';\n\n// ---------------------------------------------------------------------------\n// Error\n// ---------------------------------------------------------------------------\n\nexport class PathaoWebhookError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'PathaoWebhookError';\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Event types\n// ---------------------------------------------------------------------------\n\n/**\n * All webhook event types emitted by Pathao.\n * Values are the exact strings that appear in the \\`event\\` field of each payload.\n */\nexport enum PathaoWebhookEvent {\n  WEBHOOK_INTEGRATION             = 'webhook_integration',\n  ORDER_CREATED                   = 'order.created',\n  ORDER_UPDATED                   = 'order.updated',\n  ORDER_PICKUP_REQUESTED          = 'order.pickup-requested',\n  ORDER_ASSIGNED_FOR_PICKUP       = 'order.assigned-for-pickup',\n  ORDER_PICKED                    = 'order.picked',\n  ORDER_PICKUP_FAILED             = 'order.pickup-failed',\n  ORDER_PICKUP_CANCELLED          = 'order.pickup-cancelled',\n  ORDER_AT_THE_SORTING_HUB        = 'order.at-the-sorting-hub',\n  ORDER_IN_TRANSIT                = 'order.in-transit',\n  ORDER_RECEIVED_AT_LAST_MILE_HUB = 'order.received-at-last-mile-hub',\n  ORDER_ASSIGNED_FOR_DELIVERY     = 'order.assigned-for-delivery',\n  ORDER_DELIVERED                 = 'order.delivered',\n  ORDER_PARTIAL_DELIVERY          = 'order.partial-delivery',\n  ORDER_RETURNED                  = 'order.returned',\n  ORDER_DELIVERY_FAILED           = 'order.delivery-failed',\n  ORDER_ON_HOLD                   = 'order.on-hold',\n  ORDER_PAID                      = 'order.paid',\n  ORDER_PAID_RETURN               = 'order.paid-return',\n  ORDER_EXCHANGED                 = 'order.exchanged',\n  STORE_CREATED                   = 'store.created',\n  STORE_UPDATED                   = 'store.updated',\n}\n\n// ---------------------------------------------------------------------------\n// Payload types\n// ---------------------------------------------------------------------------\n\nexport interface WebhookIntegrationPayload {\n  event: PathaoWebhookEvent.WEBHOOK_INTEGRATION;\n}\n\n/** Fields present on every normal webhook payload */\nexport interface BaseWebhookPayload {\n  event: string;\n  /** Format: MySQL datetime YYYY-MM-DD HH:MM:SS (no timezone indicator) */\n  updated_at: string;\n  /** Format: ISO 8601 timestamp */\n  timestamp: string;\n}\n\n/** Fields shared by all order-related events */\nexport interface OrderWebhookPayload extends BaseWebhookPayload {\n  consignment_id: string;\n  merchant_order_id?: string;\n  store_id: number;\n  delivery_fee?: number;\n}\n\n/** Fields shared by all store-related events */\nexport interface StoreWebhookPayload extends BaseWebhookPayload {\n  store_id: number;\n  store_name: string;\n  store_address: string;\n  is_active: 0 | 1;\n}\n\n// Per-event payload types ────────────────────────────────────────────────────\n\nexport interface OrderCreatedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_CREATED;\n  delivery_fee: number;\n}\n\nexport interface OrderUpdatedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_UPDATED;\n  delivery_fee: number;\n}\n\nexport interface OrderPickupRequestedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PICKUP_REQUESTED;\n  delivery_fee: number;\n}\n\nexport interface OrderAssignedForPickupPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_ASSIGNED_FOR_PICKUP;\n}\n\nexport interface OrderPickedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PICKED;\n}\n\nexport interface OrderPickupFailedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PICKUP_FAILED;\n}\n\nexport interface OrderPickupCancelledPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PICKUP_CANCELLED;\n}\n\nexport interface OrderAtSortingHubPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_AT_THE_SORTING_HUB;\n}\n\nexport interface OrderInTransitPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_IN_TRANSIT;\n}\n\nexport interface OrderAtLastMileHubPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_RECEIVED_AT_LAST_MILE_HUB;\n}\n\nexport interface OrderAssignedForDeliveryPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_ASSIGNED_FOR_DELIVERY;\n}\n\nexport interface OrderDeliveredPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_DELIVERED;\n  collected_amount: number;\n}\n\nexport interface OrderPartialDeliveryPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PARTIAL_DELIVERY;\n  collected_amount: number;\n  reason?: string;\n}\n\nexport interface OrderReturnedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_RETURNED;\n  reason?: string;\n}\n\nexport interface OrderDeliveryFailedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_DELIVERY_FAILED;\n  reason?: string;\n}\n\nexport interface OrderOnHoldPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_ON_HOLD;\n  reason?: string;\n}\n\nexport interface OrderPaidPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PAID;\n  invoice_id: string;\n}\n\nexport interface OrderPaidReturnPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_PAID_RETURN;\n  collected_amount: number;\n  reason?: string;\n}\n\nexport interface OrderExchangedPayload extends OrderWebhookPayload {\n  event: PathaoWebhookEvent.ORDER_EXCHANGED;\n  collected_amount: number;\n  reason?: string;\n}\n\nexport interface StoreCreatedPayload extends StoreWebhookPayload {\n  event: PathaoWebhookEvent.STORE_CREATED;\n}\n\nexport interface StoreUpdatedPayload extends StoreWebhookPayload {\n  event: PathaoWebhookEvent.STORE_UPDATED;\n}\n\n/** Union of all possible webhook payloads */\nexport type PathaoWebhookPayload =\n  | WebhookIntegrationPayload\n  | OrderCreatedPayload\n  | OrderUpdatedPayload\n  | OrderPickupRequestedPayload\n  | OrderAssignedForPickupPayload\n  | OrderPickedPayload\n  | OrderPickupFailedPayload\n  | OrderPickupCancelledPayload\n  | OrderAtSortingHubPayload\n  | OrderInTransitPayload\n  | OrderAtLastMileHubPayload\n  | OrderAssignedForDeliveryPayload\n  | OrderDeliveredPayload\n  | OrderPartialDeliveryPayload\n  | OrderReturnedPayload\n  | OrderDeliveryFailedPayload\n  | OrderOnHoldPayload\n  | OrderPaidPayload\n  | OrderPaidReturnPayload\n  | OrderExchangedPayload\n  | StoreCreatedPayload\n  | StoreUpdatedPayload;\n\n/** Maps each \\`PathaoWebhookEvent\\` to its specific payload type */\nexport interface WebhookEventPayloadMap {\n  [PathaoWebhookEvent.WEBHOOK_INTEGRATION]:             WebhookIntegrationPayload;\n  [PathaoWebhookEvent.ORDER_CREATED]:                   OrderCreatedPayload;\n  [PathaoWebhookEvent.ORDER_UPDATED]:                   OrderUpdatedPayload;\n  [PathaoWebhookEvent.ORDER_PICKUP_REQUESTED]:          OrderPickupRequestedPayload;\n  [PathaoWebhookEvent.ORDER_ASSIGNED_FOR_PICKUP]:       OrderAssignedForPickupPayload;\n  [PathaoWebhookEvent.ORDER_PICKED]:                    OrderPickedPayload;\n  [PathaoWebhookEvent.ORDER_PICKUP_FAILED]:             OrderPickupFailedPayload;\n  [PathaoWebhookEvent.ORDER_PICKUP_CANCELLED]:          OrderPickupCancelledPayload;\n  [PathaoWebhookEvent.ORDER_AT_THE_SORTING_HUB]:        OrderAtSortingHubPayload;\n  [PathaoWebhookEvent.ORDER_IN_TRANSIT]:                OrderInTransitPayload;\n  [PathaoWebhookEvent.ORDER_RECEIVED_AT_LAST_MILE_HUB]: OrderAtLastMileHubPayload;\n  [PathaoWebhookEvent.ORDER_ASSIGNED_FOR_DELIVERY]:     OrderAssignedForDeliveryPayload;\n  [PathaoWebhookEvent.ORDER_DELIVERED]:                 OrderDeliveredPayload;\n  [PathaoWebhookEvent.ORDER_PARTIAL_DELIVERY]:          OrderPartialDeliveryPayload;\n  [PathaoWebhookEvent.ORDER_RETURNED]:                  OrderReturnedPayload;\n  [PathaoWebhookEvent.ORDER_DELIVERY_FAILED]:           OrderDeliveryFailedPayload;\n  [PathaoWebhookEvent.ORDER_ON_HOLD]:                   OrderOnHoldPayload;\n  [PathaoWebhookEvent.ORDER_PAID]:                      OrderPaidPayload;\n  [PathaoWebhookEvent.ORDER_PAID_RETURN]:               OrderPaidReturnPayload;\n  [PathaoWebhookEvent.ORDER_EXCHANGED]:                 OrderExchangedPayload;\n  [PathaoWebhookEvent.STORE_CREATED]:                   StoreCreatedPayload;\n  [PathaoWebhookEvent.STORE_UPDATED]:                   StoreUpdatedPayload;\n}\n\n// ---------------------------------------------------------------------------\n// Core functions\n// ---------------------------------------------------------------------------\n\n/** Required response header used to authorize your endpoint with Pathao */\nexport const PATHAO_SECRET_HEADER = 'x-pathao-merchant-webhook-integration-secret';\n\n/**\n * Parses the raw body into a webhook payload.\n * Pathao does not sign inbound requests, so this just ensures it is valid JSON with an event field.\n *\n * Throws \\`PathaoWebhookError\\` on malformed JSON or missing event.\n *\n * @param rawBody       Raw request body or parsed object\n */\nexport function constructEvent(\n  rawBody: Buffer | string | object,\n): PathaoWebhookPayload {\n  let parsed: unknown;\n  if (typeof rawBody === 'object' && !Buffer.isBuffer(rawBody)) {\n    parsed = rawBody;\n  } else {\n    const bodyStr = Buffer.isBuffer(rawBody) ? rawBody.toString('utf8') : rawBody;\n    try {\n      parsed = JSON.parse(bodyStr);\n    } catch {\n      throw new PathaoWebhookError('Webhook payload is not valid JSON.');\n    }\n  }\n\n  if (\n    !parsed ||\n    typeof parsed !== 'object' ||\n    !('event' in parsed)\n  ) {\n    throw new PathaoWebhookError(\n      'Webhook payload is missing the required \\`event\\` field.',\n    );\n  }\n\n  return parsed as PathaoWebhookPayload;\n}\n\n// ---------------------------------------------------------------------------\n// PathaoWebhookHandler\n// ---------------------------------------------------------------------------\n\nexport type WebhookResponseInstructions = {\n  statusCode: number;\n  headers: Record<string, string>;\n  payload: PathaoWebhookPayload | null;\n  error: PathaoWebhookError | null;\n};\n\n/**\n * Stateful webhook handler that parses payloads, provides response instructions,\n * and dispatches events to typed listeners.\n *\n * @example\n * \\`\\`\\`typescript\n * const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);\n *\n * handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => {\n *   // payload is fully typed as OrderDeliveredPayload\n *   console.log(payload.consignment_id, payload.collected_amount);\n * });\n * \\`\\`\\`\n */\nexport class PathaoWebhookHandler extends EventEmitter {\n  private readonly webhookSecret: string;\n\n  constructor(webhookSecret: string) {\n    super();\n    if (!webhookSecret) {\n      throw new PathaoWebhookError(\n        'webhookSecret is required to create a PathaoWebhookHandler.',\n      );\n    }\n    this.webhookSecret = webhookSecret;\n  }\n\n  // Typed on() overloads ──────────────────────────────────────────────────\n\n  /** Listen for a specific Pathao event with a fully-typed payload callback. */\n  on<E extends PathaoWebhookEvent>(\n    event: E,\n    listener: (payload: WebhookEventPayloadMap[E]) => void,\n  ): this;\n  /** Fires for every successfully parsed event regardless of type. */\n  on(event: 'webhook', listener: (payload: PathaoWebhookPayload) => void): this;\n  /** Fires when parsing fails. */\n  on(event: 'error', listener: (error: PathaoWebhookError) => void): this;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  on(event: string | symbol, listener: (...args: any[]) => void): this {\n    return super.on(event, listener);\n  }\n\n  /** Listen once for a specific Pathao event. */\n  once<E extends PathaoWebhookEvent>(\n    event: E,\n    listener: (payload: WebhookEventPayloadMap[E]) => void,\n  ): this;\n  once(event: 'webhook', listener: (payload: PathaoWebhookPayload) => void): this;\n  once(event: 'error', listener: (error: PathaoWebhookError) => void): this;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  once(event: string | symbol, listener: (...args: any[]) => void): this {\n    return super.once(event, listener);\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Parse the body and dispatch the event.\n   *\n   * Throws \\`PathaoWebhookError\\` on failure and also emits \\`'error'\\` so\n   * listeners can respond without a try/catch.\n   *\n   * @param rawBody  Raw request body or matched json object\n   */\n  process(rawBody: Buffer | string | object): PathaoWebhookPayload {\n    let payload: PathaoWebhookPayload;\n\n    try {\n      payload = constructEvent(rawBody);\n    } catch (err) {\n      const webhookErr = err instanceof PathaoWebhookError\n        ? err\n        : new PathaoWebhookError(err instanceof Error ? err.message : 'Unknown error');\n      if (this.listenerCount('error') > 0) {\n        this.emit('error', webhookErr);\n      }\n      throw webhookErr;\n    }\n\n    this.emit(payload.event, payload);\n    this.emit('webhook', payload);\n\n    return payload;\n  }\n\n  /**\n   * Returns an Express-compatible middleware function.\n   *\n   * Automatically sets the required \\`X-Pathao-Merchant-Webhook-Integration-Secret\\` header.\n   * Automatically responds with 202 for the \\`webhook_integration\\` handshake.\n   * For standard events, attaches the payload to \\`req.pathaoWebhook\\` and calls \\`next()\\`.\n   * On error, calls \\`next(err)\\`.\n   *\n   * \\`\\`\\`typescript\n   * app.post(\n   *   '/webhooks/pathao',\n   *   express.json(),\n   *   handler.expressMiddleware(),\n   *   (req, res) => res.sendStatus(200) // You must send 200 for other events\n   * );\n   * \\`\\`\\`\n   */\n  expressMiddleware() {\n    return (\n      req: {\n        body: Buffer | string | object;\n        pathaoWebhook?: PathaoWebhookPayload;\n      },\n      res: {\n        setHeader: (name: string, value: string) => void;\n        status: (code: number) => { send: () => void };\n      },\n      next: (err?: unknown) => void,\n    ): void => {\n      try {\n        res.setHeader(PATHAO_SECRET_HEADER, this.webhookSecret);\n        \n        const payload = this.process(req.body);\n        req.pathaoWebhook = payload;\n        \n        if (payload.event === PathaoWebhookEvent.WEBHOOK_INTEGRATION) {\n          res.status(202).send();\n          return;\n        }\n\n        next();\n      } catch (err) {\n        next(err);\n      }\n    };\n  }\n\n  /**\n   * Returns response instructions for any framework (Fastify, Hono, etc.).\n   *\n   * Never throws — always resolves with a \\`WebhookResponseInstructions\\` object\n   * that tells you which status code and headers to return, along with the payload/error.\n   *\n   * \\`\\`\\`typescript\n   * const handle = handler.middleware();\n   * const instructions = await handle(request.body);\n   * \n   * // Apply the required headers (the secret header)\n   * for (const [key, value] of Object.entries(instructions.headers)) {\n   *   reply.header(key, value);\n   * }\n   * \n   * if (instructions.error) {\n   *   return reply.status(instructions.statusCode).send({ error: instructions.error.message });\n   * }\n   * \n   * // If it was the handshake, we should just return 202 as instructed\n   * if (instructions.payload?.event === 'webhook_integration') {\n   *   return reply.status(instructions.statusCode).send();\n   * }\n   * \n   * // Process your real webhook\n   * return reply.status(instructions.statusCode).send({ received: true });\n   * \\`\\`\\`\n   */\n  middleware() {\n    return async (\n      rawBody: Buffer | string | object,\n    ): Promise<WebhookResponseInstructions> => {\n      const headers = { [PATHAO_SECRET_HEADER]: this.webhookSecret };\n      \n      try {\n        const payload = this.process(rawBody);\n        const isHandshake = payload.event === PathaoWebhookEvent.WEBHOOK_INTEGRATION;\n        return {\n          statusCode: isHandshake ? 202 : 200,\n          headers,\n          payload,\n          error: null\n        };\n      } catch (err) {\n        const webhookErr = err instanceof PathaoWebhookError\n          ? err\n          : new PathaoWebhookError(\n            err instanceof Error ? err.message : 'Unknown error',\n          );\n        return {\n          statusCode: 400,\n          headers,\n          payload: null,\n          error: webhookErr\n        };\n      }\n    };\n  }\n}\n"]}