epic-collection-gateway-sdk 1.0.2 → 1.0.3

package/README.md

@@ -1,248 +1,264 @@
-# Epic Pay Collection Payment Gateway SDK (Demo)
+# Epic Collection Gateway SDK
 
-A lightweight demo SDK exposing a payment sheet with three flows: Pay by Card, Pay by Bank, and Pay by Epic Pay. Intended for integration demos and sandbox presentations.
+A lightweight TypeScript/JavaScript SDK for integrating **Epic Collections Web Checkout** into your web storefront. It handles authentication, redirect-flow initiation, and return-URL parsing — no backend proxy required on your end.
 
-## Features
+---
 
-- Minimal, framework-agnostic checkout modal
-- Three demo payment methods: `card`, `bank`, `epic`
-- Simple event callbacks via `onEvent`
-- Zero backend required (simulated success/failure)
+## Features
 
-## Installation
+- **`startEpicCollectionPayment`** – Authenticate with the Epic Collections API and get the redirect URL to the hosted payment portal in one call.
+- **`redirectToPortal`** – Build a portal redirect URL manually (useful when you already have credentials configured via `initEpicPay`).
+- **`parsePaymentResponseFromUrl`** – Parse query-string / hash parameters on your return page after the user completes (or cancels) payment.
+- **`initEpicPay`** – Optional global config initializer (environment, APIbase, event callbacks, etc.).
+- Zero dependencies, ESM-only, full TypeScript types included.
 
-Published name: `epic-pay-sdk` (demo).
+---
 
-Install from npm:
+## Installation
 
 ```bash
-npm i epic-pay-sdk
+npm install epic-collection-gateway-sdk
 ```
 
-## Quick start
+---
+
+## Quick Start
 
 ```ts
-import { initEpicPay, openPaymentSheet } from "epic-pay-sdk";
+import { startEpicCollectionPayment } from "epic-collection-gateway-sdk";
 
-initEpicPay({ environment: "sandbox" });
+const url = await startEpicCollectionPayment({
+  environment: "sandbox",
+  clientId: "YOUR_CLIENT_ID",
+  clientSecret: "YOUR_CLIENT_SECRET",
+  redirectUrl: "https://your-site.com/order-result",
+  amount: 2500,
+  sessionId: "unique_order_session_id",
+  customerDetails: { email: "user@example.com" },
+});
 
-// Trigger at checkout
-const result = await openPaymentSheet({ amount: 999, currency: "₦" });
-if (result.status === "succeeded") {
-  console.log("Paid", result.transactionId);
-}
+// Navigate the user to the hosted payment portal
+window.location.assign(url);
 ```
 
-## Usage
-
-### ESM (bundlers like Vite, Webpack, Next.js)
+On your `redirectUrl` page, parse the response:
 
 ```ts
-import EpicPay, {
-  initEpicPay,
-  openPaymentSheet,
-  closePaymentSheet,
-} from "epic-pay-sdk";
+import { parsePaymentResponseFromUrl } from "epic-collection-gateway-sdk";
 
-initEpicPay({
-  merchantId: "demo_merchant_123",
-  environment: "sandbox",
-  onEvent: (e) => console.log("[EpicPay event]", e),
-});
+const result = parsePaymentResponseFromUrl();
+// { status, paymentRef, sessionId, ... }
+console.log(result);
+```
 
-// On checkout
-const result = await openPaymentSheet({
-  amount: 999,
-  currency: "₦",
-  paymentMethods: ["card", "bank", "epic"],
-});
-if (result.status === "succeeded") {
-  console.log("Paid", result.transactionId);
-}
+---
 
-// You can programmatically close the sheet if needed
-closePaymentSheet();
-```
+## API Reference
 
-### Vanilla JS (no framework)
+### `startEpicCollectionPayment(options)` → `Promise<string>`
 
-Import via your bundler/ESM pipeline and call from regular scripts:
+Authenticates your session with the Epic Collections backend and returns the fully-qualified portal redirect URL. This is the **primary integration function** for most storefronts.
 
-```js
-import { initEpicPay, openPaymentSheet, closePaymentSheet } from "epic-pay-sdk";
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `environment` | `string` | ✅ | Environment (sandbox or production). |
+| `clientId` | `string` | ✅ | Issued from the Epic Collections Admin Portal (min 16 chars). |
+| `clientSecret` | `string` | ✅ | Issued from the Epic Collections Admin Portal (min 16 chars). |
+| `redirectUrl` | `string` | ✅ | Merchant callback URL — where the user lands after payment or cancellation. |
+| `amount` | `number` | ✅ | Checkout amount (e.g. `2500` for ₦2,500). |
+| `sessionId` | `string` | ✅ | Unique identifier for this checkout session / order (min 16 chars). |
+| `customerDetails` | `EpicCollectioncustomerDetails` | — | Optional customer info forwarded to the portal. |
 
-initEpicPay({ environment: "sandbox" });
-document.getElementById("pay-btn").addEventListener("click", async () => {
-  try {
-    const res = await openPaymentSheet({ amount: 500, currency: "₦" });
-    console.log(res);
-  } catch (err) {
-    console.error(err);
-  }
-});
+**`EpicCollectioncustomerDetails`**
+
+```ts
+interface EpicCollectioncustomerDetails {
+  name?: string;
+  email?: string;
+  phone?: string;
+}
 ```
 
-## API
+**Example — React checkout button**
 
-- **`initEpicPay(options)`**
+```tsx
+import { startEpicCollectionPayment } from "epic-collection-gateway-sdk";
 
-  - `merchantId?: string`
-  - `environment?: 'sandbox' | 'production'` (default: `sandbox`)
-  - `onEvent?: (event) => void` event callback
+function CheckoutButton({ cartItems }: { cartItems: CartItem[] }) {
+  const [paying, setPaying] = useState(false);
+  const total = cartItems.reduce((sum, i) => sum + i.price * i.quantity, 0);
 
-- **`openPaymentSheet(params)` -> `Promise<PaymentResult>`**
+  const handleCheckout = async () => {
+    if (!cartItems.length) return;
+    try {
+      setPaying(true);
+      const url = await startEpicCollectionPayment({
+        environment: "sandbox",
+        clientId: "YOUR_CLIENT_ID",
+        clientSecret: "YOUR_CLIENT_SECRET",
+        redirectUrl: "https://your-site.com",
+        amount: total,
+        sessionId: crypto.randomUUID(), // unique per order
+        customerDetails: { email: "user@example.com" },
+      });
+      window.location.assign(url);
+    } catch (err) {
+      console.error("Payment initiation failed:", err);
+    } finally {
+      setPaying(false);
+    }
+  };
 
-  - `amount: number` (required)
-  - `currency?: string` (default: `₦`)
-  - `customer?: Record<string, any>`
-  - `paymentMethods?: ('card' | 'bank' | 'epic')[]` (default: all)
+  return (
+    <button onClick={handleCheckout} disabled={!cartItems.length || paying}>
+      {paying ? "Processing…" : `Pay ₦${total.toFixed(2)}`}
+    </button>
+  );
+}
+```
 
-  Notes:
+---
 
-  - Must be called in a browser environment (uses DOM to render a modal sheet).
-  - Prevents multiple concurrent sheets; rejects if one is already open.
+### `redirectToPortal(params)` → `string`
 
-- **`closePaymentSheet()`** closes the sheet.
+Builds and returns the portal URL without making an auth API call. Use this if credentials are already set via `initEpicPay` and you want manual control.
 
-### Events
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `amount` | `number` | ✅ | Checkout amount. |
+| `sessionId` | `string` | ✅ | Unique checkout session ID. |
+| `redirectUrl` | `string` | — | Overrides the `redirectUrl` set in `initEpicPay`. |
+| `customerDetails` | `EpicCollectioncustomerDetails` | — | Optional customer metadata. |
+| `additionalParams` | `Record<string, string \| number \| boolean>` | — | Any extra query params to append to the URL. |
 
-Events emitted to `onEvent`:
+> **Note:** `initEpicPay({ redirectUrl: "..." })` must be called before `redirectToPortal`, or a `redirectUrl` must be passed directly in params.
 
-- `payment_opened`
-- `payment_initiated`
-- `payment_succeeded`
-- `payment_failed`
-- `payment_closed`
+```ts
+import { initEpicPay, redirectToPortal } from "epic-collection-gateway-sdk";
 
-## TypeScript
+initEpicPay({
+  redirectUrl: "https://pay.your-portal.com/checkout",
+  clientId: "YOUR_CLIENT_ID",
+  clientSecret: "YOUR_CLIENT_SECRET",
+});
 
-Type definitions are included at `epic-pay-sdk/index.d.ts`.
+const url = redirectToPortal({
+  amount: 2300,
+  sessionId: "sess_123456789",
+  redirectUrl: "https://your-site.com/order-result",
+  customerDetails: { email: "user@example.com" },
+});
 
-- `EpicPayInitOptions`
-- `OpenPaymentSheetParams`
-- `PaymentResult` union with `succeeded | cancelled | failed`
+window.location.assign(url);
+```
+
+---
 
-Importing with types:
+### `parsePaymentResponseFromUrl(raw?)` → `Record<string, string>`
+
+Parses query-string or hash parameters from the current page URL (or a custom string) and returns them as a plain object. Call this on your `redirectUrl` return page.
 
 ```ts
-import type { OpenPaymentSheetParams, PaymentResult } from "epic-pay-sdk";
+import { parsePaymentResponseFromUrl } from "epic-collection-gateway-sdk";
+
+// Automatically reads window.location.search or window.location.hash
+const result = parsePaymentResponseFromUrl();
+
+if (result.status === "success") {
+  console.log("Payment reference:", result.paymentRef);
+  console.log("Session ID:", result.sessionId);
+} else {
+  console.warn("Payment not completed:", result.status);
+}
 ```
 
-## Demo app
+You may also pass a raw query string:
 
-A simple integration demo is available in this repo at `epic-demo/`.
+```ts
+const result = parsePaymentResponseFromUrl("?status=success&paymentRef=TXN_001");
+```
 
-## Notes
+---
 
-- This is a front-end only demo. No real payments are processed.
-- Success is simulated (~90% chance).
-- Styles are injected dynamically by the SDK.
+### `initEpicPay(options?)` → `void`
 
-## Redirect-only integration (new flow)
+Sets global SDK configuration. Call this once at app startup. All options are optional.
 
-If you want a redirect-only flow (the SDK only performs the redirect to your hosted portal and helps parse the return), initialize with `redirectUrl` and optional `clientId`/`clientSecret`:
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `environment` | `'sandbox' \| 'production'` | `'sandbox'` | Target environment. |
+| `apiBase` | `string` | — | Base URL for the Epic Collections API. |
+| `redirectUrl` | `string` | — | Default portal redirect URL. |
+| `clientId` | `string` | — | Client ID (can be passed here or per-call). |
+| `clientSecret` | `string` | — | Client secret (can be passed here or per-call). |
+| `headers` | `Record<string, string>` | — | Custom headers appended to API requests. |
+| `onEvent` | `(event: PaymentEvent) => void` | — | Global event callback. |
 
 ```ts
-import { initEpicPay, redirectToPortal, parsePaymentResponseFromUrl } from 'epic-pay-sdk';
+import { initEpicPay } from "epic-collection-gateway-sdk";
 
 initEpicPay({
-  redirectUrl: 'https://pay.your-portal.com/checkout',
-  clientId: 'your_public_client_id',
-});
-
-// When user clicks "Proceed to pay" on the integrator page:
-redirectToPortal({
-  amount: 2300,
-  currency: 'NGN',
-  customerEmail: 'user@example.com', // optional
-  sessionId: 'sess_123456789',
-  returnUrl: 'https://merchant.example.com/order-success',
+  environment: "production",
+  onEvent: (e) => console.log("[EpicPay event]", e.type, e.payload),
 });
-
-// On your returnUrl page, parse the response:
-const res = parsePaymentResponseFromUrl();
-// res may contain: sessionId, paymentRef, status, and any other keys your portal includes
-console.log(res);
 ```
 
-## License
-
-MIT
-
 ---
 
-## Epic Collections Web Checkout integration (React example)
+## TypeScript Types
 
-This is a concrete example of how a React storefront (like `eCommerceFE`) integrates with this SDK for the Epic Collections Web Checkout flow.
+All types are exported from the package root:
 
-### Example: Checkout button in a React header/cart component
+```ts
+import type {
+  EpicPayInitOptions,
+  EpicPayEnvironment,
+  StartEpicCollectionPaymentOptions,
+  EpicCollectioncustomerDetails,
+  RedirectToPortalParams,
+  EpicPayConfig,
+  PaymentEvent,
+  PaymentResult,
+  CustomerInfo,
+} from "epic-collection-gateway-sdk";
+```
 
-```tsx
-import { startEpicCollectionPayment } from '@naderepic/epic-collection-payment-gateway-sdk';
+| Type | Description |
+|---|---|
+| `EpicPayInitOptions` | Options for `initEpicPay()`. |
+| `StartEpicCollectionPaymentOptions` | Options for `startEpicCollectionPayment()`. |
+| `RedirectToPortalParams` | Params for `redirectToPortal()`. |
+| `EpicCollectioncustomerDetails` | Optional customer fields forwarded to the portal. |
+| `PaymentEvent` | Event object emitted via `onEvent`. Shape: `{ type, payload, timestamp }`. |
+| `PaymentResult` | Result shape returned from the portal on the return URL. |
 
-function CheckoutButton({ cartItems }) {
-  const [paying, setPaying] = useState(false);
-  const total = cartItems.reduce((sum, i) => sum + i.price * i.quantity, 0);
+---
 
-  const handleCheckout = async () => {
-    if (cartItems.length === 0) return;
-    try {
-      setPaying(true);
-      const sessionId = '2349283949994959000345340212778'; // generate per order in production
+## Default Export
 
-      const url = await startEpicCollectionPayment({
-        clientId: '3cEePs32ipRTQkBRn0c33gAb7UOqcLPwMBMNhDgK',
-        clientSecret: 'mye008uvYFzqWUQEjLGBbIuWd8eEJmhSRUPy1IlmsZlCa84apHxNrsDGvSLVVL5z',
-        redirectUrl: 'https://your-site.com/order-result',
-        amount: total,
-        sessionId,
-        customerDetails: {
-          email: 'user@gmail.com',
-        },
-      });
+A convenience object is available as the default export:
 
-      window.location.assign(url);
-    } finally {
-      setPaying(false);
-    }
-  };
+```ts
+import EpicCollectionSdk from "epic-collection-gateway-sdk";
 
-  return (
-    <button
-      onClick={handleCheckout}
-      disabled={cartItems.length === 0 || paying}
-    >
-      {paying ? 'Processing...' : `Proceed to Pay ( ₦${total.toFixed(2)})`}
-    </button>
-  );
-}
+const { startEpicCollectionPayment, redirectToPortal, parsePaymentResponseFromUrl, initEpicPay } = EpicCollectionSdk;
 ```
 
-### Options passed from frontend to the SDK
+---
 
-The options object passed to `startEpicCollectionPayment` has the following shape on the **frontend**:
+## Environment Variables (SDK-internal)
 
-```json
-{
-  "clientId": "<clientId>",
-  "clientSecret": "<clientSecret>",
-  "redirectUrl": "https://your-site.com/order-result",
-  "amount": <amount>,
-  "sessionId": "<sessionId>",
-  "customerDetails": {
-    "email": "user@example.com"
-  }
-}
-```
+When bundling the SDK from source, the following `VITE_` environment variables are resolved at build time:
+
+| Variable | Purpose |
+|---|---|
+| `VITE_PORTAL_URL` | Overrides the default payment portal base URL. |
+| `VITE_EPIC_ENVIRONMENT` | Sets the default environment (`sandbox` / `production`). |
+
+> These are for SDK development only. Integrators do **not** need to set these — pass `apiBase` / `redirectUrl` via `initEpicPay` or `startEpicCollectionPayment` instead.
 
-- `clientId`, `clientSecret` – provided by the Epic Collections Admin Portal.
-- `redirectUrl` – **merchant callback URL** where the shopper is sent back after payment/cancel.
-- `amount` – total amount for this checkout (computed from cart).
-- `sessionId` – unique per checkout session/order.
-- `customerDetails` – optional customer metadata forwarded as query params (`clientEmail`, `clientName`, `clientPhone`).
+---
 
-The SDK uses this **frontend** payload to:
-- Call the Epic backend `/web-checkout/auth` with `clientId`, `clientSecret`, `sessionId`, `amount`, `redirectUrl`, and any `customerDetails`.
-- Build and return the final redirect URL for the **Collections payment portal** (from `VITE_PORTAL_URL` / `VITE_EPIC_COLLECTION_PORTAL_URL` inside the SDK), which your frontend then navigates to with `window.location.assign(url)` (or your router of choice).
+## License
 
-> Note: For this Epic Collections Web Checkout flow you **do not need to call `initEpicPay`**. The payment portal URL is resolved inside the SDK from environment variables.
+MIT

package/dist/core/api.d.ts

@@ -28,6 +28,7 @@ export interface EpicCollectioncustomerDetails {
     phone?: string;
 }
 export interface StartEpicCollectionPaymentOptions {
+    environment?: EpicPayEnvironment;
     clientId: string;
     clientSecret: string;
     /** Merchant callback URL where the shopper is sent back after payment/cancel */

package/dist/index.js

@@ -1,8 +1,8 @@
-const f = { BASE_URL: "/", MODE: "production", DEV: !1, PROD: !0, SSR: !1 }, m = f.VITE_PORTAL_URL || "https://checkout.epicpay.co", E = f.VITE_PORTAL_URL || "https://zppicbcegi.execute-api.af-south-1.amazonaws.com/prod/api/v1", y = f.VITE_EPIC_ENVIRONMENT || "", s = {
-  environment: y,
-  apiBase: E,
+const u = "https://checkout.epicpay.co", y = "https://zppicbcegi.execute-api.af-south-1.amazonaws.com/prod/api/v1", s = {
+  environment: "",
+  apiBase: y,
   headers: {},
-  redirectUrl: m,
+  redirectUrl: u,
   clientId: "",
   clientSecret: "",
   dryRun: !0,
@@ -11,83 +11,86 @@ const f = { BASE_URL: "/", MODE: "production", DEV: !1, PROD: !0, SSR: !1 }, m =
 function p(e) {
   Object.assign(s, e);
 }
-function u(e) {
-  const { amount: n, sessionId: i, additionalParams: c, redirectUrl: o } = e, r = s.redirectUrl || s.apiBase;
-  if (!r)
+function m(e) {
+  const { amount: r, sessionId: c, additionalParams: n, redirectUrl: i } = e, a = s.redirectUrl || s.apiBase;
+  if (!a)
     throw new Error('No redirectUrl configured. Call initEpicPay({ redirectUrl: "https://..." }).');
   const t = {
-    amount: String(n),
-    sessionId: i
+    amount: String(r),
+    sessionId: c
   };
-  o && (t.redirectUrl = String(o)), s.clientId && (t.clientId = s.clientId), s.clientSecret && (t.clientSecret = s.clientSecret), c && Object.keys(c).forEach((a) => {
-    t[a] = String(c[a]);
+  i && (t.redirectUrl = String(i)), s.clientId && (t.clientId = s.clientId), s.clientSecret && (t.clientSecret = s.clientSecret), n && Object.keys(n).forEach((d) => {
+    t[d] = String(n[d]);
   });
-  const l = Object.keys(t).map((a) => `${encodeURIComponent(a)}=${encodeURIComponent(t[a])}`).join("&"), h = r + (r.includes("?") ? "&" : "?") + l;
+  const o = Object.keys(t).map((d) => `${encodeURIComponent(d)}=${encodeURIComponent(t[d])}`).join("&"), l = a + (a.includes("?") ? "&" : "?") + o;
   try {
-    console.log("[EpicPay] redirectToPortal", { portal: r, amount: n, sessionId: i });
+    console.log("[EpicPay] redirectToPortal", { portal: a, amount: r, sessionId: c });
   } catch {
   }
   try {
-    console.log("[EpicPay] redirectToPortal URL:", h);
+    console.log("[EpicPay] redirectToPortal URL:", l);
   } catch {
   }
-  return h;
+  return l;
 }
 async function g(e) {
-  const { clientId: n, clientSecret: i, redirectUrl: c, amount: o, sessionId: r, customerDetails: t } = e;
-  if (!n || typeof n != "string" || n.length < 16)
+  const { environment: r, clientId: c, clientSecret: n, redirectUrl: i, amount: a, sessionId: t, customerDetails: o } = e;
+  if (!r || typeof r != "string")
+    throw new Error("Invalid environment");
+  if (!c || typeof c != "string" || c.length < 16)
     throw new Error("Invalid clientId");
-  if (!i || typeof i != "string" || i.length < 16)
+  if (!n || typeof n != "string" || n.length < 16)
     throw new Error("Invalid clientSecret");
-  if (!r || typeof r != "string" || r.length < 16)
+  if (!t || typeof t != "string" || t.length < 16)
     throw new Error("Invalid sessionId");
-  if (!c || typeof c != "string")
+  if (!i || typeof i != "string")
     throw new Error("Invalid redirectUrl");
   p({
-    clientId: n,
-    clientSecret: i
+    environment: r,
+    clientId: c,
+    clientSecret: n
   });
   const l = s.apiBase;
   if (!l)
     throw new Error("No API base configured for authentication");
-  const h = (l.endsWith("/") ? l.slice(0, -1) : l) + "/web-checkout/auth", a = await fetch(h, {
+  const d = (l.endsWith("/") ? l.slice(0, -1) : l) + "/web-checkout/auth", f = await fetch(d, {
     method: "POST",
     headers: { "Content-Type": "application/json", grabbersbeware: "getthehellout989898" },
     body: JSON.stringify({
-      clientId: n,
-      clientSecret: i,
-      sessionId: r,
-      amount: o,
-      redirectUrl: c,
-      customerDetails: t
+      clientId: c,
+      clientSecret: n,
+      sessionId: t,
+      amount: a,
+      redirectUrl: i,
+      customerDetails: o
     })
   });
-  if (!a.ok)
+  if (!f.ok)
     throw new Error("Authentication request failed");
   try {
-    await a.json();
+    await f.json();
   } catch {
   }
-  const d = {};
-  return d.clientSecret = i, t && (t.name && (d.clientName = String(t.name)), t.email && (d.clientEmail = String(t.email)), t.phone && (d.clientPhone = String(t.phone))), u({
-    amount: o,
-    sessionId: r,
-    additionalParams: d,
-    redirectUrl: c
+  const h = {};
+  return h.clientSecret = n, o && (o.name && (h.clientName = String(o.name)), o.email && (h.clientEmail = String(o.email)), o.phone && (h.clientPhone = String(o.phone))), m({
+    amount: a,
+    sessionId: t,
+    additionalParams: h,
+    redirectUrl: i
   });
 }
 function w(e) {
-  const n = e ?? (typeof window < "u" ? window.location.search || window.location.hash : ""), i = n.startsWith("?") || n.startsWith("#") ? n.substring(1) : n, c = new URLSearchParams(i), o = {};
-  c.forEach((r, t) => {
-    o[t] = r;
+  const r = e ?? (typeof window < "u" ? window.location.search || window.location.hash : ""), c = r.startsWith("?") || r.startsWith("#") ? r.substring(1) : r, n = new URLSearchParams(c), i = {};
+  n.forEach((a, t) => {
+    i[t] = a;
   });
   try {
-    console.log("[EpicPay] parsePaymentResponseFromUrl", o);
+    console.log("[EpicPay] parsePaymentResponseFromUrl", i);
   } catch {
   }
-  return o;
+  return i;
 }
-function I(e = {}) {
+function E(e = {}) {
   p({
     environment: e.environment ?? "sandbox",
     apiBase: e.apiBase,
@@ -102,13 +105,13 @@ function I(e = {}) {
   } catch {
   }
 }
-const S = { initEpicPay: I, redirectToPortal: u, parsePaymentResponseFromUrl: w, startEpicCollectionPayment: g };
+const I = { initEpicPay: E, redirectToPortal: m, parsePaymentResponseFromUrl: w, startEpicCollectionPayment: g };
 export {
-  S as default,
+  I as default,
   s as epicConfig,
-  I as initEpicPay,
+  E as initEpicPay,
   w as parsePaymentResponseFromUrl,
-  u as redirectToPortal,
+  m as redirectToPortal,
   p as setConfig,
   g as startEpicCollectionPayment
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epic-collection-gateway-sdk",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",