epic-collection-gateway-sdk 1.0.2 → 1.0.4

package/README.md

@@ -1,248 +1,132 @@
-# 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 and redirect-flow initiation.
 
-## 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.
+- Zero dependencies, ESM-only, full TypeScript types included.
 
-Published name: `epic-pay-sdk` (demo).
+---
 
-Install from npm:
+## Installation
 
 ```bash
-npm i epic-pay-sdk
-```
-
-## Quick start
-
-```ts
-import { initEpicPay, openPaymentSheet } from "epic-pay-sdk";
-
-initEpicPay({ environment: "sandbox" });
-
-// Trigger at checkout
-const result = await openPaymentSheet({ amount: 999, currency: "₦" });
-if (result.status === "succeeded") {
-  console.log("Paid", result.transactionId);
-}
+npm install epic-collection-gateway-sdk
 ```
 
-## Usage
+---
 
-### ESM (bundlers like Vite, Webpack, Next.js)
+## Quick Start
 
 ```ts
-import EpicPay, {
-  initEpicPay,
-  openPaymentSheet,
-  closePaymentSheet,
-} from "epic-pay-sdk";
-
-initEpicPay({
-  merchantId: "demo_merchant_123",
-  environment: "sandbox",
-  onEvent: (e) => console.log("[EpicPay event]", e),
-});
+import { startEpicCollectionPayment } from "epic-collection-gateway-sdk";
 
-// On checkout
-const result = await openPaymentSheet({
-  amount: 999,
-  currency: "₦",
-  paymentMethods: ["card", "bank", "epic"],
+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" },
 });
-if (result.status === "succeeded") {
-  console.log("Paid", result.transactionId);
-}
 
-// You can programmatically close the sheet if needed
-closePaymentSheet();
+// Navigate the user to the hosted payment portal
+window.location.assign(url);
 ```
 
-### Vanilla JS (no framework)
-
-Import via your bundler/ESM pipeline and call from regular scripts:
-
-```js
-import { initEpicPay, openPaymentSheet, closePaymentSheet } from "epic-pay-sdk";
-
-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);
-  }
-});
-```
-
-## API
-
-- **`initEpicPay(options)`**
-
-  - `merchantId?: string`
-  - `environment?: 'sandbox' | 'production'` (default: `sandbox`)
-  - `onEvent?: (event) => void` event callback
-
-- **`openPaymentSheet(params)` -> `Promise<PaymentResult>`**
-
-  - `amount: number` (required)
-  - `currency?: string` (default: `₦`)
-  - `customer?: Record<string, any>`
-  - `paymentMethods?: ('card' | 'bank' | 'epic')[]` (default: all)
-
-  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.
-
-- **`closePaymentSheet()`** closes the sheet.
-
-### Events
-
-Events emitted to `onEvent`:
+---
 
-- `payment_opened`
-- `payment_initiated`
-- `payment_succeeded`
-- `payment_failed`
-- `payment_closed`
+## API Reference
 
-## TypeScript
+### `startEpicCollectionPayment(options)` → `Promise<string>`
 
-Type definitions are included at `epic-pay-sdk/index.d.ts`.
+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.
 
-- `EpicPayInitOptions`
-- `OpenPaymentSheetParams`
-- `PaymentResult` union with `succeeded | cancelled | failed`
+| 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. |
 
-Importing with types:
+**`EpicCollectioncustomerDetails`**
 
 ```ts
-import type { OpenPaymentSheetParams, PaymentResult } from "epic-pay-sdk";
+interface EpicCollectioncustomerDetails {
+  name?: string;
+  email?: string;
+  phone?: string;
+}
 ```
 
-## Demo app
-
-A simple integration demo is available in this repo at `epic-demo/`.
-
-## 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.
+### `redirectToPortal(params)` → `string`
 
-## Redirect-only integration (new flow)
+Builds and returns the portal URL without making an auth API call.
 
-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`:
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `amount` | `number` | ✅ | Checkout amount. |
+| `sessionId` | `string` | ✅ | Unique checkout session ID. |
+| `redirectUrl` | `string` | — | Overrides the default redirect URL. |
+| `customerDetails` | `EpicCollectioncustomerDetails` | — | Optional customer metadata. |
+| `additionalParams` | `Record<string, string \| number \| boolean>` | — | Any extra query params to append to the URL. |
 
 ```ts
-import { initEpicPay, redirectToPortal, parsePaymentResponseFromUrl } from 'epic-pay-sdk';
+import { redirectToPortal } 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({
+const url = redirectToPortal({
   amount: 2300,
-  currency: 'NGN',
-  customerEmail: 'user@example.com', // optional
-  sessionId: 'sess_123456789',
-  returnUrl: 'https://merchant.example.com/order-success',
+  sessionId: "sess_123456789",
+  redirectUrl: "https://your-site.com/order-result",
+  customerDetails: { email: "user@example.com" },
 });
 
-// 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);
+window.location.assign(url);
 ```
 
-## License
+---
 
-MIT
+## TypeScript Types
 
----
+All types are exported from the package root:
 
-## Epic Collections Web Checkout integration (React example)
-
-This is a concrete example of how a React storefront (like `eCommerceFE`) integrates with this SDK for the Epic Collections Web Checkout flow.
-
-### Example: Checkout button in a React header/cart component
-
-```tsx
-import { startEpicCollectionPayment } from '@naderepic/epic-collection-payment-gateway-sdk';
-
-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
-
-      const url = await startEpicCollectionPayment({
-        clientId: '3cEePs32ipRTQkBRn0c33gAb7UOqcLPwMBMNhDgK',
-        clientSecret: 'mye008uvYFzqWUQEjLGBbIuWd8eEJmhSRUPy1IlmsZlCa84apHxNrsDGvSLVVL5z',
-        redirectUrl: 'https://your-site.com/order-result',
-        amount: total,
-        sessionId,
-        customerDetails: {
-          email: 'user@gmail.com',
-        },
-      });
-
-      window.location.assign(url);
-    } finally {
-      setPaying(false);
-    }
-  };
-
-  return (
-    <button
-      onClick={handleCheckout}
-      disabled={cartItems.length === 0 || paying}
-    >
-      {paying ? 'Processing...' : `Proceed to Pay ( ₦${total.toFixed(2)})`}
-    </button>
-  );
-}
+```ts
+import type {
+  EpicPayEnvironment,
+  StartEpicCollectionPaymentOptions,
+  EpicCollectioncustomerDetails,
+  RedirectToPortalParams,
+  EpicPayConfig,
+  PaymentEvent,
+  PaymentResult,
+  CustomerInfo,
+} from "epic-collection-gateway-sdk";
 ```
 
-### Options passed from frontend to the SDK
+---
 
-The options object passed to `startEpicCollectionPayment` has the following shape on the **frontend**:
+## Default Export
 
-```json
-{
-  "clientId": "<clientId>",
-  "clientSecret": "<clientSecret>",
-  "redirectUrl": "https://your-site.com/order-result",
-  "amount": <amount>,
-  "sessionId": "<sessionId>",
-  "customerDetails": {
-    "email": "user@example.com"
-  }
-}
+A convenience object is available as the default export:
+
+```ts
+import EpicCollectionSdk from "epic-collection-gateway-sdk";
+
+const { startEpicCollectionPayment, redirectToPortal } = EpicCollectionSdk;
 ```
 
-- `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

@@ -1,21 +1,6 @@
 export type EpicPayEnvironment = 'sandbox' | 'production';
-export interface EpicPayInitOptions {
-    merchantId?: string;
-    environment?: EpicPayEnvironment;
-    onEvent?: (event: {
-        type: string;
-        payload?: any;
-        timestamp: number;
-    }) => void;
-    apiBase?: string;
-    headers?: Record<string, string>;
-    paymentMethodsUrl?: string;
-    theme?: Record<string, string>;
-    redirectUrl?: string;
-    clientId?: string;
-    clientSecret?: string;
-}
 export interface RedirectToPortalParams {
+    environment?: EpicPayEnvironment;
     amount: number;
     sessionId: string;
     additionalParams?: Record<string, string | number | boolean>;
@@ -28,6 +13,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 */
@@ -38,5 +24,3 @@ export interface StartEpicCollectionPaymentOptions {
 }
 export declare function redirectToPortal(params: RedirectToPortalParams): string;
 export declare function startEpicCollectionPayment(options: StartEpicCollectionPaymentOptions): Promise<string>;
-export declare function parsePaymentResponseFromUrl(raw?: string): Record<string, string>;
-export declare function initEpicPay(options?: EpicPayInitOptions): void;

package/dist/core/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const EPIC_PORTAL_URL = "https://checkout.epicpay.co";
+export declare const EPIC_API_BASE = "https://zppicbcegi.execute-api.af-south-1.amazonaws.com/prod/api/v1";
+export declare const EPIC_HEADERS: {
+    grabbersbeware: string;
+};

package/dist/core/epicConfig.d.ts

@@ -2,4 +2,3 @@ import { EpicPayConfig } from './types';
 
 export declare const epicConfig: EpicPayConfig;
 export declare function setConfig(config: Partial<EpicPayConfig>): void;
-export declare function emit(type: string, payload?: any): void;

package/dist/core/types.d.ts

@@ -10,52 +10,4 @@ export interface EpicPayConfig {
     clientSecret?: string;
     /** If true, do not actually redirect; only log what would happen. */
     dryRun?: boolean;
-    onEvent?: (event: PaymentEvent) => void;
-}
-export interface ThemeConfig {
-    colorPrimaryViolet?: string;
-    borderColor?: string;
-    fontColor?: string;
-    black?: string;
-    white?: string;
-    inputBackground?: string;
-    tabBackground?: string;
-}
-export interface PaymentMethod {
-    identityKey: string;
-    methodName: string;
-    icon?: string;
-}
-export interface PaymentSheetProps {
-    amount: number;
-    currency?: string;
-    customer?: CustomerInfo;
-    paymentMethods?: PaymentMethod[] | 'auto';
-    onSuccess?: (result: PaymentResult) => void;
-    onError?: (error: PaymentError) => void;
-    onClose?: () => void;
-}
-export interface CustomerInfo {
-    id?: string;
-    email?: string;
-    name?: string;
-    phone?: string;
-}
-export interface PaymentResult {
-    status: 'succeeded' | 'failed' | 'cancelled';
-    method?: string;
-    amount?: number;
-    currency?: string;
-    transactionId?: string;
-    error?: string;
-}
-export interface PaymentError {
-    status: 'failed';
-    method?: string;
-    error: string;
-}
-export interface PaymentEvent {
-    type: string;
-    payload: any;
-    timestamp: number;
 }

package/dist/index.d.ts

@@ -1,13 +1,11 @@
-import { initEpicPay, redirectToPortal, parsePaymentResponseFromUrl, startEpicCollectionPayment } from './core/api';
+import { redirectToPortal, startEpicCollectionPayment } from './core/api';
 export { setConfig, epicConfig } from './core/epicConfig';
 export * from './core/types';
-export { initEpicPay, redirectToPortal, parsePaymentResponseFromUrl, startEpicCollectionPayment } from './core/api';
-export type { EpicPayInitOptions, EpicPayEnvironment } from './core/api';
+export { redirectToPortal, startEpicCollectionPayment } from './core/api';
+export type { EpicPayEnvironment } from './core/api';
 export type { RedirectToPortalParams, StartEpicCollectionPaymentOptions, EpicCollectioncustomerDetails } from './core/api';
 declare const EpicCollectionSdk: {
-    initEpicPay: typeof initEpicPay;
     redirectToPortal: typeof redirectToPortal;
-    parsePaymentResponseFromUrl: typeof parsePaymentResponseFromUrl;
     startEpicCollectionPayment: typeof startEpicCollectionPayment;
 };
 export default EpicCollectionSdk;

package/dist/index.js

@@ -1,114 +1,90 @@
-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", g = "https://zppicbcegi.execute-api.af-south-1.amazonaws.com/prod/api/v1", m = {
+  grabbersbeware: "getthehellout989898"
+}, c = {
+  environment: "",
+  apiBase: g,
   headers: {},
-  redirectUrl: m,
+  redirectUrl: u,
   clientId: "",
   clientSecret: "",
-  dryRun: !0,
-  onEvent: void 0
+  dryRun: !0
 };
-function p(e) {
-  Object.assign(s, e);
+function w(l) {
+  Object.assign(c, l);
 }
-function u(e) {
-  const { amount: n, sessionId: i, additionalParams: c, redirectUrl: o } = e, r = s.redirectUrl || s.apiBase;
-  if (!r)
+function p(l) {
+  const { environment: a, amount: r, sessionId: n, additionalParams: i, redirectUrl: d } = l, t = c.redirectUrl || c.apiBase;
+  if (!t)
     throw new Error('No redirectUrl configured. Call initEpicPay({ redirectUrl: "https://..." }).');
-  const t = {
-    amount: String(n),
-    sessionId: i
+  const e = {
+    amount: String(r),
+    sessionId: n
   };
-  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]);
+  d && (e.redirectUrl = String(d)), c.clientId && (e.clientId = c.clientId), c.clientSecret && (e.clientSecret = c.clientSecret), a && (e.environment = String(a)), i && Object.keys(i).forEach((o) => {
+    e[o] = String(i[o]);
   });
-  const l = Object.keys(t).map((a) => `${encodeURIComponent(a)}=${encodeURIComponent(t[a])}`).join("&"), h = r + (r.includes("?") ? "&" : "?") + l;
+  const s = Object.keys(e).map((o) => `${encodeURIComponent(o)}=${encodeURIComponent(e[o])}`).join("&"), f = t + (t.includes("?") ? "&" : "?") + s;
   try {
-    console.log("[EpicPay] redirectToPortal", { portal: r, amount: n, sessionId: i });
+    console.log("[EpicPay] redirectToPortal", { portal: t, amount: r, sessionId: n });
   } catch {
   }
   try {
-    console.log("[EpicPay] redirectToPortal URL:", h);
+    console.log("[EpicPay] redirectToPortal URL:", f);
   } catch {
   }
-  return h;
+  return f;
 }
-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)
+async function E(l) {
+  const { environment: a, clientId: r, clientSecret: n, redirectUrl: i, amount: d, sessionId: t, customerDetails: e } = l;
+  if (!a || typeof a != "string")
+    throw new Error("Invalid environment");
+  if (!r || typeof r != "string" || r.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
+  w({
+    environment: a,
+    clientId: r,
+    clientSecret: n
   });
-  const l = s.apiBase;
-  if (!l)
+  const s = c.apiBase;
+  if (!s)
     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 f = (s.endsWith("/") ? s.slice(0, -1) : s) + "/web-checkout/auth", o = await fetch(f, {
     method: "POST",
-    headers: { "Content-Type": "application/json", grabbersbeware: "getthehellout989898" },
+    headers: { "Content-Type": "application/json", ...m },
     body: JSON.stringify({
-      clientId: n,
-      clientSecret: i,
-      sessionId: r,
-      amount: o,
-      redirectUrl: c,
-      customerDetails: t
+      clientId: r,
+      clientSecret: n,
+      sessionId: t,
+      amount: d,
+      redirectUrl: i,
+      customerDetails: e
     })
   });
-  if (!a.ok)
+  if (!o.ok)
     throw new Error("Authentication request failed");
   try {
-    await a.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
-  });
-}
-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;
-  });
-  try {
-    console.log("[EpicPay] parsePaymentResponseFromUrl", o);
+    await o.json();
   } catch {
   }
-  return o;
-}
-function I(e = {}) {
-  p({
-    environment: e.environment ?? "sandbox",
-    apiBase: e.apiBase,
-    headers: e.headers,
-    onEvent: e.onEvent,
-    redirectUrl: e.redirectUrl,
-    clientId: e.clientId,
-    clientSecret: e.clientSecret
+  const h = {};
+  return h.clientSecret = n, e && (e.name && (h.clientName = String(e.name)), e.email && (h.clientEmail = String(e.email)), e.phone && (h.clientPhone = String(e.phone))), p({
+    amount: d,
+    sessionId: t,
+    additionalParams: h,
+    redirectUrl: i
   });
-  try {
-    console.log("[EpicPay] initEpicPay", { environment: e.environment ?? "sandbox", redirectUrl: e.redirectUrl, clientId: e.clientId, clientSecret: e.clientSecret });
-  } catch {
-  }
 }
-const S = { initEpicPay: I, redirectToPortal: u, parsePaymentResponseFromUrl: w, startEpicCollectionPayment: g };
+const I = { redirectToPortal: p, startEpicCollectionPayment: E };
 export {
-  S as default,
-  s as epicConfig,
-  I as initEpicPay,
-  w as parsePaymentResponseFromUrl,
-  u as redirectToPortal,
-  p as setConfig,
-  g as startEpicCollectionPayment
+  I as default,
+  c as epicConfig,
+  p as redirectToPortal,
+  w as setConfig,
+  E as startEpicCollectionPayment
 };

package/package.json

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