paykit-bd 0.1.0

package/dist/bkash/index.cjs

@@ -0,0 +1,1335 @@
+'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 ProviderError = class extends PaykitError {
+  static [Symbol.hasInstance] = brandedInstanceOf("ProviderError");
+  constructor(message, opts, brands = []) {
+    super(message, opts, ["ProviderError", ...brands]);
+  }
+};
+var NetworkError = class extends PaykitError {
+  static [Symbol.hasInstance] = brandedInstanceOf("NetworkError");
+  /** HTTP status, when there was one. */
+  status;
+  constructor(message, opts) {
+    super(
+      message,
+      {
+        provider: opts.provider,
+        code: opts.code ?? "network_error",
+        retryable: true,
+        raw: opts.raw,
+        cause: opts.cause
+      },
+      ["NetworkError"]
+    );
+    this.status = opts.status;
+  }
+};
+var ConfigError = class extends PaykitError {
+  static [Symbol.hasInstance] = brandedInstanceOf("ConfigError");
+  constructor(message, opts = {}) {
+    super(
+      message,
+      {
+        provider: opts.provider ?? "paykit",
+        code: opts.code ?? "config_error",
+        retryable: false
+      },
+      ["ConfigError"]
+    );
+  }
+};
+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"]
+    );
+  }
+};
+var RateLimitError = class extends PaykitError {
+  static [Symbol.hasInstance] = brandedInstanceOf("RateLimitError");
+  /** Epoch ms when the guard will let the call through. */
+  retryAt;
+  constructor(message, opts) {
+    super(
+      message,
+      {
+        provider: opts.provider,
+        code: opts.code ?? "rate_limited",
+        retryable: true
+      },
+      ["RateLimitError"]
+    );
+    this.retryAt = opts.retryAt;
+  }
+};
+function brandCheckFor(tag) {
+  return brandedInstanceOf(tag);
+}
+
+// src/core/http.ts
+var noopLogger = {
+  debug() {
+  },
+  warn() {
+  },
+  error() {
+  }
+};
+var DEFAULT_TIMEOUT_MS = 3e4;
+var SECRET_HEADERS = /* @__PURE__ */ new Set(["authorization", "password", "username", "x-app-key", "x-app-secret"]);
+function redactHeaders(headers) {
+  const out = {};
+  for (const [key, value] of Object.entries(headers)) {
+    out[key] = SECRET_HEADERS.has(key.toLowerCase()) ? "[redacted]" : value;
+  }
+  return out;
+}
+async function requestJson(url, options = {}, ctx = { provider: "paykit" }) {
+  const {
+    method = "POST",
+    headers = {},
+    json,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    retries = 0,
+    retryBaseMs = 300,
+    signal
+  } = options;
+  const logger = ctx.logger ?? noopLogger;
+  const requestHeaders = { Accept: "application/json", ...headers };
+  let payload;
+  if (json !== void 0) {
+    payload = JSON.stringify(json);
+    requestHeaders["Content-Type"] ??= "application/json";
+  }
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (attempt > 0) {
+      const delay = retryBaseMs * 2 ** (attempt - 1) + Math.floor(Math.random() * retryBaseMs);
+      logger.warn("paykit: retrying request", { url, attempt, delay });
+      await sleep(delay, signal);
+    }
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: requestHeaders,
+        body: payload,
+        signal: mergeSignals(signal, AbortSignal.timeout(timeoutMs))
+      });
+      const text = await response.text();
+      if (response.status >= 500) {
+        lastError = new NetworkError(`${ctx.provider}: gateway returned HTTP ${response.status}`, {
+          provider: ctx.provider,
+          code: "upstream_error",
+          status: response.status,
+          raw: text.slice(0, 2e3)
+        });
+        if (attempt < retries) continue;
+        throw lastError;
+      }
+      let body;
+      try {
+        body = text ? JSON.parse(text) : {};
+      } catch (cause) {
+        throw new NetworkError(
+          `${ctx.provider}: expected JSON but got ${describeBody(text)} (HTTP ${response.status})`,
+          { provider: ctx.provider, code: "invalid_json", status: response.status, raw: text.slice(0, 2e3), cause }
+        );
+      }
+      logger.debug("paykit: request complete", {
+        url,
+        method,
+        status: response.status,
+        headers: redactHeaders(requestHeaders)
+      });
+      return { status: response.status, headers: response.headers, body, text };
+    } catch (error) {
+      if (error instanceof NetworkError && error.code === "invalid_json") throw error;
+      lastError = error;
+      const aborted = signal?.aborted === true;
+      if (aborted || attempt >= retries) {
+        if (error instanceof NetworkError) throw error;
+        throw new NetworkError(`${ctx.provider}: request to ${url} failed`, {
+          provider: ctx.provider,
+          code: isTimeout(error) ? "timeout" : "network_error",
+          cause: error
+        });
+      }
+    }
+  }
+  throw lastError instanceof Error ? lastError : new NetworkError(`${ctx.provider}: request to ${url} failed`, { provider: ctx.provider });
+}
+function describeBody(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return "an empty body";
+  if (trimmed.startsWith("<")) return "HTML (usually a proxy or WAF page)";
+  return `${JSON.stringify(trimmed.slice(0, 80))}\u2026`;
+}
+function isTimeout(error) {
+  return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+}
+function mergeSignals(...signals) {
+  const present = signals.filter((s) => s !== void 0);
+  return present.length === 1 ? present[0] : AbortSignal.any(present);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/core/money.ts
+var AMOUNT_RE = /^-?\d+(\.\d{1,2})?$/;
+function toPoisha(amount) {
+  const text = typeof amount === "number" ? formatNumber(amount) : amount.trim();
+  if (!AMOUNT_RE.test(text)) {
+    throw new ConfigError(
+      `Invalid BDT amount ${JSON.stringify(amount)}: expected a decimal with at most 2 places, e.g. "12.50".`,
+      { code: "invalid_amount" }
+    );
+  }
+  const negative = text.startsWith("-");
+  const [whole = "0", fraction = ""] = (negative ? text.slice(1) : text).split(".");
+  const poisha = BigInt(whole) * 100n + BigInt(fraction.padEnd(2, "0"));
+  return negative ? -poisha : poisha;
+}
+function fromPoisha(poisha) {
+  const negative = poisha < 0n;
+  const abs = negative ? -poisha : poisha;
+  const whole = abs / 100n;
+  const fraction = (abs % 100n).toString().padStart(2, "0");
+  return `${negative ? "-" : ""}${whole}.${fraction}`;
+}
+function toAmountString(amount) {
+  return fromPoisha(toPoisha(amount));
+}
+function formatNumber(value) {
+  if (!Number.isFinite(value)) {
+    throw new ConfigError(`Invalid BDT amount ${value}: not a finite number.`, { code: "invalid_amount" });
+  }
+  return value.toFixed(2);
+}
+
+// src/bkash/config.ts
+var BKASH_HOSTS = {
+  sandbox: "https://tokenized.sandbox.bka.sh",
+  live: "https://tokenized.pay.bka.sh"
+};
+var BKASH_API_VERSION = "v1.2.0-beta";
+var BKASH_MODE = {
+  /** Create an agreement — no money moves, you get an agreementID back. */
+  CREATE_AGREEMENT: "0000",
+  /** Charge an existing agreement. Customer confirms with a PIN only. */
+  AGREEMENT_PAYMENT: "0001",
+  /** One-off payment, no agreement. Customer is redirected to bKash. */
+  ONE_OFF_PAYMENT: "0011"
+};
+function endpoints(origin) {
+  const versioned = `${origin}/${BKASH_API_VERSION}`;
+  return {
+    grantToken: `${versioned}/tokenized/checkout/token/grant`,
+    refreshToken: `${versioned}/tokenized/checkout/token/refresh`,
+    /** Serves agreement creation and both payment modes; `mode` decides which. */
+    create: `${versioned}/tokenized/checkout/create`,
+    /** Finalises whatever `create` started, agreement or payment. */
+    execute: `${versioned}/tokenized/checkout/execute`,
+    queryPayment: `${versioned}/tokenized/checkout/payment/status`,
+    // Undocumented in the public index but live in sandbox: both answer
+    // "2051 Invalid Agreement ID" for a bad id rather than a routing error.
+    queryAgreement: `${versioned}/tokenized/checkout/agreement/status`,
+    cancelAgreement: `${versioned}/tokenized/checkout/agreement/cancel`,
+    // The v2 refund API hangs off the host root, not off the version segment.
+    // Probing the sandbox confirms it: the versioned path answers "Missing
+    // Authentication Token", which is API Gateway for "no such route".
+    refund: `${origin}/v2/tokenized-checkout/refund/payment/transaction`,
+    refundStatus: `${origin}/v2/tokenized-checkout/refund/payment/status`,
+    /** Pre-v2 refund, still provisioned for some merchants. */
+    legacyRefund: `${versioned}/tokenized/checkout/payment/refund`
+  };
+}
+function resolveConfig(config) {
+  const missing = ["username", "password", "appKey", "appSecret"].filter(
+    (key) => !config[key] || String(config[key]).trim() === ""
+  );
+  if (missing.length > 0) {
+    throw new ConfigError(
+      `bKash: missing required credential${missing.length > 1 ? "s" : ""} ${missing.join(", ")}. These are issued by bKash during merchant onboarding.`,
+      { provider: "bkash", code: "missing_credentials" }
+    );
+  }
+  const environment = config.environment ?? "sandbox";
+  if (!config.baseUrl && !(environment in BKASH_HOSTS)) {
+    throw new ConfigError(`bKash: unknown environment ${JSON.stringify(environment)}; expected "sandbox" or "live".`, {
+      provider: "bkash",
+      code: "invalid_environment"
+    });
+  }
+  const origin = stripTrailingSlash(config.baseUrl ?? BKASH_HOSTS[environment]);
+  return {
+    environment,
+    origin,
+    username: config.username,
+    password: config.password,
+    appKey: config.appKey,
+    appSecret: config.appSecret,
+    callbackUrl: config.callbackUrl,
+    tokenKey: config.tokenKey ?? `bkash:${environment}:${config.appKey.slice(0, 12)}`,
+    refreshSkewMs: config.refreshSkewMs ?? 10 * 60 * 1e3,
+    maxRefreshesPerHour: config.maxRefreshesPerHour ?? 2,
+    timeoutMs: config.timeoutMs ?? 3e4,
+    webhookTopicArn: config.webhookTopicArn
+  };
+}
+function configFromEnv(env = process.env) {
+  const environment = env["BKASH_ENV"] ?? "sandbox";
+  return {
+    environment,
+    baseUrl: env["BKASH_BASE_URL"],
+    username: env["BKASH_USERNAME"] ?? "",
+    password: env["BKASH_PASSWORD"] ?? "",
+    appKey: env["BKASH_APP_KEY"] ?? "",
+    appSecret: env["BKASH_APP_SECRET"] ?? "",
+    callbackUrl: env["BKASH_CALLBACK_URL"],
+    webhookTopicArn: env["BKASH_WEBHOOK_TOPIC_ARN"]
+  };
+}
+function stripTrailingSlash(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+// src/bkash/errors.ts
+var BKASH_ERROR_CODES = {
+  "0000": "Successful",
+  "2001": "Invalid App Key",
+  "2002": "Invalid Payment ID",
+  "2003": "Process failed",
+  "2004": "Invalid firstPaymentDate",
+  "2005": "Invalid frequency",
+  "2006": "Invalid amount",
+  "2007": "Invalid currency",
+  "2008": "Invalid intent",
+  "2009": "Invalid Wallet",
+  "2010": "Invalid OTP",
+  "2011": "Invalid PIN",
+  "2012": "Invalid Receiver MSISDN",
+  "2013": "Resend Limit Exceeded",
+  "2014": "Wrong PIN",
+  "2015": "Wrong PIN count exceeded",
+  "2016": "Wrong verification code",
+  "2017": "Wrong verification limit exceeded",
+  "2018": "OTP verification time expired",
+  "2019": "PIN verification time expired",
+  "2020": "Exception Occurred",
+  "2021": "Invalid Mandate ID",
+  "2022": "The mandate does not exist",
+  "2023": "Insufficient Balance",
+  "2024": "Exception occurred",
+  "2025": "Invalid request body",
+  "2026": "The reversal amount cannot be greater than the original transaction amount",
+  "2027": "The mandate corresponding to the payer reference number already exists and cannot be created again",
+  "2028": "Reverse failed because the transaction serial number does not exist",
+  "2029": "Duplicate for all transactions",
+  "2030": "Invalid mandate request type",
+  "2031": "Invalid merchant invoice number",
+  "2032": "Invalid transfer type",
+  "2033": "Transaction not found",
+  "2034": "The transaction cannot be reversed because the original transaction has been reversed",
+  "2035": "Reverse failed because the initiator has no permission to reverse the transaction",
+  "2036": "The direct debit mandate is not in Active state",
+  "2037": "The account of the debit party is in a state which prohibits execution of this transaction",
+  "2038": "Debit party identity tag prohibits execution of this transaction",
+  "2039": "The account of the credit party is in a state which prohibits execution of this transaction",
+  "2040": "Credit party identity tag prohibits execution of this transaction",
+  "2041": "Credit party identity is in a state which does not support the current service",
+  "2042": "Reverse failed because the initiator has no permission to reverse the transaction",
+  "2043": "The security credential of the subscriber is incorrect",
+  "2044": "Identity has not subscribed to a product that contains the expected service, or the identity is not in Active status",
+  "2045": "The MSISDN of the customer does not exist",
+  "2046": "Identity has not subscribed to a product that contains requested service",
+  "2047": "TLV Data Format Error",
+  "2048": "Invalid Payer Reference",
+  "2049": "Invalid Merchant Callback URL",
+  "2050": "Agreement already exists between payer and merchant",
+  "2051": "Invalid Agreement ID",
+  "2052": "Agreement is in incomplete state",
+  "2053": "Agreement has already been cancelled",
+  "2054": "Agreement execution pre-requisite hasn't been met",
+  "2055": "Invalid Agreement State",
+  "2056": "Invalid Payment State",
+  "2057": "Not a bKash Account",
+  "2058": "Not a Customer Wallet",
+  "2059": "Multiple OTP request for a single session denied",
+  "2060": "Payment execution pre-requisite hasn't been met",
+  "2061": "This action can only be performed by the agreement or payment initiator party",
+  "2062": "The payment has already been completed",
+  "2063": "Mode is not valid as per request data",
+  "2064": "This product mode currently unavailable",
+  "2065": "Mandatory field missing",
+  "2066": "Agreement is not shared with other merchant",
+  "2067": "Invalid permission",
+  "2068": "Transaction has already been completed",
+  "2069": "Transaction has already been cancelled",
+  "2116": "The agreement execution has already been completed",
+  "2117": "The payment execution has already been completed",
+  "2118": "The Platform value is invalid",
+  "2119": "The authorized payment has already been processed"
+};
+var RETRYABLE_CODES = /* @__PURE__ */ new Set(["2003", "2020", "2024"]);
+var ALREADY_SETTLED_CODES = /* @__PURE__ */ new Set(["2062", "2068", "2116", "2117", "2119"]);
+var CUSTOMER_FAULT_CODES = /* @__PURE__ */ new Set([
+  "2010",
+  "2011",
+  "2013",
+  "2014",
+  "2015",
+  "2016",
+  "2017",
+  "2018",
+  "2019",
+  "2023",
+  "2057",
+  "2058",
+  "2059"
+]);
+var BkashError = class extends ProviderError {
+  // Branded like the core errors so `instanceof` holds across this package's
+  // separate entry-point bundles. See the note in src/core/errors.ts.
+  static [Symbol.hasInstance] = brandCheckFor("BkashError");
+  /** True when bKash considers the payment already settled — re-query, don't retry. */
+  alreadySettled;
+  /** True when the customer caused it (wrong PIN, no balance). */
+  customerFault;
+  /** Bangla message, on the v2 refund API only. */
+  messageBn;
+  constructor(opts) {
+    super(
+      opts.message,
+      {
+        provider: "bkash",
+        code: opts.code,
+        retryable: opts.retryable ?? RETRYABLE_CODES.has(opts.code),
+        raw: opts.raw
+      },
+      ["BkashError"]
+    );
+    this.alreadySettled = ALREADY_SETTLED_CODES.has(opts.code);
+    this.customerFault = CUSTOMER_FAULT_CODES.has(opts.code);
+    this.messageBn = opts.messageBn;
+  }
+};
+function toBkashError(body, status) {
+  if (typeof body !== "object" || body === null) {
+    return new NetworkError(`bKash: unreadable response body (HTTP ${status})`, {
+      provider: "bkash",
+      raw: body,
+      status
+    });
+  }
+  const b = body;
+  if (typeof b["externalCode"] === "string" || typeof b["internalCode"] === "string") {
+    const code = b["externalCode"] ?? b["internalCode"];
+    return new BkashError({
+      code,
+      message: describe(code, b["errorMessageEn"] ?? b["internalCode"]),
+      messageBn: b["errorMessageBn"] ?? void 0,
+      raw: body
+    });
+  }
+  if (typeof b["errorCode"] === "string" && b["errorCode"] !== "") {
+    const code = b["errorCode"];
+    return new BkashError({ code, message: describe(code, b["errorMessage"]), raw: body });
+  }
+  if (typeof b["statusCode"] === "string") {
+    const code = b["statusCode"];
+    if (code === "0000") return null;
+    return new BkashError({ code, message: describe(code, b["statusMessage"]), raw: body });
+  }
+  if (status >= 400) {
+    const message = typeof b["message"] === "string" ? b["message"] : `HTTP ${status}`;
+    if (status === 401 || status === 403) {
+      return new BkashError({
+        code: "unauthorized",
+        message: `bKash rejected the request before reaching the payment API: ${message}. Usually an expired or malformed id_token, or an x-app-key that does not match the token.`,
+        raw: body
+      });
+    }
+    return new BkashError({ code: `http_${status}`, message: `bKash: ${message}`, raw: body });
+  }
+  return null;
+}
+function describe(code, message) {
+  const known = BKASH_ERROR_CODES[code];
+  const text = message?.trim() || known || "Unknown error";
+  return known && message && known.toLowerCase() !== message.trim().toLowerCase() ? `bKash ${code}: ${text} (${known})` : `bKash ${code}: ${text}`;
+}
+function parseBkashTime(value) {
+  if (!value) return void 0;
+  const match = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?::(\d{1,3}))?(?:\s*(?:GMT|UTC)?\s*([+-])(\d{2}):?(\d{2}))?\s*$/.exec(
+    value.trim()
+  );
+  if (!match) {
+    const fallback = new Date(value);
+    return Number.isNaN(fallback.getTime()) ? void 0 : fallback;
+  }
+  const [, y, mo, d, h, mi, s, ms, sign, offH, offM] = match;
+  const offsetMinutes = sign && offH && offM ? (sign === "-" ? -1 : 1) * (Number(offH) * 60 + Number(offM)) : 6 * 60;
+  const utcMs = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s), Number((ms ?? "0").padEnd(3, "0"))) - offsetMinutes * 6e4;
+  const date = new Date(utcMs);
+  return Number.isNaN(date.getTime()) ? void 0 : date;
+}
+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/core/token-store.ts
+var MemoryTokenStore = class {
+  #records = /* @__PURE__ */ new Map();
+  async get(key) {
+    return this.#records.get(key) ?? null;
+  }
+  async set(key, record) {
+    this.#records.set(key, record);
+  }
+  async delete(key) {
+    this.#records.delete(key);
+  }
+};
+
+// src/bkash/token-manager.ts
+var HOUR_MS = 60 * 60 * 1e3;
+var ACQUISITION_CIRCUIT_BREAKER = 10;
+var BkashTokenManager = class {
+  #config;
+  #store;
+  #logger;
+  #urls;
+  #inFlight = null;
+  constructor(config, options = {}) {
+    this.#config = config;
+    this.#store = options.store ?? new MemoryTokenStore();
+    this.#logger = options.logger ?? noopLogger;
+    this.#urls = endpoints(config.origin);
+  }
+  /** A token that is valid now, acquiring one only if the cached one will not do. */
+  async getToken() {
+    const record = await this.#store.get(this.#config.tokenKey);
+    if (record && !this.#needsRefresh(record)) return record.idToken;
+    this.#inFlight ??= this.#acquire(record).finally(() => {
+      this.#inFlight = null;
+    });
+    return this.#inFlight;
+  }
+  /**
+   * Drop the cached token so the next call acquires a new one. Use this when
+   * bKash answers 401 — it means the token died earlier than advertised.
+   */
+  async invalidate() {
+    const record = await this.#store.get(this.#config.tokenKey);
+    if (!record) return;
+    await this.#store.set(this.#config.tokenKey, { ...record, expiresAt: 0 });
+  }
+  /**
+   * Force one refresh, spending a unit of the hourly budget. Only useful for
+   * proving the refresh path works — normal use should let {@link getToken}
+   * decide. Throws if the budget is already spent.
+   */
+  async refreshNow() {
+    const record = await this.#store.get(this.#config.tokenKey);
+    if (!record?.refreshToken) {
+      throw new ConfigError("bKash: no refresh_token stored yet \u2014 grant a token first.", {
+        provider: "bkash",
+        code: "no_refresh_token"
+      });
+    }
+    const now = Date.now();
+    const refreshes = withinWindow(record.refreshes, now);
+    if (refreshes.length >= this.#config.maxRefreshesPerHour) {
+      throw new RateLimitError(
+        `bKash: refresh budget for this hour is already spent (${refreshes.length}/${this.#config.maxRefreshesPerHour}).`,
+        { provider: "bkash", code: "refresh_budget_spent", retryAt: (refreshes[0] ?? now) + HOUR_MS }
+      );
+    }
+    const response = await this.#call(this.#urls.refreshToken, {
+      app_key: this.#config.appKey,
+      app_secret: this.#config.appSecret,
+      refresh_token: record.refreshToken
+    });
+    if (!response.id_token) {
+      throw new BkashError({
+        code: response.statusCode ?? "no_token",
+        message: `bKash refresh returned no id_token: ${response.statusMessage ?? "no status message"}`,
+        raw: response
+      });
+    }
+    await this.#store.set(this.#config.tokenKey, {
+      idToken: response.id_token,
+      refreshToken: response.refresh_token ?? record.refreshToken,
+      expiresAt: Date.now() + (Number(response.expires_in) || 3600) * 1e3,
+      acquisitions: [...withinWindow(record.acquisitions, now), Date.now()],
+      refreshes: [...refreshes, Date.now()]
+    });
+    return response.id_token;
+  }
+  /** What the budget looks like right now. Useful for a health endpoint. */
+  async budget() {
+    const record = await this.#store.get(this.#config.tokenKey);
+    const now = Date.now();
+    return {
+      refreshesUsed: withinWindow(record?.refreshes, now).length,
+      refreshesAllowed: this.#config.maxRefreshesPerHour,
+      acquisitionsUsed: withinWindow(record?.acquisitions, now).length
+    };
+  }
+  #needsRefresh(record) {
+    return Date.now() >= record.expiresAt - this.#config.refreshSkewMs;
+  }
+  async #acquire(cached) {
+    const run = async () => {
+      const current = await this.#store.get(this.#config.tokenKey);
+      if (current && !this.#needsRefresh(current)) return current.idToken;
+      const record = current ?? cached;
+      const now = Date.now();
+      const acquisitions = withinWindow(record?.acquisitions, now);
+      const refreshes = withinWindow(record?.refreshes, now);
+      if (acquisitions.length >= ACQUISITION_CIRCUIT_BREAKER) {
+        const retryAt = (acquisitions[0] ?? now) + HOUR_MS;
+        throw new RateLimitError(
+          `bKash: ${acquisitions.length} token acquisitions in the last hour, which is past the safety ceiling. Refusing to call bKash again until ${new Date(retryAt).toISOString()} \u2014 going further risks an hour-long block on the merchant account. This usually means a retry loop, or a per-request client instance with no shared token store.`,
+          { provider: "bkash", code: "token_circuit_open", retryAt }
+        );
+      }
+      const canRefresh = record?.refreshToken && refreshes.length < this.#config.maxRefreshesPerHour;
+      if (record?.refreshToken && !canRefresh) {
+        this.#logger.warn("paykit/bkash: refresh budget spent this hour, granting a new token instead", {
+          refreshesUsed: refreshes.length,
+          allowed: this.#config.maxRefreshesPerHour
+        });
+      }
+      const response = canRefresh ? await this.#call(this.#urls.refreshToken, {
+        app_key: this.#config.appKey,
+        app_secret: this.#config.appSecret,
+        refresh_token: record.refreshToken
+      }) : await this.#call(this.#urls.grantToken, {
+        app_key: this.#config.appKey,
+        app_secret: this.#config.appSecret
+      });
+      if (!response.id_token) {
+        throw new BkashError({
+          code: response.statusCode ?? "no_token",
+          message: `bKash returned no id_token: ${response.statusMessage ?? "no status message"}`,
+          raw: response
+        });
+      }
+      const lifetimeMs = (Number(response.expires_in) || 3600) * 1e3;
+      const next = {
+        idToken: response.id_token,
+        refreshToken: response.refresh_token ?? record?.refreshToken ?? "",
+        expiresAt: Date.now() + lifetimeMs,
+        acquisitions: [...acquisitions, Date.now()],
+        refreshes: canRefresh ? [...refreshes, Date.now()] : refreshes
+      };
+      await this.#store.set(this.#config.tokenKey, next);
+      this.#logger.debug("paykit/bkash: token acquired", {
+        method: canRefresh ? "refresh" : "grant",
+        expiresInSeconds: Math.round(lifetimeMs / 1e3),
+        refreshesUsedThisHour: next.refreshes.length
+      });
+      return next.idToken;
+    };
+    return this.#store.withLock ? this.#store.withLock(this.#config.tokenKey, 15e3, run) : run();
+  }
+  async #call(url, body) {
+    const { body: parsed, status } = await requestJson(
+      url,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          username: this.#config.username,
+          password: this.#config.password
+        },
+        json: body,
+        timeoutMs: this.#config.timeoutMs,
+        // Token acquisition moves no money, but it does spend budget, so retry
+        // transport failures only, and only once.
+        retries: 1
+      },
+      { provider: "bkash", logger: this.#logger }
+    );
+    const error = toBkashError(parsed, status);
+    if (error) {
+      if (error instanceof NetworkError) throw error;
+      throw error;
+    }
+    return parsed;
+  }
+};
+function withinWindow(timestamps, now) {
+  return (timestamps ?? []).filter((t) => now - t < HOUR_MS).sort((a, b) => a - b);
+}
+var SNS_CERT_HOST = /^sns\.[a-z0-9-]+\.amazonaws\.com(\.cn)?$/i;
+var BKASH_TRANSACTION_TYPES = {
+  "10002294": "Payment via API",
+  "10003126": "Payment via QR",
+  "10002175": "Payment via USSD",
+  "10002809": "Voucher Redeem",
+  "10002264": "M2M Payment via API",
+  "10003209": "M2M Payment via QR",
+  "10002177": "M2M Payment via USSD",
+  "10003476": "Bank Payment",
+  "10003237": "B2B Collection"
+};
+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/client.ts
+var BkashClient = class {
+  id = "bkash";
+  #config;
+  #urls;
+  #tokens;
+  #logger;
+  #verifier;
+  constructor(config, options = {}) {
+    this.#config = resolveConfig(config);
+    this.#urls = endpoints(this.#config.origin);
+    this.#logger = options.logger ?? config.logger ?? noopLogger;
+    this.#tokens = new BkashTokenManager(this.#config, {
+      store: options.tokenStore ?? config.tokenStore,
+      logger: this.#logger
+    });
+    this.#verifier = new BkashWebhookVerifier({
+      topicArn: this.#config.webhookTopicArn,
+      ...options.webhook,
+      logger: this.#logger
+    });
+  }
+  /** Which environment and host this client is pointed at. */
+  get environment() {
+    return { environment: this.#config.environment, origin: this.#config.origin };
+  }
+  /** Token budget for the current rolling hour. */
+  tokenBudget() {
+    return this.#tokens.budget();
+  }
+  /**
+   * Force a token refresh, spending one unit of the hourly budget. Normal use
+   * should leave this alone and let the client renew when it needs to; it is
+   * here so the refresh path can be exercised deliberately.
+   */
+  refreshToken() {
+    return this.#tokens.refreshNow();
+  }
+  // ---------------------------------------------------------------- agreements
+  /**
+   * Step 1 of 2. Start an agreement so this customer can later pay with a PIN
+   * alone. Send them to `redirectUrl`, then call {@link executeAgreement}.
+   */
+  async createAgreement(input) {
+    const callbackURL = input.callbackUrl ?? this.#config.callbackUrl;
+    if (!callbackURL) throw missingCallback();
+    const raw = await this.#post(this.#urls.create, {
+      mode: BKASH_MODE.CREATE_AGREEMENT,
+      payerReference: input.payerReference,
+      callbackURL
+    });
+    return {
+      paymentId: raw.paymentID ?? "",
+      redirectUrl: raw.bkashURL ?? null,
+      status: raw.agreementStatus ?? "Initiated",
+      raw
+    };
+  }
+  /**
+   * Step 2 of 2. Call once the customer returns to your callback URL. The
+   * `agreementID` it returns is what you store against the customer — it is the
+   * whole point of the flow and bKash will not hand it to you again.
+   */
+  async executeAgreement(paymentId) {
+    const raw = await this.#post(this.#urls.execute, { paymentID: paymentId });
+    return this.#toAgreement(raw);
+  }
+  async getAgreement(agreementId) {
+    const raw = await this.#post(this.#urls.queryAgreement, { agreementID: agreementId });
+    return this.#toAgreement(raw);
+  }
+  /** Ends the agreement. The customer must go through the OTP flow again after this. */
+  async cancelAgreement(agreementId) {
+    const raw = await this.#post(this.#urls.cancelAgreement, { agreementID: agreementId });
+    return this.#toAgreement(raw);
+  }
+  // ------------------------------------------------------------------ payments
+  /**
+   * Start a payment.
+   *
+   * Passing `extra.agreementID` charges an existing agreement (mode 0001) and
+   * returns no `redirectUrl` — the customer confirms with a PIN in the bKash
+   * app. Without it this is a one-off payment (mode 0011) and the customer must
+   * be sent to `redirectUrl`.
+   */
+  async createPayment(input) {
+    const callbackURL = input.callbackUrl ?? this.#config.callbackUrl;
+    if (!callbackURL) throw missingCallback();
+    const agreementID = input.extra?.["agreementID"];
+    const amount = toAmountString(input.amount);
+    const raw = await this.#post(this.#urls.create, {
+      mode: agreementID ? BKASH_MODE.AGREEMENT_PAYMENT : BKASH_MODE.ONE_OFF_PAYMENT,
+      payerReference: input.payerReference ?? input.reference,
+      callbackURL,
+      amount,
+      currency: input.currency ?? "BDT",
+      intent: input.intent ?? "sale",
+      merchantInvoiceNumber: input.reference,
+      ...agreementID ? { agreementID } : {},
+      ...input.extra?.["merchantAssociationInfo"] ? { merchantAssociationInfo: input.extra["merchantAssociationInfo"] } : {}
+    });
+    const createdAt = parseBkashTime(raw.paymentCreateTime);
+    return {
+      provider: this.id,
+      paymentId: raw.paymentID ?? "",
+      redirectUrl: raw.bkashURL ?? null,
+      status: toStatus(raw.transactionStatus),
+      amount: raw.amount ?? amount,
+      currency: raw.currency ?? "BDT",
+      reference: raw.merchantInvoiceNumber ?? input.reference,
+      // A payment id is good for 24 hours and one execution.
+      expiresAt: createdAt ? new Date(createdAt.getTime() + 24 * 60 * 60 * 1e3) : void 0,
+      raw
+    };
+  }
+  /**
+   * Finalise a payment after the customer approves it. Valid exactly once per
+   * payment id.
+   *
+   * If bKash answers that the payment was already executed, this reads the real
+   * outcome with {@link getPayment} instead of throwing — that response means
+   * the money moved, and the caller wants the result, not an error.
+   */
+  async executePayment(paymentId) {
+    try {
+      const raw = await this.#post(this.#urls.execute, { paymentID: paymentId });
+      return {
+        provider: this.id,
+        paymentId: raw.paymentID ?? paymentId,
+        transactionId: raw.trxID ?? null,
+        status: toStatus(raw.transactionStatus),
+        amount: raw.amount ?? "",
+        currency: raw.currency ?? "BDT",
+        reference: raw.merchantInvoiceNumber,
+        payerAccount: raw.customerMsisdn ?? raw.payerReference,
+        completedAt: parseBkashTime(raw.paymentExecuteTime),
+        raw
+      };
+    } catch (error) {
+      if (error instanceof BkashError && error.alreadySettled) {
+        this.#logger.warn("paykit/bkash: payment already executed, reading current state", {
+          paymentId,
+          code: error.code
+        });
+        return this.getPayment(paymentId);
+      }
+      throw error;
+    }
+  }
+  /** Read current state. Safe to call as often as you like — this is the recovery path. */
+  async getPayment(paymentId) {
+    const raw = await this.#post(this.#urls.queryPayment, { paymentID: paymentId });
+    return {
+      provider: this.id,
+      paymentId: raw.paymentID ?? paymentId,
+      transactionId: raw.trxID ?? null,
+      status: toStatus(raw.transactionStatus),
+      amount: raw.amount ?? "",
+      currency: raw.currency ?? "BDT",
+      // The query endpoint calls it merchantInvoice; create and execute call it
+      // merchantInvoiceNumber. Same field.
+      reference: raw.merchantInvoice ?? raw.merchantInvoiceNumber,
+      payerAccount: raw.customerMsisdn ?? raw.payerReference,
+      completedAt: parseBkashTime(raw.paymentExecuteTime),
+      raw
+    };
+  }
+  /** How much of this payment can still be refunded, per bKash. */
+  async getRefundableAmount(paymentId) {
+    const raw = await this.#post(this.#urls.queryPayment, { paymentID: paymentId });
+    return raw.maxRefundableAmount ?? null;
+  }
+  // ------------------------------------------------------------------- refunds
+  /**
+   * Refund all or part of a completed payment.
+   *
+   * The v2 API allows up to ten partial refunds per transaction, within 60 days.
+   * Omit `amount` for a full refund, which is read from bKash's own
+   * `maxRefundableAmount` rather than assumed.
+   */
+  async refund(input) {
+    const refundAmount = input.amount ? toAmountString(input.amount) : await this.getRefundableAmount(input.paymentId) ?? void 0;
+    if (!refundAmount) {
+      throw new ConfigError(
+        `bKash: no refund amount given and bKash reported no refundable balance for payment ${input.paymentId}.`,
+        { provider: "bkash", code: "refund_amount_unknown" }
+      );
+    }
+    const raw = await this.#post(this.#urls.refund, {
+      // Note the lower-case d: the v2 refund API alone spells it paymentId.
+      paymentId: input.paymentId,
+      trxId: input.transactionId,
+      refundAmount,
+      // Both are always sent. They are mandatory at bKash's schema layer even
+      // though the docs present them as optional, and leaving either out gets
+      // you "Invalid request body" with no indication of which field is wrong.
+      sku: input.sku?.trim() || "refund",
+      reason: input.reason?.trim() || "Merchant refund"
+    });
+    return {
+      provider: this.id,
+      refundTransactionId: raw.refundTrxId ?? "",
+      originalTransactionId: raw.originalTrxId ?? input.transactionId,
+      status: toStatus(raw.refundTransactionStatus),
+      amount: raw.refundAmount ?? refundAmount,
+      currency: raw.currency ?? "BDT",
+      completedAt: parseBkashTime(raw.completedTime),
+      raw
+    };
+  }
+  /** Every refund recorded against one transaction. */
+  async getRefunds(input) {
+    const raw = await this.#post(this.#urls.refundStatus, {
+      paymentId: input.paymentId,
+      trxId: input.transactionId
+    });
+    return {
+      originalTransactionId: raw.originalTrxId ?? input.transactionId,
+      originalAmount: raw.originalTrxAmount ?? "",
+      refunds: (raw.refundTransactions ?? []).map((entry) => ({
+        provider: this.id,
+        refundTransactionId: entry.refundTrxId ?? "",
+        originalTransactionId: raw.originalTrxId ?? input.transactionId,
+        status: toStatus(entry.refundTransactionStatus),
+        amount: entry.refundAmount ?? "",
+        currency: "BDT",
+        completedAt: parseBkashTime(entry.completedTime),
+        raw: entry
+      })),
+      raw
+    };
+  }
+  // ------------------------------------------------------------------ webhooks
+  /** Verify an inbound IPN message and normalise it. Throws if it is not genuine. */
+  verifyWebhook(request) {
+    return this.#verifier.verify(request);
+  }
+  get webhooks() {
+    return this.#verifier;
+  }
+  /**
+   * Read the query string bKash appends when it redirects a customer back.
+   *
+   * Nothing here is proof of payment — it is a URL the customer's own browser
+   * followed and could have edited. Always confirm with {@link executePayment}
+   * or {@link getPayment} before releasing an order.
+   */
+  static parseCallback(input) {
+    const params = input instanceof URLSearchParams ? input : typeof input === "string" ? new URL(input, "https://placeholder.invalid").searchParams : input instanceof URL ? input.searchParams : new URLSearchParams(input);
+    return {
+      paymentID: params.get("paymentID") ?? params.get("paymentId") ?? void 0,
+      status: params.get("status") ?? void 0,
+      signature: params.get("signature") ?? void 0,
+      apiVersion: params.get("apiVersion") ?? params.get("version") ?? void 0,
+      product: params.get("product") ?? void 0
+    };
+  }
+  // ------------------------------------------------------------------ internal
+  #toAgreement(raw) {
+    return {
+      agreementId: raw.agreementID ?? "",
+      paymentId: raw.paymentID,
+      customerMsisdn: raw.customerMsisdn,
+      payerReference: raw.payerReference,
+      status: raw.agreementStatus ?? "Unknown",
+      createdAt: parseBkashTime(raw.agreementCreateTime),
+      executedAt: parseBkashTime(raw.agreementExecuteTime),
+      raw
+    };
+  }
+  /**
+   * One POST, with the token attached and the four bKash error envelopes turned
+   * into a thrown BkashError.
+   *
+   * `retries` stays 0: a create or execute that times out may well have
+   * succeeded at bKash, so the safe recovery is getPayment, never a second
+   * attempt. The single exception is a 401, which means the token died early —
+   * that is retried once with a fresh token.
+   */
+  async #post(url, body, isRetry = false) {
+    const token = await this.#tokens.getToken();
+    const { body: parsed, status } = await requestJson(
+      url,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          authorization: token,
+          "x-app-key": this.#config.appKey
+        },
+        json: body,
+        timeoutMs: this.#config.timeoutMs,
+        retries: 0
+      },
+      { provider: "bkash", logger: this.#logger }
+    );
+    const error = toBkashError(parsed, status);
+    if (error) {
+      if (!isRetry && error instanceof BkashError && error.code === "unauthorized") {
+        this.#logger.warn("paykit/bkash: token rejected, acquiring a new one and retrying once", { url });
+        await this.#tokens.invalidate();
+        return this.#post(url, body, true);
+      }
+      throw error;
+    }
+    return parsed;
+  }
+};
+function toStatus(value) {
+  switch ((value ?? "").toLowerCase()) {
+    case "completed":
+      return "completed";
+    case "initiated":
+      return "initiated";
+    case "pending":
+    case "processing":
+      return "pending";
+    case "cancelled":
+    case "canceled":
+      return "cancelled";
+    case "failed":
+      return "failed";
+    default:
+      return value ? "pending" : "initiated";
+  }
+}
+function missingCallback() {
+  return new ConfigError(
+    "bKash: no callback URL. Set `callbackUrl` on the client config (or BKASH_CALLBACK_URL), or pass `callbackUrl` on the call.",
+    { provider: "bkash", code: "missing_callback_url" }
+  );
+}
+
+exports.ALREADY_SETTLED_CODES = ALREADY_SETTLED_CODES;
+exports.BKASH_API_VERSION = BKASH_API_VERSION;
+exports.BKASH_ERROR_CODES = BKASH_ERROR_CODES;
+exports.BKASH_HOSTS = BKASH_HOSTS;
+exports.BKASH_MODE = BKASH_MODE;
+exports.BKASH_TRANSACTION_TYPES = BKASH_TRANSACTION_TYPES;
+exports.BkashClient = BkashClient;
+exports.BkashError = BkashError;
+exports.BkashTokenManager = BkashTokenManager;
+exports.BkashWebhookVerifier = BkashWebhookVerifier;
+exports.CUSTOMER_FAULT_CODES = CUSTOMER_FAULT_CODES;
+exports.assertSnsUrl = assertSnsUrl;
+exports.canonicalString = canonicalString;
+exports.configFromEnv = configFromEnv;
+exports.endpoints = endpoints;
+exports.parseBkashCompactTime = parseBkashCompactTime;
+exports.parseBkashTime = parseBkashTime;
+exports.resolveConfig = resolveConfig;
+exports.toBkashError = toBkashError;