paykit-bd 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joarder97
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# paykit-bd
+
+Typed, zero-dependency payment clients for Bangladeshi gateways. bKash tokenized
+checkout today; the provider seam is there so Nagad and SSLCommerz slot in
+without rewriting order handling.
+
+Checked against the live bKash sandbox, not only against the docs — which turned
+out to be wrong or silent in seven places, listed in
+[docs/bkash.md](docs/bkash.md).
+
+```bash
+npm install paykit-bd
+```
+
+Node 20+. No runtime dependencies — `fetch` and `node:crypto` are enough.
+
+## Quickstart
+
+```ts
+import { BkashClient, configFromEnv } from "paykit-bd/bkash";
+
+const bkash = new BkashClient(configFromEnv());
+
+// 1. Start the payment and send the customer to bKash.
+const payment = await bkash.createPayment({ amount: "500", reference: "ORD-1042" });
+redirect(payment.redirectUrl!);
+
+// 2. When they come back, ask bKash what actually happened.
+const settled = await bkash.executePayment(payment.paymentId);
+if (settled.status === "completed") {
+  await fulfilOrder("ORD-1042", settled.transactionId!);
+}
+```
+
+The redirect back from bKash carries `status=success`, and it is worth nothing on
+its own — the customer's browser followed that URL and could have edited it.
+`executePayment` is what decides.
+
+## Webhooks (IPN)
+
+bKash delivers payment notifications through Amazon SNS, so what has to be
+verified is an **SNS message signature** — not an HMAC of the body, which is what
+most bKash integrations assume, and then skip.
+
+```ts
+// app/api/bkash/webhook/route.ts
+import { createBkashWebhookHandler } from "paykit-bd/bkash/next";
+
+export const POST = createBkashWebhookHandler(bkash, {
+  onPaymentCompleted: async (event) => {
+    await markPaid(event.reference!, event.transactionId!, event.amount!);
+  },
+});
+```
+
+Express needs the raw body, and bKash posts as `text/plain`, so `express.json()`
+sees nothing:
+
+```ts
+import { bkashWebhookMiddleware, rawBodyParser } from "paykit-bd/bkash/express";
+
+app.post("/api/bkash/webhook", rawBodyParser(), bkashWebhookMiddleware(bkash, {
+  onPaymentCompleted: fulfilOrder,
+}));
+```
+
+Set `BKASH_WEBHOOK_TOPIC_ARN` to your own SNS topic. Without it, any
+Amazon-signed topic passes — including someone else's merchant account.
+
+## What this handles that a hand-rolled client usually does not
+
+**The refresh-token trap.** bKash blocks your merchant account for a full hour if
+the Refresh Token API is called more than twice in an hour. The budget belongs to
+the account, not to your process, so this counts refreshes in a rolling window,
+falls back to a fresh Grant when the budget is spent, de-duplicates concurrent
+callers into one acquisition, and opens a local circuit breaker at ten
+acquisitions per hour rather than letting a retry loop get you blocked. Put the
+token in a shared store and it stays correct across instances:
+
+```ts
+new BkashClient(config, { tokenStore: createKvTokenStore(redis) })
+```
+
+**Forged webhooks.** The SNS signature is verified against a certificate fetched
+from a URL *inside the message*. A verifier that does not pin that URL to an
+Amazon host will fetch an attacker's certificate and confirm the attacker's own
+signature over a forged "payment completed" — free orders with a clean audit
+trail. `SigningCertURL` is checked against `sns.<region>.amazonaws.com` before
+anything is fetched.
+
+**`sku` and `reason` are mandatory on refunds.** The docs read as though they were
+optional. Omit either and the v2 refund API answers
+`{"message": "Invalid request body"}` — no code, no field name. Defaults are
+always sent.
+
+**Timestamps that `Date` cannot parse.** bKash sends
+`2026-09-18T06:00:19:952 GMT+0600` — a colon before the milliseconds. `new Date()`
+returns `Invalid Date`. The refund API drops the offset entirely and means
+Bangladesh time.
+
+**Four different error envelopes**, depending on endpoint and version:
+`{statusCode}` with HTTP 200 (a 200 is not success), `{errorCode}`,
+`{internalCode, externalCode, errorMessageEn}` on the v2 refund API, and
+`{message}` from the API Gateway in front of bKash. All four normalise to one
+`BkashError` with the code, whether the customer caused it, and whether the
+payment was already settled.
+
+**Money as integers.** Amounts are handled in poisha, never floats, so partial
+refunds still sum to the original.
+
+**Field names that change between endpoints.** Create and execute return
+`merchantInvoiceNumber`; query returns `merchantInvoice`. Every endpoint takes
+`paymentID` except the v2 refund API, which takes `paymentId`.
+
+## Try it without credentials
+
+```bash
+pnpm smoke
+```
+
+Runs against the real bKash sandbox using bKash's published demo credentials. It
+grants a token, refreshes it and checks the budget moved, creates an agreement
+and a payment, queries the payment, confirms a premature execute is refused,
+exercises the error envelopes, and prints a URL you can open to finish the
+payment by hand. It also runs in CI on every push.
+
+## API
+
+| | |
+| --- | --- |
+| `createPayment(input)` | Mode 0011, or 0001 with `extra.agreementID`. |
+| `executePayment(paymentId)` | Finalise. Re-queries instead of throwing if bKash says it already ran. |
+| `getPayment(paymentId)` | Current state. Safe to repeat — this is the recovery path. |
+| `refund(input)` | Full or partial. Reads `maxRefundableAmount` when no amount is given. |
+| `getRefunds({paymentId, transactionId})` | Every refund taken against a transaction. |
+| `verifyWebhook(request)` | Verify an IPN message and normalise it. |
+| `createAgreement` / `executeAgreement` | Two-step setup for PIN-only repeat payments. |
+| `getAgreement` / `cancelAgreement` | Undocumented by bKash, live in sandbox. |
+| `tokenBudget()` | Refreshes used this hour. Worth putting on a health endpoint. |
+
+Details and the full endpoint map: [docs/bkash.md](docs/bkash.md).
+Adding a gateway: [docs/adding-a-provider.md](docs/adding-a-provider.md).
+
+## Status
+
+bKash tokenized checkout is complete. Nagad and SSLCommerz are not written yet —
+the `PaymentProvider` interface is the seam they plug into.
+
+**Verified against the live sandbox:** grant token, refresh token, create
+agreement (0000), create payment (0011, both `sale` and `authorization`), execute,
+query payment, agreement status and cancel, refund and refund status on v2, and
+all four error envelopes.
+
+**Not verified end to end, because it needs a human with a test wallet:** a
+completed payment, and therefore executing an agreement (0001), and a refund of
+real money. Those paths are covered by unit tests against recorded response
+shapes, which is weaker evidence — `pnpm smoke` prints a URL if you want to
+finish a payment by hand and check.
+
+**Not verified at all:** a real inbound IPN message, which needs bKash support to
+register a listener URL against a live merchant account. The SNS verification is
+tested against signatures generated with a real RSA key the same way Amazon
+generates them, but no message from bKash itself has passed through it. If you
+wire one up, an issue saying whether it verified would be useful.
+
+## License
+
+MIT

package/dist/bkash/adapters/express.cjs

@@ -0,0 +1,128 @@
+'use strict';
+
+// 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/bkash/adapters/express.ts
+function rawBodyParser(limitBytes = 1e6) {
+  return function parse(req, res, next) {
+    if (typeof req.body === "string") {
+      next();
+      return;
+    }
+    let data = "";
+    let size = 0;
+    req.setEncoding?.("utf8");
+    req.on("data", (chunk) => {
+      const text = String(chunk);
+      size += Buffer.byteLength(text, "utf8");
+      if (size > limitBytes) {
+        next(new Error(`paykit/bkash: webhook body exceeded ${limitBytes} bytes`));
+        return;
+      }
+      data += text;
+    });
+    req.on("end", () => {
+      req.body = data;
+      next();
+    });
+    req.on("error", (error) => next(error));
+  };
+}
+function bkashWebhookMiddleware(client, options = {}) {
+  return async function handle(req, res) {
+    const rawBody = typeof req.body === "string" ? req.body : Buffer.isBuffer(req.body) ? req.body.toString("utf8") : "";
+    if (!rawBody) {
+      res.status(400).json({
+        ok: false,
+        error: "paykit/bkash: empty raw body. bKash posts its IPN as text/plain, so mount rawBodyParser() (or express.text({ type: '*/*' })) on this route before this middleware."
+      });
+      return;
+    }
+    let event;
+    try {
+      event = await client.verifyWebhook({ body: rawBody, headers: req.headers });
+    } catch (error) {
+      await options.onVerificationFailure?.(error, rawBody);
+      res.status(400).json({
+        ok: false,
+        error: error instanceof WebhookVerificationError ? error.message : "webhook verification failed"
+      });
+      return;
+    }
+    try {
+      if (event.type === "subscription.confirmation") {
+        const envelope = event.raw;
+        const shouldConfirm = await options.onSubscriptionConfirmation?.(envelope) ?? false;
+        if (shouldConfirm) await client.webhooks.confirmSubscription(envelope);
+        res.status(200).json({ ok: true, confirmed: shouldConfirm });
+        return;
+      }
+      if (event.type === "payment.completed") {
+        await options.onPaymentCompleted?.(event);
+      } else {
+        await options.onOtherEvent?.(event);
+      }
+      res.status(200).json({ ok: true });
+    } catch (error) {
+      res.status(500).json({ ok: false, error: error instanceof Error ? error.message : "handler failed" });
+    }
+  };
+}
+
+exports.bkashWebhookMiddleware = bkashWebhookMiddleware;
+exports.rawBodyParser = rawBodyParser;

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

@@ -0,0 +1,50 @@
+import { W as WebhookEvent } from '../../token-store-C8IMMLPJ.cjs';
+import { S as SnsEnvelope, B as BkashClient } from '../../client-UNDtdWhu.cjs';
+
+/**
+ * Express middleware.
+ *
+ * ```ts
+ * import express from "express";
+ * import { bkashWebhookMiddleware, rawBodyParser } from "paykit-bd/bkash/express";
+ *
+ * app.post("/api/bkash/webhook",
+ *   rawBodyParser(),
+ *   bkashWebhookMiddleware(bkash, { onPaymentCompleted: fulfilOrder }));
+ * ```
+ *
+ * **The body parser matters.** bKash sends its IPN with
+ * `Content-Type: text/plain; charset=UTF-8`, so `express.json()` ignores it and
+ * `req.body` arrives empty. Even with the right content type, a parsed and
+ * re-serialised body no longer matches the signature. Use {@link rawBodyParser}
+ * or `express.text({ type: "*​/*" })` on this route only.
+ *
+ * Typed structurally so Express is not a dependency of this package.
+ */
+
+interface ExpressRequestLike {
+    body?: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    setEncoding?(encoding: string): void;
+    on(event: string, listener: (chunk?: unknown) => void): unknown;
+}
+interface ExpressResponseLike {
+    status(code: number): ExpressResponseLike;
+    json(body: unknown): unknown;
+}
+type NextFn = (error?: unknown) => void;
+interface ExpressWebhookOptions {
+    onPaymentCompleted?: (event: WebhookEvent) => Promise<void> | void;
+    onOtherEvent?: (event: WebhookEvent) => Promise<void> | void;
+    /** Return true to confirm the SNS subscription. Default false — see the Next adapter. */
+    onSubscriptionConfirmation?: (envelope: SnsEnvelope) => Promise<boolean> | boolean;
+    onVerificationFailure?: (error: unknown, rawBody: string) => Promise<void> | void;
+}
+/**
+ * Collect the raw request body into `req.body` as a string, whatever the
+ * content type. Mount it on the webhook route only.
+ */
+declare function rawBodyParser(limitBytes?: number): (req: ExpressRequestLike, res: ExpressResponseLike, next: NextFn) => void;
+declare function bkashWebhookMiddleware(client: BkashClient, options?: ExpressWebhookOptions): (req: ExpressRequestLike, res: ExpressResponseLike) => Promise<void>;
+
+export { type ExpressWebhookOptions, bkashWebhookMiddleware, rawBodyParser };

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

@@ -0,0 +1,50 @@
+import { W as WebhookEvent } from '../../token-store-C8IMMLPJ.js';
+import { S as SnsEnvelope, B as BkashClient } from '../../client-Y9603twG.js';
+
+/**
+ * Express middleware.
+ *
+ * ```ts
+ * import express from "express";
+ * import { bkashWebhookMiddleware, rawBodyParser } from "paykit-bd/bkash/express";
+ *
+ * app.post("/api/bkash/webhook",
+ *   rawBodyParser(),
+ *   bkashWebhookMiddleware(bkash, { onPaymentCompleted: fulfilOrder }));
+ * ```
+ *
+ * **The body parser matters.** bKash sends its IPN with
+ * `Content-Type: text/plain; charset=UTF-8`, so `express.json()` ignores it and
+ * `req.body` arrives empty. Even with the right content type, a parsed and
+ * re-serialised body no longer matches the signature. Use {@link rawBodyParser}
+ * or `express.text({ type: "*​/*" })` on this route only.
+ *
+ * Typed structurally so Express is not a dependency of this package.
+ */
+
+interface ExpressRequestLike {
+    body?: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    setEncoding?(encoding: string): void;
+    on(event: string, listener: (chunk?: unknown) => void): unknown;
+}
+interface ExpressResponseLike {
+    status(code: number): ExpressResponseLike;
+    json(body: unknown): unknown;
+}
+type NextFn = (error?: unknown) => void;
+interface ExpressWebhookOptions {
+    onPaymentCompleted?: (event: WebhookEvent) => Promise<void> | void;
+    onOtherEvent?: (event: WebhookEvent) => Promise<void> | void;
+    /** Return true to confirm the SNS subscription. Default false — see the Next adapter. */
+    onSubscriptionConfirmation?: (envelope: SnsEnvelope) => Promise<boolean> | boolean;
+    onVerificationFailure?: (error: unknown, rawBody: string) => Promise<void> | void;
+}
+/**
+ * Collect the raw request body into `req.body` as a string, whatever the
+ * content type. Mount it on the webhook route only.
+ */
+declare function rawBodyParser(limitBytes?: number): (req: ExpressRequestLike, res: ExpressResponseLike, next: NextFn) => void;
+declare function bkashWebhookMiddleware(client: BkashClient, options?: ExpressWebhookOptions): (req: ExpressRequestLike, res: ExpressResponseLike) => Promise<void>;
+
+export { type ExpressWebhookOptions, bkashWebhookMiddleware, rawBodyParser };

package/dist/bkash/adapters/express.js

@@ -0,0 +1,125 @@
+// 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/bkash/adapters/express.ts
+function rawBodyParser(limitBytes = 1e6) {
+  return function parse(req, res, next) {
+    if (typeof req.body === "string") {
+      next();
+      return;
+    }
+    let data = "";
+    let size = 0;
+    req.setEncoding?.("utf8");
+    req.on("data", (chunk) => {
+      const text = String(chunk);
+      size += Buffer.byteLength(text, "utf8");
+      if (size > limitBytes) {
+        next(new Error(`paykit/bkash: webhook body exceeded ${limitBytes} bytes`));
+        return;
+      }
+      data += text;
+    });
+    req.on("end", () => {
+      req.body = data;
+      next();
+    });
+    req.on("error", (error) => next(error));
+  };
+}
+function bkashWebhookMiddleware(client, options = {}) {
+  return async function handle(req, res) {
+    const rawBody = typeof req.body === "string" ? req.body : Buffer.isBuffer(req.body) ? req.body.toString("utf8") : "";
+    if (!rawBody) {
+      res.status(400).json({
+        ok: false,
+        error: "paykit/bkash: empty raw body. bKash posts its IPN as text/plain, so mount rawBodyParser() (or express.text({ type: '*/*' })) on this route before this middleware."
+      });
+      return;
+    }
+    let event;
+    try {
+      event = await client.verifyWebhook({ body: rawBody, headers: req.headers });
+    } catch (error) {
+      await options.onVerificationFailure?.(error, rawBody);
+      res.status(400).json({
+        ok: false,
+        error: error instanceof WebhookVerificationError ? error.message : "webhook verification failed"
+      });
+      return;
+    }
+    try {
+      if (event.type === "subscription.confirmation") {
+        const envelope = event.raw;
+        const shouldConfirm = await options.onSubscriptionConfirmation?.(envelope) ?? false;
+        if (shouldConfirm) await client.webhooks.confirmSubscription(envelope);
+        res.status(200).json({ ok: true, confirmed: shouldConfirm });
+        return;
+      }
+      if (event.type === "payment.completed") {
+        await options.onPaymentCompleted?.(event);
+      } else {
+        await options.onOtherEvent?.(event);
+      }
+      res.status(200).json({ ok: true });
+    } catch (error) {
+      res.status(500).json({ ok: false, error: error instanceof Error ? error.message : "handler failed" });
+    }
+  };
+}
+
+export { bkashWebhookMiddleware, rawBodyParser };