remita-checkout-client 0.1.0

package/dist/index.mjs

@@ -0,0 +1,102 @@
+import {
+  ENVIRONMENT_BASE_URLS,
+  RemitaCheckoutClient,
+  init_client,
+  init_environment,
+  init_stream,
+  openStatusStream,
+  resolveEnvironment
+} from "./chunk-MGQQHIIZ.mjs";
+
+// src/index.ts
+init_client();
+
+// src/session.ts
+var PaymentSession = class {
+  constructor(client) {
+    this.client = client;
+    this.stage = "idle";
+  }
+  async pre(request) {
+    const response = await this.client.prePayment(request);
+    this.transactionId = response.transactionId ?? this.transactionId;
+    this.paymentReference = response.paymentReference ?? this.paymentReference;
+    this.stage = "pre";
+    return response;
+  }
+  async fee(request) {
+    const response = await this.client.calculateFee(request);
+    this.stage = "fee";
+    return response;
+  }
+  async initiate(request) {
+    const response = await this.client.initiatePayment(request);
+    this.authorizeActionUrl = response.actionUrl;
+    this.validateActionUrl = void 0;
+    this.paymentReference = response.paymentReference ?? this.paymentReference;
+    this.transactionId = response.transactionId ?? this.transactionId;
+    this.stage = "initiated";
+    return response;
+  }
+  /**
+   * Uses the actionUrl captured from initiate() unless you pass one explicitly.
+   * Pass `contentType` for 3DS processor endpoints that require form-encoding.
+   */
+  async authorize(payload, actionUrlOverride, contentType) {
+    const url = actionUrlOverride ?? this.authorizeActionUrl;
+    if (!url) {
+      throw new Error(
+        "No actionUrl available \u2014 call initiate() first, or pass actionUrlOverride explicitly."
+      );
+    }
+    const response = await this.client.authorize(url, payload, contentType);
+    const next = response.actionUrl;
+    if (next) this.validateActionUrl = next;
+    this.stage = "authorized";
+    return response;
+  }
+  async validate(request, actionUrlOverride) {
+    const url = actionUrlOverride ?? this.validateActionUrl;
+    const response = await this.client.validatePayment(request, url);
+    this.stage = "validated";
+    return response;
+  }
+  async verify(paymentRefOverride) {
+    const ref = paymentRefOverride ?? this.paymentReference ?? this.transactionId;
+    if (!ref) {
+      throw new Error(
+        "No paymentReference or transactionId available \u2014 call initiate() first, or pass it explicitly."
+      );
+    }
+    const response = await this.client.verifyPayment(ref);
+    if (response.status === "APPROVED") {
+      this.stage = "verified";
+    } else if (response.status === "FAILED") {
+      this.stage = "failed";
+    }
+    return response;
+  }
+};
+
+// src/index.ts
+init_environment();
+init_stream();
+
+// src/types.ts
+var RemitaApiError = class extends Error {
+  constructor(message, status, payload) {
+    super(message);
+    this.name = "RemitaApiError";
+    this.status = status;
+    this.payload = payload;
+  }
+};
+export {
+  ENVIRONMENT_BASE_URLS,
+  PaymentSession,
+  RemitaApiError,
+  RemitaCheckoutClient,
+  openStatusStream,
+  resolveEnvironment
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/session.ts","../src/types.ts"],"sourcesContent":["export { RemitaCheckoutClient } from \"./client\";\nexport type { RemitaCheckoutClientOptions } from \"./client\";\n\nexport { PaymentSession } from \"./session\";\nexport type { PaymentSessionStage } from \"./session\";\n\nexport {\n  resolveEnvironment,\n  ENVIRONMENT_BASE_URLS,\n} from \"./environment\";\nexport type {\n  RemitaEnvironment,\n  ResolveEnvironmentOptions,\n  ResolvedEnvironment,\n} from \"./environment\";\n\nexport { openStatusStream } from \"./stream\";\nexport type { StatusStreamOptions, StatusStreamHandle } from \"./stream\";\n\nexport { RemitaApiError } from \"./types\";\nexport type {\n  ApiErrorPayload,\n  PrePaymentRequest,\n  PrePaymentResponse,\n  PaymentChannel,\n  FeeChargeRequest,\n  FeeChargeResponse,\n  InitiatePaymentRequest,\n  InitiatePaymentResponse,\n  AuthorizePayload,\n  AuthorizeResponse,\n  ValidatePaymentRequest,\n  ValidatePaymentResponse,\n  PaymentStatus,\n  VerifyPaymentResponse,\n  Bank,\n  BankListResponse,\n  UssdCode,\n  UssdCodesResponse,\n  WalletType,\n  WalletTypesResponse,\n  StatusStreamEvent,\n} from \"./types\";\n","import type { RemitaCheckoutClient } from \"./client\";\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} from \"./types\";\n\nexport type PaymentSessionStage =\n  | \"idle\"\n  | \"pre\"\n  | \"fee\"\n  | \"initiated\"\n  | \"authorized\"\n  | \"validated\"\n  | \"verified\"\n  | \"failed\";\n\n/**\n * Sequences the multi-step payment flow (pre → fee → initiate → authorize →\n * validate → verify) and tracks the refs each step hands to the next\n * (paymentReference, transactionId, actionUrl), so callers don't have to\n * thread that state through by hand.\n */\nexport class PaymentSession {\n  stage: PaymentSessionStage = \"idle\";\n  paymentReference?: string;\n  transactionId?: string;\n\n  /** URL returned by initiate() for the *authorize* step. */\n  private authorizeActionUrl?: string;\n  /** URL returned by authorize() for the *validate* step, if different. */\n  private validateActionUrl?: string;\n\n  constructor(private readonly client: RemitaCheckoutClient) {}\n\n  async pre(request: PrePaymentRequest): Promise<PrePaymentResponse> {\n    const response = await this.client.prePayment(request);\n    // Read refs from the RESPONSE, not the request.\n    this.transactionId = response.transactionId ?? this.transactionId;\n    this.paymentReference = response.paymentReference ?? this.paymentReference;\n    this.stage = \"pre\";\n    return response;\n  }\n\n  async fee(request: FeeChargeRequest): Promise<FeeChargeResponse> {\n    const response = await this.client.calculateFee(request);\n    this.stage = \"fee\";\n    return response;\n  }\n\n  async initiate(request: InitiatePaymentRequest): Promise<InitiatePaymentResponse> {\n    const response = await this.client.initiatePayment(request);\n    this.authorizeActionUrl = response.actionUrl;\n    this.validateActionUrl = undefined; // reset until authorize tells us otherwise\n    this.paymentReference = response.paymentReference ?? this.paymentReference;\n    this.transactionId = response.transactionId ?? this.transactionId;\n    this.stage = \"initiated\";\n    return response;\n  }\n\n  /**\n   * Uses the actionUrl captured from initiate() unless you pass one explicitly.\n   * Pass `contentType` for 3DS processor endpoints that require form-encoding.\n   */\n  async authorize(\n    payload: AuthorizePayload,\n    actionUrlOverride?: string,\n    contentType?: string\n  ): Promise<AuthorizeResponse> {\n    const url = actionUrlOverride ?? this.authorizeActionUrl;\n    if (!url) {\n      throw new Error(\n        \"No actionUrl available — call initiate() first, or pass actionUrlOverride explicitly.\"\n      );\n    }\n    const response = await this.client.authorize(url, payload, contentType);\n\n    // If the processor told us where the next validation step lives, use it.\n    const next = (response as { actionUrl?: string }).actionUrl;\n    if (next) this.validateActionUrl = next;\n\n    this.stage = \"authorized\";\n    return response;\n  }\n\n  async validate(\n    request: ValidatePaymentRequest,\n    actionUrlOverride?: string\n  ): Promise<ValidatePaymentResponse> {\n    // Prefer an explicit override, then the URL authorize() handed us,\n    // then fall through to /payment/validate.\n    const url = actionUrlOverride ?? this.validateActionUrl;\n    const response = await this.client.validatePayment(request, url);\n    this.stage = \"validated\";\n    return response;\n  }\n\n  async verify(paymentRefOverride?: string): Promise<VerifyPaymentResponse> {\n    const ref = paymentRefOverride ?? this.paymentReference ?? this.transactionId;\n    if (!ref) {\n      throw new Error(\n        \"No paymentReference or transactionId available — call initiate() first, or pass it explicitly.\"\n      );\n    }\n    const response = await this.client.verifyPayment(ref);\n    // Only APPROVED counts as verified. PENDING stays \"validated\".\n    if (response.status === \"APPROVED\") {\n      this.stage = \"verified\";\n    } else if (response.status === \"FAILED\") {\n      this.stage = \"failed\";\n    }\n    return response;\n  }\n}","export interface ApiErrorPayload {\n  responseCode?: string;\n  responseMessage?: string;\n  message?: string;\n  [key: string]: unknown;\n}\n\nexport class RemitaApiError extends Error {\n  readonly status: number;\n  readonly payload: ApiErrorPayload | undefined;\n\n  constructor(message: string, status: number, payload?: ApiErrorPayload) {\n    super(message);\n    this.name = \"RemitaApiError\";\n    this.status = status;\n    this.payload = payload;\n  }\n}\n\n/* -------------------------------------------------------------------- *\n * NOTE ON THE TYPES BELOW\n *\n * Field names for PrePaymentRequest are verified against a working QA\n * cURL. The rest remain best-effort based on standard gateway\n * conventions and should be tightened as real DTOs are confirmed.\n *\n * `publicKey` is NEVER part of a request body — it is sent as a header\n * by RemitaCheckoutClient. Do not add it back to any request interface.\n * -------------------------------------------------------------------- */\n\nexport interface PrePaymentRequest {\n  firstName: string;\n  lastName: string;\n  email: string;\n  phoneNumber: string;\n  paymentIdentifier: string;\n  currency: string;\n  narration?: string;\n  amount: number;\n  [key: string]: unknown;\n}\n\nexport interface PaymentChannel {\n  code: string;\n  name: string;\n  [key: string]: unknown;\n}\n\nexport interface PrePaymentResponse {\n  merchantName?: string;\n  amount?: number | string;\n  currency?: string;\n  channels?: PaymentChannel[];\n  /** Forwarded from /payment/pre if the API echoes one. */\n  transactionId?: string;\n  paymentReference?: string;\n  [key: string]: unknown;\n}\n\nexport interface FeeChargeRequest {\n  amount: number;\n  channel: string;\n  [key: string]: unknown;\n}\n\nexport interface FeeChargeResponse {\n  fee?: number | string;\n  totalAmount?: number | string;\n  [key: string]: unknown;\n}\n\nexport interface InitiatePaymentRequest {\n  channel: string;\n  amount: number;\n  transactionId?: string;\n  [key: string]: unknown;\n}\n\nexport interface InitiatePaymentResponse {\n  /** Where to POST the next-step authorization payload (OTP, PIN, 3DS fields, etc). */\n  actionUrl?: string;\n  paymentReference?: string;\n  transactionId?: string;\n  status?: string;\n  [key: string]: unknown;\n}\n\nexport type AuthorizePayload = Record<string, unknown>;\n\nexport interface AuthorizeResponse {\n  status?: string;\n  requiresValidation?: boolean;\n  [key: string]: unknown;\n}\n\nexport interface ValidatePaymentRequest {\n  paymentReference?: string;\n  transactionId?: string;\n  otp?: string;\n  [key: string]: unknown;\n}\n\nexport interface ValidatePaymentResponse {\n  status?: string;\n  [key: string]: unknown;\n}\n\nexport type PaymentStatus = \"APPROVED\" | \"PENDING\" | \"FAILED\" | (string & {});\n\nexport interface VerifyPaymentResponse {\n  status?: PaymentStatus;\n  paymentReference?: string;\n  amount?: number | string;\n  [key: string]: unknown;\n}\n\nexport interface Bank {\n  code: string;\n  name: string;\n  currency?: string;\n  [key: string]: unknown;\n}\n\nexport interface BankListResponse {\n  banks: Bank[];\n  [key: string]: unknown;\n}\n\nexport interface UssdCode {\n  bankCode: string;\n  ussdCode: string;\n  [key: string]: unknown;\n}\n\nexport interface UssdCodesResponse {\n  codes: UssdCode[];\n  [key: string]: unknown;\n}\n\nexport interface WalletType {\n  code: string;\n  name: string;\n  [key: string]: unknown;\n}\n\nexport interface WalletTypesResponse {\n  wallets: WalletType[];\n  [key: string]: unknown;\n}\n\nexport interface StatusStreamEvent {\n  status?: PaymentStatus;\n  [key: string]: unknown;\n}"],"mappings":";;;;;;;;;;;AAAA;;;AC+BO,IAAM,iBAAN,MAAqB;AAAA,EAU1B,YAA6B,QAA8B;AAA9B;AAT7B,iBAA6B;AAAA,EAS+B;AAAA,EAE5D,MAAM,IAAI,SAAyD;AACjE,UAAM,WAAW,MAAM,KAAK,OAAO,WAAW,OAAO;AAErD,SAAK,gBAAgB,SAAS,iBAAiB,KAAK;AACpD,SAAK,mBAAmB,SAAS,oBAAoB,KAAK;AAC1D,SAAK,QAAQ;AACb,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,IAAI,SAAuD;AAC/D,UAAM,WAAW,MAAM,KAAK,OAAO,aAAa,OAAO;AACvD,SAAK,QAAQ;AACb,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,SAAS,SAAmE;AAChF,UAAM,WAAW,MAAM,KAAK,OAAO,gBAAgB,OAAO;AAC1D,SAAK,qBAAqB,SAAS;AACnC,SAAK,oBAAoB;AACzB,SAAK,mBAAmB,SAAS,oBAAoB,KAAK;AAC1D,SAAK,gBAAgB,SAAS,iBAAiB,KAAK;AACpD,SAAK,QAAQ;AACb,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,UACJ,SACA,mBACA,aAC4B;AAC5B,UAAM,MAAM,qBAAqB,KAAK;AACtC,QAAI,CAAC,KAAK;AACR,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,UAAM,WAAW,MAAM,KAAK,OAAO,UAAU,KAAK,SAAS,WAAW;AAGtE,UAAM,OAAQ,SAAoC;AAClD,QAAI,KAAM,MAAK,oBAAoB;AAEnC,SAAK,QAAQ;AACb,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,SACJ,SACA,mBACkC;AAGlC,UAAM,MAAM,qBAAqB,KAAK;AACtC,UAAM,WAAW,MAAM,KAAK,OAAO,gBAAgB,SAAS,GAAG;AAC/D,SAAK,QAAQ;AACb,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,OAAO,oBAA6D;AACxE,UAAM,MAAM,sBAAsB,KAAK,oBAAoB,KAAK;AAChE,QAAI,CAAC,KAAK;AACR,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,UAAM,WAAW,MAAM,KAAK,OAAO,cAAc,GAAG;AAEpD,QAAI,SAAS,WAAW,YAAY;AAClC,WAAK,QAAQ;AAAA,IACf,WAAW,SAAS,WAAW,UAAU;AACvC,WAAK,QAAQ;AAAA,IACf;AACA,WAAO;AAAA,EACT;AACF;;;ADnHA;AAUA;;;AETO,IAAM,iBAAN,cAA6B,MAAM;AAAA,EAIxC,YAAY,SAAiB,QAAgB,SAA2B;AACtE,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,UAAU;AAAA,EACjB;AACF;","names":[]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "remita-checkout-client",
+  "version": "0.1.0",
+  "description": "Typed client for the Remita Checkout REST API (pre-payment, fee calc, initiate, authorize, validate, verify, SSE status, channel config).",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "bin": {
+    "remita-checkout": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --sourcemap --clean",
+    "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --reporter=verbose",
+    "prepublishOnly": "npm run build && npm run typecheck"
+  },
+  "keywords": [
+    "remita",
+    "payment",
+    "checkout",
+    "nigeria",
+    "fintech"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/<you>/<repo>.git"
+  },
+  "homepage": "https://github.com/<you>/<repo>#readme",
+  "bugs": {
+    "url": "https://github.com/<you>/<repo>/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.0"
+  },
+  "dependencies": {
+    "license": "^1.0.3"
+  }
+}