remita-checkout-client 0.1.1 → 0.1.2

package/README.md

@@ -1,57 +1,60 @@
 # 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+.
 
-## Two product surfaces
+Two clients are available:
 
-This package is built around two user types:
+- **`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.
 
-### Merchant checkout
+## Requirements
 
-Use this when you are a business or storefront that only wants to accept payment
-for a sale.
+- Node.js 18 or newer, or a browser with `fetch` support.
+- A Remita public key for your environment.
 
-Typical needs:
-
-- create a checkout session
-- redirect or embed the payment flow
-- verify payment completion
-- update order status
-
-Recommended client:
-
-- `MerchantCheckoutClient`
+## Install
 
-### PSP / platform
+```bash
+npm install remita-checkout-client
+```
 
-Use this when you are a payment facilitator, gateway, or platform operator that
-needs the full Remita lifecycle.
+The package includes TypeScript types and works with both ESM and CommonJS.
 
-Typical needs:
+## Environments
 
-- pre-payment flows
-- fee calculation
-- payment initiation
-- authorization and validation
-- status verification
-- channel lookup and platform configuration
+Choose the environment that matches your key:
 
-Recommended client:
+| 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`        |
 
-- `RemitaPlatformClient`
+Set the environment explicitly, especially for production.
 
-### Compatibility
+```ts
+import { RemitaPlatformClient } from "remita-checkout-client";
 
-`RemitaCheckoutClient` remains available as a backwards-compatible alias of the
-platform client for older integrations, but the preferred split is:
+const client = new RemitaPlatformClient({
+  publicKey: process.env.REMITA_PUBLIC_KEY!,
+  environment: "qa",
+});
+```
 
-- `MerchantCheckoutClient` for checkout-only usage
-- `RemitaPlatformClient` for PSP/platform usage
+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.
 
----
+## Merchant checkout
 
-## Quick example: 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 { MerchantCheckoutClient } from "remita-checkout-client";
@@ -61,22 +64,62 @@ const checkout = new MerchantCheckoutClient({
   environment: "production",
 });
 
-const session = await checkout.createCheckoutSession({
-  amount: 25000,
-  paymentIdentifier: "TRANSACTION_REF_123",
-  narration: "Order 123",
-  paymentChannel: "CARD",
-  metaData: {},
-  merchantInformation: {},
+// 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 verified = await checkout.verifyPayment("PAYMENT_REF_123");
-console.log(verified.status);
+engine.openIframe();
 ```
 
----
+After the customer completes payment, verify it on your server before
+fulfilling the order:
 
-## Quick example: PSP / platform flow
+```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";
@@ -87,19 +130,16 @@ const remita = new RemitaPlatformClient({
 });
 
 const pre = await remita.prePayment({
-  firstName: "Test",
-  lastName: "User",
-  email: "test@example.com",
+  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 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");
@@ -110,114 +150,51 @@ const initiated = await remita.initiatePayment({
   paymentChannel: "CARD",
 });
 
-const verified = await remita.verifyPayment(initiated.paymentReference!);
-console.log(verified.status);
-```
-
-## ⚠️ Before you use this in anything real
-
-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:
-
-- `remita-api-client.service.ts`
-- `payment-status.service.ts`
-
-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.
-
-## Install
-
-```bash
-npm install remita-checkout-client
-```
-
-## Usage
-
-### Low-level client
-
-```ts
-import { RemitaCheckoutClient } from "remita-checkout-client";
-
-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}`),
-});
-
-const pre = await client.prePayment({
-  firstName: "Test",
-  lastName: "User",
-  email: "test@example.com",
-  phoneNumber: "08000000000",
-  paymentIdentifier: "ORDER-123",
-  currency: "NGN",
-  amount: 5000,
-});
-const fee = await client.calculateFee({ publicKey: client.publicKey, amount: 5000, channel: "card" });
-const paymentIdentifier = pre.transactionId ?? pre.paymentReference;
-if (!paymentIdentifier) throw new Error("Pre-payment did not return a transaction reference");
-const initiated = await client.initiatePayment({
-  amount: 5000,
-  paymentIdentifier: "TRANSACTION_REF_123",
-  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({
-  firstName: "Test",
-  lastName: "User",
-  email: "test@example.com",
-  phoneNumber: "08000000000",
-  paymentIdentifier: "ORDER-123",
-  currency: "NGN",
-  amount: 5000,
+  firstName: "Ada", lastName: "Okafor", email: "ada@example.com",
+  phoneNumber: "08000000000", paymentIdentifier: "ORDER-123",
+  currency: "NGN", amount: 25000,
 });
-await session.fee({ publicKey: client.publicKey, amount: 5000, channel: "card" });
+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: 5000,
-  paymentIdentifier,
-  paymentChannel: "CARD",
-});
+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, {
@@ -226,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();
@@ -242,36 +214,105 @@ const ussdCodes = await client.getUssdCodes();
 const wallets = await client.getWalletTypes();
 ```
 
-## Node < 18
+## Command line
 
-Global `fetch` isn't available before Node 18. Pass a `fetchImpl` explicitly:
+The package also installs a `remita-checkout` command with two groups:
+`merchant` and `platform`.
 
-```ts
-import fetch from "node-fetch";
-
-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

package/dist/{chunk-RLUJCMLB.mjs → chunk-O2KJGHVA.mjs}

@@ -5,6 +5,16 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// src/types.ts
+var RemitaApiError = class extends Error {
+  constructor(message, status, payload) {
+    super(message);
+    this.name = "RemitaApiError";
+    this.status = status;
+    this.payload = payload;
+  }
+};
+
 // src/environment.ts
 var ENVIRONMENT_BASE_URLS = {
   qa: "https://api-checkout-qa.systemspecsng.com/api/v1",
@@ -91,15 +101,39 @@ function openStatusStream(baseUrl, trxRef, publicKey, options) {
   };
 }
 
-// src/http-client.ts
-var RemitaApiError = class extends Error {
-  constructor(message, status, payload) {
-    super(message);
-    this.status = status;
-    this.payload = payload;
-    this.name = "RemitaApiError";
-  }
+// src/inline.ts
+var INLINE_CHECKOUT_SCRIPT_URLS = {
+  qa: "https://checkout-web-qa.systemspecsng.com/js/payment-checkout.js",
+  demo: "https://checkout-web-demo.systemspecsng.com/js/payment-checkout.js",
+  production: "https://checkout-web.systemspecsng.com/js/payment-checkout.js"
 };
+function getInlineCheckoutScriptUrl(environment, override) {
+  return override ?? INLINE_CHECKOUT_SCRIPT_URLS[environment];
+}
+function loadInlineCheckoutScript(scriptUrl, env = {}) {
+  const win = env.window ?? globalThis;
+  const doc = env.document ?? win.document;
+  if (!doc) {
+    return Promise.reject(
+      new Error("Inline checkout requires a browser DOM (no document available).")
+    );
+  }
+  if (win.RmPaymentEngine) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const script = doc.createElement("script");
+    script.src = scriptUrl;
+    script.async = true;
+    script.onload = () => resolve();
+    script.onerror = () => reject(new Error(`Failed to load Remita checkout script: ${scriptUrl}`));
+    doc.head?.appendChild(script);
+  });
+}
+function getRmPaymentEngine(env = {}) {
+  const win = env.window ?? globalThis;
+  return win.RmPaymentEngine;
+}
+
+// src/http-client.ts
 var HttpClient = class {
   constructor(options) {
     this.baseUrl = options.baseUrl.replace(/\/+$/, "");
@@ -191,15 +225,51 @@ var CheckoutCoreClient = class {
   }
 };
 var MerchantCheckoutClient = class extends CheckoutCoreClient {
+  constructor(options) {
+    super(options);
+    this.scriptLoaded = false;
+    this.scriptUrl = getInlineCheckoutScriptUrl(
+      this.environment,
+      options.scriptUrl
+    );
+    this.inlineEnvironment = options.inlineEnvironment ?? {};
+  }
   /**
-   * Merchant checkout clients are intentionally narrow. They focus on the public
-   * payment flow rather than the full platform lifecycle used by PSPs.
+   * Merchant checkout mirrors Remita's hosted inline flow: load
+   * `payment-checkout.js`, then drive the global `RmPaymentEngine`.
    */
-  createCheckoutSession(request) {
-    return this.http.request("POST", "/payment/initiate", { body: request });
+  async load() {
+    if (this.scriptLoaded) return;
+    await loadInlineCheckoutScript(this.scriptUrl, this.inlineEnvironment);
+    this.scriptLoaded = true;
+  }
+  engine() {
+    const engine = getRmPaymentEngine(this.inlineEnvironment);
+    if (!engine) {
+      throw new Error(
+        "RmPaymentEngine is not available. Call load() before creating a checkout session."
+      );
+    }
+    return engine;
+  }
+  /**
+   * Mirrors `RmPaymentEngine.init(...)`. The returned engine's `openIframe()`
+   * opens the hosted checkout. The public key is injected automatically.
+   */
+  async init(options = {}) {
+    await this.load();
+    return this.engine().init({ key: this.publicKey, ...options });
+  }
+  async createCheckoutSession(options = {}) {
+    return this.init(options);
+  }
+  async createSession(options = {}) {
+    return this.init(options);
   }
-  createSession(request) {
-    return this.createCheckoutSession(request);
+  /** Mirrors `RmPaymentEngine.processRRR(...)` for RRR-based payments. */
+  async processRRR(options) {
+    await this.load();
+    return this.engine().processRRR({ key: this.publicKey, ...options });
   }
 };
 var RemitaPlatformClient = class extends CheckoutCoreClient {
@@ -257,12 +327,17 @@ var RemitaCheckoutClient = class extends RemitaPlatformClient {
 
 export {
   __require,
+  RemitaApiError,
   ENVIRONMENT_BASE_URLS,
   resolveEnvironment,
   openStatusStream,
+  INLINE_CHECKOUT_SCRIPT_URLS,
+  getInlineCheckoutScriptUrl,
+  loadInlineCheckoutScript,
+  getRmPaymentEngine,
   CheckoutCoreClient,
   MerchantCheckoutClient,
   RemitaPlatformClient,
   RemitaCheckoutClient
 };
-//# sourceMappingURL=chunk-RLUJCMLB.mjs.map
+//# sourceMappingURL=chunk-O2KJGHVA.mjs.map