remita-checkout-client 0.1.0 → 0.1.2

package/README.md

@@ -1,30 +1,21 @@
 # remita-checkout-client
 
-A typed client for the Remita Checkout REST API (`api-checkout*.systemspecsng.com`).
-Works in the browser and in Node 18+ (both have global `fetch`).
+A typed TypeScript client for the Remita Checkout API. It lets you accept
+payments, run the full payment lifecycle, check payment status in real time, and
+look up supported channels — from the browser or Node.js 18+.
 
-## ⚠️ Before you use this in anything real
+Two clients are available:
 
-The request/response **field names** in `src/types.ts` were written from
-endpoint paths + one-line descriptions only — not the actual DTOs. Every
-interface has an index signature so unexpected fields won't break at the
-type level, but treat the field names themselves as **unverified**. To
-tighten them, pull the actual interfaces out of:
+- **`MerchantCheckoutClient`** — start a checkout and verify the result. Best for
+  storefronts and businesses that only need to accept payment for a sale.
+- **`RemitaPlatformClient`** — the full payment lifecycle (pre-payment, fees,
+  initiation, authorization, validation, verification) plus channel lookups.
+  Best for payment facilitators, gateways, and platforms.
 
-- `remita-api-client.service.ts`
-- `payment-status.service.ts`
+## Requirements
 
-and update `src/types.ts` to match. The transport layer, URLs, HTTP
-methods, and the pre → fee → initiate → authorize → validate → verify
-sequencing are all solid; it's specifically the shape of each request/
-response body that needs confirming.
-
-The **environment auto-detection from key prefix** (`src/environment.ts`)
-is also a guess (Stripe-style `pk_test_`/`pk_live_` conventions) — it has
-not been verified against Remita's real key format. It intentionally never
-silently resolves to `"production"` — an unrecognized prefix falls back to
-`"qa"` and reports `detected: false` so you can log/warn on it. Until you
-verify the real prefixes, pass `environment` explicitly and skip detection.
+- Node.js 18 or newer, or a browser with `fetch` support.
+- A Remita public key for your environment.
 
 ## Install
 
@@ -32,53 +23,178 @@ verify the real prefixes, pass `environment` explicitly and skip detection.
 npm install remita-checkout-client
 ```
 
-## Usage
+The package includes TypeScript types and works with both ESM and CommonJS.
+
+## Environments
+
+Choose the environment that matches your key:
+
+| Environment  | Base URL                                              |
+| ------------ | ----------------------------------------------------- |
+| `qa`         | `https://api-checkout-qa.systemspecsng.com/api/v1`     |
+| `demo`       | `https://api-checkout-demo.systemspecsng.com/api/v1`   |
+| `production` | `https://api-checkout.systemspecsng.com/api/v1`        |
+
+Set the environment explicitly, especially for production.
+
+```ts
+import { RemitaPlatformClient } from "remita-checkout-client";
+
+const client = new RemitaPlatformClient({
+  publicKey: process.env.REMITA_PUBLIC_KEY!,
+  environment: "qa",
+});
+```
+
+Your public key is sent in a request header. Keep secret keys out of browser
+code, and always verify a payment on your server before fulfilling an order.
 
-### Low-level client
+## Merchant checkout
+
+Merchant payments use Remita's hosted inline checkout. The client loads Remita's
+`payment-checkout.js`, then drives the global `RmPaymentEngine` — the same
+integration as Remita's own inline sample — and can verify the payment
+afterwards over REST.
 
 ```ts
-import { RemitaCheckoutClient } from "remita-checkout-client";
+import { MerchantCheckoutClient } from "remita-checkout-client";
+
+const checkout = new MerchantCheckoutClient({
+  publicKey: "MERCHANT_PUBLIC_KEY",
+  environment: "production",
+});
 
-const client = new RemitaCheckoutClient({
-  publicKey: "YOUR_PUBLIC_KEY",
-  // environment: "qa", // recommended explicitly until prefix detection is verified
-  onEnvironmentDetectionFallback: (guessed) =>
-    console.warn(`Couldn't detect environment from key prefix, defaulting to ${guessed}`),
+// Loads Remita's checkout script once and calls RmPaymentEngine.init.
+const engine = await checkout.init({
+  paymentIdentifier: 788885554,
+  customerId: "abc@ya.com",
+  firstName: "Mike",
+  lastName: "Mike",
+  email: "abc@ya.com",
+  phoneNumber: "08067493797",
+  amount: "3000",
+  narration: "Test Payment",
+  currency: "NGN",
+  // channels: "TRANSFER",
+  onSuccess: (response) => console.log("success", response),
+  onError: (response) => console.log("error", response),
+  onClose: () => console.log("closed"),
 });
 
-const pre = await client.prePayment({ publicKey: client.publicKey, rrr: "RRR12345" });
-const fee = await client.calculateFee({ publicKey: client.publicKey, amount: 5000, channel: "card" });
-const initiated = await client.initiatePayment({ publicKey: client.publicKey, amount: 5000, channel: "card" });
+engine.openIframe();
+```
 
+After the customer completes payment, verify it on your server before
+fulfilling the order:
+
+```ts
+const verified = await checkout.verifyPayment("PAYMENT_REF_FROM_REMITA");
+if (verified.status === "APPROVED") {
+  // Confirm the order on your backend before fulfilling it.
+}
+```
+
+To collect an existing Remita Retrieval Reference (RRR) instead, use
+`processRRR`, which mirrors `RmPaymentEngine.processRRR`:
+
+```ts
+const engine = await checkout.processRRR({
+  rrr: "927227066514",
+  paymentIdentifier: "7888855540094893435734834935035408",
+  channels: "",
+  onSuccess: (response) => console.log("success", response),
+  onError: (response) => console.log("error", response),
+  onClose: () => console.log("closed"),
+});
+
+engine.openIframe();
+```
+
+The hosted checkout is browser-only. `init`, `createCheckoutSession`,
+`createSession`, and `processRRR` return the `RmPaymentEngine` instance, so you
+call `openIframe()` to display it exactly like the script tag example. The
+script URL is chosen from the environment and can be overridden with
+`scriptUrl`.
+
+## Platform lifecycle
+
+`RemitaPlatformClient` walks the full flow: pre-payment, fee, initiation,
+authorization, validation, and verification.
+
+```ts
+import { RemitaPlatformClient } from "remita-checkout-client";
+
+const remita = new RemitaPlatformClient({
+  publicKey: "PSP_PUBLIC_KEY",
+  environment: "production",
+});
+
+const pre = await remita.prePayment({
+  firstName: "Ada",
+  lastName: "Okafor",
+  email: "ada@example.com",
+  phoneNumber: "08000000000",
+  paymentIdentifier: "ORDER-123",
+  currency: "NGN",
+  amount: 25000,
+});
+
+const fee = await remita.calculateFee({ amount: 25000, channel: "card" });
+
+const paymentIdentifier = pre.transactionId ?? pre.paymentReference;
+if (!paymentIdentifier) throw new Error("Pre-payment did not return a transaction reference");
+
+const initiated = await remita.initiatePayment({
+  amount: 25000,
+  paymentIdentifier,
+  paymentChannel: "CARD",
+});
+
+// Only when the payment processor asks for it:
 if (initiated.actionUrl) {
-  await client.authorize(initiated.actionUrl, { /* OTP / PIN / 3DS fields */ });
+  await remita.authorize(initiated.actionUrl, { otp: "123456" });
+  await remita.validatePayment({ paymentReference: initiated.paymentReference, otp: "123456" });
 }
 
-const verified = await client.verifyPayment(initiated.paymentReference!);
+const verified = await remita.verifyPayment(initiated.paymentReference!);
 console.log(verified.status); // "APPROVED" | "PENDING" | "FAILED" | ...
 ```
 
-### Higher-level session (tracks refs between steps for you)
+### Tracking a payment with PaymentSession
+
+`PaymentSession` carries the references between steps so you don't have to, and
+tracks the current stage of the flow. Its `stage` becomes `verified` only when
+the payment is `APPROVED` and `failed` when it is `FAILED`; a `PENDING` payment
+leaves the stage unchanged.
 
 ```ts
-import { RemitaCheckoutClient, PaymentSession } from "remita-checkout-client";
+import { RemitaPlatformClient, PaymentSession } from "remita-checkout-client";
 
-const client = new RemitaCheckoutClient({ publicKey: "YOUR_PUBLIC_KEY", environment: "qa" });
+const client = new RemitaPlatformClient({ publicKey: "YOUR_PUBLIC_KEY", environment: "qa" });
 const session = new PaymentSession(client);
 
-await session.pre({ publicKey: client.publicKey, rrr: "RRR12345" });
-await session.fee({ publicKey: client.publicKey, amount: 5000, channel: "card" });
-await session.initiate({ publicKey: client.publicKey, amount: 5000, channel: "card" });
+await session.pre({
+  firstName: "Ada", lastName: "Okafor", email: "ada@example.com",
+  phoneNumber: "08000000000", paymentIdentifier: "ORDER-123",
+  currency: "NGN", amount: 25000,
+});
+await session.fee({ amount: 25000, channel: "card" });
+
+const paymentIdentifier = session.transactionId ?? session.paymentReference;
+if (!paymentIdentifier) throw new Error("Pre-payment did not return a transaction reference");
+await session.initiate({ amount: 25000, paymentIdentifier, paymentChannel: "CARD" });
 
-// actionUrl from initiate() is remembered automatically
+// The actionUrl from initiate() is remembered automatically.
 await session.authorize({ otp: "123456" });
 await session.validate({ otp: "123456" });
 
-const result = await session.verify(); // uses paymentReference captured from initiate()
+const result = await session.verify();
 console.log(session.stage, result.status);
 ```
 
-### Real-time status via SSE
+## Real-time payment status
+
+Follow a payment's status live with server-sent events:
 
 ```ts
 const handle = client.streamPaymentStatus(trxRef, {
@@ -87,15 +203,10 @@ const handle = client.streamPaymentStatus(trxRef, {
   onError: (err) => console.error("stream error:", err),
 });
 
-// later
-handle.close();
+handle.close(); // when you're done
 ```
 
-This is implemented as a manual `fetch` + `ReadableStream` reader (not the
-browser-only `EventSource` global), so it behaves the same in the browser
-and in Node.
-
-### Channel config endpoints
+## Channel and configuration lookups
 
 ```ts
 const banks = await client.getBankList();
@@ -103,36 +214,105 @@ const ussdCodes = await client.getUssdCodes();
 const wallets = await client.getWalletTypes();
 ```
 
-## Node < 18
-
-Global `fetch` isn't available before Node 18. Pass a `fetchImpl` explicitly:
+## Command line
 
-```ts
-import fetch from "node-fetch";
+The package also installs a `remita-checkout` command with two groups:
+`merchant` and `platform`.
 
-const client = new RemitaCheckoutClient({
-  publicKey: "...",
-  environment: "qa",
-  fetchImpl: fetch as unknown as typeof globalThis.fetch,
-});
+```bash
+remita-checkout <group> <command> [options]
 ```
 
-## Not covered in this version
+### Merchant commands
+
+| Command            | Description                      |
+| ------------------ | -------------------------------- |
+| `merchant verify`  | Verify a payment by reference    |
+| `merchant status`  | Alias for `verify`               |
+
+Merchant checkout itself runs in the browser through the hosted
+`RmPaymentEngine`, so there is no CLI command to start it — the CLI only checks
+payment status.
+
+### Platform commands
+
+| Command              | Description                                   |
+| -------------------- | --------------------------------------------- |
+| `platform pre`       | Pre-payment initialization                    |
+| `platform fee`       | Calculate the fee for a channel               |
+| `platform initiate`  | Initiate a payment                            |
+| `platform authorize` | Submit authorization details                  |
+| `platform validate`  | Complete second-factor authorization (OTP)    |
+| `platform verify`    | Verify payment status by reference            |
+| `platform stream`    | Stream real-time status updates               |
+| `platform banks`     | List supported banks                          |
+| `platform ussd`      | List USSD codes                               |
+| `platform wallets`   | List wallet types                             |
+
+### Options
+
+| Option                        | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
+| `--key <publicKey>`           | Remita public key (required for most commands)      |
+| `--env <qa\|demo\|production>`| Environment to use                                  |
+| `--payment-identifier <ref>`  | Reference from the payment flow                     |
+| `--payment-channel <channel>` | Payment channel, e.g. `CARD`                        |
+| `--payload <json>`            | Additional details as JSON                          |
+| `--show-payload`              | Preview the request with sensitive fields redacted  |
+| `--json`                      | Print raw JSON, useful for piping                   |
+
+### Examples
 
-Per the agreed v1 scope, this does **not** include:
+```bash
+remita-checkout merchant verify --key QA-abc123 --ref PAY-REF-1 --json
+remita-checkout platform pre --key QA-abc123 --rrr 123456789
+remita-checkout platform verify --key QA-abc123 --ref PAY-REF-1 --json
+```
 
-- Google Pay / Apple Pay config endpoints (`/misc/googlepay`, `/misc/applepay`)
-- CyberSource / Cardinal 3DS flow (Cruise Collect iframe, Centinel API, the
-  return listener endpoint)
+Only use Remita-approved test data in QA. Never pass real card details on the
+command line — `--show-payload` redacts them, but shell history does not.
 
-Both are separate, non-trivial integrations (iframe orchestration for DDC,
-CyberSource's Accept.js script loading) — worth their own follow-up rather
-than bolting on here.
+## Errors
 
-## Development
+Failed requests throw a `RemitaApiError` that includes the HTTP status and the
+error details returned by the API:
 
-```bash
-npm install
-npm run typecheck
-npm run build   # outputs dist/ as CJS + ESM + .d.ts
+```ts
+import { RemitaApiError } from "remita-checkout-client";
+
+try {
+  await client.verifyPayment("PAYMENT_REF");
+} catch (error) {
+  if (error instanceof RemitaApiError) {
+    console.error(error.status, error.message, error.payload);
+  } else {
+    throw error;
+  }
+}
 ```
+
+## API coverage
+
+| Operation                    | Method and path                                     |
+| ---------------------------- | --------------------------------------------------- |
+| Pre-payment                  | `POST /payment/pre`                                 |
+| Fee calculation              | `POST /payment/pre/feeCharge`                       |
+| Initiate / merchant checkout | `POST /payment/initiate`                            |
+| Authorize                    | `POST` to the action URL returned by initiation     |
+| Validate payment             | `POST /payment/validate`                            |
+| Verify payment               | `GET /payment/verify/{reference}`                   |
+| Payment status stream        | `GET /payment/status/stream/{transactionReference}` |
+| Bank list                    | `GET /payment/bank-list`                            |
+| USSD codes                   | `GET /misc/ussd-codes`                              |
+| Wallet types                 | `GET /misc/wallet-type`                             |
+
+## Notes
+
+- Google Pay / Apple Pay configuration and the CyberSource / Cardinal 3DS iframe
+  flow are not included in this version.
+- Confirm request and response details against Remita's current API
+  documentation for your environment before going live.
+
+## License
+
+MIT