remita-checkout-client 0.1.0 → 0.1.1

package/README.md

@@ -3,6 +3,117 @@
 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`).
 
+## Two product surfaces
+
+This package is built around two user types:
+
+### Merchant checkout
+
+Use this when you are a business or storefront that only wants to accept payment
+for a sale.
+
+Typical needs:
+
+- create a checkout session
+- redirect or embed the payment flow
+- verify payment completion
+- update order status
+
+Recommended client:
+
+- `MerchantCheckoutClient`
+
+### PSP / platform
+
+Use this when you are a payment facilitator, gateway, or platform operator that
+needs the full Remita lifecycle.
+
+Typical needs:
+
+- pre-payment flows
+- fee calculation
+- payment initiation
+- authorization and validation
+- status verification
+- channel lookup and platform configuration
+
+Recommended client:
+
+- `RemitaPlatformClient`
+
+### Compatibility
+
+`RemitaCheckoutClient` remains available as a backwards-compatible alias of the
+platform client for older integrations, but the preferred split is:
+
+- `MerchantCheckoutClient` for checkout-only usage
+- `RemitaPlatformClient` for PSP/platform usage
+
+---
+
+## Quick example: merchant checkout
+
+```ts
+import { MerchantCheckoutClient } from "remita-checkout-client";
+
+const checkout = new MerchantCheckoutClient({
+  publicKey: "MERCHANT_PUBLIC_KEY",
+  environment: "production",
+});
+
+const session = await checkout.createCheckoutSession({
+  amount: 25000,
+  paymentIdentifier: "TRANSACTION_REF_123",
+  narration: "Order 123",
+  paymentChannel: "CARD",
+  metaData: {},
+  merchantInformation: {},
+});
+
+const verified = await checkout.verifyPayment("PAYMENT_REF_123");
+console.log(verified.status);
+```
+
+---
+
+## Quick example: PSP / platform flow
+
+```ts
+import { RemitaPlatformClient } from "remita-checkout-client";
+
+const remita = new RemitaPlatformClient({
+  publicKey: "PSP_PUBLIC_KEY",
+  environment: "production",
+});
+
+const pre = await remita.prePayment({
+  firstName: "Test",
+  lastName: "User",
+  email: "test@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",
+});
+
+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
@@ -46,9 +157,23 @@ const client = new RemitaCheckoutClient({
     console.warn(`Couldn't detect environment from key prefix, defaulting to ${guessed}`),
 });
 
-const pre = await client.prePayment({ publicKey: client.publicKey, rrr: "RRR12345" });
+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 initiated = await client.initiatePayment({ 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",
+});
 
 if (initiated.actionUrl) {
   await client.authorize(initiated.actionUrl, { /* OTP / PIN / 3DS fields */ });
@@ -66,9 +191,23 @@ 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.pre({
+  firstName: "Test",
+  lastName: "User",
+  email: "test@example.com",
+  phoneNumber: "08000000000",
+  paymentIdentifier: "ORDER-123",
+  currency: "NGN",
+  amount: 5000,
+});
 await session.fee({ publicKey: client.publicKey, amount: 5000, channel: "card" });
-await session.initiate({ publicKey: client.publicKey, amount: 5000, 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",
+});
 
 // actionUrl from initiate() is remembered automatically
 await session.authorize({ otp: "123456" });

package/dist/chunk-RLUJCMLB.mjs

@@ -0,0 +1,268 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/environment.ts
+var 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"
+};
+var PREFIX_RULES = [
+  { pattern: /^(qa[-_]|pk_qa_)/i, environment: "qa" },
+  { pattern: /^(demo[-_]|pk_demo_|pk_test_)/i, environment: "demo" }
+];
+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 };
+}
+
+// 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()
+  };
+}
+
+// src/http-client.ts
+var RemitaApiError = class extends Error {
+  constructor(message, status, payload) {
+    super(message);
+    this.status = status;
+    this.payload = payload;
+    this.name = "RemitaApiError";
+  }
+};
+var 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",
+      ...opts.omitDefaultHeaders ? {} : 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 CheckoutCoreClient = 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: options.publicKey,
+        ...options.defaultHeaders
+      }
+    });
+  }
+  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);
+  }
+};
+var MerchantCheckoutClient = class extends CheckoutCoreClient {
+  /**
+   * Merchant checkout clients are intentionally narrow. They focus on the public
+   * payment flow rather than the full platform lifecycle used by PSPs.
+   */
+  createCheckoutSession(request) {
+    return this.http.request("POST", "/payment/initiate", { body: request });
+  }
+  createSession(request) {
+    return this.createCheckoutSession(request);
+  }
+};
+var RemitaPlatformClient = class extends CheckoutCoreClient {
+  // --- 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().
+   *
+  * Authorization URLs are external processor endpoints, so the Remita
+  * public-key header is not forwarded. Pass form content type for processors
+  * that require URL-encoded authorization fields.
+   */
+  authorize(actionUrl, payload, contentType) {
+    return this.http.request("POST", "", {
+      body: payload,
+      absoluteUrl: actionUrl,
+      omitDefaultHeaders: true,
+      contentType
+    });
+  }
+  /**
+   * 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,
+      omitDefaultHeaders: true
+    }) : this.http.request("POST", "/payment/validate", { body: request });
+  }
+  // --- 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");
+  }
+};
+var RemitaCheckoutClient = class extends RemitaPlatformClient {
+};
+
+export {
+  __require,
+  ENVIRONMENT_BASE_URLS,
+  resolveEnvironment,
+  openStatusStream,
+  CheckoutCoreClient,
+  MerchantCheckoutClient,
+  RemitaPlatformClient,
+  RemitaCheckoutClient
+};
+//# sourceMappingURL=chunk-RLUJCMLB.mjs.map

package/dist/chunk-RLUJCMLB.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  omitDefaultHeaders?: boolean;\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      ...(opts.omitDefaultHeaders ? {} : 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  PaymentInitiationRequest,\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 CheckoutCoreClient {\n  readonly publicKey: string;\n  readonly environment: string;\n  readonly baseUrl: string;\n  protected 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: options.publicKey,\n        ...options.defaultHeaders,\n      },\n    });\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\nexport class MerchantCheckoutClient extends CheckoutCoreClient {\n  /**\n   * Merchant checkout clients are intentionally narrow. They focus on the public\n   * payment flow rather than the full platform lifecycle used by PSPs.\n   */\n  createCheckoutSession(request: PaymentInitiationRequest): Promise<Record<string, unknown>> {\n    return this.http.request(\"POST\", \"/payment/initiate\", { body: request });\n  }\n\n  createSession(request: PaymentInitiationRequest): Promise<Record<string, unknown>> {\n    return this.createCheckoutSession(request);\n  }\n}\n\nexport class RemitaPlatformClient extends CheckoutCoreClient {\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  * Authorization URLs are external processor endpoints, so the Remita\n  * public-key header is not forwarded. Pass form content type for processors\n  * that require URL-encoded authorization fields.\n   */\n  authorize(\n    actionUrl: string,\n    payload: AuthorizePayload,\n    contentType?: string\n  ): Promise<AuthorizeResponse> {\n    return this.http.request(\"POST\", \"\", {\n      body: payload,\n      absoluteUrl: actionUrl,\n      omitDefaultHeaders: true,\n      contentType,\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\", \"\", {\n          body: request,\n          absoluteUrl: actionUrl,\n          omitDefaultHeaders: true,\n        })\n      : this.http.request(\"POST\", \"/payment/validate\", { body: request });\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}\n\nexport class RemitaCheckoutClient extends RemitaPlatformClient {}\n"],"mappings":"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","names":[]}

package/dist/cli.d.mts

@@ -1 +1,12 @@
 #!/usr/bin/env node
+type WritableLike = {
+    write: (text: string) => void;
+};
+type CliDeps = {
+    stdout?: WritableLike;
+    stderr?: WritableLike;
+    fetch?: typeof fetch;
+};
+declare function runCli(argv: string[], deps?: CliDeps): Promise<number>;
+
+export { runCli };

package/dist/cli.d.ts

@@ -1 +1,12 @@
 #!/usr/bin/env node
+type WritableLike = {
+    write: (text: string) => void;
+};
+type CliDeps = {
+    stdout?: WritableLike;
+    stderr?: WritableLike;
+    fetch?: typeof fetch;
+};
+declare function runCli(argv: string[], deps?: CliDeps): Promise<number>;
+
+export { runCli };