dibakarsutradhar/bkash-rs

bkash-rs is a Rust client library, not an application server. The architecture is organized around one shared client core, several feature-gated product facades, a typed model layer, and a small set of utility subsystems for auth, transport, errors, and webhook verification.

1. The main entrypoint is Bkash in src/client.rs. It is a cheaply cloneable handle that owns shared internal state and is the only thing consumers need to keep around. Product-specific APIs are obtained from it through accessors such as bkash.tokenized(), bkash.checkout(), bkash.auth_capture(), and bkash.subscriptions().

2. Configuration lives in src/config.rs. ConfigBuilder validates credentials, environment, timeout, retry count, base URL, and optional custom HTTP client. Environment selects sandbox vs production and determines the API host family. This is the boundary where user inputs become runtime configuration.

3. The outbound HTTP boundary is src/transport.rs. It wraps reqwest, applies timeouts, retries transient failures with backoff, and is responsible for attaching auth tokens to requests. All network calls to bKash flow through this layer rather than directly from the product modules.

4. Authentication is centralized in src/token.rs and the transport. The client caches the bKash access token, transparently grants or refreshes it when needed, and reuses it across all product accessors. The README’s build_and_connect() behavior indicates the token cache can be warmed during client construction.

5. Product logic is split into separate façades in src/tokenized.rs, src/checkout.rs, src/auth_capture.rs, and src/subscriptions.rs. These modules mostly translate high-level methods into the correct bKash endpoint, base URL subdomain, and request shape. The differences between products are encoded here: for example, classic checkout and tokenized checkout share endpoint paths but differ in host and payment mode, while auth-capture uses some path parameters instead of body fields.

6. The request/response schema layer is under src/models/. It is divided by product and operation type (checkout, tokenized, auth_capture, subscriptions, plus common and token). This is where typed request bodies, response structs, and shared DTOs live, so the rest of the crate can stay strongly typed instead of dealing with raw JSON.

7. Error handling is a first-class subsystem in src/error.rs. The crate maps bKash’s status/error envelopes into a typed Error enum that distinguishes authentication failures, API errors, transport failures, timeouts, config problems, and JSON decoding issues. This lets callers separate retryable failures from auth/config problems without parsing response bodies themselves.

8. The operational flow for a typical API call is: user builds Bkash with credentials and environment; a product accessor constructs a request object; transport ensures a valid token exists; reqwest sends the HTTP request to the product-specific host and endpoint; the response is deserialized into a typed model; errors are normalized into Error. That is the core data path for all payment-related features.

9. Webhook support is isolated in src/webhooks.rs and is synchronous rather than network-client driven. It verifies SNS-style signatures, optionally fetches or uses an RSA public key, parses inbound webhook envelopes, and exposes typed event accessors. This is a separate inbound trust boundary from the outbound payment APIs.

10. Feature flags materially shape the compiled architecture. tokenized-checkout and checkout are enabled by default; auth-capture, subscriptions, and webhooks are optional. TLS is also split into mutually exclusive rustls-tls or native-tls. In diagram terms, the crate can be viewed as a shared core with optional product and security modules compiled in or out.

11. Testing is split between offline fixture-based integration tests and optional live sandbox smoke tests. tests/transport_wiremock.rs and the fixture directories validate request/response behavior against recorded JSON, while tests/live/sandbox.rs exercises real sandbox calls when explicitly run. This mirrors the architecture: local typed behavior is validated separately from the external bKash integration.

12. The examples in examples/ are small orchestration drivers, not part of the library core. quickstart.rs demonstrates a single payment flow, and from_env.rs stages longer sandbox walkthroughs with manual wallet approval. They show the expected call sequencing across the same underlying client, transport, and model layers.