@ngandu-dev/flexpay 2.0.5 → 3.0.0

package/README.md

@@ -1,167 +1,217 @@
 # FlexPay TypeScript
 
-![npm](https://img.shields.io/npm/v/@ngandu-dev/flexpay?style=flat-square)
-![npm](https://img.shields.io/npm/dt/@ngandu-dev/flexpay?style=flat-square)
-[![Quality](https://github.com/ngandu-dev/flexpay/actions/workflows/quality.yml/badge.svg?branch=main)](https://github.com/ngandu-dev/flexpay/actions/workflows/quality.yml)
-[![Tests](https://github.com/ngandu-dev/flexpay/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/ngandu-dev/flexpay/actions/workflows/test.yml)
-![GitHub](https://img.shields.io/github/license/ngandu-dev/flexpay?style=flat-square)
+TypeScript client for FlexPay corporate mobile-money and card collections, transaction checks,
+callback parsing, and the existing payout API.
 
-For privacy reasons, FlexPay's original documentation cannot be shared without written permission.
-For credentials and implementation details, contact [FlexPay](https://flexpay.cd).
-
-## Features
-
-- Typed mobile-money and card payment requests
-- Transaction status checks and callback validation
-- Development and production API environments with optional custom base URLs
-- ESM and CommonJS distributions with TypeScript declarations
-
-## Requirements
-
-- Node.js 24 or newer
+For credentials and the original provider documentation, contact [FlexPay](https://flexpay.cd).
+This package requires Node.js 24 or newer and ships ESM, CommonJS, and TypeScript declarations.
 
 ## Installation
 
-Add the TypeScript client to your application's dependencies:
-
-```bash
-npm install @ngandu-dev/flexpay
+```sh
+npm install @ngandu-dev/flexpay@^3
 ```
 
-## Quick start
-
-### Authentication
+These examples use the version 3 API.
+For version 2 migration steps, see [UPGRADE_3.0.0.md](UPGRADE_3.0.0.md).
 
-- **Step 1**. Contact FlexPay to get a Merchant Account
-  You will receive a Merchant Form to complete in order to provide your business details and preferred Cash out Wallet or Banking Details.
-- **Step 2**. Once the paperwork is completed, you will be issued with Live and Sandbox Accounts (Merchant Code and Authorization token)
+## Configure a client
 
-Then use these credentials to authenticate your client
+Every client requires a `Credential` and a `BaseUrl` with exactly three versioned prefixes:
+`payment`, `check`, and `payout`. There is no environment switch or implicit production fallback.
 
 ```ts
-import { Client as Flexpay } from "@ngandu-dev/flexpay";
+import { Client, productionBaseUrl } from "@ngandu-dev/flexpay";
 
-const flexpay = new Flexpay("merchant_code", "token", "dev"); // use "prod" for production
+const client = new Client(
+  { merchant: "MERCHANT_CODE", token: "YOUR_TOKEN" },
+  productionBaseUrl,
+);
 ```
 
-### Local simulator or custom endpoints
+`productionBaseUrl` is a frozen value containing:
 
-Pass optional versioned prefixes as the fourth constructor argument:
+| Property | Prefix | Operations |
+| --- | --- | --- |
+| `payment` | `https://corporateapi.flexpay.cd/api/rest/v1` | `/paymentService` for mobile and card |
+| `check` | `https://apicheck.flexpaie.com/api/rest/v1` | `/check/{orderNumber}` |
+| `payout` | `https://backend.flexpay.cd/api/rest/v1` | `/merchantPayOutService` |
+
+FlexPay has not supplied a corporate sandbox URL. Point every prefix at your local simulator
+when testing. Include the version path but omit the service path.
 
 ```ts
-const flexpay = new Flexpay("TESTMERCHANT", "test-token", "dev", {
-  apiBaseUrl: "http://localhost:8080/api/rest/v1",
-  cardBaseUrl: "http://localhost:8080/v1.1",
-});
+import { Client, type BaseUrl } from "@ngandu-dev/flexpay";
+
+const localBaseUrl = {
+  payment: "http://localhost:8080/api/rest/v1",
+  check: "http://localhost:8080/api/rest/v1",
+  payout: "http://localhost:8080/api/rest/v1",
+} satisfies BaseUrl;
+
+const localClient = new Client(
+  { merchant: "TESTMERCHANT", token: "test-token" },
+  localBaseUrl,
+);
 ```
 
-`apiBaseUrl` is shared by mobile payments, payouts, and status checks; the client appends
-`/paymentService`, `/merchantPayOutService`, or `/check/{orderNumber}`. `cardBaseUrl` gets `/pay`
-appended. Include the version path in each prefix, and omit the final service path.
-Trailing slashes are removed. Each omitted option keeps its selected `dev`/`prod` default,
-so existing constructor calls continue to work. Overrides must be absolute HTTP(S) URLs without
-credentials, query strings, or fragments; invalid values throw during construction.
-The optional `BaseUrls` type is exported from the package root. `Environment` also accepts these
-options as its second argument when generating endpoint URLs directly.
+`BaseUrlSchema` validates all three prefixes, removes surrounding whitespace and trailing slashes,
+and freezes the result. Prefixes must be absolute HTTP(S) URLs without credentials, query strings,
+fragments, or internal whitespace/control characters. Unknown configuration fields are rejected.
+`CredentialSchema` rejects blank merchant codes and tokens without modifying their contents.
+The client retains validated snapshots, so later caller mutations cannot change its configuration.
 
-## Usage
+An optional third constructor argument accepts a Fetch-compatible function for testing or an
+application-owned HTTP integration. It must honor the supplied abort signal and `redirect: "manual"`.
 
-### Create a Payment Request
+## Initiate payments
 
-```typescript
-import type { CardRequest, MobileRequest } from "@ngandu-dev/flexpay";
+Use explicit methods. Both collections send JSON to the corporate payment endpoint with a bearer
+header. Public input is camelCase; the client writes the documented snake_case wire fields.
 
-const mobile = {
-  amount: 10, // 10 USD
-  currency: "USD",
-  phone: "243999999999",
-  reference: "mobile_order_12345",
-  description: "your_transaction_description",
-  callbackUrl: "https://example.com/flexpay/callback",
-} satisfies MobileRequest;
-
-const card = {
-  amount: 10, // 10 USD
+```ts
+const mobile = await client.mobile({
+  amount: 10,
   currency: "USD",
-  reference: "card_order_12345",
-  description: "your_transaction_description",
-  callbackUrl: "https://example.com/flexpay/callback",
-  approveUrl: "https://example.com/flexpay/approved",
-  cancelUrl: "https://example.com/flexpay/cancelled",
-  declineUrl: "https://example.com/flexpay/declined",
-  homeUrl: "https://example.com",
-} satisfies CardRequest;
-```
-
-> **Note**: we highly recommend your `callbacks` urls to be unique for each transaction.
-
-### Mobile Payment
-Once called, Flexpay will send a payment request to the user's mobile money account, and the user will have to confirm the payment on their phone.
-after that the payment will be processed and the callback url will be called with the transaction details.
-
-```typescript
-const mobileResponse = await flexpay.pay(mobile);
-```
-
-### Visa Card Payment
-You can set up card payment via VPOS features, which is typically used for online payments.
-it's a gateway that allows you to accept payments from your customers using their credit cards.
-
-```typescript
-const cardResponse = await flexpay.pay(card);
-// redirect to cardResponse.url to complete the payment
-```
-
-#### **handling callback (callbackUrl, approveUrl, cancelUrl, declineUrl)**
-Flexpay will send a POST request to the defined callbackUrl and the response will contain the transaction details.
-you can use the following code to validate the incoming payload.
+  phone: "243810000001",
+  reference: "mobile-order-123",
+  callbackUrl: "https://example.com/payments/callback",
+});
 
-```typescript
-const webhook = flexpay.handleCallback(req.body);
-flexpay.isSuccessful(webhook); // true or false
-```
+if (!mobile.accepted || !mobile.orderNumber) {
+  throw new Error(mobile.message || "Payment initiation was not accepted");
+}
 
-### Check Transaction state
-You don't trust webhook ? you can always check the transaction state by providing the order number.
+const card = await client.card({
+  amount: 10,
+  currency: "USD",
+  reference: "card-order-123",
+  callbackUrl: "https://example.com/payments/callback",
+  approveUrl: "https://example.com/payments/approved",
+  cancelUrl: "https://example.com/payments/cancelled",
+  declineUrl: "https://example.com/payments/declined",
+});
 
-```typescript
-if (!mobileResponse.orderNumber) {
-  throw new Error("FlexPay did not return an order number");
+if (!card.accepted || !card.orderNumber || !card.url) {
+  throw new Error(card.message || "Card checkout is unavailable");
 }
 
-const tx = await flexpay.check(mobileResponse.orderNumber);
-flexpay.isSuccessful(tx); // true or false
+// Store card.orderNumber, then redirect the customer to card.url.
 ```
 
-## Migrating to `@ngandu-dev/flexpay`
+`accepted` reports request acceptance, not collection of funds. Wait for the transaction outcome
+before fulfilling an order. Card checkout URLs and order numbers can be null or empty on rejection.
 
-Replace the dependency and every import with `@ngandu-dev/flexpay`. Version 2 is a clean package
-move and does not provide an alias for the old scope.
+Inputs reject unknown fields. Amounts must be positive finite numbers, phone numbers must contain
+exactly 12 digits, and references and callback/redirect strings must not be blank. References have
+no client-imposed length cap.
 
-## Development
+`client.payout()` accepts `amount`, `currency`, `phone`, `reference`, and `callbackUrl`. Its response
+has `accepted`. Payouts retain the existing provider protocol, including the `callbackUrl` wire field;
+the corporate collection document does not replace that protocol.
 
-Install dependencies with `bun install`, then run `bun run quality` before opening a pull request.
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete contribution workflow.
+## Read transaction outcomes
 
-## Testing
-
-Run `bun run test` for the test suite or `bun run test:coverage` for a coverage report.
-
-## Contributing
-
-Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) and follow our
-[Code of Conduct](CODE_OF_CONDUCT.md).
+```ts
+import { parseCallback } from "@ngandu-dev/flexpay";
 
-## Security
+const check = await client.check(mobile.orderNumber);
 
-Please report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+if (check.successful) {
+  // The lookup succeeded and the nested transaction has a success status.
+}
 
-## License
+// incomingBody is the unknown JSON body received by your callback endpoint.
+const callback = parseCallback(incomingBody);
 
-Released under the [MIT License](LICENSE).
+if (callback.successful) {
+  // The parsed callback claims success. Authenticate its sender in your application.
+}
+```
 
-## Contributors
+`parseCallback` requires no client or credentials. It validates the payload; it does not authenticate
+the sender, establish webhook trust, or fulfill an order. `CallbackResponse` preserves amounts,
+phone, currency, timestamps, channel, reference, order number, and `providerReference`. The wire
+field is `provider_reference`; a pre-normalized `providerReference` input alias is not supported.
+
+Every response `code` and transaction `status` is an immutable `Status` instance.
+`status.value` preserves the numeric provider code. `status.isSuccessful()`
+means code `0`, and `status.isFailure()` means code `1`. Other integer codes are retained without
+assigning them a meaning. For example, a simulator status of `2` makes both methods return `false`.
+
+Initiation results expose `accepted`; callback and check results expose `successful`. Check success
+requires both a successful lookup code and a successful nested transaction status. A missing,
+failed, pending, or unknown transaction cannot produce `successful: true`. Response objects,
+nested transactions, and their `Status` objects are frozen so these derived outcomes cannot become stale.
+
+Live checks have verified both the unknown-order rejection and an existing card order with lookup
+code `0`, nested status `4`, and a message stating that the operator declined that order. The client
+preserves status `4` and returns `successful: false`; this observation does not assign status `4` a
+global meaning. The response omitted the nested order number, which normalizes to `null`. A paid
+transaction with nested status `0` and the upstream pending-status code remain unverified.
+
+## Failure behavior
+
+Each HTTP attempt has a 30-second deadline. Payment and payout POST requests are sent once.
+GET checks can retry three times after transient network, timeout, or server failures. Default delays
+are 500, 1,000, and 2,000 milliseconds. On a 5xx response, a numeric `Retry-After` of at most two seconds
+raises the delay when it exceeds the default. A longer, date-formatted, or invalid `Retry-After`
+stops retries instead of retrying earlier than requested. The four attempts and three bounded waits
+take at most 126 seconds, plus event-loop scheduling and processing time. No automatic retry follows
+a 4xx response or malformed HTTP 200 response.
+
+Redirects are not followed. A 3xx response raises `NetworkException` with `type: "unexpected_redirect"`.
+This prevents the transport from forwarding a bearer token or replaying a POST to another location.
+A timeout raises `NetworkException` with `type: "timeout"`.
+
+Unreadable JSON and structurally invalid provider responses raise `NetworkException` with
+`type: "invalid_response"`, HTTP status, and Content-Type. HTTP classifications are retained:
+401/429 use `AccountException`, other 4xx use `ClientException`, and 5xx use `ServerException`.
+HTTP failures containing JSON use `type: "http_error"`. Provider error bodies and raw fetch/parser
+causes are not copied into these exceptions. Local request/configuration validation and
+`parseCallback` report Zod validation errors.
+
+A transport failure does not prove that a payment was rejected. Reconcile the original transaction
+before attempting another collection.
+
+## Design and tests
+
+`Client` coordinates four provider operations. Configuration schemas own input validation and
+immutable endpoint/credential snapshots. Request schemas and wire factories own request shape;
+response schemas own normalization and distinguish acceptance from completion. `Status` owns the
+meaning of a numeric provider code. `HttpTransport` owns bearer authentication, deadlines,
+redirect policy, response validation failures, and bounded read retries.
+
+For a card collection, the client validates input, creates the wire body, and asks the transport
+for a response parsed by the card schema. That schema computes `accepted` from its `Status`.
+For an HTML 403, the transport returns a `ClientException` marked `invalid_response`, sends no
+second POST, and excludes the HTML from the diagnostic. The caller owns reconciliation.
+
+```sh
+bun install --frozen-lockfile
+bun run format
+bun run quality
+bun run test:coverage
+bun audit
+```
 
-<a href="https://github.com/ngandu-dev/flexpay/graphs/contributors" title="Show all contributors">
-  <img src="https://contrib.rocks/image?repo=ngandu-dev/flexpay" alt="Contributors" />
-</a>
+`quality` runs formatting checks, type checks, tests, builds, and package/export validation.
+Tests exercise injected Fetch implementations, exact wire payloads, immutable statuses,
+acceptance/completion semantics, deadlines, redirects, and error classifications.
+
+`src/__tests__/fixtures/corporate.json` contains deterministic simulator examples. Its pending code
+`2` is a simulator convention, not a confirmed provider mapping. The provider rejection fixtures
+record controlled observations from October 29, 2026. Mobile `callback_url` and `callbackUrl` probes
+both advanced past missing-callback validation to an invalid-amount rejection. Card string probes
+were inconclusive because absent callbacks also reached the amount error. Object-field controls
+supported recognition of both spellings during input handling but did not verify initiation or
+callback delivery. Serialization therefore keeps the documented `callback_url` field.
+`provider-existing-order.json` preserves an observed declined-card check shape with an anonymized
+order/reference and a synthetic timestamp in the observed format.
+No automated test uses real credentials or submits a provider payment.
+
+## Contributing and security
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and
+[SECURITY.md](SECURITY.md) for private vulnerability reporting. Contributions follow the
+[Code of Conduct](CODE_OF_CONDUCT.md). Released under the [MIT License](LICENSE).