remita-checkout-client 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# 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`).
+
+## ⚠️ 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({ 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" });
+
+if (initiated.actionUrl) {
+  await client.authorize(initiated.actionUrl, { /* OTP / PIN / 3DS fields */ });
+}
+
+const verified = await client.verifyPayment(initiated.paymentReference!);
+console.log(verified.status); // "APPROVED" | "PENDING" | "FAILED" | ...
+```
+
+### Higher-level session (tracks refs between steps for you)
+
+```ts
+import { RemitaCheckoutClient, PaymentSession } from "remita-checkout-client";
+
+const client = new RemitaCheckoutClient({ 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" });
+
+// 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()
+console.log(session.stage, result.status);
+```
+
+### Real-time status via SSE
+
+```ts
+const handle = client.streamPaymentStatus(trxRef, {
+  onOpen: () => console.log("stream open"),
+  onMessage: (event) => console.log("status update:", event.data),
+  onError: (err) => console.error("stream error:", err),
+});
+
+// later
+handle.close();
+```
+
+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
+
+```ts
+const banks = await client.getBankList();
+const ussdCodes = await client.getUssdCodes();
+const wallets = await client.getWalletTypes();
+```
+
+## Node < 18
+
+Global `fetch` isn't available before Node 18. Pass a `fetchImpl` explicitly:
+
+```ts
+import fetch from "node-fetch";
+
+const client = new RemitaCheckoutClient({
+  publicKey: "...",
+  environment: "qa",
+  fetchImpl: fetch as unknown as typeof globalThis.fetch,
+});
+```
+
+## Not covered in this version
+
+Per the agreed v1 scope, this does **not** include:
+
+- Google Pay / Apple Pay config endpoints (`/misc/googlepay`, `/misc/applepay`)
+- CyberSource / Cardinal 3DS flow (Cruise Collect iframe, Centinel API, the
+  return listener endpoint)
+
+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.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run build   # outputs dist/ as CJS + ESM + .d.ts
+```

package/dist/chunk-MGQQHIIZ.mjs

@@ -0,0 +1,275 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+// src/environment.ts
+function resolveEnvironment(publicKey, options = {}) {
+  const baseUrls = { ...ENVIRONMENT_BASE_URLS, ...options.baseUrls };
+  if (options.environment) {
+    return {
+      environment: options.environment,
+      baseUrl: baseUrls[options.environment],
+      detected: true
+    };
+  }
+  for (const rule of PREFIX_RULES) {
+    if (rule.pattern.test(publicKey)) {
+      return {
+        environment: rule.environment,
+        baseUrl: baseUrls[rule.environment],
+        detected: true
+      };
+    }
+  }
+  return { environment: "qa", baseUrl: baseUrls.qa, detected: false };
+}
+var ENVIRONMENT_BASE_URLS, PREFIX_RULES;
+var init_environment = __esm({
+  "src/environment.ts"() {
+    "use strict";
+    ENVIRONMENT_BASE_URLS = {
+      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"
+    };
+    PREFIX_RULES = [
+      { pattern: /^(qa[-_]|pk_qa_)/i, environment: "qa" },
+      { pattern: /^(demo[-_]|pk_demo_|pk_test_)/i, environment: "demo" }
+    ];
+  }
+});
+
+// src/stream.ts
+function openStatusStream(baseUrl, trxRef, publicKey, options) {
+  const fetchImpl = options.fetchImpl ?? (typeof fetch !== "undefined" ? fetch : void 0);
+  if (!fetchImpl) {
+    throw new Error("No fetch implementation available for streamPaymentStatus.");
+  }
+  const url = `${baseUrl.replace(/\/+$/, "")}/payment/status/stream/${encodeURIComponent(
+    trxRef
+  )}?publicKey=${encodeURIComponent(publicKey)}`;
+  const headers = { Accept: "text/event-stream" };
+  if (options.sendPublicKeyHeader) {
+    headers.publicKey = publicKey;
+  }
+  const controller = new AbortController();
+  (async () => {
+    try {
+      const response = await fetchImpl(url, {
+        headers,
+        signal: controller.signal
+      });
+      if (!response.ok || !response.body) {
+        throw new Error(`Status stream request failed with status ${response.status}`);
+      }
+      options.onOpen?.();
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const events = buffer.split("\n\n");
+        buffer = events.pop() ?? "";
+        for (const rawEvent of events) {
+          const dataLines = rawEvent.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim());
+          if (dataLines.length === 0) continue;
+          const raw = dataLines.join("\n");
+          let data = raw;
+          try {
+            data = JSON.parse(raw);
+          } catch {
+          }
+          options.onMessage({ data, raw });
+        }
+      }
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") return;
+      options.onError?.(err);
+    }
+  })();
+  return {
+    close: () => controller.abort()
+  };
+}
+var init_stream = __esm({
+  "src/stream.ts"() {
+    "use strict";
+  }
+});
+
+// src/http-client.ts
+var RemitaApiError, HttpClient;
+var init_http_client = __esm({
+  "src/http-client.ts"() {
+    "use strict";
+    RemitaApiError = class extends Error {
+      constructor(message, status, payload) {
+        super(message);
+        this.status = status;
+        this.payload = payload;
+        this.name = "RemitaApiError";
+      }
+    };
+    HttpClient = class {
+      constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.fetchImpl = options.fetchImpl ?? (typeof fetch !== "undefined" ? fetch : void 0);
+        this.timeoutMs = options.timeoutMs ?? 3e4;
+        this.defaultHeaders = options.defaultHeaders ?? {};
+        if (!this.fetchImpl) {
+          throw new Error("No fetch implementation available for HttpClient.");
+        }
+      }
+      async request(method, path, opts = {}) {
+        const url = opts.absoluteUrl ? opts.absoluteUrl : `${this.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
+        const headers = {
+          Accept: "application/json",
+          ...this.defaultHeaders,
+          ...opts.headers
+        };
+        let body;
+        if (opts.body !== void 0) {
+          if (opts.contentType === "application/x-www-form-urlencoded") {
+            headers["Content-Type"] = opts.contentType;
+            body = new URLSearchParams(
+              Object.entries(opts.body).map(([k, v]) => [
+                k,
+                String(v)
+              ])
+            ).toString();
+          } else {
+            headers["Content-Type"] = opts.contentType ?? "application/json";
+            body = JSON.stringify(opts.body);
+          }
+        }
+        const controller = new AbortController();
+        const timer = this.timeoutMs > 0 ? setTimeout(() => controller.abort(), this.timeoutMs) : void 0;
+        try {
+          const response = await this.fetchImpl(url, {
+            method,
+            headers,
+            body,
+            signal: controller.signal
+          });
+          const text = await response.text();
+          let parsed = text;
+          try {
+            parsed = text ? JSON.parse(text) : void 0;
+          } catch {
+          }
+          if (!response.ok) {
+            const payload = parsed ?? {};
+            const message = payload.responseMessage ?? payload.message ?? `Request failed with status ${response.status}`;
+            throw new RemitaApiError(message, response.status, payload);
+          }
+          return parsed;
+        } finally {
+          if (timer) clearTimeout(timer);
+        }
+      }
+    };
+  }
+});
+
+// src/client.ts
+var RemitaCheckoutClient;
+var init_client = __esm({
+  "src/client.ts"() {
+    "use strict";
+    init_http_client();
+    init_environment();
+    init_stream();
+    RemitaCheckoutClient = class {
+      constructor(options) {
+        this.publicKey = options.publicKey;
+        const resolved = resolveEnvironment(options.publicKey, {
+          environment: options.environment,
+          baseUrls: options.baseUrls
+        });
+        if (!resolved.detected) {
+          options.onEnvironmentDetectionFallback?.("qa");
+        }
+        this.environment = resolved.environment;
+        this.baseUrl = resolved.baseUrl;
+        this.http = new HttpClient({
+          baseUrl: resolved.baseUrl,
+          fetchImpl: options.fetchImpl,
+          timeoutMs: options.timeoutMs,
+          defaultHeaders: {
+            // publicKey is required as a header on every checkout API call.
+            publicKey: options.publicKey,
+            ...options.defaultHeaders
+          }
+        });
+      }
+      // --- Core payment lifecycle ---------------------------------------------
+      prePayment(request) {
+        return this.http.request("POST", "/payment/pre", { body: request });
+      }
+      calculateFee(request) {
+        return this.http.request("POST", "/payment/pre/feeCharge", { body: request });
+      }
+      initiatePayment(request) {
+        return this.http.request("POST", "/payment/initiate", { body: request });
+      }
+      /**
+       * Posts authorization params (OTP, PIN, 3DS form fields, etc) to the
+       * processor-provided actionUrl from initiatePayment().
+       *
+       * NOTE: CyberSource/Cardinal 3DS endpoints expect
+       * `application/x-www-form-urlencoded`. Pass `contentType` if the
+       * actionUrl is a 3DS processor endpoint.
+       */
+      authorize(actionUrl, payload, contentType) {
+        void contentType;
+        return this.http.request("POST", "", {
+          body: payload,
+          absoluteUrl: actionUrl
+        });
+      }
+      /**
+       * Validates second-factor authorization (e.g. OTP). Per the endpoint docs
+       * this may go to a fixed /payment/validate endpoint OR to a dynamic
+       * actionUrl — pass `actionUrl` if the preceding step returned one.
+       */
+      validatePayment(request, actionUrl) {
+        return actionUrl ? this.http.request("POST", "", { body: request, absoluteUrl: actionUrl }) : this.http.request("POST", "/payment/validate", { body: request });
+      }
+      verifyPayment(paymentRef) {
+        return this.http.request("GET", `/payment/verify/${encodeURIComponent(paymentRef)}`);
+      }
+      /** Opens an SSE stream for real-time status updates. Call the returned `close()` when done. */
+      streamPaymentStatus(trxRef, options) {
+        return openStatusStream(this.baseUrl, trxRef, this.publicKey, options);
+      }
+      // --- Channel data / configuration ---------------------------------------
+      getBankList() {
+        return this.http.request("GET", "/payment/bank-list");
+      }
+      getUssdCodes() {
+        return this.http.request("GET", "/misc/ussd-codes");
+      }
+      getWalletTypes() {
+        return this.http.request("GET", "/misc/wallet-type");
+      }
+    };
+  }
+});
+
+export {
+  __commonJS,
+  ENVIRONMENT_BASE_URLS,
+  resolveEnvironment,
+  init_environment,
+  openStatusStream,
+  init_stream,
+  RemitaCheckoutClient,
+  init_client
+};
+//# sourceMappingURL=chunk-MGQQHIIZ.mjs.map

package/dist/chunk-MGQQHIIZ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/environment.ts","../src/stream.ts","../src/http-client.ts","../src/client.ts"],"sourcesContent":["export type RemitaEnvironment = \"qa\" | \"demo\" | \"production\";\n\nexport const ENVIRONMENT_BASE_URLS: Record<RemitaEnvironment, string> = {\n  qa: \"https://api-checkout-qa.systemspecsng.com/api/v1\",\n  demo: \"https://api-checkout-demo.systemspecsng.com/api/v1\",\n  production: \"https://api-checkout.systemspecsng.com/api/v1\",\n};\n\n/**\n * Best-effort prefix-based environment detection from a public key.\n *\n * IMPORTANT: `pk_live_` is deliberately NOT mapped here. Remita's real key\n * format has not been verified, and silently routing a key to production\n * is worse than failing loudly. Callers who want production MUST pass\n * `environment: \"production\"` (or `--env production` on the CLI) explicitly.\n */\nconst PREFIX_RULES: Array<{ pattern: RegExp; environment: RemitaEnvironment }> = [\n  { pattern: /^(qa[-_]|pk_qa_)/i, environment: \"qa\" },\n  { pattern: /^(demo[-_]|pk_demo_|pk_test_)/i, environment: \"demo\" },\n];\n\nexport interface ResolveEnvironmentOptions {\n  /** Explicit override — always wins over prefix detection. */\n  environment?: RemitaEnvironment;\n  /** Custom base URLs, e.g. to point at a local/staging mirror. */\n  baseUrls?: Partial<Record<RemitaEnvironment, string>>;\n}\n\nexport interface ResolvedEnvironment {\n  environment: RemitaEnvironment;\n  baseUrl: string;\n  /** False when detection couldn't confidently match a prefix and we fell back to a default. */\n  detected: boolean;\n}\n\nexport function resolveEnvironment(\n  publicKey: string,\n  options: ResolveEnvironmentOptions = {}\n): ResolvedEnvironment {\n  const baseUrls = { ...ENVIRONMENT_BASE_URLS, ...options.baseUrls };\n\n  if (options.environment) {\n    return {\n      environment: options.environment,\n      baseUrl: baseUrls[options.environment],\n      detected: true,\n    };\n  }\n\n  for (const rule of PREFIX_RULES) {\n    if (rule.pattern.test(publicKey)) {\n      return {\n        environment: rule.environment,\n        baseUrl: baseUrls[rule.environment],\n        detected: true,\n      };\n    }\n  }\n\n  return { environment: \"qa\", baseUrl: baseUrls.qa, detected: false };\n}","export interface StatusStreamOptions {\n  onMessage: (event: { data: unknown; raw: string }) => void;\n  onError?: (err: unknown) => void;\n  onOpen?: () => void;\n  fetchImpl?: typeof fetch;\n  /** Optional override; publicKey is sent as a query param by default. */\n  sendPublicKeyHeader?: boolean;\n}\n\nexport interface StatusStreamHandle {\n  close: () => void;\n}\n\n/**\n * Opens the payment status SSE stream using a manual fetch + ReadableStream\n * reader rather than the browser-only `EventSource` global, so this works\n * identically in the browser and in Node 18+.\n */\nexport function openStatusStream(\n  baseUrl: string,\n  trxRef: string,\n  publicKey: string,\n  options: StatusStreamOptions\n): StatusStreamHandle {\n  const fetchImpl =\n    options.fetchImpl ?? (typeof fetch !== \"undefined\" ? fetch : undefined);\n  if (!fetchImpl) {\n    throw new Error(\"No fetch implementation available for streamPaymentStatus.\");\n  }\n\n  const url = `${baseUrl.replace(/\\/+$/, \"\")}/payment/status/stream/${encodeURIComponent(\n    trxRef\n  )}?publicKey=${encodeURIComponent(publicKey)}`;\n\n  const headers: Record<string, string> = { Accept: \"text/event-stream\" };\n  if (options.sendPublicKeyHeader) {\n    headers.publicKey = publicKey;\n  }\n\n  const controller = new AbortController();\n\n  (async () => {\n    try {\n      const response = await fetchImpl(url, {\n        headers,\n        signal: controller.signal,\n      });\n\n      if (!response.ok || !response.body) {\n        throw new Error(`Status stream request failed with status ${response.status}`);\n      }\n\n      options.onOpen?.();\n\n      const reader = response.body.getReader();\n      const decoder = new TextDecoder();\n      let buffer = \"\";\n\n      // eslint-disable-next-line no-constant-condition\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const events = buffer.split(\"\\n\\n\");\n        buffer = events.pop() ?? \"\";\n\n        for (const rawEvent of events) {\n          const dataLines = rawEvent\n            .split(\"\\n\")\n            .filter((line) => line.startsWith(\"data:\"))\n            .map((line) => line.slice(5).trim());\n\n          if (dataLines.length === 0) continue;\n\n          const raw = dataLines.join(\"\\n\");\n          let data: unknown = raw;\n          try {\n            data = JSON.parse(raw);\n          } catch {\n            // not JSON — leave as the raw string\n          }\n\n          options.onMessage({ data, raw });\n        }\n      }\n    } catch (err) {\n      if (err instanceof Error && err.name === \"AbortError\") return;\n      options.onError?.(err);\n    }\n  })();\n\n  return {\n    close: () => controller.abort(),\n  };\n}","export interface HttpRequestOptions {\n  body?: unknown;\n  headers?: Record<string, string>;\n  absoluteUrl?: string;\n  /** Overrides the default application/json for a single request. */\n  contentType?: string;\n}\n\nexport interface HttpClientOptions {\n  baseUrl: string;\n  fetchImpl?: typeof fetch;\n  timeoutMs?: number;\n  defaultHeaders?: Record<string, string>;\n}\n\nexport interface ApiErrorPayload {\n  responseMessage?: string;\n  message?: string;\n  [key: string]: unknown;\n}\n\nexport class RemitaApiError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly payload: ApiErrorPayload\n  ) {\n    super(message);\n    this.name = \"RemitaApiError\";\n  }\n}\n\nexport class HttpClient {\n  private readonly baseUrl: string;\n  private readonly fetchImpl: typeof fetch;\n  private readonly timeoutMs: number;\n  private readonly defaultHeaders: Record<string, string>;\n\n  constructor(options: HttpClientOptions) {\n    this.baseUrl = options.baseUrl.replace(/\\/+$/, \"\");\n    this.fetchImpl =\n      options.fetchImpl ?? (typeof fetch !== \"undefined\" ? fetch : (undefined as never));\n    this.timeoutMs = options.timeoutMs ?? 30_000;\n    this.defaultHeaders = options.defaultHeaders ?? {};\n\n    if (!this.fetchImpl) {\n      throw new Error(\"No fetch implementation available for HttpClient.\");\n    }\n  }\n\n  async request<T>(\n    method: string,\n    path: string,\n    opts: HttpRequestOptions = {}\n  ): Promise<T> {\n    // --- L6 fix: join WITHOUT dropping /api/v1 ---\n    // path is expected to start with \"/\" and the baseUrl already ends with\n    // \"/api/v1\", so plain concatenation is correct. Do NOT use `new URL(path, base)`.\n    const url = opts.absoluteUrl\n      ? opts.absoluteUrl\n      : `${this.baseUrl}${path.startsWith(\"/\") ? \"\" : \"/\"}${path}`;\n\n    const headers: Record<string, string> = {\n      Accept: \"application/json\",\n      ...this.defaultHeaders,\n      ...opts.headers,\n    };\n\n    let body: BodyInit | undefined;\n    if (opts.body !== undefined) {\n      if (opts.contentType === \"application/x-www-form-urlencoded\") {\n        headers[\"Content-Type\"] = opts.contentType;\n        body = new URLSearchParams(\n          Object.entries(opts.body as Record<string, unknown>).map(([k, v]) => [\n            k,\n            String(v),\n          ])\n        ).toString();\n      } else {\n        headers[\"Content-Type\"] = opts.contentType ?? \"application/json\";\n        body = JSON.stringify(opts.body);\n      }\n    }\n\n    const controller = new AbortController();\n    const timer =\n      this.timeoutMs > 0 ? setTimeout(() => controller.abort(), this.timeoutMs) : undefined;\n\n    try {\n      const response = await this.fetchImpl(url, {\n        method,\n        headers,\n        body,\n        signal: controller.signal,\n      });\n\n      const text = await response.text();\n      let parsed: unknown = text;\n      try {\n        parsed = text ? JSON.parse(text) : undefined;\n      } catch {\n        // leave as raw string\n      }\n\n      if (!response.ok) {\n        const payload = (parsed ?? {}) as ApiErrorPayload;\n        const message =\n          payload.responseMessage ??\n          payload.message ??\n          `Request failed with status ${response.status}`;\n        throw new RemitaApiError(message, response.status, payload);\n      }\n\n      return parsed as T;\n    } finally {\n      if (timer) clearTimeout(timer);\n    }\n  }\n}","import { HttpClient } from \"./http-client\";\nimport { resolveEnvironment } from \"./environment\";\nimport type { ResolveEnvironmentOptions } from \"./environment\";\nimport type {\n  PrePaymentRequest,\n  PrePaymentResponse,\n  FeeChargeRequest,\n  FeeChargeResponse,\n  InitiatePaymentRequest,\n  InitiatePaymentResponse,\n  AuthorizePayload,\n  AuthorizeResponse,\n  ValidatePaymentRequest,\n  ValidatePaymentResponse,\n  VerifyPaymentResponse,\n  BankListResponse,\n  UssdCodesResponse,\n  WalletTypesResponse,\n} from \"./types\";\nimport { openStatusStream } from \"./stream\";\nimport type { StatusStreamHandle, StatusStreamOptions } from \"./stream\";\n\nexport interface RemitaCheckoutClientOptions extends ResolveEnvironmentOptions {\n  publicKey: string;\n  fetchImpl?: typeof fetch;\n  timeoutMs?: number;\n  /** Extra headers merged after `publicKey` is set (so they can override). */\n  defaultHeaders?: Record<string, string>;\n  /** Called once if the environment couldn't be confidently detected from the key prefix (falls back to \"qa\"). */\n  onEnvironmentDetectionFallback?: (guessed: \"qa\") => void;\n}\n\nexport class RemitaCheckoutClient {\n  readonly publicKey: string;\n  readonly environment: string;\n  readonly baseUrl: string;\n  private readonly http: HttpClient;\n\n  constructor(options: RemitaCheckoutClientOptions) {\n    this.publicKey = options.publicKey;\n\n    const resolved = resolveEnvironment(options.publicKey, {\n      environment: options.environment,\n      baseUrls: options.baseUrls,\n    });\n\n    if (!resolved.detected) {\n      options.onEnvironmentDetectionFallback?.(\"qa\");\n    }\n\n    this.environment = resolved.environment;\n    this.baseUrl = resolved.baseUrl;\n\n    this.http = new HttpClient({\n      baseUrl: resolved.baseUrl,\n      fetchImpl: options.fetchImpl,\n      timeoutMs: options.timeoutMs,\n      defaultHeaders: {\n        // publicKey is required as a header on every checkout API call.\n        publicKey: options.publicKey,\n        ...options.defaultHeaders,\n      },\n    });\n  }\n\n  // --- Core payment lifecycle ---------------------------------------------\n\n  prePayment(request: PrePaymentRequest): Promise<PrePaymentResponse> {\n    return this.http.request(\"POST\", \"/payment/pre\", { body: request });\n  }\n\n  calculateFee(request: FeeChargeRequest): Promise<FeeChargeResponse> {\n    return this.http.request(\"POST\", \"/payment/pre/feeCharge\", { body: request });\n  }\n\n  initiatePayment(request: InitiatePaymentRequest): Promise<InitiatePaymentResponse> {\n    return this.http.request(\"POST\", \"/payment/initiate\", { body: request });\n  }\n\n  /**\n   * Posts authorization params (OTP, PIN, 3DS form fields, etc) to the\n   * processor-provided actionUrl from initiatePayment().\n   *\n   * NOTE: CyberSource/Cardinal 3DS endpoints expect\n   * `application/x-www-form-urlencoded`. Pass `contentType` if the\n   * actionUrl is a 3DS processor endpoint.\n   */\n  authorize(\n    actionUrl: string,\n    payload: AuthorizePayload,\n    contentType?: string\n  ): Promise<AuthorizeResponse> {\n    void contentType;\n    return this.http.request(\"POST\", \"\", {\n      body: payload,\n      absoluteUrl: actionUrl,\n    });\n  }\n\n  /**\n   * Validates second-factor authorization (e.g. OTP). Per the endpoint docs\n   * this may go to a fixed /payment/validate endpoint OR to a dynamic\n   * actionUrl — pass `actionUrl` if the preceding step returned one.\n   */\n  validatePayment(\n    request: ValidatePaymentRequest,\n    actionUrl?: string\n  ): Promise<ValidatePaymentResponse> {\n    return actionUrl\n      ? this.http.request(\"POST\", \"\", { body: request, absoluteUrl: actionUrl })\n      : this.http.request(\"POST\", \"/payment/validate\", { body: request });\n  }\n\n  verifyPayment(paymentRef: string): Promise<VerifyPaymentResponse> {\n    return this.http.request(\"GET\", `/payment/verify/${encodeURIComponent(paymentRef)}`);\n  }\n\n  /** Opens an SSE stream for real-time status updates. Call the returned `close()` when done. */\n  streamPaymentStatus(trxRef: string, options: StatusStreamOptions): StatusStreamHandle {\n    return openStatusStream(this.baseUrl, trxRef, this.publicKey, options);\n  }\n\n  // --- Channel data / configuration ---------------------------------------\n\n  getBankList(): Promise<BankListResponse> {\n    return this.http.request(\"GET\", \"/payment/bank-list\");\n  }\n\n  getUssdCodes(): Promise<UssdCodesResponse> {\n    return this.http.request(\"GET\", \"/misc/ussd-codes\");\n  }\n\n  getWalletTypes(): Promise<WalletTypesResponse> {\n    return this.http.request(\"GET\", \"/misc/wallet-type\");\n  }\n}"],"mappings":"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","names":[]}

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node