bkash-client 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antigravity Open Source & Contributors
+
+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

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# bkash-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/iamtashanto/Bkash/actions/workflows/ci.yml/badge.svg)](https://github.com/iamtashanto/Bkash/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/bkash-client.svg?color=indigo)](https://www.npmjs.com/package/bkash-client)
+
+Universal, headless, tree-shakeable frontend client SDK for bKash payment integrations. Works with React, React Native, Vue, Svelte, Angular, and vanilla HTML `<script>` tags.
+
+> **Disclaimer:** This is an open-source, community-maintained SDK and is **NOT** officially affiliated with, endorsed by, or sponsored by bKash Limited. "bKash" is a registered trademark of bKash Limited.
+
+---
+
+## Features
+
+- **Headless-First Architecture (0.1.x):** Unstyled, headless state machines and hooks (`useBkash`, `<BkashButton />`, `<BkashCheckout />`). Zero opinionated CSS or bundled stylesheets, giving you 100% control over layout and styling. Pre-packaged themes are planned for post-0.1.
+- **Client States:** Fully typed state machine (`idle`, `creating`, `awaiting_user`, `verifying`, `success`, `pending`, `cancelled`, `timeout`, `offline`, `error`). Unknown or timed-out transactions present "payment pending, do not pay again" rather than false errors.
+- **Zero Frontend Secrets:** Never touches merchant credentials or API keys; communicates strictly with your backend routes.
+- **Framework Bindings:** First-class bindings for React (`useBkash`, `<BkashButton />`), React Native (`<BkashCheckout />`), Vue 3 (`useBkash` with deep Refs), Svelte store (`createBkashStore`), and Angular service (`BkashService`).
+- **Drop-in Script Tag:** Standalone IIFE bundle for plain HTML/JS websites.
+
+> **Alpha Limitation (AUD-04):** On Android devices, `<BkashCheckout />` does not automatically attach a native `BackHandler`. Developers must manage Android hardware back actions in their navigation container until built-in BackHandler integration lands in beta.
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install bkash-client
+
+# pnpm
+pnpm add bkash-client
+
+# bun
+bun add bkash-client
+```
+
+---
+
+## Quickstart (React)
+
+```tsx
+import React from 'react';
+import { useBkash, BkashButton } from 'bkash-client/react';
+
+export function CheckoutPage() {
+  const { state, error, checkout } = useBkash({
+    createUrl: '/api/bkash/create',
+  });
+
+  return (
+    <div>
+      <h2>Order Summary</h2>
+      <BkashButton
+        amount={1550}
+        invoiceNumber="INV_1001"
+        orderId="ORD_555"
+        className="btn-bkash"
+      >
+        Pay 1,550 BDT with bKash
+      </BkashButton>
+      {error && <p className="error">{error.message}</p>}
+    </div>
+  );
+}
+```
+
+---
+
+## React Native / Expo
+
+```tsx
+import React from 'react';
+import { WebView } from 'react-native-webview';
+import { BkashCheckout } from 'bkash-client/react-native';
+
+export function PaymentScreen({ route, navigation }: any) {
+  const { redirectUrl } = route.params;
+
+  return (
+    <BkashCheckout
+      redirectUrl={redirectUrl}
+      callbackUrl="https://merchant.example.com/api/bkash/callback"
+      WebViewComponent={WebView}
+      onSuccess={(paymentId) => {
+        navigation.navigate('Success', { paymentId });
+      }}
+      onCancel={() => {
+        navigation.goBack();
+      }}
+      onError={(err) => {
+        alert(err.message);
+      }}
+    />
+  );
+}
+```
+
+---
+
+## License
+
+MIT © [Antigravity Open Source & Contributors](https://github.com/iamtashanto/Bkash)

package/dist/angular.cjs

@@ -0,0 +1,149 @@
+'use strict';
+
+// src/index.ts
+var BkashClient = class {
+  state = "idle";
+  options;
+  currentPaymentId = null;
+  listeners = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.options = {
+      createUrl: "/api/bkash/create",
+      ...options
+    };
+  }
+  getState() {
+    return this.state;
+  }
+  getPaymentId() {
+    return this.currentPaymentId;
+  }
+  /**
+   * Returns human-readable UI guidance for the current client state.
+   * Specifically guarantees that unknown or timed-out outcomes are presented as
+   * "payment pending, do not pay again" rather than a false failure.
+   */
+  getStateMessage() {
+    switch (this.state) {
+      case "idle":
+        return "Ready to initiate checkout.";
+      case "creating":
+        return "Initializing payment session with bKash...";
+      case "awaiting_user":
+        return "Redirecting to bKash secure payment page...";
+      case "verifying":
+        return "Verifying payment with bKash...";
+      case "success":
+        return "Payment completed successfully!";
+      case "pending":
+      case "timeout":
+        return "Payment pending, do not pay again. Please wait while your transaction is reconciled with bKash.";
+      case "cancelled":
+        return "Payment was cancelled.";
+      case "offline":
+        return "Device is offline. Please check your internet connection before retrying.";
+      case "error":
+        return "An error occurred during checkout.";
+      default:
+        return "";
+    }
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  cancel() {
+    this.setState("cancelled");
+    this.options.onCancel?.();
+  }
+  setPending(paymentId) {
+    if (paymentId) this.currentPaymentId = paymentId;
+    this.setState("pending");
+  }
+  setState(newState) {
+    this.state = newState;
+    this.options.onStateChange?.(newState);
+    this.listeners.forEach((fn) => fn(newState));
+  }
+  /**
+   * Initiates payment flow by calling the merchant backend,
+   * obtaining the gateway URL, and redirecting the customer.
+   */
+  async checkout(params) {
+    if (typeof navigator !== "undefined" && navigator.onLine === false) {
+      this.setState("offline");
+      const offlineErr = new Error("Device is offline. Please check your internet connection.");
+      this.options.onError?.(offlineErr);
+      throw offlineErr;
+    }
+    try {
+      this.setState("creating");
+      const defaultCallback = typeof window !== "undefined" ? window.location?.href : "";
+      const res = await fetch(this.options.createUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          amount: params.amount,
+          invoiceNumber: params.invoiceNumber,
+          orderId: params.orderId,
+          callbackUrl: this.options.callbackUrl || defaultCallback,
+          payerReference: params.payerReference,
+          metadata: params.metadata
+        })
+      });
+      if (!res.ok) {
+        throw new Error(`Failed to create payment session: HTTP ${res.status}`);
+      }
+      const data = await res.json();
+      if (!data.redirectUrl || !data.paymentId) {
+        throw new Error(data.error || "Invalid session response from payment server.");
+      }
+      this.currentPaymentId = data.paymentId;
+      this.setState("awaiting_user");
+      if (typeof window !== "undefined" && window.location) {
+        window.location.href = data.redirectUrl;
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      const isTimeout = error.name === "AbortError" || error.name === "TimeoutError" || /timeout|abort/i.test(error.message);
+      if (isTimeout) {
+        this.setState("pending");
+      } else {
+        this.setState("error");
+      }
+      this.options.onError?.(error);
+      throw error;
+    }
+  }
+  reset() {
+    this.currentPaymentId = null;
+    this.setState("idle");
+  }
+};
+
+// src/angular.ts
+var BkashService = class {
+  client;
+  constructor(options) {
+    this.client = new BkashClient(options);
+  }
+  getState() {
+    return this.client.getState();
+  }
+  getPaymentId() {
+    return this.client.getPaymentId();
+  }
+  subscribe(listener) {
+    return this.client.subscribe(listener);
+  }
+  checkout(params) {
+    return this.client.checkout(params);
+  }
+  reset() {
+    this.client.reset();
+  }
+};
+
+exports.BkashService = BkashService;
+//# sourceMappingURL=angular.cjs.map
+//# sourceMappingURL=angular.cjs.map

package/dist/angular.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/angular.ts"],"names":[],"mappings":"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","file":"angular.cjs","sourcesContent":["/**\n * @bkash/client\n * Universal, headless client SDK for bKash payment integrations.\n */\n\nexport type BkashClientState =\n  | 'idle'\n  | 'creating'\n  | 'awaiting_user'\n  | 'verifying'\n  | 'success'\n  | 'pending'\n  | 'cancelled'\n  | 'timeout'\n  | 'offline'\n  | 'error';\n\nexport interface BkashClientOptions {\n  /**\n   * Endpoint on merchant backend to create payment session.\n   * Defaults to \"/api/bkash/create\".\n   */\n  createUrl?: string;\n  /**\n   * Callback URL registered with merchant backend.\n   */\n  callbackUrl?: string;\n  /**\n   * Hook triggered on state transition.\n   */\n  onStateChange?: (state: BkashClientState) => void;\n  /**\n   * Hook triggered when payment completes successfully.\n   */\n  onSuccess?: (paymentId: string) => void;\n  /**\n   * Hook triggered on payment error.\n   */\n  onError?: (error: Error) => void;\n  /**\n   * Hook triggered if user cancels payment.\n   */\n  onCancel?: () => void;\n}\n\nexport interface InitiateCheckoutParams {\n  amount: number | string;\n  invoiceNumber: string;\n  orderId?: string;\n  payerReference?: string;\n  metadata?: Record<string, string>;\n}\n\nexport class BkashClient {\n  private state: BkashClientState = 'idle';\n  private options: BkashClientOptions;\n  private currentPaymentId: string | null = null;\n  private listeners = new Set<(state: BkashClientState) => void>();\n\n  constructor(options?: BkashClientOptions) {\n    this.options = {\n      createUrl: '/api/bkash/create',\n      ...options,\n    };\n  }\n\n  public getState(): BkashClientState {\n    return this.state;\n  }\n\n  public getPaymentId(): string | null {\n    return this.currentPaymentId;\n  }\n\n  /**\n   * Returns human-readable UI guidance for the current client state.\n   * Specifically guarantees that unknown or timed-out outcomes are presented as\n   * \"payment pending, do not pay again\" rather than a false failure.\n   */\n  public getStateMessage(): string {\n    switch (this.state) {\n      case 'idle':\n        return 'Ready to initiate checkout.';\n      case 'creating':\n        return 'Initializing payment session with bKash...';\n      case 'awaiting_user':\n        return 'Redirecting to bKash secure payment page...';\n      case 'verifying':\n        return 'Verifying payment with bKash...';\n      case 'success':\n        return 'Payment completed successfully!';\n      case 'pending':\n      case 'timeout':\n        return 'Payment pending, do not pay again. Please wait while your transaction is reconciled with bKash.';\n      case 'cancelled':\n        return 'Payment was cancelled.';\n      case 'offline':\n        return 'Device is offline. Please check your internet connection before retrying.';\n      case 'error':\n        return 'An error occurred during checkout.';\n      default:\n        return '';\n    }\n  }\n\n  public subscribe(listener: (state: BkashClientState) => void): () => void {\n    this.listeners.add(listener);\n    return () => this.listeners.delete(listener);\n  }\n\n  public cancel(): void {\n    this.setState('cancelled');\n    this.options.onCancel?.();\n  }\n\n  public setPending(paymentId?: string): void {\n    if (paymentId) this.currentPaymentId = paymentId;\n    this.setState('pending');\n  }\n\n  private setState(newState: BkashClientState): void {\n    this.state = newState;\n    this.options.onStateChange?.(newState);\n    this.listeners.forEach((fn) => fn(newState));\n  }\n\n  /**\n   * Initiates payment flow by calling the merchant backend,\n   * obtaining the gateway URL, and redirecting the customer.\n   */\n  public async checkout(params: InitiateCheckoutParams): Promise<void> {\n    // Offline pre-check\n    if (typeof navigator !== 'undefined' && navigator.onLine === false) {\n      this.setState('offline');\n      const offlineErr = new Error('Device is offline. Please check your internet connection.');\n      this.options.onError?.(offlineErr);\n      throw offlineErr;\n    }\n\n    try {\n      this.setState('creating');\n\n      const defaultCallback = typeof window !== 'undefined' ? window.location?.href : '';\n      const res = await fetch(this.options.createUrl!, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n          amount: params.amount,\n          invoiceNumber: params.invoiceNumber,\n          orderId: params.orderId,\n          callbackUrl: this.options.callbackUrl || defaultCallback,\n          payerReference: params.payerReference,\n          metadata: params.metadata,\n        }),\n      });\n\n      if (!res.ok) {\n        throw new Error(`Failed to create payment session: HTTP ${res.status}`);\n      }\n\n      const data = (await res.json()) as {\n        redirectUrl?: string;\n        paymentId?: string;\n        error?: string;\n      };\n      if (!data.redirectUrl || !data.paymentId) {\n        throw new Error(data.error || 'Invalid session response from payment server.');\n      }\n\n      this.currentPaymentId = data.paymentId;\n      this.setState('awaiting_user');\n\n      // Launch bKash Hosted Checkout\n      if (typeof window !== 'undefined' && window.location) {\n        window.location.href = data.redirectUrl;\n      }\n    } catch (err: unknown) {\n      const error = err instanceof Error ? err : new Error(String(err));\n      const isTimeout =\n        error.name === 'AbortError' ||\n        error.name === 'TimeoutError' ||\n        /timeout|abort/i.test(error.message);\n\n      if (isTimeout) {\n        // Under AUD-08: timeout / unknown outcome MUST display pending (\"do not pay again\")\n        this.setState('pending');\n      } else {\n        this.setState('error');\n      }\n\n      this.options.onError?.(error);\n      throw error;\n    }\n  }\n\n  public reset(): void {\n    this.currentPaymentId = null;\n    this.setState('idle');\n  }\n}\n","import {\n  BkashClient,\n  type BkashClientOptions,\n  type BkashClientState,\n  type InitiateCheckoutParams,\n} from './index.js';\n\n/**\n * Plain TypeScript Service for Angular applications.\n *\n * Design Decision & Justification:\n * Modern Angular (16+) seamlessly imports standard TypeScript services directly\n * without requiring the heavy complexity of ng-packagr / Angular Package Format (APF),\n * ensuring broad compatibility across Angular 16, 17, 18, and 19 without version pinning.\n */\nexport class BkashService {\n  private client: BkashClient;\n\n  constructor(options?: BkashClientOptions) {\n    this.client = new BkashClient(options);\n  }\n\n  public getState(): BkashClientState {\n    return this.client.getState();\n  }\n\n  public getPaymentId(): string | null {\n    return this.client.getPaymentId();\n  }\n\n  public subscribe(listener: (state: BkashClientState) => void): () => void {\n    return this.client.subscribe(listener);\n  }\n\n  public checkout(params: InitiateCheckoutParams): Promise<void> {\n    return this.client.checkout(params);\n  }\n\n  public reset(): void {\n    this.client.reset();\n  }\n}\n"]}

package/dist/angular.d.cts

@@ -0,0 +1,21 @@
+import { BkashClientOptions, BkashClientState, InitiateCheckoutParams } from './index.cjs';
+
+/**
+ * Plain TypeScript Service for Angular applications.
+ *
+ * Design Decision & Justification:
+ * Modern Angular (16+) seamlessly imports standard TypeScript services directly
+ * without requiring the heavy complexity of ng-packagr / Angular Package Format (APF),
+ * ensuring broad compatibility across Angular 16, 17, 18, and 19 without version pinning.
+ */
+declare class BkashService {
+    private client;
+    constructor(options?: BkashClientOptions);
+    getState(): BkashClientState;
+    getPaymentId(): string | null;
+    subscribe(listener: (state: BkashClientState) => void): () => void;
+    checkout(params: InitiateCheckoutParams): Promise<void>;
+    reset(): void;
+}
+
+export { BkashService };

package/dist/angular.d.ts

@@ -0,0 +1,21 @@
+import { BkashClientOptions, BkashClientState, InitiateCheckoutParams } from './index.js';
+
+/**
+ * Plain TypeScript Service for Angular applications.
+ *
+ * Design Decision & Justification:
+ * Modern Angular (16+) seamlessly imports standard TypeScript services directly
+ * without requiring the heavy complexity of ng-packagr / Angular Package Format (APF),
+ * ensuring broad compatibility across Angular 16, 17, 18, and 19 without version pinning.
+ */
+declare class BkashService {
+    private client;
+    constructor(options?: BkashClientOptions);
+    getState(): BkashClientState;
+    getPaymentId(): string | null;
+    subscribe(listener: (state: BkashClientState) => void): () => void;
+    checkout(params: InitiateCheckoutParams): Promise<void>;
+    reset(): void;
+}
+
+export { BkashService };

package/dist/angular.js

@@ -0,0 +1,29 @@
+import { BkashClient } from './chunk-L3C2S2EZ.js';
+import './chunk-DGUM43GV.js';
+
+// src/angular.ts
+var BkashService = class {
+  client;
+  constructor(options) {
+    this.client = new BkashClient(options);
+  }
+  getState() {
+    return this.client.getState();
+  }
+  getPaymentId() {
+    return this.client.getPaymentId();
+  }
+  subscribe(listener) {
+    return this.client.subscribe(listener);
+  }
+  checkout(params) {
+    return this.client.checkout(params);
+  }
+  reset() {
+    this.client.reset();
+  }
+};
+
+export { BkashService };
+//# sourceMappingURL=angular.js.map
+//# sourceMappingURL=angular.js.map

package/dist/angular.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/angular.ts"],"names":[],"mappings":";;;;AAeO,IAAM,eAAN,MAAmB;AAAA,EAChB,MAAA;AAAA,EAER,YAAY,OAAA,EAA8B;AACxC,IAAA,IAAA,CAAK,MAAA,GAAS,IAAI,WAAA,CAAY,OAAO,CAAA;AAAA,EACvC;AAAA,EAEO,QAAA,GAA6B;AAClC,IAAA,OAAO,IAAA,CAAK,OAAO,QAAA,EAAS;AAAA,EAC9B;AAAA,EAEO,YAAA,GAA8B;AACnC,IAAA,OAAO,IAAA,CAAK,OAAO,YAAA,EAAa;AAAA,EAClC;AAAA,EAEO,UAAU,QAAA,EAAyD;AACxE,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,SAAA,CAAU,QAAQ,CAAA;AAAA,EACvC;AAAA,EAEO,SAAS,MAAA,EAA+C;AAC7D,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,QAAA,CAAS,MAAM,CAAA;AAAA,EACpC;AAAA,EAEO,KAAA,GAAc;AACnB,IAAA,IAAA,CAAK,OAAO,KAAA,EAAM;AAAA,EACpB;AACF","file":"angular.js","sourcesContent":["import {\n  BkashClient,\n  type BkashClientOptions,\n  type BkashClientState,\n  type InitiateCheckoutParams,\n} from './index.js';\n\n/**\n * Plain TypeScript Service for Angular applications.\n *\n * Design Decision & Justification:\n * Modern Angular (16+) seamlessly imports standard TypeScript services directly\n * without requiring the heavy complexity of ng-packagr / Angular Package Format (APF),\n * ensuring broad compatibility across Angular 16, 17, 18, and 19 without version pinning.\n */\nexport class BkashService {\n  private client: BkashClient;\n\n  constructor(options?: BkashClientOptions) {\n    this.client = new BkashClient(options);\n  }\n\n  public getState(): BkashClientState {\n    return this.client.getState();\n  }\n\n  public getPaymentId(): string | null {\n    return this.client.getPaymentId();\n  }\n\n  public subscribe(listener: (state: BkashClientState) => void): () => void {\n    return this.client.subscribe(listener);\n  }\n\n  public checkout(params: InitiateCheckoutParams): Promise<void> {\n    return this.client.checkout(params);\n  }\n\n  public reset(): void {\n    this.client.reset();\n  }\n}\n"]}

package/dist/bkash-client.browser.global.js

@@ -0,0 +1,149 @@
+"use strict";
+var BkashClient = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+  var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+  // src/index.ts
+  var src_exports = {};
+  __export(src_exports, {
+    BkashClient: () => BkashClient
+  });
+  var BkashClient = class {
+    constructor(options) {
+      __publicField(this, "state", "idle");
+      __publicField(this, "options");
+      __publicField(this, "currentPaymentId", null);
+      __publicField(this, "listeners", /* @__PURE__ */ new Set());
+      this.options = {
+        createUrl: "/api/bkash/create",
+        ...options
+      };
+    }
+    getState() {
+      return this.state;
+    }
+    getPaymentId() {
+      return this.currentPaymentId;
+    }
+    /**
+     * Returns human-readable UI guidance for the current client state.
+     * Specifically guarantees that unknown or timed-out outcomes are presented as
+     * "payment pending, do not pay again" rather than a false failure.
+     */
+    getStateMessage() {
+      switch (this.state) {
+        case "idle":
+          return "Ready to initiate checkout.";
+        case "creating":
+          return "Initializing payment session with bKash...";
+        case "awaiting_user":
+          return "Redirecting to bKash secure payment page...";
+        case "verifying":
+          return "Verifying payment with bKash...";
+        case "success":
+          return "Payment completed successfully!";
+        case "pending":
+        case "timeout":
+          return "Payment pending, do not pay again. Please wait while your transaction is reconciled with bKash.";
+        case "cancelled":
+          return "Payment was cancelled.";
+        case "offline":
+          return "Device is offline. Please check your internet connection before retrying.";
+        case "error":
+          return "An error occurred during checkout.";
+        default:
+          return "";
+      }
+    }
+    subscribe(listener) {
+      this.listeners.add(listener);
+      return () => this.listeners.delete(listener);
+    }
+    cancel() {
+      this.setState("cancelled");
+      this.options.onCancel?.();
+    }
+    setPending(paymentId) {
+      if (paymentId) this.currentPaymentId = paymentId;
+      this.setState("pending");
+    }
+    setState(newState) {
+      this.state = newState;
+      this.options.onStateChange?.(newState);
+      this.listeners.forEach((fn) => fn(newState));
+    }
+    /**
+     * Initiates payment flow by calling the merchant backend,
+     * obtaining the gateway URL, and redirecting the customer.
+     */
+    async checkout(params) {
+      if (typeof navigator !== "undefined" && navigator.onLine === false) {
+        this.setState("offline");
+        const offlineErr = new Error("Device is offline. Please check your internet connection.");
+        this.options.onError?.(offlineErr);
+        throw offlineErr;
+      }
+      try {
+        this.setState("creating");
+        const defaultCallback = typeof window !== "undefined" ? window.location?.href : "";
+        const res = await fetch(this.options.createUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            amount: params.amount,
+            invoiceNumber: params.invoiceNumber,
+            orderId: params.orderId,
+            callbackUrl: this.options.callbackUrl || defaultCallback,
+            payerReference: params.payerReference,
+            metadata: params.metadata
+          })
+        });
+        if (!res.ok) {
+          throw new Error(`Failed to create payment session: HTTP ${res.status}`);
+        }
+        const data = await res.json();
+        if (!data.redirectUrl || !data.paymentId) {
+          throw new Error(data.error || "Invalid session response from payment server.");
+        }
+        this.currentPaymentId = data.paymentId;
+        this.setState("awaiting_user");
+        if (typeof window !== "undefined" && window.location) {
+          window.location.href = data.redirectUrl;
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const isTimeout = error.name === "AbortError" || error.name === "TimeoutError" || /timeout|abort/i.test(error.message);
+        if (isTimeout) {
+          this.setState("pending");
+        } else {
+          this.setState("error");
+        }
+        this.options.onError?.(error);
+        throw error;
+      }
+    }
+    reset() {
+      this.currentPaymentId = null;
+      this.setState("idle");
+    }
+  };
+  return __toCommonJS(src_exports);
+})();
+//# sourceMappingURL=bkash-client.browser.global.js.map

package/dist/bkash-client.browser.global.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @bkash/client\n * Universal, headless client SDK for bKash payment integrations.\n */\n\nexport type BkashClientState =\n  | 'idle'\n  | 'creating'\n  | 'awaiting_user'\n  | 'verifying'\n  | 'success'\n  | 'pending'\n  | 'cancelled'\n  | 'timeout'\n  | 'offline'\n  | 'error';\n\nexport interface BkashClientOptions {\n  /**\n   * Endpoint on merchant backend to create payment session.\n   * Defaults to \"/api/bkash/create\".\n   */\n  createUrl?: string;\n  /**\n   * Callback URL registered with merchant backend.\n   */\n  callbackUrl?: string;\n  /**\n   * Hook triggered on state transition.\n   */\n  onStateChange?: (state: BkashClientState) => void;\n  /**\n   * Hook triggered when payment completes successfully.\n   */\n  onSuccess?: (paymentId: string) => void;\n  /**\n   * Hook triggered on payment error.\n   */\n  onError?: (error: Error) => void;\n  /**\n   * Hook triggered if user cancels payment.\n   */\n  onCancel?: () => void;\n}\n\nexport interface InitiateCheckoutParams {\n  amount: number | string;\n  invoiceNumber: string;\n  orderId?: string;\n  payerReference?: string;\n  metadata?: Record<string, string>;\n}\n\nexport class BkashClient {\n  private state: BkashClientState = 'idle';\n  private options: BkashClientOptions;\n  private currentPaymentId: string | null = null;\n  private listeners = new Set<(state: BkashClientState) => void>();\n\n  constructor(options?: BkashClientOptions) {\n    this.options = {\n      createUrl: '/api/bkash/create',\n      ...options,\n    };\n  }\n\n  public getState(): BkashClientState {\n    return this.state;\n  }\n\n  public getPaymentId(): string | null {\n    return this.currentPaymentId;\n  }\n\n  /**\n   * Returns human-readable UI guidance for the current client state.\n   * Specifically guarantees that unknown or timed-out outcomes are presented as\n   * \"payment pending, do not pay again\" rather than a false failure.\n   */\n  public getStateMessage(): string {\n    switch (this.state) {\n      case 'idle':\n        return 'Ready to initiate checkout.';\n      case 'creating':\n        return 'Initializing payment session with bKash...';\n      case 'awaiting_user':\n        return 'Redirecting to bKash secure payment page...';\n      case 'verifying':\n        return 'Verifying payment with bKash...';\n      case 'success':\n        return 'Payment completed successfully!';\n      case 'pending':\n      case 'timeout':\n        return 'Payment pending, do not pay again. Please wait while your transaction is reconciled with bKash.';\n      case 'cancelled':\n        return 'Payment was cancelled.';\n      case 'offline':\n        return 'Device is offline. Please check your internet connection before retrying.';\n      case 'error':\n        return 'An error occurred during checkout.';\n      default:\n        return '';\n    }\n  }\n\n  public subscribe(listener: (state: BkashClientState) => void): () => void {\n    this.listeners.add(listener);\n    return () => this.listeners.delete(listener);\n  }\n\n  public cancel(): void {\n    this.setState('cancelled');\n    this.options.onCancel?.();\n  }\n\n  public setPending(paymentId?: string): void {\n    if (paymentId) this.currentPaymentId = paymentId;\n    this.setState('pending');\n  }\n\n  private setState(newState: BkashClientState): void {\n    this.state = newState;\n    this.options.onStateChange?.(newState);\n    this.listeners.forEach((fn) => fn(newState));\n  }\n\n  /**\n   * Initiates payment flow by calling the merchant backend,\n   * obtaining the gateway URL, and redirecting the customer.\n   */\n  public async checkout(params: InitiateCheckoutParams): Promise<void> {\n    // Offline pre-check\n    if (typeof navigator !== 'undefined' && navigator.onLine === false) {\n      this.setState('offline');\n      const offlineErr = new Error('Device is offline. Please check your internet connection.');\n      this.options.onError?.(offlineErr);\n      throw offlineErr;\n    }\n\n    try {\n      this.setState('creating');\n\n      const defaultCallback = typeof window !== 'undefined' ? window.location?.href : '';\n      const res = await fetch(this.options.createUrl!, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n          amount: params.amount,\n          invoiceNumber: params.invoiceNumber,\n          orderId: params.orderId,\n          callbackUrl: this.options.callbackUrl || defaultCallback,\n          payerReference: params.payerReference,\n          metadata: params.metadata,\n        }),\n      });\n\n      if (!res.ok) {\n        throw new Error(`Failed to create payment session: HTTP ${res.status}`);\n      }\n\n      const data = (await res.json()) as {\n        redirectUrl?: string;\n        paymentId?: string;\n        error?: string;\n      };\n      if (!data.redirectUrl || !data.paymentId) {\n        throw new Error(data.error || 'Invalid session response from payment server.');\n      }\n\n      this.currentPaymentId = data.paymentId;\n      this.setState('awaiting_user');\n\n      // Launch bKash Hosted Checkout\n      if (typeof window !== 'undefined' && window.location) {\n        window.location.href = data.redirectUrl;\n      }\n    } catch (err: unknown) {\n      const error = err instanceof Error ? err : new Error(String(err));\n      const isTimeout =\n        error.name === 'AbortError' ||\n        error.name === 'TimeoutError' ||\n        /timeout|abort/i.test(error.message);\n\n      if (isTimeout) {\n        // Under AUD-08: timeout / unknown outcome MUST display pending (\"do not pay again\")\n        this.setState('pending');\n      } else {\n        this.setState('error');\n      }\n\n      this.options.onError?.(error);\n      throw error;\n    }\n  }\n\n  public reset(): void {\n    this.currentPaymentId = null;\n    this.setState('idle');\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-DGUM43GV.js

@@ -0,0 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export { __require };
+//# sourceMappingURL=chunk-DGUM43GV.js.map
+//# sourceMappingURL=chunk-DGUM43GV.js.map

package/dist/chunk-DGUM43GV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-DGUM43GV.js"}