pathao-merchant-sdk 2.1.0 → 2.2.0

package/dist/webhooks.mjs

@@ -1,4 +1,3 @@
-import { timingSafeEqual } from 'crypto';
 import { EventEmitter } from 'events';
 
 // src/webhooks.ts
@@ -9,6 +8,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";
@@ -32,36 +32,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 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(
@@ -84,23 +66,28 @@ var PathaoWebhookHandler = class extends 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);
@@ -110,69 +97,91 @@ var PathaoWebhookHandler = class extends 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;
-}
 
-export { PATHAO_SIGNATURE_HEADER, PathaoWebhookError, PathaoWebhookEvent, PathaoWebhookHandler, constructEvent, verifySignature };
+export { PATHAO_SECRET_HEADER, PathaoWebhookError, PathaoWebhookEvent, PathaoWebhookHandler, constructEvent };
 //# sourceMappingURL=webhooks.mjs.map
 //# sourceMappingURL=webhooks.mjs.map

package/dist/webhooks.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/webhooks.ts"],"names":["PathaoWebhookEvent"],"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,OAAO,eAAA,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,cAAmC,YAAA,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.mjs","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"],"mappings":"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","file":"webhooks.mjs","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"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pathao-merchant-sdk",
-  "version": "2.1.0",
-  "description": "Unofficial Pathao Merchant API SDK for Node.js and TypeScript",
+  "version": "2.2.0",
+  "description": "Unofficial TypeScript SDK for the Pathao Merchant API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -75,6 +75,7 @@
     "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@typescript-eslint/parser": "^6.21.0",
+    "axios-mock-adapter": "^2.1.0",
     "eslint": "^8.0.0",
     "jest": "^29.0.0",
     "ts-jest": "^29.0.0",