@ngandu-dev/flexpay 2.0.4 → 3.0.0

package/UPGRADE_3.0.0.md

@@ -0,0 +1,345 @@
+# Upgrade to FlexPay TypeScript 3.0.0
+
+Version 3 moves mobile-money and card collections to FlexPay's corporate API and changes the public
+client, status, and response contracts. This guide covers migration from version 2. Current usage
+examples are in the [README](README.md).
+
+## Configure explicit destinations
+
+Replace positional merchant/token arguments with a `Credential` object and a required `BaseUrl`.
+Remove imports of `Environment`, `EnvironmentType`, and `BaseUrls`. There is no default environment
+or destination. Node.js 24 or newer remains required.
+
+Before:
+
+```ts
+import { Client } from "@ngandu-dev/flexpay";
+
+const client = new Client("MERCHANT_CODE", "YOUR_TOKEN", "prod");
+```
+
+After:
+
+```ts
+import { Client, type Credential, productionBaseUrl } from "@ngandu-dev/flexpay";
+
+const credential = {
+  merchant: "MERCHANT_CODE",
+  token: "YOUR_TOKEN",
+} satisfies Credential;
+
+const client = new Client(credential, productionBaseUrl);
+```
+
+Replace `apiBaseUrl` and `cardBaseUrl` overrides with all three `BaseUrl` properties, even if your
+application uses only one operation. Prefixes include the API version and omit the service path.
+
+Before:
+
+```ts
+const localClient = new Client("TESTMERCHANT", "test-token", "dev", {
+  apiBaseUrl: "http://localhost:8080/api/rest/v1",
+  cardBaseUrl: "http://localhost:8080/v1.1",
+});
+```
+
+After:
+
+```ts
+import { Client, type BaseUrl } from "@ngandu-dev/flexpay";
+
+const baseUrl = {
+  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" },
+  baseUrl,
+);
+```
+
+`productionBaseUrl` contains these prefixes:
+
+| Property | Prefix |
+| --- | --- |
+| `payment` | `https://corporateapi.flexpay.cd/api/rest/v1` |
+| `check` | `https://apicheck.flexpaie.com/api/rest/v1` |
+| `payout` | `https://backend.flexpay.cd/api/rest/v1` |
+
+FlexPay has not supplied a corporate sandbox URL. Configure your simulator explicitly instead of
+relying on the removed `dev` environment. Both mobile and card now use `/paymentService`. Checks
+use the separate check prefix. Payouts retain `/merchantPayOutService` and the existing wire protocol.
+
+Configuration schemas reject unknown fields and blank credentials. Base URLs must be absolute
+HTTP(S) prefixes without credentials, query strings, fragments, backslashes, or internal whitespace
+and control characters. Surrounding whitespace and trailing slashes are removed from prefixes.
+Merchant/token contents are preserved. The client retains immutable validated snapshots.
+
+An optional third constructor argument accepts a Fetch-compatible function. It must honor the
+provided abort signal and `redirect: "manual"` behavior.
+
+## Replace payment dispatch and removed request fields
+
+Replace `pay()` with `mobile()` or `card()`. Request schemas reject unknown fields rather than
+silently stripping them. Remove obsolete fields from runtime objects as well as TypeScript types.
+
+For mobile requests, remove `description`, `approveUrl`, `cancelUrl`, and `declineUrl`.
+
+Before:
+
+```ts
+const mobile = await client.pay({
+  amount: 10,
+  currency: "USD",
+  phone: "243810000001",
+  reference: "mobile-order-123",
+  callbackUrl: "https://example.com/payments/callback",
+  description: "Order payment",
+  approveUrl: "https://example.com/payments/approved",
+});
+```
+
+After:
+
+```ts
+const mobile = await client.mobile({
+  amount: 10,
+  currency: "USD",
+  phone: "243810000001",
+  reference: "mobile-order-123",
+  callbackUrl: "https://example.com/payments/callback",
+});
+
+if (!mobile.accepted || !mobile.orderNumber) {
+  throw new Error(mobile.message || "Payment initiation was not accepted");
+}
+```
+
+For card requests, remove `description` and `homeUrl`. The 25-character reference cap is removed.
+
+Before:
+
+```ts
+const card = await client.card({
+  amount: 10,
+  currency: "USD",
+  reference: "card-order-123",
+  description: "Order payment",
+  homeUrl: "https://example.com",
+  callbackUrl: "https://example.com/payments/callback",
+  approveUrl: "https://example.com/payments/approved",
+  cancelUrl: "https://example.com/payments/cancelled",
+  declineUrl: "https://example.com/payments/declined",
+});
+```
+
+After:
+
+```ts
+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",
+});
+
+if (!card.accepted || !card.orderNumber || !card.url) {
+  throw new Error(card.message || "Card checkout is unavailable");
+}
+
+// Store card.orderNumber, then redirect the customer to card.url.
+```
+
+Public fields remain camelCase. The SDK writes string types `"1"`/`"2"`, `callback_url`, and the
+card redirect fields in snake_case. Authorization is sent only in the bearer header. Remove any
+application-side dependency on body authorization, `home_url`, description, or the old card `/pay`
+endpoint. Payout input fields remain `amount`, `currency`, `phone`, `reference`, and `callbackUrl`;
+its wire body still uses numeric type `1` and `callbackUrl`.
+
+Phones now require exactly 12 digits, rather than any 12 characters. Amounts must be positive finite
+numbers. References, callback strings, and redirect strings must contain non-whitespace content;
+the SDK does not validate callback/redirect strings as absolute URLs. Check identifiers cannot be
+blank or exactly `.` or `..`. Request validation does not silently trim or rewrite your values.
+
+## Separate acceptance from completion
+
+Remove `client.isSuccessful()`. Use the result property for the operation you performed:
+
+| Operation | Property | Meaning |
+| --- | --- | --- |
+| `mobile()`, `card()`, `payout()` | `accepted` | The provider returned initiation code 0. |
+| `check()` | `successful` | Both lookup code and nested transaction status are 0. |
+| `parseCallback()` | `successful` | The supplied callback claims code 0. |
+
+An accepted initiation can still have a missing or empty order number or checkout URL. Check these
+fields before using them. Acceptance does not confirm collection of funds.
+
+Before:
+
+```ts
+const check = await client.check("ORDER_NUMBER");
+
+if (client.isSuccessful(check)) {
+  // Version 2 checked only the top-level lookup code.
+}
+```
+
+After:
+
+```ts
+const check = await client.check("ORDER_NUMBER");
+
+if (check.successful) {
+  // The lookup succeeded and the nested transaction has a success status.
+}
+```
+
+An observed live card check returned lookup code `0`, transaction status `4`, and a message saying
+the operator declined that order. Version 3 preserves status `4` and returns `successful: false`.
+This observation does not establish a global mapping for status `4`. A paid transaction with
+nested status `0` and the provider's pending-status code remain unverified.
+
+## Migrate status comparisons and serialization
+
+`Status` is now an immutable value object. Every response `code` and transaction `status` is a
+`Status` instance. Remove `Status.SUCCESS`, `Status.FAILURE`, and direct numeric comparisons.
+
+Before:
+
+```ts
+import { Status } from "@ngandu-dev/flexpay";
+
+const hasSuccessCode = check.code === Status.SUCCESS;
+const hasFailureCode = check.transaction?.status === Status.FAILURE;
+```
+
+After:
+
+```ts
+const lookupSucceeded = check.code.isSuccessful();
+const hasKnownFailureCode = check.transaction?.status.isFailure() === true;
+const rawTransactionStatus = check.transaction?.status.value;
+```
+
+`isSuccessful()` recognizes only `0`; `isFailure()` recognizes only `1`. Other safe integer codes
+remain intact without an inferred state. For example, status `4` makes both methods return `false`.
+Never treat `!status.isFailure()` as proof of payment success. Use `check.successful` for the full
+check outcome, not `check.code.isSuccessful()` alone.
+
+Use `new Status(integer)` for application-owned values. `StatusSchema` parses provider integers or
+canonical integer strings into `Status`; it does not accept an already-normalized `Status` object.
+
+JSON output changes with the value object:
+
+```ts
+import { Status } from "@ngandu-dev/flexpay";
+
+JSON.stringify(new Status(0)); // {"value":0}
+```
+
+Serializing a whole SDK response preserves these nested objects. `JSON.parse` does not restore
+their methods. If your persistence or API contract requires numeric codes, map `.value` explicitly:
+
+```ts
+const storedCheck = {
+  code: check.code.value,
+  message: check.message,
+  transaction:
+    check.transaction === null
+      ? null
+      : { ...check.transaction, status: check.transaction.status.value },
+};
+
+const storedJson = JSON.stringify(storedCheck);
+```
+
+To read that numeric representation back into SDK objects, parse it with `CheckResponseSchema`:
+
+```ts
+import { CheckResponseSchema } from "@ngandu-dev/flexpay";
+
+const restoredCheck = CheckResponseSchema.parse(JSON.parse(storedJson));
+```
+
+## Update response types and callback handling
+
+`MobileResponse` now contains only `code`, `message`, `orderNumber`, and `accepted`.
+`PayoutResponse` has the same shape. `CardResponse` adds nullable `url`. Reporting fields belong
+to the new `CallbackResponse`, which has `successful`, amounts, phone, currency, timestamps,
+channel, reference, order number, and `providerReference`.
+
+Replace `client.handleCallback()` with standalone `parseCallback()`. No client or credential is
+needed to parse a callback.
+
+Before:
+
+```ts
+const callback = client.handleCallback(incomingBody);
+const claimedSuccess = client.isSuccessful(callback);
+```
+
+After:
+
+```ts
+import { parseCallback } from "@ngandu-dev/flexpay";
+
+const callback = parseCallback(incomingBody);
+const claimedSuccess = callback.successful;
+```
+
+The parser validates payload structure and reports the payload's claim. It does not authenticate
+the sender or authorize fulfillment. Keep that verification in your application.
+
+Only the provider's wire field `provider_reference` populates `callback.providerReference`.
+An input containing only the old camelCase alias `providerReference` leaves the output field null;
+provider response objects permit extra fields, so the alias does not raise a validation error.
+
+Normalized results, nested transactions, and statuses are frozen and readonly. Optional wire
+fields such as card URL and nested transaction order number now normalize to required nullable
+output properties. Missing messages normalize to an empty string. An empty order number remains
+an empty string. Do not mutate a result or rely on `undefined` for these fields.
+
+Update hand-built typed mocks to include `Status` instances, derived outcome properties, and all
+normalized nullable fields. Exported schemas can build consistent fixtures from wire data:
+
+```ts
+import { MobileResponseSchema } from "@ngandu-dev/flexpay";
+
+const mobileResponse = MobileResponseSchema.parse({
+  code: "0",
+  message: "Accepted",
+  orderNumber: "TEST-ORDER",
+});
+```
+
+Do not pass a serialized SDK response containing `{ "value": 0 }` into a provider-response schema.
+Use raw numeric/string wire codes, or explicitly restore the numeric representation as shown above.
+
+## Update error handling and retry assumptions
+
+HTTP response parsing now occurs inside the transport. Malformed JSON or an invalid response
+structure raises `NetworkException` with `type: "invalid_response"`, rather than a Zod error.
+HTTP status and Content-Type remain available in the diagnostic. Parsed HTTP failures use
+`type: "http_error"`; provider error bodies, error messages, and raw fetch/parser causes are no
+longer copied into the exception. HTTP 200 business rejection codes remain decoded result objects.
+
+The exception classes retain their HTTP mapping: 401/429 use `AccountException`, other 4xx use
+`ClientException`, and 5xx use `ServerException`. Direct request/configuration validation and
+`parseCallback` still raise Zod errors. Invalid check identifiers raise `Error`; invalid direct
+`Status` construction raises `RangeError`.
+
+Payment and payout POSTs are sent once. Only GET checks retry transient network, timeout, or 5xx
+failures, up to three retries after the original attempt. Each attempt has a 30-second deadline.
+Default waits are 500, 1,000, and 2,000 milliseconds. A numeric `Retry-After` of at most two seconds
+can increase a wait; a longer, date-formatted, or invalid value suppresses retry. Known 4xx
+responses do not retry, even if reading the body later fails.
+
+Redirects now raise `NetworkException` with `type: "unexpected_redirect"` and are not followed.
+Timeouts use `type: "timeout"`; unknown fetch failures use `type: "network_error"`. Unfinished
+responses are closed when an attempt ends. A transport failure does not establish whether a
+payment was accepted. Reconcile the original transaction before attempting another collection.