paykit-bd 0.1.0

package/dist/bkash/adapters/next.cjs

@@ -0,0 +1,383 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/core/errors.ts
+var BRANDS = /* @__PURE__ */ Symbol.for("paykit-bd.error.brands");
+function brandedInstanceOf(tag) {
+  return (value) => {
+    if (typeof value !== "object" || value === null) return false;
+    const brands = value[BRANDS];
+    return Array.isArray(brands) && brands.includes(tag);
+  };
+}
+var PaykitError = class extends Error {
+  static [Symbol.hasInstance] = brandedInstanceOf("PaykitError");
+  /** Class lineage, innermost last. Read `instanceof` instead of this. */
+  [BRANDS];
+  /** Gateway this came from — `"bkash"`, or `"paykit"` for local failures. */
+  provider;
+  /** Stable machine-readable code. Gateway codes are passed through verbatim. */
+  code;
+  /** True when retrying the identical request could plausibly succeed. */
+  retryable;
+  /** Untouched gateway response body, for logging. */
+  raw;
+  constructor(message, opts, brands = []) {
+    super(message, { cause: opts.cause });
+    this.name = new.target.name;
+    this[BRANDS] = ["PaykitError", ...brands];
+    this.provider = opts.provider;
+    this.code = opts.code;
+    this.retryable = opts.retryable ?? false;
+    this.raw = opts.raw;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      provider: this.provider,
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable
+    };
+  }
+};
+var WebhookVerificationError = class extends PaykitError {
+  static [Symbol.hasInstance] = brandedInstanceOf("WebhookVerificationError");
+  constructor(message, opts) {
+    super(
+      message,
+      {
+        provider: opts.provider,
+        code: opts.code ?? "webhook_verification_failed",
+        retryable: false,
+        raw: opts.raw,
+        cause: opts.cause
+      },
+      ["WebhookVerificationError"]
+    );
+  }
+};
+
+// src/core/http.ts
+var noopLogger = {
+  debug() {
+  },
+  warn() {
+  },
+  error() {
+  }
+};
+function parseBkashCompactTime(value) {
+  if (!value) return void 0;
+  const match = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/.exec(value.trim());
+  if (!match) return void 0;
+  const [, y, mo, d, h, mi, s] = match;
+  const date = new Date(
+    Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s)) - 6 * 60 * 6e4
+  );
+  return Number.isNaN(date.getTime()) ? void 0 : date;
+}
+
+// src/bkash/webhook.ts
+var SNS_CERT_HOST = /^sns\.[a-z0-9-]+\.amazonaws\.com(\.cn)?$/i;
+var BkashWebhookVerifier = class _BkashWebhookVerifier {
+  #options;
+  #logger;
+  #fetch;
+  #certCache = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.#options = options;
+    this.#logger = options.logger ?? noopLogger;
+    this.#fetch = options.fetchImpl ?? fetch;
+  }
+  /**
+   * Verify an inbound request and normalise it.
+   *
+   * `request.body` must be the raw bytes as received. A body that has been
+   * parsed and re-serialised will not match the signature.
+   */
+  async verify(request) {
+    const envelope = this.#parseEnvelope(request.body);
+    await this.#verifySignature(envelope);
+    this.#checkTopic(envelope);
+    this.#checkAge(envelope);
+    return this.#normalise(envelope);
+  }
+  /**
+   * Confirm an SNS subscription by visiting its SubscribeURL.
+   *
+   * Deliberately not automatic: it is an outbound call that switches on real
+   * payment traffic, so your handler decides when to make it. Verify the
+   * message first — this method re-checks the URL host but assumes the
+   * signature was already proven.
+   */
+  async confirmSubscription(envelope) {
+    const url = envelope.SubscribeURL;
+    if (!url) {
+      throw new WebhookVerificationError("bKash: subscription confirmation has no SubscribeURL", {
+        provider: "bkash",
+        code: "missing_subscribe_url",
+        raw: envelope
+      });
+    }
+    assertSnsUrl(url, "SubscribeURL");
+    const response = await this.#fetch(url, { method: "GET" });
+    if (!response.ok) {
+      throw new WebhookVerificationError(
+        `bKash: SNS subscription confirmation failed with HTTP ${response.status}`,
+        { provider: "bkash", code: "subscribe_failed", raw: await response.text().catch(() => "") }
+      );
+    }
+    this.#logger.debug("paykit/bkash: SNS subscription confirmed", { topicArn: envelope.TopicArn });
+  }
+  /** Parse an already-verified envelope's inner payment message. */
+  static parseMessage(envelope) {
+    if (!envelope.Message) return null;
+    try {
+      return JSON.parse(envelope.Message);
+    } catch {
+      return null;
+    }
+  }
+  #parseEnvelope(body) {
+    if (!body || body.trim() === "") {
+      throw new WebhookVerificationError("bKash: empty webhook body", {
+        provider: "bkash",
+        code: "empty_body"
+      });
+    }
+    try {
+      return JSON.parse(body);
+    } catch (cause) {
+      throw new WebhookVerificationError("bKash: webhook body is not JSON", {
+        provider: "bkash",
+        code: "invalid_body",
+        raw: body.slice(0, 500),
+        cause
+      });
+    }
+  }
+  async #verifySignature(envelope) {
+    const { Signature, SignatureVersion, SigningCertURL, Type } = envelope;
+    if (!Signature || !SigningCertURL || !Type) {
+      throw new WebhookVerificationError(
+        "bKash: webhook is missing Type, Signature or SigningCertURL \u2014 it is not an SNS message",
+        { provider: "bkash", code: "not_sns", raw: envelope }
+      );
+    }
+    const algorithm = SignatureVersion === "2" ? "RSA-SHA256" : "RSA-SHA1";
+    if (SignatureVersion !== "1" && SignatureVersion !== "2") {
+      throw new WebhookVerificationError(
+        `bKash: unsupported SNS SignatureVersion ${JSON.stringify(SignatureVersion)}`,
+        { provider: "bkash", code: "unsupported_signature_version", raw: envelope }
+      );
+    }
+    assertSnsUrl(SigningCertURL, "SigningCertURL");
+    const pem = await this.#loadCertificate(SigningCertURL);
+    const canonical = canonicalString(envelope);
+    let valid;
+    try {
+      valid = crypto.createVerify(algorithm).update(canonical, "utf8").verify(pem, Signature, "base64");
+    } catch (cause) {
+      throw new WebhookVerificationError("bKash: SNS signature could not be checked", {
+        provider: "bkash",
+        code: "signature_check_failed",
+        cause
+      });
+    }
+    if (!valid) {
+      throw new WebhookVerificationError(
+        "bKash: SNS signature does not match the message. Treat the payload as forged, and check that the raw request body reached the verifier unmodified.",
+        { provider: "bkash", code: "signature_mismatch" }
+      );
+    }
+  }
+  #checkTopic(envelope) {
+    const expected = this.#options.topicArn;
+    if (!expected) {
+      this.#logger.warn(
+        "paykit/bkash: webhook accepted without a pinned topicArn \u2014 any Amazon-signed SNS topic will pass"
+      );
+      return;
+    }
+    const allowed = Array.isArray(expected) ? expected : [expected];
+    if (!envelope.TopicArn || !allowed.includes(envelope.TopicArn)) {
+      throw new WebhookVerificationError(
+        `bKash: message came from SNS topic ${JSON.stringify(envelope.TopicArn)}, which is not one of yours`,
+        { provider: "bkash", code: "topic_mismatch", raw: envelope.TopicArn }
+      );
+    }
+  }
+  #checkAge(envelope) {
+    const maxAgeMs = this.#options.maxAgeMs;
+    if (!maxAgeMs || !envelope.Timestamp) return;
+    const sent = new Date(envelope.Timestamp).getTime();
+    if (Number.isNaN(sent)) return;
+    if (Date.now() - sent > maxAgeMs) {
+      throw new WebhookVerificationError(
+        `bKash: message is older than the configured maxAgeMs (${maxAgeMs}ms)`,
+        { provider: "bkash", code: "message_too_old", raw: envelope.Timestamp }
+      );
+    }
+  }
+  #normalise(envelope) {
+    const base = {
+      provider: "bkash",
+      eventId: envelope.MessageId,
+      raw: envelope
+    };
+    if (envelope.Type === "SubscriptionConfirmation" || envelope.Type === "UnsubscribeConfirmation") {
+      return { ...base, type: "subscription.confirmation" };
+    }
+    const message = _BkashWebhookVerifier.parseMessage(envelope);
+    if (!message) return { ...base, type: "unknown" };
+    const completed = (message.transactionStatus ?? "").toLowerCase() === "completed";
+    return {
+      ...base,
+      type: completed ? "payment.completed" : "payment.failed",
+      transactionId: message.trxID,
+      reference: message.merchantInvoiceNumber ?? message.transactionReference,
+      amount: message.amount,
+      currency: message.currency ?? "BDT",
+      payerAccount: message.debitMSISDN,
+      occurredAt: parseBkashCompactTime(message.dateTime)
+    };
+  }
+  async #loadCertificate(url) {
+    const ttl = this.#options.certCacheMs ?? 24 * 60 * 60 * 1e3;
+    const cached = this.#certCache.get(url);
+    if (cached && Date.now() - cached.fetchedAt < ttl) return cached.pem;
+    const response = await this.#fetch(url, { method: "GET", signal: AbortSignal.timeout(1e4) });
+    if (!response.ok) {
+      throw new WebhookVerificationError(
+        `bKash: could not fetch the SNS signing certificate (HTTP ${response.status})`,
+        { provider: "bkash", code: "cert_fetch_failed", raw: url }
+      );
+    }
+    const pem = await response.text();
+    if (!pem.includes("BEGIN CERTIFICATE") && !pem.includes("BEGIN PUBLIC KEY")) {
+      throw new WebhookVerificationError("bKash: SigningCertURL did not return a PEM certificate", {
+        provider: "bkash",
+        code: "cert_invalid",
+        raw: pem.slice(0, 200)
+      });
+    }
+    this.#certCache.set(url, { pem, fetchedAt: Date.now() });
+    return pem;
+  }
+};
+function canonicalString(envelope) {
+  const fields = envelope.Type === "SubscriptionConfirmation" || envelope.Type === "UnsubscribeConfirmation" ? ["Message", "MessageId", "SubscribeURL", "Timestamp", "Token", "TopicArn", "Type"] : ["Message", "MessageId", "Subject", "Timestamp", "TopicArn", "Type"];
+  let canonical = "";
+  for (const field of fields) {
+    const value = envelope[field];
+    if (value === void 0 || value === null) continue;
+    canonical += `${field}
+${value}
+`;
+  }
+  return canonical;
+}
+function assertSnsUrl(rawUrl, field) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new WebhookVerificationError(`bKash: ${field} is not a URL`, {
+      provider: "bkash",
+      code: "cert_url_invalid",
+      raw: rawUrl
+    });
+  }
+  if (url.protocol !== "https:") {
+    throw new WebhookVerificationError(`bKash: ${field} must be https`, {
+      provider: "bkash",
+      code: "cert_url_insecure",
+      raw: rawUrl
+    });
+  }
+  if (!SNS_CERT_HOST.test(url.hostname)) {
+    throw new WebhookVerificationError(
+      `bKash: ${field} points at ${url.hostname}, which is not an Amazon SNS host. This is what a forged notification looks like \u2014 the payload is not from bKash.`,
+      { provider: "bkash", code: "cert_url_untrusted", raw: rawUrl }
+    );
+  }
+  if (field === "SigningCertURL" && !url.pathname.endsWith(".pem")) {
+    throw new WebhookVerificationError(`bKash: ${field} does not point at a .pem file`, {
+      provider: "bkash",
+      code: "cert_url_invalid",
+      raw: rawUrl
+    });
+  }
+  return url;
+}
+
+// src/bkash/adapters/next.ts
+function createBkashWebhookHandler(client, options = {}) {
+  return async function POST(request) {
+    const rawBody = await request.text();
+    let event;
+    try {
+      event = await client.verifyWebhook({ body: rawBody, headers: headersToObject(request.headers) });
+    } catch (error) {
+      await options.onVerificationFailure?.(error, rawBody);
+      const message = error instanceof WebhookVerificationError ? error.message : "webhook verification failed";
+      return Response.json({ ok: false, error: message }, { status: 400 });
+    }
+    try {
+      if (event.type === "subscription.confirmation") {
+        const envelope = event.raw;
+        const shouldConfirm = await options.onSubscriptionConfirmation?.(envelope) ?? false;
+        if (shouldConfirm) await client.webhooks.confirmSubscription(envelope);
+        return Response.json({ ok: true, confirmed: shouldConfirm });
+      }
+      if (event.type === "payment.completed") {
+        await options.onPaymentCompleted?.(event);
+      } else {
+        await options.onOtherEvent?.(event);
+      }
+      return Response.json({ ok: true });
+    } catch (error) {
+      return Response.json(
+        { ok: false, error: error instanceof PaykitError ? error.message : "handler failed" },
+        { status: 500 }
+      );
+    }
+  };
+}
+function createBkashCallbackHandler(client, options = {}) {
+  return async function GET(request) {
+    const url = new URL(request.url);
+    const query = client.constructor.parseCallback(url.searchParams);
+    const paymentId = query.paymentID;
+    if (!paymentId) {
+      const handled = await options.onFailure?.(new Error("callback has no paymentID"), void 0);
+      return handled ?? redirect(options.failureUrl ?? "/", url);
+    }
+    try {
+      const payment = query.status === "success" ? await client.executePayment(paymentId) : await client.getPayment(paymentId);
+      const handled = await options.onSettled?.(payment);
+      if (handled) return handled;
+      const destination = payment.status === "completed" ? options.successUrl ?? "/" : options.failureUrl ?? "/";
+      return redirect(destination, url);
+    } catch (error) {
+      const handled = await options.onFailure?.(error, paymentId);
+      return handled ?? redirect(options.failureUrl ?? "/", url);
+    }
+  };
+}
+function redirect(destination, base) {
+  return Response.redirect(new URL(destination, base).toString(), 303);
+}
+function headersToObject(headers) {
+  const out = {};
+  headers.forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}
+
+exports.BkashWebhookVerifier = BkashWebhookVerifier;
+exports.createBkashCallbackHandler = createBkashCallbackHandler;
+exports.createBkashWebhookHandler = createBkashWebhookHandler;

package/dist/bkash/adapters/next.d.cts

@@ -0,0 +1,64 @@
+import { W as WebhookEvent } from '../../token-store-C8IMMLPJ.cjs';
+import { B as BkashClient, S as SnsEnvelope } from '../../client-UNDtdWhu.cjs';
+export { a as BkashWebhookVerifier } from '../../client-UNDtdWhu.cjs';
+
+/**
+ * Next.js App Router route handlers.
+ *
+ * ```ts
+ * // app/api/bkash/webhook/route.ts
+ * import { createBkashWebhookHandler } from "paykit-bd/bkash/next";
+ * export const POST = createBkashWebhookHandler(bkash, {
+ *   onPaymentCompleted: async (event) => { await fulfilOrder(event.reference!); },
+ * });
+ * ```
+ *
+ * No Next.js import is needed — these are plain `Request` → `Response`
+ * functions, so they also work in any fetch-based runtime.
+ */
+
+interface WebhookHandlerOptions {
+    /** A genuine, completed payment. Do your fulfilment here. */
+    onPaymentCompleted?: (event: WebhookEvent) => Promise<void> | void;
+    /** A genuine notification that is not a completed payment. */
+    onOtherEvent?: (event: WebhookEvent) => Promise<void> | void;
+    /**
+     * Called for an SNS SubscriptionConfirmation. Return true to confirm the
+     * subscription, which turns on live notification delivery.
+     *
+     * Default is false — confirming is an outbound action that starts real
+     * traffic, so it is yours to trigger, usually once during onboarding.
+     */
+    onSubscriptionConfirmation?: (envelope: SnsEnvelope) => Promise<boolean> | boolean;
+    /** Called when verification fails. The request is already being rejected. */
+    onVerificationFailure?: (error: unknown, rawBody: string) => Promise<void> | void;
+}
+/**
+ * Build a POST handler for the bKash IPN endpoint.
+ *
+ * Status codes are chosen for how SNS behaves: 200 means delivered and SNS
+ * stops; a 5xx makes SNS retry, which is what you want when your own
+ * fulfilment threw. A forged message gets 400 and no retry.
+ */
+declare function createBkashWebhookHandler(client: BkashClient, options?: WebhookHandlerOptions): (request: Request) => Promise<Response>;
+interface CallbackHandlerOptions {
+    /**
+     * Called after the payment has been executed and its real outcome is known.
+     * Return a Response to control the redirect; returning nothing sends the
+     * customer to `successUrl` or `failureUrl`.
+     */
+    onSettled?: (result: Awaited<ReturnType<BkashClient["executePayment"]>>) => Promise<Response | void> | Response | void;
+    onFailure?: (error: unknown, paymentId: string | undefined) => Promise<Response | void> | Response | void;
+    successUrl?: string;
+    failureUrl?: string;
+}
+/**
+ * Build a GET handler for the URL bKash redirects the customer back to.
+ *
+ * It executes the payment, because the redirect itself proves nothing: the
+ * customer's browser followed that URL and could have edited it. `status=success`
+ * in the query string is a hint, never the decision.
+ */
+declare function createBkashCallbackHandler(client: BkashClient, options?: CallbackHandlerOptions): (request: Request) => Promise<Response>;
+
+export { type CallbackHandlerOptions, type WebhookHandlerOptions, createBkashCallbackHandler, createBkashWebhookHandler };

package/dist/bkash/adapters/next.d.ts

@@ -0,0 +1,64 @@
+import { W as WebhookEvent } from '../../token-store-C8IMMLPJ.js';
+import { B as BkashClient, S as SnsEnvelope } from '../../client-Y9603twG.js';
+export { a as BkashWebhookVerifier } from '../../client-Y9603twG.js';
+
+/**
+ * Next.js App Router route handlers.
+ *
+ * ```ts
+ * // app/api/bkash/webhook/route.ts
+ * import { createBkashWebhookHandler } from "paykit-bd/bkash/next";
+ * export const POST = createBkashWebhookHandler(bkash, {
+ *   onPaymentCompleted: async (event) => { await fulfilOrder(event.reference!); },
+ * });
+ * ```
+ *
+ * No Next.js import is needed — these are plain `Request` → `Response`
+ * functions, so they also work in any fetch-based runtime.
+ */
+
+interface WebhookHandlerOptions {
+    /** A genuine, completed payment. Do your fulfilment here. */
+    onPaymentCompleted?: (event: WebhookEvent) => Promise<void> | void;
+    /** A genuine notification that is not a completed payment. */
+    onOtherEvent?: (event: WebhookEvent) => Promise<void> | void;
+    /**
+     * Called for an SNS SubscriptionConfirmation. Return true to confirm the
+     * subscription, which turns on live notification delivery.
+     *
+     * Default is false — confirming is an outbound action that starts real
+     * traffic, so it is yours to trigger, usually once during onboarding.
+     */
+    onSubscriptionConfirmation?: (envelope: SnsEnvelope) => Promise<boolean> | boolean;
+    /** Called when verification fails. The request is already being rejected. */
+    onVerificationFailure?: (error: unknown, rawBody: string) => Promise<void> | void;
+}
+/**
+ * Build a POST handler for the bKash IPN endpoint.
+ *
+ * Status codes are chosen for how SNS behaves: 200 means delivered and SNS
+ * stops; a 5xx makes SNS retry, which is what you want when your own
+ * fulfilment threw. A forged message gets 400 and no retry.
+ */
+declare function createBkashWebhookHandler(client: BkashClient, options?: WebhookHandlerOptions): (request: Request) => Promise<Response>;
+interface CallbackHandlerOptions {
+    /**
+     * Called after the payment has been executed and its real outcome is known.
+     * Return a Response to control the redirect; returning nothing sends the
+     * customer to `successUrl` or `failureUrl`.
+     */
+    onSettled?: (result: Awaited<ReturnType<BkashClient["executePayment"]>>) => Promise<Response | void> | Response | void;
+    onFailure?: (error: unknown, paymentId: string | undefined) => Promise<Response | void> | Response | void;
+    successUrl?: string;
+    failureUrl?: string;
+}
+/**
+ * Build a GET handler for the URL bKash redirects the customer back to.
+ *
+ * It executes the payment, because the redirect itself proves nothing: the
+ * customer's browser followed that URL and could have edited it. `status=success`
+ * in the query string is a hint, never the decision.
+ */
+declare function createBkashCallbackHandler(client: BkashClient, options?: CallbackHandlerOptions): (request: Request) => Promise<Response>;
+
+export { type CallbackHandlerOptions, type WebhookHandlerOptions, createBkashCallbackHandler, createBkashWebhookHandler };